@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/snapshot/validate.d.ts

@@ -0,0 +1,192 @@
+/**
+ * `validate()` (design sections 3.2, 9.5 and 11.4): the invariants I1-I13 as one function each, the
+ * two levels "structure" (O(n + m + columns): lengths, ranges, counts, alignment, column length
+ * rules) and "full" (O(m log d): sortedness, orientation, pairing, NaN, flag recomputation, id
+ * bijection, unique columns), and the flag predicates of design section 3.8 shared with the derived
+ * graph core builder so that every flag has exactly one definition.
+ *
+ * Every check throws `E_INVALID_SNAPSHOT` on the first violation with `details.invariant` naming the
+ * number ("I4") and the location (`row`, `arc`, `edge`, `column`, `table`, `flag`, `reason`). The
+ * functions take the public `GraphSnapshot` contract, so test/invariants.test.ts runs the same
+ * helpers over hand-written fixtures. Checksum comparison needs the snapshot's private records and
+ * lives in graph-snapshot.ts.
+ */
+import { GraphFormatError } from "../errors.js";
+import { type Column, type F32, type GraphSnapshot, type SnapshotFlags, type U32 } from "../types/index.js";
+/**
+ * Build the E_INVALID_SNAPSHOT error of one violated invariant.
+ * @param invariant - the invariant number, e.g. "I4"
+ * @param message - a plain-ASCII description naming the location
+ * @param details - the location (row, arc, edge, column, ...); `invariant` is added
+ * @returns the error
+ */
+export declare function invariantViolation(invariant: string, message: string, details?: Readonly<Record<string, unknown>>): GraphFormatError;
+/** The arrays the flag predicates read; a subset of the core so the builder can call it before the snapshot exists. */
+interface FlagSource {
+    /** Whether the graph is directed. */
+    readonly directed: boolean;
+    /** The node count. */
+    readonly nodeCount: number;
+    /** The row offsets. */
+    readonly rowPtr: U32;
+    /** The sorted targets. */
+    readonly colIdx: U32;
+    /** The per-arc weights, or null. */
+    readonly weights: F32 | null;
+    /** The arc -> edge permutation, or null when it is known to be the identity. */
+    readonly arcToEdge: U32 | null;
+    /** The number of self-loop logical edges. */
+    readonly selfLoopCount: number;
+}
+/**
+ * The number of arcs a with colIdx[a] === row(a).
+ * @param rowPtr - the row offsets
+ * @param colIdx - the sorted targets
+ * @param nodeCount - the node count
+ * @returns the loop arc count
+ */
+export declare function countLoopArcs(rowPtr: U32, colIdx: U32, nodeCount: number): number;
+/**
+ * Whether a permutation array is the identity.
+ * @param perm - the array
+ * @returns true when perm[i] === i for every i
+ */
+export declare function isIdentity(perm: U32): boolean;
+/**
+ * Compute every flag of design section 3.8 from the arrays (invariant I9: never guessed).
+ * @param core - the arrays and counts the predicates read
+ * @returns the truthful flags
+ */
+export declare function computeFlags(core: FlagSource): SnapshotFlags;
+/**
+ * I1: rowPtr has nodeCount + 1 entries, starts at 0, is non-decreasing and ends at arcCount ===
+ * colIdx.length.
+ * @param s - the snapshot
+ */
+export declare function checkI1(s: GraphSnapshot): void;
+/**
+ * I2: every colIdx entry is below nodeCount (so INVALID_INDEX never appears).
+ * @param s - the snapshot
+ */
+export declare function checkI2(s: GraphSnapshot): void;
+/**
+ * I3: the counts are non-negative integers at most MAX_COUNT, edgeCount <= arcCount and selfLoopCount
+ * <= edgeCount.
+ * @param s - the snapshot
+ */
+export declare function checkI3(s: GraphSnapshot): void;
+/**
+ * I4: within every row colIdx is non-decreasing and arcs with equal colIdx are ordered by ascending
+ * arcToEdge. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI4(s: GraphSnapshot): void;
+/**
+ * I5 (structure part): arcToEdge has arcCount entries below edgeCount and edgeToArc has edgeCount
+ * entries below arcCount; an identity flag requires arcCount === edgeCount and a directed snapshot.
+ * @param s - the snapshot
+ */
+export declare function checkI5Ranges(s: GraphSnapshot): void;
+/**
+ * I5 (orientation part): arcToEdge[edgeToArc[e]] === e for every edge. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI5Orientation(s: GraphSnapshot): void;
+/**
+ * I6: a directed snapshot has arcCount === edgeCount (structure) and arcToEdge is a permutation of
+ * 0..edgeCount-1 (full: every edge exactly once).
+ * @param s - the snapshot
+ * @param full - whether to run the permutation check
+ */
+export declare function checkI6(s: GraphSnapshot, full: boolean): void;
+/**
+ * I7 (structure part): an undirected snapshot has arcCount === 2 * edgeCount - selfLoopCount.
+ * @param s - the snapshot
+ */
+export declare function checkI7Counts(s: GraphSnapshot): void;
+/**
+ * I7 (pairing part): every arc u -> v with u !== v has exactly one mate v -> u with the same logical
+ * edge and weight, a self-loop edge has exactly one arc, and every edge appears once (loop) or twice
+ * (mates). The lockstep walk of design section 6.4. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI7Pairing(s: GraphSnapshot): void;
+/**
+ * I8 (length part): weights is null or has arcCount entries.
+ * @param s - the snapshot
+ */
+export declare function checkI8Length(s: GraphSnapshot): void;
+/**
+ * I8 (value part): no weight is NaN. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI8NaN(s: GraphSnapshot): void;
+/**
+ * I9: every flag equals its predicate over the arrays, and selfLoopCount equals the number of loop
+ * arcs. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI9(s: GraphSnapshot): void;
+/**
+ * I10: every core array is 4-byte aligned over a plain ArrayBuffer and, when an arena exists, every
+ * array with a non-null segment is the 256-aligned view the segment describes and hotByteLength is the
+ * end of the weights (or colIdx, or rowPtr) segment.
+ * @param s - the snapshot
+ */
+export declare function checkI10(s: GraphSnapshot): void;
+/**
+ * I11 (size part): the id map has nodeCount ids.
+ * @param s - the snapshot
+ */
+export declare function checkI11Size(s: GraphSnapshot): void;
+/**
+ * I11 (bijection part): ids.indexOf(ids.idOf(i)) === i for every i and no id is NaN. Full level.
+ * @param s - the snapshot
+ */
+export declare function checkI11Bijection(s: GraphSnapshot): void;
+/**
+ * The length rules of design section 5.7 for one column, plus dictionary code ranges, refersTo
+ * ranges, the recorded nullCount (recomputed from the bitmap, design section 9.5) and the plain
+ * ArrayBuffer rule of I10 for every typed array the column exposes (I12).
+ * @param table - the table name for the message
+ * @param column - the column
+ * @param rows - the table's row count
+ * @param s - the snapshot (for the referenced row counts)
+ */
+export declare function checkColumnRules(table: string, column: Column, rows: number, s: GraphSnapshot): void;
+/**
+ * I12: the node, edge and graph tables have nodeCount, edgeCount and 1 rows, every column (extension
+ * tables included) obeys its length rules, dictionary codes are in range and refersTo values are in
+ * range or INVALID_INDEX with the row unset.
+ * @param s - the snapshot
+ */
+export declare function checkI12(s: GraphSnapshot): void;
+/**
+ * I13: edge attribute columns are indexed by logical edge: the edge table has edgeCount rows.
+ * @param s - the snapshot
+ */
+export declare function checkI13(s: GraphSnapshot): void;
+/**
+ * The "structure" level of design section 9.5: I1-I3, I5 lengths and ranges, I6 / I7 counts, I8
+ * length, I10, I11 size, I12 lengths and ranges, I13. O(n + m + columns).
+ * @param s - the snapshot
+ */
+export declare function validateStructure(s: GraphSnapshot): void;
+/**
+ * The "full" level of design section 9.5: structure plus I4, I5 orientation, I6 permutation, I8 NaN
+ * (before the pairing walk, so a NaN weight is reported as I8 rather than as an unequal mate), I7
+ * pairing, I9 flags, I11 bijection and unique columns. O(m log d).
+ * @param s - the snapshot
+ */
+export declare function validateFull(s: GraphSnapshot): void;
+/**
+ * The `unique` rule of a column as a validation failure (design sections 9.5 and 11.4): the
+ * freeze-time codes E_DUPLICATE_ID / E_DUPLICATE_EDGE_ID of `verifyUniqueColumn` become
+ * E_INVALID_SNAPSHOT with `details.invariant` "I12", `details.reason` "unique" and the original
+ * code in `details.cause`, so a reader of untrusted input sees one error family.
+ * @param table - the table name for the message
+ * @param column - the column
+ */
+export declare function checkUniqueColumn(table: string, column: Column): void;
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/dist/src/snapshot/validate.d.ts.map

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