@davesheffer/hunch 1.24.0 → 1.26.0

package/dist/store/stateBinding.js

@@ -0,0 +1,398 @@
+/**
+ * nuryel.state/1 bound to the store — the ONE implementation of read / write / subscribe
+ * that every transport (MCP today; HTTP, CLI, typed client next) calls. Transport-free:
+ * takes a HunchStore and a validated request, returns a validated response, throws a
+ * StateRefusal for every typed refusal. No transport may re-implement any rule here.
+ *
+ * Homing follows the store's routing, decided by SCOPE, never by a flag:
+ *   repository scope → the repository's capture home (public `.hunch/`, or the overlay in
+ *                      shared mode) — today's git-native store, unchanged;
+ *   organization / team / user scopes → the overlay ONLY. They never ride a repository
+ *                      (privacy rule of the contract); without an overlay the write is refused.
+ * The change ledger for a scope lives in that same home, so a scope has one sequence.
+ *
+ * Invariants enforced here (exported from stateContract as assertions, not prose):
+ * authorization-before-retrieval (grant check is the FIRST predicate on every path),
+ * provenance-on-every-write, one-live-decision-per-topic, derived-state-carries-
+ * dependencies, external-truth-stays-external (schema refinements), never-in-request-path
+ * (there is no proxy verb — this module never fetches anything).
+ */
+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";
+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";
+/** A typed refusal. `code` is stable for bindings; `conflict` names the incumbent when one exists. */
+export class StateRefusal extends Error {
+    code;
+    conflict;
+    constructor(code, message, conflict = null) {
+        super(message);
+        this.code = code;
+        this.conflict = conflict;
+        this.name = "StateRefusal";
+    }
+}
+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 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,
+    /** The scope's newest seq — the caller's cursor for the next call, whatever filters applied. */
+    head_seq: z.number().int().nonnegative(),
+    events: z.array(ChangeEventSchema),
+    /** 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(),
+}).strict();
+export function capabilities(store) {
+    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 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)}`);
+    }
+    return { home: "private", hunchDir: store.privateDir, isPrivate: true };
+}
+const recordScope = (record, repo) => {
+    const s = record.scope;
+    const parsed = ScopeSchema.safeParse(s);
+    return parsed.success ? parsed.data : repo;
+};
+// ---- read ----------------------------------------------------------------------------------
+function refOf(facet, record, scope) {
+    return { facet, id: record.id, record_hash: stateHash(record), scope };
+}
+/** read — the system-of-record answer for a subject, under the delivery envelope's receipt.
+ *  Grants are the first predicate on every candidate; a matching record in a scope the
+ *  principal lacks is NAMED in denied_scopes and never described. */
+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 = 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);
+    const envelope = buildDeliveryEnvelope(ctx, {
+        root: store.publicRoot,
+        symbols: store.recs("symbols"),
+        components: store.recs("components"),
+        decisionCorpus: store.recs("decisions"),
+        profile: request.profile ?? "builder",
+    });
+    let stateOfRecord = null;
+    const denied = new Map();
+    if (request.subject !== undefined) {
+        const subject = request.subject;
+        const current = [];
+        const inForce = [];
+        const done = [];
+        const dependsOn = [];
+        const invalidatedBy = new Set();
+        /** authorization-before-retrieval: the grant check runs before the record is examined. */
+        const admit = (facet, record) => {
+            const scope = recordScope(record, repo);
+            if (!granted(request.principal, scope)) {
+                denied.set(scopePath(scope), scope);
+                return null;
+            }
+            return scope;
+        };
+        if (facets.has("decisions"))
+            for (const d of store.recs("decisions")) {
+                if (d.topic !== subject && d.id !== subject)
+                    continue;
+                const scope = admit("decisions", d);
+                if (!scope)
+                    continue;
+                if (isLive(d))
+                    current.push(refOf("decisions", d, scope));
+            }
+        if (facets.has("constraints"))
+            for (const c of store.recs("constraints")) {
+                if (c.id !== subject && !c.scope.includes(subject))
+                    continue;
+                const scope = admit("constraints", c);
+                if (!scope)
+                    continue;
+                if (c.status === "active" && c.valid_to == null)
+                    inForce.push(refOf("constraints", c, scope));
+            }
+        if (facets.has("receipts"))
+            for (const r of store.recs("receipts")) {
+                const targets = r.id === subject || r.invalidates.includes(subject) || `${r.target.object_type}:${r.target.object_key}` === subject;
+                if (!targets)
+                    continue;
+                const scope = admit("receipts", r);
+                if (!scope)
+                    continue;
+                if (r.state === "succeeded" || r.state === "verified")
+                    done.push(refOf("receipts", r, scope));
+                if (r.invalidates.includes(subject))
+                    invalidatedBy.add(r.id);
+            }
+        if (facets.has("commitments"))
+            for (const c of store.recs("commitments")) {
+                if (c.subject !== subject && c.id !== subject)
+                    continue;
+                const scope = admit("commitments", c);
+                if (!scope)
+                    continue;
+                if ((c.status === "open" || c.status === "waiting") && c.valid_to == null)
+                    inForce.push(refOf("commitments", c, scope));
+            }
+        if (facets.has("derived"))
+            for (const d of store.recs("derived")) {
+                if (d.subject !== subject && d.id !== subject)
+                    continue;
+                const scope = admit("derived", d);
+                if (!scope)
+                    continue;
+                if (d.state === "current" && d.valid_to == null) {
+                    current.push(refOf("derived", d, scope));
+                    dependsOn.push(...d.dependencies);
+                }
+            }
+        if (facets.has("entities"))
+            for (const e of store.recs("entities")) {
+                if (e.id !== subject)
+                    continue;
+                const scope = admit("entities", e);
+                if (!scope)
+                    continue;
+                if (e.lifecycle === "active")
+                    current.push(refOf("entities", e, scope));
+            }
+        if (facets.has("relationships"))
+            for (const r of store.recs("relationships")) {
+                if (r.from !== subject && r.to !== subject)
+                    continue;
+                const scope = admit("relationships", r);
+                if (!scope)
+                    continue;
+                current.push(refOf("relationships", r, scope));
+            }
+        stateOfRecord = { subject, current, in_force: inForce, done, depends_on: dependsOn, invalidated_by: [...invalidatedBy].sort() };
+    }
+    const response = ReadResponseSchema.parse({
+        schema: STATE_READ_VERSION,
+        receipt_id: envelope.receipt_id,
+        scope: request.scope,
+        state_of_record: stateOfRecord,
+        denied_scopes: [...denied.values()],
+    });
+    assertReadWithinGrants(request.principal, response);
+    return { response, envelope };
+}
+/** What a record is ABOUT, for subscribers filtering by subject. Mirrors the read verb's matching. */
+function subjectOf(facet, record) {
+    const r = record;
+    switch (facet) {
+        case "commitments":
+        case "derived": return typeof r.subject === "string" ? r.subject : undefined;
+        case "entities": return typeof r.id === "string" ? r.id : undefined;
+        case "relationships": return typeof r.from === "string" ? r.from : undefined;
+        case "receipts": {
+            const t = r.target;
+            return t?.object_type && t.object_key ? `${t.object_type}:${t.object_key}` : undefined;
+        }
+        case "decisions": return typeof r.topic === "string" ? r.topic : undefined;
+        default: return undefined;
+    }
+}
+/** Records the store can close a valid-time window on when superseded. */
+function closeWindow(store, facet, incumbentId, byId, at, isPrivate) {
+    if (facet === "decisions") {
+        const by = store.getRec("decisions", byId);
+        if (!by)
+            return false;
+        return (isPrivate ? store.supersedePrivate(incumbentId, by) : store.supersede(incumbentId, by)) !== null;
+    }
+    const old = store.getRec(facet, incumbentId);
+    if (!old || !("valid_to" in old))
+        return false;
+    const closed = { ...old, valid_to: old.valid_to ?? at, ...(facet === "derived" ? { state: "stale" } : {}) };
+    store.putCapture(facet, closed, isPrivate);
+    return true;
+}
+/** Normalize + validate the record for its facet; enforce the identity rule (an id, when
+ *  given, must be the one the record's facts derive). Returns the canonical record. */
+function normalizeRecord(facet, scope, raw, principal) {
+    const record = { ...raw };
+    if (LEGACY_FACETS.has(facet)) {
+        // Legacy records carry no partition scope (a constraint's `scope` is its path globs);
+        // the repository scope is implied, so an echoed partition is dropped, not stored.
+        if (ScopeSchema.safeParse(record.scope).success)
+            delete record.scope;
+    }
+    else {
+        record.scope = scope;
+    }
+    // Authorship tier (memory supply chain): only a human principal may sign as
+    // human_confirmed through this path; an agent's write is agent testimony.
+    const prov = record.provenance;
+    if (prov && typeof prov.source === "string" && principal.kind !== "human" && prov.source.split("+").includes("human_confirmed")) {
+        record.provenance = { ...prov, source: prov.source.split("+").map((t) => (t === "human_confirmed" ? "agent_recorded" : t)).join("+") };
+    }
+    let expectedId = null;
+    try {
+        if (facet === "receipts")
+            expectedId = actionReceiptId(record);
+        else if (facet === "commitments")
+            expectedId = commitmentId(record);
+        else if (facet === "derived")
+            expectedId = derivedId(record);
+        else if (facet === "decisions" && typeof record.id !== "string")
+            expectedId = decisionId(String(record.topic ?? record.title ?? ""));
+    }
+    catch (e) {
+        throw new StateRefusal("malformed", `cannot derive ${facet} identity: ${e.message}`);
+    }
+    if (expectedId) {
+        if (typeof record.id === "string" && record.id !== expectedId)
+            throw new StateRefusal("identity", `${facet} id ${record.id} is not the identity its facts derive (${expectedId}); ids are derived, never chosen`);
+        record.id = expectedId;
+    }
+    const parsed = SCHEMAS[facet].safeParse(record);
+    if (!parsed.success)
+        throw new StateRefusal("malformed", `${facet} record is malformed: ${parsed.error.issues.map((i) => `${i.path.join(".") || "record"}: ${i.message}`).join("; ")}`);
+    if (facet === "derived") {
+        try {
+            assertDerivedState(parsed.data);
+        }
+        catch (e) {
+            throw new StateRefusal("malformed", e.message);
+        }
+    }
+    return parsed.data;
+}
+/** write — provenance + idempotency in, durability out. A replay returns the original;
+ *  a conflict names the incumbent; nothing is ever silently overwritten or duplicated. */
+export function writeState(store, input, opts = {}) {
+    const request = WriteRequestSchema.parse(input);
+    try {
+        assertWriteWellFormed(request);
+    }
+    catch (e) {
+        throw new StateRefusal(/grants/.test(e.message) ? "outside-grants" : "malformed", e.message);
+    }
+    const { home, hunchDir, isPrivate } = homeFor(store, request.scope);
+    const now = (opts.now ?? (() => new Date()))().toISOString();
+    const facet = request.facet;
+    if (!ENTITY_KINDS.includes(facet))
+        throw new StateRefusal("unsupported", `facet ${facet} is not a store kind`);
+    const record = normalizeRecord(facet, request.scope, request.record, request.principal);
+    const id = record.id;
+    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 });
+    // 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" });
+    }
+    const existing = store.recsInHome(facet, home).find((r) => r.id === id);
+    if (existing && stateHash(existing) === hash) {
+        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, facet } }, now);
+        return result("replayed");
+    }
+    if (existing && request.expected_version !== null) {
+        const ok = typeof request.expected_version === "number"
+            ? latestSeqFor(ledger, id) === request.expected_version
+            : stateHash(existing) === request.expected_version;
+        if (!ok)
+            throw new StateRefusal("conflict", `expected_version does not match the incumbent ${id}`, { incumbent_id: id, reason: "expected_version mismatch" });
+    }
+    // one-live-decision-per-topic — refuse with the incumbent named; supersession is explicit.
+    let supersedes = request.supersedes ?? null;
+    if (facet === "decisions") {
+        const d = record;
+        if (d.topic && d.status === "accepted") {
+            const willClose = supersedes && store.recsInHome("decisions", home).some((x) => x.id === supersedes) ? supersedes : null;
+            const conflicts = captureConflicts(store.recsInHome("decisions", home), d.topic, d.id, willClose);
+            if (conflicts.length) {
+                throw new StateRefusal("conflict", `topic ${d.topic} already has a live decision ${conflicts[0].id}; pass supersedes to replace it`, { incumbent_id: conflicts[0].id, reason: "one-live-decision-per-topic" });
+            }
+        }
+    }
+    if (supersedes && !store.recsInHome(facet, home).some((r) => r.id === supersedes)) {
+        throw new StateRefusal("conflict", `supersedes ${supersedes} is not a ${facet} record in this partition`, { incumbent_id: supersedes, reason: "supersede target absent" });
+    }
+    if (supersedes === id)
+        supersedes = null;
+    store.putCapture(facet, record, isPrivate);
+    const changes = [];
+    const cause = { kind: "write", principal: request.principal.id };
+    const invalidates = facet === "receipts" ? record.invalidates : [];
+    const subject = subjectOf(facet, record);
+    if (supersedes) {
+        const closed = closeWindow(store, facet, supersedes, id, now, isPrivate);
+        if (closed) {
+            const old = store.getRec(facet, supersedes);
+            changes.push({ facet, record_id: supersedes, record_hash: stateHash(old), change: "superseded", subject: subjectOf(facet, old), invalidates: [], cause });
+        }
+    }
+    changes.push({ facet, record_id: id, record_hash: hash, change: existing ? "updated" : "created", subject, invalidates, cause });
+    appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, facet } }, now);
+    store.reindex();
+    return result(supersedes ? "superseded" : existing ? "updated" : "created");
+}
+// ---- subscribe -----------------------------------------------------------------------------
+/** subscribe — the scope's ordered change stream after a cursor. Unfiltered, the events are
+ *  contiguous and assertChangeSequence holds; filtered, `head_seq` is still the cursor. */
+export function subscribeState(store, input) {
+    const request = SubscribeRequestSchema.parse(input);
+    if (!granted(request.principal, request.scope))
+        throw new StateRefusal("outside-grants", `scope ${scopePath(request.scope)} is outside the principal's grants`);
+    const { hunchDir } = homeFor(store, request.scope);
+    const ledger = readLedger(hunchDir, request.scope);
+    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
+        && (!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 });
+}
+//# sourceMappingURL=stateBinding.js.map

package/package.json

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