@woosh/meep-engine 3.10.0 → 3.11.0

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

@@ -1,6 +1,6 @@
 # A graphical GPU profiler for Shade — recorder, format, inspector
 
-Proposal, 2026-08-28. Alex Goldring / Company Named Limited.
+Proposal, 2026-08-28. Decisions folded in 2026-08-29. Alex Goldring / Company Named Limited.
 
 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
@@ -9,6 +9,11 @@ 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
@@ -141,21 +146,25 @@ feature, which additionally needs the device to expose `timestamp-query`.
 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.
 
-Three consequences, all of which belong in the design rather than in a README:
-
-- **Measure the quantum, do not assume it.** At session start, run a calibration: submit a known
-  workload repeatedly, collect raw timestamp values, take the GCD of the deltas. Store the result as
-  `timestamp_period_ns` in the recording header.
-- **Stamp it into the container** so the inspector knows what it is looking at without being told.
-- **The inspector refuses to draw a precise-looking picture from imprecise data.** If
-  `timestamp_period_ns > 1000`, the timeline renders spans with explicit uncertainty bars and a
-  persistent banner naming the flag. Not a footnote in a tooltip.
-
-There is a real mitigation beyond the flag: **aggregate across frames.** 600 frames of a 40 µs pass
-quantized to 100 µs still average toward ~40 µs, because the quantization is in practice a floor
-applied to a free-running counter rather than a deterministic snap of the duration. The inspector's
-statistical view is therefore not a nicety — on a default browser it is the *only* trustworthy view.
-This shapes the format: keep every frame's raw values, never pre-aggregate on the recorder side.
+**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
 
@@ -274,7 +283,7 @@ 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.
-- `timestamp_period_ns` (§2.1) and whether the developer-features flag was detected.
+- 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.
 
@@ -287,7 +296,7 @@ Without this a shared recording is unreadable:
   ─────────────────────               ─────────                 ───────────────────────────────
   GPUTimerArray ────┐
   FrameGraph ───────┤                                            ┌── timeline / flame graph
-  proxy encoders ───┼──> GPUProfileRecorder ──> .sgpt ──drop──>  ├── dependency graph
+  proxy encoders ───┼──> GPUProfileSession ───> .sgpt ──drop──>  ├── dependency graph
   GraphicsContext ──┘         │                  bytes           ├── resource table
                               │                                  ├── pass detail
                        sgpt_write_*                              └── frame comparison
@@ -322,13 +331,75 @@ A capture is a trade between fidelity and cost. Four levels, recorded in the hea
 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 `0x54505347` — the ASCII bytes `S G P T` read as a
+**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](src/shade/renderer/geometry/virtual/format/header/VGEO_MAGIC.js).
+[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
 
@@ -347,31 +418,29 @@ can pull the header and the frame index without reading the payload.
 ```
   offset  size   field
   ──────────────────────────────────────────────────────────────────
-       0     4   magic                        u32   0x54505347
+       0     4   magic                        u32   0x54504753
        4     2   format_version               u16
        6     2   min_reader_version           u16
-       8     4   flags                        u32   bit0 = payload deflated
-      12     4   header_checksum              u32   over bytes [0, 12)
-      16     8   directory_offset             u64
+       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   ...   chunks, in write order
-     ...   ...   directory
+      32   ...   records, in write order
+     ...   ...   directory record
 ```
 
-Chunk framing, uniform:
-
-```
-       0     4   chunk_type                   u32   FourCC
-       4     8   payload_byte_length          u64
-      12   ...   payload
-```
+**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, `timestamp_period_ns`, verbosity level, session note. | 1 |
-| `STRS` | String table. Every name, label, format, scope name — written once, referenced by u32 index. | 1 |
+| `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 |
@@ -430,41 +499,155 @@ is precisely why it is an export and not the storage format.
 
 ### 5.7 String encoding
 
-Use an explicit `STRS` table with u32 indices rather than `EncodingBinaryBuffer`. The latter
-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 chunks are written out of order, compressed independently, or
-skipped by a reader that does not understand them. An index table costs one indirection and is
-robust against all three.
+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
+### 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({
-    graphics,
     level: GPUProfileLevel.WORKLOAD,
-    max_frames: 600,
+    frame_limit: Infinity,                       // default; a number caps it
     note: "hitch on shadow refresh, RTX 3070"
 });
 
-session.start();
-// ... frames run ...
-const bytes = await session.stop();     // ArrayBuffer, ready to save
+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;
 ```
 
-`Renderer` gets `begin_profile(options)` / `end_profile()` wrapping it, so the common case is two
-calls and no wiring. `add_debug_frame` and `onFrameDebug` stay as they are — cheap, synchronous,
-console-shaped, and a different tool for a different question.
+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.
 
 ### 6.2 The five hooks
 
-1. **`FrameGraph.execute`** — bracket `node.execute(...)`. Notify the context which graph pass is
-   open; take CPU timestamps either side; push/pop a debug group. The only edit outside `src/shade/`.
-   Guarded so a graph with no listener does nothing.
+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.
@@ -478,10 +661,14 @@ console-shaped, and a different tool for a different question.
 
 ### 6.3 Cost when off
 
-Every hook is a null check against a field that is `undefined` in normal operation. No allocation and
-no proxy construction; the frame-graph bracket is two comparisons per pass. This must stay true — a
+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
@@ -514,8 +701,8 @@ other engine import.
 | 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. Uncertainty rendering when `timestamp_period_ns` is coarse (§2.1). |
-| **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 default-quantization capture this is the only honest view**, and the inspector should open on it in that case rather than on the timeline. |
+| **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. |
@@ -523,8 +710,9 @@ other engine import.
 
 ### 7.3 What it must refuse to do
 
-- **Never interpolate across the quantum.** If the data is 100 µs-granular, no view draws a 12 µs
-  span. Draw the quantum.
+- **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
@@ -542,41 +730,101 @@ Before any of the below. Instrument one Sponza capture and answer three question
 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_ns` on our dev machines, flag on and flag off? (§2.1)
+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.
 
-### M1 — Timing spine (2–3 days)
+### M0.5 — Workspace restructure — **DONE**
 
-`GPUTimerArray` pooling and bound checks; the `FrameGraph.execute` bracket and debug groups;
-`GPUProfileSession` at level 0; `META`/`STRS`/`FRAM`/`DIRE` chunks; round-trip test on
-`SoftwareGPUDevice`. Deliverable: a `.sgpt` with real spans and no viewer.
+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.
 
-### M2 — Inspector skeleton (2–3 days)
+**`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.
 
-Package scaffold, format readers, drop target, frame strip, timeline, pass detail. Deliverable: a
-capture you can look at.
+<details><summary>Original plan</summary>
 
-### M3 — Structure (2–3 days)
+§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.
 
-`TOPO` chunk with deduplication; resource descriptors; scopes; cull state. Dependency graph and
-resource table in the inspector. Deliverable: the "why is this pass here" question becomes
-answerable.
+</details>
 
-### M4 — Workload (2–3 days)
+### M1 — Timing spine — **DONE**
 
-Proxy encoders; `PIPE` chunk; dispatch/draw counts; derived invocation counts. Deliverable: the "is
-this dispatch the right size" question becomes answerable.
+Landed:
 
-### M5 — Analysis (2–3 days)
+- `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.
 
-Statistics view, frame comparison, counter tracks, Chrome Trace Event export.
+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.
 
-### M6 — Publish (1–2 days)
+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.
 
-Build target, static hosting, a format specification document written for someone outside the
-company, and the sharing story: what a user sends us and what we can read from it.
+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.
+
+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.
@@ -596,30 +844,33 @@ Per the established tiers:
 
 ---
 
-## 10. Risks and open questions
+## 10. Risks
 
 | Risk | Severity | Handling |
 |---|---|---|
-| **Timestamp quantization makes captures useless on default browsers** (§2.1) | **High** | Measure and record the period; make the statistics view the default when it is coarse; document the flag prominently. Accept that shared user captures will mostly be coarse. |
+| **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. |
-
-**Open questions for you:**
-
-1. **Monorepo or not.** `packages/` does not exist and this repo has no workspaces. Options: (a) npm
-   workspaces with `packages/gpu-inspector-tool` as a real workspace — cleanest, touches the root
-   `package.json` and CI; (b) an unreferenced directory with its own `package.json`, built manually —
-   zero risk to the engine build, worse ergonomics. **Recommendation: (a)**, but it is your call
-   whether you want workspaces in this repo at all.
-2. **Does the recorder ship in production builds?** Rollup runs `@rollup/plugin-strip`. Shipping it
-   means users can send us captures, which is the stated goal; it also means the hooks survive
-   stripping and the null-check cost must genuinely be zero.
-3. **How much does the frame-graph bracket in `FrameGraph.execute` bother you?** It is the one edit
-   outside `src/shade/` and outside the profiler's own files. The alternative — inferring attribution
-   from labels — does not work (§1.4).
-4. **Recording length policy.** Ring buffer of the last N frames (good for "capture the hitch that
-   just happened") or explicit start/stop (good for reproducible benchmarks)? Both are cheap; the
-   ring buffer is more useful in the field. **Recommendation: both, ring by default.**
+| **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.