@oxyhq/contracts 0.27.0 → 0.28.0

package/dist/esm/inference/money.js

@@ -85,6 +85,49 @@ export const moneySchema = z
 /**
  * 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/esm/inference/usage.js

@@ -128,6 +128,12 @@ export const inferenceRequestOutcomeSchema = z.enum([
  * `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 const normalizedUsageReportSchema = z
     .object({

package/dist/esm/inference/version.js

@@ -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.
  */
 /**