@davesheffer/hunch 1.32.8 → 1.33.0

package/dist/core/stateHttp.d.ts

@@ -0,0 +1,280 @@
+/** HTTP-only response shapes. Verb and record schemas remain in stateContract. */
+import { z } from 'zod';
+export declare const HttpCapabilitiesSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"nuryel.state/1">;
+    capabilities: z.ZodArray<z.ZodString>;
+    repository: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    partitions: z.ZodArray<z.ZodEnum<{
+        repository: "repository";
+        organization: "organization";
+        team: "team";
+        user: "user";
+    }>>;
+    principal: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            service: "service";
+            human: "human";
+            agent: "agent";
+        }>;
+        grants: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const HttpHealthSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    version: z.ZodString;
+    protocol: z.ZodLiteral<"nuryel.state/1">;
+    partitions: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const HttpReadResponseSchema: 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<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    state_of_record: z.ZodNullable<z.ZodObject<{
+        subject: z.ZodString;
+        current: z.ZodArray<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>>;
+        in_force: z.ZodArray<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>>;
+        done: z.ZodArray<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>>;
+        observed: z.ZodOptional<z.ZodArray<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>>>;
+        observed_truncated: z.ZodOptional<z.ZodBoolean>;
+        observed_page: z.ZodOptional<z.ZodObject<{
+            snapshot_hash: z.ZodString;
+            total: z.ZodNumber;
+            next_cursor: z.ZodNullable<z.ZodObject<{
+                snapshot_hash: z.ZodString;
+                offset: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        relationships_truncated: z.ZodOptional<z.ZodBoolean>;
+        depends_on: 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">>;
+        invalidated_by: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    denied_scopes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>>;
+    records: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>>;
+    receipts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        receipt_id: z.ZodString;
+    }, z.core.$strict>>>;
+    envelope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const StateProblemSchema: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodNumber;
+    detail: z.ZodString;
+    conflict: z.ZodOptional<z.ZodObject<{
+        incumbent_id: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/core/stateHttp.js

@@ -0,0 +1,17 @@
+/** HTTP-only response shapes. Verb and record schemas remain in stateContract. */
+import { z } from 'zod';
+import { CapabilityNegotiationSchema, PrincipalSchema, ReadResponseSchema, ScopeSchema, STATE_CONTRACT_VERSION } from './stateContract.js';
+export const HttpCapabilitiesSchema = CapabilityNegotiationSchema.extend({
+    repository: ScopeSchema, partitions: z.array(ScopeSchema.shape.kind),
+    principal: PrincipalSchema.pick({ id: true, kind: true, grants: true }),
+}).strict();
+export const HttpHealthSchema = z.object({
+    ok: z.boolean(), version: z.string(), protocol: z.literal(STATE_CONTRACT_VERSION), partitions: z.array(z.string()),
+}).strict();
+// Delivery has its own richer assertion and receipt checks in delivery.ts.
+export const HttpReadResponseSchema = ReadResponseSchema.extend({ envelope: z.record(z.string(), z.unknown()) });
+export const StateProblemSchema = z.object({
+    type: z.string(), title: z.string(), status: z.number().int(), detail: z.string(),
+    conflict: z.object({ incumbent_id: z.string(), reason: z.string() }).optional(), issues: z.array(z.string()).optional(),
+});
+//# sourceMappingURL=stateHttp.js.map

package/dist/core/stateProof.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const STATE_PROOF_CAPABILITY = "nuryel.auth.dpop/1";
+export declare const ProofPublicKeySchema: z.ZodObject<{
+    kty: z.ZodLiteral<"OKP">;
+    crv: z.ZodLiteral<"Ed25519">;
+    x: z.ZodString;
+}, z.core.$strict>;
+export type ProofPublicKey = z.infer<typeof ProofPublicKeySchema>;
+export declare const PublicOriginSchema: z.ZodString;
+export declare const tokenProofHash: (value: string) => string;
+export declare function proofThumbprint(input: unknown): string;
+export declare function proofPublicKey(pem: string): ProofPublicKey;
+export declare function proofTarget(value: string): string;

package/dist/core/stateProof.js

@@ -0,0 +1,34 @@
+/** DPoP resource-server profile: RFC 9449, RFC 7638 and RFC 8037. Ed25519 only. */
+import { createHash, createPublicKey } from 'node:crypto';
+import { z } from 'zod';
+export const STATE_PROOF_CAPABILITY = 'nuryel.auth.dpop/1';
+export const ProofPublicKeySchema = z.object({ kty: z.literal('OKP'), crv: z.literal('Ed25519'), x: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict().superRefine((key, ctx) => {
+    if (Buffer.from(key.x, 'base64url').toString('base64url') !== key.x)
+        ctx.addIssue({ code: 'custom', message: 'public key encoding must be canonical base64url' });
+});
+export const PublicOriginSchema = z.string().url().refine(value => {
+    const url = new URL(value);
+    return url.protocol === 'https:' && url.origin === value && !url.username && !url.password;
+}, 'public_origin must be an HTTPS origin without a path, credentials, query or fragment');
+export const tokenProofHash = (value) => createHash('sha256').update(value, 'ascii').digest('base64url');
+export function proofThumbprint(input) {
+    const key = ProofPublicKeySchema.parse(input);
+    return createHash('sha256').update(JSON.stringify({ crv: key.crv, kty: key.kty, x: key.x })).digest('base64url');
+}
+export function proofPublicKey(pem) {
+    if (pem.trimStart().startsWith('{'))
+        return ProofPublicKeySchema.parse(JSON.parse(pem));
+    const key = createPublicKey(pem);
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('proof keys must use Ed25519');
+    return ProofPublicKeySchema.parse(key.export({ format: 'jwk' }));
+}
+export function proofTarget(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password)
+        throw new Error('key-bound requests require an HTTPS URL without credentials');
+    url.search = '';
+    url.hash = '';
+    return url.href;
+}
+//# sourceMappingURL=stateProof.js.map

package/dist/core/stateRecords.d.ts

@@ -87,6 +87,11 @@ export declare const DependencyRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 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<{
+    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.receipt/1">;
     id: z.ZodString;
     scope: z.ZodObject<{
@@ -161,6 +166,11 @@ export declare const ActionReceiptSchema: z.ZodObject<{
 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<{
+    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.commitment/1">;
     id: z.ZodString;
     scope: z.ZodObject<{
@@ -203,9 +213,37 @@ export declare const CommitmentSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strict>;
 export type Commitment = z.infer<typeof CommitmentSchema>;
+export declare const FieldSelectorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"json_pointer">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export type FieldSelector = z.infer<typeof FieldSelectorSchema>;
+/** Hash references stay attached to the same sources if dependencies are reordered. */
+export declare const FieldProvenanceSchema: z.ZodObject<{
+    selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"json_pointer">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    value_hash: z.ZodString;
+    dependency_hashes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type FieldProvenance = z.infer<typeof FieldProvenanceSchema>;
 /** 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<{
+    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.derived/1">;
     id: z.ZodString;
     scope: z.ZodObject<{
@@ -249,6 +287,18 @@ export declare const DerivedStateSchema: z.ZodObject<{
         name: z.ZodString;
         fingerprint: z.ZodString;
     }, z.core.$strict>], "kind">>;
+    field_provenance: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"json_pointer">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>], "kind">;
+        value_hash: z.ZodString;
+        dependency_hashes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
     transform_version: z.ZodString;
     computed_at: z.ZodString;
     valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -287,6 +337,11 @@ export type DerivedState = z.infer<typeof DerivedStateSchema>;
  *  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<{
+    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.entity/1">;
     id: z.ZodString;
     kind: z.ZodString;
@@ -328,6 +383,11 @@ export declare const ExternalEntitySchema: z.ZodObject<{
 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<{
+    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.relationship/1">;
     id: z.ZodString;
     from: z.ZodString;
@@ -381,3 +441,70 @@ export declare const DnaFacetRefSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const entityId: typeof resourceId;
 export declare const relationshipId: typeof edgeId;
+export declare const CONVENTION_SCHEMA_VERSION: "nuryel.convention/1";
+/** Explicit conventions are advisory records. Acceptance records human review, never policy authority. */
+export declare const ConventionSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"nuryel.convention/1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        kind: z.ZodEnum<{
+            repository: "repository";
+            organization: "organization";
+            team: "team";
+            user: "user";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    key: z.ZodString;
+    value: z.ZodString;
+    status: z.ZodEnum<{
+        stale: "stale";
+        proposed: "proposed";
+        accepted: "accepted";
+        withdrawn: "withdrawn";
+    }>;
+    sources: 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">>;
+    valid_from: z.ZodString;
+    valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    review_by: 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>;
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Convention = z.infer<typeof ConventionSchema>;

package/dist/core/stateRecords.js

@@ -1,3 +1,4 @@
+import { RecordVisibilitySchema } from "./recordVisibility.js";
 /**
  * nuryel.state/1 — the RECORD schemas (the facets that are new record kinds in the store).
  *
@@ -13,6 +14,7 @@
 import { z } from "zod";
 import { edgeId, resourceId } from "./ids.js";
 import { ProvenanceSchema, isCredentialFreeValue } from "./provenance.js";
+import { assertFieldProvenance } from "./fieldProvenance.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";
@@ -73,6 +75,7 @@ export const DependencyRefSchema = z.discriminatedUnion("kind", [
 // ---- facets ------------------------------------------------------------------------------
 /** done — a side effect that happened. Never replayable as a read; idempotency is explicit. */
 export const ActionReceiptSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(RECEIPT_SCHEMA_VERSION),
     id: z.string().regex(/^nrc_[a-f0-9]{24}$/),
     scope: ScopeSchema,
@@ -96,6 +99,7 @@ export const ActionReceiptSchema = z.object({
 }).strict();
 /** committed — an obligation with a due date and an in-force window. */
 export const CommitmentSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(COMMITMENT_SCHEMA_VERSION),
     id: z.string().regex(/^ncm_[a-f0-9]{24}$/),
     scope: ScopeSchema,
@@ -113,9 +117,20 @@ export const CommitmentSchema = z.object({
     valid_to: z.string().regex(ISO).nullable().default(null),
     provenance: ProvenanceSchema,
 }).strict();
+export const FieldSelectorSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("json_pointer"), path: z.string().max(2048).regex(/^(?:\/(?:[^~/]|~[01])*)*$/) }).strict(),
+    z.object({ kind: z.literal("text"), start: z.number().int().min(0).max(20_000), end: z.number().int().min(1).max(20_000) }).strict(),
+]);
+/** Hash references stay attached to the same sources if dependencies are reordered. */
+export const FieldProvenanceSchema = z.object({
+    selector: FieldSelectorSchema,
+    value_hash: z.string().regex(SHA256),
+    dependency_hashes: z.array(z.string().regex(SHA256)).min(1).max(256),
+}).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({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(DERIVED_SCHEMA_VERSION),
     id: z.string().regex(/^nds_[a-f0-9]{24}$/),
     scope: ScopeSchema,
@@ -123,6 +138,8 @@ export const DerivedStateSchema = z.object({
     content: z.string().min(1).max(20_000),
     content_hash: z.string().regex(SHA256),
     dependencies: z.array(DependencyRefSchema).min(1).max(256),
+    /** Optional exact field/text citations; absence means no field-level mapping is recorded. */
+    field_provenance: z.array(FieldProvenanceSchema).min(1).max(128).optional(),
     transform_version: z.string().max(128),
     computed_at: z.string().regex(ISO),
     valid_to: z.string().regex(ISO).nullable().default(null),
@@ -136,12 +153,19 @@ export const DerivedStateSchema = z.object({
 }).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' });
+    try {
+        assertFieldProvenance(record);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['field_provenance'], message: error.message });
+    }
 });
 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({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(ENTITY_SCHEMA_VERSION),
     id: z.string().min(3).max(2048),
     kind: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
@@ -176,6 +200,7 @@ export const ExternalEntitySchema = z.object({
 });
 /** relationship — rides the same identity rule as the graph's edges. Index-file stored. */
 export const StateRelationshipSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     schema: z.literal(RELATIONSHIP_SCHEMA_VERSION),
     id: z.string().regex(/^edge_[a-f0-9]+$/),
     from: z.string().min(1).max(2048),
@@ -203,4 +228,27 @@ export const DnaFacetRefSchema = z.object({
 }).strict();
 export const entityId = resourceId;
 export const relationshipId = edgeId;
+export const CONVENTION_SCHEMA_VERSION = "nuryel.convention/1";
+/** Explicit conventions are advisory records. Acceptance records human review, never policy authority. */
+export const ConventionSchema = z.object({
+    schema: z.literal(CONVENTION_SCHEMA_VERSION),
+    id: z.string().regex(/^ncv_[a-f0-9]{24}$/),
+    scope: ScopeSchema,
+    key: z.string().regex(/^[a-z][a-z0-9._-]{0,127}$/),
+    value: z.string().trim().min(1).max(1200),
+    status: z.enum(["proposed", "accepted", "stale", "withdrawn"]),
+    sources: z.array(DependencyRefSchema).min(1).max(8),
+    valid_from: z.string().regex(ISO),
+    valid_to: z.string().regex(ISO).nullable().default(null),
+    review_by: z.string().regex(ISO),
+    provenance: ProvenanceSchema,
+    visibility: RecordVisibilitySchema.optional(),
+}).strict().superRefine((record, ctx) => {
+    if (!Number.isFinite(Date.parse(record.valid_from)) || !Number.isFinite(Date.parse(record.review_by)) || Date.parse(record.review_by) <= Date.parse(record.valid_from))
+        ctx.addIssue({ code: 'custom', message: 'review_by must be a valid instant after valid_from' });
+    if (record.sources.some(source => source.kind === 'schema' || (source.kind === 'external' && !source.ref.version && !source.ref.content_hash)))
+        ctx.addIssue({ code: 'custom', path: ['sources'], message: 'conventions require exact record hashes or versioned/hashed external sources' });
+    if (record.status === 'accepted' && !record.provenance.source.split('+').includes('human_confirmed'))
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'accepted conventions require human-confirmed provenance' });
+});
 //# sourceMappingURL=stateRecords.js.map