@woosh/meep-engine 3.30.0 → 3.31.0

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

@@ -372,7 +372,7 @@ export class GPUTypedTableDescriptor {
         lines.add(`fn ${fn_name}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>${access_suffix}>, index: u32) -> ${type.wgsl_ref} {`);
         lines.indent();
 
-        this.#wgsl_gen_element_offset(lines);
+        this.#wgsl_gen_element_offset(lines, `return ${type.wgsl_ref}();`);
 
         lines.add(`return `);
         table_wgsl_gen_read_code(lines, 0, "database", type);
@@ -399,7 +399,7 @@ export class GPUTypedTableDescriptor {
         lines.add(`fn ${this.marshalling_method_write}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>, read_write>, index: u32, value: ${type.wgsl_ref}) {`);
         lines.indent();
 
-        this.#wgsl_gen_element_offset(lines);
+        this.#wgsl_gen_element_offset(lines, `return;`);
 
         table_wgsl_gen_write_code(lines, 0, "database", type);
 
@@ -744,7 +744,7 @@ fn ${prefix}_read(
         lines.add(`fn ${fn_name}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>>, index: u32) -> ${field_type.wgsl_ref} {`);
         lines.indent();
 
-        this.#wgsl_gen_element_offset(lines);
+        this.#wgsl_gen_element_offset(lines, `return ${field_type.wgsl_ref}();`);
 
         lines.add(`return `);
         table_wgsl_gen_read_code(lines, field_offset_words, "database", field_type);
@@ -797,7 +797,7 @@ fn ${prefix}_read(
         lines.add(`fn ${fn_name}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>, read_write>, index: u32, value: ${field_type.wgsl_ref}) {`);
         lines.indent();
 
-        this.#wgsl_gen_element_offset(lines);
+        this.#wgsl_gen_element_offset(lines, `return;`);
 
         table_wgsl_gen_write_code(lines, field_offset_words, "database", field_type);
 
@@ -824,9 +824,32 @@ fn ${prefix}_read(
      *
      * @param {LineBuilder} lines
      */
-    #wgsl_gen_element_offset(lines) {
+    #wgsl_gen_element_offset(lines, refusal) {
         this.#wgsl_gen_page_lookup(lines);
 
+        /*
+         The same two guards the hand-written table shaders carry — gpu_table_element_upload_shader,
+         the partial upload, the gather and the iterator codegen above all have them, and this had
+         neither.
+
+         #deallocate_empty_pages writes 0xFFFFFFFF into a freed page's lookup slot, and the offset
+         below is u32 arithmetic: 0xFFFFFFFF plus the page header wraps to a small word index, which
+         lands INSIDE the page-address table. A write through it rewrites another page's address and
+         every later read of that table marshals unrelated bytes — corruption of the one structure
+         the whole database addresses through, from a shader that did nothing but name a row whose
+         page went away. A page index past this table's own limit is the milder version: it resolves
+         the next table's page and reads its records as this one's.
+
+         Refusing is not free — a caller that asks for a row it no longer holds now gets a zero
+         record or a dropped write instead of an error — but it is the same answer the iteration
+         path gives for the same page, and the alternative is not an error either.
+        */
+        lines.add(`if (page_index >= ${this.page_limit}u || page_address == 0xFFFFFFFFu) {`);
+        lines.indent();
+        lines.add(refusal);
+        lines.dedent();
+        lines.add(`}`);
+
         const packed_element_size = this.packed_element_size_bytes;
         const element_size = packed_element_size / GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
         assert.isNonNegativeInteger(element_size, 'element_size');

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

@@ -0,0 +1,14 @@
+/**
+ * The one value a link word holds when it names no row, in every table of every database.
+ *
+ * A link is a `u32` row index, and 0 is a row like any other, so "no target" needs a value no row
+ * can have. This is the one the page-address table already uses for an unallocated page. It is
+ * also the first word of an empty range, `(GPU_DATABASE_NULL, 0)`.
+ *
+ * A link does not choose its own: a declaration says only whether its word may hold this one — see
+ * {@link GPUDatabaseDefinition#add_link}.
+ *
+ * @type {number}
+ */
+export const GPU_DATABASE_NULL: number;
+//# sourceMappingURL=GPU_DATABASE_NULL.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPU_DATABASE_NULL.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPU_DATABASE_NULL.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,gCAFU,MAAM,CAE4B"}

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

@@ -0,0 +1,13 @@
+/**
+ * The one value a link word holds when it names no row, in every table of every database.
+ *
+ * A link is a `u32` row index, and 0 is a row like any other, so "no target" needs a value no row
+ * can have. This is the one the page-address table already uses for an unallocated page. It is
+ * also the first word of an empty range, `(GPU_DATABASE_NULL, 0)`.
+ *
+ * A link does not choose its own: a declaration says only whether its word may hold this one — see
+ * {@link GPUDatabaseDefinition#add_link}.
+ *
+ * @type {number}
+ */
+export const GPU_DATABASE_NULL = 0xFFFFFFFF;

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

@@ -0,0 +1,80 @@
+/**
+ * Check every declared link and range of `databases` against the rows they hold, and report what
+ * disagrees. An empty answer means every link of every occupied row names an occupied row of its
+ * target (or holds NULL where that is allowed), every range is empty or covers only occupied rows,
+ * and every row that only owning declarations point into belongs to exactly one owner.
+ *
+ * A declaration pointing into a database that was not passed is reported once as `unresolved` and
+ * not checked, so pass every database the links reach — for the renderer, the scene database with
+ * the light, animation and particle ones. Two databases built from one definition throw: a link into
+ * that definition would not say which of them it means.
+ *
+ * **When.** Only once the frame's CPU writes are all done — after `GPUSceneContext.update`, and after
+ * the shadow draw when shadows are on. Before that, some links legitimately name rows nobody has
+ * written yet: a light's record is written before the scene rows are flushed, a child can be flushed
+ * before its parent, and a light's shadow slot is written during the draw.
+ *
+ * **What it cannot see.** A link to a row that was freed and handed out again before the check ran
+ * names an occupied row — just not the one it was written for. Rows are handed out lowest-first, at
+ * once, so that is the likely form of a stale link, and nothing here catches it.
+ *
+ * **Cost.** O(rows × declarations) on the CPU, reading every link and range of every occupied row,
+ * plus a visit to each live row a range covers — never to a missing one. Measured at 0.5 ms for the
+ * scene database of a 10,000-entity scene with 2,500 meshes — 12,501 link words, about 40 ns each
+ * (node, software device, 2026-09-25). At a few million rows that is a few hundred milliseconds. For
+ * specs and debug tools; never run it per frame.
+ *
+ * @param {GPUDatabase[]} databases
+ * @returns {GPUDatabaseLinkViolation[]}
+ */
+export function gpu_database_check_links(databases: GPUDatabase[]): GPUDatabaseLinkViolation[];
+export type GPUDatabase = import("./GPUDatabase.js").GPUDatabase;
+export type GPUDatabaseDefinition = import("./GPUDatabaseDefinition.js").GPUDatabaseDefinition;
+export type GPUTypedTable = import("./GPUTypedTable.js").GPUTypedTable<any>;
+export type GPUTableLink = import("./GPUTableLink.js").GPUTableLink;
+export type GPUTableRange = import("./GPUTableRange.js").GPUTableRange;
+/**
+ * One way a set of databases disagrees with its declared links and ranges.
+ *
+ * - `dangling`: an occupied row's link names a row its target table does not hold, or its range
+ *   covers rows it does not. `value` is that row — for a range, the first of them: however many
+ *   rows are missing, one range is one violation.
+ * - `null_in_required`: an occupied row holds {@link GPU_DATABASE_NULL } in a link that may not.
+ * - `malformed_range`: a range that is neither empty — `(NULL, 0)` — nor a run its target table
+ *   could hold: a count of 0 with a first row, a count with no first row, or a run reaching past the
+ *   table's last row. `field` is the range's first field and `value` its first word. The rows of a
+ *   malformed range are not looked at, so a garbage count costs one violation, not four billion.
+ * - `unresolved`: the link or range points into a database that was not passed, so none of its
+ *   rows was checked. Reported once per declaration, with `row` and `value` of -1.
+ * - `orphan`: an occupied row of a table that only owning links and ranges point into, which no
+ *   owner reaches. `field` is empty and `value` is the row.
+ * - `owned_twice`: a row named by the owning links or ranges of more than one occupied row. `field`
+ *   is empty and `value` is how many.
+ *
+ * An owned chain that loops back on itself shows up as one of the last two: owned twice where an
+ * owner also reaches it, orphans where nothing does.
+ */
+export type GPUDatabaseLinkViolation = {
+    reason: 'dangling' | 'null_in_required' | 'malformed_range' | 'unresolved' | 'orphan' | 'owned_twice';
+    /**
+     * label of the database holding the row
+     */
+    database: string;
+    table: string;
+    row: number;
+    /**
+     * the link's field path, or the range's first field; empty for an
+     * ownership violation
+     */
+    field: string;
+    value: number;
+};
+/**
+ * An owning declaration out of a table, with the table it points into.
+ */
+export type OwningEdge = {
+    link: GPUTableLink | null;
+    range: GPUTableRange | null;
+    target: import("./GPUTypedTable.js").GPUTypedTable<any>;
+};
+//# sourceMappingURL=gpu_database_check_links.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_database_check_links.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_database_check_links.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oDAHW,WAAW,EAAE,GACX,wBAAwB,EAAE,CA2VtC;0BAlcY,OAAO,kBAAkB,EAAE,WAAW;oCACtC,OAAO,4BAA4B,EAAE,qBAAqB;;2BAE1D,OAAO,mBAAmB,EAAE,YAAY;4BACxC,OAAO,oBAAoB,EAAE,aAAa;;;;;;;;;;;;;;;;;;;;;;;YAyBzC,UAAU,GAAC,kBAAkB,GAAC,iBAAiB,GAAC,YAAY,GAAC,QAAQ,GAAC,aAAa;;;;cACnF,MAAM;WACN,MAAM;SACN,MAAM;;;;;WACN,MAAM;WAEN,MAAM;;;;;yBAMP;IAAC,IAAI,EAAE,YAAY,GAAC,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,GAAC,IAAI,CAAC;IAAC,MAAM,kDAAe;CAAC"}

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

@@ -0,0 +1,456 @@
+import { assert } from "../../../../core/assert.js";
+import { GPU_DATABASE_NULL } from "./GPU_DATABASE_NULL.js";
+import { gpu_table_range_well_formed } from "./gpu_table_range_well_formed.js";
+
+/**
+ * @typedef {import("./GPUDatabase.js").GPUDatabase} GPUDatabase
+ * @typedef {import("./GPUDatabaseDefinition.js").GPUDatabaseDefinition} GPUDatabaseDefinition
+ * @typedef {import("./GPUTypedTable.js").GPUTypedTable} GPUTypedTable
+ * @typedef {import("./GPUTableLink.js").GPUTableLink} GPUTableLink
+ * @typedef {import("./GPUTableRange.js").GPUTableRange} GPUTableRange
+ */
+
+/**
+ * One way a set of databases disagrees with its declared links and ranges.
+ *
+ * - `dangling`: an occupied row's link names a row its target table does not hold, or its range
+ *   covers rows it does not. `value` is that row — for a range, the first of them: however many
+ *   rows are missing, one range is one violation.
+ * - `null_in_required`: an occupied row holds {@link GPU_DATABASE_NULL} in a link that may not.
+ * - `malformed_range`: a range that is neither empty — `(NULL, 0)` — nor a run its target table
+ *   could hold: a count of 0 with a first row, a count with no first row, or a run reaching past the
+ *   table's last row. `field` is the range's first field and `value` its first word. The rows of a
+ *   malformed range are not looked at, so a garbage count costs one violation, not four billion.
+ * - `unresolved`: the link or range points into a database that was not passed, so none of its
+ *   rows was checked. Reported once per declaration, with `row` and `value` of -1.
+ * - `orphan`: an occupied row of a table that only owning links and ranges point into, which no
+ *   owner reaches. `field` is empty and `value` is the row.
+ * - `owned_twice`: a row named by the owning links or ranges of more than one occupied row. `field`
+ *   is empty and `value` is how many.
+ *
+ * An owned chain that loops back on itself shows up as one of the last two: owned twice where an
+ * owner also reaches it, orphans where nothing does.
+ *
+ * @typedef {object} GPUDatabaseLinkViolation
+ * @property {'dangling'|'null_in_required'|'malformed_range'|'unresolved'|'orphan'|'owned_twice'} reason
+ * @property {string} database label of the database holding the row
+ * @property {string} table
+ * @property {number} row
+ * @property {string} field the link's field path, or the range's first field; empty for an
+ *      ownership violation
+ * @property {number} value
+ */
+
+/**
+ * An owning declaration out of a table, with the table it points into.
+ *
+ * @typedef {{link: GPUTableLink|null, range: GPUTableRange|null, target: GPUTypedTable}} OwningEdge
+ */
+
+
+/**
+ * Push `[table, row]` onto `stack` for each row one owning edge of `row` names — for a range, each
+ * live row of its run. A malformed range names none; it is reported where the range is read.
+ *
+ * @param {GPUTypedTable} table
+ * @param {number} row
+ * @param {OwningEdge} edge
+ * @param {Array<GPUTypedTable|number>} stack
+ */
+function push_owned(table, row, edge, stack) {
+    if (edge.link !== null) {
+        stack.push(edge.target, table.get_word(row, edge.link.word));
+        return;
+    }
+
+    const first = table.get_word(row, edge.range.first_word);
+    const count = table.get_word(row, edge.range.count_word);
+    const target = edge.target;
+
+    if (first === GPU_DATABASE_NULL || !gpu_table_range_well_formed(first, count, target.descriptor)) {
+        return;
+    }
+
+    const end = first + count;
+    const occupancy = target.occupancy;
+
+    for (let r = occupancy.nextSetBit(first); r !== -1 && r < end; r = occupancy.nextSetBit(r + 1)) {
+        stack.push(target, r);
+    }
+}
+
+/**
+ * Check every declared link and range of `databases` against the rows they hold, and report what
+ * disagrees. An empty answer means every link of every occupied row names an occupied row of its
+ * target (or holds NULL where that is allowed), every range is empty or covers only occupied rows,
+ * and every row that only owning declarations point into belongs to exactly one owner.
+ *
+ * A declaration pointing into a database that was not passed is reported once as `unresolved` and
+ * not checked, so pass every database the links reach — for the renderer, the scene database with
+ * the light, animation and particle ones. Two databases built from one definition throw: a link into
+ * that definition would not say which of them it means.
+ *
+ * **When.** Only once the frame's CPU writes are all done — after `GPUSceneContext.update`, and after
+ * the shadow draw when shadows are on. Before that, some links legitimately name rows nobody has
+ * written yet: a light's record is written before the scene rows are flushed, a child can be flushed
+ * before its parent, and a light's shadow slot is written during the draw.
+ *
+ * **What it cannot see.** A link to a row that was freed and handed out again before the check ran
+ * names an occupied row — just not the one it was written for. Rows are handed out lowest-first, at
+ * once, so that is the likely form of a stale link, and nothing here catches it.
+ *
+ * **Cost.** O(rows × declarations) on the CPU, reading every link and range of every occupied row,
+ * plus a visit to each live row a range covers — never to a missing one. Measured at 0.5 ms for the
+ * scene database of a 10,000-entity scene with 2,500 meshes — 12,501 link words, about 40 ns each
+ * (node, software device, 2026-09-25). At a few million rows that is a few hundred milliseconds. For
+ * specs and debug tools; never run it per frame.
+ *
+ * @param {GPUDatabase[]} databases
+ * @returns {GPUDatabaseLinkViolation[]}
+ */
+export function gpu_database_check_links(databases) {
+    assert.isArray(databases, 'databases');
+
+    /**
+     * @type {Map<GPUDatabaseDefinition, GPUDatabase>}
+     */
+    const by_definition = new Map();
+
+    for (let i = 0; i < databases.length; i++) {
+        const database = databases[i];
+
+        assert.notOk(
+            by_definition.has(database.definition),
+            `'${by_definition.get(database.definition)?.label}' and '${database.label}' share a definition, so a link into it would not say which one it means`
+        );
+
+        by_definition.set(database.definition, database);
+    }
+
+    /**
+     * @type {GPUDatabaseLinkViolation[]}
+     */
+    const violations = [];
+
+    /**
+     * Owning references each row received from occupied rows, per target table.
+     * @type {Map<GPUTypedTable, Map<number, number>>}
+     */
+    const owner_counts = new Map();
+
+    /**
+     * Whether each declaration pointing into a table owns, per target table.
+     * @type {Map<GPUTypedTable, boolean[]>}
+     */
+    const inbound = new Map();
+
+    /**
+     * The owning declarations held by each table's rows.
+     * @type {Map<GPUTypedTable, OwningEdge[]>}
+     */
+    const owning_out = new Map();
+
+    /**
+     * @param {GPUTypedTable} target
+     * @param {number} row
+     */
+    const count_owner = (target, row) => {
+        let counts = owner_counts.get(target);
+
+        if (counts === undefined) {
+            counts = new Map();
+            owner_counts.set(target, counts);
+        }
+
+        counts.set(row, (counts.get(row) ?? 0) + 1);
+    };
+
+    /**
+     * Record a declaration pointing into `target`, and an owning one as an edge out of `source`.
+     *
+     * @param {GPUTypedTable} source
+     * @param {GPUTypedTable} target
+     * @param {boolean} owning
+     * @param {OwningEdge} edge
+     */
+    const note_declaration = (source, target, owning, edge) => {
+        let into = inbound.get(target);
+
+        if (into === undefined) {
+            into = [];
+            inbound.set(target, into);
+        }
+
+        into.push(owning);
+
+        if (!owning) {
+            return;
+        }
+
+        let out = owning_out.get(source);
+
+        if (out === undefined) {
+            out = [];
+            owning_out.set(source, out);
+        }
+
+        out.push(edge);
+    };
+
+    for (let d = 0; d < databases.length; d++) {
+        const database = databases[d];
+        const links = database.definition.links;
+
+        for (let l = 0; l < links.length; l++) {
+            const link = links[l];
+            const source = database.tables[link.table.index];
+            const target_database = by_definition.get(link.target_database);
+
+            if (target_database === undefined) {
+                violations.push({
+                    reason: 'unresolved',
+                    database: database.label,
+                    table: link.table.name,
+                    row: -1,
+                    field: link.field,
+                    value: -1,
+                });
+
+                continue;
+            }
+
+            const target = target_database.tables[link.target_table.index];
+
+            note_declaration(source, target, link.owning, { link, range: null, target });
+
+            const occupancy = source.occupancy;
+
+            for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+                const value = source.get_word(row, link.word);
+
+                if (value === GPU_DATABASE_NULL) {
+                    if (!link.nullable) {
+                        violations.push({
+                            reason: 'null_in_required',
+                            database: database.label,
+                            table: link.table.name,
+                            row,
+                            field: link.field,
+                            value,
+                        });
+                    }
+
+                    continue;
+                }
+
+                if (!target.occupancy.get(value)) {
+                    violations.push({
+                        reason: 'dangling',
+                        database: database.label,
+                        table: link.table.name,
+                        row,
+                        field: link.field,
+                        value,
+                    });
+
+                    continue;
+                }
+
+                if (link.owning) {
+                    count_owner(target, value);
+                }
+            }
+        }
+
+        const ranges = database.definition.ranges;
+
+        for (let r = 0; r < ranges.length; r++) {
+            const range = ranges[r];
+            const source = database.tables[range.table.index];
+            const target_database = by_definition.get(range.target_database);
+
+            if (target_database === undefined) {
+                violations.push({
+                    reason: 'unresolved',
+                    database: database.label,
+                    table: range.table.name,
+                    row: -1,
+                    field: range.first_field,
+                    value: -1,
+                });
+
+                continue;
+            }
+
+            const target = target_database.tables[range.target_table.index];
+
+            note_declaration(source, target, range.owning, { link: null, range, target });
+
+            const occupancy = source.occupancy;
+
+            for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+                const first = source.get_word(row, range.first_word);
+                const count = source.get_word(row, range.count_word);
+
+                if (!gpu_table_range_well_formed(first, count, target.descriptor)) {
+                    violations.push({
+                        reason: 'malformed_range',
+                        database: database.label,
+                        table: range.table.name,
+                        row,
+                        field: range.first_field,
+                        value: first,
+                    });
+
+                    continue;
+                }
+
+                if (first === GPU_DATABASE_NULL) {
+                    continue;
+                }
+
+                // The live rows the run covers, found a bitset word at a time: a count of a million
+                // over three live rows costs three visits.
+                const end = first + count;
+                const covered = target.occupancy;
+
+                let live = 0;
+
+                for (let r = covered.nextSetBit(first); r !== -1 && r < end; r = covered.nextSetBit(r + 1)) {
+                    live++;
+
+                    if (range.owning) {
+                        count_owner(target, r);
+                    }
+                }
+
+                if (live < count) {
+                    violations.push({
+                        reason: 'dangling',
+                        database: database.label,
+                        table: range.table.name,
+                        row,
+                        field: range.first_field,
+                        value: covered.nextClearBit(first),
+                    });
+                }
+            }
+        }
+    }
+
+    // A table is owned-only when declarations point into it and every one of them owns. Its rows
+    // exist only for an owner; one that no owner reaches has leaked.
+    const owned_only = new Set();
+
+    for (const [table, owning] of inbound) {
+        if (owning.every(o => o)) {
+            owned_only.add(table);
+        }
+    }
+
+    // Walk the owning declarations out of every occupied row of every table that is not owned-only.
+    /**
+     * @type {Map<GPUTypedTable, Set<number>>}
+     */
+    const reached = new Map();
+
+    for (const table of owned_only) {
+        reached.set(table, new Set());
+    }
+
+    const stack = [];
+
+    for (const [source, edges] of owning_out) {
+        if (owned_only.has(source)) {
+            continue;
+        }
+
+        const occupancy = source.occupancy;
+
+        for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+            for (let i = 0; i < edges.length; i++) {
+                push_owned(source, row, edges[i], stack);
+            }
+        }
+    }
+
+    while (stack.length > 0) {
+        const value = /** @type {number} */ (stack.pop());
+        const table = /** @type {GPUTypedTable} */ (stack.pop());
+
+        if (value === GPU_DATABASE_NULL || !table.occupancy.get(value)) {
+            // reported above, where the declaration was read
+            continue;
+        }
+
+        const seen = reached.get(table);
+
+        if (seen === undefined || seen.has(value)) {
+            // a table that something else points into as well, or a row already walked from
+            continue;
+        }
+
+        seen.add(value);
+
+        const edges = owning_out.get(table);
+
+        if (edges === undefined) {
+            continue;
+        }
+
+        for (let i = 0; i < edges.length; i++) {
+            push_owned(table, value, edges[i], stack);
+        }
+    }
+
+    for (let d = 0; d < databases.length; d++) {
+        const database = databases[d];
+        const tables = database.tables;
+
+        for (let t = 0; t < tables.length; t++) {
+            const table = tables[t];
+            const counts = owner_counts.get(table);
+
+            if (counts !== undefined) {
+                const rows = Array.from(counts.keys()).sort((a, b) => a - b);
+
+                for (let i = 0; i < rows.length; i++) {
+                    const count = counts.get(rows[i]);
+
+                    if (count > 1) {
+                        violations.push({
+                            reason: 'owned_twice',
+                            database: database.label,
+                            table: table.descriptor.name,
+                            row: rows[i],
+                            field: '',
+                            value: count,
+                        });
+                    }
+                }
+            }
+
+            if (!owned_only.has(table)) {
+                continue;
+            }
+
+            const seen = reached.get(table);
+            const occupancy = table.occupancy;
+
+            for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+                if (!seen.has(row)) {
+                    violations.push({
+                        reason: 'orphan',
+                        database: database.label,
+                        table: table.descriptor.name,
+                        row,
+                        field: '',
+                        value: row,
+                    });
+                }
+            }
+        }
+    }
+
+    return violations;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The word offset, within one record of `type`, of the single `u32` word that `path` names.
+ *
+ * A path is a field name followed by any number of `.name` (into a struct) and `[i]` (into an array,
+ * or into one lane of a `u32` vector): `'node'`, `'joints[3].node'`, `'curves[2]'`. It has to end on
+ * exactly one `u32`: a vector, a struct or an array is refused, because a link is one word.
+ *
+ * Offsets come from the type as it is laid out — after `pack()` has reordered a struct — so a path
+ * names a field, never a position.
+ *
+ * @param {WebGPUType} type a table's record type
+ * @param {string} path
+ * @returns {number} offset from the start of the record, in {@link GPU_DATABASE_BUFFER_ELEMENT_TYPE} units
+ */
+export function gpu_table_field_word(type: WebGPUType, path: string): number;
+export type WebGPUType = import("../../shader/type/WebGPUType.js").WebGPUType;
+//# sourceMappingURL=gpu_table_field_word.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_table_field_word.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_table_field_word.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;GAaG;AACH,2CAJW,UAAU,QACV,MAAM,GACJ,MAAM,CA2ElB;yBAxGY,OAAO,iCAAiC,EAAE,UAAU"}