@bldrs-ai/conway 1.536.1507 → 1.543.1513

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

@@ -13,11 +13,14 @@
  *
  *   Model: Arty_Z7.stp — AP214, 38.1 MB, SolidWorks 2021 (SwSTEP 2.0)
  *   Parsing [0%................100%] 3.2s, +210 MB heap
+ *   Preview: first mesh 0.275s, 539 emitted, 12 deferred (11 on placements), 8 retried
  *   Geometry [0%........56%] 41.0s, +388 MB heap
  *   Total: 44.7s, 512 → 1110 MB heap
  *
  * Stage lines own only their deltas (duration, heap growth); Total is not
  * additive — it is a separate before/after wall-clock + heap observation.
+ * The Preview line is not a stage either — it reports what the parse-time
+ * preview delivered while Parsing ran (see {@link formatPreviewLine}).
  */
 /** What a header parse can tell us before the full file parse (issue #301). */
 export interface ModelInfo {
@@ -79,6 +82,62 @@ export declare function formatMb(megabytes: number): string;
  * SolidWorks 2021 (SwSTEP 2.0)"
  */
 export declare function formatModelLine(info: ModelInfo): string;
+/**
+ * What a parse-time preview channel delivered — structurally typed against
+ * both channels' `previewYield` (compat/web-ifc/{store,streamed}_preview_
+ * channel.ts) so this module stays import-free.
+ */
+export interface PreviewYieldLike {
+    /**
+     * Ms from the channel starting to the first mesh handed to the consumer;
+     * undefined when it never emitted one.
+     */
+    firstMeshMs?: number;
+    /**
+     * Preview meshes actually handed to the consumer. Distinct from
+     * {@link emitted}: one unit can yield several meshes, and a unit with no
+     * representation yields none at all, so reporting only units produced the
+     * self-contradicting "no mesh, 20 emitted" (codex round 2 on #543).
+     */
+    meshes: number;
+    /**
+     * Units the preview EXTRACTED — attempted and got a non-throwing answer
+     * from. Not a count of what reached the screen; that is
+     * {@link meshes}. This is the counter the channel's `maxUnits` cap
+     * measures, which is why it stays unit-shaped.
+     */
+    emitted: number;
+    deferred: number;
+    deferredOnPlacement: number;
+    retried: number;
+}
+/**
+ * The preview line: time-to-first-pixel, and why the preview delivered what
+ * it did.
+ *
+ * First pixels are the number that decides whether a first-time visitor
+ * sees their building or a blank canvas, and until conway#542 it was
+ * judged by eye — measurable only in a Node harness nobody runs in
+ * production. The deferral split is what makes a blank first load
+ * attributable rather than merely observed: a ratio near 1.0 ON PLACEMENTS
+ * is the file-layout case (an exporter that writes the leaf points and
+ * directions a product's placement chain bottoms out in toward the tail of
+ * the file), and anything else is a different problem wearing the same
+ * blank screen. `retried` is the second-look count — a retry path that has
+ * silently stopped firing shows up here rather than merely as a slower
+ * load.
+ *
+ * Meshes and units are reported separately because they diverge in both
+ * directions: one unit can place several meshes, and a unit with no
+ * representation (a site, a storey) extracts cleanly while placing none.
+ * Folding them into one "emitted" number let the line say "no mesh, 20
+ * emitted" about the same load (codex round 2 on #543).
+ *
+ * @param preview The channel's reported yield.
+ * @return {string} e.g. "Preview: first mesh 0.275s, 1750 meshes from 539
+ * units, 12 deferred (11 on placements), 8 retried"
+ */
+export declare function formatPreviewLine(preview: PreviewYieldLike): string;
 /**
  * Accumulates progress events into the normalized text report: a live
  * current-stage line while a stage runs, a frozen line per finished stage,
@@ -96,6 +155,7 @@ export declare class LoadLogAccumulator {
     private firstHeapMb_;
     private lastHeapMb_;
     private modelLine_;
+    private previewLine_;
     /**
      * Record the model line (from header info) — kept with the report.
      *
@@ -103,6 +163,18 @@ export declare class LoadLogAccumulator {
      * @return {string} The formatted model line.
      */
     setModelInfo(info: ModelInfo): string;
+    /**
+     * Record what the parse-time preview delivered — kept with the report
+     * and rendered between the stage lines and Total.
+     *
+     * Not a stage: the preview runs *inside* Parsing, so feeding it through
+     * onProgress would close the Parsing stage and reopen it, splitting one
+     * parse across two lines.
+     *
+     * @param preview The channel's reported yield.
+     * @return {string} The formatted preview line.
+     */
+    setPreviewStats(preview: PreviewYieldLike): string;
     /**
      * Feed one progress event; returns the finished stage's line when this
      * event closed a stage (so callers can mirror it to a console/log once).
@@ -141,8 +213,9 @@ export declare class LoadLogAccumulator {
      */
     totalLine(): string;
     /**
-     * The full report: model line (if known), finished stage lines, then the
-     * Total line. Call closeCurrentStage() first at load end.
+     * The full report: model line (if known), finished stage lines, the
+     * preview line (if reported), then the Total line. Call
+     * closeCurrentStage() first at load end.
      *
      * @return {string[]} All report lines.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"progress_log.d.ts","sourceRoot":"","sources":["../../../src/core/progress_log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM,CAQlD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAE,OAAO,CAAC,EAAE,MAAM,GAAI,MAAM,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAE,YAAY,EAAE,MAAM,GAAI,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM,CA0BzD;AA6DD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;;OAKG;IACI,YAAY,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM;IAM9C;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,iBAAiB,GAAI,MAAM,GAAG,SAAS;IAiDjE;;;;;;;;OAQG;IACI,iBAAiB,CAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAI,MAAM,GAAG,SAAS;IAuBzF;;;;OAIG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;IAQxC;;;;OAIG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAY1B;;;;;OAKG;IACI,QAAQ,IAAI,MAAM,EAAE;CAY5B"}
+{"version":3,"file":"progress_log.d.ts","sourceRoot":"","sources":["../../../src/core/progress_log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,KAAK,EAAE,MAAM,GAAI,MAAM,CAQlD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAE,OAAO,CAAC,EAAE,MAAM,GAAI,MAAM,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAE,YAAY,EAAE,MAAM,GAAI,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM,CA0BzD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAE,OAAO,EAAE,gBAAgB,GAAI,MAAM,CAUrE;AA6DD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,YAAY,CAAoB;IAExC;;;;;OAKG;IACI,YAAY,CAAE,IAAI,EAAE,SAAS,GAAI,MAAM;IAM9C;;;;;;;;;;OAUG;IACI,eAAe,CAAE,OAAO,EAAE,gBAAgB,GAAI,MAAM;IAM3D;;;;;;OAMG;IACI,UAAU,CAAE,KAAK,EAAE,iBAAiB,GAAI,MAAM,GAAG,SAAS;IAiDjE;;;;;;;;OAQG;IACI,iBAAiB,CAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAI,MAAM,GAAG,SAAS;IAuBzF;;;;OAIG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;IAQxC;;;;OAIG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;OAKG;IACI,SAAS,IAAI,MAAM;IAY1B;;;;;;OAMG;IACI,QAAQ,IAAI,MAAM,EAAE;CAiB5B"}

package/compiled/src/core/progress_log.js

@@ -13,11 +13,14 @@
  *
  *   Model: Arty_Z7.stp — AP214, 38.1 MB, SolidWorks 2021 (SwSTEP 2.0)
  *   Parsing [0%................100%] 3.2s, +210 MB heap
+ *   Preview: first mesh 0.275s, 539 emitted, 12 deferred (11 on placements), 8 retried
  *   Geometry [0%........56%] 41.0s, +388 MB heap
  *   Total: 44.7s, 512 → 1110 MB heap
  *
  * Stage lines own only their deltas (duration, heap growth); Total is not
  * additive — it is a separate before/after wall-clock + heap observation.
+ * The Preview line is not a stage either — it reports what the parse-time
+ * preview delivered while Parsing ran (see {@link formatPreviewLine}).
  */
 /** Display labels for the phase taxonomy; unknown phases title-case as-is. */
 const STAGE_LABELS = {
@@ -112,6 +115,41 @@ export function formatModelLine(info) {
     const detail = parts.length > 0 ? ` — ${parts.join(', ')}` : '';
     return `Model: ${name}${detail}`;
 }
+/**
+ * The preview line: time-to-first-pixel, and why the preview delivered what
+ * it did.
+ *
+ * First pixels are the number that decides whether a first-time visitor
+ * sees their building or a blank canvas, and until conway#542 it was
+ * judged by eye — measurable only in a Node harness nobody runs in
+ * production. The deferral split is what makes a blank first load
+ * attributable rather than merely observed: a ratio near 1.0 ON PLACEMENTS
+ * is the file-layout case (an exporter that writes the leaf points and
+ * directions a product's placement chain bottoms out in toward the tail of
+ * the file), and anything else is a different problem wearing the same
+ * blank screen. `retried` is the second-look count — a retry path that has
+ * silently stopped firing shows up here rather than merely as a slower
+ * load.
+ *
+ * Meshes and units are reported separately because they diverge in both
+ * directions: one unit can place several meshes, and a unit with no
+ * representation (a site, a storey) extracts cleanly while placing none.
+ * Folding them into one "emitted" number let the line say "no mesh, 20
+ * emitted" about the same load (codex round 2 on #543).
+ *
+ * @param preview The channel's reported yield.
+ * @return {string} e.g. "Preview: first mesh 0.275s, 1750 meshes from 539
+ * units, 12 deferred (11 on placements), 8 retried"
+ */
+export function formatPreviewLine(preview) {
+    const first = preview.firstMeshMs !== void 0 ?
+        `first mesh ${formatSeconds(preview.firstMeshMs)}` : 'no mesh';
+    return `Preview: ${first}, ${preview.meshes} meshes ` +
+        `from ${preview.emitted} units, ` +
+        `${preview.deferred} deferred ` +
+        `(${preview.deferredOnPlacement} on placements), ` +
+        `${preview.retried} retried`;
+}
 /**
  * The signed heap-delta suffix for a stage, byte precision, e.g.
  * ", +663.000000 MB heap" — empty when memory wasn't sampled.
@@ -178,6 +216,21 @@ export class LoadLogAccumulator {
         this.modelLine_ = formatModelLine(info);
         return this.modelLine_;
     }
+    /**
+     * Record what the parse-time preview delivered — kept with the report
+     * and rendered between the stage lines and Total.
+     *
+     * Not a stage: the preview runs *inside* Parsing, so feeding it through
+     * onProgress would close the Parsing stage and reopen it, splitting one
+     * parse across two lines.
+     *
+     * @param preview The channel's reported yield.
+     * @return {string} The formatted preview line.
+     */
+    setPreviewStats(preview) {
+        this.previewLine_ = formatPreviewLine(preview);
+        return this.previewLine_;
+    }
     /**
      * Feed one progress event; returns the finished stage's line when this
      * event closed a stage (so callers can mirror it to a console/log once).
@@ -281,8 +334,9 @@ export class LoadLogAccumulator {
         return `Total: ${formatSeconds(duration)}${heap}`;
     }
     /**
-     * The full report: model line (if known), finished stage lines, then the
-     * Total line. Call closeCurrentStage() first at load end.
+     * The full report: model line (if known), finished stage lines, the
+     * preview line (if reported), then the Total line. Call
+     * closeCurrentStage() first at load end.
      *
      * @return {string[]} All report lines.
      */
@@ -292,6 +346,9 @@ export class LoadLogAccumulator {
             lines.push(this.modelLine_);
         }
         lines.push(...this.finished_);
+        if (this.previewLine_ !== void 0) {
+            lines.push(this.previewLine_);
+        }
         lines.push(this.totalLine());
         return lines;
     }

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "@jest/globals";
-import { LoadLogAccumulator, formatBar, formatMb, formatModelLine, formatSeconds, stageLabel, } from "./progress_log.js";
+import { LoadLogAccumulator, formatBar, formatMb, formatModelLine, formatPreviewLine, formatSeconds, stageLabel, } from "./progress_log.js";
 const HALF_PERCENT = 56;
 const HALF_DOTS = 9;
 const SAMPLE_MS = 3210;
@@ -108,3 +108,77 @@ describe("LoadLogAccumulator", () => {
         expect(log.totalLine()).toBe("Total: 12.400s");
     });
 });
+describe("formatPreviewLine", () => {
+    test("reports time-to-first-pixel and the deferral split", () => {
+        expect(formatPreviewLine({
+            firstMeshMs: 275,
+            meshes: 1750,
+            emitted: 539,
+            deferred: 12,
+            deferredOnPlacement: 11,
+            retried: 8,
+        })).toBe("Preview: first mesh 0.275s, 1750 meshes from 539 units, " +
+            "12 deferred (11 on placements), 8 retried");
+    });
+    test("separates meshes delivered from units extracted", () => {
+        // Codex round 2 on #543. `emitted` counts units extraction ACCEPTED,
+        // and a unit that extracts cleanly can still place nothing: an IfcSite
+        // or IfcBuildingStorey has no Representation, so
+        // extractProductGeometry returns early while
+        // extractProductGeometryByLocalID still answers true. Folded into one
+        // number, the line contradicted itself -- "no mesh, 20 emitted" -- so
+        // meshes and units are reported separately and the mesh count is what
+        // firstMeshMs is consistent with.
+        expect(formatPreviewLine({
+            meshes: 0,
+            emitted: 20,
+            deferred: 0,
+            deferredOnPlacement: 0,
+            retried: 0,
+        })).toBe("Preview: no mesh, 0 meshes from 20 units, " +
+            "0 deferred (0 on placements), 0 retried");
+    });
+    test("says so when the preview never emitted a mesh", () => {
+        // The load this line exists for: 532 attempts, one mesh's worth of
+        // nothing, and a deferral ratio of 1.0 on placements is what names the
+        // cause as file layout rather than "the preview is slow" (conway#542).
+        expect(formatPreviewLine({
+            meshes: 0,
+            emitted: 0,
+            deferred: 532,
+            deferredOnPlacement: 531,
+            retried: 0,
+        })).toBe("Preview: no mesh, 0 meshes from 0 units, " +
+            "532 deferred (531 on placements), 0 retried");
+    });
+});
+describe("LoadLogAccumulator preview line", () => {
+    test("renders between the stage lines and Total, and only when set", () => {
+        const log = new LoadLogAccumulator();
+        log.onProgress({ phase: "dataParse", completed: 0, elapsedMs: 0 });
+        log.onProgress({ phase: "dataParse", completed: 1, total: 1, elapsedMs: 1000 });
+        log.closeCurrentStage();
+        expect(log.allLines()).toEqual([
+            "Parsing: 1.000s",
+            "Total: 1.000s",
+        ]);
+        log.setPreviewStats({
+            firstMeshMs: 275,
+            meshes: 6,
+            emitted: 4,
+            deferred: 0,
+            deferredOnPlacement: 0,
+            retried: 0,
+        });
+        // The preview runs INSIDE Parsing, so it is not a stage — feeding it
+        // through onProgress would close Parsing and reopen it, splitting one
+        // parse across two lines.
+        expect(log.allLines()).toEqual([
+            "Parsing: 1.000s",
+            "Preview: first mesh 0.275s, 6 meshes from 4 units, " +
+                "0 deferred (0 on placements), 0 retried",
+            "Total: 1.000s",
+        ]);
+        expect(log.finishedLines()).toEqual(["Parsing: 1.000s"]);
+    });
+});

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

@@ -0,0 +1,35 @@
+/**
+ * A product whose placement chain is not in the scanned prefix yet.
+ *
+ * Thrown by `extractPlacementStrict_` under `deferDanglingPlacements`, and
+ * caught by the parse-time preview channels, which treat it — like any throw
+ * from a product extract — as "not yet extractable, leave it to the durable
+ * pump".
+ *
+ * Strictly "not in the prefix YET": the tag is applied only when the
+ * underlying throw is a `DanglingReferenceError`, i.e. the placement chain
+ * referenced a record the index does not hold. A placement that is present
+ * but broken (wrong entity type, a select that is not an axis placement)
+ * propagates untagged, because the channels use this tag to decide what to
+ * retry, and retrying a permanently broken placement also keeps the early
+ * generation-preemption trigger alive for nothing.
+ *
+ * It exists only so that catch can ATTRIBUTE the deferral. The preview emits
+ * a product once its whole closure sits inside the prefix, and Revit writes
+ * per-product placements toward the file tail, so on those files early ticks
+ * meet long runs of products that all defer and the user sees nothing until
+ * the parse is nearly done. Whether a given blank preview is that, or
+ * something else entirely, decides whether sharding the parse would help it
+ * at all — so the distinction has to be measurable rather than inferred from
+ * a comment (conway#542).
+ */
+export declare class DanglingPlacementError extends Error {
+    readonly productLocalID: number;
+    readonly cause: unknown;
+    /**
+     * @param productLocalID The product that could not be placed.
+     * @param cause The underlying dangling-reference error.
+     */
+    constructor(productLocalID: number, cause: unknown);
+}
+//# sourceMappingURL=dangling_placement_error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dangling_placement_error.d.ts","sourceRoot":"","sources":["../../../src/ifc/dangling_placement_error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAM7B,cAAc,EAAE,MAAM;aACtB,KAAK,EAAE,OAAO;IANhC;;;OAGG;gBAEe,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,OAAO;CAQjC"}

package/compiled/src/ifc/dangling_placement_error.js

@@ -0,0 +1,38 @@
+/**
+ * A product whose placement chain is not in the scanned prefix yet.
+ *
+ * Thrown by `extractPlacementStrict_` under `deferDanglingPlacements`, and
+ * caught by the parse-time preview channels, which treat it — like any throw
+ * from a product extract — as "not yet extractable, leave it to the durable
+ * pump".
+ *
+ * Strictly "not in the prefix YET": the tag is applied only when the
+ * underlying throw is a `DanglingReferenceError`, i.e. the placement chain
+ * referenced a record the index does not hold. A placement that is present
+ * but broken (wrong entity type, a select that is not an axis placement)
+ * propagates untagged, because the channels use this tag to decide what to
+ * retry, and retrying a permanently broken placement also keeps the early
+ * generation-preemption trigger alive for nothing.
+ *
+ * It exists only so that catch can ATTRIBUTE the deferral. The preview emits
+ * a product once its whole closure sits inside the prefix, and Revit writes
+ * per-product placements toward the file tail, so on those files early ticks
+ * meet long runs of products that all defer and the user sees nothing until
+ * the parse is nearly done. Whether a given blank preview is that, or
+ * something else entirely, decides whether sharding the parse would help it
+ * at all — so the distinction has to be measurable rather than inferred from
+ * a comment (conway#542).
+ */
+export class DanglingPlacementError extends Error {
+    /**
+     * @param productLocalID The product that could not be placed.
+     * @param cause The underlying dangling-reference error.
+     */
+    constructor(productLocalID, cause) {
+        super(`product ${productLocalID} placement is not resolvable in this ` +
+            `prefix: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.productLocalID = productLocalID;
+        this.cause = cause;
+        this.name = 'DanglingPlacementError';
+    }
+}

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

@@ -44,9 +44,17 @@ import IfcStepModel from "./ifc_step_model.js";
  * then to the product's own local ID, which is unique and therefore places
  * that product positionally rather than pretending to know better.
  *
- * Total, and deliberately so: a product whose attributes do not resolve gets
- * a usable key rather than aborting a load. A wrong placement costs a
- * duplicated extraction; a thrown error costs the model.
+ * Total for attribute failures, and deliberately so: a product whose
+ * attributes do not resolve gets a usable key rather than aborting a load. A
+ * wrong placement costs a duplicated extraction; a thrown error costs the
+ * model. That is safe precisely because an unresolvable attribute is a
+ * property of the FILE — every worker sees it and takes the same fallback.
+ *
+ * A NON-RESIDENT read is not: it is a property of one worker's paging, and a
+ * fallback taken for it is a key another worker will not agree with. Those
+ * propagate. On a windowed source, call {@link computeDispatchKeys} rather
+ * than this — it pages the walk's closure first, so the only way to reach
+ * that throw is a defect in the paging itself.
  *
  * @param model The model to read attributes from.
  * @param productLocalID The product's local ID.
@@ -65,4 +73,67 @@ export declare function geometryDispatchKey(model: IfcStepModel, productLocalID:
  * @return {number} The owning shard index.
  */
 export declare function shardOfDispatchKey(key: number, shardCount: number): number;
+/**
+ * Dispatch keys for a worklist, computed with the source bytes guaranteed
+ * present. Parallel to the worklist — `keys[i]` places `localIDs[i]`.
+ *
+ * **This is what makes a windowed source shardable.** Called inline,
+ * {@link geometryDispatchKey} reads records as it walks; on a windowed
+ * source a record that is not paged in throws, and the walk would fall back
+ * to the product's own local ID — so *which* products fell back would depend
+ * on which chunks that worker happened to hold. Two workers then disagree
+ * about a product, and both moduli select it (extracted twice) or neither
+ * (dropped silently). Paging the walk's own closure first removes the
+ * dependence: every worker reads the same bytes and computes the same key.
+ *
+ * A fully resident source takes the direct walk — there is nothing to page,
+ * and the keys are identical by construction rather than by agreement, which
+ * is what the paired windowed/resident fixtures assert.
+ *
+ * **Aligned to the worklist, not indexed by local ID.** Keys are wanted for
+ * products and for rel-aggregates' relating objects — tens of thousands of
+ * entries — and the consumer filters the worklist in order, so there is
+ * nothing to look up. A column over local IDs would be 37 MB on PSB's 9.4 M
+ * records to carry ~24 k useful ones.
+ *
+ * @param model The model to read attributes from.
+ * @param localIDs The worklist, in the order the consumer will filter it.
+ * @param waveSize Products whose closure is pinned at once.
+ * @return {Promise<Uint32Array>} Keys aligned to `localIDs`.
+ */
+export declare function computeDispatchKeys(model: IfcStepModel, localIDs: readonly number[], waveSize?: number): Promise<Uint32Array>;
+/**
+ * The local IDs an aggregate pass should be PLACED by — each
+ * `IfcRelAggregates`' relating object, paged first on a windowed source.
+ *
+ * A rel-aggregates entry is not an `IfcProduct`, so keying on the
+ * relationship record itself falls straight through
+ * {@link geometryDispatchKey} to its own local ID and shards by file
+ * position while claiming to place by representation. The assembly whose
+ * geometry the pass actually builds is the relating object, and that is what
+ * has to agree across workers.
+ *
+ * An aggregate whose relating object does not resolve keys by its own local
+ * ID — the same file-wide fallback the product walk takes, and the same
+ * reason it is safe.
+ *
+ * @param model The model to read attributes from.
+ * @param aggregateLocalIDs The `IfcRelAggregates` worklist, in order.
+ * @param waveSize Records whose bytes are pinned at once.
+ * @return {Promise<number[]>} Seeds aligned to `aggregateLocalIDs`.
+ */
+export declare function computeRelatingLocalIDs(model: IfcStepModel, aggregateLocalIDs: readonly number[], waveSize?: number): Promise<number[]>;
+/**
+ * One aggregate's relating object, or the aggregate itself when it does not
+ * resolve.
+ *
+ * Reads the aggregate's record, so a windowed caller must have paged it —
+ * {@link computeRelatingLocalIDs} is that caller. Exported for the resident
+ * path, which has nothing to page.
+ *
+ * @param model The model to read attributes from.
+ * @param aggregateLocalID The `IfcRelAggregates` record.
+ * @return {number} The local ID to key by.
+ */
+export declare function relatingLocalIDOf(model: IfcStepModel, aggregateLocalID: number): number;
 //# sourceMappingURL=geometry_dispatch.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"geometry_dispatch.d.ts","sourceRoot":"","sources":["../../../src/ifc/geometry_dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAS3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,YAAY,EACnB,cAAc,EAAE,MAAM,GAAI,MAAM,CAmCnC;AAGD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAI,MAAM,CAS5E"}
+{"version":3,"file":"geometry_dispatch.d.ts","sourceRoot":"","sources":["../../../src/ifc/geometry_dispatch.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,YAAY,EACnB,cAAc,EAAE,MAAM,GAAI,MAAM,CAuCnC;AAGD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAI,MAAM,CAS5E;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACrC,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,GAAE,MAA2B,GAAI,OAAO,CAAE,WAAW,CAAE,CAyClE;AAsKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,uBAAuB,CACzC,KAAK,EAAE,YAAY,EACnB,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,QAAQ,GAAE,MAA2B,GAAI,OAAO,CAAE,MAAM,EAAE,CAAE,CAoC/D;AAGD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAE,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,GAAI,MAAM,CAUzF"}