FE-762: Petrinaut-format JSON export of the compiled net

[kostandinang]

Summary

• New module petrinaut-export.ts — pure serializer serializeBlueprint(blueprint, { runId, tokenIdFn? }) → PetrinautNet converting the (FE-761 Petri-net-faithful) NetBlueprint into Petrinaut's expected JSON shape.
• Cook writes <runDir>/net.json on every run so the Petrinaut team can render the compiled topology and pressure-test the integration.
• Token shape { id: <UUID>, ...payload } per the cross-team-agreed format; envelope carries schemaVersion 0.1.0 for forward-compatibility.

Context

• Second sub-issue of the Petrinaut integration sub-track (parent FE-760). Pairs with FE-763 (event stream); together they give Petrinaut everything it needs to visualize a live cook run.
• Stacks on FE-761 (Petri-net semantic alignment). The blueprint already exposes the topology in a serializer-friendly shape — places + transitions + initialTokens — so this is a thin export layer rather than a substrate refactor.
• The Petrinaut team is unblocked: they were waiting on a sample net.json for fixtures/txt/ to begin their side of the work.

What changed

• New src/orchestrator/src/petrinaut-export.ts: pure serializer.
  • Types: PetrinautNet { schemaVersion, runId, places, transitions, initialMarking }, PetrinautPlace { id, label }, PetrinautTransition { id, label, lane, kind, actor, guard, inputs, outputs }, PetrinautToken { id, sliceId?, epicId?, retryCount?, reworkCount? }, PetrinautMarking { place, tokens[] }.
  • Places: full internal IDs preserved as id; short visual label strips the slice:<id>: / epic:<id>: prefix.
  • Transitions: inputs come from TransitionSkeleton.inputs; outputs from enumerateCandidateOutputs (so the full reachable output set is visible to Petrinaut, including the FE-761 Slice 4 dispatch → running:* arcs).
  • Initial marking: tokens grouped by place, each assigned a fresh UUID; semantic payload fields (sliceId, epicId, retryCount, reworkCount) preserved when present.
• engine.ts: when input.runDir is present, writes the serialized net to <runDir>/net.json after compileTopology() returns. Library callers and tests that omit runDir are unaffected.
• cook-cli.ts: passes the existing runDir through to the orchestrator.
• types.ts: OrchestratorInput gains optional runDir field.

Verification

• 10 new tests in petrinaut-export.test.ts: envelope (schemaVersion, runId), places (label-stripping), transitions (arc shape, contract metadata), initial marking (tokens grouped, UUIDs distinct, payload preserved), JSON round-trip, golden counts pinned per fixture (simplePlan: 22 places, 19 transitions, 5 places hold initial tokens; depPlan: 42 places, 37 transitions, 8 places).
• All 125 orchestrator tests pass; full npm run verify (check + test + build) green.
• Outer-loop integration smoke (real Petrinaut loader round-trip on fixtures/txt/) deferred to cross-team validation once the loader is available.

Out of scope

• Runtime event stream — initial markings event + transition-firing events (FE-763).
• Sync transport — wire net.json and event stream to a live Petrinaut session (FE-764).
• Final JSON envelope wire format per Petrinaut's loader — v1 is a sensible best-guess; expect cross-team revisions once Petrinaut publishes their schema reference.
• Discrete-type system for semantic IDs (string vs uuid) — pending Petrinaut's H-6518 / H-6519.

Traceability

• Linear FE-762 (parent FE-760); pairs with FE-763 and feeds FE-764; H-6518 / H-6519 (Petrinaut discrete types).
• Frontier petri-blueprint-export in memory/PLAN.md; 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
• FE-762: Petrinaut-format JSON export of the compiled net #157 👈 (View in Graphite)
• 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
Additive optional filesystem write after compile; no changes to Petri net firing or cook execution semantics.

Overview
Adds a Petrinaut JSON export of the compiled Petri net so cook runs can ship topology to the visualization team.

A new pure serializeBlueprint maps NetBlueprint to PetrinautNet (schemaVersion 0.1.0, runId, places with short labels, transitions with full input/output arcs via enumerateCandidateOutputs, and initial marking with per-token UUIDs and semantic payload fields). When OrchestratorInput.runDir is set, the engine writes <runDir>/net.json immediately after compileTopology; cook-cli now passes the existing run directory. Callers without runDir behave as before.

Tests cover envelope, labeling, transition metadata, marking grouping, JSON round-trip, and golden topology counts for fixture plans.

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR adds a Petrinaut-compatible JSON export for the compiled Petri net so runs can be visualized/validated by the Petrinaut team.

Changes:

• Introduces petrinaut-export.ts with serializeBlueprint() to convert a NetBlueprint into a PetrinautNet envelope (schemaVersion, runId, places, transitions, initialMarking).
• Derives transition outputs via enumerateCandidateOutputs to expose the full reachable arc set.
• Adds a deterministic token-id hook for tests; production uses UUIDs.
• Extends OrchestratorInput with optional runDir.
• Updates the engine to write <runDir>/net.json after compileTopology() when runDir is provided.
• Threads runDir through the cook CLI into the orchestrator.
• Adds comprehensive Vitest coverage for envelope fields, label stripping, arc shape/metadata, marking/token behavior, and golden counts per fixture.

Technical Notes: The export is designed as a pure serializer (no I/O); file output is owned by the runtime engine path when running via CLI.

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

[augmentcode]

Review completed. 1 suggestion posted.

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

[augmentcode]

src/orchestrator/src/engine.ts:38 — Because the writeFileSync is inside the main try, any failure to write net.json (missing/unwritable runDir, permissions, disk issues) will halt the entire cook run even though compilation succeeded. If this is intended as best-effort integration output, it may be worth ensuring export failures don’t change the run’s success/failure semantics.

Severity: medium

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