FE-738: Petri semantic lanes with two-lane subnet and engine factory

[kostandinang]

Summary

• Introduces the first Petri slice model where mechanical test success and semantic evaluator satisfaction are separate lanes; a slice completes only when both gates clear.
• Adds structured orchestration events and transition metadata so observers can reason about firing without parsing ad-hoc logs.
• Splits net compilation into topology blueprint vs handler wiring, and centralizes engine construction behind a single factory so proc/petri paths do not diverge on every frontier.

Context

• FE-730 validated cook on a greenfield fixture with a minimal Petri loop. This PR is the substrate step toward richer plans where “tests green” and “evaluator says done” are intentionally different concerns.
• Semantic rework is bounded via a dedicated budget place and RunPolicy.maxSemanticReworks, so assess/eval cycles cannot run unbounded when the evaluator never marks a slice satisfied.
• Unblocks later work on parallel firing (FE-743) and graph-level analysis by making transition contracts and events first-class.

What changed

• Two-lane subnet per slice: mechanical path evaluate → write-tests → write-code → run-tests; semantic path assess-semantic → semantic-satisfied; completion requires progress on both lanes.
• TransitionContract metadata on transitions plus §7 event vocabulary (transition_fired, net_halted, net_deadlocked) with enough structure for contract tests and future tooling.
• HandlerDescriptor union and typed handler wiring at the subnet boundary instead of growing ad-hoc closure dispatch.
• Compiler split: compileTopology produces NetBlueprint; wireHandlers materializes PetriNet; createOrchestrator(policy) replaces duplicated orchestrator setup.

Verification

• Full repo gate: npm run verify (fmt/lint check, test, build).
• Engine contract suite extended for dual-lane semantics, semantic budget exhaustion, and structured events (1378 tests at PR time).

Out of scope

• Stale-graph routing and full graph compilation/reachability (deferred to Phase 3; pairs with declarative routing in FE-747 and broader FE-700 work).
• Parallel slice execution and resource pools (FE-743).

Traceability

• Requirements 46–50; SPEC §2, §4, §6, §7, §8, §10; frontier petri-semantic-lanes in memory/PLAN.md; umbrella H-6476.

[kostandinang]

• FE-763: Petrinaut event stream — initial markings + transition firings #158
• FE-762: Petrinaut-format JSON export of the compiled net #157
• FE-761: Petri-net semantic alignment for Petrinaut visualization #156
• FE-755: Cook codebase mode for brownfield brunch #155
• FE-747: Declarative output routing for branching transitions #154
• FE-745: Epic-scoped sandbox merge for verify-epic #152
• FE-743: Petri parallel execution with resource pools and per-slice sandboxes #149
• FE-738: Petri semantic lanes with two-lane subnet and engine factory #148 👈 (View in Graphite)
• FE-730: Greenfield orchestrator POC with pi-agent dispatch #143
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Medium Risk
Orchestrator execution topology and CLI flags changed; behavior is heavily contract-tested but cook defaults and completion gating now depend on semantic assessment.

Overview
Delivers petri-semantic-lanes (FE-738): each slice now runs a mechanical TDD lane and a separate semantic lane. Slices finish only after assess-semantic produces semantic-satisfied; return-done no longer keys off done-spec alone. Failed semantic checks route back to needs-more with a semantic-budget place and RunPolicy.maxSemanticReworks to cap rework loops.

The net pipeline is split into compileTopology → NetBlueprint (pure topology + HandlerDescriptor recipes) and wireHandlers → PetriNet. TransitionContract metadata tags mechanical vs semantic transitions. The interpreter emits §7-style transition_fired, net_halted, and net_deadlocked events (optional sink).

createOrchestrator('serial') replaces duplicate proc/petri engine classes; brunch cook uses --policy=serial instead of --engine. Contract and adapter tests cover the new call order, semantic rework, topology counts, and events. Planning docs mark the frontier done and drop memory/CARDS.md.

^{Reviewed by Cursor Bugbot for commit 420f890. Bugbot is set up for automated code reviews on this repo. Configure here.}

[augmentcode]

🤖 Augment PR Summary

Summary: This PR evolves the Petri-net orchestrator by introducing distinct mechanical vs semantic completion lanes, and refactors compilation/execution so the net shape is testable as pure data.

Changes:

• Introduces a two-lane slice subnet (mechanical TDD loop + semantic assessment) with a completion gate so slices can’t finish without semantic satisfaction.
• Adds TransitionContract metadata to transitions (kind/lane/actor/guard) to classify execution without parsing IDs.
• Splits the compiler into compileTopology(plan, policy) → NetBlueprint (pure topology) and wireHandlers(...) (runtime closures), plus a convenience compilePlan wrapper.
• Consolidates engine entrypoints into createOrchestrator(firingPolicy), removing duplicated Petri/procedural engine classes.
• Adds semantic rework budgeting via a semantic-budget token (reworkCount) and RunPolicy.maxSemanticReworks to prevent infinite semantic-rejection loops.
• Defines §7-style interpreter events (transition_fired, net_halted, net_deadlocked) and updates adapter tests to assert event emission.
• Updates engine contract tests to cover semantic-gate rework and semantic budget exhaustion scenarios.

Technical Notes: Topology-only adapter tests no longer require action handlers/test runners, and runtime wiring now interprets declarative handler descriptors from the blueprint.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8b45a97. Configure here.}