@spendguard/sdk 0.5.0

package/dist/cache-DOnw8QtJ.d.ts

@@ -0,0 +1,1164 @@
+import '@grpc/grpc-js';
+import { Tracer } from '@opentelemetry/api';
+import { E as Error$1, T as Timestamp, C as CommitSessionDeltaRequest$1, R as ReleaseSessionRequest$1, a as ReserveSessionRequest$1 } from './adapter-D9T3yEEw.js';
+
+/** Default p99-ceiling for `requestDecision` round-trip; design §4.2. */
+declare const DEFAULT_DECISION_TIMEOUT_MS: 250;
+/** Default handshake deadline; design §4.2. */
+declare const DEFAULT_HANDSHAKE_TIMEOUT_MS: 2000;
+/** Default deadline for `confirmPublishOutcome` / `release`; design §4.2. */
+declare const DEFAULT_PUBLISH_TIMEOUT_MS: 150;
+/** Default deadline for `emitTraceEvents` ack loop; design §4.2. */
+declare const DEFAULT_TRACE_TIMEOUT_MS: 500;
+/** Default capability the adapter advertises (L3_POLICY_HOOK = 0x40); design §4.2. */
+declare const DEFAULT_CAPABILITY_LEVEL: 64;
+/** Default protocol version (design §4.2); only `1` is wire-supported in v0.1.x. */
+declare const DEFAULT_PROTOCOL_VERSION: 1;
+/**
+ * Lightweight span record passed to the `onSpan` observer hook. The hook
+ * receives one record per RPC the client makes. Used by adapters that want
+ * to integrate with their own tracing pipeline without pulling
+ * `@opentelemetry/api`.
+ */
+interface SpanRecord {
+    /** RPC span name, e.g. `spendguard.reserve`. */
+    name: string;
+    /** Span start time in milliseconds since epoch. */
+    startTimeMs: number;
+    /** Span wall-clock duration in milliseconds. */
+    durationMs: number;
+    /** Span attributes (snake_case keys per OTel semantic conventions). */
+    attributes: Readonly<Record<string, string | number | boolean | undefined>>;
+    /** Set when the span completed with an error. */
+    error?: Error;
+}
+/**
+ * Constructor options for `SpendGuardClient`. This shape is part of the
+ * LOCKED public surface — design.md §4.2. Adapters in D04 / D06 / D08 / D29
+ * build directly against these fields; renames / removals require a v0.minor
+ * bump and a coordinated update of every adapter spec.
+ *
+ * Per design.md §5.2:
+ *   - Explicit fields override env fallback.
+ *   - Required (no default + no env) fields throw `SpendGuardConfigError` at
+ *     constructor time.
+ *
+ * Two SLICE 3 deviations from design.md §4.2 worth noting:
+ *   - `socketPath` is *optional* on this interface even though design §4.2
+ *     marks it `required in v0.1.x`. The reason: design §5.2 requires env
+ *     fallback to fill it, which only the constructor can do. The validator
+ *     enforces presence post-merge.
+ *   - `tenantId` is similarly optional here, required post-merge.
+ */
+interface SpendGuardClientConfig {
+    /** UDS path the sidecar listens on. Env fallback: `SPENDGUARD_SOCKET_PATH` then `SPENDGUARD_SIDECAR_UDS`. */
+    socketPath?: string;
+    /** Tenant id assertion the sidecar verifies at handshake time. Env fallback: `SPENDGUARD_TENANT_ID`. */
+    tenantId?: string;
+    /** Runtime kind tag e.g. `"langchain-js"` / `"vercel-ai-sdk"`; default `""`. */
+    runtimeKind?: string;
+    /** Optional runtime version tag (caller's own SDK version). */
+    runtimeVersion?: string;
+    /** Override the SDK version reported on the wire. Defaults to the package's `VERSION`. */
+    sdkVersion?: string;
+    /** Adapter↔sidecar protocol version; only `1` is wire-supported in v0.1.x. */
+    protocolVersion?: number;
+    /** Capability the adapter advertises; default `0x40` (L3_POLICY_HOOK). */
+    capabilityLevel?: number;
+    /** Stable workload-instance id; env fallback: `SPENDGUARD_WORKLOAD_INSTANCE_ID`. */
+    workloadInstanceId?: string;
+    /** Per-decision RPC deadline in ms; default 250; env fallback: `SPENDGUARD_DECISION_TIMEOUT_MS`. */
+    decisionTimeoutMs?: number;
+    /** Handshake RPC deadline in ms; default 2_000; env fallback: `SPENDGUARD_HANDSHAKE_TIMEOUT_MS`. */
+    handshakeTimeoutMs?: number;
+    /** Publish-side RPC deadline in ms; default 150. */
+    publishTimeoutMs?: number;
+    /** Trace-event RPC deadline in ms; default 500. */
+    traceTimeoutMs?: number;
+    /**
+     * Observer hook invoked once per RPC. Mutually exclusive with `otelTracer`
+     * (constructor throws `SpendGuardConfigError` when both are set).
+     * Wired in SLICE 8.
+     */
+    onSpan?: (span: SpanRecord) => void;
+    /**
+     * OTel Tracer. When provided, the client emits spans through it instead of
+     * `onSpan`. Mutually exclusive with `onSpan`.
+     * `@opentelemetry/api` is a `peerDependenciesMeta.optional` dep — adapters
+     * that never enable OTel pay zero dep cost. Wired in SLICE 8.
+     */
+    otelTracer?: Tracer;
+    /**
+     * Forward-reserved transport selector. v0.1.x supports only `"uds-grpc"`;
+     * the literal type carries the slot for a future ASP HTTP gateway transport
+     * (design §9 decision 10) without a v0.minor bump.
+     */
+    runtime?: "uds-grpc";
+    /**
+     * Test-only short-circuit: when set, every RPC method returns a no-op
+     * outcome without contacting the sidecar. **For tests only** — production
+     * users who set this and forget have silently lost enforcement. See
+     * design.md §5.1 `SPENDGUARD_DISABLE` for the env fallback. Wired in SLICE 4.
+     */
+    disabled?: boolean;
+    /**
+     * Default `run_projection` policy when callers do not pass one. Slice-doc
+     * addition; env fallback: `SPENDGUARD_RUN_PROJECTION_DEFAULT`. SLICE 4
+     * wires consumption: when set to a non-empty value, the resolved policy
+     * is folded into the `DecisionRequest.inputs.runtime_metadata` under the
+     * `run_projection_policy` key so the sidecar's projector observes the
+     * default per design.md §4.2 R2 amendment.
+     */
+    runProjectionDefault?: RunProjectionPolicy;
+    /**
+     * In-process idempotency cache. When set, `reserve()` consults this cache
+     * before issuing the sidecar RPC: a hit short-circuits to the cached
+     * `DecisionOutcome`. SLICE 8 wires the consumption; see
+     * `InMemoryIdempotencyCache` / `NoopIdempotencyCache` from
+     * `@spendguard/sdk/cache` for ready-made impls. When `undefined`,
+     * `reserve()` issues every RPC unconditionally (the sidecar is still the
+     * correctness gate via its own idempotency-key dedup).
+     */
+    idempotencyCache?: IdempotencyCache;
+}
+/**
+ * Default `run_projection` policy. Forward-extensible string-literal union per
+ * design.md §4.2 R2 amendment + COV_S05_03 R2 commitment MJ-1.
+ *
+ * v0.1.x ships:
+ *   - `""` — leave policy unset; rely on contract-bundle default.
+ *   - `"STRICT_CEILING"` — ASP Draft-01 strict-ceiling policy.
+ *   - `"ELASTIC"` — ASP Draft-01 elastic policy.
+ *
+ * The third member `(string & {})` is the standard TS literal-string escape
+ * hatch: adapters can pass policy names that land in a future contract DSL
+ * bump without forcing a v0.minor on the SDK, while preserving completion
+ * suggestions for the two named members above.
+ */
+type RunProjectionPolicy = "" | "STRICT_CEILING" | "ELASTIC" | (string & {});
+/**
+ * **LOCKED §4.1 spec name** for the constructor options. Identical to
+ * `SpendGuardClientConfig` — this alias preserves the symbol that
+ * design.md §4.1 line 45 enumerates as part of the consumer-facing barrel
+ * import for D04 / D06 / D08 / D29. The slice doc named the file-internal
+ * shape `SpendGuardClientConfig`; the spec name `SpendGuardClientOptions`
+ * is the cross-deliverable contract. Both resolve to the same shape so
+ * that `import { type SpendGuardClientOptions } from "@spendguard/sdk"`
+ * (the form every adapter spec uses) compiles unchanged.
+ *
+ * Added in COV_S05_03 R2 to close the spec-vs-slice-doc rename drift.
+ */
+type SpendGuardClientOptions = SpendGuardClientConfig;
+/**
+ * Resolved config: every field that the SLICE 3 constructor promises to fill
+ * is non-optional here. The runtime validator narrows `SpendGuardClientConfig`
+ * to this stricter shape after merging env fallback + defaults.
+ */
+interface ResolvedConfig {
+    socketPath: string;
+    tenantId: string;
+    runtimeKind: string;
+    runtimeVersion: string;
+    sdkVersion: string;
+    protocolVersion: number;
+    capabilityLevel: number;
+    workloadInstanceId: string;
+    decisionTimeoutMs: number;
+    handshakeTimeoutMs: number;
+    publishTimeoutMs: number;
+    traceTimeoutMs: number;
+    onSpan?: (span: SpanRecord) => void;
+    otelTracer?: Tracer;
+    idempotencyCache?: IdempotencyCache;
+    runtime: "uds-grpc";
+    disabled: boolean;
+    runProjectionDefault: RunProjectionPolicy;
+}
+
+type SessionCommitOutcome = "SUCCESS" | "PROVIDER_ERROR" | "CLIENT_TIMEOUT" | "RUN_ABORTED";
+declare const DEFAULT_MAX_PENDING_SESSION_DELTAS = 64;
+interface ReserveSessionRequest {
+    tenantId: string;
+    budgetId: string;
+    windowInstanceId: string;
+    unit: UnitRef;
+    pricing: PricingFreeze;
+    sessionId: string;
+    route: string;
+    estimatedAmountAtomic: string;
+    ttlSeconds: number;
+    idempotencyKey: string;
+}
+interface CommitSessionDeltaRequest {
+    sessionReservationId: string;
+    streamingCommitId: string;
+    amountAtomicDelta: string;
+    outcome: SessionCommitOutcome;
+    eventTime: Date | number | Timestamp;
+    idempotencyKey: string;
+}
+interface ReleaseSessionRequest {
+    sessionReservationId: string;
+    reasonCode: string;
+    eventTime: Date | number | Timestamp;
+    idempotencyKey: string;
+}
+type ReserveSessionOutcome = {
+    kind: "accepted";
+    sessionReservationId: string;
+    ledgerTransactionId: string;
+    auditSessionEventId: string;
+    ttlExpiresAt: Date | null;
+    reservedAmountAtomic: string;
+    remainingAmountAtomic: string;
+} | {
+    kind: "denied";
+    auditSessionEventId: string;
+    reasonCodes: readonly string[];
+    matchedRuleIds: readonly string[];
+    error?: Error$1;
+};
+interface CommitSessionDeltaOutcome {
+    sessionReservationId: string;
+    streamingCommitId: string;
+    ledgerTransactionId: string;
+    auditSessionEventId: string;
+    committedDeltaAtomic: string;
+    cumulativeCommittedAtomic: string;
+    remainingAmountAtomic: string;
+    recordedAt: Date | null;
+}
+interface ReleaseSessionOutcome {
+    sessionReservationId: string;
+    ledgerTransactionId: string;
+    auditSessionEventId: string;
+    releasedAmountAtomic: string;
+    committedAmountAtomic: string;
+    recordedAt: Date | null;
+}
+interface SessionDeltaCommitInput {
+    amountAtomicDelta: string;
+    outcome: SessionCommitOutcome;
+    eventTime: Date | number | Timestamp;
+    idempotencyKey?: string;
+}
+interface SessionReleaseInput {
+    reasonCode: string;
+    eventTime: Date | number | Timestamp;
+    idempotencyKey: string;
+}
+interface PendingSessionDelta {
+    sequence: number;
+    request: CommitSessionDeltaRequest;
+}
+interface SessionReservationHandleOptions {
+    sessionReservationId: string;
+    nextStreamingCommitSequence?: number;
+    maxPendingDeltas?: number;
+    pendingDeltas?: readonly PendingSessionDelta[];
+    released?: boolean;
+}
+interface SessionReservationHandleSnapshot {
+    sessionReservationId: string;
+    nextStreamingCommitSequence: number;
+    maxPendingDeltas: number;
+    released: boolean;
+    pendingDeltas: readonly PendingSessionDelta[];
+}
+interface SessionDeltaCommitClient {
+    commitSessionDelta(req: CommitSessionDeltaRequest): Promise<CommitSessionDeltaOutcome>;
+}
+interface SessionReleaseClient {
+    releaseSession(req: ReleaseSessionRequest): Promise<ReleaseSessionOutcome>;
+}
+declare class SessionReservationHandleError extends Error {
+    constructor(message: string);
+}
+declare class SessionPendingDeltaLimitError extends SessionReservationHandleError {
+    constructor(maxPendingDeltas: number);
+}
+declare class SessionReservationReleasedError extends SessionReservationHandleError {
+    constructor(sessionReservationId: string);
+}
+declare class SessionReservationReplayMismatchError extends SessionReservationHandleError {
+    constructor(message: string);
+}
+declare class SessionReservationHandle {
+    readonly sessionReservationId: string;
+    readonly maxPendingDeltas: number;
+    private nextStreamingCommitSequenceValue;
+    private pendingDeltaBuffer;
+    private releasedValue;
+    constructor(options: SessionReservationHandleOptions);
+    static fromSnapshot(snapshot: SessionReservationHandleSnapshot): SessionReservationHandle;
+    get nextStreamingCommitSequence(): number;
+    get released(): boolean;
+    get pendingDeltas(): readonly PendingSessionDelta[];
+    snapshot(): SessionReservationHandleSnapshot;
+    enqueueDelta(input: SessionDeltaCommitInput): PendingSessionDelta;
+    commitDelta(client: SessionDeltaCommitClient, input: SessionDeltaCommitInput): Promise<CommitSessionDeltaOutcome>;
+    replayPending(client: SessionDeltaCommitClient): Promise<CommitSessionDeltaOutcome[]>;
+    release(client: SessionReleaseClient, input: SessionReleaseInput): Promise<ReleaseSessionOutcome>;
+    private ackOutcome;
+    private assertOpen;
+}
+declare function buildReserveSessionRequest(req: ReserveSessionRequest): ReserveSessionRequest$1;
+declare function buildCommitSessionDeltaRequest(req: CommitSessionDeltaRequest): CommitSessionDeltaRequest$1;
+declare function buildReleaseSessionRequest(req: ReleaseSessionRequest): ReleaseSessionRequest$1;
+
+/**
+ * Outcome of a successful handshake. SLICE 4 populates this; SLICE 3 only
+ * locks the type so `sessionId` / `handshakeOutcome` getters compile.
+ */
+interface HandshakeOutcome {
+    sessionId: string;
+    sidecarVersion: string;
+    schemaBundleId: string;
+    schemaBundleHash: Uint8Array;
+    contractBundleId: string;
+    contractBundleHash: Uint8Array;
+    capabilityRequired: number;
+    /**
+     * Key id the sidecar reports for `announcementSignature`. **Pass-through
+     * only in v0.1.x — NOT verified by the SDK.** See `announcementSignature`.
+     */
+    signingKeyId: string;
+    /**
+     * Sidecar-supplied announcement signature.
+     *
+     * **PASS-THROUGH ONLY (v0.1.x): these bytes are surfaced verbatim and are
+     * NOT cryptographically verified by the SDK.** Trust rests entirely on the
+     * local UDS transport: the sidecar enforces the kernel `SO_PEERCRED`
+     * peer-credential check, which is the trust anchor under the documented
+     * local-socket threat model. The SDK does not (yet) verify
+     * `announcementSignature` against a pinned `signingKeyId` / control-plane
+     * public key.
+     *
+     * Pinned-key verification is deferred to the future non-local transport
+     * (the forward-reserved `runtime: "fetch"` / TLS path), where the UDS peer-
+     * cred anchor no longer applies. Until then, callers MUST NOT treat a
+     * non-empty `announcementSignature` as an independent proof of sidecar
+     * authenticity. Empty when the sidecar omits it.
+     */
+    announcementSignature: Uint8Array;
+}
+interface UnitRef {
+    unit: string;
+    denomination: number;
+    /** Canonical-truth UUID of the ledger unit row.
+     *
+     * When provided, the SDK threads it verbatim onto `BudgetClaim.unit.unit_id`
+     * on the wire. When omitted, the SDK sends "" and the ledger reject with
+     * `INVALID_REQUEST: claim[N].unit.unit_id empty`.
+     *
+     * Adapters that issue ledger-backed `client.reserve()` MUST provide
+     * `unitId`. Recipe-style integrations (where no ledger reserve happens) MAY
+     * omit. The most common operator path is to set this from the
+     * `SPENDGUARD_UNIT_ID` env var at adapter construction time.
+     *
+     * NB: this is the ledger UUID, distinct from the free-form `unit` slug —
+     * they are NOT interchangeable. Multiple unit slugs can resolve to the same
+     * unit_id when migration aliasing is configured.
+     */
+    unitId?: string;
+}
+interface BudgetClaim {
+    scopeId: string;
+    amountAtomic: string;
+    unit: UnitRef;
+    /** Canonical-truth UUID of the ledger window-instance row.
+     *
+     * When provided, the SDK threads it verbatim onto
+     * `BudgetClaim.window_instance_id` on the wire. When omitted, the SDK sends
+     * "" and the ledger rejects with
+     * `INVALID_REQUEST: claim[N].window_instance_id empty`.
+     *
+     * Adapters that issue ledger-backed `client.reserve()` MUST provide
+     * `windowInstanceId`. Recipe-style integrations (where no ledger reserve
+     * happens) MAY omit. The most common operator path is to set this from the
+     * `SPENDGUARD_WINDOW_INSTANCE_ID` env var at adapter construction time.
+     *
+     * Mirrors the HARDEN_D05_UR `UnitRef.unitId` broadening — same disease,
+     * same additive backward-compatible cure (HARDEN_D05_WI).
+     */
+    windowInstanceId?: string;
+}
+interface PricingFreeze {
+    pricingVersion: string;
+    pricingHash: Uint8Array;
+    /** HARDEN_D05_WI — optional FX rate version of the pricing freeze tuple.
+     * When omitted the SDK sends "" (pre-HARDEN wire shape). Ledger commit
+     * validation compares the FULL tuple against the reservation's freeze, so
+     * adapters whose reservations carry a non-empty fx version MUST thread it. */
+    fxRateVersion?: string;
+    /** HARDEN_D05_WI — optional unit-conversion version (see fxRateVersion). */
+    unitConversionVersion?: string;
+}
+interface ClaimEstimate {
+    tokenizerTier?: "T1" | "T2" | "T3" | "";
+    tokenizerVersionId?: string;
+    inputTokens?: number | bigint;
+    predictedATokens?: number | bigint;
+    predictedBTokens?: number | bigint;
+    predictedCTokens?: number | bigint;
+    reservedStrategy?: "A" | "B" | "C" | "";
+    predictionStrategyUsed?: "A" | "B" | "C" | "";
+    predictionPolicyUsed?: string;
+    predictionConfidence?: number;
+    predictionSampleSize?: number | bigint;
+    coldStartLayerUsed?: "L1" | "L2" | "L3" | "L4" | "";
+    classifierVersion?: string;
+    fingerprintVersion?: string;
+    promptClassFingerprint?: string;
+    runProjectionAtDecisionAtomic?: number | bigint;
+    runPredictedRemainingSteps?: number;
+    runStepsCompletedSoFar?: number | bigint;
+    runCodeTriggered?: string;
+    model?: string;
+    promptClass?: string;
+}
+interface ReserveRequest {
+    trigger: "RUN_PRE" | "AGENT_STEP_PRE" | "LLM_CALL_PRE" | "TOOL_CALL_PRE";
+    runId: string;
+    stepId: string;
+    llmCallId: string;
+    toolCallId?: string;
+    decisionId: string;
+    route: string;
+    projectedClaims: BudgetClaim[];
+    idempotencyKey: string;
+    traceparent?: string;
+    tracestate?: string;
+    parentRunId?: string;
+    budgetGrantJti?: string;
+    projectedP50Atomic?: string;
+    projectedP90Atomic?: string;
+    projectedP95Atomic?: string;
+    projectedP99Atomic?: string;
+    projectedUnit?: UnitRef;
+    promptText?: string;
+    decisionContextJson?: Record<string, unknown>;
+    claimEstimate?: ClaimEstimate;
+}
+interface DecisionOutcome {
+    decisionId: string;
+    auditDecisionEventId: string;
+    decision: "CONTINUE" | "DEGRADE";
+    mutationPatchJson: string;
+    effectHash: Uint8Array;
+    ledgerTransactionId: string;
+    reservationIds: readonly string[];
+    ttlExpiresAtSeconds: number;
+    reasonCodes: readonly string[];
+    matchedRuleIds: readonly string[];
+}
+interface CommitEstimatedRequest {
+    runId: string;
+    stepId: string;
+    llmCallId: string;
+    decisionId: string;
+    reservationId: string;
+    estimatedAmountAtomic: string;
+    unit: UnitRef;
+    pricing: PricingFreeze;
+    providerEventId: string;
+    outcome: "SUCCESS" | "PROVIDER_ERROR" | "CLIENT_TIMEOUT" | "RUN_ABORTED";
+    actualInputTokens?: number;
+    actualOutputTokens?: number;
+    deltaBRatio?: number;
+    deltaCRatio?: number;
+    traceparent?: string;
+    tracestate?: string;
+    providerResponseMetadata?: string;
+    outcomeKind?: "SUCCESS" | "FAILURE";
+    /**
+     * `int64`-as-string, mirroring SLICE 4 `actualInputTokens` semantics for
+     * the multi-event path. When `outcomeKind` is set and this is provided,
+     * the outcome event carries the value verbatim; when omitted on the
+     * outcome event, the SDK reuses `actualInputTokens` from this request
+     * (avoids a double-spec for callers that already populate the SLICE 4
+     * field).
+     */
+    actualInputTokensWire?: string;
+    /** `int64`-as-string companion of `actualOutputTokens` (see above). */
+    actualOutputTokensWire?: string;
+    /**
+     * Free-form error message threaded onto the outcome event's
+     * `providerResponseMetadata` JSON envelope as `{"error_message": "..."}`.
+     * Only consulted when `outcomeKind === "FAILURE"`; ignored on SUCCESS.
+     */
+    actualErrorMessage?: string;
+}
+interface ReleaseRequest {
+    reservationId: string;
+    idempotencyKey: string;
+    reasonCodes?: readonly string[];
+    workloadInstanceId?: string;
+    tenantId?: string;
+}
+interface ReleaseOutcome {
+    /**
+     * Audit-chain signature for the release event, as reported by the sidecar.
+     *
+     * **PASS-THROUGH ONLY (v0.1.x): NOT cryptographically verified by the SDK.**
+     * Like `HandshakeOutcome.announcementSignature`, trust rests on the local
+     * UDS `SO_PEERCRED` peer-credential anchor; these are unvalidated bytes the
+     * adapter may forward but MUST NOT treat as independent proof. Pinned-key
+     * verification is deferred to the future non-local (TLS) transport. Empty
+     * when the sidecar omits it.
+     */
+    auditEventSignature: Uint8Array;
+    ledgerTransactionId: string;
+    releasedReservationIds: readonly string[];
+}
+interface QueryBudgetRequest {
+    scopeId: string;
+    asOfSeconds?: number;
+}
+interface QueryBudgetResult {
+    availableAtomic: string;
+    reservedAtomic: string;
+    committedAtomic: string;
+    unit: UnitRef;
+    asOfSeconds: number;
+}
+interface PublishOutcomeRequest {
+    decisionId: string;
+    effectHash: Uint8Array;
+    outcome: "APPLIED" | "APPLIED_NOOP" | "APPLY_FAILED" | "APPROVAL_GRANTED" | "APPROVAL_DENIED" | "APPROVAL_TIMED_OUT";
+    adapterError?: string;
+}
+interface ApplyFailedRequest {
+    decisionId: string;
+    effectHash: Uint8Array;
+    adapterError: string;
+}
+interface ResumeAfterApprovalRequest {
+    approvalId: string;
+    tenantId: string;
+    decisionId: string;
+    workloadInstanceId?: string;
+}
+/** Alias for `CommitEstimatedRequest` exposed for the lower-level entry point. */
+type EmitLlmCallPostRequest = CommitEstimatedRequest;
+/**
+ * Async gRPC client for the SpendGuard sidecar over a Unix Domain Socket.
+ *
+ * SLICE 3 wired lifecycle + UDS transport; SLICE 4 wires handshake / reserve /
+ * commitEstimated bodies; SLICE 5 wires release / queryBudget. Adapters (D04 /
+ * D06 / D08 / D29) build against the LOCKED §4.2 surface and treat this class
+ * as their primary integration point.
+ *
+ * Usage:
+ *
+ *     await using client = SpendGuardClient.fromEnv();
+ *     await client.connect();
+ *     const handshake = await client.handshake();
+ *     const decision = await client.reserve({ ... });
+ *     await client.commitEstimated({ ... });
+ *     // `await using` runs `[Symbol.asyncDispose]` here → graceful close
+ *
+ * @example Test-only short-circuit (per design.md §5.1)
+ *
+ *     // SPENDGUARD_DISABLE=1 in env, or:
+ *     const client = new SpendGuardClient({
+ *       socketPath: "/dev/null",
+ *       tenantId: "test",
+ *       disabled: true,
+ *     });
+ *     // Every RPC returns a no-op outcome; no UDS contact. **TESTS ONLY** —
+ *     // a forgotten production setting silently loses enforcement.
+ */
+declare class SpendGuardClient implements AsyncDisposable {
+    /** Frozen, merged + validated configuration. */
+    private readonly cfg;
+    /** Active gRPC transport, or `null` before `connect()` / after `close()`. */
+    private transport;
+    /** Active SidecarAdapter gRPC client; mirrors `transport` lifetime. */
+    private adapterClient;
+    /** Cached handshake outcome; first `handshake()` populates, subsequent reads reuse. */
+    private handshakeResult;
+    /**
+     * Coalesces concurrent `handshake()` callers into a single in-flight RPC.
+     * Mirrors Python `self._handshake_lock` in `client.py`. Stays non-null only
+     * while a handshake RPC is pending; cleared after success or failure so a
+     * post-failure retry can re-enter.
+     */
+    private handshakeInFlight;
+    /**
+     * Construct a client. Per design.md §5.2: explicit options win over env
+     * fallback; required fields without either throw `SpendGuardConfigError`
+     * immediately.
+     */
+    constructor(rawOpts?: SpendGuardClientConfig);
+    /**
+     * Wrap an RPC body in the configured observability hook(s). Threads BOTH
+     * `cfg.otelTracer` and `cfg.onSpan` into `withOtelSpan` so every RPC site
+     * gets span emission uniformly — the documented `onSpan` observer (the
+     * no-OTel-dep path) is invoked once per RPC, fixing the prior drift where
+     * `onSpan` was stored but never called. The two are mutually exclusive at
+     * config-validation time, so at most one fires.
+     */
+    private withSpan;
+    /**
+     * Convenience factory that reads required config from env vars and falls
+     * back to `/var/run/spendguard/adapter.sock` when `SPENDGUARD_SOCKET_PATH`
+     * is unset.
+     *
+     * Env vars consumed:
+     *   - `SPENDGUARD_SOCKET_PATH` (slice-doc alias) / `SPENDGUARD_SIDECAR_UDS`
+     *     (design §5.1) — UDS path; defaults to `/var/run/spendguard/adapter.sock`.
+     *   - `SPENDGUARD_TENANT_ID` — **required**; throws `SpendGuardConfigError`
+     *     when unset.
+     *   - `SPENDGUARD_RUN_PROJECTION_DEFAULT` — optional default
+     *     `run_projection` policy name; SLICE 4 wires consumption.
+     *   - `SPENDGUARD_WORKLOAD_INSTANCE_ID` / `SPENDGUARD_DECISION_TIMEOUT_MS`
+     *     / `SPENDGUARD_HANDSHAKE_TIMEOUT_MS` / `SPENDGUARD_DISABLE` — optional
+     *     per design §5.1.
+     *
+     * Extra options provided as the `overrides` argument win over env per
+     * design.md §5.2.
+     *
+     * @throws SpendGuardConfigError when `SPENDGUARD_TENANT_ID` is missing.
+     */
+    static fromEnv(overrides?: SpendGuardClientConfig): SpendGuardClient;
+    /**
+     * Open the UDS gRPC channel. Idempotent — a second call when already
+     * connected is a no-op.
+     *
+     * Per design.md §6.3 / Python `client.py:240-251`, the `unix:` URI scheme
+     * is used and `grpc.default_authority=localhost` is set so the tonic-based
+     * sidecar accepts the HTTP/2 `:authority` pseudo-header. Without this
+     * channel option, tonic resets every stream with `PROTOCOL_ERROR`.
+     *
+     * In disabled mode (`SPENDGUARD_DISABLE=1` or `disabled: true`), no
+     * transport is opened — the call returns immediately. Subsequent RPCs
+     * short-circuit to no-op outcomes in SLICE 4.
+     *
+     * @throws SpendGuardConnectionError when the underlying transport could
+     *   not be opened (e.g. malformed socket path).
+     */
+    connect(): Promise<void>;
+    /**
+     * Graceful close. Idempotent — calling `close()` twice (or `close()` before
+     * `connect()`) does not throw.
+     *
+     * On success the transport is dropped; the next `connect()` allocates a new
+     * channel. In-flight RPCs may complete with a `CANCELLED` status; SLICE 8
+     * adds the grace-period drain semantics that mirror the Python SDK's
+     * `await ch.close(grace=0.5)` path.
+     */
+    close(): Promise<void>;
+    /**
+     * ESM 2024 `await using` hook. Equivalent to `await this.close()`.
+     *
+     * Usage:
+     *
+     *     await using client = new SpendGuardClient({ ... });
+     *     // ... use client ...
+     *     // [Symbol.asyncDispose] runs here automatically.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** The tenant id this client asserted at construction. Stable for the client's lifetime. */
+    get tenantId(): string;
+    /**
+     * The negotiated session id. Throws `HandshakeError` until `handshake()`
+     * has completed (SLICE 4 wires the handshake; until then the getter is
+     * effectively unusable, which is intentional — adapters should call
+     * `handshake()` before reading state).
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     */
+    get sessionId(): string;
+    /** Full handshake outcome. Throws `HandshakeError` until `handshake()` completes. */
+    get handshakeOutcome(): HandshakeOutcome;
+    /** Whether the client is currently connected to the sidecar. */
+    get isConnected(): boolean;
+    /** Frozen view of the resolved configuration. Useful for tests + debugging. */
+    get config(): Readonly<ResolvedConfig>;
+    /**
+     * Mandatory initial handshake. Idempotent — a second call returns the cached
+     * outcome without re-issuing the RPC (design.md §4.5). Concurrent callers
+     * are coalesced into the same in-flight RPC via `handshakeInFlight`.
+     *
+     * Disabled mode (`SPENDGUARD_DISABLE=1` / `disabled: true`) short-circuits
+     * to a synthetic `HandshakeOutcome` so unit tests can run without a real
+     * sidecar (`makeDisabledHandshake`).
+     *
+     * @throws HandshakeError on protocol-version mismatch or insufficient
+     *   capability advertisement.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on any other gRPC failure surface.
+     */
+    handshake(opts?: {
+        workloadInstanceId?: string;
+    }): Promise<HandshakeOutcome>;
+    /**
+     * Internal: issue the real Handshake RPC and map the response.
+     *
+     * Splits out from `handshake()` so the idempotency guard there stays
+     * obviously correct: `doHandshake` never reads `handshakeResult` itself;
+     * it only writes it on success.
+     */
+    private doHandshake;
+    /**
+     * Run a `*.pre` decision boundary through the sidecar. Equivalent to the
+     * Python SDK's `request_decision` (design.md §4.7).
+     *
+     * The wire shape is built in `buildDecisionRequest()` and consumes:
+     *   - the cached handshake `sessionId` (auto-handshakes on first use),
+     *   - the caller-supplied `idempotencyKey` (REQUIRED — see design §6.5),
+     *   - `runProjectionDefault` from config when the caller did not pass
+     *     one in `decisionContextJson.run_projection_policy` (closes MJ-1).
+     *
+     * The response is mapped through `mapDecisionResponse()`: CONTINUE / DEGRADE
+     * return a `DecisionOutcome`; STOP / STOP_RUN_PROJECTION / SKIP /
+     * REQUIRE_APPROVAL raise the matching typed exception so adapters can route
+     * on `instanceof DecisionDenied` (and its subclasses) per review-standards §5.
+     *
+     * @throws DecisionStopped on STOP / STOP_RUN_PROJECTION.
+     * @throws DecisionSkipped on SKIP.
+     * @throws ApprovalRequired on REQUIRE_APPROVAL — `await err.resume(client)`
+     *   surfaces the operator decision.
+     * @throws DecisionDenied on an unknown decision enum.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on any other gRPC failure surface.
+     */
+    reserve(req: ReserveRequest): Promise<DecisionOutcome>;
+    /**
+     * Alias for `reserve()` — identical function reference (review-standards §1.5
+     * P0 BLOCKER). The Python SDK exposes the symbol as `request_decision`; the
+     * TS surface keeps `reserve` as the canonical name AND exposes
+     * `requestDecision` so cross-language docs work without surprise.
+     *
+     * Implemented as an instance-field initializer that reads `this.reserve`
+     * during construction. The dot-lookup on `this.reserve` (inside the field
+     * initializer, before any instance shadow exists) resolves to the prototype
+     * method `SpendGuardClient.prototype.reserve`. Assigning it to the field
+     * makes `client.requestDecision === client.reserve` Boolean-true at runtime
+     * (both resolve to the same prototype function reference).
+     *
+     * NOTE on `.bind(this)`: implementation.md §4 line 581 sketches the field
+     * as `this.reserve.bind(this)`. The literal `bind` would produce a NEW
+     * function object and break the §1.5 identity gate; the constraint cited
+     * by the slice doc (review-standards §1.5 P0 BLOCKER) wins, so we drop
+     * `.bind(this)`. Callers always invoke as `client.requestDecision(req)`
+     * (method-call form) which preserves `this` via JS dispatch semantics —
+     * the bind was over-specification for the Pythonic detached-method
+     * pattern, which the TS SDK does not advertise.
+     *
+     * NOTE: do NOT add a JSDoc `@throws` block here — TypeScript erases JSDoc
+     * from runtime fields and the identity invariant is the primary contract
+     * this declaration enforces.
+     */
+    readonly requestDecision: SpendGuardClient["reserve"];
+    /**
+     * Commit an estimated LLM-call outcome. Equivalent to the Python SDK's
+     * `emit_llm_call_post` with `estimated_amount_atomic` (design.md §4.8).
+     *
+     * Single-event LlmCallPostPayload over the EmitTraceEvents duplex stream:
+     * the client opens a fresh stream per commit, sends one event, awaits one
+     * ack, and closes (Python parity — `emit_llm_call_post` at client.py:818).
+     * SLICE 5+ may switch to a long-lived stream for production latency, but
+     * the per-event setup cost is acceptable in v0.1.x.
+     *
+     * Ack semantics: the sidecar emits exactly one `TraceEventAck` per inbound
+     * event in this POC. Status != ACCEPTED surfaces as `SpendGuardError`
+     * (Codex round-2 P1.1 from Python parity — silent failure here would mask
+     * a commit-lifecycle bug).
+     *
+     * Mutually exclusive with the deferred provider-report path: this method
+     * always sends `estimated_amount_atomic`; the `provider_reported_amount_atomic`
+     * wire field stays empty. Adapters needing the provider-report path use the
+     * lower-level `emitLlmCallPost` (SLICE 7+).
+     *
+     * **SLICE 5 multi-event extension.** When `req.outcomeKind` is set, the
+     * client emits TWO events on the same bidi stream — the original
+     * LLM_CALL_POST event first, then a second LLM_CALL_POST-kind event whose
+     * `outcome` field reflects `outcomeKind` (SUCCESS → SUCCESS,
+     * FAILURE → PROVIDER_ERROR) and whose `providerResponseMetadata` carries a
+     * `{"error_message": ...}` envelope when `actualErrorMessage` is supplied.
+     * Both events are acked individually; if either ack is non-ACCEPTED the
+     * method raises `SpendGuardError`. See the JSDoc on
+     * `CommitEstimatedRequest.outcomeKind` for the LLM_CALL_OUTCOME proto-kind
+     * deviation note (Declared Deviation #1 in SLICE 5).
+     *
+     * When `req.outcomeKind` is ABSENT, behaviour is identical to SLICE 4 —
+     * a single event is sent, a single ack is drained.
+     *
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on rejected ack or any other gRPC failure surface.
+     */
+    commitEstimated(req: CommitEstimatedRequest): Promise<void>;
+    /**
+     * Explicit release of a held reservation. Matches Agent Spend Protocol
+     * Draft-01 §4 one-to-one (the proto wire's
+     * `ReleaseReservationRequest` carries the canonical ASP fields at tags 1-3
+     * and SpendGuard extensions at tag 100+).
+     *
+     * Behaviour:
+     *   - Disabled-mode short-circuit returns a synthetic
+     *     `makeDisabledReleaseOutcome(req)` — no UDS contact.
+     *   - Pre-handshake call throws `HandshakeError` via the `sessionId` getter
+     *     gate (the request envelope requires the negotiated session id).
+     *   - Wire envelope built by `buildReleaseRequest(req, sessionId)`.
+     *   - Response mapped by `mapReleaseResponse(res, decisionIdHint)`.
+     *   - Errors mapped centrally through `mapGrpcStatusToError`, with the
+     *     `release`-specific NOT_FOUND override (reservation lookup misses
+     *     surface as a plain `SpendGuardError("reservation not found")` so
+     *     adapters can distinguish "no such reservation" from the rich
+     *     FAILED_PRECONDITION cluster).
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws MutationApplyFailed on FAILED_PRECONDITION + IDEMPOTENCY_CONFLICT
+     *   or BUDGET_EXCEEDED — or an unknown FAILED_PRECONDITION reason (the
+     *   conservative default; never bare `SpendGuardError` for this cluster).
+     * @throws ApprovalBundleHotReloadedError on FAILED_PRECONDITION +
+     *   BUNDLE_HOT_RELOADED.
+     * @throws SpendGuardError on NOT_FOUND ("reservation not found") + any
+     *   other unmapped gRPC failure.
+     */
+    release(req: ReleaseRequest): Promise<ReleaseOutcome>;
+    /**
+     * Reserve a session-scoped hold for a realtime voice session (D41 SR-V3).
+     *
+     * The public request shape mirrors `buildReserveSessionRequest`. When
+     * `req.sessionId` is empty, the SDK fills it from the completed sidecar
+     * handshake so adapter code can bind the session reservation to the active
+     * UDS session without duplicating handshake plumbing.
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on proto error outcome or unmapped gRPC failure.
+     */
+    reserveSession(req: ReserveSessionRequest): Promise<ReserveSessionOutcome>;
+    /**
+     * Commit one positive streaming spend delta against a session reservation.
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on proto error outcome or unmapped gRPC failure.
+     */
+    commitSessionDelta(req: CommitSessionDeltaRequest): Promise<CommitSessionDeltaOutcome>;
+    /**
+     * Release the uncommitted remainder of a session reservation.
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     * @throws SidecarUnavailable on UNAVAILABLE / DEADLINE_EXCEEDED / CANCELLED.
+     * @throws SpendGuardError on proto error outcome or unmapped gRPC failure.
+     */
+    releaseSession(req: ReleaseSessionRequest): Promise<ReleaseSessionOutcome>;
+    /**
+     * Read-only budget snapshot. Locked decision #4 of design.md §9: in v0.1.x
+     * the substrate ships the method signature but the sidecar wire is NOT yet
+     * implemented. SLICE 5 wires the §9.4 placeholder body — adapters call this
+     * method, catch the explicit `SpendGuardError`, and surface a clear "feature
+     * not yet available" upstream rather than a stray NOT_FOUND from a missing
+     * RPC route.
+     *
+     * Disabled-mode short-circuit returns a synthetic
+     * `makeDisabledQueryBudgetResult(req)` so unit tests can program against
+     * the method without a sidecar.
+     *
+     * @throws HandshakeError before `handshake()` completes.
+     * @throws SpendGuardError carrying the tracking-issue URL otherwise.
+     */
+    queryBudget(req: QueryBudgetRequest): Promise<QueryBudgetResult>;
+    /**
+     * Confirm `publish_effect` outcome. SLICE 7 wires body.
+     * @throws SpendGuardError until SLICE 7 wires the body.
+     */
+    confirmPublishOutcome(req: PublishOutcomeRequest): Promise<string>;
+    /**
+     * Resume after a human approver acted on a `REQUIRE_APPROVAL` decision.
+     * SLICE 7 wires the body; references this method from `ApprovalRequired.resume`.
+     * @throws SpendGuardError until SLICE 7 wires the body.
+     */
+    resumeAfterApproval(req: ResumeAfterApprovalRequest): Promise<DecisionOutcome>;
+    /**
+     * Safe-ack the `APPLY_FAILED` publish outcome — swallows transport errors
+     * so the caller's original exception is never shadowed. SLICE 7 wires body.
+     * @throws SpendGuardError until SLICE 7 wires the body.
+     */
+    safeConfirmApplyFailed(req: ApplyFailedRequest): Promise<void>;
+    /**
+     * Lower-level entry point that `commitEstimated()` wraps. Provided so
+     * adapters that need the raw trace-event surface have access. SLICE 7
+     * wires body (the provider-report path).
+     * @throws SpendGuardError until SLICE 7 wires the body.
+     */
+    emitLlmCallPost(req: EmitLlmCallPostRequest): Promise<void>;
+    /**
+     * Build the gRPC channel credentials. Always insecure over UDS — the kernel
+     * `SO_PEERCRED` check on the sidecar side is the trust anchor (Sidecar
+     * Architecture §5). TLS over a Unix socket adds overhead with no security
+     * benefit when the connection is implicitly local.
+     *
+     * Carved into its own method so a future slice can override under a
+     * `runtime` flag once HTTP-gateway transport is added — `runtime: "fetch"`
+     * would override to use TLS credentials. v0.1.x only supports `"uds-grpc"`.
+     */
+    private buildChannelCredentials;
+    /**
+     * Translate the public `ReserveRequest` (camelCase, TS-idiomatic) into the
+     * snake_case-on-wire `DecisionRequest` proto. Per implementation.md §4:
+     *
+     *   1. SessionId from the cached handshake (caller already gated above).
+     *   2. Trigger enum mapping via `triggerEnumOf()`.
+     *   3. W3C `traceparent` → `TraceContext` via `buildTraceContext()` (matches
+     *      Python `_build_trace_context`).
+     *   4. `runtimeMetadata` carries the prompt hash (when caller supplied
+     *      `promptText`) and any `decisionContextJson` keys. The
+     *      `run_projection_policy` slot is filled from the caller's
+     *      `decisionContextJson.run_projection_policy` if present, otherwise
+     *      from `cfg.runProjectionDefault` when non-empty. **This is the
+     *      SLICE 4 consumption of MJ-1** — SLICE 3 stored the field on the
+     *      config; this method wires it onto the wire.
+     *   5. `plannedStepsHint` is `plan.plannedCalls + plan.plannedTools` when
+     *      a `withRunPlan` scope is active (SLICE 7 R2), otherwise the proto3
+     *      default `0`.
+     *
+     * `runtime_metadata` is encoded as a hand-built `google.protobuf.Struct`
+     * payload because the SDK does not yet ship `computePromptHash` (SLICE 6).
+     * Until then this method ALWAYS sends an empty Struct body when no caller
+     * decoration is requested — matching Python `runtime_metadata = None` which
+     * is wire-equivalent to "field absent" under proto3 message optionality.
+     */
+    private buildDecisionRequest;
+    /**
+     * Build the `google.protobuf.Struct` payload that lands in
+     * `DecisionRequest.inputs.runtime_metadata`. Returns `undefined` when there
+     * is nothing to send (proto3 message optionality — wire equivalent to
+     * "field absent").
+     *
+     * Two slots are populated here:
+     *   - `decision_context_json.*` keys from the caller (verbatim).
+     *   - `run_projection_policy` from the caller (if present in
+     *     `decisionContextJson`) OR `cfg.runProjectionDefault` (when set and
+     *     non-empty). The caller's value wins; the default only fills in when
+     *     the caller did not provide one — matches design.md §4.2 R2 semantics.
+     *
+     * SLICE 6 R1 closure of SLICE 4 M-3: when `req.promptText` is set,
+     * `computePromptHash(req.promptText, this.cfg.tenantId)` populates
+     * `runtime_metadata.prompt_hash` as a stringValue. Mirrors Python parity
+     * at `sdk/python/.../client.py` (the `prompt_hash` field is the rules
+     * dedup key per Cost Advisor P0.5 §5.1). The caller may pre-set
+     * `decisionContextJson.prompt_hash` to override (e.g. when the prompt is
+     * tokenised upstream and the hash is computed there); the caller-supplied
+     * value wins.
+     */
+    private buildRuntimeMetadataStruct;
+    /**
+     * Build the single LLM_CALL_POST trace event for `commitEstimated()`.
+     * Mirrors Python `emit_llm_call_post` at client.py:818 with the difference
+     * that `provider_reported_amount_atomic` is always empty here (the
+     * provider-report path lives in SLICE 5+'s `emitLlmCallPost`).
+     */
+    private buildLlmCallPostEvent;
+    /**
+     * Build the SLICE 5 multi-event "outcome" companion event for
+     * `commitEstimated()` when `req.outcomeKind` is set.
+     *
+     * The event reuses `TraceEvent_EventKind.LLM_CALL_POST` (per Declared
+     * Deviation #1 — `LLM_CALL_OUTCOME` does not exist as a proto enum value
+     * in `sidecar_adapter/v1/adapter.proto` yet).
+     *
+     * TODO(GH-issue-TBD): proto bump for `LLM_CALL_OUTCOME` +
+     * sidecar `x-spendguard-reason-code` trailer extension. Both deferred to
+     * the cross-component slice that touches `proto/` and
+     * `services/sidecar/`. Track at
+     * https://github.com/m24927605/agentic-spendguard/issues/TBD-proto-bump-llm-call-outcome
+     * (R2 follow-up; not in scope for D05 SLICE 5).
+     *
+     * The `outcome` field on the inner `LlmCallPostPayload` carries the
+     * semantic:
+     *
+     *   - `outcomeKind === "SUCCESS"` → `LlmCallPostPayload_Outcome.SUCCESS`
+     *   - `outcomeKind === "FAILURE"` → `LlmCallPostPayload_Outcome.PROVIDER_ERROR`
+     *
+     * Actuals (`actualInputTokens` / `actualOutputTokens`) prefer the SLICE 5
+     * `*Wire` fields when supplied (int64-as-string form), falling back to
+     * the SLICE 4 numeric `actualInputTokens` / `actualOutputTokens` shape so
+     * adapters do not need to double-specify. `actualErrorMessage` is threaded
+     * onto `TraceEvent.providerResponseMetadata` as a JSON envelope
+     * `{"error_message": "..."}` only when `outcomeKind === "FAILURE"`.
+     *
+     * `estimatedAmountAtomic` is intentionally set to an empty string on the
+     * outcome event — the first event already booked the commit; the outcome
+     * event only carries observation, not commit semantics. The sidecar will
+     * surface a rejection ack if it requires the field (`mock-sidecar`'s tests
+     * lock this in).
+     *
+     * @private
+     */
+    private buildLlmCallOutcomeEvent;
+}
+/**
+ * Stable, in-process hash of a `ReserveRequest`'s identity for binding
+ * idempotency-cache entries to the request body.
+ *
+ * Why: `cfg.idempotencyCache` is keyed on the caller-supplied
+ * `idempotencyKey`. A cache HIT short-circuits the UDS round trip entirely, so
+ * the sidecar (the correctness gate) never re-evaluates. If an adapter reuses
+ * an `idempotencyKey` for a logically DIFFERENT reserve (different claims /
+ * amount / route / window / pricing), a key-only cache would return the prior
+ * CONTINUE — allowing spend against a stale decision the sidecar never saw.
+ * Binding the entry to this hash makes a key-hit-with-different-body fall
+ * through to the sidecar (see `InMemoryIdempotencyCache.get`).
+ *
+ * This hash is a LOCAL latency-optimisation discriminator only — it is NOT a
+ * wire value and needs NO cross-language byte-equivalence. It MUST, however,
+ * be deterministic within a process and cover every field that changes the
+ * ledger/sidecar decision, so the local fall-through decision provably agrees
+ * with the sidecar's accept / IDEMPOTENCY_CONFLICT decision. We therefore hash
+ * the FULL request identity (all decision-affecting fields) via a canonical
+ * JSON encoding with sorted keys.
+ *
+ * `idempotencyKey` is intentionally EXCLUDED from the hashed body (it is the
+ * cache key, not part of the identity being disambiguated under that key).
+ *
+ * Exported for the cache-collision regression test; not part of the LOCKED
+ * public surface (no index.ts re-export).
+ */
+declare function computeReserveBodyHash(req: ReserveRequest): string;
+/**
+ * Lockable contract: `DomainError::Display` prefix → canonical reason code.
+ *
+ * Sourced from `services/sidecar/src/domain/error.rs` `#[error(...)]`
+ * attributes (lines 26-45) — these strings ARE the public Status-message
+ * format the sidecar emits via `Status::failed_precondition(self.to_string())`.
+ * Match is case-insensitive prefix on the bare `RpcError.message`
+ * (anchored at the start; the `: <detail>` tail varies per call).
+ *
+ * Forward-compat: the bracket-tagged `[BUNDLE_HOT_RELOADED]` form comes from
+ * `services/sidecar/src/server/adapter_uds.rs:1379` (resume path) and is
+ * included so dispatch already works when a future cross-component slice
+ * unifies the release/resume Status surface.
+ *
+ * Ordered ARRAY (not a map): longest / most-specific prefixes FIRST so a
+ * shorter prefix doesn't accidentally swallow a longer one.
+ */
+declare const REASON_CODE_PREFIXES: ReadonlyArray<readonly [string, string]>;
+/**
+ * Context passed to `mapGrpcStatusToError`. The `rpc` field is folded into
+ * the typed-error message; `releaseNotFoundAsPlain` opt-in flips NOT_FOUND
+ * into a plain `SpendGuardError("reservation not found")` for the
+ * `release()` call path (the only RPC that needs the override — `reserve` /
+ * `handshake` / `commitEstimated` never legitimately surface NOT_FOUND).
+ */
+interface MapGrpcStatusContext {
+    rpc: string;
+    releaseNotFoundAsPlain?: boolean;
+}
+
+/**
+ * Idempotency cache contract. Adapters consume via
+ * `SpendGuardClientConfig.idempotencyCache?: IdempotencyCache`.
+ *
+ * - `get(key, bodyHash?)` MUST return the cached outcome for `key` when it is
+ *   fresh (TTL-window unexpired) AND — when both the caller and the stored
+ *   entry carry a `bodyHash` — the hashes match; else `undefined`.
+ *   Implementations MAY treat the read as a recency signal (LRU
+ *   move-to-front); MUST NOT bump the TTL.
+ * - `set(key, outcome, ttlMs?, bodyHash?)` stores the outcome. Optional `ttlMs`
+ *   overrides the cache's default TTL for this entry. Optional `bodyHash` binds
+ *   the entry to the request identity that produced `outcome` so a later
+ *   `get(key, otherHash)` with a colliding key but a different body falls
+ *   through (returns `undefined`) instead of returning a stale decision.
+ *   Implementations MAY evict in amortised O(1) to honor a `maxEntries` cap.
+ * - `clear()` resets the cache to empty.
+ * - `size` is a snapshot getter; readers MAY observe a non-monotonic value
+ *   across concurrent sets (no atomicity guarantee).
+ *
+ * The `bodyHash` parameters are OPTIONAL and additive: callers that omit them
+ * get key-only semantics (unchanged from v0.1.0). `SpendGuardClient.reserve()`
+ * always supplies a `bodyHash` so a reused `idempotencyKey` for a logically
+ * different request never short-circuits the authoritative sidecar gate.
+ */
+interface IdempotencyCache {
+    get(key: string, bodyHash?: string): DecisionOutcome | undefined;
+    set(key: string, outcome: DecisionOutcome, ttlMs?: number, bodyHash?: string): void;
+    clear(): void;
+    readonly size: number;
+}
+/**
+ * Default cache cap. design.md §3 line 35 LOCKS this at "default 1024
+ * entries". The number is a balance:
+ *   - 1024 entries × ~512 B/entry (DecisionOutcome with reservation IDs +
+ *     reason codes) → ~512 KiB ceiling. Fits comfortably in adapter
+ *     working-set budgets.
+ *   - 1024 is large enough to absorb a steady-state burst of in-flight
+ *     decisions (each adapter request issues at most one `reserve`).
+ *   - Override via `new InMemoryIdempotencyCache({ maxEntries: ... })`
+ *     when adapters know their working set is larger.
+ */
+declare const DEFAULT_CACHE_MAX_ENTRIES = 1024;
+/**
+ * Default TTL. design.md §3 line 35 + implementation.md §10 LOCK this at
+ * "TTL 5 minutes" — long enough to cover a same-process retry storm
+ * (the SLICE 8 retry helper has a 50 ms ceiling per attempt × 2 attempts =
+ * ≤100 ms — the cache TTL must dominate by 3-4 orders of magnitude to be
+ * useful) but short enough that a cache-bypass-via-eviction edge case
+ * doesn't propagate stale outcomes hours after the original reservation
+ * was already released by TTL sweep on the sidecar side.
+ */
+declare const DEFAULT_CACHE_TTL_MS: number;
+/** Options for `InMemoryIdempotencyCache`. */
+interface InMemoryIdempotencyCacheOptions {
+    /** Max entries before LRU eviction. Default 1024. */
+    maxEntries?: number;
+    /** Default per-entry TTL in ms. Default 300_000. Per-call `ttlMs` overrides. */
+    defaultTtlMs?: number;
+    /** Override the clock for tests. Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * In-memory LRU + TTL cache. Backed by a `Map` whose insertion order doubles
+ * as the LRU axis:
+ *   - `set` deletes-then-inserts so the entry moves to the most-recently-used
+ *     end of the iteration order.
+ *   - `get` on a fresh entry also delete-then-inserts (LRU move-to-front).
+ *   - Eviction pops the oldest entry via `keys().next().value`.
+ *
+ * TTL is checked on every `get`: an expired entry is treated as a miss AND
+ * is evicted immediately (lazy expiry — no background sweeper).
+ *
+ * Thread-safety: Node.js is single-threaded for user code. Worker_threads
+ * cannot share `Map` references via structured clone, so the cache is
+ * inherently per-thread. Multi-process deployments need an external cache;
+ * see `IdempotencyCache` interface JSDoc.
+ *
+ * @example
+ *   const cache = new InMemoryIdempotencyCache({ maxEntries: 2048 });
+ *   const client = new SpendGuardClient({ idempotencyCache: cache, ... });
+ */
+declare class InMemoryIdempotencyCache implements IdempotencyCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly defaultTtlMs;
+    private readonly now;
+    constructor(opts?: InMemoryIdempotencyCacheOptions);
+    get(key: string, bodyHash?: string): DecisionOutcome | undefined;
+    set(key: string, outcome: DecisionOutcome, ttlMs?: number, bodyHash?: string): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * No-op cache impl. Always misses on `get`; `set` discards. Useful for:
+ *   - Tests that want to assert every reserved decision hits the sidecar.
+ *   - Disabled-mode short-circuit (when `SPENDGUARD_DISABLE=1`, the client
+ *     never reaches the cache path, but `NoopIdempotencyCache` is the
+ *     conservative-default if an adapter passes `idempotencyCache: undefined`
+ *     and wants explicit no-cache semantics).
+ *
+ * The `size` getter always returns 0; `clear()` is a no-op.
+ */
+declare class NoopIdempotencyCache implements IdempotencyCache {
+    get(_key: string, _bodyHash?: string): DecisionOutcome | undefined;
+    set(_key: string, _outcome: DecisionOutcome, _ttlMs?: number, _bodyHash?: string): void;
+    clear(): void;
+    get size(): number;
+}
+
+export { type UnitRef as $, type ApplyFailedRequest as A, type BudgetClaim as B, type ClaimEstimate as C, DEFAULT_CACHE_MAX_ENTRIES as D, type EmitLlmCallPostRequest as E, type SessionDeltaCommitClient as F, type SessionDeltaCommitInput as G, type HandshakeOutcome as H, type IdempotencyCache as I, SessionPendingDeltaLimitError as J, type SessionReleaseClient as K, type SessionReleaseInput as L, SessionReservationHandle as M, NoopIdempotencyCache as N, SessionReservationHandleError as O, type PendingSessionDelta as P, type QueryBudgetRequest as Q, type RunProjectionPolicy as R, type SessionCommitOutcome as S, type SessionReservationHandleOptions as T, type SessionReservationHandleSnapshot as U, SessionReservationReleasedError as V, SessionReservationReplayMismatchError as W, type SpanRecord as X, SpendGuardClient as Y, type SpendGuardClientConfig as Z, type SpendGuardClientOptions as _, type CommitEstimatedRequest as a, buildCommitSessionDeltaRequest as a0, buildReleaseSessionRequest as a1, buildReserveSessionRequest as a2, type MapGrpcStatusContext as a3, REASON_CODE_PREFIXES as a4, computeReserveBodyHash as a5, type CommitSessionDeltaOutcome as b, type CommitSessionDeltaRequest as c, DEFAULT_CACHE_TTL_MS as d, DEFAULT_CAPABILITY_LEVEL as e, DEFAULT_DECISION_TIMEOUT_MS as f, DEFAULT_HANDSHAKE_TIMEOUT_MS as g, DEFAULT_MAX_PENDING_SESSION_DELTAS as h, DEFAULT_PROTOCOL_VERSION as i, DEFAULT_PUBLISH_TIMEOUT_MS as j, DEFAULT_TRACE_TIMEOUT_MS as k, type DecisionOutcome as l, InMemoryIdempotencyCache as m, type InMemoryIdempotencyCacheOptions as n, type PricingFreeze as o, type PublishOutcomeRequest as p, type QueryBudgetResult as q, type ReleaseOutcome as r, type ReleaseRequest as s, type ReleaseSessionOutcome as t, type ReleaseSessionRequest as u, type ReserveRequest as v, type ReserveSessionOutcome as w, type ReserveSessionRequest as x, type ResolvedConfig as y, type ResumeAfterApprovalRequest as z };