@bldrs-ai/conway 1.389.1221 → 1.394.1504

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

@@ -0,0 +1,224 @@
+/** Type sentinel for "no concrete type" in the typeID column. */
+export const COLUMN_UNDEFINED_TYPE = -1;
+// Records per growth segment. 64 K rows × 16 B ≈ 1 MB per segment — growth
+// never copies previously written rows, and finalize concatenates one column
+// at a time so the transient overhead is one column's segments, not 2× the
+// index.
+// eslint-disable-next-line no-magic-numbers
+const SEGMENT_ROWS = 64 * 1024;
+/**
+ * A {@link StepIndexSink} that encodes top-level records straight into
+ * chunked-segment typed-array columns, so the parse holds **no per-record
+ * objects** for the (overwhelmingly common) simple records. Records with
+ * children keep their object form — inline entities are unfolded into the
+ * inline column range at {@link finalize}, and multi-mapping holders are
+ * retained for the model's `complexEntries`, matching the object path's
+ * behaviour entry-for-entry.
+ *
+ * `reset` supports the streaming builder's rare grow-and-restart: columns
+ * rewind to empty without reallocating the first segment.
+ */
+export class ColumnarIndexSink {
+    constructor() {
+        this.segments_ = [];
+        this.count_ = 0;
+        /** Entries with inlineEntities and/or multiMapping, keyed by localID. */
+        this.retained_ = new Map();
+        this.expressIdsSorted_ = true;
+        this.previousExpressID_ = 0;
+    }
+    /**
+     * @return {number} Top-level records pushed so far.
+     */
+    get topLevelCount() {
+        return this.count_;
+    }
+    /**
+     * Encode one completed top-level record into the columns. The entry object
+     * is not kept unless it carries children (inline entities / multi-mapping).
+     *
+     * @param entry The completed top-level index entry.
+     */
+    pushTopLevel(entry) {
+        const localID = this.count_++;
+        const segmentIndex = Math.floor(localID / SEGMENT_ROWS);
+        const row = localID % SEGMENT_ROWS;
+        if (segmentIndex === this.segments_.length) {
+            this.segments_.push({
+                address: new Uint32Array(SEGMENT_ROWS),
+                length: new Uint32Array(SEGMENT_ROWS),
+                typeID: new Int32Array(SEGMENT_ROWS),
+                expressID: new Uint32Array(SEGMENT_ROWS),
+            });
+        }
+        const segment = this.segments_[segmentIndex];
+        segment.address[row] = entry.address;
+        segment.length[row] = entry.length;
+        segment.typeID[row] =
+            entry.typeID === void 0 ? COLUMN_UNDEFINED_TYPE : entry.typeID;
+        segment.expressID[row] = entry.expressID;
+        if (entry.expressID < this.previousExpressID_) {
+            this.expressIdsSorted_ = false;
+        }
+        this.previousExpressID_ = entry.expressID;
+        if (entry.inlineEntities !== void 0 || entry.multiMapping !== void 0) {
+            this.retained_.set(localID, entry);
+        }
+    }
+    /**
+     * Rewind to empty (the streaming builder's grow-and-restart). The first
+     * segment is kept for reuse.
+     */
+    reset() {
+        this.segments_.length = Math.min(this.segments_.length, 1);
+        this.count_ = 0;
+        this.retained_.clear();
+        this.expressIdsSorted_ = true;
+        this.previousExpressID_ = 0;
+    }
+    /**
+     * Snapshot the columns pushed SO FAR into a self-contained prefix index,
+     * without disturbing the sink — the parse can keep pushing afterwards and
+     * a later snapshot/finalize sees the full data. Safe to call between the
+     * cooperative parse's yields (the parser only suspends at top-level
+     * record boundaries, where the sink is consistent). Top-level localIDs
+     * are stable across snapshots (dense parse order), so consumers can carry
+     * per-localID cursors from one snapshot to the next; inline-range
+     * localIDs are NOT stable (the inline tail re-packs after the growing
+     * top-level range) and must not be carried across snapshots.
+     *
+     * @return {StepIndexColumns} A prefix columnar index over the records
+     * pushed so far.
+     */
+    snapshot() {
+        return this.assemble_();
+    }
+    /**
+     * Assemble the final columns: concatenate the top-level segments (one
+     * column at a time, bounding transient overhead to a single column's
+     * segments) and unfold retained inline entities into the inline range in
+     * the model's exact unfold order.
+     *
+     * @return {StepIndexColumns} The finished columnar index.
+     */
+    finalize() {
+        return this.assemble_();
+    }
+    /**
+     * Shared assembly behind {@link snapshot} and {@link finalize} — pure
+     * over the sink's current state.
+     *
+     * @return {StepIndexColumns} The assembled columnar index.
+     */
+    assemble_() {
+        const topLevel = this.count_;
+        // Unfold inline entities exactly as StepModelBase does over the object
+        // array: scan in localID order appending children, then keep scanning
+        // the appended region (children of children follow all first-level
+        // children). Only retained entries can contribute — simple records have
+        // no children by construction.
+        const unfolded = [];
+        for (const entry of this.retained_.values()) {
+            if (entry.inlineEntities !== void 0) {
+                unfolded.push(...entry.inlineEntities);
+            }
+        }
+        for (let where = 0; where < unfolded.length; ++where) {
+            const inlineEntities = unfolded[where].inlineEntities;
+            if (inlineEntities !== void 0) {
+                unfolded.push(...inlineEntities);
+            }
+        }
+        const count = topLevel + unfolded.length;
+        const address = concatColumn(this.segments_, 'address', topLevel, count);
+        const length = concatColumn(this.segments_, 'length', topLevel, count);
+        const typeID = new Int32Array(count);
+        for (let segment = 0; segment * SEGMENT_ROWS < topLevel; ++segment) {
+            const rows = Math.min(SEGMENT_ROWS, topLevel - segment * SEGMENT_ROWS);
+            typeID.set(this.segments_[segment].typeID.subarray(0, rows), segment * SEGMENT_ROWS);
+        }
+        const expressID = concatColumn(this.segments_, 'expressID', topLevel, topLevel);
+        for (let where = 0; where < unfolded.length; ++where) {
+            const entry = unfolded[where];
+            const row = topLevel + where;
+            address[row] = entry.address;
+            length[row] = entry.length;
+            typeID[row] =
+                entry.typeID === void 0 ? COLUMN_UNDEFINED_TYPE : entry.typeID;
+        }
+        let complexEntries;
+        for (const [localID, entry] of this.retained_) {
+            if (entry.multiMapping !== void 0) {
+                (complexEntries ??= new Map()).set(localID, cloneIndexEntry(entry));
+            }
+        }
+        return {
+            address,
+            length,
+            typeID,
+            expressID,
+            count,
+            firstInlineElement: topLevel,
+            complexEntries,
+            expressIdsSorted: this.expressIdsSorted_,
+        };
+    }
+}
+/**
+ * Clone an index entry (and its multiMapping sub-entries, which models
+ * also stamp) down to the persistent index fields.
+ *
+ * Models materialise complex entries by writing lazy parse state —
+ * vtable views, buffer references, entity instances — onto the entry
+ * objects IN PLACE (see StepModelBase.invalidate, which clears exactly
+ * those fields). Handing every snapshot/finalize the same retained
+ * object therefore let one model poison every other model built over
+ * the same sink: a throwaway prefix model (parse-time preview channel)
+ * stamped its own vtable views, and the durable model's short-circuit
+ * (`vtableIndex !== undefined`) then read stale views — "Value in STEP
+ * was incorrectly typed" on AP214's complex-instance transforms.
+ * Cloning per assembly keeps each model's lazy state private.
+ * `inlineEntities` stays shared: inline records are unfolded into
+ * column scalars above and their objects are never stamped.
+ *
+ * @param entry The retained entry to clone.
+ * @return {StepIndexEntryBase} A fresh holder with persistent fields only.
+ */
+function cloneIndexEntry(entry) {
+    const clone = {
+        address: entry.address,
+        length: entry.length,
+    };
+    if (entry.typeID !== void 0) {
+        clone.typeID = entry.typeID;
+    }
+    if (entry.expressID !== void 0) {
+        clone.expressID = entry.expressID;
+    }
+    if (entry.inlineEntities !== void 0) {
+        clone.inlineEntities = entry.inlineEntities;
+    }
+    if (entry.multiMapping !== void 0) {
+        clone.multiMapping = entry.multiMapping.map(cloneIndexEntry);
+    }
+    return clone;
+}
+/**
+ * Concatenate one Uint32 column's segments into a final array of
+ * `finalLength`, copying `rows` valid rows.
+ *
+ * @param segments The growth segments.
+ * @param column Which column to concatenate.
+ * @param rows Valid rows across the segments.
+ * @param finalLength Length of the final array (≥ rows; the tail is for
+ * inline rows filled by the caller).
+ * @return {Uint32Array} The concatenated column.
+ */
+function concatColumn(segments, column, rows, finalLength) {
+    const result = new Uint32Array(finalLength);
+    for (let segment = 0; segment * SEGMENT_ROWS < rows; ++segment) {
+        const valid = Math.min(SEGMENT_ROWS, rows - segment * SEGMENT_ROWS);
+        result.set(segments[segment][column].subarray(0, valid), segment * SEGMENT_ROWS);
+    }
+    return result;
+}

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

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

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

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

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

@@ -0,0 +1,155 @@
+/* eslint-disable no-magic-numbers, @typescript-eslint/no-explicit-any */
+// M7: the columnar (no-object-phase) index build must produce a model
+// indistinguishable from the object-path build — identical SoA columns,
+// identical lookup behaviour, identical type index — including on AP214
+// fixtures with inline entities and multi-mappings, the paths the object
+// walk handles specially.
+import * as fs from "fs";
+import { describe, expect, test } from "@jest/globals";
+import ParsingBuffer from "../../parsing/parsing_buffer.js";
+import IfcStepParser from "../../ifc/ifc_step_parser.js";
+import IfcStepModel from "../../ifc/ifc_step_model.js";
+import AP214StepParser from "../../AP214E3_2010/ap214_step_parser.js";
+import AP214StepModel from "../../AP214E3_2010/ap214_step_model.js";
+import { BufferByteSource } from "./byte_source.js";
+import { buildColumnarIndexStreaming } from "./streaming_index_builder.js";
+import { ColumnarIndexSink } from "./columnar_index.js";
+import { ParseResult } from "./step_parser.js";
+import { IfcProduct, IfcRoot } from "../../ifc/ifc4_gen/index.js";
+/**
+ * Parse a file resident via the object path and return buffer + elements.
+ *
+ * @param path The file to parse.
+ * @param parser The parser instance for its schema.
+ * @return {object} `{ bytes, elements }`.
+ */
+function objectParse(path, parser) {
+    const bytes = new Uint8Array(fs.readFileSync(path));
+    const input = new ParsingBuffer(bytes);
+    parser.parseHeader(input);
+    const [index, result] = parser.parseDataBlock(input);
+    expect(result).toBe(ParseResult.COMPLETE);
+    return { bytes, elements: index.elements };
+}
+/**
+ * Assert two models have byte-identical internal columns and equal type
+ * indexes across every type either contains.
+ *
+ * @param a First model.
+ * @param b Second model.
+ */
+function expectModelParity(a, b) {
+    expect(a.count_).toBe(b.count_);
+    expect(a.firstInlineElement_).toBe(b.firstInlineElement_);
+    expect(Array.from(a.address_)).toEqual(Array.from(b.address_));
+    expect(Array.from(a.length_)).toEqual(Array.from(b.length_));
+    expect(Array.from(a.typeID_)).toEqual(Array.from(b.typeID_));
+    expect(Array.from(a.expressID_)).toEqual(Array.from(b.expressID_));
+    const typesA = new Set(a.typeIndex.types());
+    const typesB = new Set(b.typeIndex.types());
+    expect(typesA).toEqual(typesB);
+    for (const type of typesA) {
+        expect(b.typeIndex.count(type)).toBe(a.typeIndex.count(type));
+    }
+}
+describe("columnar index build (M7)", () => {
+    test("IFC: columnar streamed model matches the object-path model", () => {
+        const path = "data/index.ifc";
+        const { bytes, elements } = objectParse(path, IfcStepParser.Instance);
+        const objectModel = new IfcStepModel(bytes, elements);
+        const { columns, result } = buildColumnarIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024);
+        expect(result).toBe(ParseResult.COMPLETE);
+        const columnarModel = new IfcStepModel(bytes, columns);
+        expectModelParity(objectModel, columnarModel);
+        // Behavioural spot checks through the public surface.
+        const roots = new Set(objectModel.expressIDsOfTypes(IfcRoot));
+        expect(new Set(columnarModel.expressIDsOfTypes(IfcRoot))).toEqual(roots);
+        expect(new Set(columnarModel.expressIDsOfTypes(IfcProduct)))
+            .toEqual(new Set(objectModel.expressIDsOfTypes(IfcProduct)));
+        for (const expressID of roots) {
+            expect(columnarModel.getElementByExpressID(expressID)?.expressID)
+                .toBe(objectModel.getElementByExpressID(expressID)?.expressID);
+        }
+    });
+    test.each([
+        ["as1-oc-214.stp"],
+        ["ap214-mapped-item-test.step"],
+        ["ap214-multibody-part.step"],
+    ])("AP214 (inline/multi-mapping): parity on %s", (name) => {
+        const path = `data/${name}`;
+        const { bytes, elements } = objectParse(path, AP214StepParser.Instance);
+        const objectModel = new AP214StepModel(bytes, elements);
+        const { columns, result } = buildColumnarIndexStreaming(new BufferByteSource(bytes), AP214StepParser.Instance, 4 * 1024);
+        expect(result).toBe(ParseResult.COMPLETE);
+        const columnarModel = new AP214StepModel(bytes, columns);
+        // Inline entities must actually be present for these fixtures to prove
+        // the unfold path (guard against a silently trivial test).
+        if (name !== "as1-oc-214.stp") {
+            expect(columnarModel.count_).toBeGreaterThan(columnarModel.firstInlineElement_);
+        }
+        expectModelParity(objectModel, columnarModel);
+    });
+    test("the sink drops simple records but retains complex ones", () => {
+        const sink = new ColumnarIndexSink();
+        sink.pushTopLevel({ address: 0, length: 10, typeID: 5, expressID: 1 });
+        sink.pushTopLevel({
+            address: 10,
+            length: 20,
+            typeID: 0,
+            expressID: 2,
+            multiMapping: [{ address: 12, length: 5, typeID: 7 }],
+        });
+        const columns = sink.finalize();
+        expect(columns.firstInlineElement).toBe(2);
+        expect(columns.count).toBe(2);
+        expect(columns.complexEntries?.size).toBe(1);
+        expect(columns.complexEntries?.get(1)?.multiMapping?.[0].typeID).toBe(7);
+        expect(Array.from(columns.typeID)).toEqual([5, 0]);
+    });
+    test("inline entities unfold in the model object-walk order", () => {
+        const sink = new ColumnarIndexSink();
+        // Two parents with children; first parent's child itself has a child.
+        // Object-path order: parents (0,1), then first-level children in parent
+        // order (2 = p0c, 3 = p1c), then second-level (4 = p0c's child).
+        sink.pushTopLevel({
+            address: 0,
+            length: 10,
+            typeID: 1,
+            expressID: 1,
+            inlineEntities: [{
+                    address: 2,
+                    length: 3,
+                    typeID: 10,
+                    inlineEntities: [{ address: 3, length: 1, typeID: 20 }],
+                }],
+        });
+        sink.pushTopLevel({
+            address: 10,
+            length: 10,
+            typeID: 2,
+            expressID: 2,
+            inlineEntities: [{ address: 12, length: 3, typeID: 11 }],
+        });
+        const columns = sink.finalize();
+        expect(columns.firstInlineElement).toBe(2);
+        expect(columns.count).toBe(5);
+        expect(Array.from(columns.typeID)).toEqual([1, 2, 10, 11, 20]);
+        expect(Array.from(columns.address)).toEqual([0, 10, 2, 12, 3]);
+    });
+    test("reset rewinds for the grow-and-restart", () => {
+        const sink = new ColumnarIndexSink();
+        sink.pushTopLevel({ address: 0, length: 1, typeID: 1, expressID: 9 });
+        sink.reset();
+        sink.pushTopLevel({ address: 5, length: 2, typeID: 3, expressID: 1 });
+        const columns = sink.finalize();
+        expect(columns.count).toBe(1);
+        expect(Array.from(columns.address)).toEqual([5]);
+        expect(columns.expressIdsSorted).toBe(true);
+    });
+    test("detects unsorted express IDs", () => {
+        const sink = new ColumnarIndexSink();
+        sink.pushTopLevel({ address: 0, length: 1, typeID: 1, expressID: 10 });
+        sink.pushTopLevel({ address: 1, length: 1, typeID: 1, expressID: 5 });
+        expect(sink.finalize().expressIdsSorted).toBe(false);
+    });
+});

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

@@ -0,0 +1,95 @@
+import { EntityAddress } from "../../core/model_uri.js";
+import { RecordHandler } from "./streaming_record_dispatcher.js";
+/**
+ * Reads the `Location` string of a cross-reference entity by express ID.
+ * Implemented over the finished (or partially materialised) model — a thin
+ * seam so the registry's link resolution is testable without a full model.
+ * `IfcExternalReference.Location` is the canonical field; STEP AP242's external
+ * references expose their location the same way.
+ */
+export interface ReferenceLocationReader {
+    /**
+     * @param expressID The cross-reference entity's express ID.
+     * @return {string | null | undefined} Its `Location`, or null/undefined when
+     * absent.
+     */
+    locationOf(expressID: number): string | null | undefined;
+}
+/**
+ * An outbound federation link discovered from a cross-reference: the
+ * referencing entity in this model, the raw location it declared, and — once
+ * resolved against the model's own URI — the absolute URI (and, if the
+ * location carried a `#expressID` fragment, the entity address) it points at.
+ */
+export interface CrossReferenceLink {
+    /** Express ID of the referencing entity in the source model. */
+    fromExpressID: number;
+    /** The raw `Location` string as authored in the file. */
+    location: string;
+    /** The location resolved to an absolute URI against the source model URI. */
+    targetURI: string;
+    /** The target entity address, when the location carried a `#expressID`. */
+    targetEntity?: EntityAddress;
+}
+/**
+ * Collects a model's **outbound cross-model references** during the streaming
+ * parse and, once locations are readable, resolves them into navigable
+ * federation links (M5 / design S3).
+ *
+ * The links come from IFC's own reference entities — `IfcExternalReference`
+ * and its subtypes (`IfcDocumentReference`, `IfcClassificationReference`,
+ * `IfcLibraryReference`) — and, for STEP AP242, its external references. Two
+ * phases, matching M2's "identify while parsing, resolve on demand":
+ *
+ *  1. **Identify** — subscribe {@link handler} to a
+ *     {@link StreamingRecordDispatcher} for the reference types
+ *     (`dispatcher.on([IfcExternalReference], reg.handler)`); it records the
+ *     express ID of every such record as it streams past. Cheap and idempotent
+ *     (a `Set`), so the rare grow-restart is harmless.
+ *  2. **Resolve** — after parse, {@link resolve} reads each reference's
+ *     `Location` via a {@link ReferenceLocationReader} and resolves it against
+ *     the source model URI, yielding {@link CrossReferenceLink}s the UI renders
+ *     as links. Visiting one opens the target model in the `ModelRegistry`.
+ *
+ * The location read is deferred because the event stream carries only
+ * `(localID, expressID, typeID)` — not attribute strings; pulling `Location`
+ * needs the entity's fields, which is a model read, not a parse event.
+ */
+export declare class CrossReferenceRegistry<TypeIDType extends number> {
+    private readonly sourceURI_;
+    private readonly fromExpressIDs_;
+    /**
+     * @param sourceURI_ The URI of the model these references were found in —
+     * the base for resolving relative locations.
+     */
+    constructor(sourceURI_: string);
+    /**
+     * Record one cross-reference entity. Bind to a dispatcher subscription
+     * filtered to the reference types; every record it is handed is taken to be
+     * a cross-reference (the dispatcher does the type filtering).
+     *
+     * @param localID Unused (kept for the RecordHandler shape).
+     * @param expressID The reference entity's express ID.
+     * @param typeID Unused (the dispatcher already matched the type set).
+     */
+    readonly handler: RecordHandler<TypeIDType>;
+    /**
+     * @return {number} The number of cross-references collected.
+     */
+    get count(): number;
+    /**
+     * @return {IterableIterator<number>} The express IDs of the collected
+     * reference entities.
+     */
+    expressIDs(): IterableIterator<number>;
+    /**
+     * Resolve the collected references into navigable links by reading each
+     * one's `Location` and resolving it against the source model URI. References
+     * whose location is absent (null / empty) are skipped — they carry no link.
+     *
+     * @param reader Reads the `Location` of an express ID.
+     * @return {CrossReferenceLink[]} The resolved outbound links.
+     */
+    resolve(reader: ReferenceLocationReader): CrossReferenceLink[];
+}
+//# sourceMappingURL=cross_reference_registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cross_reference_registry.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/cross_reference_registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,sBAAsB,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAG7D;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IAEtC;;;;OAIG;IACH,UAAU,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC3D;AAGD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAEjC,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAA;IAErB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAEhB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAA;IAEjB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,aAAa,CAAA;CAC7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,sBAAsB,CAAC,UAAU,SAAS,MAAM;IAQ9C,OAAO,CAAC,QAAQ,CAAC,UAAU;IANxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IAEpD;;;OAGG;gBAC2B,UAAU,EAAE,MAAM;IAEhD;;;;;;;;OAQG;IACH,SAAgB,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAG/C;IAEH;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACI,UAAU,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAI7C;;;;;;;OAOG;IACI,OAAO,CAAE,MAAM,EAAE,uBAAuB,GAAI,kBAAkB,EAAE;CA8BxE"}

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

@@ -0,0 +1,91 @@
+import { resolveReference } from "../../core/model_uri.js";
+const FRAGMENT = "#";
+const RADIX = 10;
+/**
+ * Collects a model's **outbound cross-model references** during the streaming
+ * parse and, once locations are readable, resolves them into navigable
+ * federation links (M5 / design S3).
+ *
+ * The links come from IFC's own reference entities — `IfcExternalReference`
+ * and its subtypes (`IfcDocumentReference`, `IfcClassificationReference`,
+ * `IfcLibraryReference`) — and, for STEP AP242, its external references. Two
+ * phases, matching M2's "identify while parsing, resolve on demand":
+ *
+ *  1. **Identify** — subscribe {@link handler} to a
+ *     {@link StreamingRecordDispatcher} for the reference types
+ *     (`dispatcher.on([IfcExternalReference], reg.handler)`); it records the
+ *     express ID of every such record as it streams past. Cheap and idempotent
+ *     (a `Set`), so the rare grow-restart is harmless.
+ *  2. **Resolve** — after parse, {@link resolve} reads each reference's
+ *     `Location` via a {@link ReferenceLocationReader} and resolves it against
+ *     the source model URI, yielding {@link CrossReferenceLink}s the UI renders
+ *     as links. Visiting one opens the target model in the `ModelRegistry`.
+ *
+ * The location read is deferred because the event stream carries only
+ * `(localID, expressID, typeID)` — not attribute strings; pulling `Location`
+ * needs the entity's fields, which is a model read, not a parse event.
+ */
+export class CrossReferenceRegistry {
+    /**
+     * @param sourceURI_ The URI of the model these references were found in —
+     * the base for resolving relative locations.
+     */
+    constructor(sourceURI_) {
+        this.sourceURI_ = sourceURI_;
+        this.fromExpressIDs_ = new Set();
+        /**
+         * Record one cross-reference entity. Bind to a dispatcher subscription
+         * filtered to the reference types; every record it is handed is taken to be
+         * a cross-reference (the dispatcher does the type filtering).
+         *
+         * @param localID Unused (kept for the RecordHandler shape).
+         * @param expressID The reference entity's express ID.
+         * @param typeID Unused (the dispatcher already matched the type set).
+         */
+        this.handler = (localID, expressID, typeID) => {
+            this.fromExpressIDs_.add(expressID);
+        };
+    }
+    /**
+     * @return {number} The number of cross-references collected.
+     */
+    get count() {
+        return this.fromExpressIDs_.size;
+    }
+    /**
+     * @return {IterableIterator<number>} The express IDs of the collected
+     * reference entities.
+     */
+    expressIDs() {
+        return this.fromExpressIDs_.keys();
+    }
+    /**
+     * Resolve the collected references into navigable links by reading each
+     * one's `Location` and resolving it against the source model URI. References
+     * whose location is absent (null / empty) are skipped — they carry no link.
+     *
+     * @param reader Reads the `Location` of an express ID.
+     * @return {CrossReferenceLink[]} The resolved outbound links.
+     */
+    resolve(reader) {
+        const links = [];
+        for (const fromExpressID of this.fromExpressIDs_) {
+            const location = reader.locationOf(fromExpressID);
+            if (location === null || location === void 0 || location.length === 0) {
+                continue;
+            }
+            const resolved = resolveReference(this.sourceURI_, location);
+            const link = { fromExpressID, location, targetURI: resolved };
+            // A location may itself address a specific entity (model.ifc#42).
+            const hash = resolved.lastIndexOf(FRAGMENT);
+            if (hash >= 0 && /^\d+$/.test(resolved.slice(hash + 1))) {
+                link.targetEntity = {
+                    modelURI: resolved.slice(0, hash),
+                    expressID: parseInt(resolved.slice(hash + 1), RADIX),
+                };
+            }
+            links.push(link);
+        }
+        return links;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,66 @@
+/* eslint-disable no-magic-numbers */
+// M5: outbound cross-model references are collected during the parse (by type,
+// via the dispatcher) and resolved to navigable federation links against the
+// source model URI once their Location strings are readable.
+import { describe, expect, test } from "@jest/globals";
+import { CrossReferenceRegistry, } from "./cross_reference_registry.js";
+import { StreamingRecordDispatcher } from "./streaming_record_dispatcher.js";
+import { IfcExternalReference } from "../../ifc/ifc4_gen/index.js";
+/**
+ * A mock reader over a fixed express-ID → Location map.
+ *
+ * @param locations The express-ID → Location map.
+ * @return {ReferenceLocationReader} The reader.
+ */
+function reader(locations) {
+    return { locationOf: (expressID) => locations[expressID] };
+}
+describe("CrossReferenceRegistry", () => {
+    test("collects references handed to its handler and resolves them", () => {
+        const registry = new CrossReferenceRegistry("https://ex.com/site/plan.ifc");
+        // Simulate the dispatcher delivering three reference records.
+        registry.handler(0, 100, 1);
+        registry.handler(1, 200, 1);
+        registry.handler(2, 300, 1);
+        expect(registry.count).toBe(3);
+        const links = registry.resolve(reader({
+            100: "../shared/grid.ifc",
+            200: "https://other.org/lib.ifc",
+            300: "wing-A.ifc#4022",
+        }));
+        const byFrom = new Map(links.map((l) => [l.fromExpressID, l]));
+        expect(byFrom.get(100)?.targetURI).toBe("https://ex.com/shared/grid.ifc");
+        expect(byFrom.get(200)?.targetURI).toBe("https://other.org/lib.ifc");
+        // A location with a #expressID resolves to a full entity address.
+        const wing = byFrom.get(300);
+        expect(wing?.targetURI).toBe("https://ex.com/site/wing-A.ifc#4022");
+        expect(wing?.targetEntity).toEqual({
+            modelURI: "https://ex.com/site/wing-A.ifc",
+            expressID: 4022,
+        });
+    });
+    test("skips references with no location", () => {
+        const registry = new CrossReferenceRegistry("base.ifc");
+        registry.handler(0, 1, 1);
+        registry.handler(1, 2, 1);
+        const links = registry.resolve(reader({ 1: null, 2: "" }));
+        expect(links).toEqual([]);
+    });
+    test("is idempotent under the streaming grow-restart (dedupes express IDs)", () => {
+        const registry = new CrossReferenceRegistry("base.ifc");
+        registry.handler(0, 42, 1);
+        registry.handler(0, 42, 1); // re-fire from localID 0 after a restart
+        expect(registry.count).toBe(1);
+    });
+    test("wires to the dispatcher, collecting only the reference types", () => {
+        const registry = new CrossReferenceRegistry("base.ifc");
+        const dispatcher = new StreamingRecordDispatcher();
+        dispatcher.on([IfcExternalReference], registry.handler);
+        // One record of a matching (subtype-closure) type, one outside it.
+        const matching = IfcExternalReference.query[0];
+        const nonMatching = 10000000; // not in the reference closure
+        dispatcher.onRecordIndexed(0, 500, matching);
+        dispatcher.onRecordIndexed(1, 600, nonMatching);
+        expect([...registry.expressIDs()]).toEqual([500]);
+    });
+});

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

@@ -27,6 +27,21 @@
  * @return The decoded string.
  */
 export declare function decodeUtf8(view: Uint8Array): string;
+/**
+ * Decode the raw byte run of a STEP string literal.
+ *
+ * ISO 10303-21 says raw (non-\X\-escaped) bytes are ISO 8859-1, but modern
+ * exporters routinely write UTF-8 (and some, like Onshape's ST-Developer,
+ * write outright invalid sequences). The lenient default decoder mapped every
+ * non-UTF-8 byte to U+FFFD, so a spec-conformant latin-1 'Küche' surfaced as
+ * 'K�che' in product names and titles. Decode as strict UTF-8 first (the
+ * common modern case, and unambiguous when it validates), and fall back to
+ * exact ISO 8859-1 (byte = code point, which cannot fail) when it doesn't.
+ *
+ * @param view The bytes of the string literal's raw run.
+ * @return The decoded string.
+ */
+export declare function decodeStepString(view: Uint8Array): string;
 /**
  * Install a global, idempotent `TextDecoder.prototype.decode` shim that copies a
  * view out of a resizable/growable buffer before decoding. This covers decodes