FE-1882: Convert Petrinaut entity IDs to UUIDs

[kube]

Summary

Before this PR, net and subnet ids and newly created entity ids were UUIDs. Places, transitions, types, type elements, parameters, equations, scenarios, metrics and component instances loaded from a document, or given by a host or an assistant, kept their ids, such as place__queue or p1.

Converts every entity id the same way as net ids: a UUID passes through lowercased, and any other id becomes its UUIDv5 in the same fixed namespace. Core converts each id together with every reference to it when a document, file, clipboard payload, recording or manifest loads. Mutation, command, assistant tool and experiment inputs convert the same way. CLI selectors and Brunch history match old ids against converted ones. Same legacy id always maps to the same UUID, so references converted at different boundaries stay linked.

Links

• Ticket FE-1882
• Docs Embedding in a host application
• Docs Untrusted names
• Docs CLI usage manual
• Docs Actual Mode › Timeline and events

Changes

Petrinaut core

• canonicalizePetrinautIds converts every entity id and every reference to it

  Arc endpoints, type and equation references, component instances' subnet ids and parameter value keys, and scenario overrides and initial states keyed by id convert with them, at the root and in subnets.
  Names, user code, metadata, scenario parameter identifiers and token values stay as written.

• canonicalizeArcId converts the ids inside a generated arc id

  An arc id built from old ids names the same arc after its places and transitions convert.

• Mutation, command and assistant tool inputs convert ids

  idSchema converts any non-UUID string, and records keyed by id convert their keys.
  idSchema replaces subnetIdSchema.
  Arc items in deleteItemsByIds use arcIdSchema, which runs canonicalizeArcId.

• Experiment requests, optimization manifests and Actual mode recordings convert ids

  Actual mode markings and firings convert their place and transition ids.

• Clipboard payloads convert as a whole, so a payload copied with old ids pastes with its arcs
• File import converts reserved ids such as __proto__ instead of rejecting them

  Reserved names are still rejected.

Petrinaut

• Preview checks precompiled scenarios against the converted document

Website

• Core examples load with converted ids, in the catalog and in the build-time scenario compiler

  Precompiled scenarios match the document the Preview opens.

• Stored nets convert every entity id on read
• AI experiments demo reads its metric by converted id

CLI

• Run selectors match an element's id or the converted form of an old id

  Parameters, places, metrics and scenarios resolve this way.
  Results report UUID keys.

HASH

• Process embed opens saved nets with converted ids

  A net saved with old ids stores UUIDs on its next save.

Brunch

• History attribution matches model-written ids against converted document ids

  namesId matches a written id as is, after toPetrinautId, or after canonicalizeArcId.

• Draft experiments convert reportedByMetricId like their metric ids
• Modelling guidance says supplied ids are stored as UUIDs

Review fixes

• Experiment, optimization, scenario and Actual mode id fields share one petrinautIdSchema

  idSchema derives from it.

• In-band browser calls parse both the issued and the admitted input before comparing them

  Ids compare converted whether or not the Brunch server converts them.

• Actual mode converts the Brunch stream's definition

  Its places and transitions carry the converted ids that markings and firings name.

• Assistant change summaries convert a call's ids themselves

  Rows for calls not yet applied target the existing items.

• Synthesized ad-hoc scenario id is toPetrinautId("adhoc-scenario")
• Brunch workpiece queries reuse namesId
• Brunch attribution converts only id fields

  Names, kinds and code compare exactly, so they cannot match a converted id.

• Recordings normalize their definition

  Omitted collections fill in before ids convert.

• One release note per package

Known issues

• Links that name an item or scenario by an old id open the default view

  Remapping old ids in links and showing names where raw ids appear are not part of this change.

Test coverage

• petrinaut-id.test.ts:

  Every definition and every reference converts, at the root and in subnets.
  Names, metadata, scenario parameter identifiers and token values do not.
  Idempotence, identity preservation and canonicalizeArcId for place and component port arcs.

• ai.test.ts:

  Entity id, arc id and id-keyed record key inputs export as plain JSON Schema strings.
  An assistant's own ids resolve across add place, add transition, add arc and delete by arc id.

• parse-sdcpn-file.test.ts:

  Entity ids and references convert on import.
  A __proto__ place id imports as its UUID.
  A reserved colour element name is still rejected in the legacy format.

• commands.test.ts, optimization.test.ts, host.test.ts, actual-mode.test.ts:

  Legacy clipboard payloads, manifests, experiment requests and recordings convert.

• create-petrinaut-optimization-run-handler.test.ts:

  Handler forwards the parsed manifest, whose ids are converted.

• net-change-attribution.test.ts, draft-experiment.test.ts:

  Brunch attributes a change written with the model's own ids, and a draft's reporting metric id converts.

• Existing core, Petrinaut, website, CLI and Brunch suites and the Brunch browser witness, with expectations on converted ids

How to test

• Open Petrinaut preview on Vercel
• Menu > Load example > SIR Model
• Menu > Export > JSON

  Expect every place, transition, scenario and metric id to be a UUID

• Menu > Import > JSON file exported from production

  Expect the net to load and simulate

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 8, 2026 6:47pm UTC
petrinaut	Ready	Preview	Oct 8, 2026 6:47pm UTC
petrinaut-docs	Ready	Preview	Oct 8, 2026 6:47pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 8, 2026 6:47pm UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

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