@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.js

@@ -17,6 +17,10 @@ import { vgeo_runtime_page_block_words } from "./vgeo_runtime_page_block_words.j
 import { vgeo_runtime_page_slot_words } from "./vgeo_runtime_page_slot_words.js";
 import { vgeo_runtime_write_page_block } from "./vgeo_runtime_write_page_block.js";
 
+/**
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
+
 /**
  * What a VRAM-resident page **is**, with no device anywhere near it.
  *
@@ -44,10 +48,10 @@ import { vgeo_runtime_write_page_block } from "./vgeo_runtime_write_page_block.j
  * row of a second table, which saves the traversal a storage binding it does not have to spare
  * (RUNTIME_PLAN §4.9) and makes an install one contiguous range.
  *
- * ## This tier answers its own activation question
+ * ## This tier answers its own activation question, and keeps the answer
  *
- * {@link refresh_selectable} computes selectability from the arena and the lookup — this tier's
- * residency — and consults no reader. It used to publish `VGeoContainerReader.is_selectable`, which
+ * Selectability is computed from the arena and the lookup — this tier's residency — and consults
+ * no reader. It used to publish `VGeoContainerReader.is_selectable`, which
  * is a fact about the **RAM** tier, into the flag the kernel reads while the descent was gated on
  * the **VRAM** lookup. VRAM is a strict subset, so a group could be flagged selectable while a page
  * holding one of its parents had no row here, and the parent's own ancestor then drew a coarse
@@ -55,6 +59,22 @@ import { vgeo_runtime_write_page_block } from "./vgeo_runtime_write_page_block.j
  * the group row carrying its parent count (VGEO_GROUP_ROW_OFFSET.PARENT_COUNT) so that the rule
  * can be evaluated where the residency it is about lives.
  *
+ * And it is **kept, not recomputed**. The rule is design §6's: a group is selectable iff every one
+ * of its parent-cluster references is live — the referencing cluster's page resident here and
+ * that cluster's own group selectable here. `refresh_selectable` used to evaluate that as a
+ * closure over every resident group of the geometry after every install and every evict: 4.2 ms
+ * a call at 4,096 resident pages of a real asset, twice per promotion at a full tier, which is
+ * where a 637 ms frame came from (RUNTIME_PLAN_2026_09_14 §0). §6 also says how it is meant to
+ * be kept — "carried by a counter instead of dependency lists … activation cascades" — and
+ * `VGeoContainerReader` already does that for the RAM tier. This tier does it over the arena:
+ * the live-reference count lives in the group row's FLAGS word above the flag bit, a page's
+ * groups are seeded from the resident parents that reference them when it arrives, and the
+ * groups that reach their count cascade into the resident children that were waiting on them
+ * (§3 of that plan). An install costs the clusters of the page's resident parents plus the
+ * cascade; an eviction under the child rule cascades nothing, because nothing resident depends
+ * on a page with no resident children. The rule itself survives as the fixpoint oracle
+ * `VGeoRuntimeTables.spec.js` holds the counter to after every step of random tours.
+ *
  * **Nothing here decides anything.** What to install, what to evict — all of that is the pool's.
  * What this refuses is only what it cannot represent.
  *
@@ -120,12 +140,39 @@ export class VGeoRuntimeTables {
     #resident_rows = new Set();
 
     /**
-     * Resident page rows per geometry row — what {@link refresh_selectable} runs over, and what an
-     * eviction has to look at to find a page's VRAM children.
+     * Resident page rows per geometry row.
      * @type {Map<number, Set<number>>}
      */
     #geometry_rows = new Map();
 
+    /**
+     * Per geometry row, the reverse index of the DAG over this tier's residency: container page
+     * index to the resident page rows whose clusters refer into that page. Written from a page's
+     * own child table when it installs and removed when it evicts, so an entry is O(parents) and
+     * a lookup is O(1) — design §6's "reverse-reference index", kept for resident pages too. It is
+     * what seeds an arriving page's live counts from the parents already here, and what keeps
+     * {@link resident_children} without a cluster walk per candidate.
+     * @type {Map<number, Map<number, number[]>>}
+     */
+    #referrers = new Map();
+
+    /**
+     * Per page row, how many distinct child pages of it are resident in this tier — design §6's
+     * eviction rule, "no child page resident in this tier", as a number kept at install and evict
+     * rather than a walk of the page's clusters per candidate (REVIEW_LEDGER M9 for why it is this
+     * tier's own answer and not the reader's).
+     * @type {Uint32Array}
+     */
+    #resident_children;
+
+    /**
+     * Page rows whose group flags flipped since {@link take_activated_rows} last emptied it — what
+     * the owner has to upload. Counts move without appearing here: the kernels mask the flag bit
+     * and never read the count, so a count alone is not worth a dirty range.
+     * @type {number[]}
+     */
+    #activated = [];
+
     /**
      * Lookup allocation per geometry row, so an unregistered geometry gives its lookup back.
      * @type {Map<number, Allocation>}
@@ -196,13 +243,6 @@ export class VGeoRuntimeTables {
      */
     #broken_child_refs = 0;
 
-    /**
-     * Scratch for {@link refresh_selectable}: live parent references per resident group, indexed by
-     * the group's word offset in the arena. One map reused across calls rather than one allocated
-     * per call, because activation runs on every install and every eviction.
-     * @type {Map<number, number>}
-     */
-    #live_refs = new Map();
 
     /**
      * @param {Object} [options]
@@ -232,6 +272,7 @@ export class VGeoRuntimeTables {
         this.#lookup = new Uint32Array(lookup_words);
         this.#geometries = new Uint32Array(geometry_capacity * VGEO_GEOMETRY_ROW_WORDS);
         this.#generations = new Uint32Array(page_capacity);
+        this.#resident_children = new Uint32Array(page_capacity);
 
         const words = new Uint32Array(page_capacity * slot_words);
 
@@ -372,6 +413,7 @@ export class VGeoRuntimeTables {
 
         this.#ordinals.set(row, { free: [], high_water: ordinal_capacity });
         this.#geometry_rows.set(row, new Set());
+        this.#referrers.set(row, new Map());
 
         return row;
     }
@@ -399,8 +441,9 @@ export class VGeoRuntimeTables {
         const allocation = this.#geometry_allocations.get(geometry_row);
 
         if (allocation !== undefined) {
+            // absent, not row 0: a freed block is still a block some late reader can name
             this.#lookup.fill(
-                0,
+                VGEO_PAGE_ROW_NONE,
                 allocation.offset,
                 allocation.offset + this.geometry_field(
                     geometry_row, VGEO_GEOMETRY_ROW_OFFSET.PAGE_COUNT
@@ -422,6 +465,7 @@ export class VGeoRuntimeTables {
         ] = VGEO_PAGE_ROW_NONE;
 
         this.#geometry_rows.delete(geometry_row);
+        this.#referrers.delete(geometry_row);
         this.#ordinals.delete(geometry_row);
         this.#free_geometry_rows.push(geometry_row);
 
@@ -487,12 +531,29 @@ export class VGeoRuntimeTables {
             + this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT) * VGEO_GROUP_ROW_WORDS;
     }
 
+    /**
+     * Word offset of a page's parent rows, which is the end of its cluster rows.
+     *
+     * Equal to the end of the block when the page has none, which is every page of a container
+     * written before `format_version` 4: `PARENT_ENTRY_COUNT` is zero and nothing reads past it.
+     *
+     * @param {number} page_row
+     * @returns {number}
+     */
+    parent_base(page_row) {
+        return this.cluster_base(page_row)
+            + this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT) * VGEO_CLUSTER_ROW_WORDS;
+    }
+
     /**
      * Make a decoded page resident: one slot, one lookup word.
      *
-     * The page installs **not selectable** — every group's flag is clear — because a page that
-     * arrives drawing is a page that draws before the ancestors it hangs off have. Activation is
-     * {@link refresh_selectable}.
+     * The page's rows are written with every group's flag clear, and then activated in place: its
+     * groups are seeded with the live references the resident parents make into them, the ones
+     * that reach their parent count flip on, and the flip cascades into whatever resident children
+     * were waiting on this page. A page that arrives drawing would draw before the ancestors it
+     * hangs off have; a page whose arrival completes a group several pages down turns that group
+     * on. Both are this method's, and the rows that flipped are on {@link take_activated_rows}.
      *
      * @param {number} geometry_row
      * @param {VGeoPage} page as `vgeo_read_page` decoded it
@@ -510,8 +571,11 @@ export class VGeoRuntimeTables {
         const group_count = page.group_cluster_first.length;
         const cluster_count = page.cluster_count;
 
-        const words = VGEO_PAGE_ROW_WORDS
-            + vgeo_runtime_page_block_words(node_count, group_count, cluster_count);
+        const parent_entry_count = page.parent_ref.length;
+
+        const words = VGEO_PAGE_ROW_WORDS + vgeo_runtime_page_block_words(
+            node_count, group_count, cluster_count, parent_entry_count
+        );
 
         if (words > this.#slot_words) {
             throw new Error(
@@ -546,6 +610,16 @@ export class VGeoRuntimeTables {
         this.#arena[base + VGEO_PAGE_ROW_OFFSET.ORDINAL] = ordinal;
         this.#arena[base + VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW] = geometry_row;
         this.#arena[base + VGEO_PAGE_ROW_OFFSET.DECODED_SIZE] = page.decoded_size;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.PARENT_ENTRY_COUNT] = parent_entry_count;
+
+        /*
+         The generation this row is at as it takes this occupant. An eviction bumps it, so anything
+         that stores a page row and outlives the frame can tell "still the page I meant" from "that
+         slot was refilled" with one equality against the value it saw. It is mirrored here rather
+         than read from #generations because the kernel cannot reach a private field, and it is a
+         counter rather than a frame number because a row can be refilled twice inside one frame.
+        */
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.GENERATION] = this.#generations[page_row];
 
         this.#resident_rows.add(page_row);
         this.#geometry_rows.get(geometry_row).add(page_row);
@@ -562,6 +636,9 @@ export class VGeoRuntimeTables {
             ] = page_row;
         }
 
+        this.#link(page_row, geometry_row, page, lookup_base);
+        this.#activate(page_row, geometry_row, page, lookup_base);
+
         return page_row;
     }
 
@@ -573,7 +650,8 @@ export class VGeoRuntimeTables {
      */
     slot_words_for(page) {
         return VGEO_PAGE_ROW_WORDS + vgeo_runtime_page_block_words(
-            page.node_count, page.group_cluster_first.length, page.cluster_count
+            page.node_count, page.group_cluster_first.length, page.cluster_count,
+            page.parent_ref.length
         );
     }
 
@@ -614,6 +692,10 @@ export class VGeoRuntimeTables {
 
         this.#give_ordinal(geometry_row, this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.ORDINAL));
 
+        // before the header is zeroed: both read this page's rows
+        this.#deactivate_page(page_row, lookup_base);
+        this.#unlink(page_row, geometry_row, page_index, lookup_base);
+
         const base = page_row * this.#slot_words;
 
         this.#arena.fill(0, base, base + VGEO_PAGE_ROW_WORDS);
@@ -639,80 +721,177 @@ export class VGeoRuntimeTables {
     }
 
     /**
-     * Whether any page resident **in this tier** refines out of this one.
+     * How many distinct child pages of this one are resident in this tier.
      *
-     * Design §6's eviction rule reads "no child page resident in this tier", and this answers it out
-     * of the arena rather than out of the RAM reader's child table — which returned "no children"
-     * the moment the RAM tier dropped the page, orphaning every VRAM-resident child under it
-     * (REVIEW_LEDGER M9).
+     * Design §6's eviction rule reads "no child page resident in this tier", and this answers it
+     * out of a count kept at install and evict rather than a walk of the page's cluster rows per
+     * candidate — and out of this tier's own residency rather than the RAM reader's child table,
+     * which returned "no children" the moment the RAM tier dropped the page (REVIEW_LEDGER M9).
      *
      * @param {number} page_row
-     * @returns {boolean}
+     * @returns {number}
      */
-    has_resident_child(page_row) {
-        const geometry_row = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW);
+    resident_children(page_row) {
+        return this.#resident_children[page_row];
+    }
 
-        const lookup_base = this.geometry_field(
-            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
-        );
+    /**
+     * Page rows whose group flags flipped since this was last called, and empties the list.
+     *
+     * @returns {number[]}
+     */
+    take_activated_rows() {
+        const rows = this.#activated;
+
+        this.#activated = [];
+
+        return rows;
+    }
+
+    /**
+     * Put an arriving page into the reverse index and the child counts.
+     *
+     * Both directions, because a page arrives in either order relative to its parents: a child
+     * fetched through one parent while another parent page is absent, and that parent arriving
+     * later, are both the ordinary streaming path. So the page counts the children of its own that
+     * are already here, and every resident parent that refers into it counts one more.
+     *
+     * @param {number} page_row
+     * @param {number} geometry_row
+     * @param {VGeoPage} page
+     * @param {number} lookup_base
+     */
+    #link(page_row, geometry_row, page, lookup_base) {
+        const referrers = this.#referrers.get(geometry_row);
+
+        // the child table is the distinct list; the cluster rows repeat it once per cluster
+        for (const child of page.child_page_index) {
+            let rows = referrers.get(child);
+
+            if (rows === undefined) {
+                rows = [];
+
+                referrers.set(child, rows);
+            }
+
+            rows.push(page_row);
+
+            if (this.#lookup[lookup_base + child] !== VGEO_PAGE_ROW_NONE) {
+                this.#resident_children[page_row]++;
+            }
+        }
+
+        const parents = referrers.get(page.index);
 
+        if (parents !== undefined) {
+            for (const parent_row of parents) {
+                this.#resident_children[parent_row]++;
+            }
+        }
+    }
+
+    /**
+     * Take a leaving page out of the reverse index and the child counts.
+     *
+     * @param {number} page_row
+     * @param {number} geometry_row
+     * @param {number} page_index
+     * @param {number} lookup_base
+     */
+    #unlink(page_row, geometry_row, page_index, lookup_base) {
+        const referrers = this.#referrers.get(geometry_row);
+
+        // out of every child's list of parents; the rows repeat a child once per cluster, and the
+        // list holds this row once, so only the first cluster naming a child finds anything
         const cluster_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT);
         const cluster_base = this.cluster_base(page_row);
 
         for (let cluster = 0; cluster < cluster_count; cluster++) {
-            const child_page_index = this.#arena[
+            const child = this.#arena[
                 cluster_base + cluster * VGEO_CLUSTER_ROW_WORDS
                     + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX
             ];
 
-            if (child_page_index === VGEO_NO_CHILD_PAGE) {
+            if (child === VGEO_NO_CHILD_PAGE || child === page_index) {
                 continue;
             }
 
-            const child_row = this.#lookup[lookup_base + child_page_index];
+            const rows = referrers.get(child);
 
-            if (child_row !== VGEO_PAGE_ROW_NONE && child_row !== page_row) {
-                return true;
+            if (rows === undefined) {
+                continue;
+            }
+
+            const at = rows.indexOf(page_row);
+
+            if (at !== -1) {
+                rows.splice(at, 1);
+
+                if (rows.length === 0) {
+                    referrers.delete(child);
+                }
+            }
+        }
+
+        const parents = referrers.get(page_index);
+
+        if (parents !== undefined) {
+            for (const parent_row of parents) {
+                this.#resident_children[parent_row]--;
             }
         }
 
-        return false;
+        this.#resident_children[page_row] = 0;
+    }
+
+    /**
+     * @param {number} group_row word offset of a group row
+     * @returns {number} live parent references counted so far
+     */
+    #live_count(group_row) {
+        return this.#arena[group_row + VGEO_GROUP_ROW_OFFSET.FLAGS] >>> 16;
     }
 
     /**
-     * Recompute one geometry's group selectability over **this tier's** residency.
+     * One more live reference into a group. Above the flag bit, which the kernels mask; a count
+     * alone marks nothing dirty.
      *
-     * `VIRTUAL_GEOMETRY_DESIGN.md` §6: a group is selectable iff every one of its parent-cluster
-     * references is live — the referencing cluster's page resident here, and that cluster's own
-     * group selectable here. Groups with no parents at all are the top of the DAG and are selectable
-     * the moment their page is. That is a closure over the resident set, so it is computed as one:
-     * seed the parentless groups and cascade down, counting a reference only when the group making
-     * it is already selectable.
+     * @param {number} group_row
+     * @returns {boolean} whether the count now equals the group's parent count
+     */
+    #count_reference(group_row) {
+        const word = group_row + VGEO_GROUP_ROW_OFFSET.FLAGS;
+
+        this.#arena[word] += 1 << 16;
+
+        return (this.#arena[word] >>> 16) === this.#arena[group_row + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT];
+    }
+
+    /**
+     * Activate an arriving page: seed its groups from the resident parents that refer into them,
+     * then cascade from every group that has all of its parents.
      *
-     * Recomputed whole rather than propagated incrementally, because an install can turn groups on
-     * several pages away and an eviction can turn them off again, and because the cost is the same
-     * order as the install that provoked it — one pass over the geometry's resident clusters. The
-     * incremental form is a later optimization with a counter to keep correct; the one thing it
-     * must not be is a *second* implementation of the rule.
+     * Same-page parents are not seeded; the cascade reaches them, because the page's own lookup
+     * word is already set and a same-page child reference resolves to this row.
      *
+     * @param {number} page_row
      * @param {number} geometry_row
-     * @returns {number[]} page rows whose group flags changed, for the caller to upload
+     * @param {VGeoPage} page
+     * @param {number} lookup_base
      */
-    refresh_selectable(geometry_row) {
-        const rows = this.#geometry_rows.get(geometry_row);
-
-        if (rows === undefined || rows.size === 0) {
-            return [];
-        }
-
+    #activate(page_row, geometry_row, page, lookup_base) {
         const arena = this.#arena;
-        const live = this.#live_refs;
 
-        live.clear();
+        const group_count = page.group_cluster_first.length;
+        const group_base = this.group_base(page_row);
 
-        const lookup_base = this.geometry_field(
-            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
-        );
+        const parents = this.#referrers.get(geometry_row).get(page.index);
+
+        if (parents !== undefined) {
+            for (const parent_row of parents) {
+                this.#seed_from(parent_row, page.index, group_base, group_count);
+            }
+        }
 
         /**
          * Word offsets of group rows to turn on, as a stack.
@@ -720,37 +899,87 @@ export class VGeoRuntimeTables {
          */
         const queue = [];
 
-        for (const page_row of rows) {
-            const group_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
-            const group_base = this.group_base(page_row);
+        for (let group = 0; group < group_count; group++) {
+            const row = group_base + group * VGEO_GROUP_ROW_WORDS;
 
-            for (let group = 0; group < group_count; group++) {
-                const row = group_base + group * VGEO_GROUP_ROW_WORDS;
+            if (this.#live_count(row) === arena[row + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT]) {
+                queue.push(row);
+            }
+        }
 
-                live.set(row, 0);
+        this.#cascade(queue, lookup_base);
+    }
 
-                if (arena[row + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT] === 0) {
-                    queue.push(row);
+    /**
+     * Count the references one resident parent page's **selectable** groups make into an arriving
+     * page's groups.
+     *
+     * @param {number} parent_row
+     * @param {number} child_page_index
+     * @param {number} child_group_base
+     * @param {number} child_group_count
+     */
+    #seed_from(parent_row, child_page_index, child_group_base, child_group_count) {
+        const arena = this.#arena;
+
+        const group_count = this.page_field(parent_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
+        const group_base = this.group_base(parent_row);
+        const cluster_base = this.cluster_base(parent_row);
+
+        for (let group = 0; group < group_count; group++) {
+            const group_row = group_base + group * VGEO_GROUP_ROW_WORDS;
+
+            if ((arena[group_row + VGEO_GROUP_ROW_OFFSET.FLAGS] & VGEO_GROUP_FLAG_SELECTABLE) === 0) {
+                continue;
+            }
+
+            const first = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST];
+            const count = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT];
+
+            for (let i = 0; i < count; i++) {
+                const cluster = cluster_base + (first + i) * VGEO_CLUSTER_ROW_WORDS;
+
+                if (arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX] !== child_page_index) {
+                    continue;
+                }
+
+                const child_group = arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP];
+
+                if (child_group >= child_group_count) {
+                    // outside the child page's table; counting it would land in a cluster row
+                    continue;
                 }
+
+                this.#count_reference(child_group_base + child_group * VGEO_GROUP_ROW_WORDS);
             }
         }
+    }
 
-        /**
-         * @type {Set<number>}
-         */
-        const selectable = new Set();
+    /**
+     * Turn groups on and let each one count itself into its resident children, turning on the
+     * children that reach their parent count — design §6's cascade, over this tier's residency.
+     *
+     * @param {number[]} queue word offsets of group rows whose count has reached their parent count
+     * @param {number} lookup_base
+     */
+    #cascade(queue, lookup_base) {
+        const arena = this.#arena;
 
         while (queue.length > 0) {
             const group_row = queue.pop();
 
-            if (selectable.has(group_row)) {
+            const flags_word = group_row + VGEO_GROUP_ROW_OFFSET.FLAGS;
+
+            if ((arena[flags_word] & VGEO_GROUP_FLAG_SELECTABLE) !== 0) {
                 continue;
             }
 
-            selectable.add(group_row);
+            arena[flags_word] |= VGEO_GROUP_FLAG_SELECTABLE;
 
             const page_row = Math.floor(group_row / this.#slot_words);
 
+            this.#activated.push(page_row);
+
             const cluster_base = this.cluster_base(page_row);
 
             const first = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST];
@@ -759,80 +988,131 @@ export class VGeoRuntimeTables {
             for (let i = 0; i < count; i++) {
                 const cluster = cluster_base + (first + i) * VGEO_CLUSTER_ROW_WORDS;
 
-                const child_page_index = arena[
-                    cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX
-                ];
+                const child = this.#child_group_row(cluster, lookup_base);
 
-                if (child_page_index === VGEO_NO_CHILD_PAGE) {
+                if (child === -1) {
                     continue;
                 }
 
-                const child_row = this.#lookup[lookup_base + child_page_index];
-
-                if (child_row === VGEO_PAGE_ROW_NONE) {
-                    // the child page is not in this tier; its groups stay blocked, which is exactly
-                    // what makes the cluster above clamp and draw
-                    continue;
+                if (this.#count_reference(child)) {
+                    queue.push(child);
                 }
+            }
+        }
+    }
 
-                const child_group = arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP];
+    /**
+     * The group row a cluster refines into, if that group's page is resident and the reference is
+     * inside its table.
+     *
+     * @param {number} cluster word offset of the cluster row
+     * @param {number} lookup_base
+     * @returns {number} word offset of the child group row, or -1
+     */
+    #child_group_row(cluster, lookup_base) {
+        const arena = this.#arena;
 
-                if (child_group >= this.page_field(child_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT)) {
-                    // a child_group outside the child page's table; counting it would corrupt a
-                    // neighbour's counter, and the traversal draws the referring cluster instead
-                    continue;
-                }
+        const child_page_index = arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX];
 
-                const child = this.group_base(child_row) + child_group * VGEO_GROUP_ROW_WORDS;
+        if (child_page_index === VGEO_NO_CHILD_PAGE) {
+            return -1;
+        }
 
-                const counted = live.get(child) + 1;
+        const child_row = this.#lookup[lookup_base + child_page_index];
 
-                live.set(child, counted);
+        if (child_row === VGEO_PAGE_ROW_NONE) {
+            // the child page is not in this tier; its groups stay blocked, which is exactly what
+            // makes the cluster above clamp and draw
+            return -1;
+        }
 
-                if (counted === arena[child + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT]) {
-                    queue.push(child);
-                }
-            }
+        const child_group = arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP];
+
+        if (child_group >= this.page_field(child_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT)) {
+            // a child_group outside the child page's table; counting it would corrupt a
+            // neighbour's row, and the traversal draws the referring cluster instead
+            return -1;
         }
 
-        /**
-         * @type {number[]}
-         */
-        const changed = [];
+        return this.group_base(child_row) + child_group * VGEO_GROUP_ROW_WORDS;
+    }
+
+    /**
+     * Retract a leaving page's references and turn off whatever they were holding up.
+     *
+     * Under the child rule this finds nothing to retract: a page with no resident child has no
+     * resident group depending on it. It is here for the callers that evict against the rule —
+     * `unregister_geometry`, a tool, a spec — so that a child group is never left selectable
+     * with a parent's page gone, which is the double-draw the whole rule exists to prevent
+     * (REVIEW_LEDGER C1).
+     *
+     * @param {number} page_row
+     * @param {number} lookup_base
+     */
+    #deactivate_page(page_row, lookup_base) {
+        if (this.#resident_children[page_row] === 0) {
+            return;
+        }
 
-        for (const page_row of rows) {
-            const group_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
-            const group_base = this.group_base(page_row);
+        const arena = this.#arena;
 
-            let dirty = false;
+        const group_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
+        const group_base = this.group_base(page_row);
 
-            for (let group = 0; group < group_count; group++) {
-                const row = group_base + group * VGEO_GROUP_ROW_WORDS;
+        for (let group = 0; group < group_count; group++) {
+            const group_row = group_base + group * VGEO_GROUP_ROW_WORDS;
 
-                const flags = selectable.has(row) ? VGEO_GROUP_FLAG_SELECTABLE : 0;
+            if ((arena[group_row + VGEO_GROUP_ROW_OFFSET.FLAGS] & VGEO_GROUP_FLAG_SELECTABLE) !== 0) {
+                this.#retract(group_row, lookup_base);
+            }
+        }
+    }
 
-                if (arena[row + VGEO_GROUP_ROW_OFFSET.FLAGS] !== flags) {
-                    arena[row + VGEO_GROUP_ROW_OFFSET.FLAGS] = flags;
+    /**
+     * Take one selectable group's references back out of its resident children, and turn off —
+     * recursively — every child group that loses one.
+     *
+     * @param {number} group_row
+     * @param {number} lookup_base
+     */
+    #retract(group_row, lookup_base) {
+        const arena = this.#arena;
 
-                    dirty = true;
-                }
+        const page_row = Math.floor(group_row / this.#slot_words);
+        const cluster_base = this.cluster_base(page_row);
+
+        const first = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST];
+        const count = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT];
+
+        for (let i = 0; i < count; i++) {
+            const cluster = cluster_base + (first + i) * VGEO_CLUSTER_ROW_WORDS;
+
+            const child = this.#child_group_row(cluster, lookup_base);
+
+            if (child === -1) {
+                continue;
             }
 
-            if (dirty) {
-                changed.push(page_row);
+            const flags_word = child + VGEO_GROUP_ROW_OFFSET.FLAGS;
+
+            arena[flags_word] -= 1 << 16;
+
+            if ((arena[flags_word] & VGEO_GROUP_FLAG_SELECTABLE) !== 0) {
+                arena[flags_word] &= ~VGEO_GROUP_FLAG_SELECTABLE;
+
+                this.#activated.push(Math.floor(child / this.#slot_words));
+
+                this.#retract(child, lookup_base);
             }
         }
-
-        return changed;
     }
-
     /**
      * Publish one group's selectability directly.
      *
-     * {@link refresh_selectable} is what a runtime calls; this is for a spec that needs a state the
-     * rule happens not to produce on the assets measured so far — the cut's own-group term is
-     * correctness for exactly such a state, and a guard nothing can construct is a guard nothing can
-     * test. The next {@link refresh_selectable} overwrites it.
+     * Activation is the tables' own; this is for a spec that needs a state the rule happens not to
+     * produce on the assets measured so far — the cut's own-group term is correctness for exactly
+     * such a state, and a guard nothing can construct is a guard nothing can test. It writes the
+     * flag bit and leaves the count, so the next cascade through the group may overwrite it.
      *
      * @param {number} page_row
      * @param {number} group
@@ -844,7 +1124,9 @@ export class VGeoRuntimeTables {
             + group * VGEO_GROUP_ROW_WORDS
             + VGEO_GROUP_ROW_OFFSET.FLAGS;
 
-        this.#arena[word] = selectable ? VGEO_GROUP_FLAG_SELECTABLE : 0;
+        this.#arena[word] = selectable
+            ? this.#arena[word] | VGEO_GROUP_FLAG_SELECTABLE
+            : this.#arena[word] & ~VGEO_GROUP_FLAG_SELECTABLE;
     }
 
     /**
@@ -872,7 +1154,8 @@ export class VGeoRuntimeTables {
         const words = VGEO_PAGE_ROW_WORDS + vgeo_runtime_page_block_words(
             this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.NODE_COUNT),
             this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT),
-            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT)
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT),
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.PARENT_ENTRY_COUNT)
         );
 
         return [base, words];