@davesheffer/hunch 1.32.7 → 1.33.0

package/dist/cli/state.js

@@ -0,0 +1,150 @@
+import { createStateProofSigner } from '../client/stateProof.js';
+import { readFileSync, statSync } from 'node:fs';
+import { z } from 'zod';
+import { createStateClient, StateClientError } from '../client/state.js';
+import { ReadRequestSchema, WriteRequestSchema, SubscribeRequestSchema, RecordsRequestSchema, ScopeSchema, STATE_FIELD_PROVENANCE_VERSION, STATE_RECORD_VISIBILITY_VERSION } from '../core/stateContract.js';
+const MAX_INPUT_BYTES = 1024 * 1024;
+function scopeFrom(value) {
+    const match = /^([a-z]+):(.+)$/.exec(value ?? '');
+    if (!match)
+        throw new Error('pass --scope kind:id, or supply scope in --input JSON');
+    return ScopeSchema.parse({ kind: match[1], id: match[2] });
+}
+async function inputObject(file) {
+    let text;
+    if (file !== '-') {
+        const stat = statSync(file);
+        if (!stat.isFile() || stat.size > MAX_INPUT_BYTES)
+            throw new Error('input must be a regular JSON file of at most 1 MiB');
+        text = readFileSync(file, 'utf8');
+    }
+    else {
+        if (process.stdin.isTTY)
+            throw new Error('pipe a JSON request or pass --input <file>');
+        const chunks = [];
+        let length = 0;
+        for await (const chunk of process.stdin) {
+            const bytes = Buffer.from(chunk);
+            length += bytes.length;
+            if (length > MAX_INPUT_BYTES)
+                throw new Error('input exceeds 1 MiB');
+            chunks.push(bytes);
+        }
+        text = Buffer.concat(chunks).toString('utf8');
+    }
+    if (Buffer.byteLength(text) > MAX_INPUT_BYTES)
+        throw new Error('input exceeds 1 MiB');
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error('input must be valid JSON');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('input must be a JSON request object');
+    return value;
+}
+function connection(options) {
+    const timeoutMs = Number(options.timeout);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+        throw new Error('--timeout must be 1..300000 milliseconds');
+    const url = new URL(options.url);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('--url must be an HTTP(S) base URL without credentials, query or fragment');
+    let token = process.env.HUNCH_STATE_TOKEN?.trim();
+    if (options.tokenFile) {
+        const stat = statSync(options.tokenFile);
+        if (!stat.isFile() || stat.size > 8192)
+            throw new Error('token file must be a regular file of at most 8 KiB');
+        token = readFileSync(options.tokenFile, 'utf8').trim();
+    }
+    if (!token)
+        throw new Error('set HUNCH_STATE_TOKEN or pass --token-file; tokens are not accepted as command arguments');
+    let proof;
+    if (options.proofKeyFile) {
+        const stat = statSync(options.proofKeyFile);
+        if (!stat.isFile() || stat.size > 8192)
+            throw new Error('proof key must be a regular private-key file of at most 8 KiB');
+        proof = createStateProofSigner(readFileSync(options.proofKeyFile, 'utf8'));
+    }
+    return createStateClient({ baseUrl: options.url, token, timeoutMs, proof });
+}
+export function registerStateCommands(program) {
+    const state = program.command('state').description('Read and write a served workspace using the state contract; JSON output')
+        .option('--url <url>', 'server base URL (or HUNCH_STATE_URL)', process.env.HUNCH_STATE_URL || 'http://127.0.0.1:7474')
+        .option('--token-file <file>', 'read a bearer token from a file; otherwise use HUNCH_STATE_TOKEN')
+        .option('--proof-key-file <file>', 'Ed25519 private PEM or JWK file for a key-bound token')
+        .option('--timeout <ms>', 'timeout for each HTTP request', '15000')
+        .option('--pretty', 'indent JSON output');
+    const run = (work) => async () => {
+        try {
+            const options = state.opts(), result = await work(connection(options));
+            process.stdout.write(JSON.stringify(result, null, options.pretty ? 2 : undefined) + '\n');
+        }
+        catch (error) {
+            const problem = error instanceof StateClientError ? error.problem : {
+                type: 'about:blank', title: error instanceof z.ZodError ? 'malformed' : 'client-error', status: 0,
+                detail: error instanceof z.ZodError ? error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ') : error instanceof Error ? error.message : 'state request failed',
+            };
+            process.stderr.write(JSON.stringify(problem) + '\n');
+            process.exitCode = 1;
+        }
+    };
+    state.command('capabilities').description('Show the authenticated principal and supported contract capabilities')
+        .option('--scope <kind:id>', 'partition to negotiate; defaults to the token’s first grant')
+        .action((options) => run(client => client.capabilities(options.scope ? scopeFrom(options.scope) : undefined))());
+    for (const verb of ['read', 'write', 'records', 'subscribe']) {
+        const command = state.command(verb).description(verb === 'subscribe' ? 'Poll changes once; use head_seq as the next after_seq and honor resync' : `${verb} using the authenticated state contract`)
+            .option('--input <file>', 'complete request JSON; - reads stdin (default for write)');
+        if (verb !== 'write')
+            command.option('--scope <kind:id>', 'partition when using shortcut options');
+        if (verb === 'read')
+            command.option('--subject <subject>', 'exact subject or record key').option('--task <text>', 'task phrase for memory delivery');
+        if (verb === 'records')
+            command.option('--ids <id...>', 'exact record IDs');
+        if (verb === 'subscribe')
+            command.option('--after <seq>', 'last observed sequence; defaults to zero');
+        command.action((options) => run(async (client) => {
+            const shortcut = options.scope || options.subject || options.task || options.ids || options.after;
+            if (options.input && shortcut)
+                throw new Error('use either --input JSON or shortcut options, not both');
+            const raw = options.input || verb === 'write' ? await inputObject(options.input ?? '-') : {
+                scope: scopeFrom(options.scope),
+                ...(options.subject !== undefined ? { subject: options.subject } : {}),
+                ...(options.task !== undefined ? { task: options.task } : {}),
+                ...(verb === 'records' ? { ids: options.ids } : {}),
+                ...(verb === 'subscribe' ? { after_seq: Number(options.after ?? 0) } : {}),
+            };
+            const schemas = {
+                read: ReadRequestSchema.omit({ schema: true, principal: true }),
+                write: WriteRequestSchema.omit({ schema: true, principal: true }),
+                records: RecordsRequestSchema.omit({ schema: true, principal: true }),
+                subscribe: SubscribeRequestSchema.omit({ schema: true, principal: true }),
+            };
+            const request = schemas[verb].parse(raw);
+            const caps = await client.capabilities(request.scope);
+            const required = [`nuryel.state.${verb}/1`];
+            if ('record' in request) {
+                if (request.record.field_provenance !== undefined)
+                    required.push(STATE_FIELD_PROVENANCE_VERSION);
+                if (request.record.visibility !== undefined)
+                    required.push(STATE_RECORD_VISIBILITY_VERSION);
+                if (typeof request.record.schema === 'string')
+                    required.push(request.record.schema);
+            }
+            const missing = required.filter(capability => !caps.capabilities.includes(capability));
+            if (missing.length)
+                throw new StateClientError(400, 'unsupported', { type: 'about:blank', title: 'unsupported', status: 400, detail: 'server lacks required capabilities: ' + missing.join(', ') });
+            // The chosen request schema matches the verb; state semantics remain server-owned.
+            if (verb === 'read')
+                return client.read(request);
+            if (verb === 'write')
+                return client.write(request);
+            if (verb === 'records')
+                return client.records(request);
+            return client.subscribe(request);
+        })());
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/cli/update.js

@@ -59,8 +59,12 @@ export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(roo
         if (!opts.dryRun)
             run(args);
     }
-    if (!opts.dryRun)
-        log("Hunch updated; repository integration check passed. Restart or reconnect active harnesses to load the new MCP version.");
+    if (!opts.dryRun) {
+        log("Hunch updated; repository configuration check passed. Restart or reconnect active harnesses to load the new MCP version. Runtime hook delivery is not verified by this check.");
+        if (existsSync(join(root, ".codex", "hooks.json"))) {
+            log("Codex: open /hooks to review and trust any changed commands, then start a new session. Command changes require renewed trust; Hunch does not grant it automatically.");
+        }
+    }
 }
 export function registerUpdateCommand(program) {
     program.command("update")

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";
@@ -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

@@ -468,6 +468,7 @@ 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";
@@ -477,7 +478,6 @@ export declare const PolicyAuditEventSchema: z.ZodObject<{
         approved_advisory: "approved_advisory";
         approved_blocking: "approved_blocking";
         demoted: "demoted";
-        withdrawn: "withdrawn";
     }>;
     actor_kind: z.ZodEnum<{
         system: "system";
@@ -661,6 +661,7 @@ 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";
@@ -670,7 +671,6 @@ export declare const PolicySpecSchema: z.ZodObject<{
             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;