@davesheffer/hunch 1.26.2 → 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

@@ -1,6 +1,8 @@
 import { resolve } from "node:path";
 import { createServeApp } from "../serve/app.js";
-import { initServeConfig, readServeConfig } from "../serve/config.js";
+import { initServeConfig, partitionFor, readServeConfig } from "../serve/config.js";
+import { compactLedger } from "../store/changeLedger.js";
+import { join } from "node:path";
 import { ScopeSchema, scopePath } from "../core/stateContract.js";
 import { HUNCH_VERSION } from "../core/version.js";
 function parseScopeArg(value) {
@@ -31,9 +33,31 @@ export function registerServeCommands(program) {
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     });
+    serve.command("compact")
+        .description("Compact a served partition's change ledger: keep the newest N events, move the floor up; subscribers below the floor resynchronize")
+        .requiredOption("--partition <kind:id>", "the partition whose ledger to compact")
+        .option("--keep <n>", "events to keep", "1000")
+        .option("--json", "machine-readable output")
+        .action((opts) => {
+        const parent = serve.opts();
+        const config = readServeConfig(resolve(parent.config ?? DEFAULT_CONFIG));
+        const scope = parseScopeArg(opts.partition);
+        const partition = partitionFor(config, scope);
+        if (!partition)
+            throw new Error(`this config does not serve ${scopePath(scope)}`);
+        const keep = Number(opts.keep);
+        if (!Number.isInteger(keep) || keep < 0)
+            throw new Error("--keep must be a non-negative integer");
+        const result = compactLedger(join(partition.root, ".hunch"), scope, { keep });
+        if (opts.json) {
+            console.log(JSON.stringify({ partition: scopePath(scope), ...result }));
+            return;
+        }
+        console.log(result.dropped ? `${scopePath(scope)}: dropped ${result.dropped} event(s); floor ${result.floor_seq}, head ${result.head_seq}` : `${scopePath(scope)}: nothing to compact (${result.head_seq - result.floor_seq} events retained)`);
+    });
     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/client/state.js

@@ -42,6 +42,7 @@ export function createStateClient(opts) {
         read: (request) => call("POST", "/nuryel/v1/read", request),
         write: (request) => call("POST", "/nuryel/v1/write", request),
         subscribe: (request) => call("POST", "/nuryel/v1/subscribe", request),
+        records: (request) => call("POST", "/nuryel/v1/records", request),
         health: () => call("GET", "/nuryel/v1/health"),
     };
 }

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

@@ -34,10 +34,11 @@ export const STATE_CONTRACT_VERSION = "nuryel.state/1";
 export const STATE_READ_VERSION = "nuryel.state.read/1";
 export const STATE_WRITE_VERSION = "nuryel.state.write/1";
 export const STATE_SUBSCRIBE_VERSION = "nuryel.state.subscribe/1";
+export const STATE_RECORDS_VERSION = "nuryel.state.records/1";
 /** Capabilities a server advertises; a client that needs one the server lacks gets a typed
  *  `unsupported`, never a compatible-looking degraded answer. */
 export const STATE_CAPABILITIES = [
-    STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION,
+    STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION,
     RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION,
 ];
 const SHA256 = /^sha256:[a-f0-9]{64}$/;
@@ -55,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(),
@@ -91,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),
@@ -110,6 +122,9 @@ export const WriteResultSchema = z.object({
     durability: z.enum(DURABILITY),
     outcome: z.enum(["created", "updated", "replayed", "superseded"]),
     conflict: z.object({ incumbent_id: z.string().max(2048), reason: z.string().max(512) }).strict().nullable().default(null),
+    /** The record as stored (after normalization and identity derivation), so a writer can verify
+     *  what landed without a second lookup. Additive. */
+    record: z.record(z.string(), z.unknown()).optional(),
 }).strict();
 export const SubscribeRequestSchema = z.object({
     schema: z.literal(STATE_SUBSCRIBE_VERSION),
@@ -138,6 +153,23 @@ export const ChangeEventSchema = z.object({
         z.object({ kind: z.literal("write"), principal: z.string().regex(TOKEN) }).strict(),
     ]).optional(),
 }).strict();
+/** records — fetch records by id, grants first. A subscribe event names a record; this is how
+ *  a consumer gets its body without a subject read. Ids outside the grants are named in
+ *  `denied`, unknown ids in `missing`; neither is silently dropped. */
+export const RecordsRequestSchema = z.object({
+    schema: z.literal(STATE_RECORDS_VERSION),
+    principal: PrincipalSchema,
+    scope: ScopeSchema,
+    ids: z.array(z.string().min(1).max(2048)).min(1).max(256),
+}).strict();
+export const RecordsResponseSchema = z.object({
+    schema: z.literal(STATE_RECORDS_VERSION),
+    scope: ScopeSchema,
+    records: z.record(z.string(), z.record(z.string(), z.unknown())),
+    facets: z.record(z.string(), z.enum(STATE_FACETS)),
+    missing: z.array(z.string().max(2048)).default([]),
+    denied: z.array(z.string().max(2048)).default([]),
+}).strict();
 export const CapabilityNegotiationSchema = z.object({
     protocol: z.literal(STATE_CONTRACT_VERSION),
     capabilities: z.array(z.string().max(128)).max(64),
@@ -215,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

@@ -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, subscribeState, writeState } from "../store/stateBinding.js";
-import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION } from "../core/stateContract.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 { 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")}`);
     });
@@ -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}`,
@@ -1777,6 +1784,22 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return stateRefusal(e);
         }
     });
+    server.registerTool("nuryel_records", {
+        title: "nuryel.state/1 records — fetch records by id, grants first",
+        description: "Fetch state records by id (from a subscribe event, a read ref, or a write result). Every id is accounted for: found (with its facet), denied (its scope is outside your grants — named, never described) or missing.",
+        inputSchema: RecordsRequestSchema.omit({ schema: true }).shape,
+        outputSchema: RecordsResponseSchema.shape,
+    }, async (input) => {
+        try {
+            const response = recordsState(store, { schema: STATE_RECORDS_VERSION, ...input });
+            const lines = Object.entries(response.records).map(([id, r]) => `- ${response.facets[id]} ${id}: ${JSON.stringify(r).slice(0, 600)}`);
+            const tail = [...(response.missing.length ? [`missing: ${response.missing.join(", ")}`] : []), ...(response.denied.length ? [`denied: ${response.denied.join(", ")}`] : [])];
+            return stateResult(`${Object.keys(response.records).length} record(s)\n${lines.join("\n")}${tail.length ? `\n${tail.join("\n")}` : ""}`, response);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
     // -- hunch_findings (read: the open-observations ledger) --------------------
     server.registerTool("hunch_findings", {
         title: "Open findings for a scope",

package/dist/serve/app.js

@@ -8,17 +8,19 @@
  *
  * 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)
  * Request bodies are the contract's request schemas minus `schema` and `principal`.
  */
 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, subscribeState, writeState } from "../store/stateBinding.js";
-import { STATE_READ_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";
@@ -147,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);
@@ -163,6 +183,11 @@ export function createServeApp(config, opts = {}) {
                 const { store } = storeFor(scope);
                 return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }));
             }
+            if (url.pathname === "/nuryel/v1/records") {
+                const scope = requireScope(principal, body);
+                const { store } = storeFor(scope);
+                return send(res, 200, recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }));
+            }
             throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
         }
         catch (error) {

package/dist/store/changeLedger.js

@@ -28,6 +28,9 @@ export const LedgerSchema = z.object({
     schema: z.literal(LEDGER_SCHEMA_VERSION),
     scope: ScopeSchema,
     head_seq: z.number().int().nonnegative(),
+    /** Events below this seq were compacted away. `events` starts at floor_seq + 1. A subscriber
+     *  whose cursor is below the floor must resynchronize (the contract's gap rule, made explicit). */
+    floor_seq: z.number().int().nonnegative().default(0),
     events: z.array(ChangeEventSchema),
     idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
 }).strict();
@@ -40,7 +43,7 @@ export function ledgerFile(hunchDir, scope) {
     return join(hunchDir, CHANGES_DIR, `${scope.kind}-${safe}-${tag}.json`);
 }
 export function emptyLedger(scope) {
-    return { schema: LEDGER_SCHEMA_VERSION, scope, head_seq: 0, events: [], idempotency: {} };
+    return { schema: LEDGER_SCHEMA_VERSION, scope, head_seq: 0, floor_seq: 0, events: [], idempotency: {} };
 }
 /** Read the ledger for a scope; a missing file is an empty ledger, a corrupt one is an
  *  error (never silently treated as empty — that would restart the sequence). */
@@ -52,14 +55,14 @@ export function readLedger(hunchDir, scope) {
     const ledger = LedgerSchema.parse(raw);
     if (scopePath(ledger.scope) !== scopePath(scope))
         throw new Error(`ledger ${file} belongs to scope ${scopePath(ledger.scope)}, not ${scopePath(scope)}`);
-    let expected = 1;
+    let expected = ledger.floor_seq + 1;
     for (const event of ledger.events) {
         if (event.seq !== expected)
             throw new Error(`ledger ${file} is not contiguous at seq ${event.seq} (expected ${expected})`);
         expected += 1;
     }
-    if (ledger.head_seq !== ledger.events.length)
-        throw new Error(`ledger ${file} head_seq ${ledger.head_seq} disagrees with ${ledger.events.length} events`);
+    if (ledger.head_seq !== ledger.floor_seq + ledger.events.length)
+        throw new Error(`ledger ${file} head_seq ${ledger.head_seq} disagrees with floor ${ledger.floor_seq} + ${ledger.events.length} events`);
     return ledger;
 }
 export function writeLedger(hunchDir, ledger) {
@@ -93,4 +96,58 @@ export function latestSeqFor(ledger, recordId) {
     }
     return 0;
 }
+/** Keep the newest `keep` events; everything older is dropped and the floor moves up. The
+ *  idempotency table is kept whole (it is what makes replays exact); the records themselves are
+ *  untouched. Returns how many events were dropped. */
+export function compactLedger(hunchDir, scope, opts = {}) {
+    const keep = Math.max(0, Math.floor(opts.keep ?? 1000));
+    const ledger = readLedger(hunchDir, scope);
+    const dropped = Math.max(0, ledger.events.length - keep);
+    if (dropped === 0)
+        return { dropped: 0, floor_seq: ledger.floor_seq, head_seq: ledger.head_seq };
+    ledger.events = ledger.events.slice(dropped);
+    ledger.floor_seq = ledger.head_seq - ledger.events.length;
+    writeLedger(hunchDir, ledger);
+    return { dropped, floor_seq: ledger.floor_seq, head_seq: ledger.head_seq };
+}
+const eventIdentity = (e) => [e.change, e.facet, e.record_id, e.record_hash, e.at, e.cause ? JSON.stringify(e.cause) : ""].join("|");
+/** Three-way merge of one scope's ledger, for the git merge driver: two clones that both
+ *  appended to the same partition. The union of events is kept (identity = what changed, to
+ *  which hash, when, by whom), ordered by time then ours-before-theirs, and RE-SEQUENCED from
+ *  the higher floor; every subscriber's cursor is therefore invalid after a merge and the gap
+ *  rule makes it resynchronize. Idempotency entries are unioned; a key both sides used for
+ *  different records is a conflict the caller must surface (ours is kept). */
+export function mergeLedgers(base, ours, theirs) {
+    if (scopePath(ours.scope) !== scopePath(theirs.scope))
+        throw new Error("ledgers for different scopes cannot be merged");
+    const seen = new Map();
+    const order = [];
+    const add = (e) => { const k = eventIdentity(e); if (!seen.has(k)) {
+        seen.set(k, e);
+        order.push(e);
+    } };
+    for (const e of base?.events ?? [])
+        add(e);
+    for (const e of ours.events)
+        add(e);
+    for (const e of theirs.events)
+        add(e);
+    const ranked = order.map((e, i) => ({ e, i, side: (ours.events.includes(e) ? 0 : 1) }));
+    ranked.sort((a, b) => a.e.at.localeCompare(b.e.at) || a.side - b.side || a.i - b.i);
+    const floor = Math.max(base?.floor_seq ?? 0, ours.floor_seq, theirs.floor_seq);
+    const events = ranked.map(({ e }, i) => ({ ...e, seq: floor + i + 1 }));
+    const conflicts = [];
+    const idempotency = { ...(base?.idempotency ?? {}), ...theirs.idempotency, ...ours.idempotency };
+    for (const [key, entry] of Object.entries(theirs.idempotency)) {
+        const mine = ours.idempotency[key];
+        if (mine && mine.record_id !== entry.record_id)
+            conflicts.push(`idempotency key ${key}: ours ${mine.record_id}, theirs ${entry.record_id} (kept ours)`);
+    }
+    for (const key of Object.keys(idempotency)) {
+        const entry = idempotency[key];
+        const at = events.find((e) => e.record_id === entry.record_id && e.record_hash === entry.record_hash);
+        idempotency[key] = { ...entry, seq: at ? at.seq : Math.min(entry.seq, floor + events.length) };
+    }
+    return { ledger: { schema: LEDGER_SCHEMA_VERSION, scope: ours.scope, floor_seq: floor, head_seq: floor + events.length, events, idempotency }, conflicts };
+}
 //# sourceMappingURL=changeLedger.js.map

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/merge.js

@@ -17,9 +17,15 @@
  * content tiebreak (so both developers' merges converge on the same result). Records
  * are pure data here — no filesystem access; the CLI reads/writes the files.
  */
+import { LEDGER_SCHEMA_VERSION, LedgerSchema, mergeLedgers } from "./changeLedger.js";
 /** Merge three versions of one `.hunch` JSON file (an index array OR a single
  *  record object). Returns the merged text, or conflict=true to fall back. */
 export function mergeHunchJson(baseText, oursText, theirsText) {
+    // A per-scope change ledger is not a record array: two clones that both appended get the
+    // union of their events, re-sequenced, and unioned idempotency tables (see mergeLedgers).
+    const ledger = mergeLedgerText(baseText, oursText, theirsText);
+    if (ledger)
+        return ledger;
     const ours = parseSide(oursText);
     const theirs = parseSide(theirsText);
     const base = parseSide(baseText);
@@ -42,6 +48,34 @@ export function mergeHunchJson(baseText, oursText, theirsText) {
         return { text: oursText, conflict: true };
     return { text: serialize(merged[0]), conflict: false };
 }
+function mergeLedgerText(baseText, oursText, theirsText) {
+    const parse = (text) => {
+        if (!text.trim())
+            return null;
+        try {
+            const raw = JSON.parse(text);
+            return raw && raw.schema === LEDGER_SCHEMA_VERSION ? LedgerSchema.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const ours = parse(oursText);
+    const theirs = parse(theirsText);
+    if (!ours && !theirs)
+        return null;
+    if (!ours || !theirs)
+        return null; // one side is not a ledger (or deleted it): let git surface it
+    try {
+        const { ledger, conflicts } = mergeLedgers(parse(baseText), ours, theirs);
+        if (conflicts.length)
+            return { text: oursText, conflict: true };
+        return { text: JSON.stringify(ledger, null, 2) + "\n", conflict: false };
+    }
+    catch {
+        return { text: oursText, conflict: true };
+    }
+}
 /** Three-way merge of record arrays keyed by `id`. Additions on either side are
  *  kept; a record changed on one side only takes that side; a delete is honored
  *  only if the other side left the record unchanged (a modification beats a delete);

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

@@ -26,7 +26,7 @@ import { decisionId } from "../core/ids.js";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { captureConflicts, isLive } from "../core/topics.js";
 import { buildDeliveryEnvelope } from "../core/delivery.js";
-import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, ScopeSchema, scopePath, stateHash, actionReceiptId, commitmentId, derivedId, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, } from "../core/stateContract.js";
+import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_RECORDS_VERSION, ScopeSchema, scopePath, stateHash, actionReceiptId, commitmentId, derivedId, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, } from "../core/stateContract.js";
 /** A typed refusal. `code` is stable for bindings; `conflict` names the incumbent when one exists. */
 export class StateRefusal extends Error {
     code;
@@ -68,6 +68,11 @@ export const SubscribeResponseSchema = z.object({
     /** True when facet / subject filters were applied: `events` is then a subsequence and
      *  assertChangeSequence does not apply; `head_seq` remains the cursor. */
     filtered: z.boolean(),
+    /** Events below this seq were compacted away. */
+    floor_seq: z.number().int().nonnegative().default(0),
+    /** True when `after_seq` was below the floor: the caller's cursor is stale, the events returned
+     *  start at the floor, and the caller must rebuild what it holds from a read. */
+    resync: z.boolean().default(false),
 }).strict();
 export function capabilities(store) {
     const own = partitionOf(store);
@@ -120,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 = [];
@@ -223,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;
@@ -243,6 +330,11 @@ function subjectOf(facet, record) {
         default: return undefined;
     }
 }
+/** Top-level fields whose canonical hash differs between two records, sorted. */
+function differingFields(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].filter((k) => stateHash(a[k] ?? null) !== stateHash(b[k] ?? null)).sort();
+}
 /** Records the store can close a valid-time window on when superseded. */
 function closeWindow(store, facet, incumbentId, byId, at, isPrivate) {
     if (facet === "decisions") {
@@ -329,14 +421,19 @@ export function writeState(store, input, opts = {}) {
     const hash = stateHash(record);
     const ledger = readLedger(hunchDir, request.scope);
     const durability = () => opts.flush?.(isPrivate, `nuryel: write ${id}`) ?? "local";
-    const result = (outcome, conflict = null, rid = id, rhash = hash) => WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: rhash, durability: durability(), outcome, conflict });
+    const result = (outcome, conflict = null, rid = id, rhash = hash) => WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: rhash, durability: durability(), outcome, conflict, record: store.getRec(facet, rid) ?? record });
     // Idempotency: the same key replays the original; the same key with a different payload
     // is a refusal, never a second record.
     const seen = ledger.idempotency[request.idempotency_key];
     if (seen) {
         if (seen.record_hash === hash && seen.record_id === id)
             return result("replayed");
-        throw new StateRefusal("idempotency", `idempotency key was already used for ${seen.record_id} with a different payload`, { incumbent_id: seen.record_id, reason: "idempotency key reused with a different payload" });
+        // Say WHAT differs and what to do: a stable key with a varying payload (a timestamp, new
+        // wording) is the trap every writer falls into once; the refusal must teach the way out.
+        const stored = store.getRec(facet, seen.record_id);
+        const differing = stored ? differingFields(stored, record) : [];
+        const where = differing.length ? ` — this payload differs in: ${differing.join(", ")}` : (seen.record_id !== id ? ` — this payload derives a different identity (${id})` : "");
+        throw new StateRefusal("idempotency", `idempotency key "${request.idempotency_key}" was already used for ${seen.record_id}${where}. A key names ONE request payload: re-send the original payload to replay it, or use a new key to write this payload (the record keeps its derived id and is updated in place).`, { incumbent_id: seen.record_id, reason: "idempotency key reused with a different payload" });
     }
     const existing = store.recsInHome(facet, home).find((r) => r.id === id);
     if (existing && stateHash(existing) === hash) {
@@ -367,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 };
@@ -396,9 +511,46 @@ export function subscribeState(store, input) {
     const facets = request.facets ? new Set(request.facets) : null;
     const subjects = request.subjects ? new Set(request.subjects) : null;
     const filtered = !!(facets || subjects);
-    const events = ledger.events.filter((e) => e.seq > request.after_seq
+    const resync = request.after_seq < ledger.floor_seq;
+    const after = resync ? ledger.floor_seq : request.after_seq;
+    const events = ledger.events.filter((e) => e.seq > after
         && (!facets || facets.has(e.facet))
         && (!subjects || subjects.has(e.record_id) || (e.subject !== undefined && subjects.has(e.subject)) || e.invalidates.some((s) => subjects.has(s))));
-    return SubscribeResponseSchema.parse({ schema: STATE_SUBSCRIBE_VERSION, scope: request.scope, head_seq: ledger.head_seq, events, filtered });
+    return SubscribeResponseSchema.parse({ schema: STATE_SUBSCRIBE_VERSION, scope: request.scope, head_seq: ledger.head_seq, events, filtered, floor_seq: ledger.floor_seq, resync });
+}
+// ---- records ------------------------------------------------------------------------------
+/** records — fetch by id, grants first. Every id is accounted for: found, denied (its scope is
+ *  outside the grants — named, never described) or missing. */
+export function recordsState(store, input) {
+    const request = RecordsRequestSchema.parse(input);
+    if (!granted(request.principal, request.scope))
+        throw new StateRefusal("outside-grants", `scope ${scopePath(request.scope)} is outside the principal's grants`);
+    const repo = partitionOf(store);
+    const records = {};
+    const facets = {};
+    const denied = [];
+    const missing = [];
+    for (const id of new Set(request.ids)) {
+        let found = null;
+        for (const facet of STATE_FACETS) {
+            const record = store.getRec(facet, id);
+            if (record) {
+                found = { facet, record };
+                break;
+            }
+        }
+        if (!found) {
+            missing.push(id);
+            continue;
+        }
+        const scope = recordScope(found.record, repo);
+        if (!granted(request.principal, scope)) {
+            denied.push(id);
+            continue;
+        }
+        records[id] = found.record;
+        facets[id] = found.facet;
+    }
+    return RecordsResponseSchema.parse({ schema: STATE_RECORDS_VERSION, scope: request.scope, records, facets, missing, denied });
 }
 //# sourceMappingURL=stateBinding.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.26.2",
+  "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.26.2",
+  "version": "1.28.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.26.2",
+      "version": "1.28.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {