@davesheffer/hunch 1.32.8 → 1.33.0

package/dist/core/fieldProvenance.js

@@ -0,0 +1,72 @@
+import { stateHash } from "./stateCanonical.js";
+/** Resolve exactly one scalar JSON field or one Unicode-code-point text range.
+ * No normalization, inherited properties, array aliases or substring guessing. */
+export function fieldCitationValue(content, selector) {
+    if (selector.kind === "text") {
+        const points = Array.from(content);
+        if (!Number.isInteger(selector.start) || !Number.isInteger(selector.end) || selector.start < 0 || selector.end <= selector.start || selector.end > points.length)
+            throw new Error("text citation range must be nonempty and within the content's Unicode code points");
+        return points.slice(selector.start, selector.end).join("");
+    }
+    if (!/^(?:\/(?:[^~/]|~[01])*)*$/.test(selector.path))
+        throw new Error("citation path must be an escaped JSON Pointer");
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw new Error("JSON field citations require JSON content");
+    }
+    for (const encoded of selector.path === "" ? [] : selector.path.slice(1).split("/")) {
+        const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (value === null || typeof value !== "object" || (Array.isArray(value) && !/^(0|[1-9][0-9]*)$/.test(key)) || !Object.hasOwn(value, key))
+            throw new Error(`citation path ${selector.path} does not name an existing field`);
+        value = value[key];
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
+        return value;
+    throw new Error("JSON field citations must name a scalar value, not an object or array");
+}
+/** This is structural traceability, not a check that a source supports a claim. */
+export function assertFieldProvenance(record) {
+    if (!record.field_provenance)
+        return;
+    const dependencies = new Set(record.dependencies.map(stateHash));
+    const selectors = new Set();
+    for (const [index, citation] of record.field_provenance.entries()) {
+        try {
+            const key = stateHash(citation.selector);
+            if (selectors.has(key))
+                throw new Error("duplicate citation selector; combine its dependency hashes in one entry");
+            selectors.add(key);
+            const value = fieldCitationValue(record.content, citation.selector);
+            if (stateHash(value) !== citation.value_hash)
+                throw new Error("citation value_hash does not match the selected content; rebuild the citation after editing");
+            if (new Set(citation.dependency_hashes).size !== citation.dependency_hashes.length)
+                throw new Error("duplicate citation dependency hash");
+            if (!citation.dependency_hashes.length || citation.dependency_hashes.some(hash => !dependencies.has(hash)))
+                throw new Error("every citation dependency_hash must name an existing summary dependency");
+        }
+        catch (error) {
+            throw new Error(`field_provenance[${index}]: ${error.message}`);
+        }
+    }
+}
+/** Bounded, plain-text source map for assistant clients; structured records remain complete. */
+export function fieldCitationText(record) {
+    if (!record.field_provenance?.length)
+        return "";
+    const dependencies = new Map(record.dependencies.map(dep => [stateHash(dep), dep]));
+    const source = (dep) => !dep ? "unavailable source" : dep.kind === "external"
+        ? `${dep.ref.system} ${dep.ref.object_type}:${dep.ref.object_key}` : dep.kind === "record"
+        ? `record ${dep.id}${dep.scope ? ` in ${dep.scope.kind}/${dep.scope.id}` : ""}` : `schema ${dep.name}`;
+    const lines = record.field_provenance.slice(0, 8).map(citation => {
+        const selector = citation.selector;
+        const target = selector.kind === "text" ? `text ${selector.start}–${selector.end} (Unicode code points)` : `field ${selector.path || "(root)"}`;
+        const value = JSON.stringify(fieldCitationValue(record.content, selector));
+        const sources = citation.dependency_hashes.slice(0, 4).map(hash => source(dependencies.get(hash)).slice(0, 200)).join("; ");
+        return `    ${target}: ${value.slice(0, 200)}${value.length > 200 ? "…" : ""} ← ${sources}${citation.dependency_hashes.length > 4 ? "; more sources in structured record" : ""}`;
+    });
+    return `\n    Writer-supplied field citations (traceability, not verified support or freshness):\n${lines.join("\n")}${record.field_provenance.length > 8 ? "\n    More citations in structured record." : ""}`;
+}
+//# sourceMappingURL=fieldProvenance.js.map

package/dist/core/recordVisibility.d.ts

@@ -0,0 +1,9 @@
+/** Inline policy stays bound to the record revision and its atomic JSON write. */
+import { z } from 'zod';
+export declare const RecordVisibilitySchema: z.ZodObject<{
+    owner: z.ZodString;
+    readers: z.ZodArray<z.ZodString>;
+    writers: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type RecordVisibility = z.infer<typeof RecordVisibilitySchema>;
+export declare function visibilityAllows(record: unknown, id: string, mode?: 'read' | 'write'): boolean;

package/dist/core/recordVisibility.js

@@ -0,0 +1,25 @@
+/** Inline policy stays bound to the record revision and its atomic JSON write. */
+import { z } from 'zod';
+const principalId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$/);
+export const RecordVisibilitySchema = z.object({
+    owner: principalId,
+    readers: z.array(principalId).max(256),
+    writers: z.array(principalId).max(256),
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.readers).size !== value.readers.length || new Set(value.writers).size !== value.writers.length)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'visibility lists must contain distinct principal IDs' });
+    if (value.writers.some(id => id !== value.owner && !value.readers.includes(id)))
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'every writer must also be a reader' });
+});
+export function visibilityAllows(record, id, mode = 'read') {
+    if (!record || typeof record !== 'object')
+        return false;
+    const raw = record.visibility;
+    if (raw === undefined)
+        return true;
+    const parsed = RecordVisibilitySchema.safeParse(raw);
+    if (!parsed.success)
+        return false;
+    return parsed.data.owner === id || (mode === 'read' ? parsed.data.readers : parsed.data.writers).includes(id);
+}
+//# sourceMappingURL=recordVisibility.js.map

package/dist/core/stateCanonical.d.ts

@@ -0,0 +1,3 @@
+/** Keep this encoding stable: existing record identities and dependency hashes use it. */
+export declare function canonicalize(value: unknown): unknown;
+export declare function stateHash(value: unknown): string;

package/dist/core/stateCanonical.js

@@ -0,0 +1,34 @@
+/** Shared canonical form for state identity, revisions and citation validation. */
+import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
+/** Keep this encoding stable: existing record identities and dependency hashes use it. */
+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)) {
+            // The historical encoding assigns into an ordinary object. This key would
+            // invoke its prototype setter and disappear from JSON. Refuse ambiguous
+            // input rather than silently collide or change existing valid identities.
+            if (key === "__proto__")
+                throw new Error("canonical form rejects reserved key __proto__");
+            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")}`;
+}
+//# sourceMappingURL=stateCanonical.js.map

package/dist/core/stateContract.d.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
+export { canonicalize, stateHash } from "./stateCanonical.js";
+export { fieldCitationValue, assertFieldProvenance } from "./fieldProvenance.js";
 import { type DeliveryEnvelope } from "./delivery.js";
-import { type Scope, type ActionReceipt, type Commitment, type DerivedState } from "./stateRecords.js";
+import { type Convention, type Scope, type ActionReceipt, type Commitment, type DerivedState } from "./stateRecords.js";
 export * from "./stateRecords.js";
 export declare const STATE_CONTRACT_VERSION: "nuryel.state/1";
 export declare const STATE_READ_VERSION: "nuryel.state.read/1";
@@ -12,9 +14,21 @@ export declare const STATE_CAPTURE_BATCH_VERSION: "nuryel.state.capture-batch/1"
 export declare const STATE_OBSERVATION_LINKS_VERSION: "nuryel.observation-links/1";
 export declare const STATE_OBSERVATION_REVIEW_VERSION: "nuryel.observation-review/1";
 export declare const STATE_OBSERVATION_PAGES_VERSION: "nuryel.observation-pages/1";
+export declare const STATE_RECORD_VISIBILITY_VERSION: "nuryel.record-visibility/1";
+export declare const PartitionDeclarationSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        repository: "repository";
+        organization: "organization";
+        team: "team";
+        user: "user";
+    }>;
+    id: z.ZodString;
+    required_capabilities: z.ZodOptional<z.ZodArray<z.ZodLiteral<"nuryel.record-visibility/1">>>;
+}, z.core.$strict>;
+export declare const STATE_FIELD_PROVENANCE_VERSION: "nuryel.field-provenance/1";
 /** Capabilities a server advertises; a client that needs one the server lacks gets a typed
  *  `unsupported`, never a compatible-looking degraded answer. */
-export declare const STATE_CAPABILITIES: readonly ["nuryel.state.read/1", "nuryel.state.write/1", "nuryel.state.subscribe/1", "nuryel.state.records/1", "nuryel.state.capture/1", "nuryel.state.capture-batch/1", "nuryel.observation-links/1", "nuryel.observation-review/1", "nuryel.observation-pages/1", "nuryel.receipt/1", "nuryel.commitment/1", "nuryel.derived/1", "nuryel.entity/1", "nuryel.relationship/1"];
+export declare const STATE_CAPABILITIES: readonly ["nuryel.state.read/1", "nuryel.state.write/1", "nuryel.state.subscribe/1", "nuryel.state.records/1", "nuryel.state.capture/1", "nuryel.state.capture-batch/1", "nuryel.observation-links/1", "nuryel.observation-review/1", "nuryel.observation-pages/1", "nuryel.field-provenance/1", "nuryel.record-visibility/1", "nuryel.convention/1", "nuryel.receipt/1", "nuryel.commitment/1", "nuryel.derived/1", "nuryel.entity/1", "nuryel.relationship/1"];
 export type StateCapability = (typeof STATE_CAPABILITIES)[number];
 /** Who is reading or writing. Grants are the scopes the principal may see; authorization is
  *  decided BEFORE retrieval against these, never after ranking. */
@@ -40,6 +54,11 @@ export type Principal = z.infer<typeof PrincipalSchema>;
 /** 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 declare const CaptureRequestSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     schema: z.ZodLiteral<"nuryel.state.capture/1">;
     principal: z.ZodObject<{
         id: z.ZodString;
@@ -148,6 +167,11 @@ export declare const CaptureBatchRequestSchema: z.ZodObject<{
             }>;
             reason: z.ZodString;
         }, z.core.$strict>;
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         subject: z.ZodString;
         statement: z.ZodString;
         evidence: z.ZodArray<z.ZodObject<{
@@ -172,7 +196,7 @@ export declare function captureTransform(scope: Scope, subject: string, statemen
     source: string;
     excerpt: string;
 }[]): string;
-export declare const STATE_FACETS: readonly ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
+export declare const STATE_FACETS: readonly ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 export type StateFacet = (typeof STATE_FACETS)[number];
 /** 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
@@ -246,6 +270,7 @@ export declare const ReadRequestSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>>>;
     observed_page: z.ZodOptional<z.ZodObject<{
         cursor: z.ZodOptional<z.ZodObject<{
@@ -266,6 +291,7 @@ declare const StateRefSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>;
     id: z.ZodString;
     record_hash: z.ZodString;
@@ -295,6 +321,7 @@ export declare const StateOfRecordSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         id: z.ZodString;
         record_hash: z.ZodString;
@@ -319,6 +346,7 @@ export declare const StateOfRecordSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         id: z.ZodString;
         record_hash: z.ZodString;
@@ -343,6 +371,7 @@ export declare const StateOfRecordSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         id: z.ZodString;
         record_hash: z.ZodString;
@@ -367,6 +396,7 @@ export declare const StateOfRecordSchema: z.ZodObject<{
             derived: "derived";
             entities: "entities";
             relationships: "relationships";
+            conventions: "conventions";
         }>;
         id: z.ZodString;
         record_hash: z.ZodString;
@@ -422,7 +452,82 @@ export declare const StateOfRecordSchema: z.ZodObject<{
     invalidated_by: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type StateOfRecord = z.infer<typeof StateOfRecordSchema>;
+export declare const ConventionDeliverySchema: z.ZodObject<{
+    advisory: z.ZodLiteral<true>;
+    items: z.ZodArray<z.ZodObject<{
+        ref: z.ZodObject<{
+            facet: z.ZodEnum<{
+                decisions: "decisions";
+                constraints: "constraints";
+                bugs: "bugs";
+                findings: "findings";
+                receipts: "receipts";
+                commitments: "commitments";
+                derived: "derived";
+                entities: "entities";
+                relationships: "relationships";
+                conventions: "conventions";
+            }>;
+            id: z.ZodString;
+            record_hash: z.ZodString;
+            scope: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    repository: "repository";
+                    organization: "organization";
+                    team: "team";
+                    user: "user";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        key: z.ZodString;
+        conflict: z.ZodBoolean;
+        currentness: z.ZodEnum<{
+            stale: "stale";
+            recorded: "recorded";
+        }>;
+    }, z.core.$strict>>;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+export type ConventionDelivery = z.infer<typeof ConventionDeliverySchema>;
 export declare const ReadResponseSchema: z.ZodObject<{
+    conventions: z.ZodOptional<z.ZodObject<{
+        advisory: z.ZodLiteral<true>;
+        items: z.ZodArray<z.ZodObject<{
+            ref: z.ZodObject<{
+                facet: z.ZodEnum<{
+                    decisions: "decisions";
+                    constraints: "constraints";
+                    bugs: "bugs";
+                    findings: "findings";
+                    receipts: "receipts";
+                    commitments: "commitments";
+                    derived: "derived";
+                    entities: "entities";
+                    relationships: "relationships";
+                    conventions: "conventions";
+                }>;
+                id: z.ZodString;
+                record_hash: z.ZodString;
+                scope: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        repository: "repository";
+                        organization: "organization";
+                        team: "team";
+                        user: "user";
+                    }>;
+                    id: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+            key: z.ZodString;
+            conflict: z.ZodBoolean;
+            currentness: z.ZodEnum<{
+                stale: "stale";
+                recorded: "recorded";
+            }>;
+        }, z.core.$strict>>;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>>;
     schema: z.ZodLiteral<"nuryel.state.read/1">;
     receipt_id: z.ZodString;
     scope: z.ZodObject<{
@@ -447,6 +552,7 @@ export declare const ReadResponseSchema: z.ZodObject<{
                 derived: "derived";
                 entities: "entities";
                 relationships: "relationships";
+                conventions: "conventions";
             }>;
             id: z.ZodString;
             record_hash: z.ZodString;
@@ -471,6 +577,7 @@ export declare const ReadResponseSchema: z.ZodObject<{
                 derived: "derived";
                 entities: "entities";
                 relationships: "relationships";
+                conventions: "conventions";
             }>;
             id: z.ZodString;
             record_hash: z.ZodString;
@@ -495,6 +602,7 @@ export declare const ReadResponseSchema: z.ZodObject<{
                 derived: "derived";
                 entities: "entities";
                 relationships: "relationships";
+                conventions: "conventions";
             }>;
             id: z.ZodString;
             record_hash: z.ZodString;
@@ -519,6 +627,7 @@ export declare const ReadResponseSchema: z.ZodObject<{
                 derived: "derived";
                 entities: "entities";
                 relationships: "relationships";
+                conventions: "conventions";
             }>;
             id: z.ZodString;
             record_hash: z.ZodString;
@@ -645,6 +754,7 @@ export declare const WriteRequestSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>;
     record: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     idempotency_key: z.ZodString;
@@ -792,10 +902,16 @@ export declare const SubscribeRequestSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>>>;
 }, z.core.$strict>;
 export type SubscribeRequest = z.infer<typeof SubscribeRequestSchema>;
 export declare const ChangeEventSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     schema: z.ZodLiteral<"nuryel.state.subscribe/1">;
     seq: z.ZodNumber;
     at: z.ZodString;
@@ -818,6 +934,7 @@ export declare const ChangeEventSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>;
     record_id: z.ZodString;
     record_hash: z.ZodString;
@@ -907,6 +1024,7 @@ export declare const RecordsResponseSchema: z.ZodObject<{
         derived: "derived";
         entities: "entities";
         relationships: "relationships";
+        conventions: "conventions";
     }>>;
     missing: z.ZodDefault<z.ZodArray<z.ZodString>>;
     denied: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -920,16 +1038,13 @@ export declare function negotiate(offered: readonly string[], required?: readonl
     supported: string[];
     unsupported: string[];
 };
-/** 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 declare function canonicalize(value: unknown): unknown;
-export declare function stateHash(value: unknown): string;
 /** 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 declare function actionReceiptId(r: Pick<ActionReceipt, "scope" | "actor" | "action_kind" | "target" | "request_fingerprint"> & {
     idempotency_key?: string;
 }): string;
 export declare function commitmentId(c: Pick<Commitment, "scope" | "subject" | "title" | "owner" | "due">): string;
+export declare function conventionId(c: Pick<Convention, "scope" | "key" | "value" | "sources">): string;
 export declare function derivedId(d: Pick<DerivedState, "scope" | "subject" | "transform_version" | "dependencies">): string;
 export declare const STATE_INVARIANTS: readonly [{
     readonly id: "authorization-before-retrieval";

package/dist/core/stateContract.js

@@ -1,3 +1,4 @@
+import { RecordVisibilitySchema } from "./recordVisibility.js";
 /**
  * nuryel.state/1 — the ONE contract every orchestrator and agent speaks to the state layer.
  *
@@ -27,9 +28,13 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { compareCodeUnits } from "./canonicalOrder.js";
+import { canonicalize, stateHash } from "./stateCanonical.js";
+import { assertFieldProvenance } from "./fieldProvenance.js";
+export { canonicalize, stateHash } from "./stateCanonical.js";
+export { fieldCitationValue, assertFieldProvenance } from "./fieldProvenance.js";
 import { DELIVERY_PROFILES } from "./delivery.js";
 import { isHumanConfirmed as sourceIsHumanConfirmed } from "./strictgate.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";
+import { ScopeSchema, scopePath, externalKey, DependencyRefSchema, ExternalRefSchema, CONVENTION_SCHEMA_VERSION, 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";
@@ -41,11 +46,14 @@ 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";
+export const STATE_RECORD_VISIBILITY_VERSION = "nuryel.record-visibility/1";
+export const PartitionDeclarationSchema = ScopeSchema.extend({ required_capabilities: z.array(z.literal(STATE_RECORD_VISIBILITY_VERSION)).min(1).max(1).optional() }).strict();
+export const STATE_FIELD_PROVENANCE_VERSION = "nuryel.field-provenance/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_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,
+    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, STATE_FIELD_PROVENANCE_VERSION, STATE_RECORD_VISIBILITY_VERSION,
+    CONVENTION_SCHEMA_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.
@@ -63,6 +71,7 @@ export const PrincipalSchema = z.object({
 /** 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({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(STATE_CAPTURE_VERSION),
     principal: PrincipalSchema,
     scope: ScopeSchema,
@@ -82,7 +91,7 @@ export const CaptureRequestSchema = z.object({
 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({
+    observations: z.array(CaptureRequestSchema.pick({ subject: true, statement: true, relevance: true, visibility: 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({
@@ -97,7 +106,7 @@ 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"];
+export const STATE_FACETS = ["decisions", "constraints", "bugs", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 // ---- 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
@@ -140,7 +149,13 @@ export const StateOfRecordSchema = z.object({
     depends_on: z.array(DependencyRefSchema).max(1024),
     invalidated_by: z.array(z.string().max(512)).max(256),
 }).strict();
+export const ConventionDeliverySchema = z.object({
+    advisory: z.literal(true),
+    items: z.array(z.object({ ref: StateRefSchema, key: z.string(), conflict: z.boolean(), currentness: z.enum(["recorded", "stale"]) }).strict()).max(16),
+    truncated: z.boolean(),
+}).strict();
 export const ReadResponseSchema = z.object({
+    conventions: ConventionDeliverySchema.optional(),
     schema: z.literal(STATE_READ_VERSION),
     receipt_id: z.string().regex(/^hdr_[a-f0-9]{24}$/).describe("the delivery envelope's receipt"),
     scope: ScopeSchema,
@@ -203,6 +218,7 @@ export const SubscribeRequestSchema = z.object({
     facets: z.array(z.enum(STATE_FACETS)).max(STATE_FACETS.length).optional(),
 }).strict();
 export const ChangeEventSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(STATE_SUBSCRIBE_VERSION),
     seq: z.number().int().positive(),
     at: z.string().regex(ISO),
@@ -251,32 +267,6 @@ export function negotiate(offered, required = STATE_CAPABILITIES) {
     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. */
@@ -286,6 +276,9 @@ export function actionReceiptId(r) {
 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 conventionId(c) {
+    return idFrom("ncv", { scope: c.scope, key: c.key, value: c.value.trim(), sources: c.sources.map(stateHash).sort(compareCodeUnits) });
+}
 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.
@@ -322,6 +315,7 @@ export function assertReadWithinGrants(principal, response) {
     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, ...(response.state_of_record.observed ?? [])] : [];
+    refs.push(...(response.conventions?.items.map(item => item.ref) ?? []));
     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`);
@@ -358,6 +352,7 @@ 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");
+    assertFieldProvenance(d);
     if (d.transform_version.startsWith(CAPTURE_TRANSFORM)) {
         const content = z.object({
             schema: z.literal("nuryel.observation-content/1"),

package/dist/core/stateDelivery.d.ts

@@ -15,12 +15,12 @@
  * 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 { Convention, 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 declare const STATE_KINDS: readonly ["receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 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 type StateRecord = Convention | 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;

package/dist/core/stateDelivery.js

@@ -1,10 +1,11 @@
-export const STATE_KINDS = ["receipts", "commitments", "derived", "entities", "relationships"];
+export const STATE_KINDS = ["receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 const STATE_KIND_SET = new Set(STATE_KINDS);
 export function isStateKind(kind) {
     return STATE_KIND_SET.has(kind);
 }
 /** Singular facet label used in renders: `[commitment/in_force]`, `[derived/current]`. */
 const FACET_LABEL = {
+    conventions: "convention",
     receipts: "receipt",
     commitments: "commitment",
     derived: "derived",
@@ -16,6 +17,10 @@ const FACET_LABEL = {
  *  receipt succeeded/verified; entity active; a relationship is always current). */
 export function stateLiveness(kind, record) {
     switch (kind) {
+        case "conventions": {
+            const c = record;
+            return { label: c.valid_to != null ? 'superseded' : c.status, live: c.status === 'accepted' && c.valid_to === null && Date.parse(c.review_by) > Date.now() };
+        }
         case "derived": {
             const d = record;
             if (d.valid_to != null)
@@ -45,6 +50,7 @@ export function stateLiveness(kind, record) {
  *  object (`event:10042`), the entity id, or the relationship's `from` endpoint. */
 export function stateSubject(kind, record) {
     switch (kind) {
+        case "conventions": return record.key;
         case "derived": return record.subject;
         case "commitments": return record.subject;
         case "receipts": {
@@ -59,6 +65,7 @@ export function stateSubject(kind, record) {
  *  updated_at. Relationships carry no clock and sort last among equals. */
 export function stateObservedAt(kind, record) {
     switch (kind) {
+        case "conventions": return record.valid_from;
         case "derived": return record.computed_at;
         case "commitments": return record.valid_from;
         case "receipts": {
@@ -77,6 +84,7 @@ export function stateSearchDoc(kind, record) {
     const { label } = stateLiveness(kind, record);
     const subject = stateSubject(kind, record);
     switch (kind) {
+        case "conventions": return { title: subject, body: `${record.value} ${label} advisory convention` };
         case "derived": {
             const d = record;
             return { title: subject, body: `${d.content} ${label} ${d.transform_version} ${d.computed_at.slice(0, 10)}` };
@@ -116,6 +124,7 @@ export function renderStateLine(kind, record) {
     const { label } = stateLiveness(kind, record);
     const head = `[${FACET_LABEL[kind]}/${label}] ${stateSubject(kind, record)} — `;
     switch (kind) {
+        case "conventions": return `${head}${oneLine(record.value, 120)} (advisory)`;
         case "derived":
             return `${head}${oneLine(record.content, DERIVED_HEADLINE_CHARS)}`;
         case "commitments": {