@greatwait/contracts 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/operations.js

@@ -1,13 +1,14 @@
+import { effectiveCustomerLimitsSchema } from "./effective-limits.js";
 import { z } from "./zod.js";
 import { DATA_EXPORT_OPERATIONS } from "./data-export.js";
 import { ORGANIZATION_LIFECYCLE_OPERATIONS } from "./organization-lifecycle.js";
 import { API_UNUSED_RESPONSE_SCHEMA } from "./operation-definitions.js";
 import { credentialContextSchema } from "./authority.js";
 import { callbackEndpointCreatedSchema, callbackEndpointPageSchema, callbackEndpointRequestSchema, callbackEndpointRotatedSchema, callbackEndpointSchema, callbackEndpointSigningSecretsSchema, callbackSigningKeyRotationRequestSchema, } from "./endpoints.js";
-import { FORECAST_WINDOW_VERSION, forecastRequestSchema, forecastSchema, forecastWindowsSchema, } from "./forecast.js";
+import { FORECAST_WINDOW_VERSION, forecastRequestSchema, forecastSchema, forecastRequestHeadersSchema, forecastWindowsSchema, } from "./forecast.js";
 import { usageRequestSchema, usageSchema } from "./usage.js";
 import { deliveryTimingSummarySchema } from "./timing.js";
-import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, projectBillingStateSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, projectBillingChangeRequestSchema, billingPortalSchema, } from "./billing.js";
+import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, projectBillingStateSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, projectBillingChangeRequestSchema, billingPortalSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, } from "./billing.js";
 import { conditionalRequestHeaderSchema, idempotencyReplayResponseHeaderSchema, idempotencyRequestHeaderSchema, historyPageRequestSchema, pageRequestSchema, scheduleListRequestSchema, replayedResponseHeaderSchema, requiredConditionalRequestHeaderSchema, requiredIdempotencyRequestHeaderSchema, versionResponseHeaderSchema, } from "./protocol.js";
 import { oauthGrantListSchema, oauthGrantRevokedSchema } from "./oauth.js";
 import { credentialCreatedSchema, credentialPageSchema, credentialRequestSchema, credentialRevokedSchema, credentialRotatedSchema, credentialRotationRequestSchema, } from "./secrets.js";
@@ -299,7 +300,7 @@ const BILLING_NOTIFICATION_SETTINGS_OPERATION = {
     creates: false,
     description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
         ? ""
-        : "Reads the USD 2.00 default low-credit threshold and optional-email choice. Critical email remains mandatory for owners and active billing-role members; addresses and contact management are absent.",
+        : "Reads the low-credit threshold in effect and the optional-email choice. Unless a threshold was chosen, it is one fifth of the organization's most recent credit purchase or grant, rounded down to a whole cent, and zero before any credit was granted. Critical email remains mandatory for owners and active billing-role members; addresses and contact management are absent.",
     example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
         ? {}
         : BILLING_NOTIFICATION_SETTINGS_EXAMPLE,
@@ -325,7 +326,7 @@ const BILLING_NOTIFICATION_SETTINGS_UPDATE_OPERATION = {
     creates: false,
     description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
         ? ""
-        : "Replaces the low-credit threshold and noncritical email choice at an expected revision. Critical email stays mandatory; idempotent retries converge and agents require explicit approval.",
+        : "Replaces the low-credit threshold and noncritical email choice at an expected revision. A null threshold returns to the default of one fifth of the most recent credit purchase or grant; an omitted threshold is left exactly as it is. Critical email stays mandatory; idempotent retries converge and agents require explicit approval.",
     environments: ["live"],
     example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
         ? {}
@@ -469,6 +470,60 @@ const BILLING_AUTO_TOP_UP_APPLY_OPERATION = withBillingFundingContract({
     surfaces: ["api", "mock"],
 });
 export const OPERATIONS = [
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Read the verified organization's execution-credit payments with bounded cursor continuation. Existing recent-history responses remain compatible.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { data: [], freshness: { kind: "authoritative" } },
+        id: "billing.paymenthistory",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/billing/payment-history",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "service_unavailable"],
+        query: pageRequestSchema,
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPaymentHistoryPageSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Page execution-credit payments",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Read the verified organization's project subscription invoices with bounded cursor continuation. Existing recent-history responses remain compatible.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { data: [], freshness: { kind: "authoritative" } },
+        id: "billing.invoicehistory",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/billing/invoice-history",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "service_unavailable"],
+        query: pageRequestSchema,
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingInvoiceHistoryPageSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Page project subscription invoices",
+        surfaces: ["api", "mock"],
+    },
     ...DATA_EXPORT_OPERATIONS,
     ...ORGANIZATION_LIFECYCLE_OPERATIONS,
     {
@@ -604,7 +659,7 @@ export const OPERATIONS = [
         creates: true,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Creates a reusable callback endpoint in the caller's project and environment. The destination must be HTTPS on effective port 443, contain no URL credentials or fragment, and resolve only to public unicast addresses. The endpoint is active and usable the moment it exists; there is nothing to verify. A disabled endpoint is never delivered to, and a schedule write naming one answers not_found, because disabling is terminal rather than a state to recover from. The per-endpoint secret is returned in this response and nowhere else. The 50-record safety ceiling includes disabled endpoints because they remain readable for audit.",
+            : "Creates a reusable callback endpoint in the caller's project and environment. The destination must be HTTPS on effective port 443, contain no URL credentials or fragment, and resolve only to public unicast addresses. The endpoint is active and usable the moment it exists; there is nothing to verify. A disabled endpoint is never delivered to, and a schedule write naming one answers not_found, because disabling is terminal rather than a state to recover from. The per-endpoint secret is returned to this call and to no other call an API credential or an OAuth token can make; a signed-in member can read it again through endpoints.revealSigningSecret. There is no endpoint-count ceiling. Disabled endpoints remain readable for audit; request and DNS inspection admission bound creation work and reads are paged.",
         example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
             ? {}
             : {
@@ -792,7 +847,7 @@ export const OPERATIONS = [
         creates: true,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once and has no recovery operation, so a call whose answer was never read may have rotated a key nobody holds: read the endpoint and compare its signing keys before repeating one. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.",
+            : "Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once to this call, so a call whose answer was never read has rotated a key the caller does not hold. It is recoverable: a signed-in member can read both keys, and the instant the overlap ends, through endpoints.revealSigningSecret. An API credential or an OAuth token cannot, so an integration that loses the answer needs a member to read it back rather than a second rotation, which is refused until the overlap ends. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.",
         example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
             ? {}
             : {
@@ -2083,10 +2138,11 @@ export const OPERATIONS = [
             "not_found",
             // The organization ceiling, the same code and the same shape
             // `projects.create` and `endpoints.create` use. A plan may bound the
-            // live schedules an organization holds, the distinct partition keys it
-            // has live, and how large a `data` body it may carry; all three refuse
-            // here rather than truncating, because a schedule created without the
-            // body the caller sent is not the schedule they asked for.
+            // distinct partition keys an organization has live and how large a
+            // `data` body it may carry; both refuse here rather than truncating,
+            // because a schedule created without the body the caller sent is not
+            // the schedule they asked for. How many schedules an organization holds
+            // is not bounded (FXO-2556).
             "plan_limit_reached",
             "service_unavailable",
             // A schedule against a disabled endpoint. Refused rather than accepted
@@ -2230,7 +2286,7 @@ export const OPERATIONS = [
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Counts the occurrences this project and environment expect to fire, in epoch-aligned time buckets, with a latency-class split on every bucket and an optional customer partition-key breakdown. A recurring series contributes every instant it fires inside the window rather than only its next one, and `nextFireCount` reports how many of a bucket's occurrences are a schedule's next firing. The answer states its own freshness and is refused rather than shortened when a partition cannot complete it. It carries counts only: no schedule identifier, callback destination, payload or endpoint detail has a field in the response.",
+            : "Counts the occurrences this project and environment expect to fire, in epoch-aligned time buckets, with a latency-class split on every bucket and an optional customer partition-key breakdown. A recurring series contributes every instant it fires inside the window rather than only its next one, and `nextFireCount` reports how many of a bucket's occurrences are a schedule's next firing. The answer states freshness and explicit coverage. Clients sending X-Greatwait-Accept-Partial-Forecast: true receive bounded lower-bound counts when a book reaches a row, cell or recurrence-work bound, with coverage.complete false and the exact bounds reached. Without this capability header the previous refusal behavior remains safe for clients that only read totals. Unavailable or stale sources still refuse. Coverage identifies the selected recurring schedule range but never includes destinations, payload or endpoint detail.",
         example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
             ? {}
             : {
@@ -2255,6 +2311,7 @@ export const OPERATIONS = [
                     to: "2026-07-29T15:00:00.000Z",
                 },
             },
+        requestHeaders: forecastRequestHeadersSchema,
         id: "forecast.read",
         idempotent: true,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -2278,7 +2335,7 @@ export const OPERATIONS = [
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Reads the verified principal's organization-wide prepaid execution position from the authoritative PostgreSQL ledger. Desired and effective revisions remain distinct, and pending stays true until D1 records PostgreSQL confirmation. Amounts are exact integer microdollars encoded as decimal strings; currency is USD and scale is six. Reserved credit has already been committed to a logical attempt but is not yet a settled debit. A missing hard cap means the customer elected no execution spending cap, never zero room. Shadow mode records what enforcement would have done without charging or blocking, and the activation boundary prevents retroactive charges.",
+            : "Reads the verified principal's organization-wide prepaid execution position from the authoritative PostgreSQL ledger. Desired and effective revisions remain distinct, and pending stays true until the control plane records PostgreSQL confirmation. Amounts are exact integer microdollars encoded as decimal strings; currency is USD and scale is six. Reserved credit has already been committed to a logical attempt but is not yet a settled debit. A missing hard cap means the customer elected no execution spending cap, never zero room. Shadow mode records what enforcement would have done without charging or blocking, and the activation boundary prevents retroactive charges.",
         example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
             ? {}
             : BILLING_SUMMARY_EXAMPLE,
@@ -2289,7 +2346,7 @@ export const OPERATIONS = [
         mutates: false,
         path: "/v1/billing/summary",
         principals: ["api-credential", "oauth", "session"],
-        problems: [],
+        problems: ["billing_not_ready", "service_unavailable"],
         response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
             ? API_UNUSED_RESPONSE_SCHEMA
             : billingSummarySchema,
@@ -2405,6 +2462,32 @@ export const OPERATIONS = [
             : "Confirm manual execution funding",
         surfaces: ["api", "mock"],
     }),
+    withBillingFundingContract({
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Confirms one execution-credit payment or saved-payment-method setup now, typically when the customer returns from hosted Checkout, instead of waiting for the provider's notification or the scheduled repair. It reads that one operation from the payment provider under the caller organization's authenticated account and applies what the provider reports: a paid Checkout grants its exact credit once, an open or unpaid one stays pending, and an operation already settled is answered without reading the provider. Nothing in the request can claim a payment succeeded — it names only which operation to read. Repeating the call is safe and converges on the same state. Returns the same execution-funding position as billing.funding.",
+        environments: ["live"],
+        id: "billing.fundingconfirm",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/billing/funding/{paymentOperation}/confirm",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "not_found",
+            "service_unavailable",
+            "state_conflict",
+            "test_to_live_escalation",
+        ],
+        scopes: ["billing:write"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Confirm one payment with the provider now",
+        surfaces: ["api", "mock"],
+    }),
     withBillingFundingContract({
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
@@ -2455,7 +2538,7 @@ export const OPERATIONS = [
         creates: true,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Records an explicitly approved billing-owner request for operator review of unused purchased execution credit. It never submits a refund, cashes out credit or grants an MCP cash-out path; the Idempotency-Key preserves one request across retries. Trial credit has no cash value, provider submission remains an operator action, and any later refund does not restore automatic purchasing authority for the month.",
+            : "Reserves unused purchased execution credit against one original payment, with the billing owner's explicit confirmation. Purchased credit is not refundable except where a charge is refunded because the service did not work as described, so this records no promise of a refund: it never calls Stripe, cashes out credit or grants an MCP cash-out path. A Stripe refund of that payment settles the reservation when it carries the same credit and supersedes it otherwise; the Idempotency-Key preserves one reservation across retries. Trial credit has no cash value, and a refund does not restore automatic purchasing authority used in the month.",
         environments: ["live"],
         example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
             ? {}
@@ -2472,7 +2555,14 @@ export const OPERATIONS = [
         method: "POST",
         mutates: true,
         path: "/v1/billing/funding/refunds",
-        principals: ["api-credential", "oauth", "session"],
+        // **No browser session** (W9-09). The dashboard's refund request and
+        // refund review forms were an operator's procedure rendered on a customer's
+        // home screen, and they are gone; refunds are a conversation with support.
+        // The operation is unchanged for an API credential and OAuth — the CLI's
+        // `billing refund-request` — and a session write nothing calls is an
+        // authorization path nobody exercises, which `workspace-mutations.test.ts`
+        // exists to refuse.
+        principals: ["api-credential", "oauth"],
         problems: [
             "idempotency_key_reused",
             "invalid_request",
@@ -2499,17 +2589,16 @@ export const OPERATIONS = [
             ? {}
             : { responseHeaders: idempotencyReplayResponseHeaderSchema }),
         scopes: ["billing:write"],
-        sessionAuthority: "headers",
         summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
             ? ""
-            : "Request operator-reviewed refund",
+            : "Reserve credit against a payment for refund",
         surfaces: ["api", "mock"],
     },
     withBillingFundingContract({
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
             ? ""
-            : "Records an already-made external operator decision on a pending unused-credit refund request. Completion verifies an existing Stripe refund by authenticated provider read before applying the exact credit, tax and gross adjustment; it never creates a provider refund. Decline releases the reserved credit without contacting the provider. The Idempotency-Key makes either decision converge across retries.",
+            : "Completes or declines a pending refund reservation. Completion verifies an existing Stripe refund by authenticated provider read before applying the exact credit, tax and gross adjustment, and converges on the recorded adjustment when that refund already settled the reservation; it never creates a provider refund. Decline releases the reserved credit without contacting the provider, and a reservation a Stripe refund superseded is refused as a state conflict. The Idempotency-Key makes either outcome converge across retries.",
         environments: ["live"],
         id: "billing.refundresolution",
         idempotent: true,
@@ -2517,7 +2606,14 @@ export const OPERATIONS = [
         method: "PATCH",
         mutates: true,
         path: "/v1/billing/funding/refunds/{refundRequest}",
-        principals: ["api-credential", "oauth", "session"],
+        // **No browser session** (W9-09). The dashboard's refund request and
+        // refund review forms were an operator's procedure rendered on a customer's
+        // home screen, and they are gone; refunds are a conversation with support.
+        // The operation is unchanged for an API credential and OAuth — the CLI's
+        // `billing refund-request` — and a session write nothing calls is an
+        // authorization path nobody exercises, which `workspace-mutations.test.ts`
+        // exists to refuse.
+        principals: ["api-credential", "oauth"],
         problems: [
             "idempotency_key_reused",
             "invalid_request",
@@ -2539,10 +2635,9 @@ export const OPERATIONS = [
             ? {}
             : { responseHeaders: idempotencyReplayResponseHeaderSchema }),
         scopes: ["billing:write"],
-        sessionAuthority: "headers",
         summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
             ? ""
-            : "Record a reviewed refund decision",
+            : "Complete or decline a refund reservation",
         surfaces: ["api", "mock"],
     }),
     {
@@ -2695,6 +2790,209 @@ export const OPERATIONS = [
             "test_to_live_escalation",
         ],
     },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Reads the verified organization's saved payment method: the one method automatic execution top-ups and project subscriptions charge. It is the payment provider's default payment method for the organization, read by authenticated provider call. method says what it is — type card with brand, last four digits and expiry; type link with the email Link reports, when it reports one; or type other with the provider's type name (cashapp, amazon_pay, klarna and the like) — and every variant carries label, the name to show a person. card repeats the card details when the method is a card and is null otherwise; it is kept for clients written before other payment methods were accepted. A method the organization already authorized for automatic top-up or a project subscription is adopted as the saved method, so an existing customer is not told they have none. method and card are null when the organization has none.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                card: { brand: "visa", expMonth: 12, expYear: 2030, last4: "4242" },
+                method: {
+                    brand: "visa",
+                    expMonth: 12,
+                    expYear: 2030,
+                    label: "Visa ending in 4242",
+                    last4: "4242",
+                    type: "card",
+                },
+            },
+        id: "billing.paymentmethod",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/billing/payment-method",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["service_unavailable"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPaymentMethodSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Read the saved payment method",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Lists the verified organization's project subscription charges: the payment provider's invoices for its project subscription, read by authenticated provider call, most recent first and at most 24. Execution-credit purchases are not listed here; billing.funding reports them. Draft and zero-amount invoices are omitted. Each amount is the invoice total including tax, and the receipt link, when present, is the provider-hosted invoice page. An organization that has never been billed has an empty list; reading it creates nothing and changes nothing.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                data: [
+                    {
+                        amount: {
+                            currency: "USD",
+                            microdollars: "5000000",
+                            scale: 6,
+                        },
+                        createdAt: "2026-09-01T12:00:00.000Z",
+                        id: "in_example_project_charge",
+                        receiptUrl: "https://invoice.stripe.com/i/acct_example/example",
+                        state: "paid",
+                    },
+                ],
+            },
+        id: "billing.invoices",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/billing/invoices",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["service_unavailable"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingInvoiceListSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "List project subscription charges",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Creates a short-lived provider-hosted payment-method setup session for the verified organization and returns its address. It offers every payment method the provider account enables that can be charged later without the customer present — cards, Link and others. Saving one there charges nothing; it becomes the saved payment method only once billing.paymentmethodconfirm (when the browser returns) or the provider's notification reads the completed setup by authenticated provider call. An optional return address must share the origin of the configured billing page.",
+        environments: ["live"],
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { url: "https://checkout.stripe.com/c/pay/example-card-setup" },
+        id: "billing.paymentmethodsetup",
+        idempotent: false,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/billing/payment-method/setup",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "service_unavailable",
+            "state_conflict",
+            "not_found",
+            "revision_conflict",
+            "test_to_live_escalation",
+        ],
+        request: billingPaymentMethodSetupRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {},
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPortalSchema,
+        scopes: ["billing:write"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Start saving a payment method",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Makes the payment method saved in one completed hosted setup the organization's saved payment method, typically when the browser returns from it. The session is read by authenticated provider call and must belong to the verified organization's own customer; a session of another organization is answered not found. It becomes the provider default for invoices, the default of the organization's project subscription, and the automatic top-up payment method — readying a top-up rule that was waiting for one. The response has the shape billing.paymentmethod returns. When the previous method was removed (billing.paymentmethodremove) and the paid period it let run out has not ended, renewal resumes for the projects that removal stopped; a project the customer cancelled themselves stays cancelled. Nothing in the request can claim a setup succeeded, and repeating the call is safe.",
+        environments: ["live"],
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                card: { brand: "visa", expMonth: 12, expYear: 2030, last4: "4242" },
+                method: {
+                    brand: "visa",
+                    expMonth: 12,
+                    expYear: 2030,
+                    label: "Visa ending in 4242",
+                    last4: "4242",
+                    type: "card",
+                },
+            },
+        id: "billing.paymentmethodconfirm",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/billing/payment-method/confirm",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "service_unavailable",
+            "state_conflict",
+            "revision_conflict",
+            "test_to_live_escalation",
+        ],
+        request: billingPaymentMethodConfirmRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { checkoutSession: "cs_example_card_setup" },
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPaymentMethodSchema,
+        scopes: ["billing:write"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Confirm a saved payment method",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Removes the verified organization's saved payment method, and with it everything that charges it. Removing it stops renewal: every project subscription is set to end at the end of the period already paid for, so paid projects keep running until then and then stop, with nothing refunded and nothing more charged; billing.projects shows each one's cancellationAt. The included free project is unaffected. Automatic top-up turns off immediately and forgets its payment method. A pending or declined project addition is ended, so nothing later starts a checkout or a charge, and no project can be added until a payment method is saved again. The method stops being the provider default and is detached from the organization's customer. The request must carry confirmed: true. Repeating the call is safe: with nothing on file it answers a null method and card and still makes sure nothing is left that could charge one. Saving a payment method through billing.paymentmethodsetup before the period ends keeps those projects: renewal resumes on the new method, except for any project the customer cancelled themselves. After the period ends, a paid project must be added again.",
+        environments: ["live"],
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { card: null, method: null },
+        id: "billing.paymentmethodremove",
+        idempotent: true,
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/billing/payment-method/remove",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "service_unavailable",
+            "state_conflict",
+            "revision_conflict",
+            "test_to_live_escalation",
+        ],
+        request: billingPaymentMethodRemoveRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { confirmed: true },
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPaymentMethodSchema,
+        scopes: ["billing:write"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Remove the saved payment method",
+        surfaces: ["api", "mock"],
+    },
     {
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
@@ -2711,7 +3009,16 @@ export const OPERATIONS = [
         mutates: true,
         path: "/v1/billing/reconcile",
         principals: ["api-credential", "oauth", "session"],
-        problems: ["service_unavailable", "test_to_live_escalation"],
+        // `billing.reconcile` answers from the same summary read as
+        // `billing.summary`, so it reaches the same not-provisioned refusal. It is
+        // declared here because an integrator reading the published OpenAPI would
+        // otherwise be told a 503 on this operation can only ever be
+        // `service_unavailable`.
+        problems: [
+            "billing_not_ready",
+            "service_unavailable",
+            "test_to_live_escalation",
+        ],
         response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
             ? API_UNUSED_RESPONSE_SCHEMA
             : billingSummarySchema,
@@ -2838,6 +3145,44 @@ export const OPERATIONS = [
             : "List immutable billing entries",
         surfaces: ["api", "mock"],
     },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Read effective customer allowances for the verified organization. Deployment and organization revisions identify the policy used; infrastructure and other organizations' settings are excluded.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                limits: {
+                    inlinePayloadBytes: 65536,
+                    forecastHorizonSeconds: 90000,
+                    usageWindowDays: 366,
+                },
+                provenance: {
+                    inlinePayloadBytes: "default",
+                    forecastHorizonSeconds: "default",
+                    usageWindowDays: "default",
+                },
+                revision: { global: 0, organization: 0 },
+            },
+        id: "limits.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/limits",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["service_unavailable"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : effectiveCustomerLimitsSchema,
+        scopes: ["schedules:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Read effective customer limits",
+        surfaces: ["api", "mock"],
+    },
     {
         creates: false,
         description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
@@ -2972,7 +3317,7 @@ export const OPERATIONS = [
         // scheduled for removal, which is the opposite of what a tool list is for.
         mcp: {
             kind: "unavailable",
-            reason: "A transitional shape for the autoscaler migration, scheduled for withdrawal once W6-02 has cut over. forecast.read is the same data in the shape this product publishes, and it is the tool an agent should reach for.",
+            reason: "A transitional shape for the autoscaler migration, withdrawn after its cutover. forecast.read is the same data in the shape this product publishes, and it is the tool an agent should reach for.",
         },
         method: "GET",
         mutates: false,
@@ -3127,6 +3472,8 @@ export const OPERATIONS = [
                     {
                         attemptNumber: 1,
                         classifiedAt: "2026-07-28T15:00:00.071Z",
+                        dispatchRecoveries: 0,
+                        localReceiptRecoveries: 0,
                         delivery: "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8",
                         diagnostic: "http_retryable",
                         durationMs: 71,
@@ -3176,6 +3523,8 @@ export const OPERATIONS = [
                 attempt: {
                     attemptNumber: 2,
                     classifiedAt: "2026-07-28T15:02:00.000Z",
+                    dispatchRecoveries: 2,
+                    localReceiptRecoveries: 1,
                     delivery: "dlv_11h8xyz9k2m4n6p8r0t2v4w6y8",
                     diagnostic: "network_ambiguous",
                     durationMs: 10_000,
@@ -3220,6 +3569,8 @@ export const OPERATIONS = [
             : {
                 attempt: {
                     attemptNumber: 3,
+                    dispatchRecoveries: 0,
+                    localReceiptRecoveries: 0,
                     delivery: "dlv_21h8xyz9k2m4n6p8r0t2v4w6y8",
                     id: "att_21h8xyz9k2m4n6p8r0t2v4w6y8",
                     occurrence: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
@@ -3652,6 +4003,16 @@ export function successStatusFor(operation) {
  * so an operation's own `problems` list stays about that operation.
  */
 export const UNIVERSAL_PROBLEMS = [
+    // **Universal rather than per-operation, because its earliest raise sites
+    // are before any operation exists.** Request admission runs as pre-route
+    // middleware on every `/v1/*`, `/oauth/*` and `/mcp` path, and the Worker
+    // refuses an unconfigured PostgreSQL authority before it builds an app at
+    // all. Declaring it operation by operation would leave the published
+    // contract, the mock and the SDK telling an integrator that a 503 on those
+    // paths can only be `service_unavailable` — which is the mistake a review
+    // round caught when `billing_not_ready` was declared on one of its two
+    // operations and not the other.
+    "capability_not_configured",
     "rate_limited",
     "service_unavailable",
 ];