@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/core/progress_log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress_log.d.ts","sourceRoot":"","sources":["../../../src/core/progress_log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM,CAQlD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAE,OAAO,CAAC,EAAE,MAAM,GAAI,MAAM,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAE,YAAY,EAAE,MAAM,GAAI,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM,CA0BzD;AA0DD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;;OAKG;IACI,YAAY,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM;IAM9C;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,iBAAiB,GAAI,MAAM,GAAG,SAAS;IA6CjE;;;;;;;;OAQG;IACI,iBAAiB,CAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAI,MAAM,GAAG,SAAS;IAuBzF;;;;OAIG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;IAQxC;;;;OAIG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAY1B;;;;;OAKG;IACI,QAAQ,IAAI,MAAM,EAAE;CAY5B"}
+{"version":3,"file":"progress_log.d.ts","sourceRoot":"","sources":["../../../src/core/progress_log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM,CAQlD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAE,OAAO,CAAC,EAAE,MAAM,GAAI,MAAM,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAE,YAAY,EAAE,MAAM,GAAI,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM,CA0BzD;AA6DD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;;OAKG;IACI,YAAY,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM;IAM9C;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,iBAAiB,GAAI,MAAM,GAAG,SAAS;IAiDjE;;;;;;;;OAQG;IACI,iBAAiB,CAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAI,MAAM,GAAG,SAAS;IAuBzF;;;;OAIG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;IAQxC;;;;OAIG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAY1B;;;;;OAKG;IACI,QAAQ,IAAI,MAAM,EAAE;CAY5B"}

package/compiled/src/core/progress_log.js

@@ -143,14 +143,16 @@ function heapDeltaSuffix(state) {
 function formatStageLine(state, final) {
     const duration = state.lastElapsedMs - state.startElapsedMs;
     const heap = heapDeltaSuffix(state);
+    const window = state.residentSourceMb !== void 0 ?
+        `, window=${formatMb(state.residentSourceMb)} MB` : '';
     const determinate = state.percent !== void 0;
     // Completed: no bar, colon-separated. A determinate stage that stopped
     // short of 100% is a failure — keep its bar to show the reach.
     if (final && !(determinate && state.percent < PERCENT)) {
-        return `${state.label}: ${formatSeconds(duration)}${heap}`;
+        return `${state.label}: ${formatSeconds(duration)}${heap}${window}`;
     }
     const bar = formatBar(determinate ? state.percent : void 0);
-    return `${state.label} ${bar} ${formatSeconds(duration)}${heap}`;
+    return `${state.label} ${bar} ${formatSeconds(duration)}${heap}${window}`;
 }
 /**
  * Accumulates progress events into the normalized text report: a live
@@ -211,6 +213,9 @@ export class LoadLogAccumulator {
             current.startHeapMb ??= event.memoryMb;
             current.lastHeapMb = event.memoryMb;
         }
+        if (event.residentSourceMb !== void 0) {
+            current.residentSourceMb = event.residentSourceMb;
+        }
         if (event.total !== void 0 && event.total > 0) {
             current.percent = (event.completed / event.total) * PERCENT;
         }

package/compiled/src/core/progress_log.test.js

@@ -76,6 +76,27 @@ describe("LoadLogAccumulator", () => {
         expect(log.finishedLines()[0]).toBe("Geometry: 16.500s, +220.000000 MB heap");
         expect(log.totalLine()).toBe("Total: 16.500s, 500.000000 \u2192 720.000000 MB heap");
     });
+    test("appends window residency on the Geometry line when provided", () => {
+        const log = new LoadLogAccumulator();
+        log.onProgress({
+            phase: "geometry",
+            completed: 0,
+            total: 10,
+            elapsedMs: 0,
+            memoryMb: 100,
+            residentSourceMb: 64,
+        });
+        log.onProgress({
+            phase: "geometry",
+            completed: 10,
+            total: 10,
+            elapsedMs: 1000,
+            memoryMb: 120,
+            residentSourceMb: 64,
+        });
+        log.closeCurrentStage();
+        expect(log.finishedLines()[0]).toBe("Geometry: 1.000s, +20.000000 MB heap, window=64.000000 MB");
+    });
     test("handles indeterminate stages and missing memory", () => {
         const log = new LoadLogAccumulator();
         log.onProgress({ phase: "geometry", completed: 0, elapsedMs: 0 });

package/compiled/src/core/shared_byte_budget.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A byte budget shared across many models (M5 / design S3).
+ *
+ * The federation invariant: budgets must be **per browser, not per model**, or
+ * opening N cross-referenced files re-introduces O(N) memory. This is the one
+ * accounting primitive that enforces it — every model's demand-geometry queue
+ * and window pool draws from a single {@link SharedByteBudget}, so the total
+ * resident footprint across all open models is bounded no matter how many are
+ * federated in.
+ *
+ * It owns only the accounting (reserve / release / availability); the eviction
+ * policy that frees bytes when a reservation can't be met stays with each
+ * model's scheduler (M3's {@link DemandGeometryQueue}) — the budget just tells
+ * a caller how much it must evict first via {@link overageFor}.
+ */
+export declare class SharedByteBudget {
+    private readonly totalBytes_;
+    private used_;
+    /**
+     * @param totalBytes_ The global ceiling shared across all models.
+     */
+    constructor(totalBytes_: number);
+    /**
+     * @return {number} The global ceiling.
+     */
+    get total(): number;
+    /**
+     * @return {number} Bytes currently reserved across all models.
+     */
+    get used(): number;
+    /**
+     * @return {number} Bytes still reservable without eviction.
+     */
+    get available(): number;
+    /**
+     * Try to reserve `bytes` against the shared ceiling. Succeeds (and charges
+     * the budget) only if it fits without exceeding the total; otherwise makes
+     * no change and returns false, leaving the caller to evict and retry.
+     *
+     * @param bytes The bytes to reserve (≥ 0).
+     * @return {boolean} True if reserved.
+     */
+    reserve(bytes: number): boolean;
+    /**
+     * Release previously reserved bytes back to the shared budget.
+     *
+     * @param bytes The bytes to release (≥ 0). Clamped so `used` never goes
+     * negative — a double-release is a no-op past zero, not a corruption.
+     */
+    release(bytes: number): void;
+    /**
+     * How many bytes a caller must evict (anywhere, across any model) before a
+     * reservation of `bytes` would fit. Zero when it already fits.
+     *
+     * @param bytes The desired reservation.
+     * @return {number} The bytes of eviction required (≥ 0).
+     */
+    overageFor(bytes: number): number;
+}
+//# sourceMappingURL=shared_byte_budget.d.ts.map

package/compiled/src/core/shared_byte_budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared_byte_budget.d.ts","sourceRoot":"","sources":["../../../src/core/shared_byte_budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAOd,OAAO,CAAC,QAAQ,CAAC,WAAW;IALzC,OAAO,CAAC,KAAK,CAAI;IAEjB;;OAEG;gBAC2B,WAAW,EAAE,MAAM;IAOjD;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;;;;OAOG;IACI,OAAO,CAAE,KAAK,EAAE,MAAM,GAAI,OAAO;IAexC;;;;;OAKG;IACI,OAAO,CAAE,KAAK,EAAE,MAAM,GAAI,IAAI;IASrC;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM;CAG3C"}

package/compiled/src/core/shared_byte_budget.js

@@ -0,0 +1,85 @@
+/**
+ * A byte budget shared across many models (M5 / design S3).
+ *
+ * The federation invariant: budgets must be **per browser, not per model**, or
+ * opening N cross-referenced files re-introduces O(N) memory. This is the one
+ * accounting primitive that enforces it — every model's demand-geometry queue
+ * and window pool draws from a single {@link SharedByteBudget}, so the total
+ * resident footprint across all open models is bounded no matter how many are
+ * federated in.
+ *
+ * It owns only the accounting (reserve / release / availability); the eviction
+ * policy that frees bytes when a reservation can't be met stays with each
+ * model's scheduler (M3's {@link DemandGeometryQueue}) — the budget just tells
+ * a caller how much it must evict first via {@link overageFor}.
+ */
+export class SharedByteBudget {
+    /**
+     * @param totalBytes_ The global ceiling shared across all models.
+     */
+    constructor(totalBytes_) {
+        this.totalBytes_ = totalBytes_;
+        this.used_ = 0;
+        if (totalBytes_ <= 0) {
+            throw new Error(`Invalid totalBytes ${totalBytes_}`);
+        }
+    }
+    /**
+     * @return {number} The global ceiling.
+     */
+    get total() {
+        return this.totalBytes_;
+    }
+    /**
+     * @return {number} Bytes currently reserved across all models.
+     */
+    get used() {
+        return this.used_;
+    }
+    /**
+     * @return {number} Bytes still reservable without eviction.
+     */
+    get available() {
+        return this.totalBytes_ - this.used_;
+    }
+    /**
+     * Try to reserve `bytes` against the shared ceiling. Succeeds (and charges
+     * the budget) only if it fits without exceeding the total; otherwise makes
+     * no change and returns false, leaving the caller to evict and retry.
+     *
+     * @param bytes The bytes to reserve (≥ 0).
+     * @return {boolean} True if reserved.
+     */
+    reserve(bytes) {
+        if (bytes < 0) {
+            throw new Error(`Cannot reserve negative bytes ${bytes}`);
+        }
+        if (bytes > this.available) {
+            return false;
+        }
+        this.used_ += bytes;
+        return true;
+    }
+    /**
+     * Release previously reserved bytes back to the shared budget.
+     *
+     * @param bytes The bytes to release (≥ 0). Clamped so `used` never goes
+     * negative — a double-release is a no-op past zero, not a corruption.
+     */
+    release(bytes) {
+        if (bytes < 0) {
+            throw new Error(`Cannot release negative bytes ${bytes}`);
+        }
+        this.used_ = Math.max(0, this.used_ - bytes);
+    }
+    /**
+     * How many bytes a caller must evict (anywhere, across any model) before a
+     * reservation of `bytes` would fit. Zero when it already fits.
+     *
+     * @param bytes The desired reservation.
+     * @return {number} The bytes of eviction required (≥ 0).
+     */
+    overageFor(bytes) {
+        return Math.max(0, bytes - this.available);
+    }
+}

package/compiled/src/core/shared_byte_budget.test.d.ts

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

package/compiled/src/core/shared_byte_budget.test.d.ts.map

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

package/compiled/src/core/shared_byte_budget.test.js

@@ -0,0 +1,55 @@
+/* eslint-disable no-magic-numbers */
+// M5: the per-browser shared budget is what keeps federation from re-growing
+// memory O(N) with the number of open models — reservations across all models
+// draw from one ceiling.
+import { describe, expect, test } from "@jest/globals";
+import { SharedByteBudget } from "./shared_byte_budget.js";
+describe("SharedByteBudget", () => {
+    test("reserves up to the ceiling and refuses to overcommit", () => {
+        const budget = new SharedByteBudget(1000);
+        expect(budget.reserve(600)).toBe(true);
+        expect(budget.reserve(300)).toBe(true);
+        expect(budget.used).toBe(900);
+        expect(budget.available).toBe(100);
+        // 200 doesn't fit in the remaining 100 — refused, no change.
+        expect(budget.reserve(200)).toBe(false);
+        expect(budget.used).toBe(900);
+    });
+    test("releasing frees room for later reservations", () => {
+        const budget = new SharedByteBudget(1000);
+        budget.reserve(800);
+        expect(budget.reserve(300)).toBe(false);
+        budget.release(500);
+        expect(budget.used).toBe(300);
+        expect(budget.reserve(300)).toBe(true);
+    });
+    test("release clamps at zero (a double release is not corruption)", () => {
+        const budget = new SharedByteBudget(1000);
+        budget.reserve(100);
+        budget.release(100);
+        budget.release(100);
+        expect(budget.used).toBe(0);
+    });
+    test("overageFor reports how much must be evicted before a reservation fits", () => {
+        const budget = new SharedByteBudget(1000);
+        budget.reserve(700);
+        // 500 wanted, 300 available → must evict 200.
+        expect(budget.overageFor(500)).toBe(200);
+        // 200 wanted, 300 available → fits, no eviction.
+        expect(budget.overageFor(200)).toBe(0);
+    });
+    test("the ceiling is shared: two models cannot each spend the whole budget", () => {
+        const budget = new SharedByteBudget(1000);
+        // "Model A" and "model B" both draw from the same budget.
+        expect(budget.reserve(700)).toBe(true); // A
+        expect(budget.reserve(700)).toBe(false); // B — only 300 left
+        expect(budget.reserve(300)).toBe(true); // B fits in the remainder
+        expect(budget.used).toBe(budget.total);
+    });
+    test("rejects an invalid ceiling and negative amounts", () => {
+        expect(() => new SharedByteBudget(0)).toThrow();
+        const budget = new SharedByteBudget(10);
+        expect(() => budget.reserve(-1)).toThrow();
+        expect(() => budget.release(-1)).toThrow();
+    });
+});

package/compiled/src/core/wasm_heap.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Reading and writing the wasm heap from JS, through views that are known to
+ * belong to the heap as it is RIGHT NOW.
+ *
+ * This lives in one place because the two geometry extractors had a copy each,
+ * and the copies had drifted: one honoured the source view's window and the
+ * other did not, and neither checked what _malloc returned. The failure modes
+ * are quiet enough to be worth naming here.
+ *
+ * See bldrs-ai/conway#485 for what an uninstrumented failure on this path
+ * costs: `Invalid typed array length: 80`, no context, and two sightings
+ * across two models before it could even be located.
+ *
+ * The confirmed mechanism behind #485
+ * -----------------------------------
+ * conway's MT builds create their memory as
+ * `new WebAssembly.Memory({ initial, maximum: 65536, shared: true })` with no
+ * `maxByteLength`, so `wasmMemory.buffer` is a **non-extensible**
+ * SharedArrayBuffer - `growable === false`, `maxByteLength === byteLength`
+ * (verified against Dist/ConwayGeomWasmNodeMT.js and by inspecting a live
+ * module). A non-extensible buffer cannot grow in place, so
+ * `WebAssembly.Memory.grow()` materialises a NEW SharedArrayBuffer, which the
+ * `.buffer` getter hands out from then on.
+ *
+ * emscripten rebuilds `Module.HEAPU8` and friends over that new buffer in
+ * `updateMemoryViews()` - but only on the thread that did the growing, and
+ * only when its own glue passes through `growMemViews()`. Growth driven by a
+ * pthread runs `updateMemoryViews()` in the WORKER's JS scope; the main
+ * thread's `Module.HEAPU8` stays bound to the pre-growth buffer until some
+ * main-thread glue call happens to run `growMemViews()`. `_malloc` is a raw
+ * wasm export, so it is not one of those calls: it can hand back an address in
+ * the newly added region while the JS-side view still ends before it. That is
+ * exactly the state #498's diagnostic captured in CI - view length equal to
+ * its own buffer's byteLength (so not stale relative to that buffer),
+ * `extensible false` (so that buffer never grew), and the pointer past the end
+ * of both.
+ *
+ * Which is why every view here is built through wasmHeapView(): it re-reads
+ * the module's view, reconciles it against the pointer, and only then
+ * constructs.
+ */
+/**
+ * What the wasm module exposes that this needs. Deliberately narrow.
+ *
+ * Everything past `HEAPU8` is a refresh route that MAY be present; see
+ * refreshHeapViews for what each one is worth and which of them conway's
+ * current builds actually have.
+ */
+export interface WasmHeapModule {
+    _malloc(bytes: number): number;
+    _free(pointer: number): void;
+    HEAPU8: Uint8Array;
+    /**
+     * emscripten's own view rebuilder, if the build exports it. Not exported by
+     * any conway build today.
+     */
+    updateMemoryViews?: () => void;
+    /**
+     * The live `WebAssembly.Memory`, if the build exposes it. Its `.buffer`
+     * getter always yields the current buffer, which makes staleness
+     * unrepresentable. Not exposed by any conway build today.
+     */
+    wasmMemory?: {
+        readonly buffer: ArrayBufferLike;
+    };
+    /**
+     * embind's `std::vector<std::string>`. Present on every conway-geom build;
+     * used as a refresh route of last resort (see refreshHeapViews).
+     */
+    stringVector?: new () => {
+        push_back(value: string): void;
+        delete(): void;
+    };
+}
+export type CopyableArray = Float32Array | Float64Array | Uint32Array;
+/**
+ * The part of a typed-array constructor wasmHeapView needs: build over a
+ * buffer at a byte offset, and say how wide an element is.
+ */
+export interface WasmHeapArrayConstructor<TArray> {
+    new (buffer: ArrayBufferLike, byteOffset: number, length: number): TArray;
+    readonly BYTES_PER_ELEMENT: number;
+}
+/**
+ * Build a typed-array view over a region of the wasm heap.
+ *
+ * Every view onto the heap in this repo goes through here, because the
+ * property that makes a view safe - that its buffer is the heap's CURRENT
+ * buffer - is not something a caller can check by looking at its own code. It
+ * depends on whether some other thread grew the heap between the call that
+ * produced `pointer` and this line.
+ *
+ * Two things beyond the reconcile are worth knowing:
+ *
+ * - The pointer is normalised to unsigned. Pointers reaching JS from raw i32
+ *   wasm exports arrive NEGATIVE once the heap passes 2GB, and every target
+ *   builds with `maximum: 65536` pages (4GB), so that is a reachable state and
+ *   not a theoretical one. (This build's `applySignatureConversions` already
+ *   wraps `_malloc` as `a0 => f(a0) >>> 0`; pointers from other exports and
+ *   from other builds are not covered by that, so it is done here too.)
+ * - A view is CONSTRUCTED rather than `subarray`d off the module's view.
+ *   `subarray` silently clamps an out-of-range window, which turns "the heap
+ *   moved" into a short view and then into a copy that lands somewhere else
+ *   entirely; the constructor throws instead, and by then the reconcile has
+ *   already made throwing the right answer.
+ *
+ * @param wasmModule The module owning the heap.
+ * @param arrayType The typed-array constructor for the element type wanted.
+ * @param pointer Byte address in the heap, signed or unsigned.
+ * @param elementCount How many elements the view spans.
+ * @return {TArray} A view over the live heap. Do not retain it across any
+ * further call into wasm.
+ */
+export declare function wasmHeapView<TArray>(wasmModule: WasmHeapModule, arrayType: WasmHeapArrayConstructor<TArray>, pointer: number, elementCount: number): TArray;
+/**
+ * How many bytes of wasm heap there currently are.
+ *
+ * Refreshes first, unconditionally - which is the opposite of what
+ * wasmHeapView does, and deliberate. There is nothing to compare a size
+ * against, so lag here cannot be detected the way an out-of-range pointer can;
+ * and `HEAPU8.length` on its own under-reports by a whole growth step whenever
+ * the module's views are behind (see this file's header), which is the one
+ * thing a high-water figure must not do. This is a reporting call - a line at
+ * the end of a run - so paying microseconds for a true answer is the right
+ * trade. Do not put it in a loop.
+ *
+ * That the refresh cannot throw (see refreshHeapViews) matters more here than
+ * at the other call site: this figure's only consumer is the AP214 CLI's
+ * high-water log line, so an embind failure escaping would abort an otherwise
+ * complete extraction from a log statement. A lagging number is the right
+ * answer there.
+ *
+ * @param wasmModule The module to measure.
+ * @return {number} The heap's size in bytes, or 0 if it has no heap yet.
+ */
+export declare function wasmHeapByteLength(wasmModule: WasmHeapModule): number;
+/**
+ * Copy an array into a fresh wasm heap allocation.
+ *
+ * @param wasmModule The module to allocate in.
+ * @param array The data to copy. May be a view into a larger buffer.
+ * @return {number} Pointer to the copy, owned by the caller.
+ */
+export declare function arrayToWasmHeap(wasmModule: WasmHeapModule, array: CopyableArray): number;
+/**
+ * Copy several arrays into the wasm heap, all or nothing.
+ *
+ * arrayToWasmHeap throws on a failed allocation, which is the right thing on
+ * its own but turns a caller that allocates N buffers before freeing any into
+ * a leak: the throw on buffer 2 strands buffer 1, the per-record catch
+ * upstream moves to the next record, and the leak repeats - accelerating the
+ * exhaustion being reported. Callers that hold several at once use this
+ * instead, which frees what it took before letting the error out.
+ *
+ * @param wasmModule The module to allocate in.
+ * @param arrays The data to copy, in order.
+ * @return {number[]} Pointers in the same order, owned by the caller.
+ */
+export declare function arraysToWasmHeap(wasmModule: WasmHeapModule, arrays: readonly CopyableArray[]): number[];
+/**
+ * Run a resource release so it cannot replace an exception already in flight.
+ *
+ * Releases here re-enter the wasm runtime - _free, embind delete(), returning
+ * a pooled buffer - and they run from finally blocks that may be unwinding
+ * because that runtime just failed. A throw from one of them would REPLACE the
+ * original error, so the caller upstream would see a generic teardown failure
+ * instead of the diagnostic that says what actually went wrong. Losing the
+ * cause is strictly worse than failing to reclaim memory on a path where the
+ * heap is already lost.
+ *
+ * Reported at debug rather than swallowed outright, so it is still findable
+ * with -vv, and NOT at warning/error: this runs during teardown of an already
+ * failing record, where a second message would be noise on top of the one that
+ * matters.
+ *
+ * @param release The release step to run.
+ */
+export declare function releaseQuietly(release: () => void): void;
+/**
+ * Run `body`, then release - propagating a release failure on success, and
+ * suppressing it only when something is already being unwound.
+ *
+ * That asymmetry is the point. releaseQuietly on its own is right during
+ * unwinding and wrong otherwise: on the success path a teardown failure is a
+ * real fault with nothing competing to report it, and swallowing it would let
+ * a record be reported COMPLETE while its resources were never reclaimed. So
+ * the quiet treatment applies to exactly the case it was argued for.
+ *
+ * @param body The work that needs the resource.
+ * @param release How to give the resource back.
+ * @return {T} Whatever body returned.
+ */
+export declare function withRelease<T>(body: () => T, release: () => void): T;
+/**
+ * Free several pointers, independently.
+ *
+ * One failing free must not abandon the rest - batching them into a single
+ * statement means the first failure strands every pointer after it - and it
+ * must not be lost either, so the first error is re-thrown once they have all
+ * been attempted. Combined with withRelease that gives the wanted behaviour on
+ * both paths: everything is freed either way, and the failure surfaces on the
+ * success path while staying quiet during unwinding.
+ *
+ * @param wasmModule The module the pointers belong to.
+ * @param pointers The allocations to release.
+ */
+export declare function freeAll(wasmModule: WasmHeapModule, pointers: readonly number[]): void;
+//# sourceMappingURL=wasm_heap.d.ts.map

package/compiled/src/core/wasm_heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm_heap.d.ts","sourceRoot":"","sources":["../../../src/core/wasm_heap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM,CAAA;IAChC,KAAK,CAAE,OAAO,EAAE,MAAM,GAAI,IAAI,CAAA;IAC9B,MAAM,EAAE,UAAU,CAAA;IAElB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAE9B;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAEjD;;;OAGG;IACH,YAAY,CAAC,EAAE,UAAU;QAAE,SAAS,CAAE,KAAK,EAAE,MAAM,GAAI,IAAI,CAAC;QAAC,MAAM,IAAI,IAAI,CAAA;KAAE,CAAA;CAC9E;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,CAAA;AAMrE;;;GAGG;AACH,MAAM,WAAW,wBAAwB,CAAE,MAAM;IAC/C,KAAM,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAI,MAAM,CAAA;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC;AA6MD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAE,MAAM,EAChC,UAAU,EAAE,cAAc,EAC1B,SAAS,EAAE,wBAAwB,CAAE,MAAM,CAAE,EAC7C,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAI,MAAM,CASjC;AAGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAE,UAAU,EAAE,cAAc,GAAI,MAAM,CAKvE;AAGD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC3B,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,GAAI,MAAM,CA8C7D;AAGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC5B,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,GAAI,MAAM,EAAE,CAqB/C;AAGD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAE,OAAO,EAAE,MAAM,IAAI,GAAI,IAAI,CAW1D;AAGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAG,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,GAAI,CAAC,CAiBtE;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CACnB,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAI,IAAI,CAkBlE"}