@bldrs-ai/conway 1.389.1221 → 1.394.1504

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

@@ -1 +1 @@
-{"version":3,"file":"decode_utf8.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/decode_utf8.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA+BH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEnD;AAID;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAqBtD"}
+{"version":3,"file":"decode_utf8.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/decode_utf8.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA+BH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEnD;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAczD;AAID;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAqBtD"}

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

@@ -54,6 +54,34 @@ function copyOutOfResizable(view) {
 export function decodeUtf8(view) {
     return decoder.decode(decodeNeedsCopy(view.buffer) ? view.slice() : view);
 }
+const strictUtf8Decoder = new TextDecoder('utf-8', { fatal: true });
+/**
+ * Decode the raw byte run of a STEP string literal.
+ *
+ * ISO 10303-21 says raw (non-\X\-escaped) bytes are ISO 8859-1, but modern
+ * exporters routinely write UTF-8 (and some, like Onshape's ST-Developer,
+ * write outright invalid sequences). The lenient default decoder mapped every
+ * non-UTF-8 byte to U+FFFD, so a spec-conformant latin-1 'Küche' surfaced as
+ * 'K�che' in product names and titles. Decode as strict UTF-8 first (the
+ * common modern case, and unambiguous when it validates), and fall back to
+ * exact ISO 8859-1 (byte = code point, which cannot fail) when it doesn't.
+ *
+ * @param view The bytes of the string literal's raw run.
+ * @return The decoded string.
+ */
+export function decodeStepString(view) {
+    const bytes = decodeNeedsCopy(view.buffer) ? view.slice() : view;
+    try {
+        return strictUtf8Decoder.decode(bytes);
+    }
+    catch {
+        let result = '';
+        for (let where = 0; where < bytes.length; ++where) {
+            result += String.fromCharCode(bytes[where]);
+        }
+        return result;
+    }
+}
 let shimInstalled = false;
 /**
  * Install a global, idempotent `TextDecoder.prototype.decode` shim that copies a

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

@@ -0,0 +1,20 @@
+/**
+ * Lexical scan of a STEP record for `#<expressID>` references.
+ *
+ * Used to prefetch the source-byte closure a windowed extract will
+ * acquire: walking typed attributes requires those records to already
+ * be resident, so the walk has to happen on the raw text. Strings
+ * (`'...'` with `''` escapes), binary blobs (`"..."`) and C-style
+ * comments are skipped so a hash inside a string is not a ref.
+ */
+/**
+ * Collect the distinct express IDs referenced from a STEP record's
+ * bytes. Order is first-seen; `#0` is ignored (not a real entity).
+ *
+ * @param bytes The record text (or a view containing it).
+ * @param from Start offset within `bytes`.
+ * @param length Number of bytes to scan.
+ * @return {number[]} Distinct referenced express IDs.
+ */
+export declare function scanExpressRefs(bytes: Uint8Array, from?: number, length?: number): number[];
+//# sourceMappingURL=express_ref_scan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"express_ref_scan.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/express_ref_scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,MAAU,EAAE,MAAM,GAAE,MAA4B,GAAI,MAAM,EAAE,CA8DxF"}

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

@@ -0,0 +1,91 @@
+/**
+ * Lexical scan of a STEP record for `#<expressID>` references.
+ *
+ * Used to prefetch the source-byte closure a windowed extract will
+ * acquire: walking typed attributes requires those records to already
+ * be resident, so the walk has to happen on the raw text. Strings
+ * (`'...'` with `''` escapes), binary blobs (`"..."`) and C-style
+ * comments are skipped so a hash inside a string is not a ref.
+ */
+const HASH = 0x23;
+const QUOTE = 0x27;
+const DQUOTE = 0x22;
+const ZERO = 0x30;
+const NINE = 0x39;
+const SLASH = 0x2F;
+const STAR = 0x2A;
+/**
+ * Collect the distinct express IDs referenced from a STEP record's
+ * bytes. Order is first-seen; `#0` is ignored (not a real entity).
+ *
+ * @param bytes The record text (or a view containing it).
+ * @param from Start offset within `bytes`.
+ * @param length Number of bytes to scan.
+ * @return {number[]} Distinct referenced express IDs.
+ */
+export function scanExpressRefs(bytes, from = 0, length = bytes.length - from) {
+    const refs = [];
+    const seen = new Set();
+    const end = Math.min(from + length, bytes.length);
+    let cursor = from;
+    while (cursor < end) {
+        const byte = bytes[cursor];
+        if (byte === QUOTE) {
+            cursor = skipQuoted_(bytes, cursor + 1, end, QUOTE, true);
+            continue;
+        }
+        if (byte === DQUOTE) {
+            cursor = skipQuoted_(bytes, cursor + 1, end, DQUOTE, false);
+            continue;
+        }
+        if (byte === SLASH && cursor + 1 < end && bytes[cursor + 1] === STAR) {
+            cursor += 2;
+            while (cursor + 1 < end &&
+                !(bytes[cursor] === STAR && bytes[cursor + 1] === SLASH)) {
+                ++cursor;
+            }
+            cursor += 2;
+            continue;
+        }
+        if (byte === HASH) {
+            let value = 0;
+            let digit = cursor + 1;
+            while (digit < end && bytes[digit] >= ZERO && bytes[digit] <= NINE) {
+                value = (value * 10) + (bytes[digit] - ZERO);
+                ++digit;
+            }
+            if (digit > cursor + 1 && value !== 0 && !seen.has(value)) {
+                seen.add(value);
+                refs.push(value);
+            }
+            cursor = digit;
+            continue;
+        }
+        ++cursor;
+    }
+    return refs;
+}
+/**
+ * Advance past a quoted span that started just before `from`.
+ *
+ * @param bytes Source bytes.
+ * @param from First byte after the opening quote.
+ * @param end Exclusive scan limit.
+ * @param quote The quote byte to match.
+ * @param doubledEscape True for STEP strings (`''` is one quote).
+ * @return {number} Index just after the closing quote (or `end`).
+ */
+function skipQuoted_(bytes, from, end, quote, doubledEscape) {
+    let cursor = from;
+    while (cursor < end) {
+        if (bytes[cursor] === quote) {
+            if (doubledEscape && cursor + 1 < end && bytes[cursor + 1] === quote) {
+                cursor += 2;
+                continue;
+            }
+            return cursor + 1;
+        }
+        ++cursor;
+    }
+    return end;
+}

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

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

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

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

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

@@ -0,0 +1,28 @@
+/* eslint-disable no-magic-numbers */
+import { describe, expect, test } from "@jest/globals";
+import { scanExpressRefs } from "./express_ref_scan.js";
+/**
+ * @param text STEP text to scan.
+ * @return {number[]} Referenced express IDs.
+ */
+function scan(text) {
+    return scanExpressRefs(new TextEncoder().encode(text));
+}
+describe("scanExpressRefs", () => {
+    test("collects distinct #ids in first-seen order", () => {
+        expect(scan("#10=IFCWALL(#20,#20,#30);")).toEqual([10, 20, 30]);
+    });
+    test("ignores hashes inside STEP strings and doubled quotes", () => {
+        expect(scan("#1=IFCLABEL('door #99 is fine');#2=IFCNAME('it''s #8');"))
+            .toEqual([1, 2]);
+    });
+    test("ignores hashes inside binary blobs", () => {
+        expect(scan("#1=IFCBLOB(\"#99DEAD\");")).toEqual([1]);
+    });
+    test("ignores hashes inside comments", () => {
+        expect(scan("#1=IFCWALL(/* see #99 */#2);")).toEqual([1, 2]);
+    });
+    test("skips #0", () => {
+        expect(scan("#1=IFCWALL(#0,#2);")).toEqual([1, 2]);
+    });
+});

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

@@ -0,0 +1,81 @@
+import { StepIndexColumns } from "./columnar_index.js";
+import { StepIndexEntry } from "./step_parser.js";
+/**
+ * The decoded sidecar: the source identity it was built against, plus the
+ * reconstructed top-level element index.
+ */
+export interface DecodedSidecar<TypeIDType extends number> {
+    version: number;
+    sourceByteLength: number;
+    sourceHash: number;
+    elements: StepIndexEntry<TypeIDType>[];
+    /**
+     * True for records the sidecar under-describes (they had inline / multi
+     * children the v1 format doesn't serialise). Same order as `elements`.
+     */
+    hasChildren: boolean[];
+}
+/**
+ * A placeholder strong-ish hash of the source bytes (FNV-1a, 32-bit). Stands
+ * in for a production digest (SHA-256); only the fixed slot matters to the
+ * format. Sufficient to demonstrate the mismatch → cold-scan handshake.
+ *
+ * @param source The source bytes.
+ * @return {number} A 32-bit unsigned hash.
+ */
+export declare function hashSource(source: Uint8Array): number;
+/**
+ * Serialise a model's top-level element index to a sidecar blob.
+ *
+ * @param elements The top-level element index.
+ * @param sourceByteLength The length of the source it was built from.
+ * @param sourceHash The source hash (see {@link hashSource}).
+ * @return {Uint8Array} The sidecar bytes.
+ */
+export declare function serializeIndexSidecar<TypeIDType extends number>(elements: StepIndexEntry<TypeIDType>[], sourceByteLength: number, sourceHash: number): Uint8Array;
+/**
+ * Deserialise a sidecar blob back to the top-level element index.
+ *
+ * @param bytes The sidecar bytes.
+ * @return {DecodedSidecar} The decoded source identity + element index.
+ */
+export declare function deserializeIndexSidecar<TypeIDType extends number>(bytes: Uint8Array): DecodedSidecar<TypeIDType>;
+/**
+ * Serialise a columnar index (M7) to a sidecar blob — same format as
+ * {@link serializeIndexSidecar}, byte for byte, but read straight off the SoA
+ * columns so no object index is needed. Only the top-level range is carried
+ * (the v1 format; inline rows re-materialise from record bytes on demand).
+ *
+ * @param columns The columnar index.
+ * @param sourceByteLength The length of the source it was built from.
+ * @param sourceHash The source hash (see {@link hashSource}).
+ * @return {Uint8Array} The sidecar bytes.
+ */
+export declare function serializeIndexSidecarFromColumns<TypeIDType extends number>(columns: StepIndexColumns<TypeIDType>, sourceByteLength: number, sourceHash: number): Uint8Array;
+/**
+ * Deserialise a sidecar blob straight to a columnar index (M7) — the
+ * index-first open path: no per-record objects at any point between the
+ * sidecar bytes and a constructed model. Top-level rows only (v1 sidecars
+ * carry no inline rows), so `count === firstInlineElement`.
+ *
+ * @param bytes The sidecar bytes.
+ * @return {{ sourceByteLength: number, sourceHash: number,
+ *  columns: StepIndexColumns }} Source identity + the columnar index.
+ */
+export declare function deserializeIndexSidecarToColumns<TypeIDType extends number>(bytes: Uint8Array): {
+    sourceByteLength: number;
+    sourceHash: number;
+    columns: StepIndexColumns<TypeIDType>;
+};
+/**
+ * Validate a decoded sidecar against the actual source identity. The
+ * index-first open path calls this before trusting the sidecar; on false it
+ * must fall back to a cold scan.
+ *
+ * @param sidecar The decoded sidecar.
+ * @param sourceByteLength The actual source length.
+ * @param sourceHash The actual source hash.
+ * @return {boolean} True if the sidecar matches the source.
+ */
+export declare function sidecarMatchesSource<TypeIDType extends number>(sidecar: DecodedSidecar<TypeIDType>, sourceByteLength: number, sourceHash: number): boolean;
+//# sourceMappingURL=index_sidecar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index_sidecar.d.ts","sourceRoot":"","sources":["../../../../src/step/parsing/index_sidecar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AA0D9C;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,UAAU,SAAS,MAAM;IACvD,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,CAAA;IAEtC;;;OAGG;IACH,WAAW,EAAE,OAAO,EAAE,CAAA;CACvB;AAGD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAI,MAAM,CASvD;AAGD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,SAAS,MAAM,EAC3D,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,EACtC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GAAI,UAAU,CAsCnC;AAGD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,SAAS,MAAM,EAC7D,KAAK,EAAE,UAAU,GAAI,cAAc,CAAC,UAAU,CAAC,CA0ClD;AAGD;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,SAAS,MAAM,EACtE,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,EACrC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GAAI,UAAU,CAkCnC;AAGD;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,SAAS,MAAM,EACtE,KAAK,EAAE,UAAU,GAAI;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACvC,CA+DA;AAGD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,SAAS,MAAM,EAC1D,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,EACnC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GAAI,OAAO,CAIhC"}

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

@@ -0,0 +1,283 @@
+/**
+ * Index sidecar (M4): a compact, version-stamped binary serialisation of a
+ * model's parse index, so a revisit (or a first visit with a server-provided
+ * sidecar) can open **index-first** — reconstruct the entity index without
+ * re-scanning the source, then fetch only the byte ranges demand asks for
+ * (see RangeByteSource).
+ *
+ * Layout (all little-endian):
+ *
+ *   'CIDX'            4  magic
+ *   version           u32
+ *   sourceByteLength  f64  (length of the source the index was built from)
+ *   sourceHash        u32  (hash of the source bytes — the handshake)
+ *   recordCount       u32
+ *   address[]         f64 × recordCount  (file-absolute; f64 tolerates >4 GB)
+ *   length[]          u32 × recordCount
+ *   typeID[]          i32 × recordCount  (−1 = undefined type)
+ *   expressID[]       u32 × recordCount
+ *
+ * This carries the top-level record columns — enough to answer type/express
+ * queries and locate every record's bytes. Inline / multi-mapping child
+ * serialisation is a v2 extension (records with children re-materialise their
+ * children from the record bytes on demand); `hasChildren` flags which
+ * records the sidecar under-describes so a consumer can fall back for them.
+ *
+ * The sidecar is a **cache, not an interchange format**: it is only trusted
+ * after `sourceHash` + `sourceByteLength` match the actual source. A mismatch
+ * means fall back to a cold scan — never serve wrong bytes. Production should
+ * swap the placeholder 32-bit hash for a strong digest (e.g. SHA-256); the
+ * format reserves a fixed slot so that is a version bump, not a reshape.
+ */
+const MAGIC = 0x58444943; // 'CIDX' little-endian
+const VERSION = 1;
+const UNDEFINED_TYPE = -1;
+// FNV-1a 32-bit parameters (see hashSource).
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+const HEX = 16;
+// Byte sizes of the fixed header fields, in order.
+const HEADER_BYTES = 4 + // magic
+    4 + // version
+    8 + // sourceByteLength (f64)
+    4 + // sourceHash (u32)
+    4; // recordCount (u32)
+const ADDRESS_BYTES = 8;
+const LENGTH_BYTES = 4;
+const TYPEID_BYTES = 4;
+const EXPRESSID_BYTES = 4;
+/**
+ * A placeholder strong-ish hash of the source bytes (FNV-1a, 32-bit). Stands
+ * in for a production digest (SHA-256); only the fixed slot matters to the
+ * format. Sufficient to demonstrate the mismatch → cold-scan handshake.
+ *
+ * @param source The source bytes.
+ * @return {number} A 32-bit unsigned hash.
+ */
+export function hashSource(source) {
+    let hash = FNV_OFFSET_BASIS >>> 0;
+    for (let where = 0; where < source.length; ++where) {
+        hash ^= source[where];
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash >>> 0;
+}
+/**
+ * Serialise a model's top-level element index to a sidecar blob.
+ *
+ * @param elements The top-level element index.
+ * @param sourceByteLength The length of the source it was built from.
+ * @param sourceHash The source hash (see {@link hashSource}).
+ * @return {Uint8Array} The sidecar bytes.
+ */
+export function serializeIndexSidecar(elements, sourceByteLength, sourceHash) {
+    const recordCount = elements.length;
+    const total = HEADER_BYTES +
+        recordCount * (ADDRESS_BYTES + LENGTH_BYTES + TYPEID_BYTES + EXPRESSID_BYTES);
+    const bytes = new Uint8Array(total);
+    const view = new DataView(bytes.buffer);
+    let offset = 0;
+    view.setUint32(offset, MAGIC, true);
+    offset += 4;
+    view.setUint32(offset, VERSION, true);
+    offset += 4;
+    view.setFloat64(offset, sourceByteLength, true);
+    offset += 8;
+    view.setUint32(offset, sourceHash >>> 0, true);
+    offset += 4;
+    view.setUint32(offset, recordCount, true);
+    offset += 4;
+    // Column-major: better compression locality than row-major, and it mirrors
+    // the SoA columns the model rebuilds.
+    for (const element of elements) {
+        view.setFloat64(offset, element.address, true);
+        offset += ADDRESS_BYTES;
+    }
+    for (const element of elements) {
+        view.setUint32(offset, element.length, true);
+        offset += LENGTH_BYTES;
+    }
+    for (const element of elements) {
+        const typeID = element.typeID;
+        view.setInt32(offset, typeID === void 0 ? UNDEFINED_TYPE : typeID, true);
+        offset += TYPEID_BYTES;
+    }
+    for (const element of elements) {
+        view.setUint32(offset, element.expressID, true);
+        offset += EXPRESSID_BYTES;
+    }
+    return bytes;
+}
+/**
+ * Deserialise a sidecar blob back to the top-level element index.
+ *
+ * @param bytes The sidecar bytes.
+ * @return {DecodedSidecar} The decoded source identity + element index.
+ */
+export function deserializeIndexSidecar(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let offset = 0;
+    const magic = view.getUint32(offset, true);
+    offset += 4;
+    if (magic !== MAGIC) {
+        throw new Error(`Not a sidecar: bad magic 0x${magic.toString(HEX)}`);
+    }
+    const version = view.getUint32(offset, true);
+    offset += 4;
+    if (version !== VERSION) {
+        throw new Error(`Unsupported sidecar version ${version}`);
+    }
+    const sourceByteLength = view.getFloat64(offset, true);
+    offset += 8;
+    const sourceHash = view.getUint32(offset, true);
+    offset += 4;
+    const recordCount = view.getUint32(offset, true);
+    offset += 4;
+    const addressBase = offset;
+    const lengthBase = addressBase + recordCount * ADDRESS_BYTES;
+    const typeIDBase = lengthBase + recordCount * LENGTH_BYTES;
+    const expressIDBase = typeIDBase + recordCount * TYPEID_BYTES;
+    const elements = new Array(recordCount);
+    const hasChildren = new Array(recordCount).fill(false);
+    for (let where = 0; where < recordCount; ++where) {
+        const typeID = view.getInt32(typeIDBase + where * TYPEID_BYTES, true);
+        elements[where] = {
+            address: view.getFloat64(addressBase + where * ADDRESS_BYTES, true),
+            length: view.getUint32(lengthBase + where * LENGTH_BYTES, true),
+            typeID: (typeID === UNDEFINED_TYPE ? void 0 : typeID),
+            expressID: view.getUint32(expressIDBase + where * EXPRESSID_BYTES, true),
+        };
+    }
+    return { version, sourceByteLength, sourceHash, elements, hasChildren };
+}
+/**
+ * Serialise a columnar index (M7) to a sidecar blob — same format as
+ * {@link serializeIndexSidecar}, byte for byte, but read straight off the SoA
+ * columns so no object index is needed. Only the top-level range is carried
+ * (the v1 format; inline rows re-materialise from record bytes on demand).
+ *
+ * @param columns The columnar index.
+ * @param sourceByteLength The length of the source it was built from.
+ * @param sourceHash The source hash (see {@link hashSource}).
+ * @return {Uint8Array} The sidecar bytes.
+ */
+export function serializeIndexSidecarFromColumns(columns, sourceByteLength, sourceHash) {
+    const recordCount = columns.firstInlineElement;
+    const total = HEADER_BYTES +
+        recordCount * (ADDRESS_BYTES + LENGTH_BYTES + TYPEID_BYTES + EXPRESSID_BYTES);
+    const bytes = new Uint8Array(total);
+    const view = new DataView(bytes.buffer);
+    let offset = 0;
+    view.setUint32(offset, MAGIC, true);
+    offset += 4;
+    view.setUint32(offset, VERSION, true);
+    offset += 4;
+    view.setFloat64(offset, sourceByteLength, true);
+    offset += 8;
+    view.setUint32(offset, sourceHash >>> 0, true);
+    offset += 4;
+    view.setUint32(offset, recordCount, true);
+    offset += 4;
+    for (let where = 0; where < recordCount; ++where) {
+        view.setFloat64(offset, columns.address[where], true);
+        offset += ADDRESS_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        view.setUint32(offset, columns.length[where], true);
+        offset += LENGTH_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        // The column already uses the sidecar's −1 sentinel for undefined.
+        view.setInt32(offset, columns.typeID[where], true);
+        offset += TYPEID_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        view.setUint32(offset, columns.expressID[where], true);
+        offset += EXPRESSID_BYTES;
+    }
+    return bytes;
+}
+/**
+ * Deserialise a sidecar blob straight to a columnar index (M7) — the
+ * index-first open path: no per-record objects at any point between the
+ * sidecar bytes and a constructed model. Top-level rows only (v1 sidecars
+ * carry no inline rows), so `count === firstInlineElement`.
+ *
+ * @param bytes The sidecar bytes.
+ * @return {{ sourceByteLength: number, sourceHash: number,
+ *  columns: StepIndexColumns }} Source identity + the columnar index.
+ */
+export function deserializeIndexSidecarToColumns(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let offset = 0;
+    const magic = view.getUint32(offset, true);
+    offset += 4;
+    if (magic !== MAGIC) {
+        throw new Error(`Not a sidecar: bad magic 0x${magic.toString(HEX)}`);
+    }
+    const version = view.getUint32(offset, true);
+    offset += 4;
+    if (version !== VERSION) {
+        throw new Error(`Unsupported sidecar version ${version}`);
+    }
+    const sourceByteLength = view.getFloat64(offset, true);
+    offset += 8;
+    const sourceHash = view.getUint32(offset, true);
+    offset += 4;
+    const recordCount = view.getUint32(offset, true);
+    offset += 4;
+    const address = new Uint32Array(recordCount);
+    const length = new Uint32Array(recordCount);
+    const typeID = new Int32Array(recordCount);
+    const expressID = new Uint32Array(recordCount);
+    let sorted = true;
+    let previous = 0;
+    for (let where = 0; where < recordCount; ++where) {
+        address[where] = view.getFloat64(offset, true);
+        offset += ADDRESS_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        length[where] = view.getUint32(offset, true);
+        offset += LENGTH_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        typeID[where] = view.getInt32(offset, true);
+        offset += TYPEID_BYTES;
+    }
+    for (let where = 0; where < recordCount; ++where) {
+        const id = view.getUint32(offset, true);
+        offset += EXPRESSID_BYTES;
+        expressID[where] = id;
+        if (id < previous) {
+            sorted = false;
+        }
+        previous = id;
+    }
+    return {
+        sourceByteLength,
+        sourceHash,
+        columns: {
+            address,
+            length,
+            typeID,
+            expressID,
+            count: recordCount,
+            firstInlineElement: recordCount,
+            expressIdsSorted: sorted,
+        },
+    };
+}
+/**
+ * Validate a decoded sidecar against the actual source identity. The
+ * index-first open path calls this before trusting the sidecar; on false it
+ * must fall back to a cold scan.
+ *
+ * @param sidecar The decoded sidecar.
+ * @param sourceByteLength The actual source length.
+ * @param sourceHash The actual source hash.
+ * @return {boolean} True if the sidecar matches the source.
+ */
+export function sidecarMatchesSource(sidecar, sourceByteLength, sourceHash) {
+    return sidecar.sourceByteLength === sourceByteLength &&
+        sidecar.sourceHash === (sourceHash >>> 0);
+}

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

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

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

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