verdifax 1.0.0 → 1.1.0

package/README.md

@@ -80,13 +80,17 @@ if (v.verified) {
 | `client.getPublicBundleByToken(token)` | `GET /public/runs/{token}/bundle.json` | none |
 | `client.dcaeVerify(bundle)` | `POST /dcae/verify` | none |
 | `client.registerRequestKey()` | `POST /keys/request-key` | required |
+| `client.rotateRequestKey(newSigningKey)` | `POST /keys/request-key` | required |
 | `client.clearRequestKey()` | `DELETE /keys/request-key` | required |
 | `client.adminCreateKey(name)` | `POST /admin/keys` | admin |
 | `client.adminListKeys()` | `GET /admin/keys` | admin |
 | `client.adminRevokeKey(id)` | `DELETE /admin/keys/{id}` | admin |
+| `client.adminClearRequestKey(id)` | `DELETE /admin/keys/{id}/request-key` | admin |
 | `client.adminErase(req)` | `POST /admin/erase` | admin |
 
-These functions make no request: `captureEnvironment`, `formatProviderPayload`, `signRequest`, `requestKeyRegistrationBody`, `requestSignaturePreimage`, `generateRequestKeyPair`, `validateHex64`, `validateRouteId`, `dseDispatchHash`, `dcaeClosureHash` and `cresReceiptHash`. `RUN_STATUSES` lists every run status the server uses.
+`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.
 
 `getRunArtifacts`, `getPublicBundle` and `getPublicBundleByToken` return the exact JSON text the server sent, so you can save it and check it with `verdifax-verify`.
 
@@ -126,6 +130,44 @@ for (const row of batch.results) {
 
 The client's timeout covers the whole batch, so raise `timeoutMs` for a large one. A batch is one POST and it is never retried. After a timeout the server may have run some or all of the rows, so list your runs before you send them again.
 
+## Jobs
+
+A job links several runs into one map: each step names the records it directly follows, so work can split into branches and join again. `client.job(jobId)` returns a helper that keeps the map for you.
+
+```typescript
+const job = client.job("loan-1042");
+const run = { program_id, route_id, registry_record_hash };
+
+await job.step("intake", { ...run, payload_text: "application received" });
+
+// Two branches after one step.
+await job.step("credit", { ...run, payload_text: "credit check", after: ["intake"] });
+await job.step("income", { ...run, payload_text: "income check", after: ["intake"] });
+
+// A final step joining them.
+await job.step("decide", {
+  ...run,
+  payload_text: "decision",
+  after: ["credit", "income"],
+  final: true,
+});
+
+console.log(job.recordHashes); // step id to record hash
+console.log(job.signedRequests); // step id to signed text, when the client signs
+```
+
+`job.step(stepId, options)` takes everything `attest` takes, plus `after`, `external_previous` and `final`, and returns what `attest` returns. `after` lists step ids in this job. Without it, a step follows the one run just before it through this helper, and the first step follows nothing. An `after` that names an unknown step throws a `VerdifaxError` before anything is sent.
+
+A refused or halted step stays in the map, so a later step can follow it. `job.step` records its hash and signed text, then throws the same `APIError` that `attest` throws, with the hash in `err.recordHash`. A step that sealed nothing, such as a timeout or a 409, is not in the map and does not move the default `after`, so it can run again under the same id. To run branches at the same time, give each one its `after`. An empty `after` starts another root step.
+
+A successful step records `record_hash`, or `manifest_hash` if the response has no `record_hash`. If it has neither, `job.step` throws a `VerdifaxError`, so the map never silently gets a gap. A mistyped option such as `afer` is refused before sending, so a typo cannot silently drop a link.
+
+`execute`, `attest` and each row of `executeBatch` also take a `job` block directly: `{ job_id, step_id, previous_record_hashes, external_previous, final }`. Results carry `record_hash`. `job_id` and `step_id` are 1 to 128 letters, digits, `.`, `_`, `:` or `-`, and any other name is refused before sending. The SDK sorts both lists and removes repeats, and refuses unknown fields, a `final` that is not true or false, and hash lists that are not lists. A determinism check runs twice, so `verifyDeterminism` refuses a job.
+
+The server refuses a step in a closed job, a repeated step id, and a final step that leaves a branch with no step after it. To check a whole job, save each record in one folder and run `verdifax-verify --job FOLDER`.
+
+A job map covers what was sent. It cannot show a step that was never sent.
+
 ## 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.
@@ -142,6 +184,8 @@ if (truncated) {
 }
 ```
 
+Pass `job_id` in the period to export one job. JSON rows also carry `anchor_source` (`bundle`, `receipt` or `none`), and `job_id` and `step_id` when the run is a job step.
+
 The export states what the server stored, not a verdict. A call that never reached Verdifax cannot appear in it. Both forms say when a period holds more rows than the export returned: check `truncated`. `exportRunsCSV` reads `total` and `truncated` from the `X-Verdifax-Total` and `X-Verdifax-Truncated` response headers, and throws if the server does not send them. In the CSV, a `route_id` that a spreadsheet could read as a formula gets a leading `'`.
 
 ## Provider helpers
@@ -159,6 +203,8 @@ await client.attestClaudeResponse({
 });
 ```
 
+Both helpers take the same optional `job` block as `attest` and return `record_hash` and `signed_request` the same way.
+
 `govern` is false by default, which changes earlier behavior. Set `govern: true` to also send the response text as `ai_output_text` for the AIVP review, which runs on Anthropic in production. Without it, the AI output text is not sent for review.
 
 ## Optional execute fields
@@ -219,6 +265,7 @@ Request signing is optional. A client with no signing key sends the same request
 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.
 
 ```typescript
+import { writeFileSync } from "node:fs";
 import { VerdifaxClient, generateRequestKeyPair } from "verdifax";
 
 // Run once, then store privateKey as a secret.
@@ -233,21 +280,29 @@ await client.registerRequestKey(); // sends the public key with its proof
 
 // execute, attest, attestClaudeResponse, attestOpenAIResponse, executeBatch
 // and verifyDeterminism now sign.
-await client.execute({
+const run = await client.execute({
   program_id: "1111111111111111111111111111111111111111111111111111111111111111",
   route_id: "demo-attestation",
   registry_record_hash: "2222222222222222222222222222222222222222222222222222222222222222",
   payload_text: "first signed attestation",
 });
 
-await client.clearRequestKey(); // stops requiring signatures on this API key
+// The exact text that was signed. Keep it for verdifax-verify --request FILE.
+writeFileSync("signed-request.json", run.signed_request!);
+
+// The current key approves the change, and this client then signs with the new key.
+await client.rotateRequestKey(generateRequestKeyPair().privateKey);
+
+await client.clearRequestKey(); // stops requiring signatures, and this client stops signing
 ```
 
-Registering a key changes that API key for every client that uses it: the server then refuses a run without a valid signature, so every caller on the key needs the private key. Each request carries the time and a fresh random nonce. The server refuses a repeated nonce and a time more than five minutes from its own clock.
+A signed call serializes the request once and signs that exact text, using signature version 2, so the signature covers the whole request. It sends `signed_request` and `request_signature` and nothing else, and a batch row has the same shape. The result carries the text as `signed_request`, on each row for a batch. A refused or halted run throws the usual `APIError`, with the text in `err.signedRequest`. It holds your payload, so it stays out of the error message and logging the error does not print it: read it by name.
+
+Registering a key changes that API key for every client that uses it: the server then refuses a run without a valid signature, so every caller on the key needs the private key. An API key alone cannot replace or clear a registered key: `rotateRequestKey` and `clearRequestKey` send the current key's approval. After a successful `clearRequestKey` the client drops its signing key and sends unsigned requests, because the server refuses a signed run on an API key with no registered key. To sign again, create a client with a `signingKey` and register it. Each request carries the time and a fresh random nonce. The server refuses a repeated nonce and a time more than five minutes from its own clock.
 
 In a batch each row carries its own signature and nonce, and the server checks them as it reaches that row. A row refused for its signature comes back in `results`, so a repeated batch returns HTTP 200 with failed rows, and a row reached more than five minutes after it was signed fails the same way. A determinism check uses one signature for the request, and repeating it returns HTTP 403.
 
-The signature shows the holder of the key requested the run. It does not show the key holder accepted the outcome.
+A signature shows who requested the run, not that they accepted the outcome.
 
 ## Trust model
 

package/dist/index.d.mts

@@ -68,9 +68,27 @@ interface ExecuteRequest {
     /** Caller-supplied record of what led to this run. Recorded as
      *  supplied. */
     causal_graph?: Record<string, unknown>;
-    /** Filled in by the client when the `signingKey` option is set. */
+    /** Places this run in a job map. Not accepted by a determinism check,
+     *  which runs twice. */
+    job?: JobLink;
+    /** 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;
 }
+/** 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
+ *  `final`. */
+interface JobLink {
+    job_id: string;
+    step_id: string;
+    /** Record hashes of the steps this one directly follows, in this job. */
+    previous_record_hashes?: Hex64[];
+    /** Record hashes from another account that this step follows. */
+    external_previous?: Hex64[];
+    /** True on the step that closes the job. */
+    final?: boolean;
+}
 /** The runtime a caller declares for a run. Every field is optional.
  *  The server records these values as given and does not check them. */
 interface ReproducibilityContext {
@@ -98,6 +116,27 @@ interface RequestSignature {
     /** 16 random bytes as 32 lowercase hex characters, fresh per request. */
     nonce: string;
 }
+/** A version 2 request signature, which covers the exact `signed_request`
+ *  text. */
+interface RequestSignatureV2 extends RequestSignature {
+    version: "2";
+}
+/** The whole body of a signed call, and of each row of a signed batch.
+ *  The server reads the request from `signed_request` alone. */
+interface SignedRequestBody {
+    /** The request as JSON text, exactly as it was signed. */
+    signed_request: string;
+    request_signature: RequestSignatureV2;
+}
+/** The current key's approval of replacing or clearing itself. */
+interface RequestKeyChange {
+    /** Base64 Ed25519 signature by the current 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;
+}
 /** A key pair from {@link generateRequestKeyPair}, as raw bytes. */
 interface RequestKeyPair {
     /** The 32-byte Ed25519 public key. */
@@ -112,7 +151,8 @@ interface RequestKeyRegistrationBody {
     /** Base64 signature proving the caller holds the private key. */
     proof: string;
 }
-/** Returned by {@link VerdifaxClient.registerRequestKey}. */
+/** Returned by {@link VerdifaxClient.registerRequestKey} and
+ *  {@link VerdifaxClient.rotateRequestKey}. */
 interface RequestKeyRegistration {
     ok: boolean;
     public_key: string;
@@ -120,8 +160,16 @@ interface RequestKeyRegistration {
 interface ExecuteResponse {
     ok: boolean;
     run_id: number;
+    /** The record's hash: the manifest hash of a completed run. A refused or
+     *  halted run throws an {@link APIError} carrying its `recordHash` and,
+     *  when signed, its `signedRequest`. */
+    record_hash?: Hex64;
+    manifest_hash?: Hex64;
     manifest: ExecutionManifest;
     duration_ms: number;
+    /** The exact text that was signed, when the call was signed. Keep it to
+     *  pass to `verdifax-verify --request FILE`. */
+    signed_request?: string;
 }
 /** One row of {@link ExecuteBatchResponse}. A successful row has
  *  `manifest`. A failed row has `error`, and `error_stage` and a typed
@@ -131,11 +179,16 @@ interface ExecuteBatchResult {
     index: number;
     ok: boolean;
     run_id?: number;
+    /** The manifest hash of a completed row, or the receipt hash of a refused
+     *  or halted one. */
+    record_hash?: Hex64;
     manifest_hash?: Hex64;
     manifest?: ExecutionManifest;
     error?: string;
     error_stage?: string;
     duration_ms: number;
+    /** The exact text that was signed for this row, when it was signed. */
+    signed_request?: string;
     partial_manifest?: ExecutionManifest;
     deny_receipt?: Record<string, unknown>;
     ccv_halt_receipt?: Record<string, unknown>;
@@ -176,6 +229,8 @@ interface VerifyDeterminismResponse {
     first: DeterminismRun;
     second: DeterminismRun;
     diff: DeterminismDiff;
+    /** The exact text that was signed, when the call was signed. */
+    signed_request?: string;
 }
 /**
  * Sealed manifest. Field names match the orchestrator's Go-default
@@ -284,6 +339,21 @@ interface AttestRequest {
     authorization_chain?: Record<string, unknown>;
     regulatory_scaffolding?: Record<string, unknown>;
     causal_graph?: Record<string, unknown>;
+    /** Places this run in a job map. {@link VerdifaxJob.step} fills it in. */
+    job?: JobLink;
+}
+/** The second argument of {@link VerdifaxJob.step}: everything
+ *  {@link VerdifaxClient.attest} takes except `job`, which the helper
+ *  builds, plus the step's place in the job. */
+interface JobStepOptions extends Omit<AttestRequest, "job"> {
+    /** Step ids in this job that this step directly follows. When omitted,
+     *  the step follows the one run just before it through this helper. An
+     *  empty list means it follows none. */
+    after?: string[];
+    /** Record hashes from another account that this step follows. */
+    external_previous?: Hex64[];
+    /** True on the step that closes the job. */
+    final?: boolean;
 }
 /** Optional filters for {@link VerdifaxClient.listRuns}. */
 interface ListRunsParams {
@@ -325,6 +395,8 @@ interface SearchRunsParams {
 interface ExportRunsParams {
     from?: string;
     to?: string;
+    /** Limits the export to the runs of one job. */
+    job_id?: string;
 }
 /** One run in an evidence export: what the server stored, not a verdict. */
 interface ExportRow {
@@ -338,6 +410,11 @@ interface ExportRow {
     leaf_hash: string;
     complete_record_entry_id: string;
     complete_record_leaf_hash: string;
+    /** Where the row's public-log entry was read from: `bundle`, `receipt`
+     *  or `none`. */
+    anchor_source?: string;
+    job_id?: string;
+    step_id?: string;
 }
 /** Body returned by GET /runs/export in JSON form. */
 interface RunsExport {
@@ -453,6 +530,47 @@ interface AdminAPIKey {
     revoked: boolean;
 }
 
+/**
+ * The job helper: runs the steps of one job and keeps the map of step ids
+ * to record hashes, so a later step can name the steps it follows.
+ */
+
+/** Returned by {@link VerdifaxClient.job}.
+ *
+ *  Every step goes through `attest`, so it signs when the client signs. A
+ *  refused or halted step stays in the map and a later step can name it.
+ *  A step that sealed nothing, for example a timeout or a 409, is not in the
+ *  map and does not move the default `after`, so it can run again under the
+ *  same id. An empty `after` starts another root step.
+ *
+ *  `signedRequests` holds the payloads of signed steps, so it is a private
+ *  field: logging a job prints the hashes and not that text.
+ *
+ *  To run branches at the same time, give each its `after`: the default
+ *  reads the last step that finished. */
+declare class VerdifaxJob {
+    #private;
+    readonly jobId: string;
+    private readonly client;
+    private readonly hashes;
+    private lastStepId;
+    constructor(client: {
+        attest(req: AttestRequest): Promise<ExecuteResponse>;
+    }, jobId: string);
+    /** Step id to record hash for every step that left a record, on a copy. */
+    get recordHashes(): Record<string, Hex64>;
+    /** Step id to the exact text that was signed, for every signed step that
+     *  left a record, refused and halted steps included, on a copy. Each text
+     *  can be passed to `verdifax-verify --request FILE`. */
+    get signedRequests(): Record<string, string>;
+    /** Runs one step and records its hash and signed text. A refused or halted
+     *  step records both from the error, then throws the same error `attest`
+     *  throws. */
+    step(stepId: string, options: JobStepOptions): Promise<ExecuteResponse>;
+    private previousHashes;
+    private record;
+}
+
 /** The most rows POST /execute/batch accepts in one request. */
 declare const MAX_BATCH_ROWS = 1000;
 /**
@@ -496,14 +614,19 @@ declare const MAX_BATCH_ROWS = 1000;
  * | `adminCreateKey(name)` | POST /admin/keys | required |
  * | `adminListKeys()` | GET /admin/keys | required |
  * | `adminRevokeKey(id)` | DELETE /admin/keys/{id} | required |
+ * | `adminClearRequestKey(id)` | DELETE /admin/keys/{id}/request-key | required |
  * | `attestClaudeResponse(...)` | POST /execute (helper) | required |
  * | `attestOpenAIResponse(...)` | POST /execute (helper) | required |
  * | `registerRequestKey()` | POST /keys/request-key | required |
+ * | `rotateRequestKey(newSigningKey)` | POST /keys/request-key | required |
  * | `clearRequestKey()` | DELETE /keys/request-key | required |
+ * | `job(jobId)` | none, returns a {@link VerdifaxJob} | none |
  *
  * With the `signingKey` option set, every path to POST /execute carries
  * a fresh request signature, each row of a batch carries its own, and a
- * determinism check carries one. Without it, requests are unsigned.
+ * determinism check carries one. Each sends `signed_request` and
+ * `request_signature` and nothing else, and the result carries the signed
+ * text as `signed_request`. Without it, requests are unsigned.
  *
  * Idempotent GETs that hit a transient failure (502/503/504/429)
  * are retried with exponential backoff + full jitter. Non-
@@ -517,7 +640,7 @@ declare class VerdifaxClient {
     private readonly userAgent;
     private readonly maxRetries;
     private readonly retryBaseDelayMs;
-    private readonly signingKey;
+    private signingKey;
     constructor(config?: ClientConfig);
     health(): Promise<Health>;
     version(): Promise<VerdifaxVersion>;
@@ -528,13 +651,15 @@ declare class VerdifaxClient {
     execute(req: ExecuteRequest): Promise<ExecuteResponse>;
     /** Runs one payload twice on the server and compares the manifest
      *  hashes. One signature covers the request, and the server claims
-     *  its nonce once. Both runs are recorded. */
+     *  its nonce once. Both runs are recorded. A run that happens twice
+     *  cannot be one job step, so a `job` is refused here. */
     verifyDeterminism(req: ExecuteRequest): Promise<VerifyDeterminismResponse>;
     /** Sends up to {@link MAX_BATCH_ROWS} runs in one request. With a
      *  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: the server
-     *  reports a bad row in that row's result.
+     *  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.
      *
      *  This is one POST and it is never retried. After a timeout the
      *  server may have run some or all of the rows. */
@@ -544,12 +669,26 @@ declare class VerdifaxClient {
      *  string (for plain text). Validates the hex fields and
      *  routes the call through to the canonical /execute. */
     attest(req: AttestRequest): Promise<ExecuteResponse>;
+    /** A helper that runs the steps of one job through {@link attest} and
+     *  keeps each step's record hash, so a later step can name it. It makes
+     *  no request until a step runs. */
+    job(jobId: string): VerdifaxJob;
     /** Registers this client's public key on its API key, with the proof
      *  that the client holds the private key. From then on the server
      *  refuses a run on this API key without a request signature. */
     registerRequestKey(): Promise<RequestKeyRegistration>;
+    /** Replaces the registered key with `newSigningKey`. The new key proves
+     *  itself and this client's current key approves the change. After
+     *  success this client signs with the new key. If the call fails it
+     *  keeps the current key, including after a timeout, when the server may
+     *  have made the change. */
+    rotateRequestKey(newSigningKey: Uint8Array | KeyObject): Promise<RequestKeyRegistration>;
     /** Clears the registered public key, so the server stops requiring
-     *  request signatures on this API key. */
+     *  request signatures on this API key. With a signing key the client
+     *  sends that key's approval, which the server requires while a key is
+     *  registered. After success the client drops its signing key and sends
+     *  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>;
     getRun(runId: number): Promise<Run>;
     verifyRun(runId: number): Promise<VerifyResponse>;
@@ -608,6 +747,10 @@ declare class VerdifaxClient {
     adminCreateKey(name: string): Promise<AdminCreateKeyResponse>;
     adminListKeys(): Promise<AdminAPIKey[]>;
     adminRevokeKey(keyId: number): Promise<void>;
+    /** Clears the request key on an API key whose holder lost it, after a
+     *  manual check. It is the one way to clear a key without that key. The
+     *  id can be any API key, so this client keeps its own signing key. */
+    adminClearRequestKey(keyId: number): Promise<void>;
     /** Convenience for attesting an Anthropic Claude API response. With
      *  `govern: true` the response text also goes to the AIVP review as
      *  `ai_output_text`; that is off by default, so the text leaves your
@@ -619,6 +762,7 @@ declare class VerdifaxClient {
         prompt: string;
         response: string;
         govern?: boolean;
+        job?: JobLink;
     }): Promise<ExecuteResponse>;
     /** Convenience for attesting an OpenAI API response. `govern` works as
      *  in {@link attestClaudeResponse}. */
@@ -629,6 +773,7 @@ declare class VerdifaxClient {
         prompt: string;
         response: string;
         govern?: boolean;
+        job?: JobLink;
     }): Promise<ExecuteResponse>;
     private attestProviderResponse;
     private request;
@@ -636,8 +781,8 @@ declare class VerdifaxClient {
     private requestRaw;
     private requireAPIKey;
     private requireExecuteFields;
-    /** The request with its derived flags and, with a signing key, a fresh
-     *  signature and nonce, on a copy. */
+    /** The body to send, on a copy: the request with its derived flags or,
+     *  with a signing key, the signed text with a fresh signature and nonce. */
     private prepared;
 }
 
@@ -749,8 +894,9 @@ declare function cresReceiptHash(fields: {
  *  32-byte public key and a 32-byte private key. Nothing is sent to
  *  the server. Store the private key as a secret. */
 declare function generateRequestKeyPair(): RequestKeyPair;
-/** The bytes a request signature signs: the fields joined with single
- *  zero bytes, matching the orchestrator's RequestSignaturePreimage. */
+/** The bytes a version 1 request signature signs: the fields joined with
+ *  single zero bytes, matching the orchestrator's RequestSignaturePreimage.
+ *  The client now sends version 2. See {@link requestSignaturePreimageV2}. */
 declare function requestSignaturePreimage(fields: {
     payload_hash: string;
     program_id: string;
@@ -759,9 +905,37 @@ declare function requestSignaturePreimage(fields: {
     signed_at: string;
     nonce: string;
 }): Buffer;
-/** Signs one execute request. The server hashes payload_text when it is
- *  non-empty, otherwise the payload string exactly as sent (it does not
- *  base64-decode it), so this does the same.
+/** The bytes a version 2 request signature signs: the fields joined with
+ *  single zero bytes, matching the orchestrator's
+ *  RequestSignaturePreimageV2. With no job, the job fields are empty and
+ *  `final` is false. */
+declare function requestSignaturePreimageV2(fields: {
+    body_hash: string;
+    payload_hash: string;
+    program_id: string;
+    route_id: string;
+    registry_record_hash: string;
+    ai_output_hash: string;
+    job?: JobLink;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** Signs one execute request with signature version 2 and returns the
+ *  whole body to send. The request is serialized once, and that exact text
+ *  is what is hashed, signed and sent.
+ *
+ *  The payload hash follows the same rule as {@link signRequest}.
+ *  `signedAt` and `nonce` default to the current time and fresh random
+ *  bytes. A nonce the server has already seen is refused. */
+declare function signRequestV2(signingKey: Uint8Array | KeyObject, req: ExecuteRequest, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): SignedRequestBody;
+/** Signs one execute request with signature version 1, which the server
+ *  still accepts. The client now sends version 2: see {@link signRequestV2}.
+ *  The server hashes payload_text when it is non-empty, otherwise the
+ *  payload string exactly as sent (it does not base64-decode it), so this
+ *  does the same.
  *
  *  `signedAt` and `nonce` default to the current time and fresh random
  *  bytes. A nonce the server has already seen is refused. */
@@ -772,6 +946,21 @@ declare function signRequest(signingKey: Uint8Array | KeyObject, req: ExecuteReq
 /** The body of POST /keys/request-key: the base64 public key and a
  *  signature proving the caller holds its private key. */
 declare function requestKeyRegistrationBody(signingKey: Uint8Array | KeyObject): RequestKeyRegistrationBody;
+/** The bytes the current key signs to replace or clear itself. `new_public_key`
+ *  is the new base64 public key, or empty when clearing. */
+declare function requestKeyChangePreimage(fields: {
+    new_public_key: string;
+    signed_at: string;
+    nonce: string;
+}): Buffer;
+/** The current key's approval of a key change, the `change` value of POST
+ *  and DELETE /keys/request-key. Pass an empty `newPublicKey` when clearing.
+ *  `signedAt` and `nonce` default to the current time and fresh random
+ *  bytes. */
+declare function requestKeyChangeApproval(currentSigningKey: Uint8Array | KeyObject, newPublicKey: string, options?: {
+    signedAt?: string;
+    nonce?: string;
+}): RequestKeyChange;
 
 /**
  * Input-validation helpers, mirrors the Python SDK's
@@ -791,6 +980,9 @@ declare function validateHex64(value: string, fieldName: string): void;
  *  a wider character set, but the SDK enforces the conservative
  *  subset by default to catch typos early. */
 declare function validateRouteId(value: string): void;
+/** Throws unless `value` is a job or step name: 1 to 128 letters, digits,
+ *  dots, underscores, colons or dashes, the server's own rule. */
+declare function validateJobName(value: string, fieldName: string): void;
 
 /**
  * Typed errors returned by the Verdifax SDK.
@@ -830,13 +1022,22 @@ declare class NotFoundError extends VerdifaxError {
     constructor(path: string, message: string);
 }
 /** Every other non-2xx response. Carries the HTTP status and
- *  the path so callers can switch on either dimension. */
+ *  the path so callers can switch on either dimension. `recordHash` is
+ *  the receipt hash of a refused or halted run, when the server sealed
+ *  one; it is undefined when no record exists.
+ *
+ *  `signedRequest` is the exact text that was signed, when the call was a
+ *  signed run. Keep it to pass to `verdifax-verify --request FILE`. It holds
+ *  the payload, so it stays out of the message and is not enumerable: read
+ *  it by name, and logging the error does not print it. */
 declare class APIError extends VerdifaxError {
     readonly status: number;
     readonly path: string;
     readonly message: string;
+    readonly recordHash?: string | undefined;
     readonly name: string;
-    constructor(status: number, path: string, message: string);
+    readonly signedRequest?: string;
+    constructor(status: number, path: string, message: string, recordHash?: string | undefined, signedRequest?: string);
 }
 /** Returned when an authenticated method is called on a client
  *  constructed without an apiKey. */
@@ -845,4 +1046,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 ListAttestationsParams, type ListRunsParams, MAX_BATCH_ROWS, NotFoundError, type PDFFormat, RUN_STATUSES, type ReproducibilityContext, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type Run, type RunStats, type RunStatus, type RunSummary, type RunsExport, type RunsExportCSV, type SearchRunsParams, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyDeterminismResponse, type VerifyResponse, captureEnvironment, cresReceiptHash, dcaeClosureHash, dseDispatchHash, formatProviderPayload, fromEnv, generateRequestKeyPair, requestKeyRegistrationBody, requestSignaturePreimage, signRequest, validateHex64, 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, 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 };