@company-semantics/contracts 94.0.0 → 96.0.0

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),
 });
 
 /**

package/src/billing/types.ts

@@ -37,8 +37,13 @@ import type {
   ModelAllowlistSchema,
   OrgBillingOverviewSchema,
   PortalSessionResponseSchema,
+  PriceBookVersionListSchema,
+  PriceBookVersionSummarySchema,
   PriceListModelSchema,
+  PriceListQuerySchema,
+  PriceListRatesSchema,
   PriceListSchema,
+  PriceListTierSchema,
   ProviderKeyListSchema,
   ProviderKeyStatusSchema,
   SpendingControlsSchema,
@@ -151,11 +156,28 @@ export type ProviderKeyStatus = z.infer<typeof ProviderKeyStatusSchema>;
 /** Every provider the org could configure a key for. */
 export type ProviderKeyList = z.infer<typeof ProviderKeyListSchema>;
 
-/** One priced model. Every rate is micro-USD per million tokens. */
+/** One rate set, micro-USD per million tokens; null = no separate rate. */
+export type PriceListRates = z.infer<typeof PriceListRatesSchema>;
+
+/** One tier of one processing mode: reference and hosted rates. */
+export type PriceListTier = z.infer<typeof PriceListTierSchema>;
+
+/** One priced model's card: provenance, aliases and tiers per mode. */
 export type PriceListModel = z.infer<typeof PriceListModelSchema>;
 
 /** The published price book, versioned. */
 export type PriceList = z.infer<typeof PriceListSchema>;
 
+/** The price-list query: an optional version label, else the active one. */
+export type PriceListQuery = z.infer<typeof PriceListQuerySchema>;
+
+/** One published price-book version. */
+export type PriceBookVersionSummary = z.infer<
+  typeof PriceBookVersionSummarySchema
+>;
+
+/** The price book's version history, newest first. */
+export type PriceBookVersionList = z.infer<typeof PriceBookVersionListSchema>;
+
 /** A house-funded org's grant. */
 export type HouseFunding = z.infer<typeof HouseFundingSchema>;

package/src/billing/vocabulary.ts

@@ -332,6 +332,43 @@ export const BILLING_PROVIDERS = [
 export type BillingProvider = (typeof BILLING_PROVIDERS)[number];
 export const BillingProviderSchema = z.enum(BILLING_PROVIDERS);
 
+/**
+ * How a provider processes a request, which selects the rate set it is billed
+ * at. Each mode is an EXPLICIT rate set published by the provider, never a
+ * multiplier we derive: OpenAI's gpt-4o "Fast" is 1.7x Standard, gpt-6-luna's is
+ * 2x, and Anthropic's Batch is 0.5x. "fast" is what OpenAI called "priority"
+ * until 2026-07-30 and what Anthropic calls fast mode.
+ */
+export const PROCESSING_MODES = [
+  /** The provider's default processing. Every priced model has it. */
+  "standard",
+  /** Asynchronous batch processing. */
+  "batch",
+  /** OpenAI Flex: lower price, slower and best-effort capacity. */
+  "flex",
+  /** Premium latency (OpenAI Fast, formerly Priority; Anthropic fast mode). */
+  "fast",
+  /** OpenAI Ultrafast. */
+  "ultrafast",
+] as const;
+export type ProcessingMode = (typeof PROCESSING_MODES)[number];
+export const ProcessingModeSchema = z.enum(PROCESSING_MODES);
+
+/**
+ * What a provider counts to decide which prompt-length tier a request pays.
+ * Anthropic (Claude Haiku 5.5, >100K): every input token, INCLUDING cache reads
+ * and cache writes. A model with more than one tier must name its measure; an
+ * ambiguous provider rule is never guessed (the long tier stays unpublished).
+ */
+export const PROMPT_TIER_MEASURES = [
+  /** input + cache read + cache write. */
+  "input_incl_cache",
+  /** Fresh (uncached) input only. */
+  "input_excl_cache",
+] as const;
+export type PromptTierMeasure = (typeof PROMPT_TIER_MEASURES)[number];
+export const PromptTierMeasureSchema = z.enum(PROMPT_TIER_MEASURES);
+
 /* -------------------------------------------------------------------------- */
 /* Derived tables                                                             */
 /* -------------------------------------------------------------------------- */

package/src/generated/openapi-routes.ts

@@ -11,6 +11,9 @@ export const openApiRoutes = {
   '/api/account/sessions/{sessionId}': ['DELETE'],
   '/api/affordances/state': ['GET'],
   '/api/analysis-workflows/{id}': ['GET'],
+  '/api/analysis-workflows/{id}/continue': ['POST'],
+  '/api/analysis-workflows/{id}/retry': ['POST'],
+  '/api/analysis-workflows/{id}/run-again': ['POST'],
   '/api/analysis-workflows/{id}/settlement': ['POST'],
   '/api/analysis-workflows/{id}/stop': ['POST'],
   '/api/auth/consent/grant': ['POST'],

package/src/root-exports/delivery.ts

@@ -215,9 +215,41 @@ export type {
 // chat part and by the generic projection read. Namespaced `<domain>/<flow>`
 // so domains cannot collide, and a CLOSED const array so the discriminator is
 // validated and handled exhaustively. See src/workflows/README.md.
-export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "../workflows/index";
+export {
+  ANALYSIS_WORKFLOW_STATES,
+  ANALYSIS_WORKFLOW_TYPES,
+  isWorkflowType,
+} from "../workflows/index";
+
+export type { AnalysisWorkflowState, WorkflowType } from "../workflows/index";
+
+// Workflow execution actions (ADR-CONTRACTS-227): `executionAffordancesFor` is
+// the one total offer table from a workflow's state, its type's support and
+// its frozen outcome to the workflow.* affordances. See
+// src/workflows/execution-affordances.ts.
+export {
+  DOMAIN_RELAUNCH_AFFORDANCE_IDS,
+  WORKFLOW_EXECUTION_ACTIONS,
+  executionAffordancesFor,
+} from "../workflows/index";
+
+export type {
+  ExecutionAffordancesInput,
+  WorkflowExecutionAction,
+  WorkflowExecutionAffordance,
+  WorkflowExecutionSupport,
+} from "../workflows/index";
+
+// Workflow execution projection fields (ADR-CONTRACTS-227): the offered
+// workflow.* affordances, relaunch lineage and per-epoch timing the backend
+// composes into its (backend-local) workflow projection. See
+// src/workflows/projection-fields.ts.
+export {
+  WorkflowExecutionAffordanceSchema,
+  WorkflowExecutionProjectionFieldsSchema,
+} from "../workflows/index";
 
-export type { WorkflowType } from "../workflows/index";
+export type { WorkflowExecutionProjectionFields } from "../workflows/index";
 
 // The typed outcome of a workflow's terminal transition (control ADR-CTRL-540):
 // per-type closed reasons, typed facts and an explicit disposition, classified
@@ -317,6 +349,7 @@ export {
   ReviewOpenArgsSchema,
   SourceSyncOpenUpdateArgsSchema,
   TeamOpenArgsSchema,
+  WorkflowExecutionArgsSchema,
   sameAffordances,
 } from "../affordances/index";
 

package/src/workflows/README.md

@@ -62,13 +62,37 @@ so every producer, validator and renderer agrees on it.
   the backend verifies the covering occurrence at route time), and `silent`
   exactly for `stopped_by_user`. A `produced`, `empty` or `partial` ending is
   never explained.
+- **`ANALYSIS_WORKFLOW_STATES` is the backend's six states, in order**
+  (`pending`, `running`, `draining`, `stopped`, `complete`, `failed`). A
+  workflow id is the logical run; the backend's execution epoch is the attempt.
+- **Execution actions come from one total table** (ADR-CONTRACTS-227).
+  `executionAffordancesFor` maps a workflow's state, its type's
+  `WorkflowExecutionSupport` and its frozen outcome offer to the `workflow.*`
+  affordances: `pending`/`running` → stop; `draining` → nothing; `stopped` →
+  continue, runAgain; `failed` → retry, runAgain; `complete` → runAgain. An
+  unsupported action is never offered, and `workflow.runAgain` is dropped
+  beside a frozen domain relaunch (`DOMAIN_RELAUNCH_AFFORDANCE_IDS`) — one
+  relaunch control, the domain's. It never emits `review.open`.
+- **Projection fields, not the projection.** The workflow projection is
+  backend-local; `WorkflowExecutionProjectionFieldsSchema` is the one wire
+  shape for the fields it composes (`executionAffordances`, `relaunchedFrom`,
+  `epochStartedAt`, `epochCompletedAt`), every key required. Contracts does not
+  touch the projection's `capabilities` flags.
 - **Workflows never imports proactive.** The covering kinds are literal
   strings pinned against `PROACTIVE_EVENT_KIND_IDS` by a test; the dependency
   runs proactive → workflows only.
 
 ## Public API
 
-- `ANALYSIS_WORKFLOW_TYPES`, `WorkflowType`, `isWorkflowType` (`types.ts`).
+- `ANALYSIS_WORKFLOW_TYPES`, `WorkflowType`, `isWorkflowType`,
+  `ANALYSIS_WORKFLOW_STATES`, `AnalysisWorkflowState` (`types.ts`).
+- `WORKFLOW_EXECUTION_ACTIONS`, `WorkflowExecutionAction`,
+  `WorkflowExecutionSupport`, `WorkflowExecutionAffordance`,
+  `DOMAIN_RELAUNCH_AFFORDANCE_IDS`, `ExecutionAffordancesInput`,
+  `executionAffordancesFor` (`execution-affordances.ts`).
+- `WorkflowExecutionAffordanceSchema`,
+  `WorkflowExecutionProjectionFieldsSchema` /
+  `WorkflowExecutionProjectionFields` (`projection-fields.ts`).
 - `WorkflowOutcomeSchema` / `WorkflowOutcome`, the per-type member schemas and
   `WorkflowOutcomeDispositionSchema` (`outcome.ts`).
 - `WORKFLOW_OUTCOME_KINDS` and the per-type reason tables and fact schemas
@@ -88,5 +112,6 @@ so every producer, validator and renderer agrees on it.
 
 `zod` (outcome schemas), `../input-requests/types` (the review disposition's
 request type) and `../affordances/affordance` (the offered-affordance schema,
-its sanity bound and `sameAffordances`). Otherwise pure vocabulary data, one
+its sanity bound and `sameAffordances`) and `../affordances/args` (the
+`workflow.*` args schema). Otherwise pure vocabulary data, one
 guard and pure helpers.