@davesheffer/hunch 1.27.0 → 1.28.0

package/dist/cli/index.js

@@ -55,7 +55,8 @@ import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
-import { formatContext, formatStructure } from "../core/format.js";
+import { formatContext, formatSearchHit, formatStructure } from "../core/format.js";
+import { isStateKind, renderStateLine, stateSupplements } from "../core/stateDelivery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -1320,7 +1321,7 @@ program
     else {
         console.log(`Top matches for "${q}"${how}:\n`);
         for (const h of hits)
-            console.log(`• [${h.kind}] ${h.ref} — ${h.title}\n    ${h.snippet}`);
+            console.log(formatSearchHit(h, isStateKind(h.kind) ? store.resolve(h.ref)?.record : undefined));
     }
     store.close();
 });
@@ -4059,12 +4060,24 @@ program
         !ctx.findings.length &&
         !ctx.landscape?.resources.length &&
         !ctx.landscape?.relationships.length;
+    // The "State" section (nuryel.state/1): current derived, in-force commitments, latest
+    // receipts matching the target — the same slice and render as hunch_context.
+    const slice = asOf ? null : store.stateSlice(target);
+    const stateGrounding = slice ? stateSupplements(slice, target) : [];
     if (empty && !asOf) {
-        const hits = store.rankedSearch(target, 8);
-        if (hits.length) {
+        const hits = store.rankedSearch(target, 8).filter((h) => !isStateKind(h.kind));
+        if (hits.length || stateGrounding.length) {
             console.log(`No file/symbol resolves for "${target}" — closest graph matches instead:\n`);
             for (const h of hits)
                 console.log(`• ${h.ref} — ${h.title}\n    ${h.snippet}`);
+            if (slice) {
+                const stateHits = [...slice.derived, ...slice.commitments, ...slice.receipts];
+                if (stateHits.length) {
+                    console.log(`${hits.length ? "\n" : ""}State (nuryel.state/1):`);
+                    for (const hit of stateHits)
+                        console.log(`• ${renderStateLine(hit.kind, hit.record)}`);
+                }
+            }
             console.log(`\n(For a file/symbol brief use a concrete target; for free-text this is what \`hunch query\` returns.)`);
             store.close();
             return;
@@ -4077,6 +4090,7 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
+        supplements: stateGrounding,
     }));
     store.close();
 });

package/dist/cli/serve.js

@@ -57,7 +57,7 @@ export function registerServeCommands(program) {
     });
     serve.command("init")
         .description("Declare a partition directory and mint a principal token (printed once; only its hash is stored)")
-        .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:ylm")
+        .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:acme")
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
         .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")

package/dist/core/format.js

@@ -1,7 +1,18 @@
 import { buildDeliveryEnvelope } from "./delivery.js";
+import { isStateKind, renderStateLine } from "./stateDelivery.js";
 export function formatContext(ctx, options = {}) {
     return buildDeliveryEnvelope(ctx, options).text;
 }
+/** One search hit as `hunch query` / hunch_query print it (headline + indented detail line).
+ *  Graph records keep their `[kind] id — title` shape; a nuryel.state/1 hit renders through
+ *  renderStateLine (`[commitment/in_force] customer:Site:7 — "send report" due … (owner …)`)
+ *  with the record id on the detail line, so both readers say the same thing. */
+export function formatSearchHit(hit, record) {
+    if (isStateKind(hit.kind) && record) {
+        return `• ${renderStateLine(hit.kind, record)}\n    ${hit.ref}`;
+    }
+    return `• [${hit.kind}] ${hit.ref} — ${hit.title}\n    ${hit.snippet}`;
+}
 /** Render a StructureView as a compact orientation brief (hunch_structure). */
 export function formatStructure(v) {
     const NL = "\n";

package/dist/core/stateContract.js

@@ -56,10 +56,15 @@ export const PrincipalSchema = z.object({
 }).strict();
 export const STATE_FACETS = ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
 // ---- verbs ------------------------------------------------------------------------------
+/** Union read: the partitions a principal wants in ONE answer. `scope` stays required (it is the
+ *  primary partition; its envelope and receipt lead the response). An entry the principal is not
+ *  granted is NAMED in `denied_scopes` — it never refuses the whole call, and is never described. */
+export const ReadScopesSchema = z.array(ScopeSchema).min(1).max(64);
 export const ReadRequestSchema = z.object({
     schema: z.literal(STATE_READ_VERSION),
     principal: PrincipalSchema,
     scope: ScopeSchema,
+    scopes: ReadScopesSchema.optional(),
     subject: z.string().max(512).optional(),
     task: z.string().max(4096).optional(),
     profile: z.enum(DELIVERY_PROFILES).optional(),
@@ -92,6 +97,12 @@ export const ReadResponseSchema = z.object({
     /** The records behind every ref in `state_of_record`, by id, so a consumer can answer from
      *  the drawer without a second lookup. Additive; absent when there is no subject. */
     records: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    /** Union read (additive): the partitions actually read, primary first. Absent on a
+     *  single-partition read. */
+    scopes: z.array(ScopeSchema).max(64).optional(),
+    /** Union read (additive): one delivery receipt per partition read; `receipt_id` above stays
+     *  the primary's. */
+    receipts: z.array(z.object({ scope: ScopeSchema, receipt_id: z.string().regex(/^hdr_[a-f0-9]{24}$/) }).strict()).max(64).optional(),
 }).strict();
 export const WriteRequestSchema = z.object({
     schema: z.literal(STATE_WRITE_VERSION),
@@ -236,6 +247,14 @@ export function assertReadWithinGrants(principal, response) {
         if (granted.has(grantKey(denied)))
             throw new Error(`denied scope ${grantKey(denied)} is actually granted — the response is inconsistent`);
     }
+    for (const read of response.scopes ?? []) {
+        if (!granted.has(grantKey(read)))
+            throw new Error(`read scope ${grantKey(read)} is outside the principal's grants`);
+    }
+    for (const receipt of response.receipts ?? []) {
+        if (!granted.has(grantKey(receipt.scope)))
+            throw new Error(`receipt for scope ${grantKey(receipt.scope)} is outside the principal's grants`);
+    }
 }
 /** provenance-on-every-write + scope agreement between the envelope and the record. */
 export function assertWriteWellFormed(request) {

package/dist/core/stateDelivery.js

@@ -0,0 +1,179 @@
+export const STATE_KINDS = ["receipts", "commitments", "derived", "entities", "relationships"];
+const STATE_KIND_SET = new Set(STATE_KINDS);
+export function isStateKind(kind) {
+    return STATE_KIND_SET.has(kind);
+}
+/** Singular facet label used in renders: `[commitment/in_force]`, `[derived/current]`. */
+const FACET_LABEL = {
+    receipts: "receipt",
+    commitments: "commitment",
+    derived: "derived",
+    entities: "entity",
+    relationships: "relationship",
+};
+/** Liveness per kind, mirroring readState's state_of_record predicates exactly
+ *  (derived `current` with an open window; commitment open/waiting with an open window;
+ *  receipt succeeded/verified; entity active; a relationship is always current). */
+export function stateLiveness(kind, record) {
+    switch (kind) {
+        case "derived": {
+            const d = record;
+            if (d.valid_to != null)
+                return { label: "superseded", live: false };
+            return { label: d.state, live: d.state === "current" };
+        }
+        case "commitments": {
+            const c = record;
+            if (c.status === "open" || c.status === "waiting") {
+                return c.valid_to == null ? { label: "in_force", live: true } : { label: "superseded", live: false };
+            }
+            return { label: c.status, live: false };
+        }
+        case "receipts": {
+            const r = record;
+            return { label: r.state, live: r.state === "succeeded" || r.state === "verified" };
+        }
+        case "entities": {
+            const e = record;
+            return { label: e.lifecycle, live: e.lifecycle === "active" };
+        }
+        case "relationships":
+            return { label: "current", live: true };
+    }
+}
+/** The subject key a reader would type: the commitment/derived subject, the receipt's target
+ *  object (`event:10042`), the entity id, or the relationship's `from` endpoint. */
+export function stateSubject(kind, record) {
+    switch (kind) {
+        case "derived": return record.subject;
+        case "commitments": return record.subject;
+        case "receipts": {
+            const r = record;
+            return `${r.target.object_type}:${r.target.object_key}`;
+        }
+        case "entities": return record.id;
+        case "relationships": return record.from;
+    }
+}
+/** The instant that orders "latest first": computed_at, valid_from, verified_at ?? occurred_at,
+ *  updated_at. Relationships carry no clock and sort last among equals. */
+export function stateObservedAt(kind, record) {
+    switch (kind) {
+        case "derived": return record.computed_at;
+        case "commitments": return record.valid_from;
+        case "receipts": {
+            const r = record;
+            return r.verified_at ?? r.occurred_at;
+        }
+        case "entities": return record.updated_at;
+        case "relationships": return "";
+    }
+}
+/** The FTS document for a state record: title = the subject key (so an id query hits the
+ *  title column, which the snippet and LIKE fallback both prefer), body = the human words plus
+ *  the actor/owner, the status label and the dates. Every reader's query — a subject id, a
+ *  phrase from a summary, an action kind, a principal — lands on one of these. */
+export function stateSearchDoc(kind, record) {
+    const { label } = stateLiveness(kind, record);
+    const subject = stateSubject(kind, record);
+    switch (kind) {
+        case "derived": {
+            const d = record;
+            return { title: subject, body: `${d.content} ${label} ${d.transform_version} ${d.computed_at.slice(0, 10)}` };
+        }
+        case "commitments": {
+            const c = record;
+            return { title: subject, body: `${c.title} ${c.evidence_excerpt ?? ""} ${label} ${c.status} owner ${c.owner} due ${c.due}` };
+        }
+        case "receipts": {
+            const r = record;
+            return {
+                title: subject,
+                body: `${r.action_kind} ${r.actor} ${label} ${r.target.system} ${r.target.object_type} ${r.target.object_key} ${r.occurred_at.slice(0, 10)} ${r.invalidates.join(" ")}`,
+            };
+        }
+        case "entities": {
+            const e = record;
+            const attrs = Object.entries(e.attributes).map(([k, v]) => `${k} ${v ?? ""}`).join(" ");
+            return { title: subject, body: `${e.name} ${e.kind} ${label} ${attrs}` };
+        }
+        case "relationships": {
+            const r = record;
+            return { title: subject, body: `${r.type} ${r.to} ${r.reason}` };
+        }
+    }
+}
+const DERIVED_HEADLINE_CHARS = 120;
+function oneLine(value, max) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+/** The one-line render shared by hunch_query, `hunch query` and the context "State" section:
+ *    [commitment/in_force] customer:Site:7 — "send report" due 2026-09-11 (owner sofia)
+ *    [derived/current] customer:Site:7 — <first 120 chars of the summary>
+ *    [receipt/verified] event:10042 — events_add_actions by sofia@david 2026-09-08 */
+export function renderStateLine(kind, record) {
+    const { label } = stateLiveness(kind, record);
+    const head = `[${FACET_LABEL[kind]}/${label}] ${stateSubject(kind, record)} — `;
+    switch (kind) {
+        case "derived":
+            return `${head}${oneLine(record.content, DERIVED_HEADLINE_CHARS)}`;
+        case "commitments": {
+            const c = record;
+            return `${head}"${oneLine(c.title, 100)}" due ${c.due} (owner ${c.owner})`;
+        }
+        case "receipts": {
+            const r = record;
+            return `${head}${r.action_kind} by ${r.actor} ${(r.verified_at ?? r.occurred_at).slice(0, 10)}`;
+        }
+        case "entities": {
+            const e = record;
+            return `${head}${oneLine(e.name, 100)} (${e.kind})`;
+        }
+        case "relationships": {
+            const r = record;
+            return `${head}${r.type} → ${r.to}${r.reason ? ` (${oneLine(r.reason, 80)})` : ""}`;
+        }
+    }
+}
+/** Bounded caps for the context "State" section: current derived, in-force commitments,
+ *  latest receipts. Deliberately small — a brief, not a dump; `nuryel_read` is the full view. */
+export const STATE_SLICE_CAPS = { derived: 3, commitments: 5, receipts: 3 };
+/** Deterministic order for a state slice: score (best first), then observed_at DESC (latest
+ *  first), then id ASC. Applied after liveness filtering, before the cap. */
+export function compareStateHits(a, b) {
+    if (a.score !== b.score)
+        return a.score - b.score;
+    const at = stateObservedAt(b.kind, b.record).localeCompare(stateObservedAt(a.kind, a.record));
+    if (at !== 0)
+        return at;
+    return a.record.id.localeCompare(b.record.id);
+}
+/** Supplement priority band for the State section: above Project DNA (425), below
+ *  decision-grounding (1000) and the ranked memory records (which are not supplements). */
+const STATE_SUPPLEMENT_PRIORITY = 500;
+/** Render a state slice as delivery supplements (one header + one line per record) so the
+ *  section shares the context brief's hard budget and receipt like every other grounding.
+ *  Empty slice → no supplements at all: a store with zero state records is byte-identical. */
+export function stateSupplements(slice, target) {
+    const hits = [...slice.derived, ...slice.commitments, ...slice.receipts];
+    if (!hits.length)
+        return [];
+    const out = [{
+            id: "state-of-record",
+            kind: "state",
+            text: `STATE (nuryel.state/1) for "${target}": ${slice.derived.length} current derived, ${slice.commitments.length} in-force commitment(s), ${slice.receipts.length} latest receipt(s). Follow the state of record; nuryel_read(subject) returns the full records.`,
+            priority: STATE_SUPPLEMENT_PRIORITY,
+        }];
+    hits.forEach((hit, index) => {
+        out.push({
+            id: hit.record.id,
+            kind: `state-${FACET_LABEL[hit.kind]}`,
+            text: renderStateLine(hit.kind, hit.record),
+            // Strictly descending so the sort in buildDeliveryEnvelope keeps slice order.
+            priority: STATE_SUPPLEMENT_PRIORITY - 1 - index,
+        });
+    });
+    return out;
+}
+//# sourceMappingURL=stateDelivery.js.map

package/dist/mcp/server.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")}`);
     });
@@ -1034,6 +1035,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 +1046,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 +1073,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}`,

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/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'

package/dist/store/stateBinding.js

@@ -125,6 +125,12 @@ export function readState(store, input) {
     let stateOfRecord = null;
     const records = {};
     const denied = new Map();
+    // Union read against ONE store: every requested scope the principal lacks is named up front;
+    // the partitions actually read are declared so a caller never mistakes this for the union
+    // (a multi-partition host merges per-store answers with mergeReadResponses).
+    for (const s of request.scopes ?? [])
+        if (!granted(request.principal, s))
+            denied.set(scopePath(s), s);
     if (request.subject !== undefined) {
         const subject = request.subject;
         const current = [];
@@ -228,10 +234,86 @@ export function readState(store, input) {
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
         ...(stateOfRecord ? { records } : {}),
+        ...(request.scopes ? { scopes: [request.scope], receipts: [{ scope: request.scope, receipt_id: envelope.receipt_id }] } : {}),
     });
     assertReadWithinGrants(request.principal, response);
     return { response, envelope };
 }
+/** Union read — one state_of_record across several partitions, each read by `readState` against
+ *  its own store. Pure: no store, no grants decided here (every input already passed its own
+ *  grant check). The primary's receipt, scope and envelope lead; refs concatenate (each already
+ *  carries its partition), `depends_on` concatenates, `invalidated_by` is a sorted union, `records`
+ *  merge by id (first writer wins — ids are identity, two copies are the same record),
+ *  `denied_scopes` is the union of every partition's denied plus `extraDenied` (requested-but-
+ *  ungranted scopes the host refused to open), `scopes` names the partitions read and `receipts`
+ *  carries one delivery receipt per partition. Reusable by any host (HTTP today; MCP or CLI
+ *  fronting several roots later). */
+export function mergeReadResponses(primary, others, extraDenied = []) {
+    const all = [primary, ...others];
+    const scopes = new Map();
+    const receipts = new Map();
+    for (const r of all) {
+        for (const s of r.scopes ?? [r.scope])
+            if (!scopes.has(scopePath(s)))
+                scopes.set(scopePath(s), s);
+        for (const x of r.receipts ?? [{ scope: r.scope, receipt_id: r.receipt_id }])
+            if (!receipts.has(scopePath(x.scope)))
+                receipts.set(scopePath(x.scope), x);
+    }
+    const denied = new Map();
+    for (const s of [...all.flatMap((r) => r.denied_scopes), ...extraDenied])
+        if (!scopes.has(scopePath(s)) && !denied.has(scopePath(s)))
+            denied.set(scopePath(s), s);
+    const sors = all.map((r) => r.state_of_record).filter((s) => s !== null);
+    let stateOfRecord = null;
+    const records = {};
+    if (sors.length) {
+        const refKey = (ref) => `${ref.facet}|${scopePath(ref.scope)}|${ref.id}`;
+        const dedupeRefs = (pick) => {
+            const seen = new Set();
+            const out = [];
+            for (const ref of sors.flatMap(pick)) {
+                const k = refKey(ref);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    out.push(ref);
+                }
+            }
+            return out;
+        };
+        const seenDeps = new Set();
+        const dependsOn = [];
+        for (const dep of sors.flatMap((s) => s.depends_on)) {
+            const k = stateHash(dep);
+            if (!seenDeps.has(k)) {
+                seenDeps.add(k);
+                dependsOn.push(dep);
+            }
+        }
+        stateOfRecord = {
+            subject: sors[0].subject,
+            current: dedupeRefs((s) => s.current),
+            in_force: dedupeRefs((s) => s.in_force),
+            done: dedupeRefs((s) => s.done),
+            depends_on: dependsOn,
+            invalidated_by: [...new Set(sors.flatMap((s) => s.invalidated_by))].sort(),
+        };
+        for (const r of all)
+            for (const [id, record] of Object.entries(r.records ?? {}))
+                if (!(id in records))
+                    records[id] = record;
+    }
+    return ReadResponseSchema.parse({
+        schema: STATE_READ_VERSION,
+        receipt_id: primary.receipt_id,
+        scope: primary.scope,
+        state_of_record: stateOfRecord,
+        denied_scopes: [...denied.values()],
+        ...(stateOfRecord ? { records } : {}),
+        scopes: [...scopes.values()],
+        receipts: [...receipts.values()],
+    });
+}
 /** What a record is ABOUT, for subscribers filtering by subject. Mirrors the read verb's matching. */
 function subjectOf(facet, record) {
     const r = record;
@@ -382,6 +464,24 @@ export function writeState(store, input, opts = {}) {
     }
     if (supersedes === id)
         supersedes = null;
+    // A supersede target must still be open. Two writers racing to replace the same incumbent
+    // would otherwise both succeed and leave two current records for one subject (fnd_eeb8bf3cb8);
+    // the loser is told which record is current now, so it can re-read and supersede that one.
+    // The writer that closed the incumbent itself (same id, new key) is not a loser.
+    if (supersedes && facet !== "decisions") {
+        const incumbent = store.getRec(facet, supersedes);
+        if (incumbent && "valid_to" in incumbent && incumbent.valid_to !== null) {
+            const subject = subjectOf(facet, incumbent);
+            const open = store.recsInHome(facet, home)
+                .filter((r) => subjectOf(facet, r) === subject && r.valid_to === null)
+                .map((r) => r.id).sort();
+            if (!open.includes(id)) {
+                const current = open.length ? `the current ${facet} record for ${subject ?? "that subject"} is ${open.join(", ")}` : `no ${facet} record for ${subject ?? "that subject"} is open now`;
+                throw new StateRefusal("conflict", `supersedes ${supersedes} was already superseded (window closed ${String(incumbent.valid_to)}); ${current}: re-read and supersede that one`, { incumbent_id: open[0] ?? supersedes, reason: "supersede target already closed" });
+            }
+            supersedes = null; // already closed by this record: nothing to close again, no second "superseded" event
+        }
+    }
     store.putCapture(facet, record, isPrivate);
     const changes = [];
     const cause = { kind: "write", principal: request.principal.id };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.27.0",
+      "version": "1.28.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {