@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/step/parsing/streaming_record_dispatcher.js

@@ -0,0 +1,88 @@
+/**
+ * Routes the streaming parse's per-record events (M2) to consumers that
+ * subscribe by **type set**. A subscription's type set is the subtype closure
+ * of the entity constructors it names — the same `query` closure the type
+ * index and `expressIDsOfTypes` use (conway #383) — so `on([IfcRoot], …)`
+ * matches every product, relationship, property set and quantity, and any
+ * future IfcRoot subtype, with no whitelist to maintain.
+ *
+ * Feed `dispatcher.onRecordIndexed` to `buildIndexStreaming` /
+ * `parseDataBlockStreamed`. Handlers run synchronously in the parse path, so
+ * they must be cheap (copy ids into a compact structure); anything expensive
+ * belongs on a demand queue, not here.
+ *
+ * Because subscriptions match on the raw parse `typeID`, external-mapping /
+ * complex records (typeID 0) are only delivered via `onAnyRecord`. Resolving
+ * their concrete types is not this class's job and never was: the columns
+ * carry the multi-mapping, so
+ * {@link import('./prefix_type_index').PrefixTypeIndex} attributes them
+ * correctly without the event stream. For the overwhelming majority of records
+ * (simple, one type each) type-set delivery is exact.
+ */
+export class StreamingRecordDispatcher {
+    constructor() {
+        /**
+         * Concrete type → the handlers subscribed to it, unioned across
+         * subscriptions. Dispatch is one lookup per record no matter how many
+         * consumers are attached: the per-record cost of a subscription is the only
+         * cost this class has at 9.4 M records, so it must not scale with the
+         * subscriber count (issue #393).
+         */
+        this.byType = new Map();
+        this.any = [];
+        /**
+         * The per-record callback to hand to the streaming parse. Dispatches each
+         * record to the matching subscribers. Bound so it can be passed directly.
+         *
+         * @param localID The record's dense local ID.
+         * @param expressID The record's express ID.
+         * @param typeID The record's type ID (0 for external-mapping records).
+         * @param buffer The live parse window holding the record's bytes.
+         * @param byteOffset Offset of the record's first byte within `buffer`.
+         * @param byteLength Length of the record in bytes.
+         */
+        this.onRecordIndexed = (localID, expressID, typeID, buffer, byteOffset, byteLength) => {
+            for (const handler of this.any) {
+                handler(localID, expressID, typeID, buffer, byteOffset, byteLength);
+            }
+            if (typeID !== void 0) {
+                const handlers = this.byType.get(typeID);
+                if (handlers !== void 0) {
+                    for (const handler of handlers) {
+                        handler(localID, expressID, typeID, buffer, byteOffset, byteLength);
+                    }
+                }
+            }
+        };
+    }
+    /**
+     * Subscribe to records of the given entity types (including their
+     * subtypes).
+     *
+     * @param types The entity constructors whose subtype closures to match.
+     * @param handler Called for each matching record.
+     */
+    on(types, handler) {
+        // Closures overlap between subscriptions (IfcRoot ⊃ IfcProduct, …), so a
+        // type may already have handlers; dedupe within one subscription so a
+        // constructor named twice doesn't deliver twice.
+        for (const typeID of new Set(types.flatMap((type) => type.query))) {
+            const handlers = this.byType.get(typeID);
+            if (handlers === void 0) {
+                this.byType.set(typeID, [handler]);
+            }
+            else {
+                handlers.push(handler);
+            }
+        }
+    }
+    /**
+     * Subscribe to every record regardless of type (the firehose — including
+     * external-mapping records).
+     *
+     * @param handler Called for every record.
+     */
+    onAnyRecord(handler) {
+        this.any.push(handler);
+    }
+}

package/compiled/src/step/parsing/streaming_record_dispatcher.test.d.ts

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

package/compiled/src/step/parsing/streaming_record_dispatcher.test.d.ts.map

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

package/compiled/src/step/parsing/streaming_record_dispatcher.test.js

@@ -0,0 +1,66 @@
+/* eslint-disable no-magic-numbers */
+// M2 core: record events emitted live from the streaming parse, routed by a
+// type-set subscription, let a consumer build a semantic structure
+// incrementally — and it must match what the finished model's type index
+// yields. Here: a roots registry collected from the event stream equals
+// `expressIDsOfTypes(IfcRoot)` on the resident model.
+import * as fs from "fs";
+import { beforeAll, describe, expect, test } from "@jest/globals";
+import ParsingBuffer from "../../parsing/parsing_buffer.js";
+import IfcStepParser from "../../ifc/ifc_step_parser.js";
+import { BufferByteSource } from "./byte_source.js";
+import { buildIndexStreaming } from "./streaming_index_builder.js";
+import { StreamingRecordDispatcher } from "./streaming_record_dispatcher.js";
+import { ParseResult } from "./step_parser.js";
+import { IfcRoot, IfcProduct } from "../../ifc/ifc4_gen/index.js";
+let bytes;
+let residentRoots;
+let residentProducts;
+beforeAll(() => {
+    bytes = new Uint8Array(fs.readFileSync("data/index.ifc"));
+    const input = new ParsingBuffer(bytes);
+    IfcStepParser.Instance.parseHeader(input);
+    const [, model] = IfcStepParser.Instance.parseDataToModel(input);
+    residentRoots = new Set(model.expressIDsOfTypes(IfcRoot));
+    residentProducts = new Set(model.expressIDsOfTypes(IfcProduct));
+});
+describe("StreamingRecordDispatcher", () => {
+    test("a roots registry built live from the event stream matches the type index", () => {
+        const roots = [];
+        const products = new Set();
+        const dispatcher = new StreamingRecordDispatcher();
+        dispatcher.on([IfcRoot], (_localID, expressID) => roots.push(expressID));
+        dispatcher.on([IfcProduct], (_localID, expressID) => products.add(expressID));
+        const result = buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024, // tiny pool → the parse slides; events still fire per record
+        dispatcher.onRecordIndexed);
+        expect(result.result).toBe(ParseResult.COMPLETE);
+        // index.ifc has no external-mapping records, so raw-typeID delivery is
+        // exact vs. the type index.
+        expect(new Set(roots)).toEqual(residentRoots);
+        expect(products).toEqual(residentProducts);
+        // Products are a strict subset of roots (IfcProduct ⊂ IfcRoot).
+        expect(residentProducts.size).toBeLessThan(residentRoots.size);
+        for (const p of products) {
+            expect(residentRoots.has(p)).toBe(true);
+        }
+    });
+    test("localIDs arrive dense and in ascending parse order", () => {
+        const localIDs = [];
+        const dispatcher = new StreamingRecordDispatcher();
+        dispatcher.onAnyRecord((localID) => localIDs.push(localID));
+        buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 128 * 1024, dispatcher.onRecordIndexed);
+        expect(localIDs.length).toBeGreaterThan(10);
+        // 0,1,2,…,n-1 in order.
+        expect(localIDs).toEqual(localIDs.map((_v, i) => i));
+    });
+    test("onAnyRecord sees every record; a type filter sees a subset", () => {
+        let all = 0;
+        let rootsCount = 0;
+        const dispatcher = new StreamingRecordDispatcher();
+        dispatcher.onAnyRecord(() => ++all);
+        dispatcher.on([IfcRoot], () => ++rootsCount);
+        buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 128 * 1024, dispatcher.onRecordIndexed);
+        expect(all).toBeGreaterThan(rootsCount);
+        expect(rootsCount).toBe(residentRoots.size);
+    });
+});

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

@@ -0,0 +1,72 @@
+/**
+ * Growable Uint32Array append sink.
+ *
+ * Exists so hot extraction loops can parse integer list fields straight
+ * out of the STEP buffer into one reusable typed array, instead of
+ * allocating (and caching) a boxed `Array< number >` per record. On
+ * tessellated IFC4 models that difference is structural: a large
+ * polygonal-faceset model carries millions of IfcIndexedPolygonalFace
+ * records, and a per-record array for each is the dominant source of
+ * both GC time and retained heap during geometry extraction.
+ */
+export declare class Uint32Sink {
+    private data_;
+    private length_;
+    /**
+     * @param initialCapacity Initial element capacity.
+     */
+    constructor(initialCapacity?: number);
+    /** @return {number} Element count appended since the last reset. */
+    get length(): number;
+    /**
+     * A view of exactly the appended elements. Only valid until the next
+     * append (which may reallocate) — copy it if it must outlive that.
+     *
+     * @return {Uint32Array} View over [0, length).
+     */
+    get view(): Uint32Array;
+    /** Drop all appended elements, keeping the allocated capacity. */
+    reset(): void;
+    /**
+     * Keep the first `length` elements. Used to unwind a failed fast path.
+     *
+     * @param length New length, ≤ current length.
+     */
+    truncate(length: number): void;
+    /**
+     * Append one value, growing geometrically when full.
+     *
+     * @param value The value to append.
+     */
+    push(value: number): void;
+}
+/**
+ * Parse a STEP integer list at `cursor` into `sink`, appending in order.
+ *
+ * The single implementation shared by the entity-level and
+ * reference-level fast paths, so they cannot drift from each other or
+ * from the generated array getters they stand in for (same optional
+ * handling, same element extraction, same "incorrectly typed" error).
+ *
+ * @param buffer The record's buffer window.
+ * @param cursor Start of the field.
+ * @param endCursor End bound for extraction.
+ * @param sink Receives the appended values.
+ * @return {number} How many values were appended (0 when unset/optional-null).
+ */
+export declare function extractIntegerArrayAt(buffer: Uint8Array, cursor: number, endCursor: number, sink: Uint32Sink): number;
+/**
+ * Fast path for `(1,2,3,4)` / `(1, 2, 3, 4)` — the CoordIndex shape.
+ * Digits only, no comments, no reals. Returns undefined when the field
+ * is not that shape so the caller can use the general parser. A failed
+ * parse does not leave partial values in `sink`.
+ *
+ * @param buffer Record window.
+ * @param cursor Start of the field.
+ * @param endCursor End bound.
+ * @param sink Receives values.
+ * @return {number | undefined} Count appended, or undefined if this
+ * is not an unsigned-integer list.
+ */
+export declare function extractUnsignedIntegerListAt(buffer: Uint8Array, cursor: number, endCursor: number, sink: Uint32Sink): number | undefined;
+//# sourceMappingURL=uint32_sink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uint32_sink.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/uint32_sink.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IAErB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,OAAO,CAAY;IAE3B;;OAEG;gBACU,eAAe,GAAE,MAAa;IAI3C,oEAAoE;IACpE,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED;;;;;OAKG;IACH,IAAW,IAAI,IAAI,WAAW,CAE7B;IAED,kEAAkE;IAC3D,KAAK,IAAI,IAAI;IAIpB;;;;OAIG;IACI,QAAQ,CAAE,MAAM,EAAE,MAAM,GAAI,IAAI;IAIvC;;;;OAIG;IACI,IAAI,CAAE,KAAK,EAAE,MAAM,GAAI,IAAI;CAanC;AAGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,GAAI,MAAM,CAqC7B;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CACxC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,GAAI,MAAM,GAAG,SAAS,CAsFzC"}

package/compiled/src/step/parsing/uint32_sink.js

@@ -0,0 +1,180 @@
+import { skipValue, stepExtractArrayBegin, stepExtractArrayToken, stepExtractNumber, stepExtractOptional, } from "./step_deserialization_functions.js";
+import ParsingConstants from "../../parsing/parsing_constants.js";
+const OPEN_PAREN = ParsingConstants.OPEN_PAREN;
+const CLOSE_PAREN = ParsingConstants.CLOSE_PAREN;
+const COMMA = ParsingConstants.COMMA;
+const ZERO = ParsingConstants.ZERO;
+const WHITESPACE = ParsingConstants.WHITE_SPACE_SET;
+/**
+ * Growable Uint32Array append sink.
+ *
+ * Exists so hot extraction loops can parse integer list fields straight
+ * out of the STEP buffer into one reusable typed array, instead of
+ * allocating (and caching) a boxed `Array< number >` per record. On
+ * tessellated IFC4 models that difference is structural: a large
+ * polygonal-faceset model carries millions of IfcIndexedPolygonalFace
+ * records, and a per-record array for each is the dominant source of
+ * both GC time and retained heap during geometry extraction.
+ */
+export class Uint32Sink {
+    /**
+     * @param initialCapacity Initial element capacity.
+     */
+    constructor(initialCapacity = 1024) {
+        this.length_ = 0;
+        this.data_ = new Uint32Array(Math.max(1, initialCapacity));
+    }
+    /** @return {number} Element count appended since the last reset. */
+    get length() {
+        return this.length_;
+    }
+    /**
+     * A view of exactly the appended elements. Only valid until the next
+     * append (which may reallocate) — copy it if it must outlive that.
+     *
+     * @return {Uint32Array} View over [0, length).
+     */
+    get view() {
+        return this.data_.subarray(0, this.length_);
+    }
+    /** Drop all appended elements, keeping the allocated capacity. */
+    reset() {
+        this.length_ = 0;
+    }
+    /**
+     * Keep the first `length` elements. Used to unwind a failed fast path.
+     *
+     * @param length New length, ≤ current length.
+     */
+    truncate(length) {
+        this.length_ = length;
+    }
+    /**
+     * Append one value, growing geometrically when full.
+     *
+     * @param value The value to append.
+     */
+    push(value) {
+        if (this.length_ === this.data_.length) {
+            const grown = new Uint32Array(this.data_.length * 2);
+            grown.set(this.data_);
+            this.data_ = grown;
+        }
+        this.data_[this.length_++] = value;
+    }
+}
+/**
+ * Parse a STEP integer list at `cursor` into `sink`, appending in order.
+ *
+ * The single implementation shared by the entity-level and
+ * reference-level fast paths, so they cannot drift from each other or
+ * from the generated array getters they stand in for (same optional
+ * handling, same element extraction, same "incorrectly typed" error).
+ *
+ * @param buffer The record's buffer window.
+ * @param cursor Start of the field.
+ * @param endCursor End bound for extraction.
+ * @param sink Receives the appended values.
+ * @return {number} How many values were appended (0 when unset/optional-null).
+ */
+export function extractIntegerArrayAt(buffer, cursor, endCursor, sink) {
+    const marked = sink.length;
+    const fast = extractUnsignedIntegerListAt(buffer, cursor, endCursor, sink);
+    if (fast !== void 0) {
+        return fast;
+    }
+    sink.truncate(marked);
+    if (stepExtractOptional(buffer, cursor, endCursor) === null) {
+        return 0;
+    }
+    let count = 0;
+    let signedCursor0 = stepExtractArrayBegin(buffer, cursor, endCursor);
+    let readCursor = Math.abs(signedCursor0);
+    while (signedCursor0 >= 0) {
+        const value = stepExtractNumber(buffer, readCursor, endCursor);
+        if (value === void 0) {
+            throw new Error("Value in STEP was incorrectly typed");
+        }
+        readCursor = skipValue(buffer, readCursor, endCursor);
+        sink.push(value);
+        ++count;
+        signedCursor0 = stepExtractArrayToken(buffer, readCursor, endCursor);
+        readCursor = Math.abs(signedCursor0);
+    }
+    return count;
+}
+/**
+ * Fast path for `(1,2,3,4)` / `(1, 2, 3, 4)` — the CoordIndex shape.
+ * Digits only, no comments, no reals. Returns undefined when the field
+ * is not that shape so the caller can use the general parser. A failed
+ * parse does not leave partial values in `sink`.
+ *
+ * @param buffer Record window.
+ * @param cursor Start of the field.
+ * @param endCursor End bound.
+ * @param sink Receives values.
+ * @return {number | undefined} Count appended, or undefined if this
+ * is not an unsigned-integer list.
+ */
+export function extractUnsignedIntegerListAt(buffer, cursor, endCursor, sink) {
+    const marked = sink.length;
+    while (cursor < endCursor && WHITESPACE.has(buffer[cursor])) {
+        ++cursor;
+    }
+    if (cursor >= endCursor) {
+        return void 0;
+    }
+    if (buffer[cursor] === ParsingConstants.DOLLAR) {
+        return 0;
+    }
+    if (buffer[cursor] !== OPEN_PAREN) {
+        return void 0;
+    }
+    ++cursor;
+    let count = 0;
+    while (cursor < endCursor) {
+        while (cursor < endCursor && WHITESPACE.has(buffer[cursor])) {
+            ++cursor;
+        }
+        if (cursor >= endCursor) {
+            sink.truncate(marked);
+            return void 0;
+        }
+        if (buffer[cursor] === CLOSE_PAREN) {
+            return count;
+        }
+        if (count > 0) {
+            if (buffer[cursor] !== COMMA) {
+                sink.truncate(marked);
+                return void 0;
+            }
+            ++cursor;
+            while (cursor < endCursor && WHITESPACE.has(buffer[cursor])) {
+                ++cursor;
+            }
+            if (cursor >= endCursor) {
+                sink.truncate(marked);
+                return void 0;
+            }
+        }
+        const digit = buffer[cursor] - ZERO;
+        if (digit < 0 || digit > 9) {
+            sink.truncate(marked);
+            return void 0;
+        }
+        let value = digit;
+        ++cursor;
+        while (cursor < endCursor) {
+            const next = buffer[cursor] - ZERO;
+            if (next < 0 || next > 9) {
+                break;
+            }
+            value = value * 10 + next;
+            ++cursor;
+        }
+        sink.push(value);
+        ++count;
+    }
+    sink.truncate(marked);
+    return void 0;
+}

package/compiled/src/step/parsing/uint32_sink.test.d.ts

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

package/compiled/src/step/parsing/uint32_sink.test.d.ts.map

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

package/compiled/src/step/parsing/uint32_sink.test.js

@@ -0,0 +1,199 @@
+/* eslint-disable no-magic-numbers */
+// Uint32Sink backs the polygonal-faceset extraction fast path, and
+// extractIntegerArrayInto must stay exactly equivalent to the generated
+// array getters it replaces there — including for a real model's faces.
+import * as fs from "fs";
+import { beforeAll, describe, expect, test } from "@jest/globals";
+import { IfcAPI } from "../../compat/web-ifc/ifc_api.js";
+import EntityTypesIfc from "../../ifc/ifc4_gen/entity_types_ifc.gen.js";
+import { IfcIndexedPolygonalFace, IfcIndexedPolygonalFaceWithVoids, IfcPolygonalFaceSet, } from "../../ifc/ifc4_gen/index.js";
+import { Uint32Sink, extractUnsignedIntegerListAt } from "./uint32_sink.js";
+describe("Uint32Sink", () => {
+    test("appends, grows past its initial capacity, and views exactly its length", () => {
+        const sink = new Uint32Sink(2);
+        expect(sink.length).toBe(0);
+        expect(Array.from(sink.view)).toEqual([]);
+        for (let where = 0; where < 10; ++where) {
+            sink.push(where * 3);
+        }
+        expect(sink.length).toBe(10);
+        expect(Array.from(sink.view)).toEqual([0, 3, 6, 9, 12, 15, 18, 21, 24, 27]);
+    });
+    test("extractUnsignedIntegerListAt parses a plain CoordIndex list", () => {
+        const sink = new Uint32Sink(4);
+        const bytes = new TextEncoder().encode("(1,2,3,4)");
+        expect(extractUnsignedIntegerListAt(bytes, 0, bytes.length, sink)).toBe(4);
+        expect(Array.from(sink.view)).toEqual([1, 2, 3, 4]);
+    });
+    test("extractUnsignedIntegerListAt refuses a real and leaves the sink clean", () => {
+        const sink = new Uint32Sink(4);
+        const bytes = new TextEncoder().encode("(1,2.5,3)");
+        sink.push(9);
+        expect(extractUnsignedIntegerListAt(bytes, 0, bytes.length, sink))
+            .toBeUndefined();
+        expect(Array.from(sink.view)).toEqual([9]);
+    });
+    test("reset drops elements but keeps capacity for reuse", () => {
+        const sink = new Uint32Sink(4);
+        sink.push(11);
+        sink.push(22);
+        sink.reset();
+        expect(sink.length).toBe(0);
+        expect(Array.from(sink.view)).toEqual([]);
+        sink.push(33);
+        expect(Array.from(sink.view)).toEqual([33]);
+    });
+});
+describe("extractIntegerArrayInto", () => {
+    let api;
+    let modelID;
+    /**
+     * The faces the extraction fast path actually covers: voided faces
+     * keep the getter path in production, so exclude them here too.
+     *
+     * @return {IfcIndexedPolygonalFace[]} Non-voided faces of the fixture.
+     */
+    function plainFaces() {
+        // The passthrough holds the proxy tuple; the StepModel is its head.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const model = api.models.get(modelID).model[0];
+        return Array.from(model.types(IfcIndexedPolygonalFace))
+            .filter((face) => !(face instanceof IfcIndexedPolygonalFaceWithVoids));
+    }
+    beforeAll(async () => {
+        api = new IfcAPI();
+        await api.Init();
+        modelID = api.OpenModel(new Uint8Array(fs.readFileSync("data/index.ifc")), { COORDINATE_TO_ORIGIN: true, USE_FAST_BOOLS: true });
+    }, 120000);
+    test("matches the generated CoordIndex getter on every face of a real model", () => {
+        const faces = plainFaces();
+        expect(faces.length).toBeGreaterThan(0);
+        const sink = new Uint32Sink(4);
+        for (const face of faces) {
+            // The getter caches, so read it first and compare the in-place
+            // parse against it — the fast path must be a drop-in.
+            const expected = face.CoordIndex;
+            sink.reset();
+            const count = face.extractIntegerArrayInto(0, 0, 3, sink);
+            expect(count).toBe(expected.length);
+            expect(Array.from(sink.view)).toEqual(expected);
+        }
+    }, 120000);
+    test("appends consecutively across records into one sink", () => {
+        const faces = plainFaces();
+        const sink = new Uint32Sink(4);
+        const expected = [];
+        for (const face of faces) {
+            face.extractIntegerArrayInto(0, 0, 3, sink);
+            expected.push(...face.CoordIndex);
+        }
+        expect(Array.from(sink.view)).toEqual(expected);
+    }, 120000);
+});
+// The reference-level path the faceset extraction uses to avoid
+// constructing an entity per face. It must agree with the generated
+// getters exactly, and must report failure (rather than guess) whenever
+// its preconditions don't hold, because the caller's fallback depends on
+// that signal.
+describe("reference-level faceset fast path", () => {
+    const FACES_OFFSET = 2;
+    const FACES_BASE_OFFSET = 1;
+    const FACES_DEPTH = 4;
+    const COORD_INDEX_OFFSET = 0;
+    let api;
+    let modelID;
+    /**
+     * @return {object} The StepModel behind the passthrough tuple.
+     */
+    function stepModel() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return api.models.get(modelID).model[0];
+    }
+    /**
+     * @return {IfcPolygonalFaceSet[]} The fixture's facesets.
+     */
+    function faceSets() {
+        return Array.from(stepModel().types(IfcPolygonalFaceSet));
+    }
+    beforeAll(async () => {
+        api = new IfcAPI();
+        await api.Init();
+        modelID = api.OpenModel(new Uint8Array(fs.readFileSync("data/index.ifc")), { COORDINATE_TO_ORIGIN: true, USE_FAST_BOOLS: true });
+    }, 120000);
+    test("forEachReferenceInField yields exactly the express IDs the Faces getter resolves", () => {
+        const sets = faceSets();
+        expect(sets.length).toBeGreaterThan(0);
+        for (const faceSet of sets) {
+            const walked = [];
+            const completed = faceSet.forEachReferenceInField(FACES_OFFSET, FACES_BASE_OFFSET, FACES_DEPTH, (expressID) => {
+                walked.push(expressID);
+                return true;
+            });
+            expect(completed).toBe(true);
+            expect(walked).toEqual(faceSet.Faces.map((face) => face.expressID));
+        }
+    }, 120000);
+    test("forEachReferenceInField stops when the callback returns false", () => {
+        const faceSet = faceSets()[0];
+        const walked = [];
+        const completed = faceSet.forEachReferenceInField(FACES_OFFSET, FACES_BASE_OFFSET, FACES_DEPTH, (expressID) => {
+            walked.push(expressID);
+            return false;
+        });
+        expect(completed).toBe(false);
+        expect(walked.length).toBe(1);
+    }, 120000);
+    test("extractIntegerArrayByExpressIDInto matches the generated CoordIndex getter", () => {
+        const model = stepModel();
+        const sink = new Uint32Sink(4);
+        for (const faceSet of faceSets()) {
+            for (const face of faceSet.Faces) {
+                if (face instanceof IfcIndexedPolygonalFaceWithVoids) {
+                    continue;
+                }
+                sink.reset();
+                const count = model.extractIntegerArrayByExpressIDInto(face.expressID, COORD_INDEX_OFFSET, EntityTypesIfc.IFCINDEXEDPOLYGONALFACE, sink);
+                expect(count).toBe(face.CoordIndex.length);
+                expect(Array.from(sink.view)).toEqual(face.CoordIndex);
+            }
+        }
+    }, 120000);
+    test("column path matches CoordIndex without materialising the face first", () => {
+        const model = stepModel();
+        const sink = new Uint32Sink(4);
+        for (const faceSet of faceSets()) {
+            const expressIDs = [];
+            faceSet.forEachReferenceInField(FACES_OFFSET, FACES_BASE_OFFSET, FACES_DEPTH, (expressID) => {
+                if (expressID !== void 0) {
+                    expressIDs.push(expressID);
+                }
+                return true;
+            });
+            const fromColumns = [];
+            for (const expressID of expressIDs) {
+                sink.reset();
+                const count = model.extractIntegerArrayByExpressIDInto(expressID, COORD_INDEX_OFFSET, EntityTypesIfc.IFCINDEXEDPOLYGONALFACE, sink);
+                if (count === void 0) {
+                    continue;
+                }
+                fromColumns.push(Array.from(sink.view));
+            }
+            const fromGetter = faceSet.Faces
+                .filter((face) => !(face instanceof IfcIndexedPolygonalFaceWithVoids))
+                .map((face) => face.CoordIndex);
+            expect(fromColumns).toEqual(fromGetter);
+        }
+    }, 120000);
+    test("reports failure for an unknown express ID and for a type mismatch", () => {
+        const model = stepModel();
+        const sink = new Uint32Sink(4);
+        const face = faceSets()[0].Faces[0];
+        // Unknown record: the caller must fall back, not read something else.
+        expect(model.extractIntegerArrayByExpressIDInto(268435455, COORD_INDEX_OFFSET, EntityTypesIfc.IFCINDEXEDPOLYGONALFACE, sink))
+            .toBeUndefined();
+        // Right record, wrong expected type: field offsets would not be
+        // comparable, so this must refuse rather than misread the record.
+        expect(model.extractIntegerArrayByExpressIDInto(face.expressID, COORD_INDEX_OFFSET, EntityTypesIfc.IFCPOLYGONALFACESET, sink))
+            .toBeUndefined();
+    }, 120000);
+});