ai-foreman 1.7.20 → 1.7.21

package/dist/graph/maintenance.d.ts

@@ -0,0 +1,43 @@
+export { graphSemanticHost } from "./host.js";
+export { ensureGraphInstallation } from "./install.js";
+import { type GraphAdoptionV1, type GraphConfigV1 } from "rafi-spec";
+export interface SemanticChunk {
+    path: string;
+    digest: string;
+    text: string;
+}
+export interface SemanticExtraction {
+    nodes: Array<Record<string, unknown>>;
+    edges: Array<Record<string, unknown>>;
+    origin: {
+        provider: string;
+        model?: string;
+        operationId: string;
+    };
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export type GraphSemanticHost = (chunks: SemanticChunk[], operationId: string, budget?: {
+    deadline: number;
+    signal?: AbortSignal;
+}) => Promise<SemanticExtraction>;
+export interface GraphMaintenanceOutcome {
+    operationId: string;
+    state: "published" | "failed" | "deferred";
+    generationId?: string;
+    reason?: string;
+}
+/** Called only by an accepted setup or explicit adoption, never by a read/factory. */
+export declare function adoptGraph(configRoot: string, input: {
+    config?: GraphConfigV1;
+    authorization: "setup" | "explicit";
+}): GraphAdoptionV1;
+export declare function disableGraph(configRoot: string): void;
+/** Foreground, fenced publication. Semantic failure never replaces a mixed graph. */
+export declare function refreshGraph(configRoot: string, workspace: string, logicalTaskId: string, options?: {
+    semanticHost?: GraphSemanticHost;
+    sourceRef?: string;
+    python?: string;
+    signal?: AbortSignal;
+}): Promise<GraphMaintenanceOutcome>;
+export { loadGraphConfig } from "./config.js";

package/dist/graph/maintenance.js

@@ -0,0 +1,301 @@
+export { graphSemanticHost } from "./host.js";
+import { capturePreimage, finalizeOwnedWrite, registerOwnedFile, readInstallManifest } from "../installOwnership.js";
+import { graphStorageBytes } from "./lifecycle.js";
+import { ownedGraphPython } from "./install.js";
+export { ensureGraphInstallation } from "./install.js";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, openSync, closeSync, fsyncSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { parseDocument } from "yaml";
+import { loadSourceRegistry } from "../sources/sourceRegistry.js";
+import { assertGraphConfig, DEFAULT_GRAPH_CONFIG, GRAPHIFY_VERSION } from "rafi-spec";
+import { WorkflowDb } from "../workflowDb.js";
+import { loadGraphConfig } from "./config.js";
+import { captureGraphCorpus } from "./corpus.js";
+import { resolveGraphPython, runBridge } from "./bridge.js";
+import { graphScope } from "./read.js";
+import { bytesDigest, canonical, digest, readBounded, confined } from "./util.js";
+/** Called only by an accepted setup or explicit adoption, never by a read/factory. */
+export function adoptGraph(configRoot, input) {
+    const existing = loadGraphConfig(configRoot);
+    const config = structuredClone(input.config ?? existing.config ?? DEFAULT_GRAPH_CONFIG);
+    config.enabled = true;
+    if (config.sourceSelection === "active-captured") {
+        config.sourceVersions = { ...(existing.config?.sourceSelection === "active-captured" ? existing.config.sourceVersions : {}), ...config.sourceVersions };
+        const registry = loadSourceRegistry(configRoot).registry;
+        config.sourceIds = registry.entries.filter(entry => entry.active && entry.versions.length).map(entry => entry.id).sort();
+        config.sourceVersions = Object.fromEntries(config.sourceIds.flatMap(id => config.sourceVersions?.[id] ? [[id, config.sourceVersions[id]]] : []));
+    }
+    if (config.sourceIds.length) {
+        const registry = loadSourceRegistry(configRoot).registry;
+        config.sourceVersions = { ...config.sourceVersions };
+        for (const id of config.sourceIds) {
+            const entry = registry.entries.find(e => e.id === id && e.active);
+            const version = config.sourceVersions[id] ?? entry?.versions.at(-1)?.fingerprint;
+            if (!version || !entry?.versions.some(v => v.fingerprint === version))
+                throw new Error(`Registered source ${id} requires an approved captured version`);
+            config.sourceVersions[id] = version;
+        }
+    }
+    assertGraphConfig(config);
+    if (existing.enabled && existing.policyDigest === digest("policy", config) && existing.adoption)
+        return existing.adoption;
+    const adoption = { version: 1, projectRef: existing.projectRef, config, policyDigest: digest("policy", config), acceptedAt: new Date().toISOString(), authorization: input.authorization, initialOperationId: randomUUID() };
+    // Update only the graph setting; preserve other project fields and user files.
+    const configFile = ["rafi-config.yaml", "project.yaml"].map(name => join(configRoot, name)).find(existsSync);
+    if (configFile) {
+        const ownedConfig = capturePreimage(configRoot, relative(configRoot, configFile), "graph-adoption", "config");
+        const raw = parseDocument(readFileSync(configFile, "utf8"));
+        if (!raw || typeof raw !== "object")
+            throw new Error("Invalid project configuration");
+        raw.set("graph", config);
+        const temporary = `${configFile}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, raw.toString());
+        renameSync(temporary, configFile);
+        finalizeOwnedWrite(configRoot, ownedConfig);
+    }
+    const db = new WorkflowDb(configRoot);
+    try {
+        db.graphStore().put("adoption", "project", adoption);
+    }
+    finally {
+        db.close();
+    }
+    const ignore = join(configRoot, ".gitignore");
+    const prior = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    if (!prior.split(/\r?\n/).includes("/graphify-out/")) {
+        const recorded = readInstallManifest(configRoot)?.files.find(entry => entry.path === ".gitignore");
+        const ownedIgnore = capturePreimage(configRoot, ".gitignore", "graph-adoption", "managed-gitignore");
+        const [start, end] = recorded?.marker?.split("..") ?? [];
+        if (recorded?.mode === "managed-block" && start && end && prior.includes(start) && prior.includes(end)) {
+            // Ownership has one entry per path: extend its existing managed block.
+            writeFileSync(ignore, prior.replace(end, `/graphify-out/\n${end}`));
+            finalizeOwnedWrite(configRoot, recorded);
+        }
+        else {
+            writeFileSync(ignore, `${prior}${prior && !prior.endsWith("\n") ? "\n" : ""}# rafi-graph:start\n/graphify-out/\n# rafi-graph:end\n`);
+            finalizeOwnedWrite(configRoot, ownedIgnore.mode === "created" || ownedIgnore.mode === "generated" ? ownedIgnore : { ...ownedIgnore, mode: "managed-block", marker: "# rafi-graph:start..# rafi-graph:end" });
+        }
+    }
+    const ownedRoot = join(configRoot, "graphify-out", "rafi");
+    if (!existsSync(ownedRoot)) {
+        mkdirSync(ownedRoot, { recursive: true });
+        registerOwnedFile(configRoot, "graphify-out/rafi", { mode: "generated", origin: "graph-adoption", category: "runtime-state" });
+    }
+    return adoption;
+}
+export function disableGraph(configRoot) {
+    const effective = loadGraphConfig(configRoot);
+    if (!effective.config || !effective.adoption)
+        return;
+    const config = { ...effective.config, enabled: false };
+    const configFile = ["rafi-config.yaml", "project.yaml"].map(name => join(configRoot, name)).find(existsSync);
+    if (configFile) {
+        const raw = parseDocument(readFileSync(configFile, "utf8"));
+        raw.set("graph", config);
+        const temp = `${configFile}.${randomUUID()}.tmp`;
+        writeFileSync(temp, raw.toString());
+        renameSync(temp, configFile);
+    }
+    const db = new WorkflowDb(configRoot);
+    try {
+        db.graphStore().put("adoption", "project", { ...effective.adoption, config, policyDigest: digest("policy", config) });
+    }
+    finally {
+        db.close();
+    }
+}
+function validateSemantics(result, corpus, expected) {
+    if (Buffer.byteLength(canonical(result)) > 120000)
+        throw new Error("Semantic output budget exceeded");
+    if (!Array.isArray(result.nodes) || !Array.isArray(result.edges) || !result.origin?.operationId || !result.origin.provider)
+        throw new Error("Invalid semantic extraction protocol");
+    const files = new Set(expected.map(x => x.path));
+    const ids = new Set();
+    for (const node of result.nodes) {
+        if (typeof node.id !== "string" || ids.has(node.id) || typeof node.source_file !== "string" || !files.has(node.source_file) || !corpus.bytes.has(node.source_file))
+            throw new Error("Semantic node has invalid identity/provenance");
+        ids.add(node.id);
+    }
+    for (const edge of result.edges)
+        if (typeof edge.source_file !== "string" || !files.has(edge.source_file) || !ids.has(String(edge.source)) || !ids.has(String(edge.target)) || !["EXTRACTED", "INFERRED", "AMBIGUOUS"].includes(String(edge.confidence)))
+            throw new Error("Semantic edge has invalid endpoint/evidence class");
+    for (const file of files)
+        if (!result.nodes.some(n => n.source_file === file))
+            throw new Error(`Semantic extraction omitted ${file}; input remains unstamped`);
+}
+/** Foreground, fenced publication. Semantic failure never replaces a mixed graph. */
+export async function refreshGraph(configRoot, workspace, logicalTaskId, options = {}) {
+    const effective = loadGraphConfig(configRoot);
+    if (!effective.enabled)
+        throw new Error(`Graph ${effective.reason}; explicit adoption required`);
+    const scope = graphScope(workspace), operationId = digest("maintenance", { scope, logicalTaskId, policy: effective.policyDigest });
+    const db = new WorkflowDb(configRoot), store = db.graphStore();
+    const previous = store.get("job", operationId);
+    if (previous?.value.state === "published") {
+        db.close();
+        return previous.value;
+    }
+    const owner = operationId;
+    let fence;
+    try {
+        fence = store.lease(scope, owner, Date.now(), effective.limits.maintenanceMs);
+    }
+    catch (error) {
+        db.close();
+        return { operationId, state: "deferred", reason: String(error) };
+    }
+    const stage = join(configRoot, "graphify-out", "rafi", "staging", `${operationId}-${fence}`);
+    const started = Date.now();
+    const check = () => {
+        if (options.signal?.aborted)
+            throw new Error("Graph maintenance cancelled");
+        if (Date.now() - started > effective.limits.maintenanceMs)
+            throw new Error("Graph maintenance deadline exceeded");
+        if (!store.ownsLease(scope, owner, fence, Date.now()))
+            throw new Error("Graph maintenance lease lost");
+    };
+    try {
+        const prior = store.get("head", scope);
+        store.put("job", operationId, { version: 1, operationId, state: "capturing", scope, fence, startedAt: new Date().toISOString() });
+        const corpus = captureGraphCorpus(workspace, configRoot, effective, options.sourceRef);
+        check();
+        const parent = prior ? store.get("generation", prior.value.generationId)?.value : undefined;
+        if (parent) {
+            const { id, ...metadata } = parent;
+            if (!/^[a-f0-9]{64}$/.test(id) || digest("generation", metadata) !== id)
+                throw new Error("Parent generation metadata checksum mismatch");
+        }
+        let reusable;
+        if (parent?.policyDigest === effective.policyDigest) {
+            try {
+                const bytes = readBounded(confined(configRoot, `graphify-out/rafi/generations/${parent.id}/semantic.json`), effective.limits.maxGraphBytes);
+                if (parent.files["semantic.json"] !== bytesDigest(bytes))
+                    throw new Error("Semantic cache checksum mismatch");
+                reusable = JSON.parse(bytes.toString("utf8"));
+            }
+            catch { /* Unknown legacy semantic provenance is never silently reused. */ }
+        }
+        const unchanged = new Set(corpus.inputs.filter(i => i.kind === "semantic" && parent?.inputs.some(p => p.path === i.path && p.digest === i.digest)).map(i => i.path));
+        const preservedNodes = reusable?.nodes.filter(n => unchanged.has(String(n.source_file))) ?? [];
+        const preservedIds = new Set(preservedNodes.map(n => String(n.id)));
+        const preservedEdges = reusable?.edges.filter(e => preservedIds.has(String(e.source)) && preservedIds.has(String(e.target)) && unchanged.has(String(e.source_file))) ?? [];
+        const semanticInputs = effective.config.mode === "mixed" ? corpus.inputs.filter(i => i.kind === "semantic" && (!unchanged.has(i.path) || !preservedNodes.some(n => n.source_file === i.path))) : [];
+        if (semanticInputs.length > effective.limits.semanticInputs)
+            throw new Error("scope-decision-required: semantic input budget exceeded");
+        if (semanticInputs.length && !options.semanticHost)
+            throw new Error("semantic-runtime-unavailable: mixed extraction needs an authorized host exchange");
+        store.reserveStorage(`${operationId}:${fence}`, corpus.inputs.reduce((n, i) => n + i.bytes, 0) + effective.limits.maxGraphBytes * 4, graphStorageBytes(configRoot), effective.limits.storageBytes, { scope, owner, fence });
+        mkdirSync(join(stage, "input"), { recursive: true });
+        confined(configRoot, `graphify-out/rafi/staging/${operationId}-${fence}`);
+        for (const input of corpus.inputs) {
+            const path = join(stage, "input", input.path);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, corpus.bytes.get(input.path), { mode: 0o444 });
+        }
+        let semantic;
+        if (semanticInputs.length) {
+            const chunks = semanticInputs.map(i => ({ path: i.path, digest: i.digest, text: corpus.bytes.get(i.path).toString("utf8") }));
+            if (chunks.reduce((n, c) => n + c.text.length, 0) > 750000)
+                throw new Error("Semantic input budget exceeded; choose an explicit larger scoped policy");
+            semantic = await options.semanticHost(chunks, operationId, { deadline: started + effective.limits.maintenanceMs, signal: options.signal });
+            validateSemantics(semantic, corpus, chunks);
+        }
+        if (preservedNodes.length) {
+            semantic = { nodes: [...preservedNodes, ...(semantic?.nodes ?? [])], edges: [...preservedEdges, ...(semantic?.edges ?? [])], origin: semantic?.origin ?? reusable.origin, inputTokens: semantic?.inputTokens, outputTokens: semantic?.outputTokens };
+        }
+        check();
+        const python = options.python ?? (existsSync(ownedGraphPython(configRoot)) ? ownedGraphPython(configRoot) : await resolveGraphPython());
+        store.put("capability", "machine", { version: 1, python, packageVersion: GRAPHIFY_VERSION, checkedAt: new Date().toISOString(), scope: "local-machine; not portable" });
+        store.put("job", operationId, { version: 1, operationId, state: "extracting", scope, fence });
+        const extracted = await runBridge(python, { action: "extract", staging: stage, ...(parent?.policyDigest === effective.policyDigest ? { parentCache: confined(configRoot, `graphify-out/rafi/generations/${parent.id}`), cacheChecksums: parent.files } : {}), paths: corpus.inputs.filter(i => i.kind === "code").map(i => i.path), semantic: semantic ?? { nodes: [], edges: [] } }, { timeoutMs: Math.max(1, effective.limits.maintenanceMs - (Date.now() - started)), maxOutputBytes: effective.limits.maxGraphBytes, cwd: stage, signal: options.signal });
+        check();
+        if (Array.isArray(extracted.extraction.failed_sources) && extracted.extraction.failed_sources.length)
+            throw new Error(`AST extraction failed for ${extracted.extraction.failed_sources.length} inputs; prior generation retained`);
+        if (parent?.policyDigest === effective.policyDigest) {
+            try {
+                const parentBytes = readBounded(confined(configRoot, `graphify-out/rafi/generations/${parent.id}/graph.json`), effective.limits.maxGraphBytes);
+                if (bytesDigest(parentBytes) !== parent.graphDigest)
+                    throw new Error("Parent graph checksum mismatch");
+                const old = JSON.parse(parentBytes.toString("utf8"));
+                const stable = new Set(corpus.inputs.filter(i => parent.inputs.some(p => p.path === i.path && p.digest === i.digest)).map(i => i.path));
+                const nextIds = new Set(extracted.graph.nodes.map(n => n.id));
+                const lost = old.nodes.filter(n => n.source_file && stable.has(n.source_file) && !nextIds.has(n.id));
+                if (lost.length)
+                    throw new Error(`unexplained-shrinkage: ${lost.length} unchanged-input nodes disappeared`);
+                const stableIds = new Set(old.nodes.filter(n => n.source_file && stable.has(n.source_file)).map(n => n.id));
+                const edgeKey = (edge) => canonical({ source: edge.source, target: edge.target, relation: edge.relation, source_file: edge.source_file });
+                const nextEdges = new Set((extracted.graph.links ?? extracted.graph.edges ?? []).map(edgeKey));
+                const lostEdges = (old.links ?? old.edges ?? []).filter(edge => stableIds.has(String(edge.source)) && stableIds.has(String(edge.target))
+                    && typeof edge.source_file === "string" && stable.has(edge.source_file) && !nextEdges.has(edgeKey(edge)));
+                if (lostEdges.length)
+                    throw new Error(`unexplained-shrinkage: ${lostEdges.length} unchanged-input relationships disappeared`);
+            }
+            catch (error) {
+                if (String(error).includes("unexplained-shrinkage"))
+                    throw error;
+                throw new Error(`Parent graph validation unavailable: ${String(error)}`);
+            }
+        }
+        const graphBytes = Buffer.from(canonical(extracted.graph));
+        const limitations = effective.config.mode === "code-only" && corpus.inputs.some(i => i.kind === "semantic") ? [{ reason: "code-only", detail: "Documentation and requirement semantics were deliberately not extracted" }] : [];
+        const sidecars = { "extraction.json": canonical(extracted.extraction), ...(semantic ? { "semantic.json": canonical(semantic), "semantic-origin.json": canonical(semantic.origin) } : {}) };
+        const sidecarDigests = {};
+        for (const [name, text] of Object.entries(sidecars)) {
+            writeFileSync(join(stage, name), text);
+            sidecarDigests[name] = bytesDigest(text);
+        }
+        sidecarDigests["graph.html"] = bytesDigest(readBounded(join(stage, "graph.html"), effective.limits.maxGraphBytes * 2));
+        const metadata = { version: 1, corpusDigest: corpus.corpusDigest, policyDigest: effective.policyDigest, graphDigest: bytesDigest(graphBytes), binding: corpus.binding, inputs: corpus.inputs, createdAt: new Date().toISOString(), operationId, packageVersion: GRAPHIFY_VERSION, graphSchema: 1, parent: prior?.value.generationId, limitations, files: { ...extracted.cacheFiles, ...sidecarDigests, "exclusions-digest": corpus.exclusionsDigest } };
+        const generation = { ...metadata, id: digest("generation", metadata) };
+        writeFileSync(join(stage, "graph.json"), graphBytes);
+        writeFileSync(join(stage, "manifest.json"), canonical(generation));
+        const report = `# Rafi Graphify generation\n\nGeneration: ${generation.id}\nCorpus: ${corpus.corpusDigest}\nInputs: ${corpus.inputs.length}\nReused AST inputs: ${extracted.reusedAstInputs}\nGraphify: ${GRAPHIFY_VERSION}\n\nUsage: ${semantic?.inputTokens ?? "unknown"} input tokens; ${semantic?.outputTokens ?? "unknown"} output tokens.\n\nGraph evidence requires independent source verification.\n${limitations.map(l => l.detail).join("\n")}\n`;
+        writeFileSync(join(stage, "GRAPH_REPORT.md"), report);
+        if (!existsSync(join(stage, "graph.html")))
+            throw new Error("Required graph visualization missing");
+        const current = loadGraphConfig(configRoot);
+        if (!current.enabled || current.policyDigest !== effective.policyDigest)
+            throw new Error("Graph policy revoked during extraction");
+        if (captureGraphCorpus(workspace, configRoot, current, options.sourceRef).corpusDigest !== corpus.corpusDigest)
+            throw new Error("Source drift during extraction; publication deferred");
+        check();
+        rmSync(join(stage, "input"), { recursive: true, force: true });
+        const directory = join(configRoot, "graphify-out", "rafi", "generations", generation.id);
+        mkdirSync(dirname(directory), { recursive: true });
+        for (const name of ["graph.json", "manifest.json", "extraction.json", "GRAPH_REPORT.md", "graph.html", ...(semantic ? ["semantic.json", "semantic-origin.json"] : []), ...Object.keys(extracted.cacheFiles)]) {
+            const fd = openSync(join(stage, name), "r");
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        renameSync(stage, directory);
+        if (process.platform !== "win32") {
+            const fd = openSync(dirname(directory), "r");
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        const outcome = { operationId, state: "published", generationId: generation.id };
+        store.publish(scope, owner, fence, Date.now(), prior?.revision ?? 0, generation, outcome);
+        return outcome;
+    }
+    catch (error) {
+        const outcome = { operationId, state: "failed", reason: String(error) };
+        if (store.ownsLease(scope, owner, fence, Date.now()))
+            store.put("job", operationId, outcome);
+        return outcome;
+    }
+    finally {
+        store.remove("storage-reservation", `${operationId}:${fence}`);
+        store.release(scope, owner, fence);
+        db.close();
+    }
+}
+export { loadGraphConfig } from "./config.js";

package/dist/graph/manager.d.ts

@@ -0,0 +1,9 @@
+import { type ManagerGraphRequestV3 } from "rafi-spec";
+import type { GraphDerivedAccess } from "./derived.js";
+export declare const MANAGER_GRAPH_GUIDANCE = "For substantial architecture/dependency questions, request graph evidence through this additional host envelope: {\"kind\":\"manager_graph_evidence_request\",\"version\":3,\"requestId\":\"unique-id\",\"operations\":[{\"operation\":\"query\",\"query\":\"specific source concepts\"}]}. Do not mix envelopes. This shares your existing evidence lookup budget. Only the host chooses project/source scope. An optional receiptId can select previously delivered evidence belonging to the host-selected run; unavailable historical caches stay unavailable. Current-source graph evidence cannot establish a historical run's implementation or cause. Graph output never authorizes controls.";
+export declare function parseManagerGraphRequest(text: string): ManagerGraphRequestV3 | undefined;
+export declare function createManagerGraphEvidence(configRoot: string, runId?: string): {
+    guidance: string;
+    access: () => GraphDerivedAccess[];
+    execute: (request: ManagerGraphRequestV3) => Promise<string>;
+};

package/dist/graph/manager.js

@@ -0,0 +1,92 @@
+import { WorkflowReader } from "../workflowReader.js";
+import { assertManagerGraphRequest, parseStrictJson } from "rafi-spec";
+import { loadGraphConfig } from "./config.js";
+import { captureGraphCorpus } from "./corpus.js";
+import { acquireGraphView, graphUnavailable, readGraph } from "./read.js";
+import { canonical } from "./util.js";
+export const MANAGER_GRAPH_GUIDANCE = `For substantial architecture/dependency questions, request graph evidence through this additional host envelope: {"kind":"manager_graph_evidence_request","version":3,"requestId":"unique-id","operations":[{"operation":"query","query":"specific source concepts"}]}. Do not mix envelopes. This shares your existing evidence lookup budget. Only the host chooses project/source scope. An optional receiptId can select previously delivered evidence belonging to the host-selected run; unavailable historical caches stay unavailable. Current-source graph evidence cannot establish a historical run's implementation or cause. Graph output never authorizes controls.`;
+export function parseManagerGraphRequest(text) {
+    if (Buffer.byteLength(text) > 8192 || !text.trim().startsWith("{"))
+        return undefined;
+    let value;
+    try {
+        value = parseStrictJson(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== "object" || value.kind !== "manager_graph_evidence_request")
+        return undefined;
+    if (value.version !== 3)
+        throw new Error("Unsupported Manager graph protocol");
+    assertManagerGraphRequest(value);
+    return value;
+}
+export function createManagerGraphEvidence(configRoot, runId) {
+    const config = loadGraphConfig(configRoot);
+    let deliveredAccess;
+    let initialized = false, view;
+    return {
+        access: () => deliveredAccess ? [deliveredAccess] : [],
+        guidance: config.enabled ? MANAGER_GRAPH_GUIDANCE : "", execute: async (request) => {
+            let unavailable = graphUnavailable(config.reason, "Graph unavailable; use source/runtime evidence");
+            if (config.enabled && !initialized) {
+                initialized = true;
+                try {
+                    const captured = captureGraphCorpus(configRoot, configRoot, config);
+                    const acquired = acquireGraphView(configRoot, configRoot, captured);
+                    if ("graph" in acquired)
+                        view = acquired;
+                    else
+                        unavailable = acquired;
+                }
+                catch (error) {
+                    unavailable = graphUnavailable("freshness-check-failed", String(error));
+                }
+            }
+            let selected = view;
+            if (request.receiptId) {
+                const reader = new WorkflowReader(configRoot);
+                try {
+                    const receipt = reader.graphRecord("receipt", request.receiptId)?.value;
+                    if (!runId || receipt?.runId !== runId || !receipt.generationIds.length) {
+                        selected = undefined;
+                        unavailable = graphUnavailable("invalid-scope", "Receipt is unavailable in the host-selected run");
+                    }
+                    else {
+                        const acquired = acquireGraphView(configRoot, configRoot, undefined, receipt.generationIds[0]);
+                        if ("graph" in acquired)
+                            selected = acquired;
+                        else {
+                            selected = undefined;
+                            unavailable = acquired;
+                        }
+                    }
+                }
+                finally {
+                    reader.close();
+                }
+            }
+            const results = [];
+            for (const operation of request.operations)
+                results.push(selected ? await readGraph(selected, operation) : unavailable);
+            const reader = new WorkflowReader(configRoot);
+            let receipts = [];
+            try {
+                if (runId && request.operations.some(o => o.operation === "status"))
+                    receipts = reader.graphReceiptSummaries(runId);
+            }
+            finally {
+                reader.close();
+            }
+            let packet = canonical({ kind: "manager_graph_evidence", version: 3, requestId: request.requestId, sourceTime: request.receiptId ? "historical receipt-bound navigation; not proof of executed work" : "current-checkout observation; not historical run evidence", results, receipts });
+            if (Buffer.byteLength(packet) > 24 * 1024)
+                packet = canonical({ kind: "manager_graph_evidence", version: 3, requestId: request.requestId, results: [graphUnavailable("packet-limit", "Narrow the request to one focused operation")] });
+            if (selected)
+                deliveredAccess = { policyDigest: config.policyDigest, workspace: configRoot,
+                    exclusionsDigest: selected.generation.files["exclusions-digest"], sourceVersions: config.config?.sourceVersions ?? {},
+                    paths: selected.generation.inputs.filter(i => !i.sourceId).map(i => i.path) };
+            return packet;
+        }
+    };
+}

package/dist/graph/preparation.d.ts

@@ -0,0 +1,41 @@
+import type { BuilderAdapter } from "../adapters/types.js";
+/** One reserved preparation operation owns all optional evidence subturns. */
+export declare function sendPreparationGraphTurn(adapter: BuilderAdapter, instruction: string, input: {
+    phase: "planner" | "prepare" | "assess" | "challenge" | "repair";
+    projectDir: string;
+    workspace: string;
+    accessWorkspace?: string;
+    sourceRef: string;
+    runId: string;
+    workId: string;
+    operationId: string;
+    remainingMs: number;
+}): Promise<{
+    graphReceiptRefs: string[];
+    text: string;
+    isError: boolean;
+    numTurns: number;
+    costUsd: number;
+    costAuthoritative?: boolean;
+    inputTokens?: number;
+    outputTokens?: number;
+    usage?: {
+        scope: "turn-delta" | "session-cumulative";
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        costUsd?: number;
+    };
+    failure?: import("../adapters/types.js").RuntimeFailure;
+    turnId?: string;
+    continuityErrors?: string[];
+    hostInstruction?: string;
+    providerInstruction?: string;
+    rawResponse?: string;
+    cleanedResponse?: string;
+    providerMetadata?: {
+        provider: "claude" | "codex";
+        sessionId?: string;
+        sessionRef?: import("rafi-spec").ProviderSessionRefV1;
+    };
+}>;

package/dist/graph/preparation.js

@@ -0,0 +1,43 @@
+import { OperationDeadline } from "../util/deadline.js";
+import { graphContext, sendGraphTurn } from "./turn.js";
+import { WorkflowReader } from "../workflowReader.js";
+import { inheritGraphDerivedAccess } from "./derived.js";
+import { digest } from "./util.js";
+/** One reserved preparation operation owns all optional evidence subturns. */
+export async function sendPreparationGraphTurn(adapter, instruction, input) {
+    const purpose = input.phase === "planner" ? "planning" : input.phase === "assess" ? "preparation-assessment"
+        : input.phase === "challenge" ? "preparation-challenge" : "qa-preparation";
+    const context = graphContext(input.projectDir, input.workspace, purpose, instruction, {
+        runId: input.runId, workId: input.workId, operationId: input.operationId,
+        logicalTaskId: input.operationId, sourceRef: input.sourceRef, accessWorkspace: input.accessWorkspace,
+    });
+    const policy = { purpose: input.phase === "repair" ? "response-repair"
+            : input.phase === "planner" ? "planning" : "preparation",
+        responseOnly: input.phase === "repair" };
+    const deadline = new OperationDeadline("QA preparation graph exchange", input.remainingMs);
+    let expired = false;
+    const result = await deadline.run(() => sendGraphTurn(adapter, instruction, context, policy, (text, turnPolicy) => {
+        // A read already in flight may finish after timeout. It must not dispatch again.
+        if (expired || deadline.remaining() <= 0)
+            throw new Error("Preparation deadline expired; graph continuation cannot dispatch");
+        return adapter.sendTurn(text, turnPolicy);
+    }), () => { expired = true; void adapter.close().catch(() => { }); });
+    const reader = new WorkflowReader(input.projectDir);
+    try {
+        const session = adapter.sessionId();
+        if (session)
+            inheritGraphDerivedAccess(reader.graphRecord("session-access", digest("session-access", { provider: adapter.agent, session }))?.value.grants ?? []);
+        const exchange = reader.graphRecord("exchange", input.operationId)?.value;
+        const graphReceiptRefs = [];
+        if (exchange)
+            for (let round = 0; round <= exchange.rounds; round++) {
+                const id = `${input.operationId}:${round}`;
+                if (reader.graphRecord("receipt", id))
+                    graphReceiptRefs.push(id);
+            }
+        return { ...result, graphReceiptRefs };
+    }
+    finally {
+        reader.close();
+    }
+}

package/dist/graph/read.d.ts

@@ -0,0 +1,27 @@
+import type { GraphGenerationV1, GraphReadOperationV1, GraphReadResultV1 } from "rafi-spec";
+import { WorkflowReader } from "../workflowReader.js";
+import { type EffectiveGraphConfig } from "./config.js";
+import { type CapturedGraphCorpus } from "./corpus.js";
+export declare function graphScope(workspace: string): string;
+export declare function graphUnavailable(reason: string, detail: string): GraphReadResultV1;
+export declare function sealResult(result: Omit<GraphReadResultV1, "digest">): GraphReadResultV1;
+export declare function graphStatus(configRoot: string, workspace?: string): {
+    enabled: boolean;
+    reason: string;
+    policyDigest: string;
+    generation?: GraphGenerationV1;
+    capability?: unknown;
+    jobs?: ReturnType<WorkflowReader["graphRecentJobs"]>;
+};
+export interface GraphReadView {
+    configRoot: string;
+    workspace: string;
+    config: EffectiveGraphConfig;
+    generation: GraphGenerationV1;
+    graph: Record<string, unknown>;
+    corpus?: CapturedGraphCorpus;
+    python?: string;
+    historical?: boolean;
+}
+export declare function acquireGraphView(configRoot: string, workspace: string, corpus?: CapturedGraphCorpus, historicalGenerationId?: string): GraphReadView | GraphReadResultV1;
+export declare function readGraph(view: GraphReadView, operation: GraphReadOperationV1): Promise<GraphReadResultV1>;