@aexhq/sdk 0.46.4-canary → 0.50.0

package/dist/_contracts/schemas/response-billing.d.ts

@@ -1,208 +0,0 @@
-/**
- * Response schemas for the `billing.*` and `adminBilling.*` families.
- *
- * Both `BillingSummary` and `BillingLedgerEntry` USED to carry
- * `[key: string]: unknown` — an explicit "additive server fields pass through"
- * promise. That promise is what made two real gaps invisible (`BillingSummary`
- * omitting `accountType`, `BillingLedgerEntry` omitting `workspaceId`), and it
- * is exactly what a strict response schema exists to stop being invisible. Both
- * signatures are now gone from the types as well, and both interfaces declare
- * every field the server sends.
- *
- * One gap remains, resolved in favour of the server (a schema that fails every
- * real response is not a gate): `workspaceId` on a ledger entry and on the three
- * admin routes is a RAW id, not the public `wsp_<hex>` form `whoami` and the
- * MCP-server records carry, so it is validated as a plain string.
- *
- * `createdAt` on a ledger entry is NOT ISO-8601: it is selected raw, so it
- * arrives as the Data API's `"YYYY-MM-DD HH:MM:SS"` text. It is validated as a
- * non-empty string, deliberately, and the inconsistency is reported rather than
- * encoded as if intended. `resetAt` and `blocked.at` ARE ISO-8601 — they are
- * constructed, not selected. `pastDueAt`, the third timestamp that used to sit
- * here, went with the plan catalog.
- */
-import * as z from "zod/mini";
-/**
- * One free monthly allowance row inside `GET /billing`.
- *
- * `dimension`, `unit` and `label` are validated as non-empty strings rather than
- * as enums on purpose: the dimensions a free allowance is denominated in are
- * hosted billing policy, and pinning them here would put a second copy of that
- * policy in the public package — the exact duplication the prepaid model was
- * built to remove. The SHAPE is what this schema is for.
- *
- * `approximateTokens` rides only on the USD-denominated token allowance, and
- * only when there is usage to infer a model from.
- */
-export declare const BillingAllowanceSchema: z.ZodMiniObject<{
-    dimension: z.ZodMiniString<string>;
-    quota: z.ZodMiniNumber<number>;
-    used: z.ZodMiniNumber<number>;
-    remaining: z.ZodMiniNumber<number>;
-    unit: z.ZodMiniString<string>;
-    label: z.ZodMiniString<string>;
-    resetAt: z.ZodMiniString<string>;
-    approximateTokens: z.ZodMiniOptional<z.ZodMiniObject<{
-        model: z.ZodMiniString<string>;
-        tokens: z.ZodMiniNumber<number>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-/** Auto-recharge settings plus the two guards a top-up form has to respect. */
-export declare const BillingAutoTopupSchema: z.ZodMiniObject<{
-    enabled: z.ZodMiniBoolean<boolean>;
-    thresholdUsd: z.ZodMiniNumber<number>;
-    amountUsd: z.ZodMiniNumber<number>;
-    minimumAmountUsd: z.ZodMiniNumber<number>;
-    maxPerDay: z.ZodMiniNumber<number>;
-}, z.core.$strict>;
-/**
- * `GET /billing`.
- *
- * `planKey`, `subscriptionStatus` and `pastDueAt` are GONE with the catalog they
- * described; a strict schema still expecting them fails C4 against the current
- * server. What replaces them is the prepaid surface: the period, the
- * card-derived `admissionState`, the allowance rows, the auto-recharge block,
- * the saved card, and any live block.
- */
-export declare const BillingSummaryResponseSchema: z.ZodMiniObject<{
-    balanceUsd: z.ZodMiniNumber<number>;
-    monthSpendUsd: z.ZodMiniNumber<number>;
-    spendCapUsd: z.ZodMiniNumber<number>;
-    period: z.ZodMiniString<string>;
-    admissionState: z.ZodMiniEnum<{
-        free: "free";
-        carded_manual: "carded_manual";
-        carded_auto: "carded_auto";
-    }>;
-    accountType: z.ZodMiniEnum<{
-        standard: "standard";
-        internal: "internal";
-    }>;
-    paymentMethodStatus: z.ZodMiniEnum<{
-        none: "none";
-        active: "active";
-    }>;
-    autoTopupEnabled: z.ZodMiniBoolean<boolean>;
-    blocked: z.ZodMiniNullable<z.ZodMiniObject<{
-        at: z.ZodMiniString<string>;
-        reason: z.ZodMiniString<string>;
-    }, z.core.$strict>>;
-    paymentMethod: z.ZodMiniObject<{
-        present: z.ZodMiniBoolean<boolean>;
-        brand: z.ZodMiniNullable<z.ZodMiniString<string>>;
-        last4: z.ZodMiniNullable<z.ZodMiniString<string>>;
-    }, z.core.$strict>;
-    autoTopup: z.ZodMiniObject<{
-        enabled: z.ZodMiniBoolean<boolean>;
-        thresholdUsd: z.ZodMiniNumber<number>;
-        amountUsd: z.ZodMiniNumber<number>;
-        minimumAmountUsd: z.ZodMiniNumber<number>;
-        maxPerDay: z.ZodMiniNumber<number>;
-    }, z.core.$strict>;
-    allowances: z.ZodMiniArray<z.ZodMiniObject<{
-        dimension: z.ZodMiniString<string>;
-        quota: z.ZodMiniNumber<number>;
-        used: z.ZodMiniNumber<number>;
-        remaining: z.ZodMiniNumber<number>;
-        unit: z.ZodMiniString<string>;
-        label: z.ZodMiniString<string>;
-        resetAt: z.ZodMiniString<string>;
-        approximateTokens: z.ZodMiniOptional<z.ZodMiniObject<{
-            model: z.ZodMiniString<string>;
-            tokens: z.ZodMiniNumber<number>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-/** `PATCH /billing/autotopup` echoes exactly the stored settings. */
-export declare const BillingAutoTopupResponseSchema: z.ZodMiniObject<{
-    autoTopup: z.ZodMiniObject<{
-        enabled: z.ZodMiniBoolean<boolean>;
-        thresholdUsd: z.ZodMiniNumber<number>;
-        amountUsd: z.ZodMiniNumber<number>;
-        minimumAmountUsd: z.ZodMiniNumber<number>;
-        maxPerDay: z.ZodMiniNumber<number>;
-    }, z.core.$strict>;
-}, z.core.$strict>;
-/**
- * One row of `GET /billing/statements`.
- *
- * Only ISSUED periods are listed. A month whose statement did not reconcile is
- * withheld rather than rendered on demand, so an absent period is a statement
- * that was never issued — not one this read failed to find.
- *
- * `issuedAt` IS ISO-8601: the handler formats it, unlike the raw ledger
- * `createdAt` above.
- */
-export declare const BillingStatementSummarySchema: z.ZodMiniObject<{
-    period: z.ZodMiniString<string>;
-    issuedAt: z.ZodMiniString<string>;
-    openingBalanceUsd: z.ZodMiniNumber<number>;
-    creditsPurchasedUsd: z.ZodMiniNumber<number>;
-    usageUsd: z.ZodMiniNumber<number>;
-    adjustmentsUsd: z.ZodMiniNumber<number>;
-    closingBalanceUsd: z.ZodMiniNumber<number>;
-}, z.core.$strict>;
-export declare const BillingStatementListResponseSchema: z.ZodMiniObject<{
-    statements: z.ZodMiniArray<z.ZodMiniObject<{
-        period: z.ZodMiniString<string>;
-        issuedAt: z.ZodMiniString<string>;
-        openingBalanceUsd: z.ZodMiniNumber<number>;
-        creditsPurchasedUsd: z.ZodMiniNumber<number>;
-        usageUsd: z.ZodMiniNumber<number>;
-        adjustmentsUsd: z.ZodMiniNumber<number>;
-        closingBalanceUsd: z.ZodMiniNumber<number>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export declare const BillingLedgerEntrySchema: z.ZodMiniObject<{
-    id: z.ZodMiniString<string>;
-    entryType: z.ZodMiniString<string>;
-    amountUsd: z.ZodMiniNumber<number>;
-    currency: z.ZodMiniString<string>;
-    sessionId: z.ZodMiniNullable<z.ZodMiniString<string>>;
-    workspaceId: z.ZodMiniNullable<z.ZodMiniString<string>>;
-    description: z.ZodMiniNullable<z.ZodMiniString<string>>;
-    createdBy: z.ZodMiniString<string>;
-    createdAt: z.ZodMiniString<string>;
-}, z.core.$strict>;
-export declare const BillingLedgerResponseSchema: z.ZodMiniObject<{
-    entries: z.ZodMiniArray<z.ZodMiniObject<{
-        id: z.ZodMiniString<string>;
-        entryType: z.ZodMiniString<string>;
-        amountUsd: z.ZodMiniNumber<number>;
-        currency: z.ZodMiniString<string>;
-        sessionId: z.ZodMiniNullable<z.ZodMiniString<string>>;
-        workspaceId: z.ZodMiniNullable<z.ZodMiniString<string>>;
-        description: z.ZodMiniNullable<z.ZodMiniString<string>>;
-        createdBy: z.ZodMiniString<string>;
-        createdAt: z.ZodMiniString<string>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-/** `POST /billing/topup/checkout` and `POST /billing/portal` both answer exactly `{ url }`. */
-export declare const BillingHostedSessionResponseSchema: z.ZodMiniObject<{
-    url: z.ZodMiniString<string>;
-}, z.core.$strict>;
-export declare const AdminBillingTopupResponseSchema: z.ZodMiniObject<{
-    ok: z.ZodMiniLiteral<true>;
-    workspaceId: z.ZodMiniString<string>;
-    orgId: z.ZodMiniString<string>;
-    amountUsd: z.ZodMiniNumber<number>;
-    inserted: z.ZodMiniBoolean<boolean>;
-    balanceUsd: z.ZodMiniNumber<number>;
-}, z.core.$strict>;
-export declare const AdminBillingPaymentMethodResponseSchema: z.ZodMiniObject<{
-    ok: z.ZodMiniLiteral<true>;
-    workspaceId: z.ZodMiniString<string>;
-    paymentMethodStatus: z.ZodMiniEnum<{
-        none: "none";
-        active: "active";
-    }>;
-}, z.core.$strict>;
-export declare const AdminBillingAccountTypeResponseSchema: z.ZodMiniObject<{
-    ok: z.ZodMiniLiteral<true>;
-    workspaceId: z.ZodMiniString<string>;
-    accountType: z.ZodMiniEnum<{
-        standard: "standard";
-        internal: "internal";
-    }>;
-}, z.core.$strict>;
-export type BillingSummaryResponse = z.infer<typeof BillingSummaryResponseSchema>;

package/dist/_contracts/schemas/response-billing.js

@@ -1,139 +0,0 @@
-/**
- * Response schemas for the `billing.*` and `adminBilling.*` families.
- *
- * Both `BillingSummary` and `BillingLedgerEntry` USED to carry
- * `[key: string]: unknown` — an explicit "additive server fields pass through"
- * promise. That promise is what made two real gaps invisible (`BillingSummary`
- * omitting `accountType`, `BillingLedgerEntry` omitting `workspaceId`), and it
- * is exactly what a strict response schema exists to stop being invisible. Both
- * signatures are now gone from the types as well, and both interfaces declare
- * every field the server sends.
- *
- * One gap remains, resolved in favour of the server (a schema that fails every
- * real response is not a gate): `workspaceId` on a ledger entry and on the three
- * admin routes is a RAW id, not the public `wsp_<hex>` form `whoami` and the
- * MCP-server records carry, so it is validated as a plain string.
- *
- * `createdAt` on a ledger entry is NOT ISO-8601: it is selected raw, so it
- * arrives as the Data API's `"YYYY-MM-DD HH:MM:SS"` text. It is validated as a
- * non-empty string, deliberately, and the inconsistency is reported rather than
- * encoded as if intended. `resetAt` and `blocked.at` ARE ISO-8601 — they are
- * constructed, not selected. `pastDueAt`, the third timestamp that used to sit
- * here, went with the plan catalog.
- */
-import * as z from "zod/mini";
-import { BILLING_ADMISSION_STATES } from "../billing-admission.js";
-import { describeResponse, responseObject, wireBoolean, wireEnum, wireLiteral, wireNonEmptyString, wireNumber, wireString, wireTimestamp } from "./response-common.js";
-/**
- * One free monthly allowance row inside `GET /billing`.
- *
- * `dimension`, `unit` and `label` are validated as non-empty strings rather than
- * as enums on purpose: the dimensions a free allowance is denominated in are
- * hosted billing policy, and pinning them here would put a second copy of that
- * policy in the public package — the exact duplication the prepaid model was
- * built to remove. The SHAPE is what this schema is for.
- *
- * `approximateTokens` rides only on the USD-denominated token allowance, and
- * only when there is usage to infer a model from.
- */
-export const BillingAllowanceSchema = describeResponse("BillingAllowance", "One free monthly allowance: quota, consumption and the instant it resets.", responseObject({
-    dimension: wireNonEmptyString,
-    quota: wireNumber,
-    used: wireNumber,
-    remaining: wireNumber,
-    unit: wireNonEmptyString,
-    label: wireNonEmptyString,
-    resetAt: wireTimestamp,
-    approximateTokens: z.optional(responseObject({ model: wireNonEmptyString, tokens: wireNumber }))
-}));
-/** Auto-recharge settings plus the two guards a top-up form has to respect. */
-export const BillingAutoTopupSchema = describeResponse("BillingAutoTopup", "Auto-recharge settings, the minimum accepted top-up and the daily recharge cap.", responseObject({
-    enabled: wireBoolean,
-    thresholdUsd: wireNumber,
-    amountUsd: wireNumber,
-    minimumAmountUsd: wireNumber,
-    maxPerDay: wireNumber
-}));
-/**
- * `GET /billing`.
- *
- * `planKey`, `subscriptionStatus` and `pastDueAt` are GONE with the catalog they
- * described; a strict schema still expecting them fails C4 against the current
- * server. What replaces them is the prepaid surface: the period, the
- * card-derived `admissionState`, the allowance rows, the auto-recharge block,
- * the saved card, and any live block.
- */
-export const BillingSummaryResponseSchema = describeResponse("BillingSummaryResponse", "Workspace billing summary: prepaid balance, month-to-date spend, cap, free allowances and card state.", responseObject({
-    balanceUsd: wireNumber,
-    monthSpendUsd: wireNumber,
-    spendCapUsd: wireNumber,
-    period: wireNonEmptyString,
-    admissionState: wireEnum(BILLING_ADMISSION_STATES),
-    accountType: wireEnum(["standard", "internal"]),
-    paymentMethodStatus: wireEnum(["none", "active"]),
-    autoTopupEnabled: wireBoolean,
-    blocked: z.nullable(responseObject({ at: wireTimestamp, reason: wireNonEmptyString })),
-    paymentMethod: responseObject({
-        present: wireBoolean,
-        brand: z.nullable(wireString),
-        last4: z.nullable(wireString)
-    }),
-    autoTopup: BillingAutoTopupSchema,
-    allowances: z.array(BillingAllowanceSchema)
-}));
-/** `PATCH /billing/autotopup` echoes exactly the stored settings. */
-export const BillingAutoTopupResponseSchema = describeResponse("BillingAutoTopupResponse", "The stored auto-recharge settings after the update.", responseObject({ autoTopup: BillingAutoTopupSchema }));
-/**
- * One row of `GET /billing/statements`.
- *
- * Only ISSUED periods are listed. A month whose statement did not reconcile is
- * withheld rather than rendered on demand, so an absent period is a statement
- * that was never issued — not one this read failed to find.
- *
- * `issuedAt` IS ISO-8601: the handler formats it, unlike the raw ledger
- * `createdAt` above.
- */
-export const BillingStatementSummarySchema = describeResponse("BillingStatementSummary", "One issued monthly statement: the period, when it was issued, and the five " +
-    "figures that reconcile opening balance to closing.", responseObject({
-    period: wireNonEmptyString,
-    issuedAt: wireTimestamp,
-    openingBalanceUsd: wireNumber,
-    creditsPurchasedUsd: wireNumber,
-    usageUsd: wireNumber,
-    adjustmentsUsd: wireNumber,
-    closingBalanceUsd: wireNumber
-}));
-export const BillingStatementListResponseSchema = describeResponse("BillingStatementListResponse", "The months a customer can download, newest first. Bounded server-side; not cursor-paged.", responseObject({ statements: z.array(BillingStatementSummarySchema) }));
-export const BillingLedgerEntrySchema = describeResponse("BillingLedgerEntry", "One signed credit-ledger row. Top-ups are positive, run charges negative.", responseObject({
-    id: wireNonEmptyString,
-    entryType: wireNonEmptyString,
-    amountUsd: wireNumber,
-    currency: wireNonEmptyString,
-    sessionId: z.nullable(wireString),
-    workspaceId: z.nullable(wireString),
-    description: z.nullable(wireString),
-    createdBy: wireString,
-    createdAt: wireNonEmptyString
-}));
-export const BillingLedgerResponseSchema = describeResponse("BillingLedgerResponse", "Recent credit-ledger rows, newest first. Bounded by `limit`; not cursor-paged.", responseObject({ entries: z.array(BillingLedgerEntrySchema) }));
-/** `POST /billing/topup/checkout` and `POST /billing/portal` both answer exactly `{ url }`. */
-export const BillingHostedSessionResponseSchema = describeResponse("BillingHostedSessionResponse", "A hosted checkout or billing-portal session. The client should open `url`.", responseObject({ url: wireNonEmptyString }));
-export const AdminBillingTopupResponseSchema = describeResponse("AdminBillingTopupResponse", "Operator credit grant. `inserted` is false on an idempotent replay; " +
-    "`balanceUsd` is the authoritative post-state either way.", responseObject({
-    ok: wireLiteral(true),
-    workspaceId: wireNonEmptyString,
-    orgId: wireNonEmptyString,
-    amountUsd: wireNumber,
-    inserted: wireBoolean,
-    balanceUsd: wireNumber
-}));
-export const AdminBillingPaymentMethodResponseSchema = describeResponse("AdminBillingPaymentMethodResponse", "Operator payment-method override, echoing the applied status.", responseObject({
-    ok: wireLiteral(true),
-    workspaceId: wireNonEmptyString,
-    paymentMethodStatus: wireEnum(["none", "active"])
-}));
-export const AdminBillingAccountTypeResponseSchema = describeResponse("AdminBillingAccountTypeResponse", "Operator account-type override, echoing the applied type.", responseObject({
-    ok: wireLiteral(true),
-    workspaceId: wireNonEmptyString,
-    accountType: wireEnum(["standard", "internal"])
-}));

package/dist/_contracts/schemas/response-common.d.ts

@@ -1,132 +0,0 @@
-/**
- * Shared machinery for the RESPONSE half of the wire contract (C4 / P3).
- *
- * The request schemas answer "what may a caller send". These answer "what did
- * the server actually send", and they are checked against real bytes by
- * {@link import("../testing/wire-conformance.js").installWireConformance} rather
- * than by anything on the request path. That is the whole value: it is the one
- * gate in the contract pipeline that observes reality instead of comparing two
- * of our own artefacts to each other.
- *
- * Three rules the modules in this family follow:
- *
- * 1. **Strict.** Every response object is a {@link responseObject}, i.e. a
- *    `z.strictObject`. A field the server added and we never declared FAILS the
- *    suite. That generalises what `parseWhoAmI` did by hand for three removed
- *    fields (`caps`, `tokenId`, `tokenName`) to the whole surface. Several of
- *    our own declared types used to carry `[key: string]: unknown` — an explicit
- *    "additive server fields pass through" promise — and these schemas
- *    deliberately did not honour it. They no longer have to: an index signature
- *    makes EVERY undeclared field structurally legal, which is how
- *    `BillingSummary` came to omit two fields the server always sends without
- *    anything being able to notice. The signatures are gone from the types too.
- * 2. **No `.transform()`.** `z.toJSONSchema(s, { io: "output" })` throws on any
- *    transform, which would make the response half of the generated spec
- *    ungenerable. Schemas validate; `normalize*()` functions transform.
- * 3. **`zod/mini` only**, like every other module in this directory.
- */
-import * as z from "zod/mini";
-/**
- * Metadata registry for response schemas.
- *
- * Deliberately NOT `z.globalRegistry`. The OpenAPI generator converts
- * `OPENAPI_SCHEMA_REGISTRY`, and that constant *is* `z.globalRegistry` — so
- * registering a response schema there would silently add a component to
- * `openapi/data-plane.json`, break the committed-spec freshness gate (C3), and
- * do it as a side effect of merely importing this file. Response schemas are not
- * referenced by any generated operation yet (`scripts/openapi/generate.ts` still
- * emits `"2XX": { description: "Success." }`), so an entry there would be an
- * unreferenced component describing nothing.
- *
- * When the generator learns to declare responses, this registry is what it
- * converts — the ids below are already the component names.
- */
-export declare const responseSchemaRegistry: z.core.$ZodRegistry<{
-    readonly id: string;
-    readonly description: string;
-}, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
-/**
- * A strict response object.
- *
- * Paths are resolved against the ROOT of the parse rather than anchored on a
- * fixed name, so a nested object reports its real position
- * (`response.session.currentRun.phase`) instead of doubling a segment — the trap
- * the port measured and `08-refined-plan.md` records.
- */
-export declare function responseObject<Shape extends z.core.$ZodLooseShape>(shape: Shape): z.ZodMiniObject<Shape, z.core.$strict>;
-/**
- * Attach the component id and prose a spec consumer needs.
- *
- * `.meta()` does not exist on `zod/mini` schemas; `.register()` is the mini
- * equivalent and is what every metadata instruction in the plan documents means.
- */
-export declare function describeResponse<Schema extends z.core.$ZodType>(id: string, description: string, schema: Schema): Schema;
-export declare const wireString: z.ZodMiniString<string>;
-/**
- * A string the hand-written parsers already required to be non-empty (ids,
- * statuses, timestamps). Asserting less than the client already asserts would
- * make C4 weaker than the code it is meant to backstop.
- */
-export declare const wireNonEmptyString: z.ZodMiniString<string>;
-/** A finite number. `z.number()` already rejects `NaN` and `±Infinity` (measured). */
-export declare const wireNumber: z.ZodMiniNumber<number>;
-export declare const wireNonNegativeNumber: z.ZodMiniNumber<number>;
-export declare const wireInteger: z.ZodMiniNumberFormat;
-export declare const wireNonNegativeInteger: z.ZodMiniNumberFormat;
-export declare const wirePositiveInteger: z.ZodMiniNumberFormat;
-export declare const wireBoolean: z.ZodMiniBoolean<boolean>;
-/** An ISO-8601 timestamp, judged the way the parsers judge one: `Date.parse` succeeds. */
-export declare const wireTimestamp: z.ZodMiniString<string>;
-/** A closed vocabulary. The message names the accepted values, as the parsers do. */
-export declare function wireEnum<const Values extends readonly [string, ...string[]]>(values: Values): z.ZodMiniEnum<{ [k_1 in Values[number]]: k_1; } extends infer T ? { [k in keyof T]: { [k_1 in Values[number]]: k_1; }[k]; } : never>;
-/** A literal the server always sends verbatim (`ok: true`, `kind: "file"`). */
-export declare function wireLiteral<const Value extends string | number | boolean>(value: Value): z.ZodMiniLiteral<Value>;
-/**
- * The empty JSON body an HTTP 204 becomes by the time the harness sees it.
- *
- * `HttpClient.request` reads the body as text and returns `{}` for a zero-length
- * one, so a 204 arrives at the observer as an empty object. Declaring it as a
- * strict empty object is a real assertion — a route that starts returning
- * content fails.
- */
-export declare const NoContentResponseSchema: z.ZodMiniObject<{}, z.core.$strict>;
-/**
- * The error envelope EVERY operation declares — and, until now, the only
- * declared response nothing ever checked.
- *
- * `scripts/openapi/generate.ts` gives all 68 operations a `default` response of
- * `#/components/schemas/ApiErrorEnvelope`. C4 could not see it, because
- * `HttpClient.request` threw on a non-2xx *before* reporting to the wire
- * observer, so the harness only ever met 2xx bodies. Both halves move together:
- * the report now happens ahead of the throw, and this is what the reported body
- * is checked against.
- *
- * ## Why this one is NOT a `responseObject`
- *
- * Every other schema in this family is strict, deliberately — an undeclared
- * field should fail the suite. The generated component declares
- * `additionalProperties: true`, and it is right to: the envelope is a BASE that
- * individual codes extend. `session_busy` adds the session's current `status`,
- * `rate_limited` adds `retryAfterMs`, `content_deleted` adds `sessionId` /
- * `purgedAt` / `deletedBy`, an auth failure adds `requiredScope` —
- * `error-factory.ts` reads every one of them. Declaring this strict would fail
- * the suite on error bodies our own client is built to consume, which is
- * inventing a contract rather than checking one.
- *
- * ## What it therefore does assert
- *
- * That a non-2xx JSON body carries the two fields the spec marks required — a
- * stable machine-readable `error` code and a human `message` — and that
- * `requestId`, when present, is a string. That is a real assertion about the
- * wire, not a tautology: the lambda's `finalizeApiResponse` only defaults a
- * `message` for codes present in its `API_ERROR_MESSAGES` table, and only
- * rewrites a body that already carries an `error` or a `code`. A rejection
- * produced anywhere other than a route handler — an API-Gateway-native 403, say
- * — carries neither and surfaces here as a violation. That is a FINDING about
- * the declared contract; do not loosen this schema to make such a body pass.
- */
-export declare const ApiErrorEnvelopeSchema: z.ZodMiniObject<{
-    error: z.ZodMiniString<string>;
-    message: z.ZodMiniString<string>;
-    requestId: z.ZodMiniOptional<z.ZodMiniString<string>>;
-}, z.core.$loose>;

package/dist/_contracts/schemas/response-common.js

@@ -1,162 +0,0 @@
-/**
- * Shared machinery for the RESPONSE half of the wire contract (C4 / P3).
- *
- * The request schemas answer "what may a caller send". These answer "what did
- * the server actually send", and they are checked against real bytes by
- * {@link import("../testing/wire-conformance.js").installWireConformance} rather
- * than by anything on the request path. That is the whole value: it is the one
- * gate in the contract pipeline that observes reality instead of comparing two
- * of our own artefacts to each other.
- *
- * Three rules the modules in this family follow:
- *
- * 1. **Strict.** Every response object is a {@link responseObject}, i.e. a
- *    `z.strictObject`. A field the server added and we never declared FAILS the
- *    suite. That generalises what `parseWhoAmI` did by hand for three removed
- *    fields (`caps`, `tokenId`, `tokenName`) to the whole surface. Several of
- *    our own declared types used to carry `[key: string]: unknown` — an explicit
- *    "additive server fields pass through" promise — and these schemas
- *    deliberately did not honour it. They no longer have to: an index signature
- *    makes EVERY undeclared field structurally legal, which is how
- *    `BillingSummary` came to omit two fields the server always sends without
- *    anything being able to notice. The signatures are gone from the types too.
- * 2. **No `.transform()`.** `z.toJSONSchema(s, { io: "output" })` throws on any
- *    transform, which would make the response half of the generated spec
- *    ungenerable. Schemas validate; `normalize*()` functions transform.
- * 3. **`zod/mini` only**, like every other module in this directory.
- */
-import * as z from "zod/mini";
-import { wireObject, wirePath } from "./wire.js";
-/**
- * Metadata registry for response schemas.
- *
- * Deliberately NOT `z.globalRegistry`. The OpenAPI generator converts
- * `OPENAPI_SCHEMA_REGISTRY`, and that constant *is* `z.globalRegistry` — so
- * registering a response schema there would silently add a component to
- * `openapi/data-plane.json`, break the committed-spec freshness gate (C3), and
- * do it as a side effect of merely importing this file. Response schemas are not
- * referenced by any generated operation yet (`scripts/openapi/generate.ts` still
- * emits `"2XX": { description: "Success." }`), so an entry there would be an
- * unreferenced component describing nothing.
- *
- * When the generator learns to declare responses, this registry is what it
- * converts — the ids below are already the component names.
- */
-export const responseSchemaRegistry = z.registry();
-/** Render the position of an issue as a wire path rooted at the response body. */
-function responsePath(issuePath) {
-    return wirePath("response", issuePath);
-}
-function expected(description) {
-    return (issue) => `${responsePath(issue.path ?? [])} must be ${description}`;
-}
-/**
- * A strict response object.
- *
- * Paths are resolved against the ROOT of the parse rather than anchored on a
- * fixed name, so a nested object reports its real position
- * (`response.session.currentRun.phase`) instead of doubling a segment — the trap
- * the port measured and `08-refined-plan.md` records.
- */
-export function responseObject(shape) {
-    return wireObject(responsePath, shape, {
-        notObject: (path) => `${path} must be an object`,
-        unknownKey: (path, key, permitted) => `${path}.${key} is not a declared response field; declared: ${permitted.join(", ")}`
-    });
-}
-/**
- * Attach the component id and prose a spec consumer needs.
- *
- * `.meta()` does not exist on `zod/mini` schemas; `.register()` is the mini
- * equivalent and is what every metadata instruction in the plan documents means.
- */
-export function describeResponse(id, description, schema) {
-    responseSchemaRegistry.add(schema, { id, description });
-    return schema;
-}
-// ===========================================================================
-// Field primitives
-//
-// One instance each, shared across every response shape. Zod schemas are
-// immutable, and the message is derived from the issue's own path, so a single
-// `wireString` reports `response.session.id must be a string` in one object and
-// `response.entries[3].currency must be a string` in another.
-// ===========================================================================
-export const wireString = z.string({ error: expected("a string") });
-/**
- * A string the hand-written parsers already required to be non-empty (ids,
- * statuses, timestamps). Asserting less than the client already asserts would
- * make C4 weaker than the code it is meant to backstop.
- */
-export const wireNonEmptyString = z.string({ error: expected("a non-empty string") }).check(z.refine((value) => value.length > 0, { error: expected("a non-empty string") }));
-/** A finite number. `z.number()` already rejects `NaN` and `±Infinity` (measured). */
-export const wireNumber = z.number({ error: expected("a finite number") });
-export const wireNonNegativeNumber = z.number({ error: expected("a non-negative finite number") }).check(z.refine((value) => value >= 0, { error: expected("a non-negative finite number") }));
-export const wireInteger = z.int({ error: expected("a safe integer") });
-export const wireNonNegativeInteger = z.int({ error: expected("a non-negative safe integer") }).check(z.refine((value) => value >= 0, { error: expected("a non-negative safe integer") }));
-export const wirePositiveInteger = z.int({ error: expected("a positive safe integer") }).check(z.refine((value) => value >= 1, { error: expected("a positive safe integer") }));
-export const wireBoolean = z.boolean({ error: expected("a boolean") });
-/** An ISO-8601 timestamp, judged the way the parsers judge one: `Date.parse` succeeds. */
-export const wireTimestamp = z.string({ error: expected("an ISO-8601 timestamp") }).check(z.refine((value) => Number.isFinite(Date.parse(value)), {
-    error: expected("an ISO-8601 timestamp")
-}));
-/** A closed vocabulary. The message names the accepted values, as the parsers do. */
-export function wireEnum(values) {
-    return z.enum(values, { error: expected(`one of: ${values.join(", ")}`) });
-}
-/** A literal the server always sends verbatim (`ok: true`, `kind: "file"`). */
-export function wireLiteral(value) {
-    return z.literal(value, { error: expected(JSON.stringify(value)) });
-}
-/**
- * The empty JSON body an HTTP 204 becomes by the time the harness sees it.
- *
- * `HttpClient.request` reads the body as text and returns `{}` for a zero-length
- * one, so a 204 arrives at the observer as an empty object. Declaring it as a
- * strict empty object is a real assertion — a route that starts returning
- * content fails.
- */
-export const NoContentResponseSchema = describeResponse("NoContentResponse", "An HTTP 204 with no body. `HttpClient` renders a zero-length body as `{}`, " +
-    "so the assertion is that the route sends nothing at all.", responseObject({}));
-/**
- * The error envelope EVERY operation declares — and, until now, the only
- * declared response nothing ever checked.
- *
- * `scripts/openapi/generate.ts` gives all 68 operations a `default` response of
- * `#/components/schemas/ApiErrorEnvelope`. C4 could not see it, because
- * `HttpClient.request` threw on a non-2xx *before* reporting to the wire
- * observer, so the harness only ever met 2xx bodies. Both halves move together:
- * the report now happens ahead of the throw, and this is what the reported body
- * is checked against.
- *
- * ## Why this one is NOT a `responseObject`
- *
- * Every other schema in this family is strict, deliberately — an undeclared
- * field should fail the suite. The generated component declares
- * `additionalProperties: true`, and it is right to: the envelope is a BASE that
- * individual codes extend. `session_busy` adds the session's current `status`,
- * `rate_limited` adds `retryAfterMs`, `content_deleted` adds `sessionId` /
- * `purgedAt` / `deletedBy`, an auth failure adds `requiredScope` —
- * `error-factory.ts` reads every one of them. Declaring this strict would fail
- * the suite on error bodies our own client is built to consume, which is
- * inventing a contract rather than checking one.
- *
- * ## What it therefore does assert
- *
- * That a non-2xx JSON body carries the two fields the spec marks required — a
- * stable machine-readable `error` code and a human `message` — and that
- * `requestId`, when present, is a string. That is a real assertion about the
- * wire, not a tautology: the lambda's `finalizeApiResponse` only defaults a
- * `message` for codes present in its `API_ERROR_MESSAGES` table, and only
- * rewrites a body that already carries an `error` or a `code`. A rejection
- * produced anywhere other than a route handler — an API-Gateway-native 403, say
- * — carries neither and surfaces here as a violation. That is a FINDING about
- * the declared contract; do not loosen this schema to make such a body pass.
- */
-export const ApiErrorEnvelopeSchema = describeResponse("ApiErrorEnvelope", "The body every non-2xx response carries: a stable `error` code, a human " +
-    "`message`, and the `requestId` to quote in a support request. Open by " +
-    "design — individual codes extend it with their own fields.", z.looseObject({
-    error: wireNonEmptyString,
-    message: wireString,
-    requestId: z.optional(wireString)
-}, { error: (issue) => `${responsePath(issue.path ?? [])} must be an object` }));