@bldrs-ai/conway 1.403.1239 → 1.405.1243

package/compiled/src/core/model_uri.js

@@ -0,0 +1,101 @@
+/**
+ * Cross-model entity addressing (M5 / design S3).
+ *
+ * Federation turns "thousands of cross-referenced files" from a loader problem
+ * into an addressing problem: every entity has a **universal address** of a
+ * model URI plus an express ID — `https://…/part-B.ifc#4022`. The engine never
+ * holds all the files; it holds a registry of models keyed by URI (see
+ * {@link ModelRegistry}) and resolves an address to a (model, expressID) pair
+ * on demand, opening a sibling loader for a URI it hasn't seen.
+ *
+ * The URI is opaque to the engine except for its `#expressID` fragment: the
+ * scheme, host, path and any version identity live entirely in the model URI,
+ * so "many versions side by side" is expressible without an engine change.
+ */
+const FRAGMENT = '#';
+const RADIX = 10;
+/**
+ * Format a model URI + express ID as a single entity address URI.
+ *
+ * @param modelURI The model URI (must not itself contain a `#`).
+ * @param expressID The express ID (a non-negative integer).
+ * @return {string} The `modelURI#expressID` address.
+ */
+export function formatEntityAddress(modelURI, expressID) {
+    if (modelURI.includes(FRAGMENT)) {
+        throw new Error(`Model URI must not contain '#': ${modelURI}`);
+    }
+    if (!Number.isInteger(expressID) || expressID < 0) {
+        throw new Error(`Invalid express ID ${expressID}`);
+    }
+    return `${modelURI}${FRAGMENT}${expressID}`;
+}
+/**
+ * Parse an entity address URI into its model URI and express ID.
+ *
+ * The split is on the **last** `#`, so a fragment is required; the model URI
+ * is everything before it. A missing or non-integer fragment is an error —
+ * an address without an express ID isn't an entity address.
+ *
+ * @param uri The `modelURI#expressID` address.
+ * @return {EntityAddress} The parsed address.
+ */
+export function parseEntityAddress(uri) {
+    const hash = uri.lastIndexOf(FRAGMENT);
+    if (hash < 0) {
+        throw new Error(`Entity address has no '#expressID' fragment: ${uri}`);
+    }
+    const modelURI = uri.slice(0, hash);
+    const fragment = uri.slice(hash + 1);
+    if (fragment.length === 0 || !/^\d+$/.test(fragment)) {
+        throw new Error(`Entity address fragment is not an express ID: ${uri}`);
+    }
+    return { modelURI, expressID: parseInt(fragment, RADIX) };
+}
+/**
+ * Resolve a (possibly relative) reference URI against a base model URI, so an
+ * `IfcExternalReference.Location` like `../shared/grid.ifc` becomes an absolute
+ * model URI addressable in the registry. Absolute references (with a scheme,
+ * or protocol-relative) pass through unchanged.
+ *
+ * Uses the standard URL resolver when the base is absolute; falls back to a
+ * plain path join when the base has no scheme (e.g. a bare filename in tests).
+ *
+ * @param base The base model URI the reference was found in.
+ * @param reference The reference URI (absolute or relative).
+ * @return {string} The resolved absolute reference URI.
+ */
+export function resolveReference(base, reference) {
+    // Already absolute (has a scheme like `https:` or is protocol-relative).
+    if (/^[a-z][a-z0-9+.-]*:/i.test(reference) || reference.startsWith('//')) {
+        return reference;
+    }
+    try {
+        return new URL(reference, base).toString();
+    }
+    catch {
+        // Base isn't a valid absolute URL (bare filename): join paths manually.
+        const slash = base.lastIndexOf('/');
+        const dir = slash < 0 ? '' : base.slice(0, slash + 1);
+        return normalizePath(dir + reference);
+    }
+}
+/**
+ * Collapse `.` / `..` segments in a slash-joined path (used only for the
+ * scheme-less fallback in {@link resolveReference}).
+ *
+ * @param path The path to normalise.
+ * @return {string} The normalised path.
+ */
+function normalizePath(path) {
+    const out = [];
+    for (const segment of path.split('/')) {
+        if (segment === '..') {
+            out.pop();
+        }
+        else if (segment !== '.') {
+            out.push(segment);
+        }
+    }
+    return out.join('/');
+}

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

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

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

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

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

@@ -0,0 +1,49 @@
+/* eslint-disable no-magic-numbers */
+// M5: universal entity addressing — a model URI plus an express-ID fragment —
+// must round-trip and resolve relative references the way IFC external-ref
+// locations demand.
+import { describe, expect, test } from "@jest/globals";
+import { formatEntityAddress, parseEntityAddress, resolveReference, } from "./model_uri.js";
+describe("model URI addressing", () => {
+    test("formats and parses an entity address round-trip", () => {
+        const uri = formatEntityAddress("https://ex.com/part-B.ifc", 4022);
+        expect(uri).toBe("https://ex.com/part-B.ifc#4022");
+        const parsed = parseEntityAddress(uri);
+        expect(parsed.modelURI).toBe("https://ex.com/part-B.ifc");
+        expect(parsed.expressID).toBe(4022);
+    });
+    test("splits on the last # so the model URI keeps earlier structure", () => {
+        // (Model URIs shouldn't carry a '#', but parsing must be unambiguous.)
+        const parsed = parseEntityAddress("scheme://h/a#b#42");
+        expect(parsed.modelURI).toBe("scheme://h/a#b");
+        expect(parsed.expressID).toBe(42);
+    });
+    test("rejects formatting a model URI that contains #", () => {
+        expect(() => formatEntityAddress("a#b", 1)).toThrow(/#/);
+    });
+    test("rejects formatting a non-integer or negative express ID", () => {
+        expect(() => formatEntityAddress("a", 1.5)).toThrow();
+        expect(() => formatEntityAddress("a", -1)).toThrow();
+    });
+    test("rejects an address with no fragment or a non-numeric fragment", () => {
+        expect(() => parseEntityAddress("a.ifc")).toThrow(/fragment/);
+        expect(() => parseEntityAddress("a.ifc#")).toThrow(/express ID/);
+        expect(() => parseEntityAddress("a.ifc#x")).toThrow(/express ID/);
+    });
+    test("resolves a relative reference against an absolute base URI", () => {
+        expect(resolveReference("https://ex.com/site/plan.ifc", "../shared/grid.ifc"))
+            .toBe("https://ex.com/shared/grid.ifc");
+        expect(resolveReference("https://ex.com/site/plan.ifc", "wing-A.ifc"))
+            .toBe("https://ex.com/site/wing-A.ifc");
+    });
+    test("passes an already-absolute reference through unchanged", () => {
+        expect(resolveReference("https://ex.com/a.ifc", "https://other.org/b.ifc"))
+            .toBe("https://other.org/b.ifc");
+    });
+    test("resolves relative references against a scheme-less base", () => {
+        expect(resolveReference("project/plan.ifc", "wing-A.ifc"))
+            .toBe("project/wing-A.ifc");
+        expect(resolveReference("project/site/plan.ifc", "../grid.ifc"))
+            .toBe("project/grid.ifc");
+    });
+});

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

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

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

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

package/compiled/src/core/shared_byte_budget.js

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

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

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

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

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

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

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

package/compiled/src/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]);
+    });
+});