loopgraph 0.1.0

package/dist/loader/find-yaml-files.js

@@ -0,0 +1,51 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+const MODEL_DIR_READ_HINTS = {
+    ENOENT: `not found — run "loopgraph init" and "loopgraph import" first`,
+    ENOTDIR: "not a directory — check the target path",
+    EACCES: "not readable (permission denied)",
+    EPERM: "not readable (permission denied)",
+};
+/**
+ * Pure error-code → message mapping, factored out of findYamlFiles so
+ * every branch (ENOENT/ENOTDIR/EACCES/EPERM/unknown) is directly
+ * unit-testable without needing to actually reproduce each condition on
+ * a real filesystem — reproducing EACCES portably (across macOS/Linux/CI
+ * containers, some of which run as root and ignore chmod) is exactly the
+ * kind of flaky test this sidesteps. Returns undefined for an
+ * unrecognized/missing error code, signaling "rethrow as-is".
+ */
+export function formatModelDirReadError(dir, code) {
+    const hint = code ? MODEL_DIR_READ_HINTS[code] : undefined;
+    return hint ? `model directory "${dir}" is ${hint}` : undefined;
+}
+/**
+ * An unreadable model directory (missing, wrong permissions, or not
+ * actually a directory) is a setup error, not "zero nodes". Treating it
+ * as an empty model would make `runT0` trivially pass with zero
+ * violations — a false "T0 passed" that implies something was checked
+ * when nothing was. This surfaces a clear, actionable error instead of
+ * whatever raw errno a bare `readdir` would throw.
+ *
+ * Lives in its own module (not inlined in load-model.ts) because it's
+ * reused by src/staleness.ts (computeModelContentHash needs the same
+ * "every *.yaml/*.yml file under a model dir" listing to hash) — a
+ * second, unrelated caller that has no business depending on
+ * `loadModel`'s own orchestration module.
+ */
+export async function findYamlFiles(dir) {
+    let dirents;
+    try {
+        dirents = await readdir(dir, { recursive: true, withFileTypes: true });
+    }
+    catch (err) {
+        const message = formatModelDirReadError(dir, err.code);
+        if (message)
+            throw new Error(message);
+        throw err;
+    }
+    return dirents
+        .filter((d) => d.isFile() && /\.ya?ml$/.test(d.name))
+        .map((d) => join(d.parentPath ?? d.path, d.name));
+}
+//# sourceMappingURL=find-yaml-files.js.map

package/dist/loader/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./model-graph.js";
+export * from "./find-yaml-files.js";
+export * from "./load-model.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/loader/index.js

@@ -0,0 +1,4 @@
+export * from "./model-graph.js";
+export * from "./find-yaml-files.js";
+export * from "./load-model.js";
+//# sourceMappingURL=index.js.map

package/dist/loader/load-model.d.ts

@@ -0,0 +1,32 @@
+import { type DuplicateId, type ModelEntry, type ModelGraph } from "./model-graph.js";
+export interface ParseError {
+    file: string;
+    message: string;
+}
+export interface LoadResult {
+    graph: ModelGraph;
+    entries: ModelEntry[];
+    parseErrors: ParseError[];
+    duplicateIds: DuplicateId[];
+    /**
+     * Files written as a SINGLE node (not a YAML array), mapped to that node's
+     * id. This is exactly the set the file-per-node convention applies to
+     * (Decision 004 技术点 3: filename must equal id) — array files that group
+     * many nodes under a section name (the seed's loops/*.yaml) are deliberately
+     * absent, so `checkFilenameMatchesId` doesn't false-flag them.
+     */
+    singleNodeFiles: Map<string, string>;
+}
+/**
+ * Loads every *.yaml/*.yml file under `dir`. A file may contain a single
+ * node or an array of nodes; array elements are validated independently
+ * so one malformed sibling doesn't take down the rest of the file's
+ * otherwise-valid nodes (a whole-array `safeParse` would fail the entire
+ * batch on a single bad element — that's the wrong blast radius for a
+ * file that groups many unrelated loops together, see
+ * examples/agenthub/model/loops/*.yaml). Parse/validation failures are
+ * collected rather than thrown so `loopgraph check` can report every
+ * broken node in one pass instead of stopping at the first one.
+ */
+export declare function loadModel(dir: string): Promise<LoadResult>;
+//# sourceMappingURL=load-model.d.ts.map

package/dist/loader/load-model.js

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ModelNode } from "../schema/index.js";
+import { findYamlFiles } from "./find-yaml-files.js";
+import { buildGraph } from "./model-graph.js";
+/**
+ * Loads every *.yaml/*.yml file under `dir`. A file may contain a single
+ * node or an array of nodes; array elements are validated independently
+ * so one malformed sibling doesn't take down the rest of the file's
+ * otherwise-valid nodes (a whole-array `safeParse` would fail the entire
+ * batch on a single bad element — that's the wrong blast radius for a
+ * file that groups many unrelated loops together, see
+ * examples/agenthub/model/loops/*.yaml). Parse/validation failures are
+ * collected rather than thrown so `loopgraph check` can report every
+ * broken node in one pass instead of stopping at the first one.
+ */
+export async function loadModel(dir) {
+    const files = await findYamlFiles(dir);
+    const entries = [];
+    const parseErrors = [];
+    const singleNodeFiles = new Map();
+    for (const absPath of files.sort()) {
+        const relPath = relative(dir, absPath);
+        let raw;
+        try {
+            const text = await readFile(absPath, "utf8");
+            raw = parseYaml(text);
+        }
+        catch (err) {
+            parseErrors.push({ file: relPath, message: `YAML parse error: ${err.message}` });
+            continue;
+        }
+        const isArrayFile = Array.isArray(raw);
+        const items = Array.isArray(raw) ? raw : [raw];
+        items.forEach((item, index) => {
+            const result = ModelNode.safeParse(item);
+            if (!result.success) {
+                const location = isArrayFile ? `${relPath} (item ${index})` : relPath;
+                parseErrors.push({
+                    file: location,
+                    message: `schema validation failed: ${result.error.message}`,
+                });
+                return;
+            }
+            entries.push({ node: result.data, file: relPath });
+            if (!isArrayFile)
+                singleNodeFiles.set(relPath, result.data.id);
+        });
+    }
+    const { graph, duplicateIds } = buildGraph(entries);
+    return { graph, entries, parseErrors, duplicateIds, singleNodeFiles };
+}
+//# sourceMappingURL=load-model.js.map

package/dist/loader/model-graph.d.ts

@@ -0,0 +1,43 @@
+import type { DebtEntry, Feature, Flow, Junction, Loop, ModelNode, Scenario } from "../schema/index.js";
+/**
+ * A single successfully-parsed node together with the file it came from.
+ * This is the raw ingredient both the graph builder and the T0 checker
+ * (ID uniqueness in particular) need — keeping it as a flat list first
+ * means "two nodes share an id" is representable before we collapse
+ * anything into a Map.
+ */
+export interface ModelEntry {
+    node: ModelNode;
+    file: string;
+}
+export interface ModelGraph {
+    byKind: {
+        feature: Map<string, Feature>;
+        flow: Map<string, Flow>;
+        loop: Map<string, Loop>;
+        junction: Map<string, Junction>;
+        scenario: Map<string, Scenario>;
+        debt: Map<string, DebtEntry>;
+    };
+    /** Source file each id was loaded from (first occurrence wins on duplicates). */
+    sourceFile: Map<string, string>;
+}
+export interface DuplicateId {
+    id: string;
+    files: string[];
+}
+export declare function createEmptyGraph(): ModelGraph;
+/**
+ * Builds a ModelGraph from a flat list of parsed entries. Duplicate ids
+ * (same id appearing in more than one entry, whether same kind or not)
+ * are reported rather than silently overwritten — first occurrence wins
+ * in the graph, but every duplicate is surfaced so T0's ID-uniqueness
+ * check can fail the build.
+ */
+export declare function buildGraph(entries: ModelEntry[]): {
+    graph: ModelGraph;
+    duplicateIds: DuplicateId[];
+};
+export declare function getNode(graph: ModelGraph, id: string): ModelNode | undefined;
+export declare function allNodes(graph: ModelGraph): ModelNode[];
+//# sourceMappingURL=model-graph.d.ts.map

package/dist/loader/model-graph.js

@@ -0,0 +1,78 @@
+export function createEmptyGraph() {
+    return {
+        byKind: {
+            feature: new Map(),
+            flow: new Map(),
+            loop: new Map(),
+            junction: new Map(),
+            scenario: new Map(),
+            debt: new Map(),
+        },
+        sourceFile: new Map(),
+    };
+}
+/**
+ * Builds a ModelGraph from a flat list of parsed entries. Duplicate ids
+ * (same id appearing in more than one entry, whether same kind or not)
+ * are reported rather than silently overwritten — first occurrence wins
+ * in the graph, but every duplicate is surfaced so T0's ID-uniqueness
+ * check can fail the build.
+ */
+export function buildGraph(entries) {
+    const graph = createEmptyGraph();
+    const filesById = new Map();
+    for (const { node, file } of entries) {
+        const existing = filesById.get(node.id);
+        if (existing) {
+            existing.push(file);
+            continue;
+        }
+        filesById.set(node.id, [file]);
+        graph.sourceFile.set(node.id, file);
+        switch (node.kind) {
+            case "feature":
+                graph.byKind.feature.set(node.id, node);
+                break;
+            case "flow":
+                graph.byKind.flow.set(node.id, node);
+                break;
+            case "loop":
+                graph.byKind.loop.set(node.id, node);
+                break;
+            case "junction":
+                graph.byKind.junction.set(node.id, node);
+                break;
+            case "scenario":
+                graph.byKind.scenario.set(node.id, node);
+                break;
+            case "debt":
+                graph.byKind.debt.set(node.id, node);
+                break;
+        }
+    }
+    const duplicateIds = [];
+    for (const [id, files] of filesById) {
+        if (files.length > 1)
+            duplicateIds.push({ id, files });
+    }
+    return { graph, duplicateIds };
+}
+export function getNode(graph, id) {
+    return (graph.byKind.feature.get(id) ??
+        graph.byKind.flow.get(id) ??
+        graph.byKind.loop.get(id) ??
+        graph.byKind.junction.get(id) ??
+        graph.byKind.scenario.get(id) ??
+        graph.byKind.debt.get(id));
+}
+export function allNodes(graph) {
+    return [
+        ...graph.byKind.feature.values(),
+        ...graph.byKind.flow.values(),
+        ...graph.byKind.loop.values(),
+        ...graph.byKind.junction.values(),
+        ...graph.byKind.scenario.values(),
+        ...graph.byKind.debt.values(),
+    ];
+}
+//# sourceMappingURL=model-graph.js.map

package/dist/mcp/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function buildMcpServer(targetDir: string): McpServer;
+/** Starts the server on stdio (the shape an MCP client launches: `loopgraph mcp <dir>`). */
+export declare function startMcpServer(targetDir: string): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.js

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { runInspect } from "../cli/commands/inspect.js";
+import { runQuery } from "../query/run-query.js";
+/**
+ * The loopgraph stdio MCP server (Proposal 006 B4 / 001 §0 §8): a few-entry
+ * query surface that hands an Agent task-relevant model slices, so it doesn't
+ * have to read the whole spec. Every tool follows the 001 §4.2 side-channel
+ * shape — the response is a compact SUMMARY plus the path to a full workspace
+ * file — keeping tool responses small while the detail stays retrievable.
+ *
+ * All tools are read-only model queries (no repoRoot, no code scan, no LLM).
+ * `targetDir` (the dir holding `model/`) is fixed at server start.
+ */
+function toolResult(text, isError = false) {
+    return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
+}
+export function buildMcpServer(targetDir) {
+    const server = new McpServer({ name: "loopgraph", version: "0.1.0" });
+    const render = (r) => toolResult(`${r.staleWarning ? `⚠ ${r.staleWarning}\n\n` : ""}${r.summary}\n\nfull detail written to: ${r.outputPath}`);
+    server.registerTool("model_inspect", {
+        description: "Slice the behavioral model around a node id (flow C1.., loop L1.., junction J-.., scenario GWT-..). Returns a summary (node skeletons + child counts + effective constraints) plus a side-channel file with the full slice. Use this first to orient on an unfamiliar part of the system.",
+        inputSchema: { id: z.string(), depth: z.number().int().min(0).optional() },
+    }, async ({ id, depth }) => {
+        try {
+            return render(await runInspect(targetDir, id, depth != null ? { depth } : {}));
+        }
+        catch (err) {
+            return toolResult(err instanceof Error ? err.message : String(err), true);
+        }
+    });
+    const queryTool = (name, command, description) => server.registerTool(`model_${name}`, { description, inputSchema: { id: z.string() } }, async ({ id }) => {
+        try {
+            return render(await runQuery(targetDir, command, id));
+        }
+        catch (err) {
+            return toolResult(err instanceof Error ? err.message : String(err), true);
+        }
+    });
+    queryTool("impact", "impact", "Reverse-dependency blast radius of a node: everything that references it (which flows traverse a loop, which junctions sit between it, which scenarios constrain it). Use before changing a node to see what must be re-checked.");
+    queryTool("plan", "plan", "A flow's ordered execution plan (id like C1): the traverses sequence, watchdog guards, and crossing junctions with their risk classes and endpoints. Use to understand how one end-to-end flow runs.");
+    queryTool("scenario", "scenario", "A GWT scenario's full detail (id like GWT-C1-001): given/when/then, the tests that verify it, which loops/junctions reference it, and (for invariants) the loops it applies to.");
+    queryTool("evidence", "evidence", "A node's grounding: a junction's typed evidence anchors (code/spec/issue/test) with notes, or a loop's code anchors, plus the scenarios bound to it.");
+    queryTool("matrix", "matrix", "A flow's GWT↔test coverage matrix (id like C1): every scenario reachable from the flow, the tests it's bound to, and whether it's verified — the flow's test-coverage surface at a glance.");
+    return server;
+}
+/** Starts the server on stdio (the shape an MCP client launches: `loopgraph mcp <dir>`). */
+export async function startMcpServer(targetDir) {
+    const server = buildMcpServer(targetDir);
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=server.js.map

package/dist/query/diff.d.ts

@@ -0,0 +1,47 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+/**
+ * `--diff` incremental support (Proposal 006 B2 / 001 §5 §6): resolve what a PR
+ * changed so a check re-runs only over the diff closure instead of the whole
+ * repo, and map the changed files back to the model nodes they touch.
+ */
+/**
+ * Repo-relative paths changed between `merge-base(baseRef, HEAD)` and the
+ * working tree (committed + uncommitted), via git. Uses the merge-base (not a
+ * raw `baseRef..HEAD`) so a stale base branch doesn't inflate the diff with
+ * commits already on HEAD. Returns undefined when the ref/repo is unusable —
+ * the caller falls back to a full scan rather than silently checking nothing.
+ */
+export declare function changedFiles(gitRoot: string, baseRef: string): Promise<string[] | undefined>;
+/** The git top-level of `dir`, or undefined if `dir` isn't inside a git checkout. */
+export declare function gitRootOf(dir: string): Promise<string | undefined>;
+export interface AffectedNode {
+    nodeId: string;
+    kind: string;
+    /** the anchor whose file is in the changed set */
+    anchor: string;
+    file: string;
+}
+/**
+ * Model nodes whose anchor points at one of `changedFiles` — the diff's impact
+ * surface on the model. Pure. A loop/junction/scenario is "affected" when a
+ * file it anchors to (Loop.anchors, Junction.evidence[].anchor,
+ * Scenario.verified_by[]) changed, so a reviewer sees which modeled behaviors a
+ * diff might have moved out from under.
+ */
+export declare function affectedNodes(graph: ModelGraph, changed: Iterable<string>): AffectedNode[];
+/**
+ * Debt ids present in the model at `baseRef`, for the baseline-only-decreases
+ * check's "before" snapshot. `modelRelDir` is the model directory relative to
+ * `gitRoot`. Uses a SINGLE `git grep` over the base tree (not one `git show`
+ * per model file) so it stays fast on a large model.
+ *
+ * Returns undefined only when the base snapshot is genuinely unreadable (bad
+ * ref / not a git repo); an empty set (no debt at base) is a real result, not a
+ * skip. Note: the id scrape is a text match — only DebtEntry nodes can carry a
+ * `DEBT-` id (the schema's id regexes forbid it elsewhere), and a stray match
+ * in a comment/string could at worst add a spurious "before" id, which only
+ * *suppresses* a growth violation, never invents one (checkBaselineOnlyDecreases
+ * flags after-not-before).
+ */
+export declare function debtIdsAtRef(gitRoot: string, modelRelDir: string, baseRef: string): Promise<Set<string> | undefined>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/query/diff.js

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { allNodes } from "../loader/model-graph.js";
+import { anchorFilePath } from "../validate/anchor.js";
+const execFileAsync = promisify(execFile);
+/**
+ * `--diff` incremental support (Proposal 006 B2 / 001 §5 §6): resolve what a PR
+ * changed so a check re-runs only over the diff closure instead of the whole
+ * repo, and map the changed files back to the model nodes they touch.
+ */
+/**
+ * Repo-relative paths changed between `merge-base(baseRef, HEAD)` and the
+ * working tree (committed + uncommitted), via git. Uses the merge-base (not a
+ * raw `baseRef..HEAD`) so a stale base branch doesn't inflate the diff with
+ * commits already on HEAD. Returns undefined when the ref/repo is unusable —
+ * the caller falls back to a full scan rather than silently checking nothing.
+ */
+export async function changedFiles(gitRoot, baseRef) {
+    try {
+        const { stdout: mb } = await execFileAsync("git", ["merge-base", baseRef, "HEAD"], {
+            cwd: gitRoot,
+        });
+        const base = mb.trim();
+        // `git diff --name-only <base>` compares base..working-tree (includes
+        // uncommitted edits), which is what a pre-push / local check wants.
+        const { stdout } = await execFileAsync("git", ["diff", "--name-only", base], {
+            cwd: gitRoot,
+            maxBuffer: 32 * 1024 * 1024,
+        });
+        return stdout
+            .split("\n")
+            .map((l) => l.trim().replace(/^"(.*)"$/, "$1"))
+            .filter(Boolean);
+    }
+    catch {
+        return undefined; // bad ref / not a git repo / no merge-base
+    }
+}
+/** The git top-level of `dir`, or undefined if `dir` isn't inside a git checkout. */
+export async function gitRootOf(dir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Model nodes whose anchor points at one of `changedFiles` — the diff's impact
+ * surface on the model. Pure. A loop/junction/scenario is "affected" when a
+ * file it anchors to (Loop.anchors, Junction.evidence[].anchor,
+ * Scenario.verified_by[]) changed, so a reviewer sees which modeled behaviors a
+ * diff might have moved out from under.
+ */
+export function affectedNodes(graph, changed) {
+    // Normalize both sides to forward slashes: git emits POSIX paths and anchors
+    // are authored with `/`, but normalizing guards any backslash that slips in.
+    const posix = (p) => p.replace(/\\/g, "/");
+    const changedSet = new Set([...changed].map(posix));
+    const out = [];
+    const consider = (nodeId, kind, anchor) => {
+        const file = anchorFilePath(anchor);
+        if (file && changedSet.has(posix(file)))
+            out.push({ nodeId, kind, anchor, file });
+    };
+    for (const node of allNodes(graph)) {
+        if (node.kind === "loop") {
+            for (const a of node.anchors)
+                consider(node.id, "loop", a);
+        }
+        else if (node.kind === "junction") {
+            for (const e of node.evidence)
+                consider(node.id, "junction", e.anchor);
+        }
+        else if (node.kind === "scenario") {
+            for (const a of node.verified_by)
+                consider(node.id, "scenario", a);
+        }
+    }
+    return out;
+}
+/**
+ * Debt ids present in the model at `baseRef`, for the baseline-only-decreases
+ * check's "before" snapshot. `modelRelDir` is the model directory relative to
+ * `gitRoot`. Uses a SINGLE `git grep` over the base tree (not one `git show`
+ * per model file) so it stays fast on a large model.
+ *
+ * Returns undefined only when the base snapshot is genuinely unreadable (bad
+ * ref / not a git repo); an empty set (no debt at base) is a real result, not a
+ * skip. Note: the id scrape is a text match — only DebtEntry nodes can carry a
+ * `DEBT-` id (the schema's id regexes forbid it elsewhere), and a stray match
+ * in a comment/string could at worst add a spurious "before" id, which only
+ * *suppresses* a growth violation, never invents one (checkBaselineOnlyDecreases
+ * flags after-not-before).
+ */
+export async function debtIdsAtRef(gitRoot, modelRelDir, baseRef) {
+    let base;
+    try {
+        base = (await execFileAsync("git", ["merge-base", baseRef, "HEAD"], { cwd: gitRoot })).stdout.trim();
+    }
+    catch {
+        return undefined; // bad ref / not a git repo
+    }
+    let stdout;
+    try {
+        // POSIX ERE (git grep -E) — `[[:space:]]`, not `\s` (that's PCRE). A pathspec
+        // is only appended when non-empty (modelRelDir is always `.../model` in
+        // practice, but an empty/`.` pathspec after `--` would be ambiguous).
+        const pattern = 'id:[[:space:]]*"?DEBT-[A-Za-z0-9-]+';
+        const args = modelRelDir && modelRelDir !== "."
+            ? ["grep", "-hE", pattern, base, "--", modelRelDir]
+            : ["grep", "-hE", pattern, base];
+        ({ stdout } = await execFileAsync("git", args, { cwd: gitRoot, maxBuffer: 32 * 1024 * 1024 }));
+    }
+    catch (err) {
+        // git grep exits 1 when there are simply no matches — that's an empty debt
+        // baseline (a real result), not a failure.
+        if (err.code === 1)
+            return new Set();
+        return undefined;
+    }
+    const ids = new Set();
+    for (const m of stdout.matchAll(/id:\s*"?(DEBT-[A-Za-z0-9-]+)"?/g)) {
+        if (m[1])
+            ids.add(m[1]);
+    }
+    return ids;
+}
+//# sourceMappingURL=diff.js.map

package/dist/query/effective-constraints.d.ts

@@ -0,0 +1,48 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+import type { Scenario } from "../schema/index.js";
+/**
+ * `owner_match` matching semantics (Decision record 004, 技术点 2):
+ * `Loop.owner` is free text, not a clean path (e.g. an owner might read
+ * `"canonical writer = packages/core service; ui layer read-only"` — the
+ * package path is not a prefix). A pattern with no `*` is a
+ * substring-containment check anywhere in `owner`. A pattern with `*`
+ * treats it as "any-length any-characters" (like a simplified `.*`),
+ * useful for asserting two fragments appear in a given order — e.g.
+ * `"packages/core*apps/worker"`. This is deliberately NOT full POSIX glob
+ * (no `**`, no character classes) — `owner` is a short free-text field,
+ * not a file path, and doesn't need that vocabulary. Case-sensitive,
+ * matching `owner`'s own casing.
+ *
+ * The `*`-pattern match is deliberately UNANCHORED (no `^`/`$`), for the
+ * same reason the no-`*` case is substring-anywhere and not a full-string
+ * equality check: real `owner` values carry surrounding decoration, so
+ * "these two fragments appear in this order" needs to tolerate a
+ * prefix/suffix around the whole match, not just between the two
+ * fragments. Anchoring would make `*`-patterns behave inconsistently
+ * stricter than plain-substring patterns for no benefit — `owner` isn't
+ * adversarial input, it's short static text authored by whoever wrote
+ * the model.
+ */
+export declare function ownerMatches(owner: string, pattern: string): boolean;
+/**
+ * Whether `scenario` applies to `nodeId`, per its `applies_to` selector.
+ * Predicates combine with OR (matching either is sufficient). `nodes`
+ * works against any of the 6 node kinds by exact id; `owner_match` only
+ * ever matches Loop nodes (other kinds have no `owner` field) and never
+ * matches a dormant loop (`owner: null`).
+ */
+export declare function scenarioApplies(scenario: Scenario, nodeId: string, graph: ModelGraph): boolean;
+/**
+ * Every Scenario that applies to `nodeId`, resolved at query time —
+ * never materialized back onto the node (Decision record 004: writing
+ * this back to every matching node's `scenarios` array on every new
+ * Invariant would create merge conflicts across the user's many git
+ * worktrees, for no correctness benefit at this model's node count).
+ */
+export declare function resolveApplicableScenarios(graph: ModelGraph, nodeId: string): Scenario[];
+/** Every (scenario, nodeId) pair where a Scenario's `applies_to` names a node that doesn't exist in the graph. */
+export declare function collectDanglingAppliesTo(graph: ModelGraph): {
+    scenarioId: string;
+    targetId: string;
+}[];
+//# sourceMappingURL=effective-constraints.d.ts.map

package/dist/query/effective-constraints.js

@@ -0,0 +1,81 @@
+import { allNodes } from "../loader/model-graph.js";
+/**
+ * `owner_match` matching semantics (Decision record 004, 技术点 2):
+ * `Loop.owner` is free text, not a clean path (e.g. an owner might read
+ * `"canonical writer = packages/core service; ui layer read-only"` — the
+ * package path is not a prefix). A pattern with no `*` is a
+ * substring-containment check anywhere in `owner`. A pattern with `*`
+ * treats it as "any-length any-characters" (like a simplified `.*`),
+ * useful for asserting two fragments appear in a given order — e.g.
+ * `"packages/core*apps/worker"`. This is deliberately NOT full POSIX glob
+ * (no `**`, no character classes) — `owner` is a short free-text field,
+ * not a file path, and doesn't need that vocabulary. Case-sensitive,
+ * matching `owner`'s own casing.
+ *
+ * The `*`-pattern match is deliberately UNANCHORED (no `^`/`$`), for the
+ * same reason the no-`*` case is substring-anywhere and not a full-string
+ * equality check: real `owner` values carry surrounding decoration, so
+ * "these two fragments appear in this order" needs to tolerate a
+ * prefix/suffix around the whole match, not just between the two
+ * fragments. Anchoring would make `*`-patterns behave inconsistently
+ * stricter than plain-substring patterns for no benefit — `owner` isn't
+ * adversarial input, it's short static text authored by whoever wrote
+ * the model.
+ */
+export function ownerMatches(owner, pattern) {
+    if (!pattern.includes("*"))
+        return owner.includes(pattern);
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(escaped).test(owner);
+}
+/**
+ * Whether `scenario` applies to `nodeId`, per its `applies_to` selector.
+ * Predicates combine with OR (matching either is sufficient). `nodes`
+ * works against any of the 6 node kinds by exact id; `owner_match` only
+ * ever matches Loop nodes (other kinds have no `owner` field) and never
+ * matches a dormant loop (`owner: null`).
+ */
+export function scenarioApplies(scenario, nodeId, graph) {
+    const appliesTo = scenario.applies_to;
+    if (!appliesTo)
+        return false;
+    if (appliesTo.nodes.includes(nodeId))
+        return true;
+    if (appliesTo.owner_match !== undefined) {
+        const loop = graph.byKind.loop.get(nodeId);
+        if (loop && loop.owner !== null && ownerMatches(loop.owner, appliesTo.owner_match)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Every Scenario that applies to `nodeId`, resolved at query time —
+ * never materialized back onto the node (Decision record 004: writing
+ * this back to every matching node's `scenarios` array on every new
+ * Invariant would create merge conflicts across the user's many git
+ * worktrees, for no correctness benefit at this model's node count).
+ */
+export function resolveApplicableScenarios(graph, nodeId) {
+    return [...graph.byKind.scenario.values()].filter((scenario) => scenarioApplies(scenario, nodeId, graph));
+}
+/** Every (scenario, nodeId) pair where a Scenario's `applies_to` names a node that doesn't exist in the graph. */
+export function collectDanglingAppliesTo(graph) {
+    const out = [];
+    for (const node of allNodes(graph)) {
+        if (node.kind !== "scenario" || !node.applies_to)
+            continue;
+        for (const targetId of node.applies_to.nodes) {
+            const exists = graph.byKind.feature.has(targetId) ||
+                graph.byKind.flow.has(targetId) ||
+                graph.byKind.loop.has(targetId) ||
+                graph.byKind.junction.has(targetId) ||
+                graph.byKind.scenario.has(targetId) ||
+                graph.byKind.debt.has(targetId);
+            if (!exists)
+                out.push({ scenarioId: node.id, targetId });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=effective-constraints.js.map

package/dist/query/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./effective-constraints.js";
+export * from "./queries.js";
+export * from "./run-query.js";
+export * from "./side-channel.js";
+export * from "./slice.js";
+export * from "./summary.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/query/index.js

@@ -0,0 +1,7 @@
+export * from "./effective-constraints.js";
+export * from "./queries.js";
+export * from "./run-query.js";
+export * from "./side-channel.js";
+export * from "./slice.js";
+export * from "./summary.js";
+//# sourceMappingURL=index.js.map