@oxyhq/contracts 0.27.0 → 0.29.0

package/dist/cjs/index.js

@@ -18,7 +18,7 @@ exports.hubActivateRequestSchema = exports.hubClaimRequestSchema = exports.hubSe
 exports.transparencyCheckpointSchema = exports.transparencyAnchorSchema = exports.transparencyCheckpointSignatureSchema = exports.deviceTransferDenyResponseSchema = exports.deviceTransferApproveResponseSchema = exports.deviceTransferApproveRequestSchema = exports.deviceTransferInfoResponseSchema = exports.deviceTransferInitResponseSchema = exports.deviceTransferInitRequestSchema = exports.devicePairingStatusSchema = exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = exports.updateRolloutPatchSchema = exports.promoteRequestSchema = exports.rollbackToEmbeddedRequestSchema = exports.rollbackRequestSchema = exports.updateListResponseSchema = exports.channelListResponseSchema = exports.channelSchema = exports.rollbackToEmbeddedEntrySchema = exports.createUpdateResponseSchema = exports.updateSchema = exports.createUpdateRequestSchema = exports.updateAssetRefSchema = exports.assetCompleteResponseSchema = exports.assetCompleteResultItemSchema = exports.assetCompleteRequestSchema = exports.assetInitResponseSchema = exports.assetUploadTicketSchema = exports.assetInitRequestSchema = exports.assetInitItemSchema = exports.rolloutPercentSchema = exports.runtimeVersionSchema = exports.channelNameSchema = exports.sha256HexSchema = exports.updateAssetStatusSchema = exports.updateStatusSchema = exports.updatePlatformSchema = exports.backupStatusResponseSchema = exports.backupUploadRequestSchema = exports.encryptedBackupEnvelopeSchema = exports.backupLookupIdSchema = exports.rotateKeyCompleteResponseSchema = exports.rotateKeyCompleteRequestSchema = exports.rotateKeyChallengeResponseSchema = exports.loginResultSchema = exports.hubAuthorizeResultSchema = exports.hubAuthorizeRequestSchema = void 0;
 exports.inferenceModalitySchema = exports.priceSnapshotSchema = exports.priceVersionSchema = exports.priceVersionStatusSchema = exports.inferenceErrorSchema = exports.providerErrorPassthroughSchema = exports.safeErrorTextSchema = exports.upstreamErrorCategorySchema = exports.inferenceErrorCodeSchema = exports.NON_RETRYABLE_INFERENCE_ERROR_CODES = exports.INFERENCE_ERROR_CODES = exports.inferenceAttributionSchema = exports.authenticatedPrincipalSchema = exports.billingPrincipalSchema = exports.inferenceScopeSchema = exports.INFERENCE_SCOPES = exports.unitPriceSchema = exports.usageQuantitySchema = exports.usageSourceSchema = exports.USAGE_SOURCES = exports.usageUnitSchema = exports.USAGE_UNITS = exports.moneySchema = exports.exactDecimalSchema = exports.INFERENCE_MONEY_SCALE = exports.currencyCodeSchema = exports.RESERVED_ALIA_PUBLISHER = exports.inferenceRegionSchema = exports.deploymentIdSchema = exports.inferenceProviderSlugSchema = exports.routingProfileSlugSchema = exports.modelReferenceSchema = exports.modelRevisionLabelSchema = exports.modelIdSchema = exports.modelSlugSchema = exports.publisherSlugSchema = exports.inferenceHttpsUrlSchema = exports.inferenceDateSchema = exports.inferenceTimestampSchema = exports.inferenceEnvironmentSchema = exports.idempotencyKeySchema = exports.generationIdSchema = exports.requestIdSchema = exports.oxyCredentialIdSchema = exports.oxyApplicationIdSchema = exports.delegatedUserIdSchema = exports.oxyAccountIdSchema = exports.INFERENCE_CONTRACT_VERSION = exports.transparencyCheckpointListSchema = exports.transparencyInclusionProofSchema = void 0;
 exports.usageReservationSchema = exports.usageReservationStatusSchema = exports.usageReservationRequestSchema = exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = exports.inferenceRequestSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = exports.routingPolicyReferenceSchema = exports.routingPolicySchema = exports.routingFallbackPolicySchema = exports.routingPolicyScopeSchema = exports.routingTargetSchema = exports.modelCatalogueEntrySchema = exports.catalogueServingProviderSummarySchema = exports.cataloguePublisherSummarySchema = exports.routingProfileSchema = exports.routingProfileCandidateSchema = exports.modelDeploymentSchema = exports.inferenceProviderSchema = exports.modelRevisionSchema = exports.catalogueModelSchema = exports.modelPublisherSchema = exports.modelSafetyMetadataSchema = exports.modelEvaluationResultSchema = exports.modelDeprecationSchema = exports.commercialPermissionSchema = exports.availabilityScopeSchema = exports.inferenceDataPolicySchema = exports.modelProvenanceSchema = exports.modelLicenseSchema = exports.modelCapabilitiesSchema = void 0;
-exports.providerConnectionSchema = exports.providerConnectionStatusSchema = exports.providerConnectionValidationSchema = exports.providerSecretReferenceSchema = exports.providerConnectionScopeSchema = exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = void 0;
+exports.productEntitlementSchema = exports.costCenterSpendSchema = exports.costCenterSchema = exports.costCenterStatusSchema = exports.COST_CENTER_STATUSES = exports.payAsYouGoEntitlementSchema = exports.productPlanSchema = exports.planAllowanceSchema = exports.LIVE_PRODUCT_PLAN_STATUSES = exports.productPlanStatusSchema = exports.PRODUCT_PLAN_STATUSES = exports.reconciliationReportSchema = exports.reconciliationRunSchema = exports.reconciliationDiscrepancySchema = exports.reconciliationRunStatusSchema = exports.RECONCILIATION_RUN_STATUSES = exports.reconciliationDiscrepancyKindSchema = exports.RECONCILIATION_DISCREPANCY_KINDS = exports.autoRechargeAttemptSchema = exports.autoRechargeStatusSchema = exports.AUTO_RECHARGE_STATUSES = exports.externalPaymentSchema = exports.externalPaymentKindSchema = exports.EXTERNAL_PAYMENT_KINDS = exports.externalPaymentProviderSchema = exports.EXTERNAL_PAYMENT_PROVIDERS = exports.billingInvoiceSchema = exports.billingInvoiceStatusSchema = exports.BILLING_INVOICE_STATUSES = exports.accountBillingStateSchema = exports.billingProfileSchema = exports.autoRechargeSchema = exports.billingProfileStatusSchema = exports.BILLING_PROFILE_STATUSES = exports.billingModeSchema = exports.BILLING_MODES = exports.providerConnectionSchema = exports.providerConnectionStatusSchema = exports.providerConnectionValidationSchema = exports.providerSecretReferenceSchema = exports.providerConnectionScopeSchema = exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = void 0;
 var accountGraph_1 = require("./accountGraph");
 Object.defineProperty(exports, "ACCOUNT_KINDS", { enumerable: true, get: function () { return accountGraph_1.ACCOUNT_KINDS; } });
 Object.defineProperty(exports, "accountKindSchema", { enumerable: true, get: function () { return accountGraph_1.accountKindSchema; } });
@@ -472,3 +472,46 @@ Object.defineProperty(exports, "providerSecretReferenceSchema", { enumerable: tr
 Object.defineProperty(exports, "providerConnectionValidationSchema", { enumerable: true, get: function () { return providerConnection_1.providerConnectionValidationSchema; } });
 Object.defineProperty(exports, "providerConnectionStatusSchema", { enumerable: true, get: function () { return providerConnection_1.providerConnectionStatusSchema; } });
 Object.defineProperty(exports, "providerConnectionSchema", { enumerable: true, get: function () { return providerConnection_1.providerConnectionSchema; } });
+var accountBilling_1 = require("./inference/accountBilling");
+// Account-scoped billing: who pays, what they hold, what bounds them, and
+// how it reconciles against the payment processor. A grant and a purchase
+// are never one number — there is deliberately no total.
+Object.defineProperty(exports, "BILLING_MODES", { enumerable: true, get: function () { return accountBilling_1.BILLING_MODES; } });
+Object.defineProperty(exports, "billingModeSchema", { enumerable: true, get: function () { return accountBilling_1.billingModeSchema; } });
+Object.defineProperty(exports, "BILLING_PROFILE_STATUSES", { enumerable: true, get: function () { return accountBilling_1.BILLING_PROFILE_STATUSES; } });
+Object.defineProperty(exports, "billingProfileStatusSchema", { enumerable: true, get: function () { return accountBilling_1.billingProfileStatusSchema; } });
+Object.defineProperty(exports, "autoRechargeSchema", { enumerable: true, get: function () { return accountBilling_1.autoRechargeSchema; } });
+Object.defineProperty(exports, "billingProfileSchema", { enumerable: true, get: function () { return accountBilling_1.billingProfileSchema; } });
+Object.defineProperty(exports, "accountBillingStateSchema", { enumerable: true, get: function () { return accountBilling_1.accountBillingStateSchema; } });
+Object.defineProperty(exports, "BILLING_INVOICE_STATUSES", { enumerable: true, get: function () { return accountBilling_1.BILLING_INVOICE_STATUSES; } });
+Object.defineProperty(exports, "billingInvoiceStatusSchema", { enumerable: true, get: function () { return accountBilling_1.billingInvoiceStatusSchema; } });
+Object.defineProperty(exports, "billingInvoiceSchema", { enumerable: true, get: function () { return accountBilling_1.billingInvoiceSchema; } });
+Object.defineProperty(exports, "EXTERNAL_PAYMENT_PROVIDERS", { enumerable: true, get: function () { return accountBilling_1.EXTERNAL_PAYMENT_PROVIDERS; } });
+Object.defineProperty(exports, "externalPaymentProviderSchema", { enumerable: true, get: function () { return accountBilling_1.externalPaymentProviderSchema; } });
+Object.defineProperty(exports, "EXTERNAL_PAYMENT_KINDS", { enumerable: true, get: function () { return accountBilling_1.EXTERNAL_PAYMENT_KINDS; } });
+Object.defineProperty(exports, "externalPaymentKindSchema", { enumerable: true, get: function () { return accountBilling_1.externalPaymentKindSchema; } });
+Object.defineProperty(exports, "externalPaymentSchema", { enumerable: true, get: function () { return accountBilling_1.externalPaymentSchema; } });
+Object.defineProperty(exports, "AUTO_RECHARGE_STATUSES", { enumerable: true, get: function () { return accountBilling_1.AUTO_RECHARGE_STATUSES; } });
+Object.defineProperty(exports, "autoRechargeStatusSchema", { enumerable: true, get: function () { return accountBilling_1.autoRechargeStatusSchema; } });
+Object.defineProperty(exports, "autoRechargeAttemptSchema", { enumerable: true, get: function () { return accountBilling_1.autoRechargeAttemptSchema; } });
+Object.defineProperty(exports, "RECONCILIATION_DISCREPANCY_KINDS", { enumerable: true, get: function () { return accountBilling_1.RECONCILIATION_DISCREPANCY_KINDS; } });
+Object.defineProperty(exports, "reconciliationDiscrepancyKindSchema", { enumerable: true, get: function () { return accountBilling_1.reconciliationDiscrepancyKindSchema; } });
+Object.defineProperty(exports, "RECONCILIATION_RUN_STATUSES", { enumerable: true, get: function () { return accountBilling_1.RECONCILIATION_RUN_STATUSES; } });
+Object.defineProperty(exports, "reconciliationRunStatusSchema", { enumerable: true, get: function () { return accountBilling_1.reconciliationRunStatusSchema; } });
+Object.defineProperty(exports, "reconciliationDiscrepancySchema", { enumerable: true, get: function () { return accountBilling_1.reconciliationDiscrepancySchema; } });
+Object.defineProperty(exports, "reconciliationRunSchema", { enumerable: true, get: function () { return accountBilling_1.reconciliationRunSchema; } });
+Object.defineProperty(exports, "reconciliationReportSchema", { enumerable: true, get: function () { return accountBilling_1.reconciliationReportSchema; } });
+var entitlement_1 = require("./inference/entitlement");
+// Product entitlements. Allowances are integer counts and money is an exact
+// decimal, so a plan allowance cannot be added to a balance.
+Object.defineProperty(exports, "PRODUCT_PLAN_STATUSES", { enumerable: true, get: function () { return entitlement_1.PRODUCT_PLAN_STATUSES; } });
+Object.defineProperty(exports, "productPlanStatusSchema", { enumerable: true, get: function () { return entitlement_1.productPlanStatusSchema; } });
+Object.defineProperty(exports, "LIVE_PRODUCT_PLAN_STATUSES", { enumerable: true, get: function () { return entitlement_1.LIVE_PRODUCT_PLAN_STATUSES; } });
+Object.defineProperty(exports, "planAllowanceSchema", { enumerable: true, get: function () { return entitlement_1.planAllowanceSchema; } });
+Object.defineProperty(exports, "productPlanSchema", { enumerable: true, get: function () { return entitlement_1.productPlanSchema; } });
+Object.defineProperty(exports, "payAsYouGoEntitlementSchema", { enumerable: true, get: function () { return entitlement_1.payAsYouGoEntitlementSchema; } });
+Object.defineProperty(exports, "COST_CENTER_STATUSES", { enumerable: true, get: function () { return entitlement_1.COST_CENTER_STATUSES; } });
+Object.defineProperty(exports, "costCenterStatusSchema", { enumerable: true, get: function () { return entitlement_1.costCenterStatusSchema; } });
+Object.defineProperty(exports, "costCenterSchema", { enumerable: true, get: function () { return entitlement_1.costCenterSchema; } });
+Object.defineProperty(exports, "costCenterSpendSchema", { enumerable: true, get: function () { return entitlement_1.costCenterSpendSchema; } });
+Object.defineProperty(exports, "productEntitlementSchema", { enumerable: true, get: function () { return entitlement_1.productEntitlementSchema; } });

package/dist/cjs/inference/accountBilling.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * The account-scoped billing surface: who pays, what they hold, what bounds
+ * them, and how it reconciles against the payment processor.
+ *
+ * Every shape here is denominated in {@link exactDecimalSchema} — an exact
+ * decimal string — for the reason `money.ts` gives at length: a JS `number`
+ * cannot represent `0.1 + 0.2`, and a balance is the last place a rounding error
+ * should be allowed to accumulate silently.
+ *
+ * ## What is NOT here, and where it is instead
+ *
+ * The BALANCE and the BUDGETS both live at `/inference/reporting` (#972
+ * workstream 8), which owns the customer's view of what they hold and what
+ * bounds them, stamped `{source, consistency}` so a reader can always tell which
+ * kind of number they are looking at. This file declares who PAYS and on what
+ * TERMS, plus the records that sit behind those numbers — invoices, processor
+ * payments, auto-recharge attempts and reconciliation.
+ *
+ * The split is not cosmetic. A second balance shape here would be a second
+ * answer to one question, and the pair would disagree the day one of them stops
+ * accounting for an invoiced account's unused credit line — which is exactly the
+ * kind of drift a customer discovers before we do.
+ *
+ * ## Product entitlements are NOT here
+ *
+ * Alia plans, their monthly allowances and the API-credit product live in
+ * `entitlement.ts`, in a shape that cannot be added to a balance. #972 is
+ * explicit that confusing a product subscription with pay-as-you-go inference
+ * spend is the failure mode, so the two are separate types that share no field
+ * and no unit.
+ *
+ * ## Stripe appears only as a REFERENCE
+ *
+ * `externalRef` names a record in the processor's database; nothing in this file
+ * is derived from Stripe, and no shape here can carry a processor-computed
+ * balance. The epic's invariant is that Stripe is a payment and invoicing
+ * processor and not the authoritative usage ledger, so the reconciliation shapes
+ * below describe a COMPARISON between two independent records rather than an
+ * import of one into the other.
+ *
+ * Decided in: docs/adr/0014-account-billing-and-entitlements.md,
+ * docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconciliationReportSchema = exports.reconciliationRunSchema = exports.reconciliationDiscrepancySchema = exports.reconciliationRunStatusSchema = exports.RECONCILIATION_RUN_STATUSES = exports.reconciliationDiscrepancyKindSchema = exports.RECONCILIATION_DISCREPANCY_KINDS = exports.autoRechargeAttemptSchema = exports.autoRechargeStatusSchema = exports.AUTO_RECHARGE_STATUSES = exports.externalPaymentSchema = exports.externalPaymentKindSchema = exports.EXTERNAL_PAYMENT_KINDS = exports.externalPaymentProviderSchema = exports.EXTERNAL_PAYMENT_PROVIDERS = exports.billingInvoiceSchema = exports.billingInvoiceStatusSchema = exports.BILLING_INVOICE_STATUSES = exports.accountBillingStateSchema = exports.billingProfileSchema = exports.autoRechargeSchema = exports.billingProfileStatusSchema = exports.BILLING_PROFILE_STATUSES = exports.billingModeSchema = exports.BILLING_MODES = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+/* -------------------------------------------------------------------------- */
+/*  Billing profile                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * How an account pays.
+ *
+ * `prepaid` spends money it topped up in advance. `invoiced` draws against a
+ * credit limit and is billed in arrears — the enterprise shape. Both settle
+ * through the same ledger; the difference is only which bucket a reservation
+ * draws from once the prepaid and granted balances are exhausted.
+ */
+exports.BILLING_MODES = ['prepaid', 'invoiced'];
+exports.billingModeSchema = zod_1.z.enum(exports.BILLING_MODES);
+/** Whether the profile may currently spend at all. */
+exports.BILLING_PROFILE_STATUSES = ['active', 'suspended', 'closed'];
+exports.billingProfileStatusSchema = zod_1.z.enum(exports.BILLING_PROFILE_STATUSES);
+/**
+ * Automatic top-up settings.
+ *
+ * An IMPLICATION rather than a biconditional, matching the column CHECK: the
+ * two amounts may be configured before the feature is switched on, but an
+ * `enabled` recharge with either missing is a setting that reads as "on" and can
+ * never fire — the shape a customer discovers only when their traffic stops.
+ */
+exports.autoRechargeSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean(),
+    /** Recharge when the spendable balance falls below this. */
+    threshold: money_1.exactDecimalSchema.optional(),
+    /** How much to add. */
+    amount: money_1.exactDecimalSchema.optional(),
+})
+    .strict()
+    .refine((value) => !value.enabled || (value.threshold !== undefined && value.amount !== undefined), { message: 'an enabled auto-recharge must carry both a threshold and an amount' });
+/**
+ * Which account pays for a workload, and on what terms.
+ *
+ * `accountId` is an Oxy account of ANY kind — personal, organization, project,
+ * bot or channel — because `Application.ownerAccountId` may be any of them. It
+ * is branded (`oxyAccountIdSchema`), so a delegated end-user id cannot be
+ * substituted for it anywhere in this contract.
+ */
+exports.billingProfileSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    currency: money_1.currencyCodeSchema,
+    billingMode: exports.billingModeSchema,
+    status: exports.billingProfileStatusSchema,
+    /**
+     * How far an `invoiced` account may draw before a reservation is refused.
+     * Always `'0'` for a `prepaid` account, where it is not consulted at all.
+     */
+    creditLimit: money_1.exactDecimalSchema,
+    autoRecharge: exports.autoRechargeSchema,
+    createdAt: zod_1.z.string().datetime(),
+    updatedAt: zod_1.z.string().datetime(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Billing state                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * WHO pays for an account and on what TERMS. Deliberately not how much they
+ * have.
+ *
+ * The balance lives at `GET /inference/reporting/accounts/:accountId/balance`
+ * (#972 workstream 8), which reads `account_balances` and stamps every response
+ * with `{source: 'financial_ledger', consistency: 'authoritative'}`. Restating
+ * those amounts here would be a second answer to one question, and the failure
+ * mode of two balance endpoints is the pair disagreeing on the day one of them
+ * stops accounting for the credit line.
+ *
+ * What this shape adds, and what nothing else carries: `billingAccountId` and
+ * `inherited`. A project draws on the nearest ancestor that has a profile
+ * (ADR 0014), so a Console page has to be able to say "this project spends the
+ * organization's balance" — showing somebody else's money under a project's name
+ * with no indication whose it is would be worse than showing nothing.
+ */
+exports.accountBillingStateSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    billingAccountId: identifiers_1.oxyAccountIdSchema,
+    inherited: zod_1.z.boolean(),
+    profile: exports.billingProfileSchema,
+})
+    .strict();
+/*
+ * SPENDING LIMITS AND THEIR ALERTS ARE NOT DECLARED HERE.
+ *
+ * `/inference/reporting` owns the budget surface (#972 workstream 8) and
+ * declares its own shapes beside the router that serves them, stamped
+ * `{source, consistency}` so a reader can always tell which kind of number they
+ * are looking at. A second set here would be a second answer to what a budget
+ * is, on a table both would write — and the closed alert-threshold set already
+ * lives once more where it is ENFORCED, as a CHECK on
+ * `spending_limits.alert_threshold_bps`.
+ */
+/* -------------------------------------------------------------------------- */
+/*  Invoices                                                                  */
+/* -------------------------------------------------------------------------- */
+exports.BILLING_INVOICE_STATUSES = ['draft', 'open', 'paid', 'void'];
+exports.billingInvoiceStatusSchema = zod_1.z.enum(exports.BILLING_INVOICE_STATUSES);
+/**
+ * A period's charges, aggregated — the invoiced-enterprise settlement document.
+ *
+ * `subtotalAmount` is the EXACT sum of the receipts on the invoice, at full
+ * scale; `totalAmount` is the rounded figure actually charged. The difference is
+ * booked as an `invoice_rounding` ledger entry rather than discarded, because a
+ * discarded remainder is money that exists in one system and not the other.
+ *
+ * `minorUnitExponent` is carried rather than derived from the currency code:
+ * USD is 2, JPY is 0, BHD is 3, and that is not a property this platform's
+ * database knows. Storing what was used keeps the invoice reproducible.
+ */
+exports.billingInvoiceSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    id: zod_1.z.string().min(1).max(64),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    currency: money_1.currencyCodeSchema,
+    periodStart: zod_1.z.string().datetime(),
+    periodEnd: zod_1.z.string().datetime(),
+    status: exports.billingInvoiceStatusSchema,
+    subtotalAmount: money_1.exactDecimalSchema,
+    totalAmount: money_1.exactDecimalSchema,
+    minorUnitExponent: zod_1.z.number().int().min(0).max(4),
+    /** The processor's own invoice id, for reconciliation. Never an authority. */
+    externalInvoiceRef: zod_1.z.string().min(1).max(255).optional(),
+    issuedAt: zod_1.z.string().datetime().optional(),
+    paidAt: zod_1.z.string().datetime().optional(),
+    receiptCount: zod_1.z.number().int().nonnegative().safe(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Payment processor boundary                                                */
+/* -------------------------------------------------------------------------- */
+/** The processors this platform records payments from. */
+exports.EXTERNAL_PAYMENT_PROVIDERS = ['stripe'];
+exports.externalPaymentProviderSchema = zod_1.z.enum(exports.EXTERNAL_PAYMENT_PROVIDERS);
+/**
+ * What kind of processor record `externalRef` names.
+ *
+ * Kept explicit because reconciliation compares like with like: a payment intent
+ * and the invoice it paid are two records of one movement of money, and counting
+ * both would double the external total.
+ */
+exports.EXTERNAL_PAYMENT_KINDS = ['payment_intent', 'invoice'];
+exports.externalPaymentKindSchema = zod_1.z.enum(exports.EXTERNAL_PAYMENT_KINDS);
+/**
+ * A processor payment that funded an Oxy balance.
+ *
+ * This is the reconciliation ANCHOR: one row per charge that landed in the
+ * ledger, carrying both the processor's reference and the ledger entry it
+ * produced. Without it, matching a Stripe charge back to a ledger entry means
+ * parsing an idempotency key, and a parser is not a foreign key.
+ */
+exports.externalPaymentSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().min(1).max(64),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    provider: exports.externalPaymentProviderSchema,
+    externalKind: exports.externalPaymentKindSchema,
+    externalRef: zod_1.z.string().min(1).max(255),
+    amount: money_1.exactDecimalSchema,
+    currency: money_1.currencyCodeSchema,
+    ledgerEntryId: zod_1.z.string().min(1).max(64),
+    occurredAt: zod_1.z.string().datetime(),
+    createdAt: zod_1.z.string().datetime(),
+})
+    .strict();
+/** Lifecycle of one automatic top-up. */
+exports.AUTO_RECHARGE_STATUSES = ['pending', 'succeeded', 'failed'];
+exports.autoRechargeStatusSchema = zod_1.z.enum(exports.AUTO_RECHARGE_STATUSES);
+/**
+ * One attempt to top an account up automatically.
+ *
+ * Recorded BEFORE the processor is called and keyed on the account, currency and
+ * the window it fired in, so a sweep that runs twice — or two instances of it —
+ * charges a customer's card once. An off-session charge is the one operation on
+ * this surface where a duplicate is not merely a wrong number in a report.
+ */
+exports.autoRechargeAttemptSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    id: zod_1.z.string().min(1).max(64),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    currency: money_1.currencyCodeSchema,
+    requestedAmount: money_1.exactDecimalSchema,
+    /** The spendable balance that triggered it — why this attempt exists. */
+    balanceAtTrigger: money_1.exactDecimalSchema,
+    status: exports.autoRechargeStatusSchema,
+    externalRef: zod_1.z.string().min(1).max(255).optional(),
+    /** The processor's own decline code. Never a free-form message. */
+    failureCode: zod_1.z.string().min(1).max(64).optional(),
+    createdAt: zod_1.z.string().datetime(),
+    updatedAt: zod_1.z.string().datetime(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Reconciliation                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * How an Oxy record and a processor record fail to agree.
+ *
+ * A closed set, and every member is a DIFFERENT operational problem:
+ *
+ *  - `missing_in_ledger` — the processor took money Oxy never credited. The
+ *    customer paid and has no balance. This is the one that costs a customer.
+ *  - `missing_in_external` — Oxy credited a balance with no processor charge
+ *    behind it. This is the one that costs Oxy.
+ *  - `amount_mismatch` — both exist and disagree.
+ *  - `account_unresolved` — a processor charge whose customer maps to no Oxy
+ *    account. Money arrived and nobody owns it.
+ *
+ * Collapsing them into a single "discrepancy" count is what makes a
+ * reconciliation report a number nobody acts on.
+ */
+exports.RECONCILIATION_DISCREPANCY_KINDS = [
+    'missing_in_ledger',
+    'missing_in_external',
+    'amount_mismatch',
+    'account_unresolved',
+];
+exports.reconciliationDiscrepancyKindSchema = zod_1.z.enum(exports.RECONCILIATION_DISCREPANCY_KINDS);
+exports.RECONCILIATION_RUN_STATUSES = ['running', 'completed', 'failed'];
+exports.reconciliationRunStatusSchema = zod_1.z.enum(exports.RECONCILIATION_RUN_STATUSES);
+exports.reconciliationDiscrepancySchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    id: zod_1.z.string().min(1).max(64),
+    runId: zod_1.z.string().min(1).max(64),
+    kind: exports.reconciliationDiscrepancyKindSchema,
+    accountId: identifiers_1.oxyAccountIdSchema.optional(),
+    externalRef: zod_1.z.string().min(1).max(255).optional(),
+    ledgerEntryId: zod_1.z.string().min(1).max(64).optional(),
+    /** What Oxy recorded. Absent for `missing_in_ledger`. */
+    ledgerAmount: money_1.exactDecimalSchema.optional(),
+    /** What the processor recorded. Absent for `missing_in_external`. */
+    externalAmount: money_1.exactDecimalSchema.optional(),
+    currency: money_1.currencyCodeSchema,
+    createdAt: zod_1.z.string().datetime(),
+})
+    .strict();
+/**
+ * One reconciliation pass over a window.
+ *
+ * The totals are carried beside the discrepancy list on purpose: two totals that
+ * agree while the lists differ is a real and common state (a charge recorded
+ * against the wrong account), and a report that only published a difference
+ * would call it clean.
+ */
+exports.reconciliationRunSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    id: zod_1.z.string().min(1).max(64),
+    provider: exports.externalPaymentProviderSchema,
+    /** Absent for a platform-wide pass. */
+    accountId: identifiers_1.oxyAccountIdSchema.optional(),
+    currency: money_1.currencyCodeSchema,
+    periodStart: zod_1.z.string().datetime(),
+    periodEnd: zod_1.z.string().datetime(),
+    status: exports.reconciliationRunStatusSchema,
+    ledgerTotal: money_1.exactDecimalSchema,
+    externalTotal: money_1.exactDecimalSchema,
+    discrepancyCount: zod_1.z.number().int().nonnegative().safe(),
+    startedAt: zod_1.z.string().datetime(),
+    completedAt: zod_1.z.string().datetime().optional(),
+})
+    .strict();
+exports.reconciliationReportSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    run: exports.reconciliationRunSchema,
+    discrepancies: zod_1.z.array(exports.reconciliationDiscrepancySchema),
+})
+    .strict();

package/dist/cjs/inference/attribution.js

@@ -88,10 +88,15 @@ exports.authenticatedPrincipalSchema = zod_1.z.object({
  * access, and lives outside {@link billingPrincipalSchema} so that no code path
  * can read it as the payer.
  *
- * `requestId` is generated by the data plane and always present; `generationId`
- * is present
- * once a generation exists, which is why it is optional on a request and
- * expected on a receipt.
+ * `requestId` is generated by the OXY EDGE, on admission and before
+ * authentication completes, and is always present (ADR 0007). Not by the data
+ * plane: a data plane that minted the correlation key could not correlate a
+ * request it never received, and the requests rejected at the edge are exactly
+ * the ones an operator most needs to find.
+ *
+ * `generationId` is present once a generation exists, which is why it is
+ * optional on a request and expected on a receipt. That one IS the data plane's,
+ * because only the data plane knows how many outputs a request produced.
  */
 exports.inferenceAttributionSchema = zod_1.z.object({
     principal: exports.authenticatedPrincipalSchema,

package/dist/cjs/inference/entitlement.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Product entitlements — the interface a first-party product (Alia) queries to
+ * learn what an account is entitled to, WITHOUT learning anything it could
+ * mistake for a balance.
+ *
+ * ## The separation this file is
+ *
+ * #972 states the failure mode outright: confusing a product subscription with
+ * pay-as-you-go inference usage. So the two live in disjoint shapes here, and
+ * the separation is structural rather than documented:
+ *
+ *  - {@link productEntitlementSchema} carries PLAN and ALLOWANCES. Allowances
+ *    are whole integer counts of a product entitlement (API credits, included
+ *    requests) — `z.number().int()`, never `exactDecimalSchema`, so an allowance
+ *    is not even the same TYPE as money and cannot be added to one.
+ *  - `accountBalanceSchema` (in `accountBilling.ts`) carries MONEY, as exact
+ *    decimal strings.
+ *
+ * There is no field anywhere that is both, and no schema that sums them. A
+ * consumer wanting "what can this account do right now" reads both sections and
+ * presents both; a consumer that only wanted one is not handed the other in a
+ * form it can accidentally arithmetic.
+ *
+ * ## Allowances do not change what a request COSTS
+ *
+ * An Alia plan may include an allowance of inference. Oxy still records the
+ * exact underlying cost of every request against the account's ledger — the
+ * allowance is a PRODUCT-side entitlement that decides what Alia charges its
+ * user, not a discount applied to the receipt. That is why
+ * {@link productEntitlementSchema} names no price and no currency: a plan that
+ * could restate the cost of a request would be a second pricing authority, and
+ * a receipt has exactly one.
+ *
+ * ## Cost centres
+ *
+ * A first-party cost centre IS an Oxy project account — `users.kind` already has
+ * `project`, and an application's `ownerAccountId` already points at one. So a
+ * cost centre adds a LABEL and a slug to an account rather than a parallel
+ * hierarchy, which is the epic's "do not add a second organization model" rule
+ * applied to internal accounting.
+ *
+ * Decided in: docs/adr/0014-account-billing-and-entitlements.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.productEntitlementSchema = exports.costCenterSpendSchema = exports.costCenterSchema = exports.costCenterStatusSchema = exports.COST_CENTER_STATUSES = exports.payAsYouGoEntitlementSchema = exports.productPlanSchema = exports.planAllowanceSchema = exports.LIVE_PRODUCT_PLAN_STATUSES = exports.productPlanStatusSchema = exports.PRODUCT_PLAN_STATUSES = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+const accountBilling_1 = require("./accountBilling");
+const money_1 = require("./money");
+/* -------------------------------------------------------------------------- */
+/*  Plans and allowances                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The statuses a subscription may be mirrored in.
+ *
+ * All of the processor's, not just the ones this platform sells: a mirror that
+ * cannot represent what it mirrors freezes at its previous value, and a
+ * subscription the processor moved to `paused` would keep granting a plan
+ * nobody is paying for.
+ */
+exports.PRODUCT_PLAN_STATUSES = [
+    'active',
+    'canceled',
+    'incomplete',
+    'incomplete_expired',
+    'past_due',
+    'paused',
+    'trialing',
+    'unpaid',
+];
+exports.productPlanStatusSchema = zod_1.z.enum(exports.PRODUCT_PLAN_STATUSES);
+/**
+ * The statuses that mean the plan is LIVE.
+ *
+ * Exported because "is this entitlement in force" must have one answer across
+ * Oxy and every product consuming it — a consumer deriving its own list is how
+ * `past_due` comes to be honoured in one place and refused in another.
+ */
+exports.LIVE_PRODUCT_PLAN_STATUSES = ['active', 'trialing'];
+/**
+ * One allowance included in a plan.
+ *
+ * `remaining` is optional and absent means "not metered against this allowance
+ * here" — NOT zero. A consumer that read an absent allowance as exhausted would
+ * refuse a user who has spent nothing.
+ */
+exports.planAllowanceSchema = zod_1.z
+    .object({
+    /** A stable machine name, e.g. `api_credits_per_month`. */
+    key: zod_1.z.string().regex(/^[a-z][a-z0-9_]{0,62}$/),
+    /** Whole units included per period. Never money. */
+    included: zod_1.z.number().int().nonnegative().safe(),
+    remaining: zod_1.z.number().int().nonnegative().safe().optional(),
+})
+    .strict();
+/**
+ * The plan an account is on, if any.
+ *
+ * `price` is deliberately absent. What a customer pays for their plan is the
+ * processor's record and this platform's `billing_transactions`; restating it
+ * here would put a second price authority in the one interface whose whole job
+ * is to keep product pricing and inference cost apart.
+ */
+exports.productPlanSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().min(1).max(64),
+    name: zod_1.z.string().min(1).max(120),
+    status: exports.productPlanStatusSchema,
+    live: zod_1.z.boolean(),
+    currentPeriodStart: zod_1.z.string().datetime(),
+    currentPeriodEnd: zod_1.z.string().datetime(),
+    cancelAtPeriodEnd: zod_1.z.boolean(),
+    allowances: zod_1.z.array(exports.planAllowanceSchema),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Pay-as-you-go position                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The account's inference-spend position, summarised for a product consumer.
+ *
+ * A REDUCTION of `accountBillingStateSchema`, not a copy: a product asking "may
+ * this account run another request" needs to know whether spending is possible
+ * and roughly how much room is left, and does not need the bucket breakdown.
+ * `promotionalBalance` and `purchasedBalance` are still separate — the rule that
+ * a grant and a purchase are never one number does not relax because the
+ * consumer is first-party.
+ */
+exports.payAsYouGoEntitlementSchema = zod_1.z
+    .object({
+    /** The account that actually pays — the nearest ancestor with a profile. */
+    billingAccountId: identifiers_1.oxyAccountIdSchema,
+    currency: money_1.currencyCodeSchema,
+    billingMode: accountBilling_1.billingModeSchema,
+    purchasedBalance: money_1.exactDecimalSchema,
+    promotionalBalance: money_1.exactDecimalSchema,
+    availableToSpend: money_1.exactDecimalSchema,
+    /** False when the profile is suspended, closed, or out of room. */
+    canSpend: zod_1.z.boolean(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Cost centres                                                              */
+/* -------------------------------------------------------------------------- */
+exports.COST_CENTER_STATUSES = ['active', 'retired'];
+exports.costCenterStatusSchema = zod_1.z.enum(exports.COST_CENTER_STATUSES);
+/**
+ * An internal cost centre — an Oxy account that first-party spend is attributed
+ * to, with a stable slug so a report can name it without an id.
+ *
+ * The account IS the cost centre; this shape only labels it. There is no
+ * `parentId` here for the same reason: the account graph already has one, and a
+ * second parent link would be a second hierarchy that can disagree with it.
+ */
+exports.costCenterSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    slug: zod_1.z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
+    label: zod_1.z.string().min(1).max(120),
+    status: exports.costCenterStatusSchema,
+    createdAt: zod_1.z.string().datetime(),
+    updatedAt: zod_1.z.string().datetime(),
+})
+    .strict();
+/**
+ * What one cost centre spent over a window.
+ *
+ * `billedAmount` comes from settled receipts — the FINANCIAL ledger — never from
+ * telemetry sums, per #972 workstream 8. `requestCount` is a count of receipts,
+ * so the two are always about the same set of rows.
+ */
+exports.costCenterSpendSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    costCenter: exports.costCenterSchema,
+    currency: money_1.currencyCodeSchema,
+    periodStart: zod_1.z.string().datetime(),
+    periodEnd: zod_1.z.string().datetime(),
+    billedAmount: money_1.exactDecimalSchema,
+    requestCount: zod_1.z.number().int().nonnegative().safe(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  The interface Alia queries                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Everything a product needs to decide what an account may do, in one read.
+ *
+ * The three sections never merge:
+ *
+ *  - `plan` + `allowances` — the product subscription.
+ *  - `payAsYouGo` — inference money. `null` when the account has no billing
+ *    profile anywhere up its ancestry, which is a REAL and distinct state from a
+ *    zero balance: nobody has decided who pays for this account yet.
+ *  - `costCenter` — where first-party spend is booked, `null` for a customer.
+ */
+exports.productEntitlementSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: zod_1.z.literal(1),
+    accountId: identifiers_1.oxyAccountIdSchema,
+    plan: exports.productPlanSchema.nullable(),
+    /**
+     * Allowances in force right now, whether they came from a plan or from the
+     * platform's own free tier. Whole counts; never money.
+     */
+    allowances: zod_1.z.array(exports.planAllowanceSchema),
+    payAsYouGo: exports.payAsYouGoEntitlementSchema.nullable(),
+    costCenter: exports.costCenterSchema.nullable(),
+    /** When this view was computed. Entitlements are eventually consistent. */
+    resolvedAt: zod_1.z.string().datetime(),
+})
+    .strict();