@davesheffer/hunch 1.31.0 → 1.32.0

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

@@ -0,0 +1,78 @@
+/**
+ * nuryel.state/1 — search and delivery of the five state kinds (receipts, commitments,
+ * derived, entities, relationships). Registered in 1.25 as store kinds, they were stored and
+ * counted but neither indexed nor delivered: `hunch_query("customer:Site:7")` could not surface
+ * a current summary, an open commitment or a verified receipt, and `hunch_context` had no
+ * "State" section. This module is the single place that says, per kind:
+ *
+ *   - what text goes into the `search` FTS row (subject + content/title + actor + status, so a
+ *     subject id and a human phrase both hit),
+ *   - whether a record is LIVE (current / in_force / verified…) or HISTORY (superseded, done,
+ *     cancelled, failed, retired) — history stays indexed and findable, it only ranks below,
+ *   - the one-line render every reader gets (`[commitment/in_force] customer:Site:7 — …`),
+ *   - the bounded, deterministically ordered "State" supplements for a context brief.
+ *
+ * Pure functions over records; no store or SQLite dependency, so the CLI, the MCP server and
+ * the store's own reindex/rank paths cannot drift from each other.
+ */
+import type { ActionReceipt, Commitment, DerivedState, ExternalEntity, StateRelationship } from "./stateRecords.js";
+import type { DeliverySupplement } from "./delivery.js";
+export declare const STATE_KINDS: readonly ["receipts", "commitments", "derived", "entities", "relationships"];
+export type StateKind = (typeof STATE_KINDS)[number];
+export declare function isStateKind(kind: string): kind is StateKind;
+export type StateRecord = ActionReceipt | Commitment | DerivedState | ExternalEntity | StateRelationship;
+export interface StateLiveness {
+    /** The contract's own word for the record's standing: current, in_force, verified, done, superseded … */
+    label: string;
+    /** True when the record is the state of record NOW; false for history (still indexed, ranked below). */
+    live: boolean;
+}
+/** Liveness per kind, mirroring readState's state_of_record predicates exactly
+ *  (derived `current` with an open window; commitment open/waiting with an open window;
+ *  receipt succeeded/verified; entity active; a relationship is always current). */
+export declare function stateLiveness(kind: StateKind, record: StateRecord): StateLiveness;
+/** The subject key a reader would type: the commitment/derived subject, the receipt's target
+ *  object (`event:10042`), the entity id, or the relationship's `from` endpoint. */
+export declare function stateSubject(kind: StateKind, record: StateRecord): string;
+/** The instant that orders "latest first": computed_at, valid_from, verified_at ?? occurred_at,
+ *  updated_at. Relationships carry no clock and sort last among equals. */
+export declare function stateObservedAt(kind: StateKind, record: StateRecord): string;
+/** The FTS document for a state record: title = the subject key (so an id query hits the
+ *  title column, which the snippet and LIKE fallback both prefer), body = the human words plus
+ *  the actor/owner, the status label and the dates. Every reader's query — a subject id, a
+ *  phrase from a summary, an action kind, a principal — lands on one of these. */
+export declare function stateSearchDoc(kind: StateKind, record: StateRecord): {
+    title: string;
+    body: string;
+};
+/** The one-line render shared by hunch_query, `hunch query` and the context "State" section:
+ *    [commitment/in_force] customer:Site:7 — "send report" due 2026-09-11 (owner sofia)
+ *    [derived/current] customer:Site:7 — <first 120 chars of the summary>
+ *    [receipt/verified] event:10042 — events_add_actions by sofia@david 2026-09-08 */
+export declare function renderStateLine(kind: StateKind, record: StateRecord): string;
+/** One ranked state hit, as the store's stateSlice() returns it. `score` is the search
+ *  score (bm25: lower is better; 0 for the LIKE fallback and exact-subject matches). */
+export interface StateHit<K extends StateKind = StateKind> {
+    kind: K;
+    record: StateRecord;
+    score: number;
+}
+/** Bounded caps for the context "State" section: current derived, in-force commitments,
+ *  latest receipts. Deliberately small — a brief, not a dump; `nuryel_read` is the full view. */
+export declare const STATE_SLICE_CAPS: {
+    readonly derived: 3;
+    readonly commitments: 5;
+    readonly receipts: 3;
+};
+export interface StateSlice {
+    derived: StateHit<"derived">[];
+    commitments: StateHit<"commitments">[];
+    receipts: StateHit<"receipts">[];
+}
+/** Deterministic order for a state slice: score (best first), then observed_at DESC (latest
+ *  first), then id ASC. Applied after liveness filtering, before the cap. */
+export declare function compareStateHits(a: StateHit, b: StateHit): number;
+/** Render a state slice as delivery supplements (one header + one line per record) so the
+ *  section shares the context brief's hard budget and receipt like every other grounding.
+ *  Empty slice → no supplements at all: a store with zero state records is byte-identical. */
+export declare function stateSupplements(slice: StateSlice, target: string): DeliverySupplement[];

package/dist/core/stateRecords.d.ts

@@ -0,0 +1,383 @@
+/**
+ * nuryel.state/1 — the RECORD schemas (the facets that are new record kinds in the store).
+ *
+ * Kept separate from stateContract.ts (verbs, invariants, hashing) because the store's kind
+ * registry in types.ts must reference these schemas, and stateContract imports types.ts —
+ * this module imports only zod, the id helpers and the provenance leaf, so there is no cycle.
+ *
+ * Facets here: done (ActionReceipt), committed (Commitment), current (DerivedState with
+ * mandatory dependencies), entity / relationship (external, Landscape-shaped), plus the
+ * credential-free ExternalRef ("changed") and DependencyRef they share. Scope is the one
+ * graph's partition: organization › team › user › repository.
+ */
+import { z } from "zod";
+import { edgeId, resourceId } from "./ids.js";
+export declare const RECEIPT_SCHEMA_VERSION: "nuryel.receipt/1";
+export declare const COMMITMENT_SCHEMA_VERSION: "nuryel.commitment/1";
+export declare const DERIVED_SCHEMA_VERSION: "nuryel.derived/1";
+export declare const ENTITY_SCHEMA_VERSION: "nuryel.entity/1";
+export declare const RELATIONSHIP_SCHEMA_VERSION: "nuryel.relationship/1";
+/** organization › team › user › repository — partitions of ONE graph, not separate stores. */
+export declare const SCOPE_KINDS: readonly ["organization", "team", "user", "repository"];
+export declare const ScopeSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        repository: "repository";
+        organization: "organization";
+        team: "team";
+        user: "user";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type Scope = z.infer<typeof ScopeSchema>;
+export declare const scopePath: (scope: Scope) => string;
+/** "What changed" and "where this came from": a credential-free pointer to an object that
+ *  stays authoritative in its own system. Nuryel never mirrors its content. */
+export declare const ExternalRefSchema: z.ZodObject<{
+    system: z.ZodString;
+    object_type: z.ZodString;
+    object_key: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    content_hash: z.ZodOptional<z.ZodString>;
+    observed_at: z.ZodString;
+    locator: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ExternalRef = z.infer<typeof ExternalRefSchema>;
+/** The external system's own key, canonicalized so two writers that copied it from the same
+ *  system agree byte for byte: Unicode NFC, trimmed, internal whitespace collapsed. Case is
+ *  preserved — the key belongs to the external system, and folding it could merge two of its
+ *  records. No other guessing: identity here is explicit refs, never similarity. */
+export declare function canonicalObjectKey(key: string): string;
+/** The identity of an external record across writers: system, type and canonical key. Two
+ *  entities in one partition that carry the same external key are the same thing. */
+export declare function externalKey(ref: Pick<ExternalRef, "system" | "object_type" | "object_key">): string;
+/** The subject an external record is known by, the convention the read verb already uses for
+ *  receipts (`event:26904`): the object type and the canonical key. When an entity in the
+ *  partition carries the ref, that entity's id is the subject and this form resolves to it. */
+export declare function subjectOfRef(ref: Pick<ExternalRef, "object_type" | "object_key">): string;
+/** What a derived statement rests on. Exactly what a currentness check re-validates. */
+export declare const DependencyRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"record">;
+    id: z.ZodString;
+    record_hash: z.ZodString;
+    scope: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    ref: z.ZodObject<{
+        system: z.ZodString;
+        object_type: z.ZodString;
+        object_key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        observed_at: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"schema">;
+    name: z.ZodString;
+    fingerprint: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type DependencyRef = z.infer<typeof DependencyRefSchema>;
+/** done — a side effect that happened. Never replayable as a read; idempotency is explicit. */
+export declare const ActionReceiptSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.receipt/1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    actor: z.ZodString;
+    action_kind: z.ZodString;
+    target: z.ZodObject<{
+        system: z.ZodString;
+        object_type: z.ZodString;
+        object_key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        observed_at: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    request_fingerprint: z.ZodString;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        requested: "requested";
+        succeeded: "succeeded";
+        failed: "failed";
+        verified: "verified";
+    }>;
+    occurred_at: z.ZodString;
+    verified_at: z.ZodOptional<z.ZodString>;
+    result_fingerprint: z.ZodOptional<z.ZodString>;
+    invalidates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    rests_on: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"record">;
+        id: z.ZodString;
+        record_hash: z.ZodString;
+        scope: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        ref: z.ZodObject<{
+            system: z.ZodString;
+            object_type: z.ZodString;
+            object_key: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            content_hash: z.ZodOptional<z.ZodString>;
+            observed_at: z.ZodString;
+            locator: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"schema">;
+        name: z.ZodString;
+        fingerprint: z.ZodString;
+    }, z.core.$strict>], "kind">>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type ActionReceipt = z.infer<typeof ActionReceiptSchema>;
+/** committed — an obligation with a due date and an in-force window. */
+export declare const CommitmentSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.commitment/1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    subject: z.ZodString;
+    title: z.ZodString;
+    owner: z.ZodString;
+    due: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        waiting: "waiting";
+        done: "done";
+        cancelled: "cancelled";
+    }>;
+    source: z.ZodOptional<z.ZodObject<{
+        system: z.ZodString;
+        object_type: z.ZodString;
+        object_key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        observed_at: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    evidence_excerpt: z.ZodOptional<z.ZodString>;
+    closed_by: z.ZodOptional<z.ZodString>;
+    valid_from: z.ZodString;
+    valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type Commitment = z.infer<typeof CommitmentSchema>;
+/** current — a statement that is true now, and on what it rests. Dependencies are mandatory:
+ *  a derived statement without them cannot be invalidated and therefore cannot be trusted. */
+export declare const DerivedStateSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.derived/1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    subject: z.ZodString;
+    content: z.ZodString;
+    content_hash: z.ZodString;
+    dependencies: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"record">;
+        id: z.ZodString;
+        record_hash: z.ZodString;
+        scope: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        ref: z.ZodObject<{
+            system: z.ZodString;
+            object_type: z.ZodString;
+            object_key: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            content_hash: z.ZodOptional<z.ZodString>;
+            observed_at: z.ZodString;
+            locator: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"schema">;
+        name: z.ZodString;
+        fingerprint: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+    transform_version: z.ZodString;
+    computed_at: z.ZodString;
+    valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        current: "current";
+        stale: "stale";
+    }>;
+    review: z.ZodOptional<z.ZodObject<{
+        by: z.ZodString;
+        at: z.ZodString;
+        previous_hash: z.ZodString;
+        reason: z.ZodString;
+        evidence: z.ZodArray<z.ZodObject<{
+            ref: z.ZodObject<{
+                system: z.ZodString;
+                object_type: z.ZodString;
+                object_key: z.ZodString;
+                version: z.ZodOptional<z.ZodString>;
+                content_hash: z.ZodOptional<z.ZodString>;
+                observed_at: z.ZodString;
+                locator: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            excerpt: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type DerivedState = z.infer<typeof DerivedStateSchema>;
+/** 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
+ *  an index file, like resources, because kind-qualified ids are not safe file names. */
+export declare const ExternalEntitySchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.entity/1">;
+    id: z.ZodString;
+    kind: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    refs: z.ZodArray<z.ZodObject<{
+        system: z.ZodString;
+        object_type: z.ZodString;
+        object_key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        observed_at: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    lifecycle: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        deprecated: "deprecated";
+        retired: "retired";
+    }>>;
+    merged_into: z.ZodOptional<z.ZodString>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strict>;
+export type ExternalEntity = z.infer<typeof ExternalEntitySchema>;
+/** relationship — rides the same identity rule as the graph's edges. Index-file stored. */
+export declare const StateRelationshipSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.relationship/1">;
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    type: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    reason: z.ZodDefault<z.ZodString>;
+    observation_hash: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodObject<{
+        system: z.ZodString;
+        object_type: z.ZodString;
+        object_key: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodOptional<z.ZodString>;
+        observed_at: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    lifecycle: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+    }>>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type StateRelationship = z.infer<typeof StateRelationshipSchema>;
+/** DNA facet: existing Project DNA profiles, keyed by scope. No new schema — the reference only. */
+export declare const DnaFacetRefSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"hunch.project-dna/1">;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    profile_id: z.ZodString;
+}, z.core.$strict>;
+export declare const entityId: typeof resourceId;
+export declare const relationshipId: typeof edgeId;

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({