@davesheffer/hunch 1.26.1 → 1.27.0

package/dist/cli/index.js

@@ -20,7 +20,7 @@ import { join, relative, dirname, basename, resolve, isAbsolute } from "node:pat
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget, isDir } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -5160,8 +5160,16 @@ function printAutoReviewPlan(plan) {
 program
     .command("mcp")
     .description("Start the MCP server over stdio (Claude Code connects here).")
-    .action(async () => {
+    .option("--root <dir>", "serve exactly this store or served partition and ignore the client's workspace roots and cwd hints")
+    .action(async (opts) => {
     const { startServer } = await import("../mcp/server.js");
+    if (opts.root) {
+        const pinned = resolve(opts.root);
+        if (!isDir(join(pinned, ".hunch")))
+            throw new Error(`--root ${pinned} has no .hunch/ store`);
+        await startServer(pinned, { pinned: true });
+        return;
+    }
     await startServer(process.cwd());
 });
 // ---- migrate (schema versioning) ------------------------------------------

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}$/;
@@ -88,6 +89,9 @@ export const ReadResponseSchema = z.object({
     state_of_record: StateOfRecordSchema.nullable(),
     /** Scopes the principal asked about but is not granted — named, never silently dropped. */
     denied_scopes: z.array(ScopeSchema).max(64).default([]),
+    /** 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(),
 }).strict();
 export const WriteRequestSchema = z.object({
     schema: z.literal(STATE_WRITE_VERSION),
@@ -107,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),
@@ -135,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/extractors/git.js

@@ -818,7 +818,11 @@ function stagedMemoryPaths(hunchDir, env, allowMemoryDeletions = false) {
 function isDerivedStoreArtifact(relativeName) {
     return /^[^/]+\.sqlite[^/]*$/i.test(relativeName)
         || relativeName.split("/").some((segment) => segment.includes(".tmp"))
-        || relativeName === "events.log";
+        || relativeName === "events.log"
+        // `hunch serve` flushes INSIDE its cross-process write lock, so the lock file is always
+        // staged alongside the record; treating it as a violation made every served write skip
+        // the commit quietly and report durability "local" forever (1.26.0/1.26.1).
+        || relativeName === "write.lock";
 }
 /** Enumerate ordinary JSON files already contained under an overlay. Push-capable
  * stores force-add this exact allowlist so remote .gitignore, info/exclude, or an

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";
@@ -22,6 +22,7 @@ import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
 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 { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
@@ -517,7 +518,8 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
         throw error;
     }
 }
-export function buildServerWithRootControl(initialRoot) {
+export function buildServerWithRootControl(initialRoot, options = {}) {
+    const pinned = options.pinned === true;
     const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
     const initial = prepareRoot(initialRoot, explicitOverlay, false);
     let root = initial.root;
@@ -670,7 +672,9 @@ export function buildServerWithRootControl(initialRoot) {
         // sole in-flight request — re-homing under a concurrent request would tear its
         // root/store out from under it, so that case is refused rather than risked.
         const cwdHint = extractCwdHint(args[0]);
-        if (cwdHint !== undefined) {
+        // A pinned root is the whole point of `hunch mcp --root`: a served partition must not
+        // follow the caller's working directory into some other checkout.
+        if (cwdHint !== undefined && !pinned) {
             const target = canonicalRootPath(findRoot(cwdHint));
             if (target !== canonicalRootPath(root)) {
                 if (activeRequests) {
@@ -1710,7 +1714,31 @@ export function buildServerWithRootControl(initialRoot) {
                 ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
                 : "no subject — delivery envelope only";
             const deniedNote = response.denied_scopes.length ? `\ndenied scopes: ${response.denied_scopes.map((s) => `${s.kind}/${s.id}`).join(", ")}` : "";
-            return stateResult(`${response.receipt_id} · ${summary}${deniedNote}\n\n${envelope.text}`, response);
+            // Render the state of record itself, not only its refs: a consumer answers from this text.
+            const line = (label, ref) => {
+                const r = (response.records ?? {})[ref.id] ?? {};
+                const g = (k) => { const v = r[k]; return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v); };
+                if (ref.facet === "derived")
+                    return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
+                if (ref.facet === "commitments")
+                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}`;
+                if (ref.facet === "receipts") {
+                    const t = (r.target ?? {});
+                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}`;
+                }
+                if (ref.facet === "decisions")
+                    return `- ${label} decision ${ref.id} · ${g("status")}: ${g("title")}`;
+                if (ref.facet === "constraints")
+                    return `- ${label} constraint ${ref.id} · ${g("severity")}: ${g("statement")}`;
+                if (ref.facet === "entities")
+                    return `- ${label} entity ${ref.id} · ${g("kind")} ${g("name")} · ${g("lifecycle")}`;
+                return `- ${label} ${ref.facet} ${ref.id}`;
+            };
+            const stateText = sor
+                ? [...sor.current.map((r) => line("current", r)), ...sor.in_force.map((r) => line("in force", r)), ...sor.done.map((r) => line("done", r)),
+                    ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
+                : "";
+            return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
         }
         catch (e) {
             return stateRefusal(e);
@@ -1723,9 +1751,11 @@ export function buildServerWithRootControl(initialRoot) {
         outputSchema: WriteResultSchema.shape,
     }, async ({ cwd: _cwd, ...input }) => {
         try {
-            const result = writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
+            // Same cross-process lock `hunch serve` takes: a second agent writing over stdio must
+            // not race the HTTP server between the ledger read and the record write.
+            const result = await withWriteLock(hunchPaths(root).hunch, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
                 flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
-            });
+            }));
             return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, result);
         }
         catch (e) {
@@ -1747,6 +1777,22 @@ export function buildServerWithRootControl(initialRoot) {
             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",
@@ -2290,7 +2336,9 @@ export function buildServerWithRootControl(initialRoot) {
     return {
         server,
         getRoot: () => root,
-        setRoot,
+        setRoot: (next) => { if (!pinned)
+            setRoot(next); },
+        pinned,
         cancelPendingRoot: () => { pendingRoot = null; },
     };
 }
@@ -2309,6 +2357,8 @@ function provLine(record) {
 /** Query client roots after initialization and follow later list changes.
  *  Generation ordering prevents a slow stale roots/list response from winning. */
 export function wireClientRoots(control, fallback) {
+    if (control.pinned)
+        return; // `hunch mcp --root`: the client's workspace is not this server's store
     let generation = 0;
     const syncRoots = async () => {
         const mine = ++generation;
@@ -2346,12 +2396,14 @@ export function wireClientRoots(control, fallback) {
     control.server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => { await syncRoots(); });
 }
 /** Start the stdio server (called by `hunch mcp`). */
-export async function startServer(cwd = process.cwd()) {
-    const fallback = findRoot(cwd);
-    const control = buildServerWithRootControl(fallback);
+export async function startServer(cwd = process.cwd(), options = {}) {
+    const fallback = options.pinned ? cwd : findRoot(cwd);
+    const control = buildServerWithRootControl(fallback, options);
     wireClientRoots(control, fallback);
     const transport = new StdioServerTransport();
     await control.server.connect(transport);
-    console.error(`[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
+    console.error(control.pinned
+        ? `[hunch-mcp] serving Hunch over stdio (pinned root ${control.getRoot()}; client roots ignored)`
+        : `[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
 }
 //# sourceMappingURL=server.js.map

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/serve/config.js

@@ -34,6 +34,11 @@ export const ServeConfigSchema = z.object({
     partitions: z.array(PartitionConfigSchema).min(1).max(256),
     principals: z.array(PrincipalConfigSchema).max(1024).default([]),
 }).strict();
+export const PARTITION_GITIGNORE = [
+    "# hunch serve partition — derived runtime artifacts (regenerable from .hunch/*.json)",
+    ".hunch/*.sqlite", ".hunch/*.sqlite-shm", ".hunch/*.sqlite-wal", ".hunch/*.sqlite-journal",
+    ".hunch/**/*.tmp*", ".hunch/write.lock", ".hunch/.hunch-commit.lock", ".hunch/local.json", ".hunch/events.log", "",
+].join("\n");
 export function hashToken(token) {
     return createHash("sha256").update(token, "utf8").digest("hex");
 }
@@ -104,6 +109,11 @@ export function initServeConfig(opts) {
     const manifest = resolve(hunchDir, "manifest.json");
     if (!existsSync(manifest))
         writeFileAtomic(manifest, JSON.stringify({ schema_version: 3 }, null, 2) + "\n");
+    // A served partition is meant to be its own git repository: keep the derived index, temp
+    // files and locks out of it so every auto-commit is records + ledger only.
+    const ignore = resolve(root, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileAtomic(ignore, PARTITION_GITIGNORE);
     const partitions = existing ? existing.partitions.filter((p) => scopePath(p.scope) !== scopePath(opts.scope)) : [];
     const partition = { scope: opts.scope, root };
     partitions.push(partition);

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);
@@ -118,6 +123,7 @@ export function readState(store, input) {
         profile: request.profile ?? "builder",
     });
     let stateOfRecord = null;
+    const records = {};
     const denied = new Map();
     if (request.subject !== undefined) {
         const subject = request.subject;
@@ -135,6 +141,10 @@ export function readState(store, input) {
             }
             return scope;
         };
+        const keep = (facet, record, scope) => {
+            records[record.id] = record;
+            return refOf(facet, record, scope);
+        };
         if (facets.has("decisions"))
             for (const d of store.recs("decisions")) {
                 if (d.topic !== subject && d.id !== subject)
@@ -143,7 +153,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (isLive(d))
-                    current.push(refOf("decisions", d, scope));
+                    current.push(keep("decisions", d, scope));
             }
         if (facets.has("constraints"))
             for (const c of store.recs("constraints")) {
@@ -153,7 +163,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (c.status === "active" && c.valid_to == null)
-                    inForce.push(refOf("constraints", c, scope));
+                    inForce.push(keep("constraints", c, scope));
             }
         if (facets.has("receipts"))
             for (const r of store.recs("receipts")) {
@@ -164,7 +174,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (r.state === "succeeded" || r.state === "verified")
-                    done.push(refOf("receipts", r, scope));
+                    done.push(keep("receipts", r, scope));
                 if (r.invalidates.includes(subject))
                     invalidatedBy.add(r.id);
             }
@@ -176,7 +186,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if ((c.status === "open" || c.status === "waiting") && c.valid_to == null)
-                    inForce.push(refOf("commitments", c, scope));
+                    inForce.push(keep("commitments", c, scope));
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
@@ -186,7 +196,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (d.state === "current" && d.valid_to == null) {
-                    current.push(refOf("derived", d, scope));
+                    current.push(keep("derived", d, scope));
                     dependsOn.push(...d.dependencies);
                 }
             }
@@ -198,7 +208,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (e.lifecycle === "active")
-                    current.push(refOf("entities", e, scope));
+                    current.push(keep("entities", e, scope));
             }
         if (facets.has("relationships"))
             for (const r of store.recs("relationships")) {
@@ -207,7 +217,7 @@ export function readState(store, input) {
                 const scope = admit("relationships", r);
                 if (!scope)
                     continue;
-                current.push(refOf("relationships", r, scope));
+                current.push(keep("relationships", r, scope));
             }
         stateOfRecord = { subject, current, in_force: inForce, done, depends_on: dependsOn, invalidated_by: [...invalidatedBy].sort() };
     }
@@ -217,6 +227,7 @@ export function readState(store, input) {
         scope: request.scope,
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
+        ...(stateOfRecord ? { records } : {}),
     });
     assertReadWithinGrants(request.principal, response);
     return { response, envelope };
@@ -237,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") {
@@ -323,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) {
@@ -390,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.1",
+  "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.1",
+  "version": "1.27.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.26.1",
+      "version": "1.27.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {