@company-semantics/contracts 93.3.0 → 95.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "93.3.0",
+  "version": "95.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '694bbd340597' as const;
-export const SPEC_HASH_FULL = '694bbd3405976ed940683994c167242174ad628748e5694fc6f138ccd4802cee' as const;
+export const SPEC_HASH = 'd4db95eeefb4' as const;
+export const SPEC_HASH_FULL = 'd4db95eeefb4bf7a97541fcefdcb90c1804e1e39508fe0b98e6389ce001a6f16' as const;

package/src/api/generated.ts

@@ -5569,6 +5569,10 @@ export interface components {
                     requestId: string;
                     questionId: string;
                 };
+                presentationGroupId: string | null;
+                /** @enum {string} */
+                turnKind: "conversation" | "workflow_launch" | "workflow_settlement" | "input_request_launch" | "proactive" | "refusal";
+                myFeedback: ("up" | "down") | null;
             }[];
         };
         SuccessResponse: {
@@ -10125,17 +10129,38 @@ export interface components {
             hostedSurchargeBps: number;
             byoFeeBps: number;
             priceBookVersion: string;
+            /** Format: date-time */
+            priceBookEffectiveAt: string;
             models: {
                 /** @enum {string} */
                 provider: "openai" | "anthropic";
                 modelId: string;
-                inputPerMMicros: string;
-                outputPerMMicros: string;
-                cacheReadPerMMicros: string;
-                cacheWritePerMMicros: string;
-                reasoningPerMMicros: string;
-                hostedInputPerMMicros: string;
-                hostedOutputPerMMicros: string;
+                aliases: string[];
+                sourceUrl: string | null;
+                retrievedOn: string | null;
+                promptTierMeasure: ("input_incl_cache" | "input_excl_cache") | null;
+                promptTokensCeiling: number | null;
+                tiers: {
+                    /** @enum {string} */
+                    processingMode: "standard" | "batch" | "flex" | "fast" | "ultrafast";
+                    promptTokensAbove: number;
+                    reference: {
+                        inputPerMMicros: string;
+                        outputPerMMicros: string | null;
+                        cacheReadPerMMicros: string | null;
+                        cacheWritePerMMicros: string | null;
+                        cacheWrite1hPerMMicros: string | null;
+                        reasoningPerMMicros: string | null;
+                    };
+                    hosted: {
+                        inputPerMMicros: string;
+                        outputPerMMicros: string | null;
+                        cacheReadPerMMicros: string | null;
+                        cacheWritePerMMicros: string | null;
+                        cacheWrite1hPerMMicros: string | null;
+                        reasoningPerMMicros: string | null;
+                    };
+                }[];
             }[];
         };
         SourceSyncDiscoveryRunResponse: {

package/src/billing/README.md

@@ -18,7 +18,8 @@ What it publishes:
 - **Closed enums**, each an `as const` tuple with a union type and a `z.enum`
   built from the same tuple: credential source, funding mode, platform status,
   AI pause reason, ledger entry type, reservation state, settlement basis,
-  top-up kind and status, token dimension, principal kind, and provider.
+  top-up kind and status, token dimension, principal kind, provider, processing
+  mode and prompt tier measure.
 - **Derived tables.** `SEAT_BILLABILITY`, the mapping from principal kind to
   seat billability, and `TokenDimensionsSchema`, one integer count per token
   dimension.
@@ -99,6 +100,41 @@ owner is always its owner contradicts ADR-BE-296, and nothing imported them.
   who paid and was never credited, and `succeeded` and `credited` stay distinct
   in `TOP_UP_STATUSES` so that gap is visible to an operator.
 
+## Price list card (ADR slug price-list-tiers)
+
+`PriceListSchema` publishes one card per model (`PriceListModelSchema`), not one
+flat rate row. The card mirrors the provider's own pricing structure, so a
+customer can check every charge against the provider's published page.
+
+- **A card is `tiers[]`**: one `PriceListTierSchema` entry per
+  (`processingMode`, `promptTokensAbove`). Each tier carries the provider's
+  `reference` rates and the `hosted` rates derived from them, both as
+  `PriceListRatesSchema` (micro-USD per million tokens). Every priced model has a
+  `standard` tier at `promptTokensAbove: 0`; a request whose prompt is above a
+  tier's threshold pays that tier's rates on every dimension.
+- **A processing mode is an explicit provider rate set, never a multiplier we
+  derive.** `PROCESSING_MODES` names the sets (standard, batch, flex, fast,
+  ultrafast); a mode's rates are the provider's published numbers, because
+  providers do not price modes by a clean factor (OpenAI gpt-4o Fast is 1.7x
+  Standard).
+- **`null` means the provider publishes no separate rate** for that dimension —
+  never `"0"`. An input-side null (cache read, cache write) bills at the tier's
+  input rate, which is what the provider charges. `cacheWrite1hPerMMicros` is
+  published for transparency; the backend refuses 1-hour-TTL requests until a
+  usage axis exists for it (`TokenDimensionsSchema` is unchanged).
+- **A model with more than one tier names its `promptTierMeasure`**
+  (`PROMPT_TIER_MEASURES`): what the provider counts to choose the tier. An
+  ambiguous provider rule is never guessed; the long tier stays unpublished and
+  `promptTokensCeiling` refuses prompts above the published range.
+- **An id is listed once** per price list: as a card's `modelId` or as one
+  card's `aliases` entry, never both.
+- **Corrections publish a new price-book version; history is never
+  recomputed.** `priceBookEffectiveAt` says when a version took effect,
+  `PriceBookVersionListSchema` lists every version that has ever priced a
+  charge, and `PriceListQuerySchema` selects one by label (omit for the active
+  version). The query schema is the one request-side shape here, published
+  because the version label is part of the price list's public promise.
+
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
@@ -169,14 +205,30 @@ owner is always its owner contradicts ADR-BE-296, and nothing imported them.
 - `OrgBillingOverview` _(type)_ — Everything the org's billing page needs, in one response.
 - `OrgBillingOverviewSchema` — Everything the org's billing page needs, in ONE response.
 - `PRINCIPAL_KINDS` — WHAT KIND of thing an org membership represents.
+- `PROCESSING_MODES` — How a provider processes a request, which selects the rate set it is billed at.
+- `PROMPT_TIER_MEASURES` — What a provider counts to decide which prompt-length tier a request pays.
 - `PortalSessionResponse` _(type)_ — A Stripe customer-portal session to send the customer to.
 - `PortalSessionResponseSchema` — A Stripe customer-portal session to send the customer to.
+- `PriceBookVersionList` _(type)_ — The price book's version history, newest first.
+- `PriceBookVersionListSchema` — The price book's version history, newest first.
+- `PriceBookVersionSummary` _(type)_ — One published price-book version.
+- `PriceBookVersionSummarySchema` — One published price-book version, newest first in the list.
 - `PriceList` _(type)_ — The published price book, versioned.
-- `PriceListModel` _(type)_ — One priced model.
-- `PriceListModelSchema` — One priced model.
+- `PriceListModel` _(type)_ — One priced model's card: provenance, aliases and tiers per mode.
+- `PriceListModelSchema` — One priced model's card: its provenance, the ids it serves, and its tiers per processing mode.
+- `PriceListQuery` _(type)_ — The price-list query: an optional version label, else the active one.
+- `PriceListQuerySchema` — `GET /api/billing/price-list?version=<label>` — omit for the active version.
+- `PriceListRates` _(type)_ — One rate set, micro-USD per million tokens; null = no separate rate.
+- `PriceListRatesSchema` — One rate set, micro-USD PER MILLION tokens.
 - `PriceListSchema` — The published price book, versioned.
+- `PriceListTier` _(type)_ — One tier of one processing mode: reference and hosted rates.
+- `PriceListTierSchema` — One tier of one processing mode.
 - `PrincipalKind` _(type)_ — What kind of thing an org membership represents.
 - `PrincipalKindSchema`
+- `ProcessingMode` _(type)_
+- `ProcessingModeSchema`
+- `PromptTierMeasure` _(type)_
+- `PromptTierMeasureSchema`
 - `ProviderKeyList` _(type)_ — Every provider the org could configure a key for.
 - `ProviderKeyListSchema` — Every provider the org could configure a key for, configured or not.
 - `ProviderKeyStatus` _(type)_ — What an org may see about one of its own provider keys.

package/src/billing/__tests__/price-list-tiers.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import {
+  PriceListModelSchema,
+  PriceListSchema,
+  PriceBookVersionListSchema,
+} from "../schemas";
+import { PROCESSING_MODES, PROMPT_TIER_MEASURES } from "../vocabulary";
+
+const rates = (input: string) => ({
+  inputPerMMicros: input,
+  outputPerMMicros: "500000",
+  cacheReadPerMMicros: "10000",
+  cacheWritePerMMicros: "125000",
+  cacheWrite1hPerMMicros: "200000",
+  reasoningPerMMicros: "500000",
+});
+const haiku55 = {
+  provider: "anthropic",
+  modelId: "claude-haiku-5-5",
+  aliases: [],
+  sourceUrl: "https://platform.claude.com/docs/en/about-claude/pricing",
+  retrievedOn: "2026-10-09",
+  promptTierMeasure: "input_incl_cache",
+  promptTokensCeiling: null,
+  tiers: [
+    {
+      processingMode: "standard",
+      promptTokensAbove: 0,
+      reference: rates("100000"),
+      hosted: rates("120000"),
+    },
+    {
+      processingMode: "standard",
+      promptTokensAbove: 100000,
+      reference: rates("500000"),
+      hosted: rates("600000"),
+    },
+  ],
+};
+
+describe("price list tiers", () => {
+  it("accepts a two-tier model that names its measure", () => {
+    expect(PriceListModelSchema.safeParse(haiku55).success).toBe(true);
+  });
+  it("refuses two tiers without a promptTierMeasure", () => {
+    expect(
+      PriceListModelSchema.safeParse({ ...haiku55, promptTierMeasure: null })
+        .success,
+    ).toBe(false);
+  });
+  it("refuses a model with no standard base tier", () => {
+    expect(
+      PriceListModelSchema.safeParse({ ...haiku55, tiers: [haiku55.tiers[1]] })
+        .success,
+    ).toBe(false);
+  });
+  it("accepts a null cache read as not separately priced", () => {
+    const t = {
+      ...haiku55.tiers[0],
+      reference: { ...rates("500000"), cacheReadPerMMicros: null },
+    };
+    expect(
+      PriceListModelSchema.safeParse({
+        ...haiku55,
+        promptTierMeasure: null,
+        tiers: [t],
+      }).success,
+    ).toBe(true);
+  });
+  it("accepts a pre-catalog card with no source", () => {
+    expect(
+      PriceListModelSchema.safeParse({
+        ...haiku55,
+        sourceUrl: null,
+        retrievedOn: null,
+      }).success,
+    ).toBe(true);
+  });
+  it("refuses an alias that is also listed as its own model", () => {
+    const dated = { ...haiku55, modelId: "claude-haiku-5-5-20261001" };
+    expect(
+      PriceListSchema.safeParse({
+        seatPriceMicros: null,
+        hostedSurchargeBps: 2000,
+        byoFeeBps: 500,
+        priceBookVersion: "pb-2026-10-v3",
+        priceBookEffectiveAt: "2026-10-10T00:00:00Z",
+        models: [{ ...haiku55, aliases: ["claude-haiku-5-5-20261001"] }, dated],
+      }).success,
+    ).toBe(false);
+  });
+  it("names the closed processing modes and tier measures", () => {
+    expect(PROCESSING_MODES).toEqual([
+      "standard",
+      "batch",
+      "flex",
+      "fast",
+      "ultrafast",
+    ]);
+    expect(PROMPT_TIER_MEASURES).toEqual([
+      "input_incl_cache",
+      "input_excl_cache",
+    ]);
+  });
+  it("requires the effective-at on the list and the version history shape", () => {
+    expect(
+      PriceListSchema.safeParse({
+        seatPriceMicros: null,
+        hostedSurchargeBps: 2000,
+        byoFeeBps: 500,
+        priceBookVersion: "pb-2026-10-v3",
+        models: [haiku55],
+      }).success,
+    ).toBe(false);
+    expect(
+      PriceBookVersionListSchema.safeParse({
+        versions: [
+          {
+            versionLabel: "pb-2026-10-v3",
+            effectiveAt: "2026-10-10T00:00:00Z",
+            source: "catalog",
+            notes: null,
+            active: true,
+          },
+        ],
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/billing/__tests__/processing-modes.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import {
+  PROCESSING_MODES,
+  ProcessingModeSchema,
+  PROMPT_TIER_MEASURES,
+  PromptTierMeasureSchema,
+} from "../index";
+
+describe("processing modes and prompt tier measures", () => {
+  it("exports the processing modes through the billing index", () => {
+    expect(PROCESSING_MODES).toContain("fast");
+    expect(PROMPT_TIER_MEASURES).toContain("input_excl_cache");
+    // "priority" was renamed to "fast"; the closed vocabulary refuses it.
+    expect(ProcessingModeSchema.safeParse("priority").success).toBe(false);
+    expect(PromptTierMeasureSchema.safeParse("input_incl_cache").success).toBe(
+      true,
+    );
+  });
+});

package/src/billing/__tests__/schemas.test.ts

@@ -179,27 +179,50 @@ describe("the billing response schemas", () => {
     });
 
     it("rejects a price list whose per-million rate is a number", () => {
-      expect(
-        PriceListSchema.safeParse({
-          seatPriceMicros: null,
-          hostedSurchargeBps: 2000,
-          byoFeeBps: 500,
-          priceBookVersion: "2026-09-01",
-          models: [
-            {
-              provider: "anthropic",
-              modelId: "claude-opus-5",
-              inputPerMMicros: 15000000,
-              outputPerMMicros: "75000000",
-              cacheReadPerMMicros: "1500000",
-              cacheWritePerMMicros: "18750000",
-              reasoningPerMMicros: "75000000",
-              hostedInputPerMMicros: "18000000",
-              hostedOutputPerMMicros: "90000000",
-            },
-          ],
-        }).success,
-      ).toBe(false);
+      const rates = {
+        inputPerMMicros: "15000000",
+        outputPerMMicros: "75000000",
+        cacheReadPerMMicros: "1500000",
+        cacheWritePerMMicros: "18750000",
+        cacheWrite1hPerMMicros: "30000000",
+        reasoningPerMMicros: "75000000",
+      };
+      const priceList = (inputPerMMicros: string | number) => ({
+        seatPriceMicros: null,
+        hostedSurchargeBps: 2000,
+        byoFeeBps: 500,
+        priceBookVersion: "2026-09-01",
+        priceBookEffectiveAt: "2026-09-01T00:00:00Z",
+        models: [
+          {
+            provider: "anthropic",
+            modelId: "claude-opus-5",
+            aliases: [],
+            sourceUrl:
+              "https://platform.claude.com/docs/en/about-claude/pricing",
+            retrievedOn: "2026-09-01",
+            promptTierMeasure: null,
+            promptTokensCeiling: null,
+            tiers: [
+              {
+                processingMode: "standard",
+                promptTokensAbove: 0,
+                reference: { ...rates, inputPerMMicros },
+                hosted: { ...rates, inputPerMMicros: "18000000" },
+              },
+            ],
+          },
+        ],
+      });
+
+      // The same list with the rate as a string parses, so the only defect is
+      // the JSON number.
+      expect(PriceListSchema.safeParse(priceList("15000000")).success).toBe(
+        true,
+      );
+      expect(PriceListSchema.safeParse(priceList(15000000)).success).toBe(
+        false,
+      );
     });
   });
 

package/src/billing/index.ts

@@ -30,6 +30,8 @@ export type {
   TokenDimension,
   PrincipalKind,
   BillingProvider,
+  ProcessingMode,
+  PromptTierMeasure,
   SeatBillability,
 } from "./vocabulary";
 
@@ -60,6 +62,10 @@ export {
   PrincipalKindSchema,
   BILLING_PROVIDERS,
   BillingProviderSchema,
+  PROCESSING_MODES,
+  ProcessingModeSchema,
+  PROMPT_TIER_MEASURES,
+  PromptTierMeasureSchema,
   SEAT_BILLABILITY,
   TokenDimensionsSchema,
 } from "./vocabulary";
@@ -102,8 +108,13 @@ export {
   ModelAllowlistSchema,
   OrgBillingOverviewSchema,
   PortalSessionResponseSchema,
+  PriceBookVersionListSchema,
+  PriceBookVersionSummarySchema,
   PriceListModelSchema,
+  PriceListQuerySchema,
+  PriceListRatesSchema,
   PriceListSchema,
+  PriceListTierSchema,
   ProviderKeyListSchema,
   ProviderKeyStatusSchema,
   SpendingControlsSchema,
@@ -144,8 +155,13 @@ export type {
   ModelAllowlist,
   OrgBillingOverview,
   PortalSessionResponse,
+  PriceBookVersionList,
+  PriceBookVersionSummary,
   PriceList,
   PriceListModel,
+  PriceListQuery,
+  PriceListRates,
+  PriceListTier,
   ProviderKeyList,
   ProviderKeyStatus,
   SpendingControls,

package/src/billing/schemas.ts

@@ -19,7 +19,11 @@
  * - EVERY percentage is {@link BpsSchema} — an integer number of basis points.
  *   `effectiveMarkupBps: 20.5` is not a fine-grained markup, it is a bug.
  * - EVERY timestamp is {@link IsoDateTime}, the package's single definition
- *   site for a `format: date-time` field (ADR-CONTRACTS-156).
+ *   site for a `format: date-time` field (ADR-CONTRACTS-156); the price book's
+ *   effective-at timestamps use its offset-tolerant sibling.
+ * - A price-list rate that is `null` means the provider publishes no separate
+ *   rate for it — never `"0"`. A processing mode is an explicit rate set, never
+ *   a multiplier (ADR slug price-list-tiers).
  * - EVERY token count is a non-negative integer, reported per dimension via
  *   {@link TokenDimensionsSchema} and never collapsed into one total
  *   (INV-BILL-RAW-TOKENS-ALWAYS-VISIBLE).
@@ -35,7 +39,7 @@
  */
 import { z } from "zod";
 
-import { IsoDateTime } from "../api/primitives";
+import { IsoDateTime, IsoDateTimeWithOffset } from "../api/primitives";
 import {
   AI_PAUSE_REASONS,
   BILLING_PLATFORM_STATUSES,
@@ -45,6 +49,9 @@ import {
   FUNDING_MODES,
   LEDGER_ENTRY_TYPES,
   MoneyMicrosSchema,
+  PROCESSING_MODES,
+  ProcessingModeSchema,
+  PromptTierMeasureSchema,
   TOP_UP_KINDS,
   TOP_UP_STATUSES,
   TokenDimensionsSchema,
@@ -412,37 +419,151 @@ export const ProviderKeyListSchema = z.object({
 /* -------------------------------------------------------------------------- */
 
 /**
- * One priced model. Every rate is micro-USD PER MILLION tokens, which is what
- * the `PerM` suffix means and the only unit any of them is ever in — the
- * provider publishes per-million prices, and converting on the way in would
- * round before anything has been metered.
+ * One rate set, micro-USD PER MILLION tokens. `null` means the provider publishes
+ * no separate rate for that dimension: an input-side dimension (cache read,
+ * cache write) is then billed at the tier's input rate, which is what the
+ * provider charges; an output-side null on a model is refused at the gate when
+ * the call could produce output. `cacheWritePerMMicros` is the provider's default
+ * (Anthropic: 5-minute) write; `cacheWrite1hPerMMicros` the Anthropic 1-hour write.
  *
- * The `hosted*` pair is the rate charged when this platform's credential paid.
- * There is no BYO counterpart: a BYO call is billed by the provider directly
- * and this platform charges `byoFeeBps` on it, not a per-token rate.
+ * Null is never encoded as `"0"`: zero would be a price (free), not the absence
+ * of one.
  */
-export const PriceListModelSchema = z.object({
-  provider: z.enum(BILLING_PROVIDERS),
-  modelId: z.string(),
+export const PriceListRatesSchema = z.object({
   inputPerMMicros: MoneyMicrosSchema,
-  outputPerMMicros: MoneyMicrosSchema,
-  cacheReadPerMMicros: MoneyMicrosSchema,
-  cacheWritePerMMicros: MoneyMicrosSchema,
-  reasoningPerMMicros: MoneyMicrosSchema,
-  hostedInputPerMMicros: MoneyMicrosSchema,
-  hostedOutputPerMMicros: MoneyMicrosSchema,
+  outputPerMMicros: MoneyMicrosSchema.nullable(),
+  cacheReadPerMMicros: MoneyMicrosSchema.nullable(),
+  cacheWritePerMMicros: MoneyMicrosSchema.nullable(),
+  cacheWrite1hPerMMicros: MoneyMicrosSchema.nullable(),
+  reasoningPerMMicros: MoneyMicrosSchema.nullable(),
 });
 
+/**
+ * One tier of one processing mode. `promptTokensAbove` is 0 for the base tier;
+ * a request whose prompt (per the model's `promptTierMeasure`) is ABOVE it pays
+ * this tier's rates on EVERY dimension. `reference` is the provider's list
+ * rate; `hosted` is what a hosted call is charged per million (reference plus
+ * the surcharge, same rounding as settlement, null preserved).
+ *
+ * A processing mode is its own explicit rate set, never a multiplier on the
+ * standard one: the providers do not publish clean multipliers.
+ */
+export const PriceListTierSchema = z.object({
+  processingMode: ProcessingModeSchema,
+  promptTokensAbove: z.number().int().min(0),
+  reference: PriceListRatesSchema,
+  hosted: PriceListRatesSchema,
+});
+
+/**
+ * One priced model's card: its provenance, the ids it serves, and its tiers
+ * per processing mode. Every model has a `standard` base tier; a model with
+ * more than one tier in any mode names the {@link PromptTierMeasureSchema} that
+ * decides which tier a request falls in.
+ *
+ * There is no BYO rate: a BYO call is billed by the provider directly and this
+ * platform charges `byoFeeBps` on it, not a per-token rate.
+ */
+export const PriceListModelSchema = z
+  .object({
+    provider: z.enum(BILLING_PROVIDERS),
+    modelId: z.string().min(1),
+    /**
+     * Ids this version records as served by the same card; [] when the version
+     * records none. An id appears once in a price list, as a modelId or as an
+     * alias, never both.
+     */
+    aliases: z.array(z.string().min(1)),
+    /**
+     * The provider's official pricing page the card was authored from. Null for
+     * a price-book version authored before the catalog recorded provenance.
+     */
+    sourceUrl: z.string().url().nullable(),
+    /**
+     * ISO date (YYYY-MM-DD) the source was last read. Null for a price-book
+     * version authored before the catalog recorded provenance.
+     */
+    retrievedOn: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .nullable(),
+    promptTierMeasure: PromptTierMeasureSchema.nullable(),
+    /** Prompts above this many tokens are refused (a tier we have not published). Null = no ceiling. */
+    promptTokensCeiling: z.number().int().positive().nullable(),
+    tiers: z.array(PriceListTierSchema).min(1),
+  })
+  .superRefine((m, ctx) => {
+    const standardBase = m.tiers.some(
+      (t) => t.processingMode === "standard" && t.promptTokensAbove === 0,
+    );
+    if (!standardBase) {
+      ctx.addIssue("every priced model has a standard base tier");
+    }
+    for (const mode of PROCESSING_MODES) {
+      const above = m.tiers
+        .filter((t) => t.processingMode === mode)
+        .map((t) => t.promptTokensAbove);
+      if (above.length > 1 && m.promptTierMeasure === null) {
+        ctx.addIssue(
+          "a model with more than one tier names its promptTierMeasure",
+        );
+      }
+      if (new Set(above).size !== above.length) {
+        ctx.addIssue(`duplicate tier threshold in mode ${mode}`);
+      }
+    }
+  });
+
 /**
  * The published price book, versioned. Read by the app to show what a model
  * costs before it is used, and by control to audit what it charged after.
+ * A correction is a new version; a published version is never recomputed.
  */
-export const PriceListSchema = z.object({
-  seatPriceMicros: MoneyMicrosSchema.nullable(),
-  hostedSurchargeBps: BpsSchema,
-  byoFeeBps: BpsSchema,
-  priceBookVersion: z.string(),
-  models: z.array(PriceListModelSchema),
+export const PriceListSchema = z
+  .object({
+    seatPriceMicros: MoneyMicrosSchema.nullable(),
+    hostedSurchargeBps: BpsSchema,
+    byoFeeBps: BpsSchema,
+    priceBookVersion: z.string(),
+    /** When this version became the one calls are priced against (ISO timestamp). */
+    priceBookEffectiveAt: IsoDateTimeWithOffset,
+    models: z.array(PriceListModelSchema),
+  })
+  .superRefine((list, ctx) => {
+    // An id is listed once: as a card's modelId or as one card's alias, never both.
+    const seen = new Set<string>();
+    for (const m of list.models) {
+      for (const id of [m.modelId, ...m.aliases]) {
+        if (seen.has(id)) {
+          ctx.addIssue(`model id ${id} is listed more than once`);
+        }
+        seen.add(id);
+      }
+    }
+  });
+
+/**
+ * `GET /api/billing/price-list?version=<label>` — omit for the active version.
+ * A request shape published here by exception (ADR slug price-list-tiers): the
+ * app and the backend must agree on how a past version is addressed.
+ */
+export const PriceListQuerySchema = z.object({
+  version: z.string().min(1).optional(),
+});
+
+/** One published price-book version, newest first in the list. */
+export const PriceBookVersionSummarySchema = z.object({
+  versionLabel: z.string(),
+  effectiveAt: IsoDateTimeWithOffset,
+  source: z.string(),
+  notes: z.string().nullable(),
+  /** True for exactly the version calls are priced against now. */
+  active: z.boolean(),
+});
+
+/** The price book's version history, newest first. */
+export const PriceBookVersionListSchema = z.object({
+  versions: z.array(PriceBookVersionSummarySchema),
 });
 
 /**