@davesheffer/hunch 1.32.8 → 1.35.0

package/dist/cli/update.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findRoot } from "../core/paths.js";
-const PACKAGE = "@davesheffer/hunch";
+import { HUNCH_PACKAGE_NAME } from "../core/version.js";
 /** Arguments come only from fixed commands and a validated registry version.
  * Windows needs the shell to resolve npm.cmd; cwd is never interpolated. */
 export function runNpm(root, args, capture = false) {
@@ -26,24 +26,24 @@ export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(roo
     const manifest = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         throw new Error("package.json must contain an object");
-    if (manifest.name === PACKAGE)
+    if (manifest.name === HUNCH_PACKAGE_NAME)
         throw new Error("Run hunch update in a consumer repository, not Hunch's own source checkout.");
     const sections = ["dependencies", "devDependencies", "optionalDependencies"];
     const declared = sections.filter(section => {
         const deps = manifest[section];
         if (deps !== undefined && (!deps || typeof deps !== "object" || Array.isArray(deps)))
             throw new Error(`invalid ${section} in package.json`);
-        return deps && Object.hasOwn(deps, PACKAGE);
+        return deps && Object.hasOwn(deps, HUNCH_PACKAGE_NAME);
     });
     if (declared.length > 1)
         throw new Error("Hunch is declared in multiple dependency sections; resolve the duplicate before updating.");
     if (declared.length && (manifest.workspaces || (manifest.packageManager && !/^npm@/.test(manifest.packageManager)) || ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].some(name => existsSync(join(root, name))))) {
         throw new Error("Automatic dependency updates currently support standalone npm projects. Update Hunch to an exact version with your package manager, then run hunch integrations repair-pins.");
     }
-    const version = JSON.parse(run(["view", `${PACKAGE}@latest`, "version", "--json"], true));
+    const version = JSON.parse(run(["view", `${HUNCH_PACKAGE_NAME}@latest`, "version", "--json"], true));
     if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
         throw new Error("npm returned an invalid Hunch version");
-    const spec = `${PACKAGE}@${version}`;
+    const spec = `${HUNCH_PACKAGE_NAME}@${version}`;
     const commands = [];
     if (declared.length) {
         const flag = { dependencies: "--save-prod", devDependencies: "--save-dev", optionalDependencies: "--save-optional" }[declared[0]];

package/dist/client/state.d.ts

@@ -3,21 +3,16 @@
  * Import from `@davesheffer/hunch/state`. The principal is the bearer token's; the request
  * shapes are the contract's minus `schema` and `principal`.
  */
-import type { ReadRequest, SubscribeRequest, WriteRequest, ChangeEvent, Scope } from "../core/stateContract.js";
+import type { ReadRequest, SubscribeRequest, WriteRequest, Scope } from "../core/stateContract.js";
 import type { DeliveryEnvelope } from "../core/delivery.js";
 import type { CaptureRequest, CaptureBatchRequest } from "../core/stateContract.js";
+import type { SubscribeResponse } from '../store/stateBinding.js';
 export type ClientReadRequest = Omit<ReadRequest, "schema" | "principal">;
 export type ClientWriteRequest = Omit<WriteRequest, "schema" | "principal" | "expected_version"> & {
     expected_version?: string | number | null;
 };
 export type ClientSubscribeRequest = Omit<SubscribeRequest, "schema" | "principal">;
-export interface ClientSubscribeResponse {
-    schema: string;
-    scope: Scope;
-    head_seq: number;
-    events: ChangeEvent[];
-    filtered: boolean;
-}
+export type ClientSubscribeResponse = SubscribeResponse;
 export interface StateProblem {
     type: string;
     title: string;
@@ -36,7 +31,14 @@ export declare class StateClientError extends Error {
     readonly problem: StateProblem;
     constructor(status: number, code: string, problem: StateProblem);
 }
+export interface StateProofRequest {
+    method: string;
+    url: string;
+    token: string;
+    nonce?: string;
+}
 export interface StateClientOptions {
+    proof?: (request: StateProofRequest) => Promise<string>;
     baseUrl: string;
     token: string;
     fetch?: typeof fetch;
@@ -64,7 +66,7 @@ export declare function createStateClient(opts: StateClientOptions): {
         state_of_record: {
             subject: string;
             current: {
-                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships";
+                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
                 id: string;
                 record_hash: string;
                 scope: {
@@ -73,7 +75,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 };
             }[];
             in_force: {
-                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships";
+                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
                 id: string;
                 record_hash: string;
                 scope: {
@@ -82,7 +84,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 };
             }[];
             done: {
-                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships";
+                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
                 id: string;
                 record_hash: string;
                 scope: {
@@ -116,7 +118,7 @@ export declare function createStateClient(opts: StateClientOptions): {
             })[];
             invalidated_by: string[];
             observed?: {
-                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships";
+                facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
                 id: string;
                 record_hash: string;
                 scope: {
@@ -139,6 +141,24 @@ export declare function createStateClient(opts: StateClientOptions): {
             kind: "repository" | "organization" | "team" | "user";
             id: string;
         }[];
+        conventions?: {
+            advisory: true;
+            items: {
+                ref: {
+                    facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
+                    id: string;
+                    record_hash: string;
+                    scope: {
+                        kind: "repository" | "organization" | "team" | "user";
+                        id: string;
+                    };
+                };
+                key: string;
+                conflict: boolean;
+                currentness: "stale" | "recorded";
+            }[];
+            truncated: boolean;
+        } | undefined;
         records?: Record<string, Record<string, unknown>> | undefined;
         scopes?: {
             kind: "repository" | "organization" | "team" | "user";
@@ -158,7 +178,7 @@ export declare function createStateClient(opts: StateClientOptions): {
         schema: "nuryel.state.write/1";
         record_id: string;
         record_hash: string;
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
         outcome: "updated" | "superseded" | "created" | "replayed";
         conflict: {
             incumbent_id: string;
@@ -170,7 +190,7 @@ export declare function createStateClient(opts: StateClientOptions): {
         schema: "nuryel.state.write/1";
         record_id: string;
         record_hash: string;
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
         outcome: "updated" | "superseded" | "created" | "replayed";
         conflict: {
             incumbent_id: string;
@@ -187,7 +207,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 schema: "nuryel.state.write/1";
                 record_id: string;
                 record_hash: string;
-                durability: "committed" | "pushed" | "local";
+                durability: "local" | "committed" | "pushed";
                 outcome: "updated" | "superseded" | "created" | "replayed";
                 conflict: {
                     incumbent_id: string;
@@ -208,7 +228,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 schema: "nuryel.state.write/1";
                 record_id: string;
                 record_hash: string;
-                durability: "committed" | "pushed" | "local";
+                durability: "local" | "committed" | "pushed";
                 outcome: "updated" | "superseded" | "created" | "replayed";
                 conflict: {
                     incumbent_id: string;
@@ -223,7 +243,55 @@ export declare function createStateClient(opts: StateClientOptions): {
             message: string;
         })[] | undefined;
     }>;
-    subscribe: (request: ClientSubscribeRequest) => Promise<ClientSubscribeResponse>;
+    subscribe: (request: ClientSubscribeRequest) => Promise<{
+        schema: "nuryel.state.subscribe/1";
+        scope: {
+            kind: "repository" | "organization" | "team" | "user";
+            id: string;
+        };
+        head_seq: number;
+        events: {
+            schema: "nuryel.state.subscribe/1";
+            seq: number;
+            at: string;
+            scope: {
+                kind: "repository" | "organization" | "team" | "user";
+                id: string;
+            };
+            facet: "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions";
+            record_id: string;
+            record_hash: string;
+            change: "updated" | "retired" | "superseded" | "created" | "invalidated";
+            invalidates: string[];
+            visibility?: {
+                owner: string;
+                readers: string[];
+                writers: string[];
+            } | undefined;
+            subject?: string | undefined;
+            cause?: {
+                kind: "receipt";
+                receipt_id: string;
+            } | {
+                kind: "external";
+                ref: {
+                    system: string;
+                    object_type: string;
+                    object_key: string;
+                    observed_at: string;
+                    version?: string | undefined;
+                    content_hash?: string | undefined;
+                    locator?: string | undefined;
+                };
+            } | {
+                kind: "write";
+                principal: string;
+            } | undefined;
+        }[];
+        filtered: boolean;
+        floor_seq: number;
+        resync: boolean;
+    }>;
     records: (request: {
         scope: Scope;
         ids: string[];
@@ -234,7 +302,7 @@ export declare function createStateClient(opts: StateClientOptions): {
             id: string;
         };
         records: Record<string, Record<string, unknown>>;
-        facets: Record<string, "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships">;
+        facets: Record<string, "decisions" | "constraints" | "bugs" | "findings" | "receipts" | "commitments" | "derived" | "entities" | "relationships" | "conventions">;
         missing: string[];
         denied: string[];
     }>;

package/dist/client/state.js

@@ -15,16 +15,30 @@ export function createStateClient(opts) {
     const base = opts.baseUrl.replace(/\/+$/, "");
     const doFetch = opts.fetch ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 15_000;
+    let nonce;
     async function call(method, path, body) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            const response = await doFetch(`${base}${path}`, {
+            const url = `${base}${path}`;
+            const request = async () => doFetch(url, {
                 method,
-                headers: { authorization: `Bearer ${opts.token}`, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+                headers: { authorization: `${opts.proof ? 'DPoP' : 'Bearer'} ${opts.token}`, ...(opts.proof ? { dpop: await opts.proof({ method, url, token: opts.token, nonce }) } : {}), ...(body !== undefined ? { "content-type": "application/json" } : {}) },
                 body: body !== undefined ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
+                redirect: "error",
             });
+            let response = await request();
+            // This one retry is an authentication challenge before any operation runs.
+            // Idempotency/conflict/network failures never trigger automatic write retries.
+            if (opts.proof && response.status === 401 && response.headers.has('dpop-nonce')) {
+                const challenge = await response.clone().json().catch(() => null);
+                if (challenge?.title === 'use_dpop_nonce') {
+                    nonce = response.headers.get('dpop-nonce');
+                    await response.arrayBuffer();
+                    response = await request();
+                }
+            }
             const text = await response.text();
             const parsed = text ? JSON.parse(text) : {};
             if (!response.ok) {

package/dist/client/stateProof.d.ts

@@ -0,0 +1,4 @@
+/** Optional Node signer. The fetch-only client stays usable in other runtimes. */
+import { type KeyObject } from 'node:crypto';
+import type { StateProofRequest } from './state.js';
+export declare function createStateProofSigner(input: string | KeyObject): (request: StateProofRequest) => Promise<string>;

package/dist/client/stateProof.js

@@ -0,0 +1,17 @@
+/** Optional Node signer. The fetch-only client stays usable in other runtimes. */
+import { createPrivateKey, createPublicKey, randomUUID, sign } from 'node:crypto';
+import { ProofPublicKeySchema, proofTarget, tokenProofHash } from '../core/stateProof.js';
+export function createStateProofSigner(input) {
+    const key = typeof input === 'string' ? (input.trimStart().startsWith('{') ? createPrivateKey({ key: JSON.parse(input), format: 'jwk' }) : createPrivateKey(input)) : input;
+    if (key.type !== 'private' || key.asymmetricKeyType !== 'ed25519')
+        throw new Error('proof signing requires an Ed25519 private key');
+    const jwk = ProofPublicKeySchema.parse(createPublicKey(key).export({ format: 'jwk' }));
+    const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+    const header = encode({ typ: 'dpop+jwt', alg: 'EdDSA', jwk });
+    return async ({ method, url, token, nonce }) => {
+        const claims = encode({ jti: randomUUID(), htm: method, htu: proofTarget(url), iat: Math.floor(Date.now() / 1000), ath: tokenProofHash(token), ...(nonce ? { nonce } : {}) });
+        const message = `${header}.${claims}`;
+        return `${message}.${sign(null, Buffer.from(message), key).toString('base64url')}`;
+    };
+}
+//# sourceMappingURL=stateProof.js.map

package/dist/constitution/behaviorEvaluator.js

@@ -132,7 +132,7 @@ export function evaluateExecutableBehaviorPolicy(root, policy, opts = {}) {
         if (!existsSync(join(root, ".hunch-cache", "behavior-deps"))) {
             return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-cache-absent" }, "error", "no dependency snapshot cache exists on this machine (.hunch-cache/behavior-deps); executable behavior is unevaluated here, not failed — provision the policy's snapshots (hunch constitution g2 --behavior-deps <candidate> --behavior-review-hash <hash>) or evaluate where they were built");
         }
-        return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-unavailable" }, "error", `no unique exact dependency snapshot matches this commit's package.json/package-lock.json among the policy's pinned ids (${assertion.dependency_snapshot_ids.join(", ")}); dependency inputs changed since compilation — re-plan and re-prove the policy (rb_g2_stale_policy_01)`);
+        return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-unavailable" }, "error", `no unique exact dependency snapshot matches this commit's package.json/package-lock.json among the policy's pinned ids (${assertion.dependency_snapshot_ids.join(", ")}); restore and validate the exact pinned cache first. If dependency inputs changed, prepare a replacement behavior candidate and replay; human selection, activation and retirement remain required. Re-proving an active policy does not refresh its pins (docs/behavior-policy-recovery.md)`);
     }
     const session = mkdtempSync(join(tmpdir(), "hunch-behavior-policy-"));
     const hooks = join(session, "hooks-disabled");

package/dist/constitution/schema.d.ts

@@ -370,13 +370,13 @@ export declare const PolicyStateSchema: z.ZodEnum<{
     proposed: "proposed";
     rejected: "rejected";
     superseded: "superseded";
+    repaired: "repaired";
+    active_advisory: "active_advisory";
+    active_blocking: "active_blocking";
     compiled: "compiled";
+    validating: "validating";
     uncompilable: "uncompilable";
     drafted: "drafted";
-    validating: "validating";
-    active_advisory: "active_advisory";
-    active_blocking: "active_blocking";
-    repaired: "repaired";
 }>;
 export type PolicyState = z.infer<typeof PolicyStateSchema>;
 export declare const PolicySelectorSchema: z.ZodObject<{
@@ -468,16 +468,16 @@ export type PolicyAssertion = z.infer<typeof PolicyAssertionSchema>;
 export declare const PolicyAuditEventSchema: z.ZodObject<{
     action: z.ZodEnum<{
         retired: "retired";
+        withdrawn: "withdrawn";
         rejected: "rejected";
-        compiled: "compiled";
         repaired: "repaired";
+        compiled: "compiled";
         enriched: "enriched";
         linked_exception: "linked_exception";
         proved: "proved";
         approved_advisory: "approved_advisory";
         approved_blocking: "approved_blocking";
         demoted: "demoted";
-        withdrawn: "withdrawn";
     }>;
     actor_kind: z.ZodEnum<{
         system: "system";
@@ -518,13 +518,13 @@ export declare const PolicySpecSchema: z.ZodObject<{
         proposed: "proposed";
         rejected: "rejected";
         superseded: "superseded";
+        repaired: "repaired";
+        active_advisory: "active_advisory";
+        active_blocking: "active_blocking";
         compiled: "compiled";
+        validating: "validating";
         uncompilable: "uncompilable";
         drafted: "drafted";
-        validating: "validating";
-        active_advisory: "active_advisory";
-        active_blocking: "active_blocking";
-        repaired: "repaired";
     }>;
     statement: z.ZodString;
     rationale: z.ZodDefault<z.ZodString>;
@@ -610,10 +610,10 @@ export declare const PolicySpecSchema: z.ZodObject<{
     }>>;
     surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         ci: "ci";
-        pre_edit: "pre_edit";
-        pre_commit: "pre_commit";
         mcp: "mcp";
         cli: "cli";
+        pre_edit: "pre_edit";
+        pre_commit: "pre_commit";
     }>>>;
     authority: z.ZodDefault<z.ZodNullable<z.ZodObject<{
         kind: z.ZodLiteral<"human">;
@@ -661,16 +661,16 @@ export declare const PolicySpecSchema: z.ZodObject<{
     audit: z.ZodDefault<z.ZodArray<z.ZodObject<{
         action: z.ZodEnum<{
             retired: "retired";
+            withdrawn: "withdrawn";
             rejected: "rejected";
-            compiled: "compiled";
             repaired: "repaired";
+            compiled: "compiled";
             enriched: "enriched";
             linked_exception: "linked_exception";
             proved: "proved";
             approved_advisory: "approved_advisory";
             approved_blocking: "approved_blocking";
             demoted: "demoted";
-            withdrawn: "withdrawn";
         }>;
         actor_kind: z.ZodEnum<{
             system: "system";

package/dist/core/automaticReviewMemory.d.ts

@@ -55,6 +55,11 @@ export declare function automateReviewMemory(options: {
             evidence: string[];
             last_verified?: string | undefined;
         };
+        visibility?: {
+            owner: string;
+            readers: string[];
+            writers: string[];
+        } | undefined;
         valid_from?: string | undefined;
     }[];
 }>;

package/dist/core/conventionDelivery.d.ts

@@ -0,0 +1,8 @@
+/** Explicit conventions alongside repository DNA. No scope wins and no policy is activated. */
+import type { Convention, Scope } from './stateRecords.js';
+import { type ConventionDelivery } from './stateContract.js';
+import type { DeliverySupplement } from './delivery.js';
+export declare function conventionCurrentness(record: Convention, resolve?: (id: string, scope: Scope) => unknown, now?: number): 'recorded' | 'stale';
+export declare function conventionDelivery(records: readonly Convention[], resolve?: (id: string, scope: Scope) => unknown, verified?: ReadonlyMap<string, "recorded" | "stale">): ConventionDelivery | undefined;
+/** The regular brief uses its existing token budget and keeps Project DNA's separate identity. */
+export declare function conventionSupplements(records: readonly Convention[], resolve?: (id: string, scope: Scope) => unknown): DeliverySupplement[];

package/dist/core/conventionDelivery.js

@@ -0,0 +1,52 @@
+import { scopePath, stateHash } from './stateContract.js';
+import { compareCodeUnits } from './canonicalOrder.js';
+export function conventionCurrentness(record, resolve, now = Date.now()) {
+    if (record.status === 'stale' || record.status === 'withdrawn' || record.valid_to !== null || Date.parse(record.valid_from) > now || Date.parse(record.review_by) <= now)
+        return 'stale';
+    for (const source of record.sources)
+        if (source.kind === 'record') {
+            const held = resolve?.(source.id, source.scope ?? record.scope);
+            if (!held || stateHash(held) !== source.record_hash || held.valid_to != null || held.state === 'stale' || held.status === 'stale' || held.status === 'withdrawn')
+                return 'stale';
+        }
+    return 'recorded';
+}
+export function conventionDelivery(records, resolve, verified) {
+    const currentness = (record) => verified?.get(record.id) ?? conventionCurrentness(record, resolve);
+    const candidates = [...new Map(records.map(r => [r.id, r])).values()].filter(r => r.valid_to === null && r.status !== 'withdrawn').sort((a, b) => compareCodeUnits(a.key, b.key) || compareCodeUnits(scopePath(a.scope), scopePath(b.scope)) || compareCodeUnits(a.id, b.id));
+    if (!candidates.length)
+        return undefined;
+    const values = new Map();
+    for (const record of candidates)
+        if (currentness(record) !== 'stale') {
+            const set = values.get(record.key) ?? new Set();
+            set.add(record.value);
+            values.set(record.key, set);
+        }
+    let bytes = 0;
+    const selected = [];
+    for (const record of candidates) {
+        const size = Buffer.byteLength(JSON.stringify(record));
+        if (selected.length >= 16 || bytes + size > 16_384)
+            break;
+        selected.push(record);
+        bytes += size;
+    }
+    return { advisory: true, items: selected.map(record => ({ ref: { facet: 'conventions', id: record.id, record_hash: stateHash(record), scope: record.scope }, key: record.key,
+            currentness: currentness(record), conflict: (values.get(record.key)?.size ?? 0) > 1 })), truncated: selected.length < candidates.length };
+}
+/** The regular brief uses its existing token budget and keeps Project DNA's separate identity. */
+export function conventionSupplements(records, resolve) {
+    const delivery = conventionDelivery(records, resolve);
+    if (!delivery)
+        return [];
+    const byId = new Map(records.map(r => [r.id, r]));
+    return [{ id: 'explicit-conventions', kind: 'conventions', priority: 424,
+            text: `EXPLICIT CONVENTIONS — advisory; scope is context, never precedence or policy authority. Resolve conflicting values before acting.${delivery.truncated || delivery.items.length > 8 ? ' Delivery is incomplete; more records exist.' : ''}` },
+        ...delivery.items.slice(0, 8).map((item, i) => {
+            const record = byId.get(item.ref.id);
+            return { id: record.id, kind: 'convention', priority: 423 - i,
+                text: `${scopePath(record.scope)} · ${record.key} · ${record.status}/${item.currentness}${item.conflict ? ' · CONFLICT' : ''}: ${record.value.slice(0, 300)} (revision ${item.ref.record_hash}; sources ${record.sources.length}; review by ${record.review_by})` };
+        })];
+}
+//# sourceMappingURL=conventionDelivery.js.map

package/dist/core/fieldProvenance.d.ts

@@ -0,0 +1,8 @@
+import type { DerivedState, FieldSelector } from "./stateRecords.js";
+/** Resolve exactly one scalar JSON field or one Unicode-code-point text range.
+ * No normalization, inherited properties, array aliases or substring guessing. */
+export declare function fieldCitationValue(content: string, selector: FieldSelector): string | number | boolean | null;
+/** This is structural traceability, not a check that a source supports a claim. */
+export declare function assertFieldProvenance(record: Pick<DerivedState, "content" | "dependencies" | "field_provenance">): void;
+/** Bounded, plain-text source map for assistant clients; structured records remain complete. */
+export declare function fieldCitationText(record: DerivedState): string;

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