@davesheffer/hunch 1.30.0 → 1.31.1

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, externalKey, subjectOfRef, assertReadWithinGrants, assertWriteWellFormed, assertDerivedState, isHumanConfirmed, } 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, relationshipId, 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;
@@ -169,6 +169,9 @@ 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`);
+    if (request.observed_page && (request.subject === undefined || request.scopes !== undefined || (request.facets && !request.facets.includes('derived')))) {
+        throw new StateRefusal('malformed', 'observation pages require a subject, the derived facet and a single partition without scopes');
+    }
     const repo = partitionOf(store);
     const facets = new Set(request.facets ?? STATE_FACETS);
     const target = request.task ?? request.subject ?? scopePath(request.scope);
@@ -196,9 +199,23 @@ export function readState(store, input) {
         // 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);
+        // One hop only. Do not broaden aliases: a linked observation does not merge subjects,
+        // bring unrelated facts, receipts or commitments, or traverse another relationship.
+        const linkedObservations = new Map();
+        for (const r of store.recs("relationships")) {
+            if (!granted(request.principal, r.scope) || scopePath(r.scope) !== scopePath(request.scope))
+                continue;
+            if (r.type !== "observation_about" || r.lifecycle === "retired" || !isSubject(r.to) || !r.observation_hash)
+                continue;
+            const hashes = linkedObservations.get(r.from) ?? new Set();
+            hashes.add(r.observation_hash);
+            linkedObservations.set(r.from, hashes);
+        }
         const current = [];
         const inForce = [];
         const done = [];
+        const observations = [];
+        let relationshipsTruncated = false;
         const dependsOn = [];
         const invalidatedBy = new Set();
         /** authorization-before-retrieval: the grant check runs before the record is examined. */
@@ -265,15 +282,26 @@ export function readState(store, input) {
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
-                if (!isSubject(d.subject) && d.id !== subject)
-                    continue;
                 const scope = admit("derived", d);
                 if (!scope)
                     continue;
+                if (request.observed_page && scopePath(scope) !== scopePath(request.scope))
+                    continue;
+                const direct = isSubject(d.subject) || d.id === subject;
+                const linked = scopePath(scope) === scopePath(request.scope) && linkedObservations.get(d.id)?.has(stateHash(d));
+                if (!direct && !linked)
+                    continue;
+                if (!direct) {
+                    if (d.state === "unknown" && d.valid_to == null)
+                        observations.push(d);
+                    continue;
+                }
                 if (d.state === "current" && d.valid_to == null) {
                     current.push(keep("derived", d, scope));
                     dependsOn.push(...d.dependencies);
                 }
+                else if (d.state === "unknown" && d.valid_to == null)
+                    observations.push(d);
             }
         if (facets.has("entities"))
             for (const e of store.recs("entities")) {
@@ -287,14 +315,39 @@ export function readState(store, input) {
             }
         if (facets.has("relationships"))
             for (const r of store.recs("relationships")) {
+                if (r.lifecycle === "retired")
+                    continue;
                 if (!isSubject(r.from) && !isSubject(r.to))
                     continue;
                 const scope = admit("relationships", r);
                 if (!scope)
                     continue;
+                if (current.length >= 256) {
+                    relationshipsTruncated = true;
+                    continue;
+                }
                 current.push(keep("relationships", r, scope));
             }
-        stateOfRecord = { subject, current, in_force: inForce, done, depends_on: dependsOn, invalidated_by: [...invalidatedBy].sort() };
+        observations.sort((a, b) => Date.parse(b.computed_at) - Date.parse(a.computed_at) || a.id.localeCompare(b.id));
+        let offset = 0;
+        let page;
+        if (request.observed_page) {
+            // Fingerprint the authorized membership AND record contents. A change between
+            // pages is a conflict, never a silently skipped or duplicated observation.
+            const snapshot_hash = stateHash({ scope: request.scope, subject, observations });
+            const cursor = request.observed_page.cursor;
+            if (cursor && cursor.snapshot_hash !== snapshot_hash)
+                throw new StateRefusal('conflict', 'observations changed between pages; restart from the first page');
+            offset = cursor?.offset ?? 0;
+            if (offset > observations.length)
+                throw new StateRefusal('malformed', 'observation cursor is outside this snapshot');
+            page = { snapshot_hash, total: observations.length, next_cursor: offset + 64 < observations.length ? { snapshot_hash, offset: offset + 64 } : null };
+        }
+        const observed = observations.slice(offset, offset + 64).map(d => keep("derived", d, recordScope(d, repo)));
+        stateOfRecord = { subject, current, in_force: inForce, done, depends_on: dependsOn, invalidated_by: [...invalidatedBy].sort(),
+            ...(relationshipsTruncated ? { relationships_truncated: true } : {}),
+            ...(observed.length || page ? { observed, observed_truncated: observations.length > offset + observed.length } : {}),
+            ...(page ? { observed_page: page } : {}) };
     }
     const response = ReadResponseSchema.parse({
         schema: STATE_READ_VERSION,
@@ -364,6 +417,9 @@ export function mergeReadResponses(primary, others, extraDenied = []) {
             current: dedupeRefs((s) => s.current),
             in_force: dedupeRefs((s) => s.in_force),
             done: dedupeRefs((s) => s.done),
+            ...(sors.some(s => s.relationships_truncated) ? { relationships_truncated: true } : {}),
+            ...(sors.some(s => s.observed?.length) ? { observed: dedupeRefs(s => s.observed ?? []).slice(0, 64),
+                observed_truncated: sors.some(s => s.observed_truncated) || dedupeRefs(s => s.observed ?? []).length > 64 } : {}),
             depends_on: dependsOn,
             invalidated_by: [...new Set(sors.flatMap((s) => s.invalidated_by))].sort(),
         };
@@ -390,7 +446,7 @@ function subjectOf(facet, record) {
         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 "relationships": return r.type === "observation_about" && typeof r.to === "string" ? r.to : 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;
@@ -565,6 +621,8 @@ function normalizeRecord(facet, scope, raw, principal) {
             expectedId = commitmentId(record);
         else if (facet === "derived")
             expectedId = derivedId(record);
+        else if (facet === "relationships")
+            expectedId = relationshipId(String(record.from), String(record.to), String(record.type));
         else if (facet === "decisions" && typeof record.id !== "string")
             expectedId = decisionId(String(record.topic ?? record.title ?? ""));
     }
@@ -602,20 +660,46 @@ export function writeState(store, input, opts = {}) {
     const { home, hunchDir, isPrivate } = stateHomeFor(store, request.scope);
     const now = (opts.now ?? (() => new Date()))().toISOString();
     const facet = request.facet;
+    const getHere = (id) => facet === "derived" || facet === "receipts" || facet === "commitments"
+        ? store.getStateDirect(facet, id, home)
+        : home === "private" ? store.getPrivateRec(facet, id) : store.json.get(facet, id);
     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);
+    let replayLink;
+    if (facet === "relationships" && record.type === "observation_about") {
+        const link = record;
+        const observation = store.getStateDirect("derived", link.from, home);
+        if (!observation || scopePath(observation.scope) !== scopePath(request.scope) || !granted(request.principal, observation.scope))
+            throw new StateRefusal("conflict", "observation is absent from the granted partition");
+        if (!observation.transform_version.startsWith("agent-capture/1:"))
+            throw new StateRefusal("malformed", "only captured observations can be linked");
+        if (link.lifecycle !== "retired" && (observation.state !== "unknown" || observation.valid_to != null || stateHash(observation) !== link.observation_hash))
+            throw new StateRefusal("conflict", "observation changed or is no longer eligible; re-read before linking");
+        const prior = getHere(link.id);
+        if (prior?.lifecycle === "retired" && link.lifecycle !== "retired" && request.expected_version === null)
+            throw new StateRefusal("conflict", "retired observation link requires an explicit expected_version to reactivate");
+        // Repeated reads and different agents do not rewrite an identical association.
+        // Preserve its first author/evidence time and avoid index/Git work on replay.
+        if (prior && prior.from === link.from && prior.to === link.to && prior.type === link.type && prior.reason === link.reason
+            && prior.observation_hash === link.observation_hash && prior.lifecycle === link.lifecycle
+            && prior.evidence && link.evidence && externalKey(prior.evidence) === externalKey(link.evidence) && prior.evidence.content_hash === link.evidence.content_hash) {
+            replayLink = prior;
+        }
+    }
     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 ledger = opts.ledgerCache?.ledger ?? readLedger(hunchDir, request.scope);
+    if (opts.ledgerCache)
+        opts.ledgerCache.ledger = ledger;
     const durability = () => opts.flush?.(isPrivate, `nuryel: write ${id}`) ?? "local";
     /** 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;
+        const onFile = getHere(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
@@ -631,9 +715,14 @@ export function writeState(store, input, opts = {}) {
         const where = differing.length ? ` — this payload differs in: ${differing.join(", ")}` : (seen.record_id !== id ? ` — this payload derives a different identity (${id})` : "");
         throw new StateRefusal("idempotency", `idempotency key "${request.idempotency_key}" was already used for ${seen.record_id}${where}. A key names ONE request payload: re-send the original payload to replay it, or use a new key to write this payload (the record keeps its derived id and is updated in place).`, { incumbent_id: seen.record_id, reason: "idempotency key reused with a different payload" });
     }
-    const existing = store.recsInHome(facet, home).find((r) => r.id === id);
+    const existing = getHere(id);
+    if (facet === 'derived') {
+        const review = record.review;
+        if (review && stateHash(review) !== stateHash(existing?.review ?? null) && review.by !== request.principal.id)
+            throw new StateRefusal('malformed', 'reviewer must be the initiating principal');
+    }
     if (existing && stateHash(existing) === hash) {
-        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now);
+        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
         return result("replayed");
     }
     if (existing && request.expected_version !== null) {
@@ -643,6 +732,11 @@ 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" });
     }
+    if (replayLink) {
+        const recordHash = stateHash(replayLink);
+        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: replayLink.id, record_hash: recordHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
+        return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: replayLink.id, record_hash: recordHash, record: replayLink, outcome: "replayed", conflict: null, durability: "local" });
+    }
     // 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
@@ -670,7 +764,7 @@ export function writeState(store, input, opts = {}) {
         };
         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);
+            appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: stateHash(existing), payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
             return result("replayed");
         }
         if (verdict === "keep-provenance")
@@ -719,15 +813,15 @@ export function writeState(store, input, opts = {}) {
     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 onFileHash = stateHash(getHere(id) ?? record);
     const changes = [];
     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 invalidated = facet === "derived" && !!existing && (existing.state === "current" || existing.state === "unknown") && 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 retired = (facet === "entities" || facet === "relationships") && record.lifecycle === "retired" && (!existing || existing.lifecycle !== "retired");
     const subject = subjectOf(facet, record);
     if (supersedes) {
         const closed = closeWindow(store, facet, supersedes, id, now, isPrivate);
@@ -737,8 +831,9 @@ export function writeState(store, input, opts = {}) {
         }
     }
     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();
+    appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: onFileHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);
+    if (!opts.deferReindex)
+        store.reindex();
     return result(supersedes ? "superseded" : existing ? "updated" : "created");
 }
 // ---- subscribe -----------------------------------------------------------------------------

package/dist/store/stateCapture.js

@@ -0,0 +1,145 @@
+import { CaptureRequestSchema, CaptureBatchRequestSchema, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION, STATE_WRITE_VERSION, assertDerivedState, captureTransform, derivedId, normalizeAssertion, canonicalObjectKey, externalKey, scopePath, stateHash } from "../core/stateContract.js";
+import { isCredentialFreeValue } from "../core/provenance.js";
+import { StateRefusal, stateHomeFor, writeState } from "./stateBinding.js";
+/** The caller selects relevant atomic claims; this deterministic boundary checks evidence
+ * fidelity and deduplication. It does not pretend to prove semantic entailment or relevance.
+ * Both bindings hold the partition write lock over lookup AND write. */
+export function captureState(store, input, opts = {}) {
+    const request = CaptureRequestSchema.parse(input);
+    if (!request.principal.grants.some(s => scopePath(s) === scopePath(request.scope)))
+        throw new StateRefusal("outside-grants", "capture scope is outside the principal's grants");
+    const { home } = stateHomeFor(store, request.scope);
+    const statement = normalizeAssertion(request.statement);
+    if (![statement, request.relevance.reason, ...request.evidence.map(e => e.excerpt)].every(isCredentialFreeValue))
+        throw new StateRefusal("malformed", "captured content must not contain credential material");
+    const evidence = request.evidence.map(e => {
+        if (!e.source_text.includes(e.excerpt))
+            throw new StateRefusal("malformed", "every excerpt must occur exactly in its supplied source text");
+        const hash = opts.sourceHashes?.get(e.source_text) ?? stateHash(e.source_text);
+        opts.sourceHashes?.set(e.source_text, hash);
+        if (e.ref.content_hash && e.ref.content_hash !== hash)
+            throw new StateRefusal("malformed", "source text does not match its declared content hash");
+        return { ref: { ...e.ref, object_key: canonicalObjectKey(e.ref.object_key), content_hash: hash }, excerpt: e.excerpt };
+    });
+    // Ignore read time, writer and unrelated source text when deduplicating an assertion.
+    // A different excerpt, statement, source identity or subject is a distinct observation.
+    const transform = captureTransform(request.scope, request.subject, statement, evidence.map(e => ({ source: externalKey(e.ref), excerpt: e.excerpt })));
+    const id = derivedId({ scope: request.scope, subject: request.subject, transform_version: transform, dependencies: [] });
+    const incumbent = store.getStateDirect("derived", id, home);
+    if (incumbent) {
+        assertDerivedState(incumbent);
+        if (incumbent.transform_version !== transform || scopePath(incumbent.scope) !== scopePath(request.scope) || incumbent.subject !== request.subject)
+            throw new StateRefusal("conflict", "capture identity collision; incumbent preserved");
+        // Never revive stale or human-corrected evidence, replace its author, or claim a new
+        // observation because another agent saw the same excerpt. Return what actually exists.
+        return { schema: STATE_WRITE_VERSION, record_id: incumbent.id, record_hash: stateHash(incumbent), durability: "local", outcome: "replayed", conflict: null, record: incumbent };
+    }
+    const refs = [...new Map(evidence.map(e => [stateHash(e.ref), e.ref])).entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, ref]) => ref);
+    const content = JSON.stringify({ schema: "nuryel.observation-content/1", statement, relevance: request.relevance,
+        evidence: evidence.map(e => ({ source: externalKey(e.ref), excerpt: e.excerpt })), captured_by: request.principal.id });
+    const record = {
+        schema: "nuryel.derived/1", scope: request.scope, subject: request.subject, content, content_hash: stateHash(content),
+        dependencies: refs.map(ref => ({ kind: "external", ref })), transform_version: transform,
+        computed_at: (opts.now ?? (() => new Date()))().toISOString(), valid_to: null, state: "unknown",
+        provenance: { source: "agent_recorded", confidence: 0.8, evidence: [`captured by ${request.principal.id}`, ...refs.map(externalKey)] },
+    };
+    return writeState(store, { schema: STATE_WRITE_VERSION, principal: request.principal, scope: request.scope, facet: "derived", record, idempotency_key: transform }, opts);
+}
+/** Bounded partial-success batch. The caller holds the same partition lock as writeState.
+ * Every result has its input index; a refused claim never hides a later valid new detail.
+ * A duplicate-only batch performs no record, ledger, index or Git writes. */
+export function captureBatchState(store, input, opts = {}) {
+    const request = CaptureBatchRequestSchema.parse(input);
+    if (!request.principal.grants.some(s => scopePath(s) === scopePath(request.scope)))
+        throw new StateRefusal("outside-grants", "capture scope is outside the principal's grants");
+    if (!request.observations.length && !request.reviews?.length)
+        throw new StateRefusal("malformed", "capture batch must contain observations or reviews");
+    const { home, isPrivate } = stateHomeFor(store, request.scope);
+    const sourceHashes = new Map();
+    const ledgerCache = {};
+    const results = [];
+    const reviews = [];
+    let changed = false;
+    try {
+        // Review before capture: a replay in the same batch must see the withdrawn state.
+        for (const [index, review] of (request.reviews ?? []).entries()) {
+            try {
+                const record = store.getStateDirect("derived", review.record_id, home);
+                if (!record || scopePath(record.scope) !== scopePath(request.scope) || !record.transform_version.startsWith('agent-capture/1:'))
+                    throw new StateRefusal('conflict', 'captured observation is absent from this partition');
+                if (!isCredentialFreeValue(review.reason))
+                    throw new StateRefusal('malformed', 'review reason contains credential material');
+                const evidence = review.evidence.map(e => {
+                    const source = request.sources[e.source];
+                    if (!source || !source.source_text.includes(e.excerpt) || !isCredentialFreeValue(e.excerpt))
+                        throw new StateRefusal('malformed', 'review excerpt must occur exactly in the supplied source');
+                    const hash = sourceHashes.get(source.source_text) ?? stateHash(source.source_text);
+                    sourceHashes.set(source.source_text, hash);
+                    if (source.ref.content_hash && source.ref.content_hash !== hash)
+                        throw new StateRefusal('malformed', 'review source hash mismatch');
+                    const ref = { ...source.ref, object_key: canonicalObjectKey(source.ref.object_key), content_hash: hash };
+                    const original = record.dependencies.find(d => d.kind === 'external' && externalKey(d.ref) === externalKey(ref));
+                    if (!original || original.kind !== 'external' || original.ref.content_hash === hash)
+                        throw new StateRefusal('conflict', 'review must cite a changed source the observation actually depends on');
+                    return { ref, excerpt: e.excerpt };
+                });
+                const identity = stateHash({ record_id: record.id, expected_hash: review.expected_hash, reason: review.reason, evidence: evidence.map(e => ({ source: externalKey(e.ref), hash: e.ref.content_hash, excerpt: e.excerpt })) });
+                // A safe retry returns the same withdrawal without changing its reviewer/time.
+                const old = record.review;
+                if (record.state === 'stale' && old && old.previous_hash === review.expected_hash && old.reason === review.reason && stateHash(old.evidence.map(e => ({ source: externalKey(e.ref), hash: e.ref.content_hash, excerpt: e.excerpt }))) === stateHash(evidence.map(e => ({ source: externalKey(e.ref), hash: e.ref.content_hash, excerpt: e.excerpt })))) {
+                    reviews.push({ index, status: 'saved', result: { schema: STATE_WRITE_VERSION, record_id: record.id, record_hash: stateHash(record), record: record, durability: 'local', outcome: 'replayed', conflict: null } });
+                    continue;
+                }
+                if (record.state !== 'unknown' || record.valid_to != null || stateHash(record) !== review.expected_hash)
+                    throw new StateRefusal('conflict', 'observation changed since review; read it again');
+                const at = (opts.now ?? (() => new Date()))().toISOString();
+                const result = writeState(store, { schema: STATE_WRITE_VERSION, principal: request.principal, scope: request.scope, facet: 'derived',
+                    record: { ...record, state: 'stale', review: { by: request.principal.id, at, previous_hash: review.expected_hash, reason: review.reason, evidence } },
+                    expected_version: review.expected_hash, idempotency_key: `observation-review:${identity}`, cause: { kind: 'external', ref: evidence[0].ref } }, { now: opts.now, ledgerCache, deferReindex: true });
+                changed ||= result.outcome !== 'replayed';
+                reviews.push({ index, status: 'saved', result });
+            }
+            catch (error) {
+                if (!(error instanceof StateRefusal))
+                    throw error;
+                reviews.push({ index, status: 'refused', code: error.code, message: error.message });
+            }
+        }
+        for (const [index, observation] of request.observations.entries()) {
+            try {
+                const evidence = observation.evidence.map(e => {
+                    const source = request.sources[e.source];
+                    if (!source)
+                        throw new StateRefusal("malformed", `evidence source index ${e.source} is absent`);
+                    return { ...source, excerpt: e.excerpt };
+                });
+                const result = captureState(store, { schema: STATE_CAPTURE_VERSION, principal: request.principal, scope: request.scope, ...observation, evidence }, { now: opts.now, sourceHashes, ledgerCache, deferReindex: true });
+                changed ||= result.outcome !== "replayed";
+                results.push({ index, status: "saved", result });
+            }
+            catch (error) {
+                if (!(error instanceof StateRefusal))
+                    throw error;
+                results.push({ index, status: "refused", code: error.code, message: error.message });
+            }
+        }
+    }
+    catch (error) {
+        // A filesystem failure may occur after an atomic record write but before its
+        // result; refresh the derived index before propagating the failure to the caller.
+        changed = true;
+        throw error;
+    }
+    finally {
+        if (changed)
+            store.reindex();
+    }
+    if (changed) {
+        const durability = opts.flush?.(isPrivate, `nuryel: capture ${results.filter(r => r.status === "saved" && r.result.outcome === "created").length} observations`) ?? "local";
+        for (const item of [...results, ...reviews])
+            if (item.status === "saved")
+                item.result.durability = durability;
+    }
+    return { schema: STATE_CAPTURE_BATCH_VERSION, results, ...(request.reviews ? { reviews } : {}) };
+}
+//# sourceMappingURL=stateCapture.js.map

package/dist/synthesis/cliAdapter.js

@@ -0,0 +1,168 @@
+/** Extensible local CLI transport. Executables/arguments come only from explicit user config. */
+import spawn from "cross-spawn";
+import { execFile } from "node:child_process";
+import { mkdtempSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative } from "node:path";
+import { z } from "zod";
+import { assertInitiatorProvider, initiatorChildEnv } from "./initiator.js";
+const adapterSchema = z.object({
+    name: z.string().regex(/^[a-z][a-z0-9-]{0,59}$/),
+    command: z.string().min(1).max(1000).refine(s => !/[\r\n\0]/.test(s)),
+    args: z.array(z.string().max(2000).refine(s => !/[\r\n\0]/.test(s))).max(40),
+    protocol: z.enum(["stdin", "acp"]),
+    probe_args: z.array(z.string().max(200).refine(s => !/[\r\n\0]/.test(s))).max(10).default(["--version"]),
+    timeout_ms: z.number().int().min(1000).max(600000).default(120000),
+}).strict();
+export function readAgentCliConfig(file) {
+    if (statSync(file).size > 64 * 1024)
+        throw new Error("CLI adapter config exceeds 64 KiB");
+    const adapters = z.array(adapterSchema).max(20).parse(JSON.parse(readFileSync(file, "utf8")));
+    if (new Set(adapters.map(a => a.name)).size !== adapters.length)
+        throw new Error("duplicate CLI adapter names");
+    return adapters;
+}
+/** ACP (Kimi and other agents) or plain stdin → JSON stdout for any user-configured CLI. */
+export async function runAgentCli(adapterInput, prompt) {
+    const adapter = adapterSchema.parse(adapterInput);
+    assertInitiatorProvider(adapter.name);
+    const parent = realpathSync(tmpdir());
+    const cwd = mkdtempSync(join(parent, "hunch-agent-provider-"));
+    const child = spawn(adapter.command, adapter.args, { cwd, env: initiatorChildEnv(), windowsHide: true, stdio: "pipe" });
+    const stop = () => {
+        if (process.platform === "win32" && child.pid) {
+            execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true }, () => { });
+        }
+        child.kill();
+    };
+    try {
+        return await new Promise((resolve, reject) => {
+            let done = false;
+            let buffer = "";
+            let output = "";
+            let bytes = 0;
+            let sequence = 0;
+            let sessionId;
+            const waiting = new Map();
+            const finish = (error) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve(output.trim());
+            };
+            const timer = setTimeout(() => { finish(new Error("CLI provider timed out")); stop(); }, adapter.timeout_ms);
+            const send = (message) => child.stdin.write(JSON.stringify(message) + "\n");
+            const request = (method, params, callback) => {
+                const id = ++sequence;
+                waiting.set(id, callback);
+                send({ jsonrpc: "2.0", id, method, params });
+            };
+            const receive = (line) => {
+                const message = JSON.parse(line);
+                if (message.method && message.id !== undefined) {
+                    // No permission approvals, filesystem reads/writes or shell services are granted.
+                    if (message.method === "session/request_permission") {
+                        send({ jsonrpc: "2.0", id: message.id, result: { outcome: { outcome: "cancelled" } } });
+                    }
+                    else
+                        send({ jsonrpc: "2.0", id: message.id, error: { code: -32601, message: "Unavailable in review-only client" } });
+                    return;
+                }
+                if (message.method === "session/update") {
+                    const params = message.params;
+                    if (params?.sessionId === sessionId && params.update?.sessionUpdate === "agent_message_chunk"
+                        && params.update.content?.type === "text" && typeof params.update.content.text === "string")
+                        output += params.update.content.text;
+                }
+                else if (typeof message.id === "number" && waiting.has(message.id)) {
+                    const callback = waiting.get(message.id);
+                    waiting.delete(message.id);
+                    if (message.error || !message.result || typeof message.result !== "object")
+                        throw new Error("ACP request failed");
+                    callback(message.result);
+                }
+            };
+            child.on("error", () => finish(new Error("CLI provider could not start")));
+            child.stdin.on("error", () => finish(new Error("CLI provider input closed")));
+            child.stderr.on("data", () => { }); // drain without collecting credentials or raw prompts
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                if (done)
+                    return;
+                bytes += Buffer.byteLength(chunk);
+                if (bytes > 2 * 1024 * 1024) {
+                    finish(new Error("CLI provider exceeded output budget"));
+                    stop();
+                    return;
+                }
+                if (adapter.protocol === "stdin") {
+                    output += chunk;
+                    return;
+                }
+                buffer += chunk;
+                try {
+                    let newline;
+                    while ((newline = buffer.indexOf("\n")) >= 0 && !done) {
+                        const line = buffer.slice(0, newline).trim();
+                        buffer = buffer.slice(newline + 1);
+                        if (line)
+                            receive(line);
+                    }
+                }
+                catch {
+                    finish(new Error("Invalid ACP response"));
+                }
+            });
+            child.on("close", code => {
+                if (adapter.protocol === "stdin" && code === 0)
+                    finish();
+                else
+                    finish(new Error("CLI provider exited before completing review"));
+            });
+            if (adapter.protocol === "stdin")
+                child.stdin.end(prompt);
+            else
+                request("initialize", { protocolVersion: 1, clientInfo: { name: "hunch-review-memory", version: "1" },
+                    clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true } }, initialized => {
+                    if (initialized.protocolVersion !== 1)
+                        throw new Error("Unsupported ACP protocol");
+                    request("session/new", { cwd, mcpServers: [] }, session => {
+                        if (typeof session.sessionId !== "string" || !session.sessionId)
+                            throw new Error("Missing ACP session");
+                        sessionId = session.sessionId;
+                        request("session/prompt", { sessionId, prompt: [{ type: "text", text: prompt }] }, result => {
+                            if (result.stopReason !== "end_turn")
+                                throw new Error("ACP turn did not complete");
+                            finish();
+                        });
+                    });
+                });
+        });
+    }
+    finally {
+        stop();
+        // Only remove the directory created for this invocation, after checking its resolved boundary.
+        const rel = relative(parent, realpathSync(cwd));
+        if (!isAbsolute(rel) && rel.startsWith("hunch-agent-provider-") && !rel.includes("/") && !rel.includes("\\")) {
+            try {
+                rmSync(cwd, { recursive: true, force: true });
+            }
+            catch { /* transient Windows handles; never affect review result */ }
+        }
+    }
+}
+export function discoverAgentClis(configured = [], initiator) {
+    const kimi = adapterSchema.parse({ name: "kimi-cli", command: "kimi", args: ["acp"], protocol: "acp" });
+    const adapters = [...configured, ...(configured.some(a => a.name === kimi.name) ? [] : [kimi])];
+    return adapters.filter(adapter => !initiator || adapter.name === initiator).filter(adapter => {
+        const result = spawn.sync(adapter.command, adapter.probe_args, {
+            cwd: tmpdir(), encoding: "utf8", windowsHide: true, timeout: 5000, maxBuffer: 64 * 1024,
+        });
+        return !result.error && result.status === 0;
+    }).map(adapter => ({ name: adapter.name, draftProse: prompt => runAgentCli(adapter, prompt) }));
+}
+//# sourceMappingURL=cliAdapter.js.map

package/dist/synthesis/initiator.js

@@ -0,0 +1,58 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const context = new AsyncLocalStorage();
+const aliases = { claude: "claude-cli", codex: "codex-cli", cursor: "cursor-agent", kimi: "kimi-cli", ollama: "openai-compat" };
+export function normalizeInitiator(name) {
+    const normalized = aliases[name] ?? name;
+    if (!/^[a-z][a-z0-9-]{0,59}$/.test(normalized) || ["auto", "available", "deterministic"].includes(normalized)) {
+        throw new Error("Initiator must identify one concrete agent provider.");
+    }
+    return normalized;
+}
+export function detectInitiator(env = process.env) {
+    if (env.HUNCH_INITIATOR === "unknown")
+        return { provider: null, source: "unknown" };
+    if (env.HUNCH_INITIATOR)
+        return { provider: normalizeInitiator(env.HUNCH_INITIATOR), source: "explicit" };
+    const names = new Set();
+    if (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID)
+        names.add("codex-cli");
+    if (env.CLAUDECODE === "1")
+        names.add("claude-cli");
+    return { provider: names.size === 1 ? [...names][0] : null,
+        source: names.size === 1 ? "environment" : names.size > 1 ? "ambiguous" : "unknown" };
+}
+export function currentInitiator(env = process.env) {
+    return context.getStore() ?? detectInitiator(env);
+}
+export function withInitiator(initiator, work) {
+    return context.run(Object.freeze({ ...initiator }), work);
+}
+/** Bind the MCP client, not the process that happened to start the server. Unknown clients stay unknown. */
+export function initiatorFromClient(name) {
+    const lower = name?.toLowerCase() ?? "";
+    const providers = [
+        [/\bclaude(?:[ _-]code)?\b/, "claude-cli"], [/\bcodex\b/, "codex-cli"],
+        [/\bcursor\b/, "cursor-agent"], [/\bkimi\b/, "kimi-cli"],
+    ];
+    const matched = providers.filter(([pattern]) => pattern.test(lower));
+    return { provider: matched.length === 1 ? matched[0][1] : null,
+        source: matched.length > 1 ? "ambiguous" : "client" };
+}
+/** Freeze the operation's origin before spawning Git hooks or other deferred children. */
+export function initiatorChildEnv(env = process.env) {
+    const origin = currentInitiator(env);
+    return { ...env, HUNCH_INITIATOR: origin.provider ?? "unknown" };
+}
+export function assertInitiatorProvider(provider) {
+    const origin = currentInitiator();
+    if (origin.provider && origin.provider !== provider)
+        throw new Error(`Initiator ${origin.provider} cannot launch ${provider}; refusing an account switch.`);
+    if (origin.source === "ambiguous")
+        throw new Error("Ambiguous initiating agent; refusing to launch another provider.");
+    if (origin.source === "client" && !origin.provider)
+        throw new Error("Unknown initiating MCP client; refusing to launch another provider.");
+    if (!origin.provider && (context.getStore() || process.env.HUNCH_INITIATOR === "unknown")) {
+        throw new Error("Unknown initiating event; refusing to launch another provider.");
+    }
+}
+//# sourceMappingURL=initiator.js.map