@davesheffer/hunch 1.32.8 → 1.33.0

package/README.md

@@ -41,7 +41,9 @@ Hunch works with Claude Code, Codex, Cursor, VS Code/Copilot, Windsurf, Antigrav
 | Check the rules your team chose | Evaluates supported constraints and code relationships without a model in the blocking path. |
 | See what happened during a task | Separates delivered memory, the agent's reported use, rule results, and observed command results in a contribution report. |
 | Share project memory with teammates | Keeps repository memory in Git, with an optional dedicated private memory repository. |
-| Share work state across agents | Serves authorized records for decisions, actions, commitments, entities, and relationships through HTTP, MCP, and a typed client. |
+| Share work state across agents | Serves authorized records through HTTP, MCP, the state CLI, and typed TypeScript and Python clients. |
+| Inspect what the agents know | A read-only browser view shows current records, commitments, completed work and writer-supplied citations. |
+| Keep access and conventions explicit | Optional per-record audiences, key-bound credentials and sourced conventions use the same state contract. |
 
 For example, a team fixes a logout bug by keeping sessions on the server. Months later, an agent proposes removing that code. Hunch can surface the original reason and rejected alternative before the edit. A supported, trusted rule can flag the conflict; strict mode can block it. Recording the lesson and configuring the integration are what make this possible.
 
@@ -124,13 +126,17 @@ This shares a project's engineering memory. The state server below adds authenti
 
 A coding agent needs to know why a module exists. An operations agent may need to know whether a customer action was completed or who owes the next follow-up. Both need a maintained record they can check.
 
-Hunch already ships `hunch serve`: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. The same state contract is available through MCP and the `@davesheffer/hunch/state` client.
+Hunch ships `hunch serve`: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. Optional record audiences further restrict access; optional key-bound credentials require proof from the configured private key on each request.
+
+Open `/operator` on your server to inspect current records, completed work and commitments in a read-only browser view. Writer-supplied citations can point to an exact summary field or text passage and its recorded sources. They show traceability; they do not prove that a source supports a claim.
+
+Agents can use the same contract through MCP, `hunch state read|write|records|subscribe`, the `@davesheffer/hunch/state` TypeScript client, or the [Python client](docs/python-state-client.md). The Python package is built and tested from this repository; it is not yet published to PyPI. [Scoped conventions](docs/scoped-conventions.md) let a person record sourced user, team or organization preferences. Those preferences remain advisory and do not silently become blocking rules.
 
 Records can describe decisions, action outcomes, commitments, entities, relationships, and summaries that name their dependencies. Actions retain their status, including unknown or unverified outcomes. Repeated writes have stable identities, conflicting current decisions are refused, and confirmed human records receive protections against agent overwrites. These are defined checks on structured records; Hunch cannot establish every fact in the outside world on its own.
 
 This is what **deterministic state** means here: explicit rules govern the stored record, rather than having each agent reconstruct it from scratch. Git holds the durable data; SQLite is a rebuildable index. The server binds to loopback and requires deployment and agent integration by its operator. Hunch does not provide a managed CRM or email connector service.
 
-[Set up and understand the state server](docs/deterministic-state.md) · [State contract and client reference](docs/nuryel-state-contract.md)
+[Set up and understand the state server](docs/deterministic-state.md) · [State contract and client reference](docs/nuryel-state-contract.md) · [Upgrade to 1.33](docs/upgrade-1.33.md)
 
 ### The vision, and what is still being tested
 

package/dist/cli/index.js

@@ -26,6 +26,7 @@ import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
 import { registerTaskReportCommands } from "./taskReport.js";
+import { registerStateCommands } from "./state.js";
 import { registerServeCommands } from "./serve.js";
 import { registerUpdateCommand } from "./update.js";
 import { registerReviewMemoryCommands } from "./reviewMemory.js";
@@ -164,6 +165,7 @@ registerIntegrationCommands(program, () => {
 });
 registerTaskReportCommands(program, () => { const { store, root } = storeFor(); return { store, root }; });
 registerServeCommands(program);
+registerStateCommands(program);
 registerUpdateCommand(program);
 registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     const { store, root } = storeFor();

package/dist/cli/serve.js

@@ -1,6 +1,8 @@
+import { readFileSync, statSync } from 'node:fs';
+import { proofPublicKey } from '../core/stateProof.js';
 import { resolve } from "node:path";
 import { createServeApp } from "../serve/app.js";
-import { initServeConfig, partitionFor, readServeConfig } from "../serve/config.js";
+import { initServeConfig, partitionFor, readServeConfig, writeServeConfig } from "../serve/config.js";
 import { compactLedger } from "../store/changeLedger.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
@@ -32,11 +34,23 @@ export function registerServeCommands(program) {
         // reverse proxy that terminates TLS and auth of its own. Folded-in decision from Hunch Memory.
         app.listen(port, "127.0.0.1", () => {
             console.log(`hunch ${HUNCH_VERSION} serving nuryel.state/1 on http://127.0.0.1:${port} — ${config.partitions.map((p) => scopePath(p.scope)).join(", ")} (${config.principals.length} principal(s))`);
+            console.log(`Shared state view: http://127.0.0.1:${port}/operator`);
         });
         const stop = () => { app.close(() => { app.closeStores(); process.exit(0); }); };
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     });
+    serve.command("revoke")
+        .description("Revoke a principal credential; current servers reload the config before each request")
+        .requiredOption("--principal <id>", "principal whose credential to revoke")
+        .action((opts) => {
+        const { file, ...config } = readServeConfig(resolve(serve.opts().config ?? DEFAULT_CONFIG));
+        if (!config.principals.some(p => p.id === opts.principal))
+            throw new Error('principal is not configured');
+        config.principals = config.principals.filter(p => p.id !== opts.principal);
+        writeServeConfig(file, config);
+        console.log(JSON.stringify({ revoked: opts.principal }));
+    });
     serve.command("compact")
         .description("Compact a served partition's change ledger: keep the newest N events, move the floor up; subscribers below the floor resynchronize")
         .requiredOption("--partition <kind:id>", "the partition whose ledger to compact")
@@ -105,6 +119,8 @@ export function registerServeCommands(program) {
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
         .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")
+        .option("--proof-key-file <file>", "bind this token to an Ed25519 public PEM or JWK key")
+        .option("--public-origin <origin>", "external HTTPS origin of the reverse proxy; required for key-bound tokens")
         .option("--kind <kind>", "principal kind: human | agent | service", "agent")
         .option("--grant <kind:id...>", "additional partitions to grant the principal (must be served by this config)")
         .option("--port <n>", "port to record in a new config")
@@ -120,10 +136,20 @@ export function registerServeCommands(program) {
         const port = parent.port ?? opts.port;
         const scope = parseScopeArg(opts.partition);
         const grants = [scope, ...(opts.grant ?? []).map(parseScopeArg)];
+        let proofKey;
+        if (opts.proofKeyFile) {
+            if (!opts.principal)
+                throw new Error('--proof-key-file requires --principal');
+            const stat = statSync(opts.proofKeyFile);
+            if (!stat.isFile() || stat.size > 8192)
+                throw new Error('public proof key must be a regular file of at most 8 KiB');
+            proofKey = proofPublicKey(readFileSync(opts.proofKeyFile, 'utf8'));
+        }
         const result = initServeConfig({
             file: configFile, scope, root: resolve(opts.root),
-            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants } } : {}),
+            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants, proofKey } } : {}),
             ...(port ? { port: Number(port) } : {}),
+            ...(opts.publicOrigin ? { publicOrigin: opts.publicOrigin } : {}),
         });
         if (opts.json) {
             console.log(JSON.stringify({ config: configFile, partition: result.partition, token: result.token }));

package/dist/cli/state.d.ts

@@ -0,0 +1,3 @@
+/** JSON CLI over the existing HTTP client. The server owns authorization and state rules. */
+import type { Command } from 'commander';
+export declare function registerStateCommands(program: Command): void;

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/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;