@woosh/meep-engine 3.28.0 → 3.30.0

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.js

@@ -4,12 +4,8 @@ import {
     allocator_run_size_for,
     OffsetAllocator
 } from "../../../../core/binary/allocator/OffsetAllocator.js";
-import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
-import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
 import Signal from "../../../../core/events/signal/Signal.js";
 import { MEGABYTE } from "../../../../core/science/units/memory/MEGABYTE.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 { inspect_gpu_buffer_typed } from "../../buffer/inspect_gpu_buffer_typed.js";
 import {
     BUFFER_INTRA_COPY_REGION_STRUCT,
@@ -50,6 +46,121 @@ const DEFAULT_DATA_CAPACITY = 32 * MEGABYTE;
  */
 const ALLOCATION_LIMIT = 128 * 1024;
 
+/**
+ * Where a row's `address` sits, in words. The patch that places a batch adds the allocation offset
+ * to this word of every row and copies the rest as bytes — which is only right while the row is
+ * packed and the field is where the struct says (`GPUMeshletManager.spec.js` pins both).
+ * @type {number}
+ */
+const METADATA_ROW_WORDS = MESHLET_METADATA_STRUCT.aligned_size >>> 2;
+
+/**
+ * The most records one {@link GPUMeshletManager#sweep} moves. A move is an O(1) slide in the
+ * allocator, four copy encodes, `meshlet_count` pairs in a patch table and one `changed`
+ * dispatch, so this bounds the main-thread cost of a sweep per frame by a count that does not
+ * grow with the resident set (COMPACTION_PLAN_2026_09_16 §3, §4.3).
+ * @type {number}
+ */
+export const MESHLET_SWEEP_MOVE_BUDGET = 64;
+
+/**
+ * The most words one sweep copies, data and rows together — 4 MB of GPU copy through the staging
+ * buffer. Whichever of the two budgets is met first ends the call, but never before one move
+ * when one is possible: a single record larger than this still moves, once.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_WORD_BUDGET = 1024 * 1024;
+
+/**
+ * The most cursor steps one sweep takes, moves or not. A step that moves nothing — a hole the
+ * cursor was stepped back for that an allocation has since filled — is a link walk.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_STEP_BUDGET = 4096;
+
+/**
+ * A removal that leaves at least this much of an arena free *in pieces* — free space less the
+ * largest free run — and at least an eighth of the arena that way, arms the sweep by itself.
+ *
+ * A sweep armed only by a refusal reclaims the space after the growth it could have prevented,
+ * and the next fill carves that tail before the next large arrival. Armed on scatter, the tail
+ * is clear by the time something needs it, at a cost bounded per frame as ever and proportional
+ * to the churn in total. Under a churn of one class the holes are recycled as fast as they are
+ * made and the scatter stays below the eighth; this is for a pool that thins.
+ * In words for the data arena; the row arena's floor is {@link MESHLET_SWEEP_SCATTER_MINIMUM_ROWS}.
+ * @type {number}
+ */
+export const MESHLET_SWEEP_SCATTER_MINIMUM_WORDS = 16 * 1024;
+
+/**
+ * @type {number}
+ */
+export const MESHLET_SWEEP_SCATTER_MINIMUM_ROWS = 512;
+const METADATA_ADDRESS_WORD = MESHLET_METADATA_STRUCT.fields.find(f => f.name === 'address').offset >>> 2;
+
+/**
+ * What the manager has done to its arenas, for a bench, a tour or an overlay to read without
+ * reaching inside. A rebuild is the O(all batches) event the compaction plan is about; a growth
+ * is the bounded alternative; the sweep counters are COMPACTION_PLAN_2026_09_16 §4.7's.
+ */
+class GPUMeshletManagerStats {
+    growths = 0;
+    rebuilds = 0;
+    moves = 0;
+    sweeps_armed = 0;
+    sweeps_completed = 0;
+    moves_last_sweep = 0;
+}
+
+/**
+ * One arena's compaction state. An episode is armed by a fragmentation refusal and ended by the
+ * sweep reaching the arena's end or by a rebuild; `grew` says whether the episode has spent its
+ * one growth (plan §4.4).
+ */
+class ArenaSweep {
+    armed = false;
+    grew = false;
+
+    /**
+     * The used node the current pass considers next. {@link ALLOCATOR_NO_SPACE} when no pass is
+     * running.
+     * @type {number}
+     */
+    cursor = ALLOCATOR_NO_SPACE;
+
+    /**
+     * Where the next pass starts: the used node after the lowest hole opened since the current
+     * pass went by it — or, with no pass running, since the arena was last packed. Kept by every
+     * removal, so a pass needs no walk to find its first hole. {@link ALLOCATOR_NO_SPACE} when
+     * nothing is known to be behind a hole.
+     *
+     * A pass does not step back for a hole opened below it: under a pool that thins fast, every
+     * removal would send the cursor back below the records it had just packed, and the pass
+     * would never reach the end. It finishes, then a second pass from here closes every hole the
+     * first one left behind in one walk — the holes gather into one bubble whichever pass slides
+     * over them.
+     * @type {number}
+     */
+    restart = ALLOCATOR_NO_SPACE;
+
+    /**
+     * Records moved in the current episode.
+     * @type {number}
+     */
+    moves = 0;
+}
+
+/**
+ * One record's move in one arena, as the sweep recorded it: where the range was, where it is,
+ * both in that arena's elements.
+ */
+class ArenaMove {
+    /** @type {MeshletBatchAllocationRecord} */
+    record;
+    from = 0;
+    to = 0;
+}
+
 class MeshletBatchAllocationRecord {
     /**
      * @type {Allocation}
@@ -123,10 +234,76 @@ export class GPUMeshletManager {
     #device;
 
     /**
-     *
+     * Node budget both allocators are built with; a rebuild re-picks the larger of this and twice
+     * the live batch count.
      * @type {number}
      */
-    #deallocations_since_last_rebuild = 0;
+    #allocation_limit = ALLOCATION_LIMIT;
+
+    /**
+     * The state of the compaction of each arena (COMPACTION_PLAN_2026_09_16 §4.3–4.4).
+     * @type {ArenaSweep}
+     */
+    #sweep_data = new ArenaSweep();
+
+    /**
+     * @type {ArenaSweep}
+     */
+    #sweep_metadata = new ArenaSweep();
+
+    /**
+     * What the sweep needs of an arena, gathered so the two are one code path: its sweep state,
+     * its live records by the allocator node that describes their range (a used node's index is
+     * stable until it is freed, and a freed one is immediately reused — so the map is kept by one
+     * release path and the sweep asserts on it), and how to read a record's range in it.
+     */
+    #arena_data = {
+        sweep: this.#sweep_data,
+        /** @type {Map<number, MeshletBatchAllocationRecord>} */
+        records: new Map(),
+        allocator: () => this.#allocator_data,
+        /** @param {MeshletBatchAllocationRecord} record @returns {Allocation} */
+        allocation_of: record => record.data,
+        /** @param {MeshletBatchAllocationRecord} record @returns {number} true elements */
+        elements_of: record => record.data_size,
+        element_words: 1,
+        scatter_minimum: MESHLET_SWEEP_SCATTER_MINIMUM_WORDS,
+    };
+
+    #arena_metadata = {
+        sweep: this.#sweep_metadata,
+        /** @type {Map<number, MeshletBatchAllocationRecord>} */
+        records: new Map(),
+        allocator: () => this.#allocator_metadata,
+        /** @param {MeshletBatchAllocationRecord} record @returns {Allocation} */
+        allocation_of: record => record.metadata,
+        /** @param {MeshletBatchAllocationRecord} record @returns {number} true elements */
+        elements_of: record => record.meshlet_count,
+        element_words: METADATA_ROW_WORDS,
+        scatter_minimum: MESHLET_SWEEP_SCATTER_MINIMUM_ROWS,
+    };
+
+    /**
+     * The command context the last {@link sweep} recorded moves into, while it has not finished.
+     * A recorded copy names the range a record left; an arrival placed there in the meantime is
+     * uploaded ahead of the copy, and a growth or rebuild destroys the buffer the copy names — so
+     * nothing may allocate, free, grow or rebuild until that context has been submitted
+     * (COMPACTION_PLAN_2026_09_16 §4.3.1, §5).
+     * @type {ShadeGPUCommandContext|null}
+     */
+    #moving_ctx = null;
+
+    /**
+     * @type {GPUMeshletManagerStats}
+     */
+    #stats = new GPUMeshletManagerStats();
+
+    /**
+     * @returns {Readonly<GPUMeshletManagerStats>}
+     */
+    get stats() {
+        return this.#stats;
+    }
 
     /**
      * Every live allocation, in the order it was made — which is the order a rebuild packs them in.
@@ -167,26 +344,32 @@ export class GPUMeshletManager {
      * @param {GPUDevice} options.device
      * @param {number} [options.initial_data_capacity] in bytes
      * @param {number} [options.initial_metadata_capacity] in meshlets
+     * @param {number} [options.allocation_limit] node budget of each arena — the most ranges, live
+     *        and free together, either can describe. Growth never raises it; a rebuild re-picks it.
      */
     constructor({
                     device,
                     initial_data_capacity = DEFAULT_DATA_CAPACITY,
                     initial_metadata_capacity = DEFAULT_METADATA_CAPACITY,
+                    allocation_limit = ALLOCATION_LIMIT,
                 }) {
         assert.defined(device, 'device');
 
         assert.isNonNegativeInteger(initial_data_capacity, 'initial_data_capacity');
         assert.isNonNegativeInteger(initial_metadata_capacity, 'initial_metadata_capacity');
+        assert.isNonNegativeInteger(allocation_limit, 'allocation_limit');
 
         assert.greaterThan(initial_data_capacity, 0, 'initial_data_capacity');
         assert.greaterThan(initial_metadata_capacity, 0, 'initial_data_capacity');
+        assert.greaterThan(allocation_limit, 0, 'allocation_limit');
 
         this.#device = device;
+        this.#allocation_limit = allocation_limit;
 
         const data_buffer_size_words = Math.ceil(initial_data_capacity / 4);
 
-        this.#allocator_data = new OffsetAllocator(data_buffer_size_words, ALLOCATION_LIMIT);
-        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity, ALLOCATION_LIMIT);
+        this.#allocator_data = new OffsetAllocator(data_buffer_size_words, allocation_limit);
+        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity, allocation_limit);
 
         this.#meshlet_data_buffer = device.createBuffer({
             label: 'GPUMeshletManager/data',
@@ -203,6 +386,8 @@ export class GPUMeshletManager {
     }
 
     compact() {
+        this.#assert_not_moving();
+
         this.#rebuild(
             this.#meshlet_data_buffer.size >>> 2,
             Math.ceil(this.#meshlet_metadata_buffer.size / MESHLET_METADATA_STRUCT.aligned_size)
@@ -218,8 +403,8 @@ export class GPUMeshletManager {
      * re-patching, and no {@link MeshletBatchAllocationRecord#changed} fires. Compare {@link compact},
      * which makes room by re-packing instead, and pays all three of those for every record it moves.
      *
-     * Growing closes no holes, which is why it leaves {@link #deallocations_since_last_rebuild}
-     * alone: the holes it did not close are still there for a later {@link compact} to close.
+     * Growing closes no holes: the holes it did not close are still there for the sweep, or a
+     * later {@link compact}, to close.
      *
      * The arena an allocator is asked for is {@link OffsetAllocator#grow_target_for}, not the
      * shortfall: room for exactly `extra_data_size` can still be refused the allocation that asked
@@ -240,6 +425,8 @@ export class GPUMeshletManager {
             return;
         }
 
+        this.#assert_not_moving();
+
         const device = this.#device;
 
         const old_buffer_data = this.#meshlet_data_buffer;
@@ -337,6 +524,8 @@ export class GPUMeshletManager {
 
         device.queue.submit([encoder.finish()]);
 
+        this.#stats.growths++;
+
         if (new_buffer_data !== null) {
             old_buffer_data.destroy();
 
@@ -351,8 +540,16 @@ export class GPUMeshletManager {
     }
 
     /**
-     * Helper to patch pointers in metadata and upload to GPU
-     * @param {ArrayBuffer} source_array_buffer
+     * Place a batch's rows in the metadata buffer with every `address` made absolute.
+     *
+     * The rows a batch arrives with address its data relative to the batch; on the device they
+     * address the arena. The row is packed (`MESHLET_METADATA_STRUCT.size === aligned_size`) and
+     * the field is one word, so the patch is a byte copy of the batch's rows and one add per row.
+     * This used to be a struct read and a struct write per row through the generic serde, at
+     * ~20 µs a batch of 34 rows — which was most of what a rebuild cost per record, and what every
+     * page promotion paid (COMPACTION_PLAN_2026_09_16 §2.2).
+     *
+     * @param {ArrayBuffer} source_array_buffer the batch's rows, addresses relative to the batch
      * @param {number} meshlet_count
      * @param {number} data_offset_words
      * @param {number} metadata_offset_index
@@ -365,29 +562,22 @@ export class GPUMeshletManager {
         metadata_offset_index,
         target_buffer
     ) {
-        const temp_writer = BinaryBuffer.fromEndianness(platform_compute_endianness());
-        temp_writer.setCapacity(meshlet_count * MESHLET_METADATA_STRUCT.size); // pre-allocate to avoid resizing
-
-        const source_reader = BinaryBuffer.fromArrayBuffer(source_array_buffer);
-        source_reader.endianness = platform_compute_endianness();
-
-        // Iterate over meshlets in the batch, patch the address, and write to temp buffer
-        for (let i = 0; i < meshlet_count; i++) {
-            const header = read_wgsl_type_value(source_reader, MESHLET_METADATA_STRUCT);
+        const word_count = meshlet_count * METADATA_ROW_WORDS;
 
-            // PATCH: Add the allocation offset to the relative address
-            header.address += data_offset_words;
+        // `metadata_buffer_original` is an ArrayBuffer from a BinaryBuffer, offset 0; a slice
+        // rather than a view because the batch keeps its rows relative for the next placement
+        const words = new Uint32Array(source_array_buffer.slice(0, word_count * 4));
 
-            write_wgsl_type_value(header, temp_writer, MESHLET_METADATA_STRUCT);
+        for (let w = METADATA_ADDRESS_WORD; w < word_count; w += METADATA_ROW_WORDS) {
+            words[w] += data_offset_words;
         }
 
-        // Upload
         this.#device.queue.writeBuffer(
             target_buffer,
             metadata_offset_index * MESHLET_METADATA_STRUCT.aligned_size,
-            temp_writer.data,
+            words.buffer,
             0,
-            meshlet_count * MESHLET_METADATA_STRUCT.aligned_size
+            word_count * 4
         );
     }
 
@@ -417,7 +607,7 @@ export class GPUMeshletManager {
         const record_count = records.size;
         const new_allocator_data = new OffsetAllocator(
             new_data_size,
-            Math.max(record_count * 2, ALLOCATION_LIMIT)
+            Math.max(record_count * 2, this.#allocation_limit)
         );
 
         const old_buffer_data = this.#meshlet_data_buffer;
@@ -429,7 +619,7 @@ export class GPUMeshletManager {
 
         const new_allocator_metadata = new OffsetAllocator(
             new_metadata_size,
-            Math.max(record_count * 2, ALLOCATION_LIMIT)
+            Math.max(record_count * 2, this.#allocation_limit)
         );
 
         const old_buffer_metadata = this.#meshlet_metadata_buffer;
@@ -445,11 +635,20 @@ export class GPUMeshletManager {
 
         const moved_records = [];
 
-        // move data, in allocation order, which is the order the set keeps
+        const nodes_data = this.#arena_data.records;
+        const nodes_metadata = this.#arena_metadata.records;
+
+        nodes_data.clear();
+        nodes_metadata.clear();
+
+        // move data, in allocation order, which is the order the set keeps. Each range is the
+        // bin the record was placed in originally (see #allocate_data_and_metadata), which is
+        // also what makes sequential packing exact: a bin-sized request never falls in the gap
+        // between a remainder's size and the bin it is filed under.
         for (const record of records) {
 
-            const new_allocation_data = new_allocator_data.allocate(record.data_size);
-            const new_allocation_metadata = new_allocator_metadata.allocate(record.meshlet_count);
+            const new_allocation_data = new_allocator_data.allocate(allocator_run_size_for(record.data_size));
+            const new_allocation_metadata = new_allocator_metadata.allocate(allocator_run_size_for(record.meshlet_count));
 
             assert.notEqual(new_allocation_data.offset, ALLOCATOR_NO_SPACE);
             assert.notEqual(new_allocation_metadata.offset, ALLOCATOR_NO_SPACE);
@@ -478,6 +677,9 @@ export class GPUMeshletManager {
             record.data = new_allocation_data;
             record.metadata = new_allocation_metadata;
 
+            nodes_data.set(new_allocation_data.metadata, record);
+            nodes_metadata.set(new_allocation_metadata.metadata, record);
+
             if (metadata_record_moved) {
                 moved_records.push(record);
             }
@@ -501,96 +703,170 @@ export class GPUMeshletManager {
         this.#allocator_data = new_allocator_data;
         this.#allocator_metadata = new_allocator_metadata;
 
-        // reset count
-        this.#deallocations_since_last_rebuild = 0;
+        // packed: whatever episode was running is over, and the nodes it was walking are gone
+        for (const sweep of [this.#sweep_data, this.#sweep_metadata]) {
+            sweep.armed = false;
+            sweep.grew = false;
+            sweep.cursor = ALLOCATOR_NO_SPACE;
+            sweep.restart = ALLOCATOR_NO_SPACE;
+            sweep.moves = 0;
+        }
+
+        this.#stats.rebuilds++;
     }
 
     /**
      * Allocate `data_size_words` in the data buffer and `meshlet_count`
-     * in the metadata buffer, growing or compacting on failure and trying
-     * again. Throws if the third attempt still can't satisfy both. The two
+     * in the metadata buffer, making room on refusal and trying again.
+     * Throws if the last attempt still can't satisfy both. The two
      * allocations are kept in lockstep — partial successes are released
      * before retrying so we never leak.
      *
-     * Which of the two a failure gets is decided by what the failure is.
-     * {@link grow} appends a contiguous run and moves nothing, so it is
-     * the cheap and complete answer to an arena that is merely full.
-     * {@link compact} adds no space at all — it closes holes — and pays a
-     * migration of every allocation, a CPU metadata rewrite each and a
-     * `changed` for every moved address to do it, so it is reserved for
-     * the failure it is the only answer to: the room is already there and
-     * merely scattered. Queued clone work is carried through either —
-     * {@link #pending_clones} names records, not addresses — so an
-     * allocation made while a clone is pending is safe.
+     * Every request is rounded up to the bin it would be looked up from
+     * (`allocator_run_size_for`) before it reaches the allocator. The
+     * allocator files a freed run under the largest bin that fits inside
+     * it and looks a request up from the smallest bin that fits the
+     * request, so a hole left by a batch serves only requests a whole bin
+     * smaller than it — under a churn of near-uniform batches that was
+     * most refusals, and each refusal a rebuild. A range that is exactly
+     * a bin is filed under exactly the bin any request of its class is
+     * looked up from, and is consumed whole by one, leaving no splinter.
+     * The record keeps the true sizes; the arena reserves the bin
+     * (COMPACTION_PLAN_2026_09_16 §2.1, §4.1).
+     *
+     * What a refusal gets (plan §4.4). {@link grow} appends and moves
+     * nothing, so it is the answer to an arena that is short — and, once
+     * per sweep episode, to one that is merely fragmented: the growth
+     * leaves headroom, the holes stay, and the sweep closes them over the
+     * frames that follow. A second fragmentation refusal before the sweep
+     * has finished is the case growth would compound, so it gets the one
+     * {@link compact}, which is O(all batches) and now bounded by the row
+     * patch. The rebuild is also the last resort before the throw, for an
+     * arena the device will not let grow — and for one that is out of
+     * nodes, which no arena size answers and which a rebuild re-picks.
+     * Queued clone work is carried through any of these — {@link
+     * #pending_clones} names records, not addresses.
      *
      * @param {number} data_size_words
      * @param {number} meshlet_count
      * @returns {{data: Allocation, metadata: Allocation}}
      */
     #allocate_data_and_metadata(data_size_words, meshlet_count) {
-        let data_allocation;
-        let metadata_allocation;
+        assert.isNonNegativeInteger(data_size_words, 'data_size_words');
+        assert.isNonNegativeInteger(meshlet_count, 'meshlet_count');
+
+        this.#assert_not_moving();
+
+        // An empty batch — a mesh with no triangles yet, a placeholder geometry — reserves one
+        // element rather than none: a zero-sized node has no place in a partition of the arena,
+        // and the sweep's head and cursor rules (plan §4.2) assume every node covers something.
+        const data_run = allocator_run_size_for(Math.max(1, data_size_words));
+        const metadata_run = allocator_run_size_for(Math.max(1, meshlet_count));
 
-        for (let try_index = 0; try_index < 3; try_index++) {
+        // attempt 0 grows; attempt 1 grows or rebuilds; attempt 2 rebuilds; attempt 3 is the last
+        const LAST_ATTEMPT = 3;
 
-            data_allocation = this.#allocator_data.allocate(data_size_words);
-            metadata_allocation = this.#allocator_metadata.allocate(meshlet_count);
+        for (let attempt = 0; ; attempt++) {
+
+            const data_allocation = this.#allocator_data.allocate(data_run);
+            const metadata_allocation = this.#allocator_metadata.allocate(metadata_run);
 
             const data_ok = data_allocation.offset !== ALLOCATOR_NO_SPACE;
             const metadata_ok = metadata_allocation.offset !== ALLOCATOR_NO_SPACE;
 
             if (data_ok && metadata_ok) {
-                break;
+                return { data: data_allocation, metadata: metadata_allocation };
             }
 
             // release partial allocation
             if (data_ok) {
                 this.#allocator_data.free(data_allocation);
-
-                data_allocation.offset = ALLOCATOR_NO_SPACE;
-                data_allocation.metadata = ALLOCATOR_NO_SPACE;
             }
             if (metadata_ok) {
                 this.#allocator_metadata.free(metadata_allocation);
+            }
 
-                metadata_allocation.offset = ALLOCATOR_NO_SPACE;
-                metadata_allocation.metadata = ALLOCATOR_NO_SPACE;
+            if (attempt === LAST_ATTEMPT) {
+                throw new Error('Failed to allocate GPU memory for meshlet batch');
             }
 
             // An allocator holding enough free space for the request it just refused is one whose
-            // space is scattered, and closing the holes is the only thing that helps. Anything else
-            // is a shortfall, which growth covers by appending. "Enough" is what a compaction would
-            // hand back — every hole as one run — measured against the run the request is accepted
-            // from, or a compaction could return the whole arena as one run and still be refused.
+            // space is scattered: with that much free and no run accepted there are at least two
+            // free nodes, so closing holes is what would help. Anything else is a shortfall.
+            // "Enough" is measured against the run the request is accepted from, or a packing
+            // could hand back the whole free space as one run and still be refused.
             const data_is_fragmented = !data_ok
-                && this.#allocator_data.freeStorage >= allocator_run_size_for(data_size_words);
+                && this.#allocator_data.freeStorage >= data_run;
 
             const metadata_is_fragmented = !metadata_ok
-                && this.#allocator_metadata.freeStorage >= allocator_run_size_for(meshlet_count);
-
-            // #rebuild zeroes the counter, so a compaction that does not free the request through
-            // leaves the next pass to grow — the loop always makes progress
-            if (
-                this.#deallocations_since_last_rebuild > 0
-                && (data_is_fragmented || metadata_is_fragmented)
-            ) {
+                && this.#allocator_metadata.freeStorage >= metadata_run;
+
+            let rebuild = attempt === LAST_ATTEMPT - 1;
+
+            if (data_is_fragmented) {
+                rebuild ||= this.#sweep_data.grew;
+
+                this.#arm_sweep(this.#sweep_data, this.#allocator_data);
+            }
+
+            if (metadata_is_fragmented) {
+                rebuild ||= this.#sweep_metadata.grew;
+
+                this.#arm_sweep(this.#sweep_metadata, this.#allocator_metadata);
+            }
+
+            if (rebuild) {
                 this.compact();
 
                 continue;
             }
 
-            const grow_data_size = data_ok ? 0 : data_size_words;
-            const grow_metadata_size = metadata_ok ? 0 : meshlet_count;
+            if (data_is_fragmented) {
+                this.#sweep_data.grew = true;
+            }
+
+            if (metadata_is_fragmented) {
+                this.#sweep_metadata.grew = true;
+            }
 
-            this.grow(grow_data_size, grow_metadata_size);
+            this.grow(data_ok ? 0 : data_run, metadata_ok ? 0 : metadata_run);
+        }
+    }
 
+    /**
+     * Start a sweep of one arena, if one is not running. The cursor is kept up to date by every
+     * removal whether or not a sweep is running (plan §4.3), so arming is a flag.
+     *
+     * @param {ArenaSweep} sweep
+     * @param {OffsetAllocator} allocator
+     */
+    #arm_sweep(sweep, allocator) {
+        if (sweep.armed) {
+            return;
         }
 
-        if (data_allocation.offset === ALLOCATOR_NO_SPACE || metadata_allocation.offset === ALLOCATOR_NO_SPACE) {
-            throw new Error('Failed to allocate GPU memory for meshlet batch');
+        sweep.armed = true;
+        sweep.grew = false;
+        sweep.moves = 0;
+
+        if (sweep.cursor === ALLOCATOR_NO_SPACE) {
+            // every hole comes from a removal, which records where the pass should start; the
+            // case of none known walks from the head, bounded by the step budget
+            sweep.cursor = sweep.restart !== ALLOCATOR_NO_SPACE ? sweep.restart : allocator.first_used_node();
+            sweep.restart = ALLOCATOR_NO_SPACE;
         }
 
-        return { data: data_allocation, metadata: metadata_allocation };
+        this.#stats.sweeps_armed++;
+    }
+
+    /**
+     * @throws when a sweep's moves are recorded into a command context that has not finished
+     */
+    #assert_not_moving() {
+        assert.ok(
+            this.#moving_ctx === null || this.#moving_ctx.finished,
+            'GPUMeshletManager: a sweep recorded moves into a command context that has not finished; an allocation, removal, growth or rebuild now would race the copies it recorded'
+        );
     }
 
     /**
@@ -621,13 +897,15 @@ export class GPUMeshletManager {
 
         this.#records.add(record);
 
+        this.#arena_data.records.set(data.metadata, record);
+        this.#arena_metadata.records.set(metadata.metadata, record);
+
         return record;
     }
 
     /**
      * Release a batch allocation back to the data and metadata allocators. The GPU bytes are
-     * not cleared — the freed slices are reclaimed lazily by the next {@link compact} (a
-     * deallocation bumps the compaction counter the allocator consults under pressure).
+     * not cleared — the freed slices are handed to whoever asks next, or closed by a sweep.
      * Other batches' allocations are unaffected (the OffsetAllocator frees disjoint slices),
      * so callers only need to ensure nothing still references this batch's metadata rows
      * (the geometry table rebuild in {@link GPUGeometryManager} handles that).
@@ -643,17 +921,328 @@ export class GPUMeshletManager {
             return false;
         }
 
+        this.#assert_not_moving();
+
         this.#cancel_pending_clones_naming(record);
 
-        this.#allocator_data.free(record.data);
-        this.#allocator_metadata.free(record.metadata);
+        this.#retire(this.#arena_data, record);
+        this.#retire(this.#arena_metadata, record);
 
         this.#records.delete(record);
-        this.#deallocations_since_last_rebuild++;
 
         return true;
     }
 
+    /**
+     * Give a record's range in one arena back, keeping the sweep's pointers and the node map right.
+     *
+     * A freed node's index is immediately the merged free node's, and then the next allocation's;
+     * a pointer left on it would name another live record and never fail loudly. So a pointer on
+     * this node is moved to the used node after it before the free. And the hole this leaves is
+     * recorded for the sweep: if it is above the running pass's cursor the pass reaches it; if
+     * it is below — or no pass is running — the *restart* point is moved down to the used node
+     * after it when it is the lowest hole known, so the next pass starts there and closes it
+     * (COMPACTION_PLAN_2026_09_16 §4.3).
+     *
+     * @param {object} arena
+     * @param {MeshletBatchAllocationRecord} record
+     */
+    #retire(arena, record) {
+        const sweep = arena.sweep;
+        const allocator = arena.allocator();
+        const allocation = arena.allocation_of(record);
+        const node = allocation.metadata;
+
+        const successor = allocator.next_used_node(node);
+
+        if (node === sweep.cursor) {
+            sweep.cursor = successor;
+        }
+
+        if (node === sweep.restart) {
+            sweep.restart = successor;
+        } else if (this.#is_below(arena, allocation, sweep.cursor) && this.#is_below(arena, allocation, sweep.restart)) {
+            sweep.restart = successor;
+        }
+
+        arena.records.delete(node);
+
+        allocator.free(allocation);
+
+        // Free space less the largest free run, both from the bins: O(1), and the largest run
+        // is bin-rounded down, which errs towards arming.
+        const report = allocator.storageReport();
+        const scattered = report.totalFreeSpace - report.largestFreeRegion;
+
+        if (scattered >= arena.scatter_minimum && scattered * 8 >= allocator.size) {
+            this.#arm_sweep(sweep, allocator);
+        }
+    }
+
+    /**
+     * Whether `allocation` sits below the record `pointer` names — or `pointer` names nothing,
+     * which counts as below: a hole with no pass or restart ahead of it is the lowest known.
+     *
+     * @param {object} arena
+     * @param {Allocation} allocation
+     * @param {number} pointer node index, or ALLOCATOR_NO_SPACE
+     * @returns {boolean}
+     */
+    #is_below(arena, allocation, pointer) {
+        if (pointer === ALLOCATOR_NO_SPACE) {
+            return true;
+        }
+
+        const record = arena.records.get(pointer);
+
+        assert.defined(record, 'record, a sweep pointer names a node no record holds');
+
+        return allocation.offset < arena.allocation_of(record).offset;
+    }
+
+    /**
+     * One budgeted step of the compaction of both arenas, recorded into `cmd_ctx`.
+     *
+     * Nothing happens unless a fragmentation refusal has armed a sweep (see
+     * {@link #allocate_data_and_metadata}). Then, in each arena, the cursor walks up the used
+     * ranges sliding each down over the free space before it — which gathers every hole passed
+     * into one run just behind the cursor — until {@link MESHLET_SWEEP_MOVE_BUDGET} records or
+     * {@link MESHLET_SWEEP_WORD_BUDGET} words have moved (never fewer than one when one can) or
+     * {@link MESHLET_SWEEP_STEP_BUDGET} steps have been taken, across both arenas. The sweep is
+     * done when the cursor reaches the arena's end: all free space is one run at the tail, and
+     * the episode is over.
+     *
+     * A moved record's bytes — data and rows alike — go through a transient staging buffer in
+     * two `copyBufferToBuffer`s: WebGPU refuses a same-buffer copy, the intra-copy shader the
+     * clone flush uses is not overlap-safe, and a slide by less than a record's size overlaps.
+     * Rows are copied rather than re-derived from the batch's bytes because the skinning bounds
+     * chain writes into clone rows on the device every frame. A data move then patches the
+     * moved rows' `address` with the clone flush's shader. Every move is recorded in cursor
+     * order, so a record sliding into space another vacated earlier in the same call reads what
+     * that record's copy already wrote out. `changed` fires once per moved record after the
+     * whole batch is recorded, with the new offsets on the record.
+     *
+     * The renderer calls this once per frame, at the head of the frame, before
+     * {@link update}, so the clone flush reads post-sweep offsets and every pass reads rows and
+     * data that agree. Until `cmd_ctx` finishes the manager refuses to allocate, free, grow or
+     * rebuild — a recorded copy names ranges that must stay what they are until it runs.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    sweep(cmd_ctx) {
+        assert.defined(cmd_ctx, 'cmd_ctx');
+
+        this.#assert_not_moving();
+
+        const budget = {
+            moves: MESHLET_SWEEP_MOVE_BUDGET,
+            words: MESHLET_SWEEP_WORD_BUDGET,
+            steps: MESHLET_SWEEP_STEP_BUDGET,
+        };
+
+        const data_moves = this.#sweep_arena(this.#arena_data, budget);
+        const metadata_moves = this.#sweep_arena(this.#arena_metadata, budget);
+
+        if (data_moves.length === 0 && metadata_moves.length === 0) {
+            return;
+        }
+
+        this.#record_moves(cmd_ctx, data_moves, metadata_moves);
+
+        this.#moving_ctx = cmd_ctx;
+
+        const moved = new Set();
+
+        for (const move of data_moves) {
+            moved.add(move.record);
+        }
+
+        for (const move of metadata_moves) {
+            moved.add(move.record);
+        }
+
+        for (const record of moved) {
+            record.changed.send0();
+        }
+    }
+
+    /**
+     * The sweep steps of one arena, within `budget` (which is spent across both arenas).
+     *
+     * @param {object} arena
+     * @param {{moves: number, words: number, steps: number}} budget
+     * @returns {ArenaMove[]}
+     */
+    #sweep_arena(arena, budget) {
+        const sweep = arena.sweep;
+
+        /** @type {ArenaMove[]} */
+        const moves = [];
+
+        if (!sweep.armed) {
+            return moves;
+        }
+
+        const allocator = arena.allocator();
+
+        while (budget.moves > 0 && budget.words > 0 && budget.steps > 0) {
+            const node = sweep.cursor;
+
+            if (node === ALLOCATOR_NO_SPACE) {
+                if (sweep.restart !== ALLOCATOR_NO_SPACE) {
+                    // holes opened below this pass while it ran: another pass, from the lowest
+                    sweep.cursor = sweep.restart;
+                    sweep.restart = ALLOCATOR_NO_SPACE;
+
+                    continue;
+                }
+
+                // the arena's end: all free space is one run at the tail
+                sweep.armed = false;
+                sweep.grew = false;
+
+                this.#stats.sweeps_completed++;
+                this.#stats.moves_last_sweep = sweep.moves;
+
+                sweep.moves = 0;
+
+                break;
+            }
+
+            const record = arena.records.get(node);
+
+            assert.defined(record, 'record, the cursor names a node no record holds');
+
+            const allocation = arena.allocation_of(record);
+
+            assert.equal(allocation.metadata, node, 'allocation.metadata, the cursor names a node another record holds');
+
+            budget.steps--;
+
+            const delta = allocator.slide_down(node);
+
+            sweep.cursor = allocator.next_used_node(node);
+
+            if (delta === 0) {
+                continue;
+            }
+
+            const move = new ArenaMove();
+
+            move.record = record;
+            move.from = allocation.offset;
+            move.to = allocation.offset - delta;
+
+            allocation.offset = move.to;
+
+            moves.push(move);
+
+            budget.moves--;
+            budget.words -= arena.elements_of(record) * arena.element_words;
+
+            sweep.moves++;
+
+            this.#stats.moves++;
+        }
+
+        return moves;
+    }
+
+    /**
+     * The GPU side of a sweep step: the staged copies of every moved range, then the address
+     * patch of every row whose data moved.
+     *
+     * One staging buffer sized to the largest move, reused from offset 0 by every copy: copies in
+     * one command buffer are ordered. The patch table is built after the row copies from the
+     * records' post-move row offsets, which is where the rows are by the time it runs.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {ArenaMove[]} data_moves
+     * @param {ArenaMove[]} metadata_moves
+     */
+    #record_moves(cmd_ctx, data_moves, metadata_moves) {
+        const data_buffer = this.#meshlet_data_buffer;
+        const metadata_buffer = this.#meshlet_metadata_buffer;
+        const row_bytes = MESHLET_METADATA_STRUCT.aligned_size;
+
+        let largest_bytes = 0;
+
+        for (const move of data_moves) {
+            largest_bytes = Math.max(largest_bytes, move.record.data_size * 4);
+        }
+
+        for (const move of metadata_moves) {
+            largest_bytes = Math.max(largest_bytes, move.record.meshlet_count * row_bytes);
+        }
+
+        if (largest_bytes > 0) {
+            const stage = cmd_ctx.allocateTransientBuffer(
+                GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+                largest_bytes
+            );
+
+            for (const move of data_moves) {
+                const bytes = move.record.data_size * 4;
+
+                if (bytes === 0) {
+                    continue;
+                }
+
+                cmd_ctx.copyBufferToBuffer(data_buffer, move.from * 4, stage, 0, bytes);
+                cmd_ctx.copyBufferToBuffer(stage, 0, data_buffer, move.to * 4, bytes);
+            }
+
+            for (const move of metadata_moves) {
+                const bytes = move.record.meshlet_count * row_bytes;
+
+                if (bytes === 0) {
+                    continue;
+                }
+
+                cmd_ctx.copyBufferToBuffer(metadata_buffer, move.from * row_bytes, stage, 0, bytes);
+                cmd_ctx.copyBufferToBuffer(stage, 0, metadata_buffer, move.to * row_bytes, bytes);
+            }
+        }
+
+        let patch_count = 0;
+
+        for (const move of data_moves) {
+            patch_count += move.record.meshlet_count;
+        }
+
+        if (patch_count === 0) {
+            return;
+        }
+
+        const patches = new Uint32Array(patch_count * 2);
+
+        let p = 0;
+
+        for (const move of data_moves) {
+            const record = move.record;
+
+            // the same wrapping add as the clone flush: a move down is a negative delta
+            const delta = (move.to - move.from) >>> 0;
+
+            for (let i = 0; i < record.meshlet_count; i++) {
+                patches[p++] = record.metadata.offset + i;
+                patches[p++] = delta;
+            }
+        }
+
+        const patches_buffer = cmd_ctx.allocateTransientBufferAndLoad(patches.buffer, GPUBufferUsage.STORAGE);
+
+        shader_meshlet_metadata_address_patch.dispatchThreads({
+            encoder: cmd_ctx,
+            thread_count_x: patch_count,
+            bindings: {
+                meshlet_metadata: metadata_buffer,
+                patches: patches_buffer,
+                patch_count,
+            },
+        });
+    }
+
     /**
      * Drop the queued clone copies that name `record`, because it is about to stop owning the
      * ranges they were going to read from or write to.
@@ -729,6 +1318,9 @@ export class GPUMeshletManager {
 
         this.#records.add(record);
 
+        this.#arena_data.records.set(data.metadata, record);
+        this.#arena_metadata.records.set(metadata.metadata, record);
+
         // The queue names the two records rather than the addresses they
         // hold right now. Both are in `#records`, so a rebuild between
         // this call and the flush moves them and the flush still reads
@@ -922,6 +1514,21 @@ export class GPUMeshletManager {
         return result;
     }
 
+    /**
+     * Bytes the arenas have handed out: every batch's range rounded to its bin, data and metadata
+     * both. Above {@link gpu_memory_usage_occupied} by the quantization overhead — 3.4 % of data
+     * and 3.9 % of rows on page-shaped batches, at most 12.5 % on any.
+     *
+     * @returns {number}
+     */
+    get gpu_memory_usage_reserved() {
+        const data = this.#allocator_data;
+        const metadata = this.#allocator_metadata;
+
+        return (data.size - data.freeStorage) * 4
+            + (metadata.size - metadata.freeStorage) * MESHLET_METADATA_STRUCT.aligned_size;
+    }
+
     get gpu_memory_usage() {
         let result = 0;