@company-semantics/contracts 95.0.0 → 97.0.0

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.

package/src/workflows/__tests__/README.md

@@ -11,7 +11,22 @@ wire value against it.
   `<domain>/<flow>` with exactly one separator, which is the collision guard
   between domains. For `isWorkflowType`, the load-bearing cases are the
   rejections: a bare `hris-connect` without its namespace, the namespace on
-  its own, a trailing separator, an unknown flow, and non-string inputs.
+  its own, a trailing separator, an unknown flow, and non-string inputs. Also
+  pins `ANALYSIS_WORKFLOW_STATES` as the backend's six states in order.
+
+- `execution-affordances.test.ts` — pins `WORKFLOW_EXECUTION_ACTIONS` and
+  `DOMAIN_RELAUNCH_AFFORDANCE_IDS`; `executionAffordancesFor` offers the
+  per-state table with full support, never offers an unsupported action,
+  drops `workflow.runAgain` beside a frozen domain relaunch (one relaunch
+  control), never emits `review.open`, and every instance is a valid
+  `Affordance` carrying `{ workflowId }`.
+
+- `projection-fields.test.ts` — `WorkflowExecutionAffordanceSchema` accepts
+  every instance the offer table emits and refuses non-`workflow.*` ids,
+  non-uuid `workflowId`s and extra keys; `WorkflowExecutionProjectionFieldsSchema`
+  requires every key (also in its JSON Schema), refuses extra keys, more than
+  four offers and malformed lineage/timing, and both schemas reach the package
+  root.
 
 - `outcome.test.ts` — the outcome union covers every registered workflow type
   (compile-time), each reason table's kinds are valid, the schema accepts a
@@ -51,5 +66,6 @@ None — test-only.
 ## Dependencies
 
 `vitest`, `node:fs`, `../types`, `../outcome`, `../affordances-of-outcome`,
-`../deferred-route`, `../../affordances/affordance` and
+`../execution-affordances`, `../projection-fields`, `../deferred-route`, `../index`,
+`../../index` (root reachability), `../../affordances/affordance` and
 `../../proactive/kinds` (test-only: pins the covering kinds).

package/src/workflows/__tests__/execution-affordances.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  AffordanceSchema,
+  type Affordance,
+} from "../../affordances/affordance";
+import { ANALYSIS_WORKFLOW_STATES, type AnalysisWorkflowState } from "../types";
+import {
+  DOMAIN_RELAUNCH_AFFORDANCE_IDS,
+  WORKFLOW_EXECUTION_ACTIONS,
+  executionAffordancesFor,
+  type WorkflowExecutionSupport,
+} from "../execution-affordances";
+
+const workflowId = "3f1d2c4b-5a6e-4f70-8a91-b2c3d4e5f607";
+
+const ALL: WorkflowExecutionSupport = {
+  stop: true,
+  continue: true,
+  retry: true,
+  runAgain: true,
+};
+const NONE: WorkflowExecutionSupport = {
+  stop: false,
+  continue: false,
+  retry: false,
+  runAgain: false,
+};
+
+const idsFor = (
+  state: AnalysisWorkflowState,
+  support: WorkflowExecutionSupport = ALL,
+  outcomeAffordances: readonly Affordance[] = [],
+) =>
+  executionAffordancesFor({
+    workflowId,
+    state,
+    support,
+    outcomeAffordances,
+  }).map((a) => a.id);
+
+describe("WORKFLOW_EXECUTION_ACTIONS / DOMAIN_RELAUNCH_AFFORDANCE_IDS", () => {
+  it("pins the four actions and the two domain relaunches", () => {
+    expect([...WORKFLOW_EXECUTION_ACTIONS]).toEqual([
+      "stop",
+      "continue",
+      "retry",
+      "runAgain",
+    ]);
+    expect([...DOMAIN_RELAUNCH_AFFORDANCE_IDS]).toEqual([
+      "sourceSync.findFiles",
+      "orgStructure.reanalyze",
+    ]);
+  });
+});
+
+describe("executionAffordancesFor", () => {
+  it("offers per state with full support", () => {
+    expect(idsFor("pending")).toEqual(["workflow.stop"]);
+    expect(idsFor("running")).toEqual(["workflow.stop"]);
+    expect(idsFor("draining")).toEqual([]);
+    expect(idsFor("stopped")).toEqual([
+      "workflow.continue",
+      "workflow.runAgain",
+    ]);
+    expect(idsFor("failed")).toEqual(["workflow.retry", "workflow.runAgain"]);
+    expect(idsFor("complete")).toEqual(["workflow.runAgain"]);
+  });
+
+  it("a draining run offers nothing", () => {
+    expect(idsFor("draining")).toEqual([]);
+    expect(
+      idsFor("draining", ALL, [
+        { id: "sourceSync.findFiles" },
+        { id: "orgStructure.reanalyze" },
+      ]),
+    ).toEqual([]);
+  });
+
+  it("never offers an action whose support flag is false", () => {
+    for (const state of ANALYSIS_WORKFLOW_STATES) {
+      expect(idsFor(state, NONE)).toEqual([]);
+      for (const action of WORKFLOW_EXECUTION_ACTIONS) {
+        const support = { ...ALL, [action]: false };
+        expect(idsFor(state, support)).not.toContain(`workflow.${action}`);
+      }
+    }
+  });
+
+  it("run again is withheld when the outcome already offers a domain relaunch", () => {
+    expect(idsFor("complete", ALL, [{ id: "sourceSync.findFiles" }])).toEqual(
+      [],
+    );
+    expect(idsFor("failed", ALL, [{ id: "orgStructure.reanalyze" }])).toEqual([
+      "workflow.retry",
+    ]);
+    expect(idsFor("stopped", ALL, [{ id: "billing.open" }])).toEqual([
+      "workflow.continue",
+      "workflow.runAgain",
+    ]);
+  });
+
+  it("never emits review.open and every instance is schema-valid", () => {
+    const review: Affordance = {
+      id: "review.open",
+      args: { requestType: "x", requestId: "y" },
+    } as Affordance;
+    for (const state of ANALYSIS_WORKFLOW_STATES) {
+      const offered = executionAffordancesFor({
+        workflowId,
+        state,
+        support: ALL,
+        outcomeAffordances: [review],
+      });
+      for (const affordance of offered) {
+        expect(affordance.id).not.toBe("review.open");
+        expect(affordance.args).toEqual({ workflowId });
+        expect(AffordanceSchema.safeParse(affordance).success).toBe(true);
+      }
+    }
+  });
+});

package/src/workflows/__tests__/projection-fields.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import * as root from "../../index";
+import * as barrel from "../index";
+import { ANALYSIS_WORKFLOW_STATES } from "../types";
+import {
+  executionAffordancesFor,
+  type WorkflowExecutionAffordance,
+} from "../execution-affordances";
+import {
+  WorkflowExecutionAffordanceSchema,
+  WorkflowExecutionProjectionFieldsSchema,
+  type WorkflowExecutionProjectionFields,
+} from "../projection-fields";
+
+type Equals<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+
+// Compile-time: the schema's member is exactly the offer table's output.
+const memberMatchesOfferTable: Equals<
+  z.infer<typeof WorkflowExecutionAffordanceSchema>["id"],
+  WorkflowExecutionAffordance["id"]
+> = true;
+void memberMatchesOfferTable;
+
+const workflowId = "3f1d2c4b-5a6e-4f70-8a91-b2c3d4e5f607";
+
+const valid: WorkflowExecutionProjectionFields = {
+  executionAffordances: [
+    { id: "workflow.continue", args: { workflowId } },
+    { id: "workflow.runAgain", args: { workflowId } },
+  ],
+  relaunchedFrom: null,
+  epochStartedAt: "2026-10-09T10:00:00.000Z",
+  epochCompletedAt: null,
+};
+
+describe("WorkflowExecutionAffordanceSchema", () => {
+  it("accepts every instance the offer table emits", () => {
+    const support = { stop: true, continue: true, retry: true, runAgain: true };
+    for (const state of ANALYSIS_WORKFLOW_STATES) {
+      for (const affordance of executionAffordancesFor({
+        workflowId,
+        state,
+        support,
+        outcomeAffordances: [],
+      })) {
+        expect(
+          WorkflowExecutionAffordanceSchema.safeParse(affordance).success,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("refuses non-workflow ids, non-uuid ids and extra keys", () => {
+    for (const bad of [
+      { id: "review.open", args: { workflowId } },
+      { id: "sourceSync.findFiles" },
+      { id: "workflow.stop", args: { workflowId: "not-a-uuid" } },
+      { id: "workflow.stop", args: { workflowId, extra: 1 } },
+      { id: "workflow.stop", args: { workflowId }, extra: 1 },
+      { id: "workflow.stop" },
+    ]) {
+      expect(WorkflowExecutionAffordanceSchema.safeParse(bad).success).toBe(
+        false,
+      );
+    }
+  });
+});
+
+describe("WorkflowExecutionProjectionFieldsSchema", () => {
+  it("accepts a well-formed value, including a relaunch with settled timing", () => {
+    expect(
+      WorkflowExecutionProjectionFieldsSchema.safeParse(valid).success,
+    ).toBe(true);
+    expect(
+      WorkflowExecutionProjectionFieldsSchema.safeParse({
+        executionAffordances: [],
+        relaunchedFrom: workflowId,
+        epochStartedAt: "2026-10-09T10:00:00.000Z",
+        epochCompletedAt: "2026-10-09T10:05:00.000Z",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("requires every key", () => {
+    for (const key of Object.keys(valid)) {
+      const rest: Record<string, unknown> = { ...valid };
+      delete rest[key];
+      expect(
+        WorkflowExecutionProjectionFieldsSchema.safeParse(rest).success,
+      ).toBe(false);
+    }
+  });
+
+  it("projection fields without executionAffordances are refused", () => {
+    const rest: Record<string, unknown> = { ...valid };
+    delete rest.executionAffordances;
+    expect(
+      WorkflowExecutionProjectionFieldsSchema.safeParse(rest).success,
+    ).toBe(false);
+  });
+
+  it("refuses extra keys, more than four offers and malformed values", () => {
+    for (const bad of [
+      { ...valid, capabilities: {} },
+      {
+        ...valid,
+        executionAffordances: Array.from({ length: 5 }, () => ({
+          id: "workflow.stop",
+          args: { workflowId },
+        })),
+      },
+      { ...valid, relaunchedFrom: "not-a-uuid" },
+      { ...valid, epochStartedAt: "yesterday" },
+      { ...valid, epochCompletedAt: 0 },
+    ]) {
+      expect(
+        WorkflowExecutionProjectionFieldsSchema.safeParse(bad).success,
+      ).toBe(false);
+    }
+  });
+
+  it("converts to JSON Schema with every key required", () => {
+    const json = z.toJSONSchema(WorkflowExecutionProjectionFieldsSchema, {
+      io: "input",
+    }) as { required?: string[] };
+    expect([...(json.required ?? [])].sort()).toEqual([
+      "epochCompletedAt",
+      "epochStartedAt",
+      "executionAffordances",
+      "relaunchedFrom",
+    ]);
+  });
+
+  it("reaches the package root", () => {
+    for (const name of [
+      "WorkflowExecutionAffordanceSchema",
+      "WorkflowExecutionProjectionFieldsSchema",
+    ] as const) {
+      expect((root as Record<string, unknown>)[name]).toBe(barrel[name]);
+      expect(barrel[name]).toBeDefined();
+    }
+  });
+});

package/src/workflows/__tests__/types.test.ts

@@ -1,5 +1,23 @@
 import { describe, it, expect } from "vitest";
-import { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "../types";
+import {
+  ANALYSIS_WORKFLOW_STATES,
+  ANALYSIS_WORKFLOW_TYPES,
+  isWorkflowType,
+} from "../types";
+
+describe("ANALYSIS_WORKFLOW_STATES", () => {
+  // Pins the backend's six states in the backend's order.
+  it("names the backend's six lifecycle states in order", () => {
+    expect([...ANALYSIS_WORKFLOW_STATES]).toEqual([
+      "pending",
+      "running",
+      "draining",
+      "stopped",
+      "complete",
+      "failed",
+    ]);
+  });
+});
 
 describe("ANALYSIS_WORKFLOW_TYPES", () => {
   it("contains exactly the two registered org-structure flows", () => {

package/src/workflows/execution-affordances.ts

@@ -0,0 +1,107 @@
+/**
+ * The workflow execution offer table (control ADR affordance-system;
+ * ADR-CONTRACTS-227).
+ *
+ * `executionAffordancesFor` is the ONE rule deciding which execution actions
+ * (`workflow.stop | continue | retry | runAgain`) a workflow offers right now,
+ * from its lifecycle state, its type's execution support and the frozen offer
+ * of its settled outcome. The backend projection serves its result; the app
+ * renders it; neither re-derives it.
+ *
+ * INVARIANTS:
+ * - TOTAL over `AnalysisWorkflowState`: a new state fails to compile until the
+ *   table decides it.
+ * - An action whose support flag is false is never offered.
+ * - ONE relaunch control: `workflow.runAgain` is dropped whenever the frozen
+ *   outcome already offers a domain relaunch (`DOMAIN_RELAUNCH_AFFORDANCE_IDS`).
+ * - Never emits `review.open` — viewing results stays the outcome's projection.
+ * - Pure; returns a new array.
+ */
+import type { Affordance, OfferedAffordance } from "../affordances/affordance";
+import type { AnalysisWorkflowState } from "./types";
+
+/** The execution actions a workflow type may support. */
+export const WORKFLOW_EXECUTION_ACTIONS = [
+  /** Stop a pending or running workflow. */
+  "stop",
+  /** Resume a stopped workflow from where it stopped. */
+  "continue",
+  /** Re-run a failed workflow's remaining work. */
+  "retry",
+  /** Launch a fresh run of a settled or stopped workflow. */
+  "runAgain",
+] as const;
+
+/** One execution action. */
+export type WorkflowExecutionAction =
+  (typeof WORKFLOW_EXECUTION_ACTIONS)[number];
+
+/**
+ * Which execution actions a workflow type supports. Contracts names the
+ * vocabulary; the backend's per-type table holds the values.
+ */
+export type WorkflowExecutionSupport = Readonly<
+  Record<WorkflowExecutionAction, boolean>
+>;
+
+/** An execution affordance instance — one of the four `workflow.*` ids. */
+export type WorkflowExecutionAffordance = Extract<
+  Affordance,
+  { readonly id: `workflow.${WorkflowExecutionAction}` }
+>;
+
+/**
+ * Affordances that relaunch a workflow's domain work. When a frozen outcome
+ * offers one, it IS the relaunch control and `workflow.runAgain` is dropped.
+ */
+export const DOMAIN_RELAUNCH_AFFORDANCE_IDS = [
+  /** A discovery ending's relaunch. */
+  "sourceSync.findFiles",
+  /** An org-structure ending's relaunch. */
+  "orgStructure.reanalyze",
+] as const satisfies readonly OfferedAffordance["id"][];
+
+/** The actions each state may offer, in render order, before support filtering. */
+const EXECUTION_ACTIONS_OF_STATE = {
+  pending: ["stop"],
+  running: ["stop"],
+  draining: [],
+  stopped: ["continue", "runAgain"],
+  failed: ["retry", "runAgain"],
+  complete: ["runAgain"],
+} as const satisfies Record<
+  AnalysisWorkflowState,
+  readonly WorkflowExecutionAction[]
+>;
+
+/** Input to {@link executionAffordancesFor}. */
+export type ExecutionAffordancesInput = {
+  readonly workflowId: string;
+  readonly state: AnalysisWorkflowState;
+  readonly support: WorkflowExecutionSupport;
+  /** The settled outcome's frozen offer; `[]` before settlement. */
+  readonly outcomeAffordances: readonly Affordance[];
+};
+
+/** The execution affordances a workflow offers now, in render order. */
+export function executionAffordancesFor({
+  workflowId,
+  state,
+  support,
+  outcomeAffordances,
+}: ExecutionAffordancesInput): readonly WorkflowExecutionAffordance[] {
+  const domainRelaunchOffered = outcomeAffordances.some((affordance) =>
+    (DOMAIN_RELAUNCH_AFFORDANCE_IDS as readonly string[]).includes(
+      affordance.id,
+    ),
+  );
+  const actions: readonly WorkflowExecutionAction[] =
+    EXECUTION_ACTIONS_OF_STATE[state];
+  return actions
+    .filter((action) => support[action])
+    .filter((action) => !(action === "runAgain" && domainRelaunchOffered))
+    .map((action) => ({
+      id: `workflow.${action}` as const,
+      args: { workflowId },
+    }));
+}

package/src/workflows/index.ts

@@ -7,9 +7,33 @@
  * @see ./types.ts for why the list is namespaced, central and closed
  */
 
-export type { WorkflowType } from "./types";
+export type { AnalysisWorkflowState, WorkflowType } from "./types";
 
-export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "./types";
+export {
+  ANALYSIS_WORKFLOW_STATES,
+  ANALYSIS_WORKFLOW_TYPES,
+  isWorkflowType,
+} from "./types";
+
+export type {
+  ExecutionAffordancesInput,
+  WorkflowExecutionAction,
+  WorkflowExecutionAffordance,
+  WorkflowExecutionSupport,
+} from "./execution-affordances";
+
+export {
+  DOMAIN_RELAUNCH_AFFORDANCE_IDS,
+  WORKFLOW_EXECUTION_ACTIONS,
+  executionAffordancesFor,
+} from "./execution-affordances";
+
+export type { WorkflowExecutionProjectionFields } from "./projection-fields";
+
+export {
+  WorkflowExecutionAffordanceSchema,
+  WorkflowExecutionProjectionFieldsSchema,
+} from "./projection-fields";
 
 export type {
   DiscoverOutcomeFacts,

package/src/workflows/projection-fields.ts

@@ -0,0 +1,65 @@
+/**
+ * Workflow execution fields of the analysis-workflow projection (control ADR
+ * affordance-system; ADR-CONTRACTS-227).
+ *
+ * The projection itself (`AnalysisWorkflowProjectionResponseSchema`) is
+ * backend-local; the backend COMPOSES these fields into it. This module is the
+ * ONE location for their schemas, so the execution offer, the relaunch lineage
+ * and the per-epoch timing have one wire shape everywhere.
+ *
+ * INVARIANTS:
+ * - Every key is REQUIRED; absence is `null` (or `[]`), never a missing key.
+ * - `executionAffordances` carries only the four `workflow.*` instances, at most
+ *   one per action — `executionAffordancesFor`'s result, never re-derived.
+ * - Contracts neither adds nor removes the projection's other keys.
+ */
+import { z } from "zod";
+
+import { WorkflowExecutionArgsSchema } from "../affordances/args";
+
+/** One execution affordance instance — the four `workflow.*` members only. */
+export const WorkflowExecutionAffordanceSchema = z.discriminatedUnion("id", [
+  z
+    .object({
+      id: z.literal("workflow.stop"),
+      args: WorkflowExecutionArgsSchema,
+    })
+    .strict(),
+  z
+    .object({
+      id: z.literal("workflow.continue"),
+      args: WorkflowExecutionArgsSchema,
+    })
+    .strict(),
+  z
+    .object({
+      id: z.literal("workflow.retry"),
+      args: WorkflowExecutionArgsSchema,
+    })
+    .strict(),
+  z
+    .object({
+      id: z.literal("workflow.runAgain"),
+      args: WorkflowExecutionArgsSchema,
+    })
+    .strict(),
+]);
+
+/** The projection fields the backend composes into its workflow projection. */
+export const WorkflowExecutionProjectionFieldsSchema = z
+  .object({
+    /** The execution actions offered now, in render order; one per action. */
+    executionAffordances: z.array(WorkflowExecutionAffordanceSchema).max(4),
+    /** The workflow this run relaunched, or null for an original run. */
+    relaunchedFrom: z.string().uuid().nullable(),
+    /** When the current epoch started, or null before it starts. */
+    epochStartedAt: z.string().datetime().nullable(),
+    /** When the current epoch settled, or null while it is open. */
+    epochCompletedAt: z.string().datetime().nullable(),
+  })
+  .strict();
+
+/** The workflow execution projection fields. */
+export type WorkflowExecutionProjectionFields = z.infer<
+  typeof WorkflowExecutionProjectionFieldsSchema
+>;

package/src/workflows/types.ts

@@ -53,3 +53,30 @@ export function isWorkflowType(value: unknown): value is WorkflowType {
     (ANALYSIS_WORKFLOW_TYPES as readonly string[]).includes(value)
   );
 }
+
+/**
+ * The lifecycle states of an analysis workflow — the backend's six, in the
+ * backend's order (`analysis_workflows.state`; the projection enumerates the
+ * same). Domain-agnostic: every workflow type moves through the same states.
+ *
+ * INVARIANTS:
+ * - CLOSED. Tables keyed by state (`executionAffordancesFor`) are total over
+ *   this union, so a new state fails to compile until each table decides it.
+ */
+export const ANALYSIS_WORKFLOW_STATES = [
+  /** Created, not yet picked up. */
+  "pending",
+  /** Executing. */
+  "running",
+  /** A stop was requested; in-flight work is finishing. */
+  "draining",
+  /** Stopped before completing; the run's progress is kept. */
+  "stopped",
+  /** Settled successfully. */
+  "complete",
+  /** Settled with an error. */
+  "failed",
+] as const;
+
+/** One analysis-workflow lifecycle state. */
+export type AnalysisWorkflowState = (typeof ANALYSIS_WORKFLOW_STATES)[number];