FE-763: Petrinaut event stream — initial markings + transition firings

[kostandinang]

Summary

• New module petrinaut-events.ts — createPetrinautEventStream({ runId, filePath?, tokenIdFn?, onEvent? }) returns a NetEventSink adapter plus emitInitialMarking(blueprint) helper. Writes one JSON object per line to filePath when provided and fans out to onEvent for in-process consumers.
• Cook writes <runDir>/petrinaut-events.jsonl on every run: initial_marking up-front, then transition_fired per fire, then any net_halted / net_deadlocked terminal event.
• Wire format matches the cross-team agreement (2026-05-26): tokens are { id: <UUID>, ...payload }; input / output are Record<place, tokens[]>; every event carries runId.

Context

• Pairs with FE-762 (blueprint export) — together they give Petrinaut everything it needs to visualize a live cook run. Blueprint is the static topology; this PR is the runtime overlay.
• Stacks on FE-762 because both writers extend engine.ts with input.runDir-conditional behavior; chaining them avoids a self-conflict in that file. Stack ordering is a Graphite concern; the underlying frontier items remain "parallel" per memory/PLAN.md.
• Decouples visualization from reports.jsonl — Petrinaut consumes the new stream directly; reports stay the orchestrator's internal log.
• Halt outcomes (FE-761 Slice 2b halted-as-place) appear naturally as halt tokens landing on slice:<sid>:halted / epic:<eid>:halted places via transition_fired events, plus a terminal net_halted from the engine.

What changed

• New src/orchestrator/src/petrinaut-events.ts: pure adapter from the orchestrator's NetEvent stream to Petrinaut's wire format.
  • Types: PetrinautEvent discriminated union over initial_marking / transition_fired / net_halted / net_deadlocked; PetrinautToken { id, sliceId?, epicId?, retryCount?, reworkCount?, haltReason? }.
  • emitInitialMarking(blueprint) derives the up-front marking from blueprint.initialTokens, assigns fresh UUIDs, and groups by place.
  • sink.emit(event) translates each NetEvent into the corresponding Petrinaut event, building input / output records from the parallel consumedTokens / producedTokens arrays.
• petri-net.ts: NetEvent gains parallel optional consumedTokens?: Token[][] and producedTokens?: Token[][] arrays — populated for transition_fired so the adapter can include per-arc token payload without re-reading the net. scheduleDeferred gains a consumedTokens parameter alongside consumedPlaces so async fires emit the same shape as sync fires.
• net-compiler.ts: all four scheduleDeferred call sites pass the captured consumed tokens through.
• engine.ts: when input.runDir is present, opens a Petrinaut event stream writing to <runDir>/petrinaut-events.jsonl, emits initial_marking from the compiled blueprint, then passes the sink to net.run().

Verification

• 4 new unit tests in petrinaut-events.test.ts: initial_marking grouping, transition_fired adapter shape, terminal-event forwarding, JSONL file roundtrip via mkdtempSync + readFileSync.
• 1 new end-to-end test in engine-contract.test.ts running simplePlan happy path with the Petrinaut sink — asserts initial_marking first, runId on every event, the FE-761 Slice 4 dispatch + complete transition names both appear in the stream, every token carries an id, and happy paths emit no net_halted / net_deadlocked.
• All 130 orchestrator tests pass; full npm run verify (check + test + build) green.
• Outer-loop end-to-end replay against Petrinaut's live consumer deferred to FE-764 transport work and cross-team validation.

Out of scope

• Transport / sync server — wiring the event stream to a live Petrinaut session (FE-764).
• Token UUID lifecycle across consume → emit (lineage tracing) — v1 generates fresh UUIDs per emission; pending Petrinaut team confirmation on whether identity should persist.
• Petrinaut blueprint export — sibling sub-issue (FE-762), already in the stack.
• Final JSON envelope shape per Petrinaut's loader — v1 best-guess; expect cross-team revisions once Petrinaut publishes their schema.

Traceability

• Linear FE-763 (parent FE-760); pairs with FE-762 and feeds FE-764.
• Frontier petri-event-stream in memory/PLAN.md; stacks on FE-762 (which stacks on FE-761).

[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-763: Petrinaut event stream — initial markings + transition firings #158 👈 (View in Graphite)
• 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
• 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

Low Risk
Observability-only integration behind runDir with best-effort I/O; interpreter event shape changes are localized to the new adapter and existing optional sinks.

Overview
Adds a Petrinaut-shaped runtime event stream so live cook runs can be visualized without parsing reports.jsonl. A new createPetrinautEventStream adapter turns internal net events into initial_marking, transition_fired (per-place input/output with { id, ...payload } tokens), and terminal net_halted / net_deadlocked events, optionally appending JSONL to <runDir>/petrinaut-events.jsonl and fanning out via onEvent.

When input.runDir is set, the orchestrator emits initial_marking from the compiled blueprint, then passes the stream’s NetEventSink into net.run() (best-effort; failures do not halt the cook). The Petri interpreter now attaches consumedTokens / producedTokens on transition_fired events (including deferred completions via an extended scheduleDeferred), and deferred handler call sites pass through the consumed token snapshot.

Coverage adds unit tests for the adapter/JSONL and an engine contract test wiring wireHandlers + the stream on a happy-path plan.

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

[augmentcode]

🤖 Augment PR Summary

Summary: Adds a Petrinaut-focused runtime event stream to the orchestrator so Petrinaut can visualize live cook runs (initial marking + per-transition firings + terminal outcomes).

Changes:

• Introduced createPetrinautEventStream() (petrinaut-events.ts) that adapts internal NetEvents into the cross-team JSONL wire format and can optionally write petrinaut-events.jsonl.
• Added emitInitialMarking(blueprint) helper to emit a single up-front initial_marking event derived from the compiled blueprint.
• Extended NetEvent to include per-arc consumedTokens/producedTokens so downstream adapters can include token payloads without re-reading net state.
• Threaded consumed token data through deferred transition completion (scheduleDeferred) and through net-compiler call sites.
• When input.runDir is present, the orchestrator now opens the Petrinaut JSONL stream, emits initial_marking, and passes the sink into net.run().
• Added unit tests for adapter shape + JSONL roundtrip, plus an end-to-end contract test asserting ordering and per-event runId.

Technical Notes: The stream writes one JSON object per line (JSONL) and fans out to an optional in-process onEvent callback; token IDs are generated per emission (lineage persistence is explicitly deferred).

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

[augmentcode]

Review completed. 3 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 74e4df4. Configure here.}