@davesheffer/hunch 1.27.0 → 1.29.0

package/dist/store/stateBinding.js

@@ -125,6 +125,12 @@ export function readState(store, input) {
     let stateOfRecord = null;
     const records = {};
     const denied = new Map();
+    // Union read against ONE store: every requested scope the principal lacks is named up front;
+    // the partitions actually read are declared so a caller never mistakes this for the union
+    // (a multi-partition host merges per-store answers with mergeReadResponses).
+    for (const s of request.scopes ?? [])
+        if (!granted(request.principal, s))
+            denied.set(scopePath(s), s);
     if (request.subject !== undefined) {
         const subject = request.subject;
         const current = [];
@@ -173,8 +179,10 @@ export function readState(store, input) {
                 const scope = admit("receipts", r);
                 if (!scope)
                     continue;
-                if (r.state === "succeeded" || r.state === "verified")
+                if (r.state === "succeeded" || r.state === "verified") {
                     done.push(keep("receipts", r, scope));
+                    dependsOn.push(...(r.rests_on ?? []));
+                }
                 if (r.invalidates.includes(subject))
                     invalidatedBy.add(r.id);
             }
@@ -187,6 +195,10 @@ export function readState(store, input) {
                     continue;
                 if ((c.status === "open" || c.status === "waiting") && c.valid_to == null)
                     inForce.push(keep("commitments", c, scope));
+                // A commitment fulfilled by a receipt is part of what HAPPENED for the subject: it
+                // leaves in_force and joins done beside the receipt that closed it (the chain's last link).
+                else if (c.status === "done" && c.closed_by)
+                    done.push(keep("commitments", c, scope));
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
@@ -228,10 +240,86 @@ export function readState(store, input) {
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
         ...(stateOfRecord ? { records } : {}),
+        ...(request.scopes ? { scopes: [request.scope], receipts: [{ scope: request.scope, receipt_id: envelope.receipt_id }] } : {}),
     });
     assertReadWithinGrants(request.principal, response);
     return { response, envelope };
 }
+/** Union read — one state_of_record across several partitions, each read by `readState` against
+ *  its own store. Pure: no store, no grants decided here (every input already passed its own
+ *  grant check). The primary's receipt, scope and envelope lead; refs concatenate (each already
+ *  carries its partition), `depends_on` concatenates, `invalidated_by` is a sorted union, `records`
+ *  merge by id (first writer wins — ids are identity, two copies are the same record),
+ *  `denied_scopes` is the union of every partition's denied plus `extraDenied` (requested-but-
+ *  ungranted scopes the host refused to open), `scopes` names the partitions read and `receipts`
+ *  carries one delivery receipt per partition. Reusable by any host (HTTP today; MCP or CLI
+ *  fronting several roots later). */
+export function mergeReadResponses(primary, others, extraDenied = []) {
+    const all = [primary, ...others];
+    const scopes = new Map();
+    const receipts = new Map();
+    for (const r of all) {
+        for (const s of r.scopes ?? [r.scope])
+            if (!scopes.has(scopePath(s)))
+                scopes.set(scopePath(s), s);
+        for (const x of r.receipts ?? [{ scope: r.scope, receipt_id: r.receipt_id }])
+            if (!receipts.has(scopePath(x.scope)))
+                receipts.set(scopePath(x.scope), x);
+    }
+    const denied = new Map();
+    for (const s of [...all.flatMap((r) => r.denied_scopes), ...extraDenied])
+        if (!scopes.has(scopePath(s)) && !denied.has(scopePath(s)))
+            denied.set(scopePath(s), s);
+    const sors = all.map((r) => r.state_of_record).filter((s) => s !== null);
+    let stateOfRecord = null;
+    const records = {};
+    if (sors.length) {
+        const refKey = (ref) => `${ref.facet}|${scopePath(ref.scope)}|${ref.id}`;
+        const dedupeRefs = (pick) => {
+            const seen = new Set();
+            const out = [];
+            for (const ref of sors.flatMap(pick)) {
+                const k = refKey(ref);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    out.push(ref);
+                }
+            }
+            return out;
+        };
+        const seenDeps = new Set();
+        const dependsOn = [];
+        for (const dep of sors.flatMap((s) => s.depends_on)) {
+            const k = stateHash(dep);
+            if (!seenDeps.has(k)) {
+                seenDeps.add(k);
+                dependsOn.push(dep);
+            }
+        }
+        stateOfRecord = {
+            subject: sors[0].subject,
+            current: dedupeRefs((s) => s.current),
+            in_force: dedupeRefs((s) => s.in_force),
+            done: dedupeRefs((s) => s.done),
+            depends_on: dependsOn,
+            invalidated_by: [...new Set(sors.flatMap((s) => s.invalidated_by))].sort(),
+        };
+        for (const r of all)
+            for (const [id, record] of Object.entries(r.records ?? {}))
+                if (!(id in records))
+                    records[id] = record;
+    }
+    return ReadResponseSchema.parse({
+        schema: STATE_READ_VERSION,
+        receipt_id: primary.receipt_id,
+        scope: primary.scope,
+        state_of_record: stateOfRecord,
+        denied_scopes: [...denied.values()],
+        ...(stateOfRecord ? { records } : {}),
+        scopes: [...scopes.values()],
+        receipts: [...receipts.values()],
+    });
+}
 /** What a record is ABOUT, for subscribers filtering by subject. Mirrors the read verb's matching. */
 function subjectOf(facet, record) {
     const r = record;
@@ -248,6 +336,77 @@ function subjectOf(facet, record) {
         default: return undefined;
     }
 }
+/** Which facet a record id belongs to, from its prefix; `null` for a kind-qualified entity id
+ *  or an unknown shape (those are looked up across every facet). */
+function facetOfId(id) {
+    const prefix = /^([a-z]+)_/.exec(id)?.[1];
+    switch (prefix) {
+        case "dec": return "decisions";
+        case "con": return "constraints";
+        case "bug": return "bugs";
+        case "fnd": return "findings";
+        case "nrc": return "receipts";
+        case "ncm": return "commitments";
+        case "nds": return "derived";
+        case "edge": return "relationships";
+        default: return null;
+    }
+}
+/** Find a record by id in this store, with the facet it lives in. */
+function findRecord(store, id) {
+    const facets = facetOfId(id) ? [facetOfId(id)] : [...STATE_FACETS];
+    for (const facet of facets) {
+        const record = store.getRec(facet, id);
+        if (record)
+            return { facet, record };
+    }
+    return null;
+}
+/** A receipt's `rests_on` record refs: one in a partition this store holds must exist there
+ *  with the hash the writer saw (a stale hash means the decision moved — re-read); one in a
+ *  partition the store does not hold is a pointer for the reader to resolve. Grants first: a
+ *  ref into a partition the principal is not granted is refused by scope, never by content. */
+function assertRestsOn(store, principal, scope, restsOn) {
+    const repo = partitionOf(store);
+    for (const dep of restsOn) {
+        if (dep.kind !== "record")
+            continue;
+        const refScope = dep.scope ?? scope;
+        if (!granted(principal, refScope))
+            throw new StateRefusal("outside-grants", `rests_on ${dep.id} points into ${scopePath(refScope)}, which is outside the principal's grants`);
+        const found = findRecord(store, dep.id);
+        if (!found) {
+            const held = scopePath(refScope) === scopePath(scope) || scopePath(refScope) === scopePath(repo) || (store.hasPrivate && refScope.kind !== "repository");
+            if (held)
+                throw new StateRefusal("conflict", `rests_on ${dep.id} is not on record in ${scopePath(refScope)}: a receipt rests on state that exists; write or re-read it first`, { incumbent_id: dep.id, reason: "rests_on target absent" });
+            continue; // a partition this store does not hold: a pointer, resolved by the reader
+        }
+        const actualScope = recordScope(found.record, repo);
+        if (scopePath(actualScope) !== scopePath(refScope))
+            throw new StateRefusal("conflict", `rests_on ${dep.id} lives in ${scopePath(actualScope)}, not ${scopePath(refScope)}`, { incumbent_id: dep.id, reason: "rests_on scope mismatch" });
+        const actualHash = stateHash(found.record);
+        if (actualHash !== dep.record_hash)
+            throw new StateRefusal("conflict", `rests_on ${dep.id} has moved: the record on file hashes ${actualHash}, not ${dep.record_hash} — re-read it and rest on what is current`, { incumbent_id: dep.id, reason: "rests_on hash mismatch" });
+    }
+}
+/** A commitment closed by a receipt: `closed_by` must name a succeeded/verified receipt the
+ *  principal can see, and the status must be done — a closure is a fact that happened, never
+ *  an opinion. Returns the receipt id when the closure is well-formed. */
+function assertClosedBy(store, principal, commitment) {
+    if (!commitment.closed_by)
+        return null;
+    if (commitment.status !== "done")
+        throw new StateRefusal("malformed", `closed_by names a receipt but status is ${commitment.status}: a commitment closed by a receipt is done`);
+    const receipt = store.getRec("receipts", commitment.closed_by);
+    const scope = receipt ? recordScope(receipt, partitionOf(store)) : null;
+    if (!receipt || !scope || !granted(principal, scope)) {
+        throw new StateRefusal("conflict", `closed_by ${commitment.closed_by} is not a receipt on record within the principal's grants: a commitment is closed by an action that happened — write the receipt first, then close with its id`, { incumbent_id: commitment.closed_by, reason: "closed_by receipt absent" });
+    }
+    if (receipt.state !== "succeeded" && receipt.state !== "verified") {
+        throw new StateRefusal("conflict", `closed_by ${commitment.closed_by} is ${receipt.state}, not succeeded or verified: only an action that happened closes a commitment`, { incumbent_id: commitment.closed_by, reason: `closed_by receipt ${receipt.state}` });
+    }
+    return commitment.closed_by;
+}
 /** 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)]);
@@ -336,15 +495,22 @@ export function writeState(store, input, opts = {}) {
         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;
+    /** The normalized PAYLOAD hash: what idempotency recognizes on a re-send. */
     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, record: store.getRec(facet, rid) ?? record });
+    /** The result reports the record ON FILE and its hash — the store may enrich a record on put
+     *  (a private-mode decision gains `valid_from`), and a writer that goes on to rest a receipt
+     *  on this record must hold the hash a reader will verify, never a pre-store one. */
+    const result = (outcome, conflict = null, rid = id) => {
+        const onFile = store.getRec(facet, rid) ?? record;
+        return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: stateHash(onFile), durability: durability(), outcome, conflict, record: onFile });
+    };
     // 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)
+        if (seen.record_id === id && (seen.record_hash === hash || seen.payload_hash === hash))
             return result("replayed");
         // 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.
@@ -355,7 +521,7 @@ export function writeState(store, input, opts = {}) {
     }
     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);
+        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now);
         return result("replayed");
     }
     if (existing && request.expected_version !== null) {
@@ -382,9 +548,37 @@ export function writeState(store, input, opts = {}) {
     }
     if (supersedes === id)
         supersedes = null;
+    // A supersede target must still be open. Two writers racing to replace the same incumbent
+    // would otherwise both succeed and leave two current records for one subject (fnd_eeb8bf3cb8);
+    // the loser is told which record is current now, so it can re-read and supersede that one.
+    // The writer that closed the incumbent itself (same id, new key) is not a loser.
+    if (supersedes && facet !== "decisions") {
+        const incumbent = store.getRec(facet, supersedes);
+        if (incumbent && "valid_to" in incumbent && incumbent.valid_to !== null) {
+            const subject = subjectOf(facet, incumbent);
+            const open = store.recsInHome(facet, home)
+                .filter((r) => subjectOf(facet, r) === subject && r.valid_to === null)
+                .map((r) => r.id).sort();
+            if (!open.includes(id)) {
+                const current = open.length ? `the current ${facet} record for ${subject ?? "that subject"} is ${open.join(", ")}` : `no ${facet} record for ${subject ?? "that subject"} is open now`;
+                throw new StateRefusal("conflict", `supersedes ${supersedes} was already superseded (window closed ${String(incumbent.valid_to)}); ${current}: re-read and supersede that one`, { incumbent_id: open[0] ?? supersedes, reason: "supersede target already closed" });
+            }
+            supersedes = null; // already closed by this record: nothing to close again, no second "superseded" event
+        }
+    }
+    // The chain (Gate 4): a receipt names what it rested on, a closure names the receipt.
+    // Both are checked against the drawer, grants first, before anything lands.
+    if (facet === "receipts")
+        assertRestsOn(store, request.principal, request.scope, record.rests_on ?? []);
+    const closedBy = facet === "commitments" ? assertClosedBy(store, request.principal, record) : null;
     store.putCapture(facet, record, isPrivate);
+    /** What is on file now — the hash every event, ref and result carries. */
+    const onFileHash = stateHash(store.getRec(facet, id) ?? record);
     const changes = [];
-    const cause = { kind: "write", principal: request.principal.id };
+    const cause = closedBy ? { kind: "receipt", receipt_id: closedBy } : request.cause ?? { kind: "write", principal: request.principal.id };
+    // A current derived statement written back as stale is an INVALIDATION, not an update: the
+    // ledger says so, and names the external pointer that moved when the writer gives one.
+    const invalidated = facet === "derived" && !!existing && existing.state === "current" && record.state === "stale";
     const invalidates = facet === "receipts" ? record.invalidates : [];
     const subject = subjectOf(facet, record);
     if (supersedes) {
@@ -394,8 +588,8 @@ export function writeState(store, input, opts = {}) {
             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);
+    changes.push({ facet, record_id: id, record_hash: onFileHash, change: invalidated ? "invalidated" : existing ? "updated" : "created", subject, invalidates: invalidated && subject ? [subject] : invalidates, cause });
+    appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: onFileHash, payload_hash: hash, facet } }, now);
     store.reindex();
     return result(supersedes ? "superseded" : existing ? "updated" : "created");
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
-  "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",
+  "description": "Deterministic state for organizations that run many probabilistic agents: decisions, receipts, commitments, constraints and bug lineage held in git, refused when they contradict, and delivered to every MCP assistant before it answers or edits code.",
   "homepage": "https://www.hunchmemory.com",
   "repository": {
     "type": "git",

package/server.json

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

package/tooling/competitive-watch.mjs

@@ -9,6 +9,7 @@ const repos = [
   "riponcm/projectmem",
   "Cranot/roam-code",
   "blackwell-systems/knowing",
+  "markmhendrickson/neotoma",
 ];
 
 const distinctivePhrases = [