@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/renderer/animation/skinning/shader_skin_matrix_prep.js

@@ -1,104 +1,107 @@
-import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { ANIMATION_DATABASE_SPEC } from "../ANIMATION_DATABASE_SPEC.js";
-
-const SKIN_JOINT_BLOCK_TABLE = ANIMATION_DATABASE_SPEC.get('animation_skin_joint_blocks');
-
-/**
- * Workgroup size for the skin-matrix-prep pass. Exported so dispatchers
- * can pair it with
- * `animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE)` —
- * the page iterator's slot-to-workgroup mapping is computed against
- * this value, so the two must agree.
- */
-export const WORKGROUP_SIZE = 64;
-
-const PG_PREFIX = SKIN_JOINT_BLOCK_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), true);
-
-// One thread per joint-block slot — page iterator handles allocation/
-// occupancy. Each thread loads its block, then walks its inline joints
-// in a bounded inner loop. The block carries the absolute write
-// offset into `skin_matrices` (baked at registration time), so there's
-// no indirection back through the skin record.
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
-fn main(
-    @builtin(workgroup_id) wg_id: vec3<u32>,
-    @builtin(local_invocation_index) local_id: u32,
-) {
-    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
-        return;
-    }
-
-    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
-
-    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
-        return;
-    }
-    if !${PG_PREFIX}_is_occupied(slot_in_page) {
-        return;
-    }
-
-    let block = ${PG_PREFIX}_read(&animation_database, slot_in_page);
-
-    // Per-joint skin matrix is just joint-world × inverse-bind. The
-    // inverse-bind already takes a vertex from mesh-local space into
-    // joint-bind-local, so joint.global brings the deformed vertex
-    // back into world. The rasterizer then re-applies
-    // mesh.transform_global to the clone vertex (same path used for
-    // every other mesh's vertices, see chunk_mesh_resolve_vertex_
-    // position_world.js) — so any mesh-node factor in this formula
-    // would double-cancel against that re-application and shrink the
-    // rig back to mesh-local coordinates rendered as world. Keeping
-    // the formula minimal lets the SkinnedMesh sit at any transform
-    // in the scene graph and still render correctly via the standard
-    // mesh transform path.
-
-    for(var i = 0u; i < block.count; i++){
-        let joint = block.joints[i];
-        let node = scene_read_node(&scene_database, joint.node);
-
-        skin_matrices[block.skin_matrix_offset + i] =
-            node.global * joint.inverse_bind;
-    }
-}
-`, [
-        SKIN_JOINT_BLOCK_TABLE.chunk_iterate(WORKGROUP_SIZE),
-        chunk_scene_database_access,
-    ]
-);
-
-/**
- * Compute shader that walks the `animation_skin_joint_blocks` table —
- * one thread per joint-block slot via the page iterator — and writes
- * each joint's per-frame skinning matrix `node.global * inverse_bind`
- * to the shared `skin_matrices` scratch buffer at the block's pre-baked
- * absolute offset.
- *
- * Run after `graph_scene_update_transform_hierarchy` (so each joint's
- * `node.global` is up to date) and before any pass that consumes the
- * skin matrices (the pre-skinning compute pass).
- *
- * Dispatch via
- * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE), ... })`.
- * Skip the dispatch when `group_count_x === 0` — no skins registered
- * means the iterator has no work and `skin_matrices_buffer` may be
- * `null` on the manager.
- */
-export const shader_skin_matrix_prep = ComputeShader.from({
-    label: "Animation/SkinMatrixPrep",
-    body,
-    resources,
-});
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ANIMATION_DATABASE_SPEC } from "../ANIMATION_DATABASE_SPEC.js";
+
+const SKIN_JOINT_TABLE = ANIMATION_DATABASE_SPEC.get('animation_skin_joints');
+
+/**
+ * Workgroup size for the skin-matrix-prep pass. Exported so dispatchers
+ * can pair it with
+ * `animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE)` —
+ * the page iterator's slot-to-workgroup mapping is computed against
+ * this value, so the two must agree.
+ */
+export const WORKGROUP_SIZE = 64;
+
+const PG_PREFIX = SKIN_JOINT_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), true);
+
+// One thread per joint slot — page iterator handles allocation/occupancy. A joint's matrix lives at
+// the joint's own row, so there is no offset to look up and no indirection back through the skin.
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
+        return;
+    }
+
+    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
+
+    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
+        return;
+    }
+    if !${PG_PREFIX}_is_occupied(slot_in_page) {
+        return;
+    }
+
+    let joint = ${PG_PREFIX}_read(&animation_database, slot_in_page);
+
+    // A joint of a skin still waiting for its joints' rows names no node yet, and gets no matrix.
+    if joint.node == ${GPU_DATABASE_NULL}u {
+        return;
+    }
+
+    // Per-joint skin matrix is just joint-world × inverse-bind. The
+    // inverse-bind already takes a vertex from mesh-local space into
+    // joint-bind-local, so joint.global brings the deformed vertex
+    // back into world. The rasterizer then re-applies
+    // mesh.transform_global to the clone vertex (same path used for
+    // every other mesh's vertices, see chunk_mesh_resolve_vertex_
+    // position_world.js) — so any mesh-node factor in this formula
+    // would double-cancel against that re-application and shrink the
+    // rig back to mesh-local coordinates rendered as world. Keeping
+    // the formula minimal lets the SkinnedMesh sit at any transform
+    // in the scene graph and still render correctly via the standard
+    // mesh transform path.
+    let node = scene_read_node(&scene_database, joint.node);
+
+    skin_matrices[${PG_PREFIX}_slot_to_index(slot_in_page)] = node.global * joint.inverse_bind;
+}
+`, [
+        SKIN_JOINT_TABLE.chunk_iterate(WORKGROUP_SIZE),
+        chunk_scene_database_access,
+    ]
+);
+
+/**
+ * Compute shader that walks the `animation_skin_joints` table — one
+ * thread per joint slot via the page iterator — and writes each joint's
+ * per-frame skinning matrix `node.global * inverse_bind` to the shared
+ * `skin_matrices` scratch buffer at the joint's row. A skin's joints are
+ * a run of rows, so its matrices are the same run of the buffer, starting
+ * at its `joints_first`. A joint with no node yet is skipped.
+ *
+ * Run after `graph_scene_update_transform_hierarchy` (so each joint's
+ * `node.global` is up to date) and before any pass that consumes the
+ * skin matrices (the pre-skinning compute pass).
+ *
+ * One thread per joint rather than one per block of eight. Measured 2026-09-25, the 21,060 joints
+ * of 324 skins on an RTX 4090, paired launches against the block version: 5.1 µs a frame where it
+ * took 9.2, and the matrices read back within 2e-6 of the block version's.
+ *
+ * Dispatch via
+ * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE), ... })`.
+ * Skip the dispatch when `group_count_x === 0` — no skins registered
+ * means the iterator has no work and `skin_matrices_buffer` may be
+ * `null` on the manager.
+ */
+export const shader_skin_matrix_prep = ComputeShader.from({
+    label: "Animation/SkinMatrixPrep",
+    body,
+    resources,
+});

package/src/shade/renderer/binding/BindingResource.d.ts

@@ -1,10 +1,45 @@
+/**
+ * An engine-level description of one thing a bind group entry can point at, over the engine's own
+ * resource wrappers rather than the raw WebGPU objects.
+ *
+ * ## This is not what the bind-group cache uses
+ *
+ * `BindGroupDescriptor` hashes and compares its entries through its own module-private
+ * `get_resource_buffer_hash` / equality, directly over the native `GPUBindGroupEntry` resources — a
+ * `{buffer, offset, size}` record, a `GPUSampler`, a `GPUTextureView`. That is a different question from
+ * the one this hierarchy answers: it keys on engine wrappers (`GPUBufferContext` and its id), the cache
+ * keys on a `WeakMap` id of the raw `GPUBuffer`.
+ *
+ * The two are deliberately not merged. Routing the cache through these classes would mean allocating a
+ * wrapper per entry on every bind-group lookup, which is per-draw work, and the cache's inputs are native
+ * objects it does not own. So treat this as the descriptive layer and `BindGroupDescriptor`'s private
+ * functions as the cache's own key — and do not read one as the intended replacement for the other,
+ * which the names invite.
+ *
+ * Kept because `@woosh/meep-engine` publishes raw `src`, so an unreferenced export is public surface.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 export class BindingResource {
-    toGPU(): void;
+    /**
+     * @returns {GPUBindingResource}
+     */
+    toGPU(): GPUBindingResource;
+    /**
+     * @returns {number}
+     */
     hash(): number;
     /**
+     * Whether `other` points at the same thing.
+     *
+     * This used to `return false` unconditionally, so a subclass that forgot to override it reported that
+     * it was not equal to itself — a silently wrong answer from a method whose whole job is identity. It
+     * throws now, like {@link toGPU}: a subclass either answers the question or says it cannot.
      *
      * @param {BindingResource} other
      * @returns {boolean}
+     * @throws {Error} when the subclass has not overridden it
      */
     equals(other: BindingResource): boolean;
 }

package/src/shade/renderer/binding/BindingResource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BindingResource.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindingResource.js"],"names":[],"mappings":"AAAA;IAEI,cAEC;IAED,eAEC;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAInB;CACJ"}
+{"version":3,"file":"BindingResource.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindingResource.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAEI;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,cAJW,eAAe,GACb,OAAO,CAKnB;CACJ"}

package/src/shade/renderer/binding/BindingResource.js

@@ -1,21 +1,54 @@
+/**
+ * An engine-level description of one thing a bind group entry can point at, over the engine's own
+ * resource wrappers rather than the raw WebGPU objects.
+ *
+ * ## This is not what the bind-group cache uses
+ *
+ * `BindGroupDescriptor` hashes and compares its entries through its own module-private
+ * `get_resource_buffer_hash` / equality, directly over the native `GPUBindGroupEntry` resources — a
+ * `{buffer, offset, size}` record, a `GPUSampler`, a `GPUTextureView`. That is a different question from
+ * the one this hierarchy answers: it keys on engine wrappers (`GPUBufferContext` and its id), the cache
+ * keys on a `WeakMap` id of the raw `GPUBuffer`.
+ *
+ * The two are deliberately not merged. Routing the cache through these classes would mean allocating a
+ * wrapper per entry on every bind-group lookup, which is per-draw work, and the cache's inputs are native
+ * objects it does not own. So treat this as the descriptive layer and `BindGroupDescriptor`'s private
+ * functions as the cache's own key — and do not read one as the intended replacement for the other,
+ * which the names invite.
+ *
+ * Kept because `@woosh/meep-engine` publishes raw `src`, so an unreferenced export is public surface.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 export class BindingResource {
 
+    /**
+     * @returns {GPUBindingResource}
+     */
     toGPU() {
         throw new Error('Not Implemented');
     }
 
+    /**
+     * @returns {number}
+     */
     hash() {
         return 0;
     }
 
-
     /**
+     * Whether `other` points at the same thing.
+     *
+     * This used to `return false` unconditionally, so a subclass that forgot to override it reported that
+     * it was not equal to itself — a silently wrong answer from a method whose whole job is identity. It
+     * throws now, like {@link toGPU}: a subclass either answers the question or says it cannot.
      *
      * @param {BindingResource} other
      * @returns {boolean}
+     * @throws {Error} when the subclass has not overridden it
      */
     equals(other) {
-        return false;
+        throw new Error('Not Implemented');
     }
 }
-

package/src/shade/renderer/binding/BufferBinding.d.ts

@@ -1,4 +1,11 @@
 /**
+ * A range of one buffer, as a bind group entry would point at it.
+ *
+ * `size === -1` means "the whole buffer from `offset`", which {@link actual_size} resolves. That is this
+ * class own convention and is *not* the one the bind-group cache uses: `BindGroupDescriptor` reads a
+ * missing size as `0`, because it is hashing a native `GPUBindGroupEntry` where absent means
+ * "implementation default". See {@link BindingResource} for why the two are not merged.
+ *
  * @see https://www.w3.org/TR/webgpu/#dictdef-gpubufferbinding
  */
 export class BufferBinding extends BindingResource {
@@ -17,6 +24,7 @@ export class BufferBinding extends BindingResource {
      */
     size: number;
     /**
+     * Resolved size in bytes: `size`, or the rest of the buffer when `size` is -1.
      *
      * @returns {number}
      */

package/src/shade/renderer/binding/BufferBinding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BufferBinding.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BufferBinding.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAEI;;OAEG;IACH,yBAAO;IAEP;;;OAGG;IACH,QAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IAcV;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CA0BnB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;gCA1E+B,sBAAsB"}
+{"version":3,"file":"BufferBinding.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BufferBinding.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH;IAEI;;OAEG;IACH,yBAAO;IAEP;;;OAGG;IACH,QAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IA2BV;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CA0BnB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;gCA/F+B,sBAAsB"}

package/src/shade/renderer/binding/BufferBinding.js

@@ -2,6 +2,13 @@ import { combine_hash } from "../../../core/collection/array/combine_hash.js";
 import { BindingResource } from "./BindingResource.js";
 
 /**
+ * A range of one buffer, as a bind group entry would point at it.
+ *
+ * `size === -1` means "the whole buffer from `offset`", which {@link actual_size} resolves. That is this
+ * class own convention and is *not* the one the bind-group cache uses: `BindGroupDescriptor` reads a
+ * missing size as `0`, because it is hashing a native `GPUBindGroupEntry` where absent means
+ * "implementation default". See {@link BindingResource} for why the two are not merged.
+ *
  * @see https://www.w3.org/TR/webgpu/#dictdef-gpubufferbinding
  */
 export class BufferBinding extends BindingResource {
@@ -36,6 +43,20 @@ export class BufferBinding extends BindingResource {
     }
 
     /**
+     * The native entry this describes.
+     *
+     * @returns {GPUBufferBinding}
+     */
+    toGPU() {
+        return {
+            buffer: this.buffer.gpu_buffer,
+            offset: this.offset,
+            size: this.actual_size
+        };
+    }
+
+    /**
+     * Resolved size in bytes: `size`, or the rest of the buffer when `size` is -1.
      *
      * @returns {number}
      */

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts

@@ -42,6 +42,12 @@ export class GPUDatabase {
      * @return {number}
      */
     get page_size_bytes(): number;
+    /**
+     * What the database was named when it was built — the prefix of every GPU object it labels, and
+     * how a report about one of its rows says which database the row is in.
+     * @return {string}
+     */
+    get label(): string;
     /**
      * Look up a table by its declared name.
      *
@@ -69,6 +75,19 @@ export class GPUDatabase {
      * @return {number}
      */
     get data_start_offset(): number;
+    /**
+     * Whether {@link update} has anything to send: a table with an upload pending (see
+     * {@link GPUTypedTable.has_pending_upload}), or allocation-table entries the GPU has not been
+     * given — which a database has from construction until its first update.
+     *
+     * What a caller that updates only when something changed gates on, rather than on a count of
+     * its own writes: freeing a row writes nothing and still has to reach the GPU. The readback is
+     * not counted — a caller skipping an update applies and encodes it itself, as
+     * `GPUSceneContext` does.
+     *
+     * @returns {boolean}
+     */
+    get has_pending_upload(): boolean;
     /**
      * Apply all data transfer requests as well as any resizing
      * @param {ShadeGPUCommandContext} encoder

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA2CA;;;;;;;;;GASG;AACH;IAoFI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAuEhB;IA9JD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAgFD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;qCAvhCY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB;oCALd,0BAA0B"}
+{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA2CA;;;;;;;;;GASG;AACH;IA6FI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAkJhB;IAlPD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,oBAEC;IA2JD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;;;;;;;;;OAWG;IACH,kCAeC;IAED;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;qCAxoCY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB;oCALd,0BAA0B"}

package/src/shade/renderer/buffer/table/GPUDatabase.js

@@ -135,6 +135,15 @@ export class GPUDatabase {
         return this.definition.page_size_bytes;
     }
 
+    /**
+     * What the database was named when it was built — the prefix of every GPU object it labels, and
+     * how a report about one of its rows says which database the row is in.
+     * @return {string}
+     */
+    get label() {
+        return this.#label;
+    }
+
     /**
      * @param {Object} options
      * @param {GPUDatabaseDefinition} options.definition Immutable schema
@@ -170,15 +179,90 @@ export class GPUDatabase {
 
         this.tables = new Array(table_count);
 
+        // Every database built from a definition sees the same links, so the first one stops the
+        // definition taking more.
+        definition.seal();
+
         for (let i = 0; i < table_count; i++) {
-            const table = new GPUTypedTable(descriptors[i]);
+            const descriptor = descriptors[i];
+            const table = new GPUTypedTable(descriptor);
 
             table.index = i;
             table.page_buffer_pool = this.#page_buffer_pool;
+            // A freed row names nothing: NULL in every link word, and in the first word of every
+            // range — whose count the zero-fill has already emptied.
+            table.null_words = Uint32Array.from([
+                ...definition.links_of(descriptor).map(link => link.word),
+                ...definition.ranges_of(descriptor).map(range => range.first_word),
+            ]);
 
             this.tables[i] = table;
         }
 
+        // Owning links and ranges resolve to table instances once every table exists — a link can
+        // point into a table declared after its own — so that removing a row takes the rows it owns
+        // with it. They resolve by identity: a target that is not one of this database's own tables
+        // gets no cascade. The definition refuses an owning declaration into another database, but
+        // only in an assert, and by index alone a shipped build would free rows of whichever table
+        // of this one happened to share the other's index.
+        const own_table = (descriptor) => {
+            const table = this.tables[descriptor.index];
+
+            return table !== undefined && table.descriptor === descriptor ? table : undefined;
+        };
+
+        for (let i = 0; i < table_count; i++) {
+            const owning_links = [];
+            const links = definition.links_of(descriptors[i]);
+
+            for (let j = 0; j < links.length; j++) {
+                const link = links[j];
+
+                if (!link.owning) {
+                    continue;
+                }
+
+                const target = own_table(link.target_table);
+
+                assert.defined(target, `owning link ${link} points outside its database`);
+
+                if (target !== undefined) {
+                    owning_links.push(Object.freeze({ word: link.word, target }));
+                }
+            }
+
+            if (owning_links.length > 0) {
+                this.tables[i].owning_links = Object.freeze(owning_links);
+            }
+
+            const owning_ranges = [];
+            const ranges = definition.ranges_of(descriptors[i]);
+
+            for (let j = 0; j < ranges.length; j++) {
+                const range = ranges[j];
+
+                if (!range.owning) {
+                    continue;
+                }
+
+                const target = own_table(range.target_table);
+
+                assert.defined(target, `owning range ${range} points outside its database`);
+
+                if (target !== undefined) {
+                    owning_ranges.push(Object.freeze({
+                        first_word: range.first_word,
+                        count_word: range.count_word,
+                        target,
+                    }));
+                }
+            }
+
+            if (owning_ranges.length > 0) {
+                this.tables[i].owning_ranges = Object.freeze(owning_ranges);
+            }
+        }
+
         // Build the allocation table. Each table reserves its own
         // [page_limit] u32 slots at descriptor.page_lookup_address; total size
         // is the sum of page_limit across all tables.
@@ -510,6 +594,35 @@ export class GPUDatabase {
         }
     }
 
+    /**
+     * Whether {@link update} has anything to send: a table with an upload pending (see
+     * {@link GPUTypedTable.has_pending_upload}), or allocation-table entries the GPU has not been
+     * given — which a database has from construction until its first update.
+     *
+     * What a caller that updates only when something changed gates on, rather than on a count of
+     * its own writes: freeing a row writes nothing and still has to reach the GPU. The readback is
+     * not counted — a caller skipping an update applies and encodes it itself, as
+     * `GPUSceneContext` does.
+     *
+     * @returns {boolean}
+     */
+    get has_pending_upload() {
+        if (this.#alloc_table_dirty_min <= this.#alloc_table_dirty_max) {
+            return true;
+        }
+
+        const tables = this.tables;
+        const table_count = tables.length;
+
+        for (let i = 0; i < table_count; i++) {
+            if (tables[i].has_pending_upload) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Apply all data transfer requests as well as any resizing
      * @param {ShadeGPUCommandContext} encoder