@davesheffer/hunch 1.25.0 → 1.26.0

package/README.md

@@ -195,6 +195,14 @@ are homed in an overlay, never in a repository. The MCP server binds it as `nury
 `nuryel_read`, `nuryel_write` and `nuryel_subscribe`; every other transport will call the same
 store binding. Contract and evidence: [docs/nuryel-state-contract.md](docs/nuryel-state-contract.md).
 
+As of 1.26.0 the state layer is also **served**: `hunch serve --config <file>` hosts organization,
+team, user and repository partitions over HTTP on loopback with the same three verbs. A served
+partition is a directory whose `.hunch/partition.json` names the scope it is; the bearer token
+resolves the principal and grants come from the config only. `hunch serve init --partition
+user:david --root <dir> --principal sofia@david` declares a partition and mints a token. The typed
+client is `import { createStateClient } from "@davesheffer/hunch/state"`. This folds the separate
+Hunch Memory service into Hunch.
+
 Read [Deterministic organizational state](docs/deterministic-state.md) and the [roadmap](ROADMAP.md).
 
 ### Naming

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
+import { registerServeCommands } from "./serve.js";
 import { registerUpdateCommand } from "./update.js";
 import { inspectIntegrations, formatIntegrationHealth, integrationHealthFails, integrationSessionWarning } from "../integrations/health.js";
 import { HunchStore } from "../store/hunchStore.js";
@@ -113,6 +114,7 @@ import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext }
 const program = new Command();
 program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
 registerIntegrationCommands(program);
+registerServeCommands(program);
 registerUpdateCommand(program);
 let openStore = null;
 function openTeamStore(root, opts = {}) {

package/dist/cli/serve.js

@@ -0,0 +1,64 @@
+import { resolve } from "node:path";
+import { createServeApp } from "../serve/app.js";
+import { initServeConfig, readServeConfig } from "../serve/config.js";
+import { ScopeSchema, scopePath } from "../core/stateContract.js";
+import { HUNCH_VERSION } from "../core/version.js";
+function parseScopeArg(value) {
+    const m = /^([a-z]+):(.+)$/.exec(value.trim());
+    const parsed = m ? ScopeSchema.safeParse({ kind: m[1], id: m[2] }) : null;
+    if (!parsed?.success)
+        throw new Error(`partition must be kind:id (organization|team|user|repository), got "${value}"`);
+    return parsed.data;
+}
+export function registerServeCommands(program) {
+    const serve = program.command("serve")
+        .description("Serve nuryel.state/1 over HTTP for organization / team / user / repository partitions (binds 127.0.0.1; put it behind SSH or a reverse proxy)")
+        .option("--config <file>", "serve config (nuryel.serve-config/1)", "hunch-serve.json")
+        .option("--port <n>", "override the configured port")
+        .action((opts) => {
+        const config = readServeConfig(resolve(opts.config));
+        const port = opts.port ? Number(opts.port) : config.port;
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            throw new Error(`invalid port ${opts.port}`);
+        const app = createServeApp(config, { version: HUNCH_VERSION });
+        // Bind loopback, never expose a port: the orchestrator reaches it over an SSH hop or a
+        // reverse proxy that terminates TLS and auth of its own. Folded-in decision from Hunch Memory.
+        app.listen(port, "127.0.0.1", () => {
+            console.log(`hunch ${HUNCH_VERSION} serving nuryel.state/1 on http://127.0.0.1:${port} — ${config.partitions.map((p) => scopePath(p.scope)).join(", ")} (${config.principals.length} principal(s))`);
+        });
+        const stop = () => { app.close(() => { app.closeStores(); process.exit(0); }); };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+    });
+    serve.command("init")
+        .description("Declare a partition directory and mint a principal token (printed once; only its hash is stored)")
+        .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:ylm")
+        .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
+        .option("--config <file>", "serve config to create or extend", "hunch-serve.json")
+        .option("--principal <id>", "principal to add or rotate, granted this partition")
+        .option("--kind <kind>", "principal kind: human | agent | service", "agent")
+        .option("--grant <kind:id...>", "additional partitions to grant the principal (must be served by this config)")
+        .option("--port <n>", "port to record in a new config")
+        .option("--json", "machine-readable output")
+        .action((opts) => {
+        if (!["human", "agent", "service"].includes(opts.kind))
+            throw new Error("--kind must be human, agent or service");
+        const scope = parseScopeArg(opts.partition);
+        const grants = [scope, ...(opts.grant ?? []).map(parseScopeArg)];
+        const result = initServeConfig({
+            file: resolve(opts.config), scope, root: resolve(opts.root),
+            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants } } : {}),
+            ...(opts.port ? { port: Number(opts.port) } : {}),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ config: resolve(opts.config), partition: result.partition, token: result.token }));
+            return;
+        }
+        console.log(`partition ${scopePath(scope)} → ${result.partition.root}`);
+        console.log(`config: ${resolve(opts.config)} (${result.config.partitions.length} partition(s), ${result.config.principals.length} principal(s))`);
+        if (result.token)
+            console.log(`token for ${opts.principal} (shown once — only its sha256 is stored): ${result.token}`);
+        console.log(`start: hunch serve --config ${opts.config}`);
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/client/state.js

@@ -0,0 +1,48 @@
+/** A typed refusal from the server: the problem+json body, with `code` = its title. */
+export class StateClientError extends Error {
+    status;
+    code;
+    problem;
+    constructor(status, code, problem) {
+        super(`${code}: ${problem.detail}`);
+        this.status = status;
+        this.code = code;
+        this.problem = problem;
+        this.name = "StateClientError";
+    }
+}
+export function createStateClient(opts) {
+    const base = opts.baseUrl.replace(/\/+$/, "");
+    const doFetch = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    async function call(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await doFetch(`${base}${path}`, {
+                method,
+                headers: { authorization: `Bearer ${opts.token}`, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            const parsed = text ? JSON.parse(text) : {};
+            if (!response.ok) {
+                const p = parsed;
+                throw new StateClientError(response.status, p.title ?? String(response.status), p);
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        capabilities: (scope) => call("GET", `/nuryel/v1/capabilities${scope ? `?scope=${encodeURIComponent(`${scope.kind}:${scope.id}`)}` : ""}`),
+        read: (request) => call("POST", "/nuryel/v1/read", request),
+        write: (request) => call("POST", "/nuryel/v1/write", request),
+        subscribe: (request) => call("POST", "/nuryel/v1/subscribe", request),
+        health: () => call("GET", "/nuryel/v1/health"),
+    };
+}
+//# sourceMappingURL=state.js.map

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

@@ -17,7 +17,8 @@
  * dependencies, external-truth-stays-external (schema refinements), never-in-request-path
  * (there is no proxy verb — this module never fetches anything).
  */
-import { basename } from "node:path";
+import { basename, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { z } from "zod";
 import { appendChanges, latestSeqFor, readLedger } from "./changeLedger.js";
 import { hunchPaths } from "../core/paths.js";
@@ -40,14 +41,24 @@ export class StateRefusal extends Error {
 const LEGACY_FACETS = new Set(["decisions", "constraints", "bugs", "findings"]);
 // Explicit classes, no `i` flag: the pattern must survive zod → JSON schema for MCP output validation.
 const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
-/** The repository partition this store serves. The id is the checkout's directory name,
- *  sanitized to the contract's token grammar — stable per clone, discoverable through
- *  `capabilities`, and the scope every legacy record defaults to. */
-export function repositoryScope(store) {
+/** The partition this store IS. A served partition declares itself in `.hunch/partition.json`
+ *  (`{ kind, id }`, committed with the store); a plain checkout is the repository partition
+ *  named after its directory, sanitized to the contract's token grammar — stable per clone,
+ *  discoverable through `capabilities`, and the scope every legacy record defaults to. */
+export function partitionOf(store) {
+    const declared = join(hunchPaths(store.publicRoot).hunch, "partition.json");
+    if (existsSync(declared)) {
+        const parsed = ScopeSchema.safeParse(JSON.parse(readFileSync(declared, "utf8")));
+        if (!parsed.success)
+            throw new StateRefusal("unsupported", `${declared} does not declare a valid partition scope`);
+        return parsed.data;
+    }
     const raw = basename(store.publicRoot).replace(/[^A-Za-z0-9._:@+-]/g, "-").replace(/^[^A-Za-z0-9]+/, "");
     const id = TOKEN.test(raw) ? raw : "repository";
     return { kind: "repository", id };
 }
+/** @deprecated name kept for callers written before served partitions; same value as partitionOf. */
+export const repositoryScope = partitionOf;
 export const SubscribeResponseSchema = z.object({
     schema: z.literal(STATE_SUBSCRIBE_VERSION),
     scope: ScopeSchema,
@@ -59,19 +70,21 @@ export const SubscribeResponseSchema = z.object({
     filtered: z.boolean(),
 }).strict();
 export function capabilities(store) {
-    const partitions = store.hasPrivate ? ["organization", "team", "user", "repository"] : ["repository"];
-    return { protocol: STATE_CONTRACT_VERSION, capabilities: [...STATE_CAPABILITIES], repository: repositoryScope(store), partitions };
+    const own = partitionOf(store);
+    const partitions = store.hasPrivate ? ["organization", "team", "user", "repository"] : [own.kind];
+    return { protocol: STATE_CONTRACT_VERSION, capabilities: [...STATE_CAPABILITIES], repository: own, partitions };
 }
 // ---- homing --------------------------------------------------------------------------------
 const granted = (principal, scope) => principal.grants.some((g) => scopePath(g) === scopePath(scope));
 function homeFor(store, scope) {
-    const repo = repositoryScope(store);
-    if (scope.kind === "repository") {
-        if (scope.id !== repo.id)
-            throw new StateRefusal("unsupported", `this store serves repository ${repo.id}, not ${scope.id}`);
+    const own = partitionOf(store);
+    if (scopePath(scope) === scopePath(own)) {
+        // The store IS this partition: its capture home (public `.hunch/`, or the overlay in shared mode).
         const home = store.captureHome(false);
         return { home, hunchDir: home === "private" ? store.privateDir : hunchPaths(store.publicRoot).hunch, isPrivate: false };
     }
+    if (scope.kind === "repository")
+        throw new StateRefusal("unsupported", `this store serves ${scopePath(own)}, not ${scopePath(scope)}`);
     if (!store.hasPrivate || !store.privateDir) {
         throw new StateRefusal("no-partition-home", `${scope.kind} partitions never ride a repository; configure an overlay (hunch private / hunch shared) to hold ${scopePath(scope)}`);
     }
@@ -93,7 +106,7 @@ export function readState(store, input) {
     const request = ReadRequestSchema.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 = repositoryScope(store);
+    const repo = partitionOf(store);
     const facets = new Set(request.facets ?? STATE_FACETS);
     const target = request.task ?? request.subject ?? scopePath(request.scope);
     const ctx = store.assembleContext(target, request.budget_tokens ?? 1500);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -26,6 +26,7 @@
       "types": "./dist/projectDna.d.ts",
       "default": "./dist/projectDna.js"
     },
+    "./state": "./dist/client/state.js",
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },

package/server.json

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