@oxy.so/contracts 1.0.0

package/dist/types/inference/usage.d.ts

@@ -0,0 +1,1164 @@
+/**
+ * The reserve → settle → refund protocol.
+ *
+ * Four records, in the order they happen:
+ *
+ *  1. **Reservation** — before a request enters the data plane, Oxy holds the
+ *     MAXIMUM the request could cost (input units + maximum output + the
+ *     allowed route's price ceiling). A request whose account cannot cover that
+ *     hold is rejected before anything is spent upstream.
+ *  2. **Usage report** — the data plane's technical account of what was
+ *     consumed. Units and route, never money: the data plane measures, the
+ *     control plane prices.
+ *  3. **Receipt** — the immutable settlement. Carries the exact units, a COPY
+ *     of the prices they were charged at, and the amount booked. It is never
+ *     edited afterwards.
+ *  4. **Refund/reversal** — an equally immutable entry that releases an unused
+ *     hold or reverses a settled charge. Settled history is compensated, never
+ *     rewritten, because an invoice a customer already received must remain
+ *     reconstructible.
+ *
+ * Every one of them is keyed by an idempotency key, so a retried call, a
+ * redelivered event or a duplicated webhook produces the same record rather than
+ * a second charge.
+ *
+ * Money is an exact decimal string throughout (ADR 0009 — never integer minor
+ * units, never a float), and unit counts are carried separately from it (see
+ * `money.ts`).
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+import { z } from 'zod';
+/**
+ * Ask the ledger to hold the maximum a request could cost.
+ *
+ * `maxAmount` is the number the balance check is made against, and it is
+ * computed from the three inputs beside it rather than guessed: the units
+ * already known (the prompt), the ceiling on units still to come
+ * (`maxOutputTokens`), and the most expensive route the policy allows. Sizing a
+ * hold from a typical response rather than the worst allowed one is how a
+ * balance goes negative on a long generation.
+ */
+export declare const usageReservationRequestSchema: z.ZodObject<{
+    /** See `version.ts`: exchanged between the edge and the ledger on its own. */
+    schemaVersion: z.ZodLiteral<1>;
+    idempotencyKey: z.ZodString;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+            }, "strict", z.ZodTypeAny, {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            }, {
+                accountId: string;
+            }>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<["development", "staging", "production"]>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }>;
+        userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    }, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    }>;
+    /** Units already determined by the request itself, e.g. input tokens. */
+    knownUnits: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        quantity: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }>, "many">>;
+    /** The ceiling on generated output, when the request set one. */
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    /** The price version of the most expensive route the policy permits. */
+    ceilingPriceVersionId: z.ZodString;
+    maxAmount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+    currency: z.ZodString;
+    expiresInSeconds: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    knownUnits: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    ceilingPriceVersionId: string;
+    maxAmount: string & z.BRAND<"ExactDecimal">;
+    expiresInSeconds: number;
+    maxOutputTokens?: number | undefined;
+}, {
+    schemaVersion: 1;
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    ceilingPriceVersionId: string;
+    maxAmount: string;
+    expiresInSeconds: number;
+    maxOutputTokens?: number | undefined;
+    knownUnits?: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[] | undefined;
+}>;
+/** Lifecycle of a hold. Terminal states are `settled`, `released`, `expired`. */
+export declare const usageReservationStatusSchema: z.ZodEnum<["held", "settled", "released", "expired"]>;
+/**
+ * A hold placed against an account's balance.
+ *
+ * Reserved amounts are shown to customers distinctly from settled charges: a
+ * reservation is not money spent, and presenting the two as one number makes a
+ * balance appear to drop and then recover for every request.
+ */
+export declare const usageReservationSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: read back by the edge and the Console on its own. */
+    schemaVersion: z.ZodLiteral<1>;
+    reservationId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+            }, "strict", z.ZodTypeAny, {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            }, {
+                accountId: string;
+            }>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<["development", "staging", "production"]>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }>;
+        userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    }, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    }>;
+    status: z.ZodEnum<["held", "settled", "released", "expired"]>;
+    reservedAmount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+    currency: z.ZodString;
+    ceilingPriceVersionId: z.ZodString;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    /** The receipt that consumed this hold. Present exactly when `settled`. */
+    settledReceiptId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "expired" | "held" | "settled" | "released";
+    expiresAt: string;
+    createdAt: string;
+    schemaVersion: 1;
+    currency: string;
+    reservationId: string;
+    reservedAmount: string & z.BRAND<"ExactDecimal">;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    ceilingPriceVersionId: string;
+    settledReceiptId?: string | undefined;
+}, {
+    status: "expired" | "held" | "settled" | "released";
+    expiresAt: string;
+    createdAt: string;
+    schemaVersion: 1;
+    currency: string;
+    reservationId: string;
+    reservedAmount: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    ceilingPriceVersionId: string;
+    settledReceiptId?: string | undefined;
+}>, {
+    status: "expired" | "held" | "settled" | "released";
+    expiresAt: string;
+    createdAt: string;
+    schemaVersion: 1;
+    currency: string;
+    reservationId: string;
+    reservedAmount: string & z.BRAND<"ExactDecimal">;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    ceilingPriceVersionId: string;
+    settledReceiptId?: string | undefined;
+}, {
+    status: "expired" | "held" | "settled" | "released";
+    expiresAt: string;
+    createdAt: string;
+    schemaVersion: 1;
+    currency: string;
+    reservationId: string;
+    reservedAmount: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    ceilingPriceVersionId: string;
+    settledReceiptId?: string | undefined;
+}>;
+/** How a request ended, from the data plane's point of view. */
+export declare const inferenceRequestOutcomeSchema: z.ZodEnum<["completed", "partial", "cancelled", "failed"]>;
+/**
+ * The data plane's technical account of one request, and the ONLY shape a
+ * settlement is written from.
+ *
+ * `inferenceStreamUsageEventSchema` is not a narrower version of this one that
+ * could be widened into it — see that event's own comment. Its units are exact
+ * and settleable; the record around them is not inferable, so an edge settling
+ * from a stream event supplies the outcome itself and never promotes the event.
+ *
+ * No money and no price: the data plane measures units and names the route it
+ * used, and the control plane decides what that costs. Keeping the two apart is
+ * what allows a price to be corrected after the fact without re-running or
+ * re-measuring anything.
+ *
+ * `usageSource` is load-bearing when a provider returns no usage at all: the
+ * report still arrives, marked `estimated`, so settlement can apply the
+ * estimation policy knowingly instead of treating a reconstruction as fact.
+ *
+ * `units` is a PARTITION of what the request consumed, not a set of totals with
+ * details hanging off them — see `USAGE_UNITS` in `money.ts`. Reporting a provider's
+ * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
+ * reasoning tokens twice, so subtracting the children out is part of what
+ * "normalized" means in this shape's name.
+ *
+ * **A `completed` report carries at least one unit, and the other outcomes need
+ * not.** `completed` is the one outcome that asserts the customer received the
+ * whole answer, so "delivered in full, consumed nothing measurable" is a
+ * contradiction — and it is one that BILLS NOTHING: settlement prices every
+ * reported unit and sums, so an empty list is a free request produced by a
+ * provider that simply omitted its usage block. The refinement makes that shape
+ * unparseable, and the policy behind it is refuse-and-release: the report is
+ * rejected and the hold is released, never estimated and charged.
+ *
+ * The three other outcomes legitimately carry none, which is why the rule is
+ * conditional rather than a `.min(1)` on the field. In the reference data plane
+ * `failed` is DERIVED from having no units — `outcomeFor` in
+ * Kaana's `internal/kaana/executor.go` returns `partial` when units exist and `failed`
+ * when they do not — and `cancelled` is reported for a client that stopped
+ * before anything was measured. An unconditional minimum would refuse those
+ * reports, and a refused report is a request that ran, cost money upstream and
+ * can never be settled or refunded.
+ */
+export declare const normalizedUsageReportSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: emitted by the data plane as a whole message. */
+    schemaVersion: z.ZodLiteral<2>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+            }, "strict", z.ZodTypeAny, {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            }, {
+                accountId: string;
+            }>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<["development", "staging", "production"]>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }>;
+        userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    }, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    }>;
+    outcome: z.ZodEnum<["completed", "partial", "cancelled", "failed"]>;
+    units: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        quantity: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }>, "many">;
+    usageSource: z.ZodEnum<["provider_reported", "oxy_measured", "estimated"]>;
+    resolvedModelReference: z.ZodString;
+    servingProvider: z.ZodString;
+    /** Exact Kaana deployment that attempted the request; never inferred from names. */
+    deploymentId: z.ZodString;
+    /** How many allowed route switches occurred while serving this request. */
+    routeSwitches: z.ZodNumber;
+    startedAt: z.ZodString;
+    completedAt: z.ZodString;
+    timeToFirstTokenMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 2;
+    requestId: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    deploymentId: string;
+    completedAt: string;
+    startedAt: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    routeSwitches: number;
+    generationId?: string | undefined;
+    timeToFirstTokenMs?: number | undefined;
+}, {
+    schemaVersion: 2;
+    requestId: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    deploymentId: string;
+    completedAt: string;
+    startedAt: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    routeSwitches: number;
+    generationId?: string | undefined;
+    timeToFirstTokenMs?: number | undefined;
+}>, {
+    schemaVersion: 2;
+    requestId: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    deploymentId: string;
+    completedAt: string;
+    startedAt: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    routeSwitches: number;
+    generationId?: string | undefined;
+    timeToFirstTokenMs?: number | undefined;
+}, {
+    schemaVersion: 2;
+    requestId: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    deploymentId: string;
+    completedAt: string;
+    startedAt: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    routeSwitches: number;
+    generationId?: string | undefined;
+    timeToFirstTokenMs?: number | undefined;
+}>;
+/**
+ * The immutable record of what a request was actually charged.
+ *
+ * `priceSnapshot` is a COPY of the unit prices applied, not just the id of the
+ * price version they came from, so the arithmetic on this receipt can be
+ * checked years later without depending on any other record still existing.
+ *
+ * `platformFeeOnly` marks a BYOK request: the upstream provider billed the
+ * customer's own account directly, and `billedAmount` is Oxy's service fee
+ * rather than the cost of the tokens. Without the flag, the two look identical
+ * and a BYOK customer appears to have been charged twice for one request.
+ */
+export declare const usageReceiptSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: returned to customers by `GET /v1/generations/:id`. */
+    schemaVersion: z.ZodLiteral<1>;
+    receiptId: z.ZodString;
+    /** The hold this settled against. Absent for a charge with no reservation. */
+    reservationId: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodString;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+            }, "strict", z.ZodTypeAny, {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            }, {
+                accountId: string;
+            }>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<["development", "staging", "production"]>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }>;
+        userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    }, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    }>;
+    outcome: z.ZodEnum<["completed", "partial", "cancelled", "failed"]>;
+    units: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        quantity: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }>, "many">;
+    usageSource: z.ZodEnum<["provider_reported", "oxy_measured", "estimated"]>;
+    priceSnapshot: z.ZodObject<{
+        priceVersionId: z.ZodString;
+        currency: z.ZodString;
+        unitPrices: z.ZodArray<z.ZodObject<{
+            unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+            amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+            per: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            currency: string;
+            amount: string & z.BRAND<"ExactDecimal">;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }, {
+            currency: string;
+            amount: string;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string & z.BRAND<"ExactDecimal">;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    }, {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    }>;
+    billedAmount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+    currency: z.ZodString;
+    platformFeeOnly: z.ZodBoolean;
+    resolvedModelReference: z.ZodString;
+    servingProvider: z.ZodString;
+    settledAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    receiptId: string;
+    settledAt: string;
+    billedAmount: string & z.BRAND<"ExactDecimal">;
+    currency: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    platformFeeOnly: boolean;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    priceSnapshot: {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string & z.BRAND<"ExactDecimal">;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    };
+    reservationId?: string | undefined;
+}, {
+    schemaVersion: 1;
+    receiptId: string;
+    settledAt: string;
+    billedAmount: string;
+    currency: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    platformFeeOnly: boolean;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    priceSnapshot: {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    };
+    reservationId?: string | undefined;
+}>, {
+    schemaVersion: 1;
+    receiptId: string;
+    settledAt: string;
+    billedAmount: string & z.BRAND<"ExactDecimal">;
+    currency: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    platformFeeOnly: boolean;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    priceSnapshot: {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string & z.BRAND<"ExactDecimal">;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    };
+    reservationId?: string | undefined;
+}, {
+    schemaVersion: 1;
+    receiptId: string;
+    settledAt: string;
+    billedAmount: string;
+    currency: string;
+    outcome: "failed" | "cancelled" | "completed" | "partial";
+    resolvedModelReference: string;
+    servingProvider: string;
+    platformFeeOnly: boolean;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+    priceSnapshot: {
+        currency: string;
+        priceVersionId: string;
+        unitPrices: {
+            currency: string;
+            amount: string;
+            unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+            per: number;
+        }[];
+    };
+    reservationId?: string | undefined;
+}>;
+/**
+ * What a reversal acts on: an unused hold, or a settled charge.
+ *
+ * A discriminated union, so "release the rest of the hold" and "give back money
+ * already booked" can never be confused for one another — they hit different
+ * ledger accounts and only the second one is visible on an invoice.
+ */
+export declare const usageRefundSubjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"reservation">;
+    reservationId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "reservation";
+    reservationId: string;
+}, {
+    kind: "reservation";
+    reservationId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"receipt">;
+    receiptId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "receipt";
+    receiptId: string;
+}, {
+    kind: "receipt";
+    receiptId: string;
+}>]>;
+/** Why money was given back or a hold was released. */
+export declare const usageRefundReasonSchema: z.ZodEnum<["unused_reservation", "client_cancelled", "upstream_failure", "partial_stream", "usage_unavailable", "billing_correction", "duplicate_charge"]>;
+/**
+ * An immutable reversal entry.
+ *
+ * `amount` is non-negative like every other amount in this contract: the
+ * direction is carried by the record being a refund, not by a sign that a
+ * consumer could read the wrong way round. Idempotent by key, so a retried
+ * refund releases the same money once.
+ */
+export declare const usageRefundSchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: a ledger record read back on its own. */
+    schemaVersion: z.ZodLiteral<1>;
+    refundId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+            }, "strict", z.ZodTypeAny, {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            }, {
+                accountId: string;
+            }>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<["development", "staging", "production"]>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }, {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        }>;
+        userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    }, {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    }>;
+    subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"reservation">;
+        reservationId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "reservation";
+        reservationId: string;
+    }, {
+        kind: "reservation";
+        reservationId: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"receipt">;
+        receiptId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "receipt";
+        receiptId: string;
+    }, {
+        kind: "receipt";
+        receiptId: string;
+    }>]>;
+    reason: z.ZodEnum<["unused_reservation", "client_cancelled", "upstream_failure", "partial_stream", "usage_unavailable", "billing_correction", "duplicate_charge"]>;
+    amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+    currency: z.ZodString;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    reason: "unused_reservation" | "client_cancelled" | "upstream_failure" | "partial_stream" | "usage_unavailable" | "billing_correction" | "duplicate_charge";
+    schemaVersion: 1;
+    subject: {
+        kind: "reservation";
+        reservationId: string;
+    } | {
+        kind: "receipt";
+        receiptId: string;
+    };
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    amount: string & z.BRAND<"ExactDecimal">;
+    refundId: string;
+}, {
+    createdAt: string;
+    reason: "unused_reservation" | "client_cancelled" | "upstream_failure" | "partial_stream" | "usage_unavailable" | "billing_correction" | "duplicate_charge";
+    schemaVersion: 1;
+    subject: {
+        kind: "reservation";
+        reservationId: string;
+    } | {
+        kind: "receipt";
+        receiptId: string;
+    };
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    amount: string;
+    refundId: string;
+}>, {
+    createdAt: string;
+    reason: "unused_reservation" | "client_cancelled" | "upstream_failure" | "partial_stream" | "usage_unavailable" | "billing_correction" | "duplicate_charge";
+    schemaVersion: 1;
+    subject: {
+        kind: "reservation";
+        reservationId: string;
+    } | {
+        kind: "receipt";
+        receiptId: string;
+    };
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string & z.BRAND<"OxyAccountId">;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    amount: string & z.BRAND<"ExactDecimal">;
+    refundId: string;
+}, {
+    createdAt: string;
+    reason: "unused_reservation" | "client_cancelled" | "upstream_failure" | "partial_stream" | "usage_unavailable" | "billing_correction" | "duplicate_charge";
+    schemaVersion: 1;
+    subject: {
+        kind: "reservation";
+        reservationId: string;
+    } | {
+        kind: "receipt";
+        receiptId: string;
+    };
+    currency: string;
+    attribution: {
+        requestId: string;
+        principal: {
+            environment: "development" | "staging" | "production";
+            applicationId: string;
+            credentialId: string;
+            billing: {
+                accountId: string;
+            };
+            inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+        };
+        userId?: string | undefined;
+        generationId?: string | undefined;
+    };
+    idempotencyKey: string;
+    amount: string;
+    refundId: string;
+}>;
+export type UsageReservationRequest = z.infer<typeof usageReservationRequestSchema>;
+export type UsageReservationStatus = z.infer<typeof usageReservationStatusSchema>;
+export type UsageReservation = z.infer<typeof usageReservationSchema>;
+export type InferenceRequestOutcome = z.infer<typeof inferenceRequestOutcomeSchema>;
+export type NormalizedUsageReport = z.infer<typeof normalizedUsageReportSchema>;
+export type UsageReceipt = z.infer<typeof usageReceiptSchema>;
+export type UsageRefundSubject = z.infer<typeof usageRefundSubjectSchema>;
+export type UsageRefundReason = z.infer<typeof usageRefundReasonSchema>;
+export type UsageRefund = z.infer<typeof usageRefundSchema>;