loopgraph 0.1.0

package/dist/validate/inv1/scan.js

@@ -0,0 +1,172 @@
+import ts from "typescript";
+/** True if `filePath` is under (or equal to) one of the prefixes, matched at a path boundary. */
+function underAnyPrefix(filePath, prefixes) {
+    const norm = filePath.replace(/\\/g, "/");
+    return prefixes.some((p) => {
+        const pfx = p.replace(/\\/g, "/").replace(/\/$/, "");
+        return norm === pfx || norm.startsWith(`${pfx}/`);
+    });
+}
+/** Columns named by an object literal's keys, or "opaque" for a spread / computed key / non-object. */
+function columnsOfObjectLiteral(expr) {
+    if (!expr || !ts.isObjectLiteralExpression(expr))
+        return "opaque"; // .set(variable) etc.
+    const cols = [];
+    for (const prop of expr.properties) {
+        if (ts.isSpreadAssignment(prop))
+            return "opaque"; // {...base} may hide a guarded column
+        if (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) {
+            const name = prop.name;
+            if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+                cols.push(name.text);
+            else
+                return "opaque"; // computed property name — can't resolve statically
+        }
+        else {
+            return "opaque"; // method / accessor — treat conservatively
+        }
+    }
+    return cols;
+}
+/** The `set:` value inside an `onConflictDoUpdate({ target, set })` argument. */
+function columnsOfOnConflictSet(arg) {
+    if (!arg || !ts.isObjectLiteralExpression(arg))
+        return "opaque";
+    for (const prop of arg.properties) {
+        if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) && prop.name.text === "set") {
+            return columnsOfObjectLiteral(prop.initializer);
+        }
+        // A shorthand `{ set }` means `set` is a variable reference — its columns
+        // aren't visible, which is exactly "opaque". Fall through to the opaque
+        // return below rather than special-casing to the same result.
+    }
+    return "opaque"; // no static `set: {…}` property found (absent, or shorthand/variable)
+}
+/**
+ * Descends a `db.insert(T).values(...).onConflictDoUpdate(...)` / `db.update(T).set(...)`
+ * receiver chain to the `insert`/`update` call and returns its first argument
+ * (the table expression), or undefined if the chain has no such call.
+ */
+function tableArgInChain(node) {
+    let cur = node;
+    while (ts.isCallExpression(cur) && ts.isPropertyAccessExpression(cur.expression)) {
+        const method = cur.expression.name.text;
+        if (method === "insert" || method === "update")
+            return cur.arguments[0];
+        cur = cur.expression.expression;
+    }
+    return undefined;
+}
+export function scanFileForGuardedWrites(filePath, content, config) {
+    const src = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const points = [];
+    const anyGuardedAllowlist = Object.values(config.guardedTables).flatMap((t) => t.allowlist);
+    const inAnyAllowlist = underAnyPrefix(filePath, anyGuardedAllowlist);
+    const inExceptions = underAnyPrefix(filePath, config.unanalyzableExceptions);
+    const configResolve = (ident) => {
+        if (config.guardedTables[ident])
+            return ident;
+        const canon = config.aliases[ident];
+        return canon && config.guardedTables[canon] ? canon : undefined;
+    };
+    // Pre-scan file-local aliases: `const X = runs` (initializer is a guarded
+    // table identifier). Bounded, pure; closes the local-alias gap without
+    // flagging every non-guarded update as unanalyzable.
+    const localAliases = new Map();
+    (function collectAliases(node) {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isIdentifier(node.initializer)) {
+            const resolved = configResolve(node.initializer.text);
+            if (resolved)
+                localAliases.set(node.name.text, resolved);
+        }
+        ts.forEachChild(node, collectAliases);
+    })(src);
+    const resolveTable = (ident) => configResolve(ident) ?? localAliases.get(ident);
+    const lineOf = (node) => src.getLineAndCharacterOfPosition(node.getStart(src)).line + 1;
+    const snippetOf = (node) => content.slice(node.getStart(src), node.getEnd()).replace(/\s+/g, " ").trim().slice(0, 120);
+    function classify(tableArg, columns, at, form) {
+        // Dynamic table (non-identifier): could be a guarded table via a variable.
+        if (!tableArg || !ts.isIdentifier(tableArg)) {
+            if (inExceptions || inAnyAllowlist)
+                return; // db-generic primitive, or a canonical-writer file → not surfaced
+            points.push({
+                filePath,
+                line: lineOf(at),
+                table: null,
+                columns: "opaque",
+                verdict: "unanalyzable",
+                reason: `dynamic table expression in ${form} outside every writer allowlist — cannot confirm it is not a guarded write`,
+                snippet: snippetOf(at),
+            });
+            return;
+        }
+        const table = resolveTable(tableArg.text);
+        if (!table)
+            return; // a bare identifier that is not a guarded table → a write to some other table, ignore
+        const guarded = config.guardedTables[table];
+        if (!guarded)
+            return; // unreachable (resolveTable guarantees it), guard not assertion
+        // Two orthogonal facts, kept as distinct booleans for clarity: whether the
+        // column set is knowable at all, and (if it is) whether it touches a
+        // guarded column.
+        const isOpaque = columns === "opaque";
+        const guardedCols = isOpaque ? [] : columns.filter((c) => guarded.columns.includes(c));
+        if (!isOpaque && guardedCols.length === 0)
+            return; // writes only non-guarded columns → not an INV-1 concern
+        const allowed = underAnyPrefix(filePath, guarded.allowlist);
+        const base = { filePath, line: lineOf(at), table, columns, snippet: snippetOf(at) };
+        if (allowed) {
+            points.push({
+                ...base,
+                verdict: "allowed",
+                reason: isOpaque
+                    ? `opaque ${form} to guarded table ${table}, but writer file is in its allowlist`
+                    : `guarded column write to ${table} from an allowlisted canonical writer`,
+            });
+        }
+        else if (!isOpaque) {
+            points.push({
+                ...base,
+                verdict: "violation",
+                reason: `writes guarded column(s) [${guardedCols.join(", ")}] of ${table} from outside its writer allowlist (${guarded.allowlist.join(", ")})`,
+            });
+        }
+        else {
+            points.push({
+                ...base,
+                verdict: "unanalyzable",
+                reason: `opaque ${form} to guarded table ${table} outside its writer allowlist — may write a guarded column`,
+            });
+        }
+    }
+    function visit(node) {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            // `<x>.update(TABLE).set(SET)` — the drizzle update chain. Lookalikes
+            // (`hash.update(x).digest()`) have no `.set` and never reach here.
+            if (method === "set") {
+                const recv = node.expression.expression;
+                if (ts.isCallExpression(recv) &&
+                    ts.isPropertyAccessExpression(recv.expression) &&
+                    recv.expression.name.text === "update") {
+                    classify(recv.arguments[0], columnsOfObjectLiteral(node.arguments[0]), recv, "update().set()");
+                }
+            }
+            else if (method === "onConflictDoUpdate") {
+                // `<x>.insert(TABLE)…onConflictDoUpdate({ set: {...} })` — an upsert is a
+                // conditional transition, so it is classified, not silently skipped.
+                const tableArg = tableArgInChain(node);
+                if (tableArg) {
+                    classify(tableArg, columnsOfOnConflictSet(node.arguments[0]), node, "onConflictDoUpdate()");
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(src);
+    return points;
+}
+//# sourceMappingURL=scan.js.map

package/dist/validate/t0.d.ts

@@ -0,0 +1,27 @@
+import type { LoadResult } from "../loader/load-model.js";
+import type { T0Result } from "./types.js";
+export interface T0Options {
+    /**
+     * Absolute path to the repo the anchors should resolve against.
+     * Omit to skip anchor-existence entirely (format-only checking) — the
+     * right default when there's no target repo checked out yet, e.g. in
+     * loopgraph's own CI which only tests the engine against fixtures.
+     */
+    repoRoot?: string | undefined;
+    /** Promote anchor-existence to a blocking check. Default: advisory (warning). */
+    strictAnchorExistence?: boolean | undefined;
+}
+/**
+ * Runs the full T0 layer: schema validity, id uniqueness, file-per-node
+ * filename==id (advisory), cross-node referential integrity, graph acyclicity
+ * (Loop.parent / Flow.references — the only two same-kind reference fields, see
+ * checkGraphAcyclic), anchor format, and (optionally) anchor existence.
+ * Deliberately
+ * excludes: INV-1's whole-repo AST writer scan, T1's queue-derivation-
+ * chain check, and anything baseline-growth related (that needs a
+ * two-snapshot diff, see checkBaselineOnlyDecreases — it's not part of a
+ * single-snapshot T0 run). All of T0 must stay cheap and deterministic:
+ * no network calls, no LLM.
+ */
+export declare function runT0(load: LoadResult, options?: T0Options): Promise<T0Result>;
+//# sourceMappingURL=t0.d.ts.map

package/dist/validate/t0.js

@@ -0,0 +1,31 @@
+import { checkAnchorExistence, checkAnchorFormat, checkFilenameMatchesId, checkGraphAcyclic, checkIdUniqueness, checkReferentialIntegrity, checkSchema, } from "./checks.js";
+import { summarize } from "./types.js";
+/**
+ * Runs the full T0 layer: schema validity, id uniqueness, file-per-node
+ * filename==id (advisory), cross-node referential integrity, graph acyclicity
+ * (Loop.parent / Flow.references — the only two same-kind reference fields, see
+ * checkGraphAcyclic), anchor format, and (optionally) anchor existence.
+ * Deliberately
+ * excludes: INV-1's whole-repo AST writer scan, T1's queue-derivation-
+ * chain check, and anything baseline-growth related (that needs a
+ * two-snapshot diff, see checkBaselineOnlyDecreases — it's not part of a
+ * single-snapshot T0 run). All of T0 must stay cheap and deterministic:
+ * no network calls, no LLM.
+ */
+export async function runT0(load, options = {}) {
+    const violations = [
+        ...checkSchema(load),
+        ...checkIdUniqueness(load),
+        ...checkFilenameMatchesId(load),
+        ...checkReferentialIntegrity(load.graph),
+        ...checkGraphAcyclic(load.graph),
+        ...checkAnchorFormat(load.graph),
+    ];
+    if (options.repoRoot) {
+        violations.push(...(await checkAnchorExistence(load.graph, options.repoRoot, {
+            strict: options.strictAnchorExistence,
+        })));
+    }
+    return summarize(violations);
+}
+//# sourceMappingURL=t0.js.map

package/dist/validate/types.d.ts

@@ -0,0 +1,16 @@
+export type Severity = "error" | "warning";
+export type CheckName = "schema" | "id-uniqueness" | "anchor-format" | "anchor-existence" | "referential-integrity" | "graph-acyclic" | "baseline-growth" | "inv1-write-site" | "filename-id";
+export interface Violation {
+    check: CheckName;
+    severity: Severity;
+    message: string;
+    file?: string;
+    nodeId?: string;
+}
+export interface T0Result {
+    /** true iff there are no error-severity violations (warnings don't fail T0). */
+    ok: boolean;
+    violations: Violation[];
+}
+export declare function summarize(violations: Violation[]): T0Result;
+//# sourceMappingURL=types.d.ts.map

package/dist/validate/types.js

@@ -0,0 +1,4 @@
+export function summarize(violations) {
+    return { ok: violations.every((v) => v.severity !== "error"), violations };
+}
+//# sourceMappingURL=types.js.map

package/dist/validate/unregistered.d.ts

@@ -0,0 +1,70 @@
+import type { ImplementationFact } from "../adapters/agenthub/extract.js";
+import type { ModelGraph } from "../loader/model-graph.js";
+/**
+ * C2 T1 reconciliation (Proposal 006 Phase 3): which extracted implementation
+ * facts (pg-boss queues, setInterval pollers) are NOT registered by any model
+ * node. This is the "unregistered route/queue/poller 拦截" check — B1 facts
+ * reconciled against the model registry.
+ *
+ * ADVISORY (T1), not a T0 gate: it reports, it does not fail the build. The
+ * enforcement-tier promotion (report → block) is C3, gated on a measured
+ * false-positive rate on real target-repo PRs.
+ */
+/**
+ * A reconciliation partitions every fact into exactly ONE of three disjoint
+ * buckets — `registered + dormantSuppressed + unregistered === total`:
+ */
+export interface Reconciliation {
+    /** facts whose file is covered by an ACTIVE model node (a real, modeled loop/junction). */
+    registered: ImplementationFact[];
+    /**
+     * facts whose file is covered ONLY by a dormant Loop (an N-series
+     * "baseline-only" registration) — NOT by any active node. A distinct bucket,
+     * not a subset of `registered`: a dormant registration quiets the advisory
+     * signal without being real modeling, so it is surfaced separately (001 §12
+     * 不掩盖缺口 — the quieting must be visible, not hidden inside `registered`).
+     */
+    dormantSuppressed: ImplementationFact[];
+    /** facts whose file no model node anchors — the advisory findings. */
+    unregistered: ImplementationFact[];
+    /** repo-relative files the model registers (active + dormant anchors), sorted. */
+    coveredFiles: string[];
+    /**
+     * Queue names declared in some active loop's `consumes_queues` that matched NO
+     * extracted fact. A dangling declaration is almost always a typo or a
+     * stale/renamed queue — surfaced so it doesn't silently fail to register (and
+     * so the model stays honest as the code moves under it).
+     */
+    unmatchedConsumedQueues: string[];
+}
+/** File part of an anchor `FILE#SYMBOL` (or the whole string when there is no `#`). */
+export declare function anchorFile(anchor: string): string;
+/**
+ * The set of repo-relative files the model registers, via `Loop.anchors` and
+ * `Junction` evidence anchors (active + dormant). Non-code evidence anchors
+ * (spec/issue files) are folded in too — harmless, they simply never match a
+ * code fact's `filePath`.
+ */
+export declare function coveredFiles(graph: ModelGraph): Set<string>;
+/**
+ * Reconcile extracted facts against the model's registered anchors.
+ *
+ * FILE-LEVEL granularity — a fact whose file carries ANY loop/junction anchor
+ * counts as covered. This is the SOLE granularity (not a toggled mode): the
+ * fact `name` is a queue string / interval marker, a different namespace from
+ * the class/function symbols anchors use, so symbol-level matching would need
+ * the extractor to also capture each fact's enclosing symbol — future work, and
+ * if that granularity is ever added this reconciliation must be revisited.
+ * File-level deliberately UNDER-flags (a partially-modeled file hides an extra
+ * unregistered loop it also contains) rather than over-flags: an advisory T1
+ * signal that cries wolf gets ignored, so the bias is toward silence on
+ * ambiguity (001 §12 "不掩盖缺口" is about not hiding KNOWN gaps, not about
+ * manufacturing noisy ones).
+ *
+ * N-series background loops (ttl-renewal, vault-refresh, ...) are suppressed by
+ * registering them as minimal (dormant, owner-null) Loop nodes carrying an
+ * anchor — that is where "baseline-only" N-loops live (001 §9), NOT in the debt
+ * list (debt = dead-state-machines, a structurally different thing).
+ */
+export declare function reconcileFacts(facts: ImplementationFact[], graph: ModelGraph): Reconciliation;
+//# sourceMappingURL=unregistered.d.ts.map

package/dist/validate/unregistered.js

@@ -0,0 +1,111 @@
+/** File part of an anchor `FILE#SYMBOL` (or the whole string when there is no `#`). */
+export function anchorFile(anchor) {
+    const hash = anchor.indexOf("#");
+    return hash === -1 ? anchor : anchor.slice(0, hash);
+}
+/**
+ * Files registered by ACTIVE model nodes (non-dormant loops + all junction
+ * evidence). These represent real, modeled coverage. Junctions are always
+ * "active" — a junction only exists when a real cross-loop risk was modeled.
+ */
+function activeCoveredFiles(graph) {
+    const files = new Set();
+    for (const loop of graph.byKind.loop.values())
+        if (!loop.dormant)
+            for (const a of loop.anchors)
+                files.add(anchorFile(a));
+    for (const j of graph.byKind.junction.values())
+        for (const e of j.evidence)
+            files.add(anchorFile(e.anchor));
+    return files;
+}
+/** Files registered ONLY by dormant loops (N-series baseline-only registrations). */
+function dormantCoveredFiles(graph) {
+    const files = new Set();
+    for (const loop of graph.byKind.loop.values())
+        if (loop.dormant)
+            for (const a of loop.anchors)
+                files.add(anchorFile(a));
+    return files;
+}
+/**
+ * pg-boss queue names declared as consumed by an ACTIVE loop (Loop.consumes_queues,
+ * C2 root-fix). A queue fact whose name is here is registered-by-name — its
+ * lifecycle loop is modeled even though its producer-registry definition file
+ * carries no anchor. Dormant loops don't count (they're a suppression channel,
+ * not real modeling — see `dormantSuppressed`).
+ */
+function activeConsumedQueues(graph) {
+    const names = new Set();
+    for (const loop of graph.byKind.loop.values())
+        if (!loop.dormant)
+            for (const q of loop.consumes_queues)
+                names.add(q);
+    return names;
+}
+/**
+ * The set of repo-relative files the model registers, via `Loop.anchors` and
+ * `Junction` evidence anchors (active + dormant). Non-code evidence anchors
+ * (spec/issue files) are folded in too — harmless, they simply never match a
+ * code fact's `filePath`.
+ */
+export function coveredFiles(graph) {
+    return new Set([...activeCoveredFiles(graph), ...dormantCoveredFiles(graph)]);
+}
+/**
+ * Reconcile extracted facts against the model's registered anchors.
+ *
+ * FILE-LEVEL granularity — a fact whose file carries ANY loop/junction anchor
+ * counts as covered. This is the SOLE granularity (not a toggled mode): the
+ * fact `name` is a queue string / interval marker, a different namespace from
+ * the class/function symbols anchors use, so symbol-level matching would need
+ * the extractor to also capture each fact's enclosing symbol — future work, and
+ * if that granularity is ever added this reconciliation must be revisited.
+ * File-level deliberately UNDER-flags (a partially-modeled file hides an extra
+ * unregistered loop it also contains) rather than over-flags: an advisory T1
+ * signal that cries wolf gets ignored, so the bias is toward silence on
+ * ambiguity (001 §12 "不掩盖缺口" is about not hiding KNOWN gaps, not about
+ * manufacturing noisy ones).
+ *
+ * N-series background loops (ttl-renewal, vault-refresh, ...) are suppressed by
+ * registering them as minimal (dormant, owner-null) Loop nodes carrying an
+ * anchor — that is where "baseline-only" N-loops live (001 §9), NOT in the debt
+ * list (debt = dead-state-machines, a structurally different thing).
+ */
+export function reconcileFacts(facts, graph) {
+    const active = activeCoveredFiles(graph);
+    const dormant = dormantCoveredFiles(graph);
+    const consumedQueues = activeConsumedQueues(graph);
+    const registered = [];
+    const dormantSuppressed = [];
+    const unregistered = [];
+    // Three DISJOINT buckets (active wins over dormant wins over nothing), so
+    // `registered`, `dormantSuppressed`, and `unregistered` partition the facts.
+    // A queue fact is active-registered by EITHER its file being anchored OR its
+    // name being declared in some active loop's consumes_queues (producer/consumer
+    // split: the definition file may carry no anchor while the loop is modeled).
+    const isActive = (f) => active.has(f.filePath) || (f.signal === "pg_boss_queue" && consumedQueues.has(f.name));
+    for (const f of facts) {
+        if (isActive(f)) {
+            registered.push(f);
+        }
+        else if (dormant.has(f.filePath)) {
+            dormantSuppressed.push(f); // covered only by a dormant N-loop — quieted, reported apart
+        }
+        else {
+            unregistered.push(f);
+        }
+    }
+    // A declared consumed-queue name that matched no fact is a dangling assertion
+    // (typo / renamed / removed queue) — report it so it can't silently rot.
+    const factQueueNames = new Set(facts.filter((f) => f.signal === "pg_boss_queue").map((f) => f.name));
+    const unmatchedConsumedQueues = [...consumedQueues].filter((q) => !factQueueNames.has(q)).sort();
+    return {
+        registered,
+        dormantSuppressed,
+        unregistered,
+        coveredFiles: [...new Set([...active, ...dormant])].sort(),
+        unmatchedConsumedQueues,
+    };
+}
+//# sourceMappingURL=unregistered.js.map

package/dist/views/flow-mermaid.d.ts

@@ -0,0 +1,30 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+/**
+ * Renders a Flow (e.g. C1) as a mermaid `flowchart`, per Decision record
+ * 004 技术点 5 (Phase 1, C1 only — proposal 001 §12 success-criteria
+ * scope, not all 9 Flows). Structure:
+ *
+ * - Nodes: the Flow itself, every Loop in `traverses`/`guarded_by`, and
+ *   every Loop referenced by a crossing Junction's `between` (covers
+ *   Loops that aren't in `traverses`/`guarded_by` at all, e.g. a
+ *   junction linking two loops outside this flow's primary chain).
+ * - Edges: `traverses` rendered as the plain forward sequence; each
+ *   `guarded_by` Loop as a dashed "guards" edge into the Flow node
+ *   (flow-level watchdog coverage, not tied to one step); each crossing
+ *   Junction as its OWN dashed edge, drawn literally from
+ *   `junction.between[0]` to `junction.between[1]` and labeled with the
+ *   junction id + risk_class.
+ *
+ * The junction edges are deliberately NOT inferred by walking
+ * `traverses` as a forward chain and matching adjacent pairs — real flow
+ * data has junctions that aren't forward-adjacent traversal steps at all
+ * (a projection junction can be a backward edge from the last traverses
+ * step to an earlier one; a watchdog junction can link a `guarded_by`
+ * loop to a traverses step, not two traverses steps). Inferring from
+ * adjacency would silently drop both — 2 of the 5 risk classes
+ * (projection, watchdog). Drawing every
+ * junction from its own literal `between` pair, unconditionally, can't
+ * drop any of them.
+ */
+export declare function renderFlowMermaid(graph: ModelGraph, flowId: string): string;
+//# sourceMappingURL=flow-mermaid.d.ts.map

package/dist/views/flow-mermaid.js

@@ -0,0 +1,89 @@
+/**
+ * Escapes a title for use inside a mermaid `["..."]` quoted node label.
+ * `title` is unconstrained free text (schema: `z.string().min(1)`, no
+ * charset restriction), so two things need handling: a literal `"`
+ * would close the quoted label early, and a literal newline would
+ * split this function's one-line-per-node output across lines,
+ * corrupting the line-based structure `renderFlowMermaid` generates —
+ * collapsed to a space rather than stripped, so the text stays
+ * readable. Ordinary punctuation (`]`, `#`, etc.) needs no escaping:
+ * verified against a real mmdc render — mermaid's quoted-bracket label
+ * syntax tolerates it as literal text.
+ */
+function quoteLabel(text) {
+    return text.replace(/"/g, "'").replace(/[\r\n]+/g, " ");
+}
+function nodeDecl(id, title) {
+    return `  ${id}["${id}: ${quoteLabel(title)}"]`;
+}
+/**
+ * Renders a Flow (e.g. C1) as a mermaid `flowchart`, per Decision record
+ * 004 技术点 5 (Phase 1, C1 only — proposal 001 §12 success-criteria
+ * scope, not all 9 Flows). Structure:
+ *
+ * - Nodes: the Flow itself, every Loop in `traverses`/`guarded_by`, and
+ *   every Loop referenced by a crossing Junction's `between` (covers
+ *   Loops that aren't in `traverses`/`guarded_by` at all, e.g. a
+ *   junction linking two loops outside this flow's primary chain).
+ * - Edges: `traverses` rendered as the plain forward sequence; each
+ *   `guarded_by` Loop as a dashed "guards" edge into the Flow node
+ *   (flow-level watchdog coverage, not tied to one step); each crossing
+ *   Junction as its OWN dashed edge, drawn literally from
+ *   `junction.between[0]` to `junction.between[1]` and labeled with the
+ *   junction id + risk_class.
+ *
+ * The junction edges are deliberately NOT inferred by walking
+ * `traverses` as a forward chain and matching adjacent pairs — real flow
+ * data has junctions that aren't forward-adjacent traversal steps at all
+ * (a projection junction can be a backward edge from the last traverses
+ * step to an earlier one; a watchdog junction can link a `guarded_by`
+ * loop to a traverses step, not two traverses steps). Inferring from
+ * adjacency would silently drop both — 2 of the 5 risk classes
+ * (projection, watchdog). Drawing every
+ * junction from its own literal `between` pair, unconditionally, can't
+ * drop any of them.
+ */
+export function renderFlowMermaid(graph, flowId) {
+    const flow = graph.byKind.flow.get(flowId);
+    if (!flow)
+        throw new Error(`renderFlowMermaid: no such flow "${flowId}"`);
+    const crossingJunctions = flow.crosses
+        .map((id) => graph.byKind.junction.get(id))
+        .filter((j) => j !== undefined);
+    const nodeIds = new Set([
+        ...flow.traverses,
+        ...flow.guarded_by,
+        ...crossingJunctions.flatMap((j) => j.between),
+    ]);
+    const lines = ["flowchart TB", nodeDecl(flow.id, flow.title)];
+    for (const loopId of nodeIds) {
+        const loop = graph.byKind.loop.get(loopId);
+        lines.push(nodeDecl(loopId, loop?.title ?? loopId));
+    }
+    lines.push("");
+    if (flow.traverses.length > 0) {
+        const [first, ...rest] = flow.traverses;
+        lines.push(`  ${flow.id} --> ${first}`);
+        let prev = first;
+        for (const next of rest) {
+            lines.push(`  ${prev} --> ${next}`);
+            prev = next;
+        }
+    }
+    for (const guardId of flow.guarded_by) {
+        lines.push(`  ${guardId} -.->|guards| ${flow.id}`);
+    }
+    lines.push("");
+    for (const junction of crossingJunctions) {
+        const [from, to] = junction.between;
+        if (from === undefined || to === undefined)
+            continue; // schema allows a 1-element `between`; no edge to draw
+        // The label carries the endpoints explicitly (`from→to`) so a reader never
+        // has to infer direction from the auto-layout (Report 005 §5 建议 1): mermaid
+        // routes non-adjacent/reverse dashed edges close together — and readers
+        // misread which end is which. Stating it in the label removes the ambiguity.
+        lines.push(`  ${from} -.->|"${junction.id}: ${junction.risk_class} (${from}→${to})"| ${to}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=flow-mermaid.js.map

package/dist/views/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./flow-mermaid.js";
+export * from "./validate-mermaid.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/views/index.js

@@ -0,0 +1,3 @@
+export * from "./flow-mermaid.js";
+export * from "./validate-mermaid.js";
+//# sourceMappingURL=index.js.map

package/dist/views/validate-mermaid.d.ts

@@ -0,0 +1,39 @@
+export type MermaidValidationResult = {
+    status: "valid";
+} | {
+    status: "invalid";
+    error: string;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+export interface ValidateMermaidOptions {
+    /**
+     * Overrides the resolved `mmdc` script path. Test-only seam: lets
+     * test/validate-mermaid.test.ts force the "unavailable" branch
+     * deterministically (a bogus path) without needing to actually
+     * uninstall @mermaid-js/mermaid-cli from this repo's own node_modules.
+     */
+    mmdcBinPath?: string;
+}
+/**
+ * Renders `mermaidText` with mermaid-cli (`mmdc`) to a throwaway SVG and
+ * reports whether it actually rendered — the "写出即验证" enforcement
+ * from Decision record 004 技术点 5. A generated diagram nobody opens
+ * until much later isn't validated, it's just written; this is the
+ * module that makes "validated" mean something.
+ *
+ * Deliberately NOT on loopgraph's default `view` CLI path (see
+ * src/cli/commands/view.ts): mmdc needs a real puppeteer-launched
+ * browser (~300MB Chromium download on first install), which the
+ * project's own lightness principle (proposal 001 §6: views generation
+ * isn't in the CI gating path) says shouldn't be a hard runtime
+ * requirement for every consumer that installs loopgraph. It's a
+ * devDependency here so loopgraph's OWN test suite can prove the
+ * generator produces valid mermaid (test/validate-mermaid.test.ts,
+ * test/view-cli.test.ts), and available to end users only when they
+ * opt in with `loopgraph view --validate` AND have separately installed
+ * `@mermaid-js/mermaid-cli` themselves.
+ */
+export declare function validateMermaid(mermaidText: string, options?: ValidateMermaidOptions): Promise<MermaidValidationResult>;
+//# sourceMappingURL=validate-mermaid.d.ts.map