@bldrs-ai/conway 1.401.1237 → 1.404.1241

package/compiled/examples/browser-bundled.cjs

@@ -30,7 +30,7 @@ var import_node_process = require("node:process");
 var readline = __toESM(require("node:readline"), 1);
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.401.1237";
+var versionString = "Conway v1.404.1241";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/examples/cli-bundled.cjs

@@ -14965,7 +14965,7 @@ ${t5.join("\n")}` : "";
 var import_process = require("process");
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.401.1237";
+var versionString = "Conway v1.404.1241";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/cli-step-bundled.cjs

@@ -15943,7 +15943,7 @@ var ParsingBuffer = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.401.1237";
+var versionString = "Conway v1.404.1241";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/validator-bundled.cjs

@@ -944,7 +944,7 @@ var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.401.1237";
+var versionString = "Conway v1.404.1241";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

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

@@ -0,0 +1,147 @@
+/**
+ * Demand-driven, budgeted geometry materialisation (M3).
+ *
+ * The streaming loader inverts geometry: instead of extracting every product
+ * up front, extraction becomes a **cache fill keyed by product**, ordered by
+ * demand (viewport frustum + distance, explicit selection, prefetch hints)
+ * and bounded by an explicit byte budget. This module is the scheduler: a
+ * priority queue over product local IDs plus an evictable resident set, with
+ * the actual extract / release delegated to a pluggable {@link GeometryTiles}.
+ *
+ * The heavy half — the wasm-side extract → tessellate → upload and the
+ * per-product native reclaim — lives behind {@link GeometryTiles}. Its
+ * production implementation needs a **conway-geom API to free one product's
+ * native geometry** (today the wasm heap has no per-product reclaim); scoping
+ * that C++ surface is the M3 blocker tracked in the design doc. This scheduler
+ * is engine-side, fully deterministic, and tested against a mock tiles impl,
+ * so the queue/budget/eviction policy is settled independently of the wasm
+ * work.
+ */
+/**
+ * The per-product geometry work behind the queue. Implementations do the
+ * expensive materialisation; the queue owns only ordering and the budget.
+ */
+export interface GeometryTiles {
+    /**
+     * Materialise a product's geometry tile and return its resident cost in
+     * bytes (GPU/scene + any retained wasm working set the budget should count).
+     * Called at most once per product between evictions.
+     *
+     * @param productLocalID The product's local ID.
+     * @return {number} The tile's resident byte cost (≥ 0).
+     */
+    extract(productLocalID: number): number;
+    /**
+     * Release a product's materialised tile, freeing its resident bytes — the
+     * scene mesh and, crucially, the product's native (wasm) geometry. This is
+     * the per-product reclaim the production conway-geom surface must provide.
+     *
+     * @param productLocalID The product's local ID.
+     */
+    release(productLocalID: number): void;
+}
+/**
+ * Runtime counters for a queue, for tests and telemetry.
+ */
+export interface DemandQueueStats {
+    extractions: number;
+    evictions: number;
+    residentBytes: number;
+    residentCount: number;
+    pendingCount: number;
+}
+/**
+ * A budgeted, demand-ordered geometry materialisation queue.
+ *
+ * Usage: `request(productLocalID, priority)` as demand changes (higher
+ * priority = more wanted); `pump()` to materialise the most-wanted pending
+ * products until the queue drains or the byte budget forces eviction of
+ * lower-priority resident tiles. Re-requesting an evicted product re-fills it.
+ * A steady stream of `request` + `pump` keeps a bounded working set of the
+ * highest-priority products resident — the "full model navigable under a
+ * fixed budget" behaviour.
+ */
+export declare class DemandGeometryQueue {
+    private readonly tiles_;
+    private readonly budgetBytes_;
+    /** Highest priority a product currently wants materialising at. */
+    private readonly pending_;
+    /** Resident tiles by product local ID. */
+    private readonly resident_;
+    private residentBytes_;
+    private extractions_;
+    private evictions_;
+    /**
+     * @param tiles The extract/release backend.
+     * @param budgetBytes Maximum resident tile bytes before eviction kicks in.
+     */
+    constructor(tiles: GeometryTiles, budgetBytes: number);
+    /**
+     * Request a product be materialised at the given demand priority. Updates
+     * the priority if already pending (keeping the higher of the two) or already
+     * resident (so eviction ranks it correctly). Requesting a resident product
+     * does not re-extract it.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID: number, priority: number): void;
+    /**
+     * Materialise pending products in descending priority order, evicting the
+     * lowest-priority resident tiles whenever the budget is exceeded. A pending
+     * product whose priority is below every resident tile AND that can't fit is
+     * left pending (it will fill once demand raises it or resident tiles drop).
+     *
+     * @param maxExtractions Optional cap on how many tiles to extract this pump
+     * (e.g. a per-frame budget); unbounded when omitted.
+     * @return {number} The number of tiles extracted this pump.
+     */
+    pump(maxExtractions?: number): number;
+    /**
+     * Evict every resident tile (e.g. on model close), releasing all bytes.
+     */
+    evictAll(): void;
+    /**
+     * @return {boolean} True if the product's tile is resident.
+     * @param productLocalID The product to check.
+     */
+    isResident(productLocalID: number): boolean;
+    /**
+     * @return {DemandQueueStats} A snapshot of runtime counters.
+     */
+    get stats(): DemandQueueStats;
+    /**
+     * Pop the highest-priority pending request. Linear scan — swap for a heap
+     * if a real workload shows the pending set growing large per pump.
+     *
+     * @return {PendingRequest | undefined} The request, or undefined if none.
+     */
+    private popHighestPending_;
+    /**
+     * Ensure there is conceptual room for a tile requested at `priority` by
+     * evicting resident tiles strictly lower in priority while over budget.
+     * Returns false if the budget is full of tiles at least as wanted as this
+     * request (so it shouldn't displace them).
+     *
+     * @param priority The incoming request's priority.
+     * @return {boolean} True if extraction should proceed.
+     */
+    private ensureRoomFor_;
+    /**
+     * Evict lowest-priority resident tiles until within budget (used after an
+     * extraction that pushed us over — e.g. a large tile).
+     */
+    private evictToBudget_;
+    /**
+     * @return {{ productLocalID: number, priority: number } | undefined} The
+     * lowest-priority resident tile, or undefined if none.
+     */
+    private lowestPriorityResident_;
+    /**
+     * Release one resident tile.
+     *
+     * @param productLocalID The tile to evict.
+     */
+    private evictOne_;
+}
+//# sourceMappingURL=demand_geometry_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demand_geometry_queue.d.ts","sourceRoot":"","sources":["../../../src/core/demand_geometry_queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAE5B;;;;;;;OAOG;IACH,OAAO,CAAE,cAAc,EAAE,MAAM,GAAI,MAAM,CAAA;IAEzC;;;;;;OAMG;IACH,OAAO,CAAE,cAAc,EAAE,MAAM,GAAI,IAAI,CAAA;CACxC;AAiBD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;CACrB;AAGD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAmB;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IAErC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAE5D,OAAO,CAAC,cAAc,CAAI;IAE1B,OAAO,CAAC,YAAY,CAAI;IAExB,OAAO,CAAC,UAAU,CAAI;IAEtB;;;OAGG;gBACU,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM;IAUtD;;;;;;;;OAQG;IACI,OAAO,CAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAI,IAAI;IAiBhE;;;;;;;;;OASG;IACI,IAAI,CAAE,cAAc,GAAE,MAAiC,GAAI,MAAM;IAoCxE;;OAEG;IACI,QAAQ,IAAI,IAAI;IASvB;;;OAGG;IACI,UAAU,CAAE,cAAc,EAAE,MAAM,GAAI,OAAO;IAIpD;;OAEG;IACH,IAAW,KAAK,IAAI,gBAAgB,CAQnC;IAED;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;OAIG;IACH,OAAO,CAAC,SAAS;CAYlB"}

package/compiled/src/core/demand_geometry_queue.js

@@ -0,0 +1,223 @@
+/**
+ * Demand-driven, budgeted geometry materialisation (M3).
+ *
+ * The streaming loader inverts geometry: instead of extracting every product
+ * up front, extraction becomes a **cache fill keyed by product**, ordered by
+ * demand (viewport frustum + distance, explicit selection, prefetch hints)
+ * and bounded by an explicit byte budget. This module is the scheduler: a
+ * priority queue over product local IDs plus an evictable resident set, with
+ * the actual extract / release delegated to a pluggable {@link GeometryTiles}.
+ *
+ * The heavy half — the wasm-side extract → tessellate → upload and the
+ * per-product native reclaim — lives behind {@link GeometryTiles}. Its
+ * production implementation needs a **conway-geom API to free one product's
+ * native geometry** (today the wasm heap has no per-product reclaim); scoping
+ * that C++ surface is the M3 blocker tracked in the design doc. This scheduler
+ * is engine-side, fully deterministic, and tested against a mock tiles impl,
+ * so the queue/budget/eviction policy is settled independently of the wasm
+ * work.
+ */
+/**
+ * A budgeted, demand-ordered geometry materialisation queue.
+ *
+ * Usage: `request(productLocalID, priority)` as demand changes (higher
+ * priority = more wanted); `pump()` to materialise the most-wanted pending
+ * products until the queue drains or the byte budget forces eviction of
+ * lower-priority resident tiles. Re-requesting an evicted product re-fills it.
+ * A steady stream of `request` + `pump` keeps a bounded working set of the
+ * highest-priority products resident — the "full model navigable under a
+ * fixed budget" behaviour.
+ */
+export class DemandGeometryQueue {
+    /**
+     * @param tiles The extract/release backend.
+     * @param budgetBytes Maximum resident tile bytes before eviction kicks in.
+     */
+    constructor(tiles, budgetBytes) {
+        /** Highest priority a product currently wants materialising at. */
+        this.pending_ = new Map();
+        /** Resident tiles by product local ID. */
+        this.resident_ = new Map();
+        this.residentBytes_ = 0;
+        this.extractions_ = 0;
+        this.evictions_ = 0;
+        if (budgetBytes <= 0) {
+            throw new Error(`Invalid budgetBytes ${budgetBytes}`);
+        }
+        this.tiles_ = tiles;
+        this.budgetBytes_ = budgetBytes;
+    }
+    /**
+     * Request a product be materialised at the given demand priority. Updates
+     * the priority if already pending (keeping the higher of the two) or already
+     * resident (so eviction ranks it correctly). Requesting a resident product
+     * does not re-extract it.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID, priority) {
+        const tile = this.resident_.get(productLocalID);
+        if (tile !== void 0) {
+            // Already resident — just refresh its eviction ranking.
+            tile.priority = Math.max(tile.priority, priority);
+            return;
+        }
+        const existing = this.pending_.get(productLocalID);
+        this.pending_.set(productLocalID, existing === void 0 ? priority : Math.max(existing, priority));
+    }
+    /**
+     * Materialise pending products in descending priority order, evicting the
+     * lowest-priority resident tiles whenever the budget is exceeded. A pending
+     * product whose priority is below every resident tile AND that can't fit is
+     * left pending (it will fill once demand raises it or resident tiles drop).
+     *
+     * @param maxExtractions Optional cap on how many tiles to extract this pump
+     * (e.g. a per-frame budget); unbounded when omitted.
+     * @return {number} The number of tiles extracted this pump.
+     */
+    pump(maxExtractions = Number.POSITIVE_INFINITY) {
+        let extractedThisPump = 0;
+        while (extractedThisPump < maxExtractions && this.pending_.size > 0) {
+            const next = this.popHighestPending_();
+            if (next === void 0) {
+                break;
+            }
+            // If the working set is full and this request can't beat the cheapest
+            // evictable (lower-priority) resident tile, stop — nothing more fits.
+            if (!this.ensureRoomFor_(next.priority)) {
+                // Put it back; it stays pending for a future pump.
+                this.pending_.set(next.productLocalID, next.priority);
+                break;
+            }
+            const bytes = this.tiles_.extract(next.productLocalID);
+            this.resident_.set(next.productLocalID, { bytes, priority: next.priority });
+            this.residentBytes_ += bytes;
+            ++this.extractions_;
+            ++extractedThisPump;
+            // A single oversized tile can still exceed budget; evict what we can.
+            this.evictToBudget_();
+        }
+        return extractedThisPump;
+    }
+    /**
+     * Evict every resident tile (e.g. on model close), releasing all bytes.
+     */
+    evictAll() {
+        for (const productLocalID of this.resident_.keys()) {
+            this.tiles_.release(productLocalID);
+            ++this.evictions_;
+        }
+        this.resident_.clear();
+        this.residentBytes_ = 0;
+    }
+    /**
+     * @return {boolean} True if the product's tile is resident.
+     * @param productLocalID The product to check.
+     */
+    isResident(productLocalID) {
+        return this.resident_.has(productLocalID);
+    }
+    /**
+     * @return {DemandQueueStats} A snapshot of runtime counters.
+     */
+    get stats() {
+        return {
+            extractions: this.extractions_,
+            evictions: this.evictions_,
+            residentBytes: this.residentBytes_,
+            residentCount: this.resident_.size,
+            pendingCount: this.pending_.size,
+        };
+    }
+    /**
+     * Pop the highest-priority pending request. Linear scan — swap for a heap
+     * if a real workload shows the pending set growing large per pump.
+     *
+     * @return {PendingRequest | undefined} The request, or undefined if none.
+     */
+    popHighestPending_() {
+        let bestID;
+        let bestPriority = Number.NEGATIVE_INFINITY;
+        for (const [productLocalID, priority] of this.pending_) {
+            if (priority > bestPriority) {
+                bestPriority = priority;
+                bestID = productLocalID;
+            }
+        }
+        if (bestID === void 0) {
+            return void 0;
+        }
+        this.pending_.delete(bestID);
+        return { productLocalID: bestID, priority: bestPriority };
+    }
+    /**
+     * Ensure there is conceptual room for a tile requested at `priority` by
+     * evicting resident tiles strictly lower in priority while over budget.
+     * Returns false if the budget is full of tiles at least as wanted as this
+     * request (so it shouldn't displace them).
+     *
+     * @param priority The incoming request's priority.
+     * @return {boolean} True if extraction should proceed.
+     */
+    ensureRoomFor_(priority) {
+        if (this.residentBytes_ < this.budgetBytes_) {
+            return true;
+        }
+        // Over/at budget: only proceed if there's a lower-priority tile to evict.
+        let evictedAny = false;
+        while (this.residentBytes_ >= this.budgetBytes_) {
+            const victim = this.lowestPriorityResident_();
+            if (victim === void 0 || victim.priority >= priority) {
+                break;
+            }
+            this.evictOne_(victim.productLocalID);
+            evictedAny = true;
+        }
+        return this.residentBytes_ < this.budgetBytes_ || evictedAny;
+    }
+    /**
+     * Evict lowest-priority resident tiles until within budget (used after an
+     * extraction that pushed us over — e.g. a large tile).
+     */
+    evictToBudget_() {
+        while (this.residentBytes_ > this.budgetBytes_) {
+            const victim = this.lowestPriorityResident_();
+            if (victim === void 0) {
+                break;
+            }
+            this.evictOne_(victim.productLocalID);
+        }
+    }
+    /**
+     * @return {{ productLocalID: number, priority: number } | undefined} The
+     * lowest-priority resident tile, or undefined if none.
+     */
+    lowestPriorityResident_() {
+        let worstID;
+        let worstPriority = Number.POSITIVE_INFINITY;
+        for (const [productLocalID, tile] of this.resident_) {
+            if (tile.priority < worstPriority) {
+                worstPriority = tile.priority;
+                worstID = productLocalID;
+            }
+        }
+        return worstID === void 0 ?
+            void 0 : { productLocalID: worstID, priority: worstPriority };
+    }
+    /**
+     * Release one resident tile.
+     *
+     * @param productLocalID The tile to evict.
+     */
+    evictOne_(productLocalID) {
+        const tile = this.resident_.get(productLocalID);
+        if (tile === void 0) {
+            return;
+        }
+        this.tiles_.release(productLocalID);
+        this.resident_.delete(productLocalID);
+        this.residentBytes_ -= tile.bytes;
+        ++this.evictions_;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,133 @@
+/* eslint-disable no-magic-numbers */
+// M3: the demand-geometry scheduler — priority ordering, byte budget, and
+// eviction — tested against a mock tiles backend so the policy is settled
+// independently of the wasm extract/reclaim work.
+import { describe, expect, test } from "@jest/globals";
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+/**
+ * A mock tiles backend: every product costs a fixed number of bytes and
+ * records the extract/release calls so tests can assert on them.
+ *
+ * @param costBytes Per-tile resident cost.
+ * @return {object} `{ tiles, extracted, released }`.
+ */
+function mockTiles(costBytes) {
+    const extracted = [];
+    const released = [];
+    const tiles = {
+        extract(id) {
+            extracted.push(id);
+            return costBytes;
+        },
+        release(id) {
+            released.push(id);
+        },
+    };
+    return { tiles, extracted, released };
+}
+describe("DemandGeometryQueue", () => {
+    test("materialises highest-priority requests first", () => {
+        const { tiles, extracted } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        q.request(1, 5);
+        q.request(2, 50);
+        q.request(3, 20);
+        q.pump();
+        // Extracted in descending priority: 2 (50), 3 (20), 1 (5).
+        expect(extracted).toEqual([2, 3, 1]);
+        expect(q.stats.residentCount).toBe(3);
+        expect(q.stats.residentBytes).toBe(30);
+    });
+    test("evicts the lowest-priority tile when the budget is exceeded", () => {
+        const { tiles, released } = mockTiles(100);
+        // Budget holds 3 tiles (300).
+        const q = new DemandGeometryQueue(tiles, 300);
+        for (const [id, pri] of [[1, 10], [2, 20], [3, 30]]) {
+            q.request(id, pri);
+        }
+        q.pump();
+        expect(q.stats.residentCount).toBe(3);
+        // A 4th, higher-priority request must evict the lowest (id 1, pri 10).
+        q.request(4, 40);
+        q.pump();
+        expect(q.isResident(4)).toBe(true);
+        expect(q.isResident(1)).toBe(false);
+        expect(released).toContain(1);
+        expect(q.stats.residentBytes).toBeLessThanOrEqual(300);
+    });
+    test("a request below every resident tile does not displace them", () => {
+        const { tiles, extracted } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 200); // holds 2
+        q.request(1, 50);
+        q.request(2, 40);
+        q.pump();
+        expect(q.stats.residentCount).toBe(2);
+        // Low-priority newcomer can't beat either resident tile → stays pending.
+        q.request(3, 5);
+        const n = q.pump();
+        expect(n).toBe(0);
+        expect(q.isResident(3)).toBe(false);
+        expect(extracted).toEqual([1, 2]);
+        expect(q.stats.pendingCount).toBe(1);
+    });
+    test("re-requesting an evicted product re-extracts it", () => {
+        const { tiles, extracted } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 100); // holds 1
+        q.request(1, 10);
+        q.pump();
+        q.request(2, 20); // evicts 1
+        q.pump();
+        expect(q.isResident(1)).toBe(false);
+        q.request(1, 30); // evicts 2, re-extracts 1
+        q.pump();
+        expect(q.isResident(1)).toBe(true);
+        // 1 extracted twice (first fill, then re-fill after eviction).
+        expect(extracted.filter((id) => id === 1).length).toBe(2);
+    });
+    test("requesting an already-resident product does not re-extract", () => {
+        const { tiles, extracted } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        q.request(1, 10);
+        q.pump();
+        q.request(1, 99); // already resident — just bumps ranking
+        q.pump();
+        expect(extracted).toEqual([1]);
+    });
+    test("a per-pump extraction cap bounds work per call", () => {
+        const { tiles } = mockTiles(1);
+        const q = new DemandGeometryQueue(tiles, 1000000);
+        for (let id = 0; id < 100; ++id) {
+            q.request(id, id);
+        }
+        expect(q.pump(10)).toBe(10);
+        expect(q.stats.residentCount).toBe(10);
+        expect(q.stats.pendingCount).toBe(90);
+    });
+    test("evictAll releases everything", () => {
+        const { tiles, released } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        for (let id = 0; id < 5; ++id) {
+            q.request(id, id);
+        }
+        q.pump();
+        q.evictAll();
+        expect(q.stats.residentCount).toBe(0);
+        expect(q.stats.residentBytes).toBe(0);
+        expect(released.sort()).toEqual([0, 1, 2, 3, 4]);
+    });
+    test("keeps the resident set bounded by the budget across a demand stream", () => {
+        const { tiles } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 500); // holds 5
+        // A moving "viewport": 200 products stream past with rising priority.
+        for (let id = 0; id < 200; ++id) {
+            q.request(id, id);
+            q.pump();
+            expect(q.stats.residentBytes).toBeLessThanOrEqual(500);
+        }
+        // The 5 most-wanted (highest ids) remain.
+        expect(q.stats.residentCount).toBe(5);
+        for (const id of [195, 196, 197, 198, 199]) {
+            expect(q.isResident(id)).toBe(true);
+        }
+    });
+});

package/compiled/src/step/parsing/index_sidecar.d.ts

@@ -0,0 +1,53 @@
+import { StepIndexEntry } from "./step_parser.js";
+/**
+ * The decoded sidecar: the source identity it was built against, plus the
+ * reconstructed top-level element index.
+ */
+export interface DecodedSidecar<TypeIDType extends number> {
+    version: number;
+    sourceByteLength: number;
+    sourceHash: number;
+    elements: StepIndexEntry<TypeIDType>[];
+    /**
+     * True for records the sidecar under-describes (they had inline / multi
+     * children the v1 format doesn't serialise). Same order as `elements`.
+     */
+    hasChildren: boolean[];
+}
+/**
+ * A placeholder strong-ish hash of the source bytes (FNV-1a, 32-bit). Stands
+ * in for a production digest (SHA-256); only the fixed slot matters to the
+ * format. Sufficient to demonstrate the mismatch → cold-scan handshake.
+ *
+ * @param source The source bytes.
+ * @return {number} A 32-bit unsigned hash.
+ */
+export declare function hashSource(source: Uint8Array): number;
+/**
+ * Serialise a model's top-level element index to a sidecar blob.
+ *
+ * @param elements The top-level element index.
+ * @param sourceByteLength The length of the source it was built from.
+ * @param sourceHash The source hash (see {@link hashSource}).
+ * @return {Uint8Array} The sidecar bytes.
+ */
+export declare function serializeIndexSidecar<TypeIDType extends number>(elements: StepIndexEntry<TypeIDType>[], sourceByteLength: number, sourceHash: number): Uint8Array;
+/**
+ * Deserialise a sidecar blob back to the top-level element index.
+ *
+ * @param bytes The sidecar bytes.
+ * @return {DecodedSidecar} The decoded source identity + element index.
+ */
+export declare function deserializeIndexSidecar<TypeIDType extends number>(bytes: Uint8Array): DecodedSidecar<TypeIDType>;
+/**
+ * Validate a decoded sidecar against the actual source identity. The
+ * index-first open path calls this before trusting the sidecar; on false it
+ * must fall back to a cold scan.
+ *
+ * @param sidecar The decoded sidecar.
+ * @param sourceByteLength The actual source length.
+ * @param sourceHash The actual source hash.
+ * @return {boolean} True if the sidecar matches the source.
+ */
+export declare function sidecarMatchesSource<TypeIDType extends number>(sidecar: DecodedSidecar<TypeIDType>, sourceByteLength: number, sourceHash: number): boolean;
+//# sourceMappingURL=index_sidecar.d.ts.map

package/compiled/src/step/parsing/index_sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index_sidecar.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/index_sidecar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AA0D9C;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,UAAU,SAAS,MAAM;IACvD,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,CAAA;IAEtC;;;OAGG;IACH,WAAW,EAAE,OAAO,EAAE,CAAA;CACvB;AAGD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAI,MAAM,CASvD;AAGD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,SAAS,MAAM,EAC3D,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,EACtC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GAAI,UAAU,CAsCnC;AAGD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,SAAS,MAAM,EAC7D,KAAK,EAAE,UAAU,GAAI,cAAc,CAAC,UAAU,CAAC,CA0ClD;AAGD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,SAAS,MAAM,EAC1D,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,EACnC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GAAI,OAAO,CAIhC"}