FE-1139: Simulation architecture documentation by kube · Pull Request #8951 · hashintel/hash

kube · 2026-07-03T13:56:22Z

🌟 What is the purpose of this PR?

Adds engineering architecture documentation for the Petrinaut simulation subsystem: five self-contained HTML pages (zero build step — open index.html in any browser) with hand-built diagrams that markdown can't express — a byte-exact EngineFrame memory map, a worker-protocol sequence diagram, lifecycle state machines, and per-module data-flow pipelines. Goal: make the architecture legible enough to refactor against, with explicit answers to "where does the memory actually live" and "what are the protocols".

🔗 Related links

FE-1139: Petrinaut: simulation architecture documentation (internal)
Stacked on FE-1130: Token frame format v2 — packed struct token layout #8944 (the docs describe frame format v2).

🚫 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 (base chain — merges first)

🔍 What does this change?

New libs/@hashintel/petrinaut-core/docs/architecture/:
- index.html — overview: the two execution paths (Quick Simulation vs Experiments), the "where the memory actually lives" table, protocols at a glance, module map, design invariants, refactoring seams (e.g. triple frame retention).
- engine.html — build/step lifecycle, EngineFrame v2 binary format with a byte-exact memory-map SVG (header fields, section offsets, packed token structs, alignment padding), token typing, determinism.
- authoring.html — the user-code compilation pipeline, which surface compiles where and runs on which thread, sandboxing posture, deferred distribution sampling.
- worker.html — full message protocol tables, an SVG sequence diagram of one simulation run, the ack/backpressure contract with play-mode profiles, lifecycle state machine.
- monte-carlo.html — run model, double-buffer memory with byte-capacity growth, the in-worker metrics pipeline, experiment protocol.
Core pages are React-free: consumers are described as "the host application" against the public API (Simulation handle, SimulationFrameReader, experiment stores). The React integration (providers, playback ack policy, experiments rendering, uPlot timeline) moved to a new libs/@hashintel/petrinaut/ARCHITECTURE.md — deliberately not in that package's docs/ folder, which is the end-user guide read by the in-app assistant.
src/simulation/ARCHITECTURE.md and src/simulation/README.md cross-link the HTML set; the HTML pages link the source files they document (e.g. frames/internal-frame.ts).
Deliberately no Docusaurus / site generator: five internal pages whose value is the custom diagrams; a build pipeline adds nothing. GitHub Pages can serve the folder later if wanted (10-line workflow).

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

does not modify any publishable blocks or libraries, or modifications do not need publishing
- (docs/ is outside the npm files whitelist; the only code-adjacent changes are markdown cross-links)

📜 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
- (this PR is documentation — internal engineering docs; the end-user guide is untouched)

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

The changes in this PR:

do not affect the execution graph

⚠️ Known issues

The HTML pages are hand-maintained: they can drift from the code like any prose documentation. Each page links the source files it describes to keep verification cheap.

🐾 Next steps

Optionally serve docs/architecture/ via GitHub Pages.
Extend with an actual-mode/recording page if that subsystem grows.

🛡 What tests cover this?

None (documentation). All pages were parse-checked with jsdom, internal links verified to resolve, and rendered via Playwright screenshots during authoring.

❓ How to test this?

Checkout the branch.
open libs/@hashintel/petrinaut-core/docs/architecture/index.html
Navigate the pill nav across the five pages; check the memory-map diagram on the Engine page and the sequence diagram on the Worker page against the code they link.
Confirm the core pages describe consumers host-agnostically, and the React specifics live in libs/@hashintel/petrinaut/ARCHITECTURE.md.

📹 Demo

Open index.html — the pages are the demo.

Self-contained HTML pages (no build step) under petrinaut-core/docs/architecture/: overview (execution paths, memory map, protocols), engine (EngineFrame v2 binary format with byte-exact memory-map diagram), authoring (user-code compilation), worker (protocol sequence diagram, backpressure, lifecycle), and monte-carlo (run model, double-buffer memory, metric pipeline). The core pages are React-free — consumers are described as "the host application" via the public API. The React integration (providers, playback ack policy, experiments UI) is documented in a separate ARCHITECTURE.md in @hashintel/petrinaut, outside docs/ which is the end-user guide. Existing simulation READMEs cross-link the HTML set. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

vercel · 2026-07-03T13:56:28Z

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 6, 2026 6:36pm
petrinaut	Ready	Preview, Comment	Jul 6, 2026 6:36pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 6, 2026 6:36pm

cursor · 2026-07-03T13:56:29Z

PR Summary

Low Risk
Documentation-only changes (HTML, CSS, markdown); no simulation runtime, auth, or publishable library behavior is modified.

Overview
Introduces internal engineering architecture docs for Petrinaut’s headless simulation stack, aimed at answering where memory lives, what crosses thread boundaries, and how quick sim vs Monte Carlo differ.

A new petrinaut-core/docs/architecture/ set includes shared architecture.css and five browser-openable HTML pages: overview (two execution paths, memory table, invariants, refactoring seams), engine (EngineFrame v2 with byte-map SVG), authoring (compilation pipeline and sandboxing), worker (protocol tables, sequence diagram, ack/backpressure, lifecycle), and monte-carlo (double-buffer runs, in-worker metrics, experiment protocol). Core pages stay host-agnostic; React-specific wiring is split out.

libs/@hashintel/petrinaut/ARCHITECTURE.md is new and documents providers, playback ack modes, experiment metric rendering, and dev tooling—kept outside end-user docs/ so the in-app assistant guide is untouched.

src/simulation/ARCHITECTURE.md and src/simulation/README.md now link to the HTML overview; the HTML pages link back to source files (e.g. internal-frame.ts).

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

Copilot

Pull request overview

Adds internal engineering architecture documentation for the Petrinaut simulation subsystem, centered on a set of self-contained HTML pages in @hashintel/petrinaut-core (plus a separate React-integration boundary doc in @hashintel/petrinaut) so contributors can reason about frame formats, worker protocols, lifecycle, and Monte Carlo execution without a docs build pipeline.

Changes:

Introduces five standalone HTML architecture pages + shared CSS under libs/@hashintel/petrinaut-core/docs/architecture/ (overview, engine, compilation, worker/protocol, Monte Carlo).
Adds a new libs/@hashintel/petrinaut/ARCHITECTURE.md documenting how the React layer consumes the headless core.
Cross-links the new HTML docs from existing petrinaut-core/src/simulation/* markdown entrypoints.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
libs/@hashintel/petrinaut/ARCHITECTURE.md	New internal doc describing React integration points and responsibilities (providers, playback/ack policy, experiments rendering).
libs/@hashintel/petrinaut-core/src/simulation/README.md	Adds a prominent link to the new illustrated HTML architecture docs.
libs/@hashintel/petrinaut-core/src/simulation/ARCHITECTURE.md	Adds a prominent link to the new illustrated HTML architecture docs.
libs/@hashintel/petrinaut-core/docs/architecture/index.html	New overview page: execution paths, memory ownership map, protocol summary, and module map.
libs/@hashintel/petrinaut-core/docs/architecture/engine.html	New engine page: stepping lifecycle and `EngineFrame` v2 binary format overview with diagrams.
libs/@hashintel/petrinaut-core/docs/architecture/authoring.html	New compilation/authoring page: user-code compilation pipeline, surfaces, execution locations, sandboxing notes.
libs/@hashintel/petrinaut-core/docs/architecture/worker.html	New worker/protocol page: message tables, sequence diagram, backpressure/ack contract, lifecycle diagram.
libs/@hashintel/petrinaut-core/docs/architecture/monte-carlo.html	New Monte Carlo page: run model, bounded buffering strategy, metrics pipeline, protocol summary.
libs/@hashintel/petrinaut-core/docs/architecture/architecture.css	Shared styling for the HTML architecture docs and their diagram primitives.

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

…ture-docs

Copilot

Pull request overview

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

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

…ture-docs

Module-map link labels referenced stale architecture-*.html filenames; code-context snippets used Unicode −/≥ that break copy/paste; the initialMarking description said name-keyed where it is keyed by place ID; and the transfer-list refactoring note ignored that computeNextFrame() re-reads the latest frame, so a naive transfer would detach the stepping buffer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ture-docs

getPlaceTokens takes only a place since the layout became SDCPN-derived; getPlayModeBackpressure covers compute modes only (viewOnly is enforced by the playback provider pausing and never acking, not by a core profile); the initialMarking type reads `TokenRecord[] | number` to match InitialPlaceMarking. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

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

…ture-docs

The init table now shows maxTime as number | null, and the sequence diagram uses the actual protocol field name initialMarking. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

oxfmt 0.50 checks HTML, and the hand-written pages failed CI's repo-wide lint:format on this and every stacked PR above. Indentation only — pre blocks are byte-identical. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

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

…ture-docs

There is one format; the header's version word (2) stays documented as the wire constant readers assert, but section titles and asides no longer read as if a v1 coexists. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ture-docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

+      <dt>Inputs</dt>
+      <dd>
+        SDCPN snapshot, <code>InitialMarking</code>, parameter values, seed, dt,
+        maxTime, extensions
+      </dd>


+        <strong>1 · maxTime?</strong>
+        <small
+          >If <code>currentTime >= maxTime</code>, return
+          <code>"maxTime"</code> without computing.</small
+        >


+          <small
+            >owns <code>InitialMarking</code>, parameter values,
+            seed/dt/maxTime; calls <code>createSimulation()</code></small
+          >


+  element name), parameter values, seed, `dt`,
+  `maxTime`. When a scenario is compiled, its marking and parameter overrides


Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings July 3, 2026 13:56

graphite-app Bot assigned kube Jul 3, 2026

github-actions Bot added area/infra Relates to version control, CI, CD or IaC (area) area/libs Relates to first-party libraries/crates/packages (area) type/eng > frontend Owned by the @frontend team labels Jul 3, 2026

Copilot started reviewing on behalf of kube July 3, 2026 13:56 View session

Copilot AI reviewed Jul 3, 2026

View reviewed changes

vercel Bot deployed to Preview – petrinaut July 3, 2026 13:59 View deployment

vercel Bot deployed to Preview – hash July 3, 2026 14:05 View deployment

Copilot AI review requested due to automatic review settings July 3, 2026 14:19

kube force-pushed the cf/fe-1139-simulation-architecture-docs branch from 48deb41 to 087cef8 Compare July 3, 2026 14:19

Copilot started reviewing on behalf of kube July 3, 2026 14:19 View session

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

e858cee

…ture-docs

Copilot AI reviewed Jul 3, 2026

View reviewed changes

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/index.html Outdated

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/worker.html Outdated

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/worker.html Outdated

Copilot AI review requested due to automatic review settings July 3, 2026 14:22

Copilot started reviewing on behalf of kube July 3, 2026 14:23 View session

vercel Bot deployed to Preview – petrinaut July 3, 2026 14:24 View deployment

Copilot AI reviewed Jul 3, 2026

View reviewed changes

vercel Bot deployed to Preview – hash July 3, 2026 14:27 View deployment

This was referenced Jul 3, 2026

FE-1121: Add UUID token dimension type #8953

Open

FE-769: Add String token dimension type (string interning) #8956

Open

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

feb36c1

…ture-docs

vercel Bot deployed to Preview – petrinaut July 6, 2026 13:31 View deployment

vercel Bot deployed to Preview – hash July 6, 2026 13:35 View deployment

kube mentioned this pull request Jul 6, 2026

FE-1153: Collapse per-type switches into a type-policy registry #8964

Open

4 tasks

kube and others added 2 commits July 6, 2026 16:37

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

b58c962

…ture-docs

kube and others added 2 commits July 6, 2026 17:01

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

d5b45f7

…ture-docs

Copilot AI review requested due to automatic review settings July 6, 2026 15:02

Copilot started reviewing on behalf of kube July 6, 2026 15:03 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/worker.html Outdated

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/worker.html Outdated

vercel Bot deployed to Preview – petrinaut July 6, 2026 15:06 View deployment

kube and others added 2 commits July 6, 2026 17:09

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

4171a73

…ture-docs

FE-1139: Docs review fixes round 3 — protocol field accuracy

25eb787

The init table now shows maxTime as number | null, and the sequence diagram uses the actual protocol field name initialMarking. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

vercel Bot deployed to Preview – petrinaut July 6, 2026 15:14 View deployment

vercel Bot deployed to Preview – hash July 6, 2026 15:18 View deployment

FE-1139: Format architecture HTML with oxfmt

0bea516

oxfmt 0.50 checks HTML, and the hand-written pages failed CI's repo-wide lint:format on this and every stacked PR above. Indentation only — pre blocks are byte-identical. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings July 6, 2026 17:15

Copilot started reviewing on behalf of kube July 6, 2026 17:15 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread libs/@hashintel/petrinaut-core/docs/architecture/engine.html

vercel Bot deployed to Preview – petrinaut July 6, 2026 17:19 View deployment

kube and others added 2 commits July 6, 2026 19:19

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

6706412

…ture-docs

vercel Bot deployed to Preview – petrinaut July 6, 2026 17:24 View deployment

vercel Bot deployed to Preview – hash July 6, 2026 17:27 View deployment

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

c8125b8

…ture-docs

Copilot AI review requested due to automatic review settings July 6, 2026 18:25

Copilot started reviewing on behalf of kube July 6, 2026 18:25 View session

kube and others added 2 commits July 6, 2026 20:28

Merge branch 'cf/token-format-v2' into cf/fe-1139-simulation-architec…

9668ccc

…ture-docs

FE-1139: Offsets in the header diagram are token-region-relative

81e85ae

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 6, 2026 18:29

Copilot started reviewing on behalf of kube July 6, 2026 18:29 View session

vercel Bot deployed to Preview – petrinaut July 6, 2026 18:32 View deployment

Copilot AI reviewed Jul 6, 2026

View reviewed changes

vercel Bot deployed to Preview – hash July 6, 2026 18:36 View deployment

		element name), parameter values, seed, `dt`,
		`maxTime`. When a scenario is compiled, its marking and parameter overrides

Uh oh!

Conversation

kube commented Jul 3, 2026

🌟 What is the purpose of this PR?

🔗 Related links

🚫 Blocked by

🔍 What does this change?

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

📜 Does this require a change to the docs?

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

⚠️ Known issues

🐾 Next steps

🛡 What tests cover this?

❓ How to test this?

📹 Demo

Uh oh!

vercel Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Jul 3, 2026 •

edited

Loading

cursor Bot commented Jul 3, 2026 •

edited

Loading