@davesheffer/hunch 1.31.0 → 1.31.1

package/README.md

@@ -207,11 +207,7 @@ Hunch Memory service into Hunch.
 
 As of 1.27.0 a fourth verb, `records`, lists a subject's records for the first writers, and the per-scope ledger compacts and merges across clones. As of 1.28.0 reads are a union across writers, a supersede target must still be open (two racing writers can no longer leave two current records), state records are searchable and delivered by subject, and subjects are keyed by the external record rather than by the agent. Proven on an emulated organization: three agents over ten clinics and a generated year of mail, chat and CRM, one organization drawer, 96 cited summaries, 24 verified receipts, 24 commitments, zero contradictions.
 
-<<<<<<< HEAD
-As of 1.30.0 subject identity is by external reference: one active entity per external record per partition, a subject written as an entity's external key refused with the entity id named, reads resolving one explicit hop — so two agents over one CRM record land on one subject. Replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
-=======
-As of 1.30.0 replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, runs inside `hunch drift` when the partition has a ledger, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
->>>>>>> feat/replay-determinism
+As of 1.30.0 subject identity is by external reference: one active entity per external record per partition, a subject written as an entity's external key refused with the entity id named, reads resolving one explicit hop — so two agents over one CRM record land on one subject. Replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, runs inside `hunch drift` when the partition has a ledger, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
 
 Read [Deterministic organizational state](docs/deterministic-state.md), the [roadmap](ROADMAP.md) and the dated [competitive landscape](docs/competitive-landscape.md).
 
@@ -286,4 +282,4 @@ See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.m
 - [Architecture benchmark](bench/architectural-conformance.md)
 - [Contributing](CONTRIBUTING.md)
 
-Apache-2.0
+Apache-2.0

package/dist/client/state.js

@@ -41,6 +41,8 @@ export function createStateClient(opts) {
         capabilities: (scope) => call("GET", `/nuryel/v1/capabilities${scope ? `?scope=${encodeURIComponent(`${scope.kind}:${scope.id}`)}` : ""}`),
         read: (request) => call("POST", "/nuryel/v1/read", request),
         write: (request) => call("POST", "/nuryel/v1/write", request),
+        capture: (request) => call("POST", "/nuryel/v1/capture", request),
+        captureBatch: (request) => call("POST", "/nuryel/v1/capture-batch", request),
         subscribe: (request) => call("POST", "/nuryel/v1/subscribe", request),
         records: (request) => call("POST", "/nuryel/v1/records", request),
         health: () => call("GET", "/nuryel/v1/health"),

package/dist/core/stateContract.js

@@ -29,17 +29,22 @@ import { z } from "zod";
 import { compareCodeUnits } from "./canonicalOrder.js";
 import { DELIVERY_PROFILES } from "./delivery.js";
 import { isHumanConfirmed as sourceIsHumanConfirmed } from "./strictgate.js";
-import { ScopeSchema, scopePath, DependencyRefSchema, ExternalRefSchema, RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION, } from "./stateRecords.js";
+import { ScopeSchema, scopePath, externalKey, DependencyRefSchema, ExternalRefSchema, RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION, } from "./stateRecords.js";
 export * from "./stateRecords.js";
 export const STATE_CONTRACT_VERSION = "nuryel.state/1";
 export const STATE_READ_VERSION = "nuryel.state.read/1";
 export const STATE_WRITE_VERSION = "nuryel.state.write/1";
 export const STATE_SUBSCRIBE_VERSION = "nuryel.state.subscribe/1";
 export const STATE_RECORDS_VERSION = "nuryel.state.records/1";
+export const STATE_CAPTURE_VERSION = "nuryel.state.capture/1";
+export const STATE_CAPTURE_BATCH_VERSION = "nuryel.state.capture-batch/1";
+export const STATE_OBSERVATION_LINKS_VERSION = "nuryel.observation-links/1";
+export const STATE_OBSERVATION_REVIEW_VERSION = "nuryel.observation-review/1";
+export const STATE_OBSERVATION_PAGES_VERSION = "nuryel.observation-pages/1";
 /** Capabilities a server advertises; a client that needs one the server lacks gets a typed
  *  `unsupported`, never a compatible-looking degraded answer. */
 export const STATE_CAPABILITIES = [
-    STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION,
+    STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION, STATE_OBSERVATION_LINKS_VERSION, STATE_OBSERVATION_REVIEW_VERSION, STATE_OBSERVATION_PAGES_VERSION,
     RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION,
 ];
 const SHA256 = /^sha256:[a-f0-9]{64}$/;
@@ -55,12 +60,52 @@ export const PrincipalSchema = z.object({
     display: z.string().max(256).optional(),
     grants: z.array(ScopeSchema).min(1).max(64),
 }).strict();
+/** One relevant assertion, never a whole conversation. Source text is transient input:
+ * only its exact supporting excerpt and a hashed external pointer may reach the store. */
+export const CaptureRequestSchema = z.object({
+    schema: z.literal(STATE_CAPTURE_VERSION),
+    principal: PrincipalSchema,
+    scope: ScopeSchema,
+    subject: z.string().min(1).max(512),
+    statement: z.string().trim().min(1).max(1200),
+    relevance: z.object({
+        use: z.enum(["decision", "constraint", "preference", "operational_fact", "ongoing_issue"]),
+        reason: z.string().trim().min(1).max(600),
+    }).strict(),
+    evidence: z.array(z.object({
+        ref: ExternalRefSchema,
+        source_text: z.string().min(1).max(64000),
+        excerpt: z.string().trim().min(1).max(1200),
+    }).strict()).min(1).max(8),
+}).strict();
+/** Sources cross the transport once; assertions name only their supporting excerpts. */
+export const CaptureBatchRequestSchema = z.object({
+    schema: z.literal(STATE_CAPTURE_BATCH_VERSION), principal: PrincipalSchema, scope: ScopeSchema,
+    sources: z.array(CaptureRequestSchema.shape.evidence.element.omit({ excerpt: true })).min(1).max(8),
+    observations: z.array(CaptureRequestSchema.pick({ subject: true, statement: true, relevance: true }).extend({
+        evidence: z.array(z.object({ source: z.number().int().min(0).max(7), excerpt: z.string().trim().min(1).max(1200) }).strict()).min(1).max(8),
+    })).min(0).max(32),
+    reviews: z.array(z.object({
+        record_id: z.string().regex(/^nds_[a-f0-9]{24}$/), expected_hash: z.string().regex(SHA256),
+        reason: z.string().trim().min(1).max(600),
+        evidence: z.array(z.object({ source: z.number().int().min(0).max(7), excerpt: z.string().trim().min(1).max(1200) }).strict()).min(1).max(8),
+    }).strict()).min(1).max(32).optional(),
+}).strict();
+export const CAPTURE_TRANSFORM = "agent-capture/1:";
+export const normalizeAssertion = (text) => text.normalize("NFC").replace(/\r\n?/g, "\n").trim();
+export function captureTransform(scope, subject, statement, evidence) {
+    const identities = [...new Set(evidence.map(e => stateHash({ source: e.source, excerpt: normalizeAssertion(e.excerpt) })))].sort();
+    return CAPTURE_TRANSFORM + stateHash({ scope, subject, statement: normalizeAssertion(statement), evidence: identities }).slice(7);
+}
 export const STATE_FACETS = ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
 // ---- verbs ------------------------------------------------------------------------------
 /** Union read: the partitions a principal wants in ONE answer. `scope` stays required (it is the
  *  primary partition; its envelope and receipt lead the response). An entry the principal is not
  *  granted is NAMED in `denied_scopes` — it never refuses the whole call, and is never described. */
 export const ReadScopesSchema = z.array(ScopeSchema).min(1).max(64);
+export const ObservationCursorSchema = z.object({
+    snapshot_hash: z.string().regex(SHA256), offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+}).strict();
 export const ReadRequestSchema = z.object({
     schema: z.literal(STATE_READ_VERSION),
     principal: PrincipalSchema,
@@ -71,6 +116,8 @@ export const ReadRequestSchema = z.object({
     profile: z.enum(DELIVERY_PROFILES).optional(),
     budget_tokens: z.number().int().min(200).max(200_000).optional(),
     facets: z.array(z.enum(STATE_FACETS)).max(STATE_FACETS.length).optional(),
+    /** Explicit single-partition pagination; default subject reads keep their existing bound. */
+    observed_page: z.object({ cursor: ObservationCursorSchema.optional() }).strict().optional(),
 }).strict();
 const StateRefSchema = z.object({
     facet: z.enum(STATE_FACETS),
@@ -85,6 +132,11 @@ export const StateOfRecordSchema = z.object({
     current: z.array(StateRefSchema).max(256),
     in_force: z.array(StateRefSchema).max(256),
     done: z.array(StateRefSchema).max(256),
+    /** Source-backed observations, not a claim of currentness. Additive; absent on old hosts. */
+    observed: z.array(StateRefSchema).max(64).optional(),
+    observed_truncated: z.boolean().optional(),
+    observed_page: z.object({ snapshot_hash: z.string().regex(SHA256), total: z.number().int().nonnegative(), next_cursor: ObservationCursorSchema.nullable() }).strict().optional(),
+    relationships_truncated: z.boolean().optional(),
     depends_on: z.array(DependencyRefSchema).max(1024),
     invalidated_by: z.array(z.string().max(512)).max(256),
 }).strict();
@@ -131,6 +183,17 @@ export const WriteResultSchema = z.object({
      *  what landed without a second lookup. Additive. */
     record: z.record(z.string(), z.unknown()).optional(),
 }).strict();
+export const CaptureBatchResultSchema = z.object({
+    schema: z.literal(STATE_CAPTURE_BATCH_VERSION),
+    results: z.array(z.discriminatedUnion("status", [
+        z.object({ index: z.number().int(), status: z.literal("saved"), result: WriteResultSchema }).strict(),
+        z.object({ index: z.number().int(), status: z.literal("refused"), code: z.string(), message: z.string() }).strict(),
+    ])).max(32),
+    reviews: z.array(z.discriminatedUnion("status", [
+        z.object({ index: z.number().int(), status: z.literal("saved"), result: WriteResultSchema }).strict(),
+        z.object({ index: z.number().int(), status: z.literal("refused"), code: z.string(), message: z.string() }).strict(),
+    ])).max(32).optional(),
+}).strict();
 export const SubscribeRequestSchema = z.object({
     schema: z.literal(STATE_SUBSCRIBE_VERSION),
     principal: PrincipalSchema,
@@ -224,6 +287,11 @@ export function commitmentId(c) {
     return idFrom("ncm", { scope: c.scope, subject: c.subject, title: c.title.trim(), owner: c.owner, due: c.due });
 }
 export function derivedId(d) {
+    // Capture's reserved transform includes assertion/evidence identity, independent of
+    // read time and unrelated source edits. Ordinary summary identity is unchanged.
+    if (/^agent-capture\/1:[a-f0-9]{64}$/.test(d.transform_version)) {
+        return idFrom("nds", { scope: d.scope, subject: d.subject, transform_version: d.transform_version });
+    }
     return idFrom("nds", { scope: d.scope, subject: d.subject, transform_version: d.transform_version, dependencies: d.dependencies.map((dep) => stateHash(dep)).sort(compareCodeUnits) });
 }
 // ---- invariants --------------------------------------------------------------------------
@@ -237,7 +305,7 @@ export const STATE_INVARIANTS = [
     { id: "derived-state-carries-dependencies", statement: "A derived statement without dependencies cannot be invalidated and is therefore not state." },
     { id: "one-entity-per-external-ref", statement: "One external record is one entity in a partition: a second active entity carrying an external key an incumbent already carries is refused with the incumbent named, and a subject written as that record's external key is refused with the entity's id named. Identity is explicit refs, never similarity; merge is explicit — a retired entity names the survivor in `merged_into`, the ledger holds the `retired` event, nothing under the old id is rewritten and reads resolve to the survivor — and split is the explicit reverse; never a silent rewrite." },
     { id: "human-correction-outranks-agent-writes", statement: "A record a human confirmed is never overwritten or superseded by an agent or service principal: the agent may replay it, write derived state back stale with the external cause that moved, or close a commitment with a receipt on record. Changing what the human said takes a human." },
-    { id: "derived-state-writer-owns-currentness", statement: "No source writes the drawer. The writer of a derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. An agent that will not do this must not write derived state." },
+    { id: "derived-state-writer-owns-currentness", statement: "No source writes the drawer. The writer of a current derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. Without this duty an agent may capture source-backed observations only as unknown; observations never assert currentness." },
 ];
 const grantKey = (scope) => scopePath(scope);
 /** The memory supply chain's top tier: a record whose provenance a human signed. Same tier rule
@@ -252,7 +320,7 @@ export function assertReadWithinGrants(principal, response) {
     const granted = new Set(principal.grants.map(grantKey));
     if (!granted.has(grantKey(response.scope)))
         throw new Error(`read response scope ${grantKey(response.scope)} is outside the principal's grants`);
-    const refs = response.state_of_record ? [...response.state_of_record.current, ...response.state_of_record.in_force, ...response.state_of_record.done] : [];
+    const refs = response.state_of_record ? [...response.state_of_record.current, ...response.state_of_record.in_force, ...response.state_of_record.done, ...(response.state_of_record.observed ?? [])] : [];
     for (const ref of refs) {
         if (!granted.has(grantKey(ref.scope)))
             throw new Error(`state ref ${ref.id} in scope ${grantKey(ref.scope)} leaked outside the principal's grants`);
@@ -289,6 +357,21 @@ export function assertDerivedState(d) {
         throw new Error("derived state without dependencies is not state");
     if (stateHash(d.content) !== d.content_hash)
         throw new Error("derived state content hash does not match its content");
+    if (d.transform_version.startsWith(CAPTURE_TRANSFORM)) {
+        const content = z.object({
+            schema: z.literal("nuryel.observation-content/1"),
+            statement: CaptureRequestSchema.shape.statement, relevance: CaptureRequestSchema.shape.relevance,
+            evidence: z.array(z.object({ source: z.string(), excerpt: z.string().min(1).max(1200) }).strict()).min(1).max(8),
+            captured_by: PrincipalSchema.shape.id,
+        }).strict().parse(JSON.parse(d.content));
+        if (d.state === "current")
+            throw new Error("capture observations cannot assert currentness; publish a separately revalidated summary");
+        if (captureTransform(d.scope, d.subject, content.statement, content.evidence) !== d.transform_version)
+            throw new Error("capture identity does not match its assertion and evidence");
+        const pointers = new Set(d.dependencies.filter(dep => dep.kind === "external").map(dep => externalKey(dep.ref)));
+        if (content.evidence.some(e => !pointers.has(e.source)))
+            throw new Error("capture evidence lacks its external dependency");
+    }
 }
 /** Subscribe streams are strictly ordered per scope; a gap or regression means the caller must
  *  resynchronize instead of trusting what it holds. */

package/dist/core/stateRecords.js

@@ -127,8 +127,16 @@ export const DerivedStateSchema = z.object({
     computed_at: z.string().regex(ISO),
     valid_to: z.string().regex(ISO).nullable().default(null),
     state: z.enum(["current", "stale", "unknown"]),
+    /** Per-observation withdrawal. Original assertion, author and dependencies stay intact. */
+    review: z.object({
+        by: z.string().regex(TOKEN), at: z.string().regex(ISO), previous_hash: z.string().regex(SHA256), reason: z.string().trim().min(1).max(600),
+        evidence: z.array(z.object({ ref: ExternalRefSchema, excerpt: z.string().trim().min(1).max(1200) }).strict()).min(1).max(8),
+    }).strict().optional(),
     provenance: ProvenanceSchema,
-}).strict();
+}).strict().superRefine((record, ctx) => {
+    if (record.review && record.state !== 'stale')
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['review'], message: 'withdrawal review belongs only to a stale observation' });
+});
 const AttributeValue = z.union([z.string().max(2048), z.number().finite(), z.boolean(), z.null()]);
 /** entity — a customer, an incident, a thread: a non-code node, Landscape-shaped (kind-qualified
  *  id, lifecycle, provenance), with provenance pointers instead of mirrored content. Stored in
@@ -175,10 +183,17 @@ export const StateRelationshipSchema = z.object({
     type: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
     scope: ScopeSchema,
     reason: z.string().max(1024).default(""),
+    /** observation_about is a one-hop projection, never an entity merge or a copied fact. */
+    observation_hash: z.string().regex(SHA256).optional(),
+    evidence: ExternalRefSchema.optional(),
+    lifecycle: z.enum(["active", "retired"]).optional(),
     provenance: ProvenanceSchema,
 }).strict().superRefine((rel, ctx) => {
     if (rel.id !== edgeId(rel.from, rel.to, rel.type))
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "relationship id must derive from its endpoints and type" });
+    if (rel.type === "observation_about" && (!/^nds_[a-f0-9]{24}$/.test(rel.from) || !rel.observation_hash || !rel.evidence?.content_hash || !rel.reason.trim() || rel.to.length > 512 || rel.to === rel.from)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "observation_about requires an observation id/hash, a subject, reason and hashed external evidence of the explicit association" });
+    }
 });
 /** DNA facet: existing Project DNA profiles, keyed by scope. No new schema — the reference only. */
 export const DnaFacetRefSchema = z.object({

package/dist/mcp/server.js

@@ -14,6 +14,8 @@ import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { captureState, captureBatchState } from "../store/stateCapture.js";
+import { CaptureRequestSchema, CaptureBatchRequestSchema, CaptureBatchResultSchema, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, stateHash } from "../core/stateContract.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
@@ -1727,7 +1729,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     });
     server.registerTool("nuryel_read", {
         title: "nuryel.state/1 read — the system-of-record answer for a subject",
-        description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped.",
+        description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped. To read observations beyond the default 64, use observed_page:{} with one scope and a subject, then pass state_of_record.observed_page.next_cursor as observed_page.cursor until null. A conflict means the observations changed: restart from the first page. Never claim complete coverage while a next cursor remains.",
         inputSchema: ReadRequestSchema.omit({ schema: true }).shape,
         outputSchema: ReadResponseSchema.shape,
     }, async (input) => {
@@ -1735,7 +1737,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, ...input });
             const sor = response.state_of_record;
             const summary = sor
-                ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
+                ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · observed ${sor.observed?.length ?? 0} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
                 : "no subject — delivery envelope only";
             const deniedNote = response.denied_scopes.length ? `\ndenied scopes: ${response.denied_scopes.map((s) => `${s.kind}/${s.id}`).join(", ")}` : "";
             // Render the state of record itself, not only its refs: a consumer answers from this text.
@@ -1774,6 +1776,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             };
             const stateText = sor
                 ? [...sor.current.map((r) => line("current", r)), ...sor.in_force.map((r) => line("in force", r)), ...sor.done.map((r) => line("done", r)),
+                    ...(sor.observed ?? []).map(r => line("observed; verify currentness before relying on it", r)),
+                    ...(sor.observed_page ? [`- Observation page: ${sor.observed_page.total} total; next_cursor: ${JSON.stringify(sor.observed_page.next_cursor)}`]
+                        : sor.observed_truncated ? ['- More observations exist; read this subject with observed_page:{} in one partition, then follow next_cursor.'] : []),
                     ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
                 : "";
             return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
@@ -1784,7 +1789,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     });
     server.registerTool("nuryel_write", {
         title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-        description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay.",
+        description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version.",
         inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
         outputSchema: WriteResultSchema.shape,
     }, async ({ cwd: _cwd, ...input }) => {
@@ -1800,6 +1805,38 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return stateRefusal(e);
         }
     });
+    server.registerTool("nuryel_capture", {
+        title: "nuryel.state/1 capture — one relevant assertion with exact source excerpts",
+        description: "Save ONE relevant atomic assertion learned during the task. First split mixed source material into independent assertions; check each one, retaining new relevant details inside otherwise known passages. Exclude chatter, speculation, unsupported conclusions and transient tool output. Supply a concrete future-use reason and exact excerpts from the source text. Whole source text is transient and is never stored. Deduplication is per assertion + subject + source excerpt, independent of agent and read time; never skip a whole document because some of it is known. Records are observations, not verified current summaries or execution receipts. Call after substantive learning without waiting for the user to say remember. Read back the returned record before claiming it was saved.",
+        inputSchema: { ...CaptureRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
+        outputSchema: WriteResultSchema.shape,
+    }, async ({ cwd: _cwd, ...input }) => {
+        try {
+            const result = await withWriteLock(hunchPaths(root).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
+                flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+            }));
+            return stateResult(`${result.outcome} observation ${result.record_id} (${result.durability}); this does not assert currentness. ${result.record_hash}`, result);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
+    server.registerTool("nuryel_capture_batch", {
+        title: "nuryel.state/1 capture batch — save relevant atomic observations",
+        description: "Preferred capture for multiple facts learned during the task. Split source material into independent relevant assertions, select exact supporting excerpts and give each a concrete future-use reason. Exclude chatter, unsupported inference and transient output. Check every assertion even in a known paragraph: deduplication never discards a whole passage. Send each source once and reference its zero-based index. At most 32 observations and 8 sources; split larger work into batches. One partition lock and index update, no extra model call. Results preserve input indexes; inspect every refusal and stored record. Saved observations have unknown currentness, not verified receipts or current summaries. Use your own initiating agent identity automatically after substantive learning. Optional reviews withdraw specific prior observations: supply record_id, expected_hash, a reason, and exact excerpts from a changed source that observation depends on. Mere hash changes, missing text or uncertain interpretation never suffice; the initiating agent must identify explicit contradiction or withdrawal. Original facts remain in history with the review author and evidence. Review results are separately indexed; inspect every refusal.",
+        inputSchema: { ...CaptureBatchRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
+        outputSchema: CaptureBatchResultSchema.shape,
+    }, async ({ cwd: _cwd, ...input }) => {
+        try {
+            const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
+                flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+            }));
+            return stateResult(`Capture batch: ${result.results.filter(r => r.status === "saved").length} saved/replayed, ${result.results.filter(r => r.status === "refused").length} refused.${result.reviews ? ` Reviews: ${result.reviews.filter(r => r.status === "saved").length} withdrawn/replayed, ${result.reviews.filter(r => r.status === "refused").length} refused.` : ''} Inspect each indexed result.`, result);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
     server.registerTool("nuryel_subscribe", {
         title: "nuryel.state/1 subscribe — the scope's ordered change stream after a cursor",
         description: "Return the change events for a scope with seq > after_seq, strictly ordered. Unfiltered, the events are contiguous (a gap means resynchronize); with facets/subjects filters the response is a subsequence and head_seq is still your next cursor. Each event names the record, its hash, what changed, what it invalidates, and the cause.",

package/dist/serve/app.js

@@ -24,6 +24,8 @@ import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STA
 import { partitionFor, resolvePrincipal } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
 import { HUNCH_VERSION } from "../core/version.js";
+import { captureState, captureBatchState } from "../store/stateCapture.js";
+import { STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
@@ -148,6 +150,8 @@ export function createServeApp(config, opts = {}) {
             delete body.schema;
             if (url.pathname === "/nuryel/v1/read") {
                 const scope = requireScope(principal, body);
+                if (body.observed_page !== undefined && body.scopes !== undefined)
+                    throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
                 const { store } = storeFor(scope);
                 if (body.scopes === undefined) {
                     const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body });
@@ -178,6 +182,22 @@ export function createServeApp(config, opts = {}) {
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
+            if (url.pathname === "/nuryel/v1/capture") {
+                const scope = requireScope(principal, body);
+                const { store } = storeFor(scope);
+                const result = await withWriteLock(hunchPaths(store.publicRoot).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(store.publicRoot).hunch, isPrivate, message),
+                }));
+                return send(res, result.outcome === "created" ? 201 : 200, result);
+            }
+            if (url.pathname === "/nuryel/v1/capture-batch") {
+                const scope = requireScope(principal, body);
+                const { store, root } = storeFor(scope);
+                const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
+                }));
+                return send(res, 200, result);
+            }
             if (url.pathname === "/nuryel/v1/subscribe") {
                 const scope = requireScope(principal, body);
                 const { store } = storeFor(scope);

package/dist/store/changeLedger.js

@@ -10,7 +10,7 @@
  * here (see docs/nuryel-state-contract.md, "Not decided here").
  */
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { writeFileAtomic } from "../core/io.js";
@@ -39,6 +39,12 @@ export const LedgerSchema = z.object({
     events: z.array(ChangeEventSchema),
     idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
 }).strict();
+// Process-local acceleration only: compare the actual bytes on EVERY read, never
+// timestamps or a TTL. Separate processes and same-size replacements stay visible.
+// Keep only four small snapshots; oversized ledgers follow the uncached path.
+const validatedSnapshots = new Map();
+const MAX_CACHED_LEDGERS = 4;
+const MAX_CACHED_CHARACTERS = 1024 * 1024;
 /** Scope ids may carry `:` `@` `+` (safe in the contract, not in every file system), so
  *  the file name is the sanitized id plus a short hash of the exact id — readable AND
  *  collision-free. The scope inside the file is authoritative, the name is a locator. */
@@ -53,10 +59,21 @@ export function emptyLedger(scope) {
 /** Read the ledger for a scope; a missing file is an empty ledger, a corrupt one is an
  *  error (never silently treated as empty — that would restart the sequence). */
 export function readLedger(hunchDir, scope) {
-    const file = ledgerFile(hunchDir, scope);
-    if (!existsSync(file))
+    const file = resolve(ledgerFile(hunchDir, scope));
+    if (!existsSync(file)) {
+        validatedSnapshots.delete(file);
         return emptyLedger(scope);
-    const raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    const text = readFileSync(file, "utf8");
+    const cached = validatedSnapshots.get(file);
+    if (cached?.text === text && cached.scope === scopePath(scope)) {
+        validatedSnapshots.delete(file);
+        validatedSnapshots.set(file, cached);
+        // append/compaction callers mutate their copy. Never expose the cached object.
+        return JSON.parse(cached.normalized);
+    }
+    validatedSnapshots.delete(file);
+    const raw = JSON.parse(text);
     const ledger = LedgerSchema.parse(raw);
     if (scopePath(ledger.scope) !== scopePath(scope))
         throw new Error(`ledger ${file} belongs to scope ${scopePath(ledger.scope)}, not ${scopePath(scope)}`);
@@ -68,18 +85,30 @@ export function readLedger(hunchDir, scope) {
     }
     if (ledger.head_seq !== ledger.floor_seq + ledger.events.length)
         throw new Error(`ledger ${file} head_seq ${ledger.head_seq} disagrees with floor ${ledger.floor_seq} + ${ledger.events.length} events`);
+    if (text.length <= MAX_CACHED_CHARACTERS) {
+        while (validatedSnapshots.size >= MAX_CACHED_LEDGERS)
+            validatedSnapshots.delete(validatedSnapshots.keys().next().value);
+        validatedSnapshots.set(file, { text, normalized: JSON.stringify(ledger), scope: scopePath(scope) });
+    }
     return ledger;
 }
 export function writeLedger(hunchDir, ledger) {
+    writeValidatedLedger(hunchDir, LedgerSchema.parse(ledger));
+}
+function writeValidatedLedger(hunchDir, ledger) {
     const file = ledgerFile(hunchDir, ledger.scope);
     mkdirSync(join(hunchDir, CHANGES_DIR), { recursive: true });
-    writeFileAtomic(file, JSON.stringify(LedgerSchema.parse(ledger), null, 2) + "\n");
+    writeFileAtomic(file, JSON.stringify(ledger, null, 2) + "\n");
 }
 /** Append events (in order) and remember an idempotency key in ONE atomic write, so a
  *  crash between "record written" and "event appended" can be detected by the next
  *  writer (record present, ledger silent) rather than producing a half-applied write. */
-export function appendChanges(hunchDir, scope, changes, idempotency, at = new Date().toISOString()) {
-    const ledger = readLedger(hunchDir, scope);
+export function appendChanges(hunchDir, scope, changes, idempotency, at = new Date().toISOString(), 
+/** Already validated under the same uninterrupted partition lock; batch-local only. */
+current) {
+    const ledger = current ?? readLedger(hunchDir, scope);
+    if (scopePath(ledger.scope) !== scopePath(scope))
+        throw new Error("cached ledger belongs to another scope");
     const appended = [];
     for (const change of changes) {
         const event = ChangeEventSchema.parse({ schema: "nuryel.state.subscribe/1", seq: ledger.head_seq + 1, at, scope, ...change });
@@ -88,9 +117,11 @@ export function appendChanges(hunchDir, scope, changes, idempotency, at = new Da
         appended.push(event);
     }
     if (idempotency) {
-        ledger.idempotency[idempotency.key] = { ...idempotency.entry, seq: ledger.head_seq, at };
+        ledger.idempotency[idempotency.key] = IdempotencyEntrySchema.parse({ ...idempotency.entry, seq: ledger.head_seq, at });
     }
-    writeLedger(hunchDir, ledger);
+    // The initial ledger and each new event/entry are validated; don't re-validate the
+    // full history per assertion. Each append still reaches disk atomically before return.
+    writeValidatedLedger(hunchDir, ledger);
     return appended;
 }
 /** The latest seq that touched a record in this scope, or 0 when the ledger never saw it. */

package/dist/store/hunchStore.js

@@ -192,8 +192,10 @@ export class HunchStore {
     putCapture(kind, record, isPrivate = false) {
         const home = this.captureHome(isPrivate);
         const id = record.id;
-        const targetHasRecord = home === "private" ? !!this.privateJson?.get(kind, id) : !!this.json.get(kind, id);
-        const otherHasRecord = home === "private" ? !!this.json.get(kind, id) : !!this.privateJson?.get(kind, id);
+        const lookup = (json) => kind === "derived" || kind === "receipts" || kind === "commitments"
+            ? json?.getDirect(kind, id) : json?.get(kind, id);
+        const targetHasRecord = !!lookup(home === "private" ? this.privateJson : this.json);
+        const otherHasRecord = !!lookup(home === "private" ? this.json : this.privateJson);
         // Legacy repositories can already contain twins, so an idempotent update in
         // the selected home remains possible. A new capture must never CREATE that
         // ambiguous state: merged/private-first reads would make later writers and
@@ -244,6 +246,9 @@ export class HunchStore {
     getPrivateRec(kind, id) {
         return this.privateJson?.get(kind, id);
     }
+    getStateDirect(kind, id, home) {
+        return (home === "private" ? this.privateJson : this.json)?.getDirect(kind, id);
+    }
     /** Update an EXISTING record in the store that holds it — an overlay record must never
      *  fork a public copy on update (and vice versa). Falls back to captureHome routing for
      *  a record that exists nowhere yet. */

package/dist/store/jsonStore.js

@@ -559,6 +559,21 @@ export class JsonStore {
     get(kind, id) {
         return this.loadAll(kind).find((r) => r.id === id);
     }
+    /** Direct authoritative state lookup. No directory enumeration or stale cache;
+     * migration precedes validation and corrupt files fail closed. */
+    getDirect(kind, id) {
+        const file = this.fileFor(kind, id);
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
+            return undefined;
+        const text = this.readContainedFile(directory, file, this.maxBytes(kind));
+        if (text === null || text.trim() === "")
+            return undefined;
+        const record = SCHEMAS[kind].parse(this.migrate(kind, JSON.parse(text), this.schemaVersion()));
+        if (record.id !== id)
+            throw new Error(`record identity does not match ${kind} file name`);
+        return record;
+    }
     /** On-disk record count, independent of validation: per-record kinds count
      *  every non-tombstone .json file (a 0-byte merge tombstone is an intentional
      *  absence), single-file kinds count raw array entries (a corrupt index file

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.31.0",
+  "version": "1.31.1",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

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