FE-1121: Add UUID token dimension type

[kube]

🌟 What is the purpose of this PR?

Adds uuid as a fourth colour element type: 128-bit RFC-4122 identifiers on tokens, enabling entity-identity modelling (track a specific token across places, correlate firings, derive stable IDs from data). This is the first token attribute wider than one f64 slot — it exercises the format-v2 packed-struct layout exactly as designed.

🔗 Related links

• FE-1121: Add UUID discrete type to Petrinaut (internal — full design record and decisions in the ticket)
• Stacked on FE-1139: Simulation architecture documentation #8951 → FE-1130: Token frame format v2 — packed struct token layout #8944 → FE-1129: Token encoding playground (Storybook) #8943 → H-6519: Add discrete token attribute types #8764.

🚫 Blocked by

• H-6519: Add discrete token attribute types #8764 → FE-1129: Token encoding playground (Storybook) #8943 → FE-1130: Token frame format v2 — packed struct token layout #8944 → FE-1139: Simulation architecture documentation #8951 (base chain — merges first)

🔍 What does this change?

Representation (three layers):

• Buffers: u64x2 physical kind — two 64-bit little-endian lanes (16 B, align 8; JS has no 128-bit load, so 8-byte alignment is deliberate), read/written through a shared BigUint64Array view. Whole-token byte copies keep arbitrary bit patterns intact — a NaN-payload UUID (ffffffff-ffff-4fff-bfff-…) round-trips through marking → dynamics → firing → compaction → clone → reader (tested).
• Runtime: one 128-bit bigint — value-semantic (tokenA.id === tokenB.id just works), measured cheaper than the string form.
• At rest (documents, scenario JSON): canonical lowercase 36-char strings, keeping everything JSON.stringify-safe.

Kernel semantics:

• uuid output fields are optional: omitted ⇒ auto-generated from the seeded simulation RNG (deterministic per seed; v4 version/variant bits forced; never crypto.randomUUID).
• Uuid.generate() (explicit seeded generation) and Uuid.from(value) (derive a stable ID from any value) are injected into user code as engine-resolved sentinels, mirroring Distribution. Forwarding an input token's uuid is plain pass-through.
• Kernel token encoding is deduplicated into engine/encode-kernel-token.ts, shared by the interactive engine and Monte Carlo (was copy-pasted).
• Distribution on a uuid field stays a type error (LSP) and a runtime error.

Coercion — total toUuid(value): bigint, never throws: valid UUID strings parse (any case → canonical); bigint in range passes through; anything else (numbers, free text) converts deterministically via UUIDv5 under a fixed exported PETRINAUT_UUID_NAMESPACE; nil UUID (0n) is the typed default.

LSP: input tokens type uuid as bigint; kernel outputs now generate per-element Output_<colour> types in both stochasticity modes with uuid?: bigint | string | PetrinautUuid; Uuid/PetrinautUuid declarations always available; dynamics derivatives keep uuid?: never.

UI: UUID option in the dimension type select; spreadsheet uuid cells show an 8-hex short form (full canonical string via title and when selected/edited; committed text goes through toUuid, so free text like alice yields a stable ID; Delete → nil); scenario drawers round-trip strings⇄bigints; the token-encoding playground renders u64x2 slots with lo/hi lane labels and the canonical string in the hover panel.

Docs/schema/AI guidance updated (petri-net-extensions.md + scenario/simulation notes, Zod descriptions, ai.ts).

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR
  • ⚠️ the token-type screenshot in petri-net-extensions.md shows a 3-option dropdown and should be re-captured with UUID visible

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• The ticket's original "support any UUID smaller than 32 bytes" is deliberately narrowed to RFC-4122 128-bit only — display, v5 coercion, and the uuid library all assume 16 bytes; the layout machinery generalizes to u64×4 later if a real need for wider IDs appears (noted on the ticket).
• Metrics receive uuid values as bigint — fine for comparison/counting, but JSON.stringify on a whole token would throw in user code (standard bigint behaviour).

🐾 Next steps

• Re-capture the dimension-type screenshots (3 → 4 options).
• Architecture docs engine page: flip the uuid row in the format-v2 table from "future" to shipped (can ride this PR or a follow-up).

🛡 What tests cover this?

• New engine/uuid.test.ts (parse/format, toUuid fixtures incl. stable v5, generateUuidFromRng determinism + version/variant bits)
• token-layout u64x2 sizing/offset/lane tests; end-to-end NaN-payload pipeline test in compute-next-frame.test.ts
• Kernel tests: omitted-uuid seeded determinism, Uuid.from stability, forwarding, Distribution-on-uuid throws
• LSP checker tests: bigint input typing, optional/string/Uuid.generate() outputs valid, Distribution on uuid invalid
• compile-scenario canonical-string normalization; spreadsheet/playground unit tests
• Totals: 592 core + 139 UI tests, lint:tsc + lint:eslint clean

❓ How to test this?

1. Checkout the branch, yarn dev in libs/@hashintel/petrinaut.
2. Add a UUID dimension to a type; open a place's initial state — cells show short-form IDs; type free text into a cell and watch it become a stable UUID.
3. Author a kernel omitting the uuid field → run twice with the same seed → identical generated IDs; use Uuid.from(input.Source[0].some_value) for derived IDs.
4. Open Dev / Token Encoding Playground, add a UUID dimension: the memory view shows the 16-byte u64x2 slot with lo/hi lanes and the canonical string on hover.

📹 Demo

The playground story renders the exact wire format: a UUID slot with lane labels and the input → stored → reads-back round-trip.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 7, 2026 12:48pm
petrinaut	Ready	Preview, Comment	Jul 7, 2026 12:48pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 7, 2026 12:48pm

[cursor]

PR Summary

Medium Risk
Touches core simulation frame layout, RNG consumption order, and persisted UUIDv5 namespace semantics—mistakes would corrupt determinism or stored IDs—but the change is heavily tested and mostly additive behind a new element type.

Overview
Introduces uuid as a fourth colour element type for entity-identity modelling: bigint in simulation code, canonical lowercase strings in documents/scenarios, and u64×2 (16 B) lanes in format-v2 frames via a shared BigUint64Array view—never routed through number/Float64Array so arbitrary bit patterns (e.g. NaN-payload UUIDs) survive dynamics, firing, and compaction.

Kernel & RNG: Optional uuid fields on transition outputs auto-generate deterministic v4-shaped IDs from the seeded RNG; Uuid.generate() / Uuid.from(value) are injected as sentinels (like Distribution). Coercion is total via toUuid (parse strings, UUIDv5 for arbitrary text under a fixed namespace). Shared encode-kernel-token.ts replaces duplicated packing in the interactive engine and Monte Carlo paths.

Authoring surface: Zod/schema, LSP virtual types (bigint inputs; optional Output_* kernel types), scenario compile (string rows), AI cheatsheet, default kernel templates (Uuid.generate()), and user docs are extended. UI: UUID in type pickers; spreadsheet cells round-trip uuids (short display, toUuid on edit); scenario drawers serialize bigints back to strings.

Public exports add formatUuid, parseUuid, toUuid, etc. Architecture engine.html marks uuid as shipped rather than future.

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

[Copilot]

Pull request overview

Adds a new uuid token dimension type to Petrinaut (UI + persistence + simulation/LSP), represented as bigint at runtime, encoded as u64x2 in frame buffers, and stored as canonical UUID strings at rest.

Changes:

• Introduces UUID parsing/formatting/coercion (toUuid, seeded generation, v5 fallback) and wires it through kernel output encoding and token-layout packed structs.
• Extends UI editors (type dropdown, initial state + scenario spreadsheets, encoding playground) to display/edit UUIDs and round-trip at-rest strings ⇄ runtime bigints.
• Updates schemas, LSP virtual files, AI guidance, and adds broad test coverage for UUID behavior and determinism.

Reviewed changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
libs/@hashintel/petrinaut/src/ui/views/shared/place-state-visualization.tsx	Coerces initial marking token records so uuid strings become runtime bigints.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/SimulateView/scenarios/view-scenario-drawer.tsx	Plumbs token-row context and uses mapping helpers for scenario spreadsheet data.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/SimulateView/scenarios/scenario-mapping.ts	Converts scenario persisted rows (uuid strings) ⇄ spreadsheet runtime values (bigints).
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/SimulateView/scenarios/create-scenario-drawer.tsx	Provides token-row context when creating new scenarios.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/type-properties/subviews/main.tsx	Adds UUID to the dimension type selector.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/place-properties/subviews/place-initial-state/initial-state-editor.tsx	Parses at-rest uuid strings to bigints for the initial marking spreadsheet.
libs/@hashintel/petrinaut/src/ui/lib/compile-visualizer.ts	Allows visualizers to receive bigint token attributes.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/token-memory-view.tsx	Displays uuid values in canonical string form and labels u64x2 lanes.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/playground-monaco.ts	Types uuid fields as `bigint
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/physical-layout.ts	Updates token decode to use unified token views; documents u64x2 bit ordering.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/physical-layout.test.ts	Adds layout/round-trip/bit-order coverage for uuid (u64x2) fields.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/dimension-editor.tsx	Adds UUID option in the playground dimension editor.
libs/@hashintel/petrinaut/src/ui/components/spreadsheet.tsx	Supports uuid columns (bigint values), display truncation, and text editing/coercion.
libs/@hashintel/petrinaut/docs/simulation.md	Documents UUID behavior in the initial marking spreadsheet.
libs/@hashintel/petrinaut/docs/scenarios.md	Documents UUID behavior in scenario spreadsheets.
libs/@hashintel/petrinaut/docs/petri-net-extensions.md	Documents the new UUID dimension type and kernel semantics.
libs/@hashintel/petrinaut-core/src/types/sdcpn.ts	Extends element types + token attribute value types; updates scenario row typing.
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/transition-effect.ts	Reuses shared kernel-token encoder and unified token views.
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/frame-reader.ts	Reads tokens via unified token views.
libs/@hashintel/petrinaut-core/src/simulation/monte-carlo/frame-buffer.ts	Adds shared f64/u64/u8 token region views to Monte Carlo frames.
libs/@hashintel/petrinaut-core/src/simulation/frames/internal-frame.ts	Adds shared f64/u64/u8 token region views to engine frames.
libs/@hashintel/petrinaut-core/src/simulation/frames/frame-reader.ts	Reads tokens via unified token views.
libs/@hashintel/petrinaut-core/src/simulation/engine/uuid.ts	Implements uuid parsing/formatting/total coercion + seeded v4 generation.
libs/@hashintel/petrinaut-core/src/simulation/engine/uuid.test.ts	Tests uuid parsing/formatting/coercion and RNG-based generation invariants.
libs/@hashintel/petrinaut-core/src/simulation/engine/types.ts	Expands kernel output typing to include optional uuid + uuid sentinels.
libs/@hashintel/petrinaut-core/src/simulation/engine/token-values.ts	Adds uuid default/coercion and updates encoder return type for uuid lanes.
libs/@hashintel/petrinaut-core/src/simulation/engine/token-layout.ts	Adds u64x2 physical kind + BigUint64Array view; reads/writes uuid lanes.
libs/@hashintel/petrinaut-core/src/simulation/engine/token-layout.test.ts	Adds layout + lane-level correctness tests for uuid fields.
libs/@hashintel/petrinaut-core/src/simulation/engine/token-layout.test-helpers.ts	Updates helpers to use unified token views.
libs/@hashintel/petrinaut-core/src/simulation/engine/encode-kernel-token.ts	Deduplicates kernel output token encoding (Distribution + uuid sentinel handling).
libs/@hashintel/petrinaut-core/src/simulation/engine/compute-possible-transition.ts	Uses shared kernel-token encoder and unified token views.
libs/@hashintel/petrinaut-core/src/simulation/engine/compute-possible-transition.test.ts	Adds behavioral tests for uuid kernel outputs (omit/generate/from/forward/errors).
libs/@hashintel/petrinaut-core/src/simulation/engine/compute-next-frame.test.ts	Adds end-to-end test ensuring uuid lanes survive pipeline without NaN canonicalization.
libs/@hashintel/petrinaut-core/src/simulation/engine/build-simulation.ts	Reads tokens via unified token views for dynamics input.
libs/@hashintel/petrinaut-core/src/simulation/authoring/user-code/uuid-runtime.ts	Adds Uuid.generate/from sentinels for user code.
libs/@hashintel/petrinaut-core/src/simulation/authoring/user-code/compile-user-code.ts	Injects Uuid runtime code unconditionally into compiled user code.
libs/@hashintel/petrinaut-core/src/simulation/authoring/user-code/compile-user-code.test.ts	Tests Uuid runtime injection (including when Distribution is disabled).
libs/@hashintel/petrinaut-core/src/simulation/authoring/scenario/compile-scenario.ts	Normalizes uuid values to canonical strings for JSON-safe compiled scenario output.
libs/@hashintel/petrinaut-core/src/simulation/authoring/scenario/compile-scenario.test.ts	Adds scenario compilation tests for uuid normalization and deterministic v5 mapping.
libs/@hashintel/petrinaut-core/src/simulation/api.ts	Introduces JSON-safe initial marking typing that can accept uuid strings.
libs/@hashintel/petrinaut-core/src/schemas/scenario-schema.ts	Allows strings in persisted token rows (to support uuid-at-rest strings).
libs/@hashintel/petrinaut-core/src/schemas/entity-schemas.ts	Extends element type schema with uuid and updates descriptions.
libs/@hashintel/petrinaut-core/src/lsp/lib/generate-virtual-files.ts	Types uuid as bigint; generates kernel output types with optional uuid + sentinels.
libs/@hashintel/petrinaut-core/src/lsp/lib/checker.test.ts	Adds LSP checker tests around uuid typing and invalid Distribution-on-uuid outputs.
libs/@hashintel/petrinaut-core/src/index.ts	Exports uuid utilities and token region views.
libs/@hashintel/petrinaut-core/src/default-codes.ts	Uses Uuid.generate() as the default value source for uuid elements.
libs/@hashintel/petrinaut-core/src/ai.ts	Updates AI guidance for uuid typing and kernel/scenario semantics.
.changeset/fe-1121-uuid-token-dimension-type.md	Publishes a minor changeset describing the uuid dimension feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated 1 comment.

[kube]

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-1153: Collapse per-type switches into a type-policy registry #8964
• FE-769: Add String token dimension type (string interning) #8956
• FE-1121: Add UUID token dimension type #8953 👈 (View in Graphite)
• FE-1139: Simulation architecture documentation #8951
• FE-1130: Token frame format v2 — packed struct token layout #8944
• FE-1129: Token encoding playground (Storybook) #8943
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated 1 comment.