verdifax 0.3.0 → 1.0.0

package/README.md

@@ -49,17 +49,131 @@ if (v.verified) {
 | --- | --- | --- |
 | `client.health()` | `GET /health` | none |
 | `client.version()` | `GET /version` | none |
+| `client.getOpenAPI()` | `GET /openapi.json` | none |
+| `client.getStats()` | `GET /stats` | required |
 | `client.execute(req)` | `POST /execute` | required |
+| `client.attest(req)` | `POST /execute` | required |
+| `client.attestClaudeResponse(args)` | `POST /execute` | required |
+| `client.attestOpenAIResponse(args)` | `POST /execute` | required |
+| `client.executeBatch(runs)` | `POST /execute/batch` | required |
+| `client.verifyDeterminism(req)` | `POST /execute/verify-determinism` | required |
 | `client.getRun(id)` | `GET /runs/{id}` | required |
 | `client.verifyRun(id)` | `GET /runs/{id}/verify` | required |
+| `client.listRuns(params)` | `GET /runs` | required |
+| `client.searchRuns(params)` | `GET /runs/search` | required |
+| `client.exportRuns(params)` | `GET /runs/export` | required |
+| `client.exportRunsCSV(params)` | `GET /runs/export?format=csv` | required |
+| `client.getRunArtifacts(id)` | `GET /runs/{id}/artifacts` | required |
+| `client.getRunReport(id)` | `GET /runs/{id}/report` | required |
+| `client.downloadAuditPDF(id, format)` | `GET /runs/{id}/report.pdf` | required |
+| `client.getAllowToken(id)` | `GET /runs/{id}/allow-token` | required |
+| `client.getDenyReceipt(id)` | `GET /runs/{id}/deny-receipt` | required |
+| `client.getCCVHaltReceipt(id)` | `GET /runs/{id}/ccv-halt-receipt` | required |
+| `client.getMACCHaltReceipt(id)` | `GET /runs/{id}/macc-halt-receipt` | required |
+| `client.getAivpT4HaltReceipt(id)` | `GET /runs/{id}/aivp-t4-halt-receipt` | required |
+| `client.getAttestationGapReceipt(id)` | `GET /runs/{id}/attestation-gap-receipt` | required |
+| `client.getCESAuditRecord(id)` | `GET /runs/{id}/ces-audit-record` | required |
+| `client.listDeletionReceipts(id)` | `GET /runs/{id}/deletion-receipts` | required |
+| `client.listAttestations(params)` | `GET /attestations` | required |
+| `client.getAttestation(id)` | `GET /attestations/{id}` | required |
+| `client.getPublicBundle(id)` | `GET /runs/{id}/bundle.json` | none |
+| `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.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.adminErase(req)` | `POST /admin/erase` | admin |
 
-The full HTTP surface (every endpoint, deletion-receipt list,
-DCAE verify, admin endpoints) is documented in the
-[OpenAPI spec](https://github.com/Verdifax/verdifax-orchestrator/blob/main/openapi/verdifax.yaml).
-This SDK ships the canonical operations; broader coverage lands
-as integrators ask.
+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.
+
+`getRunArtifacts`, `getPublicBundle` and `getPublicBundleByToken` return the exact JSON text the server sent, so you can save it and check it with `verdifax-verify`.
+
+## Versioning
+
+From 1.0, a breaking change needs a new major version.
+
+## Settings
+
+`new VerdifaxClient(config)` takes these options. `fromEnv()` reads the same settings from the environment.
+
+| Setting | Option | Environment variable | Default |
+| --- | --- | --- | --- |
+| Base URL | `baseURL` | `VERDIFAX_BASE_URL`, then `VERDIFAX_API_URL` | `https://api.verdifax.com` |
+| API key | `apiKey` | `VERDIFAX_API_KEY` | none |
+| Timeout | `timeoutMs` | `VERDIFAX_TIMEOUT_MS` | 90 seconds |
+| User agent | `userAgent` | `VERDIFAX_USER_AGENT` | `verdifax-sdk-node/<version>` |
+| Retries | `maxRetries` | `VERDIFAX_MAX_RETRIES` | 3 |
+| First retry delay | `retryBaseDelayMs` | none | 200 ms |
+
+GET, HEAD and OPTIONS requests are retried after a network failure or an HTTP 429, 502, 503 or 504, with exponential backoff and full jitter. POST is never retried.
+
+## Batch runs
+
+`executeBatch(runs)` sends up to 1,000 runs in one request and refuses more before sending anything. A row that fails comes back in `results` with `ok: false`, so the call does not throw for it.
+
+```typescript
+const batch = await client.executeBatch([
+  { program_id, route_id, registry_record_hash, payload_text: "first" },
+  { program_id, route_id, registry_record_hash, payload_text: "second" },
+]);
+
+for (const row of batch.results) {
+  console.log(row.index, row.ok, row.ok ? row.run_id : row.error);
+}
+```
+
+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.
+
+## 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.
+
+```typescript
+const period = { from: "2026-11-01T00:00:00Z", to: "2026-12-01T00:00:00Z" };
+
+const evidence = await client.exportRuns(period);
+console.log(evidence.total, evidence.truncated, evidence.by_status);
+
+const { csv, total, truncated } = await client.exportRunsCSV(period);
+if (truncated) {
+  console.log(`The CSV holds part of ${total} runs. Use a narrower period.`);
+}
+```
+
+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
+
+`attestClaudeResponse` and `attestOpenAIResponse` attest a prompt and response as one payload: canonical JSON, exactly `{"prompt":...,"provider":...,"response":...}` with sorted keys and no extra whitespace, UTF-8, with `provider` set to `anthropic` or `openai`. `formatProviderPayload` builds that text. All four Verdifax SDKs produce the same bytes. A helper call from an earlier version used a different payload, so it gave a different hash for the same text; records already stored are not touched.
+
+```typescript
+await client.attestClaudeResponse({
+  program_id,
+  route_id,
+  registry_record_hash,
+  prompt: "What is the boiling point of water?",
+  response: "100 C at sea level.",
+  govern: true,
+});
+```
+
+`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
+
+`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`.
+
+`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
+
+`captureEnvironment()` records the Node version, the platform, the packages under `node_modules`, the git commit and any seeds you declare. Pass the result as `reproducibility_context` on `execute`, `attest`, `executeBatch` or `verifyDeterminism`. Detection is best effort, and a value it cannot read is left out. The server records these values as given and does not check them.
+
+## Determinism check
+
+`verifyDeterminism(req)` runs one payload twice on the server and compares the manifest hashes. `deterministic` is true when both runs ended `ok` and the two hashes match. Both runs are recorded, with the status `probe`.
 
 ## Authentication
 
@@ -117,7 +231,8 @@ const client = new VerdifaxClient({
 
 await client.registerRequestKey(); // sends the public key with its proof
 
-// execute, attest, attestClaudeResponse and attestOpenAIResponse now sign.
+// execute, attest, attestClaudeResponse, attestOpenAIResponse, executeBatch
+// and verifyDeterminism now sign.
 await client.execute({
   program_id: "1111111111111111111111111111111111111111111111111111111111111111",
   route_id: "demo-attestation",
@@ -130,6 +245,8 @@ await client.clearRequestKey(); // stops requiring signatures on this API key
 
 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.
 
+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.
 
 ## Trust model

package/dist/index.d.mts

@@ -48,11 +48,46 @@ interface ExecuteRequest {
     registry_record_hash: Hex64;
     /** When non-empty, opts the request into the AIVP governance pipeline. */
     ai_output_text?: string;
-    /** Caller-attested actor + decision metadata; open schema. */
+    /** Caller-attested actor + decision metadata; open schema. The client
+     *  derives `attested` from whether any other field is provided. */
     attested_context?: Record<string, unknown>;
+    /** Caller-declared runtime fingerprint, recorded in the audit bundle.
+     *  Build it with {@link captureEnvironment}. */
+    reproducibility_context?: ReproducibilityContext;
+    /** Caller-supplied substance of the request: prompt, output, cost,
+     *  latency and origin metadata. Recorded as supplied. Leave out
+     *  `origin.source_ip_hash` and `origin.user_agent_hash`: the server
+     *  computes those and refuses them. */
+    request_substance?: Record<string, unknown>;
+    /** Caller-supplied approval chain. Recorded as supplied, not verified
+     *  by Verdifax. */
+    authorization_chain?: Record<string, unknown>;
+    /** Caller-supplied regulatory metadata. Recorded as supplied, not an
+     *  assessment by Verdifax. */
+    regulatory_scaffolding?: Record<string, unknown>;
+    /** 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. */
     request_signature?: RequestSignature;
 }
+/** 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 {
+    /** True when any other field has a value. The client derives this. */
+    declared?: boolean;
+    /** 64 hex characters, without the `sha256:` prefix. */
+    container_image_hash?: string;
+    runtime_name?: string;
+    runtime_version?: string;
+    /** `name==version` strings, sorted. */
+    pinned_dependencies?: string[];
+    git_commit_sha?: string;
+    /** `library=seed` strings, sorted. */
+    random_seeds?: string[];
+    /** GOOS/GOARCH style, for example `linux/amd64`. */
+    platform?: string;
+}
 /** The signature an API key with a registered request key must carry.
  *  The public key comes from the registration, never from the request. */
 interface RequestSignature {
@@ -88,6 +123,60 @@ interface ExecuteResponse {
     manifest: ExecutionManifest;
     duration_ms: number;
 }
+/** One row of {@link ExecuteBatchResponse}. A successful row has
+ *  `manifest`. A failed row has `error`, and `error_stage` and a typed
+ *  receipt when the pipeline halted. A row refused before it ran has
+ *  no `run_id`. */
+interface ExecuteBatchResult {
+    index: number;
+    ok: boolean;
+    run_id?: number;
+    manifest_hash?: Hex64;
+    manifest?: ExecutionManifest;
+    error?: string;
+    error_stage?: string;
+    duration_ms: number;
+    partial_manifest?: ExecutionManifest;
+    deny_receipt?: Record<string, unknown>;
+    ccv_halt_receipt?: Record<string, unknown>;
+    macc_halt_receipt?: Record<string, unknown>;
+    aivp_t4_halt_receipt?: Record<string, unknown>;
+    attestation_gap_receipt?: Record<string, unknown>;
+}
+/** Body returned by POST /execute/batch. */
+interface ExecuteBatchResponse {
+    ok: boolean;
+    total: number;
+    successful: number;
+    failed: number;
+    duration_ms: number;
+    results: ExecuteBatchResult[];
+}
+/** One of the two runs of a determinism check. */
+interface DeterminismRun {
+    run_id: number;
+    manifest_hash: string;
+    bundle_hash: string;
+    duration_ms: number;
+    status: string;
+    error?: string;
+}
+/** How the two runs of a determinism check compared. */
+interface DeterminismDiff {
+    differs: boolean;
+    manifest_hash_differs: boolean;
+    bundle_hash_differs: boolean;
+    differing_fields?: string[];
+}
+/** Body returned by POST /execute/verify-determinism. `deterministic`
+ *  means both runs ended ok with equal manifest hashes. */
+interface VerifyDeterminismResponse {
+    ok: boolean;
+    deterministic: boolean;
+    first: DeterminismRun;
+    second: DeterminismRun;
+    diff: DeterminismDiff;
+}
 /**
  * Sealed manifest. Field names match the orchestrator's Go-default
  * JSON encoding (CapitalCamelCase).
@@ -121,6 +210,12 @@ interface ExecutionManifest {
     LedgerProofHash?: Hex64;
     LogEntryID?: string;
 }
+/** Every status the server gives a run. */
+declare const RUN_STATUSES: readonly ["ok", "probe", "pepg_deny", "ccv_halt", "macc_halt", "aivp_t4_halt", "attestation_gap", "stage_error"];
+/** A run's status: one of {@link RUN_STATUSES}, or a value a newer server
+ *  adds. Written with `string & {}` so editors still offer the known
+ *  values and any string can be compared. */
+type RunStatus = (typeof RUN_STATUSES)[number] | (string & {});
 interface Run {
     ok: boolean;
     id: number;
@@ -130,7 +225,7 @@ interface Run {
     route_id: string;
     manifest_hash: Hex64;
     duration_ms: number;
-    status: "ok" | "pepg_deny" | "ccv_halt" | "macc_halt" | "stage_error";
+    status: RunStatus;
     error_stage?: string;
     error_message?: string;
     manifest: ExecutionManifest;
@@ -184,6 +279,11 @@ interface AttestRequest {
     registry_record_hash: Hex64;
     ai_output_text?: string;
     attested_context?: Record<string, unknown>;
+    reproducibility_context?: ReproducibilityContext;
+    request_substance?: Record<string, unknown>;
+    authorization_chain?: Record<string, unknown>;
+    regulatory_scaffolding?: Record<string, unknown>;
+    causal_graph?: Record<string, unknown>;
 }
 /** Optional filters for {@link VerdifaxClient.listRuns}. */
 interface ListRunsParams {
@@ -199,8 +299,94 @@ interface RunSummary {
     program_id: Hex64;
     route_id: string;
     manifest_hash: Hex64;
-    status: "ok" | "pepg_deny" | "ccv_halt" | "macc_halt" | "stage_error";
+    status: RunStatus;
     outcome_kind?: string;
+    duration_ms?: number;
+    error_stage?: string;
+    execution_region?: string;
+}
+/** Optional filters for {@link VerdifaxClient.searchRuns}. `from` and
+ *  `to` are RFC 3339 times. */
+interface SearchRunsParams {
+    /** Matches manifest hashes that start with this value. */
+    manifest_hash?: string;
+    program_id?: Hex64;
+    route_id?: string;
+    status?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Period for {@link VerdifaxClient.exportRuns} and
+ *  {@link VerdifaxClient.exportRunsCSV}, as RFC 3339 times. `from` is
+ *  inclusive and `to` is exclusive. `to` defaults to the time of the
+ *  request. */
+interface ExportRunsParams {
+    from?: string;
+    to?: string;
+}
+/** One run in an evidence export: what the server stored, not a verdict. */
+interface ExportRow {
+    run_id: number;
+    created_at: string;
+    status: RunStatus;
+    error_stage: string;
+    route_id: string;
+    manifest_hash: string;
+    log_entry_id: string;
+    leaf_hash: string;
+    complete_record_entry_id: string;
+    complete_record_leaf_hash: string;
+}
+/** Body returned by GET /runs/export in JSON form. */
+interface RunsExport {
+    ok: boolean;
+    /** The upper bound the server used for this export. */
+    to: string;
+    /** Runs held for the period. */
+    total: number;
+    /** Rows in this response. */
+    returned: number;
+    /** True when the period holds more rows than this response. */
+    truncated: boolean;
+    /** Rows returned, counted by status. */
+    by_status: Record<string, number>;
+    runs: ExportRow[];
+}
+/** Returned by {@link VerdifaxClient.exportRunsCSV}. */
+interface RunsExportCSV {
+    /** The CSV text, unparsed. */
+    csv: string;
+    /** Runs held for the period. */
+    total: number;
+    /** True when the period holds more rows than `csv`. */
+    truncated: boolean;
+}
+/** Optional paging for {@link VerdifaxClient.listAttestations}. */
+interface ListAttestationsParams {
+    limit?: number;
+    offset?: number;
+}
+/** Body returned by GET /attestations. Each row is a receipt as the
+ *  server sends it, without its inclusion proof. */
+interface AttestationList {
+    ok: boolean;
+    count: number;
+    limit: number;
+    offset: number;
+    attestations: Record<string, unknown>[];
+}
+/** Body returned by GET /stats. */
+interface RunStats {
+    ok: boolean;
+    total_runs: number;
+    runs_today: number;
+    runs_last_24h: number;
+    pass_rate: number;
+    avg_duration_ms: number;
+    last_run_at: string;
+    runs_by_program: Record<string, number>;
 }
 /** Audit-PDF format selector. */
 type PDFFormat = "brief" | "auditor" | "legal" | "comprehensive";
@@ -267,6 +453,8 @@ interface AdminAPIKey {
     revoked: boolean;
 }
 
+/** The most rows POST /execute/batch accepts in one request. */
+declare const MAX_BATCH_ROWS = 1000;
 /**
  * The Verdifax SDK client.
  *
@@ -276,17 +464,32 @@ interface AdminAPIKey {
  * | --- | --- | --- |
  * | `health()` | GET /health | none |
  * | `version()` | GET /version | none |
+ * | `getOpenAPI()` | GET /openapi.json | none |
+ * | `getStats()` | GET /stats | required |
  * | `execute(req)` | POST /execute | required |
  * | `attest(req)` | POST /execute (helper) | required |
  * | `getRun(id)` | GET /runs/{id} | required |
  * | `verifyRun(id)` | GET /runs/{id}/verify | required |
  * | `listRuns(params)` | GET /runs | required |
+ * | `searchRuns(params)` | GET /runs/search | required |
+ * | `exportRuns(params)` | GET /runs/export | required |
+ * | `exportRunsCSV(params)` | GET /runs/export?format=csv | required |
+ * | `listAttestations(params)` | GET /attestations | required |
+ * | `getAttestation(id)` | GET /attestations/{id} | required |
+ * | `getRunArtifacts(id)` | GET /runs/{id}/artifacts | required |
+ * | `getRunReport(id)` | GET /runs/{id}/report | required |
+ * | `getPublicBundle(id)` | GET /runs/{id}/bundle.json | none |
+ * | `getPublicBundleByToken(token)` | GET /public/runs/{token}/bundle.json | none |
+ * | `executeBatch(runs)` | POST /execute/batch | required |
+ * | `verifyDeterminism(req)` | POST /execute/verify-determinism | required |
  * | `downloadAuditPDF(id, format)` | GET /runs/{id}/report.pdf | required |
  * | `getAllowToken(id)` | GET /runs/{id}/allow-token | required |
  * | `getDenyReceipt(id)` | GET /runs/{id}/deny-receipt | required |
  * | `getCCVHaltReceipt(id)` | GET /runs/{id}/ccv-halt-receipt | required |
  * | `getMACCHaltReceipt(id)` | GET /runs/{id}/macc-halt-receipt | required |
  * | `getAivpT4HaltReceipt(id)` | GET /runs/{id}/aivp-t4-halt-receipt | required |
+ * | `getAttestationGapReceipt(id)` | GET /runs/{id}/attestation-gap-receipt | required |
+ * | `getCESAuditRecord(id)` | GET /runs/{id}/ces-audit-record | required |
  * | `listDeletionReceipts(id)` | GET /runs/{id}/deletion-receipts | required |
  * | `adminErase(req)` | POST /admin/erase | required |
  * | `dcaeVerify(bundle)` | POST /dcae/verify | none |
@@ -299,7 +502,8 @@ interface AdminAPIKey {
  * | `clearRequestKey()` | DELETE /keys/request-key | required |
  *
  * With the `signingKey` option set, every path to POST /execute carries
- * a fresh request signature. Without it, requests are unsigned.
+ * a fresh request signature, each row of a batch carries its own, and a
+ * determinism check carries one. Without it, requests are unsigned.
  *
  * Idempotent GETs that hit a transient failure (502/503/504/429)
  * are retried with exponential backoff + full jitter. Non-
@@ -317,7 +521,24 @@ declare class VerdifaxClient {
     constructor(config?: ClientConfig);
     health(): Promise<Health>;
     version(): Promise<VerdifaxVersion>;
+    /** The server's own API description. */
+    getOpenAPI(): Promise<Record<string, unknown>>;
+    /** Run counts for this API key. */
+    getStats(): Promise<RunStats>;
     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. */
+    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.
+     *
+     *  This is one POST and it is never retried. After a timeout the
+     *  server may have run some or all of the rows. */
+    executeBatch(runs: ExecuteRequest[]): Promise<ExecuteBatchResponse>;
     /** High-level convenience wrapper around `execute()`. Accepts
      *  either a Buffer (for binary payloads, auto-base64) or a
      *  string (for plain text). Validates the hex fields and
@@ -336,11 +557,47 @@ declare class VerdifaxClient {
         runs: RunSummary[];
         total: number;
     }>;
+    /** Searches this key's runs. `manifest_hash` matches a prefix. The
+     *  server ignores a `from` or `to` it cannot parse here, unlike
+     *  {@link exportRuns}, which refuses one. */
+    searchRuns(params?: SearchRunsParams): Promise<{
+        runs: RunSummary[];
+        total: number;
+    }>;
+    /** Lists what the server holds for this key in a period, failures
+     *  included, up to 10,000 rows. `truncated` is true when the period
+     *  holds more. The list states what was stored, not a verdict, and a
+     *  call that never reached Verdifax cannot appear in it. */
+    exportRuns(params?: ExportRunsParams): Promise<RunsExport>;
+    /** The same rows as {@link exportRuns}: the raw CSV text with `total`
+     *  and `truncated` from the response headers. Check `truncated`: when
+     *  true, the CSV is missing rows for the period. Throws when the server
+     *  does not send those headers, so that a cut-off export cannot pass
+     *  for a complete one. */
+    exportRunsCSV(params?: ExportRunsParams): Promise<RunsExportCSV>;
+    private exportPath;
+    listAttestations(params?: ListAttestationsParams): Promise<AttestationList>;
+    getAttestation(attestationId: number): Promise<Record<string, unknown>>;
     getAllowToken(runId: number): Promise<Record<string, unknown>>;
     getDenyReceipt(runId: number): Promise<Record<string, unknown>>;
     getCCVHaltReceipt(runId: number): Promise<Record<string, unknown>>;
     getMACCHaltReceipt(runId: number): Promise<Record<string, unknown>>;
     getAivpT4HaltReceipt(runId: number): Promise<Record<string, unknown>>;
+    getAttestationGapReceipt(runId: number): Promise<Record<string, unknown>>;
+    getCESAuditRecord(runId: number): Promise<Record<string, unknown>>;
+    /** The audit report for a run, as JSON. */
+    getRunReport(runId: number): Promise<Record<string, unknown>>;
+    /** The run's sealed audit bundle as the exact JSON text the server
+     *  sent, to save and check with `verdifax-verify`. It is not parsed:
+     *  JSON.parse would round a number above 2^53 and the recomputed hash
+     *  would stop matching. */
+    getRunArtifacts(runId: number): Promise<string>;
+    /** The public audit bundle of a record published by run id, as the
+     *  exact JSON text the server sent. Needs no API key. */
+    getPublicBundle(runId: number): Promise<string>;
+    /** The public audit bundle a share token points to, as the exact JSON
+     *  text the server sent. Needs no API key. */
+    getPublicBundleByToken(token: string): Promise<string>;
     private getRunArtifact;
     /** Streams the audit PDF bytes as a Buffer. Format defaults to
      *  "comprehensive" when not specified. */
@@ -351,27 +608,37 @@ declare class VerdifaxClient {
     adminCreateKey(name: string): Promise<AdminCreateKeyResponse>;
     adminListKeys(): Promise<AdminAPIKey[]>;
     adminRevokeKey(keyId: number): Promise<void>;
-    /** Convenience for attesting an Anthropic Claude API response.
-     *  Wires the response text into the AIVP governance pipeline
-     *  by setting `ai_output_text`. */
+    /** 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
+     *  machine for review only when you ask. */
     attestClaudeResponse(args: {
         program_id: Hex64;
         route_id: string;
         registry_record_hash: Hex64;
         prompt: string;
         response: string;
+        govern?: boolean;
     }): Promise<ExecuteResponse>;
-    /** Convenience for attesting an OpenAI API response. */
+    /** Convenience for attesting an OpenAI API response. `govern` works as
+     *  in {@link attestClaudeResponse}. */
     attestOpenAIResponse(args: {
         program_id: Hex64;
         route_id: string;
         registry_record_hash: Hex64;
         prompt: string;
         response: string;
+        govern?: boolean;
     }): Promise<ExecuteResponse>;
     private attestProviderResponse;
     private request;
+    /** A GET whose body is kept as sent, retried like any other GET. */
+    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. */
+    private prepared;
 }
 
 /**
@@ -380,7 +647,9 @@ declare class VerdifaxClient {
  *
  * Variables consumed (identical names across SDKs):
  *
- *   VERDIFAX_BASE_URL    base URL (defaults to https://api.verdifax.com)
+ *   VERDIFAX_BASE_URL    base URL, read first
+ *   VERDIFAX_API_URL     base URL, read when VERDIFAX_BASE_URL is unset
+ *                        (defaults to https://api.verdifax.com)
  *   VERDIFAX_API_KEY     X-Verdifax-Key value
  *   VERDIFAX_TIMEOUT_MS  per-request timeout in ms (defaults to 90000)
  *   VERDIFAX_USER_AGENT  override the default User-Agent
@@ -389,6 +658,84 @@ declare class VerdifaxClient {
 
 declare function fromEnv(): VerdifaxClient;
 
+/**
+ * Best-effort detection of the running Node environment, for the
+ * `reproducibility_context` of a run. A value that cannot be read is
+ * left out, and the server records it as not declared.
+ */
+
+interface CaptureEnvironmentOptions {
+    /** Library name to seed value. Recorded as declared; the caller still
+     *  has to apply the seeds. */
+    declaredSeeds?: Record<string, string | number>;
+    /** List the packages under `node_modules` in the working directory.
+     *  Defaults to true. */
+    includeDependencies?: boolean;
+    /** Read the commit with `git rev-parse HEAD`. Defaults to true. */
+    includeGit?: boolean;
+    /** Read the container id from `/proc/self/cgroup` on Linux. Defaults
+     *  to true. */
+    includeContainer?: boolean;
+}
+/** Auto-detects the running Node environment. */
+declare function captureEnvironment(options?: CaptureEnvironmentOptions): ReproducibilityContext;
+
+/**
+ * Request-body rules shared by every path to POST /execute.
+ */
+
+/**
+ * The payload the provider helpers attest: canonical JSON with sorted keys,
+ * no extra whitespace and UTF-8 text, exactly
+ * `{"prompt":...,"provider":...,"response":...}`. All four SDKs produce the
+ * same bytes, and a shared test vector holds them to it.
+ *
+ * Text with an unpaired surrogate has no UTF-8 form and is refused.
+ */
+declare function formatProviderPayload(provider: string, prompt: string, response: string): string;
+
+/**
+ * The three canonical hash formulas from the Verdifax orchestrator, so a
+ * caller can recompute a DSE dispatch hash, a DCAE closure hash or a CRES
+ * receipt hash without calling the server.
+ *
+ * These match the Python SDK's `verdifax.section0` and pass its test
+ * vectors. Every hash is SHA-256 as 64 lowercase hex characters, over
+ * UTF-8 text.
+ */
+
+declare const DSE_FORMULA_VERSION = "dse.tcu.dispatch.v1";
+declare const DCAE_PREIMAGE_VERSION = "verdifax.dcae.v1";
+declare const CRES_PREIMAGE_VERSION = "verdifax.cres.v1";
+declare const CRES_ENGINE_VERSION = "verdifax-cres/1.0.0";
+/** The DSE formula joins its fields with a period. */
+declare function dseDispatchHash(fields: {
+    envelope_id: string;
+    sequence_id: string;
+    program_id: Hex64;
+    registry_record_hash: Hex64;
+}): Hex64;
+/** The DCAE formula joins its fields with a pipe. */
+declare function dcaeClosureHash(fields: {
+    manifest_hash: Hex64;
+    aer_hash: Hex64;
+    envelope_id: string;
+    zksp_binding_hash: Hex64;
+    formal_verifier_status: string;
+}): Hex64;
+/** The CRES formula joins its fields with a pipe. `engine_version`
+ *  defaults to {@link CRES_ENGINE_VERSION}; pass another value only to
+ *  recompute a receipt from an earlier engine. */
+declare function cresReceiptHash(fields: {
+    envelope_id: string;
+    field_path: string;
+    deletion_clock: string;
+    actor_id: string;
+    ciphertext_hash_at_shred: Hex64;
+    dsar_reference: string;
+    engine_version?: string;
+}): Hex64;
+
 /**
  * Optional customer request signing.
  *
@@ -498,4 +845,4 @@ declare class APIKeyRequiredError extends VerdifaxError {
     constructor();
 }
 
-export { APIError, APIKeyRequiredError, type AdminAPIKey, type AdminCreateKeyResponse, type AdminEraseRequest, type AttestRequest, AuthError, type ClientConfig, type DCAEProofBundle, type DCAEVerdict, type DeletionReceipt, type ExecuteRequest, type ExecuteResponse, type ExecutionManifest, type FormulaEra, type Health, type Hex64, type ListRunsParams, NotFoundError, type PDFFormat, type RequestKeyPair, type RequestKeyRegistration, type RequestKeyRegistrationBody, type RequestSignature, type Run, type RunSummary, VerdifaxClient, VerdifaxError, type VerdifaxVersion, type VerifyResponse, 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 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 };