@davesheffer/hunch 1.38.1 → 1.39.1

package/dist/serve/app.js

@@ -16,6 +16,8 @@ import { STATE_PROOF_CAPABILITY } from '../core/stateProof.js';
  *   POST /nuryel/v1/write             → writeState (under the partition's write lock)
  *   POST /nuryel/v1/subscribe         → subscribeState
  *   POST /nuryel/v1/records           → recordsState (by id, grants first)
+ *   POST /nuryel/v1/mcp               → the same verbs as nuryel_* tools over MCP streamable HTTP
+ *                                       (src/serve/mcpHttp.ts), through the same dispatcher
  * Request bodies are the contract's request schemas minus `schema` and `principal`.
  */
 import { createServer } from "node:http";
@@ -30,7 +32,9 @@ import { HUNCH_VERSION } from "../core/version.js";
 import { captureState, captureBatchState } from "../store/stateCapture.js";
 import { STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 import { operatorHtml, operatorCss, operatorJs } from "./operator.js";
+import { MCP_PATH, handleMcpRequest } from "./mcpHttp.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
+const POST_ROUTES = new Map([["/nuryel/v1/read", "read"], ["/nuryel/v1/write", "write"], ["/nuryel/v1/capture", "capture"], ["/nuryel/v1/capture-batch", "capture-batch"], ["/nuryel/v1/subscribe", "subscribe"], ["/nuryel/v1/records", "records"]]);
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
     status;
@@ -119,8 +123,87 @@ export function createServeApp(config, opts = {}) {
         res.writeHead(status, { "content-type": `${type}; charset=utf-8`, "content-length": Buffer.byteLength(text), "cache-control": "no-store", "x-hunch-version": version });
         res.end(text);
     };
-    const sendProblem = (res, p) => {
-        send(res, p.status, { type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra }, "application/problem+json");
+    const problemBody = (p) => ({ type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra });
+    const sendProblem = (res, p) => { send(res, p.status, problemBody(p), "application/problem+json"); };
+    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results). */
+    const problemOf = (error) => {
+        if (error instanceof HttpProblem)
+            return error;
+        if (error instanceof StateRefusal)
+            return problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {});
+        if (error instanceof WriteLockTimeout)
+            return problem(503, "write-lock-timeout", error.message, { "retry-after": 1 });
+        if (error && typeof error === "object" && error.name === "ZodError") {
+            const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
+            return problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues });
+        }
+        return problem(500, "internal", error.message);
+    };
+    /** One authenticated state verb. The REST routes and the MCP tools both call this, so every
+     *  rule — grants, the write lock, flushes, refusals — is the same whichever transport carried it. */
+    const dispatch = async (route, principal, body, activeConfig) => {
+        const requestStore = (scope) => storeFor(scope, activeConfig);
+        const isGranted = (s) => principal.grants.some((g) => scopePath(g) === scopePath(s));
+        if (route === "capabilities") {
+            let scope = principal.grants[0];
+            if (body.scope !== undefined) {
+                const parsed = ScopeSchema.safeParse(body.scope);
+                if (!parsed.success)
+                    throw problem(400, "invalid-scope", "scope must be { kind, id }");
+                scope = parsed.data;
+            }
+            if (!isGranted(scope))
+                throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
+            const offered = capabilities(requestStore(scope).store);
+            return { status: 200, payload: { ...offered, capabilities: [...offered.capabilities, STATE_PROOF_CAPABILITY], principal: { id: principal.id, kind: principal.kind, grants: principal.grants } } };
+        }
+        // The body never names the principal: the credential did.
+        delete body.principal;
+        delete body.schema;
+        const scope = requireScope(principal, body);
+        // Only authenticated grants select stores for cross-partition source visibility.
+        const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
+        const { store, root } = requestStore(scope);
+        const flush = (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message);
+        if (route === "read") {
+            if (body.observed_page !== undefined && body.scopes !== undefined)
+                throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
+            if (body.scopes === undefined) {
+                const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body }, accessOptions);
+                return { status: 200, payload: { ...response, envelope } };
+            }
+            // Union read. The primary `scope` was gated above as always; every extra scope is
+            // either granted (read from ITS partition — 404 no-partition if this server lacks it)
+            // or named in denied_scopes. One ungranted extra never refuses the whole call.
+            const requested = ReadScopesSchema.safeParse(body.scopes);
+            if (!requested.success)
+                throw problem(400, "invalid-scope", "scopes must be 1..64 entries of { kind, id }");
+            const { scopes: _scopes, ...rest } = body;
+            const ungranted = requested.data.filter((s) => !isGranted(s));
+            const others = new Map();
+            for (const s of requested.data)
+                if (isGranted(s) && scopePath(s) !== scopePath(scope) && !others.has(scopePath(s)))
+                    others.set(scopePath(s), s);
+            const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope }, accessOptions);
+            const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(requestStore(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }, accessOptions).response), ungranted);
+            return { status: 200, payload: { ...merged, envelope: primary.envelope } };
+        }
+        if (route === "write" || route === "capture" || route === "capture-batch") {
+            const { hunchDir } = stateHomeFor(store, scope);
+            const opts = { ...accessOptions, flush };
+            if (route === "write") {
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts));
+                return { status: result.outcome === "created" ? 201 : 200, payload: result };
+            }
+            if (route === "capture") {
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts));
+                return { status: result.outcome === "created" ? 201 : 200, payload: result };
+            }
+            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts)) };
+        }
+        if (route === "subscribe")
+            return { status: 200, payload: subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions) };
+        return { status: 200, payload: recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions) };
     };
     const server = createServer(async (req, res) => {
         try {
@@ -131,7 +214,6 @@ export function createServeApp(config, opts = {}) {
             catch {
                 throw problem(503, 'configuration-unavailable', 'server configuration is unavailable; authentication is refused');
             }
-            const requestStore = (scope) => storeFor(scope, activeConfig);
             const url = new URL(req.url ?? "/", "http://127.0.0.1");
             // Public shell only: all workspace data still uses the authenticated state routes below.
             const asset = new Map([["/operator", [operatorHtml, "text/html"]], ["/operator/", [operatorHtml, "text/html"]], ["/operator.css", [operatorCss, "text/css"]], ["/operator.js", [operatorJs, "text/javascript"]]]).get(url.pathname);
@@ -171,101 +253,34 @@ export function createServeApp(config, opts = {}) {
                 throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
             const principal = { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
-                const scope = parseScopeParam(url.searchParams.get("scope")) ?? principal.grants[0];
-                if (!principal.grants.some((g) => scopePath(g) === scopePath(scope)))
-                    throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
-                const { store } = requestStore(scope);
-                const offered = capabilities(store);
-                return send(res, 200, { ...offered, capabilities: [...offered.capabilities, STATE_PROOF_CAPABILITY], principal: { id: principal.id, kind: principal.kind, grants: principal.grants } });
+                const scope = parseScopeParam(url.searchParams.get("scope"));
+                const { status, payload } = await dispatch("capabilities", principal, scope ? { scope } : {}, activeConfig);
+                return send(res, status, payload);
             }
-            if (req.method !== "POST")
-                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
-            const body = await readBody(req);
-            // The body never names the principal: the token did.
-            delete body.principal;
-            delete body.schema;
-            // Only authenticated grants select stores for cross-partition source visibility.
-            const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
-            if (url.pathname === "/nuryel/v1/read") {
-                const scope = requireScope(principal, body);
-                if (body.observed_page !== undefined && body.scopes !== undefined)
-                    throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
-                const { store } = requestStore(scope);
-                if (body.scopes === undefined) {
-                    const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body }, accessOptions);
-                    return send(res, 200, { ...response, envelope });
+            if (url.pathname === MCP_PATH) {
+                // Stateless MCP: no server-initiated stream to open (GET) and no session to end (DELETE).
+                if (req.method !== "POST") {
+                    res.setHeader("allow", "POST");
+                    throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}; MCP here is stateless POST`);
                 }
-                // Union read. The primary `scope` was gated above as always; every extra scope is
-                // either granted (read from ITS partition — 404 no-partition if this server lacks it)
-                // or named in denied_scopes. One ungranted extra never refuses the whole call.
-                const requested = ReadScopesSchema.safeParse(body.scopes);
-                if (!requested.success)
-                    throw problem(400, "invalid-scope", "scopes must be 1..64 entries of { kind, id }");
-                const { scopes: _scopes, ...rest } = body;
-                const isGranted = (s) => principal.grants.some((g) => scopePath(g) === scopePath(s));
-                const ungranted = requested.data.filter((s) => !isGranted(s));
-                const others = new Map();
-                for (const s of requested.data)
-                    if (isGranted(s) && scopePath(s) !== scopePath(scope) && !others.has(scopePath(s)))
-                        others.set(scopePath(s), s);
-                const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope }, accessOptions);
-                const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(requestStore(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }, accessOptions).response), ungranted);
-                return send(res, 200, { ...merged, envelope: primary.envelope });
-            }
-            if (url.pathname === "/nuryel/v1/write") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, result.outcome === "created" ? 201 : 200, result);
-            }
-            if (url.pathname === "/nuryel/v1/capture") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, result.outcome === "created" ? 201 : 200, result);
-            }
-            if (url.pathname === "/nuryel/v1/capture-batch") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, 200, result);
+                const message = await readBody(req);
+                return await handleMcpRequest(req, res, message, (route, body) => dispatch(route, principal, body, activeConfig), (error) => problemBody(problemOf(error)), version);
             }
-            if (url.pathname === "/nuryel/v1/subscribe") {
-                const scope = requireScope(principal, body);
-                const { store } = requestStore(scope);
-                return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions));
-            }
-            if (url.pathname === "/nuryel/v1/records") {
-                const scope = requireScope(principal, body);
-                const { store } = requestStore(scope);
-                return send(res, 200, recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions));
-            }
-            throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
+            if (req.method !== "POST")
+                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
+            const route = POST_ROUTES.get(url.pathname);
+            if (!route)
+                throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
+            const { status, payload } = await dispatch(route, principal, await readBody(req), activeConfig);
+            return send(res, status, payload);
         }
         catch (error) {
-            if (error instanceof HttpProblem)
-                return sendProblem(res, error);
-            if (error instanceof StateRefusal)
-                return sendProblem(res, problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {}));
-            if (error instanceof WriteLockTimeout)
-                return sendProblem(res, problem(503, "write-lock-timeout", error.message, { "retry-after": 1 }));
-            if (error && typeof error === "object" && error.name === "ZodError") {
-                const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
-                return sendProblem(res, problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues }));
+            // An MCP response may already be on the wire; a second status line would corrupt it.
+            if (res.headersSent) {
+                res.end();
+                return;
             }
-            return sendProblem(res, problem(500, "internal", error.message));
+            return sendProblem(res, problemOf(error));
         }
     });
     const closeStores = () => { for (const store of stores.values())

package/dist/serve/mcpHttp.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCP over streamable HTTP for `hunch serve` — the nuryel.state/1 tools behind the same
+ * authenticated server, so an HTTP MCP client (an agent gateway, a remote orchestrator) can
+ * add the state layer as a tool target without a stdio process or a wrapper.
+ *
+ * A binding of the served routes, never a second implementation: every tool call goes through
+ * the dispatcher `createServeApp` uses for REST, so grants, the write lock, flushes and refusals
+ * are identical. The credential already resolved the principal before this runs; no tool
+ * accepts one. Stateless (a fresh server and transport per request, no session id) with JSON
+ * responses, because every verb is a single request/response.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const MCP_PATH = "/nuryel/v1/mcp";
+export type StateRoute = "capabilities" | "read" | "write" | "capture" | "capture-batch" | "subscribe" | "records";
+export type StateDispatch = (route: StateRoute, body: Record<string, unknown>) => Promise<{
+    status: number;
+    payload: unknown;
+}>;
+export interface ProblemShape {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [extra: string]: unknown;
+}
+/** Serve one authenticated MCP POST. The caller has already authenticated and parsed the body. */
+export declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, body: unknown, dispatch: StateDispatch, problemOf: (error: unknown) => ProblemShape, version: string): Promise<void>;

package/dist/serve/mcpHttp.js

@@ -0,0 +1,95 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+// The web-standard transport, not the Node one: the Node wrapper imports @hono/node-server,
+// which the production dependency audit keeps unreachable (tooling/production-dependency-audit.mjs).
+// Bridging IncomingMessage → Request → ServerResponse here is a few lines and keeps that boundary.
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { CaptureBatchRequestSchema, CaptureRequestSchema, ReadRequestSchema, RecordsRequestSchema, ScopeSchema, SubscribeRequestSchema, WriteRequestSchema } from "../core/stateContract.js";
+export const MCP_PATH = "/nuryel/v1/mcp";
+const TOOLS = [
+    {
+        name: "nuryel_capabilities", route: "capabilities",
+        title: "nuryel.state/1 — what this state server supports",
+        description: "Negotiate before depending on anything: the contract version, capability list (verbs + record schemas) and your principal's grants. Optional scope {kind, id} selects a granted partition; default is your first grant.",
+        input: { scope: ScopeSchema.optional() },
+    },
+    {
+        name: "nuryel_read", route: "read",
+        title: "nuryel.state/1 read — the system-of-record answer for a subject",
+        description: "Read current state for a scope under a delivery receipt. Pass a subject (an entity id, a decision topic, or an external object_type:object_key such as transaction:TX-1) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — with the referenced records. Read before redoing work: if a current record already answers the subject and nothing it depends on changed, reuse it. Your identity comes from your credential; scopes outside your grants are named in denied_scopes.",
+        input: ReadRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+    {
+        name: "nuryel_write", route: "write",
+        title: "nuryel.state/1 write — provenance + idempotency in, durability out",
+        description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, decisions, constraints, bugs, findings). The record must carry provenance and the request an idempotency_key: replaying the same request returns the original; the same key with a different payload is refused and the refusal names what differs. Ids are derived from the record's facts. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. The result reports durability (local, committed or pushed).",
+        input: WriteRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+    {
+        name: "nuryel_capture", route: "capture",
+        title: "nuryel.state/1 capture — one relevant assertion with exact source excerpts",
+        description: "Save ONE relevant atomic assertion learned during the task, with a concrete future-use reason and exact excerpts from the source text. Whole source text is never stored. Saved observations are not verified current summaries or receipts.",
+        input: CaptureRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+    {
+        name: "nuryel_capture_batch", route: "capture-batch",
+        title: "nuryel.state/1 capture batch — save relevant atomic observations",
+        description: "Save up to 32 independent assertions from up to 8 sources in one call, each with exact supporting excerpts and a future-use reason. Results preserve input indexes; inspect every refusal.",
+        input: CaptureBatchRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+    {
+        name: "nuryel_subscribe", route: "subscribe",
+        title: "nuryel.state/1 subscribe — the scope's ordered change stream after a cursor",
+        description: "Return change events for a scope with seq > after_seq, strictly ordered. Keep head_seq as your next cursor; if resync is true, rebuild held state with reads.",
+        input: SubscribeRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+    {
+        name: "nuryel_records", route: "records",
+        title: "nuryel.state/1 records — fetch records by id, grants first",
+        description: "Fetch state records by id (from a subscribe event, a read ref or a write result). Every id is accounted for: found, denied (outside your grants) or missing.",
+        input: RecordsRequestSchema.omit({ schema: true, principal: true }).shape,
+    },
+];
+function buildServer(dispatch, problemOf, version) {
+    const server = new McpServer({ name: "hunch-serve", version });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.input }, async (input) => {
+            try {
+                const { payload } = await dispatch(tool.route, { ...input });
+                return { content: [{ type: "text", text: JSON.stringify(payload) }], structuredContent: payload };
+            }
+            catch (error) {
+                const p = problemOf(error);
+                return { isError: true, content: [{ type: "text", text: `nuryel.state/1 refused [${p.title}] (${p.status}): ${p.detail}` }], structuredContent: p };
+            }
+        });
+    }
+    return server;
+}
+/** Serve one authenticated MCP POST. The caller has already authenticated and parsed the body. */
+export async function handleMcpRequest(req, res, body, dispatch, problemOf, version) {
+    const server = buildServer(dispatch, problemOf, version);
+    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    try {
+        await server.connect(transport);
+        // Only the headers the transport negotiates on travel; the body was already read and bounded.
+        const headers = new Headers();
+        for (const name of ["accept", "content-type", "mcp-protocol-version", "mcp-session-id", "last-event-id"]) {
+            const value = req.headers[name];
+            if (typeof value === "string")
+                headers.set(name, value);
+        }
+        const request = new Request(new URL(req.url ?? MCP_PATH, "http://127.0.0.1"), { method: "POST", headers, body: JSON.stringify(body) });
+        const response = await transport.handleRequest(request, { parsedBody: body });
+        const text = await response.text();
+        const out = { "cache-control": "no-store", "x-hunch-version": version, "content-length": String(Buffer.byteLength(text)) };
+        response.headers.forEach((value, name) => { if (name !== "content-length")
+            out[name] = value; });
+        res.writeHead(response.status, out);
+        res.end(text);
+    }
+    finally {
+        await transport.close();
+        await server.close();
+    }
+}
+//# sourceMappingURL=mcpHttp.js.map

package/dist/store/hunchStore.d.ts

@@ -5,7 +5,7 @@ import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { type RankingContext, type RankingQuery, type RankingWeights, type SlotOptions, type TaskSelection } from "../core/taskRanking.js";
 import { type VetoTier } from "../core/strictgate.js";
-import { type DiffAnalysis } from "../extractors/diff.js";
+import { type DiffAnalysis, type DiffStatus } from "../extractors/diff.js";
 import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
 import { type ReviewedLandscapeSelection } from "../core/landscapeDelivery.js";
 import { type StateSlice } from "../core/stateDelivery.js";
@@ -384,7 +384,7 @@ export declare class HunchStore {
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
      *  scope-matched constraints, why) so impact and gating can never disagree. */
-    prImpact(files: string[], diff: string): ImpactReport;
+    prImpact(files: string[], diff: string, diffStatus?: DiffStatus): ImpactReport;
     /** Structure view (hunch_structure / hunch structure): serve the indexed shape of
      *  the repo so an agent ORIENTS from the graph instead of running grep/glob rounds.
      *  Resolution: no target -> repo map; a directory -> its files+symbols; a file ->
@@ -446,6 +446,8 @@ export declare class HunchStore {
         strict: boolean;
         lastChange?: (f: string) => string;
         publicOnly?: boolean;
+        /** Completeness of `diff` as produced for a gate (a GateDiff fits). */
+        diffStatus?: DiffStatus;
     }): CheckReport;
     /** Sprawl/"this already exists" guard (ADVISORY, never blocks). A symbol the diff
      *  ADDS whose name already exists in the indexed graph in a file NOT touched by the

package/dist/store/hunchStore.js

@@ -28,7 +28,7 @@ import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
-import { analyzeDiff } from "../extractors/diff.js";
+import { analyzeDiff, diffContentGaps } from "../extractors/diff.js";
 import { selectReviewedLandscape, } from "../core/landscapeDelivery.js";
 import { STATE_KINDS, STATE_SLICE_CAPS, compareStateHits, isStateKind, stateLiveness, stateObservedAt, stateSearchDoc, stateSubject, } from "../core/stateDelivery.js";
 /** Git cannot resolve repository identity from a cwd that does not exist yet.
@@ -1332,7 +1332,7 @@ export class HunchStore {
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
      *  scope-matched constraints, why) so impact and gating can never disagree. */
-    prImpact(files, diff) {
+    prImpact(files, diff, diffStatus) {
         const changed = new Set(files.map(toPosixTarget));
         const blast = new Map();
         for (const f of changed) {
@@ -1344,7 +1344,7 @@ export class HunchStore {
                     blast.set(b.file, b);
             }
         }
-        const report = this.buildCheckReport([...changed], diff, { strict: false });
+        const report = this.buildCheckReport([...changed], diff, { strict: false, diffStatus });
         const decisions = new Map();
         for (const f of changed) {
             for (const d of this.why(f).decisions)
@@ -1639,6 +1639,7 @@ export class HunchStore {
             });
             const directReport = [];
             const addedDepSet = new Set(an.addedDeps);
+            const missingContent = diffContentGaps(diff, opts.diffStatus);
             for (const { c, files: fs } of direct.values()) {
                 const forbids = effectiveForbids(c);
                 if (forbids) {
@@ -1646,11 +1647,27 @@ export class HunchStore {
                     // dep imported / symbol added / pattern matched in scoped code) — not by bare
                     // scope-touch. A commit that touches the scope but doesn't trip it COMPLIES → drop it
                     // (no noise). A real hit blocks WITHOUT the staleness gate: content is verified per
-                    // commit, so file churn can't retract the teeth (dec_e0a36efbf5). Empty diff ⇒ can't
-                    // prove a violation ⇒ treat as clean.
+                    // commit, so file churn can't retract the teeth (dec_e0a36efbf5). A COMPLETE diff with
+                    // no added lines for a file proves nothing was added there ⇒ clean.
                     const scopedAdded = fs.flatMap((f) => an.addedLinesByFile.get(f) ?? []);
-                    if (!matchForbids(forbids, addedDepSet, scopedAdded))
+                    if (!matchForbids(forbids, addedDepSet, scopedAdded)) {
+                        // …but when the diff is truncated, git could not produce it, or a file's content
+                        // could not be read, "no added lines" is not evidence of compliance. A blocking
+                        // rule over such a file is UNEVALUABLE and fails closed under the same strict gate
+                        // a proven hit would face (dec_20db57c576). Advisory/warning rules stay quiet.
+                        const unseen = missingContent ? fs.filter((f) => missingContent.missing(f)) : [];
+                        if (c.severity !== "blocking" || !unseen.length)
+                            continue;
+                        const strictBlocks = isStrictBlocker(c, false);
+                        directReport.push({
+                            id: c.id, severity: c.severity, statement: c.statement, rationale: c.rationale ?? "",
+                            files: fs, strictBlocks,
+                            downgrade: strictBlocks ? undefined : "low-confidence",
+                            unevaluable: { reason: missingContent.reason(unseen), files: unseen },
+                            why: this.causalChain(c.id),
+                        });
                         continue;
+                    }
                     const strictBlocks = isStrictBlocker(c, false);
                     directReport.push({
                         id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",