@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -2,6 +2,13 @@ import { assert } from "../../../../core/assert.js";
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
 import { BitSet } from "../../../../core/binary/BitSet.js";
 import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
+import {
+    U32_INDEX_MISS,
+    u32_index_clear,
+    u32_index_count,
+    u32_index_get,
+    u32_index_set,
+} from "../../../../core/collection/map/u32_index.js";
 import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buffer.js";
 import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
@@ -9,11 +16,13 @@ import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_
 import { GPU_DATABASE_UPLOAD_BUFFER_LIMIT } from "./GPU_DATABASE_UPLOAD_BUFFER_LIMIT.js";
 import { GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS } from "./GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js";
 import { GPUPageMetadata } from "./GPUPageMetadata.js";
+import { WordViews } from "./WordViews.js";
 
 /**
  * @typedef {import("./GPUTypedTableDescriptor.js").GPUTypedTableDescriptor} GPUTypedTableDescriptor
  * @typedef {import("./PageBufferPool.js").PageBufferPool} PageBufferPool
  * @typedef {import("../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ * @typedef {import("./serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
  */
 
 const SCRATCH_BUFFER = new BinaryBuffer();
@@ -27,11 +36,18 @@ const READ_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endiannes
 // top-level alignment round-up is a no-op.
 const WRITE_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endianness());
 
+/**
+ * Byte size of one {@link GPU_DATABASE_BUFFER_ELEMENT_TYPE} — the width every offset into the
+ * database, and into either upload stream, is counted in.
+ * @type {number}
+ */
+const WORD_SIZE = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+
 /**
  * Byte stride of one entry in {@link GPUTypedTable.partial_upload_descriptors}.
  * @type {number}
  */
-const PARTIAL_DESCRIPTOR_BYTES = GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS * GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+const PARTIAL_DESCRIPTOR_BYTES = GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS * WORD_SIZE;
 
 /**
  * Index of the `word_count` word within one partial-upload descriptor — the one word retiring a
@@ -54,34 +70,6 @@ function empty_upload_buffer() {
     return buffer;
 }
 
-/**
- * How far {@link GPUTypedTable.set} walks back through
- * {@link GPUTypedTable.element_upload_buffer} looking for an existing
- * record targeting the same element id.
- *
- * Two records aimed at the same row race in the upload compute shader —
- * shader threads run concurrently within a workgroup and the GPU is free
- * to retire them in any order, so "last writer wins" depends on schedule,
- * not buffer order. Scanning back 256 records covers a full 256-thread
- * workgroup of accumulated writes, which is enough to keep duplicates
- * within one dispatch unit out of the buffer.
- *
- * Cross-workgroup duplicates are still possible (a hot row touched once
- * per frame for many frames could in theory have stale entries spaced
- * further apart than this window). For our current usage that doesn't
- * happen in practice; if it ever does, swap this linear scan for a tiny
- * bloom filter or a sparse `id → record_offset` map.
- *
- * The partial-write stream took the map route from the start — see
- * {@link GPUTypedTable#set_bytes} — not because its hazard is worse but
- * because a row can own several ranges at once and every write has to
- * find all of them, so a scan deep enough to be safe would have cost
- * more than the feature saves.
- *
- * @type {number}
- */
-const UPLOAD_BUFFER_DEDUP_LOOKBACK = 256;
-
 /**
  * see "Rendering 'Assassin's Creed Shadows'" GDC 2025 by Nicolas Lopez
  * @template T
@@ -133,26 +121,80 @@ export class GPUTypedTable {
      * Index of the most recent pending descriptor for a row — the head of that row's chain
      * through {@link #partial_descriptor_previous}.
      *
-     * {@link set}'s dedupe can afford a backwards scan because it only ever looks for one record;
-     * a row here can own several descriptors at once, and every write has to find all of them. A
-     * scan deep enough to be safe would cost more than the whole feature saves, so the stream
-     * carries an index instead — which also makes reconciliation exact rather than windowed.
+     * A row can own several descriptors at once — that is the point, a caller updating three
+     * scattered fields should not pay for the span between them — and every write has to find all
+     * of them, which is why this was an index from the start rather than the backwards scan
+     * {@link set} used to run. {@link #pending_records} has since gone the same way.
      *
-     * Empty for a table that never takes a partial write, which is the only thing {@link set} and
+     * A row whose descriptors have all been retired holds `-1` rather than losing its slot, which
+     * {@link u32_index_get} reports as {@link U32_INDEX_MISS} — the same thing a row that never
+     * took a partial write reads as, and every site below wants them to mean the same thing.
+     *
+     * `null` for a table that never takes a partial write, which is the only thing {@link set} and
      * {@link remove} have to check.
      *
-     * @type {Map<number,number>}
+     * @type {Uint32Array|null}
      */
-    #partial_descriptor_head = new Map();
+    #partial_descriptor_head = null;
 
     /**
      * For descriptor `i`, the index of the previous pending descriptor targeting the same row, or
      * -1 at the end of the chain. Parallel to {@link partial_upload_descriptors}, and kept on this
      * side rather than in a fifth descriptor word so the GPU-side stride stays at four.
      *
-     * @type {number[]}
+     * Never cleared, and does not need to be: descriptor indices restart at zero each time the
+     * stream is dispatched, every descriptor writes its own entry as it is appended, and a chain
+     * is only ever walked from a head recorded during the frame doing the walking. A stale entry
+     * is therefore overwritten before anything can read it.
+     *
+     * @type {Int32Array}
      */
-    #partial_descriptor_previous = [];
+    #partial_descriptor_previous = new Int32Array(0);
+
+    /**
+     * Byte offset in {@link element_upload_buffer} of the whole record pending for a row, for
+     * every row that has one.
+     *
+     * Two records aimed at the same row race in the upload shader — each is consumed by its own
+     * thread within a single dispatch and the GPU retires threads in whatever order it likes — so
+     * the buffer must hold at most one record per row, and every write has to find the one already
+     * there. This was a backwards scan over the last 256 records, which is a window: deep enough
+     * to be safe and it costs more than the write it protects, shallow enough to be cheap and a
+     * hot row can slip a stale record past it. At a few hundred rows a frame the scan was most of
+     * what {@link set} did.
+     *
+     * An index is both cheaper and exact, and the exactness is worth more. {@link set_bytes} had
+     * one interleaving it could only resolve through that window — a range landing on a whole
+     * record queued further back than the scan reached — and it is gone: a row is now never live
+     * in both streams at once.
+     *
+     * A `u32_index` rather than a `Map`, because this one is cleared and refilled every frame and
+     * `Map.clear` drops its backing store each time. Over a frame of 300 rows that is worth about
+     * 9% of {@link set_record} and 19% at 3000, and rather more of the garbage: 105 collections
+     * against 43 across the same run. It is invisible in {@link set}, whose cost is the reflective
+     * type walk and not the bookkeeping around it.
+     *
+     * `null` until the table takes its first write.
+     *
+     * @type {Uint32Array|null}
+     */
+    #pending_records = null;
+
+    /**
+     * Word views over {@link element_upload_buffer}'s storage, for the generated record writers.
+     * Rebuilt by {@link WordViews} itself whenever the buffer grows out from under them.
+     *
+     * @type {WordViews}
+     */
+    #upload_words = new WordViews();
+
+    /**
+     * Word views over {@link partial_upload_data}'s storage, on the same terms as
+     * {@link #upload_words}.
+     *
+     * @type {WordViews}
+     */
+    #partial_words = new WordViews();
 
     /**
      * When a page is updated - it is marked as dirty.
@@ -169,6 +211,23 @@ export class GPUTypedTable {
      */
     occupancy = new BitSet();
 
+    /**
+     * Per row, how many times it has been freed — `null` until {@link track_generations}, so a
+     * table nothing reads back pays one null check per {@link remove} and no memory.
+     *
+     * Rows are reused the moment they are freed: {@link add} takes the lowest clear bit, exactly as
+     * `EntityComponentDataset.createEntity` does, so a free and an add in one frame leave occupancy
+     * as it was and put a stranger where an in-flight readback was aimed. The generation is what
+     * tells the two apart, and it lives here rather than with the reader because the table is the
+     * thing that reuses rows: every path that frees one moves it, and no caller has to remember to.
+     *
+     * The plan puts a real generation in the row's flags word once entities are rows; until then
+     * this is it.
+     *
+     * @type {Uint32Array|null}
+     */
+    #generations = null;
+
     /**
      * Pages whose GPU-side header (live_count + occupancy bitmap) is stale and
      * needs to be re-uploaded. Set when {@link occupancy} or
@@ -211,6 +270,22 @@ export class GPUTypedTable {
         return id;
     }
 
+    /**
+     * {@link add} through a generated writer — {@link set_record} is to {@link set} what this is to
+     * {@link add}.
+     *
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     * @returns {number} element index
+     */
+    add_record(value, writer) {
+        const id = this.occupancy.nextClearBit(0);
+
+        this.set_record(id, value, writer);
+
+        return id;
+    }
+
     /**
      * Remove an element from the table, freeing its slot.
      * The slot will be zero-filled in the CPU shadow and an upload will be queued.
@@ -227,6 +302,10 @@ export class GPUTypedTable {
 
         this.occupancy.set(element_index, false);
 
+        if (this.#generations !== null) {
+            this.#bump_generation(element_index);
+        }
+
         const page_index = Math.floor(element_index / this.descriptor.elements_per_page);
         const page = this.pages.get(page_index);
 
@@ -251,6 +330,54 @@ export class GPUTypedTable {
         }
     }
 
+    /**
+     * Start counting how many times each row is freed. Idempotent. Called by whoever reads rows
+     * back and needs to know whether the row it asked about is still the row that answered — see
+     * {@link generation_of}.
+     */
+    track_generations() {
+        if (this.#generations === null) {
+            this.#generations = new Uint32Array(Math.max(64, this.element_capacity));
+        }
+    }
+
+    /**
+     * How many times a row has been freed since {@link track_generations}. Zero for a table that
+     * is not tracking, and for a row never freed since.
+     *
+     * @param {number} row
+     * @returns {number}
+     */
+    generation_of(row) {
+        const generations = this.#generations;
+
+        if (generations === null || row >= generations.length) {
+            return 0;
+        }
+
+        return generations[row];
+    }
+
+    /**
+     * @param {number} row
+     */
+    #bump_generation(row) {
+        let generations = this.#generations;
+
+        if (row >= generations.length) {
+            const grown = new Uint32Array(Math.max(generations.length * 2, row + 1));
+
+            grown.set(generations);
+
+            generations = grown;
+            this.#generations = generations;
+        }
+
+        // wraps at 2^32, which needs a row to be freed four billion times before a reader of
+        // exactly that age could be fooled
+        generations[row] = (generations[row] + 1) >>> 0;
+    }
+
     /**
      * Reset every slot to free in one shot. Cheaper than calling
      * {@link remove} per element when the caller knows it's about to
@@ -268,6 +395,15 @@ export class GPUTypedTable {
             return;
         }
 
+        if (this.#generations !== null) {
+            // every occupied row is being freed, and each one will be reused
+            const occupancy = this.occupancy;
+
+            for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+                this.#bump_generation(row);
+            }
+        }
+
         this.occupancy.reset();
 
         for (const [page_index, page] of this.pages) {
@@ -279,39 +415,61 @@ export class GPUTypedTable {
     }
 
     /**
-     * Walk back up to {@link UPLOAD_BUFFER_DEDUP_LOOKBACK} records in the upload buffer
-     * looking for one targeting the given element.
+     * Byte offset of the whole record already pending for a row, or -1. One record per id is the
+     * invariant that keeps the upload shader race-free — see {@link #pending_records}.
      *
-     * On a hit the buffer position is left just past the matched record's u32 id (ready
-     * for the value bytes to be overwritten); on a miss the position is restored to the
-     * tail. One record per id is the invariant that keeps the upload shader race-free:
-     * each record is consumed by its own thread within a single dispatch, so two records
-     * for the same row would be last-writer-wins, non-deterministically.
+     * Also where a stream dispatched since the last write gets noticed. `GPUDatabase` rewinds
+     * {@link element_upload_buffer} by moving its position back to zero and tells nobody, so the
+     * index can outlive the records it points at. Every mutator consults this before appending —
+     * that is the invariant the staleness check rests on, and why it lives here rather than being
+     * repeated at each of the appends.
      *
      * @param {number} element_index
-     * @returns {number} byte offset of the matched record, or -1
+     * @returns {number} byte offset of the pending record, or -1
      */
-    #find_upload_record(element_index) {
-        const upload_buffer = this.element_upload_buffer;
+    #pending_record_offset(element_index) {
+        const pending = this.#pending_records;
 
-        const step_size = u32.size + this.descriptor.packed_element_size_bytes;
-        const tail = upload_buffer.position;
+        if (pending === null || u32_index_count(pending) === 0) {
+            return -1;
+        }
 
-        const max_lookback = Math.min(
-            UPLOAD_BUFFER_DEDUP_LOOKBACK,
-            Math.floor(tail / step_size),
-        );
+        if (this.element_upload_buffer.position === 0) {
+            // the stream was dispatched and rewound since these were recorded
+            u32_index_clear(pending);
 
-        for (let i = 1; i <= max_lookback; i++) {
-            const candidate_start = tail - i * step_size;
-            upload_buffer.position = candidate_start;
-            if (upload_buffer.readUint32() === element_index) {
-                return candidate_start;
-            }
+            return -1;
         }
 
-        upload_buffer.position = tail;
-        return -1;
+        return u32_index_get(pending, element_index);
+    }
+
+    /**
+     * The page holding a row, ready to be written through: allocated if the table has never
+     * reached that far, and given a CPU shadow if it was handed one without.
+     *
+     * @param {number} element_index
+     * @returns {GPUPageMetadata}
+     */
+    #page_for_write(element_index) {
+        const page_index = Math.floor(element_index / this.descriptor.elements_per_page);
+
+        let page = this.pages.get(page_index);
+
+        if (page === undefined) {
+            page = this.#allocate_page(page_index);
+        }
+
+        if (page.cpu_data_buffer === undefined) {
+            // Materialize CPU buffer on demand (e.g. pre-allocated stub from GPUDatabase)
+            const pool = this.page_buffer_pool;
+
+            page.cpu_data_buffer = pool !== undefined
+                ? pool.acquire().buffer
+                : new ArrayBuffer(this.descriptor.page_byte_size);
+        }
+
+        return page;
     }
 
     /**
@@ -331,13 +489,16 @@ export class GPUTypedTable {
         // must not leave both the old value record and this zero record alive in one
         // dispatch, or the GPU row becomes schedule-dependent.
         const tail = upload_buffer.position;
-        const existing_record = this.#find_upload_record(element_index);
+        const existing_record = this.#pending_record_offset(element_index);
 
         if (existing_record >= 0) {
-            // position is just past the matched record's id; zero its value bytes
+            // zero the matched record's value bytes, leaving its id alone
+            upload_buffer.position = existing_record + u32.size;
+
             for (let i = 0; i < word_count; i++) {
                 upload_buffer.writeUint32(0);
             }
+
             upload_buffer.position = tail;
             return;
         }
@@ -346,6 +507,8 @@ export class GPUTypedTable {
         for (let i = 0; i < word_count; i++) {
             upload_buffer.writeUint32(0);
         }
+
+        this.#pending_records = u32_index_set(this.#pending_records, element_index, tail);
     }
 
     /**
@@ -494,29 +657,12 @@ export class GPUTypedTable {
         const type = this.descriptor.type;
 
         // write to the local page if resident
-        const page_index = Math.floor(element_index / this.descriptor.elements_per_page);
-        let page = this.pages.get(page_index);
-
-
-        if (page === undefined) {
-            // allocate page
-            page = this.#allocate_page(page_index);
-        }
+        const page = this.#page_for_write(element_index);
 
         // Track occupancy: only increment if slot was previously free
         const was_occupied = this.occupancy.get(element_index);
         this.occupancy.set(element_index, true);
 
-        if (page.cpu_data_buffer === undefined) {
-            // Materialize CPU buffer on demand (e.g. pre-allocated stub from GPUDatabase)
-            const pool = this.page_buffer_pool;
-            if (pool !== undefined) {
-                page.cpu_data_buffer = pool.acquire().buffer;
-            } else {
-                page.cpu_data_buffer = new ArrayBuffer(this.descriptor.page_byte_size);
-            }
-        }
-
         // page is resident, write to the CPU data
         const record_size = this.descriptor.packed_element_size_bytes;
         SCRATCH_BUFFER.fromArrayBuffer(page.cpu_data_buffer);
@@ -528,7 +674,7 @@ export class GPUTypedTable {
 
         if (!was_occupied) {
             page.occupancy_count++;
-            this.header_dirty_pages.set(page_index, true);
+            this.header_dirty_pages.set(page.index, true);
         }
 
         // write to the upload buffer.
@@ -537,14 +683,14 @@ export class GPUTypedTable {
         // the full stride after writing, since write_wgsl_type_value does
         // not pad to type.size when the last field ends earlier.
         //
-        // Before appending, walk back UPLOAD_BUFFER_DEDUP_LOOKBACK records
-        // looking for an entry with the same id. If we find one, overwrite
-        // its value bytes in place and leave the tail where it was — that
-        // way the upload shader sees only the latest value per row, which
-        // matters because two records targeting the same slot race within
-        // a workgroup (last-writer-wins is non-deterministic). The CPU
-        // shadow above is already idempotent w.r.t. repeated set() calls,
-        // so the GPU side is the only thing that needed the dedupe.
+        // Before appending, ask the index whether this row already has a
+        // record queued. If it does, overwrite its value bytes in place and
+        // leave the tail where it was — that way the upload shader sees only
+        // the latest value per row, which matters because two records
+        // targeting the same slot race within a workgroup (last-writer-wins
+        // is non-deterministic). The CPU shadow above is already idempotent
+        // w.r.t. repeated set() calls, so the GPU side is the only thing that
+        // needed the dedupe.
         //
         // A whole record also supersedes any sub-record range queued for this row earlier in the
         // frame — see set_bytes for the ordering rules across the two streams.
@@ -555,14 +701,15 @@ export class GPUTypedTable {
         const step_size = value_offset + record_size;
         const tail = upload_buffer.position;
 
-        const dedup_record_start = this.#find_upload_record(element_index);
+        const dedup_record_start = this.#pending_record_offset(element_index);
 
         if (dedup_record_start >= 0) {
-            // Overwrite the existing record's value section. Position is
-            // already past its u32 id from the lookup, so we can write the
-            // value directly. Restore the tail so subsequent writes still
-            // append at the end.
+            // Overwrite the existing record's value section, then restore the tail so subsequent
+            // writes still append at the end.
+            upload_buffer.position = dedup_record_start + value_offset;
+
             write_wgsl_type_value(value, upload_buffer, type);
+
             upload_buffer.position = tail;
         } else {
             // Reserve the whole stride up front. The writes below only reach the last
@@ -574,9 +721,91 @@ export class GPUTypedTable {
             upload_buffer.writeUint32(element_index);
             write_wgsl_type_value(value, upload_buffer, type);
             upload_buffer.position = tail + step_size;
+
+            this.#pending_records = u32_index_set(this.#pending_records, element_index, tail);
         }
     }
 
+    /**
+     * Write a whole record through a writer generated for its type, instead of walking the type
+     * on every call.
+     *
+     * Same contract as {@link set} in every other respect — the row is created if the table has
+     * never held it, the CPU shadow is patched, and the record joins the whole-record upload
+     * stream — and the bytes it leaves behind are the same ones. What changes is the cost: the
+     * field offsets are constants inside {@link GPURecordWriter.write_record} rather than
+     * something rediscovered per field per row, and the shadow and the queued record are written
+     * through views rather than a `BinaryBuffer` cursor.
+     *
+     * A writer naming only some of the type's fields is legal here and means what it says: the
+     * rest of the record keeps whatever the shadow held, and so does the queued record. That is
+     * rarely what a caller wants from *this* method, though — a partial writer belongs in
+     * {@link set_fields}, which uploads only the bytes it wrote.
+     *
+     * @param {number} element_index
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     */
+    set_record(element_index, value, writer) {
+        assert.isNonNegativeInteger(element_index, 'element_index');
+        assert.defined(writer, 'writer');
+        // The message names no type: `WebGPUType.toString` rebuilds the struct's whole WGSL
+        // declaration, and an interpolation is evaluated whether the assertion holds or not — which
+        // put a code generator on the per-row write path, where a writer exists to take one off.
+        assert.equal(writer.type, this.descriptor.type, `writer was generated against a type other than '${this.descriptor.name}''s — its field offsets would land anywhere in a record of this one`);
+
+        const descriptor = this.descriptor;
+        const record_size = descriptor.packed_element_size_bytes;
+
+        const page = this.#page_for_write(element_index);
+
+        const was_occupied = this.occupancy.get(element_index);
+        this.occupancy.set(element_index, true);
+
+        const in_page_index = element_index % descriptor.elements_per_page;
+        const shadow = page.words.over(page.cpu_data_buffer);
+
+        writer.write_record(
+            shadow.f32,
+            shadow.u32,
+            (page.cpu_data_address + in_page_index * record_size) / WORD_SIZE,
+            value
+        );
+
+        page.cpu_version++;
+
+        if (!was_occupied) {
+            page.occupancy_count++;
+            this.header_dirty_pages.set(page.index, true);
+        }
+
+        // A whole record supersedes any range queued for the row earlier in the frame.
+        this.#retire_partial_records(element_index);
+
+        const upload_buffer = this.element_upload_buffer;
+        const step_size = u32.size + record_size;
+        const tail = upload_buffer.position;
+
+        let record_start = this.#pending_record_offset(element_index);
+
+        if (record_start < 0) {
+            // Reserve the whole stride before taking views over the buffer — this is the call
+            // that can move the storage they would be over.
+            upload_buffer.ensureCapacity(tail + step_size);
+
+            upload_buffer.writeUint32(element_index);
+            upload_buffer.position = tail + step_size;
+
+            this.#pending_records = u32_index_set(this.#pending_records, element_index, tail);
+
+            record_start = tail;
+        }
+
+        const upload = this.#upload_words.over(upload_buffer.data);
+
+        writer.write_record(upload.f32, upload.u32, (record_start + u32.size) / WORD_SIZE, value);
+    }
+
     /**
      * Overwrite one field (or sub-struct) of an existing record, leaving the rest of it untouched
      * — on the CPU shadow and on the GPU alike.
@@ -638,11 +867,8 @@ export class GPUTypedTable {
      * the GPU is free to retire threads in any order. In append order:
      *
      * - **partial after whole-record** — the pending whole record is patched in place and nothing
-     *   is appended, so the row is not in both streams at once. This is the one case bounded by
-     *   {@link UPLOAD_BUFFER_DEDUP_LOOKBACK}, since it borrows {@link set}'s backwards scan. A
-     *   whole record further back than the window is missed and the range is queued beside it —
-     *   still correct, because {@link GPUDatabase.update} dispatches a table's whole records
-     *   before its ranges, so the range lands on top of the record exactly as append order said.
+     *   is appended, so the row is not in both streams at once. The record is found through
+     *   {@link #pending_records}, so it is found however long ago it was queued.
      * - **whole-record after partial** — {@link set} retires the row's pending descriptors (blanks
      *   their word count, making those threads no-ops); the whole record supersedes them.
      * - **partial after partial, the same range or a sub-range of a pending one** — the pending
@@ -653,8 +879,8 @@ export class GPUTypedTable {
      *   are retired and one covering their union is appended, its words read back out of the CPU
      *   shadow, which is already correct by then.
      *
-     * Every case but the first is exact rather than windowed: a row's pending descriptors are
-     * indexed by id, so they are found however long the stream has grown.
+     * Every one of those is exact rather than windowed: both streams index a row's pending
+     * entries by id, so they are found however long either stream has grown.
      *
      * @param {number} element_index row to patch; must already be occupied
      * @param {number} byte_offset offset of the range within the record, 4-byte aligned
@@ -670,10 +896,8 @@ export class GPUTypedTable {
 
         const descriptor = this.descriptor;
         const record_size = descriptor.packed_element_size_bytes;
-        const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
-
-        assert.equal(byte_offset % word_size, 0, `byte_offset (${byte_offset}) must be a multiple of ${word_size} — the database buffer is an array<u32> and a partial write is not masked`);
-        assert.equal(byte_length % word_size, 0, `byte_length (${byte_length}) must be a multiple of ${word_size} — the database buffer is an array<u32> and a partial write is not masked`);
+        assert.equal(byte_offset % WORD_SIZE, 0, `byte_offset (${byte_offset}) must be a multiple of ${WORD_SIZE} — the database buffer is an array<u32> and a partial write is not masked`);
+        assert.equal(byte_length % WORD_SIZE, 0, `byte_length (${byte_length}) must be a multiple of ${WORD_SIZE} — the database buffer is an array<u32> and a partial write is not masked`);
         assert.lessThanOrEqual(byte_offset + byte_length, record_size, `range [${byte_offset}, ${byte_offset + byte_length}) reaches past the end of a ${record_size} byte record of '${descriptor.name}'`);
 
         assert.ok(this.occupancy.get(element_index), `element ${element_index} of '${descriptor.name}' is not occupied — a partial write patches a record, it does not create one`);
@@ -715,10 +939,7 @@ export class GPUTypedTable {
         // A pending whole record for this row wins the frame outright: patch its bytes and append
         // nothing, so the row stays in exactly one stream.
         const upload_buffer = this.element_upload_buffer;
-        const upload_tail = upload_buffer.position;
-        const pending_record = this.#find_upload_record(element_index);
-
-        upload_buffer.position = upload_tail;
+        const pending_record = this.#pending_record_offset(element_index);
 
         if (pending_record >= 0) {
             new Uint8Array(upload_buffer.data, pending_record + u32.size + byte_offset, byte_length)
@@ -727,7 +948,163 @@ export class GPUTypedTable {
             return;
         }
 
-        this.#stage_partial_range(element_index, byte_offset / word_size, byte_length / word_size, record_bytes);
+        this.#stage_partial_range(element_index, byte_offset / WORD_SIZE, byte_length / WORD_SIZE, record_bytes);
+    }
+
+    /**
+     * Patch the fields a generated writer owns, on the CPU shadow and on the GPU, and leave the
+     * rest of the record alone — {@link set_bytes} for a struct whose owned fields are known at
+     * generation time rather than named per call.
+     *
+     * The point is the bookkeeping, not the stores. `set_bytes` has to treat every range as an
+     * event of its own: a page lookup, a record view, a pending-record check, a chain walk, a
+     * descriptor append. A caller patching a struct's two CPU-owned blocks through it pays all of
+     * that twice, which measured at roughly double one range's cost rather than the few extra
+     * words the second range actually is. A writer knows both ranges belong to one row's update
+     * before the call starts, so this pays for the row once: the fields reach the shadow and the
+     * stream's data blob in a single pass over the value, and the descriptors go out together.
+     *
+     * The ordering rules across the two streams are {@link set_bytes}'s and are followed exactly
+     * — a row's update lands on a pending whole record if there is one, and joins ranges already
+     * queued for the row through the same merge, one range at a time, because what to do with an
+     * overlap is a property of what is pending and not of the writer.
+     *
+     * The row must already be occupied, for the reason a partial write always must: it patches a
+     * record, it does not create one.
+     *
+     * @param {number} element_index
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     */
+    set_fields(element_index, value, writer) {
+        assert.isNonNegativeInteger(element_index, 'element_index');
+        assert.defined(writer, 'writer');
+        // Naming no type in the message is deliberate — see `set_record`.
+        assert.equal(writer.type, this.descriptor.type, `writer was generated against a type other than '${this.descriptor.name}''s — its field offsets would land anywhere in a record of this one`);
+
+        const descriptor = this.descriptor;
+        const record_size = descriptor.packed_element_size_bytes;
+        const elements_per_page = descriptor.elements_per_page;
+
+        const page = this.pages.get(Math.floor(element_index / elements_per_page));
+
+        assert.ok(this.occupancy.get(element_index), `element ${element_index} of '${descriptor.name}' is not occupied — a partial write patches a record, it does not create one`);
+        assert.defined(page, `page of element ${element_index} of '${descriptor.name}'`);
+        assert.defined(page.cpu_data_buffer, `page ${page.index} of '${descriptor.name}' has no CPU shadow — a partial write cannot run against an unmapped page`);
+
+        const record_byte_base = page.cpu_data_address + (element_index % elements_per_page) * record_size;
+        const record_word_base = record_byte_base / WORD_SIZE;
+
+        const shadow = page.words.over(page.cpu_data_buffer);
+
+        const pending_record = this.#pending_record_offset(element_index);
+
+        if (pending_record >= 0) {
+            // A whole record for this row is already queued: patch it where it lies, append
+            // nothing, and the row stays in exactly one stream.
+            writer.write_record(shadow.f32, shadow.u32, record_word_base, value);
+
+            const upload = this.#upload_words.over(this.element_upload_buffer.data);
+
+            writer.write_record(upload.f32, upload.u32, (pending_record + u32.size) / WORD_SIZE, value);
+
+            page.cpu_version++;
+
+            return;
+        }
+
+        const ranges = writer.ranges;
+
+        if (this.#partial_descriptor_head !== null && u32_index_get(this.#partial_descriptor_head, element_index) !== U32_INDEX_MISS) {
+            // The row already owns ranges this frame. Whether each of ours patches one in place or
+            // has to absorb it into a union depends on what is pending, not on the writer, so the
+            // ranges go through the general path one at a time.
+            writer.write_record(shadow.f32, shadow.u32, record_word_base, value);
+
+            page.cpu_version++;
+
+            const record_bytes = new Uint8Array(page.cpu_data_buffer, record_byte_base, record_size);
+
+            for (let i = 0; i < ranges.length; i += 2) {
+                this.#stage_partial_range(element_index, ranges[i] / WORD_SIZE, ranges[i + 1] / WORD_SIZE, record_bytes);
+            }
+
+            return;
+        }
+
+        const descriptors = this.partial_upload_descriptors;
+        const data = this.partial_upload_data;
+
+        const descriptor_tail = descriptors.position;
+        const data_tail = data.position;
+        const data_byte_count = writer.range_word_count * WORD_SIZE;
+
+        // Both reservations happen before the views are taken: growing is what moves the storage
+        // they would otherwise be over.
+        descriptors.ensureCapacity(descriptor_tail + (ranges.length / 2) * PARTIAL_DESCRIPTOR_BYTES);
+        data.ensureCapacity(data_tail + data_byte_count);
+
+        const blob = this.#partial_words.over(data.data);
+        const data_word_base = data_tail / WORD_SIZE;
+
+        writer.write_record_and_ranges(
+            shadow.f32, shadow.u32, record_word_base,
+            blob.f32, blob.u32, data_word_base,
+            value
+        );
+
+        page.cpu_version++;
+
+        data.position = data_tail + data_byte_count;
+
+        const previous = this.#previous_capacity(
+            descriptor_tail / PARTIAL_DESCRIPTOR_BYTES + ranges.length / 2
+        );
+
+        let head = -1;
+        let range_word = data_word_base;
+
+        descriptors.position = descriptor_tail;
+
+        for (let i = 0; i < ranges.length; i += 2) {
+            const word_count = ranges[i + 1] / WORD_SIZE;
+
+            descriptors.writeUint32(element_index);
+            descriptors.writeUint32(ranges[i] / WORD_SIZE);
+            descriptors.writeUint32(word_count);
+            descriptors.writeUint32(range_word);
+
+            const index = descriptor_tail / PARTIAL_DESCRIPTOR_BYTES + i / 2;
+
+            previous[index] = head;
+            head = index;
+
+            range_word += word_count;
+        }
+
+        this.#partial_descriptor_head = u32_index_set(this.#partial_descriptor_head, element_index, head);
+    }
+
+    /**
+     * {@link #partial_descriptor_previous}, guaranteed to hold at least `count` entries.
+     *
+     * @param {number} count
+     * @returns {Int32Array}
+     */
+    #previous_capacity(count) {
+        const previous = this.#partial_descriptor_previous;
+
+        if (count <= previous.length) {
+            return previous;
+        }
+
+        const grown = new Int32Array(Math.max(64, previous.length * 2, count));
+
+        grown.set(previous);
+
+        this.#partial_descriptor_previous = grown;
+
+        return grown;
     }
 
     /**
@@ -743,16 +1120,17 @@ export class GPUTypedTable {
         const descriptors = this.partial_upload_descriptors;
         const data = this.partial_upload_data;
         const previous = this.#partial_descriptor_previous;
-        const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
-
         const tail = descriptors.position;
-        const head = this.#partial_descriptor_head.get(element_index);
+        // -1 whether the row never had a chain or had one retired — see #partial_descriptor_head
+        const head = this.#partial_descriptor_head === null
+            ? U32_INDEX_MISS
+            : u32_index_get(this.#partial_descriptor_head, element_index);
 
         let lo = word_offset;
         let hi = word_offset + word_count;
         let overlaps = false;
 
-        for (let i = head === undefined ? -1 : head; i >= 0; i = previous[i]) {
+        for (let i = head; i >= 0; i = previous[i]) {
             descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + u32.size;
 
             const candidate_lo = descriptors.readUint32();
@@ -773,8 +1151,8 @@ export class GPUTypedTable {
 
                 descriptors.position = tail;
 
-                new Uint8Array(data.data, (candidate_data + (lo - candidate_lo)) * word_size, word_count * word_size)
-                    .set(record_bytes.subarray(lo * word_size, hi * word_size));
+                new Uint8Array(data.data, (candidate_data + (lo - candidate_lo)) * WORD_SIZE, word_count * WORD_SIZE)
+                    .set(record_bytes.subarray(lo * WORD_SIZE, hi * WORD_SIZE));
 
                 return;
             }
@@ -791,7 +1169,7 @@ export class GPUTypedTable {
         for (let absorbing = overlaps; absorbing;) {
             absorbing = false;
 
-            for (let i = head === undefined ? -1 : head; i >= 0; i = previous[i]) {
+            for (let i = head; i >= 0; i = previous[i]) {
                 descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + u32.size;
 
                 const candidate_lo = descriptors.readUint32();
@@ -820,11 +1198,11 @@ export class GPUTypedTable {
 
         descriptors.position = tail;
 
-        const data_offset = data.position / word_size;
+        const data_offset = data.position / WORD_SIZE;
 
         // The words come out of the shadow rather than out of the caller's `source`, so a union
         // wider than what this call supplied still carries the right values.
-        data.writeBytes(record_bytes, lo * word_size, (hi - lo) * word_size);
+        data.writeBytes(record_bytes, lo * WORD_SIZE, (hi - lo) * WORD_SIZE);
 
         descriptors.writeUint32(element_index);
         descriptors.writeUint32(lo);
@@ -833,8 +1211,8 @@ export class GPUTypedTable {
 
         const index = tail / PARTIAL_DESCRIPTOR_BYTES;
 
-        previous[index] = head === undefined ? -1 : head;
-        this.#partial_descriptor_head.set(element_index, index);
+        this.#previous_capacity(index + 1)[index] = head;
+        this.#partial_descriptor_head = u32_index_set(this.#partial_descriptor_head, element_index, index);
     }
 
     /**
@@ -849,13 +1227,13 @@ export class GPUTypedTable {
     #retire_partial_records(element_index) {
         const heads = this.#partial_descriptor_head;
 
-        if (heads.size === 0) {
+        if (heads === null) {
             return;
         }
 
-        const head = heads.get(element_index);
+        const head = u32_index_get(heads, element_index);
 
-        if (head === undefined) {
+        if (head === U32_INDEX_MISS) {
             return;
         }
 
@@ -870,7 +1248,9 @@ export class GPUTypedTable {
 
         descriptors.position = tail;
 
-        heads.delete(element_index);
+        // retired rather than removed: blanking the slot would cut the probe chains running
+        // through it, and -1 already reads back as absent
+        this.#partial_descriptor_head = u32_index_set(heads, element_index, -1);
     }
 
     /**
@@ -881,8 +1261,11 @@ export class GPUTypedTable {
         this.partial_upload_descriptors.position = 0;
         this.partial_upload_data.position = 0;
 
-        this.#partial_descriptor_head.clear();
-        this.#partial_descriptor_previous.length = 0;
+        if (this.#partial_descriptor_head !== null) {
+            u32_index_clear(this.#partial_descriptor_head);
+        }
+
+        // #partial_descriptor_previous needs no clearing — see its declaration
     }
 
     /**
@@ -940,15 +1323,15 @@ export class GPUTypedTable {
         assert.isNonNegativeInteger(offset, 'offset');
 
         const occupancy = this.occupancy;
-        const capacity = this.element_capacity;
 
         let written = 0;
 
-        for (let i = 0; i < capacity; i++) {
-            if (occupancy.get(i)) {
-                target[offset + written] = i;
-                written++;
-            }
+        // Word by word rather than bit by bit: rows can sit a long way above the live ones — an
+        // entity's row is its id, and a band of node rows sits above every entity — and the
+        // stretch between costs a word read per thirty-two rows rather than a read per row.
+        for (let i = occupancy.nextSetBit(0); i !== -1; i = occupancy.nextSetBit(i + 1)) {
+            target[offset + written] = i;
+            written++;
         }
 
         assert.equal(written, this.count, 'occupied slot scan disagreed with the table count');