@davesheffer/hunch 1.28.0 → 1.30.0

package/dist/store/stateBinding.js

@@ -26,7 +26,7 @@ import { decisionId } from "../core/ids.js";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { captureConflicts, isLive } from "../core/topics.js";
 import { buildDeliveryEnvelope } from "../core/delivery.js";
-import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_RECORDS_VERSION, ScopeSchema, scopePath, stateHash, actionReceiptId, commitmentId, derivedId, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, } from "../core/stateContract.js";
+import { STATE_CAPABILITIES, STATE_CONTRACT_VERSION, STATE_FACETS, STATE_READ_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, ChangeEventSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_RECORDS_VERSION, ScopeSchema, scopePath, stateHash, actionReceiptId, commitmentId, derivedId, externalKey, subjectOfRef, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, isHumanConfirmed, } 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;
@@ -81,7 +81,9 @@ export function capabilities(store) {
 }
 // ---- homing --------------------------------------------------------------------------------
 const granted = (principal, scope) => principal.grants.some((g) => scopePath(g) === scopePath(scope));
-function homeFor(store, scope) {
+/** Where a scope's records and ledger live in this store (exported for the replay check, which
+ *  must read the SAME home the write verb wrote — never a second routing rule). */
+export function stateHomeFor(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).
@@ -104,6 +106,62 @@ const recordScope = (record, repo) => {
 function refOf(facet, record, scope) {
     return { facet, id: record.id, record_hash: stateHash(record), scope };
 }
+/** Follow `merged_into` to the entity that stands for this one now (cycle-safe, bounded). */
+function survivorOf(byId, entity) {
+    let current = entity;
+    const seen = new Set([current.id]);
+    while (current.lifecycle === "retired" && current.merged_into) {
+        const next = byId.get(current.merged_into);
+        if (!next || seen.has(next.id))
+            break;
+        seen.add(next.id);
+        current = next;
+    }
+    return current;
+}
+/** The entities in the principal's grants that stand for an external key or an entity id — active
+ *  ones directly, retired-and-merged ones through the survivor they name. */
+function entityIndex(store, principal, repo) {
+    const byId = new Map();
+    for (const e of store.recs("entities"))
+        if (granted(principal, recordScope(e, repo)))
+            byId.set(e.id, e);
+    const survivor = (e) => survivorOf(byId, e);
+    const byKey = new Map();
+    const bySubject = new Map();
+    for (const e of byId.values()) {
+        const stands = e.lifecycle === "active" ? e : (e.lifecycle === "retired" && e.merged_into ? survivor(e) : null);
+        if (!stands || stands.lifecycle !== "active")
+            continue;
+        for (const ref of e.refs) {
+            if (!byKey.has(externalKey(ref)) || e.lifecycle === "active")
+                byKey.set(externalKey(ref), stands);
+            if (!bySubject.has(subjectOfRef(ref)) || e.lifecycle === "active")
+                bySubject.set(subjectOfRef(ref), stands);
+        }
+    }
+    return { byKey, bySubject, byId, survivor };
+}
+/** The names one subject is filed under: itself, the entity that stands for it (through merges),
+ *  every entity merged into that one, and every key any of them carries. Explicit refs only. */
+function subjectAliases(store, principal, repo, subject) {
+    const aliases = new Set([subject]);
+    const { bySubject, byId, survivor } = entityIndex(store, principal, repo);
+    const named = bySubject.get(subject) ?? byId.get(subject);
+    if (!named)
+        return aliases;
+    const stands = survivor(named);
+    if (stands.lifecycle !== "active")
+        return aliases;
+    for (const e of byId.values()) {
+        if (e.id !== stands.id && survivor(e).id !== stands.id)
+            continue;
+        aliases.add(e.id);
+        for (const ref of e.refs)
+            aliases.add(subjectOfRef(ref));
+    }
+    return aliases;
+}
 /** 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. */
@@ -133,6 +191,11 @@ export function readState(store, input) {
             denied.set(scopePath(s), s);
     if (request.subject !== undefined) {
         const subject = request.subject;
+        // Subject identity by external reference: a read for an external record's key (`event:26904`,
+        // `customer:Site:7`) also finds what is filed under the entity that carries that ref, and a
+        // read for the entity id finds what was filed under its keys — one explicit hop, grants first.
+        const aliases = subjectAliases(store, request.principal, repo, subject);
+        const isSubject = (s) => s !== undefined && aliases.has(s);
         const current = [];
         const inForce = [];
         const done = [];
@@ -173,30 +236,36 @@ export function readState(store, input) {
             }
         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;
+                const targets = r.id === subject || r.invalidates.some(isSubject) || isSubject(subjectOfRef(r.target));
                 if (!targets)
                     continue;
                 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));
-                if (r.invalidates.includes(subject))
+                    dependsOn.push(...(r.rests_on ?? []));
+                }
+                if (r.invalidates.some(isSubject))
                     invalidatedBy.add(r.id);
             }
         if (facets.has("commitments"))
             for (const c of store.recs("commitments")) {
-                if (c.subject !== subject && c.id !== subject)
+                if (!isSubject(c.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(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")) {
-                if (d.subject !== subject && d.id !== subject)
+                if (!isSubject(d.subject) && d.id !== subject)
                     continue;
                 const scope = admit("derived", d);
                 if (!scope)
@@ -208,7 +277,7 @@ export function readState(store, input) {
             }
         if (facets.has("entities"))
             for (const e of store.recs("entities")) {
-                if (e.id !== subject)
+                if (!isSubject(e.id))
                     continue;
                 const scope = admit("entities", e);
                 if (!scope)
@@ -218,7 +287,7 @@ export function readState(store, input) {
             }
         if (facets.has("relationships"))
             for (const r of store.recs("relationships")) {
-                if (r.from !== subject && r.to !== subject)
+                if (!isSubject(r.from) && !isSubject(r.to))
                     continue;
                 const scope = admit("relationships", r);
                 if (!scope)
@@ -330,6 +399,125 @@ 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;
+}
+/** one-entity-per-external-ref. An entity: no other active entity in the partition may carry one
+ *  of its external keys (the incumbent is named; merge/split are explicit, later). A commitment or
+ *  derived statement: its subject may not be the external key of a record an entity already
+ *  carries — the entity's id is the subject, and the refusal names it (the writer re-derives;
+ *  ids derive from the subject, so nothing is rewritten under it). A subject no entity claims
+ *  stays a free-form key: explicit refs only, no guessing. */
+function assertExternalIdentity(store, principal, scope, facet, record) {
+    const repo = partitionOf(store);
+    const inPartition = (e) => scopePath(recordScope(e, repo)) === scopePath(scope);
+    if (facet === "entities") {
+        const entity = record;
+        if (entity.merged_into !== undefined) {
+            const target = store.recs("entities").find((e) => e.id === entity.merged_into);
+            if (!target || !inPartition(target))
+                throw new StateRefusal("conflict", `merged_into ${entity.merged_into} is not an entity on record in ${scopePath(scope)}: a merge names a survivor that exists — write it first`, { incumbent_id: entity.merged_into, reason: "merge survivor absent" });
+            if (!granted(principal, recordScope(target, repo)))
+                throw new StateRefusal("outside-grants", `merged_into ${entity.merged_into} is outside the principal's grants`);
+            if (target.lifecycle !== "active")
+                throw new StateRefusal("conflict", `merged_into ${entity.merged_into} is ${target.lifecycle}${target.merged_into ? ` (merged into ${target.merged_into})` : ""}: the survivor of a merge is an active entity — merge into the one that stands now`, { incumbent_id: target.merged_into ?? target.id, reason: "merge survivor not active" });
+        }
+        if (entity.lifecycle !== "active")
+            return;
+        const keys = new Set(entity.refs.map(externalKey));
+        for (const other of store.recs("entities")) {
+            if (other.id === entity.id || other.lifecycle !== "active" || !inPartition(other))
+                continue;
+            const shared = other.refs.map(externalKey).find((k) => keys.has(k));
+            if (shared)
+                throw new StateRefusal("conflict", `${shared} is already carried by entity ${other.id} in ${scopePath(scope)}: one external record is one entity — write under ${other.id}, or retire it first (merge and split are explicit)`, { incumbent_id: other.id, reason: "one-entity-per-external-ref" });
+        }
+        return;
+    }
+    if (facet !== "commitments" && facet !== "derived")
+        return;
+    const subject = record.subject;
+    const { bySubject, byId, survivor } = entityIndex(store, principal, repo);
+    const byKey = bySubject.get(subject);
+    if (byKey && byKey.id !== subject && inPartition(byKey)) {
+        throw new StateRefusal("identity", `subject ${subject} is the external key of entity ${byKey.id} in ${scopePath(scope)}: the entity's id is the subject — re-derive with subject ${byKey.id}`, { incumbent_id: byKey.id, reason: "subject is an entity's external key" });
+    }
+    const named = byId.get(subject);
+    if (named && named.lifecycle === "retired" && named.merged_into && inPartition(named)) {
+        const stands = survivor(named);
+        if (stands.id !== named.id && stands.lifecycle === "active") {
+            throw new StateRefusal("identity", `subject ${subject} was merged into ${stands.id}: new state goes under the survivor — re-derive with subject ${stands.id}`, { incumbent_id: stands.id, reason: "subject was merged" });
+        }
+    }
+}
 /** 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)]);
@@ -411,22 +599,30 @@ export function writeState(store, input, opts = {}) {
     catch (e) {
         throw new StateRefusal(/grants/.test(e.message) ? "outside-grants" : "malformed", e.message);
     }
-    const { home, hunchDir, isPrivate } = homeFor(store, request.scope);
+    const { home, hunchDir, isPrivate } = stateHomeFor(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;
+    assertExternalIdentity(store, request.principal, request.scope, facet, record);
+    /** 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.
@@ -437,7 +633,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) {
@@ -447,8 +643,42 @@ export function writeState(store, input, opts = {}) {
         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.
+    // human-correction-outranks-agent-writes: what a human confirmed, an agent does not rewrite.
+    // Allowed for an agent: a replay (the same facts, the tier downgrade aside), a derived statement
+    // written back stale with the external cause that moved (the writer's currentness duty), a
+    // commitment closed by a receipt on record (a fact that happened) — both keep the human's
+    // provenance on the record. Everything else on a human-confirmed incumbent — in place or by
+    // supersession — is refused with the incumbent named.
     let supersedes = request.supersedes ?? null;
+    if (request.principal.kind !== "human") {
+        const guard = (incumbent, how) => {
+            if (!incumbent || !isHumanConfirmed(incumbent))
+                return null;
+            const incumbentId = String(incumbent.id);
+            const changed = how === "overwrite" ? differingFields(incumbent, record).filter((f) => f !== "provenance") : ["a new record"];
+            if (how === "overwrite") {
+                if (changed.length === 0)
+                    return "replay";
+                const staleWithCause = facet === "derived" && incumbent.state === "current" && record.state === "stale" && request.cause?.kind === "external"
+                    && changed.every((f) => f === "state" || f === "valid_to");
+                const closedByReceipt = facet === "commitments" && !!record.closed_by && record.status === "done"
+                    && changed.every((f) => f === "status" || f === "closed_by" || f === "valid_to");
+                if (staleWithCause || closedByReceipt)
+                    return "keep-provenance";
+            }
+            throw new StateRefusal("conflict", `${incumbentId} was confirmed by a human; ${request.principal.kind === "agent" ? "an agent" : "a service"} principal may not ${how} it (differs in: ${changed.join(", ")}). A human writes the change, or the agent leaves the record as the human left it.`, { incumbent_id: incumbentId, reason: "human-confirmed incumbent" });
+        };
+        const verdict = guard(existing, "overwrite");
+        if (verdict === "replay") {
+            appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: stateHash(existing), payload_hash: hash, facet } }, now);
+            return result("replayed");
+        }
+        if (verdict === "keep-provenance")
+            record.provenance = existing.provenance;
+        if (supersedes && supersedes !== id)
+            guard(store.getRec(facet, supersedes), "supersede");
+    }
+    // one-live-decision-per-topic — refuse with the incumbent named; supersession is explicit.
     if (facet === "decisions") {
         const d = record;
         if (d.topic && d.status === "accepted") {
@@ -482,10 +712,22 @@ export function writeState(store, input, opts = {}) {
             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 : [];
+    // An entity leaving service is a `retired` change (a merge names the survivor in the record).
+    const retired = facet === "entities" && record.lifecycle === "retired" && (!existing || existing.lifecycle !== "retired");
     const subject = subjectOf(facet, record);
     if (supersedes) {
         const closed = closeWindow(store, facet, supersedes, id, now, isPrivate);
@@ -494,8 +736,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" : retired ? "retired" : 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");
 }
@@ -506,7 +748,7 @@ 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 { hunchDir } = stateHomeFor(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;

package/dist/synthesis/provider.js

@@ -31,6 +31,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
 import { summarizeDiff } from "../extractors/diff.js";
+import { languageFor } from "../extractors/languages.js";
 const IS_WIN = process.platform === "win32";
 /**
  * Run a command, optionally feeding `input` to its stdin, and resolve its
@@ -614,6 +615,9 @@ export class DeterministicProvider {
         const dirs = topDirs(input.files);
         const a = input.analysis;
         const summary = a ? summarizeDiff(a) : "";
+        // input.files can be markdown-only (issue #12) — don't claim "code" for a
+        // commit that touched none.
+        const noun = input.files.some((f) => languageFor(f) !== null) ? "code" : "content";
         const verb = /^(add|introduce|create|feat)/i.test(input.subject) ? "introduced"
             : /^(remove|delete|drop)/i.test(input.subject) ? "removed"
                 : /^(refactor|rework|restructure)/i.test(input.subject) ? "refactored"
@@ -630,12 +634,12 @@ export class DeterministicProvider {
         // We extracted real structure → a bit more trustworthy than a blind heuristic.
         const informative = !!(a && (a.addedSymbols.length || a.removedSymbols.length || a.changedSymbols.length || a.addedDeps.length || a.removedDeps.length));
         return {
-            title: input.subject || "Code change",
+            title: input.subject || `${cap(noun)} change`,
             context: [input.body, summary && `What changed: ${summary}.`].filter(Boolean).join(" ").slice(0, 500)
                 || `Touched ${input.files.length} file(s) across ${dirs.join(", ") || "the repo"}.`,
             decision: summary
                 ? `${cap(verb)} ${dirs.join(", ") || "the repo"}: ${summary}.`
-                : `${cap(verb)} code in ${dirs.join(", ") || "the repo"} (${input.files.length} file(s)).`,
+                : `${cap(verb)} ${noun} in ${dirs.join(", ") || "the repo"} (${input.files.length} file(s)).`,
             consequences,
             alternatives_rejected: [],
             // advisory either way, but real extraction earns a touch more confidence

package/dist/synthesis/synthesize.js

@@ -5,7 +5,7 @@ import { decisionId, bugId, constraintId } from "../core/ids.js";
 import { commitCoveredBy } from "../core/dupdetect.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
-import { languageFor } from "../extractors/languages.js";
+import { isSubstantive } from "../extractors/languages.js";
 // "chore(deps):" is anchored separately (not via \b) because \b requires a
 // word/non-word transition, and the character after the closing ")" is ":" or a
 // space — both non-word — so no boundary ever fires there.
@@ -26,14 +26,16 @@ export function isTrivialSubject(meta) {
  *  deterministic. Any structural change (symbol/dependency delta), non-trivial
  *  churn, several files, OR an explanatory commit body signals a real decision
  *  worth the model. Everything below (typo/tweak/one-liner with no message) falls
- *  to the free deterministic draft — shallower but honestly low-confidence. */
-export function isSignificant(meta, a, codeFiles) {
+ *  to the free deterministic draft — shallower but honestly low-confidence.
+ *  `files` is whatever the caller is synthesizing from (code and/or markdown, per
+ *  isSubstantive) — the line/file-count checks are format-agnostic. */
+export function isSignificant(meta, a, files) {
     const structural = a.addedSymbols.length + a.removedSymbols.length + a.changedSymbols.length + a.addedDeps.length + a.removedDeps.length;
     if (structural > 0)
         return true;
     if (a.addedLines + a.removedLines >= SIG_MIN_LINES)
         return true;
-    if (codeFiles.length >= 3)
+    if (files.length >= 3)
         return true;
     if (meta.body.trim().length >= SIG_MIN_BODY)
         return true;
@@ -50,9 +52,28 @@ export async function syncCommit(store, root, sha, opts = {}) {
         return { status: "skipped", reason: "commit not found" };
     if (isTrivialSubject(meta))
         return { status: "skipped", reason: `trivial subject: ${meta.subject}` };
-    const codeFiles = meta.files.filter((f) => languageFor(f) !== null);
-    if (codeFiles.length === 0)
-        return { status: "skipped", reason: "no code files changed" };
+    // .hunch/** is Hunch's OWN store — commitDiff already excludes it from the diff
+    // CONTENT via DIFF_NOISE ("circular noise": re-synthesizing a commit that wrote
+    // it would draft a decision about Hunch's own bookkeeping). That guard never
+    // covered this file-LIST gate, and before #12 it didn't need to: languageFor()
+    // already returned null for .hunch/**'s JSON and for the .md grounding docs
+    // flushCapture regenerates alongside it (AGENTS.md/CLAUDE.md/copilot-instructions.md),
+    // so such a commit failed "no code files changed" by coincidence. Once markdown
+    // became substantive input those grounding docs alone made the commit eligible.
+    // Checked by PATH, not commit-message convention (flushCapture's exact subject
+    // wording lives as separate literals in mcp/server.ts/cli/index.ts and could
+    // drift independently of any subject regex here) — a human editing AGENTS.md on
+    // its own, with no .hunch/** change alongside it, stays fully synthesis-eligible.
+    if (meta.files.some((f) => pathMatchesGlob(f, "**/.hunch/**"))) {
+        return { status: "skipped", reason: "touches Hunch's own store (.hunch/**) — circular, never synthesis input" };
+    }
+    // Substantive, not just parseable: markdown carries the *why* in a docs/ADR repo
+    // just as legitimately as a .ts diff does, even though it has no symbol graph
+    // (issue #12). languageFor() stays the parseability question for the symbol/dep
+    // extraction inside analyzeDiff below.
+    const substantiveFiles = meta.files.filter((f) => isSubstantive(f));
+    if (substantiveFiles.length === 0)
+        return { status: "skipped", reason: "no code or markdown files changed" };
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title
     // (which varies) — so re-syncing a commit updates rather than dupes.
     const id = decisionId(meta.sha);
@@ -83,7 +104,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // review triage measured 7 of 14 queued drafts as exactly this. A recent
     // human-confirmed decision claiming this commit's files → skip the draft (and
     // the subscription call). Recency-windowed; --force overrides.
-    const covered = commitCoveredBy(codeFiles, meta.subject, store.recs("decisions"), Date.now());
+    const covered = commitCoveredBy(substantiveFiles, meta.subject, store.recs("decisions"), Date.now());
     if (covered && !opts.force) {
         return {
             status: "skipped",
@@ -111,10 +132,10 @@ export async function syncCommit(store, root, sha, opts = {}) {
         ? new DeterministicProvider()
         : opts.deep
             ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider({ root })
-            : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
+            : opts.force || opts.verify || isSignificant(meta, analysis, substantiveFiles)
                 ? await selectProvider({ root })
                 : new DeterministicProvider();
-    const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
+    const input = { subject: meta.subject, body: meta.body, files: substantiveFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
     // The Critic pass: audit the draft against the commit, PRUNE unsupported alternatives
     // (BEFORE they scaffold tripwires below) and consequences, and lower confidence on weak
@@ -150,13 +171,13 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const branchTag = branch ? [`branch:${branch}`] : [];
     const components = store.json.loadAll("components");
     const relatedComponents = components
-        .filter((c) => codeFiles.some((f) => c.paths.some((g) => pathMatchesGlob(f, g))))
+        .filter((c) => substantiveFiles.some((f) => c.paths.some((g) => pathMatchesGlob(f, g))))
         .map((c) => c.id);
     // Surface any do-not-break constraints this commit's files touch (DESIGN §4
     // "constraint touched" flag) right in the decision context, with evidence.
     const touchedConstraints = store.json
         .loadAll("constraints")
-        .filter((c) => codeFiles.some((f) => c.scope.some((g) => pathMatchesGlob(f, g))));
+        .filter((c) => substantiveFiles.some((f) => c.scope.some((g) => pathMatchesGlob(f, g))));
     const constraintNote = touchedConstraints.length
         ? ` Touches invariant(s): ${touchedConstraints.map((c) => `${c.id} (${c.statement})`).join("; ")}.`
         : "";
@@ -183,9 +204,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
         // → never block until confirmed via `hunch review --accept` (dec_a466655539).
         rejected_tripwires: existing?.rejected_tripwires?.length
             ? existing.rejected_tripwires
-            : draftTripwires(draft.alternatives_rejected, codeFiles, knownRepoDeps(root)),
+            : draftTripwires(draft.alternatives_rejected, substantiveFiles, knownRepoDeps(root)),
         related_components: relatedComponents,
-        related_files: codeFiles,
+        related_files: substantiveFiles,
         supersedes: existing?.supersedes ?? null,
         superseded_by: existing?.superseded_by ?? null,
         caused_by_bug: existing?.caused_by_bug ?? null,
@@ -201,7 +222,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
         provenance: {
             source: draft.source,
             confidence: draft.confidence,
-            evidence: [`commit:${meta.shortSha}`, synthEvidence, ...branchTag, ...codeFiles.slice(0, 8)],
+            evidence: [`commit:${meta.shortSha}`, synthEvidence, ...branchTag, ...substantiveFiles.slice(0, 8)],
             last_verified: new Date().toISOString(), // when the Hunch last re-derived this
         },
         date: meta.date, // the commit date

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.28.0",
+  "version": "1.30.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.28.0",
+  "version": "1.30.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.28.0",
+      "version": "1.30.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 = [