@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/wire/from-wire.js

@@ -0,0 +1,1425 @@
+/**
+ * The wire decoder (design sections 4.5, 5.9, 9.1, 9.5 and 11.3): `fromWire()` rebuilds a snapshot
+ * from a WireSnapshot, and `decodeManifest()` is the shared reader the GSNP container functions of
+ * bytes.ts drive with their own buffer regions.
+ *
+ * Rules (design section 9.1): a manifest whose `formatVersion` is not the reader's or whose wire
+ * major is unknown is refused with E_UNSUPPORTED_VERSION; a newer wire minor is read by ignoring
+ * unknown manifest fields; an unknown column dtype is E_UNSUPPORTED unless `unknownColumns: "skip"`
+ * drops the column and names it in `meta.extra["graphty.skippedColumns"]`; an unknown id-map kind
+ * is always E_UNSUPPORTED; unknown view entries are ignored and recomputed. Every WireBufferRef is
+ * checked against its buffer before a typed array is built over it (E_BAD_SERIALIZATION with
+ * details.ref), whatever the validation level, because a RangeError from a typed-array constructor
+ * is never an acceptable failure mode; the "structure" and "full" levels add the checks of design
+ * section 9.5 and then run the snapshot's own validate().
+ *
+ * Buffers are adopted by reference by default: the arrays are views into the caller's buffers and
+ * the arena descriptor is honoured. A SharedArrayBuffer is copied (decision D-SAB), and `copy: true`
+ * copies every buffer before adoption.
+ */
+import { CORE_ORDER } from "../builder/arena.js";
+import { createColumn, emptyParts, isPlainObject, resolveColumnMeta } from "../columns/column.js";
+import { AttributeTable } from "../columns/table.js";
+import { ALIGNMENT, FORMAT_VERSION, MAX_COUNT, WIRE_FORMAT, WIRE_MAJOR } from "../constants.js";
+import { GraphFormatError } from "../errors.js";
+import { nodeIdMapFromTyped } from "../ids/node-id-map.js";
+import { checkUtf8Layout, decodeUtf8Rows, Utf8Store } from "../ids/string-store.js";
+import { createSnapshot, seedView } from "../snapshot/graph-snapshot.js";
+import { cooViewOf, edgeListViewOf, ReverseAdjacency, rowLengths } from "../snapshot/views.js";
+import { canViewAsPaddedU32, copyToPaddedStore, padTo4 } from "../util/typed-array.js";
+import { checkCooSrc, checkDegree, checkDegreeOrder, checkEdgeList, checkF64View, checkInDegree, checkMate, checkOutDegree, checkReverse, checkSelfLoopArcs, checkSelfLoopsPerNode, CoreFacts, } from "./carried-views.js";
+import { defineJsonKey } from "./to-wire.js";
+// ============================================================ vocabularies
+const WIRE_DTYPES = new Set(["u32", "i32", "f32", "f64", "u8", "utf8"]);
+const COLUMN_DTYPES = new Set([
+    "f32",
+    "f64",
+    "i32",
+    "u32",
+    "u8",
+    "bool",
+    "dict",
+    "string",
+    "list",
+    "json",
+]);
+const ID_MAP_KINDS = new Set(["identity", "dense", "numeric", "string", "mixed"]);
+const ID_TYPES = new Set(["string", "integer", "mixed"]);
+const TIME_FORMATS = new Set([
+    "integer",
+    "double",
+    "date",
+    "dateTime",
+]);
+const TIME_REPRESENTATIONS = new Set([
+    "interval",
+    "timestamp",
+]);
+const MODES = new Set(["static", "dynamic", "slice"]);
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const NUM_TAG = "$num";
+const ESC_TAG = "$esc";
+/** The deepest JSON nesting a manifest value may have; deeper input is refused instead of overflowing the stack. */
+const MAX_JSON_DEPTH = 256;
+/**
+ * A short plain-ASCII rendering of an untrusted manifest value for an error message: strings are
+ * quoted, everything else is named by type (a bigint or a null-prototype object cannot be
+ * stringified, and a structuredClone-delivered manifest can carry both).
+ * @param value - the value
+ * @returns the rendering
+ */
+function describe(value) {
+    if (typeof value === "string") {
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 37)}...` : value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null) {
+        return String(value);
+    }
+    return value === undefined ? "undefined" : `a ${typeof value}`;
+}
+/** The meta.extra key naming the columns dropped under unknownColumns: "skip" (design section 9.1). */
+export const SKIPPED_COLUMNS_KEY = "graphty.skippedColumns";
+// ============================================================ errors and shape readers
+/**
+ * The E_BAD_SERIALIZATION error of a malformed manifest member or buffer reference.
+ * @param ref - the manifest path, e.g. "nodeColumns[2].data"
+ * @param reason - what is wrong
+ * @param details - extra context
+ * @returns the error
+ */
+export function badWire(ref, reason, details = {}) {
+    return new GraphFormatError("E_BAD_SERIALIZATION", `${ref}: ${reason}`, { ref, reason, ...details });
+}
+function asObject(value, path) {
+    if (!isPlainObject(value)) {
+        throw badWire(path, "expected an object");
+    }
+    return value;
+}
+function asArray(value, path) {
+    if (!Array.isArray(value)) {
+        throw badWire(path, "expected an array");
+    }
+    return value;
+}
+function asString(value, path) {
+    if (typeof value !== "string") {
+        throw badWire(path, "expected a string");
+    }
+    return value;
+}
+function asStringOrNull(value, path) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return asString(value, path);
+}
+function asBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw badWire(path, "expected a boolean");
+    }
+    return value;
+}
+function asBooleanOrNull(value, path) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return asBoolean(value, path);
+}
+function asCount(value, path) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_COUNT) {
+        throw badWire(path, `expected an integer in [0, ${MAX_COUNT}]`, { found: value });
+    }
+    // JSON.parse("-0") is -0; a count is stored as 0 (design section 4.1)
+    return value === 0 ? 0 : value;
+}
+function asEnum(value, path, allowed) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "string" || !allowed.has(value)) {
+        throw badWire(path, `unexpected value ${describe(value)}`, { found: value });
+    }
+    return value;
+}
+/**
+ * Whether a string names a column dtype this reader knows.
+ * @param value - the dtype text
+ * @returns true for one of the ten dtypes
+ */
+function isKnownDtype(value) {
+    return typeof value === "string" && COLUMN_DTYPES.has(value);
+}
+// ============================================================ JSON values (5.9)
+/**
+ * Decode a manifest JSON value (design section 5.9): `{ "$num": "Infinity" | "-Infinity" | "NaN" |
+ * "-0" }` becomes the number, `{ "$esc": { ... } }` unwraps a user object whose only key collided
+ * with a tag (the writer's escape), arrays and plain objects are rebuilt recursively (a key named
+ * `__proto__`, `constructor` or `prototype` is refused), everything else is returned as is. Nesting
+ * deeper than MAX_JSON_DEPTH is E_BAD_SERIALIZATION rather than a stack overflow.
+ * @param value - the value from the manifest
+ * @param path - the manifest path for error messages
+ * @param depth - the current nesting depth
+ * @returns the decoded value
+ */
+export function decodeJsonValue(value, path, depth = 0) {
+    if (depth > MAX_JSON_DEPTH) {
+        throw badWire(path, `JSON nesting deeper than ${MAX_JSON_DEPTH}`, { reason: "nesting" });
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, i) => decodeJsonValue(item, `${path}[${i}]`, depth + 1));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === NUM_TAG) {
+        const tag = value[NUM_TAG];
+        switch (tag) {
+            case "NaN":
+                return Number.NaN;
+            case "Infinity":
+                return Infinity;
+            case "-Infinity":
+                return -Infinity;
+            case "-0":
+                return -0;
+            default:
+                throw badWire(path, `unknown number tag ${describe(tag)}`, { found: tag });
+        }
+    }
+    if (keys.length === 1 && keys[0] === ESC_TAG) {
+        const inner = value[ESC_TAG];
+        if (!isPlainObject(inner)) {
+            throw badWire(path, "an escaped object must hold a plain object", { found: typeof inner });
+        }
+        return decodeJsonObject(inner, path, depth);
+    }
+    return decodeJsonObject(value, path, depth);
+}
+/**
+ * Rebuild a plain object's members (no tag interpretation of the object itself).
+ * @param value - the plain object
+ * @param path - the manifest path
+ * @param depth - the nesting depth of the object
+ * @returns the rebuilt object
+ */
+function decodeJsonObject(value, path, depth) {
+    const out = {};
+    for (const key of Object.keys(value)) {
+        if (FORBIDDEN_KEYS.has(key)) {
+            throw badWire(path, `forbidden key "${key}"`, { key });
+        }
+        defineJsonKey(out, key, decodeJsonValue(value[key], `${path}.${key}`, depth + 1));
+    }
+    return out;
+}
+/**
+ * The JSON.parse reviver of design section 9.5: refuses the prototype-pollution keys.
+ * @param key - the property name being revived
+ * @param value - the revived value
+ * @returns the value unchanged
+ */
+function guardReviver(key, value) {
+    if (FORBIDDEN_KEYS.has(key)) {
+        throw badWire("manifest", `forbidden key "${key}"`, { key });
+    }
+    return value;
+}
+/**
+ * Parse JSON text from a container (the manifest or one json column row) with the guarding
+ * reviver. A syntax error is E_BAD_SERIALIZATION.
+ * @param text - the JSON text
+ * @param path - the manifest path for error messages
+ * @returns the parsed value
+ */
+export function parseGuardedJson(text, path) {
+    try {
+        return JSON.parse(text, guardReviver);
+    }
+    catch (err) {
+        if (err instanceof GraphFormatError) {
+            throw err;
+        }
+        throw badWire(path, `not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+}
+/**
+ * Apply defaults to FromWireOptions and reject values outside their documented sets (E_UNSUPPORTED).
+ * @param options - the caller's options
+ * @param defaultLevel - "structure" for fromWire, "full" for fromBytes
+ * @returns the resolved options
+ */
+export function resolveFromWireOptions(options, defaultLevel) {
+    const level = options?.validate ?? defaultLevel;
+    if (level !== "none" && level !== "structure" && level !== "full") {
+        throw new GraphFormatError("E_UNSUPPORTED", `unknown validation level ${String(level)}`, {
+            option: "validate",
+            found: level,
+        });
+    }
+    const unknownColumns = options?.unknownColumns ?? "error";
+    if (unknownColumns !== "error" && unknownColumns !== "skip") {
+        throw new GraphFormatError("E_UNSUPPORTED", `unknown unknownColumns policy ${String(unknownColumns)}`, {
+            option: "unknownColumns",
+            found: unknownColumns,
+        });
+    }
+    const copy = options?.copy ?? false;
+    if (typeof copy !== "boolean") {
+        throw new GraphFormatError("E_UNSUPPORTED", "copy must be a boolean", { option: "copy", found: copy });
+    }
+    return { level, copy, unknownColumns };
+}
+/**
+ * A region over one plain ArrayBuffer.
+ * @param buffer - the buffer
+ * @param base - the absolute byte offset of the region's start inside the buffer
+ * @param byteLength - the region's byte length
+ * @returns the region
+ */
+export function bufferRegion(buffer, base, byteLength) {
+    return {
+        byteLength,
+        locate(byteOffset) {
+            return { buffer, byteOffset: base + byteOffset };
+        },
+        read(byteOffset, length) {
+            const out = new Uint8Array(new ArrayBuffer(padTo4(length)), 0, length);
+            out.set(new Uint8Array(buffer, base + byteOffset, length));
+            return out;
+        },
+    };
+}
+/**
+ * Copy an ArrayBuffer or SharedArrayBuffer into a fresh ArrayBuffer.
+ * @param buffer - the source
+ * @returns the copy
+ */
+function copyBuffer(buffer) {
+    const out = new ArrayBuffer(buffer.byteLength);
+    new Uint8Array(out).set(new Uint8Array(buffer));
+    return out;
+}
+/**
+ * Whether a value is a SharedArrayBuffer (never adopted, decision D-SAB).
+ * @param value - the value
+ * @returns true for a SharedArrayBuffer
+ */
+export function isSharedArrayBuffer(value) {
+    return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
+}
+/**
+ * Bytes per element and constructor of a wire dtype.
+ * @param dtype - the wire dtype
+ * @returns the element size
+ */
+function wireElementSize(dtype) {
+    switch (dtype) {
+        case "u32":
+        case "i32":
+        case "f32":
+            return 4;
+        case "f64":
+            return 8;
+        case "u8":
+        case "utf8":
+            return 1;
+        default: {
+            const name = dtype;
+            throw badWire("dtype", `unknown wire dtype ${name}`, { dtype: name });
+        }
+    }
+}
+/**
+ * Build the typed array of a wire dtype over a buffer.
+ * @param dtype - the wire dtype
+ * @param buffer - the buffer
+ * @param byteOffset - the absolute start
+ * @param length - the element count
+ * @returns the array
+ */
+function buildArray(dtype, buffer, byteOffset, length) {
+    switch (dtype) {
+        case "u32":
+            return new Uint32Array(buffer, byteOffset, length);
+        case "i32":
+            return new Int32Array(buffer, byteOffset, length);
+        case "f32":
+            return new Float32Array(buffer, byteOffset, length);
+        case "f64":
+            return new Float64Array(buffer, byteOffset, length);
+        case "u8":
+        case "utf8":
+            return new Uint8Array(buffer, byteOffset, length);
+        default: {
+            const name = dtype;
+            throw badWire("dtype", `unknown wire dtype ${name}`, { dtype: name });
+        }
+    }
+}
+/**
+ * Read a WireBufferRef's shape from an untrusted manifest member.
+ * @param value - the member
+ * @param path - its manifest path
+ * @returns the reference
+ */
+function readRef(value, path) {
+    const o = asObject(value, path);
+    const { dtype } = o;
+    if (typeof dtype !== "string" || !WIRE_DTYPES.has(dtype)) {
+        throw badWire(path, `unknown wire dtype ${describe(dtype)}`, { found: dtype });
+    }
+    const fields = ["buffer", "byteOffset", "byteLength", "length"];
+    for (const field of fields) {
+        const v = o[field];
+        if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+            throw badWire(`${path}.${field}`, "expected a non-negative integer", { found: v });
+        }
+    }
+    return {
+        buffer: o.buffer,
+        byteOffset: o.byteOffset,
+        byteLength: o.byteLength,
+        dtype: dtype,
+        length: o.length,
+    };
+}
+/**
+ * The error to throw for a failure while building a column or table from untrusted input: a
+ * column-construction error (E_COLUMN_*, and E_DUPLICATE_ROLE from the table constructor) becomes
+ * E_BAD_SERIALIZATION naming the manifest path, every other Error passes through, and a non-Error
+ * value is wrapped.
+ * @param err - the caught value
+ * @param path - the manifest path of the column or table
+ * @returns the error to throw
+ */
+function asWireError(err, path) {
+    if (err instanceof GraphFormatError && (err.code.startsWith("E_COLUMN") || err.code === "E_DUPLICATE_ROLE")) {
+        return new GraphFormatError("E_BAD_SERIALIZATION", `${path}: ${err.message}`, {
+            ref: path,
+            reason: err.message,
+            cause: err.code,
+            ...err.details,
+        });
+    }
+    if (err instanceof Error) {
+        return err;
+    }
+    return badWire(path, String(err));
+}
+/**
+ * The stateful reader of one manifest: resolves references against the regions, records placed
+ * ranges for the overlap rule and the columns skipped under unknownColumns: "skip".
+ */
+class WireDecoder {
+    /**
+     * Create a decoder.
+     * @param regions - one region per buffer index
+     * @param options - the resolved options
+     */
+    constructor(regions, options) {
+        this.ranges = [];
+        this.skipped = [];
+        this.regions = regions;
+        this.options = options;
+    }
+    /**
+     * Whether the level includes the structure checks.
+     * @returns true for "structure" and "full"
+     */
+    get structure() {
+        return this.options.level !== "none";
+    }
+    /**
+     * Whether the level is "full".
+     * @returns true for "full"
+     */
+    get full() {
+        return this.options.level === "full";
+    }
+    /**
+     * Check a reference against its region (design section 9.5) and build the typed array over the
+     * referenced bytes, adopting them when they are contiguous and aligned and copying otherwise.
+     * @param value - the manifest member holding the reference
+     * @param path - its manifest path
+     * @param expected - the wire dtype the slot requires
+     * @param kind - who the range belongs to
+     * @returns the typed array
+     */
+    array(value, path, expected, kind) {
+        const ref = readRef(value, path);
+        if (ref.dtype !== expected) {
+            throw badWire(path, `expected dtype ${expected}, found ${ref.dtype}`, {
+                expected,
+                found: ref.dtype,
+            });
+        }
+        const region = this.regions[ref.buffer];
+        if (region === undefined) {
+            throw badWire(path, `buffer index ${ref.buffer} is out of range (${this.regions.length} buffers)`, {
+                found: ref.buffer,
+                buffers: this.regions.length,
+            });
+        }
+        const elementSize = wireElementSize(ref.dtype);
+        if (ref.byteOffset % elementSize !== 0) {
+            throw badWire(path, `byteOffset ${ref.byteOffset} is not a multiple of ${elementSize}`, {
+                byteOffset: ref.byteOffset,
+                elementSize,
+            });
+        }
+        if (ref.byteLength !== ref.length * elementSize) {
+            throw badWire(path, `byteLength ${ref.byteLength} is not length ${ref.length} * ${elementSize}`, {
+                byteLength: ref.byteLength,
+                length: ref.length,
+                elementSize,
+            });
+        }
+        if (ref.byteOffset + ref.byteLength > region.byteLength) {
+            throw badWire(path, `range [${ref.byteOffset}, ${ref.byteOffset + ref.byteLength}) exceeds the buffer`, {
+                byteOffset: ref.byteOffset,
+                byteLength: ref.byteLength,
+                bufferByteLength: region.byteLength,
+            });
+        }
+        const located = region.locate(ref.byteOffset, ref.byteLength);
+        if (located !== null && located.byteOffset % elementSize === 0) {
+            // adopted: the overlap rule is checked on the ArrayBuffer itself, so listing one buffer
+            // twice in wire.buffers cannot hide an alias
+            this.ranges.push({
+                buffer: located.buffer,
+                start: located.byteOffset,
+                end: located.byteOffset + ref.byteLength,
+                kind,
+                path,
+            });
+            return buildArray(ref.dtype, located.buffer, located.byteOffset, ref.length);
+        }
+        // copied: a private buffer, nothing to overlap
+        const copy = region.read(ref.byteOffset, ref.byteLength);
+        return buildArray(ref.dtype, copy.buffer, 0, ref.length);
+    }
+    /**
+     * A u32 array slot.
+     * @param value - the manifest member
+     * @param path - its path
+     * @param kind - the range owner
+     * @returns the array
+     */
+    u32(value, path, kind) {
+        return this.array(value, path, "u32", kind);
+    }
+    /**
+     * A Utf8 store slot (offsets + utf8), its layout checked at the structure level and its bytes at
+     * the full level.
+     * @param value - the manifest member (a WireUtf8)
+     * @param path - its path
+     * @param rows - the row count the store must have, or null to take it from the offsets (a dictionary)
+     * @param kind - the range owner
+     * @param always - check the layout at every level (stores decoded eagerly)
+     * @returns the offsets and bytes
+     */
+    utf8(value, path, rows, kind, always = false) {
+        const o = asObject(value, path);
+        const offsets = this.u32(o.offsets, `${path}.offsets`, kind);
+        const utf8 = this.array(o.utf8, `${path}.utf8`, "utf8", kind);
+        if (offsets.length === 0) {
+            throw badWire(`${path}.offsets`, "a Utf8 store needs at least one offset");
+        }
+        if (this.structure || always) {
+            checkUtf8Layout(offsets, utf8, rows ?? offsets.length - 1, path);
+        }
+        if (this.full) {
+            const bad = Utf8Store.fromEncoded(offsets, utf8).firstMalformedRow();
+            if (bad !== -1) {
+                throw badWire(path, `malformed UTF-8 in row ${bad}`, { row: bad });
+            }
+        }
+        return { offsets, utf8 };
+    }
+    /**
+     * Enforce the overlap rule of design section 9.5: no byte overlap between a mutable column and
+     * any core or immutable segment.
+     */
+    checkOverlaps() {
+        const fixed = this.ranges.filter((r) => (r.kind === "core" || r.kind === "immutable") && r.end > r.start);
+        for (const range of this.ranges) {
+            if (range.kind !== "mutable" || range.end === range.start) {
+                continue;
+            }
+            for (const other of fixed) {
+                if (other.buffer === range.buffer && range.start < other.end && other.start < range.end) {
+                    throw badWire(range.path, `mutable column overlaps ${other.path}`, { overlaps: other.path });
+                }
+            }
+        }
+    }
+    // ---------------------------------------------------------------- columns
+    /**
+     * Decode one column (design section 9.1), or drop it under unknownColumns: "skip".
+     * @param value - the WireColumn
+     * @param domain - the table's domain
+     * @param table - the extension table name, or null
+     * @param rows - the row count
+     * @param path - the manifest path
+     * @returns the column, or null when skipped
+     */
+    column(value, domain, table, rows, path) {
+        const w = asObject(value, path);
+        const metaRaw = asObject(w.meta, `${path}.meta`);
+        const name = asString(metaRaw.name, `${path}.meta.name`);
+        const { dtype, itemDtype } = metaRaw;
+        const unknown = !isKnownDtype(dtype) || (dtype === "list" && !isKnownDtype(itemDtype));
+        if (unknown) {
+            const found = dtype === "list" ? itemDtype : dtype;
+            if (this.options.unknownColumns === "skip") {
+                this.skipped.push({ domain, table, name, dtype: String(found) });
+                return null;
+            }
+            throw new GraphFormatError("E_UNSUPPORTED", `column "${name}" has unknown dtype ${String(found)}`, {
+                dtype: found,
+                column: name,
+                ref: path,
+            });
+        }
+        const meta = this.columnMeta(metaRaw, name, domain, path);
+        const kind = meta.mutable ? "mutable" : "immutable";
+        const parts = emptyParts(meta, rows, w.validity === null || w.validity === undefined ? null : this.u32(w.validity, `${path}.validity`, kind));
+        const declaredNullCount = w.nullCount;
+        switch (meta.dtype) {
+            case "f32":
+            case "f64":
+            case "i32":
+            case "u32":
+                parts.data = this.array(w.data, `${path}.data`, meta.dtype, kind);
+                break;
+            case "u8": {
+                const data = this.array(w.data, `${path}.data`, "u8", kind);
+                parts.data = canViewAsPaddedU32(data) ? data : copyToPaddedStore(data);
+                break;
+            }
+            case "bool":
+                parts.data = this.u32(w.data, `${path}.data`, kind);
+                break;
+            case "dict": {
+                parts.data = this.u32(w.data, `${path}.data`, kind);
+                const dict = this.utf8(w.dictionary, `${path}.dictionary`, null, kind, true);
+                parts.dictionary = decodeUtf8Rows(dict.utf8, dict.offsets, 0, dict.offsets.length - 1);
+                break;
+            }
+            case "string": {
+                const store = this.utf8(w.strings, `${path}.strings`, rows, kind);
+                parts.offsets = store.offsets;
+                parts.utf8 = store.utf8;
+                break;
+            }
+            case "list": {
+                const offsets = this.u32(w.offsets, `${path}.offsets`, kind);
+                if (offsets.length !== rows + 1) {
+                    throw badWire(`${path}.offsets`, `expected ${rows + 1} offsets, found ${offsets.length}`, {
+                        expected: rows + 1,
+                        found: offsets.length,
+                    });
+                }
+                parts.offsets = offsets;
+                const child = this.column(w.child, domain, table, offsets[rows], `${path}.child`);
+                if (child === null || child.dtype === "list") {
+                    throw badWire(`${path}.child`, "a list column needs a non-list child column");
+                }
+                parts.child = child;
+                break;
+            }
+            case "json":
+                parts.values = this.jsonRows(w.jsonText, rows, `${path}.jsonText`, kind);
+                break;
+            default: {
+                const dtypeName = meta.dtype;
+                throw badWire(`${path}.meta.dtype`, `unknown dtype ${dtypeName}`, { dtype: dtypeName });
+            }
+        }
+        let column;
+        try {
+            column = createColumn(parts);
+        }
+        catch (err) {
+            throw asWireError(err, path);
+        }
+        if (this.structure && column.nullCount !== declaredNullCount) {
+            throw badWire(`${path}.nullCount`, `manifest says ${String(declaredNullCount)}, the bitmap says ${column.nullCount}`, {
+                expected: column.nullCount,
+                found: declaredNullCount,
+            });
+        }
+        return column;
+    }
+    /**
+     * Resolve a column's metadata from its manifest form: the tagged JSON fields decoded, then the
+     * declaration resolver of the column module applied so every rule of design section 5.5 holds.
+     * @param raw - the manifest meta
+     * @param name - the column name
+     * @param domain - the table's domain
+     * @param path - the column's manifest path
+     * @returns the resolved metadata
+     */
+    columnMeta(raw, name, domain, path) {
+        const metaPath = `${path}.meta`;
+        const optional = (key, check) => {
+            const v = raw[key];
+            return v === undefined || v === null ? undefined : check(v, `${metaPath}.${key}`);
+        };
+        const numberOf = (v, p) => {
+            if (typeof v !== "number") {
+                throw badWire(p, "expected a number", { found: v });
+            }
+            return v;
+        };
+        const decl = {
+            name,
+            dtype: raw.dtype,
+            components: optional("components", numberOf),
+            itemDtype: optional("itemDtype", (v) => v),
+            itemComponents: optional("itemComponents", numberOf),
+            nullable: optional("nullable", asBoolean),
+            mutable: optional("mutable", asBoolean),
+            role: optional("role", asString),
+            refersTo: optional("refersTo", (v) => v),
+            unique: optional("unique", asBoolean),
+            default: decodeJsonValue(raw.default, `${metaPath}.default`),
+            fill: decodeJsonValue(raw.fill, `${metaPath}.fill`),
+            options: optional("options", (v, p) => decodeJsonValue(v, p)),
+            origin: optional("origin", (v) => v),
+            dynamic: optional("dynamic", asBoolean),
+            extra: optional("extra", (v, p) => decodeJsonValue(v, p)),
+        };
+        try {
+            return resolveColumnMeta(name, domain, decl);
+        }
+        catch (err) {
+            throw asWireError(err, path);
+        }
+    }
+    /**
+     * The values of a json column from its JSON text store: empty text is an unset row (undefined),
+     * every other row is parsed with the guarding reviver and untagged.
+     * @param value - the WireUtf8
+     * @param rows - the row count
+     * @param path - the manifest path
+     * @param kind - the range owner
+     * @returns one value per row
+     */
+    jsonRows(value, rows, path, kind) {
+        const store = this.utf8(value, path, rows, kind, true);
+        const texts = decodeUtf8Rows(store.utf8, store.offsets, 0, rows);
+        const values = new Array(rows);
+        for (let row = 0; row < rows; row++) {
+            const text = texts[row];
+            values[row] =
+                text === "" ? undefined : decodeJsonValue(parseGuardedJson(text, `${path}[${row}]`), `${path}[${row}]`);
+        }
+        return values;
+    }
+    /**
+     * Decode a table's columns in declaration order.
+     * @param value - the WireColumn array
+     * @param domain - the domain
+     * @param table - the extension table name, or null
+     * @param rows - the row count
+     * @param path - the manifest path
+     * @returns the table
+     */
+    table(value, domain, table, rows, path) {
+        const list = asArray(value, path);
+        const columns = [];
+        const names = new Set();
+        for (let i = 0; i < list.length; i++) {
+            const column = this.column(list[i], domain, table, rows, `${path}[${i}]`);
+            if (column === null) {
+                continue;
+            }
+            if (names.has(column.meta.name)) {
+                throw badWire(`${path}[${i}].meta.name`, `column "${column.meta.name}" is declared twice`, {
+                    column: column.meta.name,
+                });
+            }
+            names.add(column.meta.name);
+            columns.push(column);
+        }
+        try {
+            return new AttributeTable({ domain, rowCount: rows, columns });
+        }
+        catch (err) {
+            throw asWireError(err, path);
+        }
+    }
+    // ---------------------------------------------------------------- id map
+    /**
+     * Decode the id map (design section 4.5). An unknown kind is E_UNSUPPORTED with details.kind.
+     * @param value - the WireIdMap
+     * @returns the map
+     */
+    ids(value) {
+        const o = asObject(value, "ids");
+        const kindRaw = o.kind;
+        if (typeof kindRaw !== "string" || !ID_MAP_KINDS.has(kindRaw)) {
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown id map kind ${describe(kindRaw)}`, {
+                kind: kindRaw,
+                ref: "ids.kind",
+            });
+        }
+        const kind = kindRaw;
+        const size = asCount(o.size, "ids.size");
+        const offsetRaw = o.offset ?? 0;
+        if (typeof offsetRaw !== "number") {
+            throw badWire("ids.offset", "expected a number", { found: offsetRaw });
+        }
+        const parts = {
+            kind,
+            size,
+            offset: kind === "identity" ? offsetRaw : 0,
+            values: null,
+            tags: null,
+            numbers: null,
+            offsets: null,
+            utf8: null,
+        };
+        const typed = parts;
+        switch (kind) {
+            case "identity":
+                break;
+            case "dense":
+                typed.values = this.u32(o.values, "ids.values", "immutable");
+                break;
+            case "numeric":
+                typed.values = this.array(o.values, "ids.values", "f64", "immutable");
+                break;
+            case "string": {
+                typed.offsets = this.u32(o.offsets, "ids.offsets", "immutable");
+                typed.utf8 = this.array(o.utf8, "ids.utf8", "utf8", "immutable");
+                break;
+            }
+            case "mixed": {
+                typed.tags = this.array(o.tags, "ids.tags", "u8", "immutable");
+                typed.numbers = this.array(o.numbers, "ids.numbers", "f64", "immutable");
+                typed.offsets = this.u32(o.offsets, "ids.offsets", "immutable");
+                typed.utf8 = this.array(o.utf8, "ids.utf8", "utf8", "immutable");
+                break;
+            }
+            default: {
+                const name = kind;
+                throw new GraphFormatError("E_UNSUPPORTED", `unknown id map kind ${name}`, { kind: name });
+            }
+        }
+        return nodeIdMapFromTyped(typed, this.options.level);
+    }
+    // ---------------------------------------------------------------- views
+    /**
+     * Resolve the member arrays of the carried views (design section 9.1): every reference is
+     * checked like any other, and the arrays are installed on the snapshot by `installViews()`.
+     * @param value - the manifest views member
+     * @returns the member arrays per view name (unknown names included; they are ignored later)
+     */
+    views(value) {
+        const out = new Map();
+        if (value === null || value === undefined) {
+            return out;
+        }
+        const views = asObject(value, "views");
+        for (const name of Object.keys(views)) {
+            const members = asObject(views[name], `views.${name}`);
+            const arrays = new Map();
+            for (const member of Object.keys(members)) {
+                const path = `views.${name}.${member}`;
+                const ref = readRef(members[member], path);
+                arrays.set(member, this.array(ref, path, ref.dtype, "view"));
+            }
+            out.set(name, arrays);
+        }
+        return out;
+    }
+}
+/**
+ * One member array of a carried view, checked for class and length.
+ * @param members - the view's member arrays
+ * @param view - the view name (for the error path)
+ * @param member - the member name
+ * @param ctor - the required typed-array class
+ * @param length - the required length
+ * @param required - whether an absent member is an error
+ * @returns the array, or null when absent and not required
+ */
+function viewMember(members, view, member, ctor, length, required) {
+    const path = `views.${view}.${member}`;
+    const array = members.get(member);
+    if (array === undefined) {
+        if (required) {
+            throw badWire(path, "the carried view is missing this member");
+        }
+        return null;
+    }
+    if (!(array instanceof ctor)) {
+        throw badWire(path, `expected ${ctor.name}, found ${array.constructor.name}`, {
+            expected: ctor.name,
+            found: array.constructor.name,
+        });
+    }
+    if (array.length !== length) {
+        throw badWire(path, `expected ${length} entries, found ${array.length}`, {
+            expected: length,
+            found: array.length,
+        });
+    }
+    return array;
+}
+/**
+ * The per-node or per-arc array of a single-member view.
+ * @param members - the view's member arrays
+ * @param view - the view name
+ * @param ctor - the required typed-array class
+ * @param length - the required length
+ * @returns the array
+ */
+function dataMember(members, view, ctor, length) {
+    return viewMember(members, view, "data", ctor, length, true);
+}
+/**
+ * Install the views a manifest carried into the snapshot's cache (design section 9.1), so the
+ * receiver does not recompute them. Views that alias another view on an undirected snapshot
+ * (`reverse`, `inDegree`, `weightedInDegree`, `reverseDegreeOrder`) are left to the snapshot, which
+ * produces the alias itself; `mate` on a directed snapshot and unknown view names are ignored.
+ * Every installed member must have the class and length of the view it claims to be
+ * (E_BAD_SERIALIZATION otherwise); at the "structure" level (`verify`) every carried view is also
+ * checked against the core before it is installed (src/wire/carried-views.ts), so a corrupt or
+ * forged view never enters the cache below "full".
+ * @param snapshot - the freshly built snapshot
+ * @param carried - the carried member arrays
+ * @param verify - whether to check the contents (the "structure" level)
+ */
+function installViews(snapshot, carried, verify) {
+    const { directed, nodeCount, edgeCount, arcCount, selfLoopCount } = snapshot;
+    let facts = null;
+    const factsOf = () => {
+        facts ?? (facts = new CoreFacts(snapshot));
+        return facts;
+    };
+    /**
+     * Install an f64 view; under `verify` it is compared with the snapshot's own computation instead
+     * (which then stays cached), so a corrupt value array never enters the cache.
+     * @param name - the view
+     */
+    const seedF64 = (name) => {
+        const data = dataMember(carried.get(name), name, Float64Array, nodeCount);
+        if (verify) {
+            checkF64View(name, data, snapshot[name]());
+            return;
+        }
+        seedView(snapshot, name, data);
+    };
+    for (const [name, members] of carried) {
+        switch (name) {
+            case "reverse": {
+                if (!directed) {
+                    break;
+                }
+                const rowPtr = viewMember(members, name, "rowPtr", Uint32Array, nodeCount + 1, true);
+                const colIdx = viewMember(members, name, "colIdx", Uint32Array, arcCount, true);
+                const fwdArc = viewMember(members, name, "fwdArc", Uint32Array, arcCount, true);
+                const weights = viewMember(members, name, "weights", Float32Array, arcCount, snapshot.weights !== null);
+                if (weights !== null && snapshot.weights === null) {
+                    throw badWire(`views.${name}.weights`, "weights carried for an unweighted snapshot");
+                }
+                const reverse = new ReverseAdjacency(snapshot, rowPtr, colIdx, weights, fwdArc);
+                if (verify) {
+                    checkReverse(snapshot, factsOf(), reverse);
+                }
+                seedView(snapshot, "reverse", reverse);
+                break;
+            }
+            case "coo": {
+                const src = viewMember(members, name, "src", Uint32Array, arcCount, true);
+                if (verify) {
+                    checkCooSrc(factsOf(), src);
+                }
+                seedView(snapshot, "coo", cooViewOf(snapshot, src));
+                break;
+            }
+            case "edgeList": {
+                const identity = snapshot.flags.arcToEdgeIsIdentity;
+                const src = viewMember(members, name, "src", Uint32Array, edgeCount, true);
+                const dst = viewMember(members, name, "dst", Uint32Array, edgeCount, !identity);
+                const weights = viewMember(members, name, "weights", Float32Array, edgeCount, snapshot.weights !== null && !identity);
+                if (weights !== null && snapshot.weights === null) {
+                    throw badWire(`views.${name}.weights`, "weights carried for an unweighted snapshot");
+                }
+                if (verify) {
+                    checkEdgeList(snapshot, factsOf(), src, dst, weights);
+                }
+                seedView(snapshot, "edgeList", edgeListViewOf(snapshot, src, dst ?? snapshot.colIdx, weights ?? snapshot.weights));
+                break;
+            }
+            case "outDegree": {
+                const data = dataMember(members, name, Uint32Array, nodeCount);
+                if (verify) {
+                    checkOutDegree(snapshot, data);
+                }
+                seedView(snapshot, name, data);
+                break;
+            }
+            case "degree": {
+                const data = dataMember(members, name, Uint32Array, nodeCount);
+                if (verify) {
+                    checkDegree(snapshot, factsOf(), data);
+                }
+                seedView(snapshot, name, data);
+                break;
+            }
+            case "selfLoopsPerNode": {
+                const data = dataMember(members, name, Uint32Array, nodeCount);
+                if (verify) {
+                    checkSelfLoopsPerNode(factsOf(), data);
+                }
+                seedView(snapshot, name, data);
+                break;
+            }
+            case "inDegree":
+                if (directed) {
+                    const data = dataMember(members, name, Uint32Array, nodeCount);
+                    if (verify) {
+                        checkInDegree(factsOf(), data);
+                    }
+                    seedView(snapshot, name, data);
+                }
+                break;
+            case "weightedOutDegree":
+            case "weightedDegree":
+            case "selfLoopWeight":
+                seedF64(name);
+                break;
+            case "weightedInDegree":
+                if (directed) {
+                    seedF64(name);
+                }
+                break;
+            case "selfLoopArcs": {
+                const data = dataMember(members, name, Uint32Array, selfLoopCount);
+                if (verify) {
+                    checkSelfLoopArcs(snapshot, factsOf(), data);
+                }
+                seedView(snapshot, name, data);
+                break;
+            }
+            case "mate":
+                if (!directed) {
+                    const data = dataMember(members, name, Uint32Array, arcCount);
+                    if (verify) {
+                        checkMate(snapshot, factsOf(), data);
+                    }
+                    seedView(snapshot, name, data);
+                }
+                break;
+            case "degreeOrder":
+            case "reverseDegreeOrder": {
+                if (name === "reverseDegreeOrder" && !directed) {
+                    break;
+                }
+                const perm = viewMember(members, name, "perm", Uint32Array, nodeCount, true);
+                const segmentOffsets = viewMember(members, name, "segmentOffsets", Uint32Array, 5, true);
+                if (verify) {
+                    const degree = name === "degreeOrder" ? rowLengths(snapshot.rowPtr, nodeCount) : factsOf().inDegree;
+                    checkDegreeOrder(name, degree, perm, segmentOffsets);
+                }
+                seedView(snapshot, name, Object.freeze({ perm, segmentOffsets }));
+                break;
+            }
+            default:
+                // An unknown view name (a newer minor) or a scalar view: ignored and recomputed.
+                break;
+        }
+    }
+}
+/**
+ * Read the core references from the manifest, applying the null rules of design section 9.1.
+ * @param value - manifest.core
+ * @returns the references
+ */
+function readCoreRefs(value) {
+    const core = asObject(value, "core");
+    const optionalRef = (name) => {
+        const v = core[name];
+        return v === null || v === undefined ? null : readRef(v, `core.${name}`);
+    };
+    return {
+        rowPtr: readRef(core.rowPtr, "core.rowPtr"),
+        colIdx: optionalRef("colIdx"),
+        weights: optionalRef("weights"),
+        arcToEdge: optionalRef("arcToEdge"),
+        edgeToArc: optionalRef("edgeToArc"),
+    };
+}
+/**
+ * Build the core arrays: a null colIdx is a zero-arc graph, a null weights array an unweighted (or
+ * zero-arc weighted) graph, a null permutation the identity (when the flag says so) or zero length.
+ * @param decoder - the decoder
+ * @param refs - the core references
+ * @param counts - the manifest counts
+ * @param flags - the manifest flags
+ * @returns the arrays
+ */
+function decodeCore(decoder, refs, counts, flags) {
+    const rowPtr = decoder.u32(refs.rowPtr, "core.rowPtr", "core");
+    let colIdx;
+    if (refs.colIdx === null) {
+        if (counts.arcs !== 0) {
+            throw badWire("core.colIdx", `null although counts.arcs is ${counts.arcs}`);
+        }
+        colIdx = new Uint32Array(0);
+    }
+    else {
+        colIdx = decoder.u32(refs.colIdx, "core.colIdx", "core");
+    }
+    let weights = null;
+    if (refs.weights !== null) {
+        if (!flags.weighted) {
+            throw badWire("core.weights", "present although flags.weighted is false");
+        }
+        weights = decoder.array(refs.weights, "core.weights", "f32", "core");
+    }
+    else if (flags.weighted) {
+        if (counts.arcs !== 0) {
+            throw badWire("core.weights", `null although flags.weighted is true and counts.arcs is ${counts.arcs}`);
+        }
+        weights = new Float32Array(0);
+    }
+    const identity = flags.arcToEdgeIsIdentity;
+    const permutation = (ref, name, count) => {
+        if (ref !== null) {
+            if (identity) {
+                throw badWire(`core.${name}`, "present although flags.arcToEdgeIsIdentity is true");
+            }
+            return decoder.u32(ref, `core.${name}`, "core");
+        }
+        if (identity) {
+            return null;
+        }
+        if (count !== 0) {
+            throw badWire(`core.${name}`, `null although the permutation is not the identity and the count is ${count}`);
+        }
+        return new Uint32Array(0);
+    };
+    return {
+        rowPtr,
+        colIdx,
+        weights,
+        arcToEdge: permutation(refs.arcToEdge, "arcToEdge", counts.arcs),
+        edgeToArc: permutation(refs.edgeToArc, "edgeToArc", counts.edges),
+    };
+}
+/**
+ * Honour the manifest's arena descriptor (design sections 9.1 and 10.3): the core arrays lying at
+ * 256-aligned offsets inside the described range become its segments; hotByteLength is recomputed
+ * and, at the structure level, compared with the manifest.
+ * @param value - manifest.arena
+ * @param regions - the buffer regions
+ * @param refs - the core references
+ * @param arrays - the core arrays
+ * @param structure - whether the structure checks run
+ * @returns the arena layout, or null when the manifest carries none or the region is chunked
+ */
+function decodeArena(value, regions, refs, arrays, structure) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const a = asObject(value, "arena");
+    const buffer = asCount(a.buffer, "arena.buffer");
+    const byteOffset = asCount(a.byteOffset, "arena.byteOffset");
+    const byteLength = asCount(a.byteLength, "arena.byteLength");
+    const region = regions[buffer];
+    if (region === undefined) {
+        throw badWire("arena.buffer", `buffer index ${buffer} is out of range`, { found: buffer });
+    }
+    if (byteOffset + byteLength > region.byteLength) {
+        throw badWire("arena", `range [${byteOffset}, ${byteOffset + byteLength}) exceeds the buffer`, {
+            byteOffset,
+            byteLength,
+            bufferByteLength: region.byteLength,
+        });
+    }
+    const located = region.locate(byteOffset, byteLength);
+    if (located === null) {
+        return null;
+    }
+    const segments = {
+        rowPtr: null,
+        colIdx: null,
+        weights: null,
+        arcToEdge: null,
+        edgeToArc: null,
+    };
+    let hotByteLength = 0;
+    const names = CORE_ORDER;
+    for (const name of names) {
+        const ref = refs[name];
+        const array = arrays[name];
+        if (ref === null || array === null || array.length === 0) {
+            continue;
+        }
+        const inside = ref.buffer === buffer &&
+            ref.byteOffset >= byteOffset &&
+            ref.byteOffset + ref.byteLength <= byteOffset + byteLength;
+        if (!inside) {
+            continue;
+        }
+        const relative = ref.byteOffset - byteOffset;
+        if (relative % ALIGNMENT !== 0) {
+            throw badWire(`core.${name}`, `inside the arena at offset ${relative}, not a multiple of ${ALIGNMENT}`, {
+                byteOffset: relative,
+            });
+        }
+        if (array.buffer !== located.buffer || array.byteOffset !== located.byteOffset + relative) {
+            throw badWire(`core.${name}`, "the arena describes a segment the array is not a view of");
+        }
+        segments[name] = Object.freeze({ byteOffset: located.byteOffset + relative, byteLength: ref.byteLength });
+        if (name === "rowPtr" || name === "colIdx" || name === "weights") {
+            hotByteLength = relative + ref.byteLength;
+        }
+    }
+    if (structure && a.hotByteLength !== hotByteLength) {
+        throw badWire("arena.hotByteLength", `manifest says ${String(a.hotByteLength)}, the segments say ${hotByteLength}`, {
+            expected: hotByteLength,
+            found: a.hotByteLength,
+        });
+    }
+    return Object.freeze({
+        buffer: located.buffer,
+        byteOffset: located.byteOffset,
+        byteLength,
+        alignment: ALIGNMENT,
+        segments: Object.freeze(segments),
+        hotByteLength,
+    });
+}
+/**
+ * Read the flags (every member a boolean).
+ * @param value - manifest.flags
+ * @returns the flags
+ */
+function readFlags(value) {
+    const o = asObject(value, "flags");
+    const flag = (name) => asBoolean(o[name], `flags.${name}`);
+    return {
+        multigraph: flag("multigraph"),
+        hasSelfLoops: flag("hasSelfLoops"),
+        arcToEdgeIsIdentity: flag("arcToEdgeIsIdentity"),
+        weighted: flag("weighted"),
+        allWeightsOne: flag("allWeightsOne"),
+        nonNegativeWeights: flag("nonNegativeWeights"),
+        finiteWeights: flag("finiteWeights"),
+    };
+}
+/**
+ * Read a column origin (every field a string or null).
+ * @param value - the manifest member
+ * @param path - its path
+ * @returns the origin, or null
+ */
+function readOrigin(value, path) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const o = asObject(value, path);
+    const field = (key) => asStringOrNull(o[key], `${path}.${key}`);
+    return {
+        format: field("format"),
+        id: field("id"),
+        title: field("title"),
+        type: field("type"),
+        namespace: field("namespace"),
+    };
+}
+/**
+ * Read the graph metadata (design section 5.9); unknown fields are ignored, missing ones are null.
+ * @param value - manifest.meta
+ * @returns the frozen metadata
+ */
+function readGraphMeta(value) {
+    const o = asObject(value, "meta");
+    const keywordsRaw = o.keywords ?? [];
+    const keywords = asArray(keywordsRaw, "meta.keywords").map((k, i) => asString(k, `meta.keywords[${i}]`));
+    const extraRaw = decodeJsonValue(o.extra ?? {}, "meta.extra");
+    if (!isPlainObject(extraRaw)) {
+        throw badWire("meta.extra", "expected an object");
+    }
+    return Object.freeze({
+        name: asStringOrNull(o.name, "meta.name"),
+        description: asStringOrNull(o.description, "meta.description"),
+        creator: asStringOrNull(o.creator, "meta.creator"),
+        created: asStringOrNull(o.created, "meta.created"),
+        modified: asStringOrNull(o.modified, "meta.modified"),
+        keywords: Object.freeze(keywords),
+        sourceFormat: asStringOrNull(o.sourceFormat, "meta.sourceFormat"),
+        sourceVersion: asStringOrNull(o.sourceVersion, "meta.sourceVersion"),
+        idType: asEnum(o.idType, "meta.idType", ID_TYPES),
+        timeFormat: asEnum(o.timeFormat, "meta.timeFormat", TIME_FORMATS),
+        timeRepresentation: asEnum(o.timeRepresentation, "meta.timeRepresentation", TIME_REPRESENTATIONS),
+        mode: asEnum(o.mode, "meta.mode", MODES),
+        declaredMultigraph: asBooleanOrNull(o.declaredMultigraph, "meta.declaredMultigraph"),
+        weightOrigin: readOrigin(o.weightOrigin, "meta.weightOrigin"),
+        extra: Object.freeze(extraRaw),
+    });
+}
+/**
+ * Check the manifest's discriminator and versions (design sections 9.1 and 13.5): `format`, the
+ * wire major (E_UNSUPPORTED_VERSION kind "wire") and `formatVersion` (kind "format"). A newer wire
+ * minor is accepted.
+ * @param manifest - the manifest object
+ * @returns the wire version pair
+ */
+export function checkManifestVersions(manifest) {
+    if (manifest.format !== WIRE_FORMAT) {
+        throw badWire("format", `expected "${WIRE_FORMAT}", found ${describe(manifest.format)}`, {
+            found: manifest.format,
+        });
+    }
+    const wire = asArray(manifest.wire, "wire");
+    const major = wire[0];
+    const minor = wire[1];
+    if (typeof major !== "number" ||
+        typeof minor !== "number" ||
+        !Number.isInteger(major) ||
+        !Number.isInteger(minor)) {
+        throw badWire("wire", "expected [major, minor] integers", { found: manifest.wire });
+    }
+    if (major !== WIRE_MAJOR) {
+        throw new GraphFormatError("E_UNSUPPORTED_VERSION", `wire major ${major} is not supported (reader: ${WIRE_MAJOR})`, {
+            kind: "wire",
+            found: major,
+            supported: WIRE_MAJOR,
+        });
+    }
+    if (manifest.formatVersion !== FORMAT_VERSION) {
+        throw new GraphFormatError("E_UNSUPPORTED_VERSION", `formatVersion ${describe(manifest.formatVersion)} is not supported (reader: ${FORMAT_VERSION})`, { kind: "format", found: manifest.formatVersion, supported: FORMAT_VERSION });
+    }
+    return [major, minor];
+}
+// ============================================================ the manifest reader
+/**
+ * Rebuild a snapshot from a manifest and the regions its references index (design sections 9.1 and
+ * 9.5): versions checked, core arrays and arena adopted, id map and tables decoded, then the
+ * snapshot validated at the requested level.
+ * @param manifestRaw - the manifest (an object; already parsed for a container)
+ * @param regions - one region per buffer index
+ * @param options - the resolved options
+ * @param honourArena - whether the manifest's arena descriptor is adopted (false for chunked input)
+ * @returns the snapshot
+ */
+export function decodeManifest(manifestRaw, regions, options, honourArena) {
+    const manifest = asObject(manifestRaw, "manifest");
+    checkManifestVersions(manifest);
+    const decoder = new WireDecoder(regions, options);
+    const directed = asBoolean(manifest.directed, "directed");
+    const countsRaw = asObject(manifest.counts, "counts");
+    const counts = {
+        nodes: asCount(countsRaw.nodes, "counts.nodes"),
+        edges: asCount(countsRaw.edges, "counts.edges"),
+        arcs: asCount(countsRaw.arcs, "counts.arcs"),
+        selfLoops: asCount(countsRaw.selfLoops, "counts.selfLoops"),
+    };
+    const flags = readFlags(manifest.flags);
+    if (flags.arcToEdgeIsIdentity && (!directed || counts.arcs !== counts.edges)) {
+        throw badWire("flags.arcToEdgeIsIdentity", "set on an undirected graph or with arcs !== edges");
+    }
+    const coreRefs = readCoreRefs(manifest.core);
+    const core = decodeCore(decoder, coreRefs, counts, flags);
+    const arena = honourArena ? decodeArena(manifest.arena, regions, coreRefs, core, decoder.structure) : null;
+    const ids = decoder.ids(manifest.ids);
+    const nodes = decoder.table(manifest.nodeColumns ?? [], "node", null, counts.nodes, "nodeColumns");
+    const edges = decoder.table(manifest.edgeColumns ?? [], "edge", null, counts.edges, "edgeColumns");
+    const graph = decoder.table(manifest.graphColumns ?? [], "graph", null, 1, "graphColumns");
+    const extensions = new Map();
+    const extensionsRaw = asArray(manifest.extensions ?? [], "extensions");
+    for (let i = 0; i < extensionsRaw.length; i++) {
+        const path = `extensions[${i}]`;
+        const ext = asObject(extensionsRaw[i], path);
+        const name = asString(ext.name, `${path}.name`);
+        if (extensions.has(name)) {
+            throw badWire(`${path}.name`, `extension table "${name}" appears twice`, { table: name });
+        }
+        const rowCount = asCount(ext.rowCount, `${path}.rowCount`);
+        extensions.set(name, decoder.table(ext.columns, "extension", name, rowCount, `${path}.columns`));
+    }
+    let meta = readGraphMeta(manifest.meta ?? {});
+    if (decoder.skipped.length > 0) {
+        const skipped = Object.freeze(decoder.skipped.map((s) => Object.freeze({ ...s })));
+        meta = Object.freeze({ ...meta, extra: Object.freeze({ ...meta.extra, [SKIPPED_COLUMNS_KEY]: skipped }) });
+    }
+    const carried = decoder.views(manifest.views);
+    if (decoder.structure) {
+        decoder.checkOverlaps();
+    }
+    const parts = {
+        label: asStringOrNull(manifest.label, "label"),
+        serial: null,
+        directed,
+        nodeCount: counts.nodes,
+        edgeCount: counts.edges,
+        arcCount: counts.arcs,
+        selfLoopCount: counts.selfLoops,
+        rowPtr: core.rowPtr,
+        colIdx: core.colIdx,
+        weights: core.weights,
+        arcToEdge: core.arcToEdge,
+        edgeToArc: core.edgeToArc,
+        flags,
+        ids,
+        nodes,
+        edges,
+        graph,
+        extensions,
+        meta,
+        arena,
+        checksum: false,
+    };
+    const snapshot = createSnapshot(parts);
+    if (options.level === "full") {
+        snapshot.validate({ level: "full" });
+    }
+    else if (options.level === "structure") {
+        snapshot.validate({ level: "structure" });
+    }
+    if (options.level !== "full") {
+        installViews(snapshot, carried, options.level === "structure");
+    }
+    return snapshot;
+}
+/**
+ * Rebuild a snapshot from its wire form (design section 9.1). Defaults: `validate: "structure"`
+ * (the manifest is trusted to have come from this package; the cheap checks still run) and `copy:
+ * false` (the arrays are views into `wire.buffers`; a SharedArrayBuffer is copied). The reverse id
+ * Map and decoded strings are rebuilt lazily; carried views (`includeViews`) are installed on the
+ * receiver below "full" and recomputed under "full", where nothing carried is trusted.
+ * @param wire - the wire snapshot
+ * @param options - validation level, copy and unknown-column policy
+ * @returns the snapshot; E_UNSUPPORTED_VERSION, E_UNSUPPORTED, E_BAD_SERIALIZATION or E_INVALID_SNAPSHOT on bad input
+ */
+export function fromWire(wire, options) {
+    const resolved = resolveFromWireOptions(options, "structure");
+    const w = asObject(wire, "wire");
+    const buffersRaw = asArray(w.buffers, "wire.buffers");
+    const regions = [];
+    for (let i = 0; i < buffersRaw.length; i++) {
+        const b = buffersRaw[i];
+        let buffer;
+        if (b instanceof ArrayBuffer) {
+            buffer = resolved.copy ? copyBuffer(b) : b;
+        }
+        else if (isSharedArrayBuffer(b)) {
+            buffer = copyBuffer(b);
+        }
+        else {
+            throw badWire(`wire.buffers[${i}]`, "expected an ArrayBuffer");
+        }
+        regions.push(bufferRegion(buffer, 0, buffer.byteLength));
+    }
+    return decodeManifest(w.manifest, regions, resolved, true);
+}
+//# sourceMappingURL=from-wire.js.map