@davesheffer/hunch 1.23.3 → 1.25.0

package/dist/core/stateContract.js

@@ -0,0 +1,250 @@
+/**
+ * nuryel.state/1 — the ONE contract every orchestrator and agent speaks to the state layer.
+ *
+ * Direction (private records vision.deterministic-state-layer, architecture.single-integration-
+ * surface): agents are probabilistic, organizations need deterministic state, Nuryel holds it.
+ * Protocols are bindings of this contract, never separate integrations. This module is the
+ * contract FROZEN AS CODE — the verbs, canonical hashing, id derivation and invariants. The
+ * record schemas (facets) live in ./stateRecords.js so the store's kind registry can import
+ * them without a cycle; they are re-exported here so callers see one contract module.
+ *
+ * Facets of organizational state (each maps to a record kind):
+ *   decided   — Decision (exists)              in force — Constraint / valid_to (exists)
+ *   done      — ActionReceipt                  committed — Commitment
+ *   changed   — ExternalRef version pointer    current — DerivedState with dependencies
+ *   entity / relationship — external entities and their links (Landscape-shaped)
+ *   DNA       — hunch.project-dna/1 profiles keyed by scope (exists; scope keying is new)
+ *
+ * Three verbs: read (with a delivery receipt), write (provenance + idempotency, returns
+ * durability), subscribe (changes to what the caller holds). Invariants are exported as
+ * assertions so bindings and tests enforce them, not prose.
+ *
+ * Compatibility: additive. No existing record changes shape; `scope` on legacy records defaults
+ * to the repository scope; the new facets are new record kinds an older reader ignores. The
+ * schema version of the JSON store is untouched. Verbs are not wired into the store, CLI or MCP
+ * here; bindings are generated from these schemas in a later step.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { compareCodeUnits } from "./canonicalOrder.js";
+import { DELIVERY_PROFILES } from "./delivery.js";
+import { ScopeSchema, scopePath, 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";
+/** 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,
+    RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION,
+];
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+// Explicit classes, no `i` flag: the pattern must survive zod → JSON schema for MCP output validation.
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+// ---- principal --------------------------------------------------------------------------
+/** Who is reading or writing. Grants are the scopes the principal may see; authorization is
+ *  decided BEFORE retrieval against these, never after ranking. */
+export const PrincipalSchema = z.object({
+    id: z.string().regex(TOKEN),
+    kind: z.enum(["human", "agent", "service"]),
+    display: z.string().max(256).optional(),
+    grants: z.array(ScopeSchema).min(1).max(64),
+}).strict();
+export const STATE_FACETS = ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
+// ---- verbs ------------------------------------------------------------------------------
+export const ReadRequestSchema = z.object({
+    schema: z.literal(STATE_READ_VERSION),
+    principal: PrincipalSchema,
+    scope: ScopeSchema,
+    subject: z.string().max(512).optional(),
+    task: z.string().max(4096).optional(),
+    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(),
+}).strict();
+const StateRefSchema = z.object({
+    facet: z.enum(STATE_FACETS),
+    id: z.string().min(1).max(2048),
+    record_hash: z.string().regex(SHA256),
+    scope: ScopeSchema,
+}).strict();
+/** The system-of-record answer for a subject: what is true now, on what it rests, what would
+ *  invalidate it. Carried beside the existing delivery envelope, under the same receipt. */
+export const StateOfRecordSchema = z.object({
+    subject: z.string().max(512),
+    current: z.array(StateRefSchema).max(256),
+    in_force: z.array(StateRefSchema).max(256),
+    done: z.array(StateRefSchema).max(256),
+    depends_on: z.array(DependencyRefSchema).max(1024),
+    invalidated_by: z.array(z.string().max(512)).max(256),
+}).strict();
+export const ReadResponseSchema = z.object({
+    schema: z.literal(STATE_READ_VERSION),
+    receipt_id: z.string().regex(/^hdr_[a-f0-9]{24}$/).describe("the delivery envelope's receipt"),
+    scope: ScopeSchema,
+    state_of_record: StateOfRecordSchema.nullable(),
+    /** Scopes the principal asked about but is not granted — named, never silently dropped. */
+    denied_scopes: z.array(ScopeSchema).max(64).default([]),
+}).strict();
+export const WriteRequestSchema = z.object({
+    schema: z.literal(STATE_WRITE_VERSION),
+    principal: PrincipalSchema,
+    scope: ScopeSchema,
+    facet: z.enum(STATE_FACETS),
+    record: z.record(z.string(), z.unknown()),
+    idempotency_key: z.string().min(8).max(256),
+    expected_version: z.union([z.string().max(256), z.number().int().nonnegative()]).nullable().default(null),
+    supersedes: z.string().max(2048).optional(),
+}).strict();
+export const DURABILITY = ["pushed", "committed", "local"];
+export const WriteResultSchema = z.object({
+    schema: z.literal(STATE_WRITE_VERSION),
+    record_id: z.string().min(1).max(2048),
+    record_hash: z.string().regex(SHA256),
+    durability: z.enum(DURABILITY),
+    outcome: z.enum(["created", "updated", "replayed", "superseded"]),
+    conflict: z.object({ incumbent_id: z.string().max(2048), reason: z.string().max(512) }).strict().nullable().default(null),
+}).strict();
+export const SubscribeRequestSchema = z.object({
+    schema: z.literal(STATE_SUBSCRIBE_VERSION),
+    principal: PrincipalSchema,
+    scope: ScopeSchema,
+    after_seq: z.number().int().nonnegative(),
+    subjects: z.array(z.string().max(512)).max(256).optional(),
+    facets: z.array(z.enum(STATE_FACETS)).max(STATE_FACETS.length).optional(),
+}).strict();
+export const ChangeEventSchema = z.object({
+    schema: z.literal(STATE_SUBSCRIBE_VERSION),
+    seq: z.number().int().positive(),
+    at: z.string().regex(ISO),
+    scope: ScopeSchema,
+    facet: z.enum(STATE_FACETS),
+    record_id: z.string().min(1).max(2048),
+    record_hash: z.string().regex(SHA256),
+    change: z.enum(["created", "updated", "superseded", "retired", "invalidated"]),
+    /** The record's subject (entity id / topic / external object key), so a subscriber can
+     *  filter by what it holds without reading every record. Optional: legacy facets may lack one. */
+    subject: z.string().max(512).optional(),
+    invalidates: z.array(z.string().max(512)).max(256).default([]),
+    cause: z.union([
+        z.object({ kind: z.literal("receipt"), receipt_id: z.string().regex(/^nrc_[a-f0-9]{24}$/) }).strict(),
+        z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict(),
+        z.object({ kind: z.literal("write"), principal: z.string().regex(TOKEN) }).strict(),
+    ]).optional(),
+}).strict();
+export const CapabilityNegotiationSchema = z.object({
+    protocol: z.literal(STATE_CONTRACT_VERSION),
+    capabilities: z.array(z.string().max(128)).max(64),
+}).strict();
+export function negotiate(offered, required = STATE_CAPABILITIES) {
+    const have = new Set(offered);
+    const supported = [];
+    const unsupported = [];
+    for (const cap of required)
+        (have.has(cap) ? supported : unsupported).push(cap);
+    return { supported, unsupported };
+}
+// ---- canonical form, hashes, ids -----------------------------------------------------------
+/** Canonical JSON: keys sorted by code unit at every level, `undefined` dropped, non-finite
+ *  numbers rejected. Two records with the same facts hash the same regardless of who wrote them. */
+export function canonicalize(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical form rejects non-finite numbers");
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort(compareCodeUnits)) {
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = canonicalize(v);
+        }
+        return out;
+    }
+    throw new Error(`canonical form rejects ${typeof value}`);
+}
+export function stateHash(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex")}`;
+}
+const idFrom = (prefix, seed) => `${prefix}_${createHash("sha256").update(JSON.stringify(canonicalize(seed))).digest("hex").slice(0, 24)}`;
+/** Identity = what makes two receipts the same action: who did what to which object, with which
+ *  request. Re-sending the same action replays the same receipt instead of minting a second one. */
+export function actionReceiptId(r) {
+    return idFrom("nrc", { scope: r.scope, actor: r.actor, action_kind: r.action_kind, target: { system: r.target.system, object_type: r.target.object_type, object_key: r.target.object_key }, request_fingerprint: r.request_fingerprint, idempotency_key: r.idempotency_key ?? null });
+}
+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) {
+    return idFrom("nds", { scope: d.scope, subject: d.subject, transform_version: d.transform_version, dependencies: d.dependencies.map((dep) => stateHash(dep)).sort(compareCodeUnits) });
+}
+// ---- invariants --------------------------------------------------------------------------
+export const STATE_INVARIANTS = [
+    { id: "authorization-before-retrieval", statement: "A record outside the principal's grants never enters a candidate set; filtering after ranking is a violation." },
+    { id: "similarity-never-authorizes", statement: "Semantic similarity may find candidates; only deterministic dependency, freshness and grant checks make a record current or visible." },
+    { id: "never-in-request-path", statement: "Nuryel is read and written by orchestrators; it never proxies, fetches or stores on an agent's behalf. A gate that checks state and refuses is allowed; an intermediary is not." },
+    { id: "provenance-on-every-write", statement: "Every write carries provenance and an idempotency key; a replay returns the original record, never a duplicate." },
+    { id: "one-live-decision-per-topic", statement: "A second live decision on a topic is refused with the incumbent named; supersession is explicit." },
+    { id: "external-truth-stays-external", statement: "External systems remain authoritative for their own content; Nuryel holds credential-free pointers, versions and hashes, never mirrored bodies." },
+    { id: "derived-state-carries-dependencies", statement: "A derived statement without dependencies cannot be invalidated and is therefore not state." },
+];
+const grantKey = (scope) => scopePath(scope);
+/** authorization-before-retrieval, checked on the way OUT as well: nothing in a read response
+ *  may sit outside the principal's grants. Bindings must also filter on the way in. */
+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] : [];
+    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`);
+    }
+    for (const denied of response.denied_scopes) {
+        if (granted.has(grantKey(denied)))
+            throw new Error(`denied scope ${grantKey(denied)} is actually granted — the response is inconsistent`);
+    }
+}
+/** provenance-on-every-write + scope agreement between the envelope and the record. */
+export function assertWriteWellFormed(request) {
+    // Authorization first — before the record is even looked at.
+    if (!request.principal.grants.some((g) => grantKey(g) === grantKey(request.scope)))
+        throw new Error("write scope is outside the principal's grants");
+    const record = request.record;
+    if (!record.provenance || typeof record.provenance !== "object")
+        throw new Error("write record lacks provenance");
+    // Only a PARTITION scope on the record is compared: legacy constraints carry path globs
+    // under the same key, and those are not a partition claim.
+    if (ScopeSchema.safeParse(record.scope).success && stateHash(record.scope) !== stateHash(request.scope))
+        throw new Error("write record scope disagrees with the request scope");
+}
+/** derived-state-carries-dependencies + content integrity. */
+export function assertDerivedState(d) {
+    if (d.dependencies.length === 0)
+        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");
+}
+/** Subscribe streams are strictly ordered per scope; a gap or regression means the caller must
+ *  resynchronize instead of trusting what it holds. */
+export function assertChangeSequence(events, afterSeq) {
+    let expected = afterSeq + 1;
+    for (const event of events) {
+        if (event.seq !== expected)
+            throw new Error(`change stream gap: expected seq ${expected}, got ${event.seq}`);
+        expected += 1;
+    }
+}
+/** A delivery envelope is the read receipt this contract reuses unchanged. */
+export function receiptOf(envelope) {
+    return envelope.receipt_id;
+}
+//# sourceMappingURL=stateContract.js.map

package/dist/core/stateRecords.js

@@ -0,0 +1,150 @@
+/**
+ * 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";
+import { ProvenanceSchema, isCredentialFreeValue } from "./provenance.js";
+export const RECEIPT_SCHEMA_VERSION = "nuryel.receipt/1";
+export const COMMITMENT_SCHEMA_VERSION = "nuryel.commitment/1";
+export const DERIVED_SCHEMA_VERSION = "nuryel.derived/1";
+export const ENTITY_SCHEMA_VERSION = "nuryel.entity/1";
+export const RELATIONSHIP_SCHEMA_VERSION = "nuryel.relationship/1";
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+// Explicit classes, no `i` flag: the pattern must survive zod → JSON schema for MCP output validation.
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const credentialFree = (label) => z.string().min(1).max(2048).refine(isCredentialFreeValue, { message: `${label} must not carry credential material` });
+// ---- scope ------------------------------------------------------------------------------
+/** organization › team › user › repository — partitions of ONE graph, not separate stores. */
+export const SCOPE_KINDS = ["organization", "team", "user", "repository"];
+export const ScopeSchema = z.object({
+    kind: z.enum(SCOPE_KINDS),
+    id: z.string().regex(TOKEN),
+}).strict();
+export const scopePath = (scope) => `${scope.kind}/${scope.id}`;
+// ---- provenance pointer into an external system --------------------------------------------
+/** "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 const ExternalRefSchema = z.object({
+    system: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+    object_type: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+    object_key: credentialFree("external object key").max(512),
+    version: credentialFree("external version").max(256).optional(),
+    content_hash: z.string().regex(SHA256).optional(),
+    observed_at: z.string().regex(ISO),
+    locator: credentialFree("external locator").optional(),
+}).strict();
+/** What a derived statement rests on. Exactly what a currentness check re-validates. */
+export const DependencyRefSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("record"), id: z.string().regex(TOKEN), record_hash: z.string().regex(SHA256) }).strict(),
+    z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict(),
+    z.object({ kind: z.literal("schema"), name: z.string().max(256), fingerprint: z.string().regex(SHA256) }).strict(),
+]);
+// ---- facets ------------------------------------------------------------------------------
+/** done — a side effect that happened. Never replayable as a read; idempotency is explicit. */
+export const ActionReceiptSchema = z.object({
+    schema: z.literal(RECEIPT_SCHEMA_VERSION),
+    id: z.string().regex(/^nrc_[a-f0-9]{24}$/),
+    scope: ScopeSchema,
+    actor: z.string().regex(TOKEN).describe("principal id"),
+    action_kind: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
+    target: ExternalRefSchema,
+    request_fingerprint: z.string().regex(SHA256),
+    idempotency_key: z.string().max(256).optional(),
+    state: z.enum(["requested", "succeeded", "failed", "unknown", "verified"]),
+    occurred_at: z.string().regex(ISO),
+    verified_at: z.string().regex(ISO).optional(),
+    result_fingerprint: z.string().regex(SHA256).optional(),
+    invalidates: z.array(z.string().max(512)).max(64).default([]),
+    provenance: ProvenanceSchema,
+}).strict();
+/** committed — an obligation with a due date and an in-force window. */
+export const CommitmentSchema = z.object({
+    schema: z.literal(COMMITMENT_SCHEMA_VERSION),
+    id: z.string().regex(/^ncm_[a-f0-9]{24}$/),
+    scope: ScopeSchema,
+    subject: z.string().max(512).describe("entity id or stable subject key"),
+    title: z.string().min(1).max(512),
+    owner: z.string().regex(TOKEN).describe("principal id"),
+    due: z.string().regex(DAY),
+    status: z.enum(["open", "waiting", "done", "cancelled"]),
+    source: ExternalRefSchema.optional(),
+    evidence_excerpt: z.string().max(900).optional(),
+    valid_from: z.string().regex(ISO),
+    valid_to: z.string().regex(ISO).nullable().default(null),
+    provenance: ProvenanceSchema,
+}).strict();
+/** 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 const DerivedStateSchema = z.object({
+    schema: z.literal(DERIVED_SCHEMA_VERSION),
+    id: z.string().regex(/^nds_[a-f0-9]{24}$/),
+    scope: ScopeSchema,
+    subject: z.string().max(512),
+    content: z.string().min(1).max(20_000),
+    content_hash: z.string().regex(SHA256),
+    dependencies: z.array(DependencyRefSchema).min(1).max(256),
+    transform_version: z.string().max(128),
+    computed_at: z.string().regex(ISO),
+    valid_to: z.string().regex(ISO).nullable().default(null),
+    state: z.enum(["current", "stale", "unknown"]),
+    provenance: ProvenanceSchema,
+}).strict();
+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
+ *  an index file, like resources, because kind-qualified ids are not safe file names. */
+export const ExternalEntitySchema = z.object({
+    schema: z.literal(ENTITY_SCHEMA_VERSION),
+    id: z.string().min(3).max(2048),
+    kind: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
+    name: credentialFree("entity name").max(256),
+    scope: ScopeSchema,
+    refs: z.array(ExternalRefSchema).min(1).max(64),
+    attributes: z.record(z.string().max(128), AttributeValue).default({}),
+    lifecycle: z.enum(["active", "deprecated", "retired"]).default("active"),
+    provenance: ProvenanceSchema,
+    created_at: z.string().regex(ISO),
+    updated_at: z.string().regex(ISO),
+}).strict().superRefine((entity, ctx) => {
+    const prefix = `${entity.kind}:`;
+    const key = entity.id.startsWith(prefix) ? entity.id.slice(prefix.length) : "";
+    if (!key.trim() || entity.id !== resourceId(entity.kind, key)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "entity id must be a canonical kind-qualified identity" });
+    }
+    if (Object.keys(entity.attributes).length > 64)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["attributes"], message: "attributes are a minimal projection, not a mirror" });
+});
+/** relationship — rides the same identity rule as the graph's edges. Index-file stored. */
+export const StateRelationshipSchema = z.object({
+    schema: z.literal(RELATIONSHIP_SCHEMA_VERSION),
+    id: z.string().regex(/^edge_[a-f0-9]+$/),
+    from: z.string().min(1).max(2048),
+    to: z.string().min(1).max(2048),
+    type: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
+    scope: ScopeSchema,
+    reason: z.string().max(1024).default(""),
+    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" });
+});
+/** DNA facet: existing Project DNA profiles, keyed by scope. No new schema — the reference only. */
+export const DnaFacetRefSchema = z.object({
+    schema: z.literal("hunch.project-dna/1"),
+    scope: ScopeSchema,
+    profile_id: z.string().regex(/^pdna_[a-f0-9]{24}$/),
+}).strict();
+export const entityId = resourceId;
+export const relationshipId = edgeId;
+//# sourceMappingURL=stateRecords.js.map

package/dist/core/types.js

@@ -8,14 +8,11 @@
 import { z } from "zod";
 import { createHash } from "node:crypto";
 import { findingId, resourceId, resourceRelationshipId } from "./ids.js";
-/** Where a fact came from and how much to trust it. Confidence tiers (DESIGN §4):
- *  inferred < extracted < llm_draft < llm_draft+human_confirmed/derived. */
-export const ProvenanceSchema = z.object({
-    source: z.string().describe("e.g. extracted | inferred | llm_draft | human_confirmed | test_failure+llm | derived"),
-    confidence: z.number().min(0).max(1),
-    evidence: z.array(z.string()).default([]).describe("file paths, commit ids, test ids backing the claim"),
-    last_verified: z.string().optional().describe("ISO timestamp of last re-validation"),
-});
+import { ProvenanceSchema, SENSITIVE_METADATA_KEY, isCredentialFreeText } from "./provenance.js";
+import { ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
+// Provenance and the credential-free text check live in the leaf module ./provenance.js so
+// record schemas registered below can import them without a cycle; re-exported unchanged.
+export { ProvenanceSchema, isCredentialFreeText };
 export const ComponentKind = z.enum(["service", "module", "layer", "external"]);
 /** Architecture node — a service / module / layer / external dependency. */
 export const ComponentSchema = z.object({
@@ -61,26 +58,6 @@ const MetadataValueSchema = z.union([
     z.null(),
     z.array(z.union([z.string().max(1024), z.number().finite(), z.boolean(), z.null()])).max(32),
 ]);
-const SENSITIVE_METADATA_KEY = /(^|[_-])(authorization|bearer|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)($|[_-])/i;
-const SENSITIVE_ASSIGNMENT = /\b(authorization|password|passwd|private[_-]?key|secret|access[_-]?token|refresh[_-]?token|api[_-]?key)\s*[:=]\s*[^\s,;]{4,}/i;
-const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/i;
-const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+\/-]{12,}/i;
-/** Reject credential material while allowing ordinary architecture prose such as
- * "authentication service" or "secrets are managed externally". */
-export function isCredentialFreeText(value) {
-    if (PRIVATE_KEY_BLOCK.test(value) || BEARER_VALUE.test(value) || SENSITIVE_ASSIGNMENT.test(value))
-        return false;
-    try {
-        const url = new URL(value);
-        if (url.username || url.password)
-            return false;
-        for (const [key] of url.searchParams)
-            if (SENSITIVE_METADATA_KEY.test(key))
-                return false;
-    }
-    catch { /* credential-free canonical locators need not be absolute URLs */ }
-    return true;
-}
 function isCanonicalResourceIdentity(value) {
     const separator = value.indexOf(":");
     if (separator <= 0 || separator === value.length - 1)
@@ -613,7 +590,12 @@ export function landscapeDriftCandidateFinding(value) {
     });
 }
 /** The entity collections, keyed by their on-disk directory name. */
-export const ENTITY_KINDS = ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings"];
+// nuryel.state/1 facets are ADDITIVE record kinds: a store without their directories
+// loads exactly as before, and an older build ignores directories it does not know.
+export const ENTITY_KINDS = [
+    "components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings",
+    "receipts", "commitments", "derived", "entities", "relationships",
+];
 export const SCHEMAS = {
     components: ComponentSchema,
     resources: ResourceSchema,
@@ -624,6 +606,11 @@ export const SCHEMAS = {
     constraints: ConstraintSchema,
     runbooks: RunbookSchema,
     findings: FindingSchema,
+    receipts: ActionReceiptSchema,
+    commitments: CommitmentSchema,
+    derived: DerivedStateSchema,
+    entities: ExternalEntitySchema,
+    relationships: StateRelationshipSchema,
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export function extracted(confidence, evidence = []) {

package/dist/integrations/claudemd.js

@@ -46,6 +46,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
+    lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");

package/dist/integrations/gitignore.js

@@ -54,6 +54,14 @@ const MEM_ENTRIES = [
     ".hunch/edges/",
     ".hunch/runbooks/",
     ".hunch/findings/",
+    // nuryel.state/1 record kinds (state facets)
+    ".hunch/receipts/",
+    ".hunch/commitments/",
+    ".hunch/derived/",
+    ".hunch/entities/",
+    ".hunch/relationships/",
+    // nuryel.state/1 per-scope change ledgers (subscribe stream + idempotency table)
+    ".hunch/changes/",
 ];
 function pathIsWithin(path, parent) {
     const rel = relative(parent, path);

package/dist/mcp/server.js

@@ -13,6 +13,8 @@ import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
+import { StateRefusal, SubscribeResponseSchema, capabilities, readState, subscribeState, writeState } from "../store/stateBinding.js";
+import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION } from "../core/stateContract.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
@@ -1672,6 +1674,79 @@ export function buildServerWithRootControl(initialRoot) {
             return err(`Failed to record finding: ${e.message}`);
         }
     });
+    // -- nuryel.state/1 — the ONE contract, bound over MCP -------------------------
+    // These four tools are a BINDING of src/store/stateBinding.ts, never a second
+    // implementation: every rule (grants first, provenance + idempotency, one live
+    // decision per topic, derived state carries dependencies, partition homing) lives
+    // there and is shared with every other transport. Client-agnostic (con_e04226bd05).
+    const stateRefusal = (e) => {
+        if (e instanceof StateRefusal) {
+            const conflict = e.conflict ? ` incumbent=${e.conflict.incumbent_id} (${e.conflict.reason})` : "";
+            return err(`nuryel.state/1 refused [${e.code}]: ${e.message}.${conflict}`);
+        }
+        if (e instanceof z.ZodError)
+            return err(`nuryel.state/1 malformed request: ${e.issues.map((i) => `${i.path.join(".") || "request"}: ${i.message}`).join("; ")}`);
+        return err(`nuryel.state/1 failed: ${e.message}`);
+    };
+    const stateResult = (text, structured) => ({ content: [{ type: "text", text }], structuredContent: structured });
+    server.registerTool("nuryel_capabilities", {
+        title: "nuryel.state/1 — what this state layer supports",
+        description: "Negotiate before depending on anything: returns the contract version, the capability list (verbs + record schemas), the repository partition this store serves, and which partition kinds it can hold. A capability you need that is missing here is a typed refusal on use, never a degraded answer.",
+        inputSchema: {},
+    }, async () => {
+        const caps = capabilities(store);
+        return stateResult(`${caps.protocol} · repository ${caps.repository.id} · partitions ${caps.partitions.join(", ")} · ${caps.capabilities.length} capabilities`, caps);
+    });
+    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.",
+        inputSchema: ReadRequestSchema.omit({ schema: true }).shape,
+        outputSchema: ReadResponseSchema.shape,
+    }, async (input) => {
+        try {
+            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}`
+                : "no subject — delivery envelope only";
+            const deniedNote = response.denied_scopes.length ? `\ndenied scopes: ${response.denied_scopes.map((s) => `${s.kind}/${s.id}`).join(", ")}` : "";
+            return stateResult(`${response.receipt_id} · ${summary}${deniedNote}\n\n${envelope.text}`, response);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
+    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.",
+        inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
+        outputSchema: WriteResultSchema.shape,
+    }, async ({ cwd: _cwd, ...input }) => {
+        try {
+            const result = writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
+                flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+            });
+            return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, 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.",
+        inputSchema: SubscribeRequestSchema.omit({ schema: true }).shape,
+        outputSchema: SubscribeResponseSchema.shape,
+    }, async (input) => {
+        try {
+            const response = subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, ...input });
+            const lines = response.events.map((e) => `${e.seq} ${e.at} ${e.change} ${e.facet}/${e.record_id}${e.invalidates.length ? ` invalidates ${e.invalidates.join(", ")}` : ""}`);
+            return stateResult(`${response.scope.kind}/${response.scope.id} head_seq ${response.head_seq} · ${response.events.length} event(s)${response.filtered ? " (filtered)" : ""}\n${lines.join("\n")}`, response);
+        }
+        catch (e) {
+            return stateRefusal(e);
+        }
+    });
     // -- hunch_findings (read: the open-observations ledger) --------------------
     server.registerTool("hunch_findings", {
         title: "Open findings for a scope",