@davesheffer/hunch 1.30.0 → 1.31.1

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/extractors/git.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
 import { createRepoFileReader } from "../core/safeRepoFile.js";
+import { initiatorChildEnv } from "../synthesis/initiator.js";
 // `git` exports these repository-local variables to hooks. They outrank cwd/-C,
 // so carrying them from the code repository into a command for the memory
 // overlay can target the wrong index/object store. This is the documented set
@@ -21,7 +22,7 @@ const LOCAL_GIT_ENV_VARS = [
     "GIT_INTERNAL_SUPER_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
 ];
 export function foreignRepoEnv(source) {
-    const env = { ...source };
+    const env = initiatorChildEnv(source);
     for (const key of LOCAL_GIT_ENV_VARS)
         delete env[key];
     for (const key of Object.keys(env)) {
@@ -58,6 +59,7 @@ function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
         cwd, encoding: "utf8", maxBuffer,
+        env: initiatorChildEnv(),
         stdio: ["ignore", "pipe", "ignore"],
     }).trim();
 }

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";
@@ -57,6 +59,7 @@ import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken }
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { initiatorFromClient, withInitiator } from "../synthesis/initiator.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
 /** Error classes as text prefixes — client-agnostic, no schema change, so any MCP client
@@ -741,7 +744,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     refreshIndex();
             }
             catch { /* corrupt/churning local source — serve the last durable indexed view */ }
-            const result = await callback(...args);
+            const result = await withInitiator(initiatorFromClient(server.server.getClientVersion()?.name), () => callback(...args));
             if (teamAdvertised && !matchesStartupTeamRoute()) {
                 return refused("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
             }
@@ -1726,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) => {
@@ -1734,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.
@@ -1773,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);
@@ -1783,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 }) => {
@@ -1799,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