ai-foreman 1.7.20 → 1.7.21

package/dist/graph/corpus.js

@@ -0,0 +1,188 @@
+import ignore from "ignore";
+import { readWorkspaceIdentity } from "../sessionIdentity.js";
+import { WorkflowReader } from "../workflowReader.js";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { extname, join } from "node:path";
+import { loadSourceRegistry } from "../sources/sourceRegistry.js";
+import { bytesDigest, confined, digest, readBounded } from "./util.js";
+const forbidden = new Set([".git", ".rafi", ".foreman", ".tickets", "graphify-out", "node_modules", "dist", "build", "coverage", ".agents", ".codex", ".claude", "__pycache__", ".venv", "venv"]);
+const code = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs", ".java", ".c", ".h", ".cpp", ".cs", ".rb", ".swift", ".kt", ".vue", ".svelte", ".json", ".sql"]);
+const semantic = new Set([".md", ".mdx", ".txt", ".rst", ".yaml", ".yml", ".toml", ".xml"]);
+export function globMatch(path, pattern) {
+    pattern = pattern.replace(/^\//, "");
+    const directory = pattern.endsWith("/");
+    if (directory)
+        pattern = pattern.slice(0, -1);
+    let regex = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*" && pattern[i + 1] === "*") {
+            i++;
+            if (pattern[i + 1] === "/") {
+                i++;
+                regex += "(?:.*/)?";
+            }
+            else
+                regex += ".*";
+        }
+        else if (c === "*")
+            regex += "[^/]*";
+        else if (c === "?")
+            regex += "[^/]";
+        else
+            regex += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${pattern.includes("/") ? "" : "(?:.*/)?"}${regex}${directory ? "(?:/.*)?" : ""}$`).test(path);
+}
+export function graphExclusions(workspace, inputPaths = []) {
+    const path = join(workspace, ".graphifyignore");
+    const text = existsSync(path) ? readBounded(path, 128 * 1024).toString("utf8") : "";
+    const ignorePaths = new Set([".gitignore"]);
+    for (const input of inputPaths) {
+        const parts = input.split("/");
+        parts.pop();
+        for (let i = 1; i <= parts.length; i++)
+            ignorePaths.add(`${parts.slice(0, i).join("/")}/.gitignore`);
+    }
+    const gitIgnores = [...ignorePaths].sort().filter(p => existsSync(join(workspace, p))).map(p => ({ path: p, text: readBounded(confined(workspace, p), 128 * 1024).toString("utf8") }));
+    return { text: JSON.stringify({ graphify: text, gitIgnores }), patterns: text.split(/\r?\n/) };
+}
+export function graphPathAllowed(path, config, patterns) {
+    if (!path || path.startsWith("/") || path.includes("\\") || path.split("/").some(p => p === ".." || forbidden.has(p)))
+        return false;
+    const base = path.split("/").at(-1);
+    if (/^(\.env(?:\.|$)|credentials(?:\.|$)|id_(rsa|ed25519)|\.npmrc$)|\.(pem|key|p12|pfx)$/i.test(base))
+        return false;
+    if (!config.config?.include.some(p => globMatch(path, p)))
+        return false;
+    // Preserve escaping, anchored patterns, character classes and excluded-parent
+    // semantics. Trimming lines before parsing changes Git's meaning.
+    return !ignore({ ignorecase: false }).add(patterns).ignores(path)
+        && !config.config.exclude.some(p => globMatch(path, p));
+}
+export function captureGraphCorpus(workspace, configRoot, config, sourceRef = "unknown") {
+    if (!config.enabled)
+        throw new Error(`Graph is ${config.reason}`);
+    const root = realpathSync(workspace), started = Date.now();
+    let exclusions = graphExclusions(root);
+    const check = () => {
+        if (Date.now() - started > config.limits.inventoryMs)
+            throw new Error("Graph inventory deadline exceeded");
+    };
+    let paths;
+    let gitRepository = true;
+    try {
+        paths = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: root, timeout: config.limits.inventoryMs, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }).split("\0").filter(Boolean);
+    }
+    catch (error) {
+        if (!String(error.stderr ?? error).includes("not a git repository"))
+            throw error;
+        gitRepository = false;
+        paths = [];
+        const walk = (prefix, rules = []) => {
+            const ignorePath = join(root, prefix, ".gitignore");
+            if (existsSync(ignorePath))
+                rules = [...rules, { prefix, matcher: ignore({ ignorecase: false }).add(readBounded(confined(root, prefix ? `${prefix}/.gitignore` : ".gitignore"), 128 * 1024).toString("utf8")) }];
+            check();
+            for (const e of readdirSync(join(root, prefix), { withFileTypes: true })) {
+                const p = prefix ? `${prefix}/${e.name}` : e.name;
+                if (forbidden.has(e.name) || e.isSymbolicLink())
+                    continue;
+                let excluded = false;
+                for (const rule of rules) {
+                    const result = rule.matcher.test((rule.prefix ? p.slice(rule.prefix.length + 1) : p) + (e.isDirectory() ? "/" : ""));
+                    if (result.ignored)
+                        excluded = true;
+                    else if (result.unignored)
+                        excluded = false;
+                }
+                if (excluded)
+                    continue;
+                if (e.isDirectory())
+                    walk(p, rules);
+                else if (e.isFile())
+                    paths.push(p);
+                if (paths.length > config.limits.maxFiles * 4)
+                    throw new Error("Graph scope-decision-required: inventory too large");
+            }
+        };
+        walk("");
+    }
+    exclusions = graphExclusions(root, paths.filter(p => graphPathAllowed(p, config, exclusions.patterns)));
+    if (gitRepository) {
+        const ignored = spawnSync("git", ["check-ignore", "--no-index", "-z", "--stdin"], { cwd: root, input: paths.join("\0") + (paths.length ? "\0" : ""), encoding: "utf8", timeout: Math.max(1, config.limits.inventoryMs - (Date.now() - started)), maxBuffer: 16 * 1024 * 1024 });
+        if (ignored.error)
+            throw ignored.error;
+        if (ignored.status === 0) {
+            const excluded = new Set(ignored.stdout.split("\0"));
+            paths = paths.filter(p => !excluded.has(p));
+        }
+        else if (ignored.status !== 1 && !String(ignored.stderr).includes("not a git repository"))
+            throw new Error(`Git exclusion check failed: ${ignored.stderr}`);
+    }
+    const inputs = [], bytes = new Map();
+    let total = 0, words = 0;
+    const add = (path, content, mode, kind, extra = {}) => {
+        total += content.length;
+        // Incrementally count without allocating an array proportional to the input.
+        for (const _ of content.toString("utf8").matchAll(/\S+/gu)) {
+            if (++words > config.limits.maxWords)
+                throw new Error("Graph scope-decision-required: adopted word limit exceeded");
+        }
+        if (inputs.length >= config.limits.maxFiles || total > config.limits.maxInputBytes)
+            throw new Error("Graph scope-decision-required: adopted inventory limits exceeded");
+        inputs.push({ path, digest: bytesDigest(content), bytes: content.length, mode, kind, ...extra });
+        bytes.set(path, content);
+    };
+    for (const path of [...new Set(paths)].sort()) {
+        check();
+        if (!graphPathAllowed(path, config, exclusions.patterns))
+            continue;
+        const extension = extname(path).toLowerCase();
+        if (!code.has(extension) && !semantic.has(extension))
+            continue;
+        const full = join(root, path);
+        if (!existsSync(full))
+            continue; // tracked deletion
+        if (lstatSync(full).isSymbolicLink())
+            throw new Error(`Graph symlink input is unsupported: ${path}`);
+        const safe = confined(root, path), stat = lstatSync(safe);
+        if (!stat.isFile())
+            continue;
+        const content = readBounded(safe, Math.min(config.limits.maxInputBytes, 8 * 1024 * 1024));
+        if (content.includes(0))
+            continue;
+        add(path, content, stat.mode & 0o777, code.has(extension) ? "code" : "semantic");
+    }
+    const registry = loadSourceRegistry(configRoot).registry;
+    for (const id of config.config.sourceIds) {
+        check();
+        const entry = registry.entries.find(e => e.id === id);
+        if (!entry || !entry.active)
+            throw new Error(`Registered graph source is absent or revoked: ${id}`);
+        const pin = config.config.sourceVersions?.[id];
+        const version = pin ? entry.versions.find(v => v.fingerprint === pin) : undefined;
+        if (!version)
+            throw new Error(`Registered graph source has no captured version: ${id}`);
+        const content = readBounded(confined(configRoot, version.snapshot_path), 8 * 1024 * 1024);
+        if (bytesDigest(content) !== version.fingerprint)
+            throw new Error(`Registered graph source capture checksum mismatch: ${id}@${version.fingerprint}`);
+        const key = `registered-sources/${digest("source-key", id)}.md`;
+        add(key, content, 0o444, "semantic", { sourceId: id, sourceVersion: version.fingerprint, provenance: { classification: "registered-reference", authority: "reference-only; approval not inferred", label: entry.label, sourceType: entry.type, capturedAt: version.captured_at } });
+    }
+    inputs.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const exclusionsDigest = digest("exclusions", graphExclusions(root, inputs.filter(i => !i.sourceId).map(i => i.path)).text);
+    const corpusDigest = digest("corpus", { inputs, policy: config.policyDigest, exclusionsDigest, package: "0.9.82", bridge: 1 });
+    const stat = lstatSync(root);
+    const identityReader = new WorkflowReader(configRoot);
+    let hostProjectRef;
+    try {
+        hostProjectRef = identityReader.graphHostProjectIdentity();
+    }
+    finally {
+        identityReader.close();
+    }
+    const binding = { version: 1, projectRef: config.projectRef, hostProjectRef, hostWorkspaceRef: readWorkspaceIdentity(root), workspaceRef: digest("workspace", { root, dev: stat.dev, ino: stat.ino, birthtime: stat.birthtimeMs }), sourceRef, corpusDigest, policyDigest: config.policyDigest };
+    return { inputs, bytes, corpusDigest, binding, exclusionsDigest };
+}

package/dist/graph/derived.d.ts

@@ -0,0 +1,17 @@
+import type Database from "better-sqlite3";
+export interface GraphDerivedAccess {
+    policyDigest: string;
+    workspace: string;
+    exclusionsDigest: string;
+    /** Independent canonical-project exclusion baseline for worktree evidence. */
+    projectExclusionsDigest?: string;
+    sourceVersions: Record<string, string>;
+    paths: string[];
+}
+/** Carries provenance through asynchronous provider callbacks without tainting concurrent turns. */
+export declare function withGraphDerivedAccess<T>(access: GraphDerivedAccess | GraphDerivedAccess[] | undefined, action: () => T): T;
+export declare function currentGraphDerivedAccess(): GraphDerivedAccess | GraphDerivedAccess[] | undefined;
+/** Expand an owning operation's provenance as it consumes retained evidence. */
+export declare function inheritGraphDerivedAccess(access: GraphDerivedAccess[]): void;
+export declare function registerGraphDerived(db: Database.Database, bytes: string | Buffer, access: GraphDerivedAccess | GraphDerivedAccess[]): void;
+export declare function graphDerivedAllowed(db: Database.Database, root: string, contentDigest: string): boolean;

package/dist/graph/derived.js

@@ -0,0 +1,73 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { bytesDigest, digest, readBounded, canonical } from "./util.js";
+import { graphExclusions } from "./corpus.js";
+import { readGraphRecord } from "./storage.js";
+const deliveryAccess = new AsyncLocalStorage();
+/** Carries provenance through asynchronous provider callbacks without tainting concurrent turns. */
+export function withGraphDerivedAccess(access, action) {
+    return access ? deliveryAccess.run(access, action) : action();
+}
+export function currentGraphDerivedAccess() {
+    const access = deliveryAccess.getStore();
+    return Array.isArray(access) && access.length === 0 ? undefined : access;
+}
+/** Expand an owning operation's provenance as it consumes retained evidence. */
+export function inheritGraphDerivedAccess(access) {
+    const current = deliveryAccess.getStore();
+    if (!Array.isArray(current))
+        return;
+    for (const grant of access)
+        if (!current.some(item => canonical(item) === canonical(grant)))
+            current.push(grant);
+}
+export function registerGraphDerived(db, bytes, access) {
+    if (Array.isArray(access) && access.length === 0)
+        return;
+    db.exec("CREATE TABLE IF NOT EXISTS graph_derived_refs(digest TEXT PRIMARY KEY,access_json TEXT NOT NULL)");
+    const id = bytesDigest(bytes);
+    const previous = db.prepare("SELECT access_json FROM graph_derived_refs WHERE digest=?").get(id);
+    const parsed = previous ? JSON.parse(previous.access_json) : [];
+    const grants = Array.isArray(parsed) ? parsed : [parsed];
+    for (const item of Array.isArray(access) ? access : [access])
+        if (!grants.some(grant => canonical(grant) === canonical(item)))
+            grants.push(item);
+    db.prepare("INSERT INTO graph_derived_refs(digest,access_json) VALUES(?,?) ON CONFLICT(digest) DO UPDATE SET access_json=excluded.access_json").run(id, JSON.stringify(grants));
+}
+export function graphDerivedAllowed(db, root, contentDigest) {
+    if (!db.prepare("SELECT 1 FROM sqlite_master WHERE name='graph_derived_refs'").get())
+        return true;
+    const row = db.prepare("SELECT access_json FROM graph_derived_refs WHERE digest=?").get(contentDigest);
+    if (!row)
+        return true;
+    try {
+        const decoded = JSON.parse(row.access_json);
+        if (decoded?.transferWithheld === true)
+            return false;
+        const parsed = decoded;
+        const grants = Array.isArray(parsed) ? parsed : [parsed];
+        return grants.length > 0 && grants.every(access => {
+            const path = ["rafi-config.yaml", "project.yaml"].map(p => join(root, p)).find(existsSync);
+            const raw = path ? parse(readBounded(path, 4 * 1024 * 1024).toString("utf8")) : undefined;
+            const adoption = readGraphRecord(db, "adoption", "project")?.value;
+            const config = raw?.graph ?? adoption?.config;
+            if (!config?.enabled || !adoption || adoption.projectRef !== digest("project", realpathSync(root)) || digest("policy", config) !== access.policyDigest || adoption.policyDigest !== access.policyDigest)
+                return false;
+            if (!existsSync(access.workspace))
+                return false;
+            if (digest("exclusions", graphExclusions(access.workspace, access.paths).text) !== access.exclusionsDigest)
+                return false;
+            if (access.projectExclusionsDigest && digest("exclusions", graphExclusions(root, access.paths).text) !== access.projectExclusionsDigest)
+                return false;
+            for (const [id, version] of Object.entries(access.sourceVersions))
+                if (!raw?.sources?.entries?.some((e) => e.id === id && e.active && e.versions.some(v => v.fingerprint === version)))
+                    return false;
+            return true;
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist/graph/host.d.ts

@@ -0,0 +1,4 @@
+import type { BuilderAdapter, BuilderAdapterOptions } from "../adapters/types.js";
+import type { GraphSemanticHost } from "./maintenance.js";
+/** Fresh packet-only worker, using the selected host's exact runtime settings. */
+export declare function graphSemanticHost(root: string, host: BuilderAdapter, createWorker?: (options: BuilderAdapterOptions) => Promise<BuilderAdapter>): GraphSemanticHost | undefined;

package/dist/graph/host.js

@@ -0,0 +1,160 @@
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { ClaudeAdapter } from "../adapters/claude.js";
+import { CodexAdapter } from "../adapters/codex.js";
+import { WorkflowDb } from "../workflowDb.js";
+import { parseSemanticResult, semanticExchange, SEMANTIC_INSTRUCTIONS } from "./semantic.js";
+import { canonical, confined, digest, bytesDigest } from "./util.js";
+/** Fresh packet-only worker, using the selected host's exact runtime settings. */
+export function graphSemanticHost(root, host, createWorker = async (options) => host.agent === "codex" ? new CodexAdapter(options) : ClaudeAdapter.create(options)) {
+    const settings = host.graphRuntimeSettings?.();
+    if (!settings)
+        return undefined;
+    return async (chunks, operationId, budget) => {
+        const result = { nodes: [], edges: [], origin: { provider: host.agent, model: settings.model, operationId } };
+        const deadline = budget?.deadline ?? Date.now() + 300000;
+        const check = () => {
+            if (budget?.signal?.aborted)
+                throw new Error("Semantic extraction cancelled");
+            if (Date.now() >= deadline)
+                throw new Error("Semantic extraction deadline exceeded");
+        };
+        let outputBytes = 0;
+        const accountOutput = (text) => {
+            outputBytes += Buffer.byteLength(text);
+            if (outputBytes > 120000)
+                throw new Error("Semantic output budget exceeded");
+            if (Buffer.byteLength(text) > 16000)
+                throw new Error("Semantic chunk output budget exceeded");
+        };
+        if (chunks.reduce((n, c) => n + Buffer.byteLength(c.text), 0) > 1000000)
+            throw new Error("Semantic input budget exceeds 250k conservatively estimated tokens");
+        const groups = [];
+        for (const chunk of chunks) {
+            const size = Buffer.byteLength(chunk.text);
+            if (size > 64000)
+                throw new Error("scope-decision-required: semantic file exceeds chunk budget");
+            const last = groups.at(-1);
+            if (last && last.reduce((n, c) => n + Buffer.byteLength(c.text), 0) + size <= 64000)
+                last.push(chunk);
+            else
+                groups.push([chunk]);
+        }
+        for (let index = 0; index < groups.length; index++) {
+            check();
+            // Whole input files remain attributable; oversize files require explicit
+            // narrower adoption instead of silently truncating their semantic input.
+            const request = semanticExchange(groups[index], `${operationId}:chunk:${index}`);
+            const id = digest("semantic-dispatch", request);
+            const db = new WorkflowDb(root);
+            try {
+                const store = db.graphStore(), prior = store.get("job", id)?.value;
+                if (prior) {
+                    if (prior.state !== "completed" || !prior.result)
+                        throw new Error("Uncertain semantic dispatch requires explicit reconciliation; refusing replay");
+                    outputBytes += prior.outputBytes ?? Buffer.byteLength(canonical(prior.result));
+                    if (outputBytes > 120000)
+                        throw new Error("Semantic output budget exceeded");
+                    result.nodes.push(...prior.result.nodes);
+                    result.edges.push(...prior.result.edges);
+                    continue;
+                }
+                const scratchRoot = join(root, "graphify-out", "rafi", "semantic-sessions");
+                mkdirSync(scratchRoot, { recursive: true });
+                confined(root, "graphify-out/rafi/semantic-sessions");
+                const scratch = mkdtempSync(join(scratchRoot, "worker-"));
+                let worker;
+                let closing;
+                const close = () => {
+                    // Do not memoize an empty close while asynchronous creation is pending.
+                    // A worker arriving after the deadline still needs its own teardown.
+                    if (!worker)
+                        return Promise.resolve();
+                    const target = worker;
+                    return closing ??= Promise.resolve().then(() => target.close()).then(() => undefined).catch(() => undefined);
+                };
+                let stop;
+                const stopped = new Promise((_, reject) => { stop = reject; });
+                // The provider may fail to settle its turn even after close. The host's
+                // absolute deadline independently bounds the awaited dispatch.
+                const cancel = () => {
+                    stop(new Error(budget?.signal?.aborted ? "Semantic extraction cancelled" : "Semantic extraction deadline exceeded"));
+                    if (worker)
+                        void close();
+                };
+                const timer = setTimeout(cancel, Math.max(1, deadline - Date.now()));
+                budget?.signal?.addEventListener("abort", cancel, { once: true });
+                try {
+                    const opts = { ...settings, cwd: scratch, configRoot: root, sessionRole: "planner", sessionStream: "graph-semantic", sandboxMode: "read-only", approvalPolicy: "never", networkAccess: false, systemPromptAppend: SEMANTIC_INSTRUCTIONS, permission: async () => ({ behavior: "deny", message: "Graph semantic extraction accepts only the captured packet; all tools denied" }), turnDeadlineMs: Math.max(1, deadline - Date.now()) };
+                    worker = await Promise.race([createWorker(opts).then(created => {
+                            worker = created;
+                            if (budget?.signal?.aborted || Date.now() >= deadline)
+                                void close();
+                            return created;
+                        }), stopped]);
+                    check();
+                    store.put("job", id, { version: 1, state: "dispatch-intended", operationId, requestId: request.operationId, inputDigest: request.inputDigest, provider: host.agent, model: settings.model });
+                    const chunkOutputStart = outputBytes;
+                    const observations = [];
+                    const recordObservation = (turn) => {
+                        observations.push(turn);
+                        store.put("job", id, { version: 1, state: "returned-unvalidated", operationId, requestId: request.operationId,
+                            inputDigest: request.inputDigest, sessionId: worker?.sessionId(),
+                            observations: observations.map(t => ({ turnId: t.turnId, usage: t.usage, costUsd: t.costAuthoritative ? t.costUsd : undefined,
+                                responseDigest: bytesDigest(t.rawResponse ?? t.text), failed: Boolean(t.isError || t.failure) })) });
+                    };
+                    const turn = await Promise.race([worker.sendTurn(canonical(request), { responseOnly: true, handback: true, logicalActionId: request.operationId }), stopped]);
+                    recordObservation(turn);
+                    check();
+                    accountOutput(turn.cleanedResponse ?? turn.text);
+                    if (turn.isError || turn.failure)
+                        throw new Error(`Semantic provider failed: ${turn.text.slice(0, 500)}`);
+                    let parsed;
+                    try {
+                        parsed = parseSemanticResult(turn.cleanedResponse ?? turn.text, request);
+                    }
+                    catch (error) {
+                        check();
+                        store.put("job", id, { version: 1, state: "repair-intended", operationId, requestId: request.operationId, inputDigest: request.inputDigest, initialResponseDigest: bytesDigest(turn.rawResponse ?? turn.text), observations: observations.map(t => ({ turnId: t.turnId, usage: t.usage, costUsd: t.costAuthoritative ? t.costUsd : undefined })) });
+                        const repaired = await Promise.race([worker.sendTurn(`Format correction only. Preserve your source observations; no tools or new extraction. Return strict JSON matching ${canonical({ operationId: request.operationId, inputDigest: request.inputDigest })}. Validation: ${String(error)}`, { responseOnly: true, handback: true, logicalActionId: request.operationId }), stopped]);
+                        recordObservation(repaired);
+                        check();
+                        accountOutput(repaired.cleanedResponse ?? repaired.text);
+                        if (repaired.isError || repaired.failure)
+                            throw new Error("Semantic format correction failed; reconciliation required");
+                        parsed = parseSemanticResult(repaired.cleanedResponse ?? repaired.text, request);
+                    }
+                    const known = observations.every(t => t.usage?.scope === "turn-delta" && t.usage.inputTokens !== undefined && t.usage.outputTokens !== undefined);
+                    const authoritative = observations.every(t => t.costAuthoritative === true);
+                    store.put("job", id, { version: 1, state: "completed", operationId, sessionId: worker.sessionId(),
+                        turnIds: observations.map(t => t.turnId), result: parsed, outputBytes: outputBytes - chunkOutputStart,
+                        usage: { inputTokens: known ? observations.reduce((n, t) => n + t.usage.inputTokens, 0) : undefined,
+                            outputTokens: known ? observations.reduce((n, t) => n + t.usage.outputTokens, 0) : undefined,
+                            costUsd: authoritative ? observations.reduce((n, t) => n + t.costUsd, 0) : undefined,
+                            observations: observations.map(t => ({ turnId: t.turnId, usage: t.usage, costUsd: t.costAuthoritative ? t.costUsd : undefined })) } });
+                    result.nodes.push(...parsed.nodes);
+                    result.edges.push(...parsed.edges);
+                }
+                finally {
+                    clearTimeout(timer);
+                    budget?.signal?.removeEventListener("abort", cancel);
+                    let closeTimer;
+                    try {
+                        await Promise.race([close(), new Promise(resolve => { closeTimer = setTimeout(resolve, 1000); })]);
+                    }
+                    finally {
+                        if (closeTimer)
+                            clearTimeout(closeTimer);
+                    }
+                    rmSync(scratch, { recursive: true, force: true });
+                }
+            }
+            finally {
+                db.close();
+            }
+            if (Date.now() > deadline)
+                throw new Error("Semantic extraction deadline exceeded");
+        }
+        return result;
+    };
+}

package/dist/graph/install.d.ts

@@ -0,0 +1,3 @@
+export declare function ownedGraphPython(root: string): string;
+/** Installation is called only after an explicit adoption/setup grant. */
+export declare function ensureGraphInstallation(root: string): Promise<string>;

package/dist/graph/install.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { GRAPHIFY_VERSION } from "rafi-spec";
+import { resolveGraphPython, runBridge } from "./bridge.js";
+import { confined } from "./util.js";
+function run(executable, args, deadline) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { stdio: ["ignore", "ignore", "pipe"], windowsHide: true, env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR, TEMP: process.env.TEMP, TMP: process.env.TMP } });
+        let diagnostics = "";
+        const timer = setTimeout(() => { child.kill(); reject(new Error("Graph installation deadline exceeded")); }, Math.max(1, deadline - Date.now()));
+        child.stderr.on("data", chunk => {
+            if (diagnostics.length < 8000)
+                diagnostics += String(chunk).slice(0, 8000 - diagnostics.length);
+        });
+        child.on("error", error => { clearTimeout(timer); reject(error); });
+        child.on("close", code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error(`Graph environment setup failed (${code}): ${diagnostics}`)); });
+    });
+}
+export function ownedGraphPython(root) { return join(root, "graphify-out", "rafi", "runtime", process.platform === "win32" ? "Scripts" : "bin", process.platform === "win32" ? "python.exe" : "python"); }
+/** Installation is called only after an explicit adoption/setup grant. */
+export async function ensureGraphInstallation(root) {
+    try {
+        return await resolveGraphPython();
+    }
+    catch { /* Preserve incompatible/shared installations. */ }
+    const existing = ownedGraphPython(root);
+    if (existsSync(existing)) {
+        await runBridge(existing, { action: "probe" }, { timeoutMs: 5000 });
+        return existing;
+    }
+    const base = join(root, "graphify-out", "rafi");
+    mkdirSync(base, { recursive: true });
+    confined(root, "graphify-out/rafi");
+    const temporary = join(base, `runtime-${randomUUID()}`), deadline = Date.now() + 120000;
+    const python = process.platform === "win32" ? "python" : "python3";
+    try {
+        await run(python, ["-I", "-m", "venv", temporary], deadline);
+        const isolated = join(temporary, process.platform === "win32" ? "Scripts" : "bin", process.platform === "win32" ? "python.exe" : "python");
+        await run(isolated, ["-I", "-m", "pip", "--isolated", "install", "--disable-pip-version-check", "--no-input", `graphifyy==${GRAPHIFY_VERSION}`], deadline);
+        await runBridge(isolated, { action: "probe" }, { timeoutMs: 5000 });
+        renameSync(temporary, join(base, "runtime"));
+        return existing;
+    }
+    catch (error) {
+        rmSync(temporary, { recursive: true, force: true });
+        throw new Error(`Graphify enabled-unavailable. Install a supported Python with venv/pip, then retry graph adopt. ${String(error)}`);
+    }
+}

package/dist/graph/lifecycle.d.ts

@@ -0,0 +1,11 @@
+/** Loaded readers own in-memory bytes; durable consumers explicitly retain IDs. */
+export declare function retainGraphGeneration(root: string, generationId: string, owner: string): void;
+export declare function pruneGraph(root: string): {
+    removed: string[];
+    retainedBytes: number;
+    limited: boolean;
+};
+export declare function graphStorageBytes(root: string): number;
+/** A checkout boundary invalidates its mutable head, never its immutable history.
+ * This is metadata-only: a merge or recreation does not itself authorize extraction. */
+export declare function invalidateGraphWorkspace(root: string, workspace: string, reason: "merge-or-rebase" | "worktree-created" | "worktree-removed"): void;

package/dist/graph/lifecycle.js

@@ -0,0 +1,124 @@
+import { graphScope } from "./read.js";
+import { existsSync, lstatSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { WorkflowDb } from "../workflowDb.js";
+import { loadGraphConfig } from "./config.js";
+import { confined } from "./util.js";
+/** Loaded readers own in-memory bytes; durable consumers explicitly retain IDs. */
+export function retainGraphGeneration(root, generationId, owner) {
+    const db = new WorkflowDb(root);
+    try {
+        db.graphStore().put("retention", owner, { generationId, owner, createdAt: new Date().toISOString() });
+    }
+    finally {
+        db.close();
+    }
+}
+export function pruneGraph(root) {
+    const config = loadGraphConfig(root), base = join(root, "graphify-out", "rafi");
+    if (!existsSync(base))
+        return { removed: [], retainedBytes: 0, limited: false };
+    confined(root, "graphify-out/rafi");
+    const db = new WorkflowDb(root);
+    try {
+        const store = db.graphStore();
+        const protectedIds = new Set([...store.list("head"), ...store.list("retention")].map(x => x.value.generationId));
+        // Active/recoverable run receipts pin their navigation generations. A graph
+        // cannot become required QA authority, but pruning must respect live users.
+        for (const receipt of store.list("receipt")) {
+            const run = receipt.value.runId ? db.getRun(receipt.value.runId) : undefined;
+            if (run && !["completed", "cancelled"].includes(run.status))
+                for (const id of receipt.value.generationIds ?? [])
+                    protectedIds.add(id);
+        }
+        const staging = join(base, "staging");
+        if (existsSync(staging)) {
+            confined(root, "graphify-out/rafi/staging");
+            for (const name of readdirSync(staging)) {
+                const match = /^([a-f0-9]{64})-(\d+)$/.exec(name);
+                if (!match)
+                    continue;
+                const job = store.get("job", match[1])?.value;
+                if (job?.scope && Date.now() - lstatSync(join(staging, name)).mtimeMs >= 86400000 && !store.ownsLease(job.scope, match[1], Number(match[2]), Date.now()))
+                    rmSync(confined(staging, name), { recursive: true });
+            }
+        }
+        const dir = join(base, "generations"), removed = [];
+        let retainedBytes = 0;
+        if (!existsSync(dir))
+            return { removed, retainedBytes, limited: false };
+        confined(root, "graphify-out/rafi/generations");
+        let visited = 0;
+        const inventoryStarted = Date.now();
+        const size = (path) => {
+            if (++visited > 200000 || Date.now() - inventoryStarted > 5000)
+                throw new Error("Graph cleanup inventory limit exceeded");
+            const st = lstatSync(path);
+            if (st.isSymbolicLink())
+                throw new Error("Refusing graph cleanup through symbolic link");
+            return st.isDirectory() ? readdirSync(path).reduce((n, name) => n + size(join(path, name)), 0) : st.size;
+        };
+        const generations = store.list("generation").sort((a, b) => b.value.createdAt.localeCompare(a.value.createdAt));
+        // Only known immutable Rafi generations can be deleted. Never follow an
+        // arbitrary user-provided cache path or remove shared Python installations.
+        for (const row of generations.filter(r => protectedIds.has(r.id))) {
+            if (existsSync(join(dir, row.id)))
+                retainedBytes += size(confined(dir, row.id));
+        }
+        const counts = new Map();
+        for (const row of generations.filter(r => !protectedIds.has(r.id))) {
+            if (!/^[a-f0-9]{64}$/.test(row.id) || !existsSync(join(dir, row.id)))
+                continue;
+            const path = confined(dir, row.id), bytes = size(path);
+            const scope = row.value.binding.workspaceRef, count = counts.get(scope) ?? 0;
+            counts.set(scope, count + 1);
+            if (count < 3 && Date.now() - Date.parse(row.value.createdAt) < 7 * 86400000 && retainedBytes + bytes <= config.limits.storageBytes) {
+                retainedBytes += bytes;
+                continue;
+            }
+            rmSync(path, { recursive: true });
+            removed.push(row.id);
+            store.put("revocation", `cache:${row.id}`, { generationId: row.id, reason: "cache-pruned", at: new Date().toISOString() });
+        }
+        return { removed, retainedBytes, limited: retainedBytes > config.limits.storageBytes };
+    }
+    finally {
+        db.close();
+    }
+}
+export function graphStorageBytes(root) {
+    const base = join(root, "graphify-out", "rafi");
+    if (!existsSync(base))
+        return 0;
+    confined(root, "graphify-out/rafi");
+    let entries = 0;
+    const started = Date.now();
+    const walk = (path) => {
+        if (++entries > 200000 || Date.now() - started > 5000)
+            throw new Error("Graph storage inventory limit exceeded");
+        const st = lstatSync(path);
+        if (st.isSymbolicLink())
+            throw new Error("Graph storage contains an unsupported symbolic link");
+        return st.isDirectory() ? readdirSync(path).reduce((n, name) => n + walk(join(path, name)), 0) : st.size;
+    };
+    return ["generations", "staging", "semantic-sessions"].reduce((n, name) => n + (existsSync(join(base, name)) ? walk(join(base, name)) : 0), 0);
+}
+/** A checkout boundary invalidates its mutable head, never its immutable history.
+ * This is metadata-only: a merge or recreation does not itself authorize extraction. */
+export function invalidateGraphWorkspace(root, workspace, reason) {
+    const config = loadGraphConfig(root);
+    if (!config.enabled || !existsSync(workspace))
+        return;
+    const scope = graphScope(workspace);
+    const db = new WorkflowDb(root);
+    try {
+        const store = db.graphStore(), head = store.get("head", scope);
+        if (!head)
+            return;
+        store.remove("head", scope);
+        store.put("revocation", `workspace:${scope}`, { reason, generationId: head.value.generationId, at: new Date().toISOString(), limitation: "Checkout changed; capture and rebind before current-source reuse" });
+    }
+    finally {
+        db.close();
+    }
+}