@woosh/meep-engine 3.20.0 → 3.21.0

package/src/shade/device/timing/GPU_PROFILER_PROPOSAL_2026_08_28.md

@@ -1,894 +1,894 @@
-# A graphical GPU profiler for Shade — recorder, format, inspector
-
-Proposal, 2026-08-28. Decisions folded in 2026-08-29. Alex Goldring / Company Named Limited.
-
-> **Partly superseded, 2026-08-31**, by
-> [PASS_ENCODER_PROPOSAL_2026_08_31.md](../PASS_ENCODER_PROPOSAL_2026_08_31.md). The recording
-> proxy of §6.2 hook 3 and M4 is now a pair of decorator classes; `enable_debug_timers`,
-> `Renderer.add_debug_frame` and `Renderer.onFrameDebug` — which §6.1 kept — are gone, leaving the
-> profiler as the only path. §§1–5 remain a record of the state this design was written against.
-
-Scope: a **recording** side that ships with the engine, a **binary container** that carries a
-capture, and an **inspector** web application under `packages/gpu-inspector-tool/` that reads the
-container and nothing else.
-
-> The request spelled the directory `gpu-inespector-tool`. Reading that as a typo and using
-> `packages/gpu-inspector-tool/` throughout. Say the word if the misspelling was deliberate.
-
-**Four decisions are settled and written into the design below** — npm workspaces with the existing
-tree moved to conform (§4.2), a user-instantiated recorder passed in rather than a renderer-owned one
-(§6.1), the minimal `FrameGraph` bracket via `Signal` (§1.4), and an open-ended uncapped stream of
-self-contained frame records rather than a ring buffer (§5.8). §11 records them and what each costs.
-
----
-
-## 0. Verdict
-
-**Worth building, and the engine is further along than it looks — but not in the place you would
-expect.**
-
-The timing half is the *small* half. `GPUTimerArray` already lands begin/end timestamps per GPU
-pass, and `SoftwareGPUDevice` already emulates timestamp queries well enough to test the recorder in
-node without a GPU. What is genuinely missing is **attribution**: the timestamps are keyed by
-`GPUComputePassDescriptor.label`, the dependency structure lives in `FrameGraph`, and *nothing
-connects the two*. One frame-graph pass can open several GPU passes with unrelated labels
-(`graph_build_hzb` → `hzb.build()` → its own `constructComputePass` labels), so a label is not a key.
-Closing that gap is the central piece of engineering in this proposal, and it is about thirty lines
-in `FrameGraph.execute` plus a field on the command context.
-
-The dependency half is nearly free. `FrameGraph.exportToJson()`
-([FrameGraph.js:644](src/engine/graphics/render/frame_graph/FrameGraph.js:644)) already emits passes,
-resource nodes, versions, readers, writers, producers and cull state, keyed consistently. Resource
-*sizes* fall out of the descriptors that graph already holds. Nesting for a flame-graph view falls
-out of `FrameGraphScope`.
-
-The work-size half needs a wrapper that does not exist: `beginComputePass` hands back the raw
-`GPUComputePassEncoder`, so `dispatchWorkgroups(x, y, z)` is invisible to us. A recording-only proxy
-around the pass encoder buys every dispatch and draw count for one class and no call-site churn.
-
-**The single biggest risk is not ours.** Chrome quantizes WebGPU timestamps to **100 µs** unless the
-user sets `chrome://flags/#enable-webgpu-developer-features`. Most Shade passes run well under that,
-so on a default browser almost every pass measures as exactly 0 or exactly 100 µs. A profiler that
-does not say this out loud, in the recording *and* in the inspector, is a profiler that lies. §2.1.
-
----
-
-## 1. What exists today
-
-### 1.1 The timing path, end to end
-
-| Piece | Where | What it does |
-|---|---|---|
-| `GPUTimerArray` | [GPUTimerArray.js](src/shade/device/timing/GPUTimerArray.js) | One `GPUQuerySet` of `size * 2` timestamps. `getComputeWrites(label)` / `getRenderWrites(label)` claim a slot from an `IdPool` and return the `timestampWrites` struct. Resolve + copy to a `MAP_READ` buffer, `download_results()` maps it, `results_to_console_table()` turns slots into `{label, type, duration_ms, start, end}`. |
-| `ShadeGPUCommandContext.enable_debug_timers(cb)` | [ShadeGPUCommandContext.js:89](src/shade/device/ShadeGPUCommandContext.js:89) | Constructs a `GPUTimerArray` for this context. `beginComputePass` / `beginRenderPass` then inject `timestampWrites` into every descriptor. |
-| `finish()` | [ShadeGPUCommandContext.js:699](src/shade/device/ShadeGPUCommandContext.js:699) | Resolves the query set into the command buffer before `encoder.finish()`, then after submit downloads results and calls the callback, then destroys the timer array. |
-| `Renderer.add_debug_frame(count)` | [Renderer.js:626](src/shade/renderer/Renderer.js:626) | Arms N future frames. |
-| `Renderer.onFrameDebug` | [Renderer.js:408](src/shade/renderer/Renderer.js:408) | `send2(frame_index, table)`. **Currently has no subscribers anywhere in the tree.** |
-| `GPUTimerStats`, `format_nanosecond_time` | `src/shade/device/timing/` | Ring-buffer averaging and human formatting. Reusable in the inspector. |
-
-Degradation is already correct: with `timestamp-query` withheld, the query set is never created and
-`resolve` / `download_results` / `destroy` all no-op rather than throwing. Keep that property.
-
-### 1.2 Four defects the recorder must fix, not inherit
-
-1. **No slot bound check.** `GPUTimerArray.#bind_slot` takes an id from the `IdPool` and never
-   compares it to `#size`. Pass 1025 in a frame (default `size = 1024`) writes a query index past
-   `querySet.count` and takes a WebGPU validation error, at the `beginRenderPass` rather than at the
-   place that overflowed. A recording session runs *more* passes instrumented than a debug frame
-   does, so this is on the path. Clamp and count drops; report the drop count in the recording.
-2. **Per-context GPU allocation.** `enable_debug_timers` builds a query set and two buffers per
-   context and destroys them after the download. Fine for one frame; recording 600 frames means 600
-   query-set create/destroy pairs and 600 `mapAsync` round trips. Wants a small pool of timer arrays
-   cycled N-deep against frames in flight.
-3. **Descriptor mutation.** `beginComputePass` does `let _descriptor = descriptor;` and then writes
-   `_descriptor.timestampWrites`, mutating the caller's object. Several call sites reuse descriptor
-   objects. Copy, or document the mutation.
-4. **`beginComputePass()` with no descriptor throws** once timers are on, at
-   `timers.getComputeWrites(descriptor.label)`. Currently latent because every call site passes one.
-
-### 1.3 The structure half
-
-`FrameGraph.exportToJson()` is most of the dependency model already:
-
-```js
-{
-  passes:    [{ id, name, culled, reads: [node_id], writes: [node_id] }],
-  resources: [{ id, name, transient, version?, description?, createdBy?, readers?, writers? }]
-}
-```
-
-Keyed by **resource node** (per version), not by registry entry — deliberately, so
-`passes[].reads/writes` stay resolvable across versions. The recording format must preserve that
-choice; a registry-keyed export dangles every reference past version 0.
-
-What it does *not* carry, and we want:
-
-- `FrameGraphNode.scope` — the `FrameGraphScope` chain, which is the hierarchy a flame graph needs.
-- `ref_count` and `has_side_effects` — why a pass survived culling.
-- Typed descriptors. `description` is `resource_descriptor.toString()`, a human string
-  (`"Buffer{ size = 1,048,576, usage = STORAGE | COPY_DST }"`). We want the fields.
-
-### 1.4 The gap: labels are not keys
-
-```js
-// graph_build_hzb.js
-const builder = graph.add("hzb/ build", data, (data, resources, context) => {
-    hzb.build(context.encoder, source, viewport);   // opens N compute passes, its own labels
-});
-```
-
-`GPUTimerArray` records the labels `hzb.build` chose. `FrameGraph` records `"hzb/ build"`. Nothing
-relates them, and the relation is not derivable after the fact — labels are not unique, not stable,
-and one graph pass legitimately produces many GPU passes.
-
-**Fix:** bracket `node.execute(...)` inside `FrameGraph.execute`
-([FrameGraph.js:604](src/engine/graphics/render/frame_graph/FrameGraph.js:604)) so the context knows
-which graph pass is open. Every GPU pass begun while that bracket is open is attributed to it. The
-same bracket should emit `pushDebugGroup(node.name)` / `popDebugGroup()`, which costs nothing and
-immediately improves what RenderDoc, PIX and webgpu-inspector show — worth doing on its own merits.
-
-### 1.5 Work sizes are not observable today
-
-`beginComputePass` / `constructComputePass` return the **raw** `GPUComputePassEncoder`. All 11
-production `dispatchWorkgroups` call sites talk to it directly, as does every draw call across the
-31 render-pass construction sites. Editing every one of them to report its own counts is the wrong
-trade. A proxy encoder, installed only while recording, is one class.
-
-`SoftwareGPUComputePassEncoder` already models exactly this: it records
-`{pipeline, bind_groups, dynamic_offsets, group_counts}` per dispatch. The recording proxy is the
-same shape with a real encoder behind it.
-
----
-
-## 2. What the platform will give us
-
-### 2.1 Timestamp quantization — the headline constraint
-
-Chrome quantizes `timestamp-query` results to **100 µs** as a timing-attack mitigation. It is
-disabled by `chrome://flags/#enable-webgpu-developer-features`; that flag does not itself enable the
-feature, which additionally needs the device to expose `timestamp-query`.
-
-100 µs is 0.1 ms. A Shade frame at 60 Hz has ~16.6 ms of budget spread over a couple of hundred
-passes. **The median pass is below the quantum.** Unmitigated, the tool reports a histogram of zeros
-with occasional 100 µs spikes, and every conclusion drawn from it is noise.
-
-**The decision is to leave it entirely alone.** Not measure it, not calibrate against it, not
-correct for it, not store a period in the container. Rejected 2026-08-29, and the reasoning is
-worth keeping because it is not obvious:
-
-- Recovering the quantum — GCD over observed timestamps, or any equivalent — **is the timing attack
-  the mitigation exists to prevent.** Doing it *well* means defeating a browser security control on
-  purpose, inside code we ship to other people.
-- Doing it *badly* is worse than not doing it. A period that is a multiple of the real one, or a
-  stale one from a browser update, becomes a correction applied to every number in the capture. A
-  profiler that silently skews its own data is worse than one that reports coarse data honestly.
-- Either way it is standing complexity and a source of fragility, bought for something the reader
-  can be told in one sentence.
-
-So: **note it, document it, do not treat it.** The capture records what the device reported —
-zeros included. `GPUProfileMeta` documents that browsers quantize and names the flag. The inspector
-says so where a reader will see it. What to make of a coarse capture is the reader's judgement, and
-the honest advice is the same either way: **aggregate across frames rather than trusting any single
-one.** That shapes the format in exactly one way, which it already did — keep every frame's raw
-values and never pre-aggregate on the recorder side.
-
-### 2.2 Pass granularity is the floor
-
-WebGPU writes timestamps at pass boundaries only. Per-draw timing needs
-`chromium-experimental-timestamp-query-inside-passes`, which is Chromium-only and experimental.
-
-**Design for pass granularity.** Treat inside-passes as an optional capability the recorder probes
-for and, if present, uses to add sub-pass markers — recorded as a distinct span kind so the format
-does not pretend the two are the same measurement.
-
-### 2.3 No CPU↔GPU clock sync
-
-WebGPU exposes no calibration between `performance.now()` and the GPU timestamp domain. Anything
-claiming to place CPU and GPU events on one axis is guessing.
-
-**Be honest in the format.** Record two clocks explicitly: a CPU track from `performance.now()`
-(encode time, submit time, callback time) and a GPU track from timestamps. The inspector shows two
-tracks anchored per frame at submit, and says the alignment is nominal. Perfetto solves this problem
-with explicit `ClockSnapshot` packets and a clock graph; we do not have the snapshots, so we do not
-get to claim the sync.
-
-### 2.4 Cross-query-set comparability
-
-Timestamps from two different `GPUQuerySet`s are not specified to share a domain. In Dawn they do in
-practice. Since each `ShadeGPUCommandContext` currently gets its own `GPUTimerArray`, and a frame has
-several contexts, **every frame already spans several query sets.**
-
-Record a `query_set_id` per span. Then the inspector can, if a capture ever looks wrong, colour
-spans by origin and let the reader see whether the anomaly follows a set boundary. Cheap; makes an
-otherwise unfalsifiable class of bug visible.
-
-### 2.5 Indirect work is unknowable at encode time
-
-`dispatchWorkgroupsIndirect` and `drawIndirect` take their counts from a GPU buffer. At encode time
-we know only *that* it was indirect. Two options, both worth having:
-
-- **v1:** record the indirect flag plus the source buffer's id and offset. The inspector shows
-  "indirect (unknown)" and links to the buffer.
-- **v2 (opt-in, costly):** the recorder copies indirect argument buffers into a readback staging
-  buffer at encode time and resolves the actual counts after submit. This is the only way to see the
-  real post-cull draw count, which for a GPU-driven renderer is one of the numbers most worth seeing.
-  It changes memory traffic, so it must be a flag, and the format must mark such counts as
-  *resolved* rather than *encoded* so nobody compares the two carelessly.
-
-### 2.6 Prior art
-
-| Tool | What to take | What to leave |
-|---|---|---|
-| [webgpu_inspector](https://github.com/brendan-duncan/webgpu_inspector) (Brendan Duncan) | The reference point for WebGPU frame capture in a browser. Object inspection with creation stacktraces; frame-time plotting; buffer content view. Its recorder emits a standalone replayable HTML file. | It is a *generic API* interceptor, extension-hosted. We want *engine-semantic* data — frame graph passes, resource lifetimes, cull decisions — which a generic interceptor cannot see. Complementary, not competing. |
-| [Perfetto](https://perfetto.dev/docs/getting-started/other-formats) | Track/slice model; nested slices; counter tracks; explicit clock domains. Its JSON importer is a free escape hatch — see §5.6. | The protobuf format and the full trace-processor stack are far more than we need, and its UI knows nothing about resource dependency. |
-| RenderDoc / PIX / Radeon GPU Profiler | The three-pane idiom: event list, timeline, per-event detail; a resource view keyed by lifetime; "why is this bound" attribution. | Native capture, replay, driver counters. Out of reach on WebGPU. |
-| Chrome Trace Event Format | Trivially writable, universally readable. | Text JSON at our event rates is 5–10× our binary size. Export target, not storage. |
-| [webgpufundamentals timing](https://webgpufundamentals.org/webgpu/lessons/webgpu-timing.html) | The canonical treatment of the query-set/resolve/map dance and its pitfalls. | — |
-
-The gap in that table is the whole reason to build this: **no existing tool knows what a Shade frame
-graph is.** Timings without the dependency structure tell you a pass is slow; timings *with* it tell
-you a pass is slow because it waits on a resource that a culled branch still produced.
-
----
-
-## 3. What a recording must contain
-
-Three axes were asked for. A fourth is needed to make the first three legible.
-
-### 3.1 Timings
-
-| Datum | Source | Cost |
-|---|---|---|
-| GPU pass begin/end, ns | `GPUTimerArray` | free, already there |
-| Which query set a span came from | recorder | 1 byte |
-| CPU encode time per graph pass | `performance.now()` around `node.execute` | ~2 × 200 calls/frame |
-| CPU submit timestamp | `ShadeGPUCommandContext.finish` | free |
-| Callback/readback latency | recorder | free |
-| Sub-pass markers | `chromium-experimental-timestamp-query-inside-passes` if present | optional |
-
-### 3.2 Dependencies
-
-Straight from `FrameGraph`, enriched:
-
-- Passes: id, name, scope chain, culled, `ref_count`, `has_side_effects`, reads/writes/creates.
-- Resource nodes: id, name, version, transient/imported, producer, readers, writers.
-- Per graph pass: the GPU passes it opened, in order — the join from §1.4.
-- Resource lifetime: first write → last read, derivable from `ResourceEntry.last`, which `compile()`
-  already computes.
-
-### 3.3 Data sizes
-
-Descriptors carry everything:
-
-| Resource | Fields | Footprint |
-|---|---|---|
-| Buffer | `size` bytes, `usage` bitmask, `ensure_cleared` range | `size` directly |
-| Texture | `resolution[3]`, `format`, `dimension`, `mipLevelCount`, `sampleCount`, `usage` | computed from `gpu_texture_format_info` — `bytes_per_block`, `block_width`, `block_height` — summed over the mip chain, × `sampleCount` |
-
-These are **declared** sizes, not allocated ones; a pooled allocator may serve a larger block.
-`GraphicsContext.gpu_memory_usage` gives the real total per frame — record it as a counter track and
-let the inspector show declared-vs-actual as the aliasing metric it is.
-
-### 3.4 Work sizes
-
-| Datum | Needs |
-|---|---|
-| `dispatchWorkgroups(x, y, z)` | proxy encoder |
-| Workgroup size from the shader (`@workgroup_size`) | pipeline descriptor, recorded once per pipeline |
-| Total invocations = groups × workgroup size | derived in the inspector |
-| `draw` / `drawIndexed` vertex, index, instance counts | proxy encoder |
-| Indirect flag + argument buffer id/offset | proxy encoder |
-| Resolved indirect counts | §2.5 v2, opt-in |
-| Bind group contents per dispatch | proxy encoder; **large** — gate behind a verbosity level |
-| Render pass attachment formats and load/store ops | pass descriptor |
-
-### 3.5 The fourth axis — context, so any of it means anything
-
-Without this a shared recording is unreadable:
-
-- Adapter info (`vendor`, `architecture`, `device`, `description`), features, the limits that matter.
-- Engine version, git revision, build flags, `ENV_PRODUCTION`.
-- Renderer settings: internal vs output resolution, upscaler, which features are on.
-- Nothing about timestamp quantization: see §2.1 for why that is a deliberate absence.
-- Wall-clock start, session id, user-supplied note.
-- Scene scale: mesh/instance/light counts, resident material and geometry bytes.
-
----
-
-## 4. Architecture
-
-```
-  ENGINE (ships)                      CONTAINER                 INSPECTOR (published separately)
-  ─────────────────────               ─────────                 ───────────────────────────────
-  GPUTimerArray ────┐
-  FrameGraph ───────┤                                            ┌── timeline / flame graph
-  proxy encoders ───┼──> GPUProfileSession ───> .sgpt ──drop──>  ├── dependency graph
-  GraphicsContext ──┘         │                  bytes           ├── resource table
-                              │                                  ├── pass detail
-                       sgpt_write_*                              └── frame comparison
-                              │                                          │
-                        BinaryBuffer  <───────────────────────────  sgpt_read_*
-```
-
-**Three rules that keep this from rotting.**
-
-1. **The container is the only interface.** The inspector imports the format readers and
-   `BinaryBuffer`. It never imports Shade, `FrameGraph`, or anything under `src/shade/renderer/`.
-   This is a licensing constraint as much as an architectural one — meep is proprietary and
-   source-available, and a separately published inspector must not carry renderer internals.
-2. **The recorder never blocks the frame.** Every buffer it touches is written at encode time or
-   read after submit. Serialization runs off the frame — accumulate into per-frame plain records,
-   encode to bytes when the session stops or when a chunk fills.
-3. **Reader and writer live together, in the engine tree.** Under
-   `src/shade/device/timing/profile/`, one file per concern, matching the `vgeo_*` convention. The
-   inspector package imports them by path. One definition of the format; no drift.
-
-### 4.1 Verbosity levels
-
-A capture is a trade between fidelity and cost. Four levels, recorded in the header:
-
-| Level | Adds | Bytes/frame, ~200 passes |
-|---|---|---|
-| 0 `TIMING` | GPU pass spans, frame boundaries | ~2 KB |
-| 1 `STRUCTURE` | + frame graph topology, resource descriptors, cull state | ~2 KB amortised (§5.4) |
-| 2 `WORKLOAD` | + dispatch/draw counts, pipeline identities, attachment state | ~6 KB |
-| 3 `VERBOSE` | + bind group contents, indirect readback, CPU per-pass timing | ~40 KB |
-
-Levels 0–2 are the product. Level 3 is for us, on a repro, and the inspector should say so when it
-opens one.
-
-Because a session is now **uncapped by default** (§5.8), those per-frame figures are also a rate.
-At 60 Hz:
-
-| Level | Per second | Per minute |
-|---|---|---|
-| 0 `TIMING` | ~120 KB | ~7 MB |
-| 1 `STRUCTURE` | ~120 KB | ~7 MB |
-| 2 `WORKLOAD` | ~360 KB | ~21 MB |
-| 3 `VERBOSE` | ~2.4 MB | ~144 MB |
-
-Levels 0–2 will run for many minutes without anyone noticing. **Level 3 will not**, and the session
-should say so — see the byte-budget warning in §5.8. This is the honest cost of "full and uncapped
-explicit history", and it is the right trade at levels 0–2.
-
-### 4.2 Repository layout
-
-The repo becomes an npm workspace root, and the engine moves down a level so the two packages are
-siblings rather than one being nested inside the other.
-
-```
-  meep/
-    package.json            workspace root: { "private": true, "workspaces": ["packages/*"] }
-    .gitlab-ci.yml
-    LICENSE, README.md, CONTRIBUTING.md, CHANGELOG.md, ...
-    packages/
-      meep-engine/          @woosh/meep-engine — everything that is published today
-        package.json        unchanged `exports`, `files`, version
-        src/  editor/  samples/  tools/
-        rollup.config.js  vite.config.mjs  vitest.config.mjs  tsconfig.types.json  babel.config.cjs
-      gpu-inspector-tool/   the inspector, published separately
-        package.json  index.html  src/  fixtures/
-```
-
-`@woosh/meep-engine`'s own `exports` map (`./src/*`, `./editor/*`) is relative to its own
-`package.json`, so **consumers installing from npm see no change at all**. The paths that move are
-in-repo and in anything vendoring this tree by path.
-
-**The cost is in `moh`, not here.** This tree is vendored into the game at
-`app/src/mir-engine/meep/`, and that is where the restructure is felt: every engine path becomes
-`app/src/mir-engine/meep/packages/meep-engine/src/...`. Two ways to absorb it, and this is the one
-call the restructure actually needs:
-
-- **Re-point the vendoring one level deeper** — mount `packages/meep-engine` as
-  `app/src/mir-engine/meep`. Every path in `moh` stays byte-identical, and the whole cost collapses
-  to one submodule/copy path. **This is the one to take** unless something in `moh` needs the
-  workspace root itself.
-- **Update paths in `moh`** — mechanical, wide, and it churns the ~20 design documents in this tree
-  that quote `app/src/mir-engine/meep/src/...` as a source root.
-
-In-repo edits either way: `vitest.config.mjs` `include`/`coverage.include` globs, `tsconfig.types.json`
-`include`/`rootDir`, `rollup.config.js` `input` paths, `.gitlab-ci.yml` script and artifact paths, and
-`vite.config.mjs`. All of them are prefix changes, and all of them get shorter, not longer, because
-they become relative to the package rather than the root.
-
-> Worth knowing before committing: npm lets a workspace root *also* be a package, so
-> `packages/gpu-inspector-tool` could have been added with the engine left exactly where it is and
-> zero paths touched. That option is on the table if the `moh` re-pointing turns out to be more
-> awkward than it looks. Proceeding with the move as decided — it is the cleaner end state and the
-> re-pointing above makes it cheap.
-
----
-
-## 5. The `.sgpt` container
-
-**S**hade **G**PU **P**rofile **T**race. Magic `0x54504753` — the ASCII bytes `S G P T` read as a
-little-endian u32 at offset 0, matching the `VGEO_MAGIC` convention in
-[VGEO_MAGIC.js](packages/meep-engine/src/shade/renderer/geometry/virtual/format/header/VGEO_MAGIC.js).
-`sgpt_fourcc.js` computes these and a spec asserts every literal against it, because hand-deriving
-a little-endian FourCC is exactly the kind of arithmetic that is wrong once and then forever.
-
-### 5.1 Why binary, concretely
-
-A 600-frame capture at level 2, ~200 passes/frame, in Chrome Trace Event JSON: each span is roughly
-`{"ph":"X","name":"...","cat":"gpu","ts":123456.7,"dur":234.5,"pid":1,"tid":3,"args":{...}}` — call
-it 140 bytes minified, times 120,000 spans, **~17 MB**, before pass arguments. The same content in
-the layout below is **~1.5 MB**, and gzip (already a dependency via `pako`, and available natively
-via `CompressionStream`) takes it under 400 KB. That is the difference between a capture you attach
-to a bug report and one you do not.
-
-### 5.2 Layout
-
-Chunked, directory at the tail — so a writer streams forward and only seeks back once, and a reader
-can pull the header and the frame index without reading the payload.
-
-```
-  offset  size   field
-  ──────────────────────────────────────────────────────────────────
-       0     4   magic                        u32   0x54504753
-       4     2   format_version               u16
-       6     2   min_reader_version           u16
-       8     4   flags                        u32   bit0 = CLOSED (writer reached stop)
-      12     4   header_checksum              u32   over bytes [0, 8) only — see below
-      16     8   directory_offset             u64   0 when the session never stopped
-      24     8   directory_byte_length        u64
-      32   ...   records, in write order
-     ...   ...   directory record
-```
-
-**The checksum stops at byte 8, short of `flags`.** Everything from `flags` onward is patched at
-stop — the CLOSED bit and the directory pointer — and a checksum covering them would have to be
-recomputed then. Fine for a capture that stops; exactly wrong for one that does not, which would
-carry a checksum over bytes never written and read as corrupt. What stays under it is what a reader
-must trust before it can do anything at all: is this an `.sgpt`, and can this build read it.
-
-### 5.3 Chunks
-
-| FourCC | Purpose | Cardinality |
-|---|---|---|
-| `META` | §3.5 context. Adapter, engine version, settings, verbosity level, session note. | 1 |
-| `SYMS` | Symbol block. Names, labels, formats, scope names — emitted **inside the record that first needs them** and referenced by u32 index thereafter, so a truncated capture still resolves every name it references (§5.8). | 0..n |
-| `PIPE` | Pipeline table: id, label, kind, shader module name, `@workgroup_size`, entry point, vertex layout digest. | 1 |
-| `TOPO` | Frame-graph **topologies**: pass list, resource node list, edges, scopes, descriptors. Content-hashed and deduplicated across frames (§5.4). | 0..n |
-| `FRAM` | One per frame: topology id, CPU timestamps, span array, dispatch/draw array, counters. | 0..n |
-| `CNTR` | Counter tracks sampled per frame: `gpu_memory_usage`, mesh/instance/light counts, resolution. | 0..1 |
-| `NOTE` | Free-form user annotations with a frame index — "this is where it hitches". | 0..n |
-| `DIRE` | Directory: `{chunk_type, offset, byte_length}` plus a frame index of `{frame_number, chunk_offset, gpu_duration_ns}` so the inspector can draw the frame-time strip before parsing anything else. | 1 |
-
-Unknown chunk types are skipped by length. That is what makes level-3 payloads addable without a
-version bump, and what lets an old inspector open a new capture and say honestly which parts it
-cannot show.
-
-### 5.4 The compression that matters: topology deduplication
-
-**A Shade frame graph is nearly identical frame to frame.** Same passes, same resources, same edges;
-what changes is the timings, the cull decisions, and the occasional resolution change. Recording the
-full topology 600 times is the difference between a 20 MB file and a 1.5 MB one.
-
-So: hash the recorded topology (pass names, edges, descriptors, scope chain). If the hash matches a
-`TOPO` already written, the frame stores only the topology id. Cull state and per-pass timings stay
-in `FRAM`, because they are exactly what varies.
-
-Expected behaviour on a real capture: a handful of distinct topologies over 600 frames — steady
-state, plus the shadow-refresh variants, plus resolution changes. §4.1's "~2 KB amortised" for level
-1 is that claim.
-
-This must be **measured, not assumed**. If topologies turn out to churn every frame, the design
-still works (it degrades to storing each), but the size estimates in §5.1 do not. First milestone
-work item, §8.
-
-### 5.5 Per-frame span encoding
-
-Per span, level 0:
-
-| Field | Type | Note |
-|---|---|---|
-| `pass_ref` | `uintVar` | index into the topology's GPU-pass list |
-| `t_begin` | `u32` | ns offset from the frame's `gpu_epoch_ns` |
-| `t_end_delta` | `uintVar` | ns from `t_begin` |
-| `query_set_id` | `u8` | §2.4 |
-
-`u32` for the frame-relative begin holds 4.29 s — three orders of magnitude of headroom over a
-frame, and it survives a stall without overflowing. `BinaryBuffer.writeUintVar` / `readUintVar`
-already exist and handle the two variable-length fields.
-
-That is ~10 bytes per span against 26 for a naive absolute-u64 encoding, and the frame's absolute
-epoch is stored once as a `u64`.
-
-### 5.6 Chrome Trace Event export
-
-The inspector exports the loaded capture as Chrome Trace Event JSON, for opening in
-[ui.perfetto.dev](https://perfetto.dev/docs/getting-started/other-formats). Costs an afternoon and
-buys: a second opinion when the inspector looks wrong, a viewer for anyone unwilling to run ours, and
-a sanity check on our own timeline maths. Passes become `X` slices on a GPU track, scopes become
-nesting, counters become `C` events. Lossy — the dependency graph has no representation there — which
-is precisely why it is an export and not the storage format.
-
-### 5.7 String encoding
-
-Symbols live in `SYMS` blocks with u32 indices, emitted inside the record that first needs them
-(§5.8). Not `EncodingBinaryBuffer`: it deduplicates by writing back-references to **absolute buffer
-positions** ([EncodingBinaryBuffer.js:21](src/core/binary/EncodingBinaryBuffer.js:21)), which is
-correct for a single flat buffer and wrong the moment records are skipped by a reader that does not
-understand them, resynchronised after corruption, or read from a truncated file — all three of which
-this format is explicitly built to survive. An index table costs one indirection and holds up under
-all of them.
-
-### 5.8 Streaming: self-contained frame records
-
-The session is an **open-ended forward stream with an explicit stop**. No ring, no cap: `frame_limit`
-defaults to `Infinity`, `stop()` ends it early, and everything recorded is kept.
-
-**A frame is written as one complete, self-describing record and pushed when it closes.** That is
-the organising decision, and three properties follow from it:
-
-- **It is resynchronisable.** Every record opens with a sync marker, its type, its payload length and
-  a checksum. A reader that lands on garbage scans forward for the next marker and carries on. A
-  capture cut off mid-session — tab killed, GPU reset, `device.lost` — stays readable up to the last
-  intact record, and those are exactly the captures worth having.
-- **Symbols travel with the record that introduces them.** A record carrying a new topology carries
-  the names that topology needs; a frame record reusing a known topology carries none. There is no
-  global string table to finalise, which is what would otherwise force a tail chunk and make a
-  truncated file unreadable — the failure mode where the one capture of the crash resolves no names.
-- **Nothing is back-patched except the header's directory pointer**, and even that is optional: a
-  reader can recover the whole stream by scanning records when the directory is missing or the file
-  was truncated before `stop()` ran.
-
-Order on the wire:
-
-```
-  header                 magic, versions, flags; directory_offset patched at stop, 0 if never stopped
-  META                   at start — adapter, engine version, renderer settings, level
-  TOPO #0 + its symbols  first frame's topology
-  FRAM #0                topology id + spans + counts
-  FRAM #1                same topology → id only
-  ...
-  TOPO #1 + its symbols  shadow refresh changed the graph
-  FRAM #57
-  ...
-  CNTR, DIRE             at stop — the directory is an index, not a dependency
-```
-
-Record framing, every record identical:
-
-```
-       0     4   sync                         u32   0x43455253  ('SREC')
-       4     4   record_type                  u32   FourCC
-       8     4   payload_byte_length          u32
-      12     4   payload_checksum             u32   crc32 over the payload
-      16   ...   payload
-```
-
-u32 for the length rather than u64: a record describes one frame's control flow, and resource
-*contents* are a non-goal, so nothing in one scales with the size of what it describes. Four
-gigabytes is not a ceiling anything can approach.
-
-**The sync marker alone is not enough to resynchronise on**, and the reader does not treat it as
-though it were. Four bytes of payload can spell `SREC` — a pass label could — so a candidate counts
-only when its length also fits and its payload also checksums. There is a spec for exactly that
-case.
-
-**Reallocation is a non-issue, and the slack reservation settles what is left of it.** We are
-measuring GPU time, not CPU time; a `setCapacity` copy is a heap allocation and a memcpy that may
-evict some cache, which at worst makes the next GPU upload marginally slower. That is a rounding
-error against what is being measured. To keep even that out of the frame interior, the writer
-reserves at the frame boundary:
-
-```js
-buffer.ensureCapacity(buffer.position + FRAME_SLACK);   // FRAME_SLACK = 1 MiB
-```
-
-Any growth then happens between frames, never inside a record. 1 MiB against level 2's ~6 KB per
-frame is three orders of magnitude of headroom, so the reservation only actually forces a grow once
-every ~170 frames. One `BinaryBuffer`, no segmentation, no assembly pass.
-
-**Scope note, and it is what makes the above generous rather than marginal: GPU buffer and texture
-contents are a non-goal.** The stream carries control flow and dataflow metadata — passes, edges,
-descriptors, counts, timings. Nothing in it scales with the size of the resources it describes. That
-is why a frame record is kilobytes and why 1 MiB of slack is never the binding constraint.
-
-**Uncapped still means uncapped, so the session stays legible about it.** `bytes_written` is readable
-at any time and `onBytesWritten` fires per frame, so an application can show a counter. A configurable
-`byte_budget` — default 512 MB — does not stop the recording; it warns once, naming the level and the
-observed rate. Silent unbounded growth in a debug tool is how you lose a browser tab and the capture
-with it.
-
----
-
-## 6. The recorder
-
-### 6.1 Surface — the caller owns the session
-
-**The engine never constructs a profile session.** The caller builds one and hands it in; the
-renderer holds a nullable reference and nothing more. Nothing in `Renderer` imports the profiler.
-
-```js
-import { GPUProfileSession } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileSession.js";
-import { GPUProfileLevel } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileLevel.js";
-
-const session = new GPUProfileSession({
-    level: GPUProfileLevel.WORKLOAD,
-    frame_limit: Infinity,                       // default; a number caps it
-    note: "hitch on shadow refresh, RTX 3070"
-});
-
-renderer.profile_session = session;              // nullable field, that is the whole API
-
-session.start();                                 // META is written here; populate meta first
-// ... frames run, for as long as you like ...
-const bytes = await session.stop();              // ArrayBuffer, ready to save
-
-renderer.profile_session = null;
-```
-
-Three things fall out of the caller owning it, and all three are why this is the right shape:
-
-- **It is genuinely optional.** The profiler is a leaf module nothing in the engine imports. An
-  application that never imports `GPUProfileSession` does not have it in its bundle — the answer to
-  "does this ship in production builds" is *it ships, and it costs nothing to anyone who does not ask
-  for it*. No build flag, no strip-plugin interaction, no dead-code branch to keep honest.
-- **Lifetime is explicit.** A session that outlives a device, or two sessions at once, are the
-  caller's problem to not create, and `start()` asserts against both rather than papering over them.
-- **The engine surface is one nullable field.** `Renderer.profile_session`, forwarded to the
-  `GraphicsContext` so command contexts can find it. That is the entire integration.
-
-`frame_limit` reaching zero stops the session exactly as `stop()` does. Both resolve the same
-promise, so a caller that wants "500 frames or until I say" writes one `await`.
-
-~~`add_debug_frame` and `onFrameDebug` stay exactly as they are — cheap, synchronous, console-shaped,
-and a different tool for a different question.~~
-
-> **Reversed 2026-08-31.** They were not a different tool, they were a worse view of the same one
-> reached through a second API — no graph-pass attribution, no workload, no pipeline identity — and
-> `onFrameDebug` never acquired a subscriber. Removed; the profiler is the only path. "Profile the
-> next N frames" is `new GPUProfileSession({ frame_limit: N })`.
-
-### 6.2 The five hooks
-
-1. **`FrameGraph.execute`** — bracket `node.execute(...)`. Notify listeners which graph pass is open;
-   take CPU timestamps either side; push/pop a debug group. The only edit outside `src/shade/`.
-
-   Two `Signal`s on `FrameGraph`, `onPassBegin` / `onPassEnd`, alongside the `onExecuted` that is
-   already there. **Signal, not a nullable callback field** — it is the project's standardised
-   observer interface, it supports more than one listener, and `remove` is symmetric with `add`.
-   A bare nullable callback lets the second consumer silently clobber the first, which is exactly
-   the bug that does not announce itself.
-
-   Guard the dispatch with `hasHandlers()`: `send1` on an empty signal still bumps `generation` and
-   walks a Map iterator, and this fires twice per pass — a couple of hundred passes a frame. One
-   `Map.size` comparison ahead of it keeps the disabled path honest.
-
-   `FrameGraph` still learns nothing about what a profiler is; it announces its own pass boundaries
-   and the profiler is one possible listener.
-2. **`ShadeGPUCommandContext`** — a `#profile_sink` field. When set, `beginComputePass` /
-   `beginRenderPass` report `{label, kind, graph_pass_id, query_slot, query_set_id}` and wrap the
-   returned encoder in the recording proxy.
-3. **The proxy encoders** — `ProfilingComputePassEncoder`, `ProfilingRenderPassEncoder`. Forward
-   everything; record `dispatchWorkgroups*`, `draw*`, `setPipeline`, `setBindGroup`. Modelled on
-   `SoftwareGPUComputePassEncoder`, which already records exactly this shape.
-4. **`GPUTimerArray`** — pooling (§1.2.2), bound checking (§1.2.1), and expose raw slot data rather
-   than only the console table.
-5. **`GraphicsContext`** — sample `gpu_memory_usage` and the collection counters once per frame into
-   the counter track.
-
-### 6.3 Cost when off
-
-Every hook is a null check against a field that is `null` in normal operation. No allocation and no
-proxy construction; the frame-graph bracket is two comparisons per pass. This must stay true — a
-profiler that costs something when disabled will be disabled at the build level and then rot.
-
-Because the session is caller-constructed (§6.1), an application that never imports it pays not even
-that: the profiler modules are unreachable from any engine entry point and drop out of the bundle
-entirely. The null checks are the only residue, and they are the price of the feature existing.
-
-### 6.4 Cost when on
-
-Level 0–2 add: one `performance.now()` pair per graph pass, one small record per GPU pass, one per
-dispatch/draw, and a `push`/`popDebugGroup` pair per graph pass. The existing per-context query set
-churn (§1.2.2) is the largest cost and the pool removes it. Expect single-digit percent frame-time
-overhead at level 2; measure it and record the measurement in `META`, so a reader can see how much of
-what they are looking at is the observer.
-
----
-
-## 7. The inspector
-
-`packages/gpu-inspector-tool/`. A static site: drop a `.sgpt` on it, or pass `?file=` for a
-bookmarkable view — the affordance `prototypeVGEOFormatViewer` already established in this codebase.
-
-### 7.1 Technology
-
-**Plain ES modules, Canvas 2D for the timeline, DOM for panels, no runtime dependencies, built with
-Vite.** Reasons: the repo has no UI framework and adding one for this is unjustified; the timeline is
-a custom-drawn virtualised widget that a framework would only get in the way of; zero dependencies
-keeps a separately published proprietary artifact simple to reason about; and Vite is already the dev
-server here.
-
-The only imports from the engine tree are `src/core/binary/BinaryBuffer.js` and the `sgpt_*` readers.
-That boundary is a build-time assertion, not a convention — a lint rule that fails the build on any
-other engine import.
-
-### 7.2 Views
-
-| View | Answers |
-|---|---|
-| **Frame strip** | Which frame is interesting. Frame time over the session, GPU and CPU overlaid, hitches marked, brush to select a range. Drawn from the directory index alone, so it appears before the payload finishes parsing. |
-| **Timeline / flame graph** | Where the time went in *this* frame. Spans on a GPU track, nested by `FrameGraphScope`; a CPU track above with encode time; hover for exact ns; click to select. |
-| **Statistics** | Where the time goes *in general*. Per-pass min/median/p95/max/total across the selected frame range, sorted by total contribution. **On a quantized capture this is the only honest view** — and since the tool does not measure quantization (§2.1), it cannot detect that case and switch by itself. It says so plainly instead, always. |
-| **Dependency graph** | Why this pass runs, and what it waits on. Passes and resource nodes, culled ones greyed, edges directed. Select a pass → highlight its transitive inputs. Select a resource → its version chain and every reader. |
-| **Resource table** | What memory costs. Every resource node with declared bytes, format, usage, transient/imported, lifetime span, peak concurrent footprint. Sorted by size. Declared total vs `gpu_memory_usage` side by side. |
-| **Pass detail** | Everything about one pass. Timings across frames as a sparkline, dispatch/draw counts, derived total invocations, pipeline and workgroup size, attachments, bindings at level 3. |
-| **Frame comparison** | What changed. Two frames or two ranges side by side, per-pass deltas sorted by regression. This is the view that makes the tool useful for optimisation work rather than only for diagnosis. |
-
-### 7.3 What it must refuse to do
-
-- **Never invent precision the data does not have.** Durations are drawn as reported. Where many
-  spans read as exactly zero, that is shown as what it is — a quantized capture — with a note
-  naming the browser flag, not smoothed into plausible-looking small numbers.
-- **Never present the CPU and GPU tracks as one clock** (§2.3). Two tracks, anchored per frame,
-  labelled as nominal.
-- **Never hide dropped spans.** If the recorder dropped passes on slot exhaustion (§1.2.1), say how
-  many, on the frame that dropped them.
-
----
-
-## 8. Phasing
-
-Each milestone is independently useful and independently shippable.
-
-### M0 — Measure the assumptions (½ day)
-
-Before any of the below. Instrument one Sponza capture and answer three questions, because three
-size estimates and one whole design decision rest on them:
-
-1. How many distinct frame-graph topologies over 600 frames? (§5.4)
-2. ~~What is the observed timestamp period~~ — dropped; the tool does not measure this (§2.1).
-3. How many GPU passes per frame, actually? (`GPUTimerArray` default is 1024 slots; §1.2.1)
-
-Write the answers into this document.
-
-### M0.5 — Workspace restructure — **DONE**
-
-Landed 2026-08-29. `packages/meep-engine/` holds the engine, the workspace root holds the two
-`.gitignore` halves, the CI paths and a README. Suite green at 2156 files / 14580 tests. One spec
-had to move with it: `meep_three_free.spec.js` asserts the `*.d.ts` ignore rule at the engine root,
-so that rule lives in the package's `.gitignore` rather than the workspace's.
-
-**`moh` still needs its vendoring re-pointed one level deeper** — mount `packages/meep-engine` where
-it currently mounts the repository root, and every path inside it stays byte-identical.
-
-<details><summary>Original plan</summary>
-
-§4.2. Independent of everything else and worth landing first so no profiler work has to be moved
-afterwards. Order: create `packages/meep-engine/`, `git mv` the tree, fix the five config files,
-green the suite, re-point `moh`'s vendoring one level deeper, green `moh`. Land as its own commit —
-a pure move with no content changes, so the diff stays reviewable and a bisect through it is honest.
-
-</details>
-
-### M1 — Timing spine — **DONE**
-
-Landed:
-
-- `FrameGraph.onPassBegin` / `onPassEnd`, guarded by `hasHandlers()`, closed in a `finally` so a
-  throwing pass still ends its bracket. Five specs including the exception path.
-- `GPUTimerArray`: bound check (a full array now refuses a slot instead of addressing past its query
-  set), `dropped_count`, `traverse_results` for raw `BigInt` timestamps. Seven specs.
-- `ShadeGPUCommandContext`: `#with_timestamp_writes` — copies the descriptor instead of stamping the
-  caller's, tolerates a missing descriptor, and leaves `timestampWrites` off when no slot is free.
-- The whole `.sgpt` container: header, framing, resync reader, defect model, symbol interning,
-  `META`/`SYMS`/`FRAM`/`DIRE` codecs, `GPUProfileSession`, `snapshot()`. 26 specs.
-- `GPUFrameRecorder` — holds the graph-pass ↔ timer-slot join, accumulates across every command
-  context in a frame, and rebases spans onto the frame epoch at close.
-
-Removed again on 2026-08-29: a `timestamp_period_ns` field and the GCD estimator that filled it.
-See §2.1 — quantization is documented and left alone.
-
-Wired end to end: `Renderer.profile_session`, `GPUFrameRecorder` holding the graph-pass ↔ timer-slot
-join, and `ShadeGPUCommandContext.profiling_absorbed` — which exists because `done` resolves at
-submit, before any timestamp has been read back.
-
-The calibration step is gone rather than outstanding: see §2.1.
-
-<details><summary>Original plan</summary>
-
-`GPUTimerArray` pooling and bound checks; `FrameGraph.onPassBegin`/`onPassEnd` and debug groups;
-`GPUProfileSession` at level 0, caller-constructed, streaming framed records with per-frame slack;
-`META`/`SYMS`/`FRAM`/`DIRE` records; round-trip and truncation-recovery tests on `SoftwareGPUDevice`.
-Deliverable: a `.sgpt` with real spans and no viewer.
-
-</details>
-
-### M2 — Inspector skeleton — **DONE**
-
-`packages/gpu-inspector-tool`. Plain ES modules, Canvas 2D, no runtime dependencies. Session strip,
-timeline, statistics, pass detail. `make_demo_capture` builds a synthetic capture through the
-engine's own writer, so the tool works without a GPU and the format's two halves are exercised
-against each other.
-
-### M3 — Structure — **DONE**
-
-`TOPO` with content-hash deduplication — 50 frames of an unchanged graph come to under 4 KB. Scopes,
-cull state, resource descriptors with footprints computed at record time. The inspector's Structure
-view is two cross-linked tables rather than a node-link diagram: two hundred passes over as many
-resource versions do not lay out into anything readable, and the questions actually asked are local.
-
-### M4 — Workload — **DONE**
-
-`make_profiling_pass_encoder` is a `Proxy` rather than a hand-written forwarder: a pass encoder has
-around twenty methods and WebGPU keeps adding them, and one silently dropped would break the
-renderer only while profiling. Dispatch and draw counts, pipeline identity, and `@workgroup_size`
-parsed from WGSL where it is a literal — an override expression records as *unknown*, which is not
-the same as zero.
-
-> **Reversed 2026-08-31.** The argument holds only while the wrapper is *conditional*; that is what
-> makes a missing method silent. `ShadeGPUComputePassEncoder` / `ShadeGPURenderPassEncoder` wrap
-> every pass, so a gap throws on the first frame of every build. The workgroup size now comes off
-> `ComputePipelineDescriptor`, which reads it as its code is set, with the parser that resolves
-> `const` references — a size it cannot read refuses to build the descriptor rather than recording
-> as unknown.
-
-No `PIPE` table in the end: a pass's pipeline label and workgroup size ride in its own workload
-block, which costs a symbol reference and avoids a second id space.
-
-### M5 — Analysis — **partly done**
-
-Statistics view and Chrome Trace Event export are in. Frame comparison and counter tracks are not;
-`CNTR` is reserved in the format for the latter.
-
-### M6 — Publish — **partly done**
-
-[`SGPT_FORMAT.md`](profile/SGPT_FORMAT.md) is the normative format specification, written for
-somebody outside the company, with a conformance summary for readers and writers. The inspector's
-README covers recording, levels, and the reading caveats.
-
-Outstanding: a hosting target for the built site, and deciding the licence the inspector ships
-under.
-
-**Not in scope, listed so it stays that way:** buffer/texture content capture, shader source in the
-container, replay, live attach to a running session, anything requiring a browser extension.
-
----
-
-## 9. Testing
-
-Per the established tiers:
-
-| Tier | Covers |
-|---|---|
-| **Unit, node** | Format round-trip: build a synthetic session, encode, decode, assert structural equality. Every chunk. Forward compatibility: a reader skipping an unknown chunk. Truncation and corruption: a bad checksum, a short chunk, a directory pointing past EOF — all must fail with a named error, not a stack trace out of `BinaryBuffer`. |
-| **`SoftwareGPUDevice`** | The recorder end to end without a GPU. The device already emulates `timestamp-query`, query sets and `write_pass_timestamp`, and already refuses a query set over 4096. Encode a frame graph, run a session, decode the output, assert the topology matches what was recorded. This is where the §1.4 attribution logic gets its coverage. |
-| **Playground page** | `src/shade/playground/` gets a capture harness against Sponza, which is also how M0 gets answered. |
-| **Inspector** | Golden captures checked into the package as fixtures. Parse-and-render smoke tests. A capture recorded before a format change must still open — that is what `min_reader_version` is for and it needs a test that proves it. |
-
----
-
-## 10. Risks
-
-| Risk | Severity | Handling |
-|---|---|---|
-| **Timestamp quantization makes per-frame timings unreadable on default browsers** (§2.1) | **High, and deliberately untreated** | Documented, not measured and not corrected — measuring it is the timing attack the mitigation prevents, and measuring it badly skews everything. The inspector names the flag and steers toward cross-frame aggregation, which is the honest reading of a coarse capture. |
-| Topology dedup does not pay off | Medium | M0 measures it. Design degrades gracefully; the size claims do not. |
-| Proxy encoder overhead distorts what it measures | Medium | Level-gate it; record measured overhead in `META`; forward-only methods, no allocation per call. |
-| One `GPUTimerArray` per context means several query sets per frame (§2.4) | Low–Medium | Record `query_set_id`. Consider a per-frame shared array as a follow-up, which would also simplify pooling. |
-| Format churn during development invalidates captures | Low | `min_reader_version` from day one; the inspector reads every version it ever supported; fixtures in the test suite. |
-| Publishing a proprietary-engine tool separately | Low, but real | The §4 rule-1 boundary is what makes this tractable. Enforce it in the build. Confirm the licensing intent for the published inspector before M6. |
-| **Uncapped session exhausts memory on a long level-3 capture** (§4.1, §5.8) | Medium | `bytes_written` readable and signalled; a `byte_budget` that warns rather than truncates. Accepted deliberately — full history is the point, and buffer/texture contents are a non-goal so nothing scales with resource size. |
-| Workspace restructure churns `moh` (§4.2) | Medium | Re-point the vendoring one level deeper so every `moh` path stays identical. Land as a pure move, separately. |
-
-## 11. Decisions taken — 2026-08-29
-
-| # | Question | Decision | Where it lives |
-|---|---|---|---|
-| 1 | Monorepo or not | **npm workspaces, and the existing tree moves to conform.** `packages/meep-engine/` + `packages/gpu-inspector-tool/`, symmetric siblings. | §4.2, M0.5 |
-| 2 | Does the recorder ship in production? | **Yes, but optional — the caller instantiates a `GPUProfileSession` and passes it in.** The engine never constructs one, so an application that does not import it does not carry it. | §6.1, §6.3 |
-| 3 | The `FrameGraph.execute` bracket | **Agreed, kept minimal — via `Signal`.** `onPassBegin` / `onPassEnd` beside the existing `onExecuted`, dispatch guarded by `hasHandlers()`. `Signal` is the project's standardised observer interface and a nullable callback field would let a second consumer silently clobber the first. | §1.4, §6.2 hook 1 |
-| 4 | Recording length policy | **Open-ended forward stream of self-contained frame records. `frame_limit` of N (1..∞) with an explicit `stop()`.** No ring buffer — full, uncapped, explicit history is the desired behaviour. Records are self-describing and checksummed, so a truncated capture stays readable; 1 MiB of slack reserved per frame keeps reallocation out of the record interior. | §5.8 |
-
-Two consequences of (4) worth carrying forward:
-
-- **There is no global string table.** Symbols are emitted inside the record that first needs them
-  (`SYMS`, §5.3), not gathered into a `STRS` chunk. A tail table would have made a truncated capture
-  resolve no names at all — the failure mode that hits precisely the capture of the crash you were
-  trying to record.
-- **Records are framed and checksummed** so a reader can resynchronise. This is what buys corruption
-  and truncation resilience, and it costs 20 bytes per frame.
+# A graphical GPU profiler for Shade — recorder, format, inspector
+
+Proposal, 2026-08-28. Decisions folded in 2026-08-29. Alex Goldring / Company Named Limited.
+
+> **Partly superseded, 2026-08-31**, by
+> [PASS_ENCODER_PROPOSAL_2026_08_31.md](../PASS_ENCODER_PROPOSAL_2026_08_31.md). The recording
+> proxy of §6.2 hook 3 and M4 is now a pair of decorator classes; `enable_debug_timers`,
+> `Renderer.add_debug_frame` and `Renderer.onFrameDebug` — which §6.1 kept — are gone, leaving the
+> profiler as the only path. §§1–5 remain a record of the state this design was written against.
+
+Scope: a **recording** side that ships with the engine, a **binary container** that carries a
+capture, and an **inspector** web application under `packages/gpu-inspector-tool/` that reads the
+container and nothing else.
+
+> The request spelled the directory `gpu-inespector-tool`. Reading that as a typo and using
+> `packages/gpu-inspector-tool/` throughout. Say the word if the misspelling was deliberate.
+
+**Four decisions are settled and written into the design below** — npm workspaces with the existing
+tree moved to conform (§4.2), a user-instantiated recorder passed in rather than a renderer-owned one
+(§6.1), the minimal `FrameGraph` bracket via `Signal` (§1.4), and an open-ended uncapped stream of
+self-contained frame records rather than a ring buffer (§5.8). §11 records them and what each costs.
+
+---
+
+## 0. Verdict
+
+**Worth building, and the engine is further along than it looks — but not in the place you would
+expect.**
+
+The timing half is the *small* half. `GPUTimerArray` already lands begin/end timestamps per GPU
+pass, and `SoftwareGPUDevice` already emulates timestamp queries well enough to test the recorder in
+node without a GPU. What is genuinely missing is **attribution**: the timestamps are keyed by
+`GPUComputePassDescriptor.label`, the dependency structure lives in `FrameGraph`, and *nothing
+connects the two*. One frame-graph pass can open several GPU passes with unrelated labels
+(`graph_build_hzb` → `hzb.build()` → its own `constructComputePass` labels), so a label is not a key.
+Closing that gap is the central piece of engineering in this proposal, and it is about thirty lines
+in `FrameGraph.execute` plus a field on the command context.
+
+The dependency half is nearly free. `FrameGraph.exportToJson()`
+([FrameGraph.js:644](src/engine/graphics/render/frame_graph/FrameGraph.js:644)) already emits passes,
+resource nodes, versions, readers, writers, producers and cull state, keyed consistently. Resource
+*sizes* fall out of the descriptors that graph already holds. Nesting for a flame-graph view falls
+out of `FrameGraphScope`.
+
+The work-size half needs a wrapper that does not exist: `beginComputePass` hands back the raw
+`GPUComputePassEncoder`, so `dispatchWorkgroups(x, y, z)` is invisible to us. A recording-only proxy
+around the pass encoder buys every dispatch and draw count for one class and no call-site churn.
+
+**The single biggest risk is not ours.** Chrome quantizes WebGPU timestamps to **100 µs** unless the
+user sets `chrome://flags/#enable-webgpu-developer-features`. Most Shade passes run well under that,
+so on a default browser almost every pass measures as exactly 0 or exactly 100 µs. A profiler that
+does not say this out loud, in the recording *and* in the inspector, is a profiler that lies. §2.1.
+
+---
+
+## 1. What exists today
+
+### 1.1 The timing path, end to end
+
+| Piece | Where | What it does |
+|---|---|---|
+| `GPUTimerArray` | [GPUTimerArray.js](src/shade/device/timing/GPUTimerArray.js) | One `GPUQuerySet` of `size * 2` timestamps. `getComputeWrites(label)` / `getRenderWrites(label)` claim a slot from an `IdPool` and return the `timestampWrites` struct. Resolve + copy to a `MAP_READ` buffer, `download_results()` maps it, `results_to_console_table()` turns slots into `{label, type, duration_ms, start, end}`. |
+| `ShadeGPUCommandContext.enable_debug_timers(cb)` | [ShadeGPUCommandContext.js:89](src/shade/device/ShadeGPUCommandContext.js:89) | Constructs a `GPUTimerArray` for this context. `beginComputePass` / `beginRenderPass` then inject `timestampWrites` into every descriptor. |
+| `finish()` | [ShadeGPUCommandContext.js:699](src/shade/device/ShadeGPUCommandContext.js:699) | Resolves the query set into the command buffer before `encoder.finish()`, then after submit downloads results and calls the callback, then destroys the timer array. |
+| `Renderer.add_debug_frame(count)` | [Renderer.js:626](src/shade/renderer/Renderer.js:626) | Arms N future frames. |
+| `Renderer.onFrameDebug` | [Renderer.js:408](src/shade/renderer/Renderer.js:408) | `send2(frame_index, table)`. **Currently has no subscribers anywhere in the tree.** |
+| `GPUTimerStats`, `format_nanosecond_time` | `src/shade/device/timing/` | Ring-buffer averaging and human formatting. Reusable in the inspector. |
+
+Degradation is already correct: with `timestamp-query` withheld, the query set is never created and
+`resolve` / `download_results` / `destroy` all no-op rather than throwing. Keep that property.
+
+### 1.2 Four defects the recorder must fix, not inherit
+
+1. **No slot bound check.** `GPUTimerArray.#bind_slot` takes an id from the `IdPool` and never
+   compares it to `#size`. Pass 1025 in a frame (default `size = 1024`) writes a query index past
+   `querySet.count` and takes a WebGPU validation error, at the `beginRenderPass` rather than at the
+   place that overflowed. A recording session runs *more* passes instrumented than a debug frame
+   does, so this is on the path. Clamp and count drops; report the drop count in the recording.
+2. **Per-context GPU allocation.** `enable_debug_timers` builds a query set and two buffers per
+   context and destroys them after the download. Fine for one frame; recording 600 frames means 600
+   query-set create/destroy pairs and 600 `mapAsync` round trips. Wants a small pool of timer arrays
+   cycled N-deep against frames in flight.
+3. **Descriptor mutation.** `beginComputePass` does `let _descriptor = descriptor;` and then writes
+   `_descriptor.timestampWrites`, mutating the caller's object. Several call sites reuse descriptor
+   objects. Copy, or document the mutation.
+4. **`beginComputePass()` with no descriptor throws** once timers are on, at
+   `timers.getComputeWrites(descriptor.label)`. Currently latent because every call site passes one.
+
+### 1.3 The structure half
+
+`FrameGraph.exportToJson()` is most of the dependency model already:
+
+```js
+{
+  passes:    [{ id, name, culled, reads: [node_id], writes: [node_id] }],
+  resources: [{ id, name, transient, version?, description?, createdBy?, readers?, writers? }]
+}
+```
+
+Keyed by **resource node** (per version), not by registry entry — deliberately, so
+`passes[].reads/writes` stay resolvable across versions. The recording format must preserve that
+choice; a registry-keyed export dangles every reference past version 0.
+
+What it does *not* carry, and we want:
+
+- `FrameGraphNode.scope` — the `FrameGraphScope` chain, which is the hierarchy a flame graph needs.
+- `ref_count` and `has_side_effects` — why a pass survived culling.
+- Typed descriptors. `description` is `resource_descriptor.toString()`, a human string
+  (`"Buffer{ size = 1,048,576, usage = STORAGE | COPY_DST }"`). We want the fields.
+
+### 1.4 The gap: labels are not keys
+
+```js
+// graph_build_hzb.js
+const builder = graph.add("hzb/ build", data, (data, resources, context) => {
+    hzb.build(context.encoder, source, viewport);   // opens N compute passes, its own labels
+});
+```
+
+`GPUTimerArray` records the labels `hzb.build` chose. `FrameGraph` records `"hzb/ build"`. Nothing
+relates them, and the relation is not derivable after the fact — labels are not unique, not stable,
+and one graph pass legitimately produces many GPU passes.
+
+**Fix:** bracket `node.execute(...)` inside `FrameGraph.execute`
+([FrameGraph.js:604](src/engine/graphics/render/frame_graph/FrameGraph.js:604)) so the context knows
+which graph pass is open. Every GPU pass begun while that bracket is open is attributed to it. The
+same bracket should emit `pushDebugGroup(node.name)` / `popDebugGroup()`, which costs nothing and
+immediately improves what RenderDoc, PIX and webgpu-inspector show — worth doing on its own merits.
+
+### 1.5 Work sizes are not observable today
+
+`beginComputePass` / `constructComputePass` return the **raw** `GPUComputePassEncoder`. All 11
+production `dispatchWorkgroups` call sites talk to it directly, as does every draw call across the
+31 render-pass construction sites. Editing every one of them to report its own counts is the wrong
+trade. A proxy encoder, installed only while recording, is one class.
+
+`SoftwareGPUComputePassEncoder` already models exactly this: it records
+`{pipeline, bind_groups, dynamic_offsets, group_counts}` per dispatch. The recording proxy is the
+same shape with a real encoder behind it.
+
+---
+
+## 2. What the platform will give us
+
+### 2.1 Timestamp quantization — the headline constraint
+
+Chrome quantizes `timestamp-query` results to **100 µs** as a timing-attack mitigation. It is
+disabled by `chrome://flags/#enable-webgpu-developer-features`; that flag does not itself enable the
+feature, which additionally needs the device to expose `timestamp-query`.
+
+100 µs is 0.1 ms. A Shade frame at 60 Hz has ~16.6 ms of budget spread over a couple of hundred
+passes. **The median pass is below the quantum.** Unmitigated, the tool reports a histogram of zeros
+with occasional 100 µs spikes, and every conclusion drawn from it is noise.
+
+**The decision is to leave it entirely alone.** Not measure it, not calibrate against it, not
+correct for it, not store a period in the container. Rejected 2026-08-29, and the reasoning is
+worth keeping because it is not obvious:
+
+- Recovering the quantum — GCD over observed timestamps, or any equivalent — **is the timing attack
+  the mitigation exists to prevent.** Doing it *well* means defeating a browser security control on
+  purpose, inside code we ship to other people.
+- Doing it *badly* is worse than not doing it. A period that is a multiple of the real one, or a
+  stale one from a browser update, becomes a correction applied to every number in the capture. A
+  profiler that silently skews its own data is worse than one that reports coarse data honestly.
+- Either way it is standing complexity and a source of fragility, bought for something the reader
+  can be told in one sentence.
+
+So: **note it, document it, do not treat it.** The capture records what the device reported —
+zeros included. `GPUProfileMeta` documents that browsers quantize and names the flag. The inspector
+says so where a reader will see it. What to make of a coarse capture is the reader's judgement, and
+the honest advice is the same either way: **aggregate across frames rather than trusting any single
+one.** That shapes the format in exactly one way, which it already did — keep every frame's raw
+values and never pre-aggregate on the recorder side.
+
+### 2.2 Pass granularity is the floor
+
+WebGPU writes timestamps at pass boundaries only. Per-draw timing needs
+`chromium-experimental-timestamp-query-inside-passes`, which is Chromium-only and experimental.
+
+**Design for pass granularity.** Treat inside-passes as an optional capability the recorder probes
+for and, if present, uses to add sub-pass markers — recorded as a distinct span kind so the format
+does not pretend the two are the same measurement.
+
+### 2.3 No CPU↔GPU clock sync
+
+WebGPU exposes no calibration between `performance.now()` and the GPU timestamp domain. Anything
+claiming to place CPU and GPU events on one axis is guessing.
+
+**Be honest in the format.** Record two clocks explicitly: a CPU track from `performance.now()`
+(encode time, submit time, callback time) and a GPU track from timestamps. The inspector shows two
+tracks anchored per frame at submit, and says the alignment is nominal. Perfetto solves this problem
+with explicit `ClockSnapshot` packets and a clock graph; we do not have the snapshots, so we do not
+get to claim the sync.
+
+### 2.4 Cross-query-set comparability
+
+Timestamps from two different `GPUQuerySet`s are not specified to share a domain. In Dawn they do in
+practice. Since each `ShadeGPUCommandContext` currently gets its own `GPUTimerArray`, and a frame has
+several contexts, **every frame already spans several query sets.**
+
+Record a `query_set_id` per span. Then the inspector can, if a capture ever looks wrong, colour
+spans by origin and let the reader see whether the anomaly follows a set boundary. Cheap; makes an
+otherwise unfalsifiable class of bug visible.
+
+### 2.5 Indirect work is unknowable at encode time
+
+`dispatchWorkgroupsIndirect` and `drawIndirect` take their counts from a GPU buffer. At encode time
+we know only *that* it was indirect. Two options, both worth having:
+
+- **v1:** record the indirect flag plus the source buffer's id and offset. The inspector shows
+  "indirect (unknown)" and links to the buffer.
+- **v2 (opt-in, costly):** the recorder copies indirect argument buffers into a readback staging
+  buffer at encode time and resolves the actual counts after submit. This is the only way to see the
+  real post-cull draw count, which for a GPU-driven renderer is one of the numbers most worth seeing.
+  It changes memory traffic, so it must be a flag, and the format must mark such counts as
+  *resolved* rather than *encoded* so nobody compares the two carelessly.
+
+### 2.6 Prior art
+
+| Tool | What to take | What to leave |
+|---|---|---|
+| [webgpu_inspector](https://github.com/brendan-duncan/webgpu_inspector) (Brendan Duncan) | The reference point for WebGPU frame capture in a browser. Object inspection with creation stacktraces; frame-time plotting; buffer content view. Its recorder emits a standalone replayable HTML file. | It is a *generic API* interceptor, extension-hosted. We want *engine-semantic* data — frame graph passes, resource lifetimes, cull decisions — which a generic interceptor cannot see. Complementary, not competing. |
+| [Perfetto](https://perfetto.dev/docs/getting-started/other-formats) | Track/slice model; nested slices; counter tracks; explicit clock domains. Its JSON importer is a free escape hatch — see §5.6. | The protobuf format and the full trace-processor stack are far more than we need, and its UI knows nothing about resource dependency. |
+| RenderDoc / PIX / Radeon GPU Profiler | The three-pane idiom: event list, timeline, per-event detail; a resource view keyed by lifetime; "why is this bound" attribution. | Native capture, replay, driver counters. Out of reach on WebGPU. |
+| Chrome Trace Event Format | Trivially writable, universally readable. | Text JSON at our event rates is 5–10× our binary size. Export target, not storage. |
+| [webgpufundamentals timing](https://webgpufundamentals.org/webgpu/lessons/webgpu-timing.html) | The canonical treatment of the query-set/resolve/map dance and its pitfalls. | — |
+
+The gap in that table is the whole reason to build this: **no existing tool knows what a Shade frame
+graph is.** Timings without the dependency structure tell you a pass is slow; timings *with* it tell
+you a pass is slow because it waits on a resource that a culled branch still produced.
+
+---
+
+## 3. What a recording must contain
+
+Three axes were asked for. A fourth is needed to make the first three legible.
+
+### 3.1 Timings
+
+| Datum | Source | Cost |
+|---|---|---|
+| GPU pass begin/end, ns | `GPUTimerArray` | free, already there |
+| Which query set a span came from | recorder | 1 byte |
+| CPU encode time per graph pass | `performance.now()` around `node.execute` | ~2 × 200 calls/frame |
+| CPU submit timestamp | `ShadeGPUCommandContext.finish` | free |
+| Callback/readback latency | recorder | free |
+| Sub-pass markers | `chromium-experimental-timestamp-query-inside-passes` if present | optional |
+
+### 3.2 Dependencies
+
+Straight from `FrameGraph`, enriched:
+
+- Passes: id, name, scope chain, culled, `ref_count`, `has_side_effects`, reads/writes/creates.
+- Resource nodes: id, name, version, transient/imported, producer, readers, writers.
+- Per graph pass: the GPU passes it opened, in order — the join from §1.4.
+- Resource lifetime: first write → last read, derivable from `ResourceEntry.last`, which `compile()`
+  already computes.
+
+### 3.3 Data sizes
+
+Descriptors carry everything:
+
+| Resource | Fields | Footprint |
+|---|---|---|
+| Buffer | `size` bytes, `usage` bitmask, `ensure_cleared` range | `size` directly |
+| Texture | `resolution[3]`, `format`, `dimension`, `mipLevelCount`, `sampleCount`, `usage` | computed from `gpu_texture_format_info` — `bytes_per_block`, `block_width`, `block_height` — summed over the mip chain, × `sampleCount` |
+
+These are **declared** sizes, not allocated ones; a pooled allocator may serve a larger block.
+`GraphicsContext.gpu_memory_usage` gives the real total per frame — record it as a counter track and
+let the inspector show declared-vs-actual as the aliasing metric it is.
+
+### 3.4 Work sizes
+
+| Datum | Needs |
+|---|---|
+| `dispatchWorkgroups(x, y, z)` | proxy encoder |
+| Workgroup size from the shader (`@workgroup_size`) | pipeline descriptor, recorded once per pipeline |
+| Total invocations = groups × workgroup size | derived in the inspector |
+| `draw` / `drawIndexed` vertex, index, instance counts | proxy encoder |
+| Indirect flag + argument buffer id/offset | proxy encoder |
+| Resolved indirect counts | §2.5 v2, opt-in |
+| Bind group contents per dispatch | proxy encoder; **large** — gate behind a verbosity level |
+| Render pass attachment formats and load/store ops | pass descriptor |
+
+### 3.5 The fourth axis — context, so any of it means anything
+
+Without this a shared recording is unreadable:
+
+- Adapter info (`vendor`, `architecture`, `device`, `description`), features, the limits that matter.
+- Engine version, git revision, build flags, `ENV_PRODUCTION`.
+- Renderer settings: internal vs output resolution, upscaler, which features are on.
+- Nothing about timestamp quantization: see §2.1 for why that is a deliberate absence.
+- Wall-clock start, session id, user-supplied note.
+- Scene scale: mesh/instance/light counts, resident material and geometry bytes.
+
+---
+
+## 4. Architecture
+
+```
+  ENGINE (ships)                      CONTAINER                 INSPECTOR (published separately)
+  ─────────────────────               ─────────                 ───────────────────────────────
+  GPUTimerArray ────┐
+  FrameGraph ───────┤                                            ┌── timeline / flame graph
+  proxy encoders ───┼──> GPUProfileSession ───> .sgpt ──drop──>  ├── dependency graph
+  GraphicsContext ──┘         │                  bytes           ├── resource table
+                              │                                  ├── pass detail
+                       sgpt_write_*                              └── frame comparison
+                              │                                          │
+                        BinaryBuffer  <───────────────────────────  sgpt_read_*
+```
+
+**Three rules that keep this from rotting.**
+
+1. **The container is the only interface.** The inspector imports the format readers and
+   `BinaryBuffer`. It never imports Shade, `FrameGraph`, or anything under `src/shade/renderer/`.
+   This is a licensing constraint as much as an architectural one — meep is proprietary and
+   source-available, and a separately published inspector must not carry renderer internals.
+2. **The recorder never blocks the frame.** Every buffer it touches is written at encode time or
+   read after submit. Serialization runs off the frame — accumulate into per-frame plain records,
+   encode to bytes when the session stops or when a chunk fills.
+3. **Reader and writer live together, in the engine tree.** Under
+   `src/shade/device/timing/profile/`, one file per concern, matching the `vgeo_*` convention. The
+   inspector package imports them by path. One definition of the format; no drift.
+
+### 4.1 Verbosity levels
+
+A capture is a trade between fidelity and cost. Four levels, recorded in the header:
+
+| Level | Adds | Bytes/frame, ~200 passes |
+|---|---|---|
+| 0 `TIMING` | GPU pass spans, frame boundaries | ~2 KB |
+| 1 `STRUCTURE` | + frame graph topology, resource descriptors, cull state | ~2 KB amortised (§5.4) |
+| 2 `WORKLOAD` | + dispatch/draw counts, pipeline identities, attachment state | ~6 KB |
+| 3 `VERBOSE` | + bind group contents, indirect readback, CPU per-pass timing | ~40 KB |
+
+Levels 0–2 are the product. Level 3 is for us, on a repro, and the inspector should say so when it
+opens one.
+
+Because a session is now **uncapped by default** (§5.8), those per-frame figures are also a rate.
+At 60 Hz:
+
+| Level | Per second | Per minute |
+|---|---|---|
+| 0 `TIMING` | ~120 KB | ~7 MB |
+| 1 `STRUCTURE` | ~120 KB | ~7 MB |
+| 2 `WORKLOAD` | ~360 KB | ~21 MB |
+| 3 `VERBOSE` | ~2.4 MB | ~144 MB |
+
+Levels 0–2 will run for many minutes without anyone noticing. **Level 3 will not**, and the session
+should say so — see the byte-budget warning in §5.8. This is the honest cost of "full and uncapped
+explicit history", and it is the right trade at levels 0–2.
+
+### 4.2 Repository layout
+
+The repo becomes an npm workspace root, and the engine moves down a level so the two packages are
+siblings rather than one being nested inside the other.
+
+```
+  meep/
+    package.json            workspace root: { "private": true, "workspaces": ["packages/*"] }
+    .gitlab-ci.yml
+    LICENSE, README.md, CONTRIBUTING.md, CHANGELOG.md, ...
+    packages/
+      meep-engine/          @woosh/meep-engine — everything that is published today
+        package.json        unchanged `exports`, `files`, version
+        src/  editor/  samples/  tools/
+        rollup.config.js  vite.config.mjs  vitest.config.mjs  tsconfig.types.json  babel.config.cjs
+      gpu-inspector-tool/   the inspector, published separately
+        package.json  index.html  src/  fixtures/
+```
+
+`@woosh/meep-engine`'s own `exports` map (`./src/*`, `./editor/*`) is relative to its own
+`package.json`, so **consumers installing from npm see no change at all**. The paths that move are
+in-repo and in anything vendoring this tree by path.
+
+**The cost is in `moh`, not here.** This tree is vendored into the game at
+`app/src/mir-engine/meep/`, and that is where the restructure is felt: every engine path becomes
+`app/src/mir-engine/meep/packages/meep-engine/src/...`. Two ways to absorb it, and this is the one
+call the restructure actually needs:
+
+- **Re-point the vendoring one level deeper** — mount `packages/meep-engine` as
+  `app/src/mir-engine/meep`. Every path in `moh` stays byte-identical, and the whole cost collapses
+  to one submodule/copy path. **This is the one to take** unless something in `moh` needs the
+  workspace root itself.
+- **Update paths in `moh`** — mechanical, wide, and it churns the ~20 design documents in this tree
+  that quote `app/src/mir-engine/meep/src/...` as a source root.
+
+In-repo edits either way: `vitest.config.mjs` `include`/`coverage.include` globs, `tsconfig.types.json`
+`include`/`rootDir`, `rollup.config.js` `input` paths, `.gitlab-ci.yml` script and artifact paths, and
+`vite.config.mjs`. All of them are prefix changes, and all of them get shorter, not longer, because
+they become relative to the package rather than the root.
+
+> Worth knowing before committing: npm lets a workspace root *also* be a package, so
+> `packages/gpu-inspector-tool` could have been added with the engine left exactly where it is and
+> zero paths touched. That option is on the table if the `moh` re-pointing turns out to be more
+> awkward than it looks. Proceeding with the move as decided — it is the cleaner end state and the
+> re-pointing above makes it cheap.
+
+---
+
+## 5. The `.sgpt` container
+
+**S**hade **G**PU **P**rofile **T**race. Magic `0x54504753` — the ASCII bytes `S G P T` read as a
+little-endian u32 at offset 0, matching the `VGEO_MAGIC` convention in
+[VGEO_MAGIC.js](packages/meep-engine/src/shade/renderer/geometry/virtual/format/header/VGEO_MAGIC.js).
+`sgpt_fourcc.js` computes these and a spec asserts every literal against it, because hand-deriving
+a little-endian FourCC is exactly the kind of arithmetic that is wrong once and then forever.
+
+### 5.1 Why binary, concretely
+
+A 600-frame capture at level 2, ~200 passes/frame, in Chrome Trace Event JSON: each span is roughly
+`{"ph":"X","name":"...","cat":"gpu","ts":123456.7,"dur":234.5,"pid":1,"tid":3,"args":{...}}` — call
+it 140 bytes minified, times 120,000 spans, **~17 MB**, before pass arguments. The same content in
+the layout below is **~1.5 MB**, and gzip (already a dependency via `pako`, and available natively
+via `CompressionStream`) takes it under 400 KB. That is the difference between a capture you attach
+to a bug report and one you do not.
+
+### 5.2 Layout
+
+Chunked, directory at the tail — so a writer streams forward and only seeks back once, and a reader
+can pull the header and the frame index without reading the payload.
+
+```
+  offset  size   field
+  ──────────────────────────────────────────────────────────────────
+       0     4   magic                        u32   0x54504753
+       4     2   format_version               u16
+       6     2   min_reader_version           u16
+       8     4   flags                        u32   bit0 = CLOSED (writer reached stop)
+      12     4   header_checksum              u32   over bytes [0, 8) only — see below
+      16     8   directory_offset             u64   0 when the session never stopped
+      24     8   directory_byte_length        u64
+      32   ...   records, in write order
+     ...   ...   directory record
+```
+
+**The checksum stops at byte 8, short of `flags`.** Everything from `flags` onward is patched at
+stop — the CLOSED bit and the directory pointer — and a checksum covering them would have to be
+recomputed then. Fine for a capture that stops; exactly wrong for one that does not, which would
+carry a checksum over bytes never written and read as corrupt. What stays under it is what a reader
+must trust before it can do anything at all: is this an `.sgpt`, and can this build read it.
+
+### 5.3 Chunks
+
+| FourCC | Purpose | Cardinality |
+|---|---|---|
+| `META` | §3.5 context. Adapter, engine version, settings, verbosity level, session note. | 1 |
+| `SYMS` | Symbol block. Names, labels, formats, scope names — emitted **inside the record that first needs them** and referenced by u32 index thereafter, so a truncated capture still resolves every name it references (§5.8). | 0..n |
+| `PIPE` | Pipeline table: id, label, kind, shader module name, `@workgroup_size`, entry point, vertex layout digest. | 1 |
+| `TOPO` | Frame-graph **topologies**: pass list, resource node list, edges, scopes, descriptors. Content-hashed and deduplicated across frames (§5.4). | 0..n |
+| `FRAM` | One per frame: topology id, CPU timestamps, span array, dispatch/draw array, counters. | 0..n |
+| `CNTR` | Counter tracks sampled per frame: `gpu_memory_usage`, mesh/instance/light counts, resolution. | 0..1 |
+| `NOTE` | Free-form user annotations with a frame index — "this is where it hitches". | 0..n |
+| `DIRE` | Directory: `{chunk_type, offset, byte_length}` plus a frame index of `{frame_number, chunk_offset, gpu_duration_ns}` so the inspector can draw the frame-time strip before parsing anything else. | 1 |
+
+Unknown chunk types are skipped by length. That is what makes level-3 payloads addable without a
+version bump, and what lets an old inspector open a new capture and say honestly which parts it
+cannot show.
+
+### 5.4 The compression that matters: topology deduplication
+
+**A Shade frame graph is nearly identical frame to frame.** Same passes, same resources, same edges;
+what changes is the timings, the cull decisions, and the occasional resolution change. Recording the
+full topology 600 times is the difference between a 20 MB file and a 1.5 MB one.
+
+So: hash the recorded topology (pass names, edges, descriptors, scope chain). If the hash matches a
+`TOPO` already written, the frame stores only the topology id. Cull state and per-pass timings stay
+in `FRAM`, because they are exactly what varies.
+
+Expected behaviour on a real capture: a handful of distinct topologies over 600 frames — steady
+state, plus the shadow-refresh variants, plus resolution changes. §4.1's "~2 KB amortised" for level
+1 is that claim.
+
+This must be **measured, not assumed**. If topologies turn out to churn every frame, the design
+still works (it degrades to storing each), but the size estimates in §5.1 do not. First milestone
+work item, §8.
+
+### 5.5 Per-frame span encoding
+
+Per span, level 0:
+
+| Field | Type | Note |
+|---|---|---|
+| `pass_ref` | `uintVar` | index into the topology's GPU-pass list |
+| `t_begin` | `u32` | ns offset from the frame's `gpu_epoch_ns` |
+| `t_end_delta` | `uintVar` | ns from `t_begin` |
+| `query_set_id` | `u8` | §2.4 |
+
+`u32` for the frame-relative begin holds 4.29 s — three orders of magnitude of headroom over a
+frame, and it survives a stall without overflowing. `BinaryBuffer.writeUintVar` / `readUintVar`
+already exist and handle the two variable-length fields.
+
+That is ~10 bytes per span against 26 for a naive absolute-u64 encoding, and the frame's absolute
+epoch is stored once as a `u64`.
+
+### 5.6 Chrome Trace Event export
+
+The inspector exports the loaded capture as Chrome Trace Event JSON, for opening in
+[ui.perfetto.dev](https://perfetto.dev/docs/getting-started/other-formats). Costs an afternoon and
+buys: a second opinion when the inspector looks wrong, a viewer for anyone unwilling to run ours, and
+a sanity check on our own timeline maths. Passes become `X` slices on a GPU track, scopes become
+nesting, counters become `C` events. Lossy — the dependency graph has no representation there — which
+is precisely why it is an export and not the storage format.
+
+### 5.7 String encoding
+
+Symbols live in `SYMS` blocks with u32 indices, emitted inside the record that first needs them
+(§5.8). Not `EncodingBinaryBuffer`: it deduplicates by writing back-references to **absolute buffer
+positions** ([EncodingBinaryBuffer.js:21](src/core/binary/EncodingBinaryBuffer.js:21)), which is
+correct for a single flat buffer and wrong the moment records are skipped by a reader that does not
+understand them, resynchronised after corruption, or read from a truncated file — all three of which
+this format is explicitly built to survive. An index table costs one indirection and holds up under
+all of them.
+
+### 5.8 Streaming: self-contained frame records
+
+The session is an **open-ended forward stream with an explicit stop**. No ring, no cap: `frame_limit`
+defaults to `Infinity`, `stop()` ends it early, and everything recorded is kept.
+
+**A frame is written as one complete, self-describing record and pushed when it closes.** That is
+the organising decision, and three properties follow from it:
+
+- **It is resynchronisable.** Every record opens with a sync marker, its type, its payload length and
+  a checksum. A reader that lands on garbage scans forward for the next marker and carries on. A
+  capture cut off mid-session — tab killed, GPU reset, `device.lost` — stays readable up to the last
+  intact record, and those are exactly the captures worth having.
+- **Symbols travel with the record that introduces them.** A record carrying a new topology carries
+  the names that topology needs; a frame record reusing a known topology carries none. There is no
+  global string table to finalise, which is what would otherwise force a tail chunk and make a
+  truncated file unreadable — the failure mode where the one capture of the crash resolves no names.
+- **Nothing is back-patched except the header's directory pointer**, and even that is optional: a
+  reader can recover the whole stream by scanning records when the directory is missing or the file
+  was truncated before `stop()` ran.
+
+Order on the wire:
+
+```
+  header                 magic, versions, flags; directory_offset patched at stop, 0 if never stopped
+  META                   at start — adapter, engine version, renderer settings, level
+  TOPO #0 + its symbols  first frame's topology
+  FRAM #0                topology id + spans + counts
+  FRAM #1                same topology → id only
+  ...
+  TOPO #1 + its symbols  shadow refresh changed the graph
+  FRAM #57
+  ...
+  CNTR, DIRE             at stop — the directory is an index, not a dependency
+```
+
+Record framing, every record identical:
+
+```
+       0     4   sync                         u32   0x43455253  ('SREC')
+       4     4   record_type                  u32   FourCC
+       8     4   payload_byte_length          u32
+      12     4   payload_checksum             u32   crc32 over the payload
+      16   ...   payload
+```
+
+u32 for the length rather than u64: a record describes one frame's control flow, and resource
+*contents* are a non-goal, so nothing in one scales with the size of what it describes. Four
+gigabytes is not a ceiling anything can approach.
+
+**The sync marker alone is not enough to resynchronise on**, and the reader does not treat it as
+though it were. Four bytes of payload can spell `SREC` — a pass label could — so a candidate counts
+only when its length also fits and its payload also checksums. There is a spec for exactly that
+case.
+
+**Reallocation is a non-issue, and the slack reservation settles what is left of it.** We are
+measuring GPU time, not CPU time; a `setCapacity` copy is a heap allocation and a memcpy that may
+evict some cache, which at worst makes the next GPU upload marginally slower. That is a rounding
+error against what is being measured. To keep even that out of the frame interior, the writer
+reserves at the frame boundary:
+
+```js
+buffer.ensureCapacity(buffer.position + FRAME_SLACK);   // FRAME_SLACK = 1 MiB
+```
+
+Any growth then happens between frames, never inside a record. 1 MiB against level 2's ~6 KB per
+frame is three orders of magnitude of headroom, so the reservation only actually forces a grow once
+every ~170 frames. One `BinaryBuffer`, no segmentation, no assembly pass.
+
+**Scope note, and it is what makes the above generous rather than marginal: GPU buffer and texture
+contents are a non-goal.** The stream carries control flow and dataflow metadata — passes, edges,
+descriptors, counts, timings. Nothing in it scales with the size of the resources it describes. That
+is why a frame record is kilobytes and why 1 MiB of slack is never the binding constraint.
+
+**Uncapped still means uncapped, so the session stays legible about it.** `bytes_written` is readable
+at any time and `onBytesWritten` fires per frame, so an application can show a counter. A configurable
+`byte_budget` — default 512 MB — does not stop the recording; it warns once, naming the level and the
+observed rate. Silent unbounded growth in a debug tool is how you lose a browser tab and the capture
+with it.
+
+---
+
+## 6. The recorder
+
+### 6.1 Surface — the caller owns the session
+
+**The engine never constructs a profile session.** The caller builds one and hands it in; the
+renderer holds a nullable reference and nothing more. Nothing in `Renderer` imports the profiler.
+
+```js
+import { GPUProfileSession } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileSession.js";
+import { GPUProfileLevel } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileLevel.js";
+
+const session = new GPUProfileSession({
+    level: GPUProfileLevel.WORKLOAD,
+    frame_limit: Infinity,                       // default; a number caps it
+    note: "hitch on shadow refresh, RTX 3070"
+});
+
+renderer.profile_session = session;              // nullable field, that is the whole API
+
+session.start();                                 // META is written here; populate meta first
+// ... frames run, for as long as you like ...
+const bytes = await session.stop();              // ArrayBuffer, ready to save
+
+renderer.profile_session = null;
+```
+
+Three things fall out of the caller owning it, and all three are why this is the right shape:
+
+- **It is genuinely optional.** The profiler is a leaf module nothing in the engine imports. An
+  application that never imports `GPUProfileSession` does not have it in its bundle — the answer to
+  "does this ship in production builds" is *it ships, and it costs nothing to anyone who does not ask
+  for it*. No build flag, no strip-plugin interaction, no dead-code branch to keep honest.
+- **Lifetime is explicit.** A session that outlives a device, or two sessions at once, are the
+  caller's problem to not create, and `start()` asserts against both rather than papering over them.
+- **The engine surface is one nullable field.** `Renderer.profile_session`, forwarded to the
+  `GraphicsContext` so command contexts can find it. That is the entire integration.
+
+`frame_limit` reaching zero stops the session exactly as `stop()` does. Both resolve the same
+promise, so a caller that wants "500 frames or until I say" writes one `await`.
+
+~~`add_debug_frame` and `onFrameDebug` stay exactly as they are — cheap, synchronous, console-shaped,
+and a different tool for a different question.~~
+
+> **Reversed 2026-08-31.** They were not a different tool, they were a worse view of the same one
+> reached through a second API — no graph-pass attribution, no workload, no pipeline identity — and
+> `onFrameDebug` never acquired a subscriber. Removed; the profiler is the only path. "Profile the
+> next N frames" is `new GPUProfileSession({ frame_limit: N })`.
+
+### 6.2 The five hooks
+
+1. **`FrameGraph.execute`** — bracket `node.execute(...)`. Notify listeners which graph pass is open;
+   take CPU timestamps either side; push/pop a debug group. The only edit outside `src/shade/`.
+
+   Two `Signal`s on `FrameGraph`, `onPassBegin` / `onPassEnd`, alongside the `onExecuted` that is
+   already there. **Signal, not a nullable callback field** — it is the project's standardised
+   observer interface, it supports more than one listener, and `remove` is symmetric with `add`.
+   A bare nullable callback lets the second consumer silently clobber the first, which is exactly
+   the bug that does not announce itself.
+
+   Guard the dispatch with `hasHandlers()`: `send1` on an empty signal still bumps `generation` and
+   walks a Map iterator, and this fires twice per pass — a couple of hundred passes a frame. One
+   `Map.size` comparison ahead of it keeps the disabled path honest.
+
+   `FrameGraph` still learns nothing about what a profiler is; it announces its own pass boundaries
+   and the profiler is one possible listener.
+2. **`ShadeGPUCommandContext`** — a `#profile_sink` field. When set, `beginComputePass` /
+   `beginRenderPass` report `{label, kind, graph_pass_id, query_slot, query_set_id}` and wrap the
+   returned encoder in the recording proxy.
+3. **The proxy encoders** — `ProfilingComputePassEncoder`, `ProfilingRenderPassEncoder`. Forward
+   everything; record `dispatchWorkgroups*`, `draw*`, `setPipeline`, `setBindGroup`. Modelled on
+   `SoftwareGPUComputePassEncoder`, which already records exactly this shape.
+4. **`GPUTimerArray`** — pooling (§1.2.2), bound checking (§1.2.1), and expose raw slot data rather
+   than only the console table.
+5. **`GraphicsContext`** — sample `gpu_memory_usage` and the collection counters once per frame into
+   the counter track.
+
+### 6.3 Cost when off
+
+Every hook is a null check against a field that is `null` in normal operation. No allocation and no
+proxy construction; the frame-graph bracket is two comparisons per pass. This must stay true — a
+profiler that costs something when disabled will be disabled at the build level and then rot.
+
+Because the session is caller-constructed (§6.1), an application that never imports it pays not even
+that: the profiler modules are unreachable from any engine entry point and drop out of the bundle
+entirely. The null checks are the only residue, and they are the price of the feature existing.
+
+### 6.4 Cost when on
+
+Level 0–2 add: one `performance.now()` pair per graph pass, one small record per GPU pass, one per
+dispatch/draw, and a `push`/`popDebugGroup` pair per graph pass. The existing per-context query set
+churn (§1.2.2) is the largest cost and the pool removes it. Expect single-digit percent frame-time
+overhead at level 2; measure it and record the measurement in `META`, so a reader can see how much of
+what they are looking at is the observer.
+
+---
+
+## 7. The inspector
+
+`packages/gpu-inspector-tool/`. A static site: drop a `.sgpt` on it, or pass `?file=` for a
+bookmarkable view — the affordance the `vgeo_viewer` playground already establishes in this codebase.
+
+### 7.1 Technology
+
+**Plain ES modules, Canvas 2D for the timeline, DOM for panels, no runtime dependencies, built with
+Vite.** Reasons: the repo has no UI framework and adding one for this is unjustified; the timeline is
+a custom-drawn virtualised widget that a framework would only get in the way of; zero dependencies
+keeps a separately published proprietary artifact simple to reason about; and Vite is already the dev
+server here.
+
+The only imports from the engine tree are `src/core/binary/BinaryBuffer.js` and the `sgpt_*` readers.
+That boundary is a build-time assertion, not a convention — a lint rule that fails the build on any
+other engine import.
+
+### 7.2 Views
+
+| View | Answers |
+|---|---|
+| **Frame strip** | Which frame is interesting. Frame time over the session, GPU and CPU overlaid, hitches marked, brush to select a range. Drawn from the directory index alone, so it appears before the payload finishes parsing. |
+| **Timeline / flame graph** | Where the time went in *this* frame. Spans on a GPU track, nested by `FrameGraphScope`; a CPU track above with encode time; hover for exact ns; click to select. |
+| **Statistics** | Where the time goes *in general*. Per-pass min/median/p95/max/total across the selected frame range, sorted by total contribution. **On a quantized capture this is the only honest view** — and since the tool does not measure quantization (§2.1), it cannot detect that case and switch by itself. It says so plainly instead, always. |
+| **Dependency graph** | Why this pass runs, and what it waits on. Passes and resource nodes, culled ones greyed, edges directed. Select a pass → highlight its transitive inputs. Select a resource → its version chain and every reader. |
+| **Resource table** | What memory costs. Every resource node with declared bytes, format, usage, transient/imported, lifetime span, peak concurrent footprint. Sorted by size. Declared total vs `gpu_memory_usage` side by side. |
+| **Pass detail** | Everything about one pass. Timings across frames as a sparkline, dispatch/draw counts, derived total invocations, pipeline and workgroup size, attachments, bindings at level 3. |
+| **Frame comparison** | What changed. Two frames or two ranges side by side, per-pass deltas sorted by regression. This is the view that makes the tool useful for optimisation work rather than only for diagnosis. |
+
+### 7.3 What it must refuse to do
+
+- **Never invent precision the data does not have.** Durations are drawn as reported. Where many
+  spans read as exactly zero, that is shown as what it is — a quantized capture — with a note
+  naming the browser flag, not smoothed into plausible-looking small numbers.
+- **Never present the CPU and GPU tracks as one clock** (§2.3). Two tracks, anchored per frame,
+  labelled as nominal.
+- **Never hide dropped spans.** If the recorder dropped passes on slot exhaustion (§1.2.1), say how
+  many, on the frame that dropped them.
+
+---
+
+## 8. Phasing
+
+Each milestone is independently useful and independently shippable.
+
+### M0 — Measure the assumptions (½ day)
+
+Before any of the below. Instrument one Sponza capture and answer three questions, because three
+size estimates and one whole design decision rest on them:
+
+1. How many distinct frame-graph topologies over 600 frames? (§5.4)
+2. ~~What is the observed timestamp period~~ — dropped; the tool does not measure this (§2.1).
+3. How many GPU passes per frame, actually? (`GPUTimerArray` default is 1024 slots; §1.2.1)
+
+Write the answers into this document.
+
+### M0.5 — Workspace restructure — **DONE**
+
+Landed 2026-08-29. `packages/meep-engine/` holds the engine, the workspace root holds the two
+`.gitignore` halves, the CI paths and a README. Suite green at 2156 files / 14580 tests. One spec
+had to move with it: `meep_three_free.spec.js` asserts the `*.d.ts` ignore rule at the engine root,
+so that rule lives in the package's `.gitignore` rather than the workspace's.
+
+**`moh` still needs its vendoring re-pointed one level deeper** — mount `packages/meep-engine` where
+it currently mounts the repository root, and every path inside it stays byte-identical.
+
+<details><summary>Original plan</summary>
+
+§4.2. Independent of everything else and worth landing first so no profiler work has to be moved
+afterwards. Order: create `packages/meep-engine/`, `git mv` the tree, fix the five config files,
+green the suite, re-point `moh`'s vendoring one level deeper, green `moh`. Land as its own commit —
+a pure move with no content changes, so the diff stays reviewable and a bisect through it is honest.
+
+</details>
+
+### M1 — Timing spine — **DONE**
+
+Landed:
+
+- `FrameGraph.onPassBegin` / `onPassEnd`, guarded by `hasHandlers()`, closed in a `finally` so a
+  throwing pass still ends its bracket. Five specs including the exception path.
+- `GPUTimerArray`: bound check (a full array now refuses a slot instead of addressing past its query
+  set), `dropped_count`, `traverse_results` for raw `BigInt` timestamps. Seven specs.
+- `ShadeGPUCommandContext`: `#with_timestamp_writes` — copies the descriptor instead of stamping the
+  caller's, tolerates a missing descriptor, and leaves `timestampWrites` off when no slot is free.
+- The whole `.sgpt` container: header, framing, resync reader, defect model, symbol interning,
+  `META`/`SYMS`/`FRAM`/`DIRE` codecs, `GPUProfileSession`, `snapshot()`. 26 specs.
+- `GPUFrameRecorder` — holds the graph-pass ↔ timer-slot join, accumulates across every command
+  context in a frame, and rebases spans onto the frame epoch at close.
+
+Removed again on 2026-08-29: a `timestamp_period_ns` field and the GCD estimator that filled it.
+See §2.1 — quantization is documented and left alone.
+
+Wired end to end: `Renderer.profile_session`, `GPUFrameRecorder` holding the graph-pass ↔ timer-slot
+join, and `ShadeGPUCommandContext.profiling_absorbed` — which exists because `done` resolves at
+submit, before any timestamp has been read back.
+
+The calibration step is gone rather than outstanding: see §2.1.
+
+<details><summary>Original plan</summary>
+
+`GPUTimerArray` pooling and bound checks; `FrameGraph.onPassBegin`/`onPassEnd` and debug groups;
+`GPUProfileSession` at level 0, caller-constructed, streaming framed records with per-frame slack;
+`META`/`SYMS`/`FRAM`/`DIRE` records; round-trip and truncation-recovery tests on `SoftwareGPUDevice`.
+Deliverable: a `.sgpt` with real spans and no viewer.
+
+</details>
+
+### M2 — Inspector skeleton — **DONE**
+
+`packages/gpu-inspector-tool`. Plain ES modules, Canvas 2D, no runtime dependencies. Session strip,
+timeline, statistics, pass detail. `make_demo_capture` builds a synthetic capture through the
+engine's own writer, so the tool works without a GPU and the format's two halves are exercised
+against each other.
+
+### M3 — Structure — **DONE**
+
+`TOPO` with content-hash deduplication — 50 frames of an unchanged graph come to under 4 KB. Scopes,
+cull state, resource descriptors with footprints computed at record time. The inspector's Structure
+view is two cross-linked tables rather than a node-link diagram: two hundred passes over as many
+resource versions do not lay out into anything readable, and the questions actually asked are local.
+
+### M4 — Workload — **DONE**
+
+`make_profiling_pass_encoder` is a `Proxy` rather than a hand-written forwarder: a pass encoder has
+around twenty methods and WebGPU keeps adding them, and one silently dropped would break the
+renderer only while profiling. Dispatch and draw counts, pipeline identity, and `@workgroup_size`
+parsed from WGSL where it is a literal — an override expression records as *unknown*, which is not
+the same as zero.
+
+> **Reversed 2026-08-31.** The argument holds only while the wrapper is *conditional*; that is what
+> makes a missing method silent. `ShadeGPUComputePassEncoder` / `ShadeGPURenderPassEncoder` wrap
+> every pass, so a gap throws on the first frame of every build. The workgroup size now comes off
+> `ComputePipelineDescriptor`, which reads it as its code is set, with the parser that resolves
+> `const` references — a size it cannot read refuses to build the descriptor rather than recording
+> as unknown.
+
+No `PIPE` table in the end: a pass's pipeline label and workgroup size ride in its own workload
+block, which costs a symbol reference and avoids a second id space.
+
+### M5 — Analysis — **partly done**
+
+Statistics view and Chrome Trace Event export are in. Frame comparison and counter tracks are not;
+`CNTR` is reserved in the format for the latter.
+
+### M6 — Publish — **partly done**
+
+[`SGPT_FORMAT.md`](profile/SGPT_FORMAT.md) is the normative format specification, written for
+somebody outside the company, with a conformance summary for readers and writers. The inspector's
+README covers recording, levels, and the reading caveats.
+
+Outstanding: a hosting target for the built site, and deciding the licence the inspector ships
+under.
+
+**Not in scope, listed so it stays that way:** buffer/texture content capture, shader source in the
+container, replay, live attach to a running session, anything requiring a browser extension.
+
+---
+
+## 9. Testing
+
+Per the established tiers:
+
+| Tier | Covers |
+|---|---|
+| **Unit, node** | Format round-trip: build a synthetic session, encode, decode, assert structural equality. Every chunk. Forward compatibility: a reader skipping an unknown chunk. Truncation and corruption: a bad checksum, a short chunk, a directory pointing past EOF — all must fail with a named error, not a stack trace out of `BinaryBuffer`. |
+| **`SoftwareGPUDevice`** | The recorder end to end without a GPU. The device already emulates `timestamp-query`, query sets and `write_pass_timestamp`, and already refuses a query set over 4096. Encode a frame graph, run a session, decode the output, assert the topology matches what was recorded. This is where the §1.4 attribution logic gets its coverage. |
+| **Playground page** | `src/shade/playground/` gets a capture harness against Sponza, which is also how M0 gets answered. |
+| **Inspector** | Golden captures checked into the package as fixtures. Parse-and-render smoke tests. A capture recorded before a format change must still open — that is what `min_reader_version` is for and it needs a test that proves it. |
+
+---
+
+## 10. Risks
+
+| Risk | Severity | Handling |
+|---|---|---|
+| **Timestamp quantization makes per-frame timings unreadable on default browsers** (§2.1) | **High, and deliberately untreated** | Documented, not measured and not corrected — measuring it is the timing attack the mitigation prevents, and measuring it badly skews everything. The inspector names the flag and steers toward cross-frame aggregation, which is the honest reading of a coarse capture. |
+| Topology dedup does not pay off | Medium | M0 measures it. Design degrades gracefully; the size claims do not. |
+| Proxy encoder overhead distorts what it measures | Medium | Level-gate it; record measured overhead in `META`; forward-only methods, no allocation per call. |
+| One `GPUTimerArray` per context means several query sets per frame (§2.4) | Low–Medium | Record `query_set_id`. Consider a per-frame shared array as a follow-up, which would also simplify pooling. |
+| Format churn during development invalidates captures | Low | `min_reader_version` from day one; the inspector reads every version it ever supported; fixtures in the test suite. |
+| Publishing a proprietary-engine tool separately | Low, but real | The §4 rule-1 boundary is what makes this tractable. Enforce it in the build. Confirm the licensing intent for the published inspector before M6. |
+| **Uncapped session exhausts memory on a long level-3 capture** (§4.1, §5.8) | Medium | `bytes_written` readable and signalled; a `byte_budget` that warns rather than truncates. Accepted deliberately — full history is the point, and buffer/texture contents are a non-goal so nothing scales with resource size. |
+| Workspace restructure churns `moh` (§4.2) | Medium | Re-point the vendoring one level deeper so every `moh` path stays identical. Land as a pure move, separately. |
+
+## 11. Decisions taken — 2026-08-29
+
+| # | Question | Decision | Where it lives |
+|---|---|---|---|
+| 1 | Monorepo or not | **npm workspaces, and the existing tree moves to conform.** `packages/meep-engine/` + `packages/gpu-inspector-tool/`, symmetric siblings. | §4.2, M0.5 |
+| 2 | Does the recorder ship in production? | **Yes, but optional — the caller instantiates a `GPUProfileSession` and passes it in.** The engine never constructs one, so an application that does not import it does not carry it. | §6.1, §6.3 |
+| 3 | The `FrameGraph.execute` bracket | **Agreed, kept minimal — via `Signal`.** `onPassBegin` / `onPassEnd` beside the existing `onExecuted`, dispatch guarded by `hasHandlers()`. `Signal` is the project's standardised observer interface and a nullable callback field would let a second consumer silently clobber the first. | §1.4, §6.2 hook 1 |
+| 4 | Recording length policy | **Open-ended forward stream of self-contained frame records. `frame_limit` of N (1..∞) with an explicit `stop()`.** No ring buffer — full, uncapped, explicit history is the desired behaviour. Records are self-describing and checksummed, so a truncated capture stays readable; 1 MiB of slack reserved per frame keeps reallocation out of the record interior. | §5.8 |
+
+Two consequences of (4) worth carrying forward:
+
+- **There is no global string table.** Symbols are emitted inside the record that first needs them
+  (`SYMS`, §5.3), not gathered into a `STRS` chunk. A tail table would have made a truncated capture
+  resolve no names at all — the failure mode that hits precisely the capture of the crash you were
+  trying to record.
+- **Records are framed and checksummed** so a reader can resynchronise. This is what buys corruption
+  and truncation resilience, and it costs 20 bytes per frame.