verdifax 1.1.0 → 1.2.0

package/README.md

@@ -18,6 +18,8 @@ Requires Node 22 or newer.
 
 ## Quickstart
 
+On a trial key, register a request key first and give the client that key: see [Request signing](#request-signing). Without it, a trial key refuses the run.
+
 ```typescript
 import { VerdifaxClient } from "verdifax";
 
@@ -82,6 +84,12 @@ if (v.verified) {
 | `client.registerRequestKey()` | `POST /keys/request-key` | required |
 | `client.rotateRequestKey(newSigningKey)` | `POST /keys/request-key` | required |
 | `client.clearRequestKey()` | `DELETE /keys/request-key` | required |
+| `client.uploadPolicy(document)` | `POST /policies` | required |
+| `client.listPolicies()` | `GET /policies` | required |
+| `client.getPolicy(documentHash)` | `GET /policies/{document_hash}` | required |
+| `client.testPolicy({ inputs, document?, documentHash? })` | `POST /policies/test` | required |
+| `client.getPolicyHistory()` | `GET /policies/history` | required |
+| `client.activatePolicy(documentHash)` | `POST /policies/{document_hash}/activate` | required |
 | `client.adminCreateKey(name)` | `POST /admin/keys` | admin |
 | `client.adminListKeys()` | `GET /admin/keys` | admin |
 | `client.adminRevokeKey(id)` | `DELETE /admin/keys/{id}` | admin |
@@ -90,7 +98,7 @@ if (v.verified) {
 
 `client.job(jobId)` returns a [job helper](#jobs) and makes no request until a step runs.
 
-These functions make no request: `captureEnvironment`, `formatProviderPayload`, `signRequest`, `signRequestV2`, `requestKeyRegistrationBody`, `requestKeyChangeApproval`, `requestKeyChangePreimage`, `requestSignaturePreimage`, `requestSignaturePreimageV2`, `generateRequestKeyPair`, `validateHex64`, `validateJobName`, `validateRouteId`, `dseDispatchHash`, `dcaeClosureHash` and `cresReceiptHash`. `RUN_STATUSES` lists every run status the server uses.
+These functions make no request: `captureEnvironment`, `formatProviderPayload`, `signRequest`, `signRequestV2`, `requestKeyRegistrationBody`, `requestKeyChangeApproval`, `requestKeyChangePreimage`, `policyActivationApproval`, `policyActivationPreimage`, `requestSignaturePreimage`, `requestSignaturePreimageV2`, `generateRequestKeyPair`, `validateHex64`, `validateJobName`, `validateRouteId`, `dseDispatchHash`, `dcaeClosureHash` and `cresReceiptHash`. `RUN_STATUSES` lists every run status the server uses, and `EXECUTE_FIELDS` lists every top-level key a run request may hold.
 
 `getRunArtifacts`, `getPublicBundle` and `getPublicBundleByToken` return the exact JSON text the server sent, so you can save it and check it with `verdifax-verify`.
 
@@ -168,6 +176,62 @@ The server refuses a step in a closed job, a repeated step id, and a final step
 
 A job map covers what was sent. It cannot show a step that was never sent.
 
+## Policies
+
+A policy is your own set of rules that decides whether a run is allowed or refused, from the facts the run declares. You upload its exact text, test it on sample inputs, then activate it. Each change is one more link in a chain of changes on the public log.
+
+```typescript
+import { readFileSync, writeFileSync } from "node:fs";
+
+// Upload the exact text. Nothing changes until it is activated.
+const stored = await client.uploadPolicy(readFileSync("policy.json", "utf8"));
+
+// See which rule would fire on sample inputs. This seals nothing.
+const trial = await client.testPolicy({
+  documentHash: stored.document_hash,
+  inputs: { subject_type: "agent", verb: "approve-loan", object_type: "transaction", classification: "CONFIDENTIAL" },
+});
+console.log(trial.outcome, trial.fired_rule_id, trial.reason_code);
+
+// Make it the policy in force. With a signingKey the request key signs the change.
+const change = await client.activatePolicy(stored.document_hash);
+
+// A run declares the facts the rules read, and can name the policy it expects.
+await client.attest({
+  program_id,
+  route_id,
+  registry_record_hash,
+  payload_text: "approve loan 1042",
+  attested_context: { actor_id: "agent:loan-bot" },
+  policy_context: {
+    actor_type: "agent",
+    mfa_satisfied: true,
+    object_type: "transaction",
+    object_id: "loan-1042",
+    classification: "CONFIDENTIAL",
+  },
+  expected_policy_hash: change.policy_hash,
+});
+
+// Roll back by activating an earlier document.
+await client.activatePolicy(earlierDocumentHash);
+
+// Save the chain of changes and check it with verdifax-verify --policy-history policy-history.json.
+writeFileSync("policy-history.json", JSON.stringify(await client.getPolicyHistory()));
+```
+
+`uploadPolicy` sends the string it is given unchanged, because the server hashes the exact text, and it refuses anything that is not a string. `getPolicy` returns a stored document with its exact text. `testPolicy` takes exactly one of `document` and `documentHash`. `listPolicies` returns the documents, `chain_id`, the newest change as `newest_activation_hash` (64 zeros when there is none yet) and the document in force as `active_document_hash` (empty under the built-in policy).
+
+`activatePolicy` reads `listPolicies` first and names the newest change as the one it follows. With the `signingKey` option it sends the request key's signature over the chain, the document and that change, which the server requires while a request key is registered. Rolling back is activating an earlier document: it is one more change, so the change it undoes stays on the record. An HTTP 409 means another change came first or the document is not yet effective. It throws the usual `APIError` and is not retried. `getPolicyHistory` returns the changes oldest first, in the form `verdifax-verify --policy-history FILE` reads.
+
+`execute`, `attest`, each row of `executeBatch`, `verifyDeterminism`, `job.step` and the provider helpers take `policy_context` and `expected_policy_hash`. `policy_context` holds only `actor_type` (`agent`, `user`, `service` or `system`), `mfa_satisfied` (true or false), `session_age_seconds` (a whole number, not negative), `object_type` (`text`, `transaction`, `code`, `data`, `model` or `file`), `object_id` (at most 256 bytes) and `classification` (`PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `RESTRICTED`, `TOP_SECRET` or `TS_SCI`). Any other key or value is refused before sending, because a misspelt key would be dropped and a rule on it would read its zero value. `actor_type`, `mfa_satisfied` and `session_age_seconds` describe the attested actor, so a run that sets one of them must also send `attested_context` with the actor, such as its `actor_id`. `expected_policy_hash` is 64 lowercase hex characters: when another policy is active the server refuses the run with HTTP 409. Both fields are inside `signed_request` on a signed client.
+
+Verdifax did not write, review or approve your policy. A pass means the rules ran, not that they are good rules.
+
+A policy judges what you declared. It cannot show the declared facts are true.
+
+A refusal stops the action only if your system waits for the answer.
+
 ## Evidence export
 
 `exportRuns` lists the runs the server holds for your key in a period, failures included, with up to 10,000 rows per export. `exportRunsCSV` returns the same rows as raw CSV text.
@@ -211,6 +275,8 @@ Both helpers take the same optional `job` block as `attest` and return `record_h
 
 `execute`, `attest`, `executeBatch` and `verifyDeterminism` accept `attested_context`, `reproducibility_context`, `request_substance`, `authorization_chain`, `regulatory_scaffolding` and `causal_graph`. Each is recorded as supplied and Verdifax does not check it. The client derives `attested` and `declared` from the fields you provide. Leave out `request_substance.origin.source_ip_hash` and `user_agent_hash`: the server computes them. `execute`, `attest` and `verifyDeterminism` refuse them before sending, and a batch row that sets them fails in `results`.
 
+The server ignores a key it does not know, so a misspelt field would be dropped with no error. The client refuses it instead, before sending: a run request for `execute`, `attest`, `verifyDeterminism`, `job.step` or a row of `executeBatch` with a top-level key outside `EXECUTE_FIELDS`, or an `attested_context` key outside `attested`, `actor_id`, `actor_role`, `authorization_policy`, `actor_signature`, `model_provider`, `model_name`, `model_version`, `model_temperature`, `prompt_hash`, `decision_kind`, `decision_result` and `decision_note`, throws a `VerdifaxError` naming the key. `attest` also refuses `request_signature` and `signed_request`, which it does not send. `attestClaudeResponse` and `attestOpenAIResponse` accept their own argument names and every name in `EXECUTE_FIELDS`, so a run request spread into the arguments keeps working, and refuse any other key the same way. Responses are not checked this way: a field a newer server adds is kept and does not throw.
+
 `execute`, `attest` and `verifyDeterminism` check that `program_id` and `registry_record_hash` are 64 lowercase hex characters and that `route_id` is 1 to 256 printable ASCII characters.
 
 ## Environment capture
@@ -260,7 +326,7 @@ try {
 
 ## Request signing
 
-Request signing is optional. A client with no signing key sends the same requests as before.
+A trial key, which is what a pilot receives, needs a request key: it seals nothing until one is registered, and the key can then be replaced but not cleared. On a production key, request signing is optional, and a client with no signing key sends the same requests as before.
 
 You can register an Ed25519 public key on your API key, so that each run must also be signed with a private key that only you hold. The key pair is created on your machine, and Verdifax receives only the public key.
 

package/dist/index.d.mts

@@ -71,10 +71,117 @@ interface ExecuteRequest {
     /** Places this run in a job map. Not accepted by a determinism check,
      *  which runs twice. */
     job?: JobLink;
+    /** What this request declares for the rules of an active customer policy
+     *  to read. Unknown keys and values outside the lists are refused before
+     *  sending. */
+    policy_context?: PolicyContext;
+    /** The policy hash this request expects to run under. When another policy
+     *  is active the server refuses the run with HTTP 409. */
+    expected_policy_hash?: Hex64;
     /** A version 1 signature for an unsigned client to send. A client with
      *  the `signingKey` option sends version 2 and drops this field. */
     request_signature?: RequestSignature;
 }
+/** Who the attested actor is, for a policy rule to read. */
+type PolicyActorType = "agent" | "user" | "service" | "system";
+/** What the request acts on, for a policy rule to read. */
+type PolicyObjectType = "text" | "transaction" | "code" | "data" | "model" | "file";
+/** A classification level, for a policy rule to read. */
+type PolicyClassification = "PUBLIC" | "INTERNAL" | "CONFIDENTIAL" | "RESTRICTED" | "TOP_SECRET" | "TS_SCI";
+/** The facts a request declares for the rules of a customer policy. These
+ *  are the caller's own statements: a rule on them judges what was
+ *  declared, and cannot show that it is true. Every key is optional, and
+ *  the client refuses any other key before sending, because a misspelt key
+ *  would be dropped and a rule on it would read its zero value.
+ *
+ *  `actor_type`, `mfa_satisfied` and `session_age_seconds` describe the
+ *  attested actor, so a request that sets one of them must also carry an
+ *  `attested_context` naming the actor, for example its `actor_id`. */
+interface PolicyContext {
+    actor_type?: PolicyActorType;
+    mfa_satisfied?: boolean;
+    /** A non-negative whole number of seconds. */
+    session_age_seconds?: number;
+    object_type?: PolicyObjectType;
+    /** At most 256 bytes of UTF-8. */
+    object_id?: string;
+    classification?: PolicyClassification;
+}
+/** A stored policy document, as POST /policies and GET /policies return
+ *  it. */
+interface Policy {
+    policy_id: string;
+    policy_version: string;
+    policy_hash: Hex64;
+    /** SHA-256 of the exact text that was uploaded. */
+    document_hash: Hex64;
+    created_at: string;
+}
+/** Returned by {@link VerdifaxClient.getPolicy}: the stored policy and its
+ *  exact text. */
+interface PolicyWithDocument extends Policy {
+    document: string;
+}
+/** Returned by {@link VerdifaxClient.listPolicies}. */
+interface PolicyList {
+    ok: boolean;
+    /** The chain of this key's policy changes, for example `api-key-7`. */
+    chain_id?: string;
+    /** The newest change, or 64 zeros when there is none yet. */
+    newest_activation_hash: Hex64;
+    /** The document in force, or empty under the built-in policy. */
+    active_document_hash: string;
+    policies: Policy[];
+}
+/** The argument of {@link VerdifaxClient.testPolicy}: sample inputs and
+ *  exactly one of `document` or `documentHash`. */
+interface PolicyTestRequest {
+    /** Sample inputs for the rules, passed through as given. */
+    inputs: Record<string, unknown>;
+    /** The exact text of a policy to test. */
+    document?: string;
+    /** The document hash of a policy already uploaded under this key. */
+    documentHash?: Hex64;
+}
+/** Returned by {@link VerdifaxClient.testPolicy}. A test seals nothing. */
+interface PolicyTestResult {
+    ok: boolean;
+    /** Always false. */
+    sealed: boolean;
+    outcome: string;
+    fired_rule_id: string;
+    reason_code: string;
+}
+/** The signature of a policy activation: the request key's approval of
+ *  the change. */
+interface PolicyActivationSignature {
+    /** Base64 Ed25519 signature by the request key. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per change. */
+    nonce: string;
+}
+/** One policy change, as {@link VerdifaxClient.activatePolicy} and
+ *  {@link VerdifaxClient.getPolicyHistory} return it. */
+interface PolicyActivation {
+    format: string;
+    chain_id: string;
+    sequence: number;
+    previous_activation_hash: Hex64;
+    policy_id: string;
+    policy_version: string;
+    policy_hash: Hex64;
+    document_hash: Hex64;
+    activated_at: string;
+    /** Present when the request key signed the change. */
+    signature?: PolicyActivationSignature & {
+        public_key: string;
+    };
+    activation_hash: Hex64;
+    /** Where the change was logged on the public log. */
+    anchor?: Record<string, unknown>;
+}
 /** Places one run in a job. `job_id` and `step_id` are 1 to 128 letters,
  *  digits, dots, underscores, colons or dashes. The client sorts both
  *  lists, removes repeats and leaves out an empty list and a false
@@ -341,6 +448,10 @@ interface AttestRequest {
     causal_graph?: Record<string, unknown>;
     /** Places this run in a job map. {@link VerdifaxJob.step} fills it in. */
     job?: JobLink;
+    /** What this request declares for the rules of a customer policy. */
+    policy_context?: PolicyContext;
+    /** The policy hash this request expects to run under. */
+    expected_policy_hash?: Hex64;
 }
 /** The second argument of {@link VerdifaxJob.step}: everything
  *  {@link VerdifaxClient.attest} takes except `job`, which the helper
@@ -620,6 +731,12 @@ declare const MAX_BATCH_ROWS = 1000;
  * | `registerRequestKey()` | POST /keys/request-key | required |
  * | `rotateRequestKey(newSigningKey)` | POST /keys/request-key | required |
  * | `clearRequestKey()` | DELETE /keys/request-key | required |
+ * | `uploadPolicy(document)` | POST /policies | required |
+ * | `listPolicies()` | GET /policies | required |
+ * | `getPolicy(documentHash)` | GET /policies/{document_hash} | required |
+ * | `testPolicy(req)` | POST /policies/test | required |
+ * | `getPolicyHistory()` | GET /policies/history | required |
+ * | `activatePolicy(documentHash)` | POST /policies/{document_hash}/activate | required |
  * | `job(jobId)` | none, returns a {@link VerdifaxJob} | none |
  *
  * With the `signingKey` option set, every path to POST /execute carries
@@ -658,8 +775,9 @@ declare class VerdifaxClient {
      *  signing key each row carries its own signature and nonce. A row
      *  that fails comes back in `results` with `ok: false`, so the call
      *  does not throw for it. The rows are not checked here, except a job
-     *  block, which is refused before anything is sent: the server reports
-     *  any other bad row in that row's result.
+     *  block, a `policy_context` and an `expected_policy_hash`, which are
+     *  refused before anything is sent: the server reports any other bad row
+     *  in that row's result.
      *
      *  This is one POST and it is never retried. After a timeout the
      *  server may have run some or all of the rows. */
@@ -690,6 +808,41 @@ declare class VerdifaxClient {
      *  unsigned requests, because the server refuses a signed run on an API
      *  key with no registered key. If the call fails it keeps the key. */
     clearRequestKey(): Promise<void>;
+    /** Stores a policy document. Nothing changes until it is activated with
+     *  {@link activatePolicy}. The server hashes the exact text, so this
+     *  sends the string it is given unchanged and refuses anything that is
+     *  not a string: serializing an object here would change the hash.
+     *  Verdifax does not write, review or approve a customer's policy. */
+    uploadPolicy(document: string): Promise<Policy>;
+    /** This key's stored documents, with the chain its changes belong to,
+     *  the newest change in it (64 zeros when there is none yet) and the
+     *  document in force (empty under the built-in policy). */
+    listPolicies(): Promise<PolicyList>;
+    /** One stored document, with its exact text as `document`. */
+    getPolicy(documentHash: Hex64): Promise<PolicyWithDocument>;
+    /** Shows which rule would fire on sample inputs, for a document given as
+     *  text or one already stored, named by its hash: exactly one of the two.
+     *  It seals nothing. */
+    testPolicy(req: PolicyTestRequest): Promise<PolicyTestResult>;
+    /** This key's policy changes, oldest first, as the list the server sends.
+     *  Save it as JSON, for example with
+     *  `writeFileSync("policy-history.json", JSON.stringify(history))`, and
+     *  check it with `verdifax-verify --policy-history policy-history.json`. */
+    getPolicyHistory(): Promise<PolicyActivation[]>;
+    /** Makes a stored document the policy in force and returns the change
+     *  record. It first reads GET /policies for the chain and its newest
+     *  change, then names that change as the one this follows. With the
+     *  `signingKey` option the request key signs the change, which the server
+     *  requires while a request key is registered.
+     *
+     *  Rolling back is activating an earlier document: it is one more change
+     *  in the chain, so the change it undoes stays on the record.
+     *
+     *  An HTTP 409 means the chain moved because another change came first,
+     *  or the document is not yet effective. It throws the usual
+     *  {@link APIError} and is not retried: read the policies again and
+     *  decide. */
+    activatePolicy(documentHash: Hex64): Promise<PolicyActivation>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -763,6 +916,8 @@ declare class VerdifaxClient {
         response: string;
         govern?: boolean;
         job?: JobLink;
+        policy_context?: PolicyContext;
+        expected_policy_hash?: Hex64;
     }): Promise<ExecuteResponse>;
     /** Convenience for attesting an OpenAI API response. `govern` works as
      *  in {@link attestClaudeResponse}. */
@@ -774,6 +929,8 @@ declare class VerdifaxClient {
         response: string;
         govern?: boolean;
         job?: JobLink;
+        policy_context?: PolicyContext;
+        expected_policy_hash?: Hex64;
     }): Promise<ExecuteResponse>;
     private attestProviderResponse;
     private request;
@@ -838,6 +995,9 @@ declare function captureEnvironment(options?: CaptureEnvironmentOptions): Reprod
  * Text with an unpaired surrogate has no UTF-8 form and is refused.
  */
 declare function formatProviderPayload(provider: string, prompt: string, response: string): string;
+/** Every top-level key a run request may hold. Any other key is refused
+ *  before sending, so a misspelt field cannot be silently dropped. */
+declare const EXECUTE_FIELDS: readonly string[];
 
 /**
  * The three canonical hash formulas from the Verdifax orchestrator, so a
@@ -961,6 +1121,29 @@ declare function requestKeyChangeApproval(currentSigningKey: Uint8Array | KeyObj
     signedAt?: string;
     nonce?: string;
 }): RequestKeyChange;
+/** The bytes the request key signs to make a stored policy document the
+ *  one in force, matching the orchestrator's PolicyActivationPreimage.
+ *  `chain_id` and `previous_activation_hash` come from GET /policies, so a
+ *  signature cannot be used on another key's chain, another document or
+ *  another point in the chain. */
+declare function policyActivationPreimage(fields: {
+    chain_id: string;
+    document_hash: string;
+    previous_activation_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** The request key's approval of a policy change, the `signature` value of
+ *  POST /policies/{document_hash}/activate. `signedAt` and `nonce` default
+ *  to the current time and fresh random bytes. */
+declare function policyActivationApproval(signingKey: Uint8Array | KeyObject, fields: {
+    chain_id: string;
+    document_hash: string;
+    previous_activation_hash: string;
+}, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): PolicyActivationSignature;
 
 /**
  * Input-validation helpers, mirrors the Python SDK's
@@ -1046,4 +1229,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };
+export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };

package/dist/index.d.ts

@@ -71,10 +71,117 @@ interface ExecuteRequest {
     /** Places this run in a job map. Not accepted by a determinism check,
      *  which runs twice. */
     job?: JobLink;
+    /** What this request declares for the rules of an active customer policy
+     *  to read. Unknown keys and values outside the lists are refused before
+     *  sending. */
+    policy_context?: PolicyContext;
+    /** The policy hash this request expects to run under. When another policy
+     *  is active the server refuses the run with HTTP 409. */
+    expected_policy_hash?: Hex64;
     /** A version 1 signature for an unsigned client to send. A client with
      *  the `signingKey` option sends version 2 and drops this field. */
     request_signature?: RequestSignature;
 }
+/** Who the attested actor is, for a policy rule to read. */
+type PolicyActorType = "agent" | "user" | "service" | "system";
+/** What the request acts on, for a policy rule to read. */
+type PolicyObjectType = "text" | "transaction" | "code" | "data" | "model" | "file";
+/** A classification level, for a policy rule to read. */
+type PolicyClassification = "PUBLIC" | "INTERNAL" | "CONFIDENTIAL" | "RESTRICTED" | "TOP_SECRET" | "TS_SCI";
+/** The facts a request declares for the rules of a customer policy. These
+ *  are the caller's own statements: a rule on them judges what was
+ *  declared, and cannot show that it is true. Every key is optional, and
+ *  the client refuses any other key before sending, because a misspelt key
+ *  would be dropped and a rule on it would read its zero value.
+ *
+ *  `actor_type`, `mfa_satisfied` and `session_age_seconds` describe the
+ *  attested actor, so a request that sets one of them must also carry an
+ *  `attested_context` naming the actor, for example its `actor_id`. */
+interface PolicyContext {
+    actor_type?: PolicyActorType;
+    mfa_satisfied?: boolean;
+    /** A non-negative whole number of seconds. */
+    session_age_seconds?: number;
+    object_type?: PolicyObjectType;
+    /** At most 256 bytes of UTF-8. */
+    object_id?: string;
+    classification?: PolicyClassification;
+}
+/** A stored policy document, as POST /policies and GET /policies return
+ *  it. */
+interface Policy {
+    policy_id: string;
+    policy_version: string;
+    policy_hash: Hex64;
+    /** SHA-256 of the exact text that was uploaded. */
+    document_hash: Hex64;
+    created_at: string;
+}
+/** Returned by {@link VerdifaxClient.getPolicy}: the stored policy and its
+ *  exact text. */
+interface PolicyWithDocument extends Policy {
+    document: string;
+}
+/** Returned by {@link VerdifaxClient.listPolicies}. */
+interface PolicyList {
+    ok: boolean;
+    /** The chain of this key's policy changes, for example `api-key-7`. */
+    chain_id?: string;
+    /** The newest change, or 64 zeros when there is none yet. */
+    newest_activation_hash: Hex64;
+    /** The document in force, or empty under the built-in policy. */
+    active_document_hash: string;
+    policies: Policy[];
+}
+/** The argument of {@link VerdifaxClient.testPolicy}: sample inputs and
+ *  exactly one of `document` or `documentHash`. */
+interface PolicyTestRequest {
+    /** Sample inputs for the rules, passed through as given. */
+    inputs: Record<string, unknown>;
+    /** The exact text of a policy to test. */
+    document?: string;
+    /** The document hash of a policy already uploaded under this key. */
+    documentHash?: Hex64;
+}
+/** Returned by {@link VerdifaxClient.testPolicy}. A test seals nothing. */
+interface PolicyTestResult {
+    ok: boolean;
+    /** Always false. */
+    sealed: boolean;
+    outcome: string;
+    fired_rule_id: string;
+    reason_code: string;
+}
+/** The signature of a policy activation: the request key's approval of
+ *  the change. */
+interface PolicyActivationSignature {
+    /** Base64 Ed25519 signature by the request key. */
+    signature: string;
+    /** RFC 3339 UTC with whole seconds. */
+    signed_at: string;
+    /** 16 random bytes as 32 lowercase hex characters, fresh per change. */
+    nonce: string;
+}
+/** One policy change, as {@link VerdifaxClient.activatePolicy} and
+ *  {@link VerdifaxClient.getPolicyHistory} return it. */
+interface PolicyActivation {
+    format: string;
+    chain_id: string;
+    sequence: number;
+    previous_activation_hash: Hex64;
+    policy_id: string;
+    policy_version: string;
+    policy_hash: Hex64;
+    document_hash: Hex64;
+    activated_at: string;
+    /** Present when the request key signed the change. */
+    signature?: PolicyActivationSignature & {
+        public_key: string;
+    };
+    activation_hash: Hex64;
+    /** Where the change was logged on the public log. */
+    anchor?: Record<string, unknown>;
+}
 /** Places one run in a job. `job_id` and `step_id` are 1 to 128 letters,
  *  digits, dots, underscores, colons or dashes. The client sorts both
  *  lists, removes repeats and leaves out an empty list and a false
@@ -341,6 +448,10 @@ interface AttestRequest {
     causal_graph?: Record<string, unknown>;
     /** Places this run in a job map. {@link VerdifaxJob.step} fills it in. */
     job?: JobLink;
+    /** What this request declares for the rules of a customer policy. */
+    policy_context?: PolicyContext;
+    /** The policy hash this request expects to run under. */
+    expected_policy_hash?: Hex64;
 }
 /** The second argument of {@link VerdifaxJob.step}: everything
  *  {@link VerdifaxClient.attest} takes except `job`, which the helper
@@ -620,6 +731,12 @@ declare const MAX_BATCH_ROWS = 1000;
  * | `registerRequestKey()` | POST /keys/request-key | required |
  * | `rotateRequestKey(newSigningKey)` | POST /keys/request-key | required |
  * | `clearRequestKey()` | DELETE /keys/request-key | required |
+ * | `uploadPolicy(document)` | POST /policies | required |
+ * | `listPolicies()` | GET /policies | required |
+ * | `getPolicy(documentHash)` | GET /policies/{document_hash} | required |
+ * | `testPolicy(req)` | POST /policies/test | required |
+ * | `getPolicyHistory()` | GET /policies/history | required |
+ * | `activatePolicy(documentHash)` | POST /policies/{document_hash}/activate | required |
  * | `job(jobId)` | none, returns a {@link VerdifaxJob} | none |
  *
  * With the `signingKey` option set, every path to POST /execute carries
@@ -658,8 +775,9 @@ declare class VerdifaxClient {
      *  signing key each row carries its own signature and nonce. A row
      *  that fails comes back in `results` with `ok: false`, so the call
      *  does not throw for it. The rows are not checked here, except a job
-     *  block, which is refused before anything is sent: the server reports
-     *  any other bad row in that row's result.
+     *  block, a `policy_context` and an `expected_policy_hash`, which are
+     *  refused before anything is sent: the server reports any other bad row
+     *  in that row's result.
      *
      *  This is one POST and it is never retried. After a timeout the
      *  server may have run some or all of the rows. */
@@ -690,6 +808,41 @@ declare class VerdifaxClient {
      *  unsigned requests, because the server refuses a signed run on an API
      *  key with no registered key. If the call fails it keeps the key. */
     clearRequestKey(): Promise<void>;
+    /** Stores a policy document. Nothing changes until it is activated with
+     *  {@link activatePolicy}. The server hashes the exact text, so this
+     *  sends the string it is given unchanged and refuses anything that is
+     *  not a string: serializing an object here would change the hash.
+     *  Verdifax does not write, review or approve a customer's policy. */
+    uploadPolicy(document: string): Promise<Policy>;
+    /** This key's stored documents, with the chain its changes belong to,
+     *  the newest change in it (64 zeros when there is none yet) and the
+     *  document in force (empty under the built-in policy). */
+    listPolicies(): Promise<PolicyList>;
+    /** One stored document, with its exact text as `document`. */
+    getPolicy(documentHash: Hex64): Promise<PolicyWithDocument>;
+    /** Shows which rule would fire on sample inputs, for a document given as
+     *  text or one already stored, named by its hash: exactly one of the two.
+     *  It seals nothing. */
+    testPolicy(req: PolicyTestRequest): Promise<PolicyTestResult>;
+    /** This key's policy changes, oldest first, as the list the server sends.
+     *  Save it as JSON, for example with
+     *  `writeFileSync("policy-history.json", JSON.stringify(history))`, and
+     *  check it with `verdifax-verify --policy-history policy-history.json`. */
+    getPolicyHistory(): Promise<PolicyActivation[]>;
+    /** Makes a stored document the policy in force and returns the change
+     *  record. It first reads GET /policies for the chain and its newest
+     *  change, then names that change as the one this follows. With the
+     *  `signingKey` option the request key signs the change, which the server
+     *  requires while a request key is registered.
+     *
+     *  Rolling back is activating an earlier document: it is one more change
+     *  in the chain, so the change it undoes stays on the record.
+     *
+     *  An HTTP 409 means the chain moved because another change came first,
+     *  or the document is not yet effective. It throws the usual
+     *  {@link APIError} and is not retried: read the policies again and
+     *  decide. */
+    activatePolicy(documentHash: Hex64): Promise<PolicyActivation>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
     listRuns(params?: ListRunsParams): Promise<{
@@ -763,6 +916,8 @@ declare class VerdifaxClient {
         response: string;
         govern?: boolean;
         job?: JobLink;
+        policy_context?: PolicyContext;
+        expected_policy_hash?: Hex64;
     }): Promise<ExecuteResponse>;
     /** Convenience for attesting an OpenAI API response. `govern` works as
      *  in {@link attestClaudeResponse}. */
@@ -774,6 +929,8 @@ declare class VerdifaxClient {
         response: string;
         govern?: boolean;
         job?: JobLink;
+        policy_context?: PolicyContext;
+        expected_policy_hash?: Hex64;
     }): Promise<ExecuteResponse>;
     private attestProviderResponse;
     private request;
@@ -838,6 +995,9 @@ declare function captureEnvironment(options?: CaptureEnvironmentOptions): Reprod
  * Text with an unpaired surrogate has no UTF-8 form and is refused.
  */
 declare function formatProviderPayload(provider: string, prompt: string, response: string): string;
+/** Every top-level key a run request may hold. Any other key is refused
+ *  before sending, so a misspelt field cannot be silently dropped. */
+declare const EXECUTE_FIELDS: readonly string[];
 
 /**
  * The three canonical hash formulas from the Verdifax orchestrator, so a
@@ -961,6 +1121,29 @@ declare function requestKeyChangeApproval(currentSigningKey: Uint8Array | KeyObj
     signedAt?: string;
     nonce?: string;
 }): RequestKeyChange;
+/** The bytes the request key signs to make a stored policy document the
+ *  one in force, matching the orchestrator's PolicyActivationPreimage.
+ *  `chain_id` and `previous_activation_hash` come from GET /policies, so a
+ *  signature cannot be used on another key's chain, another document or
+ *  another point in the chain. */
+declare function policyActivationPreimage(fields: {
+    chain_id: string;
+    document_hash: string;
+    previous_activation_hash: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** The request key's approval of a policy change, the `signature` value of
+ *  POST /policies/{document_hash}/activate. `signedAt` and `nonce` default
+ *  to the current time and fresh random bytes. */
+declare function policyActivationApproval(signingKey: Uint8Array | KeyObject, fields: {
+    chain_id: string;
+    document_hash: string;
+    previous_activation_hash: string;
+}, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): PolicyActivationSignature;
 
 /**
  * Input-validation helpers, mirrors the Python SDK's
@@ -1046,4 +1229,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };
+export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, type AttestationList, AuthError, CRES_ENGINE_VERSION, CRES_PREIMAGE_VERSION, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, DCAE_PREIMAGE_VERSION, DSE_FORMULA_VERSION, type DeletionReceipt, type DeterminismDiff, type DeterminismRun, EXECUTE_FIELDS, type ExecuteBatchResponse, type ExecuteBatchResult, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type ExportRow, type ExportRunsParams, type FormulaEra, type Health, type Hex64, type JobLink, type JobStepOptions, type ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, type Policy, type PolicyActivation, type PolicyActivationSignature, type PolicyActorType, type PolicyClassification, type PolicyContext, type PolicyList, type PolicyObjectType, type PolicyTestRequest, type PolicyTestResult, type PolicyWithDocument, RUN_STATUSES, type ReproducibilityContext, type RequestKeyChange, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type RequestSignatureV2, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, type SignedRequestBody, VerdifaxClient, VerdifaxError, VerdifaxJob, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, policyActivationApproval, policyActivationPreimage, requestKeyChangeApproval, requestKeyChangePreimage, requestKeyRegistrationBody, requestSignaturePreimage, requestSignaturePreimageV2, signRequest, signRequestV2, validateHex64, validateJobName, validateRouteId };