@company-semantics/contracts 95.0.0 → 97.0.0

package/package.json

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

package/src/affordances/README.md

@@ -52,6 +52,14 @@ only the binding KIND.
   below). An action on one thing names it by its id, never by a URL — the
   binding owns the route. None reads a live availability condition yet; adding
   one is an append.
+- **The execution-actions wave follows `execution.open`** (PRD-01153). Four
+  ids act on one analysis workflow's run: `workflow.stop`, `workflow.continue`,
+  `workflow.retry`, `workflow.runAgain` (see
+  [the execution-actions wave](#the-execution-actions-wave) below). They are
+  offered, never projected, and only by the workflow execution offer table in
+  `src/workflows/`, which decides from the workflow's state, so none reads a
+  live availability condition. The wave adds no availability id, unavailable
+  reason or no-affordance reason.
 - **Reverse coverage is exactly one of two things.** Every capability a person
   can act on declares `{ affordance }` or `{ noAffordance }` with a reason from
   the closed `NO_AFFORDANCE_REASONS` (`readOnly`, `inlineControl`,
@@ -89,13 +97,28 @@ id with no arguments has no `args` key. The binding kind comes from
 
 Every argument is a non-empty string and every args object is strict.
 
+## The execution-actions wave
+
+The four ids appended after `execution.open` (PRD-01153), in catalog order.
+All four share one strict args schema, a uuid because the backend route param
+it binds to is one; all four are `command`s and read no live availability
+condition (`null` in `AFFORDANCE_AVAILABILITY_OF`).
+
+| Id                  | Args (schema)                                          | Binding kind |
+| ------------------- | ------------------------------------------------------ | ------------ |
+| `workflow.stop`     | `{ workflowId }` (`WorkflowExecutionArgsSchema`, uuid) | `command`    |
+| `workflow.continue` | `{ workflowId }` (`WorkflowExecutionArgsSchema`, uuid) | `command`    |
+| `workflow.retry`    | `{ workflowId }` (`WorkflowExecutionArgsSchema`, uuid) | `command`    |
+| `workflow.runAgain` | `{ workflowId }` (`WorkflowExecutionArgsSchema`, uuid) | `command`    |
+
 ## Public API
 
 - `AFFORDANCE_IDS`, `AffordanceId`, `AffordanceIdSchema` (`ids.ts`).
 - `AFFORDANCE_ARGS`, `NO_ARG_AFFORDANCE_IDS`, `ReviewOpenArgsSchema`,
   `SourceSyncOpenUpdateArgsSchema`, `OrgStructureOpenReviewArgsSchema`,
   `ChatOpenArgsSchema`, `CompanyMdDocArgsSchema`, `TeamOpenArgsSchema`,
-  `ExecutionOpenArgsSchema`, `AffordanceArgs` (`args.ts`).
+  `ExecutionOpenArgsSchema`, `WorkflowExecutionArgsSchema`, `AffordanceArgs`
+  (`args.ts`).
 - `AFFORDANCE_BINDING_KINDS`, `AFFORDANCE_AVAILABILITY_IDS`,
   `AffordanceAvailabilityIdSchema`, `AFFORDANCE_UNAVAILABLE_REASONS`,
   `AffordanceAvailabilitySchema` and their types (`availability.ts`).

package/src/affordances/__tests__/README.md

@@ -21,6 +21,12 @@ Locks the affordance vocabulary and the shape of an affordance instance.
   no policy field, the error envelope and billing refusal part carry
   affordances only when non-empty, and every new name is reachable from the
   package root.
+- `workflow-affordances.test.ts` — pins the four execution ids (PRD-01153:
+  `workflow.stop`, `workflow.continue`, `workflow.retry`, `workflow.runAgain`)
+  appended after `execution.open`; proves each is an offered (never projected)
+  `command` with null availability that takes the shared
+  `WorkflowExecutionArgsSchema` (a uuid `workflowId`, strict), and that the wave
+  adds no availability id, unavailable reason or no-affordance reason.
 
 ## Invariants
 

package/src/affordances/__tests__/affordances.test.ts

@@ -32,7 +32,7 @@ const schemaMatchesType: Equals<
 > = true;
 
 describe("affordance vocabulary", () => {
-  it("names the nineteen affordances, in order", () => {
+  it("names the twenty-three affordances, in order", () => {
     expect(AFFORDANCE_IDS).toEqual([
       "sourceSync.findFiles",
       "integrations.connectGoogleDrive",
@@ -53,6 +53,10 @@ describe("affordance vocabulary", () => {
       "companyMd.openHistory",
       "team.open",
       "execution.open",
+      "workflow.stop",
+      "workflow.continue",
+      "workflow.retry",
+      "workflow.runAgain",
     ]);
     expect(schemaMatchesType).toBe(true);
   });
@@ -252,6 +256,7 @@ describe("affordance vocabulary", () => {
       "OfferedAffordanceSchema",
       "PROJECTED_AFFORDANCE_IDS",
       "ReviewOpenArgsSchema",
+      "WorkflowExecutionArgsSchema",
       "sameAffordances",
     ] as const) {
       expect((root as Record<string, unknown>)[name], name).toBeDefined();

package/src/affordances/__tests__/catalog-wave.test.ts

@@ -47,8 +47,8 @@ const TARGET_ARG = {
 
 describe("affordance catalog wave", () => {
   it("appends the twelve burn-down ids after the original seven, in order", () => {
-    expect(AFFORDANCE_IDS.slice(7)).toEqual(Object.keys(WAVE));
-    expect(AFFORDANCE_IDS).toHaveLength(19);
+    expect(AFFORDANCE_IDS.slice(7, 19)).toEqual(Object.keys(WAVE));
+    expect(AFFORDANCE_IDS).toHaveLength(23);
   });
 
   it("every new id has the locked binding kind", () => {

package/src/affordances/__tests__/workflow-affordances.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import {
+  AFFORDANCE_ARGS,
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_BINDING_KIND_OF,
+  AFFORDANCE_IDS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  NO_AFFORDANCE_REASONS,
+  NO_ARG_AFFORDANCE_IDS,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  WorkflowExecutionArgsSchema,
+} from "../index";
+
+// The execution-actions wave (PRD-01153): exactly these ids, appended after
+// execution.open, all bound to a backend command.
+const EXECUTION_IDS = [
+  "workflow.stop",
+  "workflow.continue",
+  "workflow.retry",
+  "workflow.runAgain",
+] as const;
+
+const WORKFLOW_ID = "3f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b";
+
+describe("workflow execution affordance ids", () => {
+  it("appends the four execution ids after execution.open, in order", () => {
+    expect(AFFORDANCE_IDS.indexOf("execution.open")).toBe(18);
+    expect(AFFORDANCE_IDS.slice(19)).toEqual([...EXECUTION_IDS]);
+  });
+
+  it("every execution id is a command that reads no live availability", () => {
+    for (const id of EXECUTION_IDS) {
+      expect(AFFORDANCE_BINDING_KIND_OF[id], id).toBe("command");
+      expect(AFFORDANCE_AVAILABILITY_OF[id], id).toBeNull();
+    }
+  });
+
+  it("every execution id takes the shared { workflowId } args", () => {
+    for (const id of EXECUTION_IDS) {
+      expect(AFFORDANCE_ARGS[id], id).toBe(WorkflowExecutionArgsSchema);
+      expect(NO_ARG_AFFORDANCE_IDS as readonly string[]).not.toContain(id);
+    }
+  });
+
+  // An instance must carry a uuid workflowId and nothing else.
+  it("workflow execution affordances require a workflowId", () => {
+    for (const id of EXECUTION_IDS) {
+      expect(
+        OfferedAffordanceSchema.safeParse({
+          id,
+          args: { workflowId: WORKFLOW_ID },
+        }).success,
+        id,
+      ).toBe(true);
+      expect(OfferedAffordanceSchema.safeParse({ id }).success, id).toBe(false);
+      expect(
+        OfferedAffordanceSchema.safeParse({ id, args: {} }).success,
+        id,
+      ).toBe(false);
+      expect(
+        OfferedAffordanceSchema.safeParse({
+          id,
+          args: { workflowId: "wf-1" },
+        }).success,
+        id,
+      ).toBe(false);
+      expect(
+        OfferedAffordanceSchema.safeParse({
+          id,
+          args: { workflowId: WORKFLOW_ID, chatId: "c1" },
+        }).success,
+        id,
+      ).toBe(false);
+    }
+  });
+
+  it("execution ids are offered, never projected", () => {
+    for (const id of EXECUTION_IDS) {
+      expect(PROJECTED_AFFORDANCE_IDS as readonly string[]).not.toContain(id);
+    }
+  });
+
+  it("adds no availability id, unavailable reason or no-affordance reason", () => {
+    expect(AFFORDANCE_AVAILABILITY_IDS).toHaveLength(4);
+    expect(AFFORDANCE_UNAVAILABLE_REASONS).toHaveLength(4);
+    expect(NO_AFFORDANCE_REASONS).toHaveLength(5);
+  });
+
+  it("the args schema converts to JSON Schema", () => {
+    expect(() =>
+      z.toJSONSchema(WorkflowExecutionArgsSchema, { io: "input" }),
+    ).not.toThrow();
+  });
+});

package/src/affordances/affordance.ts

@@ -22,6 +22,7 @@ import {
   ReviewOpenArgsSchema,
   SourceSyncOpenUpdateArgsSchema,
   TeamOpenArgsSchema,
+  WorkflowExecutionArgsSchema,
   type AffordanceArgs,
 } from "./args";
 import type {
@@ -77,6 +78,10 @@ const OFFERED_MEMBERS = [
   withArgs("companyMd.openHistory", CompanyMdDocArgsSchema),
   withArgs("team.open", TeamOpenArgsSchema),
   withArgs("execution.open", ExecutionOpenArgsSchema),
+  withArgs("workflow.stop", WorkflowExecutionArgsSchema),
+  withArgs("workflow.continue", WorkflowExecutionArgsSchema),
+  withArgs("workflow.retry", WorkflowExecutionArgsSchema),
+  withArgs("workflow.runAgain", WorkflowExecutionArgsSchema),
 ] as const;
 
 /** Every affordance instance, validated per id. */
@@ -112,6 +117,10 @@ export const AFFORDANCE_BINDING_KIND_OF = {
   "companyMd.openHistory": "navigate",
   "team.open": "navigate",
   "execution.open": "navigate",
+  "workflow.stop": "command",
+  "workflow.continue": "command",
+  "workflow.retry": "command",
+  "workflow.runAgain": "command",
 } as const satisfies Record<AffordanceId, AffordanceBindingKind>;
 
 /** The live condition each affordance's availability is read from, if any. */
@@ -140,6 +149,12 @@ export const AFFORDANCE_AVAILABILITY_OF = {
   "companyMd.openHistory": null,
   "team.open": null,
   "execution.open": null,
+  // The execution offer table (executionAffordancesFor in ../workflows)
+  // already decides from the workflow's state, so there is nothing to read.
+  "workflow.stop": null,
+  "workflow.continue": null,
+  "workflow.retry": null,
+  "workflow.runAgain": null,
 } as const satisfies Record<AffordanceId, AffordanceAvailabilityId | null>;
 
 /**

package/src/affordances/args.ts

@@ -48,6 +48,15 @@ export const ExecutionOpenArgsSchema = z
   .object({ executionId: z.string().min(1) })
   .strict();
 
+/**
+ * `workflow.stop` / `workflow.continue` / `workflow.retry` /
+ * `workflow.runAgain`: which analysis workflow. A uuid, because the backend
+ * route param it binds to is one.
+ */
+export const WorkflowExecutionArgsSchema = z
+  .object({ workflowId: z.string().uuid() })
+  .strict();
+
 /**
  * Argument schemas, ONLY for ids that take arguments. An id that takes none is
  * listed in NO_ARG_AFFORDANCE_IDS and its instance OMITS `args` entirely: there
@@ -65,6 +74,10 @@ export const AFFORDANCE_ARGS = {
   "companyMd.openHistory": CompanyMdDocArgsSchema,
   "team.open": TeamOpenArgsSchema,
   "execution.open": ExecutionOpenArgsSchema,
+  "workflow.stop": WorkflowExecutionArgsSchema,
+  "workflow.continue": WorkflowExecutionArgsSchema,
+  "workflow.retry": WorkflowExecutionArgsSchema,
+  "workflow.runAgain": WorkflowExecutionArgsSchema,
 } as const;
 
 /** The ids whose instances carry no `args` key. */

package/src/affordances/ids.ts

@@ -66,6 +66,20 @@ export const AFFORDANCE_IDS = [
   "team.open",
   /** Open one execution's detail (the target of an execution confirmation). */
   "execution.open",
+  // ---------------------------------------------------------------------------
+  // Execution actions (PRD-01153): what a person may do to one analysis
+  // workflow's run. Offered only by executionAffordancesFor (../workflows),
+  // from the workflow's state and its type's execution support. Appended,
+  // never inserted.
+  // ---------------------------------------------------------------------------
+  /** Stop one running analysis workflow (it drains, then settles stopped). */
+  "workflow.stop",
+  /** Continue one stopped analysis workflow from where it stopped. */
+  "workflow.continue",
+  /** Retry one failed analysis workflow. */
+  "workflow.retry",
+  /** Start a fresh run of one settled analysis workflow (a relaunch). */
+  "workflow.runAgain",
 ] as const;
 
 export type AffordanceId = (typeof AFFORDANCE_IDS)[number];

package/src/affordances/index.ts

@@ -14,6 +14,7 @@ export {
   ReviewOpenArgsSchema,
   SourceSyncOpenUpdateArgsSchema,
   TeamOpenArgsSchema,
+  WorkflowExecutionArgsSchema,
 } from "./args";
 export type { AffordanceArgs } from "./args";
 export {

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 = 'd4db95eeefb4' as const;
-export const SPEC_HASH_FULL = 'd4db95eeefb4bf7a97541fcefdcb90c1804e1e39508fe0b98e6389ce001a6f16' as const;
+export const SPEC_HASH = 'f571d3d78c72' as const;
+export const SPEC_HASH_FULL = 'f571d3d78c720d7ad11592b2d490a723c48c539d162c41a6dd77f67bb6ad922f' as const;