@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/runtime/VGeoResidencyOptions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Every knob of {@link VGeoResidency}, in one place, all of them per-reading budgets or plain
+ * capacities.
+ *
+ * The defaults are defaults to be overridden by whoever knows the device and the scene, not
+ * measurements. What the shape promises is that nothing the residency does per frame scales with
+ * anything but these numbers and the readback the host chose to read
+ * (RUNTIME_PLAN_2026_09_14 §1).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoResidencyOptions {
+    /**
+     * Decoded page bytes the VRAM tier may hold. `undefined` means what the pool's slots hold at the
+     * page size it was built for, so the two agree by construction.
+     * @type {number|undefined}
+     */
+    vram_budget_bytes: number | undefined;
+    /**
+     * Decoded page bytes the RAM tier may hold, across every registered container.
+     * @type {number}
+     */
+    ram_budget_bytes: number;
+    /**
+     * Pages the RAM tier may hold at once — the size of its flat slot arrays. A slot is a few words
+     * and a reference; what bounds the count is {@link ram_budget_bytes} in practice, and this only
+     * has to be at least what the budget can hold at the smallest page the containers produce.
+     * @type {number}
+     */
+    ram_slot_capacity: number;
+    /**
+     * Frames a page is safe from eviction after it was last used in its tier. No shorter than the
+     * readback latency, which is at least one frame of `mapAsync` and in practice a couple, because a
+     * page the last landed reading saw drawn from is a page still on screen.
+     * @type {number}
+     */
+    protect_frames: number;
+    /**
+     * Pages one reading may promote from RAM to VRAM. A promotion is a slot write, a meshlet batch
+     * and an activation cascade; pages are near-uniform, so the budget is in pages rather than bytes.
+     * @type {number}
+     */
+    max_promotions_per_reading: number;
+    /**
+     * Pages one reading may start fetching, across every registered container.
+     * @type {number}
+     */
+    max_fetches_per_reading: number;
+    /**
+     * Eviction candidates one reading may test, across both tiers. This is what bounds a full
+     * tier's cost per reading: the CLOCK hand tests this many rows and no more, and a reading that
+     * spends it refuses the rest of its promotions and admissions until the next reading lands —
+     * the tier turns over at a rate the host chose rather than at a rate the resident count chose
+     * (RUNTIME_PLAN_2026_09_14 §4.4).
+     * @type {number}
+     */
+    max_eviction_tests_per_reading: number;
+    /**
+     * Range requests in flight at once, across every registered container — one cap, because
+     * per-reader caps do not compose (design §6).
+     * @type {number}
+     */
+    max_concurrent_fetches: number;
+    /**
+     * Feedback readbacks that may be outstanding at once; a frame that finds this many in flight
+     * skips its reading rather than stalling.
+     * @type {number}
+     */
+    max_readbacks_in_flight: number;
+    /**
+     * Workers that fetch, verify and decode pages. Measured on the Zorah bdf6f961 container, the
+     * frame checksum is 1.0 ms a page and the decode 0.08 ms, so thirty-two fetched pages a
+     * reading is a frame of main-thread time in-process and the residency cost of thirty-two
+     * arrivals on workers. Zero runs in-process, which is also what happens wherever there is no
+     * `Worker` or a container's byte source cannot be described to one.
+     * @type {number}
+     */
+    worker_count: number;
+}
+//# sourceMappingURL=VGeoResidencyOptions.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/VGeoResidencyOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoResidencyOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoResidencyOptions.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;IACI;;;;OAIG;IACH,mBAFU,MAAM,GAAC,SAAS,CAEI;IAE9B;;;OAGG;IACH,kBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,mBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,4BAFU,MAAM,CAEgB;IAEhC;;;OAGG;IACH,yBAFU,MAAM,CAEa;IAE7B;;;;;;;OAOG;IACH,gCAFU,MAAM,CAEsB;IAEtC;;;;OAIG;IACH,wBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,cAFU,MAAM,CAEC;CACpB"}

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

@@ -0,0 +1,89 @@
+/**
+ * Every knob of {@link VGeoResidency}, in one place, all of them per-reading budgets or plain
+ * capacities.
+ *
+ * The defaults are defaults to be overridden by whoever knows the device and the scene, not
+ * measurements. What the shape promises is that nothing the residency does per frame scales with
+ * anything but these numbers and the readback the host chose to read
+ * (RUNTIME_PLAN_2026_09_14 §1).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoResidencyOptions {
+    /**
+     * Decoded page bytes the VRAM tier may hold. `undefined` means what the pool's slots hold at the
+     * page size it was built for, so the two agree by construction.
+     * @type {number|undefined}
+     */
+    vram_budget_bytes = undefined;
+
+    /**
+     * Decoded page bytes the RAM tier may hold, across every registered container.
+     * @type {number}
+     */
+    ram_budget_bytes = 512 * 1024 * 1024;
+
+    /**
+     * Pages the RAM tier may hold at once — the size of its flat slot arrays. A slot is a few words
+     * and a reference; what bounds the count is {@link ram_budget_bytes} in practice, and this only
+     * has to be at least what the budget can hold at the smallest page the containers produce.
+     * @type {number}
+     */
+    ram_slot_capacity = 1 << 14;
+
+    /**
+     * Frames a page is safe from eviction after it was last used in its tier. No shorter than the
+     * readback latency, which is at least one frame of `mapAsync` and in practice a couple, because a
+     * page the last landed reading saw drawn from is a page still on screen.
+     * @type {number}
+     */
+    protect_frames = 3;
+
+    /**
+     * Pages one reading may promote from RAM to VRAM. A promotion is a slot write, a meshlet batch
+     * and an activation cascade; pages are near-uniform, so the budget is in pages rather than bytes.
+     * @type {number}
+     */
+    max_promotions_per_reading = 64;
+
+    /**
+     * Pages one reading may start fetching, across every registered container.
+     * @type {number}
+     */
+    max_fetches_per_reading = 32;
+
+    /**
+     * Eviction candidates one reading may test, across both tiers. This is what bounds a full
+     * tier's cost per reading: the CLOCK hand tests this many rows and no more, and a reading that
+     * spends it refuses the rest of its promotions and admissions until the next reading lands —
+     * the tier turns over at a rate the host chose rather than at a rate the resident count chose
+     * (RUNTIME_PLAN_2026_09_14 §4.4).
+     * @type {number}
+     */
+    max_eviction_tests_per_reading = 1024;
+
+    /**
+     * Range requests in flight at once, across every registered container — one cap, because
+     * per-reader caps do not compose (design §6).
+     * @type {number}
+     */
+    max_concurrent_fetches = 12;
+
+    /**
+     * Feedback readbacks that may be outstanding at once; a frame that finds this many in flight
+     * skips its reading rather than stalling.
+     * @type {number}
+     */
+    max_readbacks_in_flight = 2;
+
+    /**
+     * Workers that fetch, verify and decode pages. Measured on the Zorah bdf6f961 container, the
+     * frame checksum is 1.0 ms a page and the decode 0.08 ms, so thirty-two fetched pages a
+     * reading is a frame of main-thread time in-process and the residency cost of thirty-two
+     * arrivals on workers. Zero runs in-process, which is also what happens wherever there is no
+     * `Worker` or a container's byte source cannot be described to one.
+     * @type {number}
+     */
+    worker_count = 4;
+}

package/src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
 /**
  * What a VRAM-resident page **is**, with no device anywhere near it.
  *
@@ -25,10 +28,10 @@
  * 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
@@ -36,6 +39,22 @@
  * 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.
  *
@@ -161,12 +180,25 @@ export class VGeoRuntimeTables {
      * @returns {number}
      */
     cluster_base(page_row: number): number;
+    /**
+     * 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: number): number;
     /**
      * 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
@@ -209,44 +241,30 @@ export class VGeoRuntimeTables {
      */
     pages_of(geometry_row: number): Set<number>;
     /**
-     * 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: number): boolean;
+    resident_children(page_row: number): number;
     /**
-     * Recompute one geometry's group selectability over **this tier's** residency.
-     *
-     * `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.
+     * Page rows whose group flags flipped since this was last called, and empties the list.
      *
-     * 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.
-     *
-     * @param {number} geometry_row
-     * @returns {number[]} page rows whose group flags changed, for the caller to upload
+     * @returns {number[]}
      */
-    refresh_selectable(geometry_row: number): number[];
+    take_activated_rows(): number[];
     /**
      * 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
@@ -284,4 +302,5 @@ export class VGeoRuntimeTables {
     set_meshlet_base(page_row: number, meshlet_base: number): boolean;
     #private;
 }
+export type VGeoPage = import("../format/read/VGeoPage.js").VGeoPage;
 //# sourceMappingURL=VGeoRuntimeTables.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoRuntimeTables.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IA+II;;;;;;;;OAQG;IACH;QAP4B,aAAa,GAA9B,MAAM;QACW,SAAS,GAA1B,MAAM;QAEW,UAAU,GAA3B,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,iBAAiB,GAAlC,MAAM;OA4BhB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,8BALW,MAAM,qBACN,MAAM,GACJ,MAAM,CAgDlB;IAED;;;;;;OAMG;IACH,kCAJW,MAAM,GACJ,MAAM,EAAE,CA8CpB;IAED;;;;OAIG;IACH,6BAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,0BAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,qBAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;;;;;;;OAcG;IACH,sBARW,MAAM,gCAEN,MAAM,GACJ,MAAM,CAkElB;IAED;;;;;OAKG;IACH,gCAFa,MAAM,CAMlB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAHW,MAAM,GACJ,OAAO,CAmCnB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,IAAI,MAAM,CAAC,CAIvB;IAED;;;;;;;;;;OAUG;IACH,6BAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,iCAHW,MAAM,GACJ,MAAM,EAAE,CAgIpB;IAED;;;;;;;;;;;;OAYG;IACH,+BALW,MAAM,SACN,MAAM,cACN,OAAO,GACL,IAAI,CAQhB;IAED;;;;OAIG;IACH,8BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,GACJ,MAAM,EAAE,CAYpB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;IAED;;;;;;OAMG;IACH,2BAJW,MAAM,gBACN,MAAM,GACJ,OAAO,CAYnB;;CA4DJ"}
+{"version":3,"file":"VGeoRuntimeTables.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoRuntimeTables.js"],"names":[],"mappings":"AAmBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH;IAmKI;;;;;;;;OAQG;IACH;QAP4B,aAAa,GAA9B,MAAM;QACW,SAAS,GAA1B,MAAM;QAEW,UAAU,GAA3B,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,iBAAiB,GAAlC,MAAM;OA6BhB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,8BALW,MAAM,qBACN,MAAM,GACJ,MAAM,CAiDlB;IAED;;;;;;OAMG;IACH,kCAJW,MAAM,GACJ,MAAM,EAAE,CAgDpB;IAED;;;;OAIG;IACH,6BAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,0BAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,qBAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,sBAHW,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,sBARW,MAAM,QACN,QAAQ,gBACR,MAAM,GACJ,MAAM,CAkFlB;IAED;;;;;OAKG;IACH,qBAHW,QAAQ,GACN,MAAM,CAOlB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAHW,MAAM,GACJ,OAAO,CAuCnB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,IAAI,MAAM,CAAC,CAIvB;IAED;;;;;;;;;;OAUG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,uBAFa,MAAM,EAAE,CAQpB;IAwWD;;;;;;;;;;;;OAYG;IACH,+BALW,MAAM,SACN,MAAM,cACN,OAAO,GACL,IAAI,CAUhB;IAED;;;;OAIG;IACH,8BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,GACJ,MAAM,EAAE,CAapB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;IAED;;;;;;OAMG;IACH,2BAJW,MAAM,gBACN,MAAM,GACJ,OAAO,CAYnB;;CA4DJ;uBAjtCY,OAAO,4BAA4B,EAAE,QAAQ"}