loopgraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loopgraph contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# loopgraph
+
+模型驱动工程控制系统(Model-Driven Engineering Control)——把"系统应该怎么运转"写成机器可校验的行为模型,钉在真实代码上,每次 PR 秒级对账,防止实现与认知漂移。
+
+## 核心思路
+
+以结构化行为模型(Feature / Flow / Loop / Junction / Scenario(GWT) / Evidence)为规范事实源,把目标仓库的代码、测试与可观测信号当作投影与证据:
+
+- **确定性增量 CI(永不调 LLM)**:T0 检查(schema / 引用完整性 / 图无环 / 锚点存在性)、canonical-writer 不变量扫描(纯 AST)、实现事实对账、`--diff` 增量、内容寻址共享缓存(跨 worktree)。全量亚秒级。
+- **发现靠 LLM,防腐靠引擎**:随附 agent 提示词套件(四遍扫描:假设都是 loop → 三判据证伪 → 组合 → trace 升维),由 coding agent 离线建模;引擎负责锚点核实与漂移拦截。
+- **MCP 查询 + file side-channel**:给 agent 提供任务相关的模型切片(impact / plan / scenario / evidence / matrix),替代全量阅读 spec。
+
+## 快速开始
+
+```bash
+npx loopgraph init          # 在目标仓库生成 model/ 骨架 + .loopgraph/agent/ 指令套件
+npx loopgraph check . --repo-root . --strict-anchors   # T0 门禁(确定性,秒级)
+npx loopgraph reconcile . --repo-root .                # 实现信号 vs 模型登记对账(advisory)
+npx loopgraph snapshot . --repo-root .                 # nightly 全量快照 + 漂移报告(永不进门禁)
+npx loopgraph impact <loop-id> .                       # 改这里会牵动什么
+npx loopgraph mcp .                                    # stdio MCP server(给 agent 用)
+```
+
+`init` 产出的 `.loopgraph/agent/` 含三个指令文件,由你仓库里的 coding agent 执行:发现建模(`loop-discovery.md`)、给 PR 模板加 Loop 声明栏、按本仓库 CI 约定编写 advisory / nightly 两个 workflow(均不阻塞 PR)。
+
+## 模型长什么样
+
+```yaml
+# model/loops/*.yaml — 一个后台控制循环(示例为虚构系统)
+- id: L1
+  kind: loop
+  title: Order 状态机
+  boundary: "pending→processing→shipped/cancelled;cancelled 为终态"
+  owner: packages/orders
+  anchors: ["packages/orders/src/order-service.ts#OrderService"]  # 钉在真实代码符号上
+  consumes_queues: ["order:process"]                              # 按名对账生产/消费分离
+  scenarios: [GWT-A1-001]                                         # GWT 场景,verified_by 指向真实测试
+```
+
+junction(跨循环风险点)、flow(端到端链路)、debt(死状态机基线,只减不增)同理——全部 YAML,file-per-node,`loopgraph check` 机器校验。
+
+## 设计红线
+
+- 门禁检查**零 LLM、零网络、零代码执行**——快、便宜、可复现、可解释。
+- 缓存零正确性依赖(cold == warm 逐字节一致)。
+- 快照/漂移报告(T2)永不进 PR 门禁。
+- 模型新增须过锚点核实;发现层(LLM)只产草案,落库须经维护者核实。
+
+## License
+
+见 package.json。

package/dist/adapters/agenthub/extract.d.ts

@@ -0,0 +1,63 @@
+/**
+ * AgentHub adapter — implementation-fact extraction (Proposal 006 B1 / 001 §2
+ * 三分离's "适配器" pillar). PURE functions of `(filePath, content)` — an
+ * in-memory `ts.createSourceFile` parse, no I/O — so the results are cacheable
+ * on the same `hash(adapter_version, blob_oid)` terms as A6's INV-1 scan.
+ *
+ * These surface the "registerable" implementation units (pg-boss queues,
+ * setInterval pollers) that the behavioral model is supposed to account for.
+ * Listing them is the `extract` stage of the pipeline (001 §3); comparing them
+ * against the model to flag UNREGISTERED units is a T1 check (Milestone C, out
+ * of B1's scope) — this layer only produces the facts.
+ *
+ * Scope note (B1 subset): two of the six planned signals are implemented here
+ * (pg-boss queue, setInterval poller — the clearest background-loop signals).
+ * The Next.js route / drizzle status-column / vitest-E2E / metric-event
+ * extractors are deferred; each is an independent pure extractor that slots in
+ * beside these (the file domain is non-overlapping, per 006 B1).
+ */
+/**
+ * Bumped whenever an extractor's LOGIC changes — it's part of the B3 cache key,
+ * so a bump invalidates every stale cached result at once (a file whose bytes
+ * didn't change still needs re-extraction if the extractor did).
+ */
+export declare const ADAPTER_VERSION = "agenthub-facts-1";
+export type SignalKind = "pg_boss_queue" | "setinterval_poller";
+export interface ImplementationFact {
+    signal: SignalKind;
+    /** The queue name, or the poller's enclosing function/file marker. */
+    name: string;
+    filePath: string;
+    /** 1-based line for a human reading the report — not a stable anchor. */
+    line: number;
+    /** Extra context: e.g. "env-suffixed" for a QUEUE_SUFFIX template, or the interval. */
+    detail?: string;
+    /** true when the fact's key part (queue name / interval) couldn't be read statically. */
+    unanalyzable?: boolean;
+}
+/**
+ * pg-boss queue names. In this target stack the authoritative names live in
+ * `const *_QUEUE = <string | template>` declarations (e.g.
+ * `` FOO_QUEUE = `foo:process${QUEUE_SUFFIX}` ``), referenced by identifier at
+ * the `boss.send(FOO_QUEUE, ...)` call sites — a literal AT the call site is the
+ * exception (and is often just a JSDoc-diagram string, which the AST parse
+ * ignores). So the primary signal is the const declaration; the `*QUEUE*`
+ * naming convention is adapter knowledge, which is exactly what an adapter is
+ * allowed to encode. Direct string-literal `.work/.send/.schedule` call sites
+ * are also captured. Deduped by queue name.
+ */
+export declare function extractQueues(filePath: string, content: string): ImplementationFact[];
+/**
+ * setInterval poller registrations: each `setInterval(fn, <interval>)` call
+ * site, whether called bare (`setInterval(...)`) or off an object
+ * (`globalThis.setInterval(...)`, `window.setInterval(...)`). The interval, if a
+ * numeric literal, is reported as detail; a variable/expression interval is
+ * marked unanalyzable (the poller exists either way — the cadence just isn't
+ * statically known). Residual: an aliased import (`import { setInterval as poll
+ * }` called as `poll(...)`) is not caught (needs import tracking) — a documented
+ * limitation; this target uses the bare Node global.
+ */
+export declare function extractPollers(filePath: string, content: string): ImplementationFact[];
+/** Runs every implemented extractor over one file. */
+export declare function extractFacts(filePath: string, content: string): ImplementationFact[];
+//# sourceMappingURL=extract.d.ts.map

package/dist/adapters/agenthub/extract.js

@@ -0,0 +1,144 @@
+import ts from "typescript";
+/**
+ * AgentHub adapter — implementation-fact extraction (Proposal 006 B1 / 001 §2
+ * 三分离's "适配器" pillar). PURE functions of `(filePath, content)` — an
+ * in-memory `ts.createSourceFile` parse, no I/O — so the results are cacheable
+ * on the same `hash(adapter_version, blob_oid)` terms as A6's INV-1 scan.
+ *
+ * These surface the "registerable" implementation units (pg-boss queues,
+ * setInterval pollers) that the behavioral model is supposed to account for.
+ * Listing them is the `extract` stage of the pipeline (001 §3); comparing them
+ * against the model to flag UNREGISTERED units is a T1 check (Milestone C, out
+ * of B1's scope) — this layer only produces the facts.
+ *
+ * Scope note (B1 subset): two of the six planned signals are implemented here
+ * (pg-boss queue, setInterval poller — the clearest background-loop signals).
+ * The Next.js route / drizzle status-column / vitest-E2E / metric-event
+ * extractors are deferred; each is an independent pure extractor that slots in
+ * beside these (the file domain is non-overlapping, per 006 B1).
+ */
+/**
+ * Bumped whenever an extractor's LOGIC changes — it's part of the B3 cache key,
+ * so a bump invalidates every stale cached result at once (a file whose bytes
+ * didn't change still needs re-extraction if the extractor did).
+ */
+export const ADAPTER_VERSION = "agenthub-facts-1";
+function lineOf(src, node) {
+    return src.getLineAndCharacterOfPosition(node.getStart(src)).line + 1;
+}
+/** The static queue name of a string/template expression, or null if not statically known. */
+function queueNameOf(expr) {
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))
+        return { name: expr.text };
+    if (ts.isTemplateExpression(expr)) {
+        // Join every STATIC part (head + each span's trailing literal) with "…" for
+        // the dynamic `${}` gaps: `foo:process${SUFFIX}` → "foo:process";
+        // `${PREFIX}foo:process` → "foo:process"; `${A}${B}` → "" (fully dynamic).
+        const staticParts = [expr.head.text, ...expr.templateSpans.map((s) => s.literal.text)].filter(Boolean);
+        if (staticParts.length === 0)
+            return { name: "<dynamic>", detail: "env-templated" };
+        return { name: staticParts.join("…"), detail: "env-templated" };
+    }
+    return null;
+}
+/**
+ * pg-boss queue names. In this target stack the authoritative names live in
+ * `const *_QUEUE = <string | template>` declarations (e.g.
+ * `` FOO_QUEUE = `foo:process${QUEUE_SUFFIX}` ``), referenced by identifier at
+ * the `boss.send(FOO_QUEUE, ...)` call sites — a literal AT the call site is the
+ * exception (and is often just a JSDoc-diagram string, which the AST parse
+ * ignores). So the primary signal is the const declaration; the `*QUEUE*`
+ * naming convention is adapter knowledge, which is exactly what an adapter is
+ * allowed to encode. Direct string-literal `.work/.send/.schedule` call sites
+ * are also captured. Deduped by queue name.
+ */
+export function extractQueues(filePath, content) {
+    const src = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const facts = [];
+    const seen = new Set();
+    const QUEUE_METHODS = new Set(["work", "send", "schedule"]);
+    const push = (name, node, detail) => {
+        if (seen.has(name))
+            return; // one fact per distinct queue name
+        seen.add(name);
+        facts.push({
+            signal: "pg_boss_queue",
+            name,
+            filePath,
+            line: lineOf(src, node),
+            ...(detail ? { detail } : {}),
+        });
+    };
+    function visit(node) {
+        // `const *QUEUE* = <string | template>` — the authoritative queue-name decl.
+        // The target's convention is SCREAMING_SNAKE with QUEUE as a token, mid-name
+        // or suffix (e.g. FOO_QUEUE, BAR_QUEUE_WEB, BAZ_QUEUE_BASE), so match a
+        // CASE-SENSITIVE uppercase "QUEUE": that catches every real one while
+        // excluding the camelCase/lowercase false-matches (`queueLength`,
+        // `myQueueHandler`). Direct literal call sites below catch anything not
+        // declared via this convention.
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text.includes("QUEUE") &&
+            node.initializer) {
+            const q = queueNameOf(node.initializer);
+            if (q)
+                push(q.name, node, q.detail);
+        }
+        // Direct string-literal `.work/.send/.schedule("queue", ...)` registrations.
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            QUEUE_METHODS.has(node.expression.name.text)) {
+            const arg0 = node.arguments[0];
+            const q = arg0 ? queueNameOf(arg0) : null;
+            if (q)
+                push(q.name, node, q.detail);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(src);
+    return facts;
+}
+/**
+ * setInterval poller registrations: each `setInterval(fn, <interval>)` call
+ * site, whether called bare (`setInterval(...)`) or off an object
+ * (`globalThis.setInterval(...)`, `window.setInterval(...)`). The interval, if a
+ * numeric literal, is reported as detail; a variable/expression interval is
+ * marked unanalyzable (the poller exists either way — the cadence just isn't
+ * statically known). Residual: an aliased import (`import { setInterval as poll
+ * }` called as `poll(...)`) is not caught (needs import tracking) — a documented
+ * limitation; this target uses the bare Node global.
+ */
+export function extractPollers(filePath, content) {
+    const src = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const facts = [];
+    const isSetInterval = (expr) => (ts.isIdentifier(expr) && expr.text === "setInterval") ||
+        (ts.isPropertyAccessExpression(expr) && expr.name.text === "setInterval") ||
+        // globalThis["setInterval"](...) — element access with a string key
+        (ts.isElementAccessExpression(expr) &&
+            ts.isStringLiteral(expr.argumentExpression) &&
+            expr.argumentExpression.text === "setInterval");
+    function visit(node) {
+        if (ts.isCallExpression(node) && isSetInterval(node.expression)) {
+            const intervalArg = node.arguments[1];
+            const literalMs = intervalArg && ts.isNumericLiteral(intervalArg) ? intervalArg.text : undefined;
+            facts.push({
+                signal: "setinterval_poller",
+                name: `setInterval@${filePath}:${lineOf(src, node)}`,
+                filePath,
+                line: lineOf(src, node),
+                ...(literalMs
+                    ? { detail: `${literalMs}ms` }
+                    : { detail: "dynamic interval", unanalyzable: true }),
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(src);
+    return facts;
+}
+/** Runs every implemented extractor over one file. */
+export function extractFacts(filePath, content) {
+    return [...extractQueues(filePath, content), ...extractPollers(filePath, content)];
+}
+//# sourceMappingURL=extract.js.map

package/dist/adapters/agenthub/facts.d.ts

@@ -0,0 +1,27 @@
+import type { Adapter } from "../types.js";
+import type { ImplementationFact } from "./extract.js";
+export interface FactsOptions {
+    /**
+     * Machine-level content cache dir (B3). Defaults to `~/.cache/loopgraph`;
+     * pass `null` to disable (the zero-cache-dependency path CI can take).
+     */
+    cacheDir?: string | null;
+    /** The adapter supplying the candidate pattern + extractors (E1). Default: agenthub. */
+    adapter?: Adapter;
+}
+export interface FactsResult {
+    /** false when the scan couldn't run (no git checkout) — a loud skip, not a silent empty result. */
+    ran: boolean;
+    skippedReason?: string;
+    facts: ImplementationFact[];
+    candidateFiles: number;
+    filesScanned: number;
+    timingMs: number;
+}
+/**
+ * Extracts implementation facts from the target repo via the chosen adapter
+ * (E1: the runner is engine-generic; agenthub is the default adapter). Same
+ * git-grep-then-pure-AST posture as A6's INV-1 scan.
+ */
+export declare function runFacts(repoRoot: string, options?: FactsOptions): Promise<FactsResult>;
+//# sourceMappingURL=facts.d.ts.map

package/dist/adapters/agenthub/facts.js

@@ -0,0 +1,89 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { cacheKey, contentHash, defaultCacheDir, pruneCache, withCache, } from "../../cache/content-cache.js";
+import { getAdapter } from "../registry.js";
+const execFileAsync = promisify(execFile);
+/** LRU cap for the machine-level cache (001 §5). */
+const CACHE_MAX_ENTRIES = 50_000;
+/**
+ * Candidate pre-filter for the fact extractors (same posture as A6's INV-1
+ * scan): `git grep -l` narrows to files that mention a pg-boss method or
+ * setInterval, then the pure AST extractors confirm. Over-matching only costs a
+ * cheap extra parse; under-matching would be a silent miss, so the pattern is
+ * broad. Returns undefined when the target is not a usable git checkout.
+ */
+async function gitGrepCandidates(repoRoot, pattern) {
+    try {
+        const { stdout } = await execFileAsync("git", ["grep", "-lE", pattern, "--", "*.ts", ":!*.test.ts", ":!*.spec.ts"], { cwd: repoRoot, maxBuffer: 64 * 1024 * 1024 });
+        return (stdout
+            .split("\n")
+            // strip git's optional surrounding quotes on paths with special chars
+            .map((l) => l.trim().replace(/^"(.*)"$/, "$1"))
+            .filter(Boolean)
+            // Belt-and-suspenders over the git pathspec exclude: also drop test/spec
+            // files at the Node layer, so the result is right regardless of git
+            // version / pathspec behavior.
+            .filter((f) => !/\.(test|spec)\.ts$/.test(f)));
+    }
+    catch (err) {
+        if (err.code === 1)
+            return []; // no matches
+        return undefined; // not a git repo / no git
+    }
+}
+/**
+ * Extracts implementation facts from the target repo via the chosen adapter
+ * (E1: the runner is engine-generic; agenthub is the default adapter). Same
+ * git-grep-then-pure-AST posture as A6's INV-1 scan.
+ */
+export async function runFacts(repoRoot, options = {}) {
+    const start = performance.now();
+    // `null` disables; `undefined` (default) uses the machine cache dir.
+    const cacheDir = options.cacheDir === null ? undefined : (options.cacheDir ?? defaultCacheDir());
+    // getAdapter("agenthub") is registered, so the `!` fallback is unreachable — guard, not assertion.
+    const adapter = options.adapter ?? getAdapter("agenthub");
+    if (!adapter)
+        throw new Error("no adapter available (agenthub not registered)");
+    const candidates = await gitGrepCandidates(repoRoot, adapter.candidatePattern);
+    if (candidates === undefined) {
+        return {
+            ran: false,
+            skippedReason: "fact extraction needs a git checkout (git grep unavailable at repo-root)",
+            facts: [],
+            candidateFiles: 0,
+            filesScanned: 0,
+            timingMs: performance.now() - start,
+        };
+    }
+    const facts = [];
+    let filesScanned = 0;
+    for (const rel of candidates) {
+        const content = await readFile(join(repoRoot, rel), "utf8").catch(() => undefined);
+        if (content === undefined)
+            continue;
+        filesScanned++;
+        // Key by (adapter version, repo-relative path, content hash): `rel` is the
+        // same in every worktree of the repo, so identical content shares one entry
+        // cross-worktree; the path is still part of the key so two files with the
+        // same bytes at different paths don't collide.
+        const key = cacheKey([adapter.version, rel, contentHash(content)]);
+        const fileFacts = await withCache(cacheDir, key, () => adapter.extractFacts(rel, content));
+        facts.push(...fileFacts);
+    }
+    if (cacheDir)
+        await pruneCache(cacheDir, CACHE_MAX_ENTRIES);
+    // stable order: signal, then name, then path
+    facts.sort((a, b) => a.signal.localeCompare(b.signal) ||
+        a.name.localeCompare(b.name) ||
+        a.filePath.localeCompare(b.filePath));
+    return {
+        ran: true,
+        facts,
+        candidateFiles: candidates.length,
+        filesScanned,
+        timingMs: performance.now() - start,
+    };
+}
+//# sourceMappingURL=facts.js.map

package/dist/adapters/agenthub/index.d.ts

@@ -0,0 +1,13 @@
+import type { Adapter } from "../types.js";
+/**
+ * The agenthub adapter behind the engine's Adapter interface (E1). All
+ * target-stack knowledge lives here; the engine (runner, cache, INV-1
+ * primitive) stays generic.
+ *
+ * Deliberately ships NO defaultInv1Config: the INV-1 guarded-table config
+ * (table names, writer allowlists) is target-repo knowledge and lives in the
+ * target's own loopgraph.config.json — embedding it here would compile
+ * target internals into the published package.
+ */
+export declare const agenthubAdapter: Adapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/agenthub/index.js

@@ -0,0 +1,18 @@
+import { ADAPTER_VERSION, extractFacts } from "./extract.js";
+/**
+ * The agenthub adapter behind the engine's Adapter interface (E1). All
+ * target-stack knowledge lives here; the engine (runner, cache, INV-1
+ * primitive) stays generic.
+ *
+ * Deliberately ships NO defaultInv1Config: the INV-1 guarded-table config
+ * (table names, writer allowlists) is target-repo knowledge and lives in the
+ * target's own loopgraph.config.json — embedding it here would compile
+ * target internals into the published package.
+ */
+export const agenthubAdapter = {
+    name: "agenthub",
+    version: ADAPTER_VERSION,
+    candidatePattern: "setInterval\\(|\\.(work|send|schedule)\\(",
+    extractFacts,
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/registry.d.ts

@@ -0,0 +1,4 @@
+import type { Adapter } from "./types.js";
+export declare function getAdapter(name: string): Adapter | undefined;
+export declare function adapterNames(): string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/adapters/registry.js

@@ -0,0 +1,17 @@
+import { agenthubAdapter } from "./agenthub/index.js";
+/**
+ * The adapter registry (E1): the single place the engine resolves an adapter by
+ * name. A new target stack registers here and everything else — the fact
+ * runner, the cache key, the INV-1 default config — flows through the Adapter
+ * interface without further engine changes.
+ */
+const ADAPTERS = {
+    [agenthubAdapter.name]: agenthubAdapter,
+};
+export function getAdapter(name) {
+    return ADAPTERS[name];
+}
+export function adapterNames() {
+    return Object.keys(ADAPTERS);
+}
+//# sourceMappingURL=registry.js.map

package/dist/adapters/types.d.ts

@@ -0,0 +1,40 @@
+import type { Inv1Config } from "../validate/inv1/config.js";
+import type { ImplementationFact } from "./agenthub/extract.js";
+/**
+ * The engine↔adapter boundary (Proposal 006 E1 / 001 §2 三分离, Phase 5
+ * generalization). The ENGINE (loader, T0, INV-1 scan primitive, query, cache,
+ * `--diff`, MCP) carries zero target-repo knowledge; an ADAPTER supplies the
+ * target-stack-specific facts: how to read this codebase's implementation
+ * signals, its version (part of the cache key), and its default INV-1 config.
+ *
+ * Formalizing this as an interface is the Phase 5 "通用化" — but the 001 red
+ * line holds: generalization must not degrade AgentHub analysis quality or CI
+ * speed. The regression test (test/adapter.test.ts) enforces that: the agenthub
+ * adapter routed through this interface produces BYTE-IDENTICAL facts to the
+ * direct extractor. A second adapter would slot in beside agenthub without the
+ * engine changing.
+ */
+export interface Adapter {
+    /** Stable adapter id, used to look it up and (with `version`) to key the cache. */
+    name: string;
+    /**
+     * Bumped when extractor LOGIC changes — part of the B3 cache key so a bump
+     * invalidates stale results even when file bytes are unchanged.
+     */
+    version: string;
+    /**
+     * `git grep -E` pattern selecting candidate files worth parsing (the cheap
+     * pre-filter before the pure extractor confirms). Adapter-specific because it
+     * encodes which call shapes this stack's signals appear in.
+     */
+    candidatePattern: string;
+    /** Extract implementation facts from one source file. PURE (no I/O). */
+    extractFacts(filePath: string, content: string): ImplementationFact[];
+    /**
+     * The default INV-1 guarded-column config for this target, if the adapter
+     * ships one. A repo-level `loopgraph.config.json` still overrides it; this is
+     * the fallback so a target doesn't have to re-declare what the adapter knows.
+     */
+    defaultInv1Config?: Inv1Config;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/content-cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Machine-level content-addressed cache (Proposal 006 B3 / 001 §5) for the pure
+ * per-file extractor/scanner results (A6 INV-1 scan, B1 fact extraction).
+ *
+ * Key = sha256 over caller-supplied parts — for the fact extractor,
+ * (adapter_version, repo-relative path, content_hash). Every part is
+ * worktree-INDEPENDENT: the content hash is by definition, and the
+ * repo-relative path is the same in every worktree of the repo. So identical
+ * bytes at the same in-repo path share ONE entry across the user's many
+ * worktrees (the cross-worktree sharing 001 §5 calls for), while the path stays
+ * in the key so two files with the same bytes at DIFFERENT paths don't collide
+ * (the cached value embeds its path). Content-addressing also makes writes
+ * idempotent: a given key's value is deterministic, so a concurrent write of
+ * the same key is harmless (both write identical bytes; temp+rename just makes
+ * each atomic).
+ *
+ * Correctness has ZERO cache dependency (001 §6 red line): the value is exactly
+ * `compute()` — a cold run (empty cache) and a warm run are byte-identical, and
+ * a missing/corrupt/disabled cache just recomputes. `cacheDir: undefined`
+ * disables it entirely (the path CI can take to prove independence).
+ *
+ * Not modeled (documented deferral): the git-index fast-path for reading a
+ * clean tracked file's blob OID without re-hashing. Hashing the content
+ * directly is always correct and worktree-identical; the index lookup is only a
+ * micro-optimization, so B3 ships the always-correct content-hash path.
+ */
+export declare function defaultCacheDir(): string;
+/** sha256 of a file's content — the worktree-independent part of the cache key. */
+export declare function contentHash(content: string): string;
+/** The cache key: a hash over the ordered key parts (adapter version, content hash, config hash). */
+export declare function cacheKey(parts: string[]): string;
+/**
+ * Read-or-compute. On a hit, returns the parsed cached value; on a miss (or
+ * disabled/corrupt cache), computes, atomically writes (temp + rename), and
+ * returns. `compute` must be a PURE function of the same inputs the key was
+ * derived from — that's what makes the cache sound. `compute` may be sync or
+ * async (`await` handles both).
+ */
+export declare function withCache<T>(cacheDir: string | undefined, key: string, compute: () => T | Promise<T>): Promise<T>;
+/**
+ * Bounds the cache to `maxEntries` most-recently-modified entries (the LRU cap
+ * from 001 §5). Cheap and best-effort — called once per run, not per file — so
+ * an occasional over-count between prunes is fine.
+ */
+export declare function pruneCache(cacheDir: string, maxEntries: number): Promise<number>;
+//# sourceMappingURL=content-cache.d.ts.map