@davesheffer/hunch 1.27.0 → 1.29.0

package/dist/integrations/hooks.js

@@ -97,4 +97,45 @@ export function installPreCommitHook(root, invocation, strict = false) {
     chmodSync(hookPath, 0o755);
     return { path: hookPath, action: "appended" };
 }
+const MERGE_MARK = "# >>> hunch post-merge >>>";
+const MERGE_END = "# <<< hunch post-merge <<<";
+/** Install a post-merge hook that re-syncs the committed grounding docs when a merge
+ *  brought memory in behind them (fnd_c402046ac7). Two branches that each captured a
+ *  record regenerate the same "N+1" counts line; git merges identical lines silently
+ *  and the doc ends up one behind the store. The hook regenerates the existing docs
+ *  from the PUBLIC store right after a local merge/pull that touched .hunch/, so the
+ *  next commit carries them. Foreground (it rewrites five files), loop-guarded via
+ *  HUNCH_SYNC, and it can never fail the merge. Preserves any existing hook. */
+export function installPostMergeHook(root, invocation) {
+    const dir = hooksDir(root);
+    const abs = isAbsolute(dir) ? dir : join(root, dir);
+    mkdirSync(abs, { recursive: true });
+    const hookPath = join(abs, "post-merge");
+    const blk = [
+        MERGE_MARK,
+        'if [ -z "$HUNCH_SYNC" ]; then',
+        "  if ! git diff --quiet ORIG_HEAD HEAD -- .hunch 2>/dev/null; then",
+        `    ( HUNCH_SYNC=1 ${invocation} grounding --refresh 2>/dev/null || true )`,
+        "  fi",
+        "fi",
+        MERGE_END,
+    ].join("\n");
+    if (!existsSync(hookPath)) {
+        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "created" };
+    }
+    const cur = readFileSync(hookPath, "utf8");
+    if (cur.includes(MERGE_MARK)) {
+        const updated = cur.replace(new RegExp(`${escapeRe(MERGE_MARK)}[\\s\\S]*?${escapeRe(MERGE_END)}`), blk);
+        if (updated === cur)
+            return { path: hookPath, action: "unchanged" };
+        writeFileSync(hookPath, updated);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "updated" };
+    }
+    writeFileSync(hookPath, cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`);
+    chmodSync(hookPath, 0o755);
+    return { path: hookPath, action: "appended" };
+}
 //# sourceMappingURL=hooks.js.map

package/dist/integrations/providers.js

@@ -360,6 +360,14 @@ export function regenerateGrounding(root, store) {
         writeWindsurfRule(root, store),
     ];
 }
+/** The five grounding docs, repo-relative (POSIX separators, as git prints them). */
+export const GROUNDING_DOC_PATHS = Object.freeze([
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+    ".cursor/rules/hunch.mdc",
+    ".windsurf/rules/hunch.md",
+]);
 function groundingTargets(root, store) {
     return [
         ["CLAUDE.md", () => updateClaudeMd(root, store)],

package/dist/mcp/server.js

@@ -13,8 +13,8 @@ import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
-import { StateRefusal, SubscribeResponseSchema, capabilities, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
-import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION } from "../core/stateContract.js";
+import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, stateHash } from "../core/stateContract.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
@@ -24,7 +24,8 @@ import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, c
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
-import { formatStructure } from "../core/format.js";
+import { formatSearchHit, formatStructure } from "../core/format.js";
+import { isStateKind, stateSupplements } from "../core/stateDelivery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, EvidenceExecutionSchema, EvidenceInterventionSchema, EvidenceProbeSchema, formatVerifiedEvidenceMap, VerifiedEvidenceReceiptSchema, } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -754,7 +755,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return ok(`No matches for "${query}".`);
         const lines = hits.map((h) => {
             const r = store.resolve(h.ref);
-            return `• [${h.kind}] ${h.ref} — ${h.title}\n    ${h.snippet}${provLine(r?.record)}`;
+            return `${formatSearchHit(h, r?.record)}${provLine(r?.record)}`;
         });
         return ok(`Top matches for "${query}":\n\n${lines.join("\n")}`);
     });
@@ -930,7 +931,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return {
                 content: [{
                         type: "text",
-                        text: `${proof.proof_id} — ${proof.verdict.toUpperCase()}; ${proof.changed_file_count} exact file delta(s), ${proof.blast_radius_count} dependent path(s), ${proof.omissions.length + proof.unknowns.length} explicit gap(s); sealed ${proof.content_hash}. Evidence only; no execution or merge authority.`,
+                        text: `${proof.proof_id} — ${proof.verdict.toUpperCase()}; ${proof.changed_file_count} exact file delta(s), ${proof.blast_radius_count} dependent path(s), ${proof.omissions.length + proof.unknowns.length} explicit gap(s); sealed ${proof.content_hash}. Evidence only; no execution or merge authority.`
+                            // The chain: a `shipped` receipt rests on this proof as a credential-free pointer.
+                            + `\n\nrests_on ref (for a nuryel receipt that shipped this change): ${JSON.stringify({ kind: "external", ref: { system: "hunch", object_type: "change_proof", object_key: proof.proof_id, content_hash: proof.content_hash, observed_at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z") } })}`,
                     }],
                 structuredContent: proof,
             };
@@ -1034,6 +1037,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             // Git checkout cannot provide DNA; the dedicated DNA tool reports the
             // exact derivation error when a caller needs diagnostics.
         }
+        // The "State" section (nuryel.state/1): current derived, in-force commitments and the
+        // latest receipts whose subject/text matches the target — bounded, ordered, sharing the
+        // brief's budget as supplements. Withheld on time-travel: state records carry no as-of view.
+        const stateGrounding = asOf ? [] : stateSupplements(store.stateSlice(target), target);
         const options = {
             root,
             symbols: store.recs("symbols"),
@@ -1041,7 +1048,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
-            supplements: dnaSupplement ? [dnaSupplement] : [],
+            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -1068,8 +1075,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     ...options,
                     supplements: [
                         ...(dnaSupplement ? [dnaSupplement] : []),
+                        ...stateGrounding,
                         ...hits
-                            .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind))
+                            // State hits are delivered through the State section above, not as raw search lines.
+                            .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind) && !isStateKind(hit.kind))
                             .map((hit, index) => ({
                             id: hit.ref,
                             kind: `search-${hit.kind}`,
@@ -1525,7 +1534,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
             const dest = destinationNote(resolveDestRoot(home, store, root));
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${captureNote}${quality}`);
+            // The chain (nuryel.state/1): a `shipped` receipt in an organization drawer rests on
+            // this decision by id + the hash ON FILE + this repository's partition. Hand the ref
+            // over now so the agent never rests on a pre-store hash or re-derives the scope.
+            const onFile = store.getRec("decisions", id) ?? rec;
+            const restsOn = JSON.stringify({ kind: "record", id, record_hash: stateHash(onFile), scope: partitionOf(store) });
+            const chainNote = `\n\nrests_on ref (for a nuryel receipt that implements this decision): ${restsOn}`;
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${chainNote}${captureNote}${quality}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -1721,10 +1736,24 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 if (ref.facet === "derived")
                     return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
                 if (ref.facet === "commitments")
-                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}`;
+                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}${r.closed_by ? ` · closed by ${g("closed_by")}` : ""}`;
                 if (ref.facet === "receipts") {
                     const t = (r.target ?? {});
-                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}`;
+                    // The chain: what the action rested on, one pointer per line, so a reader follows
+                    // incident → decision → change proof → closure without a second call.
+                    const rests = (Array.isArray(r.rests_on) ? r.rests_on : []);
+                    const restLines = rests.map((d) => {
+                        if (d.kind === "record") {
+                            const sc = d.scope;
+                            return `\n    rests on record ${String(d.id)}${sc ? ` in ${String(sc.kind)}/${String(sc.id)}` : ""}`;
+                        }
+                        if (d.kind === "external") {
+                            const x = (d.ref ?? {});
+                            return `\n    rests on ${String(x.system ?? "")} ${String(x.object_type ?? "")}:${String(x.object_key ?? "")}`;
+                        }
+                        return `\n    rests on ${String(d.kind)} ${String(d.name ?? "")}`;
+                    }).join("");
+                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}${restLines}`;
                 }
                 if (ref.facet === "decisions")
                     return `- ${label} decision ${ref.id} · ${g("status")}: ${g("title")}`;

package/dist/serve/app.js

@@ -8,7 +8,8 @@
  *
  * Every rule lives in src/store/stateBinding.ts; this file only maps HTTP to it:
  *   GET  /nuryel/v1/capabilities      → capabilities of the partition named by ?scope=kind:id (default: first granted)
- *   POST /nuryel/v1/read              → readState
+ *   POST /nuryel/v1/read              → readState; with `scopes` a UNION read: readState per granted
+ *                                       served partition, merged by mergeReadResponses (primary's envelope)
  *   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)
@@ -18,8 +19,8 @@ import { createServer } from "node:http";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
 import { flushCapture } from "../integrations/sync.js";
-import { StateRefusal, capabilities, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
-import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ScopeSchema, scopePath } from "../core/stateContract.js";
+import { StateRefusal, capabilities, mergeReadResponses, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadScopesSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
 import { partitionFor, resolvePrincipal } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -148,8 +149,26 @@ export function createServeApp(config, opts = {}) {
             if (url.pathname === "/nuryel/v1/read") {
                 const scope = requireScope(principal, body);
                 const { store } = storeFor(scope);
-                const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body });
-                return send(res, 200, { ...response, envelope });
+                if (body.scopes === undefined) {
+                    const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body });
+                    return send(res, 200, { ...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 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 });
+                const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(storeFor(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }).response), ungranted);
+                return send(res, 200, { ...merged, envelope: primary.envelope });
             }
             if (url.pathname === "/nuryel/v1/write") {
                 const scope = requireScope(principal, body);

package/dist/store/changeLedger.js

@@ -19,7 +19,12 @@ export const LEDGER_SCHEMA_VERSION = "nuryel.ledger/1";
 export const CHANGES_DIR = "changes";
 const IdempotencyEntrySchema = z.object({
     record_id: z.string().min(1),
+    /** Hash of the record ON FILE (what reads, events and refs see). */
     record_hash: z.string(),
+    /** Hash of the normalized payload as the writer sent it (additive). The store may enrich a
+     *  record on put (a private-mode decision gains `valid_from`), so a replay is recognized by
+     *  the payload it re-sends, while `record_hash` stays the truth a reader can verify. */
+    payload_hash: z.string().optional(),
     facet: z.string(),
     seq: z.number().int().nonnegative(),
     at: z.string(),

package/dist/store/hunchStore.js

@@ -26,6 +26,7 @@ import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
 import { analyzeDiff } 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.
  * Probe the nearest real directory so a planned nested overlay cannot evade the
  * public-repository boundary merely by deferring mkdir until its first write. */
@@ -485,6 +486,20 @@ export class HunchStore {
                 fts(f.id, "findings", f.title, `${f.observation} ${f.evidence.join(" ")} ${f.affected_files.join(" ")} ${f.affected_symbols.join(" ")} ${f.triage}`);
             }
             counts.findings = fnds.length;
+            // nuryel.state/1 kinds (receipts, commitments, derived, entities, relationships):
+            // advisory records on the same FTS-only ride as runbooks/findings — no dedicated
+            // SQL table. kind = the store kind; title = the subject key; body = the human words
+            // + actor/owner + status label (stateSearchDoc), so a subject id and a phrase both
+            // hit. History (superseded/done/failed/retired) is indexed too and demoted at
+            // query time (demoteHistoricalState / priorMeta), never dropped.
+            for (const kind of STATE_KINDS) {
+                const records = this.recs(kind);
+                for (const record of records) {
+                    const doc = stateSearchDoc(kind, record);
+                    fts(record.id, kind, doc.title, doc.body);
+                }
+                counts[kind] = records.length;
+            }
             void j;
         });
         // Reconcile embeddings AFTER the FTS rebuild (model-free): drop vectors whose
@@ -507,13 +522,104 @@ export class HunchStore {
         try {
             const rows = this.db.prepare(`SELECT ref, kind, title, snippet(search, 3, '[', ']', '…', 12) AS snip, bm25(search) AS score
          FROM search WHERE search MATCH ? ORDER BY score LIMIT ?`).all(match, limit);
-            return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score }));
+            return this.demoteHistoricalState(rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score })));
         }
         catch {
             // Malformed FTS expression — degrade to a LIKE scan over titles/bodies.
             return this.likeSearch(query, limit);
         }
     }
+    /** State-of-record ordering for nuryel.state/1 hits (superseded derived, done/cancelled
+     *  commitments, failed receipts, retired entities): indexed and findable, but ranked BELOW
+     *  the live record of the same subject. bm25 is negative (lower = better), so a history
+     *  hit's score is scaled toward 0 by STATE_HISTORY_SCORE_FACTOR and the pool is re-sorted
+     *  STABLY by score — a store with no state history returns the exact SQL order, and a
+     *  LIKE-fallback pool (all scores 0) is partitioned live-first in its existing order.
+     *  Bounded (a dimmer, not an exclusion) so the previous summary stays reachable one query
+     *  away; hybridSearch/rankedSearch additionally apply the liveness prior via priorMeta. */
+    demoteHistoricalState(hits) {
+        if (!hits.some((h) => isStateKind(h.kind)))
+            return hits;
+        const scored = hits.map((h) => {
+            const meta = this.stateMeta(h.ref, h.kind);
+            if (!meta || meta.live)
+                return h;
+            return { ...h, score: h.score * STATE_HISTORY_SCORE_FACTOR };
+        });
+        const allZero = scored.every((h) => h.score === 0);
+        if (allZero) {
+            const live = scored.filter((h) => { const m = this.stateMeta(h.ref, h.kind); return !m || m.live; });
+            const history = scored.filter((h) => !live.includes(h));
+            return [...live, ...history];
+        }
+        return scored.sort((a, b) => a.score - b.score);
+    }
+    /** Liveness + clock for a state hit (null for every non-state kind). */
+    stateMeta(ref, kind) {
+        if (!isStateKind(kind))
+            return null;
+        const record = this.recs(kind).find((r) => r.id === ref);
+        if (!record)
+            return null;
+        const { live, label } = stateLiveness(kind, record);
+        return { live, label, at: stateObservedAt(kind, record), provenance: record.provenance.source };
+    }
+    /** The bounded "State" slice for a context brief (hunch_context / `hunch context`): the
+     *  current derived summaries, in-force commitments and latest verified receipts whose
+     *  subject or text matches `target`. Matching is AND over the target's tokens (every token
+     *  must appear, prefix-tolerant) so a file path such as src/store/x.ts never drags in a
+     *  summary that merely mentions "store"; an exact subject match always qualifies. Order is
+     *  deterministic: score (best first), then observed_at DESC, then id. Caps per kind are
+     *  STATE_SLICE_CAPS. A store with no state records returns three empty lists. */
+    stateSlice(target) {
+        const empty = { derived: [], commitments: [], receipts: [] };
+        const needle = toPosixTarget(target).trim();
+        if (!needle)
+            return empty;
+        const tokens = needle.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+        const pick = (kind) => {
+            const records = this.recs(kind);
+            if (!records.length)
+                return [];
+            const scoreByRef = new Map();
+            for (const hit of this.stateFts(tokens, kind, Math.max(STATE_SLICE_CAPS[kind] * 8, 24)))
+                scoreByRef.set(hit.ref, hit.score);
+            const hits = [];
+            for (const record of records) {
+                if (!stateLiveness(kind, record).live)
+                    continue;
+                const id = record.id;
+                const exact = stateSubject(kind, record) === needle || id === needle;
+                let score = scoreByRef.get(id);
+                if (score === undefined) {
+                    if (!exact)
+                        continue;
+                    score = 0;
+                }
+                else if (!exact && !allTokensPresent(tokens, stateSearchDoc(kind, record))) {
+                    continue; // the LIKE fallback is OR-shaped; keep the AND contract on every runtime
+                }
+                hits.push({ kind, record, score: exact ? Math.min(score, STATE_EXACT_SUBJECT_SCORE) : score });
+            }
+            return hits.sort(compareStateHits).slice(0, STATE_SLICE_CAPS[kind]);
+        };
+        return { derived: pick("derived"), commitments: pick("commitments"), receipts: pick("receipts") };
+    }
+    /** AND-shaped FTS over one state kind (every token required, prefix-tolerant); degrades to
+     *  the kind-scoped LIKE scan (OR-shaped — the caller re-checks AND) without FTS5. */
+    stateFts(tokens, kind, limit) {
+        if (!tokens.length)
+            return [];
+        const match = tokens.map((t) => `"${t}"*`).join(" ");
+        try {
+            const rows = this.db.prepare(`SELECT ref, kind, title, '' AS snip, bm25(search) AS score
+         FROM search WHERE search MATCH ? AND kind = ? ORDER BY score, ref LIMIT ?`).all(match, kind, limit);
+            return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score }));
+        }
+        catch {
+            return this.likeSearch(tokens.join(" "), limit, kind);
+        }
+    }
     /** Portable bounded fallback over titles/bodies. Each natural-language token
      * is an OR candidate, mirroring the high-recall FTS query closely enough for
      * runtimes whose SQLite build omits the optional FTS5 module.
@@ -547,7 +653,7 @@ export class HunchStore {
        WHERE ${where}
        ORDER BY CASE WHEN ${titleLikes} THEN 0 ELSE 1 END, length(title), ref
        LIMIT ?`).all(...(kind ? [kind, ...likes, ...titleParams, limit] : [...likes, ...titleParams, limit]));
-        return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: 0 }));
+        return this.demoteHistoricalState(rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: 0 })));
     }
     // ---- semantic search (opt-in embeddings) --------------------------------
     /** The exact (ref, kind, title, body) docs that feed FTS — and thus embeddings.
@@ -825,6 +931,12 @@ export class HunchStore {
             // A fixed bug is not "dead" — lineage is the point of keeping it findable.
             return { dead: false, provenance: b.provenance.source };
         }
+        // nuryel.state/1 kinds: history (superseded / done / failed / retired) dims exactly like a
+        // superseded decision; the record's own clock (computed_at, valid_from, verified_at …)
+        // drives recency so the latest summary of a subject outranks last month's.
+        const state = this.stateMeta(ref, kind);
+        if (state)
+            return { dead: !state.live, provenance: state.provenance, at: state.at || undefined };
         return null;
     }
     /** Hybrid search (hunch_query / `hunch query --semantic`): FTS bm25 fused with
@@ -908,7 +1020,7 @@ export class HunchStore {
         try {
             const rows = this.db.prepare(`SELECT ref, kind, title, snippet(search, 3, '[', ']', '…', 12) AS snip, bm25(search) AS score
          FROM search WHERE search MATCH ? AND kind = ? ORDER BY score LIMIT ?`).all(match, kind, limit);
-            return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score }));
+            return this.demoteHistoricalState(rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score })));
         }
         catch {
             return this.likeSearch(query, limit, kind);
@@ -1878,7 +1990,22 @@ const DECISION_FRESHNESS_PATH_CACHE_CAP = 4_096;
  *  intent. Measured on bench/golden-retrieval.json: Recall@10 70% -> 90%, MRR
  *  0.402 -> 0.575. Set HUNCH_MEMORY_PRIOR_SHIFT=0 to disable. */
 const MEMORY_PRIOR_SHIFT = numEnv("HUNCH_MEMORY_PRIOR_SHIFT", 12);
-const MEMORY_KINDS = new Set(["decisions", "constraints", "bugs", "runbooks", "policies"]);
+const MEMORY_KINDS = new Set(["decisions", "constraints", "bugs", "runbooks", "policies", ...STATE_KINDS]);
+/** State-of-record ordering in the RAW search path: a nuryel.state/1 history hit (superseded
+ *  derived, done/cancelled commitment, failed receipt, retired entity) keeps this fraction of
+ *  its bm25 score (bm25 is negative, so scaling toward 0 demotes). 0.5 keeps the previous
+ *  summary of a subject one query away while the current one leads; hybridSearch adds the
+ *  bounded liveness prior on top. Set HUNCH_STATE_HISTORY_SCORE_FACTOR=1 to disable. */
+const STATE_HISTORY_SCORE_FACTOR = Math.max(0, Math.min(1, numEnv("HUNCH_STATE_HISTORY_SCORE_FACTOR", 0.5)));
+/** An exact subject match in stateSlice() leads regardless of bm25 (which is never below this). */
+const STATE_EXACT_SUBJECT_SCORE = -1_000_000;
+/** AND contract for stateSlice(): every query token appears (as a prefix) in the record's doc. */
+function allTokensPresent(tokens, doc) {
+    if (!tokens.length)
+        return false;
+    const words = `${doc.title} ${doc.body}`.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+    return tokens.every((t) => words.some((w) => w.startsWith(t)));
+}
 function safeFreshnessScope(value) {
     const normalized = toPosixTarget(value.trim());
     if (!normalized || normalized.length > 1_024 || normalized.includes("\0")

package/dist/store/schema.js

@@ -113,6 +113,7 @@ export const FTS_SEARCH_SCHEMA_SQL = /* sql */ `
 CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(
   ref UNINDEXED,   -- entity id
   kind UNINDEXED,  -- components | resources | edges | symbols | decisions | bugs | constraints | runbooks | findings
+                   -- | receipts | commitments | derived | entities | relationships (nuryel.state/1; title = subject key)
   title,
   body,
   tokenize = 'porter unicode61'