loopgraph 0.1.0

package/dist/schema/model.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { ConsistencyStatus, DebtCategory, RiskClass } from "./status.js";
+/**
+ * IDs are re-used verbatim from the source research documents so that the
+ * drift test (test/drift.test.ts) can diff model IDs against IDs extracted
+ * straight out of the PR tables, with no hand-maintained translation layer.
+ */
+export const LoopId = z
+    .string()
+    .regex(/^[LN]\d{1,2}[a-z]?$/, "loop id must look like L1, L1a, N32, etc.");
+export const FlowId = z.string().regex(/^C\d$/, "flow id must look like C1..C9");
+export const FeatureId = z.string().regex(/^F-[a-z0-9-]+$/, "feature id must look like F-xxx");
+export const JunctionId = z.string().regex(/^J-[a-z0-9_-]+$/, "junction id must look like J-xxx");
+export const ScenarioId = z
+    .string()
+    .regex(/^GWT-[A-Za-z0-9]+-\d{3}$/, "scenario id must look like GWT-<flow|loop>-001");
+/**
+ * Max length of `Evidence.note`. `note` exists only to help a reader
+ * *locate* the anchored evidence (a line range, a function name, a test-name
+ * fragment) — NOT to narrate causal reasoning or historical background.
+ * The cap is a mechanical backstop for that intent: prose explanations run
+ * long, pointers stay short. Kept as a named const so the schema test and
+ * any future review tooling reference the same number.
+ */
+export const EVIDENCE_NOTE_MAX = 200;
+/**
+ * Evidence is embedded inside Junction (evidence: Evidence[]) rather than
+ * a standalone top-level file — it only makes sense bound to the claim it
+ * proves. Scenario does NOT carry Evidence directly: its `verified_by`
+ * field holds plain test/E2E anchor strings instead, since GWT→test
+ * binding is a simpler 1:many mapping than Junction's need for typed,
+ * multi-kind evidence.
+ *
+ * `kind` taxonomy:
+ * - Runtime/code evidence: test / durable_event / e2e / metric / trace /
+ *   log / code — an anchor that resolves to a projection or observation of
+ *   the running system.
+ * - Intent/planning evidence (Proposal 006 A1): `spec` points at a
+ *   requirement/design statement (a spec section, an ADR line), `issue`
+ *   points at a tracked work item (a GitHub issue/PR reference). These let
+ *   a junction cite "this handoff is deliberately deferred, see #NNNN" or
+ *   "the poller's settled≠done semantics is specified here" without dressing
+ *   a planning pointer up as a runtime observation. Because they are the
+ *   easiest kind to smuggle prose into, `note` on these is held to the same
+ *   anchor-only, pointer-not-narrative discipline as every other kind (see
+ *   `EVIDENCE_NOTE_MAX`); reviewers of any content PR treat a `spec`/`issue`
+ *   note that argues causation or recounts history as a defect.
+ */
+export const Evidence = z.object({
+    id: z.string().min(1),
+    kind: z.enum(["test", "durable_event", "e2e", "metric", "trace", "log", "code", "spec", "issue"]),
+    anchor: z.string().min(1),
+    source: z.string().optional(),
+    transport: z.enum(["direct", "relay", "durable_event"]).optional(),
+    binding: z
+        .object({
+        image_revision: z.enum(["required", "optional"]),
+    })
+        .optional(),
+    confidence: z.enum(["high", "medium", "low"]).optional(),
+    // Anchor-locating aid only (line range / function name / test-name
+    // fragment). No causal reasoning, no historical background — long prose
+    // belongs in the source doc the `spec`/`issue` anchor points at, not here.
+    note: z.string().max(EVIDENCE_NOTE_MAX).optional(),
+});
+/**
+ * Loop covers both ordinary top-level loops (L1, N19, ...) and the
+ * "(内嵌)" embedded submachines (L1a/L1b/L3a/L20a) that share a parent's
+ * boundary but carry their own state. Dormant/unwired loops like N8
+ * ("M2 休眠") have owner: null and dormant: true instead of being dropped.
+ */
+export const Loop = z.object({
+    id: LoopId,
+    kind: z.literal("loop"),
+    title: z.string().min(1),
+    boundary: z.string().min(1),
+    owner: z.string().min(1).nullable(),
+    section: z.string().optional(),
+    parent: LoopId.optional(),
+    embedded: z.boolean().optional(),
+    dormant: z.boolean().optional(),
+    status: ConsistencyStatus.default("unverified"),
+    anchors: z.array(z.string()).default([]),
+    /**
+     * pg-boss queue names this loop CONSUMES (Proposal 006 C2 root-fix). A queue is
+     * defined at its producer/enqueue site (e.g. a shared `services.ts` registry)
+     * but its lifecycle belongs to the consuming loop, which may live in a
+     * different file. Declaring the names here lets reconciliation register a queue
+     * fact by NAME — so a producer-registry definition is not a false "unregistered"
+     * just because its file carries no anchor. This is an explicit modeling
+     * assertion ("this loop consumes order:process"), verified against the
+     * consumer's queue handler; it is NOT a way to silence facts (that would be a
+     * dormant loop) and NOT a synthetic node (a registry file is not a loop).
+     */
+    consumes_queues: z.array(z.string()).default([]),
+    scenarios: z.array(ScenarioId).default([]),
+    notes: z.string().optional(),
+});
+/**
+ * Flow = composite flow (C1..C9). `traverses` is the ordered loop sequence;
+ * `guarded_by` holds watchdog loops (e.g. C1's L9) that don't sit in the
+ * primary sequence but cover it; `references` holds sub-flow composition
+ * (e.g. C1 references C2/C3 as expandable sub-chains).
+ */
+export const Flow = z.object({
+    id: FlowId,
+    kind: z.literal("flow"),
+    title: z.string().min(1),
+    traverses: z.array(LoopId).default([]),
+    guarded_by: z.array(LoopId).default([]),
+    crosses: z.array(JunctionId).default([]),
+    references: z.array(FlowId).default([]),
+    risk_notes: z.string().optional(),
+    status: ConsistencyStatus.default("unverified"),
+});
+export const Junction = z.object({
+    id: JunctionId,
+    kind: z.literal("junction"),
+    title: z.string().optional(),
+    risk_class: RiskClass,
+    between: z.array(LoopId).min(1),
+    scenarios: z.array(ScenarioId).default([]),
+    evidence: z.array(Evidence).default([]),
+    status: ConsistencyStatus.default("unverified"),
+});
+/**
+ * Selector for effective-constraints propagation (Decision record 004,
+ * 技术点 2): decides which nodes an Invariant-flavored Scenario applies
+ * to automatically, without hand-listing the scenario id in every
+ * relevant node's `scenarios` array. Resolved at query time by
+ * src/query/effective-constraints.ts, never materialized — see that
+ * module for match semantics (owner_match is substring containment with
+ * optional `*` wildcard, NOT prefix-anchored or POSIX glob).
+ */
+export const AppliesTo = z.object({
+    nodes: z.array(z.string()).default([]),
+    owner_match: z.string().min(1).optional(), // empty string would match every non-dormant Loop — reject rather than allow the footgun
+});
+export const Scenario = z.object({
+    id: ScenarioId,
+    kind: z.literal("scenario"),
+    given: z.string().min(1),
+    when: z.string().min(1),
+    // biome-ignore lint/suspicious/noThenProperty: Given/When/Then is the GWT domain vocabulary, not a thenable
+    then: z.string().min(1),
+    level: z.enum(["unit", "focused-integration", "contract", "integration", "e2e", "operational"]),
+    verified_by: z.array(z.string()).default([]),
+    applies_to: AppliesTo.optional(),
+});
+export const Feature = z.object({
+    id: FeatureId,
+    kind: z.literal("feature"),
+    title: z.string().min(1),
+    contains: z.array(FlowId).default([]),
+    status: ConsistencyStatus.default("unverified"),
+});
+/**
+ * DebtEntry is deliberately a different shape from Loop: the 6
+ * dead-state-machine tables and 2 deferred loops from the seed baseline describe
+ * something that LOOKS like a loop (has a status column / was scoped as
+ * a loop) but fails the "independent advance mechanism" test — they are
+ * baseline debt, not behavior to model as Loop nodes.
+ */
+export const DebtId = z.string().regex(/^DEBT-[A-Za-z0-9-]+$/, "debt id must look like DEBT-xxx");
+export const DebtEntry = z.object({
+    id: DebtId,
+    kind: z.literal("debt"),
+    category: DebtCategory,
+    subject: z.string().min(1),
+    claim: z.string().optional(),
+    reality: z.string().min(1),
+    owner: z.string().optional(),
+    removal_condition: z.string().optional(),
+});
+export const ModelNode = z.discriminatedUnion("kind", [
+    Feature,
+    Flow,
+    Loop,
+    Junction,
+    Scenario,
+    DebtEntry,
+]);
+//# sourceMappingURL=model.js.map

package/dist/schema/status.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * Six consistency states a model node can be in, per proposal 001 §3.2.
+ * Default for freshly-imported seed nodes is "unverified": the real
+ * implementation exists in the target repo, but the model hasn't yet
+ * attached enough Scenario/Evidence to call it conformant.
+ */
+export declare const ConsistencyStatus: z.ZodEnum<["conformant", "unimplemented", "unverified", "drifted", "unregistered", "deprecated"]>;
+export type ConsistencyStatus = z.infer<typeof ConsistencyStatus>;
+/**
+ * The 5 junction risk classes (衔接点风险模式) — the frozen taxonomy for the seed.
+ * Every Junction must classify itself under exactly one of these.
+ */
+export declare const RiskClass: z.ZodEnum<["handoff", "idempotency", "projection", "failure_propagation", "watchdog"]>;
+export type RiskClass = z.infer<typeof RiskClass>;
+export declare const DebtCategory: z.ZodEnum<["dead_state_machine", "deferred", "other"]>;
+export type DebtCategory = z.infer<typeof DebtCategory>;
+//# sourceMappingURL=status.d.ts.map

package/dist/schema/status.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/**
+ * Six consistency states a model node can be in, per proposal 001 §3.2.
+ * Default for freshly-imported seed nodes is "unverified": the real
+ * implementation exists in the target repo, but the model hasn't yet
+ * attached enough Scenario/Evidence to call it conformant.
+ */
+export const ConsistencyStatus = z.enum([
+    "conformant",
+    "unimplemented",
+    "unverified",
+    "drifted",
+    "unregistered",
+    "deprecated",
+]);
+/**
+ * The 5 junction risk classes (衔接点风险模式) — the frozen taxonomy for the seed.
+ * Every Junction must classify itself under exactly one of these.
+ */
+export const RiskClass = z.enum([
+    "handoff",
+    "idempotency",
+    "projection",
+    "failure_propagation",
+    "watchdog",
+]);
+export const DebtCategory = z.enum(["dead_state_machine", "deferred", "other"]);
+//# sourceMappingURL=status.js.map

package/dist/staleness.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A point-in-time fingerprint attached to any side-channel file loopgraph
+ * writes (Decision record 004, 技术点 4, CodeGraph-inspired: side-channel
+ * output must carry an explicit staleness signal instead of silently
+ * looking as current as a freshly-computed one).
+ *
+ * `modelContentHash` is the ONLY field `isStale` compares against — it's
+ * a hash over every model YAML file's own bytes, so it changes the
+ * instant model data changes, independent of git (uncommitted edits,
+ * detached checkouts, and non-git exports all still get a real hash).
+ * `generatedAt`/`repoHead`/`repoDirty` are read-only context for a human
+ * looking at the file — never treat wall-clock age or repo dirtiness as
+ * a staleness signal by itself: time passing doesn't make a view wrong,
+ * and a repo can be dirty for reasons unrelated to the model.
+ */
+export interface StalenessStamp {
+    generatedAt: string;
+    modelContentHash: string;
+    repoHead: string | null;
+    repoDirty: boolean | null;
+}
+/**
+ * Deterministic fingerprint of every *.yaml/*.yml file under `modelDir`,
+ * independent of file iteration order (sorted before hashing) and of git
+ * (reads working-tree bytes directly, so uncommitted edits change the
+ * hash immediately — the same "reflect the working tree, not last
+ * commit" posture as the rest of loadModel). This deliberately hashes
+ * the WHOLE model dir rather than per-flow/per-node: it will over-report
+ * staleness when an unrelated node changes, which is the safe direction
+ * for a "don't trust this without checking" signal — a false "maybe
+ * stale" costs a re-run; a false "definitely fresh" costs a wrong
+ * decision made on stale data.
+ */
+export declare function computeModelContentHash(modelDir: string): Promise<string>;
+export declare function computeStalenessStamp(modelDir: string, repoRoot: string): Promise<StalenessStamp>;
+/** Renders `stamp` as an HTML comment block, prepended to a generated side-channel file. */
+export declare function formatStalenessBanner(stamp: StalenessStamp): string;
+/**
+ * Inverse of `formatStalenessBanner`. Returns undefined if `text` has no
+ * recognizable banner. Parses fields by splitting on lines and matching
+ * each line's start against `BANNER_FIELD_KEYS` rather than building a
+ * `RegExp` per field — field keys are fixed string literals here, never
+ * user input, but avoiding per-call dynamic regex construction sidesteps
+ * the need to reason about escaping altogether, and keeps every field's
+ * value confined to its own line (a value can never accidentally
+ * swallow a neighboring line the way a `.*` non-multiline capture over
+ * a shared block could invite as this function grows more fields).
+ */
+export declare function parseStalenessBanner(text: string): StalenessStamp | undefined;
+/**
+ * Whether a previously-generated stamp no longer reflects the current
+ * model. Compares `modelContentHash` ONLY — see the field's docstring on
+ * `StalenessStamp` for why wall-clock time and repo dirtiness must not
+ * factor in.
+ */
+export declare function isStale(generated: StalenessStamp, current: StalenessStamp): boolean;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/staleness.js

@@ -0,0 +1,148 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { promisify } from "node:util";
+import { findYamlFiles } from "./loader/find-yaml-files.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Deterministic fingerprint of every *.yaml/*.yml file under `modelDir`,
+ * independent of file iteration order (sorted before hashing) and of git
+ * (reads working-tree bytes directly, so uncommitted edits change the
+ * hash immediately — the same "reflect the working tree, not last
+ * commit" posture as the rest of loadModel). This deliberately hashes
+ * the WHOLE model dir rather than per-flow/per-node: it will over-report
+ * staleness when an unrelated node changes, which is the safe direction
+ * for a "don't trust this without checking" signal — a false "maybe
+ * stale" costs a re-run; a false "definitely fresh" costs a wrong
+ * decision made on stale data.
+ */
+export async function computeModelContentHash(modelDir) {
+    const files = (await findYamlFiles(modelDir)).sort();
+    const hash = createHash("sha256");
+    for (const absPath of files) {
+        const relPath = relative(modelDir, absPath);
+        const content = await readFile(absPath, "utf8");
+        hash.update(relPath);
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+/**
+ * Best-effort `git rev-parse HEAD` / `git status --porcelain` against
+ * `repoRoot`. Returns `{ head: null, dirty: null }` for anything that
+ * isn't a usable git checkout (no git binary, not a repo, no commits
+ * yet) rather than throwing — a staleness stamp must still be produced
+ * for a plain export or a fresh `git init` with no commits.
+ */
+async function readGitInfo(repoRoot) {
+    try {
+        const [{ stdout: head }, { stdout: status }] = await Promise.all([
+            execFileAsync("git", ["rev-parse", "HEAD"], { cwd: repoRoot }),
+            execFileAsync("git", ["status", "--porcelain"], { cwd: repoRoot }),
+        ]);
+        return { head: head.trim(), dirty: status.trim().length > 0 };
+    }
+    catch {
+        return { head: null, dirty: null };
+    }
+}
+export async function computeStalenessStamp(modelDir, repoRoot) {
+    const [modelContentHash, gitInfo] = await Promise.all([
+        computeModelContentHash(modelDir),
+        readGitInfo(repoRoot),
+    ]);
+    return {
+        generatedAt: new Date().toISOString(),
+        modelContentHash,
+        repoHead: gitInfo.head,
+        repoDirty: gitInfo.dirty,
+    };
+}
+const UNKNOWN_HEAD = "unknown (not a git repo or no commits yet)";
+const UNKNOWN_DIRTY = "unknown";
+/**
+ * Marks the opening of the banner's HTML comment. A bare `<!--` isn't
+ * enough of an anchor: a generated side-channel file also embeds a
+ * mermaid block (see src/views/flow-mermaid.ts / src/cli/commands/
+ * view.ts), and a future caller could reasonably run
+ * `parseStalenessBanner` against a whole file rather than the banner
+ * text alone — the non-greedy `<!--...-->` match must not lock onto
+ * some unrelated comment that happens to appear first.
+ */
+const BANNER_MARKER = "loopgraph-staleness-stamp";
+/** Renders `stamp` as an HTML comment block, prepended to a generated side-channel file. */
+export function formatStalenessBanner(stamp) {
+    return [
+        `<!-- ${BANNER_MARKER}`,
+        "This file is a point-in-time snapshot, not a live view. Before trusting",
+        "it, recompute model_content_hash (src/staleness.ts computeModelContentHash)",
+        "against the current model/ dir and compare — a matching generated_at or",
+        "repo_head does NOT by itself mean the model hasn't changed since.",
+        `generated_at: ${stamp.generatedAt}`,
+        `model_content_hash: ${stamp.modelContentHash}`,
+        `repo_head: ${stamp.repoHead ?? UNKNOWN_HEAD}`,
+        `repo_dirty: ${stamp.repoDirty === null ? UNKNOWN_DIRTY : stamp.repoDirty}`,
+        "-->",
+    ].join("\n");
+}
+/**
+ * The only lines `parseStalenessBanner` will ever treat as a field —
+ * every other line in the banner (the explanatory prose) is ignored
+ * outright, even if it happens to contain a `": "` substring. Matching
+ * against this fixed allowlist instead of "the first `": "` on any
+ * line" means the prose is free to read naturally without the parser
+ * silently misreading it as a spurious field.
+ */
+const BANNER_FIELD_KEYS = [
+    "generated_at",
+    "model_content_hash",
+    "repo_head",
+    "repo_dirty",
+];
+/**
+ * Inverse of `formatStalenessBanner`. Returns undefined if `text` has no
+ * recognizable banner. Parses fields by splitting on lines and matching
+ * each line's start against `BANNER_FIELD_KEYS` rather than building a
+ * `RegExp` per field — field keys are fixed string literals here, never
+ * user input, but avoiding per-call dynamic regex construction sidesteps
+ * the need to reason about escaping altogether, and keeps every field's
+ * value confined to its own line (a value can never accidentally
+ * swallow a neighboring line the way a `.*` non-multiline capture over
+ * a shared block could invite as this function grows more fields).
+ */
+export function parseStalenessBanner(text) {
+    const block = text.match(new RegExp(`<!--\\s*${BANNER_MARKER}([\\s\\S]*?)-->`))?.[1];
+    if (!block)
+        return undefined;
+    const fields = new Map();
+    for (const line of block.split("\n")) {
+        const key = BANNER_FIELD_KEYS.find((k) => line.startsWith(`${k}: `));
+        if (key)
+            fields.set(key, line.slice(key.length + 2).trim());
+    }
+    const generatedAt = fields.get("generated_at");
+    const modelContentHash = fields.get("model_content_hash");
+    if (!generatedAt || !modelContentHash)
+        return undefined;
+    const repoHead = fields.get("repo_head");
+    const repoDirty = fields.get("repo_dirty");
+    return {
+        generatedAt,
+        modelContentHash,
+        repoHead: repoHead && repoHead !== UNKNOWN_HEAD ? repoHead : null,
+        repoDirty: repoDirty === "true" ? true : repoDirty === "false" ? false : null,
+    };
+}
+/**
+ * Whether a previously-generated stamp no longer reflects the current
+ * model. Compares `modelContentHash` ONLY — see the field's docstring on
+ * `StalenessStamp` for why wall-clock time and repo dirtiness must not
+ * factor in.
+ */
+export function isStale(generated, current) {
+    return generated.modelContentHash !== current.modelContentHash;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/validate/anchor.d.ts

@@ -0,0 +1,4 @@
+export declare function isValidAnchorFormat(anchor: string): boolean;
+/** For a file-symbol anchor, the file path portion (before "#"). Table anchors have none. */
+export declare function anchorFilePath(anchor: string): string | undefined;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/validate/anchor.js

@@ -0,0 +1,32 @@
+/**
+ * Two anchor shapes are allowed:
+ *   - file-symbol: "packages/core/src/idle-watcher.ts#IdleWatcher"
+ *                  "packages/schemas#EventSchema.warning"
+ *   - db-table:    "jobs_table.payload"  or bare "sandboxes"
+ * The distinguishing feature is the "#" — file-symbol anchors always
+ * have one, db-table anchors never do. This is intentionally lenient:
+ * it is a syntax check, not a claim that the symbol/table exists.
+ *
+ * File-symbol paths are always relative to the target repo's checkout
+ * root, never to loopgraph's own CWD or the model
+ * YAML's own location — `checkAnchorExistence(graph, repoRoot, ...)` in
+ * checks.ts takes `repoRoot` as an explicit required parameter for
+ * exactly this reason, so anchor resolution doesn't depend on which
+ * directory the CLI happens to be invoked from.
+ */
+const FILE_SYMBOL_ANCHOR = /^[\w./-]+#[\w.]+$/;
+const TABLE_ANCHOR = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+export function isValidAnchorFormat(anchor) {
+    if (anchor.length === 0)
+        return false;
+    if (anchor.includes("#"))
+        return FILE_SYMBOL_ANCHOR.test(anchor);
+    return TABLE_ANCHOR.test(anchor);
+}
+/** For a file-symbol anchor, the file path portion (before "#"). Table anchors have none. */
+export function anchorFilePath(anchor) {
+    if (!anchor.includes("#"))
+        return undefined;
+    return anchor.split("#")[0];
+}
+//# sourceMappingURL=anchor.js.map

package/dist/validate/baseline.d.ts

@@ -0,0 +1,11 @@
+import type { Violation } from "./types.js";
+/**
+ * Debt baseline is allowed to shrink (pay off debt) but never grow: a PR
+ * must not introduce a debt id that wasn't already in the baseline it's
+ * diffing against. Content edits to *existing* ids (e.g. clarifying the
+ * `reality` text) are intentionally not checked here — judging whether a
+ * wording change "扩大了既有债务" is a semantic call, not a mechanical
+ * one, and belongs to human review, not T0.
+ */
+export declare function checkBaselineOnlyDecreases(before: Set<string>, after: Set<string>): Violation[];
+//# sourceMappingURL=baseline.d.ts.map

package/dist/validate/baseline.js

@@ -0,0 +1,18 @@
+/**
+ * Debt baseline is allowed to shrink (pay off debt) but never grow: a PR
+ * must not introduce a debt id that wasn't already in the baseline it's
+ * diffing against. Content edits to *existing* ids (e.g. clarifying the
+ * `reality` text) are intentionally not checked here — judging whether a
+ * wording change "扩大了既有债务" is a semantic call, not a mechanical
+ * one, and belongs to human review, not T0.
+ */
+export function checkBaselineOnlyDecreases(before, after) {
+    const added = [...after].filter((id) => !before.has(id));
+    return added.map((id) => ({
+        check: "baseline-growth",
+        severity: "error",
+        message: `debt baseline grew: "${id}" is new and was not in the prior baseline; new debt must be paid down, not registered as baseline`,
+        nodeId: id,
+    }));
+}
+//# sourceMappingURL=baseline.js.map

package/dist/validate/checks.d.ts

@@ -0,0 +1,59 @@
+import type { LoadResult } from "../loader/load-model.js";
+import { type ModelGraph } from "../loader/model-graph.js";
+import type { Violation } from "./types.js";
+/** Schema-parse failures collected during loadModel become blocking violations. */
+export declare function checkSchema(load: LoadResult): Violation[];
+/**
+ * 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 declare function checkFilenameMatchesId(load: LoadResult): Violation[];
+/** Duplicate ids collected during loadModel become blocking violations. */
+export declare function checkIdUniqueness(load: LoadResult): Violation[];
+/** Blocking: every anchor must be syntactically well-formed (file#symbol or table[.column]). */
+export declare function checkAnchorFormat(graph: ModelGraph): Violation[];
+/**
+ * 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 declare function checkReferentialIntegrity(graph: ModelGraph): Violation[];
+/**
+ * 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 declare function checkGraphAcyclic(graph: ModelGraph): Violation[];
+/**
+ * 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 declare function checkAnchorExistence(graph: ModelGraph, repoRoot: string, options?: {
+    strict?: boolean | undefined;
+}): Promise<Violation[]>;
+//# sourceMappingURL=checks.d.ts.map