@bldrs-ai/conway 1.404.1241 → 1.408.1248

package/compiled/src/core/mem/chunked_pool.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A fixed-chunk budget pool — the resident-memory primitive (M3 production
+ * design; see "Resident memory: two regimes" in the design doc).
+ *
+ * The wasm heap grows and never shrinks: `free()` returns bytes to the
+ * allocator's freelists, not to the browser, so the tab pays the heap's
+ * **high-water mark forever** and external fragmentation is a permanent leak,
+ * not a throughput nuisance. General-purpose allocation is therefore the
+ * wrong tool for large, evictable resident data. This pool is the explicit
+ * alternative: one region carved into fixed-size chunks with a freelist —
+ * acquire rounds up to whole chunks, release is O(chunks), and the region's
+ * high-water mark is the budget, by construction. Fragmentation is confined
+ * to bounded internal waste (the tail of the last chunk).
+ *
+ * This TS class is the pool's **accounting/policy half** and the executable
+ * spec for its C++ twin in conway-geom (which owns real bytes inside the wasm
+ * heap). It is also usable directly for JS-side resident budgets (property
+ * caches, sidecar caches) — the abstraction is deliberately not
+ * geometry-specific. The intended layering:
+ *
+ *   ChunkedPool                — chunks and bytes (this file)
+ *   SharedAssetPool            — refcounted assets living in those chunks
+ *   GeometryTilePool           — the geometry narrowing (products ⇄ assets)
+ *
+ * Lifetime regimes, for orientation: *phase-bounded* scratch (tessellation
+ * temporaries) stays on the AFTP bump arenas — reset, never freed piecemeal.
+ * *Demand-bounded* residents (data that lives until evicted) live here. The
+ * general allocator keeps only the small, messy-lifetime residual.
+ */
+/**
+ * An acquired run of chunks. `chunks` are chunk indices into the pool's
+ * region (index × chunkBytes = byte offset in the C++ twin); `byteSize` is
+ * the caller's requested size, ≤ `chunks.length × chunkBytes`.
+ */
+export interface ChunkSpan {
+    chunks: number[];
+    byteSize: number;
+}
+/** Runtime counters for a pool, for tests and telemetry. */
+export interface ChunkedPoolStats {
+    totalChunks: number;
+    freeChunks: number;
+    bytesInUse: number;
+    acquires: number;
+    releases: number;
+    failedAcquires: number;
+}
+/**
+ * A budgeted pool of fixed-size chunks with a freelist. Purely accounting —
+ * see the module docs for how it maps onto real memory.
+ */
+export declare class ChunkedPool {
+    private readonly chunkBytes_;
+    private readonly totalChunks_;
+    /** Free chunk indices (LIFO for locality in the C++ twin). */
+    private readonly freeList_;
+    private acquires_;
+    private releases_;
+    private failedAcquires_;
+    /**
+     * @param budgetBytes The pool's total byte budget (rounded down to whole
+     * chunks; must fit at least one chunk).
+     * @param chunkBytes The fixed chunk size in bytes.
+     */
+    constructor(budgetBytes: number, chunkBytes: number);
+    /**
+     * @return {number} The fixed chunk size in bytes.
+     */
+    get chunkBytes(): number;
+    /**
+     * @return {number} Total chunks in the pool.
+     */
+    get totalChunks(): number;
+    /**
+     * @return {number} Chunks currently free.
+     */
+    get freeChunks(): number;
+    /**
+     * @return {number} The pool's total byte capacity (whole chunks).
+     */
+    get totalBytes(): number;
+    /**
+     * @return {number} Physical bytes currently acquired (chunk-rounded).
+     */
+    get bytesInUse(): number;
+    /**
+     * The physical (chunk-rounded) cost of a byte size — what an acquire of
+     * `bytes` actually consumes. Use this for any budget accounting layered
+     * above the pool so logical charges cover physical use.
+     *
+     * @param bytes The byte size to round.
+     * @return {number} The chunk-rounded byte cost.
+     */
+    chunkRound(bytes: number): number;
+    /**
+     * Acquire chunks to hold `bytes`. All-or-nothing: returns undefined (and
+     * changes nothing) if the free chunks can't cover the request — the
+     * caller's cue to evict and retry.
+     *
+     * @param bytes The byte size to hold (0 is allowed and acquires no chunks).
+     * @return {ChunkSpan | undefined} The span, or undefined if it can't fit.
+     */
+    acquire(bytes: number): ChunkSpan | undefined;
+    /**
+     * Return a span's chunks to the freelist. The span must not be used (or
+     * released) again afterwards.
+     *
+     * @param span The span to release.
+     */
+    release(span: ChunkSpan): void;
+    /**
+     * @return {ChunkedPoolStats} A snapshot of runtime counters.
+     */
+    get stats(): ChunkedPoolStats;
+}
+//# sourceMappingURL=chunked_pool.d.ts.map

package/compiled/src/core/mem/chunked_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked_pool.d.ts","sourceRoot":"","sources":["../../../../src/core/mem/chunked_pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAGD,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;CACvB;AAGD;;;GAGG;AACH,qBAAa,WAAW;IAEtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IAErC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC,OAAO,CAAC,SAAS,CAAI;IAErB,OAAO,CAAC,SAAS,CAAI;IAErB,OAAO,CAAC,eAAe,CAAI;IAE3B;;;;OAIG;gBACU,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAsBpD;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;OAEG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;;;OAOG;IACI,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM;IAS1C;;;;;;;OAOG;IACI,OAAO,CAAE,KAAK,EAAE,MAAM,GAAI,SAAS,GAAG,SAAS;IAoBtD;;;;;OAKG;IACI,OAAO,CAAE,IAAI,EAAE,SAAS,GAAI,IAAI;IAUvC;;OAEG;IACH,IAAW,KAAK,IAAI,gBAAgB,CASnC;CACF"}

package/compiled/src/core/mem/chunked_pool.js

@@ -0,0 +1,149 @@
+/**
+ * A fixed-chunk budget pool — the resident-memory primitive (M3 production
+ * design; see "Resident memory: two regimes" in the design doc).
+ *
+ * The wasm heap grows and never shrinks: `free()` returns bytes to the
+ * allocator's freelists, not to the browser, so the tab pays the heap's
+ * **high-water mark forever** and external fragmentation is a permanent leak,
+ * not a throughput nuisance. General-purpose allocation is therefore the
+ * wrong tool for large, evictable resident data. This pool is the explicit
+ * alternative: one region carved into fixed-size chunks with a freelist —
+ * acquire rounds up to whole chunks, release is O(chunks), and the region's
+ * high-water mark is the budget, by construction. Fragmentation is confined
+ * to bounded internal waste (the tail of the last chunk).
+ *
+ * This TS class is the pool's **accounting/policy half** and the executable
+ * spec for its C++ twin in conway-geom (which owns real bytes inside the wasm
+ * heap). It is also usable directly for JS-side resident budgets (property
+ * caches, sidecar caches) — the abstraction is deliberately not
+ * geometry-specific. The intended layering:
+ *
+ *   ChunkedPool                — chunks and bytes (this file)
+ *   SharedAssetPool            — refcounted assets living in those chunks
+ *   GeometryTilePool           — the geometry narrowing (products ⇄ assets)
+ *
+ * Lifetime regimes, for orientation: *phase-bounded* scratch (tessellation
+ * temporaries) stays on the AFTP bump arenas — reset, never freed piecemeal.
+ * *Demand-bounded* residents (data that lives until evicted) live here. The
+ * general allocator keeps only the small, messy-lifetime residual.
+ */
+/**
+ * A budgeted pool of fixed-size chunks with a freelist. Purely accounting —
+ * see the module docs for how it maps onto real memory.
+ */
+export class ChunkedPool {
+    /**
+     * @param budgetBytes The pool's total byte budget (rounded down to whole
+     * chunks; must fit at least one chunk).
+     * @param chunkBytes The fixed chunk size in bytes.
+     */
+    constructor(budgetBytes, chunkBytes) {
+        this.acquires_ = 0;
+        this.releases_ = 0;
+        this.failedAcquires_ = 0;
+        if (chunkBytes <= 0 || !Number.isInteger(chunkBytes)) {
+            throw new Error(`Invalid chunkBytes ${chunkBytes}`);
+        }
+        const totalChunks = Math.floor(budgetBytes / chunkBytes);
+        if (totalChunks < 1) {
+            throw new Error(`Budget ${budgetBytes} does not fit one chunk of ${chunkBytes}`);
+        }
+        this.chunkBytes_ = chunkBytes;
+        this.totalChunks_ = totalChunks;
+        this.freeList_ = [];
+        for (let chunk = totalChunks - 1; chunk >= 0; --chunk) {
+            this.freeList_.push(chunk);
+        }
+    }
+    /**
+     * @return {number} The fixed chunk size in bytes.
+     */
+    get chunkBytes() {
+        return this.chunkBytes_;
+    }
+    /**
+     * @return {number} Total chunks in the pool.
+     */
+    get totalChunks() {
+        return this.totalChunks_;
+    }
+    /**
+     * @return {number} Chunks currently free.
+     */
+    get freeChunks() {
+        return this.freeList_.length;
+    }
+    /**
+     * @return {number} The pool's total byte capacity (whole chunks).
+     */
+    get totalBytes() {
+        return this.totalChunks_ * this.chunkBytes_;
+    }
+    /**
+     * @return {number} Physical bytes currently acquired (chunk-rounded).
+     */
+    get bytesInUse() {
+        return (this.totalChunks_ - this.freeList_.length) * this.chunkBytes_;
+    }
+    /**
+     * The physical (chunk-rounded) cost of a byte size — what an acquire of
+     * `bytes` actually consumes. Use this for any budget accounting layered
+     * above the pool so logical charges cover physical use.
+     *
+     * @param bytes The byte size to round.
+     * @return {number} The chunk-rounded byte cost.
+     */
+    chunkRound(bytes) {
+        if (bytes < 0) {
+            throw new Error(`Invalid byte size ${bytes}`);
+        }
+        return Math.ceil(bytes / this.chunkBytes_) * this.chunkBytes_;
+    }
+    /**
+     * Acquire chunks to hold `bytes`. All-or-nothing: returns undefined (and
+     * changes nothing) if the free chunks can't cover the request — the
+     * caller's cue to evict and retry.
+     *
+     * @param bytes The byte size to hold (0 is allowed and acquires no chunks).
+     * @return {ChunkSpan | undefined} The span, or undefined if it can't fit.
+     */
+    acquire(bytes) {
+        const needed = Math.ceil(Math.max(0, bytes) / this.chunkBytes_);
+        if (needed > this.freeList_.length) {
+            ++this.failedAcquires_;
+            return void 0;
+        }
+        const chunks = new Array(needed);
+        for (let where = 0; where < needed; ++where) {
+            chunks[where] = this.freeList_.pop();
+        }
+        ++this.acquires_;
+        return { chunks, byteSize: bytes };
+    }
+    /**
+     * Return a span's chunks to the freelist. The span must not be used (or
+     * released) again afterwards.
+     *
+     * @param span The span to release.
+     */
+    release(span) {
+        for (const chunk of span.chunks) {
+            this.freeList_.push(chunk);
+        }
+        span.chunks.length = 0;
+        ++this.releases_;
+    }
+    /**
+     * @return {ChunkedPoolStats} A snapshot of runtime counters.
+     */
+    get stats() {
+        return {
+            totalChunks: this.totalChunks_,
+            freeChunks: this.freeList_.length,
+            bytesInUse: this.bytesInUse,
+            acquires: this.acquires_,
+            releases: this.releases_,
+            failedAcquires: this.failedAcquires_,
+        };
+    }
+}

package/compiled/src/core/mem/chunked_pool.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chunked_pool.test.d.ts.map

package/compiled/src/core/mem/chunked_pool.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked_pool.test.d.ts","sourceRoot":"","sources":["../../../../src/core/mem/chunked_pool.test.ts"],"names":[],"mappings":""}

package/compiled/src/core/mem/chunked_pool.test.js

@@ -0,0 +1,63 @@
+/* eslint-disable no-magic-numbers */
+// mem: the fixed-chunk pool bounds resident memory by construction — acquire
+// rounds to whole chunks, all-or-nothing, and the high-water mark can never
+// exceed the budget.
+import { describe, expect, test } from "@jest/globals";
+import { ChunkedPool } from "./chunked_pool.js";
+describe("ChunkedPool", () => {
+    test("sizes itself in whole chunks from the byte budget", () => {
+        const pool = new ChunkedPool(1050, 100);
+        expect(pool.totalChunks).toBe(10);
+        expect(pool.totalBytes).toBe(1000);
+        expect(pool.freeChunks).toBe(10);
+        expect(pool.bytesInUse).toBe(0);
+    });
+    test("acquire rounds up to whole chunks", () => {
+        const pool = new ChunkedPool(1000, 100);
+        const span = pool.acquire(250);
+        expect(span?.chunks.length).toBe(3);
+        expect(span?.byteSize).toBe(250);
+        expect(pool.bytesInUse).toBe(300);
+        expect(pool.chunkRound(250)).toBe(300);
+    });
+    test("acquire is all-or-nothing at exhaustion", () => {
+        const pool = new ChunkedPool(300, 100);
+        expect(pool.acquire(200)).toBeDefined();
+        // 2 chunks needed, 1 free → refused with no state change.
+        const refused = pool.acquire(101);
+        expect(refused).toBeUndefined();
+        expect(pool.freeChunks).toBe(1);
+        expect(pool.stats.failedAcquires).toBe(1);
+        // Exactly one chunk still fits.
+        expect(pool.acquire(100)).toBeDefined();
+        expect(pool.freeChunks).toBe(0);
+    });
+    test("released chunks are reusable (steady-state churn stays bounded)", () => {
+        const pool = new ChunkedPool(500, 100);
+        for (let round = 0; round < 50; ++round) {
+            const a = pool.acquire(300);
+            const b = pool.acquire(200);
+            expect(a).toBeDefined();
+            expect(b).toBeDefined();
+            expect(pool.bytesInUse).toBe(500);
+            pool.release(a);
+            pool.release(b);
+            expect(pool.bytesInUse).toBe(0);
+        }
+        // The pool never grew: churn recycles the same chunks.
+        expect(pool.totalChunks).toBe(5);
+        expect(pool.stats.acquires).toBe(100);
+        expect(pool.stats.releases).toBe(100);
+    });
+    test("a zero-byte acquire holds no chunks but round-trips", () => {
+        const pool = new ChunkedPool(100, 100);
+        const span = pool.acquire(0);
+        expect(span?.chunks.length).toBe(0);
+        expect(pool.freeChunks).toBe(1);
+        pool.release(span);
+    });
+    test("rejects invalid construction", () => {
+        expect(() => new ChunkedPool(100, 0)).toThrow();
+        expect(() => new ChunkedPool(50, 100)).toThrow();
+    });
+});

package/compiled/src/core/mem/shared_asset_pool.d.ts

@@ -0,0 +1,82 @@
+import { ChunkedPool } from "./chunked_pool.js";
+/**
+ * Refcounted **assets** resident in a {@link ChunkedPool} — the sharing layer
+ * of the memory system (see `src/core/mem/`).
+ *
+ * The general relationship this models: many **instances** reference shared
+ * **assets** (the definition/occurrence split that recurs across CAD — STEP
+ * AP214 literally names it *occurrence*). Concretely for geometry: products
+ * are instances, representation geometry is the asset, and mapped items make
+ * many products share one representation. But nothing here is
+ * geometry-specific — an asset is any refcounted, chunk-resident payload
+ * (a parsed property block, a decoded sidecar, a texture).
+ *
+ * Storage is keyed and refcounted on the **asset**, so the correctness rule
+ * for shared data falls out structurally: releasing one instance's reference
+ * never frees an asset another instance still holds; chunks return to the
+ * pool only on the last release. (Evicting product A must not free the
+ * representation product B still renders — the mapped-item bug a
+ * per-instance store invites.)
+ *
+ * Instance-level bookkeeping (which assets an instance holds, demand
+ * priorities, eviction order) belongs to the layer above — see
+ * `GeometryTilePool` for the geometry narrowing and `DemandGeometryQueue`
+ * for the scheduling policy.
+ */
+export declare class SharedAssetPool<AssetID> {
+    private readonly pool_;
+    private readonly assets_;
+    /**
+     * @param pool The chunk pool assets reside in.
+     */
+    constructor(pool: ChunkedPool);
+    /**
+     * @return {ChunkedPool} The underlying chunk pool.
+     */
+    get pool(): ChunkedPool;
+    /**
+     * @return {number} The number of resident assets.
+     */
+    get assetCount(): number;
+    /**
+     * Take a reference on an asset, acquiring chunks for it if it is not yet
+     * resident. All-or-nothing: returns false (and changes nothing) only when
+     * the asset is absent and the pool can't fit it — the caller's cue to evict
+     * and retry. A `wasAbsent` result of true tells the caller to materialise
+     * the payload into the asset's chunks (the 0→1 transition).
+     *
+     * @param assetID The asset to reference.
+     * @param byteSize Its payload size (used only on first residency).
+     * @return {{ retained: boolean, wasAbsent: boolean }} Whether the reference
+     * was taken, and whether this was the residency-creating reference.
+     */
+    retain(assetID: AssetID, byteSize: number): {
+        retained: boolean;
+        wasAbsent: boolean;
+    };
+    /**
+     * Drop a reference on an asset. On the last reference (1→0) the asset's
+     * chunks return to the pool and the caller should discard the payload.
+     *
+     * @param assetID The asset to release.
+     * @return {boolean} True if this was the last reference (asset freed).
+     */
+    release(assetID: AssetID): boolean;
+    /**
+     * @param assetID The asset to check.
+     * @return {boolean} True if the asset is resident.
+     */
+    isResident(assetID: AssetID): boolean;
+    /**
+     * @param assetID The asset to query.
+     * @return {number} The asset's current reference count (0 if absent).
+     */
+    refCountOf(assetID: AssetID): number;
+    /**
+     * @param assetID The asset to query.
+     * @return {number} The asset's physical (chunk-rounded) resident bytes
+     * (0 if absent).
+     */
+    physicalBytesOf(assetID: AssetID): number;
+}
+//# sourceMappingURL=shared_asset_pool.d.ts.map

package/compiled/src/core/mem/shared_asset_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared_asset_pool.d.ts","sourceRoot":"","sources":["../../../../src/core/mem/shared_asset_pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAa,MAAM,gBAAgB,CAAA;AAGvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe,CAAC,OAAO;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4D;IAEpF;;OAEG;gBACU,IAAI,EAAE,WAAW;IAI9B;;OAEG;IACH,IAAW,IAAI,IAAI,WAAW,CAE7B;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;;;;;;;OAWG;IACI,MAAM,CAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAC7C;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAoB7C;;;;;;OAMG;IACI,OAAO,CAAE,OAAO,EAAE,OAAO,GAAI,OAAO;IAkB3C;;;OAGG;IACI,UAAU,CAAE,OAAO,EAAE,OAAO,GAAI,OAAO;IAI9C;;;OAGG;IACI,UAAU,CAAE,OAAO,EAAE,OAAO,GAAI,MAAM;IAI7C;;;;OAIG;IACI,eAAe,CAAE,OAAO,EAAE,OAAO,GAAI,MAAM;CAOnD"}

package/compiled/src/core/mem/shared_asset_pool.js

@@ -0,0 +1,113 @@
+/**
+ * Refcounted **assets** resident in a {@link ChunkedPool} — the sharing layer
+ * of the memory system (see `src/core/mem/`).
+ *
+ * The general relationship this models: many **instances** reference shared
+ * **assets** (the definition/occurrence split that recurs across CAD — STEP
+ * AP214 literally names it *occurrence*). Concretely for geometry: products
+ * are instances, representation geometry is the asset, and mapped items make
+ * many products share one representation. But nothing here is
+ * geometry-specific — an asset is any refcounted, chunk-resident payload
+ * (a parsed property block, a decoded sidecar, a texture).
+ *
+ * Storage is keyed and refcounted on the **asset**, so the correctness rule
+ * for shared data falls out structurally: releasing one instance's reference
+ * never frees an asset another instance still holds; chunks return to the
+ * pool only on the last release. (Evicting product A must not free the
+ * representation product B still renders — the mapped-item bug a
+ * per-instance store invites.)
+ *
+ * Instance-level bookkeeping (which assets an instance holds, demand
+ * priorities, eviction order) belongs to the layer above — see
+ * `GeometryTilePool` for the geometry narrowing and `DemandGeometryQueue`
+ * for the scheduling policy.
+ */
+export class SharedAssetPool {
+    /**
+     * @param pool The chunk pool assets reside in.
+     */
+    constructor(pool) {
+        this.assets_ = new Map();
+        this.pool_ = pool;
+    }
+    /**
+     * @return {ChunkedPool} The underlying chunk pool.
+     */
+    get pool() {
+        return this.pool_;
+    }
+    /**
+     * @return {number} The number of resident assets.
+     */
+    get assetCount() {
+        return this.assets_.size;
+    }
+    /**
+     * Take a reference on an asset, acquiring chunks for it if it is not yet
+     * resident. All-or-nothing: returns false (and changes nothing) only when
+     * the asset is absent and the pool can't fit it — the caller's cue to evict
+     * and retry. A `wasAbsent` result of true tells the caller to materialise
+     * the payload into the asset's chunks (the 0→1 transition).
+     *
+     * @param assetID The asset to reference.
+     * @param byteSize Its payload size (used only on first residency).
+     * @return {{ retained: boolean, wasAbsent: boolean }} Whether the reference
+     * was taken, and whether this was the residency-creating reference.
+     */
+    retain(assetID, byteSize) {
+        const existing = this.assets_.get(assetID);
+        if (existing !== void 0) {
+            ++existing.refCount;
+            return { retained: true, wasAbsent: false };
+        }
+        const span = this.pool_.acquire(byteSize);
+        if (span === void 0) {
+            return { retained: false, wasAbsent: true };
+        }
+        this.assets_.set(assetID, { span, refCount: 1 });
+        return { retained: true, wasAbsent: true };
+    }
+    /**
+     * Drop a reference on an asset. On the last reference (1→0) the asset's
+     * chunks return to the pool and the caller should discard the payload.
+     *
+     * @param assetID The asset to release.
+     * @return {boolean} True if this was the last reference (asset freed).
+     */
+    release(assetID) {
+        const asset = this.assets_.get(assetID);
+        if (asset === void 0) {
+            throw new Error(`Release of non-resident asset ${String(assetID)}`);
+        }
+        if (--asset.refCount > 0) {
+            return false;
+        }
+        this.pool_.release(asset.span);
+        this.assets_.delete(assetID);
+        return true;
+    }
+    /**
+     * @param assetID The asset to check.
+     * @return {boolean} True if the asset is resident.
+     */
+    isResident(assetID) {
+        return this.assets_.has(assetID);
+    }
+    /**
+     * @param assetID The asset to query.
+     * @return {number} The asset's current reference count (0 if absent).
+     */
+    refCountOf(assetID) {
+        return this.assets_.get(assetID)?.refCount ?? 0;
+    }
+    /**
+     * @param assetID The asset to query.
+     * @return {number} The asset's physical (chunk-rounded) resident bytes
+     * (0 if absent).
+     */
+    physicalBytesOf(assetID) {
+        const asset = this.assets_.get(assetID);
+        return asset === void 0 ?
+            0 : asset.span.chunks.length * this.pool_.chunkBytes;
+    }
+}

package/compiled/src/core/mem/shared_asset_pool.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shared_asset_pool.test.d.ts.map

package/compiled/src/core/mem/shared_asset_pool.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared_asset_pool.test.d.ts","sourceRoot":"","sources":["../../../../src/core/mem/shared_asset_pool.test.ts"],"names":[],"mappings":""}

package/compiled/src/core/mem/shared_asset_pool.test.js

@@ -0,0 +1,49 @@
+/* eslint-disable no-magic-numbers */
+// mem: assets are stored once and refcounted — the sharing layer's rule is
+// that a release never frees an asset another holder still references.
+import { describe, expect, test } from "@jest/globals";
+import { ChunkedPool } from "./chunked_pool.js";
+import { SharedAssetPool } from "./shared_asset_pool.js";
+describe("SharedAssetPool", () => {
+    test("first retain acquires chunks and reports wasAbsent", () => {
+        const assets = new SharedAssetPool(new ChunkedPool(1000, 100));
+        const first = assets.retain("rep-A", 250);
+        expect(first).toEqual({ retained: true, wasAbsent: true });
+        expect(assets.isResident("rep-A")).toBe(true);
+        expect(assets.physicalBytesOf("rep-A")).toBe(300);
+        expect(assets.pool.bytesInUse).toBe(300);
+    });
+    test("a second retain shares storage instead of duplicating it", () => {
+        const assets = new SharedAssetPool(new ChunkedPool(1000, 100));
+        assets.retain("rep-A", 250);
+        const second = assets.retain("rep-A", 250);
+        expect(second).toEqual({ retained: true, wasAbsent: false });
+        expect(assets.refCountOf("rep-A")).toBe(2);
+        // Stored once: physical bytes unchanged.
+        expect(assets.pool.bytesInUse).toBe(300);
+    });
+    test("release frees only on the last reference", () => {
+        const assets = new SharedAssetPool(new ChunkedPool(1000, 100));
+        assets.retain("rep-A", 100);
+        assets.retain("rep-A", 100);
+        expect(assets.release("rep-A")).toBe(false);
+        expect(assets.isResident("rep-A")).toBe(true);
+        expect(assets.pool.bytesInUse).toBe(100);
+        expect(assets.release("rep-A")).toBe(true);
+        expect(assets.isResident("rep-A")).toBe(false);
+        expect(assets.pool.bytesInUse).toBe(0);
+    });
+    test("retain fails cleanly when the pool cannot fit a new asset", () => {
+        const assets = new SharedAssetPool(new ChunkedPool(200, 100));
+        assets.retain("rep-A", 200);
+        const refused = assets.retain("rep-B", 100);
+        expect(refused).toEqual({ retained: false, wasAbsent: true });
+        expect(assets.isResident("rep-B")).toBe(false);
+        // A retain of an already-resident asset still succeeds at full pool.
+        expect(assets.retain("rep-A", 200).retained).toBe(true);
+    });
+    test("releasing a non-resident asset is an error, not a silent no-op", () => {
+        const assets = new SharedAssetPool(new ChunkedPool(100, 100));
+        expect(() => assets.release("ghost")).toThrow(/non-resident/);
+    });
+});