@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/runtime/RUNTIME_PLAN_2026_09_14.md

@@ -0,0 +1,548 @@
+# Virtual Geometry runtime — residency that scales
+
+**2026-09-14, revision 2** after a three-reviewer pass (scaling, correctness, integration; 56
+findings, folded in below — the ones that changed the design are marked *(rev 2)*). Supersedes
+`RUNTIME_PLAN.md` §3.2 (selectability), §3.3 (budgets and eviction), the touch half of §4.5, and
+the whole of `virtual/residency/`. Everything else in that document stands: the slot layout, the
+claim, the cut rule and its proofs, the seam.
+
+## 0. Why
+
+The runtime was written for one asset and it scans instead of indexing. On the largest converted
+Zorah container (`bdf6f961…`, 17,172 pages, 27.96 M source triangles, 920 MB) in
+`playground/vgeo_runtime/` at 4,096 slots, a DevTools trace of zooming in and out shows this:
+
+| | |
+|---|---:|
+| trace length | 5.5 s |
+| main-thread tasks over 16 ms | 24 |
+| longest task | 637 ms |
+| of which `VGeoFeedbackLoop.#apply` | 575 ms |
+| of which `VGeoRuntimeTables.refresh_selectable` | 450 ms |
+| of which `GPUVirtualGeometryPool.#make_room` | 254 ms |
+
+and the panel, zoomed well in, reads *refused 4,166,982 · pages visited 4,044 of 4,096 resident ·
+clamped 1,334 · drawn 11,597* while the surface on screen is visibly the coarse level.
+
+Three defects, each measured on the real asset in node (`scratchpad/measure.mjs`,
+`decode.mjs`, `installpath.mjs` of the diagnosing session):
+
+1. **Selectability is recomputed over the whole geometry on every install and every evict.**
+   4.19 ms per call at 4,096 resident pages (138,115 clusters, 39,450 groups) through a JS `Map`
+   and `Set`. The table is full, so every install evicts first: one promotion is two calls,
+   8.4 ms. The loop promotes up to 8 MB a frame, 136 pages of this asset, so the bound is over a
+   second of CPU in one frame. The 637 ms task is about 68 promotions.
+2. **Eviction is a scan.** `#coldest` walks the touched map once per install; a refused install
+   costs the full walk, 0.55 ms at 4,096 rows, and `#apply` keeps asking for every RAM-resident
+   want after the first refusal even though nothing can change until the next readback. Refusals
+   alone were 850 ms of the 5.5 s. `VGeoResidencyManager.evict_to_budget` is the same defect in the
+   RAM tier: `#candidates()` builds and sorts an array of every resident page of every reader,
+   every time the budget binds. And `GPUMeshletManager.remove_batch` is `indexOf` + `splice` over
+   every batch record in the manager, so each eviction also pays a scan of every resident page and
+   every static batch *(rev 2)*.
+3. **The cut poisons its own LRU.** `vg_claim_page` stamps a child page the moment a parent
+   cluster refines into it; the frustum test runs afterwards on the child's *nodes*. Clusters are
+   never frustum-tested and projected error is a function of distance alone, so zoomed in on a
+   wall every cluster of the wall at that level refines whether it is on screen or not, and
+   claims — touches — its child page. 4,044 of 4,096 rows touched per frame; 3,081 of them hold a
+   resident child and are structurally unevictable; the rest are inside the protect window;
+   `#coldest` answers −1; the 858 pages in RAM and not in VRAM never get in. `drawn` is counted at
+   `vg_draw`, before `filter meshlets 2 way`, which is why 11,597 clusters do not look like 1.4 M
+   triangles: most are culled downstream.
+
+And a fourth, not in the trace because the trace was mostly refusals, that bounds what any fix can
+reach: **frame verification costs 1.0 ms per page.** Install path measured at 1.098 ms/page with
+`verify_frames` on and 0.134 ms/page with it off; decode alone is 0.079 ms. The identity-seeded
+xxh3 over a 56 KB frame runs at ~58 MB/s in JS. The playground turns verification on, and a
+runtime should: a checksum is the one defence against a range that came back wrong. So the
+per-page main-thread cost is the checksum, not the decode, and that is what the worker is for.
+
+**The bar.** Nothing on the CPU may scale with what is resident, and nothing per frame may scale
+with what was seen. Per-frame work is proportional to the readback the host chose to read, to the
+pages that moved, and to stated per-reading budgets. That has to hold at 50,000 pages in RAM (3 GB
+at this asset's 60 KB decoded per page) and 65,536 slots in VRAM, across every registered
+geometry, with the same code.
+
+Two things the bar does *not* cover, and which this document leaves where they are (§8): the
+claim table, which is instances × slots in bits per expansion site and refuses instances past
+`visible_instance_hint` rather than slowing down; and the lookup, whose word count is a
+host-sized cap on pages across every registered geometry.
+
+## 1. What the CPU does in a frame, and the order of each step
+
+| step | work | order |
+|---|---|---:|
+| read back | header + touch bits + `want_capacity` records | O(capacity/32 + want_capacity) bytes |
+| touches | fold the bit vector into `last_used[row]`, checking each set bit's row identity (§2.4) | O(capacity/32) word loads + O(rows touched) |
+| wants | partial select of the top records by priority out of at most `want_capacity` | O(want_capacity) |
+| promote | up to `max_promotions_per_reading` pages from RAM: a slot write, a meshlet batch, the incremental cascade | O(promotions · clusters per page + cascade) |
+| fetch | up to `max_fetches_per_reading` pages, each admitted against the RAM budget first, handed to the fetcher | O(fetches) |
+| VRAM room | CLOCK hand over rows, under `max_eviction_tests_per_reading` | O(budget) |
+| RAM room | CLOCK hand over RAM slots, under the same kind of budget | O(budget) |
+| upload | the dirty ranges of the pages that moved | O(pages moved) |
+| fetch/verify/decode | off the main thread | 0 on the main thread |
+
+Nothing in the table is a Map of objects, nothing is a closure over the resident set, and every
+row that is not proportional to the readback is proportional to a number in
+`VGeoResidencyOptions`.
+
+## 2. The cut
+
+### 2.1 Frustum-test the cluster before it refines
+
+`vg_visit_group` gains one test at the top of the per-cluster loop, under the same
+`VGEO_CUT_FLAG_CULL` bit the node test uses: a cluster whose `SELF_SPHERE` is outside the frustum
+is skipped — not drawn, not clamped, not refined, and above all not claiming its child page — and
+counted in a new `VGEO_CUT_STAT.CULLED_CLUSTER` *(rev 2)*, beside the node counter.
+
+`SELF_SPHERE` is the right sphere and no new row data is needed. FORMAT §7: `parent_sphere ⊇
+self_sphere`, the node sphere is the union of the `parent_sphere`s under it, and RUNTIME_PLAN §4.4's
+containment argument for the node test is built from exactly that. The tight `bounds_sphere`
+exists in the format and is *not* in the row; if the looseness of the LOD sphere shows up as visited
+pages it can be added later at four words per cluster row.
+
+**Why this keeps §4.4's proofs** *(rev 2)*. Every parent cluster of one group was created by the
+same step and shares one `self_sphere` (FORMAT §7, "shared per group step"), so the per-cluster
+frustum decision is uniform across all of a group's parents, across pages. Either every parent of
+a group refines into it or none does; a culled parent is not drawn, and it would not have been
+drawn anyway (it fails `project(self) ≤ τ`). Culling removes visits and nothing else, the claim
+is untouched, and "no cluster is drawn twice" holds unchanged.
+
+The claim stays RUNTIME_PLAN §4.4's, at cluster granularity: turning culling on removes only
+clusters whose `self_sphere` is outside the frustum, and never one inside it. The agreement spec's
+existing test (`frustum culling removes only what is outside the frustum`) checks exactly that
+against the records. The assertion it gains is **no page other than the root is claimed unless
+some cluster refining into it has a `self_sphere` intersecting the frustum** *(rev 2)* — not "no
+page whose every cluster is outside", which the kernel cannot promise: the claim is taken at the
+parent, before the child's rows are seen, and a parent sphere can straddle a plane with every
+child sphere on the far side of it. The seed claims and touches the root unconditionally.
+
+The qualifier §4.4 wrote for the node test applies unchanged: a culled cluster's subtree is a hole
+inside geometry the frustum rejected, and the parent that would stand in is not drawn either.
+That is the deal the node test already makes.
+
+### 2.2 A touch is one bit
+
+The touch list, its capacity and `TOUCH_COUNT` go. `vg_claim_page` and the seed do one
+`atomicOr` into a bit vector of `page_row_capacity` bits at the head of the feedback buffer; the
+per-row stamp words they used to `atomicExchange` on go with the list. Seed touches iff it
+claimed; traverse touches iff the claim was won; no path touches without claiming or claims
+without touching, so one bit per row is a faithful replacement.
+
+What this buys: the readback of touches is `capacity / 8` bytes rather than up to 32 KB of list,
+and it cannot overflow — with the list, a frame that touched more than 8,192 rows took the stamp
+and lost the list entry, and the LRU treated pages on screen as cold.
+
+### 2.3 The readback reads the lists, and the want stamps stop being a transient
+
+The frame's feedback transient becomes **header, touch bits, want records** and nothing else, so
+`graph_read_buffer` reads the whole of it. At 4,096 slots and 2,048 wants that is 33 KB a frame;
+today's layout is 344 KB, of which 256 KB are the want stamps — one word per lookup word, one per
+page of every registered geometry — which the CPU never looks at.
+
+The want stamps move out of the transient into a **persistent pool buffer** the size of the lookup
+*(rev 2)*, and become frame-tagged: `vg_want` dedups with `atomicExchange(stamp, tag) != tag`
+where `tag` is the runtime's frame number plus one, carried in the params. No per-frame clear:
+the transient was `BufferResourceDescriptor.empty`, which is a clear over its full size every
+frame, and a lookup-sized clear per frame is the one term in the old layout that scaled with
+every registered geometry rather than with what was seen. The traverse binds one more storage
+buffer, nine against the engine's floor of ten.
+
+The want record is unchanged: `(source_row, child_ref, child_page_index, priority)`. The source
+page is guaranteed to be in RAM when the want is serviced, which is §4.3 below, so the byte range
+still comes out of its child table and no directory is needed.
+
+`unregister` marks the geometry's own lookup range dirty, not the whole lookup *(rev 2)*.
+
+### 2.4 Identity without a snapshot
+
+`#snapshot_generations` copies one word per row per readback. It goes. The pool records
+`visible_from[row]` *(rev 2)*: the frame number of the flush that will publish the row's current
+occupant. The pool's frame counter advances in `begin_frame` **before** the flush; an install
+stamps `visible_from = frame + 1`; an evict stamps `0xFFFFFFFF`. A record from the cut of frame
+`F` naming row `r` is valid iff `visible_from[r] <= F`. That is exact at every interleaving the
+frame permits: an install landing after `begin_frame(F)`'s flush — a readback applied mid-frame, a
+host registering a container inside its frame — is stamped `F + 1` and rejected by `F`'s reading;
+one landing before it is stamped `F` and accepted; a freed row is rejected by every reading. Same
+question as comparing generations, O(1) per record, and the touch fold applies it per set bit.
+`generation_of` stays as the row's identity for anything else that needs it.
+
+### 2.5 Nothing else moves
+
+The claim, the queue, the wavefront, the seed's instance handling, the collect pass and the
+expansion seam are untouched. The arena stays read-only in every cut pass; the cut writes into the
+frame's feedback transient and the want-stamp buffer and nowhere else.
+
+## 3. Selectability is maintained, not recomputed
+
+Design §6's rule, unchanged: a group is selectable iff every one of its parent-cluster references
+is live — the referencing cluster's page resident *in this tier* and that cluster's own group
+selectable. §6 also says how: "carried by a counter instead of dependency lists … activation
+cascades". `VGeoContainerReader` does exactly that for the RAM tier already (`#activate_page`,
+`#cascade_activate`, `#pending_refs`). The VRAM tier will do the same, over the arena.
+
+**State.** The live-reference count lives in the group row's `FLAGS` word, bits 16–31; bit 0 is
+the selectable flag the kernels read and mask, as now. `PARENT_COUNT` is a u16 in the format, so
+the count fits exactly. The count is uploaded with the row whenever the row is dirty, and the
+kernels never read it — so a count change **does not mark the row dirty**; only a flip of bit 0
+does *(rev 2)*. No parallel array, nothing per group on the CPU that is not already in the shadow.
+
+**Reverse index.** Per geometry, `referrers: Map<page_index, page_index[]>` — for each page
+index, the RAM-resident pages whose clusters reference it *(rev 2: RAM-resident pages, not VRAM
+rows, so one index serves both tiers; VRAM ⊆ RAM)*. Written when a page enters RAM from its own
+`child_page_index` list, removed when it leaves RAM. Entries are short in practice (parents per
+page is single digits on the assets measured; `group_parent_count` is a u16, so a page holding a
+popular group can legally have more, and the cost below is linear in it). A lookup is O(1) and a
+page's entry is O(parents). This is the structure design §6 calls "the reverse-reference index
+for not-yet-installed pages", kept for resident ones too.
+
+**Install `C` into VRAM.** Seed every group of `C` with the count of VRAM-resident parent clusters
+that reference it *and whose own group is selectable*: for each parent page `P` in `referrers[C]`
+whose state is `VRAM`, walk `P`'s cluster rows and count those with `CHILD_PAGE_INDEX == C` by
+child group. Same-page parents are not seeded; they arrive through the cascade (`SAME_PAGE` is in
+no child table and the row carries the page's own index). Then Kahn: every group whose count
+equals `PARENT_COUNT` (a root-level group's is 0) becomes selectable; for each of its clusters
+whose child page is resident and whose `CHILD_GROUP` is inside the child page's group table — the
+out-of-range guard `refresh_selectable` has today survives, because the count lives in the arena
+and an unguarded increment would land in a cluster row *(rev 2)* — increment the child group's
+count; a count that reaches its `PARENT_COUNT` is pushed. Cost is O(parents of `C` × clusters per
+parent page) for the seed, plus the cascade. The cascade in one call is bounded by the resident
+subtree under `C` that was waiting on `C` — small when pages install parent-first, and in every
+case each group flips on once per residency, so the total over a page's lifetime is O(its
+groups) *(rev 2)*.
+
+**Evict `C` from VRAM.** Only a page with no VRAM-resident child page is evictable (the rule
+below, unchanged), so no resident group depends on any group of `C`: nothing to decrement, nothing
+to cascade. Drop the rows. `unregister` evicts everything of a geometry and skips the bookkeeping
+entirely.
+
+**Resident-child counts** *(rev 2)*. `resident_children` per VRAM row and per RAM slot replaces
+the cluster walk `has_resident_child` does today. At install of `C` into a tier: for each parent
+`P` in `referrers[C]` resident in that tier, `resident_children[P]++`; **and** `C`'s own count is
+seeded from its child list, counting the children already resident in that tier — a parent that
+arrives after its child (ordinary: a page is fetched through one parent while another parent page
+is absent) would otherwise sit at zero, be evicted, and leave its child selectable with a parent
+absent, which is C1 again. At evict, decrement each resident parent.
+
+**On malformed counts.** A `PARENT_COUNT` larger than the references present is never reached and
+the group never activates, as today. A count *smaller* than the references present flips the
+group on when it is reached and leaves it on past it, as `refresh_selectable` does today; the
+fixpoint oracle says *not selectable* for an over-counted group. That divergence exists now and
+is preserved; the random-sequence spec runs on validator-accepted containers.
+
+**Why not a per-frame vote in the traversal.** Considered and rejected: a group's parents refine
+per *instance*, so a vote counter is per (instance, group), and that is instances × resident per
+frame — the same product with the axes renamed. Selectability is instance-free, which is exactly
+why it belongs in the row.
+
+**Proof.** `refresh_selectable` does not survive as code. Its rule does, in the agreement spec's
+`selectable_over` fixpoint oracle: a new `VGeoRuntimeTables.spec.js` drives random install/evict
+sequences under the child rule, child-before-parent orders included, against the oracle after
+every step, and the agreement spec's `vram_withheld` cases keep running against the incremental
+flags. C1's regression stays pinned by the same oracle. `set_group_selectable` **stays** *(rev
+2)*: the agreement spec constructs the own-group-term state with it (P6, RUNTIME_PLAN §4.4's
+"single most important line"), and its doc already says it is a spec verb the next cascade
+overwrites; it writes bit 0 and leaves the count.
+
+## 4. One residency, two tiers, flat
+
+`VGeoResidencyManager` and the policy half of `GPUVirtualGeometryPool` (`#owner`, `#touched`,
+`#pinned`, `#make_room`, `#coldest`, `evictable`, `touch`, `install`'s room-making,
+`register`'s root install) are replaced by one class, `VGeoResidency`, in `runtime/`. The pool
+keeps the mechanics: tables, buffers, meshlet batches, dirty ranges, the frame counter and
+`visible_from`, `register_geometry(reader)` / `unregister_geometry` for the row and the lookup,
+and `install(reader, page)` / `evict(row)` as verbs that do one slot each and decide nothing —
+`install` throws or returns −1 when there is no slot, and the caller made room or did not. The
+reader keeps decode, its page map, and quarantine.
+
+`GPUSceneContext.enable_virtual_geometry` constructs the pool, the runtime, **and the residency and
+the feedback loop** *(rev 2)*, from an options object with a `residency` key rather than one
+spread; the playground stops building any of them and wires only the two frame extensions. That
+closes REVIEW_LEDGER U1: an engine host gets the loop by enabling virtual geometry.
+
+### 4.1 State
+
+Per geometry, beside the lookup and the same length: `state: Uint32Array(total_pages)`. Values:
+`ABSENT`, `FETCHING`, `QUARANTINED`, `RAM | slot`, `VRAM | row` — a tag in the top bits, an index
+below. One word per page of every registered geometry, which is the size the lookup already is.
+(The lookup itself stays GPU-shaped: row or `VGEO_PAGE_ROW_NONE`, nothing else, because the
+kernels read it.)
+
+VRAM rows, struct-of-arrays sized to `page_capacity`:
+
+| array | what |
+|---|---|
+| `last_used` | frame of the last touch bit; **initialised to the install frame** *(rev 2)*, so a page promoted in this reading is inside the protect window and not this reading's next victim |
+| `visible_from` | §2.4, owned by the pool |
+| `resident_children` | count of VRAM-resident child pages (§3) |
+| `pinned` | root pages, one bit |
+| `bytes` | `DECODED_SIZE` mirror, so eviction refunds without reading the slot |
+
+RAM slots, struct-of-arrays sized to `ram_slot_capacity`:
+
+| array | what |
+|---|---|
+| `page` | the decoded `VGeoPage` (an object array; the one non-numeric column) |
+| `geometry`, `page_index` | the key, for the CLOCK hand to find `state` |
+| `last_in_vram` | the frame the page last left VRAM, or entered RAM |
+| `bytes` | decoded size |
+
+*(As built: no RAM-side `resident_children` and no second reverse index. The RAM hand checks a
+candidate's own child list against the state words, O(children) per test, under the same test
+budget — cheaper than an index kept on every install, and bounded by the same number.)*
+
+Two `Map`s in the whole thing — `referrers` per geometry, and readers by geometry row — and
+neither is walked per frame.
+
+### 4.2 Touches and last-use
+
+The cut cannot touch a page it cannot see, so a page in RAM and not in VRAM has no touches; its
+last use is the frame it left VRAM, written once at eviction, and it is protected by the same
+window from that frame *(rev 2)*. The RAM tier's LRU therefore costs nothing per frame. The VRAM
+tier's costs the fold of the bit vector. The clock both tiers read is the pool's frame, advanced in
+`begin_frame` whether or not a readback is scheduled that frame — which is M12's requirement, and
+it is met by the runtime rather than by the loop.
+
+### 4.3 Invariants, and who keeps them
+
+- **VRAM ⊆ RAM.** The RAM CLOCK skips any slot whose `state` is `VRAM`. Today nothing enforces
+  this; the RAM tier can drop a page the cut is drawing from, after which the want that names it
+  as a source cannot be resolved and is silently skipped. With the invariant, a want's source page
+  is in RAM whenever the record is valid. The reader's public `evict`/`evict_all` stay for tools
+  and the viewer; a reader registered with a residency is the residency's, and driving its page
+  map from outside is documented as unsupported rather than reconciled per frame *(rev 2)*.
+- **Parents before children, in each tier.** A row or slot with `resident_children > 0` is not
+  evictable.
+- **The root is pinned** in both tiers; only `unregister` drops it (the reader's `evict_all`
+  keeps page 0 already).
+- **Protect window.** A row is evictable only if `frame − max(last_used, install frame) ≥
+  protect_frames`; a RAM slot only if `frame − last_in_vram ≥ protect_frames`.
+
+### 4.4 Eviction is CLOCK, under a budget
+
+Both tiers evict with a hand over their flat arrays: advance, test evictable (pinned, protect
+window, children, byte or slot need), evict or skip. The hand persists across readings.
+
+**The bound is a test budget, not a lap** *(rev 2)*. Under the child rule a cold leaf's eviction
+makes its parent evictable, and the parent's row is behind the hand, so "one lap" is really one lap
+per DAG level while the tier is full — and a lap is O(capacity), which the bar forbids per
+reading. So a reading may run at most `max_eviction_tests_per_reading` tests of the hand across
+both tiers; when the budget is spent the tier reports **nothing may go for this reading** and every
+further promotion or admission in that reading is refused and counted. The hand carries on from
+where it stopped next reading. A full tier therefore turns over at a rate the host chose, in
+tests per reading, and never at a rate the resident count chose.
+
+Not exact LRU, deliberately. The protect window already coarsens the order to "not recently", and
+an exact order under 50,000 pages costs an update per touch per frame — the thing this document
+exists to not do. `VTPhysicalCache` picks by linear scan at ≤ 1k slots; this is the same policy
+made amortized so it holds at 65k.
+
+### 4.5 Servicing wants
+
+Per reading: partial-select the top records by priority out of at most `want_capacity`, and walk
+them in order until both per-reading budgets are spent. For each record, in this order *(rev 2)*:
+
+1. **stale** — `visible_from[source_row] > F`: drop.
+2. **already in VRAM** — the promotion happened one or two readings ago and the cut that emitted
+   this had not seen it: drop. (Any other order would mark a VRAM page `FETCHING`, fetch it, and on
+   arrival set it `RAM`, which the RAM CLOCK could then evict from under the cut.)
+3. **`FETCHING` or `QUARANTINED`**: drop. `FETCHING` is the cross-frame dedup — the GPU keeps
+   emitting the want while the page is missing, and the CPU drops it in O(1). `QUARANTINED` is what
+   stops a page that will not arrive from being fetched every reading; the reader's
+   `clear_quarantine` resets it to `ABSENT`.
+4. **`RAM`** — promote, under `max_promotions_per_reading` and the VRAM budgets, making room by
+   §4.4.
+5. **`ABSENT`** — admit against the RAM byte budget **before** the fetch, out of the record's
+   `decoded_size` and making room by §4.4 (FORMAT §10, and what `VGeoResidencyManager.#admit`
+   does today); if admitted and under `max_fetches_per_reading` and the fetch gate has room, mark
+   `FETCHING` and hand `(geometry, page_index, frame_offset, fetch_size, decoded_size, priority)`
+   to the fetcher; otherwise count and drop, and the next cut asks again.
+
+Promotions and fetches have separate budgets so that a tier full of RAM-resident pages waiting to
+be promoted is not starved by fetches or the reverse. Both are in **pages**, because each is a
+cascade and a slot write and pages are near-uniform; `install_budget_bytes` goes.
+
+The sort is not on the GPU. `want_capacity` bounds the list at 2,048 records, a partial select
+over that is microseconds, and a `graph_radix_sort` over the capacity is twelve dispatches to
+shave 28 KB off a readback. If `want_capacity` ever needs to grow past what a select can absorb,
+the sort is the swap and the record shape already suits it: the priority is a positive float, so
+its bit pattern is the key.
+
+### 4.6 Fetch, verify and decode off the main thread
+
+Two classes *(rev 2)*:
+
+- **`VGeoPageFetcherCore`** — pure logic over a byte source: read the range, retry with backoff
+  on the reader's `fetch_retries` / `fetch_retry_backoff_ms`, verify the frame against the asset
+  id, run `vgeo_read_page`, and answer either a page or a quarantine reason. It runs anywhere: in a
+  worker, or in-process. This is where the reader's `#fetch_page` / `#read_page` logic moves; the
+  reader's own `install` keeps calling it in-process, so tools and the viewer are unchanged.
+- **`VGeoPageFetcher`** — a pool of **module workers**, spawned the way `makeClothWorker` does
+  (`new Worker(new URL('./vgeo_page.worker.js', import.meta.url), { type: 'module' })`, the form
+  the consumer's bundler detects), each running the core. `WorkerProxy` is not the shape: it spawns
+  classic workers from rollup bundles and posts without a transfer list. A `loopback` mode runs the
+  core in-process on the main thread's byte source, for specs (vitest's environment is `node` and
+  has no `Worker`) and for hosts that opt out.
+
+A byte source has to be reconstructed inside a worker, per form: a URL source is rebuilt from
+`{url, byte_length, init}` (one `HEAD` saved by passing the length); a `Blob`/`File` is posted
+once per worker; an in-memory buffer is posted once per worker (a copy; a `SharedArrayBuffer`
+would need COOP/COEP headers the dev server does not set). The reader's head prefix is not
+consulted by a worker, so a page inside the head is re-fetched once — accepted, it is a few pages
+per asset.
+
+A page comes back as a plain object with ~30 typed arrays; `VGeoPage.transferable()` and
+`VGeoPage.from_transfer()` carry it across with every buffer in the transfer list and restore the
+class. The reader gains two verbs: `adopt(page)` — the success path, which puts a page decoded
+elsewhere into its map — and `quarantine(page_index, reason)` — the failure path — so that
+quarantine still lives in one place. A reply carries the request id, and a reply for a geometry
+that was unregistered while it was in flight is dropped (geometry rows are recycled; the request
+id is what tells two containers in one row apart).
+
+The reader's own activation bookkeeping (`#activate_page`, `#pending_refs`, `is_selectable`) is
+the RAM tier's answer to a question the runtime answers in the arena, and at 50,000 pages it is
+tens of megabytes of nested Maps nobody reads. `VGeoReadOptions.track_selectability` *(rev 2)*
+defaults to `true`; a residency opens its readers with it `false`, `adopt` then skips the cascade,
+and `is_selectable` throws. The viewer keeps the default.
+
+`ConcurrencyGate` stays as the cap across every geometry, in front of the workers; the residency
+dispatches only while the gate has room, so the `FETCHING` population is bounded by the gate
+plus one reading's `max_fetches_per_reading`. Failure is reported once per reading: if every fetch
+a reading dispatched for one reader was quarantined, one line names the reader — the same fact
+`failed_batch_count` reported per batch.
+
+**The number that says this is required and not nice-to-have:** at 1.0 ms per verified page on
+the main thread, 32 fetched pages a frame is 32 ms. Off the main thread it is the residency cost of
+32 arrivals, which is the cascade — tens of microseconds each.
+
+### 4.7 What the feedback loop becomes
+
+`VGeoFeedbackLoop` keeps `read(graph)` — schedule the readback with the layout and frame closed
+over, cap in flight, count skipped frames — and its `#apply` becomes one call into
+`VGeoResidency.apply(words, layout, frame)`. The class stops owning fetch state, in-flight sets,
+controllers, or budgets. `VGeoResidencyOptions` moves to `runtime/` and becomes the one place
+every knob lives: `vram_budget_bytes`, `ram_budget_bytes`, `ram_slot_capacity`, `protect_frames`,
+`max_promotions_per_reading`, `max_fetches_per_reading`, `max_eviction_tests_per_reading`,
+`max_concurrent_fetches`, `worker_count`, `max_readbacks_in_flight`.
+
+`VGeoResidency.register(reader)` registers the geometry with the pool, installs the root through
+the ordinary promotion path (making room for it, or throwing the same error `pool.register`
+throws today), and pins it in both tiers.
+
+## 5. What dies
+
+| gone | replaced by |
+|---|---|
+| `VGeoRuntimeTables.refresh_selectable`, `#live_refs` | the incremental cascade in `install`/`evict` (§3); `set_group_selectable` stays as a spec verb |
+| `VGeoRuntimeTables.has_resident_child` | `resident_children[row]` |
+| pool `#owner`, `#touched`, `#pinned`, `#make_room`, `#coldest`, `evictable`, `touch`, `entry_of`, `budget_bytes`, `protect_window` | `VGeoResidency` |
+| `VGeoResidencyManager`, `VGeoResidencyEntry`, `residency/` | `VGeoResidency`, `runtime/` |
+| touch list, `touch_capacity`, `TOUCH_COUNT`, touch stamps | the touch bit vector |
+| want stamps in the transient | the pool's frame-tagged stamp buffer |
+| `#snapshot_generations`, `#still_the_same_page` | `visible_from[row]` |
+| `install_budget_bytes` | `max_promotions_per_reading` |
+| `#in_flight_pages`, `#controllers`, `#dispatch_frame`, `#dispatch_wants` in the loop | `state == FETCHING`, `VGeoPageFetcher` |
+| `GPUMeshletManager.remove_batch`'s `indexOf` | a record → position index *(rev 2)* |
+| the reader's `#fetch_page` / `#read_page` bodies | `VGeoPageFetcherCore`, which the reader calls in-process |
+
+## 6. Order, and what each step leaves green
+
+Each step is one commit, pinned by a spec that was red before it, and the suite is green after it.
+The headless drive on the Zorah asset runs after 1, 3 and 5.
+
+| step | change | goes red first |
+|---|---|---|
+| 0 | `GPUMeshletManager.remove_batch` in O(1): a `Map` from record to position, or a swap-remove with the moved record's position updated *(rev 2)* | `GPUMeshletManager.spec.js`: removing one of 10,000 batches does not scale with the count (bounded by a measured ratio, interleaved as `paired-measurement-on-a-busy-machine` records) |
+| 1 | §2: cluster frustum test + `CULLED_CLUSTER`; touch bits; transient = header + bits + wants; persistent frame-tagged want stamps; `visible_from` in the pool with the frame advanced in `begin_frame`; `read` reads the whole (smaller) transient | `vgeo_cut_agreement.spec.js`: the §2.1 assertion, and the seed/two-instance tests read bits instead of a list; `VGeoFeedbackLoop.spec.js`: a frame touching more rows than the old list held stamps every one of them; a readback's byte size has no stamp region in it; a record naming a row re-used since the cut is dropped, by `visible_from`, including a row re-used inside the reading's own frame; C5's layout test on a fixture crossing a 32-row boundary (the ten-page torus cannot move `want_base`; use the 160×80 one) |
+| 2 | §3: incremental selectability and `resident_children` in the tables; `refresh_selectable` and `has_resident_child` deleted | new `VGeoRuntimeTables.spec.js`: 200 random install/evict steps under the child rule, child-before-parent orders included, agree with `selectable_over` after each; a parent installed after its child counts it; an out-of-range `CHILD_GROUP` is skipped; the agreement spec's withheld cases unchanged |
+| 3 | §4.1–4.5, 4.7: `VGeoResidency`; pool loses policy; loop becomes `read` + one call; scene context constructs residency and loop; `residency/` deleted | new `VGeoResidency.spec.js` — see the migration table below |
+| 4 | §4.6: `VGeoPageFetcherCore`, `VGeoPageFetcher`, `adopt`, `quarantine`, `track_selectability` | `VGeoPageFetcherCore.spec.js` in-process over an in-memory source: a page arrives decoded and verified; a bad checksum retries then quarantines once; abort abandons what is in flight; a reply for an unregistered geometry is dropped. The real worker is exercised at tier 4 only |
+| 5 | proof (§7) | the numbers below, recorded in `playground/vgeo_runtime/README.md` |
+
+Steps 0, 1 and 2 are independent of each other and of 3. Step 4 is independent of 2 but is
+measured only with 3 in place.
+
+### 6.1 Where every existing pin goes *(rev 2)*
+
+| today | pins | after |
+|---|---|---|
+| pool spec: `a page with a resident VRAM child may not go`, `a page with a VRAM child stays put after the RAM tier forgets it` | M9 | `VGeoResidency.spec.js`: same two, through `resident_children`, the second still calling `reader.evict` underneath |
+| pool spec: `a budget too small … evicts the coldest and keeps drawing`, `a full slot table evicts …` | M17 | `VGeoResidency.spec.js`: promotion under a small byte budget and under a full table both make room by the CLOCK and keep the root |
+| pool spec: `the bytes an eviction refunds …` | C4 | `VGeoResidency.spec.js`, through the `bytes` column, with `reader.evict` underneath |
+| pool spec: `a page row is reused, and its generation says so` | M10 half | stays in the pool spec (`generation_of` stays) |
+| pool spec: `a root page that cannot be made resident is a refusal …` | C7 host half | `VGeoResidency.spec.js`: `register` throws and rolls back when the root cannot be made resident |
+| loop spec: `a touch moves both tiers' clocks` | design §6 | `VGeoResidency.spec.js`: a touch bit moves `last_used`; a VRAM eviction writes `last_in_vram` |
+| loop spec: `the RAM tier's clock runs without the host winding it` | M12 | `VGeoResidency.spec.js`: the protect window is measured against the pool frame, which advances with `begin_frame` and not with readbacks |
+| loop spec: `a readback landing after the layout moved …` | C5 | loop spec, on the larger fixture |
+| loop spec: `a record naming a row that was re-used since the cut is dropped` | M10 | loop spec, by `visible_from`, at step 1 |
+| loop spec: `a page still being fetched is not asked for again every frame` | M11 dedup | `VGeoResidency.spec.js`: `FETCHING` drops the record |
+| loop spec: `a frame asks for no more pages than its limit …`, `the frame limit is one budget across every reader` | M11 limit | `VGeoResidency.spec.js`: `max_fetches_per_reading` across two readers |
+| loop spec: `aborting the loop abandons what it started …` | M11 abort | `VGeoPageFetcherCore.spec.js` |
+| loop spec: `a reader that cannot answer is reported once per batch …` | M11 report | `VGeoResidency.spec.js`: once per reading |
+| loop spec: `a want for a page already in RAM is a VRAM promotion, not a fetch` | | `VGeoResidency.spec.js` |
+| loop spec: `a saturated loop skips a frame …`, `a frame that was never opened …`, `the params a frame publishes …`, `a rasterization path on another graph …`, `the claim bitmask is sized …`, `a readback carries the counters …` | | loop spec, unchanged in substance |
+| residency spec: `refuses a want it cannot make room for, and does not pay for it`, `makes room by evicting, then admits`, `stays inside the budget over a long tour`, `two wants for one page are one fetch and one charge`, `never drops the root page`, `drops nothing while a page has resident children`, `protects a page for as many frames as the feedback takes`, `drops the coldest touch first`, `says so rather than looping when nothing may be dropped`, `bounds the total, which no reader can`, `cost their own page and nothing else`, `are not asked for again until a caller with better information says so` | RAM tier | `VGeoResidency.spec.js`, each as a RAM-tier case; "coldest first" becomes "a colder slot goes before a hotter one the hand reaches later", which is what CLOCK promises |
+| residency spec: `a reader that installed behind the manager's back is reconciled once a frame` | | dropped with a stated reason (§4.3: a registered reader is the residency's) |
+| agreement spec: everything | C1, M1–M8, P2, P6 | unchanged, `residency_to_tables` loses its `refresh_selectable` call |
+| `graph_vgeo_expand.spec.js` | seam | unchanged; it reads no layout and is not red at any step |
+
+## 7. Proof — measured 2026-09-14, every step landed
+
+In node, on the real asset (`measure2.mjs` / `measure3.mjs` of the building session):
+
+| | before | after |
+|---|---:|---:|
+| one promotion at a full 4,096-slot tier, eviction and activation included | 8.4 ms | 9.8 µs |
+| the same at 65,536 slots with 16,000 pages resident | — | 13.3 µs |
+| one refused promotion | 0.55 ms | 0 after the reading's test budget is spent |
+| readback bytes per frame at 4,096 slots | 344 KB | 33 KB |
+| per-frame GPU clear proportional to the lookup | 256 KB | 0 |
+| frame verification and decode on the main thread | 1.1 ms per page | 0 |
+
+Sixteen times the slots and four times the residency moved the per-operation cost by a third,
+which is the cascade reaching deeper pages and not the tier's size. That is the scaling claim.
+
+In headless Chrome on the same asset through `playground/vgeo_runtime/` at 4,096 slots and
+1258×646, a tour of eight rosettes held five seconds each, twice round, then the rosette of the
+diagnosing screenshot at rest (`tour.mjs`; the table is `tour_out/rows.json`):
+
+| | before (the diagnosing trace) | after |
+|---|---:|---:|
+| main-thread tasks over 50 ms | 24 in 5.5 s, longest 637 ms | 4 in 150 s, longest 115 ms — every one on a meshlet-pool compaction |
+| `refused` over the run | 4,166,982 | 999, while the tier turned over 3,009 pages |
+| `clamped` at rest, zoomed in | 1,334 | 0 |
+| `pages visited` zoomed in, of 4,096 resident | 4,044 | 2,000–3,200 |
+| frame time zoomed in | — | p50 8.3 ms, p95 12.6 ms |
+| fetches on workers | 0 | 4,887 of 4,887 |
+
+The picture at rest, zoomed in, is the fine level (`tour_out/rosette.png`).
+
+**What the tour leaves open, in order.** The four remaining long tasks are
+`GPUMeshletManager.compact()`, fired by a refused allocation with free space behind it — §8's
+deferred item, and now the whole of the hitch. `pages visited` is still half to three quarters of
+the resident set when zoomed in, because `self_sphere` is the LOD sphere and loose (§2.1); the
+tight `bounds_sphere` is four words per cluster row and the next thing to measure. And under a
+vite dev server the first seconds after a container opens stall while four worker module graphs
+are served, which a bundled build does not pay.
+
+## 8. What this does not do
+
+- **No GPU sort of the wants** (§4.5). The list is capped, and a CPU partial select is cheaper
+  than the dispatches.
+- **No GPU-nominated eviction.** A device pass could sort rows by stamp and hand back the coldest
+  `K`, but CLOCK under a test budget needs no readback beyond the bits.
+- **No exact LRU** (§4.4).
+- **No directory read, no byte ranges in the want record.** The parent stays in RAM (§4.3), so
+  its child table stays the source of the range.
+- **No change to the claim table.** It is instances × slots in *bits* per site, cleared per site,
+  and an instance past `visible_instance_hint` is refused by the seed (`INSTANCES_DROPPED`) rather
+  than slowed down — a correctness cliff the host sizes around. Sparse claiming is its own change.
+- **No `lookup_words` growth.** The 65,536-word default is a cap on pages across every registered
+  geometry; `VGeoResidencyOptions` states it so a host sizes it. With the want stamps persistent
+  and frame-tagged (§2.3) nothing per frame scales with it any more; growing it is a new buffer.
+- **No compaction fix in `GPUMeshletManager`.** RUNTIME_PLAN §9 already defers it. Under VG churn
+  a refused allocation with free space behind it triggers a rebuild that relocates every batch and
+  fires `changed` per page, which is O(resident) in one event. The drive reports how often it
+  fires (§7); if it is not zero at rest, VG pages need their own region of the pool, and that is
+  the next document.
+- **No prefetch, no hysteresis, no disk tier.** Design §6's open items stay open.