@davesheffer/hunch 1.26.2 → 1.27.0

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,6 +33,28 @@ 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")

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/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}$/;
@@ -110,6 +111,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 +142,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),

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";
@@ -1777,6 +1777,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

@@ -11,14 +11,15 @@
  *   POST /nuryel/v1/read              → readState
  *   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, 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 { partitionFor, resolvePrincipal } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -163,6 +164,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/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/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);
@@ -243,6 +248,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 +339,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) {
@@ -396,9 +411,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.27.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.27.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.26.2",
+      "version": "1.27.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {