@davesheffer/hunch 1.29.0 → 1.31.0

package/dist/mcp/server.js

@@ -57,8 +57,17 @@ import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken }
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { initiatorFromClient, withInitiator } from "../synthesis/initiator.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** Error classes as text prefixes — client-agnostic, no schema change, so any MCP client
+ *  can pick its next move from the first word:
+ *    Refused: …    a gate held. Do not retry the same call; resolve the named conflict or ask a human.
+ *    Invalid: …    the arguments are wrong. Fix them and call again.
+ *    Failed to …   internal or environmental. One retry is reasonable.
+ *  Transient states that say "retry" in their own words stay unprefixed. */
+const refused = (text) => err(`Refused: ${text}`);
+const invalid = (text) => err(`Invalid: ${text}`);
 /** Shared by every auto-committing write tool (issue #20): the MCP `roots` protocol
  *  cannot see an agent-driven `cd`/EnterWorktree, so a stdio server's cached root
  *  never moves on its own — this is the client-agnostic fallback, resolved fresh on
@@ -700,17 +709,17 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // root/store/route epoch for its complete execution.
             const teamFileNow = !explicitOverlay && existsSync(teamFile);
             if (teamFileNow !== teamAdvertised) {
-                return err("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
+                return refused("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
             }
             const currentTeamConfig = teamFileNow ? readTeamConfig(root) : null;
             if (teamAdvertised && !matchesStartupTeamRoute()) {
-                return err("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
+                return refused("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
             }
             if (teamFileNow && (!currentTeamConfig
                 || store.mode !== "shared"
                 || !store.privateDir
                 || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
-                return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
+                return refused("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
             }
             if (store.mode === "shared" && store.privateDir) {
                 pullTeamMemory();
@@ -719,7 +728,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 // blocked; serving after that race would attach the old checkout to a new
                 // destination even though the pull itself correctly refused.
                 if (teamAdvertised && !matchesStartupTeamRoute()) {
-                    return err("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
+                    return refused("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
                 }
             }
             // Stamp check in EVERY mode, not only shared: a CLI capture or post-commit
@@ -733,9 +742,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     refreshIndex();
             }
             catch { /* corrupt/churning local source — serve the last durable indexed view */ }
-            const result = await callback(...args);
+            const result = await withInitiator(initiatorFromClient(server.server.getClientVersion()?.name), () => callback(...args));
             if (teamAdvertised && !matchesStartupTeamRoute()) {
-                return err("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
+                return refused("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
             }
             return result;
         }
@@ -747,7 +756,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_query ----------------------------------------------------------
     server.registerTool("hunch_query", {
         title: "Query Hunch",
-        description: "Full-text + graph search across the engineering memory (decisions, bugs, constraints, components, symbols). Returns ranked records with provenance. Use this to ask 'why' questions about the codebase.",
+        description: "Full-text + graph search across the engineering memory (decisions, bugs, constraints, components, symbols). Returns ranked records with provenance. Use this to ask 'why' questions about the codebase. Not for orienting on a known file or symbol (hunch_context / hunch_why give the curated slice with its blast radius) or for finding where code lives (hunch_structure).",
         inputSchema: { query: z.string().describe("A natural-language question or keywords.") },
     }, async ({ query }) => {
         const hits = await store.hybridSearch(query, QUERY_HITS, { embedder: await embedderReady });
@@ -762,7 +771,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_runbook --------------------------------------------------------
     server.registerTool("hunch_runbook", {
         title: "Find a runbook for a task",
-        description: "Look up the proven 'how-to' (ordered steps + files) for a recurring task — runbook-SCOPED retrieval (searches within runbooks, not the whole graph). Use at the START of a task to reuse a known procedure instead of re-deriving it. Advisory.",
+        description: "Look up the proven 'how-to' (ordered steps + files) for a recurring task — runbook-SCOPED retrieval (searches within runbooks, not the whole graph). Use at the START of a task to reuse a known procedure instead of re-deriving it. Advisory. Not for design rationale (hunch_why) or free-text memory search (hunch_query).",
         inputSchema: { task: z.string().describe("The task/intent, e.g. 'add an MCP tool' or 'cut a release'.") },
     }, async ({ task }) => {
         const hits = await store.searchRunbooks(task, 5, { embedder: await embedderReady });
@@ -781,7 +790,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_why ------------------------------------------------------------
     server.registerTool("hunch_why", {
         title: "Explain why a file/symbol is the way it is",
-        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence. Pass `as_of` (a commit/tag/branch) to time-travel: see what was believed at that point in history.",
+        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence. Pass `as_of` (a commit/tag/branch) to time-travel: see what was believed at that point in history. Use when you need the full rationale for ONE target. Not for a budgeted task brief (hunch_context), keyword search (hunch_query), or where-is-it questions (hunch_structure).",
         inputSchema: {
             target: z.string().describe("A file path (e.g. src/auth/session.ts) or symbol name."),
             as_of: z.string().optional().describe("Time-travel ref: a commit sha, tag, or branch (e.g. v0.7.0). Omit for the current view."),
@@ -789,7 +798,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ target, as_of }) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
-            return err(`Could not resolve as_of "${as_of}" to a commit.`);
+            return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
         const w = store.why(target, { asOf });
         // Highest-signal first, then cap: invariants by severity, decisions by
         // confidence, bugs by severity — so a hot file's trim drops the tail, not
@@ -830,7 +839,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_check_constraints ---------------------------------------------
     server.registerTool("hunch_check_constraints", {
         title: "Check invariants in scope",
-        description: "Return constraints whose scope matches a glob/path, sorted by severity. Call this BEFORE editing code to avoid breaking intentional invariants.",
+        description: "Return constraints whose scope matches a glob/path, sorted by severity. Call this BEFORE editing code to avoid breaking intentional invariants. Returns each constraint's id, severity, enforcement, statement, and rationale. Not for who-depends-on-this (hunch_get_dependents) or invariants reachable only through dependents (hunch_blast_radius).",
         inputSchema: { scope: z.string().describe("A path or glob, e.g. src/auth/** or src/auth/session.ts") },
     }, async ({ scope }) => {
         const cons = store.checkConstraints(scope);
@@ -842,7 +851,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_get_dependents -------------------------------------------------
     server.registerTool("hunch_get_dependents", {
         title: "Blast radius (transitive dependents)",
-        description: "Return everything that transitively depends on a symbol/component (callers + dependent components) so a change's blast radius is known before editing.",
+        description: "Return everything that transitively depends on a symbol/component (callers + dependent components) so a change's blast radius is known before editing. Returns dependents nearest first with depth and edge kind. Not for the invariants those dependents carry (hunch_blast_radius) or constraints on the target itself (hunch_check_constraints).",
         inputSchema: { symbol: z.string().describe("A symbol id, symbol name, or file path.") },
     }, async ({ symbol }) => {
         const matches = resolveSymbols(store, symbol);
@@ -863,7 +872,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_blast_radius (dependents + near-violations) --------------------
     server.registerTool("hunch_blast_radius", {
         title: "Blast radius + near-violations for a file",
-        description: "Given a file you're about to change, return its dependency blast radius (files whose code depends on it) AND any invariants reached THROUGH that radius — 'near-violations' you could break indirectly without touching their own scope. Call before editing a widely-depended-on file. Mirrors `hunch check --blast`.",
+        description: "Given a file you're about to change, return its dependency blast radius (files whose code depends on it) AND any invariants reached THROUGH that radius — 'near-violations' you could break indirectly without touching their own scope. Call before editing a widely-depended-on file. Mirrors `hunch check --blast`. Not for a bare dependent list (hunch_get_dependents) or constraints scoped to the target alone (hunch_check_constraints).",
         inputSchema: { target: z.string().describe("A file path (e.g. src/auth/jwt.ts) or symbol.") },
     }, async ({ target }) => {
         const parts = [];
@@ -917,7 +926,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_change_proof (exact-revision semantic evidence) ----------------
     server.registerTool("hunch_change_proof", {
         title: "Derive a sealed semantic proof for an exact change",
-        description: "Bind an exact committed Git transition to its change identity, Project DNA, base/result semantic graphs, current decisions and constraints, blast radius, conformance, guard verdict, and explicit gaps. Read-only and deterministic; grants no execution, CI, deployment, merge, ranking, promotion, or policy authority.",
+        description: "Bind an exact committed Git transition to its change identity, Project DNA, base/result semantic graphs, current decisions and constraints, blast radius, conformance, guard verdict, and explicit gaps. Read-only and deterministic; grants no execution, CI, deployment, merge, ranking, promotion, or policy authority. Needs two committed refs. Not for a verdict on staged work (hunch_merge_verdict) or an impact map (hunch_pr_impact).",
         inputSchema: {
             base_ref: z.string().min(1).max(1_024).describe("Base commit or ref for the exact tree transition."),
             result_ref: z.string().min(1).max(1_024).optional().describe("Result commit or ref (default HEAD)."),
@@ -1015,7 +1024,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",
-        description: "Given a file, symbol, or task phrase you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something. A task phrase that resolves to no file/symbol falls back to the closest graph matches.",
+        description: "Given a file, symbol, or task phrase you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something. A task phrase that resolves to no file/symbol falls back to the closest graph matches. Returns a budgeted brief plus a delivery receipt. Not for exhaustive rationale on one file (hunch_why) or keyword search (hunch_query).",
         inputSchema: {
             target: z.string().describe("A file path, symbol, or task phrase you're about to work on."),
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
@@ -1026,7 +1035,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ target, budget_tokens, profile, as_of }, extra) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
-            return err(`Could not resolve as_of "${as_of}" to a commit.`);
+            return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
         const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
         let dnaSupplement = null;
         try {
@@ -1207,7 +1216,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         try {
             const decision = store.advisoryRecs("decisions").find((candidate) => candidate.id === decision_id);
             if (!decision)
-                return err(`Imported ADR ${decision_id} is not present in the current advisory memory home.`);
+                return invalid(`Imported ADR ${decision_id} is not present in the current advisory memory home.`);
             const reviewed = applyImportedAdrReview(decision, {
                 disposition,
                 expectedSourceHash: expected_source_hash,
@@ -1275,7 +1284,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_capture_decision (decision-grounding: the grilling front door) --
     server.registerTool("hunch_capture_decision", {
         title: "Capture a decision (grilling interview)",
-        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess.",
+        description: "Start a decision-capture interview: returns the grilling protocol (interrogate ONE question at a time until the decision tree is resolved) plus a capture-session token. Grill the human, then commit via hunch_record_decision with the token + confirmed topic. Use for '/capture', 'record this decision', 'grill me on this'. The token proves the write is the tail of an interview, not a silent guess. Returns the protocol text and the token; it writes nothing. Not for corrections (hunch_record_correction) or observations (hunch_record_finding).",
         inputSchema: {
             topic: z.string().optional().describe("proposed topic anchor (confirm with the human before committing)"),
             seed: z.string().optional().describe("what the decision is about, to focus the first question"),
@@ -1329,7 +1338,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_decision (write-back) -----------------------------------
     server.registerTool("hunch_record_decision", {
         title: "Record a decision (write-back)",
-        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it. Set private:true to keep a SENSITIVE decision out of a (possibly public) repo — it is written to the HUNCH_PRIVATE_DIR overlay store and stays queryable locally, never committed here.",
+        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it. Set private:true to keep a SENSITIVE decision out of a (possibly public) repo — it is written to the HUNCH_PRIVATE_DIR overlay store and stays queryable locally, never committed here. Returns the stored id, home, and status. Not for a rule the agent must obey (hunch_record_correction) or an observation with no choice made (hunch_record_finding). Errors are classed by prefix: 'Refused:' means a gate held (resolve it, do not retry), 'Invalid:' means fix the arguments, 'Failed to' means internal.",
         inputSchema: {
             decision: z.object({
                 title: z.string(),
@@ -1412,7 +1421,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // displaced by a differently-identified record, vouched or not.
             const conflictsWithHuman = curated && !sameHumanIdentity && !(gated && !existingIsHuman);
             if (conflictsWithHuman) {
-                return err(`Decision id ${id} already identifies a different curated decision: ` +
+                return refused(`Decision id ${id} already identifies a different curated decision: ` +
                     `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
                     `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
                     "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
@@ -1484,7 +1493,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     const crossStore = decision.supersedes && !willClose
                         ? ` (note: supersedes:"${decision.supersedes}" is not in the ${home} store this write lands in, so it can't be closed from here)`
                         : "";
-                    return err(`Topic "${rec.topic}" already has a live decision: ${list}.${crossStore} ` +
+                    return refused(`Topic "${rec.topic}" already has a live decision: ${list}.${crossStore} ` +
                         `Hunch will not create a second current decision for one topic. Resolve it: ` +
                         `re-record with supersedes:<id> to replace it (linked, same store), pick a distinct topic to split, or discard this capture.`);
                 }
@@ -1549,7 +1558,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_correction (write-back: "Never Twice") ------------------
     server.registerTool("hunch_record_correction", {
         title: "Capture a correction as an enforced constraint (Never Twice)",
-        description: "When a human corrects the agent ('no, do it this way' / 'never call X here'), persist that correction as a first-class, SCOPED Constraint with provenance — so the pre-edit hook and the CI Constraint Guard hold EVERY assistant to it from now on, instead of it being forgotten next session. Writes to the shared .hunch/ graph (client-agnostic). Set severity:'blocking' only when the human said never/must; set applies_to_all:true only when the rule is genuinely repo-wide (otherwise it is scoped to scope_hint_file).",
+        description: "When a human corrects the agent ('no, do it this way' / 'never call X here'), persist that correction as a first-class, SCOPED Constraint with provenance — so the pre-edit hook and the CI Constraint Guard hold EVERY assistant to it from now on, instead of it being forgotten next session. Writes to the shared .hunch/ graph (client-agnostic). Set severity:'blocking' only when the human said never/must; set applies_to_all:true only when the rule is genuinely repo-wide (otherwise it is scoped to scope_hint_file). Returns the constraint id, scope, and what it now enforces. Not for a design choice with alternatives (hunch_record_decision) or an observed gap with no rule yet (hunch_record_finding).",
         inputSchema: {
             rule: z.string().describe("The invariant in the human's words, e.g. \"never call the pay-per-token API here\"."),
             scope_hint_file: z.string().optional().describe("A file the correction was about; scopes the constraint to it (the conservative default). Prefer a REPO-RELATIVE path (src/foo.ts); an absolute path is relativized against the repo root, and one outside the repo is discarded rather than scoped to a path that could never match."),
@@ -1565,7 +1574,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async (input) => {
         try {
             if (!input.rule || !input.rule.trim())
-                return err("rule is required — state the invariant in plain words.");
+                return invalid("rule is required — state the invariant in plain words.");
             // root: relativizes an ABSOLUTE scope_hint_file. Agents naturally send absolute
             // paths (edit-tool payloads and MCP roots are absolute) and every consumer matches
             // repo-relative — without this the rule would be blocking-but-inert and would leak
@@ -1581,7 +1590,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const home = store.captureHome(!!input.private);
             if (home === "public" && rec.source_decision && !store.json.get("decisions", rec.source_decision)) {
                 const location = store.getPrivateRec("decisions", rec.source_decision) ? "exists only in the private overlay" : "does not exist in the public home";
-                return err(`Refusing to record public correction ${rec.id}: source decision ${rec.source_decision} ${location}.`);
+                return refused(`source decision ${rec.source_decision} ${location}; refusing to record public correction ${rec.id}.`);
             }
             const existing = home === "private" ? store.getPrivateRec("constraints", rec.id) : store.json.get("constraints", rec.id);
             // Same cross-home twin guard as the decision path above.
@@ -1625,7 +1634,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_record_finding (write-back: observations, no diff) ---------------
     server.registerTool("hunch_record_finding", {
         title: "Record a finding (an observation with no code change)",
-        description: "Persist an OBSERVATION into Hunch — audited knowledge with no diff: an audit that surfaced a gap (e.g. queries missing tenant scoping), a measured number, a vendor/platform fact, an incident with no code fix. The anchor is a date + evidence, not a commit. Advisory: it grounds future edits to the affected files/symbols (pre-edit hook + hunch_context) and is listed by hunch_findings; it never blocks. Re-record the SAME title to update triage (e.g. triage:'resolved' + resolved_commit once fixed). If the finding is a violation of a rule that ISN'T recorded yet, record the rule first (hunch_record_correction) and link it via violates_constraint.",
+        description: "Persist an OBSERVATION into Hunch — audited knowledge with no diff: an audit that surfaced a gap (e.g. queries missing tenant scoping), a measured number, a vendor/platform fact, an incident with no code fix. The anchor is a date + evidence, not a commit. Advisory: it grounds future edits to the affected files/symbols (pre-edit hook + hunch_context) and is listed by hunch_findings; it never blocks. Re-record the SAME title to update triage (e.g. triage:'resolved' + resolved_commit once fixed). If the finding is a violation of a rule that ISN'T recorded yet, record the rule first (hunch_record_correction) and link it via violates_constraint. Returns the finding id, triage, and the files it now grounds. Not for a rule to enforce (hunch_record_correction) or a choice between alternatives (hunch_record_decision).",
         inputSchema: {
             finding: z.object({
                 title: z.string().describe("stable one-line name — re-recording the same title updates the finding"),
@@ -1646,16 +1655,16 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ finding }) => {
         try {
             if (!finding.title.trim())
-                return err("title is required.");
+                return invalid("title is required.");
             if (!finding.observation.trim())
-                return err("observation is required — state what you saw.");
+                return invalid("observation is required — state what you saw.");
             const id = findingId(finding.title);
             const home = store.captureHome(!!finding.private);
             const existing = home === "private" ? store.getPrivateRec("findings", id) : store.json.get("findings", id);
             const now = new Date().toISOString();
             const triage = finding.triage ?? existing?.triage ?? "open";
             if (triage === "resolved" && !(finding.resolved_commit ?? existing?.resolved_commit)) {
-                return err(`Refusing to mark ${id} resolved without resolved_commit — a resolution claim needs the fixing commit (or use triage:'stale' if it no longer applies).`);
+                return refused(`refusing to mark ${id} resolved without resolved_commit — a resolution claim needs the fixing commit (or use triage:'stale' if it no longer applies).`);
             }
             const rec = {
                 id,
@@ -1825,7 +1834,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_findings (read: the open-observations ledger) --------------------
     server.registerTool("hunch_findings", {
         title: "Open findings for a scope",
-        description: "List LIVE findings (observed gaps/debt with no fix yet — triage open/accepted-risk/scheduled) concerning a file, glob, or symbol; omit scope for the whole ledger. Call before planning work in an area to inherit past audits instead of re-discovering them. Advisory; resolved/stale findings are excluded unless all:true.",
+        description: "List LIVE findings (observed gaps/debt with no fix yet — triage open/accepted-risk/scheduled) concerning a file, glob, or symbol; omit scope for the whole ledger. Call before planning work in an area to inherit past audits instead of re-discovering them. Advisory; resolved/stale findings are excluded unless all:true. Not for invariants (hunch_check_constraints) or bug history (hunch_bug_lineage): findings are observations, never rules.",
         inputSchema: {
             scope: z.string().optional().describe("a path, glob, or symbol (e.g. src/procs/** or dbo.GetOrders); omit for all"),
             all: z.boolean().optional().describe("include resolved/stale findings (the full history)"),
@@ -1856,7 +1865,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ constraint_id, public_only, private_only, include_artifacts }) => {
         try {
             if (public_only && private_only)
-                return err("Choose only one of public_only or private_only.");
+                return invalid("Choose only one of public_only or private_only.");
             // Resolve the correction's exact home before any writes. Overlay-first is
             // the same selection contract as ConstitutionService.upgradeCorrection;
             // deriving this later from a policy id is unsafe when legacy public and
@@ -1915,7 +1924,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base, commit, and working to check STAGED changes; pass working:true for all local changes, base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
+        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base, commit, and working to check STAGED changes; pass working:true for all local changes, base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change. Not for an advisory impact map (hunch_pr_impact), intent erosion with no diff (hunch_conformance), or a sealed proof of one committed transition (hunch_change_proof).",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),
@@ -1924,11 +1933,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ base, commit, working }) => {
         try {
             if ([base, commit, working].filter(Boolean).length > 1)
-                return err("Pass at most one of base/commit/working (omit all to check staged changes).");
+                return invalid("Pass at most one of base/commit/working (omit all to check staged changes).");
             if (base && !revExists(base, root))
-                return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
+                return invalid(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
-                return err(`commit "${commit}" does not resolve.`);
+                return invalid(`commit "${commit}" does not resolve.`);
             const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
             const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
@@ -1950,7 +1959,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_structure (graph-served orientation — the anti-grep) ------------
     server.registerTool("hunch_structure", {
         title: "The indexed shape of the repo / a dir / a file / a symbol",
-        description: "Orient WITHOUT grep/glob rounds: the graph already holds the repo's structure. No target → repo map (components + directories by symbol weight). A directory → its files with their symbols. A file → its outline (symbols, fan-in/out, callers). An exact symbol name → its definition site(s) with one-hop neighbors. Call this FIRST when exploring unfamiliar code — it tells you exactly which file to read, instead of searching for it.",
+        description: "Orient WITHOUT grep/glob rounds: the graph already holds the repo's structure. No target → repo map (components + directories by symbol weight). A directory → its files with their symbols. A file → its outline (symbols, fan-in/out, callers). An exact symbol name → its definition site(s) with one-hop neighbors. Call this FIRST when exploring unfamiliar code — it tells you exactly which file to read, instead of searching for it. Returns shape only (files, symbols, one-hop neighbors), never why. Not for rationale (hunch_why) or memory search (hunch_query).",
         inputSchema: {
             target: z.string().optional().describe("A directory, file path, or exact symbol name. Omit for the repo map."),
         },
@@ -1958,7 +1967,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",
-        description: "Given a change (staged, working tree, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base, commit, and working for staged changes.",
+        description: "Given a change (staged, working tree, a branch vs base, or a single commit), return its IMPACT SURFACE: the files whose code transitively depends on the changed files, the invariants directly in scope and those reached via blast radius, and the recorded decisions concerning the touched files. Read-only and advisory — use hunch_merge_verdict for the gate. Call before review to know what a PR can break and which recorded intent it touches. Omit base, commit, and working for staged changes. Not for a verdict (hunch_merge_verdict) or a sealed proof (hunch_change_proof).",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Impact of a single commit (sha/ref). Omit base AND commit for staged changes."),
@@ -1967,11 +1976,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     }, async ({ base, commit, working }) => {
         try {
             if ([base, commit, working].filter(Boolean).length > 1)
-                return err("Pass at most one of base/commit/working (omit all for staged changes).");
+                return invalid("Pass at most one of base/commit/working (omit all for staged changes).");
             if (base && !revExists(base, root))
-                return err(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
+                return invalid(`base ref "${base}" does not resolve (in CI, fetch the base branch first).`);
             if (commit && !revExists(commit, root))
-                return err(`commit "${commit}" does not resolve.`);
+                return invalid(`commit "${commit}" does not resolve.`);
             const files = commit ? commitFiles(commit, root) : base ? rangeFiles(base, root) : working ? workingFiles(root) : stagedFiles(root);
             const scope = commit ? `commit ${commit}` : base ? `${base}..HEAD` : working ? "working changes" : "staged changes";
             if (!files.length)
@@ -1996,9 +2005,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         const A = store.resolveNodeIds(from);
         const B = store.resolveNodeIds(to);
         if (!A.length)
-            return err(`"${from}" resolves to no indexed symbol/component (is the repo indexed?).`);
+            return invalid(`"${from}" resolves to no indexed symbol/component (is the repo indexed?).`);
         if (!B.length)
-            return err(`"${to}" resolves to no indexed symbol/component.`);
+            return invalid(`"${to}" resolves to no indexed symbol/component.`);
         let best = null;
         for (const a of A.slice(0, 4)) {
             for (const b of B.slice(0, 4)) {
@@ -2024,9 +2033,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         try {
             const b = base ?? "main";
             if (!candidates.length)
-                return err("Pass at least one candidate ref.");
+                return invalid("Pass at least one candidate ref.");
             if (!revExists(b, root))
-                return err(`base ref "${b}" does not resolve (in CI, fetch it first).`);
+                return invalid(`base ref "${b}" does not resolve (in CI, fetch it first).`);
             const ranked = compareCandidates(store, root, b, candidates);
             const icon = (v) => (v === "pass" ? "✅" : v === "warn" ? "⚠" : "⛔");
             const lines = ranked.map((c, i) => c.error
@@ -2244,7 +2253,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_conformance ----------------------------------------------------
     server.registerTool("hunch_conformance", {
         title: "Does the code still satisfy the recorded intent?",
-        description: "Intent-conformance (the inversion of a normal guard): for every in-force decision carrying a conformance predicate, deterministically verify the CODE still satisfies its intent over the dependency graph — e.g. 'pay still reaches verifySession'. Returns the violations: intent the code has silently drifted away from, with NO diff required. Run before a refactor or merge to catch intent erosion a diff-only check can't see.",
+        description: "Intent-conformance (the inversion of a normal guard): for every in-force decision carrying a conformance predicate, deterministically verify the CODE still satisfies its intent over the dependency graph — e.g. 'pay still reaches verifySession'. Returns the violations: intent the code has silently drifted away from, with NO diff required. Run before a refactor or merge to catch intent erosion a diff-only check can't see. Returns the violation list. Not for a diff-scoped verdict (hunch_merge_verdict) or an impact map (hunch_pr_impact).",
         inputSchema: {},
     }, async () => {
         try {

package/dist/store/replay.js

@@ -0,0 +1,153 @@
+/**
+ * Replay determinism — nuryel.replay/1.
+ *
+ * The property: a partition's current state is a pure function of its change ledger. The
+ * git-tracked JSON records stay the source of truth (the ledger proves them, it never replaces
+ * them); this module FOLDS the ledger into the state it implies — for every record the ledger
+ * names, the hash of the record on file after its last event — and compares that, hash for hash,
+ * to the records actually stored. `stateHash` is sha256 over the canonical form, so equal hashes
+ * are byte-equal canonical records: "same ledger, same state" is a check, not a claim.
+ *
+ * What counts as a divergence:
+ *   missing-record   the ledger says the record exists, no file holds it
+ *   hash-drift       the record on file is not the record the ledger's last event wrote
+ *   orphan-record    a state record in the partition that the ledger never saw (a write that
+ *                    bypassed the contract, or a crash between "record written" and "event
+ *                    appended" — the failure changeLedger promised the next writer could detect)
+ *   idempotency-drift an idempotency entry whose hash disagrees with the ledger at its seq
+ * Legacy facets (decisions, constraints, bugs, findings) are also written by paths older than the
+ * contract (captures, supersede, adopt-drafts), so their drift is reported as `legacy-drift` —
+ * visible, never a failure — and their orphans are not sought.
+ *
+ * Compaction keeps replay equivalence: events below the floor are gone, but the idempotency table
+ * is kept whole, so a record whose last event was compacted is still verified against its newest
+ * idempotency entry; a record with neither is `unverifiable`, counted, never a failure.
+ */
+import { ENTITY_KINDS } from "../core/types.js";
+import { ScopeSchema, scopePath, stateHash } from "../core/stateContract.js";
+import { readLedger } from "./changeLedger.js";
+import { partitionOf, stateHomeFor } from "./stateBinding.js";
+export const REPLAY_SCHEMA_VERSION = "nuryel.replay/1";
+/** The facets the contract is the ONLY writer of; a record here without a ledger event is an orphan. */
+export const STATE_ONLY_FACETS = ["receipts", "commitments", "derived", "entities", "relationships"];
+const LEGACY_FACETS = new Set(["decisions", "constraints", "bugs", "findings"]);
+/** Fold a ledger into the state it implies: the last event per record, in seq order. */
+export function foldLedger(ledger) {
+    const out = new Map();
+    for (const e of ledger.events) {
+        out.set(e.record_id, { facet: e.facet, record_id: e.record_id, record_hash: e.record_hash, change: e.change, seq: e.seq });
+    }
+    return out;
+}
+const snapshotHash = (entries) => stateHash([...entries].sort((a, b) => (a.record_id < b.record_id ? -1 : a.record_id > b.record_id ? 1 : 0)).map((e) => [e.facet, e.record_id, e.record_hash]));
+const recordScope = (record, own) => {
+    const parsed = ScopeSchema.safeParse(record.scope);
+    return parsed.success ? parsed.data : own;
+};
+const windowClosed = (facet, record) => (facet === "derived" && record.state !== "current") || ("valid_to" in record && record.valid_to !== null) || record.lifecycle === "retired";
+/** Verify that a partition's stored records are exactly what its ledger implies. Read-only. */
+export function verifyReplay(store, scope) {
+    const own = partitionOf(store);
+    const { home, hunchDir } = stateHomeFor(store, scope);
+    const ledger = readLedger(hunchDir, scope);
+    const fold = foldLedger(ledger);
+    const divergences = [];
+    const stored = [];
+    let verified = 0;
+    let verifiedByIdempotency = 0;
+    let unverifiable = 0;
+    let legacyChecked = 0;
+    const onFile = (facet, id) => ENTITY_KINDS.includes(facet)
+        ? store.recsInHome(facet, home).find((r) => r.id === id)
+        : undefined;
+    // 1. Every record the ledger names must be on file with the hash its last event wrote.
+    for (const entry of fold.values()) {
+        const record = onFile(entry.facet, entry.record_id);
+        const legacy = LEGACY_FACETS.has(entry.facet);
+        if (legacy)
+            legacyChecked++;
+        if (!record) {
+            stored.push({ ...entry, record_hash: "" });
+            divergences.push({ kind: legacy ? "legacy-drift" : "missing-record", facet: entry.facet, record_id: entry.record_id, seq: entry.seq, expected_hash: entry.record_hash, actual_hash: null, detail: `ledger seq ${entry.seq} ${entry.change} ${entry.record_id}; no ${entry.facet} record on file in ${scopePath(scope)}` });
+            continue;
+        }
+        const actual = stateHash(record);
+        stored.push({ ...entry, record_hash: actual });
+        if (actual === entry.record_hash) {
+            verified++;
+            continue;
+        }
+        divergences.push({ kind: legacy ? "legacy-drift" : "hash-drift", facet: entry.facet, record_id: entry.record_id, seq: entry.seq, expected_hash: entry.record_hash, actual_hash: actual, detail: `${entry.record_id} on file hashes ${actual}; the ledger's last event (seq ${entry.seq}, ${entry.change}) wrote ${entry.record_hash}` });
+    }
+    // 2. The idempotency table agrees with the ledger at each entry's seq (what a replay returns
+    //    is what the ledger said was on file then). Entries below the floor are checked against
+    //    the file directly when they are the record's newest entry — that is how a compacted
+    //    record stays verifiable.
+    const newestEntryFor = new Map();
+    for (const entry of Object.values(ledger.idempotency)) {
+        const prev = newestEntryFor.get(entry.record_id);
+        if (!prev || entry.seq > prev.seq)
+            newestEntryFor.set(entry.record_id, entry);
+        const eventsUpTo = ledger.events.filter((e) => e.record_id === entry.record_id && e.seq <= entry.seq);
+        const at = eventsUpTo[eventsUpTo.length - 1];
+        if (at && at.record_hash !== entry.record_hash && (entry.payload_hash === undefined || at.record_hash !== entry.payload_hash)) {
+            divergences.push({ kind: "idempotency-drift", facet: entry.facet, record_id: entry.record_id, seq: entry.seq, expected_hash: at.record_hash, actual_hash: entry.record_hash, detail: `idempotency entry at seq ${entry.seq} holds ${entry.record_hash}; the ledger event at seq ${at.seq} wrote ${at.record_hash}` });
+        }
+    }
+    // 3. Every state record in the partition must be one the ledger saw — or, after compaction,
+    //    one the idempotency table still names with the hash on file.
+    for (const facet of STATE_ONLY_FACETS) {
+        for (const record of store.recsInHome(facet, home)) {
+            if (scopePath(recordScope(record, own)) !== scopePath(scope))
+                continue;
+            const id = String(record.id);
+            if (fold.has(id))
+                continue;
+            const actual = stateHash(record);
+            const entry = newestEntryFor.get(id);
+            if (entry) {
+                stored.push({ facet, record_id: id, record_hash: actual, change: "updated", seq: entry.seq });
+                if (entry.record_hash === actual) {
+                    verifiedByIdempotency++;
+                    continue;
+                }
+                // The one change the contract makes WITHOUT an idempotency entry is closing a window on
+                // supersession (the `superseded` event carries the closed hash). With that event compacted
+                // away, a closed record is unverifiable; an OPEN record that differs is drift.
+                if (entry.seq <= ledger.floor_seq && windowClosed(facet, record)) {
+                    unverifiable++;
+                    continue;
+                }
+                divergences.push({ kind: "hash-drift", facet, record_id: id, seq: entry.seq, expected_hash: entry.record_hash, actual_hash: actual, detail: `${id} on file hashes ${actual}; its newest idempotency entry (seq ${entry.seq}) holds ${entry.record_hash} and no event above the floor explains the change` });
+                continue;
+            }
+            divergences.push({ kind: "orphan-record", facet, record_id: id, seq: 0, expected_hash: null, actual_hash: actual, detail: `${facet} record ${id} is on file in ${scopePath(scope)} but the ledger never saw it (no event, no idempotency entry)` });
+        }
+    }
+    // The two fingerprints cover the facets the contract owns; legacy facets are advisory.
+    const replayHash = snapshotHash([...fold.values()].filter((e) => !LEGACY_FACETS.has(e.facet)));
+    const storedHash = snapshotHash(stored.filter((s) => fold.has(s.record_id) && !LEGACY_FACETS.has(s.facet)));
+    const failing = divergences.some((d) => d.kind !== "legacy-drift");
+    return {
+        schema: REPLAY_SCHEMA_VERSION,
+        scope,
+        ledger: { head_seq: ledger.head_seq, floor_seq: ledger.floor_seq, events: ledger.events.length, idempotency_entries: Object.keys(ledger.idempotency).length },
+        replay_hash: replayHash,
+        stored_hash: storedHash,
+        records: { named_by_ledger: fold.size, verified, verified_by_idempotency: verifiedByIdempotency, unverifiable, legacy_checked: legacyChecked },
+        divergences,
+        ok: !failing && replayHash === storedHash,
+    };
+}
+export function formatReplayReport(r) {
+    const lines = [
+        `${scopePath(r.scope)}: ${r.ok ? "replay OK" : "REPLAY DIVERGED"} — ledger head ${r.ledger.head_seq}, floor ${r.ledger.floor_seq}, ${r.ledger.events} event(s), ${r.ledger.idempotency_entries} idempotency entr${r.ledger.idempotency_entries === 1 ? "y" : "ies"}`,
+        `  replay ${r.replay_hash}`,
+        `  stored ${r.stored_hash}${r.replay_hash === r.stored_hash ? "  (equal)" : "  (DIFFERENT)"}`,
+        `  records: ${r.records.named_by_ledger} named by the ledger, ${r.records.verified} verified hash for hash, ${r.records.verified_by_idempotency} verified through the idempotency table, ${r.records.unverifiable} unverifiable below the floor, ${r.records.legacy_checked} legacy`,
+    ];
+    for (const d of r.divergences)
+        lines.push(`  ${d.kind === "legacy-drift" ? "·" : "✗"} ${d.kind} ${d.facet}/${d.record_id}: ${d.detail}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=replay.js.map