loopgraph 0.1.0

package/dist/validate/checks.js

@@ -0,0 +1,303 @@
+import { access } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { allNodes } from "../loader/model-graph.js";
+import { collectDanglingAppliesTo } from "../query/effective-constraints.js";
+import { anchorFilePath, isValidAnchorFormat } from "./anchor.js";
+/** Schema-parse failures collected during loadModel become blocking violations. */
+export function checkSchema(load) {
+    return load.parseErrors.map((e) => ({
+        check: "schema",
+        severity: "error",
+        message: e.message,
+        file: e.file,
+    }));
+}
+/**
+ * Advisory: a file-per-node file's name (minus extension) must equal the id of
+ * the single node it holds (Decision 004 技术点 3 — promised for Phase 1,
+ * delivered here in A7). Only single-node files are checked; array files that
+ * group many nodes under a section name (loops/*.yaml) carry the section, not
+ * an id, and are correctly exempt (see LoadResult.singleNodeFiles). Warning,
+ * not error: a mismatch is a naming-hygiene slip a human should fix, not a
+ * reason to fail a build (the model still loads correctly).
+ */
+export function checkFilenameMatchesId(load) {
+    const violations = [];
+    for (const [file, id] of load.singleNodeFiles) {
+        const stem = basename(file).replace(/\.(ya?ml)$/i, "");
+        if (stem !== id) {
+            violations.push({
+                check: "filename-id",
+                severity: "warning",
+                message: `file-per-node file "${file}" holds node "${id}" but its filename stem is "${stem}" — rename to "${id}.yaml" (Decision 004 file-per-node convention)`,
+                file,
+                nodeId: id,
+            });
+        }
+    }
+    return violations;
+}
+/** Duplicate ids collected during loadModel become blocking violations. */
+export function checkIdUniqueness(load) {
+    return load.duplicateIds.map((d) => ({
+        check: "id-uniqueness",
+        severity: "error",
+        message: `id "${d.id}" is declared more than once, in: ${d.files.join(", ")}`,
+        nodeId: d.id,
+    }));
+}
+/** Every anchor string a graph references: Loop.anchors, Junction.evidence[].anchor, Scenario.verified_by[]. */
+function collectAnchors(graph) {
+    const out = [];
+    for (const node of allNodes(graph)) {
+        if (node.kind === "loop") {
+            for (const anchor of node.anchors)
+                out.push({ nodeId: node.id, anchor });
+        }
+        else if (node.kind === "junction") {
+            for (const evidence of node.evidence)
+                out.push({ nodeId: node.id, anchor: evidence.anchor });
+        }
+        else if (node.kind === "scenario") {
+            for (const anchor of node.verified_by)
+                out.push({ nodeId: node.id, anchor });
+        }
+    }
+    return out;
+}
+/** Blocking: every anchor must be syntactically well-formed (file#symbol or table[.column]). */
+export function checkAnchorFormat(graph) {
+    const violations = [];
+    for (const { nodeId, anchor } of collectAnchors(graph)) {
+        if (!isValidAnchorFormat(anchor)) {
+            violations.push({
+                check: "anchor-format",
+                severity: "error",
+                message: `anchor "${anchor}" on ${nodeId} is not a valid "path#symbol" or "table[.column]" anchor`,
+                nodeId,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Every id-shaped cross-reference a node carries, paired with which kind
+ * it must resolve to. This is deliberately exhaustive over every
+ * reference-shaped field in the schema (Flow.traverses/guarded_by/
+ * references/crosses, Junction.between/scenarios, Loop.parent/scenarios,
+ * Feature.contains) — a reference field added to the schema later and
+ * forgotten here would silently stop being checked, so keep this in sync
+ * with src/schema/model.ts whenever a new reference field is added.
+ */
+function collectReferences(graph) {
+    const out = [];
+    for (const node of allNodes(graph)) {
+        if (node.kind === "feature") {
+            for (const id of node.contains)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "flow", field: "contains" });
+        }
+        else if (node.kind === "flow") {
+            for (const id of node.traverses)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "loop", field: "traverses" });
+            for (const id of node.guarded_by)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "loop", field: "guarded_by" });
+            for (const id of node.references)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "flow", field: "references" });
+            for (const id of node.crosses)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "junction", field: "crosses" });
+        }
+        else if (node.kind === "loop") {
+            if (node.parent)
+                out.push({ nodeId: node.id, targetId: node.parent, targetKind: "loop", field: "parent" });
+            for (const id of node.scenarios)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "scenario", field: "scenarios" });
+        }
+        else if (node.kind === "junction") {
+            for (const id of node.between)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "loop", field: "between" });
+            for (const id of node.scenarios)
+                out.push({ nodeId: node.id, targetId: id, targetKind: "scenario", field: "scenarios" });
+        }
+    }
+    return out;
+}
+/**
+ * Blocking: every cross-node reference (Flow.traverses, Junction.between,
+ * Loop.parent, etc.) must resolve to an actual node of the expected kind
+ * in the loaded graph. This is pure set-membership over an already-loaded
+ * graph — no I/O, no AST — so it stays within T0's cost budget despite
+ * catching what would otherwise be a silent dangling/typo'd reference
+ * (e.g. a Flow.traverses entry that matches the LoopId regex shape but
+ * names a Loop that was never actually defined).
+ */
+export function checkReferentialIntegrity(graph) {
+    const violations = [];
+    for (const { nodeId, targetId, targetKind, field } of collectReferences(graph)) {
+        if (!graph.byKind[targetKind].has(targetId)) {
+            violations.push({
+                check: "referential-integrity",
+                severity: "error",
+                message: `${nodeId}.${field} references "${targetId}", which is not a defined ${targetKind}`,
+                nodeId,
+            });
+        }
+    }
+    // Scenario.applies_to.nodes is checked separately: unlike every other
+    // reference field, it's valid against ANY of the 6 kinds (Decision
+    // record 004, 技术点 2), so it doesn't fit collectReferences' one-
+    // targetKind-per-field shape.
+    for (const { scenarioId, targetId } of collectDanglingAppliesTo(graph)) {
+        violations.push({
+            check: "referential-integrity",
+            severity: "error",
+            message: `${scenarioId}.applies_to.nodes references "${targetId}", which is not a defined node of any kind`,
+            nodeId: scenarioId,
+        });
+    }
+    return violations;
+}
+/**
+ * Standard DFS back-edge cycle detection over a directed adjacency map.
+ * Returns every distinct cycle found, each as a node-id path that starts
+ * and ends on the same id (e.g. ["L1a", "L1b", "L1a"]). Duplicate
+ * reports of the same cycle entered from different starting nodes are
+ * collapsed by rotating each cycle to start at its lexicographically
+ * smallest id before deduping.
+ */
+function findCycles(adjacency) {
+    const color = new Map();
+    const stack = [];
+    const found = [];
+    function visit(node) {
+        color.set(node, "gray");
+        stack.push(node);
+        for (const next of adjacency.get(node) ?? []) {
+            if (color.get(next) === "gray") {
+                const idx = stack.indexOf(next);
+                found.push([...stack.slice(idx), next]);
+            }
+            else if (color.get(next) !== "black") {
+                visit(next);
+            }
+        }
+        stack.pop();
+        color.set(node, "black");
+    }
+    for (const node of adjacency.keys()) {
+        if (!color.has(node))
+            visit(node);
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const cycle of found) {
+        const ring = cycle.slice(0, -1); // drop the repeated closing id
+        let minIdx = 0;
+        for (let i = 1; i < ring.length; i++) {
+            const candidate = ring[i];
+            const current = ring[minIdx];
+            if (candidate !== undefined && current !== undefined && candidate < current)
+                minIdx = i;
+        }
+        const canonical = [...ring.slice(minIdx), ...ring.slice(0, minIdx)];
+        const key = canonical.join("->");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const first = canonical[0];
+        if (first === undefined)
+            continue; // ring/canonical structurally non-empty; guard, not assertion
+        deduped.push([...canonical, first]);
+    }
+    return deduped;
+}
+/**
+ * The only two fields in the schema that can form a cycle: `Loop.parent`
+ * and `Flow.references` both point at their own kind. Every other
+ * reference field is a bipartite edge into a different kind with no edge
+ * pointing back (see checkGraphAcyclic's docstring for the full
+ * argument), so a cycle is structurally impossible through them today.
+ * Adding ANY new node-reference field to the schema — same-kind or
+ * cross-kind — requires re-deriving that argument from scratch and
+ * updating this list if it turns out to close a cycle.
+ */
+const CYCLE_EDGE_SPECS = {
+    loop: {
+        field: "parent",
+        targets: (nodeId, graph) => {
+            const parent = graph.byKind.loop.get(nodeId)?.parent;
+            return parent ? [parent] : [];
+        },
+    },
+    flow: {
+        field: "references",
+        targets: (nodeId, graph) => graph.byKind.flow.get(nodeId)?.references ?? [],
+    },
+};
+/**
+ * Blocking: neither `Loop.parent` nor `Flow.references` may form a
+ * cycle. These are the only two same-kind reference fields in the
+ * schema; every other reference field (Flow.traverses/guarded_by/
+ * crosses, Junction.between/scenarios, Loop.scenarios, Feature.contains)
+ * is a bipartite edge into a *different* kind, and that target kind
+ * carries no reference field pointing back to the source kind (Scenario
+ * has no node-reference outputs at all; Loop's only outputs are `parent`
+ * and `scenarios`; Junction's only outputs are `between` and
+ * `scenarios`) — so no cross-kind cycle is reachable through the current
+ * schema. This is a claim about today's schema shape, not a structural
+ * guarantee: adding any new node-reference field (same-kind OR
+ * cross-kind) invalidates it and requires re-deriving which edges can
+ * now close a cycle.
+ */
+export function checkGraphAcyclic(graph) {
+    const violations = [];
+    for (const [kind, spec] of Object.entries(CYCLE_EDGE_SPECS)) {
+        const adjacency = new Map();
+        for (const id of graph.byKind[kind].keys()) {
+            adjacency.set(id, spec.targets(id, graph));
+        }
+        for (const cycle of findCycles(adjacency)) {
+            const nodeId = cycle[0]; // findCycles never returns an empty ring; guard rather than assert
+            if (nodeId === undefined)
+                continue;
+            violations.push({
+                check: "graph-acyclic",
+                severity: "error",
+                message: `${kind}.${spec.field} forms a cycle: ${cycle.join(" -> ")}`,
+                nodeId,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Advisory by default: does the anchored file exist under `repoRoot`?
+ * This deliberately does NOT check the symbol resolves inside the file —
+ * that needs real AST parsing (Phase 2 adapter work). It also does not
+ * fail the build by default (severity: "warning") because a target repo's
+ * HEAD legitimately moves past whatever commit the model was authored
+ * against; treat failures here as "investigate: mis-encoded vs. code
+ * moved on", not as a hard gate. Pass `strict: true` to promote to error
+ * once a repo pins anchors to a known-good commit.
+ */
+export async function checkAnchorExistence(graph, repoRoot, options = {}) {
+    const violations = [];
+    const severity = options.strict ? "error" : "warning";
+    for (const { nodeId, anchor } of collectAnchors(graph)) {
+        const filePath = anchorFilePath(anchor);
+        if (!filePath)
+            continue; // table-style anchors have no file to check
+        const exists = await access(join(repoRoot, filePath))
+            .then(() => true)
+            .catch(() => false);
+        if (!exists) {
+            violations.push({
+                check: "anchor-existence",
+                severity,
+                message: `anchor "${anchor}" on ${nodeId} points at "${filePath}", which does not exist under ${repoRoot}`,
+                nodeId,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=checks.js.map

package/dist/validate/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./anchor.js";
+export * from "./checks.js";
+export * from "./baseline.js";
+export * from "./t0.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/validate/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./anchor.js";
+export * from "./checks.js";
+export * from "./baseline.js";
+export * from "./t0.js";
+//# sourceMappingURL=index.js.map

package/dist/validate/inv1/check.d.ts

@@ -0,0 +1,36 @@
+import type { Violation } from "../types.js";
+import type { Inv1Config } from "./config.js";
+import { type WritePoint } from "./scan.js";
+export interface Inv1CheckResult {
+    /** false when the scan couldn't run (no git checkout) — a loud skip, not a silent pass. */
+    ran: boolean;
+    skippedReason?: string;
+    /** Every classified write point (allowed + violation + unanalyzable) — the inventory for human verification. */
+    writePoints: WritePoint[];
+    candidateFiles: number;
+    filesScanned: number;
+    timingMs: number;
+}
+export interface Inv1CheckOptions {
+    /**
+     * Incremental mode (B2): when set, only candidate files also in this set are
+     * scanned — the diff closure, not the whole repo. `candidateFiles` still
+     * reports the full candidate count so the ratio (scanned/candidate) is visible.
+     */
+    onlyFiles?: Set<string>;
+}
+/**
+ * Runs the INV-1 canonical-writer scan over `repoRoot` using `config`. Kept
+ * OUT of `runT0` on purpose (see t0.ts docstring): it needs a whole-repo scan,
+ * so it is timed and gated independently. The scan primitive it calls is pure;
+ * only the candidate selection + file reads here do I/O.
+ */
+export declare function runInv1Check(repoRoot: string, config: Inv1Config, options?: Inv1CheckOptions): Promise<Inv1CheckResult>;
+/**
+ * Maps scan write points to T0 violations: a `violation` verdict is a blocking
+ * error (a guarded column written from outside the allowlist); `unanalyzable`
+ * is an advisory warning (surfaced for human confirmation, never silently
+ * passed); `allowed` points are inventory only, not violations.
+ */
+export declare function inv1ViolationsFrom(result: Inv1CheckResult): Violation[];
+//# sourceMappingURL=check.d.ts.map

package/dist/validate/inv1/check.js

@@ -0,0 +1,96 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { scanFileForGuardedWrites } from "./scan.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Candidate pre-filter (proposal 001 §6 / 006 A6: "grep 预筛候选文件，再对候选做
+ * AST 确认"). `git grep -l` is the impure narrowing step (fast, tracked files
+ * only, respects .gitignore); the pure AST scan then confirms each candidate.
+ * Returns undefined when the target is not a usable git checkout.
+ *
+ * Pattern `update\(` (not `\.update\(`) so a destructured/re-exported binding
+ * `const { update } = db; update(runs)…` still lands a file in the candidate
+ * set — under-matching here would be a silent miss, over-matching only costs a
+ * cheap extra AST parse. The one residual is a *renamed* method
+ * (`const u = db.update`), which no grep pattern for `update(` can catch — a
+ * documented limitation (does not occur in the target today).
+ */
+async function gitGrepCandidates(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["grep", "-lE", "update\\(", "--", "*.ts", ":!*.test.ts", ":!*.spec.ts"], { cwd: repoRoot, maxBuffer: 64 * 1024 * 1024 });
+        return stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    catch (err) {
+        // git grep exits 1 when there are simply NO matches — an empty candidate
+        // set, not a failure. Any other exit (128 = not a repo, ENOENT = no git)
+        // is a real "cannot run" and surfaces as a skip.
+        if (err.code === 1)
+            return [];
+        return undefined;
+    }
+}
+/**
+ * Runs the INV-1 canonical-writer scan over `repoRoot` using `config`. Kept
+ * OUT of `runT0` on purpose (see t0.ts docstring): it needs a whole-repo scan,
+ * so it is timed and gated independently. The scan primitive it calls is pure;
+ * only the candidate selection + file reads here do I/O.
+ */
+export async function runInv1Check(repoRoot, config, options = {}) {
+    const start = performance.now();
+    const candidates = await gitGrepCandidates(repoRoot);
+    if (candidates === undefined) {
+        return {
+            ran: false,
+            skippedReason: "INV-1 scan needs a git checkout (git grep unavailable at repo-root)",
+            writePoints: [],
+            candidateFiles: 0,
+            filesScanned: 0,
+            timingMs: performance.now() - start,
+        };
+    }
+    const toScan = options.onlyFiles
+        ? candidates.filter((c) => options.onlyFiles?.has(c))
+        : candidates;
+    const writePoints = [];
+    let filesScanned = 0;
+    for (const rel of toScan) {
+        const content = await readFile(join(repoRoot, rel), "utf8").catch(() => undefined);
+        if (content === undefined)
+            continue; // a listed-but-unreadable file (race/symlink) — skip, don't crash
+        filesScanned++;
+        writePoints.push(...scanFileForGuardedWrites(rel, content, config));
+    }
+    return {
+        ran: true,
+        writePoints,
+        candidateFiles: candidates.length,
+        filesScanned,
+        timingMs: performance.now() - start,
+    };
+}
+/**
+ * Maps scan write points to T0 violations: a `violation` verdict is a blocking
+ * error (a guarded column written from outside the allowlist); `unanalyzable`
+ * is an advisory warning (surfaced for human confirmation, never silently
+ * passed); `allowed` points are inventory only, not violations.
+ */
+export function inv1ViolationsFrom(result) {
+    const out = [];
+    for (const wp of result.writePoints) {
+        if (wp.verdict === "allowed")
+            continue;
+        out.push({
+            check: "inv1-write-site",
+            severity: wp.verdict === "violation" ? "error" : "warning",
+            message: `${wp.reason} — ${wp.filePath}:${wp.line} (${wp.snippet})`,
+            file: wp.filePath,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=check.js.map

package/dist/validate/inv1/config.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * INV-1 (canonical-writer) enforcement config, per proposal 001 §6 and
+ * Proposal 006 A6. Lives in the TARGET repo (or, pre-GATE-1, in the agenthub
+ * adapter's example dir) so the engine hard-codes NO business paths — it only
+ * provides the generic "guarded-column write-site scan + location allowlist"
+ * primitive; which tables/columns are guarded and which paths may write them
+ * is data supplied here.
+ *
+ * Shipped as JSON (not the plan's `loopgraph.config.ts`) deliberately: T0 must
+ * stay <5s and must not compile TypeScript in its hot path, and JSON needs no
+ * TS-loader dependency. How config ultimately lands in the target repo (`.ts` vs `.json`,
+ * repo location) is a GATE-1 (A8) decision — A6 does not pre-empt it.
+ */
+export declare const GuardedTableConfig: z.ZodObject<{
+    /** Guarded state columns (drizzle property names), e.g. ["status"]. */
+    columns: z.ZodArray<z.ZodString, "many">;
+    /** Repo-relative path prefixes whose files MAY write these columns (the canonical writer). */
+    allowlist: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    columns: string[];
+    allowlist: string[];
+}, {
+    columns: string[];
+    allowlist: string[];
+}>;
+export type GuardedTableConfig = z.infer<typeof GuardedTableConfig>;
+export declare const Inv1Config: z.ZodObject<{
+    /** Keyed by the drizzle table identifier as written in code (e.g. `runs`, `sessions`). */
+    guardedTables: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Guarded state columns (drizzle property names), e.g. ["status"]. */
+        columns: z.ZodArray<z.ZodString, "many">;
+        /** Repo-relative path prefixes whose files MAY write these columns (the canonical writer). */
+        allowlist: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        columns: string[];
+        allowlist: string[];
+    }, {
+        columns: string[];
+        allowlist: string[];
+    }>>;
+    /** Alias identifier → canonical guarded-table identifier (for `import { runs as runsTable }`). */
+    aliases: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /**
+     * Path prefixes where a dynamic-table `update(<expr>).set(...)` is known to be
+     * a table-agnostic generic primitive (e.g. `packages/db`), so it is NOT
+     * surfaced as unanalyzable. Everything else dynamic outside the allowlist is.
+     */
+    unanalyzableExceptions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    guardedTables: Record<string, {
+        columns: string[];
+        allowlist: string[];
+    }>;
+    aliases: Record<string, string>;
+    unanalyzableExceptions: string[];
+}, {
+    guardedTables: Record<string, {
+        columns: string[];
+        allowlist: string[];
+    }>;
+    aliases?: Record<string, string> | undefined;
+    unanalyzableExceptions?: string[] | undefined;
+}>;
+export type Inv1Config = z.infer<typeof Inv1Config>;
+export interface LoadInv1ConfigResult {
+    /** Parsed config, or undefined when no config file is present (INV-1 simply not run). */
+    config?: Inv1Config;
+    /** Set when a config file exists but is malformed — a loud error, not a silent skip. */
+    error?: string;
+}
+export declare const INV1_CONFIG_FILENAME = "loopgraph.config.json";
+/** Loads and validates `<dir>/loopgraph.config.json`. Absent file → `{}` (skip); present+invalid → `{error}`. */
+export declare function loadInv1Config(dir: string): Promise<LoadInv1ConfigResult>;
+//# sourceMappingURL=config.d.ts.map

package/dist/validate/inv1/config.js

@@ -0,0 +1,63 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * INV-1 (canonical-writer) enforcement config, per proposal 001 §6 and
+ * Proposal 006 A6. Lives in the TARGET repo (or, pre-GATE-1, in the agenthub
+ * adapter's example dir) so the engine hard-codes NO business paths — it only
+ * provides the generic "guarded-column write-site scan + location allowlist"
+ * primitive; which tables/columns are guarded and which paths may write them
+ * is data supplied here.
+ *
+ * Shipped as JSON (not the plan's `loopgraph.config.ts`) deliberately: T0 must
+ * stay <5s and must not compile TypeScript in its hot path, and JSON needs no
+ * TS-loader dependency. How config ultimately lands in the target repo (`.ts` vs `.json`,
+ * repo location) is a GATE-1 (A8) decision — A6 does not pre-empt it.
+ */
+export const GuardedTableConfig = z.object({
+    /** Guarded state columns (drizzle property names), e.g. ["status"]. */
+    columns: z.array(z.string().min(1)).min(1),
+    /** Repo-relative path prefixes whose files MAY write these columns (the canonical writer). */
+    allowlist: z.array(z.string().min(1)).min(1),
+});
+export const Inv1Config = z.object({
+    /** Keyed by the drizzle table identifier as written in code (e.g. `runs`, `sessions`). */
+    guardedTables: z.record(z.string(), GuardedTableConfig),
+    /** Alias identifier → canonical guarded-table identifier (for `import { runs as runsTable }`). */
+    aliases: z.record(z.string(), z.string()).default({}),
+    /**
+     * Path prefixes where a dynamic-table `update(<expr>).set(...)` is known to be
+     * a table-agnostic generic primitive (e.g. `packages/db`), so it is NOT
+     * surfaced as unanalyzable. Everything else dynamic outside the allowlist is.
+     */
+    unanalyzableExceptions: z.array(z.string()).default([]),
+});
+export const INV1_CONFIG_FILENAME = "loopgraph.config.json";
+/** Loads and validates `<dir>/loopgraph.config.json`. Absent file → `{}` (skip); present+invalid → `{error}`. */
+export async function loadInv1Config(dir) {
+    const path = join(dir, INV1_CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return {}; // no config → INV-1 not configured for this target
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            error: `${INV1_CONFIG_FILENAME} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const parsed = Inv1Config.safeParse(json);
+    if (!parsed.success) {
+        return {
+            error: `${INV1_CONFIG_FILENAME} failed schema validation: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+        };
+    }
+    return { config: parsed.data };
+}
+//# sourceMappingURL=config.js.map

package/dist/validate/inv1/scan.d.ts

@@ -0,0 +1,49 @@
+import type { Inv1Config } from "./config.js";
+/**
+ * INV-1 write-site scanner (Proposal 006 A6). A PURE function of
+ * `(filePath, content, config)` — no file I/O, no git, no TS type-checking.
+ * It parses `content` with `ts.createSourceFile` (a pure in-memory syntax
+ * parse) and walks the AST for drizzle guarded-column write expressions.
+ *
+ * Purity is load-bearing: it is the precondition for the B3 machine-level
+ * cache, whose key is `hash(adapter_version, blob_oid, config_hash)` — same
+ * bytes + same config ⇒ same result, so config is an explicit parameter, never
+ * read from disk inside here.
+ *
+ * Why AST, not regex (acceptance (a) = no false-negatives): a regex can only
+ * find the forms it anticipates, so an unrecognized guarded write becomes a
+ * SILENT miss. Walking the AST classifies every guarded-table write chain, so
+ * anything not confidently analyzable falls into `unanalyzable` by
+ * construction — the conservative, human-review bucket. Chain SHAPE also
+ * disambiguates drizzle `db.update(runs).set({...})` from lookalikes like
+ * `hash.update(x).digest()` (no `.set`) without needing types.
+ *
+ * Recognized guarded-table transition-write forms:
+ *   - `update(TABLE).set(...)`
+ *   - `insert(TABLE)…onConflictDoUpdate({ set: {...} })` (an upsert IS a
+ *     transition, so it is classified, not silently skipped)
+ * TABLE is resolved from a bare identifier via: config.guardedTables →
+ * config.aliases → file-local `const X = <guardedTable>` aliases (pre-scanned).
+ *
+ * Documented residual false-negatives (no data-flow/type analysis, on purpose,
+ * to keep the parse pure and within T0's <5s budget): a guarded table reached
+ * through a *renamed method* (`const u = db.update; u(runs)`) or a *reassigned /
+ * parameter-passed* table binding is not resolved. Pure `insert(TABLE).values`
+ * (row creation, i.e. INITIAL state, not a transition) is deliberately out of
+ * INV-1's transition scope. None of these forms occur in the current target today (verified);
+ * recorded here rather than left silent.
+ */
+export type WriteVerdict = "allowed" | "violation" | "unanalyzable";
+export interface WritePoint {
+    filePath: string;
+    /** 1-based line, for a human reading the report — deliberately NOT used as a stable anchor. */
+    line: number;
+    /** Resolved guarded table identifier, or null for a dynamic (non-identifier) table expression. */
+    table: string | null;
+    columns: string[] | "opaque";
+    verdict: WriteVerdict;
+    reason: string;
+    snippet: string;
+}
+export declare function scanFileForGuardedWrites(filePath: string, content: string, config: Inv1Config): WritePoint[];
+//# sourceMappingURL=scan.d.ts.map