@oxyhq/contracts 0.27.0 → 0.28.0

package/dist/cjs/inference/errors.js

@@ -35,6 +35,12 @@ const identifiers_1 = require("./identifiers");
  * `quota_exceeded`, `byok_credential_invalid`), routing/permission policy
  * (`policy_violation`, `commercial_permission_denied`, `no_route_available`),
  * and the platform or its upstreams (everything from `deployment_unavailable`).
+ *
+ * The platform group is NOT uniformly retryable, and that is the point of
+ * `provider_credential_invalid` sitting in it: an upstream that refuses the
+ * PLATFORM's own credential fails every identical retry until an operator
+ * rotates a key, so classifying it as `provider_error` would send every client
+ * into a retry loop against a request that cannot succeed.
  */
 exports.INFERENCE_ERROR_CODES = [
     'invalid_request',
@@ -61,6 +67,7 @@ exports.INFERENCE_ERROR_CODES = [
     'provider_error',
     'provider_timeout',
     'provider_overloaded',
+    'provider_credential_invalid',
     'service_unavailable',
     'internal_error',
 ];
@@ -73,6 +80,13 @@ exports.inferenceErrorCodeSchema = zod_1.z.enum(exports.INFERENCE_ERROR_CODES);
  * names, while a quota is an account-level ceiling that only a human raises.
  * `cancelled` is here because the caller already withdrew the request; a client
  * that retries it is contradicting its own cancellation.
+ *
+ * `byok_credential_invalid` and `provider_credential_invalid` are the same
+ * failure seen from the two sides of the BYOK boundary — the customer's own
+ * upstream credential and the platform's — and they are two codes rather than
+ * one because only the first names an action the customer can take. Both are
+ * non-retryable for the same reason: a credential an upstream has refused keeps
+ * being refused until somebody replaces it.
  */
 exports.NON_RETRYABLE_INFERENCE_ERROR_CODES = [
     'invalid_request',
@@ -94,6 +108,7 @@ exports.NON_RETRYABLE_INFERENCE_ERROR_CODES = [
     'no_route_available',
     'upstream_content_filtered',
     'cancelled',
+    'provider_credential_invalid',
 ];
 const NON_RETRYABLE_CODE_SET = new Set(exports.NON_RETRYABLE_INFERENCE_ERROR_CODES);
 /**

package/dist/cjs/inference/identifiers.js

@@ -57,9 +57,17 @@ exports.oxyApplicationIdSchema = zod_1.z.string().min(1).max(64);
 /** An Oxy `ApplicationCredential._id` — the credential used for this request. */
 exports.oxyCredentialIdSchema = zod_1.z.string().min(1).max(64);
 /**
- * A request id generated by the data plane. Correlates the Oxy edge, the data
- * plane, the financial ledger and the customer-visible receipt, so it appears on
- * every stream event and every ledger record.
+ * A request id allocated by the Oxy EDGE, at admission and BEFORE
+ * authentication, so that a request rejected for a bad credential is as
+ * traceable as one that was served (ADR 0007, and step 1 of ADR 0010's edge
+ * order). It is required on the inbound envelope, which is what makes the data
+ * plane a consumer of this id rather than its source: the data plane echoes it
+ * on every stream event, on the usage report and on anything it can be asked
+ * about later.
+ *
+ * Correlates the Oxy edge, the data plane, the financial ledger and the
+ * customer-visible receipt, so it appears on every stream event and every
+ * ledger record.
  */
 exports.requestIdSchema = zod_1.z.string().min(1).max(128);
 /**

package/dist/cjs/inference/money.js

@@ -88,6 +88,49 @@ exports.moneySchema = zod_1.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/cjs/inference/usage.js

@@ -131,6 +131,12 @@ exports.inferenceRequestOutcomeSchema = zod_1.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.
  */
 exports.normalizedUsageReportSchema = zod_1.z
     .object({

package/dist/cjs/inference/version.js

@@ -35,6 +35,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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });