@company-semantics/contracts 95.0.0 → 96.0.0

package/src/api/generated.ts

@@ -1763,6 +1763,66 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/analysis-workflows/{id}/continue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Start another execution of a stopped analysis workflow
+         * @description Reopens a STOPPED workflow in a new execution epoch and starts the execution its type serves for continue — only for a type whose execution support declares continue (otherwise 409 not_supported). Answers 202 when started; 409 not_stopped or execution_in_flight otherwise. Runtime posture: intent write, impersonation restricted (it spends model calls); the billing pre-flight runs before anything is created, and a refusal is the billing refusal envelope. An Idempotency-Key header replays the first answer for the same workflow and action. Org-scoped: a workflow in another workspace answers 404.
+         */
+        post: operations["continueAnalysisWorkflow"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/analysis-workflows/{id}/retry": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Retry a failed analysis workflow in the same workflow
+         * @description Reopens a FAILED workflow in a new execution epoch (never a new workflow id) and starts the execution its type serves for retry — only for a type whose execution support declares retry (otherwise 409 not_supported). Answers 202 when started; 409 not_failed or execution_in_flight otherwise. Runtime posture: intent write, impersonation restricted (it spends model calls); the billing pre-flight runs before anything is created, and a refusal is the billing refusal envelope. An Idempotency-Key header replays the first answer for the same workflow and action. Org-scoped: a workflow in another workspace answers 404.
+         */
+        post: operations["retryAnalysisWorkflow"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/analysis-workflows/{id}/run-again": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run a settled analysis workflow again as a new workflow
+         * @description Launches a NEW workflow from the settled one’s parameters under the caller’s current authorization, recording relaunchedFrom, and anchors it in the launching conversation named by chatId so its settlement is delivered there. The old workflow is never written. Only for a type whose execution support declares runAgain (otherwise 409 not_supported); a workflow already open for the same launch answers 409 run_in_progress with its id — never joined, never duplicated. A conversation the caller may not write in answers 404 before anything is created. Runtime posture: intent write, impersonation restricted (it spends model calls); the billing pre-flight runs before anything is created, and a refusal is the billing refusal envelope. An Idempotency-Key header replays the first answer for the same workflow and action. Org-scoped: a workflow in another workspace answers 404.
+         */
+        post: operations["runAnalysisWorkflowAgain"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/affordances/state": {
         parameters: {
             query?: never;
@@ -7263,6 +7323,34 @@ export interface components {
                     args: {
                         executionId: string;
                     };
+                } | {
+                    /** @constant */
+                    id: "workflow.stop";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.continue";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.retry";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.runAgain";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7361,6 +7449,34 @@ export interface components {
                     args: {
                         executionId: string;
                     };
+                } | {
+                    /** @constant */
+                    id: "workflow.stop";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.continue";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.retry";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.runAgain";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7461,6 +7577,34 @@ export interface components {
                     args: {
                         executionId: string;
                     };
+                } | {
+                    /** @constant */
+                    id: "workflow.stop";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.continue";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.retry";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.runAgain";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7561,6 +7705,34 @@ export interface components {
                     args: {
                         executionId: string;
                     };
+                } | {
+                    /** @constant */
+                    id: "workflow.stop";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.continue";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.retry";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.runAgain";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
                 })[];
             }) | null;
             error?: string;
@@ -7586,10 +7758,44 @@ export interface components {
             /** @enum {string} */
             result: "delivered" | "deferred" | "busy" | "skipped" | "not_settled";
         };
+        WorkflowExecutionStartedResponse: {
+            /** @constant */
+            started: true;
+            /** Format: uuid */
+            workflowId: string;
+            executionEpoch: number;
+            /** @constant */
+            state: "pending";
+        };
+        WorkflowExecutionRefusal: {
+            /** @constant */
+            refused: true;
+            /** @enum {string} */
+            reason: "not_stopped" | "not_failed" | "execution_in_flight" | "not_supported" | "run_in_progress";
+            /** @enum {string} */
+            state: "pending" | "running" | "draining" | "stopped" | "complete" | "failed";
+            /** Format: uuid */
+            workflowId: string;
+            openWorkflowId?: string | null;
+        };
+        WorkflowRunAgainResponse: {
+            /** @constant */
+            launched: true;
+            /** Format: uuid */
+            workflowId: string;
+            /** Format: uuid */
+            relaunchedFrom: string;
+            /** @constant */
+            state: "pending";
+        };
+        RunAnalysisWorkflowAgainRequest: {
+            /** Format: uuid */
+            chatId: string;
+        };
         AffordanceStateResponse: {
             entries: {
                 /** @enum {string} */
-                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "orgStructure.reanalyze" | "hris.resyncDirectory" | "review.open" | "integrations.open" | "hris.connect" | "account.editProfile" | "workspace.openOrgSettings" | "sourceSync.addFile" | "sourceSync.openUpdate" | "orgStructure.openReview" | "chat.open" | "companyMd.openDoc" | "companyMd.openHistory" | "team.open" | "execution.open";
+                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "orgStructure.reanalyze" | "hris.resyncDirectory" | "review.open" | "integrations.open" | "hris.connect" | "account.editProfile" | "workspace.openOrgSettings" | "sourceSync.addFile" | "sourceSync.openUpdate" | "orgStructure.openReview" | "chat.open" | "companyMd.openDoc" | "companyMd.openHistory" | "team.open" | "execution.open" | "workflow.stop" | "workflow.continue" | "workflow.retry" | "workflow.runAgain";
                 /** @enum {string} */
                 policy: "allowed" | "blocked";
                 availability: {
@@ -8763,6 +8969,34 @@ export interface components {
                     args: {
                         executionId: string;
                     };
+                } | {
+                    /** @constant */
+                    id: "workflow.stop";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.continue";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.retry";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "workflow.runAgain";
+                    args: {
+                        /** Format: uuid */
+                        workflowId: string;
+                    };
                 } | {
                     /** @constant */
                     id: "review.open";
@@ -8869,6 +9103,34 @@ export interface components {
                         args: {
                             executionId: string;
                         };
+                    } | {
+                        /** @constant */
+                        id: "workflow.stop";
+                        args: {
+                            /** Format: uuid */
+                            workflowId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "workflow.continue";
+                        args: {
+                            /** Format: uuid */
+                            workflowId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "workflow.retry";
+                        args: {
+                            /** Format: uuid */
+                            workflowId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "workflow.runAgain";
+                        args: {
+                            /** Format: uuid */
+                            workflowId: string;
+                        };
                     } | {
                         /** @constant */
                         id: "review.open";
@@ -14118,6 +14380,145 @@ export interface operations {
             };
         };
     };
+    continueAnalysisWorkflow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Another execution of the same workflow is under way */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowExecutionStartedResponse"];
+                };
+            };
+            /** @description The workflow id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Nothing was started: the reason and the workflow’s authoritative current state */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowExecutionRefusal"];
+                };
+            };
+        };
+    };
+    retryAnalysisWorkflow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Another execution of the same workflow is under way */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowExecutionStartedResponse"];
+                };
+            };
+            /** @description The workflow id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Nothing was started: the reason and the workflow’s authoritative current state */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowExecutionRefusal"];
+                };
+            };
+        };
+    };
+    runAnalysisWorkflowAgain: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RunAnalysisWorkflowAgainRequest"];
+            };
+        };
+        responses: {
+            /** @description A new workflow was launched and anchored in the conversation */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowRunAgainResponse"];
+                };
+            };
+            /** @description The workflow id or the chat id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow, or no such conversation the caller may write in */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Nothing was started: the reason and the workflow’s authoritative current state */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkflowExecutionRefusal"];
+                };
+            };
+        };
+    };
     getAffordanceState: {
         parameters: {
             query: {

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.

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).