FE-1139: Simulation architecture documentation

[kube]

🌟 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?

1. Checkout the branch.
2. open libs/@hashintel/petrinaut-core/docs/architecture/index.html
3. 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.
4. 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.

[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 10:43am
petrinaut	Ready	Preview, Comment	Jul 7, 2026 10:43am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 7, 2026 10:43am

[cursor]

PR Summary

Low Risk
Documentation-only changes with markdown cross-links; no publishable library behavior or simulation logic is modified.

Overview
Adds internal engineering architecture docs for the Petrinaut simulation stack—no runtime or API changes.

A new petrinaut-core/docs/architecture/ set (shared architecture.css plus five browser-open HTML pages) documents the headless core: overview (Quick Sim vs Experiments, memory ownership, protocols), engine (EngineFrame v2 with byte-exact memory-map SVG), authoring (compilation pipeline and threading), worker (message tables, sequence diagram, ack/backpressure, lifecycle), and Monte Carlo (double-buffer runs, in-worker metrics). Pages link to source files (e.g. internal-frame.ts) and call out refactoring seams (triple frame retention, transfer-list opportunities).

src/simulation/ARCHITECTURE.md and README.md now point at index.html. React-specific integration (providers, playback ack modes, experiment UI) is split into a new libs/@hashintel/petrinaut/ARCHITECTURE.md, kept outside end-user docs/ for the in-app assistant.

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

[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.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[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
• FE-1139: Simulation architecture documentation #8951 👈 (View in Graphite)
• 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 9 out of 9 changed files in this pull request and generated no new comments.