@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/ifc/ifc_step_parser.js

@@ -1,6 +1,11 @@
 import StepParser from "../step/parsing/step_parser.js";
 import EntitTypesIfcSearch from "./ifc4_gen/entity_types_search.gen.js";
 import IfcStepModel from "./ifc_step_model.js";
+import { buildColumnarIndexStreaming, buildColumnarIndexStreamingAsync, } from "../step/parsing/streaming_index_builder.js";
+import { WindowedStepBufferProvider, } from "../step/step_buffer_provider.js";
+/** Default moving-window size for the streaming index build (1 MiB). */
+// eslint-disable-next-line no-magic-numbers
+const DEFAULT_STREAM_POOL_BYTES = 1024 * 1024;
 /**
  * Parser for taking IFC file serialized in step and turning them into a lazily parsed model.
  */
@@ -36,6 +41,65 @@ class IfcStepParser extends StepParser {
         const [itemIndex, parseResult] = await this.parseDataBlockAsync(input, onProgress);
         return [parseResult, new IfcStepModel(input.buffer, itemIndex.elements)];
     }
+    /**
+     * Build a model by streaming the source through a bounded moving window
+     * (see buildIndexStreaming / M0) rather than parsing one resident buffer,
+     * then backing the model with a windowed provider over `store` — so the
+     * source is never held fully resident in the JS heap.
+     *
+     * `source` serves the parse (synchronous windowed reads — on a worker this
+     * is an OPFS sync-access handle; in node/tests a file descriptor or buffer)
+     * and `store` serves the model's post-parse property access (asynchronous
+     * windowed reads paged in on demand — OPFS `File.slice()` in the browser).
+     * Both view the same file bytes, so the file-absolute addresses the index
+     * records resolve identically through either.
+     *
+     * NOTE (M1 scope): this delivers the bounded-memory *parse*. Synchronous
+     * geometry extraction still needs its record ranges resident — as after
+     * `spillSourceToExternalStore` — so a caller that extracts geometry must
+     * `ensureResident` first (demand-driven geometry is M3). Property / index
+     * access works directly via the async surfaces.
+     *
+     * @param source Synchronous byte source feeding the streaming parse.
+     * @param store Async external store backing the windowed model.
+     * @param opts Optional window sizing: `pool` (parse window),
+     * `chunkBytes` / `maxResidentChunks` (model window).
+     * @return {[ParseResult, IfcStepModel | undefined]} The parse result and
+     * the windowed model.
+     */
+    parseStreamToModel(source, store, opts) {
+        if (store.byteLength !== source.byteLength) {
+            throw new Error(`Streaming store byteLength ${store.byteLength} does not match ` +
+                `source byteLength ${source.byteLength}`);
+        }
+        // Columnar build (M7): the index goes straight into SoA columns — the
+        // per-record object phase never exists, so peak heap is window + columns.
+        const { columns, result } = buildColumnarIndexStreaming(source, this, opts?.pool ?? DEFAULT_STREAM_POOL_BYTES);
+        const provider = new WindowedStepBufferProvider(store, opts?.chunkBytes, opts?.maxResidentChunks);
+        return [result, new IfcStepModel(void 0, columns, provider)];
+    }
+    /**
+     * Cooperative twin of {@link parseStreamToModel}: the index build
+     * yields to the event loop and can fill windows from an async
+     * {@link ReadableByteSource} (an OPFS `File.slice()` store). The
+     * model is still windowed — geometry extract must
+     * `ensureResident` first.
+     *
+     * @param source Sync or async byte source feeding the parse.
+     * @param store Async external store backing the windowed model.
+     * @param opts Optional window sizing plus parse progress.
+     * @return {Promise<[ParseResult, IfcStepModel | undefined]>} The
+     * parse result and the windowed model.
+     */
+    async parseStreamToModelAsync(source, store, opts) {
+        if (store.byteLength !== source.byteLength) {
+            throw new Error(`Streaming store byteLength ${store.byteLength} does not match ` +
+                `source byteLength ${source.byteLength}`);
+        }
+        const { columns, result } = await buildColumnarIndexStreamingAsync(source, this, opts?.pool ?? DEFAULT_STREAM_POOL_BYTES, void 0, opts?.onProgress);
+        const provider = new WindowedStepBufferProvider(store, opts?.chunkBytes, opts?.maxResidentChunks);
+        return [result, new IfcStepModel(void 0, columns, provider)];
+    }
 }
 /**
  * An easily accessible and re-usable instance of the parser.

package/compiled/src/ifc/ifc_stream_model.test.d.ts

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

package/compiled/src/ifc/ifc_stream_model.test.d.ts.map

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

package/compiled/src/ifc/ifc_stream_model.test.js

@@ -0,0 +1,70 @@
+/* eslint-disable no-magic-numbers */
+// M1 core: a model built by streaming the source through a bounded window
+// (parseStreamToModel) must decode records byte-identically to the resident
+// parse — reading them on demand through the windowed provider after
+// ensureResident, with the source never held fully resident.
+import * as fs from "fs";
+import { beforeAll, describe, expect, test } from "@jest/globals";
+import ParsingBuffer from "../parsing/parsing_buffer.js";
+import IfcStepParser from "./ifc_step_parser.js";
+import { BufferByteSource } from "../step/parsing/byte_source.js";
+import { InMemoryStepByteStore } from "../step/step_buffer_provider.js";
+import { ParseResult } from "../step/parsing/step_parser.js";
+import { IfcRoot } from "./ifc4_gen/index.js";
+let bytes;
+/**
+ * Decode every IfcRoot-derived entity's GlobalId + Name from a model into a
+ * stable map — the attributes are read from the record bytes, so this
+ * exercises the actual byte path (resident buffer vs windowed provider).
+ *
+ * @param model The model to read from.
+ * @return {Map<number, string>} expressID → "GlobalId|Name".
+ */
+function rootAttributes(model) {
+    const out = new Map();
+    for (const expressID of model.expressIDsOfTypes(IfcRoot)) {
+        const entity = model.getElementByExpressID(expressID);
+        if (entity === void 0) {
+            continue;
+        }
+        const globalId = typeof entity.GlobalId === "string" ? entity.GlobalId : "";
+        const name = typeof entity.Name === "string" ? entity.Name : "";
+        out.set(expressID, `${globalId}|${name}`);
+    }
+    return out;
+}
+beforeAll(() => {
+    bytes = new Uint8Array(fs.readFileSync("data/index.ifc"));
+});
+describe("parseStreamToModel", () => {
+    test("streamed windowed model decodes records identically to the resident parse", async () => {
+        // Resident ground truth.
+        const residentInput = new ParsingBuffer(bytes);
+        IfcStepParser.Instance.parseHeader(residentInput);
+        const [, residentModel] = IfcStepParser.Instance.parseDataToModel(residentInput);
+        const expected = rootAttributes(residentModel);
+        expect(expected.size).toBeGreaterThan(10);
+        // Streamed: tiny parse window forces slides; tiny model chunks force
+        // paging. Same bytes behind both the sync source and the async store.
+        const [result, streamModel] = IfcStepParser.Instance.parseStreamToModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes), { pool: 4 * 1024, chunkBytes: 512, maxResidentChunks: 3 });
+        expect(result).toBe(ParseResult.COMPLETE);
+        expect(streamModel.isSourceExternal).toBe(true);
+        // Page each record in on demand, then decode; must match resident.
+        const actual = new Map();
+        for (const expressID of streamModel.expressIDsOfTypes(IfcRoot)) {
+            await streamModel.ensureResidentByExpressID(expressID);
+            const entity = streamModel.getElementByExpressID(expressID);
+            if (entity === void 0) {
+                continue;
+            }
+            const globalId = typeof entity.GlobalId === "string" ? entity.GlobalId : "";
+            const name = typeof entity.Name === "string" ? entity.Name : "";
+            actual.set(expressID, `${globalId}|${name}`);
+        }
+        expect(actual).toEqual(expected);
+    }, 60000);
+    test("rejects a store whose size does not match the source", () => {
+        expect(() => IfcStepParser.Instance.parseStreamToModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes.subarray(0, bytes.length - 1))))
+            .toThrow(/does not match/);
+    });
+});

package/compiled/src/ifc/ifc_stream_open.d.ts

@@ -0,0 +1,131 @@
+import { ByteSource, ReadableByteSource } from "../step/parsing/byte_source.js";
+import { ColumnarIndexSink, StepIndexColumns } from "../step/parsing/columnar_index.js";
+import { RecordEventHandler } from "../step/parsing/record_event.js";
+import { StreamingIndexStats } from "../step/parsing/streaming_index_builder.js";
+import { ParseResult, StepHeader } from "../step/parsing/step_parser.js";
+import { StepExternalByteStore } from "../step/step_buffer_provider.js";
+import EntityTypesIfc from "./ifc4_gen/entity_types_ifc.gen.js";
+import { PrefixTypeIndex } from "../step/parsing/prefix_type_index.js";
+import IfcStepModel from "./ifc_step_model.js";
+/**
+ * Options for a streamed IFC open. All optional; defaults suit a browser
+ * worker over an OPFS-backed store.
+ */
+export interface StreamedIfcOpenOptions {
+    /** Parse window size in bytes (default 1 MiB). */
+    pool?: number;
+    /** Windowed provider chunk size (default: provider's). */
+    chunkBytes?: number;
+    /** Windowed provider LRU cap in chunks (default: provider's). */
+    maxResidentChunks?: number;
+    /**
+     * Live per-record event — the M2 seam for incremental consumers (type
+     * index, roots, cross-refs, names skeleton) that run while the model is
+     * still parsing. Must be synchronous and cheap; see
+     * {@link RecordEventHandler} for the payload and the window-lifetime rule
+     * on the record bytes it hands over.
+     */
+    onRecordIndexed?: RecordEventHandler<EntityTypesIfc>;
+    /**
+     * Caller-owned index sink. Pass one to hold the columns *while* the parse
+     * runs — the seam a prefix-derived consumer reads
+     * ({@link ifcPrefixTypeIndex}). Without it the columns only exist once the
+     * open returns, which is too late for anything mid-parse.
+     */
+    indexSink?: ColumnarIndexSink<EntityTypesIfc>;
+}
+/**
+ * The result of a streamed IFC open: the windowed-source model plus the
+ * artifacts a consumer needs around it.
+ */
+export interface StreamedIfcOpen {
+    /** The model over the windowed source (undefined if the parse failed). */
+    model: IfcStepModel | undefined;
+    /** The parse result. */
+    result: ParseResult;
+    /** The STEP header (available even on some failed parses). */
+    header: StepHeader;
+    /**
+     * The columnar index the model was built from. Hand to
+     * `serializeIndexSidecarFromColumns` (with a source hash) to produce the
+     * revisit sidecar — the columns ARE the sidecar payload (M7 identity).
+     */
+    columns: StepIndexColumns<EntityTypesIfc>;
+    /** Window diagnostics from the streaming build. */
+    stats: StreamingIndexStats;
+}
+/**
+ * Open an IFC model from a streamed source with a **fixed-memory parse**
+ * (the release-facing Phase B API; composes M0/M1a/M7):
+ *
+ *  - the index builds through a moving window over `source` — the source is
+ *    never resident in the JS heap, and the index is columnar from birth
+ *    (no per-record object phase);
+ *  - the model reads source bytes on demand through a windowed LRU provider
+ *    over `store` (`ensureResidentByLocalID`/`ByExpressID` page ranges in
+ *    before synchronous reads — see `DemandResidencyPump` for the demand
+ *    orchestration).
+ *
+ * The typical browser wiring: a worker streams the network body **through**
+ * to OPFS while feeding the same bytes to `source`; `store` reads back from
+ * OPFS. `source.byteLength` and `store.byteLength` must agree.
+ *
+ * @param source The sequential parse source.
+ * @param store The random-access store the model reads from afterwards.
+ * @param options See {@link StreamedIfcOpenOptions}.
+ * @return {StreamedIfcOpen} The model + header, columns, and diagnostics.
+ */
+export declare function openStreamedIfcModel(source: ByteSource, store: StepExternalByteStore, options?: StreamedIfcOpenOptions): StreamedIfcOpen;
+/**
+ * A type index over the IFC records parsed so far, paired with the schema's
+ * production indexer — the composed form of {@link PrefixTypeIndex} that a
+ * caller needs, since the index is only useful mid-parse if it reads the same
+ * live sink the open is filling.
+ *
+ * ```ts
+ * const indexSink = new ColumnarIndexSink<EntityTypesIfc>()
+ * const types = ifcPrefixTypeIndex( indexSink )
+ * const open = await openStreamedIfcModelAsync( source, store, {
+ *   indexSink,
+ *   onProgress: () => reveal( types.expressIDsOfTypes( IfcProduct ) ),
+ * } )
+ * ```
+ *
+ * @param sink The sink passed to the open as `indexSink`.
+ * @param options Rebuild pacing (see {@link PrefixTypeIndex}).
+ * @param options.growthFactor Record growth before a query rebuilds.
+ * @param options.minimumRecords Count below which pacing is skipped.
+ * @return {PrefixTypeIndex<EntityTypesIfc>} The index over that sink.
+ */
+export declare function ifcPrefixTypeIndex(sink: ColumnarIndexSink<EntityTypesIfc>, options?: {
+    growthFactor?: number;
+    minimumRecords?: number;
+}): PrefixTypeIndex<EntityTypesIfc>;
+/**
+ * Cooperative twin of {@link openStreamedIfcModel}: the index build
+ * yields to the event loop and can fill windows from an async
+ * {@link ReadableByteSource}. Pass a {@link StoreByteSource} wrapping
+ * `store` to parse a file that is already in OPFS without ever
+ * holding it as one `ArrayBuffer`.
+ *
+ * @param source Sync or async parse source.
+ * @param store The random-access store the model reads from afterwards.
+ * @param options See {@link StreamedIfcOpenOptions} plus `onProgress`.
+ * @return {Promise<StreamedIfcOpen>} The model + header, columns, diagnostics.
+ */
+export declare function openStreamedIfcModelAsync(source: ReadableByteSource, store: StepExternalByteStore, options?: StreamedIfcOpenOptions & {
+    onProgress?: (absoluteByteCursor: number) => void;
+}): Promise<StreamedIfcOpen>;
+/**
+ * Open a windowed IFC model from a store alone — parse windows and
+ * post-parse reads share `store`. This is the M1b embedder entry for
+ * a file already sitting in OPFS.
+ *
+ * @param store The source of truth for the file bytes.
+ * @param options See {@link openStreamedIfcModelAsync}.
+ * @return {Promise<StreamedIfcOpen>} The model + header, columns, diagnostics.
+ */
+export declare function openStreamedIfcModelFromStore(store: StepExternalByteStore, options?: StreamedIfcOpenOptions & {
+    onProgress?: (absoluteByteCursor: number) => void;
+}): Promise<StreamedIfcOpen>;
+//# sourceMappingURL=ifc_stream_open.d.ts.map

package/compiled/src/ifc/ifc_stream_open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ifc_stream_open.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_stream_open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAmB,MAAM,6BAA6B,CAAA;AAC7F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,EAGL,mBAAmB,EACpB,MAAM,yCAAyC,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AACrE,OAAO,EACL,qBAAqB,EAEtB,MAAM,8BAA8B,CAAA;AACrC,OAAO,cAAuC,MAAM,iCAAiC,CAAA;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAI3C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IAErC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAA;IAEpD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;CAC9C;AAGD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAE9B,0EAA0E;IAC1E,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IAE/B,wBAAwB;IACxB,MAAM,EAAE,WAAW,CAAA;IAEnB,8DAA8D;IAC9D,MAAM,EAAE,UAAU,CAAA;IAElB;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAA;IAEzC,mDAAmD;IACnD,KAAK,EAAE,mBAAmB,CAAA;CAC3B;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAAI,eAAe,CA6BtD;AAGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,iBAAiB,CAAC,cAAc,CAAC,EACvC,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,CAAC,cAAc,CAAC,CAIlC;AAGD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC3C,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAAG;IACjC,UAAU,CAAC,EAAE,CAAE,kBAAkB,EAAE,MAAM,KAAM,IAAI,CAAA;CACpD,GAAI,OAAO,CAAC,eAAe,CAAC,CA+BhC;AAGD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CACzC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAAG;IACjC,UAAU,CAAC,EAAE,CAAE,kBAAkB,EAAE,MAAM,KAAM,IAAI,CAAA;CACpD,GAAI,OAAO,CAAC,eAAe,CAAC,CAGhC"}

package/compiled/src/ifc/ifc_stream_open.js

@@ -0,0 +1,116 @@
+import { StoreByteSource } from "../step/parsing/byte_source.js";
+import { buildColumnarIndexStreaming, buildColumnarIndexStreamingAsync, } from "../step/parsing/streaming_index_builder.js";
+import { ParseResult } from "../step/parsing/step_parser.js";
+import { WindowedStepBufferProvider, } from "../step/step_buffer_provider.js";
+import { EntityTypesIfcCount } from "./ifc4_gen/entity_types_ifc.gen.js";
+import { PrefixTypeIndex } from "../step/parsing/prefix_type_index.js";
+import { StepTypeIndexer } from "../step/indexing/step_type_indexer.js";
+import IfcStepModel from "./ifc_step_model.js";
+import IfcStepParser from "./ifc_step_parser.js";
+// eslint-disable-next-line no-magic-numbers
+const DEFAULT_STREAM_POOL_BYTES = 1024 * 1024;
+/**
+ * Open an IFC model from a streamed source with a **fixed-memory parse**
+ * (the release-facing Phase B API; composes M0/M1a/M7):
+ *
+ *  - the index builds through a moving window over `source` — the source is
+ *    never resident in the JS heap, and the index is columnar from birth
+ *    (no per-record object phase);
+ *  - the model reads source bytes on demand through a windowed LRU provider
+ *    over `store` (`ensureResidentByLocalID`/`ByExpressID` page ranges in
+ *    before synchronous reads — see `DemandResidencyPump` for the demand
+ *    orchestration).
+ *
+ * The typical browser wiring: a worker streams the network body **through**
+ * to OPFS while feeding the same bytes to `source`; `store` reads back from
+ * OPFS. `source.byteLength` and `store.byteLength` must agree.
+ *
+ * @param source The sequential parse source.
+ * @param store The random-access store the model reads from afterwards.
+ * @param options See {@link StreamedIfcOpenOptions}.
+ * @return {StreamedIfcOpen} The model + header, columns, and diagnostics.
+ */
+export function openStreamedIfcModel(source, store, options) {
+    if (store.byteLength !== source.byteLength) {
+        throw new Error(`Streaming store byteLength ${store.byteLength} does not match ` +
+            `source byteLength ${source.byteLength}`);
+    }
+    const { header, columns, result, stats } = buildColumnarIndexStreaming(source, IfcStepParser.Instance, options?.pool ?? DEFAULT_STREAM_POOL_BYTES, options?.onRecordIndexed, options?.indexSink);
+    if (result !== ParseResult.COMPLETE) {
+        return { model: void 0, result, header, columns, stats };
+    }
+    const provider = new WindowedStepBufferProvider(store, options?.chunkBytes, options?.maxResidentChunks);
+    return {
+        model: new IfcStepModel(void 0, columns, provider),
+        result,
+        header,
+        columns,
+        stats,
+    };
+}
+/**
+ * A type index over the IFC records parsed so far, paired with the schema's
+ * production indexer — the composed form of {@link PrefixTypeIndex} that a
+ * caller needs, since the index is only useful mid-parse if it reads the same
+ * live sink the open is filling.
+ *
+ * ```ts
+ * const indexSink = new ColumnarIndexSink<EntityTypesIfc>()
+ * const types = ifcPrefixTypeIndex( indexSink )
+ * const open = await openStreamedIfcModelAsync( source, store, {
+ *   indexSink,
+ *   onProgress: () => reveal( types.expressIDsOfTypes( IfcProduct ) ),
+ * } )
+ * ```
+ *
+ * @param sink The sink passed to the open as `indexSink`.
+ * @param options Rebuild pacing (see {@link PrefixTypeIndex}).
+ * @param options.growthFactor Record growth before a query rebuilds.
+ * @param options.minimumRecords Count below which pacing is skipped.
+ * @return {PrefixTypeIndex<EntityTypesIfc>} The index over that sink.
+ */
+export function ifcPrefixTypeIndex(sink, options) {
+    return new PrefixTypeIndex(sink, new StepTypeIndexer(EntityTypesIfcCount), options);
+}
+/**
+ * Cooperative twin of {@link openStreamedIfcModel}: the index build
+ * yields to the event loop and can fill windows from an async
+ * {@link ReadableByteSource}. Pass a {@link StoreByteSource} wrapping
+ * `store` to parse a file that is already in OPFS without ever
+ * holding it as one `ArrayBuffer`.
+ *
+ * @param source Sync or async parse source.
+ * @param store The random-access store the model reads from afterwards.
+ * @param options See {@link StreamedIfcOpenOptions} plus `onProgress`.
+ * @return {Promise<StreamedIfcOpen>} The model + header, columns, diagnostics.
+ */
+export async function openStreamedIfcModelAsync(source, store, options) {
+    if (store.byteLength !== source.byteLength) {
+        throw new Error(`Streaming store byteLength ${store.byteLength} does not match ` +
+            `source byteLength ${source.byteLength}`);
+    }
+    const { header, columns, result, stats } = await buildColumnarIndexStreamingAsync(source, IfcStepParser.Instance, options?.pool ?? DEFAULT_STREAM_POOL_BYTES, options?.onRecordIndexed, options?.onProgress, void 0, options?.indexSink);
+    if (result !== ParseResult.COMPLETE) {
+        return { model: void 0, result, header, columns, stats };
+    }
+    const provider = new WindowedStepBufferProvider(store, options?.chunkBytes, options?.maxResidentChunks);
+    return {
+        model: new IfcStepModel(void 0, columns, provider),
+        result,
+        header,
+        columns,
+        stats,
+    };
+}
+/**
+ * Open a windowed IFC model from a store alone — parse windows and
+ * post-parse reads share `store`. This is the M1b embedder entry for
+ * a file already sitting in OPFS.
+ *
+ * @param store The source of truth for the file bytes.
+ * @param options See {@link openStreamedIfcModelAsync}.
+ * @return {Promise<StreamedIfcOpen>} The model + header, columns, diagnostics.
+ */
+export function openStreamedIfcModelFromStore(store, options) {
+    return openStreamedIfcModelAsync(new StoreByteSource(store), store, options);
+}

package/compiled/src/ifc/ifc_stream_open.test.d.ts

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

package/compiled/src/ifc/ifc_stream_open.test.d.ts.map

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

package/compiled/src/ifc/ifc_stream_open.test.js

@@ -0,0 +1,230 @@
+/* eslint-disable no-magic-numbers */
+// Phase B3: the release-facing streamed open — fixed-memory columnar parse
+// over a ByteSource, model over a windowed store, columns exposed for the
+// revisit sidecar — behaves like a resident open for reads once ranges are
+// resident.
+import * as fs from "fs";
+import { beforeAll, describe, expect, test } from "@jest/globals";
+import ParsingBuffer from "../parsing/parsing_buffer.js";
+import IfcStepParser from "./ifc_step_parser.js";
+import { ifcPrefixTypeIndex, openStreamedIfcModel, openStreamedIfcModelFromStore, } from "./ifc_stream_open.js";
+import { ColumnarIndexSink } from "../step/parsing/columnar_index.js";
+import { BufferByteSource } from "../step/parsing/byte_source.js";
+import { InMemoryStepByteStore } from "../step/step_buffer_provider.js";
+import { ParseResult } from "../step/parsing/step_parser.js";
+import { hashSource, serializeIndexSidecarFromColumns, deserializeIndexSidecarToColumns, sidecarMatchesSource, } from "../step/parsing/index_sidecar.js";
+import { IfcRoot } from "./ifc4_gen/index.js";
+let bytes;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let residentModel;
+beforeAll(() => {
+    bytes = new Uint8Array(fs.readFileSync("data/index.ifc"));
+    const input = new ParsingBuffer(bytes);
+    IfcStepParser.Instance.parseHeader(input);
+    residentModel = IfcStepParser.Instance.parseDataToModel(input)[1];
+});
+describe("openStreamedIfcModel (Phase B3)", () => {
+    test("a caller-owned sink makes the type index queryable mid-parse", () => {
+        // The composed path a consumer of @bldrs-ai/conway/stream actually has:
+        // own the sink, hand it to the open, and read the index while the parse
+        // is still filling it. Without the sink seam the columns only exist once
+        // the open returns, which is too late for anything incremental.
+        const indexSink = new ColumnarIndexSink();
+        const types = ifcPrefixTypeIndex(indexSink, { growthFactor: 1, minimumRecords: 0 });
+        const midParse = [];
+        const open = openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes), {
+            pool: 4 * 1024,
+            indexSink,
+            onRecordIndexed: (localID) => {
+                if (localID === 64 || localID === 128) {
+                    midParse.push([...types.expressIDsOfTypes(IfcRoot)].length);
+                }
+            },
+        });
+        expect(open.result).toBe(ParseResult.COMPLETE);
+        expect(midParse).toHaveLength(2);
+        expect(midParse[0]).toBeLessThanOrEqual(midParse[1]);
+        const finalCount = [...types.expressIDsOfTypes(IfcRoot)].length;
+        expect(midParse[1]).toBeLessThanOrEqual(finalCount);
+        expect(finalCount).toBe([...residentModel.expressIDsOfTypes(IfcRoot)].length);
+    });
+    test("opens a model matching the resident parse, with header and columns", () => {
+        const open = openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes), { pool: 4 * 1024 });
+        expect(open.result).toBe(ParseResult.COMPLETE);
+        expect(open.model).toBeDefined();
+        expect(open.header.headers.size).toBeGreaterThan(0);
+        expect(open.columns.firstInlineElement).toBeGreaterThan(0);
+        const streamedRoots = new Set(open.model.expressIDsOfTypes(IfcRoot));
+        const residentRoots = new Set(residentModel.expressIDsOfTypes(IfcRoot));
+        expect(streamedRoots).toEqual(residentRoots);
+    });
+    test("reads work after ensureResident (the windowed contract)", async () => {
+        const open = openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes));
+        const model = open.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        await model.ensureResidentByExpressID(expressID);
+        const element = model.getElementByExpressID(expressID);
+        expect(element?.expressID).toBe(expressID);
+    });
+    test("record events fire live during the open", () => {
+        let events = 0;
+        openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes), { onRecordIndexed: () => void ++events });
+        expect(events).toBe(openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes)).columns.firstInlineElement);
+    });
+    test("the returned columns serialize to a trustable revisit sidecar", () => {
+        const open = openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes));
+        const hash = hashSource(bytes);
+        const sidecar = serializeIndexSidecarFromColumns(open.columns, bytes.byteLength, hash);
+        const restored = deserializeIndexSidecarToColumns(sidecar);
+        expect(sidecarMatchesSource(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        restored, bytes.byteLength, hash)).toBe(true);
+        expect(restored.columns.count).toBe(open.columns.firstInlineElement);
+    });
+    test("rejects a store whose length disagrees with the source", () => {
+        expect(() => openStreamedIfcModel(new BufferByteSource(bytes), new InMemoryStepByteStore(bytes.subarray(0, 100))))
+            .toThrow(/does not match/);
+    });
+    test("releaseSourceViews still lets a later read re-acquire", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        const localID = model.resolveExpressID(expressID);
+        await model.ensureResidentByLocalID(localID);
+        const first = model.getElementByExpressID(expressID);
+        expect(first).toBeDefined();
+        const args = first.extractLineArguments();
+        expect(args.length).toBeGreaterThan(0);
+        model.releaseSourceViews([localID]);
+        await model.ensureResidentByLocalID(localID);
+        const again = model.getElementByExpressID(expressID);
+        expect(again.extractLineArguments().length).toBe(args.length);
+    });
+    test("extractParseBuffer rematerialises after releaseSourceViews", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        const localID = model.resolveExpressID(expressID);
+        await model.ensureResidentByLocalID(localID);
+        const first = model.getElementByExpressID(expressID);
+        // Populate vtable + buffer the way a first extract does.
+        expect(first.extractLineArguments().length).toBeGreaterThan(0);
+        // A real heap rather than a stubbed HEAPU8.set. extractParseBuffer builds
+        // its destination through wasmHeapView now, which reconciles the pointer
+        // against the heap's actual buffer before writing (#485) - so the fake has
+        // to have one. It also makes the assertions stronger: the bytes are
+        // checked where they landed, not just counted on the way past.
+        const wasmHeap = new Uint8Array(4 * 1024);
+        const fakeModule = { HEAPU8: wasmHeap };
+        const copied = [];
+        const fakeResult = { resize: (n) => {
+                copied.push(n);
+                return 0;
+            } };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        first.extractParseBuffer(0, 0, 0, fakeResult, fakeModule, true);
+        expect(copied[0]).toBeGreaterThan(0);
+        // Landed in the heap, at the pointer resize handed back.
+        const written = Array.from(wasmHeap.subarray(0, copied[0]));
+        expect(written.some((byte) => byte !== 0)).toBe(true);
+        model.releaseSourceViews([localID]);
+        await model.ensureResidentByLocalID(localID);
+        // Same entity object — vtable kept, buffer dropped. This is the
+        // PSB "Cannot read properties of undefined (reading 'subarray')" path.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        first.extractParseBuffer(0, 0, 0, fakeResult, fakeModule, true);
+        expect(copied[1]).toBe(copied[0]);
+    });
+    test("ensureResidentClosureByLocalID visits every #ref hop", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        const localID = model.resolveExpressID(expressID);
+        await model.ensureResidentByLocalID(localID);
+        const refs = model.referencedExpressIDs(localID);
+        expect(refs.length).toBeGreaterThan(0);
+        const visited = await model.ensureResidentClosureByLocalID(localID);
+        expect(visited.has(localID)).toBe(true);
+        expect(model.typeIDOf(localID)).toBeDefined();
+        for (const refExpressID of refs) {
+            const refLocalID = model.resolveExpressID(refExpressID);
+            if (refLocalID !== void 0) {
+                expect(visited.has(refLocalID)).toBe(true);
+            }
+        }
+    });
+    test("ensureResidentClosureByLocalID skip-descend does not follow #refs", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        const localID = model.resolveExpressID(expressID);
+        await model.ensureResidentByLocalID(localID);
+        const refs = model.referencedExpressIDs(localID);
+        expect(refs.length).toBeGreaterThan(0);
+        const leafSpans = [];
+        const visited = await model.ensureResidentClosureByLocalID(localID, void 0, new Set(), (id) => id === localID, leafSpans);
+        expect(visited.has(localID)).toBe(true);
+        expect(visited.size).toBe(1);
+        expect(leafSpans.length).toBeGreaterThan(0);
+        expect(leafSpans[0].length).toBeGreaterThan(0);
+    });
+    test("spanLeaf spans children; !descend without spanLeaf still visits them", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressID = [...model.expressIDsOfTypes(IfcRoot)][0];
+        const localID = model.resolveExpressID(expressID);
+        await model.ensureResidentByLocalID(localID);
+        const refs = model.referencedExpressIDs(localID);
+        expect(refs.length).toBeGreaterThan(0);
+        const leafSpans = [];
+        const visited = await model.ensureResidentClosureByLocalID(localID, void 0, new Set(), (id) => id === localID, leafSpans, () => false);
+        expect(visited.has(localID)).toBe(true);
+        expect(visited.size).toBeGreaterThan(1);
+        expect(leafSpans.length).toBe(0);
+    });
+    test("spansOfExpressIDs covers each record without the holes between", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const model = fromStore.model;
+        const expressIDs = [...model.expressIDsOfTypes(IfcRoot)];
+        expect(expressIDs.length).toBeGreaterThan(1);
+        const spans = model.spansOfExpressIDs(expressIDs);
+        expect(spans.length).toBeGreaterThan(0);
+        let covered = 0;
+        let hullMin = Infinity;
+        let hullMax = 0;
+        for (const span of spans) {
+            covered += span.length;
+        }
+        for (const refExpressID of expressIDs) {
+            const localID = model.resolveExpressID(refExpressID);
+            const address = model.recordAddress(localID);
+            const end = address + model.recordLength(localID);
+            if (address < hullMin) {
+                hullMin = address;
+            }
+            if (end > hullMax) {
+                hullMax = end;
+            }
+            const inside = spans.some((span) => address >= span.address && end <= span.address + span.length);
+            expect(inside).toBe(true);
+        }
+        // IfcRoot rows are scattered through index.ifc — the coalesced
+        // spans must not be the single hull from first to last.
+        expect(covered).toBeLessThan(hullMax - hullMin);
+    });
+    test("openStreamedIfcModelFromStore matches the sync open", async () => {
+        const store = new InMemoryStepByteStore(bytes);
+        const fromStore = await openStreamedIfcModelFromStore(store, { pool: 4 * 1024 });
+        const streamed = openStreamedIfcModel(new BufferByteSource(bytes), store, { pool: 4 * 1024 });
+        expect(fromStore.result).toBe(ParseResult.COMPLETE);
+        expect(fromStore.model.isSourceExternal).toBe(true);
+        expect([...fromStore.model.expressIDsOfTypes(IfcRoot)])
+            .toEqual([...streamed.model.expressIDsOfTypes(IfcRoot)]);
+    });
+});