@attestry/sdk 0.6.0

package/dist/resources/decisions.d.ts

@@ -0,0 +1,1208 @@
+import type { AttestryClient } from "../client.js";
+import type { RequestOptions } from "../types.js";
+/**
+ * Public wire shape for a decision record returned by
+ * `GET /api/v1/decisions/:id`. Mirrors the kernel's `successResponse`
+ * column projection (canonicalPayload deliberately excluded).
+ *
+ * jsonb arrays (`frameworkClaims`, `toolInvocations`, `delegationChain`)
+ * are typed as `unknown[]` — the SDK does not enforce inner shape; the
+ * server already validated them at write time and the SDK is meant to
+ * be forward-compatible with kernel-side schema growth.
+ */
+export interface DecisionRecord {
+    id: string;
+    orgId: string;
+    systemId: string;
+    manifestVersionId: string;
+    /** Null when no attestation is bound to this record. */
+    attestationId: string | null;
+    /** Per-system monotonic sequence (notNull on the kernel side). */
+    sequenceNumber: number;
+    /** sha256:[a-f0-9]{64} format — server CHECK constraint. */
+    inputDigest: string;
+    /** sha256:[a-f0-9]{64} OR null when output isn't recorded. */
+    outputDigest: string | null;
+    frameworkClaims: unknown[];
+    toolInvocations: unknown[];
+    delegationChain: unknown[];
+    humanOversightState: string | null;
+    policyOutcome: string | null;
+    /** Null on the first record in the chain; otherwise the previous record's hash. */
+    prevRecordHash: string | null;
+    /** Hash of (prev_record_hash || canonical_payload). */
+    recordHash: string;
+    clientSignature: string | null;
+    clientKeyId: string | null;
+    idempotencyKey: string | null;
+    zkProof: Record<string, unknown> | null;
+    tombstoned: boolean;
+    /** ISO-8601 timestamp; non-null iff `tombstoned === true`. */
+    tombstonedAt: string | null;
+    tombstonedReason: string | null;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+}
+/**
+ * One framework-compliance claim asserted by the decision (e.g.
+ * `{framework: "eu_ai_act", article: "Art.13", claim: "human oversight provided"}`).
+ * Up to 50 entries per record. The server validates each item's shape
+ * via `.strict()`; the SDK forwards faithfully without per-item
+ * validation.
+ */
+export interface FrameworkClaim {
+    /** Framework code (1-100 chars). E.g., `"eu_ai_act"`, `"nist_ai_rmf"`. */
+    framework: string;
+    /** Article / section identifier (1-100 chars). E.g., `"Art.13"`, `"GV-1.1"`. */
+    article: string;
+    /** Claim text (1-2000 chars). */
+    claim: string;
+}
+/**
+ * One tool / model / external-API invocation that participated in the
+ * decision (e.g. `{name: "vector-store-query", inputHash: "sha256:..."}`).
+ * Up to 50 entries per record. Hash fields are optional; when present,
+ * must match `sha256:[a-f0-9]{64}` server-side.
+ */
+export interface ToolInvocation {
+    /** Tool / model identifier (1-200 chars). */
+    name: string;
+    /** Hash of the tool's input payload (sha256:[a-f0-9]{64}). */
+    inputHash?: string;
+    /** Hash of the tool's output payload (sha256:[a-f0-9]{64}). */
+    outputHash?: string;
+}
+/**
+ * One step in the agent-delegation chain that produced this decision.
+ * Up to 20 entries per record. `agentId` identifies the agent
+ * (caller-defined; could be a UUID, a slug, or an external system's
+ * identifier); `delegationToken` is an optional opaque proof-of-
+ * delegation (max 2000 chars).
+ */
+export interface DelegationEntry {
+    /** Agent identifier (1-500 chars). Caller-defined format. */
+    agentId: string;
+    /** Opaque delegation token (max 2000 chars). Optional. */
+    delegationToken?: string;
+}
+/**
+ * Optional zero-knowledge proof attached to the decision.
+ *
+ * Field caps (kernel-side):
+ *   - `type`: 1-100 chars (e.g., `"groth16"`, `"plonk"`, `"stark"`)
+ *   - `proof`: 1-100_000 chars — generous for real ZK schemes
+ *     (Groth16 ~200 bytes, PLONK ~5KB, STARKs can exceed 100KB)
+ *   - `publicSignals`: array of strings, each ≤500 chars, max 100 entries
+ *
+ * SDK forwards the object faithfully; server validates the inner shape.
+ */
+export interface ZkProof {
+    /** ZK scheme identifier (1-100 chars). */
+    type: string;
+    /** Proof data — opaque to the SDK (1-100_000 chars). */
+    proof: string;
+    /** Public signals — opaque strings (each ≤500 chars, max 100 entries). */
+    publicSignals: string[];
+}
+/**
+ * Input shape for `decisions.ingest()`. Mirrors the kernel's
+ * `decisionCreateSchema` (`src/lib/validation/decision-schemas.ts:17-93`)
+ * field-for-field. Strict at the server side (`.strict()`) — extra keys
+ * cause a 422 response, which is load-bearing for hash-chain
+ * non-malleability (every field that participates in the canonical hash
+ * must come through this shape; silent extras would weaken the chain).
+ *
+ * SDK validates field TYPES synchronously (throws `TypeError` BEFORE
+ * issuing any request). Format checks (UUID, hash regex, base64, enum
+ * membership, length caps, refine clause) are deferred to the server —
+ * decision D5 in the build-round audit.
+ *
+ * **Idempotency**: when `idempotencyKey` is provided AND a prior record
+ * with the same `(orgId, idempotencyKey)` exists, the server compares
+ * canonical bytes. Match → returns the persisted record (HTTP 200,
+ * `decision.idempotency_replay`). Mismatch → 409
+ * `IdempotencyConflictError` ("Idempotency key already used with
+ * different payload"). The SDK does NOT surface the 200/201 distinction
+ * (both resolve as `Promise<DecisionRecord>`); consumers can check
+ * `record.idempotencyKey === input.idempotencyKey` if they need to know.
+ *
+ * **Pairing constraint**: `clientSignature` and `clientKeyId` must
+ * EITHER both be provided OR both be absent. The server's `.refine()`
+ * rejects asymmetric input with a 422; the SDK forwards faithfully (D4).
+ */
+export interface DecisionIngestInput {
+    /** Required — UUID. The system this decision belongs to. */
+    systemId: string;
+    /** Required — `sha256:[a-f0-9]{64}`. Hash of the decision input. */
+    inputDigest: string;
+    /** Optional — `sha256:[a-f0-9]{64}`. Hash of the decision output. */
+    outputDigest?: string;
+    /** Optional — UUID. Bind this record to an existing attestation. */
+    attestationId?: string;
+    /** Optional — up to 50 framework-compliance claims. Defaults `[]`. */
+    frameworkClaims?: FrameworkClaim[];
+    /** Optional — up to 50 tool invocations. Defaults `[]`. */
+    toolInvocations?: ToolInvocation[];
+    /** Optional — up to 20 delegation steps. Defaults `[]`. */
+    delegationChain?: DelegationEntry[];
+    /** Optional — human-oversight gate state for this decision. */
+    humanOversightState?: "approved" | "bypassed" | "not_required";
+    /** Optional — final policy verdict for this decision. */
+    policyOutcome?: "permitted" | "denied" | "escalated";
+    /**
+     * Optional — base64-encoded signature over the canonical payload.
+     * Must be paired with `clientKeyId` (server `.refine()` rejects one
+     * without the other).
+     */
+    clientSignature?: string;
+    /**
+     * Optional — identifier for the key used to produce `clientSignature`.
+     * Must be paired with `clientSignature`.
+     */
+    clientKeyId?: string;
+    /**
+     * Optional — caller-supplied dedupe key (1-200 chars). Same
+     * `(orgId, idempotencyKey)` + same canonical payload → idempotent
+     * replay (returns the prior record). Different payload → 409.
+     *
+     * **For at-least-once delivery semantics across network failures,
+     * pass an `idempotencyKey` so retries dedupe server-side.** Without
+     * one, a 429-retry that succeeds-but-loses-the-response could create
+     * a duplicate record.
+     */
+    idempotencyKey?: string;
+    /** Optional — zero-knowledge proof attached to this decision. */
+    zkProof?: ZkProof;
+}
+/**
+ * Input shape for `decisions.bulk()`. Mirrors the kernel's
+ * `decisionBulkCreateSchema` (`src/lib/validation/decision-schemas.ts:105-114`)
+ * — a single-field wrapper around an items array. The wrapper (rather
+ * than a bare array) matches the kernel wire literal `{items}` and
+ * leaves room for future top-level additions (e.g.,
+ * `mode: "atomic" | "best-effort"`) without a breaking change.
+ *
+ * The SDK validates that `input` is an object and `input.items` is an
+ * array (synchronously, before any fetch). It does NOT pre-cap the
+ * length client-side — the kernel's `.min(1).max(500)` is the schema
+ * authority — and it does NOT recursively validate `items[i]` shapes
+ * (symmetric to ingest's `frameworkClaims` / `toolInvocations` policy
+ * — `.strict()` Zod is the kernel-side authority).
+ */
+export interface DecisionBulkInput {
+    /**
+     * 1-500 entries. Each item is the same shape as `decisions.ingest`
+     * input. Bulk does NOT recover from idempotency races — failed items
+     * with `code === "idempotency_unique_violation"` should be retried
+     * individually via `decisions.ingest` to invoke the per-record race
+     * recovery path.
+     */
+    items: DecisionIngestInput[];
+}
+/**
+ * One inserted-record summary in `BulkIngestResult.inserted[]`. Slim by
+ * design — matches the kernel's bulk-ingest summary (no heavy fields
+ * like `frameworkClaims` / `canonicalPayload`). Call
+ * `decisions.retrieve(id)` if the caller needs the full record.
+ *
+ * Sorted by original input `index` server-side so the caller can map
+ * each entry back to the position in the submitted `items[]` array.
+ */
+export interface BulkInsertedSummary {
+    /** Position in the submitted `items[]` array (zero-based). */
+    index: number;
+    /** UUID of the persisted decision record. */
+    id: string;
+    systemId: string;
+    /** Per-system monotonic sequence assigned at insert time. */
+    sequenceNumber: number;
+    /** sha256:[a-f0-9]{64} format. */
+    recordHash: string;
+    /**
+     * ISO-8601 timestamp string. (Kernel emits a `Date`; `JSON.stringify`
+     * converts it to the wire string.)
+     */
+    createdAt: string;
+}
+/**
+ * One failed-record summary in `BulkIngestResult.failed[]`. The whole
+ * chunk a record belonged to fails together (kernel groups records into
+ * fixed-size chunks under one `chain_heads` lock; a chunk is all-or-
+ * nothing), but other chunks for the same system OR other systems
+ * continue. Sorted by original input `index` server-side.
+ */
+export interface BulkFailedSummary {
+    /** Position in the submitted `items[]` array (zero-based). */
+    index: number;
+    systemId: string;
+    /** Human-readable per-record error message. */
+    error: string;
+    /**
+     * Machine-readable per-record code. Source of truth: kernel
+     * `classifyChunkError` in `src/lib/decisions/bulk-ingest.ts:114-156`.
+     * Today's possible values:
+     *
+     *   - `"idempotency_conflict"` — same idempotencyKey, different
+     *     canonical bytes (within a chunk).
+     *   - `"payload_too_large"` — one record's canonical bytes exceed
+     *     the 256KB per-record cap.
+     *   - `"chain_head_missing"` — internal invariant violation (should
+     *     never fire in practice).
+     *   - `"system_not_found"` — cross-org system OR cross-system
+     *     `attestationId`. Collapsed deliberately for enumeration safety
+     *     (matches single-record ingest behavior).
+     *   - `"ijson_validation_failed"` — per-record canonicalize tripped
+     *     on NaN/Infinity/BigInt/undefined/Symbol.
+     *   - `"idempotency_unique_violation"` — race condition. Bulk does
+     *     NOT recover; retry via `decisions.ingest` (single-record
+     *     endpoint) to invoke the per-record race-recovery path.
+     *   - `"chunk_failed"` — catch-all for unclassified chunk-tx
+     *     failures.
+     *
+     * Typed as `string` (NOT a literal-union) for forward-compat — same
+     * convention as `DecisionRecord.humanOversightState` and
+     * `DecisionStreamEvent.eventType`. Future kernel additions slot in
+     * cleanly without an SDK bump.
+     */
+    code: string;
+}
+/**
+ * Result envelope returned by `decisions.bulk()`. The transport
+ * unwraps the kernel's `{success:true, data}` JSON envelope — the
+ * caller receives this shape directly.
+ *
+ * **Critical contract**: `decisions.bulk()` resolves successfully (no
+ * throw) even when every record failed. Inspect `totalFailed` and
+ * `failed[]` to detect per-record errors. Top-level failures (auth,
+ * rate limit, plan limit, oversize batch) DO throw `AttestryAPIError`
+ * with the corresponding HTTP status.
+ */
+export interface BulkIngestResult {
+    /** Number of items in the submitted `items[]` array. */
+    totalSubmitted: number;
+    /** Number of records persisted to the chain. Equals `inserted.length`. */
+    totalInserted: number;
+    /** Number of records that failed. Equals `failed.length`. */
+    totalFailed: number;
+    /** Sorted by original input `index`. */
+    inserted: BulkInsertedSummary[];
+    /** Sorted by original input `index`. */
+    failed: BulkFailedSummary[];
+}
+/**
+ * Slim row returned by the list endpoint. Mirrors the kernel's
+ * `DecisionListItem` (in `src/lib/decisions/list-query.ts`) — a subset
+ * of the full `DecisionRecord`, deliberately excluding heavy fields
+ * (`canonicalPayload` BYTEA, `manifestVersionId`, `attestationId`,
+ * `clientSignature`, `clientKeyId`, `idempotencyKey`, `zkProof`,
+ * `tombstonedAt`, `tombstonedReason`, `orgId`).
+ *
+ * jsonb arrays are typed as `unknown[]` for forward-compat — same
+ * convention as `DecisionRecord`. `createdAt` is the wire-shape ISO
+ * string (kernel `Date` → JSON.stringify → string).
+ *
+ * Use `decisions.retrieve(id)` if you need the full record (e.g.,
+ * verifying a signature with `clientSignature` / `clientKeyId`).
+ */
+export interface DecisionListItem {
+    id: string;
+    systemId: string;
+    /** Per-system monotonic sequence (notNull on the kernel side). */
+    sequenceNumber: number;
+    /** sha256:[a-f0-9]{64} format. */
+    inputDigest: string;
+    /** sha256:[a-f0-9]{64} OR null when output isn't recorded. */
+    outputDigest: string | null;
+    frameworkClaims: unknown[];
+    toolInvocations: unknown[];
+    delegationChain: unknown[];
+    humanOversightState: string | null;
+    policyOutcome: string | null;
+    /** Hash of (prev_record_hash || canonical_payload). */
+    recordHash: string;
+    /** Null on the first record in the chain. */
+    prevRecordHash: string | null;
+    /** ISO-8601 timestamp string. */
+    createdAt: string;
+    tombstoned: boolean;
+}
+/**
+ * Filter / pagination inputs for `decisions.list()`. All fields optional;
+ * a bare `decisions.list()` call returns the most-recent page (default
+ * 50) of the org's records.
+ *
+ * Pagination is keyset-based: pass back `response.nextCursor` as
+ * `input.cursor` to fetch the next page. The cursor format is opaque
+ * to the SDK — kernel encodes/decodes it.
+ *
+ * Filters:
+ *   - `systemId`: limit to one system's records
+ *   - `from` / `to`: ISO datetime range filters on `createdAt`
+ *   - `framework` / `article`: jsonb-contains filters on `frameworkClaims`
+ *   - `tool`: jsonb-contains filter on `toolInvocations`
+ *   - `includeTombstoned`: include soft-deleted records (default false)
+ *   - `limit`: page size, 1-200, default 50
+ */
+export interface DecisionsListInput {
+    systemId?: string;
+    /** ISO datetime — `createdAt >= from`. */
+    from?: string;
+    /** ISO datetime — `createdAt <= to`. */
+    to?: string;
+    /** Filter by `frameworkClaims[].framework`. 1-100 chars. */
+    framework?: string;
+    /** Filter by `frameworkClaims[].article`. 1-100 chars. */
+    article?: string;
+    /** Filter by `toolInvocations[].name`. 1-200 chars. */
+    tool?: string;
+    /** Opaque cursor from a prior response's `nextCursor`. */
+    cursor?: string;
+    /** Page size, 1-200, default 50. */
+    limit?: number;
+    /** Include soft-deleted records. Default false. */
+    includeTombstoned?: boolean;
+}
+export interface DecisionsListResponse {
+    items: DecisionListItem[];
+    /**
+     * Cursor for the next page. `null` (NOT undefined) when no more pages
+     * exist — matches the kernel wire shape exactly. Pass as
+     * `input.cursor` on the next call to fetch the following page.
+     */
+    nextCursor: string | null;
+}
+/**
+ * Public stream event types. Today the kernel emits exactly one
+ * (`decision.appended`) — extracted as `as const` so consumers can
+ * iterate, narrow, and so the drift-detection pin in
+ * `src/lib/incidents/__tests__/sdk-drift.test.ts` can compare
+ * structurally against the kernel's `formatSSEFrame` default. When the
+ * kernel adds a new event type (e.g. `decision.tombstoned`), update
+ * BOTH this array AND the kernel emitter, and bump the SDK minor.
+ */
+export declare const DECISION_STREAM_EVENT_TYPES: readonly ["decision.appended"];
+export type DecisionStreamEventType = (typeof DECISION_STREAM_EVENT_TYPES)[number];
+/**
+ * One event yielded by `decisions.stream()`. Mirrors the kernel's
+ * `DecisionStreamEvent` (in `src/lib/decisions/stream-cursor.ts`) but
+ * `createdAt` is an ISO-8601 string (the wire shape — kernel emits
+ * `event.createdAt.toISOString()` in `formatSSEFrame`), and two
+ * SSE-level fields are surfaced for reconnection:
+ *
+ *   - `eventId`: the value from the SSE `id:` line. Pass this back as
+ *     `input.lastEventId` on a subsequent `stream()` call to resume.
+ *     The kernel's cursor format is opaque to the SDK (today it's a
+ *     base64url-encoded `{c, i}` JSON, but the SDK does not parse it).
+ *   - `eventType`: the value from the SSE `event:` line. Currently
+ *     always `"decision.appended"`; surfaced for forward-compat with
+ *     future event types (e.g. `"decision.tombstoned"`).
+ *
+ * Slim by design — clients call `decisions.retrieve(id)` for the full
+ * record (including `frameworkClaims`, `delegationChain`, etc., which
+ * the stream endpoint omits to keep frames small).
+ */
+export interface DecisionStreamEvent {
+    /** Decision record id (UUID). */
+    id: string;
+    /** System the decision was made for (UUID). */
+    systemId: string;
+    /** Per-system monotonic sequence number. */
+    sequenceNumber: number;
+    /** sha256:[a-f0-9]{64} format. */
+    recordHash: string;
+    /** Null on the first record in the chain. */
+    prevRecordHash: string | null;
+    /** True if the record has been tombstoned. */
+    tombstoned: boolean;
+    /** ISO-8601 timestamp string. */
+    createdAt: string;
+    /**
+     * SSE `id:` field — pass back as `input.lastEventId` to resume.
+     * Always a non-empty string (the SDK validates the frame had a
+     * non-empty `id:` line; throws `AttestryError` if not).
+     */
+    eventId: string;
+    /**
+     * SSE `event:` field. Today always `"decision.appended"` (the only
+     * type emitted by the kernel — see `DECISION_STREAM_EVENT_TYPES`).
+     * Typed as `string` rather than the literal-union for forward-compat:
+     * a future kernel patch can add a new event type and consumer code
+     * that does `if (event.eventType === 'decision.tombstoned')` keeps
+     * compiling without an SDK bump (the consumer just needs to know
+     * about the new type).
+     */
+    eventType: string;
+}
+/**
+ * Filters / resume cursor for `decisions.stream()`. All fields optional:
+ * a fresh `stream()` call with no args subscribes to the entire org's
+ * stream from "now" forward.
+ *
+ * Lifecycle:
+ *   1. First call with `lastEventId` undefined → start at "now", no
+ *      historical replay. Server only emits events created AFTER the
+ *      connection opens.
+ *   2. Server emits events. Each event carries `eventId` (the resume
+ *      cursor) — store the latest.
+ *   3. On disconnect (network drop, server timeout, deliberate abort),
+ *      call `stream({ lastEventId: lastSeen.eventId, ... })` to resume —
+ *      server backfills every event after the cursor before resuming
+ *      live polling.
+ *
+ * Validation: the SDK validates that `systemId` and `lastEventId` are
+ * non-empty strings if provided (catches `null`/empty programming
+ * errors). Format validation (UUID for systemId, base64url cursor for
+ * lastEventId) is the server's job — the server returns 400 on
+ * malformed input.
+ */
+export interface DecisionsStreamInput {
+    /** Filter to a single system's events. UUID format. */
+    systemId?: string;
+    /** Resume cursor — typically the `eventId` of the last seen event. */
+    lastEventId?: string;
+}
+/**
+ * Filter inputs for `decisions.export()`. `systemId` is REQUIRED — the
+ * kernel scopes export to a single system's chain (no cross-system
+ * exports). Date filters optional. No pagination — the response streams.
+ *
+ * Validation: SDK validates field TYPES synchronously (throws
+ * `TypeError` BEFORE issuing any request). Format checks (UUID, ISO
+ * datetime) deferred to the server's Zod schema (`decisionExportQuerySchema`).
+ */
+export interface DecisionsExportInput {
+    /** REQUIRED — UUID. The system whose chain to export. */
+    systemId: string;
+    /** Optional — ISO datetime, `createdAt >= from`. */
+    from?: string;
+    /** Optional — ISO datetime, `createdAt <= to`. */
+    to?: string;
+    /** Optional — include soft-deleted records. Default false. */
+    includeTombstoned?: boolean;
+}
+/**
+ * Per-record frame yielded by `decisions.export()`. Structurally
+ * IDENTICAL to `DecisionListItem` — same field names, same types, same
+ * null-vs-undefined semantics. Reusing the existing exported type
+ * (rather than redefining) signals to consumers that `decisions.list`
+ * and `decisions.export` emit interchangeable rows. Kernel-side, the
+ * `ExportRecord` shape was deliberately aligned with the list-row
+ * projection to enable this type identity.
+ *
+ * Build-round D2.
+ */
+export type DecisionExportRecord = DecisionListItem;
+/**
+ * Final frame in a `decisions.export()` stream. Distinguishes itself
+ * from records via the `type: "ExportTrailer"` discriminator. The
+ * kernel emits exactly one trailer at the end of every successful
+ * stream — including empty exports (recordCount === 0).
+ *
+ * The trailer commits the export to a single Merkle root over the
+ * per-record `recordHash` leaves (Bitcoin-style binary Merkle, with
+ * empty-export sentinel `sha256("ATTESTRY-EMPTY-EXPORT")`). Verifying
+ * the commitment is the consumer's responsibility — the SDK exposes
+ * the trailer raw without recomputation.
+ */
+export interface DecisionExportTrailer {
+    /** Discriminator — distinguishes the trailer from records. */
+    type: "ExportTrailer";
+    /** UUID — the systemId from the export filter. */
+    systemId: string;
+    /** Number of records that streamed before the trailer. >= 0. */
+    recordCount: number;
+    /** First record's `sequenceNumber`. `null` on empty export. */
+    sequenceFrom: number | null;
+    /** Last record's `sequenceNumber`. `null` on empty export. */
+    sequenceTo: number | null;
+    /**
+     * `sha256:[a-f0-9]{64}` format. Bitcoin-style binary Merkle root over
+     * the per-record `recordHash` leaves (in `sequenceNumber` ascending
+     * order). Empty-export sentinel: `sha256:` + hex of
+     * `sha256("ATTESTRY-EMPTY-EXPORT")`. SDK does NOT recompute — the
+     * caller (post-Prompt-1) verifies independently.
+     */
+    merkleRoot: string;
+    /**
+     * Today: literal string `"unsigned-prompt-1-blocked"`. Once Prompt 1
+     * (Ed25519 signing) ships, the kernel will replace this field with
+     * a structured `proof` value carrying an `eddsa-jcs-2022` signature
+     * over the canonical trailer bytes. Typing as `string` (rather than
+     * a literal-union) accommodates that transition without an SDK bump
+     * — same forward-compat convention as `BulkFailedSummary.code`,
+     * `humanOversightState`, and `eventType`. Build-round D1.
+     *
+     * SDK does NOT attempt signature verification — caller is
+     * responsible (post-Prompt-1).
+     */
+    signing: string;
+    /** ISO-8601 timestamp string. */
+    generatedAt: string;
+}
+/**
+ * Discriminated union of frames in the export stream. Records arrive
+ * first (in `sequenceNumber` ascending order), then exactly one trailer.
+ * Caller branches on the trailer:
+ *
+ * @example
+ * ```ts
+ * for await (const frame of client.decisions.export({ systemId })) {
+ *   if ("type" in frame && frame.type === "ExportTrailer") {
+ *     // Final frame — record count + Merkle root commit + signing field.
+ *     console.log(`exported ${frame.recordCount} records, root=${frame.merkleRoot}`);
+ *   } else {
+ *     // Per-record frame — DecisionListItem shape.
+ *     console.log(frame.id, frame.sequenceNumber, frame.recordHash);
+ *   }
+ * }
+ * ```
+ *
+ * Build-round D3 (Option A: yield typed frames, vs Option B: two-phase
+ * records + trailer-Promise API). Mirrors wire shape; symmetric to
+ * `decisions.stream`.
+ */
+export type DecisionExportFrame = DecisionExportRecord | DecisionExportTrailer;
+/**
+ * Result of `client.decisions.verifyChain(systemId)`. Source-of-truth
+ * lives kernel-side at `src/lib/decisions/chain-verification.ts:20-49`.
+ *
+ * **Critical contract**: this shape is returned for BOTH valid and
+ * invalid chains. `chainValid: false` is NOT an error — the kernel
+ * answered the customer's question (is this chain tampered?) and the
+ * SDK resolves the Promise with the verdict body. Top-level structural
+ * failures (auth, rate limit, system-not-found, ChainTooLong) throw
+ * `AttestryAPIError`. Carry-forward invariant #12.
+ *
+ * The two ID arrays distinguish two failure modes:
+ *   - `tamperedRecordIds`: stored `recordHash` doesn't match the
+ *     recomputed hash of `canonicalPayload` — direct content tampering
+ *     (security signal, fires `chain.tampered` webhook).
+ *   - `brokenRecordIds`: `prevRecordHash` doesn't match the running
+ *     watermark — gap in the sequence (ops signal: record deleted /
+ *     missing; fires `chain.broken` webhook). Both can be non-empty
+ *     simultaneously; `chain.tampered` takes precedence at webhook
+ *     dispatch but BOTH arrays appear in this response.
+ */
+export interface ChainVerificationResult {
+    /** UUID of the system whose chain was verified. */
+    systemId: string;
+    /** Total rows replayed (active + tombstoned). */
+    recordCount: number;
+    /** Records with `tombstoned: false`. */
+    activeRecordCount: number;
+    /** Records with `tombstoned: true`. */
+    tombstonedRecordCount: number;
+    /**
+     * `true` iff every record's `recordHash` matches the recomputed hash
+     * AND every record's `prevRecordHash` matches the running watermark.
+     * Empty chains verify as `true` (vacuous truth).
+     */
+    chainValid: boolean;
+    /**
+     * Sequence number of the last record before tampering was first
+     * detected. Equals the highest sequence on a valid chain; one less
+     * than the first tampered/broken record's sequence on an invalid
+     * chain (so callers can show "verified up to sequence N"). `0` on
+     * empty chains AND when the very first record fails verification.
+     */
+    lastVerifiedSequence: number;
+    /**
+     * ISO-8601 string captured by the kernel at the end of verification
+     * (`new Date().toISOString()`). Wire is a STRING, not a `Date`
+     * instance. Parse via `new Date(value)` if needed.
+     */
+    lastVerifiedAt: string;
+    /**
+     * Record IDs whose stored `recordHash` doesn't match the recomputed
+     * hash of their `canonicalPayload` — direct content tampering
+     * (security signal). Empty array on a valid chain. Triggers the
+     * `chain.tampered` webhook server-side.
+     */
+    tamperedRecordIds: string[];
+    /**
+     * Record IDs whose `prevRecordHash` doesn't match the running
+     * watermark — gap in the sequence (ops signal: record deleted /
+     * missing). Empty array on a valid chain. Triggers the
+     * `chain.broken` webhook server-side. Distinct from
+     * `tamperedRecordIds` — both can be non-empty (tampered takes
+     * precedence in webhook event selection but both arrays appear in
+     * the webhook payload AND in this response).
+     */
+    brokenRecordIds: string[];
+    /**
+     * Server-side observability counters. Authoritative — the SDK does
+     * NOT add its own timer.
+     */
+    performanceMetrics: {
+        /** Wall-clock duration of the replay loop, milliseconds. */
+        verificationDurationMs: number;
+        /**
+         * Rounded throughput. `0` on empty chains AND on sub-millisecond
+         * verifications (kernel guards divide-by-zero). The SDK preserves
+         * the kernel's value verbatim — does NOT recompute.
+         */
+        recordsPerSecond: number;
+    };
+}
+export declare class DecisionsResource {
+    private readonly client;
+    constructor(client: AttestryClient);
+    /**
+     * Retrieve one decision record by id.
+     *
+     * Server returns 400 for malformed UUIDs and 404 for not-found OR
+     * cross-org records (deliberate conflation — see route docstring).
+     * Both surface as `AttestryAPIError` with the corresponding status.
+     *
+     * Throws `TypeError` synchronously for invalid `id` BEFORE issuing
+     * a request — empty string, non-string, lone-surrogate UTF-16, or
+     * path-traversal segments (`"."` / `".."` / strings containing
+     * `\0`) all reject. The path-traversal guard exists because
+     * `encodeURIComponent` does NOT encode `.` or `..`, and `fetch`'s
+     * URL normalization would collapse `retrieve("..")` to the LIST
+     * endpoint at `/api/v1/decisions/` — silently redirecting to a
+     * different resource. Hostile-review F1 (cross-resource fix
+     * symmetric to `decisions.verifyChain`); validation centralized in
+     * the shared `encodePathSegment` helper.
+     *
+     * Rejects with `AttestryError` (P2 hardening) if the kernel emits
+     * a non-object response shape (`null`, scalar, or array). Rejects
+     * with `AttestryAPIError` (P3 hardening) if the kernel responds
+     * with a non-`application/json` Content-Type — protects against
+     * proxy-injected HTML 200 pages parsing into junk consumer state.
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<DecisionRecord>;
+    /**
+     * Append a decision record to the org's append-only hash chain.
+     *
+     * Wraps `POST /api/v1/decisions`. Returns the persisted record (with
+     * `canonicalPayload` BYTEA omitted — the kernel's `toResponseShape()`
+     * helper drops it from the wire response since the client already has
+     * the input digest for verification).
+     *
+     * **Idempotency replay**: subsequent calls with the same
+     * `idempotencyKey` AND identical canonical payload return the SAME
+     * record (server returns HTTP 200 `decision.idempotency_replay`; SDK
+     * resolves the same `Promise<DecisionRecord>` as a fresh insert,
+     * which returns 201). Different payload with the same key throws
+     * `AttestryAPIError` with `status === 409`
+     * `decision.idempotency_conflict`. Status-code distinction is NOT
+     * surfaced in the SDK return type — both 2xx resolve identically.
+     *
+     * **At-least-once delivery**: pass an `idempotencyKey` to make
+     * 429-retries safe under network failure. Without one, a retry that
+     * succeeds-but-loses-the-response could create a duplicate record.
+     * Body is re-stringified per attempt (carry-forward invariant #4).
+     *
+     * **Plan limits (402)**: when the org has exhausted its
+     * `decisionsPerMonth` quota, the kernel throws `PlanLimitError`
+     * (mapped to HTTP 402). The SDK surfaces it as `AttestryAPIError`
+     * with `status === 402` and `details: {feature, currentPlan,
+     * upgradeRequired}` — the structured body lets dashboards route the
+     * user straight to the upgrade flow (B.1 carry-forward).
+     *
+     * Errors:
+     *   - `AttestryAPIError` (status 401) — auth required
+     *   - `AttestryAPIError` (status 402) — plan limit (with
+     *     `details.feature` / `details.currentPlan` /
+     *     `details.upgradeRequired`)
+     *   - `AttestryAPIError` (status 404) — system not found OR cross-org
+     *     attestation (collapsed deliberately to prevent enumeration)
+     *   - `AttestryAPIError` (status 409) — idempotency conflict (same
+     *     key, different payload)
+     *   - `AttestryAPIError` (status 413) — canonical payload exceeds 256KB
+     *   - `AttestryAPIError` (status 422) — Zod validation failed (field
+     *     errors in `details`) OR I-JSON validation failed (NaN /
+     *     Infinity / BigInt / undefined / Symbol — `details.path` names
+     *     the offending field) OR refine-clause failed
+     *     (clientSignature/clientKeyId pairing)
+     *   - `AttestryAPIError` (status 429) — rate limit (auto-retried by
+     *     default — invariant #18)
+     *   - `AttestryAPIError` (status 500) — internal invariant violation
+     *     (chain head missing — should never fire in practice)
+     *   - `AttestryError` ("invalid request body: ...") — body
+     *     serialization failed (BigInt, circular reference) BEFORE fetch
+     *     (carry-forward invariant #4)
+     *   - `AttestryError` ("request aborted by caller") — caller-supplied
+     *     `options.signal` fired (pre-aborted or mid-flight)
+     *   - `TypeError` (synchronous, no fetch issued) — input failed SDK-
+     *     side type validation (see below)
+     *
+     * SDK-side validation (synchronous `TypeError`, no fetch issued):
+     *   - `input` itself: must be a non-null, non-array object
+     *   - `systemId` / `inputDigest`: required non-empty strings
+     *   - Optional string fields: when provided, must be non-empty strings
+     *     (outputDigest, attestationId, clientSignature, clientKeyId,
+     *     idempotencyKey, humanOversightState, policyOutcome)
+     *   - Optional array fields: when provided, must be `Array.isArray`
+     *     (frameworkClaims, toolInvocations, delegationChain). Empty
+     *     arrays pass through.
+     *   - Optional `zkProof`: when provided, must be a non-null,
+     *     non-array object.
+     *
+     * **Format validation deferred to server** (UUID, hash regex,
+     * base64, enum membership, length caps, refine pairing,
+     * inner-array shape, inner-zkProof shape). Decision D5 in the
+     * build-round audit.
+     *
+     * @example
+     * ```ts
+     * const record = await client.decisions.ingest({
+     *   systemId: "550e8400-e29b-41d4-a716-446655440000",
+     *   inputDigest: "sha256:abc123...",
+     *   frameworkClaims: [
+     *     { framework: "eu_ai_act", article: "Art.13", claim: "human oversight provided" },
+     *   ],
+     *   humanOversightState: "approved",
+     *   policyOutcome: "permitted",
+     *   idempotencyKey: "ingest-2026-05-06-trace-789",  // safe retries
+     * });
+     * console.log(record.id, record.sequenceNumber, record.recordHash);
+     * ```
+     */
+    ingest(input: DecisionIngestInput, options?: RequestOptions): Promise<DecisionRecord>;
+    /**
+     * Append up to 500 decision records in a single request, with a
+     * partial-success envelope.
+     *
+     * Wraps `POST /api/v1/decisions/bulk`. Returns a `BulkIngestResult`
+     * describing which records persisted and which failed — the call
+     * **resolves successfully even when every record failed**. Partial
+     * success is the entire point of the endpoint; the caller branches on
+     * `result.totalFailed` (or `result.failed.length`) if they care about
+     * per-record errors. Top-level failures (auth, rate limit, plan limit,
+     * oversize batch) DO throw `AttestryAPIError` with the corresponding
+     * HTTP status.
+     *
+     * **Per-record codes** — see `BulkFailedSummary.code` JSDoc for the
+     * full list. Most relevant for retries:
+     *   - `"idempotency_unique_violation"`: race condition. Bulk does NOT
+     *     auto-recover — retry the failed record individually via
+     *     `decisions.ingest()` to invoke per-record race recovery.
+     *   - `"system_not_found"`: cross-org system OR cross-system
+     *     attestationId. Collapsed for enumeration safety.
+     *
+     * **At-least-once delivery**: pass an `idempotencyKey` on every item.
+     * A 429-retry of the same batch then returns duplicates as
+     * `failed[i].code === "idempotency_unique_violation"`; other items
+     * insert normally. Without per-item keys, a retry that succeeds-but-
+     * loses-the-response can create duplicate records.
+     *
+     * **Plan limits (402)**: the kernel checks the FULL batch size against
+     * the org's `decisionsPerMonth` quota. A 100-record batch with 50
+     * quota remaining is rejected wholesale (none persisted) — partial
+     * quota fills are a reconciliation hazard. The 402 carries the same
+     * `details: {feature, currentPlan, upgradeRequired}` shape as
+     * `decisions.ingest` (B.1 carry-forward).
+     *
+     * Errors:
+     *   - `AttestryAPIError` (status 401) — auth required
+     *   - `AttestryAPIError` (status 402) — plan limit (with
+     *     `details.feature` / `details.currentPlan` /
+     *     `details.upgradeRequired`)
+     *   - `AttestryAPIError` (status 413) — defensive top-level batch
+     *     size guard (>500 items). Verbatim message: `"Bulk ingest
+     *     limited to 500 records per request"`. In practice the kernel's
+     *     Zod `.max(500)` fires first with a 422; this 413 only surfaces
+     *     if the schema is bypassed.
+     *   - `AttestryAPIError` (status 422) — Zod validation failed (one or
+     *     more `items` malformed; OR top-level Zod fails for >500 items
+     *     OR empty array — server's `.min(1).max(500)`).
+     *   - `AttestryAPIError` (status 429) — rate limit (auto-retried by
+     *     default — invariant #18). Body re-stringified per attempt.
+     *   - `AttestryError` ("invalid request body: ...") — body
+     *     serialization failed (BigInt, circular reference) BEFORE fetch
+     *     (carry-forward invariant #4)
+     *   - `AttestryError` ("request aborted by caller") — caller-supplied
+     *     `options.signal` fired (pre-aborted or mid-flight)
+     *   - `TypeError` (synchronous, no fetch issued) — input failed SDK-
+     *     side type validation (see below)
+     *
+     * Notably ABSENT from the top-level error chain (vs `decisions.ingest`):
+     *   - 404 (system not found) → per-record `failed[i].code === "system_not_found"`
+     *   - 409 (idempotency conflict) → per-record `code === "idempotency_conflict"`
+     *   - 500 (chain head missing) → per-record `code === "chain_head_missing"`
+     *
+     * SDK-side validation (synchronous `TypeError`, no fetch issued):
+     *   - `input` itself: must be a non-null, non-array object
+     *   - `input.items`: required, must be `Array.isArray`
+     *
+     * **Format and per-item validation deferred to server**. The SDK does
+     * NOT pre-cap `items.length` at 500 (kernel's `.max(500)` is the
+     * authority — a future cap raise would otherwise require an SDK
+     * change). It does NOT recurse into `items[i]` to validate per-record
+     * shape (symmetric to ingest's `frameworkClaims` / `toolInvocations`
+     * policy — server's `.strict()` Zod is the schema authority).
+     *
+     * @example
+     * ```ts
+     * const result = await client.decisions.bulk({
+     *   items: [
+     *     { systemId, inputDigest, idempotencyKey: "trace-001" },
+     *     { systemId, inputDigest, idempotencyKey: "trace-002" },
+     *   ],
+     * });
+     * console.log(`${result.totalInserted}/${result.totalSubmitted} succeeded`);
+     * for (const failure of result.failed) {
+     *   if (failure.code === "idempotency_unique_violation") {
+     *     // retry via single-record endpoint to invoke race recovery
+     *     await client.decisions.ingest(originalItems[failure.index]);
+     *   }
+     * }
+     * ```
+     */
+    bulk(input: DecisionBulkInput, options?: RequestOptions): Promise<BulkIngestResult>;
+    /**
+     * List decision records the caller can see, cursor-paginated.
+     *
+     * Pagination is keyset-based over `(createdAt DESC, id DESC)` —
+     * identical-microsecond timestamps don't cause skipped rows. Pass
+     * back `response.nextCursor` as `input.cursor` to fetch the next page.
+     *
+     * Returns a slim per-row shape (`DecisionListItem`) — subset of
+     * `DecisionRecord`, deliberately omitting heavy fields. Call
+     * `decisions.retrieve(id)` for the full record.
+     *
+     * Errors:
+     *   - `AttestryAPIError` (status 400) — malformed cursor (server-side)
+     *   - `AttestryAPIError` (status 401) — auth required
+     *   - `AttestryAPIError` (status 403) — api-key missing `read:assessments`
+     *   - `AttestryAPIError` (status 422) — invalid query parameters
+     *   - `AttestryAPIError` (status 429) — rate limit (auto-retried by default)
+     *
+     * SDK-side validation (throws `TypeError` synchronously):
+     *   - Each optional string field (systemId, from, to, framework,
+     *     article, tool, cursor) must be a non-empty string when provided.
+     *     Format validation (UUID, ISO date) is deferred to the server.
+     *   - `limit` must be a number when provided.
+     *   - `includeTombstoned` must be a boolean when provided.
+     *
+     * Response-shape validation (P2 hardening):
+     *   - Rejects with `AttestryError` if the kernel response isn't a
+     *     non-null object, lacks an `items` array, or has a `nextCursor`
+     *     that isn't a string-or-null. Per-row shape is faithful-courier
+     *     (NOT validated — P4 candidate).
+     *
+     * Transport-shape validation (P3 hardening):
+     *   - Rejects with `AttestryAPIError` if the kernel responds with a
+     *     non-`application/json` Content-Type — protects against
+     *     proxy-injected HTML 200 pages parsing into junk consumer state.
+     *
+     * @example
+     * ```ts
+     * let cursor: string | undefined;
+     * for (let page = 0; page < 100; page++) {
+     *   const { items, nextCursor } = await client.decisions.list({
+     *     systemId,
+     *     limit: 50,
+     *     cursor,
+     *   });
+     *   for (const item of items) console.log(item.id, item.sequenceNumber);
+     *   if (nextCursor === null) break;
+     *   cursor = nextCursor;
+     * }
+     * ```
+     */
+    list(input?: DecisionsListInput, options?: RequestOptions): Promise<DecisionsListResponse>;
+    /**
+     * Subscribe to decision-record events as they're appended.
+     *
+     * Returns an `AsyncIterable<DecisionStreamEvent>` — consume with
+     * `for await (const event of stream)`. Errors THROW (the iterator
+     * surfaces them via the for-await loop's natural error path), in
+     * contrast to `chat.stream()` which yields error chunks. Reason:
+     *
+     *   - `chat.stream()` is a request/response (one POST → one iterator).
+     *     Yielding errors inline lets consumers render them in the same UI
+     *     stream as the assistant's text.
+     *   - `decisions.stream()` is a long-lived subscription. An error
+     *     means the connection is gone — yielding inline would force every
+     *     consumer to write `if (chunk.type === 'error') break;`. Throwing
+     *     gives clean `try/catch` semantics with typed error classes
+     *     (`AttestryAPIError` for 4xx/5xx, `AttestryError` for network /
+     *     abort).
+     *
+     * Errors surface as:
+     *   - `AttestryAPIError` (status 401) — auth failed
+     *   - `AttestryAPIError` (status 403) — insufficient permissions
+     *     (api keys need `read:assessments` scope)
+     *   - `AttestryAPIError` (status 400) — malformed `systemId` or
+     *     `lastEventId` (server-side validation)
+     *   - `AttestryAPIError` (status 429) — rate limited
+     *   - `AttestryError` ("request aborted by caller") — caller-provided
+     *     `options.signal` fired (pre-abort or mid-iteration)
+     *   - `AttestryError` ("network error: ...") — fetch-level failure
+     *     before any frame; OR mid-stream connection drop (surfaces from
+     *     the underlying reader, wrapped during iteration)
+     *   - `AttestryError` ("SSE frame data was not valid JSON: ...") —
+     *     defensive; the kernel always emits valid JSON in `data:` lines.
+     *
+     * Reconnection: the iterator does NOT auto-reconnect. On any error or
+     * clean termination (server-side 5min timeout closes the connection),
+     * the for-await loop ends. The caller then decides whether to call
+     * `stream({lastEventId: lastSeen.eventId})` to resume.
+     *
+     * Lazy: the request is NOT issued until the first iteration. Pass
+     * `options.signal` for cancellation — pre-aborted causes the first
+     * iteration to throw `AttestryError` with no fetch issued; mid-flight
+     * abort surfaces as `AttestryError` from the iterator.
+     *
+     * Heartbeat frames (`: heartbeat\n\n`) are silently consumed by the
+     * SSE parser and never yielded to the consumer.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   for await (const event of client.decisions.stream({ systemId })) {
+     *     console.log(event.id, event.sequenceNumber);
+     *     lastEventId = event.eventId; // for reconnection
+     *   }
+     * } catch (err) {
+     *   if (err instanceof AttestryAPIError && err.status === 401) {
+     *     // re-auth
+     *   } else if (err instanceof AttestryError) {
+     *     // network drop — wait + retry with lastEventId
+     *   }
+     * }
+     * ```
+     */
+    stream(input?: DecisionsStreamInput, options?: RequestOptions): AsyncIterable<DecisionStreamEvent>;
+    /**
+     * Export a system's decision chain as a streaming NDJSON response.
+     *
+     * Wraps `GET /api/v1/decisions/export`. Returns an
+     * `AsyncIterable<DecisionExportFrame>` — records arrive first (in
+     * `sequenceNumber` ascending order), then exactly one trailer that
+     * commits the batch to a Merkle root over per-record `recordHash`
+     * leaves.
+     *
+     * Errors **throw** from the iterator (long-lived stream semantics —
+     * symmetric with `decisions.stream`). Use `try / catch` around the
+     * for-await loop:
+     *
+     * @example
+     * ```ts
+     * try {
+     *   for await (const frame of client.decisions.export({ systemId })) {
+     *     if ("type" in frame && frame.type === "ExportTrailer") {
+     *       // Final commit — verify Merkle root client-side post-Prompt-1.
+     *       console.log(`${frame.recordCount} records, root=${frame.merkleRoot}`);
+     *     } else {
+     *       // Per-record line — DecisionListItem shape.
+     *       process(frame);
+     *     }
+     *   }
+     * } catch (err) {
+     *   if (err instanceof AttestryAPIError && err.status === 422) {
+     *     // bad systemId / unknown query / malformed datetime
+     *   } else if (err instanceof AttestryError) {
+     *     // network drop, parser error, missing trailer
+     *   }
+     * }
+     * ```
+     *
+     * **Empty export** — when the systemId has zero records (or doesn't
+     * exist / belongs to another org), the iterator yields a SINGLE
+     * frame: a trailer with `recordCount: 0`, `sequenceFrom: null`,
+     * `sequenceTo: null`, and the deterministic empty-export merkleRoot
+     * (`sha256:` + hex of `sha256("ATTESTRY-EMPTY-EXPORT")`). The SDK
+     * does NOT throw — the empty trailer is the kernel's success signal
+     * for "no data".
+     *
+     * **Missing trailer** — every successful 200 stream ends with a
+     * trailer. If the iterator exhausts without seeing one (mid-stream
+     * connection drop, kernel error after headers committed), the SDK
+     * throws `AttestryError("decisions.export: stream ended without
+     * trailer — connection dropped or server failed mid-stream")`. This
+     * surfaces a class of failures that the kernel can't return as 4xx
+     * (the response was already 200 by the time the error arose).
+     *
+     * **Trailer signing field** — today the trailer's `signing` field is
+     * the literal string `"unsigned-prompt-1-blocked"`. Once Prompt 1
+     * ships Ed25519 signing, the field is replaced by a structured proof.
+     * The SDK does NOT verify the signature — caller is responsible
+     * (post-Prompt-1).
+     *
+     * Errors:
+     *   - `AttestryAPIError` (status 401) — auth required
+     *   - `AttestryAPIError` (status 422) — invalid query (missing
+     *     systemId / unknown key / non-UUID systemId / malformed datetime)
+     *   - `AttestryAPIError` (status 429) — rate limit (auto-retried by
+     *     default — invariant #18; initial fetch only — invariant #20)
+     *   - `AttestryAPIError` — wrong content-type at 200 (proxy / LB
+     *     error page wrapped at 200)
+     *   - `AttestryError` ("decisions.export: stream ended without
+     *     trailer ...") — mid-stream failure detected at iterator end
+     *   - `AttestryError` ("network error during stream: ...") — TCP
+     *     drop / proxy hang-up mid-stream
+     *   - `AttestryError` ("request aborted by caller") — caller-supplied
+     *     `options.signal` fired (pre-aborted or mid-flight)
+     *   - `AttestryError` ("NDJSON line was not valid JSON: ...") —
+     *     defensive; the kernel always emits valid JSON
+     *   - `AttestryError` ("NDJSON line exceeded maximum buffer size ...") —
+     *     defensive; the kernel's per-record line is well below 1 MiB
+     *   - `TypeError` (synchronous, no fetch issued) — input failed
+     *     SDK-side type validation (see below)
+     *
+     * Notably ABSENT from the error surface:
+     *   - **No 402 plan-limit** — export is a READ, doesn't count against
+     *     the org's `decisionsPerMonth` quota.
+     *   - **No 404 system-not-found** — a non-existent or cross-org
+     *     systemId returns 200 with zero records and a trailer with
+     *     `recordCount: 0`. Consumers detect via the trailer.
+     *
+     * SDK-side validation (synchronous `TypeError`, no fetch issued):
+     *   - `input` itself: must be a non-null, non-array object
+     *   - `input.systemId`: required, non-empty string
+     *   - `input.from` / `input.to`: optional; non-empty string when provided
+     *   - `input.includeTombstoned`: optional; boolean when provided
+     *
+     * Format validation deferred to server (UUID, ISO datetime). The
+     * `includeTombstoned: false` boolean is forwarded LITERALLY (no
+     * workaround) — the kernel session-6 fix to `stringBoolean` accepts
+     * `"false"` correctly. Asymmetry from `decisions.list` (which still
+     * omits `false` as defense-in-depth) is deliberate — build-round D7.
+     *
+     * Lazy: the request is NOT issued until the first iteration. Pass
+     * `options.signal` for cancellation — pre-aborted causes the first
+     * iteration to throw `AttestryError` with no fetch issued; mid-flight
+     * abort surfaces as `AttestryError` from the iterator.
+     */
+    export(input: DecisionsExportInput, options?: RequestOptions): AsyncIterable<DecisionExportFrame>;
+    /**
+     * Replay a system's hash chain and report integrity verdict.
+     *
+     * Wraps `GET /api/v1/decisions/verify-chain/{systemId}`. Returns a
+     * `ChainVerificationResult` describing whether tampering was detected
+     * and which records (if any) failed which check.
+     *
+     * **Critical contract — partial-success envelope**: the kernel returns
+     * **HTTP 200 with `chainValid: false`** when tampering is detected.
+     * The SDK resolves the Promise with the verdict body — it does **NOT**
+     * throw on `chainValid: false`. The customer asked the chain-integrity
+     * question and the kernel answered; the SDK is a faithful courier.
+     * Top-level structural failures (auth, rate limit, system-not-found,
+     * `ChainTooLong`) DO throw `AttestryAPIError`. Carry-forward invariant
+     * #12; same family as `decisions.bulk` (200 with `totalFailed > 0`
+     * resolves rather than throws).
+     *
+     * **Failure-mode discrimination**: the two ID arrays are surfaced
+     * separately so consumers can route on the SECURITY-vs-OPS distinction
+     * at the call site (the kernel uses the same distinction to fire the
+     * `chain.tampered` vs `chain.broken` webhook):
+     *   - `tamperedRecordIds`: direct content tampering (security signal).
+     *   - `brokenRecordIds`: gap in the chain (ops signal — missing record).
+     * Both arrays can be non-empty simultaneously.
+     *
+     * **Side effect (out-of-band)**: the kernel dispatches one of three
+     * fire-and-forget webhooks AFTER the response body is built but BEFORE
+     * returning — `chain.verified` (when valid), `chain.tampered` (when
+     * `tamperedRecordIds.length > 0`), or `chain.broken` (when only
+     * `brokenRecordIds.length > 0`). The SDK does NOT see / verify these;
+     * they're surfaced through the webhooks resource (a different SDK
+     * surface). Consumers who want webhook-based observability subscribe
+     * via the kernel's webhook endpoints.
+     *
+     * **413 with export hint**: when the chain length exceeds
+     * `MAX_SYNC_CHAIN_LENGTH` (50,000 records), the kernel returns 413
+     * with the export-endpoint hint. The transport stores the entire
+     * parsed error body under `AttestryAPIError.details`, and the kernel's
+     * own structured `details` object nests inside — so the consumer-side
+     * access path is `err.details?.details?.hint` (double-`details`).
+     * Consumers detect this case via
+     * `error.details?.details?.hint?.includes("decisions/export")` and
+     * fall back to streaming the chain through `decisions.export()` for
+     * offline verification. The `ChainTooLongError` kernel class is
+     * internal; its 413 surface is what the SDK exposes.
+     *
+     * Errors:
+     *   - `AttestryAPIError` (status 400) — `systemId` failed server-side
+     *     UUID format check (`isValidUuid` rejects, NOT a Zod 422).
+     *   - `AttestryAPIError` (status 401) — auth required (no session
+     *     and no api-key).
+     *   - `AttestryAPIError` (status 403) — propagates if upstream
+     *     `AuthError` was thrown with a custom 403 statusCode (rare; the
+     *     route's default for cross-org systems is 404).
+     *   - `AttestryAPIError` (status 404) — system not found OR cross-org
+     *     system (deliberate enumeration-safety collapse, same shape as
+     *     retrieve / ingest).
+     *   - `AttestryAPIError` (status 413) — `ChainTooLong` (>50,000 records)
+     *     with `err.details?.details?.hint` referencing `/api/v1/decisions/export`.
+     *     (Double-`details`: transport stores the whole parsed body under
+     *     `.details`; the kernel's own `details` object nests inside.)
+     *   - `AttestryAPIError` (status 429) — rate limit (auto-retried by
+     *     default — invariant #18; per-IP `assessmentLimiter`).
+     *   - `AttestryAPIError` (status 500) — internal error with a SCRUBBED
+     *     message (no leak of the underlying kernel error). Surfaces e.g.
+     *     when the DB connection drops mid-verification.
+     *   - `AttestryError` ("request aborted by caller") — caller-supplied
+     *     `options.signal` fired (pre-aborted or mid-flight).
+     *   - `TypeError` (synchronous, no fetch issued) — `systemId` failed
+     *     SDK-side validation (empty / non-string / lone-surrogate /
+     *     path-traversal segment).
+     *
+     * Notably ABSENT from the error chain:
+     *   - **No 402 plan-limit** — verifyChain is a READ; doesn't count
+     *     against `decisionsPerMonth` quota.
+     *   - **No 422** — the only input is a path segment, validated as a
+     *     UUID via `isValidUuid` (which returns 400, not 422). No query
+     *     schema, no body schema, no Zod.
+     *
+     * SDK-side validation (synchronous `TypeError`, no fetch issued):
+     *   - `systemId`: must be a non-empty string.
+     *   - `systemId`: must NOT be the exact string `"."` or `".."` — these
+     *     survive `encodeURIComponent` but get collapsed by `fetch`'s
+     *     URL normalization into the parent endpoint, silently redirecting
+     *     the request to a different resource. NUL bytes (`\0`) also
+     *     rejected. Hostile-review F1.
+     *   - `systemId`: must be encodable via `encodeURIComponent` — lone
+     *     surrogates throw a synchronous `TypeError` with `cause: err`
+     *     wrapping the original `URIError`. Mirror of `decisions.retrieve`'s
+     *     L1 pattern (carry-forward invariant #32).
+     *
+     * **Format validation deferred to server** (UUID format check happens
+     * server-side via `isValidUuid`, returns 400).
+     *
+     * Response-shape validation (P2 hardening):
+     *   - Rejects with `AttestryError` if the kernel response isn't a
+     *     non-null object (`null`, scalar, or array). Per-field shape
+     *     (e.g. `chainValid: boolean`) is faithful-courier — NOT
+     *     validated.
+     *
+     * Transport-shape validation (P3 hardening):
+     *   - Rejects with `AttestryAPIError` if the kernel responds with a
+     *     non-`application/json` Content-Type. NOTE: `chainValid: false`
+     *     is a normal 200 response and resolves the promise (carry-forward
+     *     invariant #12); only structural failures throw.
+     *
+     * @example
+     * ```ts
+     * const verdict = await client.decisions.verifyChain(systemId);
+     * if (!verdict.chainValid) {
+     *   if (verdict.tamperedRecordIds.length > 0) {
+     *     // SECURITY signal: someone edited stored bytes / hashes.
+     *     await notifySecurity({ systemId, ids: verdict.tamperedRecordIds });
+     *   } else if (verdict.brokenRecordIds.length > 0) {
+     *     // OPS signal: a record went missing.
+     *     await notifyOps({ systemId, ids: verdict.brokenRecordIds });
+     *   }
+     * }
+     * console.log(`verified up to sequence ${verdict.lastVerifiedSequence}`);
+     *
+     * // 413 → fall back to export + offline verification:
+     * try {
+     *   await client.decisions.verifyChain(largeSystemId);
+     * } catch (err) {
+     *   if (err instanceof AttestryAPIError && err.status === 413) {
+     *     // err.details?.details?.hint references /api/v1/decisions/export
+     *     // (double-details: transport's wrap + kernel's structured detail)
+     *     for await (const frame of client.decisions.export({ systemId: largeSystemId })) {
+     *       // verify chain offline ...
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    verifyChain(systemId: string, options?: RequestOptions): Promise<ChainVerificationResult>;
+}
+//# sourceMappingURL=decisions.d.ts.map