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]

• 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
• 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 👈 (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 side-effect writes guarded by optional runDir and wrapped in try/catch; core orchestration path unchanged when runDir is omitted.

Overview
Adds Petrinaut integration artifacts for cook runs: after topology compilation, optional runDir triggers best-effort writes of net.json (Brunch PetrinautNet schema 0.1.0) and net.sdcpn.json (Petrinaut file-picker import format).

New pure modules serializeBlueprint maps NetBlueprint → places, transitions (with enumerateCandidateOutputs arcs + contract metadata), and initial marking with UUID tokens; toSdcpnFile projects that into uncoloured SDCPN (PascalCase place names, per-place token counts, always-enabled predicates—visualization-only, not executable guards).

OrchestratorInput.runDir is wired from cook-cli; export is skipped when omitted. placeName is exported from petri-net for label stripping. Export failures are swallowed so runs still execute.

Coverage: petrinaut-export.test.ts and petrinaut-sdcpn.test.ts (including a mirrored Petrinaut loader schema check).

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

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

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

The base branch was changed.

[graphite-app]

Merge activity

• Jun 2, 4:35 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.