@bldrs-ai/conway 1.389.1221 → 1.394.1504

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

@@ -0,0 +1,122 @@
+/* eslint-disable no-magic-numbers */
+// M4: the index sidecar must serialise a model's parse index and deserialise
+// it back byte-identically, so an index-first open reconstructs the entity
+// index without re-scanning the source — and it must refuse to be trusted when
+// the source it was built from no longer matches (hash / length handshake).
+import * as fs from "fs";
+import { describe, expect, test } from "@jest/globals";
+import ParsingBuffer from "../../parsing/parsing_buffer.js";
+import IfcStepParser from "../../ifc/ifc_step_parser.js";
+import { deserializeIndexSidecar, deserializeIndexSidecarToColumns, hashSource, serializeIndexSidecar, serializeIndexSidecarFromColumns, sidecarMatchesSource, } from "./index_sidecar.js";
+import { BufferByteSource } from "./byte_source.js";
+import { buildColumnarIndexStreaming } from "./streaming_index_builder.js";
+/**
+ * Parse index.ifc resident and return its top-level element index plus the
+ * source bytes it was built from.
+ *
+ * @return {object} `{ bytes, elements }`.
+ */
+function residentIndex() {
+    const bytes = new Uint8Array(fs.readFileSync("data/index.ifc"));
+    const input = new ParsingBuffer(bytes);
+    IfcStepParser.Instance.parseHeader(input);
+    const [index,] = IfcStepParser.Instance.parseDataBlock(input);
+    return { bytes, elements: index.elements };
+}
+describe("index sidecar", () => {
+    test("round-trips the top-level index byte-identically", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const blob = serializeIndexSidecar(elements, bytes.byteLength, hash);
+        const decoded = deserializeIndexSidecar(blob);
+        expect(decoded.sourceByteLength).toBe(bytes.byteLength);
+        expect(decoded.sourceHash).toBe(hash);
+        expect(decoded.elements.length).toBe(elements.length);
+        for (let where = 0; where < elements.length; ++where) {
+            const original = elements[where];
+            const restored = decoded.elements[where];
+            expect(restored.address).toBe(original.address);
+            expect(restored.length).toBe(original.length);
+            expect(restored.expressID).toBe(original.expressID);
+            // typeID round-trips including the undefined case (stored as -1).
+            expect(restored.typeID).toBe(original.typeID);
+        }
+    });
+    test("accepts a sidecar whose hash and length match the source", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const decoded = deserializeIndexSidecar(serializeIndexSidecar(elements, bytes.byteLength, hash));
+        expect(sidecarMatchesSource(decoded, bytes.byteLength, hash)).toBe(true);
+    });
+    test("rejects a sidecar when the source bytes changed (hash mismatch)", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const decoded = deserializeIndexSidecar(serializeIndexSidecar(elements, bytes.byteLength, hash));
+        // Same length, one byte flipped → different hash → must not be trusted.
+        const mutated = bytes.slice();
+        mutated[Math.floor(mutated.length / 2)] ^= 255;
+        expect(sidecarMatchesSource(decoded, mutated.byteLength, hashSource(mutated)))
+            .toBe(false);
+    });
+    test("rejects a sidecar when the source length changed", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const decoded = deserializeIndexSidecar(serializeIndexSidecar(elements, bytes.byteLength, hash));
+        expect(sidecarMatchesSource(decoded, bytes.byteLength + 1, hash))
+            .toBe(false);
+    });
+    test("hashSource is deterministic and sensitive to content", () => {
+        const a = new Uint8Array([1, 2, 3, 4, 5]);
+        const b = new Uint8Array([1, 2, 3, 4, 5]);
+        const c = new Uint8Array([1, 2, 3, 4, 6]);
+        expect(hashSource(a)).toBe(hashSource(b));
+        expect(hashSource(a)).not.toBe(hashSource(c));
+    });
+    test("preserves undefined typeID through the -1 sentinel", () => {
+        const elements = [
+            { address: 0, length: 10, typeID: 7, expressID: 1 },
+            { address: 10, length: 20, typeID: void 0, expressID: 2 },
+            { address: 30, length: 5, typeID: 0, expressID: 3 },
+        ];
+        const decoded = deserializeIndexSidecar(serializeIndexSidecar(elements, 35, 0));
+        expect(decoded.elements[0].typeID).toBe(7);
+        expect(decoded.elements[1].typeID).toBe(void 0);
+        expect(decoded.elements[2].typeID).toBe(0);
+    });
+    test("throws on a blob with bad magic", () => {
+        const garbage = new Uint8Array(32);
+        expect(() => deserializeIndexSidecar(garbage)).toThrow(/magic/);
+    });
+    test("round-trips an empty index", () => {
+        const decoded = deserializeIndexSidecar(serializeIndexSidecar([], 0, 0));
+        expect(decoded.elements.length).toBe(0);
+    });
+    test("columns-form serialize is byte-identical to the object-form blob (M7)", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const { columns } = buildColumnarIndexStreaming(new BufferByteSource(bytes), 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        IfcStepParser.Instance, 4096);
+        const fromObjects = serializeIndexSidecar(elements, bytes.byteLength, hash);
+        const fromColumns = serializeIndexSidecarFromColumns(columns, bytes.byteLength, hash);
+        expect(fromColumns).toEqual(fromObjects);
+    });
+    test("deserializes straight to columns for the index-first open (M7)", () => {
+        const { bytes, elements } = residentIndex();
+        const hash = hashSource(bytes);
+        const blob = serializeIndexSidecar(elements, bytes.byteLength, hash);
+        const restored = deserializeIndexSidecarToColumns(blob);
+        expect(restored.sourceByteLength).toBe(bytes.byteLength);
+        expect(restored.sourceHash).toBe(hash);
+        expect(restored.columns.count).toBe(elements.length);
+        expect(restored.columns.firstInlineElement).toBe(elements.length);
+        expect(restored.columns.expressIdsSorted).toBe(true);
+        for (let where = 0; where < elements.length; ++where) {
+            expect(restored.columns.address[where]).toBe(elements[where].address);
+            expect(restored.columns.length[where]).toBe(elements[where].length);
+            expect(restored.columns.expressID[where]).toBe(elements[where].expressID);
+            expect(restored.columns.typeID[where])
+                .toBe(elements[where].typeID ?? -1);
+        }
+    });
+});

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

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

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

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

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

@@ -0,0 +1,108 @@
+// `INF` where a real belongs is not valid ISO 10303-21, but exporters emit it
+// for unbounded quantities and the parser recovers from it. The recovery used
+// to stamp the offending record's express ID over every top-level entry
+// indexed so far in the block, which corrupted every lookup that followed.
+//
+// It stayed hidden only because no public corpus model reaches this recovery.
+// Not because a failed parse is harmless: the stamping ran before the rollback
+// and the INF check, so any top-level inline-instance failure poisoned the
+// index, and parseDataToModel builds a model from those elements whatever the
+// ParseResult. A private model reaches it - `IFCQUANTITYLENGTH(...,INF,$)`
+// from a Swiss architectural export - where it cost 3,116 entities and
+// produced 630 relationship failures all reporting the same express ID.
+// See bldrs-ai/conway#412, #481, #482.
+//
+// Parser-only, so no geometry wasm is initialized here.
+import { describe, expect, test } from "@jest/globals";
+import IfcStepParser from "../../ifc/ifc_step_parser.js";
+import ParsingBuffer from "../../parsing/parsing_buffer.js";
+import { ParseResult } from "./step_parser.js";
+const parser = IfcStepParser.Instance;
+// The middle record carries the bare INF. The records around it are ordinary,
+// and they are the ones the stamping loop used to overwrite - the bug is not
+// in how the INF record itself is read, it is in what reading it does to
+// everything already indexed.
+// The express IDs under test, kept in one place so the assertions read as
+// "the IDs written in the source", which is exactly what the bug destroyed.
+const BEFORE_ID = 11;
+const INF_ID = 22;
+const AFTER_ID = 33;
+const EXPECTED_IDS = [BEFORE_ID, INF_ID, AFTER_ID];
+// One template, one substitution point. Derived with String.replace on a
+// whitespace-exact literal, the controls below would silently become copies of
+// the INF case the moment anyone reflowed the source - replace() returns its
+// input unchanged when the token is absent - and "indexes the same as the
+// equivalent record with a real" would degrade to expect(x).toEqual(x), which
+// passes even with the bug reinstated.
+const VALUE_SLOT = "<<VALUE>>";
+const TEMPLATE = [
+    `#${BEFORE_ID}= IFCQUANTITYLENGTH('before',$,$,1.5,$);`,
+    `#${INF_ID}= IFCQUANTITYLENGTH('unbounded',$,$,${VALUE_SLOT},$);`,
+    `#${AFTER_ID}= IFCQUANTITYLENGTH('after',$,$,2.5,$);`,
+].join("\n");
+/**
+ * Build the fixture with a given value in the middle record's 4th attribute.
+ *
+ * @param value The value text to substitute.
+ * @return {string} The fixture source.
+ */
+function withValue(value) {
+    if (!TEMPLATE.includes(VALUE_SLOT)) {
+        throw new Error("fixture template lost its substitution slot");
+    }
+    return TEMPLATE.replace(VALUE_SLOT, value);
+}
+// Leading whitespace preserved from the real export, since it is what puts an
+// identifier-like token where an attribute is expected.
+const WITH_INF = withValue("          INF");
+// The control: whatever the index looks like with an ordinary real is what the
+// INF version has to match.
+const WITHOUT_INF = withValue("3.5");
+// The same export writes `-INF` for the opposite bound. Also a CONTROL, not a
+// second case of the bug: a leading '-' is dispatched as a number, so it never
+// reaches the inline-instance recovery and was never affected. Kept so that
+// stays visible - the defect is specific to the bare identifier-like form, and
+// anyone reading INF handling should not assume both directions went through
+// it.
+const WITH_NEGATIVE_INF = withValue("         -INF");
+/**
+ * Parse a data block and return each top-level entry's express ID, in order.
+ *
+ * @param source The STEP text to parse.
+ * @return {number[]} Express IDs as indexed.
+ */
+function indexedExpressIDs(source) {
+    const input = new ParsingBuffer(new TextEncoder().encode(source));
+    const [index, result] = parser.parseDataBlock(input);
+    // INCOMPLETE is the expected result for a bare run of records with no
+    // ENDSEC; terminator - what matters here is that it is not a syntax error.
+    expect([ParseResult.COMPLETE, ParseResult.INCOMPLETE]).toContain(result);
+    return index.elements.map((element) => element.expressID);
+}
+describe("a bare INF attribute", () => {
+    test("does not stamp its express ID over the records before it", () => {
+        expect(indexedExpressIDs(WITH_INF)).toEqual(EXPECTED_IDS);
+    });
+    test("indexes the same as the equivalent record with a real", () => {
+        expect(indexedExpressIDs(WITH_INF))
+            .toEqual(indexedExpressIDs(WITHOUT_INF));
+    });
+    // Passes with or without the fix, by design - see WITH_NEGATIVE_INF above.
+    test("negative INF is dispatched as a number and never took this path", () => {
+        expect(indexedExpressIDs(WITH_NEGATIVE_INF)).toEqual(EXPECTED_IDS);
+    });
+    // The whole file has to remain resolvable, not just the index array: a
+    // corrupted express ID column makes getElementByExpressID hand back the
+    // wrong record, which is how this surfaced as relationship failures rather
+    // than as a parse error.
+    test("every record is still reachable by its own express ID", () => {
+        const [result, model] = parser.parseDataToModel(new ParsingBuffer(new TextEncoder().encode(WITH_INF)));
+        expect([ParseResult.COMPLETE, ParseResult.INCOMPLETE]).toContain(result);
+        expect(model).not.toBeUndefined();
+        for (const expressID of EXPECTED_IDS) {
+            const element = model?.getElementByExpressID(expressID);
+            expect(element).not.toBeUndefined();
+            expect(element?.expressID).toBe(expressID);
+        }
+    });
+});

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

@@ -0,0 +1,124 @@
+import { StepTypeIndexer } from "../indexing/step_type_indexer.js";
+import { StepEntityConstructorAbstract } from "../step_entity_constructor.js";
+import { ColumnarIndexSink } from "./columnar_index.js";
+/**
+ * A type index over the records parsed **so far** (M2, issue #393): the same
+ * membership the finished model exposes as `typeIndex`, available while the
+ * streaming parse is still running.
+ *
+ * It is a *derivation over the columnar index*, not a consumer of the
+ * per-record event stream — deliberately, and this is the M2 design decision
+ * that the 2026-08-18 spike settled (`scripts/m2_consumer_spike.mjs`; issue
+ * #393 for the tables). Pushing every record into per-type `Set`s cost +88 %
+ * of parse wall-clock and +254 MB on PSB (9.4 M records) and *still* produced
+ * the wrong answer — 83 concrete types against the production indexer's 95,
+ * because complex records arrive on the event stream as `typeID 0` with their
+ * mapped classes stripped. Rebuilding from a prefix snapshot through
+ * {@link StepTypeIndexer.createFromColumns} instead costs 121 ms on the same
+ * file, sees the complex entries' mapped subtypes, and is membership-identical
+ * to the finished model's index by construction — it is literally the same
+ * indexer call the model makes.
+ *
+ * The consequence for callers is that incrementality is a **cadence knob**
+ * rather than an architecture. Nothing happens per record; a rebuild happens
+ * when someone asks for a view that is more than `growthFactor` stale (14
+ * rebuilds over a PSB parse at the default 2.0, +7.2 % if you query
+ * continuously, ~0 if you query rarely). Callers that want a specific moment —
+ * a preview generation, a progress tick — call {@link refresh} themselves.
+ *
+ * Two regimes, and the boundary matters: at or below `minimumRecords` a
+ * rebuild is trivial, so every query with new records behind it rebuilds and
+ * the view is exact; above it, growth pacing applies and a query may see a
+ * view up to `growthFactor` stale. The staleness a caller can observe is
+ * therefore bounded by the growth factor — never by whatever prefix happened
+ * to be current the first time it asked.
+ *
+ * Queries are only ever answered from a built index, so a caller that has
+ * never queried has paid nothing.
+ */
+export declare class PrefixTypeIndex<TypeIDType extends number> {
+    private readonly sink_;
+    private readonly indexer_;
+    private index_;
+    private columns_;
+    private builtAtRecords_;
+    private generation_;
+    private readonly growthFactor_;
+    private readonly minimumRecords_;
+    /**
+     * @param sink_ The sink the streaming parse is filling. Held live: each
+     * rebuild takes a fresh {@link ColumnarIndexSink.snapshot} of it.
+     * @param indexer_ The schema's type indexer — the same instance kind the
+     * model builds its own `typeIndex` with, which is what makes the two
+     * membership-identical.
+     * @param options Rebuild pacing.
+     * @param options.growthFactor How much the record count must grow past the
+     * last build before a query rebuilds (default 2.0).
+     * @param options.minimumRecords The record count below which growth pacing
+     * is skipped — small parses just rebuild.
+     */
+    constructor(sink_: ColumnarIndexSink<TypeIDType>, indexer_: StepTypeIndexer<TypeIDType>, options?: {
+        growthFactor?: number;
+        minimumRecords?: number;
+    });
+    /**
+     * How many rebuilds have happened. A caller pacing its own UI can use this
+     * to tell a genuinely new view from a repeat query.
+     *
+     * @return {number} The generation counter, 0 before the first build.
+     */
+    get generation(): number;
+    /**
+     * The record count the current view was built at (0 if never built) — not
+     * the parse's current count, which is `sink.count`.
+     *
+     * @return {number} Records covered by the current view.
+     */
+    get recordCount(): number;
+    /**
+     * Rebuild the view over everything parsed so far, unconditionally. This is
+     * the expensive call — O(records) — and it is the caller's choice of when.
+     */
+    refresh(): void;
+    /**
+     * Rebuild only if the parse has moved far enough past the current view (or
+     * there is no view yet). Every query goes through this.
+     */
+    private ensureFresh;
+    /**
+     * The distinct types present in the current view, including the mapped
+     * classes of complex entries.
+     *
+     * @return {IterableIterator<TypeIDType>} The types.
+     */
+    types(): IterableIterator<TypeIDType>;
+    /**
+     * Express IDs of every record of the given types (subtype closures unioned
+     * via the generated `query`, conway #383) among the records parsed so far.
+     *
+     * @param types The entity constructors to query.
+     * @return {IterableIterator<number>} Matching express IDs, in parse order.
+     * @yields {number} Each matching express ID.
+     */
+    expressIDsOfTypes(...types: StepEntityConstructorAbstract<TypeIDType>[]): IterableIterator<number>;
+    /**
+     * Express IDs of records whose concrete (or mapped) type is one of the
+     * given raw type IDs — no subtype expansion. The closure-expanding
+     * {@link expressIDsOfTypes} is the caller-facing form; this is for callers
+     * that already hold type IDs.
+     *
+     * @param typeIDs The raw type IDs to union.
+     * @return {IterableIterator<number>} Matching express IDs, in parse order.
+     * @yields {number} Each matching express ID.
+     */
+    expressIDsOfTypeIDs(...typeIDs: TypeIDType[]): IterableIterator<number>;
+    /**
+     * Upper-bound count of records of the given types in the current view (see
+     * {@link MultiIndexSet.count} for why it is an upper bound).
+     *
+     * @param types The entity constructors to count.
+     * @return {number} The count.
+     */
+    count(...types: StepEntityConstructorAbstract<TypeIDType>[]): number;
+}
+//# sourceMappingURL=prefix_type_index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefix_type_index.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/prefix_type_index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAA;AAC1E,OAAO,EAAE,iBAAiB,EAAoB,MAAM,kBAAkB,CAAA;AAUtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,eAAe,CAAC,UAAU,SAAS,MAAM;IA2BlD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IA1B3B,OAAO,CAAC,MAAM,CAAgD;IAE9D,OAAO,CAAC,QAAQ,CAAmD;IAEnE,OAAO,CAAC,eAAe,CAAI;IAE3B,OAAO,CAAC,WAAW,CAAI;IAEvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IAEtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IAExC;;;;;;;;;;;OAWG;gBAEgB,KAAK,EAAE,iBAAiB,CAAC,UAAU,CAAC,EACpC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,EACtD,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAM9D;;;;;OAKG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACI,OAAO,IAAI,IAAI;IAOtB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAqCnB;;;;;OAKG;IACI,KAAK,IAAI,gBAAgB,CAAC,UAAU,CAAC;IAM5C;;;;;;;OAOG;IACK,iBAAiB,CACrB,GAAG,KAAK,EAAE,6BAA6B,CAAC,UAAU,CAAC,EAAE,GACrD,gBAAgB,CAAC,MAAM,CAAC;IAS5B;;;;;;;;;OASG;IACK,mBAAmB,CAAE,GAAG,OAAO,EAAE,UAAU,EAAE,GAAI,gBAAgB,CAAC,MAAM,CAAC;IAuCjF;;;;;;OAMG;IACI,KAAK,CAAE,GAAG,KAAK,EAAE,6BAA6B,CAAC,UAAU,CAAC,EAAE,GAAI,MAAM;CAS9E"}

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

@@ -0,0 +1,207 @@
+import { extractOneHotLow } from "../../indexing/bit_operations.js";
+/** Default record growth between automatic rebuilds — see the class docs. */
+const DEFAULT_GROWTH_FACTOR = 2;
+/** Below this many records a rebuild is cheap enough not to bother pacing. */
+const DEFAULT_MINIMUM_RECORDS = 1024;
+/**
+ * A type index over the records parsed **so far** (M2, issue #393): the same
+ * membership the finished model exposes as `typeIndex`, available while the
+ * streaming parse is still running.
+ *
+ * It is a *derivation over the columnar index*, not a consumer of the
+ * per-record event stream — deliberately, and this is the M2 design decision
+ * that the 2026-08-18 spike settled (`scripts/m2_consumer_spike.mjs`; issue
+ * #393 for the tables). Pushing every record into per-type `Set`s cost +88 %
+ * of parse wall-clock and +254 MB on PSB (9.4 M records) and *still* produced
+ * the wrong answer — 83 concrete types against the production indexer's 95,
+ * because complex records arrive on the event stream as `typeID 0` with their
+ * mapped classes stripped. Rebuilding from a prefix snapshot through
+ * {@link StepTypeIndexer.createFromColumns} instead costs 121 ms on the same
+ * file, sees the complex entries' mapped subtypes, and is membership-identical
+ * to the finished model's index by construction — it is literally the same
+ * indexer call the model makes.
+ *
+ * The consequence for callers is that incrementality is a **cadence knob**
+ * rather than an architecture. Nothing happens per record; a rebuild happens
+ * when someone asks for a view that is more than `growthFactor` stale (14
+ * rebuilds over a PSB parse at the default 2.0, +7.2 % if you query
+ * continuously, ~0 if you query rarely). Callers that want a specific moment —
+ * a preview generation, a progress tick — call {@link refresh} themselves.
+ *
+ * Two regimes, and the boundary matters: at or below `minimumRecords` a
+ * rebuild is trivial, so every query with new records behind it rebuilds and
+ * the view is exact; above it, growth pacing applies and a query may see a
+ * view up to `growthFactor` stale. The staleness a caller can observe is
+ * therefore bounded by the growth factor — never by whatever prefix happened
+ * to be current the first time it asked.
+ *
+ * Queries are only ever answered from a built index, so a caller that has
+ * never queried has paid nothing.
+ */
+export class PrefixTypeIndex {
+    /**
+     * @param sink_ The sink the streaming parse is filling. Held live: each
+     * rebuild takes a fresh {@link ColumnarIndexSink.snapshot} of it.
+     * @param indexer_ The schema's type indexer — the same instance kind the
+     * model builds its own `typeIndex` with, which is what makes the two
+     * membership-identical.
+     * @param options Rebuild pacing.
+     * @param options.growthFactor How much the record count must grow past the
+     * last build before a query rebuilds (default 2.0).
+     * @param options.minimumRecords The record count below which growth pacing
+     * is skipped — small parses just rebuild.
+     */
+    constructor(sink_, indexer_, options) {
+        this.sink_ = sink_;
+        this.indexer_ = indexer_;
+        this.index_ = void 0;
+        this.columns_ = void 0;
+        this.builtAtRecords_ = 0;
+        this.generation_ = 0;
+        this.growthFactor_ = options?.growthFactor ?? DEFAULT_GROWTH_FACTOR;
+        this.minimumRecords_ = options?.minimumRecords ?? DEFAULT_MINIMUM_RECORDS;
+    }
+    /**
+     * How many rebuilds have happened. A caller pacing its own UI can use this
+     * to tell a genuinely new view from a repeat query.
+     *
+     * @return {number} The generation counter, 0 before the first build.
+     */
+    get generation() {
+        return this.generation_;
+    }
+    /**
+     * The record count the current view was built at (0 if never built) — not
+     * the parse's current count, which is `sink.count`.
+     *
+     * @return {number} Records covered by the current view.
+     */
+    get recordCount() {
+        return this.builtAtRecords_;
+    }
+    /**
+     * Rebuild the view over everything parsed so far, unconditionally. This is
+     * the expensive call — O(records) — and it is the caller's choice of when.
+     */
+    refresh() {
+        this.columns_ = this.sink_.snapshot();
+        this.index_ = this.indexer_.createFromColumns(this.columns_);
+        this.builtAtRecords_ = this.sink_.topLevelCount;
+        ++this.generation_;
+    }
+    /**
+     * Rebuild only if the parse has moved far enough past the current view (or
+     * there is no view yet). Every query goes through this.
+     */
+    ensureFresh() {
+        const parsed = this.sink_.topLevelCount;
+        if (this.index_ === void 0) {
+            this.refresh();
+            return;
+        }
+        // A count that went BACKWARDS means the sink was reset — the streaming
+        // builder's grow-and-restart. The current view then describes records the
+        // restarted parse has not reached again, and growth pacing would never
+        // catch it (the new parse may finish below the old threshold), so it is
+        // rebuilt immediately rather than paced.
+        if (parsed < this.builtAtRecords_) {
+            this.refresh();
+            return;
+        }
+        if (parsed === this.builtAtRecords_) {
+            return;
+        }
+        // Below the minimum a rebuild is trivial, so the view is kept exact:
+        // pacing here would buy nothing, and — because the threshold is absolute
+        // rather than relative to the last build — it would freeze a small file's
+        // view at whatever prefix happened to be current when it was first
+        // queried, permanently, including after the parse finishes.
+        if (parsed <= this.minimumRecords_) {
+            this.refresh();
+            return;
+        }
+        if (parsed >= this.builtAtRecords_ * this.growthFactor_) {
+            this.refresh();
+        }
+    }
+    /**
+     * The distinct types present in the current view, including the mapped
+     * classes of complex entries.
+     *
+     * @return {IterableIterator<TypeIDType>} The types.
+     */
+    types() {
+        this.ensureFresh();
+        return this.index_.types();
+    }
+    /**
+     * Express IDs of every record of the given types (subtype closures unioned
+     * via the generated `query`, conway #383) among the records parsed so far.
+     *
+     * @param types The entity constructors to query.
+     * @return {IterableIterator<number>} Matching express IDs, in parse order.
+     * @yields {number} Each matching express ID.
+     */
+    *expressIDsOfTypes(...types) {
+        const distinct = types.length === 1 ?
+            types[0].query :
+            new Set(types.flatMap((type) => type.query));
+        yield* this.expressIDsOfTypeIDs(...distinct);
+    }
+    /**
+     * Express IDs of records whose concrete (or mapped) type is one of the
+     * given raw type IDs — no subtype expansion. The closure-expanding
+     * {@link expressIDsOfTypes} is the caller-facing form; this is for callers
+     * that already hold type IDs.
+     *
+     * @param typeIDs The raw type IDs to union.
+     * @return {IterableIterator<number>} Matching express IDs, in parse order.
+     * @yields {number} Each matching express ID.
+     */
+    *expressIDsOfTypeIDs(...typeIDs) {
+        this.ensureFresh();
+        const columns = this.columns_;
+        const expressIDs = columns.expressID;
+        const firstInlineElement = columns.firstInlineElement;
+        const cursor = this.index_.cursor(...typeIDs);
+        // Cursors are pooled, and a generator can be abandoned mid-iteration (a
+        // `break`, a `find`), so the release has to survive early exit — hence
+        // try/finally rather than a free() after the loop. Mirrors
+        // StepModelBase.expressIDsOfTypes, which this is the prefix twin of; a
+        // live consumer querying every generation would otherwise churn a cursor
+        // per query for the pool's whole lifetime.
+        try {
+            while (cursor.step()) {
+                const high = cursor.high;
+                let low = cursor.low;
+                while (low !== 0) {
+                    const lowestOneHot = extractOneHotLow(low);
+                    low ^= (1 << lowestOneHot);
+                    const localID = high | lowestOneHot;
+                    // Inline entities carry no express ID — the same guard the model's
+                    // expressIDsOfTypes applies over its own columns.
+                    if (localID < firstInlineElement) {
+                        yield expressIDs[localID];
+                    }
+                }
+            }
+        }
+        finally {
+            cursor.free();
+        }
+    }
+    /**
+     * Upper-bound count of records of the given types in the current view (see
+     * {@link MultiIndexSet.count} for why it is an upper bound).
+     *
+     * @param types The entity constructors to count.
+     * @return {number} The count.
+     */
+    count(...types) {
+        this.ensureFresh();
+        const distinct = types.length === 1 ?
+            types[0].query :
+            [...new Set(types.flatMap((type) => type.query))];
+        return this.index_.count(...distinct);
+    }
+}

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

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

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

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