loopgraph 0.1.0

package/dist/query/queries.d.ts

@@ -0,0 +1,111 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+import type { ModelNode } from "../schema/index.js";
+/**
+ * The Phase-2 query command family (Proposal 006 B4 / 001 §4.2 §8):
+ * `impact` / `plan` / `scenario` / `evidence` — focused views over the model,
+ * distinct from A5's general-purpose `inspect` slice. All are PURE functions of
+ * the loaded graph; the CLI and MCP layers add I/O (side-channel file) around
+ * them. Each returns `undefined` when the id isn't found (callers turn that
+ * into an "unknown id" error), and a small structured result the renderers in
+ * this file turn into a stdout summary + a full side-channel body.
+ */
+export interface Dependent {
+    id: string;
+    kind: ModelNode["kind"];
+    /** How it depends on the queried node (which reference field links them). */
+    relation: string;
+}
+export interface ImpactResult {
+    nodeId: string;
+    kind: ModelNode["kind"];
+    dependents: Dependent[];
+}
+/**
+ * Everything that references `nodeId` — the set a change to it may force you to
+ * re-check. Reverse edges only (who points AT this node), deliberately NOT the
+ * general bidirectional slice `inspect` gives: this answers "if I change X,
+ * what's the blast radius", not "what's near X".
+ */
+export declare function impactOf(graph: ModelGraph, nodeId: string): ImpactResult | undefined;
+export interface PlanStep {
+    loopId: string;
+    title: string;
+    status: string;
+    /** effective-constraint scenario ids that apply to this loop (invariants). */
+    effectiveConstraints: string[];
+}
+export interface PlanResult {
+    flowId: string;
+    title: string;
+    steps: PlanStep[];
+    guards: {
+        loopId: string;
+        title: string;
+    }[];
+    junctions: {
+        id: string;
+        risk_class: string;
+        between: string[];
+        title: string;
+    }[];
+    subFlows: string[];
+}
+/** The ordered "how this flow runs" plan: traverses sequence, guards, crossing junctions. */
+export declare function planOf(graph: ModelGraph, flowId: string): PlanResult | undefined;
+export interface ScenarioResult {
+    scenario: import("../schema/index.js").Scenario;
+    /** loops/junctions that list this scenario in their `scenarios` array. */
+    referencedBy: {
+        id: string;
+        kind: "loop" | "junction";
+    }[];
+    /** loops this scenario applies to via applies_to (resolved at query time). */
+    appliesToLoops: string[];
+}
+export declare function scenarioDetail(graph: ModelGraph, scenarioId: string): ScenarioResult | undefined;
+export interface EvidenceResult {
+    nodeId: string;
+    kind: ModelNode["kind"];
+    /** Junction evidence entries (kind/anchor/note), if the node is a junction. */
+    evidence: import("../schema/index.js").Evidence[];
+    /** Anchor strings, if the node is a loop. */
+    anchors: string[];
+    /** scenarios bound to this node (its own `scenarios` + effective constraints for loops). */
+    scenarios: string[];
+}
+export declare function evidenceOf(graph: ModelGraph, nodeId: string): EvidenceResult | undefined;
+export interface MatrixRow {
+    scenarioId: string;
+    level: string;
+    /** Test anchors this GWT is bound to (Scenario.verified_by). Empty = unverified. */
+    verifiedBy: string[];
+    /** in-flow nodes (junction/loop) that reference this scenario, or "applies_to" for an invariant. */
+    referencedBy: string[];
+    verified: boolean;
+}
+export interface TestMatrixResult {
+    flowId: string;
+    title: string;
+    rows: MatrixRow[];
+    /**
+     * `unknownScenario` counts rows whose scenario id resolved to no Scenario
+     * node — always 0 on a T0-passing model (referential integrity catches
+     * dangling scenario refs), surfaced anyway so a broken model isn't silent.
+     */
+    summary: {
+        total: number;
+        verified: number;
+        unverified: number;
+        unknownScenario: number;
+    };
+}
+/**
+ * The GWT↔test binding matrix for a flow (Proposal 006 B5 / 001 §12 "GWT 独立于
+ * 测试代码长期存在"): every scenario reachable from the flow — via its crossing
+ * junctions, its traversed/guarding loops, and each loop's effective
+ * constraints — with the tests it's bound to and whether it's verified. Makes
+ * the flow's test-coverage surface legible at a glance (which GWT are grounded
+ * in a real test, which are deliberately unverified).
+ */
+export declare function testMatrix(graph: ModelGraph, flowId: string): TestMatrixResult | undefined;
+//# sourceMappingURL=queries.d.ts.map

package/dist/query/queries.js

@@ -0,0 +1,172 @@
+import { getNode } from "../loader/model-graph.js";
+import { resolveApplicableScenarios, scenarioApplies } from "./effective-constraints.js";
+/**
+ * Everything that references `nodeId` — the set a change to it may force you to
+ * re-check. Reverse edges only (who points AT this node), deliberately NOT the
+ * general bidirectional slice `inspect` gives: this answers "if I change X,
+ * what's the blast radius", not "what's near X".
+ */
+export function impactOf(graph, nodeId) {
+    const node = getNode(graph, nodeId);
+    if (!node)
+        return undefined;
+    const dependents = [];
+    const seen = new Set(); // dedup by id: a node is one dependent even if linked two ways
+    const add = (id, kind, relation) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        dependents.push({ id, kind, relation });
+    };
+    for (const flow of graph.byKind.flow.values()) {
+        if (flow.traverses.includes(nodeId))
+            add(flow.id, "flow", "traverses");
+        if (flow.guarded_by.includes(nodeId))
+            add(flow.id, "flow", "guarded_by");
+        if (flow.crosses.includes(nodeId))
+            add(flow.id, "flow", "crosses");
+        if (flow.references.includes(nodeId))
+            add(flow.id, "flow", "references");
+    }
+    for (const feature of graph.byKind.feature.values()) {
+        if (feature.contains.includes(nodeId))
+            add(feature.id, "feature", "contains");
+    }
+    for (const loop of graph.byKind.loop.values()) {
+        if (loop.parent === nodeId)
+            add(loop.id, "loop", "parent");
+        if (loop.scenarios.includes(nodeId))
+            add(loop.id, "loop", "scenarios");
+    }
+    for (const junction of graph.byKind.junction.values()) {
+        if (junction.between.includes(nodeId))
+            add(junction.id, "junction", "between");
+        if (junction.scenarios.includes(nodeId))
+            add(junction.id, "junction", "scenarios");
+    }
+    // A loop is also "impacted" by any invariant scenario that applies to it via
+    // applies_to — and a scenario's impact includes the loops it constrains.
+    if (node.kind === "scenario") {
+        for (const loop of graph.byKind.loop.values()) {
+            if (scenarioApplies(node, loop.id, graph))
+                add(loop.id, "loop", "applies_to");
+        }
+    }
+    else if (node.kind === "loop") {
+        for (const s of resolveApplicableScenarios(graph, nodeId))
+            add(s.id, "scenario", "applies_to→");
+    }
+    // stable order: kind then id
+    dependents.sort((a, b) => a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id));
+    return { nodeId, kind: node.kind, dependents };
+}
+/** The ordered "how this flow runs" plan: traverses sequence, guards, crossing junctions. */
+export function planOf(graph, flowId) {
+    const flow = graph.byKind.flow.get(flowId);
+    if (!flow)
+        return undefined;
+    const steps = flow.traverses.map((loopId) => {
+        const loop = graph.byKind.loop.get(loopId);
+        return {
+            loopId,
+            title: loop?.title ?? loopId,
+            status: loop?.status ?? "unknown",
+            effectiveConstraints: resolveApplicableScenarios(graph, loopId).map((s) => s.id),
+        };
+    });
+    const guards = flow.guarded_by.map((loopId) => ({
+        loopId,
+        title: graph.byKind.loop.get(loopId)?.title ?? loopId,
+    }));
+    const junctions = flow.crosses
+        .map((id) => graph.byKind.junction.get(id))
+        .filter((j) => j !== undefined)
+        .map((j) => ({
+        id: j.id,
+        risk_class: j.risk_class,
+        between: j.between,
+        title: j.title ?? "",
+    }));
+    return { flowId, title: flow.title, steps, guards, junctions, subFlows: flow.references };
+}
+export function scenarioDetail(graph, scenarioId) {
+    const scenario = graph.byKind.scenario.get(scenarioId);
+    if (!scenario)
+        return undefined;
+    const referencedBy = [];
+    for (const loop of graph.byKind.loop.values())
+        if (loop.scenarios.includes(scenarioId))
+            referencedBy.push({ id: loop.id, kind: "loop" });
+    for (const junction of graph.byKind.junction.values())
+        if (junction.scenarios.includes(scenarioId))
+            referencedBy.push({ id: junction.id, kind: "junction" });
+    const appliesToLoops = [...graph.byKind.loop.values()]
+        .filter((l) => scenarioApplies(scenario, l.id, graph))
+        .map((l) => l.id);
+    return { scenario, referencedBy, appliesToLoops };
+}
+export function evidenceOf(graph, nodeId) {
+    const node = getNode(graph, nodeId);
+    if (!node)
+        return undefined;
+    const evidence = node.kind === "junction" ? node.evidence : [];
+    const anchors = node.kind === "loop" ? node.anchors : [];
+    const own = node.kind === "loop" || node.kind === "junction" ? node.scenarios : [];
+    const eff = node.kind === "loop" ? resolveApplicableScenarios(graph, nodeId).map((s) => s.id) : [];
+    const scenarios = [...new Set([...own, ...eff])];
+    return { nodeId, kind: node.kind, evidence, anchors, scenarios };
+}
+/**
+ * The GWT↔test binding matrix for a flow (Proposal 006 B5 / 001 §12 "GWT 独立于
+ * 测试代码长期存在"): every scenario reachable from the flow — via its crossing
+ * junctions, its traversed/guarding loops, and each loop's effective
+ * constraints — with the tests it's bound to and whether it's verified. Makes
+ * the flow's test-coverage surface legible at a glance (which GWT are grounded
+ * in a real test, which are deliberately unverified).
+ */
+export function testMatrix(graph, flowId) {
+    const flow = graph.byKind.flow.get(flowId);
+    if (!flow)
+        return undefined;
+    // scenarioId → the in-flow nodes that pull it in (deduped, ordered).
+    const refs = new Map();
+    const addRef = (scenarioId, from) => {
+        const set = refs.get(scenarioId) ?? new Set();
+        set.add(from);
+        refs.set(scenarioId, set);
+    };
+    for (const jid of flow.crosses) {
+        const junction = graph.byKind.junction.get(jid);
+        for (const s of junction?.scenarios ?? [])
+            addRef(s, jid);
+    }
+    for (const lid of [...flow.traverses, ...flow.guarded_by]) {
+        const loop = graph.byKind.loop.get(lid);
+        for (const s of loop?.scenarios ?? [])
+            addRef(s, lid);
+        for (const s of resolveApplicableScenarios(graph, lid))
+            addRef(s.id, `${lid}:applies_to`);
+    }
+    const rows = [...refs.keys()]
+        .map((scenarioId) => {
+        const scenario = graph.byKind.scenario.get(scenarioId);
+        const verifiedBy = scenario?.verified_by ?? [];
+        return {
+            scenarioId,
+            level: scenario?.level ?? "unknown",
+            verifiedBy,
+            referencedBy: [...(refs.get(scenarioId) ?? [])].sort(),
+            verified: verifiedBy.length > 0,
+        };
+    })
+        .sort((a, b) => a.scenarioId.localeCompare(b.scenarioId));
+    const verified = rows.filter((r) => r.verified).length;
+    const unknownScenario = rows.filter((r) => r.level === "unknown").length;
+    return {
+        flowId,
+        title: flow.title,
+        rows,
+        summary: { total: rows.length, verified, unverified: rows.length - verified, unknownScenario },
+    };
+}
+//# sourceMappingURL=queries.js.map

package/dist/query/run-query.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Phase-2 query command runner (Proposal 006 B4): loads the model, runs one
+ * focused query, writes a staleness-stamped side-channel file, and returns a
+ * compact summary + the file path — the 001 §4.2 shape shared by CLI and MCP.
+ * `inspect` has its own runner (A5); this covers impact/plan/scenario/evidence.
+ */
+export type QueryCommand = "impact" | "plan" | "scenario" | "evidence" | "matrix";
+export interface QueryResult {
+    command: QueryCommand;
+    id: string;
+    outputPath: string;
+    summary: string;
+    staleWarning?: string;
+}
+export declare function runQuery(targetDir: string, command: QueryCommand, id: string): Promise<QueryResult>;
+//# sourceMappingURL=run-query.d.ts.map

package/dist/query/run-query.js

@@ -0,0 +1,181 @@
+import { join } from "node:path";
+import { loadModel } from "../loader/load-model.js";
+import { evidenceOf, impactOf, planOf, scenarioDetail, testMatrix, } from "./queries.js";
+import { writeSideChannel } from "./side-channel.js";
+function renderImpact(r) {
+    const byRelation = {};
+    for (const d of r.dependents) {
+        const list = byRelation[d.relation] ?? [];
+        list.push(`${d.id}(${d.kind})`);
+        byRelation[d.relation] = list;
+    }
+    const summary = [
+        `impact ${r.nodeId} (${r.kind}) — ${r.dependents.length} dependent(s):`,
+        ...Object.entries(byRelation).map(([rel, ids]) => `  via ${rel}: ${ids.join(", ")}`),
+    ].join("\n");
+    const body = [
+        `# impact ${r.nodeId} (${r.kind})`,
+        "",
+        `${r.dependents.length} node(s) reference it — changing ${r.nodeId} may force re-checking these:`,
+        "",
+        ...r.dependents.map((d) => `- ${d.id} (${d.kind}) — ${d.relation}`),
+    ].join("\n");
+    return { summary, body };
+}
+function renderPlan(r) {
+    const seq = r.steps.map((s) => s.loopId).join(" → ") || "(no traverses)";
+    const summary = [
+        `plan ${r.flowId} — ${r.title}`,
+        `  sequence: ${seq}`,
+        `  guards: ${r.guards.map((g) => g.loopId).join(", ") || "(none)"}`,
+        `  junctions: ${r.junctions.map((j) => `${j.id}[${j.risk_class}]`).join(", ") || "(none)"}`,
+        r.subFlows.length ? `  sub-flows: ${r.subFlows.join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const body = [
+        `# plan ${r.flowId} — ${r.title}`,
+        "",
+        "## ordered steps",
+        "",
+        ...r.steps.map((s, i) => {
+            const head = `${i + 1}. **${s.loopId}** ${s.title} [${s.status}]`;
+            return s.effectiveConstraints.length
+                ? `${head}\n   - invariants (applies_to): ${s.effectiveConstraints.join(", ")}`
+                : head;
+        }),
+        "",
+        "## guards (watchdogs)",
+        "",
+        ...(r.guards.length ? r.guards.map((g) => `- ${g.loopId} ${g.title}`) : ["(none)"]),
+        "",
+        "## crossing junctions",
+        "",
+        ...(r.junctions.length
+            ? r.junctions.map((j) => `- ${j.id} [${j.risk_class}] ${j.between.join("→")}${j.title ? ` — ${j.title}` : ""}`)
+            : ["(none)"]),
+        r.subFlows.length ? `\n## sub-flows\n\n${r.subFlows.map((f) => `- ${f}`).join("\n")}` : "",
+    ].join("\n");
+    return { summary, body };
+}
+function renderScenario(r) {
+    const s = r.scenario;
+    const refs = r.referencedBy.map((x) => `${x.id}(${x.kind})`).join(", ") || "(none)";
+    const summary = [
+        `scenario ${s.id} [${s.level}] — verified_by ${s.verified_by.length} test(s)`,
+        `  referenced by: ${refs}`,
+        r.appliesToLoops.length ? `  applies to loops: ${r.appliesToLoops.join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const body = [
+        `# scenario ${s.id} [${s.level}]`,
+        "",
+        `- **given** ${s.given}`,
+        `- **when** ${s.when}`,
+        `- **then** ${s.then}`,
+        `- **verified_by**: ${s.verified_by.length ? s.verified_by.join(", ") : "(none — unverified)"}`,
+        s.applies_to
+            ? `- **applies_to**: nodes=[${s.applies_to.nodes.join(", ")}]${s.applies_to.owner_match ? ` owner_match="${s.applies_to.owner_match}"` : ""}`
+            : "",
+        "",
+        `## referenced by\n\n${r.referencedBy.length ? r.referencedBy.map((x) => `- ${x.id} (${x.kind})`).join("\n") : "(none)"}`,
+        r.appliesToLoops.length
+            ? `\n## applies to loops (resolved)\n\n${r.appliesToLoops.map((l) => `- ${l}`).join("\n")}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { summary, body };
+}
+function renderEvidence(r) {
+    const summary = [
+        `evidence ${r.nodeId} (${r.kind}) — ${r.evidence.length} evidence, ${r.anchors.length} anchor(s), ${r.scenarios.length} scenario(s)`,
+        ...r.evidence.map((e) => `  [${e.kind}] ${e.anchor}`),
+        ...r.anchors.map((a) => `  anchor: ${a}`),
+    ].join("\n");
+    const body = [
+        `# evidence ${r.nodeId} (${r.kind})`,
+        "",
+        r.evidence.length ? "## evidence" : "",
+        ...r.evidence.map((e) => `- [${e.kind}] \`${e.anchor}\`${e.note ? ` — ${e.note}` : ""}`),
+        r.anchors.length ? "\n## anchors" : "",
+        ...r.anchors.map((a) => `- \`${a}\``),
+        r.scenarios.length
+            ? `\n## bound scenarios\n\n${r.scenarios.map((x) => `- ${x}`).join("\n")}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { summary, body };
+}
+function renderMatrix(r) {
+    const unknownNote = r.summary.unknownScenario
+        ? ` (⚠ ${r.summary.unknownScenario} dangling scenario ref)`
+        : "";
+    const summary = [
+        `matrix ${r.flowId} — ${r.title}`,
+        `  ${r.summary.total} GWT: ${r.summary.verified} verified / ${r.summary.unverified} unverified${unknownNote}`,
+    ].join("\n");
+    const body = [
+        `# test matrix ${r.flowId} — ${r.title}`,
+        "",
+        `${r.summary.total} scenarios · ${r.summary.verified} verified · ${r.summary.unverified} unverified${unknownNote}`,
+        "",
+        "| GWT | level | verified | verified_by | referenced by |",
+        "|---|---|---|---|---|",
+        ...r.rows.map((row) => `| ${row.scenarioId} | ${row.level} | ${row.verified ? "✅" : "—"} | ${
+        // "; "-separated so the cell stays readable as plain text (not just rendered)
+        row.verifiedBy.length ? row.verifiedBy.map((v) => `\`${v}\``).join("; ") : "(none)"} | ${row.referencedBy.join(", ")} |`),
+        "",
+    ].join("\n");
+    return { summary, body };
+}
+function render(command, graph, id) {
+    switch (command) {
+        case "impact": {
+            const r = impactOf(graph, id);
+            return r && renderImpact(r);
+        }
+        case "plan": {
+            const r = planOf(graph, id);
+            return r && renderPlan(r);
+        }
+        case "scenario": {
+            const r = scenarioDetail(graph, id);
+            return r && renderScenario(r);
+        }
+        case "evidence": {
+            const r = evidenceOf(graph, id);
+            return r && renderEvidence(r);
+        }
+        case "matrix": {
+            const r = testMatrix(graph, id);
+            return r && renderMatrix(r);
+        }
+    }
+}
+export async function runQuery(targetDir, command, id) {
+    const load = await loadModel(join(targetDir, "model"));
+    if (load.parseErrors.length > 0) {
+        throw new Error(`model has ${load.parseErrors.length} parse error(s) — run "loopgraph check" first`);
+    }
+    const rendered = render(command, load.graph, id);
+    if (!rendered) {
+        const expected = command === "plan" || command === "matrix"
+            ? "flow"
+            : command === "scenario"
+                ? "scenario"
+                : "node";
+        throw new Error(`unknown ${expected} id "${id}" for \`${command}\``);
+    }
+    const { outputPath, staleWarning } = await writeSideChannel(targetDir, `${command}-${id}`, (banner) => `${banner}\n\n${rendered.body}\n`);
+    return {
+        command,
+        id,
+        outputPath,
+        summary: `${rendered.summary}\n  (full detail: ${outputPath})`,
+        ...(staleWarning ? { staleWarning } : {}),
+    };
+}
+//# sourceMappingURL=run-query.js.map

package/dist/query/side-channel.d.ts

@@ -0,0 +1,25 @@
+export interface SideChannelResult {
+    outputPath: string;
+    /** Set when a pre-existing file for this tag was stale vs the current model. */
+    staleWarning?: string;
+}
+/**
+ * Shared side-channel writer for the query family (extracted from A5's inspect
+ * so inspect/impact/plan/scenario/evidence don't each re-implement it). Writes
+ * `<targetDir>/.loopgraph/ws/<fileTag>.md`, stamped with a staleness banner,
+ * and — before overwriting — reads any prior file and warns if it was stale
+ * (Decision 004 技术点 4 consumer). `buildBody` receives the banner to place it
+ * wherever the body wants (top, by convention).
+ *
+ * Concurrency: the side-channel file is a regenerated-on-demand ADVISORY
+ * artifact, not source data — the model YAML is never touched here, only this
+ * derived output. The read→judge→write is deliberately NOT locked: the worst
+ * case under a race is a spurious/missed staleness *warning* plus one of two
+ * near-identical regenerations winning; no model data is at risk, so a file
+ * lock is not pulled in for a local dev tool. The write itself IS atomic — a
+ * uniquely-named temp (`randomUUID`, so two concurrent writers in the SAME
+ * process, e.g. two MCP tool calls for the same id, never collide on the temp)
+ * then `rename`, so a reader never observes a half-written file.
+ */
+export declare function writeSideChannel(targetDir: string, fileTag: string, buildBody: (banner: string) => string): Promise<SideChannelResult>;
+//# sourceMappingURL=side-channel.d.ts.map

package/dist/query/side-channel.js

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { computeStalenessStamp, formatStalenessBanner, isStale, parseStalenessBanner, } from "../staleness.js";
+function shortHash(h) {
+    return h.slice(0, 12);
+}
+/**
+ * Shared side-channel writer for the query family (extracted from A5's inspect
+ * so inspect/impact/plan/scenario/evidence don't each re-implement it). Writes
+ * `<targetDir>/.loopgraph/ws/<fileTag>.md`, stamped with a staleness banner,
+ * and — before overwriting — reads any prior file and warns if it was stale
+ * (Decision 004 技术点 4 consumer). `buildBody` receives the banner to place it
+ * wherever the body wants (top, by convention).
+ *
+ * Concurrency: the side-channel file is a regenerated-on-demand ADVISORY
+ * artifact, not source data — the model YAML is never touched here, only this
+ * derived output. The read→judge→write is deliberately NOT locked: the worst
+ * case under a race is a spurious/missed staleness *warning* plus one of two
+ * near-identical regenerations winning; no model data is at risk, so a file
+ * lock is not pulled in for a local dev tool. The write itself IS atomic — a
+ * uniquely-named temp (`randomUUID`, so two concurrent writers in the SAME
+ * process, e.g. two MCP tool calls for the same id, never collide on the temp)
+ * then `rename`, so a reader never observes a half-written file.
+ */
+export async function writeSideChannel(targetDir, fileTag, buildBody) {
+    const modelDir = join(targetDir, "model");
+    const currentStamp = await computeStalenessStamp(modelDir, targetDir);
+    const wsDir = join(targetDir, ".loopgraph", "ws");
+    await mkdir(wsDir, { recursive: true });
+    const outputPath = join(wsDir, `${fileTag}.md`);
+    let staleWarning;
+    const prior = await readFile(outputPath, "utf8").catch(() => undefined);
+    if (prior) {
+        const priorStamp = parseStalenessBanner(prior);
+        if (priorStamp && isStale(priorStamp, currentStamp)) {
+            staleWarning = `prior ${outputPath} was stale: model_content_hash ${shortHash(priorStamp.modelContentHash)} != current ${shortHash(currentStamp.modelContentHash)} — regenerated`;
+        }
+    }
+    const body = buildBody(formatStalenessBanner(currentStamp));
+    const tmpPath = `${outputPath}.${randomUUID()}.tmp`;
+    await writeFile(tmpPath, body, "utf8");
+    await rename(tmpPath, outputPath);
+    return { outputPath, ...(staleWarning ? { staleWarning } : {}) };
+}
+//# sourceMappingURL=side-channel.js.map

package/dist/query/slice.d.ts

@@ -0,0 +1,57 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+import type { ModelNode } from "../schema/index.js";
+/**
+ * Reusable model-slice join (Proposal 006 A5). Given a start node id and a
+ * traversal depth, produce the connected task-relevant sub-graph:
+ * flow→loops/junctions/sub-flows, loop→junctions/scenarios/parent/effective
+ * constraints, junction→loops/scenarios, scenario→referrers/applies_to.
+ *
+ * This is deliberately factored out of the `inspect` CLI command so the
+ * Phase 2 query family (`model impact`/`plan`/`scenario`/`evidence`) reuses
+ * one traversal + one summary/truncation module (proposal 001 §4.2), rather
+ * than each command re-deriving "what's related to X".
+ */
+export interface SliceNode {
+    id: string;
+    kind: ModelNode["kind"];
+    /** Shortest hop distance from the root (root = 0). */
+    depth: number;
+    node: ModelNode;
+    /**
+     * For loops only: scenario ids that apply via `applies_to` (effective
+     * constraints, Decision 004 技术点 2) — computed at query time, not
+     * hand-listed on the node. Undefined for non-loop kinds.
+     */
+    effectiveConstraints?: string[];
+}
+/** A neighbor one hop past the traversal frontier, surfaced as a pointer (not expanded). */
+export interface FrontierPointer {
+    id: string;
+    kind: ModelNode["kind"];
+    /** An in-slice node that references this pointer (so the user knows where it hangs off). */
+    fromId: string;
+}
+export interface ModelSlice {
+    rootId: string;
+    rootKind: ModelNode["kind"];
+    maxDepth: number;
+    /** Reached nodes, ordered by (depth, id). Includes the root at depth 0. */
+    nodes: SliceNode[];
+    /** Neighbors beyond `maxDepth` that were not expanded — expand with `--depth`. */
+    frontierPointers: FrontierPointer[];
+}
+/**
+ * Depth-limited breadth-first slice from `rootId`. Returns undefined if the
+ * root id isn't a node in the graph (the CLI turns that into an "unknown id"
+ * error).
+ *
+ * Standard mark-at-enqueue BFS: a node is added to `enqueued` the moment it's
+ * first discovered, so (a) each node is enqueued exactly once and recorded at
+ * its shortest distance from the root, and (b) any node reachable within
+ * `maxDepth` is marked (via its shallower parent, which the depth-ordered FIFO
+ * dequeues first) before a depth==maxDepth sibling could add it to the
+ * frontier — so `frontierPointers` and the in-slice node set never overlap by
+ * construction, no post-hoc reconciliation needed.
+ */
+export declare function sliceModel(graph: ModelGraph, rootId: string, maxDepth: number): ModelSlice | undefined;
+//# sourceMappingURL=slice.d.ts.map