@davesheffer/hunch 1.31.0 → 1.32.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, 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.d.ts

@@ -0,0 +1,15 @@
+import type { HunchStore } from "./hunchStore.js";
+import { type CaptureBatchResult, type WriteResult } from "../core/stateContract.js";
+import { type WriteOptions } from "./stateBinding.js";
+interface CaptureOptions extends WriteOptions {
+    sourceHashes?: Map<string, string>;
+}
+/** 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 declare function captureState(store: HunchStore, input: unknown, opts?: CaptureOptions): WriteResult;
+/** 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 declare function captureBatchState(store: HunchStore, input: unknown, opts?: WriteOptions): CaptureBatchResult;
+export {};

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.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+declare const adapterSchema: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    protocol: z.ZodEnum<{
+        stdin: "stdin";
+        acp: "acp";
+    }>;
+    probe_args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentCliAdapter = z.infer<typeof adapterSchema>;
+export interface AgentCliWorker {
+    name: string;
+    draftProse?(prompt: string): Promise<string>;
+}
+export declare function readAgentCliConfig(file: string): AgentCliAdapter[];
+/** ACP (Kimi and other agents) or plain stdin → JSON stdout for any user-configured CLI. */
+export declare function runAgentCli(adapterInput: AgentCliAdapter, prompt: string): Promise<string>;
+export declare function discoverAgentClis(configured?: AgentCliAdapter[], initiator?: string): AgentCliWorker[];
+export {};

package/dist/synthesis/initiator.d.ts

@@ -0,0 +1,13 @@
+export interface AgentInitiator {
+    provider: string | null;
+    source: "explicit" | "environment" | "client" | "unknown" | "ambiguous";
+}
+export declare function normalizeInitiator(name: string): string;
+export declare function detectInitiator(env?: NodeJS.ProcessEnv): AgentInitiator;
+export declare function currentInitiator(env?: NodeJS.ProcessEnv): AgentInitiator;
+export declare function withInitiator<T>(initiator: AgentInitiator, work: () => T): T;
+/** Bind the MCP client, not the process that happened to start the server. Unknown clients stay unknown. */
+export declare function initiatorFromClient(name: string | undefined): AgentInitiator;
+/** Freeze the operation's origin before spawning Git hooks or other deferred children. */
+export declare function initiatorChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function assertInitiatorProvider(provider: string): void;