@bldrs-ai/conway 1.536.1507 → 1.543.1513

package/compiled/src/compat/web-ifc/store_preview_channel.js

@@ -7,6 +7,9 @@ import { WindowedStepBufferProvider } from "../../step/step_buffer_provider.js";
 import * as glmatrix from "gl-matrix";
 import { composeTransformF64, deriveCoordinationF64, IDENTITY_MAT4, NORMALIZE_MAT_F64, } from "./coordination_f64.js";
 import { emitSpatialStructureImposters } from "./spatial_imposter.js";
+import { DanglingPlacementError } from "../../ifc/dangling_placement_error.js";
+import { formatPreviewLine } from "../../core/progress_log.js";
+import Logger from "../../logging/logger.js";
 import { releaseModelGeometry, } from "./streamed_preview_channel.js";
 /* eslint-disable no-magic-numbers */
 const TICK_INTERVAL_MS = 150;
@@ -24,13 +27,53 @@ const TICK_BUDGET_MS = 20;
  * Products a single tick may attempt, whatever the clock says.
  *
  * `deferDanglingPlacements` (Share#1744) defers any product whose
- * placement records the prefix does not hold yet, and Revit writes
- * per-product placements toward the file tail — so early ticks meet long
- * runs of products that cannot extract. Each such attempt still pages
- * source through the windowed provider, so a run of them is not free;
- * this caps the run rather than letting the deadline be the only bound.
+ * placement records the prefix does not hold yet, and some exporters
+ * write the tail of a placement chain toward the tail of the file — so
+ * early ticks meet long runs of products that cannot extract. Each such
+ * attempt still pages source through the windowed provider, so a run of
+ * them is not free; this caps the run rather than letting the deadline
+ * be the only bound.
+ *
+ * Measured across the corpus in conway#542, and note it is the WRITER
+ * that decides record order, not the authoring tool: files written by
+ * the ODA IFC SDK and Tekla's exporter are strictly backward-
+ * referencing and never hit this path, while DDS_IFC (Archicad's IFC
+ * add-on) and ST-DEVELOPER defer 100% of products. On the Archicad
+ * files the last record in a chain to arrive is always a LEAF —
+ * IfcDirection or IfcCartesianPoint, not the placement and not the
+ * geometry — which is why a head-only prefix cannot fix it however far
+ * it grows.
+ *
+ * An earlier version of this comment blamed Revit. The one
+ * Revit-authored file in that corpus is the BEST case measured (first
+ * preview mesh at 269 ms, zero deferrals) — though it was written out
+ * through the ODA SDK, so it says nothing about Revit's own exporter
+ * either way. The 398 MB Archicad file is the worst: 531 of 532
+ * attempts deferred, first mesh at 98.3% of the file, 8.9 s of blank
+ * screen.
  */
 const TICK_MAX_ATTEMPTS = 32;
+/**
+ * Deferred products carried into the next generation for a second look.
+ *
+ * The channel used to be strictly forward-only: a product that deferred was
+ * attempted once, at the earliest — and therefore most index-starved —
+ * generation it appeared in, and never again, because `unitOrdinal_` only
+ * ever advances and a rebuilt generation regenerates `products` in the same
+ * dense parse order. On a file whose placement chains resolve late that
+ * throws away nearly everything: DOWA has 19,854 of its 45,860 products
+ * emittable once 70% of the file is indexed, and emitted 1, because all of
+ * them had been attempted and discarded before the index reached their
+ * leaves (conway#542).
+ *
+ * A retry is affordable in a way a first attempt is not: a deferring
+ * attempt costs ~0.17 ms — the whole 532-attempt run on DOWA is 93 ms,
+ * against 2.1 s for that load's three generation rebuilds — because it
+ * fails on an index lookup before any geometry is paged. The cap is here
+ * because the queue must not grow with the model; it only has to keep
+ * DEFAULT_MAX_PREVIEW_UNITS worth of candidates in play.
+ */
+const RETRY_QUEUE_MAX = 4096;
 const FIRST_GENERATION_MIN_RECORDS = 1024;
 const GENERATION_GROWTH_FACTOR = 2;
 const DEFAULT_MAX_PREVIEW_UNITS = 512;
@@ -75,6 +118,36 @@ export class StorePreviewChannel {
         this.firstGenerationMinRecords = firstGenerationMinRecords;
         this.stopped_ = false;
         this.emittedUnits_ = 0;
+        /**
+         * Preview meshes handed to `onMesh_`. Tracked apart from
+         * {@link emittedUnits_} because the two genuinely diverge: a product can
+         * place several meshes, and a product with no Representation extracts
+         * cleanly while placing none — `extractProductGeometry` returns early on
+         * a null Representation and `extractProductGeometryByLocalID` still
+         * answers true. Reporting only units let the load log say "no mesh, 20
+         * emitted" about one load (codex round 2 on #543).
+         */
+        this.meshesEmitted_ = 0;
+        /* Products a tick attempted but could not extract, and how many of those
+         * were specifically waiting on a placement chain the prefix does not hold
+         * yet. Reported at the end of the preview so a blank first load is
+         * attributable: "9 812 of 9 840 attempts deferred, 9 810 on placements" is
+         * a file-layout problem that a sharded parse addresses, and anything else
+         * is not (conway#542). */
+        this.deferredUnits_ = 0;
+        this.deferredOnPlacement_ = 0;
+        /**
+         * Products that deferred under the CURRENT generation, promoted to
+         * {@link retryQueue_} when the next one is built. Held separately so a
+         * retry always runs against a longer index than the attempt that failed —
+         * re-running one inside its own generation would fail identically and
+         * spin.
+         */
+        this.deferredForRetry_ = [];
+        this.retryQueue_ = [];
+        this.retryCursor_ = 0;
+        this.retriedUnits_ = 0;
+        this.startedMs_ = Date.now();
         this.emittedBytes_ = 0;
         this.unitOrdinal_ = 0;
         this.lastInlineTick_ = 0;
@@ -105,6 +178,37 @@ export class StorePreviewChannel {
     get emittedUnits() {
         return this.emittedUnits_;
     }
+    /**
+     * What the preview delivered, and how fast.
+     *
+     * `firstMeshMs` is time-to-first-pixel measured from channel
+     * construction, undefined when no placed product was ever emitted.
+     * `meshes` counts what actually reached the consumer, `emitted` counts
+     * the products extraction accepted — they are not the same number in
+     * either direction, so the line reports both.
+     * `deferred` counts products a tick attempted and could not extract;
+     * `deferredOnPlacement` is the subset still waiting on a placement chain
+     * the prefix does not hold; `retried` counts attempts that were second
+     * looks at an earlier deferral rather than first attempts, so a channel
+     * whose retry path has silently stopped firing is visible rather than
+     * merely slower. A first load that shows nothing is a very
+     * different problem depending on that ratio — near 1.0 is the file-layout
+     * case a sharded parse attacks, anything else is not — and inferring it
+     * from a code comment is what conway#542 exists to stop.
+     *
+     * @return {object} `{firstMeshMs, meshes, emitted, deferred,
+     * deferredOnPlacement, retried}`
+     */
+    get previewYield() {
+        return {
+            firstMeshMs: this.firstMeshMs_,
+            meshes: this.meshesEmitted_,
+            emitted: this.emittedUnits_,
+            deferred: this.deferredUnits_,
+            deferredOnPlacement: this.deferredOnPlacement_,
+            retried: this.retriedUnits_,
+        };
+    }
     /** Products the current generation would run (test seam). */
     get productCount() {
         return this.generation_?.products.length ?? 0;
@@ -205,6 +309,25 @@ export class StorePreviewChannel {
     stop() {
         this.stopped_ = true;
         this.disposeGeneration_();
+        // Say what the preview delivered, and how fast, on the way out. The
+        // channel is a local of the open call — nothing outside holds it — so a
+        // counter that is not reported here is a counter nobody can read. And a
+        // first load that showed the user nothing is exactly the case where this
+        // line is the whole diagnosis: a deferral ratio near 1.0 ON PLACEMENTS
+        // is the file-layout problem, and anything else is a different problem
+        // wearing the same blank screen (conway#542). Rendered by the shared
+        // load-log formatter, so the resident path's line and this one are the
+        // same line.
+        //
+        // Unconditional, not gated on emittedUnits_ or deferredUnits_ being
+        // nonzero: a channel that never reached firstGenerationMinRecords, or
+        // whose every generation build threw, is precisely the worst-case
+        // blank-first-load this issue exists to make diagnosable — and
+        // formatPreviewLine already renders that as "no mesh, 0 emitted, 0
+        // deferred". Suppressing the line there made an enabled preview that
+        // produced nothing indistinguishable from a preview that never ran
+        // (codex round 1 on #543).
+        Logger.info(formatPreviewLine(this.previewYield));
     }
     /**
      * Test seam: drain until the current sink is exhausted or a cap hits.
@@ -232,10 +355,19 @@ export class StorePreviewChannel {
             return false;
         }
         const active = this.generation_;
-        if (this.unitOrdinal_ >= active.products.length) {
+        if (!StorePreviewChannel.hasPending_(this.retryCursor_, this.retryQueue_.length, this.unitOrdinal_, active.products.length)) {
             return false;
         }
-        const localID = active.products[this.unitOrdinal_++];
+        // Retries first: they are the products the index has most recently
+        // become able to place, and they are cheaper than a fresh attempt
+        // whichever way they go.
+        const isRetry = this.retryCursor_ < this.retryQueue_.length;
+        const localID = isRetry ?
+            this.retryQueue_[this.retryCursor_++] :
+            active.products[this.unitOrdinal_++];
+        if (isRetry) {
+            ++this.retriedUnits_;
+        }
         const model = active.model;
         const pins = new Set();
         const leafSpans = [];
@@ -246,8 +378,22 @@ export class StorePreviewChannel {
                 ++this.emittedUnits_;
             }
         }
-        catch {
-            // Forward-ref / unplaced — durable pump extracts later.
+        catch (error) {
+            // Forward-ref / unplaced — durable pump extracts later. Counted by
+            // cause: a preview that stays blank because every product's placement
+            // is still ahead of the prefix wants a different fix from one blank
+            // for any other reason, and only this split can tell them apart
+            // (conway#542).
+            ++this.deferredUnits_;
+            if (error instanceof DanglingPlacementError) {
+                ++this.deferredOnPlacement_;
+                // Only placement deferrals are worth another look. Any other throw
+                // is a property of the product rather than of how much index exists,
+                // so a longer prefix does not change the answer.
+                if (this.deferredForRetry_.length < RETRY_QUEUE_MAX) {
+                    this.deferredForRetry_.push(localID);
+                }
+            }
         }
         finally {
             model.releaseSourceViews(pins);
@@ -258,15 +404,62 @@ export class StorePreviewChannel {
         }
         return true;
     }
+    /**
+     * Whether either queue still has a product to attempt.
+     *
+     * Static and fully parameterised so the two callers — the tick and the
+     * generation gate — cannot drift apart on what "pending" means, which is
+     * the bug that would silently strand the retry queue.
+     *
+     * @param retryCursor How far into the retry queue this generation is.
+     * @param retryLength The retry queue's length.
+     * @param ordinal The forward cursor into the generation's products.
+     * @param productCount That generation's product count.
+     * @return {boolean} True when something is left to attempt.
+     */
+    static hasPending_(retryCursor, retryLength, ordinal, productCount) {
+        return retryCursor < retryLength || ordinal < productCount;
+    }
     /**
      * @return {Promise<boolean>} True when a generation with pending units exists.
      */
     async ensureGeneration_() {
         const active = this.generation_;
-        if (active !== void 0 && this.unitOrdinal_ < active.products.length) {
+        const records = this.sink_.topLevelCount;
+        // Rebuild on INDEX GROWTH, not on running out of products. The order of
+        // these two tests is the whole behaviour of the channel on a large file.
+        //
+        // It used to keep the current generation for as long as that generation
+        // still had an unattempted product, and only then consider rebuilding.
+        // A generation snapshotted at FIRST_GENERATION_MIN_RECORDS already lists
+        // thousands of products, and the tick attempts at most
+        // TICK_MAX_ATTEMPTS of them per cadence interval, so on anything large
+        // the list never emptied and the rebuild never fired: DOWA spent all 9 s
+        // of its parse extracting against a snapshot of its first 1024 records,
+        // which is why 100% of its attempts deferred and its first mesh landed
+        // at 99.2% of the file (conway#542). The growth gate below was written
+        // to bound rebuild cost and instead became unreachable.
+        //
+        // Preempting makes generations arrive on the index's schedule —
+        // O(log records) of them, GENERATION_GROWTH_FACTOR apart — and the
+        // products the old generation had not reached carry over untouched,
+        // because `unitOrdinal_` indexes a dense parse-order list that a longer
+        // snapshot only extends (see ColumnarIndexSink.snapshot).
+        // Eligibility to rebuild at all — the original growth gate, unchanged.
+        const growthReady = records >= this.lastSnapshotRecords_ * GENERATION_GROWTH_FACTOR &&
+            records >= this.lastFailedSnapshotRecords_ * GENERATION_GROWTH_FACTOR;
+        // Whether to rebuild EARLY, without waiting for the current generation's
+        // products to run out. Only worth it for a generation that is actually
+        // deferring: a longer index cannot help one whose products extract fine,
+        // and preempting anyway costs the case that already works best — on PSB,
+        // which defers nothing, unconditional preemption pushed the first mesh
+        // from 269 ms out to 495 ms. Deferrals waiting for retry are precisely
+        // the evidence that more index is the missing ingredient.
+        const preempt = active !== void 0 && growthReady &&
+            this.deferredForRetry_.length > 0;
+        if (!preempt && active !== void 0 && StorePreviewChannel.hasPending_(this.retryCursor_, this.retryQueue_.length, this.unitOrdinal_, active.products.length)) {
             return true;
         }
-        const records = this.sink_.topLevelCount;
         if (records < this.firstGenerationMinRecords) {
             return false;
         }
@@ -274,6 +467,10 @@ export class StorePreviewChannel {
             records < this.lastSnapshotRecords_ * GENERATION_GROWTH_FACTOR) {
             return false;
         }
+        // Unconditional, unlike the snapshot gate above: a prefix whose build
+        // THREW leaves no active generation, so folding this into `growthReady`
+        // and testing it only when one exists would let a structurally
+        // incomplete prefix re-snapshot and re-throw on every tick.
         if (records < this.lastFailedSnapshotRecords_ * GENERATION_GROWTH_FACTOR) {
             return false;
         }
@@ -289,7 +486,11 @@ export class StorePreviewChannel {
                 this.lastFailReason = `no products in ${records} records`;
                 return false;
             }
-            if (products.length <= this.unitOrdinal_) {
+            // A generation that adds no new products is still worth building when
+            // deferred ones are waiting: what changed is the INDEX behind them,
+            // which is the only reason a retry could now succeed.
+            if (products.length <= this.unitOrdinal_ &&
+                this.deferredForRetry_.length === 0) {
                 this.lastFailReason = `ordinal ${this.unitOrdinal_} >= ${products.length}`;
                 return false;
             }
@@ -305,6 +506,21 @@ export class StorePreviewChannel {
                 model.unpinLocalIDs(prepPins);
             }
             this.disposeGeneration_();
+            // Carry the OLD queue's unconsumed suffix forward, not just this
+            // generation's fresh deferrals. Preemption can fire mid-drain of
+            // retryQueue_ — bounded per-tick attempts (TICK_MAX_ATTEMPTS) against
+            // an index that grew enough to trigger a rebuild before the queue
+            // emptied — and every one of those un-popped entries is a product
+            // whose ordinal unitOrdinal_ has already passed, so replacing the
+            // queue outright (rather than concatenating) would strand them
+            // exactly the way abandoned deferrals were stranded before this fix
+            // existed (conway#542, codex round 1 on #543).
+            this.retryQueue_ = [
+                ...this.retryQueue_.slice(this.retryCursor_),
+                ...this.deferredForRetry_,
+            ].slice(0, RETRY_QUEUE_MAX);
+            this.retryCursor_ = 0;
+            this.deferredForRetry_ = [];
             this.generation_ = {
                 model,
                 extraction,
@@ -447,15 +663,18 @@ export class StorePreviewChannel {
     /**
      * Copy newly extracted instances out of wasm — same placement math
      * as {@link StreamedPreviewChannel}.
+     *
+     * @return {number} Meshes emitted by this pass.
      */
     captureNewInstances_() {
         const active = this.generation_;
         if (active === void 0) {
-            return;
+            return 0;
         }
         const { extraction, capturedCounts } = active;
         const scene = extraction.scene;
         const seenThisPass = new Map();
+        let emitted = 0;
         for (const walked of scene.walk()) {
             const [, nativeTransform, geometry, material, entity] = walked;
             if (entity?.localID === void 0 || entity.expressID === void 0) {
@@ -515,10 +734,14 @@ export class StorePreviewChannel {
                 this.emittedBytes_ +=
                     (vertexData.length + indexData.length) * BYTES_PER_FLOAT;
             }
+            this.firstMeshMs_ ??= Date.now() - this.startedMs_;
             this.onMesh_(payload);
+            ++this.meshesEmitted_;
+            ++emitted;
             if (this.emittedBytes_ >= this.maxBytes) {
-                return;
+                return emitted;
             }
         }
+        return emitted;
     }
 }

package/compiled/src/compat/web-ifc/store_preview_channel.test.js

@@ -1,8 +1,9 @@
 /* eslint-disable no-magic-numbers */
 import * as fs from "fs";
-import { beforeAll, describe, expect, test } from "@jest/globals";
+import { beforeAll, describe, expect, jest, test } from "@jest/globals";
 import { ConwayGeometry } from "../../../dependencies/conway-geom/index.js";
 import IfcStepParser from "../../ifc/ifc_step_parser.js";
+import Logger from "../../logging/logger.js";
 import { BufferByteSource } from "../../step/parsing/byte_source.js";
 import { ColumnarIndexSink } from "../../step/parsing/columnar_index.js";
 import { ParseResult } from "../../step/parsing/step_parser.js";
@@ -73,6 +74,147 @@ describe("StorePreviewChannel", () => {
         expect(attempted).toBeLessThanOrEqual(internals.tickMaxAttempts_);
         channel.stop();
     });
+    test("a tail-placement file recovers its deferred products", async () => {
+        // data/index_tail_placements.ifc is index_georeferenced_multicell.ifc
+        // with every leaf point/direction record moved to the end of DATA --
+        // same ids, same text, hostile order. It is the Archicad shape at
+        // fixture scale: its products reference a placement chain that bottoms
+        // out after them, so an index stopping short of the tail cannot place
+        // any of them (conway#542). The multicell fixture rather than
+        // index.ifc because it carries enough products that a few ticks cannot
+        // exhaust the generation -- which is what leaves the preemption path,
+        // not the exhaustion path, as the only way to rebuild.
+        const tailText = fs.readFileSync("data/index_tail_placements.ifc", "utf8");
+        const lines = tailText.split("\n");
+        const firstLeaf = lines.findIndex((line) => /=\s*IFC(CARTESIANPOINT|DIRECTION)/.test(line));
+        expect(firstLeaf).toBeGreaterThan(0);
+        // A genuine prefix, closed off so it parses: every record up to the
+        // leaf block, and nothing after it. The full file is stage two.
+        const prefixText = `${lines.slice(0, firstLeaf).join("\n")}\nENDSEC;\nEND-ISO-10303-21;\n`;
+        const prefixBytes = new Uint8Array(Buffer.from(prefixText, "latin1"));
+        const tailBytes = new Uint8Array(Buffer.from(tailText, "latin1"));
+        const store = new InMemoryStepByteStore(tailBytes);
+        const sink = new ColumnarIndexSink();
+        const channel = new StorePreviewChannel(store, sink, conwayGeometry, true, () => { }, 64, 48 * 1024 * 1024, 1);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const internals = channel;
+        // One product per tick, so stage one leaves products UNATTEMPTED. That
+        // is what forces the preemption path: with products still pending, a
+        // channel that only rebuilds on exhaustion keeps its starved generation
+        // and never looks at the deferrals again.
+        internals.tickBudgetMs_ = Number.MAX_SAFE_INTEGER;
+        internals.tickMaxAttempts_ = 1;
+        // Stage one: index only the prefix, then let the channel work it.
+        expect(buildIndexStreaming(new BufferByteSource(prefixBytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        internals.lastInlineTick_ = 0;
+        await channel.maybeTickAsync();
+        const afterPrefix = channel.previewYield;
+        // The fixture has to actually exercise the path, or the rest proves
+        // nothing about it -- and products must be left over, or the rebuild
+        // would happen by exhaustion and prove nothing about preemption.
+        expect(afterPrefix.deferredOnPlacement).toBeGreaterThan(0);
+        expect(afterPrefix.emitted).toBe(0);
+        expect(internals.unitOrdinal_).toBeLessThan(channel.productCount);
+        // Stage two: the same reset-and-replay the streaming builder itself
+        // performs when it grows its window, so top-level localIDs stay in
+        // dense parse order and the deferred ids the channel is holding still
+        // mean what they meant (see ColumnarIndexSink.reset).
+        sink.reset();
+        expect(buildIndexStreaming(new BufferByteSource(tailBytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        // Exactly one tick, and one attempt inside it. That is what makes this
+        // an assertion about PREEMPTION: with products still pending, a channel
+        // that rebuilds only on exhaustion spends this tick on the next fresh
+        // product against the old starved generation, and the retry never
+        // happens.
+        internals.lastInlineTick_ = 0;
+        await channel.maybeTickAsync();
+        const afterFull = channel.previewYield;
+        // Both halves of the fix, and `retried` is what separates them from a
+        // channel that merely got lucky on a later product. Without the retry
+        // queue a deferred product is attempted once, at the most
+        // index-starved generation it appears in, and abandoned. Without
+        // preemptive rebuilds the generation is kept while products remain, so
+        // the deferrals are never revisited against the longer index. Either
+        // one missing holds this at zero.
+        expect(afterFull.retried).toBeGreaterThan(0);
+        expect(afterFull.emitted).toBeGreaterThan(0);
+        channel.stop();
+    }, 120000);
+    test("a generation is preempted only when it is deferring", async () => {
+        // The counterweight. Rebuilding on index growth alone regressed the
+        // case that already worked: PSB, which defers nothing, went from a
+        // first mesh at 269ms to 495ms because it kept paying for rebuilds it
+        // had no use for. index.ifc is that shape at fixture scale, so the
+        // same two-stage growth must leave its generation alone.
+        const store = new InMemoryStepByteStore(bytes);
+        const sink = new ColumnarIndexSink();
+        const channel = new StorePreviewChannel(store, sink, conwayGeometry, true, () => { }, 64, 48 * 1024 * 1024, 1);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const internals = channel;
+        // One product per tick, but with the wall clock lifted -- a zero
+        // budget would stop the tick before it ever built a generation.
+        internals.tickBudgetMs_ = Number.MAX_SAFE_INTEGER;
+        internals.tickMaxAttempts_ = 1;
+        expect(buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        internals.lastInlineTick_ = 0;
+        await channel.maybeTickAsync();
+        const snapshotRecords = internals.lastSnapshotRecords_;
+        expect(snapshotRecords).toBeGreaterThan(0);
+        expect(channel.previewYield.deferredOnPlacement).toBe(0);
+        // Index growth well past GENERATION_GROWTH_FACTOR, with products still
+        // pending and nothing deferring: the generation must be kept.
+        sink.reset();
+        for (let repeat = 0; repeat < 3; ++repeat) {
+            expect(buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        }
+        expect(sink.topLevelCount).toBeGreaterThan(snapshotRecords * 2);
+        internals.lastInlineTick_ = 0;
+        await channel.maybeTickAsync();
+        expect(internals.lastSnapshotRecords_).toBe(snapshotRecords);
+        expect(channel.previewYield.retried).toBe(0);
+        channel.stop();
+    }, 120000);
+    test("a throwing prefix build retires the attempt, not the channel", async () => {
+        // A mid-parse prefix can be structurally incomplete, and building a
+        // generation over it throws. That must retire THIS attempt and then
+        // wait for index growth: without the wait the channel re-snapshots and
+        // re-throws on every tick, which is a snapshot copy of the whole prefix
+        // per tick on a file large enough to matter.
+        //
+        // The gate has to hold with NO active generation, because a build that
+        // throws is exactly the case that leaves none — that is why it is
+        // tested on its own rather than folded in with the growth gate.
+        const store = new InMemoryStepByteStore(bytes);
+        const sink = new ColumnarIndexSink();
+        expect(buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        let reportedRecords = sink.topLevelCount;
+        let snapshots = 0;
+        const flakySink = {
+            get topLevelCount() {
+                return reportedRecords;
+            },
+            snapshot: () => {
+                if (++snapshots === 1) {
+                    throw new Error("structurally incomplete prefix");
+                }
+                return sink.snapshot();
+            },
+        };
+        const payloads = [];
+        const channel = new StorePreviewChannel(store, flakySink, conwayGeometry, true, (mesh) => payloads.push(mesh), 64, 48 * 1024 * 1024, 1);
+        await channel.drainForTest();
+        expect(snapshots).toBe(1);
+        expect(payloads.length).toBe(0);
+        // Same record count: the failure gate must hold the retry.
+        await channel.drainForTest();
+        expect(snapshots).toBe(1);
+        // The index grows past the gate: the retry builds and emits.
+        reportedRecords *= 4;
+        await channel.drainForTest();
+        expect(snapshots).toBe(2);
+        expect(payloads.length).toBeGreaterThan(0);
+        channel.stop();
+    }, 120000);
     test("an unproductive tick does not decay the cadence", async () => {
         const sink = new ColumnarIndexSink();
         // Nothing parsed into the sink, so no generation can build. Every
@@ -231,4 +373,131 @@ describe("StorePreviewChannel", () => {
         expect(spatial[0].color).toEqual({ x: 0, y: 0, z: 0, w: 0.3 });
         api.CloseModel(id);
     });
+    test("preemption preserves the unconsumed suffix of the retry queue", async () => {
+        // Codex round 1 on #543: preemption replaced retryQueue_ outright with
+        // this generation's fresh deferredForRetry_, discarding whatever the
+        // OLD queue's tail had not yet been popped. A retry queue can easily
+        // span more than one tick's TICK_MAX_ATTEMPTS budget, so index growth
+        // can preempt a generation mid-drain of it — and every un-popped entry
+        // is a product whose unitOrdinal_ has already passed, so replacing
+        // rather than concatenating strands it exactly the way abandoned
+        // deferrals were stranded before this queue existed (conway#542).
+        //
+        // The bug is purely mechanical (which array wins the assignment), so
+        // this seeds the private queue state directly and forces the growth
+        // gate via lastSnapshotRecords_, rather than engineering a real
+        // multi-tick deferral sequence — store_preview_channel.ts's extraction
+        // seam isn't pluggable the way the resident channel's
+        // PreviewSchemaAdapter is, so a real gen1/gen2 pair here means real
+        // IfcStepModel/IfcGeometryExtraction builds regardless.
+        const store = new InMemoryStepByteStore(bytes);
+        const sink = new ColumnarIndexSink();
+        expect(buildIndexStreaming(new BufferByteSource(bytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        const channel = new StorePreviewChannel(store, sink, conwayGeometry, true, () => { }, 64, 48 * 1024 * 1024, 1);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const internals = channel;
+        // Generation 1: a real, successful build (active must be defined for
+        // the preemption branch to even be reachable).
+        expect(await internals.ensureGeneration_()).toBe(true);
+        // A retry queue spanning more than one tick's budget: 6 queued
+        // retries, only the first 3 consumed (retryCursor_ short of
+        // retryQueue_.length is exactly "mid-drain") before the index grew
+        // again. deferredForRetry_ is this generation's OWN fresh deferral —
+        // the only thing the buggy version kept.
+        internals.retryQueue_ = [10, 11, 12, 13, 14, 15];
+        internals.retryCursor_ = 3;
+        internals.deferredForRetry_ = [99];
+        // Force the growth gate trivially open on the next check, without
+        // needing the sink to actually grow: the gate is a ratio against
+        // lastSnapshotRecords_, not an absolute count.
+        internals.lastSnapshotRecords_ = 1;
+        // Preemption fires: active is defined, growthReady (real topLevelCount
+        // >= 1 * factor), and deferredForRetry_.length > 0.
+        expect(await internals.ensureGeneration_()).toBe(true);
+        // The unconsumed suffix of the old queue (indices 3..5) must survive,
+        // carried ahead of this generation's own fresh deferral — not replaced
+        // by it.
+        expect(internals.retryQueue_).toEqual([13, 14, 15, 99]);
+        expect(internals.retryCursor_).toBe(0);
+        channel.stop();
+    }, 120000);
+    test("a permanently malformed placement never enters the retry queue", async () => {
+        // Codex round 1 on #543: extractPlacementStrict_ tagged EVERY throw out
+        // of the strict placement read as DanglingPlacementError, so a placement
+        // that is broken rather than unscanned was classified as a file-layout
+        // deferral. That is not a cosmetic mislabel: the tag is what puts a
+        // product in deferredForRetry_, and a non-empty deferredForRetry_ is
+        // also the trigger for early generation PREEMPTION — so one malformed
+        // placement bought a full model/extraction rebuild on every growth step
+        // for a retry that could never come good.
+        //
+        // Two products, two causes, one file, so the assertion is about the
+        // SPLIT rather than about either case alone:
+        //
+        //   #334 RelativePlacement -> #345, an IFCPOLYGONALFACESET. Indexed
+        //        and present, but the field is an IfcAxis2Placement select, so
+        //        IfcLocalPlacement's generated getter rejects it. No amount of
+        //        further index changes that answer.
+        //   #408 Location -> #999999, which no record in the file defines.
+        //        Absent from the index, which on a prefix is exactly "not
+        //        scanned yet" — the case that must still defer and retry.
+        const text = fs.readFileSync("data/index.ifc", "utf8");
+        expect(text).toContain("#334= IFCLOCALPLACEMENT(#152,#333);");
+        expect(text).toContain("#408= IFCAXIS2PLACEMENT3D(#406,#404,#402);");
+        expect(text).toContain("#345= IFCPOLYGONALFACESET(");
+        expect(text).not.toContain("#999999=");
+        const brokenText = text
+            .replace("#334= IFCLOCALPLACEMENT(#152,#333);", "#334= IFCLOCALPLACEMENT(#152,#345);")
+            .replace("#408= IFCAXIS2PLACEMENT3D(#406,#404,#402);", "#408= IFCAXIS2PLACEMENT3D(#999999,#404,#402);");
+        const brokenBytes = new Uint8Array(Buffer.from(brokenText, "latin1"));
+        const store = new InMemoryStepByteStore(brokenBytes);
+        const sink = new ColumnarIndexSink();
+        // The COMPLETE index, deliberately: it takes prefix-vs-tail out of the
+        // picture, so the only thing left to explain a deferral is the cause of
+        // the throw. It also means no generation is ever rebuilt (the record
+        // count cannot grow past the growth factor again), so the retry queue
+        // this inspects is the one the tick built and never drained.
+        expect(buildIndexStreaming(new BufferByteSource(brokenBytes), IfcStepParser.Instance, 4 * 1024, void 0, sink).result).toBe(ParseResult.COMPLETE);
+        const channel = new StorePreviewChannel(store, sink, conwayGeometry, true, () => { }, 64, 48 * 1024 * 1024, 1);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const internals = channel;
+        await channel.drainForTest();
+        const observed = channel.previewYield;
+        // Both products fail to extract — the split is in how they are counted,
+        // and in which of them is worth another attempt.
+        expect(observed.deferred).toBe(2);
+        expect(observed.deferredOnPlacement).toBe(1);
+        expect(internals.deferredForRetry_).toHaveLength(1);
+        // And the rest of the file is unaffected: these two are the only
+        // products that lost their geometry.
+        expect(observed.emitted).toBe(channel.productCount - 2);
+        channel.stop();
+    }, 120000);
+    test("reports a preview line even when nothing was ever attempted", () => {
+        // Codex round 1 on #543: stop() suppressed the Preview line unless
+        // emittedUnits_ or deferredUnits_ was nonzero. A channel that never
+        // reached firstGenerationMinRecords -- or whose every generation build
+        // threw -- leaves both at zero, and that is exactly the worst-case
+        // blank-first-load conway#542 exists to make diagnosable: an enabled
+        // preview that produced nothing must not read the same as a preview
+        // that never ran. formatPreviewLine already renders the zero case as
+        // "no mesh, 0 meshes from 0 units, 0 deferred".
+        const store = new InMemoryStepByteStore(bytes);
+        const emptySink = {
+            get topLevelCount() {
+                return 0;
+            },
+            snapshot: () => {
+                throw new Error("must not be called: topLevelCount never grows");
+            },
+        };
+        const infoSpy = jest.spyOn(Logger, "info").mockImplementation(() => { });
+        // Default firstGenerationMinRecords (1024): with topLevelCount pinned
+        // at 0, ensureGeneration_ never builds a generation, so the channel
+        // reaches stop() having attempted nothing at all.
+        const channel = new StorePreviewChannel(store, emptySink, conwayGeometry, false, () => { });
+        channel.stop();
+        expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining("Preview: no mesh, 0 meshes from 0 units, 0 deferred"));
+        infoSpy.mockRestore();
+    });
 });