@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/wire/carried-views.js

@@ -0,0 +1,286 @@
+/**
+ * Content checks of the views a wire manifest carries (`includeViews`, design sections 9.1 and 9.5),
+ * run at the "structure" level before a carried view is installed on the receiver. Every view is a
+ * pure function of the core (design section 7.2), so each check is exact: the index views are
+ * compared with what the core says arc by arc in O(n + m) without allocating a second copy, and the
+ * four f64 views are compared with the snapshot's own computation. A view that disagrees is
+ * E_INVALID_SNAPSHOT with `details.invariant` "I2" (a corrupt index array) or "I17" (a corrupt
+ * value array) and `details.view` naming it. At "none" nothing is checked (the manifest is trusted,
+ * design section 9.5); at "full" carried views are never installed.
+ */
+import { invariantViolation } from "../snapshot/validate.js";
+import { DEGREE_TIER_HIGH, DEGREE_TIER_MID, rowLengths } from "../snapshot/views.js";
+/** The per-arc facts every index-view check reads, computed once per manifest. */
+export class CoreFacts {
+    /**
+     * Expand the core once.
+     * @param snapshot - the snapshot
+     */
+    constructor(snapshot) {
+        const { nodeCount, arcCount, rowPtr, colIdx, directed } = snapshot;
+        const arcRow = new Uint32Array(arcCount);
+        const loops = new Uint32Array(nodeCount);
+        const inDegree = directed ? new Uint32Array(nodeCount) : rowLengths(rowPtr, nodeCount);
+        for (let u = 0; u < nodeCount; u++) {
+            const end = rowPtr[u + 1];
+            for (let a = rowPtr[u]; a < end; a++) {
+                arcRow[a] = u;
+                const v = colIdx[a];
+                if (v === u) {
+                    loops[u]++;
+                }
+                if (directed) {
+                    inDegree[v]++;
+                }
+            }
+        }
+        this.arcRow = arcRow;
+        this.loops = loops;
+        this.inDegree = inDegree;
+    }
+    /**
+     * The exclusive prefix sum of the in-degrees (the reverse rowPtr).
+     * @returns nodeCount + 1 offsets
+     */
+    inDegreePrefix() {
+        const n = this.inDegree.length;
+        const out = new Uint32Array(n + 1);
+        for (let u = 0; u < n; u++) {
+            out[u + 1] = out[u] + this.inDegree[u];
+        }
+        return out;
+    }
+}
+/**
+ * The error for a carried view that disagrees with the core.
+ * @param view - the view name
+ * @param member - the member array
+ * @param index - the offending index
+ * @param invariant - "I2" for an index array, "I17" for a value array
+ * @returns the error
+ */
+function viewError(view, member, index, invariant) {
+    return invariantViolation(invariant, `carried view ${view}.${member} disagrees with the core at ${index}`, {
+        view,
+        member,
+        index,
+        reason: "view",
+    });
+}
+/**
+ * Compare two arrays element by element (NaN equal to NaN).
+ * @param view - the view name
+ * @param member - the member name
+ * @param found - the carried array
+ * @param expected - the truth
+ * @param invariant - the invariant to report
+ */
+function expectSame(view, member, found, expected, invariant) {
+    for (let i = 0; i < expected.length; i++) {
+        if (!Object.is(found[i], expected[i]) && found[i] !== expected[i]) {
+            throw viewError(view, member, i, invariant);
+        }
+    }
+}
+/**
+ * Check that an array is a permutation of 0..length-1.
+ * @param view - the view name
+ * @param member - the member name
+ * @param perm - the array
+ */
+function expectPermutation(view, member, perm) {
+    const seen = new Uint8Array(perm.length);
+    for (let i = 0; i < perm.length; i++) {
+        const p = perm[i];
+        if (p >= perm.length || seen[p] === 1) {
+            throw viewError(view, member, i, "I2");
+        }
+        seen[p] = 1;
+    }
+}
+/**
+ * outDegree: the row lengths.
+ * @param snapshot - the snapshot
+ * @param data - the carried array
+ */
+export function checkOutDegree(snapshot, data) {
+    expectSame("outDegree", "data", data, rowLengths(snapshot.rowPtr, snapshot.nodeCount), "I2");
+}
+/**
+ * inDegree (directed): the in-arc counts.
+ * @param facts - the core facts
+ * @param data - the carried array
+ */
+export function checkInDegree(facts, data) {
+    expectSame("inDegree", "data", data, facts.inDegree, "I2");
+}
+/**
+ * degree: outDegree + inDegree (directed) or outDegree + loops (undirected), design section 3.4.
+ * @param snapshot - the snapshot
+ * @param facts - the core facts
+ * @param data - the carried array
+ */
+export function checkDegree(snapshot, facts, data) {
+    const out = rowLengths(snapshot.rowPtr, snapshot.nodeCount);
+    const add = snapshot.directed ? facts.inDegree : facts.loops;
+    for (let u = 0; u < out.length; u++) {
+        if (data[u] !== out[u] + add[u]) {
+            throw viewError("degree", "data", u, "I2");
+        }
+    }
+}
+/**
+ * selfLoopsPerNode: the loop arcs per row.
+ * @param facts - the core facts
+ * @param data - the carried array
+ */
+export function checkSelfLoopsPerNode(facts, data) {
+    expectSame("selfLoopsPerNode", "data", data, facts.loops, "I2");
+}
+/**
+ * selfLoopArcs: ascending arcs, each a loop; with the length fixed to selfLoopCount that is exact.
+ * @param snapshot - the snapshot
+ * @param facts - the core facts
+ * @param data - the carried array
+ */
+export function checkSelfLoopArcs(snapshot, facts, data) {
+    const { colIdx, arcCount } = snapshot;
+    for (let i = 0; i < data.length; i++) {
+        const a = data[i];
+        if (a >= arcCount || colIdx[a] !== facts.arcRow[a] || (i > 0 && a <= data[i - 1])) {
+            throw viewError("selfLoopArcs", "data", i, "I2");
+        }
+    }
+}
+/**
+ * coo.src: the row of every arc.
+ * @param facts - the core facts
+ * @param src - the carried array
+ */
+export function checkCooSrc(facts, src) {
+    expectSame("coo", "src", src, facts.arcRow, "I2");
+}
+/**
+ * edgeList: `src[e]` is the row of `edgeToArc[e]`, `dst[e]` its target, `weights[e]` its weight.
+ * @param snapshot - the snapshot
+ * @param facts - the core facts
+ * @param src - the carried sources
+ * @param dst - the carried targets, or null when colIdx is aliased
+ * @param weights - the carried weights, or null when aliased or unweighted
+ */
+export function checkEdgeList(snapshot, facts, src, dst, weights) {
+    const { edgeCount, edgeToArc, colIdx, arcCount } = snapshot;
+    const forward = snapshot.weights;
+    for (let e = 0; e < edgeCount; e++) {
+        const a = edgeToArc[e];
+        if (a >= arcCount || src[e] !== facts.arcRow[a]) {
+            throw viewError("edgeList", "src", e, "I2");
+        }
+        if (dst !== null && dst[e] !== colIdx[a]) {
+            throw viewError("edgeList", "dst", e, "I2");
+        }
+        if (weights !== null && forward !== null && !Object.is(weights[e], forward[a])) {
+            throw viewError("edgeList", "weights", e, "I17");
+        }
+    }
+}
+/**
+ * mate (undirected): an involution pairing the two arcs of every non-loop edge (invariant I7) and
+ * fixing every loop arc.
+ * @param snapshot - the snapshot
+ * @param facts - the core facts
+ * @param mate - the carried array
+ */
+export function checkMate(snapshot, facts, mate) {
+    const { arcCount, arcToEdge, colIdx } = snapshot;
+    for (let a = 0; a < arcCount; a++) {
+        const m = mate[a];
+        const loop = colIdx[a] === facts.arcRow[a];
+        if (m >= arcCount || mate[m] !== a || arcToEdge[m] !== arcToEdge[a] || (m === a) !== loop) {
+            throw viewError("mate", "data", a, "I2");
+        }
+    }
+}
+/**
+ * degreeOrder / reverseDegreeOrder: a permutation ordered by non-increasing degree with ties in
+ * ascending node index, and the cuGraph tier offsets of design section 7.2.
+ * @param name - the view name
+ * @param degree - the degree of every node the order sorts by
+ * @param perm - the carried permutation
+ * @param segmentOffsets - the carried tier offsets
+ */
+export function checkDegreeOrder(name, degree, perm, segmentOffsets) {
+    expectPermutation(name, "perm", perm);
+    let hi = 0;
+    let mid = 0;
+    let low = 0;
+    for (let i = 0; i < perm.length; i++) {
+        const d = degree[perm[i]];
+        if (i > 0) {
+            const previous = degree[perm[i - 1]];
+            if (d > previous || (d === previous && perm[i] < perm[i - 1])) {
+                throw viewError(name, "perm", i, "I2");
+            }
+        }
+        if (d >= DEGREE_TIER_HIGH) {
+            hi++;
+        }
+        else if (d >= DEGREE_TIER_MID) {
+            mid++;
+        }
+        else if (d >= 1) {
+            low++;
+        }
+    }
+    const expected = [0, hi, hi + mid, hi + mid + low, perm.length];
+    expectSame(name, "segmentOffsets", segmentOffsets, expected, "I2");
+}
+/**
+ * reverse (directed): the in-adjacency with rows sorted by source and ties by forward arc, `fwdArc`
+ * a permutation of the arcs, `colIdx` the sources, `weights` the forward weights gathered.
+ * @param snapshot - the snapshot
+ * @param facts - the core facts
+ * @param reverse - the carried view
+ */
+export function checkReverse(snapshot, facts, reverse) {
+    const { nodeCount, arcCount, colIdx } = snapshot;
+    const forward = snapshot.weights;
+    const { rowPtr, fwdArc } = reverse;
+    const revIdx = reverse.colIdx;
+    const revWeights = reverse.weights;
+    if (rowPtr[0] !== 0 || rowPtr[nodeCount] !== arcCount) {
+        throw viewError("reverse", "rowPtr", 0, "I2");
+    }
+    expectSame("reverse", "rowPtr", rowPtr, facts.inDegreePrefix(), "I2");
+    expectPermutation("reverse", "fwdArc", fwdArc);
+    for (let v = 0; v < nodeCount; v++) {
+        const end = rowPtr[v + 1];
+        for (let k = rowPtr[v]; k < end; k++) {
+            const a = fwdArc[k];
+            const source = facts.arcRow[a];
+            if (colIdx[a] !== v || revIdx[k] !== source) {
+                throw viewError("reverse", "colIdx", k, "I2");
+            }
+            if (k > rowPtr[v]) {
+                const previous = fwdArc[k - 1];
+                const previousSource = facts.arcRow[previous];
+                if (source < previousSource || (source === previousSource && a <= previous)) {
+                    throw viewError("reverse", "fwdArc", k, "I2");
+                }
+            }
+            if (revWeights !== null && forward !== null && !Object.is(revWeights[k], forward[a])) {
+                throw viewError("reverse", "weights", k, "I17");
+            }
+        }
+    }
+}
+/**
+ * An f64 view: compared with the snapshot's own computation.
+ * @param name - the view name
+ * @param found - the carried array
+ * @param expected - the computed truth
+ */
+export function checkF64View(name, found, expected) {
+    expectSame(name, "data", found, expected, "I17");
+}
+//# sourceMappingURL=carried-views.js.map

package/dist/src/wire/carried-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carried-views.js","sourceRoot":"","sources":["../../../src/wire/carried-views.ts"],"names":[],"mappings":"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"}

package/dist/src/wire/from-wire.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 { GraphFormatError } from "../errors.js";
+import { type GraphSnapshot } from "../snapshot/graph-snapshot.js";
+import { type FromWireOptions, type U8, type ValidationLevel, type WireSnapshot } from "../types/index.js";
+/** The meta.extra key naming the columns dropped under unknownColumns: "skip" (design section 9.1). */
+export declare const SKIPPED_COLUMNS_KEY = "graphty.skippedColumns";
+/**
+ * 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 declare function badWire(ref: string, reason: string, details?: Readonly<Record<string, unknown>>): GraphFormatError;
+/**
+ * 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 declare function decodeJsonValue(value: unknown, path: string, depth?: number): unknown;
+/**
+ * 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 declare function parseGuardedJson(text: string, path: string): unknown;
+/** The options of fromWire / fromBytes after defaults were applied. */
+interface ResolvedFromWireOptions {
+    /** The validation level. */
+    readonly level: ValidationLevel;
+    /** Whether buffers are copied before adoption. */
+    readonly copy: boolean;
+    /** What to do with an unknown column dtype. */
+    readonly unknownColumns: "error" | "skip";
+}
+/**
+ * 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 declare function resolveFromWireOptions(options: FromWireOptions | undefined, defaultLevel: ValidationLevel): ResolvedFromWireOptions;
+/** Where a located byte range lives. */
+export interface LocatedRange {
+    /** The plain ArrayBuffer holding the bytes. */
+    readonly buffer: ArrayBuffer;
+    /** The absolute byte offset of the range inside `buffer`. */
+    readonly byteOffset: number;
+}
+/**
+ * One buffer index of a manifest as the decoder sees it: a byte length for range checks, a locator
+ * that finds a range contiguously in one plain buffer (null when it spans chunks or lives in a
+ * SharedArrayBuffer) and a reader that copies a range out.
+ */
+export interface WireRegion {
+    /** The byte length every reference is checked against. */
+    readonly byteLength: number;
+    /**
+     * Find a byte range in one plain buffer.
+     * @param byteOffset - region-relative start
+     * @param byteLength - length
+     * @returns the buffer and absolute offset, or null when the range cannot be adopted
+     */
+    locate(byteOffset: number, byteLength: number): LocatedRange | null;
+    /**
+     * Copy a byte range into a fresh buffer.
+     * @param byteOffset - region-relative start
+     * @param byteLength - length
+     * @returns a Uint8Array at offset 0 of a fresh ArrayBuffer of at least byteLength bytes
+     */
+    read(byteOffset: number, byteLength: number): U8;
+}
+/**
+ * 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 declare function bufferRegion(buffer: ArrayBuffer, base: number, byteLength: number): WireRegion;
+/**
+ * Whether a value is a SharedArrayBuffer (never adopted, decision D-SAB).
+ * @param value - the value
+ * @returns true for a SharedArrayBuffer
+ */
+export declare function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
+/**
+ * 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 declare function checkManifestVersions(manifest: Record<string, unknown>): readonly [number, number];
+/**
+ * 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 declare function decodeManifest(manifestRaw: unknown, regions: readonly WireRegion[], options: ResolvedFromWireOptions, honourArena: boolean): GraphSnapshot;
+/**
+ * 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 declare function fromWire(wire: WireSnapshot, options?: FromWireOptions): GraphSnapshot;
+export {};
+//# sourceMappingURL=from-wire.d.ts.map

package/dist/src/wire/from-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-wire.d.ts","sourceRoot":"","sources":["../../../src/wire/from-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAkB,KAAK,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAE7F,OAAO,EAaH,KAAK,eAAe,EAMpB,KAAK,EAAE,EAEP,KAAK,eAAe,EAGpB,KAAK,YAAY,EACpB,MAAM,mBAAmB,CAAC;AAsE3B,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAI5D;;;;;;GAMG;AACH,wBAAgB,OAAO,CACnB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAChD,gBAAgB,CAElB;AAyED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAkChF;AAiCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CASpE;AAID,uEAAuE;AACvE,UAAU,uBAAuB;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,MAAM,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,eAAe,GAAG,SAAS,EACpC,YAAY,EAAE,eAAe,GAC9B,uBAAuB,CAoBzB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IACpE;;;;;OAKG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC;CACpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAY9F;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAukCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAoClG;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC1B,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,OAAO,EAAE,uBAAuB,EAChC,WAAW,EAAE,OAAO,GACrB,aAAa,CA6Ef;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,aAAa,CAkBrF"}