FE-738: Petri semantic lanes — two-lane subnet, compiler split, engine factory

[kostandinang]

TL;DR. Phase 1 of the Petri orchestrator arc: extend the dual-engine substrate with a mechanical+semantic two-lane subnet, split the compiler into pure topology vs handler wiring, and add the §7 event vocabulary.

What changed

• Two-lane slice subnet — mechanical lane (evaluate → write-tests → write-code → run-tests) joined to semantic lane (assess-semantic → semantic-satisfied) at a completion gate. PlanDoneAccepted is unreachable without both.
• TransitionContract metadata on every transition (kind, lane, actor, guard).
• §7 event vocabulary — transition_fired, net_halted, net_deadlocked emitted by the interpreter.
• Compiler split — compileTopology(plan, policy) → NetBlueprint (pure data) + wireHandlers(blueprint, input, ctx) → PetriNet (closures). Adapter tests run on topology alone.
• Engine factory — createOrchestrator(policy) replaces duplicated PetriOrchestrator / ProceduralOrchestrator (~120 LOC).
• HandlerDescriptor discriminated union — declarative branch outputs per transition.
• Semantic rework budget — semantic-budget place + reworkCount token prevents infinite rework loops. Adds RunPolicy.maxSemanticReworks.

Why now

First frontier where Petri models a distinction proc cannot express topologically: mechanical completion ≠ semantic completion. Unblocks Phase 2 parallel firing (lanes can fire concurrently) and Phase 3 graph compilation (semantic lane structure maps to relation-policy gates).

Verification

npm run verify clean — 1378 tests across 120 files.

Out of scope

Stale-graph routing to reconciliation deferred to petri-graph-compilation (Phase 3) — depends on graph-revision tokens from FE-700.

Traceability

Requirements 46–50; spec §2 (layer split), §4 (canonical slice-net), §6 (transition contracts), §7 (event model), §8 (failure-mode nets), §10 (prototypes A–C). Frontier petri-semantic-lanes in memory/PLAN.md. Under umbrella H-6476.

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-747: Declarative output arcs — topology-level routing for branching transitions #154
• FE-745: Merge slice worktrees into epic-scoped dir for verify-epic #152
• FE-743: Petri parallel execution — concurrent firing, resource pools, worktree-per-slice #149
• FE-738: Petri semantic lanes — two-lane subnet, compiler split, engine factory #148 👈 (View in Graphite)
• FE-730: Orchestrator POC — Greenfield orchestrator with pi-agent dispatch #143
• main

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

[cursor]

PR Summary

Medium Risk
Changes core plan execution topology and CLI/engine entry points; behavior is heavily contract-tested but stale-graph routing remains deferred.

Overview
Phase 1 (petri-semantic-lanes) extends the orchestrator so mechanical TDD completion and semantic completion are separate in the net: after done-spec, slices must pass assess-semantic and reach semantic-satisfied before return-done; failed semantics route back to needs-more with a semantic-budget / maxSemanticReworks cap.

The compiler is split into compileTopology → NetBlueprint (pure topology + HandlerDescriptor recipes + TransitionContract metadata) and wireHandlers → PetriNet. createOrchestrator('serial') replaces duplicate proc/petri engine classes; brunch cook uses --policy=serial instead of --engine. The interpreter emits spec §7 events (transition_fired, net_halted, net_deadlocked). Contract/adapter tests cover the new lane, topology counts, events, and semantic rework exhaustion; pi-actions adds a POC assess-semantic that auto-satisfies. Plan docs mark FE-738 done and drop exhausted memory/CARDS.md.

^{Reviewed by Cursor Bugbot for commit 745c45a. 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.

There are 2 total unresolved issues (including 1 from previous review).

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

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