FE-764: Brunch<> Petrinaut stream — ephemeral orchestrator hosted SSE server

[kostandinang]

Screen Recording 2026-06-02 at 11.18.34 PM.mov (uploaded via Graphite)

Linear: FE-764 · Stack: main ← … ← ka/fe-784 (PR #160) ← ka/fe-764 (this)

Stream an executing brunch cook run into Petrinaut's read-only "actual/live" tab over one SSE connection hosted by the cook process itself. Ephemeral, localhost-only, dies with the run, persists nothing. Replay-on-connect: definition → initial_state → all firings so far → live firings → terminal.

Changes

• BrunchExecutionExport contract types + reducer (petrinaut-stream-export.ts)
• --petrinaut-fold=color|identity cook CLI flag (default identity); shared NetFolding seam between static export and live stream (cook-cli.ts, petrinaut-fold.ts, engine.ts)
• In-process stream bus with replay buffer + PetrinautEvent → BrunchExecutionExportFrame translator (petrinaut-stream-bus.ts)
• Ephemeral HTTP/SSE server over the bus, localhost-only, one GET /stream route (petrinaut-stream-server.ts)
• --petrinaut-stream cook wiring with multi-tier base-URL (CLI flag > PETRINAUT_BASE_URL env > hard fail), launcher-URL composer, auto-open via open package; server.stop() in finally (cook-cli.ts, petrinaut-launcher-url.ts, engine.ts)
• OrchestratorInput.setupPetrinautStream awaited factory hook so the SSE server is listening before initial_marking fires (types.ts, engine.ts)
• loadLocalEnvShellWins local .env loader (shell-wins precedence, only loaded when streaming)
• .env.example line for PETRINAUT_BASE_URL

Web-UI button + endpoint discovery left as a follow-up (memory/CARDS.md slice 5 sketch).

How to try it

# one-time setup
echo 'PETRINAUT_BASE_URL=https://your-petrinaut.example/import' >> .env

# run cook with live stream
brunch cook <dir> --petrinaut-stream
# → prints launcher URL, auto-opens browser

Flags:

• --petrinaut-stream — boot the SSE server + compose URL (opt-in; default off)
• --petrinaut-base-url=<url> — override env (requires --petrinaut-stream)
• --no-petrinaut-open — suppress auto-open; URL still prints (CI=true also suppresses)
• --petrinaut-fold=color|identity — projection mode (default identity; orthogonal to streaming)

Base-URL resolution: CLI flag > PETRINAUT_BASE_URL env > hard fail before any cook side effect.

Endpoints (cook-hosted, ephemeral, localhost-only)

http://127.0.0.1:<ephemeral-port>
  ├── GET     /stream  →  200 text/event-stream  (replay → live → close on terminal)
  ├── OPTIONS /stream  →  204 CORS preflight (GET, OPTIONS, *)
  └── *                →  404 Not Found

SSE frame shape (one event per BrunchExecutionExportFrame):

event: definition       data: {"version":1,"meta":…,"places":[…],"transitions":[…]}
event: initial_state    data: {"<placeId>": <number | TokenColour[]>, …}
event: transition_firing data: {"transitionId":"…","input":…,"output":…,"ts":"…"}
event: terminal         data:

Curl test guide

Grab <port> from the cook stderr, then:

URL=http://127.0.0.1:<port>/stream

curl -N $URL                       # live feed (closes on terminal frame)
curl -sI $URL                      # headers — text/event-stream + CORS
curl -sX OPTIONS -D - $URL -o-     # CORS preflight — 204
curl -sI $URL/nope                 # 404

Late-connect replay: the same curl -N $URL after the run finishes still receives the full timeline (definition → initial_state → all firings → terminal) before the connection closes.

Architecture

brunch cook  ──┐
               │   compileTopology + folding + sdcpnFile
               ▼
       ╭───────────────╮   await   ╭──────────────────────╮
       │ engine.run    │──────────▶│ setupPetrinautStream │
       │               │           │ ├─ createBus()        │
       │ emit events ──┼──────────▶│ ├─ createServer()     │
       │               │   onEvent │ ├─ server.start() (await)
       │               │           │ ├─ composeLauncherUrl()
       ╰───────────────╯           │ ├─ openUrl()          │
                                   │ ╰─ return bus.publish │
                                   ╰──────────────────────╯
                                              │
                                       SSE /stream
                                              ▼
                                      Petrinaut client

Key invariant: the SSE server is listening before the engine emits initial_marking. Enforced by an await-ordering test in engine-contract.test.ts.

Petrinaut contract alignment (verified against hashintel/hash)

• Marking ≡ InitialMarking byte-for-byte (petrinaut-core/simulation/api.ts)
• NetDefinition is a tight subset of sdcpnFileSchema; missing fields default to [] in parseSDCPNFile — can reuse the existing parser unchanged
• Field names match (colorId, inputArcs, outputArcs, lambdaType, lambdaCode, transitionKernelCode, dynamicsEnabled, differentialEquationId); schema version: 1 matches SDCPN_FILE_FORMAT_VERSION
• No live/SSE consumer exists in Petrinaut yet

Out of scope (v1)

Write-back / editing · persistent runs DB · auth · non-localhost transport · colour SDCPN (waits on Petrinaut H-6518/H-6519) · discovery endpoint · Last-Event-ID resume · SSE keep-alive.

Verification

npm run verify — 1571 tests green. Real-HTTP coverage in petrinaut-stream-server.test.ts; cook-CLI lifecycle in cook-cli.test.ts; await-ordering invariant in engine-contract.test.ts.

[kostandinang]

• FE-800: Spec to orchestrator plan emitter — generate plan.yaml from a completed specification #167 : 2 dependent PRs (#168 , #170 )
• FE-764: Brunch<> Petrinaut stream — ephemeral orchestrator hosted SSE server #165 👈 (View in Graphite)
• FE-784: Petrinaut export: colour-fold per-slice subnet #160
• 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
• 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
Introduces cook-time network I/O, browser auto-open, and strict engine/setup ordering before first Petrinaut events; mitigated by localhost bind, opt-in flag, and pre-flight base-URL failure.

Overview
Adds FE-764 end-to-end Petrinaut live streaming for brunch cook: an opt-in --petrinaut-stream path boots a localhost-only ephemeral SSE server (GET /stream) that replays then streams BrunchExecutionExport frames (definition → initial_state → firings → terminal).

New plumbing includes reduceBrunchExecutionExport, an in-process createPetrinautStreamBus (replay-on-subscribe), createPetrinautStreamServer, and pure resolvePetrinautBaseUrl / composeLauncherUrl. runCook resolves PETRINAUT_BASE_URL (CLI > env > hard fail before cook side effects), prints/opens a launcher URL (runId, mode=actual, sse=…), and server.stop() in finally.

--petrinaut-fold=color|identity (default identity) plus createIdentityFolding share one NetFolding between on-disk export and the live stream via OrchestratorInput.petrinautFold. The engine awaits setupPetrinautStream before initial_marking, and happy-path runs now emit net_completed through the Petrinaut event/SSE path.

Docs: .env.example, memory/PLAN.md, memory/SPEC.md (identity fold), and memory/CARDS.md (slice status).

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

[lunelson]

Really solid work — the replay-equivalence oracle (proving the live stream and the static export reduce to the same thing), the await-ordering invariant, the real-HTTP server tests, and verifying the wire shape against the actual Petrinaut repo all give a lot of confidence in the parts that have a counterpart to check against.

A few things above the code level, all questions rather than asks:

1. cook becomes a network host. brunch cook was a batch CLI; with this it can stand up an HTTP listener. It's nicely contained — localhost-only, ephemeral, off by default — but it's a genuine posture change. Is "cook hosts its own transient services" a direction we want to lean into, or is this a one-off for Petrinaut? Worth being deliberate about, since the next feature may reach for the same pattern.

2. Petrinaut-specific hooks on the generic engine contract. OrchestratorInput now carries petrinautFold, onPetrinautEvent, and setupPetrinautStream — and the last returns a callback that's fanned out alongside onPetrinautEvent, so two of the three overlap. The generic orchestrator also now names a specific consumer in its core input type. Could the streaming concern collapse to a single seam, or sit behind a generic event sink that the Petrinaut layer adapts, so the engine stays consumer-agnostic?

3. Producer ahead of consumer. Since no live Petrinaut client consumes this yet, the transition_firing frames in particular are unexercised by a real reader. The definition frame is pinned to the real schema, which helps. Is the live-frame shape firm enough to commit to, or worth treating as provisional until a consumer lands?

One observation, not a concern: streaming pushed pi-actions from spawnSync to async spawn so the loop can flush frames — sensible, just noting the agent-execution path's concurrency model changed in service of a viz feature.

Approving — none of this blocks the merge.

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