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 path gated on runDir; core firing semantics unchanged aside from richer event metadata for adapters.

Overview
Adds a Petrinaut runtime event stream so live cook runs can be visualized alongside the static blueprint (FE-762).

A new createPetrinautEventStream adapter turns internal NetEvents into the agreed wire shape: initial_marking (from blueprint seeds), transition_fired with per-place input/output tokens ({ id, …payload }), and net_halted / net_deadlocked. When input.runDir is set, the engine writes <runDir>/petrinaut-events.jsonl, emits initial marking before net.run, and passes the sink through; callers without runDir stay unchanged.

The Petri interpreter now attaches consumedTokens / producedTokens on transition_fired (sync and deferred completions), and scheduleDeferred takes the consumed token list so async handler completions show the same payload as synchronous fires.

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

[augmentcode]

transitionName: event.transitionId ?? '' will silently emit an empty transition name if an upstream transition_fired event is malformed; that can hide bugs and may violate the Petrinaut schema. Consider failing fast (or otherwise making missing transitionId unmistakable) for transition_fired events.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

groupTokens() returns {} when places is present but tokens is missing, which would silently drop arc/place information from emitted Petrinaut events. Consider validating places/tokens alignment and/or emitting empty arrays per place so data loss is obvious.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

This test description mentions net_halted, but the assertions below expect zero net_halted/net_deadlocked events on the happy path; consider updating the description to match the intended behavior.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[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 9c0641c. Configure here.}

[cursor]

Deferred handlers emit duplicate transition_fired events with consumed tokens

Medium Severity

For deferred fire handlers (action, run-tests, assess-semantic, verify-epic), depositClaim emits a transition_fired event with populated consumedTokens but empty producedTokens when the fire handler returns []. Then completeDeferred emits a second transition_fired for the same transition with the same consumedTokens plus the actual producedTokens. The rename from _consumed to consumed and the addition of consumedTokens: consumed.map((t) => [t]) means the Petrinaut stream now receives two rich events per deferred firing — the first showing tokens vanishing with no output, the second claiming the same tokens were consumed again. A Petrinaut visualizer animating token movements would see contradictory state.

Additional Locations (1)

• src/orchestrator/src/petri-net.ts#L165-L191

 

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