@woosh/meep-engine 3.22.0 → 3.23.0

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
+ */
 export class GPUGeometryMeshletsBVH {
     /**
      * The tree's bytes as they were copied into the arena, once they have been. Not taken at
@@ -14,6 +17,14 @@ export class GPUGeometryMeshletsBVH {
      * @type {number}
      */
     address: number;
+    /**
+     * The arena region {@link address} names, as the allocator handed it out — kept so the
+     * region can be given back when this tree is released. `null` until the nodes are
+     * resident, and again once they have been released.
+     *
+     * @type {Allocation|null}
+     */
+    allocation: Allocation | null;
     /**
      * The shape of this tree — parents and leaf positions — shared with every other copy of the same
      * geometry, because a copy differs only in where its bounds are.
@@ -46,4 +57,5 @@ export class GPUGeometryMeshletsBVH {
      */
     released: boolean;
 }
+export type Allocation = import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
 //# sourceMappingURL=GPUGeometryMeshletsBVH.d.ts.map

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;IAEI;;;;;;OAMG;IACH,KAFU,WAAW,GAAC,SAAS,CAE3B;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB"}
+{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;IAEI;;;;;;OAMG;IACH,KAFU,WAAW,GAAC,SAAS,CAE3B;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;OAMG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;IAElB;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB;yBAjEY,OAAO,sDAAsD,EAAE,UAAU"}

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
+ */
+
 export class GPUGeometryMeshletsBVH {
 
     /**
@@ -17,6 +21,15 @@ export class GPUGeometryMeshletsBVH {
      */
     address = 0;
 
+    /**
+     * The arena region {@link address} names, as the allocator handed it out — kept so the
+     * region can be given back when this tree is released. `null` until the nodes are
+     * resident, and again once they have been released.
+     *
+     * @type {Allocation|null}
+     */
+    allocation = null;
+
     /**
      * The shape of this tree — parents and leaf positions — shared with every other copy of the same
      * geometry, because a copy differs only in where its bounds are.

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts

@@ -15,6 +15,23 @@ export class GPUMeshletManager {
     get buffer_metadata(): GPUBuffer;
     compact(): void;
     /**
+     * Enlarge the data and metadata arenas, leaving every batch exactly where it is.
+     *
+     * Growth appends. {@link OffsetAllocator#grow} files the new tail as free space and moves
+     * nothing, and each buffer's old contents go into the larger one at offset 0 in a single copy —
+     * so no record's `data.offset` or `metadata.offset` changes, no meshlet's `address` field needs
+     * 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.
+     *
+     * The arena an allocator is asked for is a little larger than the shortfall, because the bins
+     * round free runs down and requests up, up to 9/8 apart — room for exactly `extra_data_size`
+     * can still be refused the allocation that asked for it. And no larger than
+     * `maxBufferSize`: growth stops at what the device will hand out, so an arena that cannot
+     * hold the request reports that through the caller's failed allocation rather than through a
+     * buffer that is not there.
      *
      * @param {number} extra_data_size in words (4 bytes)
      * @param {number} extra_metadata_size in metadata elements

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAqEA;IAoEI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAmChB;IAzFD,6BAEC;IAOD,iCAEC;IAgFD,gBAKC;IAED;;;;OAIG;IACH,sBAHW,MAAM,uBACN,MAAM,QAiDhB;IA+PD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAiBnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBApvBY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AAerD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}
+{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAmFA;IAqEI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAkChB;IAzFD,6BAEC;IAOD,iCAEC;IAgFD,gBAKC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QAuHhB;IAqRD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAgCD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBA/4BY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6BrD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}

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

@@ -32,6 +32,20 @@ const DEFAULT_METADATA_CAPACITY = 128 * 1024;
  */
 const DEFAULT_DATA_CAPACITY = 32 * MEGABYTE;
 
+/**
+ * Node budget both allocators are built with — the ceiling on how many ranges either can be
+ * describing at once, live allocations and free holes together.
+ *
+ * {@link OffsetAllocator#grow} cannot raise it: the node table cannot be enlarged in place, and the
+ * allocation count a caller needs does not follow from the arena's size anyway. So a manager that
+ * grows keeps whatever it was constructed with, where one that rebuilt got the number re-picked
+ * every time. It loses nothing by that — {@link #rebuild} re-picks the larger of this and twice the
+ * live batch count, which only exceeds this past 65,536 batches.
+ *
+ * @type {number}
+ */
+const ALLOCATION_LIMIT = 128 * 1024;
+
 class MeshletBatchAllocationRecord {
     /**
      * @type {Allocation}
@@ -123,10 +137,11 @@ export class GPUMeshletManager {
      * commands and N `(record_index, address_delta)` patch entries.
      *
      * Entries name the two records, not the addresses they held when the
-     * clone was queued: a {@link compact} or {@link grow} in between
-     * migrates both, and {@link update} reads where they ended up. What
-     * an entry does require is that neither record is handed back to
-     * {@link remove_batch} before the flush.
+     * clone was queued: a {@link compact} in between migrates both, and
+     * {@link update} reads where they ended up. ({@link grow} moves
+     * nothing, so it needs nothing of them.) What an entry does require
+     * is that neither record is handed back to {@link remove_batch}
+     * before the flush.
      *
      * @type {{
      *   source: MeshletBatchAllocationRecord,
@@ -159,9 +174,8 @@ export class GPUMeshletManager {
 
         const data_buffer_size_words = Math.ceil(initial_data_capacity / 4);
 
-        // TODO manage max-allocations as well
-        this.#allocator_data = new OffsetAllocator(data_buffer_size_words);
-        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity);
+        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',
@@ -185,6 +199,23 @@ export class GPUMeshletManager {
     }
 
     /**
+     * Enlarge the data and metadata arenas, leaving every batch exactly where it is.
+     *
+     * Growth appends. {@link OffsetAllocator#grow} files the new tail as free space and moves
+     * nothing, and each buffer's old contents go into the larger one at offset 0 in a single copy —
+     * so no record's `data.offset` or `metadata.offset` changes, no meshlet's `address` field needs
+     * 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.
+     *
+     * The arena an allocator is asked for is a little larger than the shortfall, because the bins
+     * round free runs down and requests up, up to 9/8 apart — room for exactly `extra_data_size`
+     * can still be refused the allocation that asked for it. And no larger than
+     * `maxBufferSize`: growth stops at what the device will hand out, so an arena that cannot
+     * hold the request reports that through the caller's failed allocation rather than through a
+     * buffer that is not there.
      *
      * @param {number} extra_data_size in words (4 bytes)
      * @param {number} extra_metadata_size in metadata elements
@@ -198,11 +229,13 @@ export class GPUMeshletManager {
             return;
         }
 
-        const current_data_buffer_size_bytes = this.#meshlet_data_buffer.size;
-        const current_metadata_buffer_size = this.#meshlet_metadata_buffer.size;
+        const device = this.#device;
+
+        const old_buffer_data = this.#meshlet_data_buffer;
+        const old_buffer_metadata = this.#meshlet_metadata_buffer;
 
-        const current_buffer_size_words = current_data_buffer_size_bytes >> 2;
-        const current_metadata_buffer_size_elements = Math.ceil(current_metadata_buffer_size / MESHLET_METADATA_STRUCT.aligned_size);
+        const current_buffer_size_words = old_buffer_data.size >> 2;
+        const current_metadata_buffer_size_elements = Math.ceil(old_buffer_metadata.size / MESHLET_METADATA_STRUCT.aligned_size);
 
         const DATA_GROWTH_STEP = 16 * 1024;
         const METADATA_GROWTH_STEP = 256;
@@ -214,7 +247,7 @@ export class GPUMeshletManager {
         } else {
             // grow
             new_data_size = Math.max(
-                current_buffer_size_words + extra_data_size,
+                current_buffer_size_words + Math.ceil(extra_data_size * 9 / 8),
                 current_buffer_size_words + DATA_GROWTH_STEP,
                 Math.ceil(current_buffer_size_words * GROWTH_MULTIPLIER)
             );
@@ -226,16 +259,84 @@ export class GPUMeshletManager {
         } else {
             // grow
             new_metadata_size = Math.max(
-                current_metadata_buffer_size_elements + extra_metadata_size,
+                current_metadata_buffer_size_elements + Math.ceil(extra_metadata_size * 9 / 8),
                 current_metadata_buffer_size_elements + METADATA_GROWTH_STEP,
-                current_metadata_buffer_size_elements * GROWTH_MULTIPLIER
+                Math.ceil(current_metadata_buffer_size_elements * GROWTH_MULTIPLIER)
             );
         }
 
-        this.#rebuild(
-            new_data_size,
-            new_metadata_size
+        // `createBuffer` answers a size past the device's limit with an *invalid* buffer rather than
+        // an exception. Swapping one of those in would destroy the arena, leave the allocator sized
+        // for space that does not exist, and throw nothing on the way. Capping means a growth gets
+        // as far as the device allows, which is often still enough — and when it is not, the caller's
+        // allocation is what fails.
+        const max_buffer_size = device.limits.maxBufferSize;
+
+        new_data_size = Math.min(new_data_size, Math.floor(max_buffer_size / 4));
+        new_metadata_size = Math.min(
+            new_metadata_size,
+            Math.floor(max_buffer_size / MESHLET_METADATA_STRUCT.aligned_size)
         );
+
+        // A buffer is left alone when its arena did not change, so growing one of the two costs
+        // nothing on the other — and an arena already at the cap is left alone by the same test.
+        const grows_data = new_data_size > current_buffer_size_words;
+        const grows_metadata = new_metadata_size > current_metadata_buffer_size_elements;
+
+        if (!grows_data && !grows_metadata) {
+            // both are as large as this device will allow
+            return;
+        }
+
+        // Buffers first. `OffsetAllocator#grow` cannot be undone, so nothing irreversible happens
+        // until the space it is about to describe exists.
+        const new_buffer_data = grows_data
+            ? device.createBuffer({
+                label: old_buffer_data.label,
+                usage: old_buffer_data.usage,
+                size: new_data_size * 4,
+            })
+            : null;
+
+        const new_buffer_metadata = grows_metadata
+            ? device.createBuffer({
+                label: old_buffer_metadata.label,
+                usage: old_buffer_metadata.usage,
+                size: new_metadata_size * MESHLET_METADATA_STRUCT.aligned_size,
+            })
+            : null;
+
+        const encoder = device.createCommandEncoder({
+            label: "GPUMeshletManager/grow",
+        });
+
+        if (new_buffer_data !== null) {
+            this.#allocator_data.grow(new_data_size);
+
+            // One copy of the whole arena at offset 0. No offset moved, so the bytes land back under
+            // the addresses the records already hold — and the metadata addressing them stays right.
+            encoder.copyBufferToBuffer(old_buffer_data, 0, new_buffer_data, 0, old_buffer_data.size);
+        }
+
+        if (new_buffer_metadata !== null) {
+            this.#allocator_metadata.grow(new_metadata_size);
+
+            encoder.copyBufferToBuffer(old_buffer_metadata, 0, new_buffer_metadata, 0, old_buffer_metadata.size);
+        }
+
+        device.queue.submit([encoder.finish()]);
+
+        if (new_buffer_data !== null) {
+            old_buffer_data.destroy();
+
+            this.#meshlet_data_buffer = new_buffer_data;
+        }
+
+        if (new_buffer_metadata !== null) {
+            old_buffer_metadata.destroy();
+
+            this.#meshlet_metadata_buffer = new_buffer_metadata;
+        }
     }
 
     /**
@@ -305,7 +406,7 @@ export class GPUMeshletManager {
         const record_count = records.length;
         const new_allocator_data = new OffsetAllocator(
             new_data_size,
-            Math.max(record_count * 2, 128 * 1024)
+            Math.max(record_count * 2, ALLOCATION_LIMIT)
         );
 
         const old_buffer_data = this.#meshlet_data_buffer;
@@ -317,7 +418,7 @@ export class GPUMeshletManager {
 
         const new_allocator_metadata = new OffsetAllocator(
             new_metadata_size,
-            Math.max(record_count * 2, 128 * 1024)
+            Math.max(record_count * 2, ALLOCATION_LIMIT)
         );
 
         const old_buffer_metadata = this.#meshlet_metadata_buffer;
@@ -396,15 +497,21 @@ export class GPUMeshletManager {
 
     /**
      * Allocate `data_size_words` in the data buffer and `meshlet_count`
-     * in the metadata buffer, retrying with compact-then-grow on failure.
-     * Throws if the third attempt still can't satisfy both. The two
+     * in the metadata buffer, growing or compacting on failure and trying
+     * again. Throws if the third attempt still can't satisfy both. The two
      * allocations are kept in lockstep — partial successes are released
      * before retrying so we never leak.
      *
-     * Compaction triggers a full {@link #rebuild} which migrates every
-     * existing allocation to a new buffer pair. Queued clone work is
-     * carried through it — {@link #pending_clones} names records, not
-     * addresses — so an allocation made while a clone is pending is safe.
+     * 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.
      *
      * @param {number} data_size_words
      * @param {number} meshlet_count
@@ -440,14 +547,30 @@ export class GPUMeshletManager {
                 metadata_allocation.metadata = ALLOCATOR_NO_SPACE;
             }
 
-            if (this.#deallocations_since_last_rebuild > 0) {
-                // try compaction
+            // 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. The margin is the bins': a free run
+            // the allocator rounds down can still be refused a request it rounds up, so "enough"
+            // has to mean 9/8 of it, or a compaction could hand back a single run and still refuse.
+            const data_is_fragmented = !data_ok
+                && this.#allocator_data.freeStorage >= Math.ceil(data_size_words * 9 / 8);
+
+            const metadata_is_fragmented = !metadata_ok
+                && this.#allocator_metadata.freeStorage >= Math.ceil(meshlet_count * 9 / 8);
+
+            // #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.compact();
+
                 continue;
             }
 
-            let grow_data_size = data_ok ? 0 : data_size_words;
-            let grow_metadata_size = metadata_ok ? 0 : meshlet_count;
+            const grow_data_size = data_ok ? 0 : data_size_words;
+            const grow_metadata_size = metadata_ok ? 0 : meshlet_count;
 
             this.grow(grow_data_size, grow_metadata_size);
 
@@ -511,6 +634,8 @@ export class GPUMeshletManager {
             return false;
         }
 
+        this.#cancel_pending_clones_naming(record);
+
         this.#allocator_data.free(record.data);
         this.#allocator_metadata.free(record.metadata);
 
@@ -520,6 +645,36 @@ export class GPUMeshletManager {
         return true;
     }
 
+    /**
+     * 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.
+     *
+     * A queued copy holds records, not addresses, precisely so a rebuild can move them under it —
+     * but a *released* record keeps the offsets it had while the allocator hands those same
+     * ranges to whoever asks next. Flushing such a copy writes a stale source over a live batch's
+     * vertices, or copies a live batch's vertices into a clone, with nothing to say it happened.
+     * This was unreachable while nothing released a clone; it became reachable the moment
+     * {@link GPUGeometryManager#remove_clone} did.
+     *
+     * Cancelling by source as well as by clone gives up the copy rather than reading a region the
+     * source no longer owns. The clone is left holding its ranges with nothing written into them,
+     * which renders as whatever those bytes were — wrong, but bounded, and it is what removing a
+     * geometry out from under a clone of it already asks for.
+     *
+     * @param {MeshletBatchAllocationRecord} record
+     */
+    #cancel_pending_clones_naming(record) {
+        const pending = this.#pending_clones;
+
+        for (let i = pending.length - 1; i >= 0; i--) {
+            const entry = pending[i];
+
+            if (entry.clone === record || entry.source === record) {
+                pending.splice(i, 1);
+            }
+        }
+    }
+
     /**
      * Allocate a fresh (data, metadata) pair sized to mirror `source`,
      * and queue a GPU-side clone: the source's data and metadata are
@@ -569,7 +724,7 @@ export class GPUMeshletManager {
         // hold right now. Both are in `#records`, so a rebuild between
         // this call and the flush moves them and the flush still reads
         // where they went — which is what lets a clone be queued in the
-        // same frame as the growth another geometry's arrival forces.
+        // same frame as the compaction another geometry's arrival forces.
         this.#pending_clones.push({ source, clone: record });
 
         return record;

package/src/shade/renderer/geometry/virtual/MICRON_COMPARISON_2026_08_20.md

@@ -12,6 +12,11 @@ Paths below are relative to the Micron root.
 > scheduled but not yet built, all live in
 > [VIRTUAL_GEOMETRY_PLAN.md](./VIRTUAL_GEOMETRY_PLAN.md) — that file is the one to act on.
 > This one is kept as the analysis behind those decisions.
+>
+> It is a **snapshot dated in its filename** and is not maintained against the code. Statements
+> about meep that have since gone stale are corrected inline in block quotes like this one,
+> rather than edited away — the argument that was made at the time is the reason the decision
+> was taken, and rewriting it hides that.
 
 ## 1. Where the two already agree
 
@@ -108,6 +113,11 @@ meep hard-gates on an error band and falls back to a full sweep when the band ha
 The soft form has no escape hatch to justify, and would work as a tie-breaker *inside* a
 band, which is where meep currently uses shared-boundary weight alone.
 
+> **Since this was written**: not alone any more. The adjacency edge weight is shared boundary
+> *times* `compactness()` (plan §1), so the tie-break slot this proposes is occupied — by a
+> spatial term rather than an error-similarity one. A level tie-break would now have to argue
+> its way past compactness, not past nothing.
+
 ```js
 normal_score = 1 - merged_cone_angle² / π²
 ```
@@ -116,6 +126,13 @@ Prefers merging co-facing patches, which keeps the normal cone tight. meep reser
 `cone_reserved` in the cluster record and has no producer; if the cone ever lands, the
 grouping should be aware of it or the cones will be useless at coarse levels.
 
+> **Since this was written**: moot — **backface cone culling is declined** (plan §5). The
+> warning above turned out to be the argument against the whole idea rather than a caveat on
+> implementing it: making cones tight enough to be worth testing means letting cone angle
+> distort grouping, to feed a cull the two-pass HZB was already performing on evidence. The
+> producer did land in the meantime and has no callers
+> (`bt_face_cluster_compute_normal_bounding_cone`); `cone_reserved` stays 0 for good.
+
 The weighting itself should **not** be copied: the terms are heterogeneous in scale and
 `shared_vertex_count` enters unnormalized, so it dominates everything else. The terms are
 the finding, not the sum.