@oxyhq/contracts 0.27.0 → 0.28.0

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

@@ -78,6 +78,49 @@ export declare const moneySchema: z.ZodObject<{
 /**
  * The closed set of units inference is metered in.
  *
+ * **The units PARTITION a request: every unit counts material no other unit
+ * counts.** `cached_input_tokens` is not part of `input_tokens`, and
+ * `reasoning_tokens` is not part of `output_tokens` — they are siblings, not
+ * subsets. A request whose 10 000-token prompt was served 9 000 tokens from
+ * cache is reported as `input_tokens: 1000` beside `cached_input_tokens: 9000`,
+ * never as `input_tokens: 10000` beside it.
+ *
+ * That belongs to the definition rather than to a convention somewhere else,
+ * because settlement applies a price to EVERY reported unit and sums them
+ * (`inferenceLedger.service.ts`'s `computeCharge`). Under the partition rule
+ * that sum IS the request's cost, and a cached token can carry its own — lower
+ * — price. Under the nested reading the same sum charges the cached and
+ * reasoning tokens twice: once inside their parent and once on their own line.
+ * It fails silently, because every total still looks plausible and the receipt
+ * is still internally consistent, and on a reasoning model the reasoning tokens
+ * can dominate the completion, so the error is not marginal.
+ *
+ * **Every OpenAI-compatible provider reports the other way round**:
+ * `prompt_tokens` INCLUDES `prompt_tokens_details.cached_tokens`, and
+ * `completion_tokens` INCLUDES `completion_tokens_details.reasoning_tokens`.
+ * Normalising is the data plane's job and it is subtraction:
+ *
+ * ```text
+ * input_tokens  = prompt_tokens     - prompt_tokens_details.cached_tokens
+ * output_tokens = completion_tokens - completion_tokens_details.reasoning_tokens
+ * ```
+ *
+ * No refinement in this package can enforce it, and saying so is part of the
+ * rule: a nested report and a disjoint one are the same four non-negative
+ * integers, so no predicate over a single report can tell them apart. The two
+ * structural guards that DO exist — refining `cached <= input` and
+ * `reasoning <= output`, or deriving the parents instead of reporting them —
+ * both encode the nested reading, which is the one this rule rejects. What IS
+ * enforceable is the arithmetic that depends on the rule, and that is where the
+ * enforcement lives — `inferenceLedger.service.test.ts` prices a report in
+ * which cached and reasoning tokens are both non-zero and asserts the exact
+ * total, which the nested reading cannot produce.
+ *
+ * Where the public surface has to speak a nested dialect, the sum is put back
+ * at the boundary rather than the internal reading being bent to it
+ * (`routes/inferenceEdge.ts` renders `prompt_tokens` as
+ * `input_tokens + cached_input_tokens`).
+ *
  * Time is carried in integer MILLISECONDS rather than seconds so that no unit
  * quantity is ever fractional: a 12.5-second transcription is `12500`, exactly,
  * and the "units are integers" rule holds for every modality instead of holding

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

@@ -345,7 +345,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
     /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
     error: z.ZodEffects<z.ZodObject<{
         schemaVersion: z.ZodLiteral<1>;
-        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "service_unavailable", "internal_error"]>;
+        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "provider_credential_invalid", "service_unavailable", "internal_error"]>;
         message: z.ZodEffects<z.ZodString, string, string>;
         retryable: z.ZodBoolean;
         requestId: z.ZodString;
@@ -369,7 +369,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
             status?: number | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -384,7 +384,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
             status?: number | undefined;
         } | undefined;
     }, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -399,7 +399,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
             status?: number | undefined;
         } | undefined;
     }>, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -414,7 +414,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
             status?: number | undefined;
         } | undefined;
     }, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -435,7 +435,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
     schemaVersion: 1;
     sequence: number;
     error: {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -456,7 +456,7 @@ export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
     schemaVersion: 1;
     sequence: number;
     error: {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -738,7 +738,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
     error: z.ZodEffects<z.ZodObject<{
         schemaVersion: z.ZodLiteral<1>;
-        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "service_unavailable", "internal_error"]>;
+        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "provider_credential_invalid", "service_unavailable", "internal_error"]>;
         message: z.ZodEffects<z.ZodString, string, string>;
         retryable: z.ZodBoolean;
         requestId: z.ZodString;
@@ -762,7 +762,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
             status?: number | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -777,7 +777,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
             status?: number | undefined;
         } | undefined;
     }, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -792,7 +792,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
             status?: number | undefined;
         } | undefined;
     }>, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -807,7 +807,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
             status?: number | undefined;
         } | undefined;
     }, {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -828,7 +828,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     schemaVersion: 1;
     sequence: number;
     error: {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;
@@ -849,7 +849,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     schemaVersion: 1;
     sequence: number;
     error: {
-        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "service_unavailable" | "internal_error";
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "service_unavailable" | "internal_error";
         message: string;
         requestId: string;
         schemaVersion: 1;

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

@@ -370,6 +370,12 @@ export declare const inferenceRequestOutcomeSchema: z.ZodEnum<["completed", "par
  * `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.
  */
 export declare const normalizedUsageReportSchema: z.ZodEffects<z.ZodObject<{
     /** See `version.ts`: emitted by the data plane as a whole message. */

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

@@ -34,6 +34,34 @@
  * field is additive and does not bump it, because a consumer on the previous
  * version parses the message correctly and simply does not read the new field.
  *
+ * ## Which shapes reject an unknown field
+ *
+ * That last rule is why the shapes EXCHANGED WITH THE DATA PLANE are not
+ * `.strict()` at their top level — the request envelope, the four usage records,
+ * the stream events, the error body, the catalogue descriptors, the price
+ * version. The split is a decision rather than an omission: `.strict()` and
+ * "adding an optional field is additive" cannot both hold on one shape, because
+ * a producer one minor version ahead would have its whole message REFUSED
+ * rather than its new field ignored. For a usage report that means a request
+ * already served upstream can never be settled and Oxy absorbs its cost, which
+ * is a worse failure than the one strictness would have caught.
+ *
+ * Their LEAVES are strict, and that is where the protection lives: a stripped
+ * field is the worse outcome exactly where it would be a leak or a second
+ * source of truth, because it disappears at this parse and survives in the
+ * producer, which is where somebody eventually reads it. So
+ * `clientRequestMetadataSchema` (no IP, ever), `moneySchema` (no convenience
+ * float beside the exact decimal), `providerErrorPassthroughSchema` (no
+ * upstream request or headers beside the message), `usageQuantitySchema` and
+ * `unitPriceSchema` all refuse an unknown field, while the envelope carrying
+ * them tolerates an additive one.
+ *
+ * A shape Oxy does NOT exchange with the data plane is strict at its top level
+ * too, since nothing there can run ahead of this package:
+ * `providerConnectionSchema`, where an unknown field is how a BYOK credential
+ * escapes, and the billing and entitlement records, where one is a second
+ * number beside an exact amount.
+ *
  * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
  */
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",