@davesheffer/hunch 1.24.0 → 1.26.0

package/dist/serve/app.js

@@ -0,0 +1,186 @@
+/**
+ * `hunch serve` — the HTTP binding of nuryel.state/1, and the served product's partition host.
+ *
+ * Folded in from Hunch Memory: bind 127.0.0.1 (the caller's job; never expose a port), a
+ * bearer token that resolves the PRINCIPAL (the body never names one — grants come from the
+ * config, never from the caller), problem+json errors, a body limit, and a cross-process
+ * write lock per partition so a stdio MCP process on the same store cannot race a write.
+ *
+ * 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/write             → writeState (under the partition's write lock)
+ *   POST /nuryel/v1/subscribe         → subscribeState
+ * 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 { partitionFor, resolvePrincipal } from "./config.js";
+import { WriteLockTimeout, withWriteLock } from "./writelock.js";
+import { HUNCH_VERSION } from "../core/version.js";
+export const BODY_LIMIT_BYTES = 1024 * 1024;
+export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
+export class HttpProblem extends Error {
+    status;
+    code;
+    extra;
+    constructor(status, code, message, extra = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.extra = extra;
+        this.name = "HttpProblem";
+    }
+}
+const problem = (status, code, message, extra = {}) => new HttpProblem(status, code, message, extra);
+/** Refusal code → HTTP status. Outside-grants is 403 (the partition list is not secret to a
+ *  principal that holds a token), conflicts are 409, identity/derivation errors 422. */
+const REFUSAL_STATUS = {
+    "outside-grants": 403, unsupported: 400, malformed: 400, identity: 422, conflict: 409, idempotency: 409, "no-partition-home": 404,
+};
+function bearerToken(req) {
+    const header = req.headers.authorization;
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (!/^bearer /i.test(trimmed))
+        return undefined;
+    const token = trimmed.slice("bearer ".length).trim();
+    return token || undefined;
+}
+async function readBody(req) {
+    const declared = req.headers["content-length"];
+    if (declared !== undefined) {
+        if (Array.isArray(declared) || !/^[0-9]+$/.test(declared))
+            throw problem(400, "invalid-body", "content-length is not valid");
+        if (Number(declared) > BODY_LIMIT_BYTES)
+            throw problem(413, "body-too-large", `body exceeds ${BODY_LIMIT_BYTES} bytes`);
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > BODY_LIMIT_BYTES)
+            throw problem(413, "body-too-large", `body exceeds ${BODY_LIMIT_BYTES} bytes`);
+        chunks.push(chunk);
+    }
+    if (size === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw problem(400, "invalid-body", "body is not a JSON object");
+    }
+}
+function parseScopeParam(value) {
+    if (!value)
+        return undefined;
+    const m = /^([a-z]+):(.+)$/.exec(value);
+    const parsed = m ? ScopeSchema.safeParse({ kind: m[1], id: m[2] }) : null;
+    if (!parsed?.success)
+        throw problem(400, "invalid-scope", "scope must be kind:id");
+    return parsed.data;
+}
+export function createServeApp(config, opts = {}) {
+    const version = opts.version ?? HUNCH_VERSION;
+    const stores = new Map();
+    const storeFor = (scope) => {
+        const partition = partitionFor(config, scope);
+        if (!partition)
+            throw problem(404, "no-partition", `this server does not serve ${scopePath(scope)}`);
+        let store = stores.get(partition.root);
+        if (!store) {
+            store = opts.openStore ? opts.openStore(partition.root) : new HunchStore(hunchPaths(partition.root));
+            store.json.ensureDirs();
+            stores.set(partition.root, store);
+        }
+        return { store, root: partition.root };
+    };
+    /** Grants are checked here AND inside the binding — the binding's check is the contract's, this
+     *  one refuses before a store is even opened. */
+    const requireScope = (principal, body) => {
+        const parsed = ScopeSchema.safeParse(body.scope);
+        if (!parsed.success)
+            throw problem(400, "invalid-scope", "scope is required: { kind, id }");
+        if (!principal.grants.some((g) => scopePath(g) === scopePath(parsed.data)))
+            throw problem(403, "outside-grants", `scope ${scopePath(parsed.data)} is outside the principal's grants`);
+        return parsed.data;
+    };
+    const send = (res, status, payload, type = "application/json") => {
+        const text = JSON.stringify(payload);
+        res.writeHead(status, { "content-type": `${type}; charset=utf-8`, "content-length": Buffer.byteLength(text), "cache-control": "no-store", "x-hunch-version": version });
+        res.end(text);
+    };
+    const sendProblem = (res, p) => {
+        send(res, p.status, { type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra }, "application/problem+json");
+    };
+    const server = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname === "/nuryel/v1/health" && req.method === "GET") {
+                return send(res, 200, { ok: true, version, protocol: "nuryel.state/1", partitions: config.partitions.map((p) => scopePath(p.scope)) });
+            }
+            const principal = resolvePrincipal(config, bearerToken(req));
+            if (!principal)
+                throw problem(401, "unauthorized", "a valid bearer token is required");
+            if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
+                const scope = parseScopeParam(url.searchParams.get("scope")) ?? principal.grants[0];
+                if (!principal.grants.some((g) => scopePath(g) === scopePath(scope)))
+                    throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
+                const { store } = storeFor(scope);
+                return send(res, 200, { ...capabilities(store), principal: { id: principal.id, kind: principal.kind, grants: principal.grants } });
+            }
+            if (req.method !== "POST")
+                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
+            const body = await readBody(req);
+            // The body never names the principal: the token did.
+            delete body.principal;
+            delete body.schema;
+            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 (url.pathname === "/nuryel/v1/write") {
+                const scope = requireScope(principal, body);
+                const { store, root } = storeFor(scope);
+                const result = await withWriteLock(hunchPaths(root).hunch, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
+                }));
+                return send(res, result.outcome === "created" ? 201 : 200, result);
+            }
+            if (url.pathname === "/nuryel/v1/subscribe") {
+                const scope = requireScope(principal, body);
+                const { store } = storeFor(scope);
+                return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }));
+            }
+            throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
+        }
+        catch (error) {
+            if (error instanceof HttpProblem)
+                return sendProblem(res, error);
+            if (error instanceof StateRefusal)
+                return sendProblem(res, problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {}));
+            if (error instanceof WriteLockTimeout)
+                return sendProblem(res, problem(503, "write-lock-timeout", error.message, { "retry-after": 1 }));
+            if (error && typeof error === "object" && error.name === "ZodError") {
+                const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
+                return sendProblem(res, problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues }));
+            }
+            return sendProblem(res, problem(500, "internal", error.message));
+        }
+    });
+    const closeStores = () => { for (const store of stores.values())
+        store.close(); stores.clear(); };
+    return Object.assign(server, { closeStores });
+}
+//# sourceMappingURL=app.js.map

package/dist/serve/config.js

@@ -0,0 +1,121 @@
+/**
+ * `hunch serve` configuration — the served partitions and the principals allowed in.
+ *
+ * A partition is a directory holding a `.hunch/` store whose `.hunch/partition.json`
+ * names the scope it IS (organization / team / user / repository). A principal is a
+ * bearer token (stored as a sha256 hash — plaintext is printed once by `serve init`)
+ * bound to a principal id, kind and grants. The request body never carries a principal:
+ * the token resolves it, and grants are decided from this file, never from the caller.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../core/io.js";
+import { ScopeSchema, scopePath } from "../core/stateContract.js";
+export const SERVE_CONFIG_VERSION = "nuryel.serve-config/1";
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
+export const PartitionConfigSchema = z.object({
+    scope: ScopeSchema,
+    /** Directory whose `.hunch/` holds the partition. Relative paths resolve from the config file. */
+    root: z.string().min(1),
+}).strict();
+export const PrincipalConfigSchema = z.object({
+    id: z.string().regex(TOKEN),
+    kind: z.enum(["human", "agent", "service"]),
+    display: z.string().max(256).optional(),
+    /** sha256 hex of the bearer token. */
+    token_sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    grants: z.array(ScopeSchema).min(1).max(64),
+}).strict();
+export const ServeConfigSchema = z.object({
+    schema: z.literal(SERVE_CONFIG_VERSION),
+    port: z.number().int().min(1).max(65535).default(7474),
+    partitions: z.array(PartitionConfigSchema).min(1).max(256),
+    principals: z.array(PrincipalConfigSchema).max(1024).default([]),
+}).strict();
+export function hashToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+export function mintToken() {
+    return `nyt_${randomBytes(24).toString("base64url")}`;
+}
+export function readServeConfig(file) {
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    const config = ServeConfigSchema.parse(raw);
+    const base = dirname(resolve(file));
+    const partitions = config.partitions.map((p) => ({ ...p, root: resolve(base, p.root) }));
+    const seen = new Set();
+    for (const p of partitions) {
+        const key = scopePath(p.scope);
+        if (seen.has(key))
+            throw new Error(`serve config lists partition ${key} twice`);
+        seen.add(key);
+    }
+    const ids = new Set();
+    for (const p of config.principals) {
+        if (ids.has(p.id))
+            throw new Error(`serve config lists principal ${p.id} twice`);
+        ids.add(p.id);
+        for (const g of p.grants)
+            if (!seen.has(scopePath(g)))
+                throw new Error(`principal ${p.id} is granted ${scopePath(g)}, which this server does not serve`);
+    }
+    return { ...config, partitions, file: resolve(file) };
+}
+export function writeServeConfig(file, config) {
+    mkdirSync(dirname(resolve(file)), { recursive: true });
+    writeFileAtomic(resolve(file), JSON.stringify(ServeConfigSchema.parse(config), null, 2) + "\n");
+}
+/** Constant-time token → principal. Undefined for a missing or unknown token. */
+export function resolvePrincipal(config, token) {
+    if (!token)
+        return undefined;
+    const hash = Buffer.from(hashToken(token), "hex");
+    for (const p of config.principals) {
+        const candidate = Buffer.from(p.token_sha256, "hex");
+        if (candidate.length === hash.length && timingSafeEqual(candidate, hash)) {
+            return { id: p.id, kind: p.kind, ...(p.display ? { display: p.display } : {}), grants: p.grants };
+        }
+    }
+    return undefined;
+}
+export function partitionFor(config, scope) {
+    return config.partitions.find((p) => scopePath(p.scope) === scopePath(scope));
+}
+/** `serve init`: ensure a partition directory declares its scope, and add a principal
+ *  with a freshly minted token. Idempotent for the partition; a principal id that
+ *  already exists gets a NEW token (rotation), the old one stops working. */
+export function initServeConfig(opts) {
+    const file = resolve(opts.file);
+    const existing = existsSync(file) ? readServeConfig(file) : null;
+    const root = resolve(opts.root);
+    const hunchDir = resolve(root, ".hunch");
+    mkdirSync(hunchDir, { recursive: true });
+    const partitionFile = resolve(hunchDir, "partition.json");
+    if (existsSync(partitionFile)) {
+        const declared = ScopeSchema.parse(JSON.parse(readFileSync(partitionFile, "utf8")));
+        if (scopePath(declared) !== scopePath(opts.scope))
+            throw new Error(`${root} already declares partition ${scopePath(declared)}, not ${scopePath(opts.scope)}`);
+    }
+    else {
+        writeFileAtomic(partitionFile, JSON.stringify(opts.scope, null, 2) + "\n");
+    }
+    const manifest = resolve(hunchDir, "manifest.json");
+    if (!existsSync(manifest))
+        writeFileAtomic(manifest, JSON.stringify({ schema_version: 3 }, null, 2) + "\n");
+    const partitions = existing ? existing.partitions.filter((p) => scopePath(p.scope) !== scopePath(opts.scope)) : [];
+    const partition = { scope: opts.scope, root };
+    partitions.push(partition);
+    let principals = existing?.principals ?? [];
+    let token = null;
+    if (opts.principal) {
+        token = mintToken();
+        const grants = opts.principal.grants?.length ? opts.principal.grants : [opts.scope];
+        principals = [...principals.filter((p) => p.id !== opts.principal.id), { id: opts.principal.id, kind: opts.principal.kind, token_sha256: hashToken(token), grants }];
+    }
+    const config = { schema: SERVE_CONFIG_VERSION, port: opts.port ?? existing?.port ?? 7474, partitions, principals };
+    writeServeConfig(file, config);
+    return { config, token, partition };
+}
+//# sourceMappingURL=config.js.map

package/dist/serve/writelock.js

@@ -0,0 +1,116 @@
+/**
+ * Cross-process write lock, one per partition root — folded in from Hunch Memory
+ * (src/service/writelock.ts there), where it held the one-live-decision-per-topic
+ * guarantee across the HTTP process and a stdio MCP process sharing a store.
+ *
+ * The state binding reads the ledger and the incumbent records, then writes; two
+ * processes can both complete the read before either writes. An in-process mutex
+ * does not span processes, so the lock is a file created with `open(path, "wx")` —
+ * atomic on POSIX and Windows. A holder that dies leaves the file behind; a lock is
+ * stealable once its owner is provably gone (pid dead on the same host) or older
+ * than any plausible write.
+ */
+import { hostname } from "node:os";
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { join } from "node:path";
+/** Longest a write may hold the lock before another process may steal it: a put plus a
+ *  git commit and push — seconds, not minutes. */
+export const STALE_AFTER_MS = 60_000;
+/** Longest a writer waits before giving up and telling the caller. */
+export const ACQUIRE_TIMEOUT_MS = 10_000;
+const POLL_MS = 25;
+export class WriteLockTimeout extends Error {
+    path;
+    heldBy;
+    waitedMs;
+    constructor(path, heldBy, waitedMs) {
+        super(heldBy
+            ? `write lock on ${path} held by pid ${heldBy.pid} on ${heldBy.host} since ${heldBy.at}; waited ${waitedMs}ms`
+            : `write lock on ${path} not acquired within ${waitedMs}ms`);
+        this.path = path;
+        this.heldBy = heldBy;
+        this.waitedMs = waitedMs;
+        this.name = "WriteLockTimeout";
+    }
+}
+export function writeLockPath(hunchDir) {
+    return join(hunchDir, "write.lock");
+}
+function readOwner(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.pid !== "number" || typeof parsed.nonce !== "string")
+            return undefined;
+        return { pid: parsed.pid, host: typeof parsed.host === "string" ? parsed.host : "", nonce: parsed.nonce, at: typeof parsed.at === "string" ? parsed.at : "" };
+    }
+    catch {
+        return undefined; // released between our open and this read, or truncated by a crash — age decides
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM"; // exists, another user — alive for our purposes
+    }
+}
+function stealable(path, owner, now) {
+    let ageMs;
+    try {
+        ageMs = now - statSync(path).mtimeMs;
+    }
+    catch {
+        return false;
+    }
+    if (owner && owner.host === hostname() && !pidAlive(owner.pid))
+        return true;
+    return ageMs > STALE_AFTER_MS;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+export async function withWriteLock(hunchDir, fn, opts = {}) {
+    const path = writeLockPath(hunchDir);
+    const timeoutMs = opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS;
+    const nonce = randomBytes(8).toString("hex");
+    const started = Date.now();
+    let fd;
+    let lastOwner;
+    for (;;) {
+        try {
+            fd = openSync(path, "wx");
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            lastOwner = readOwner(path);
+            if (stealable(path, lastOwner, Date.now())) {
+                rmSync(path, { force: true });
+                continue;
+            }
+            if (Date.now() - started >= timeoutMs)
+                throw new WriteLockTimeout(path, lastOwner, Date.now() - started);
+            await sleep(POLL_MS);
+        }
+    }
+    const owner = { pid: process.pid, host: hostname(), nonce, at: new Date().toISOString() };
+    try {
+        writeSync(fd, JSON.stringify(owner));
+    }
+    catch { /* held by existence; identity is a courtesy */ }
+    closeSync(fd);
+    try {
+        return await fn();
+    }
+    finally {
+        // Only remove a lock that is still ours: if we overran STALE_AFTER_MS and were stolen
+        // from, the file now protects another writer.
+        const current = readOwner(path);
+        if (!current || current.nonce === nonce)
+            rmSync(path, { force: true });
+    }
+}
+//# sourceMappingURL=writelock.js.map

package/dist/store/changeLedger.js

@@ -0,0 +1,96 @@
+/**
+ * The per-scope change ledger behind `subscribe` — nuryel.ledger/1.
+ *
+ * One JSON file per scope partition under `<hunch dir>/changes/`, git-native like every
+ * other record, appended atomically (con_902759b3dc). It holds the strictly ordered
+ * ChangeEvent stream for that scope (seq 1, 2, 3 … with no gaps) plus the idempotency
+ * table the write verb replays from. Seq is per scope, assigned by the writer in the
+ * home the scope lives in; a scope has exactly ONE ledger, so there is never a second
+ * sequence to reconcile. Merging two clones' ledgers for the same scope is not decided
+ * here (see docs/nuryel-state-contract.md, "Not decided here").
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { writeFileAtomic } from "../core/io.js";
+import { ChangeEventSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
+export const LEDGER_SCHEMA_VERSION = "nuryel.ledger/1";
+export const CHANGES_DIR = "changes";
+const IdempotencyEntrySchema = z.object({
+    record_id: z.string().min(1),
+    record_hash: z.string(),
+    facet: z.string(),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+}).strict();
+export const LedgerSchema = z.object({
+    schema: z.literal(LEDGER_SCHEMA_VERSION),
+    scope: ScopeSchema,
+    head_seq: z.number().int().nonnegative(),
+    events: z.array(ChangeEventSchema),
+    idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
+}).strict();
+/** Scope ids may carry `:` `@` `+` (safe in the contract, not in every file system), so
+ *  the file name is the sanitized id plus a short hash of the exact id — readable AND
+ *  collision-free. The scope inside the file is authoritative, the name is a locator. */
+export function ledgerFile(hunchDir, scope) {
+    const safe = scope.id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+    const tag = createHash("sha256").update(scopePath(scope)).digest("hex").slice(0, 8);
+    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: {} };
+}
+/** 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). */
+export function readLedger(hunchDir, scope) {
+    const file = ledgerFile(hunchDir, scope);
+    if (!existsSync(file))
+        return emptyLedger(scope);
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    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;
+    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`);
+    return ledger;
+}
+export function writeLedger(hunchDir, ledger) {
+    const file = ledgerFile(hunchDir, ledger.scope);
+    mkdirSync(join(hunchDir, CHANGES_DIR), { recursive: true });
+    writeFileAtomic(file, JSON.stringify(LedgerSchema.parse(ledger), null, 2) + "\n");
+}
+/** Append events (in order) and remember an idempotency key in ONE atomic write, so a
+ *  crash between "record written" and "event appended" can be detected by the next
+ *  writer (record present, ledger silent) rather than producing a half-applied write. */
+export function appendChanges(hunchDir, scope, changes, idempotency, at = new Date().toISOString()) {
+    const ledger = readLedger(hunchDir, scope);
+    const appended = [];
+    for (const change of changes) {
+        const event = ChangeEventSchema.parse({ schema: "nuryel.state.subscribe/1", seq: ledger.head_seq + 1, at, scope, ...change });
+        ledger.events.push(event);
+        ledger.head_seq = event.seq;
+        appended.push(event);
+    }
+    if (idempotency) {
+        ledger.idempotency[idempotency.key] = { ...idempotency.entry, seq: ledger.head_seq, at };
+    }
+    writeLedger(hunchDir, ledger);
+    return appended;
+}
+/** The latest seq that touched a record in this scope, or 0 when the ledger never saw it. */
+export function latestSeqFor(ledger, recordId) {
+    for (let i = ledger.events.length - 1; i >= 0; i--) {
+        if (ledger.events[i].record_id === recordId)
+            return ledger.events[i].seq;
+    }
+    return 0;
+}
+//# sourceMappingURL=changeLedger.js.map

package/dist/store/jsonStore.js

@@ -19,6 +19,11 @@ const SINGLE_FILE = {
     // so the canonical array avoids lossy filename encoding while keeping Git diffs
     // deterministic through id sorting.
     resources: "index.json",
+    // nuryel.state/1 entities carry the same kind-qualified ids (customer:<name>), and
+    // relationships share edge identity; both are index-file stored for the same reason.
+    // Layout only: migration-before-validation (con_947c578b2c) is untouched.
+    entities: "index.json",
+    relationships: "index.json",
 };
 const encode = (v) => JSON.stringify(v, null, 2) + "\n";
 // Sleep primitive for the single-file RMW lock's bounded spin (issue #35);