@company-semantics/contracts 90.0.0 → 91.0.0

package/src/proactive/templates/index.ts

@@ -31,6 +31,7 @@ import { billingSuspendedComposer } from "./billing-suspended";
 import { morningBriefComposer } from "./morning-brief";
 import { orgBecameSharedComposer } from "./org-became-shared";
 import { sourceSyncReviewReadyComposer } from "./source-sync-review-ready";
+import { workflowNeedsAttentionComposer } from "./workflow-needs-attention";
 
 export const PROACTIVE_CHAT_COMPOSERS = {
   orgBecameShared: orgBecameSharedComposer,
@@ -41,4 +42,5 @@ export const PROACTIVE_CHAT_COMPOSERS = {
   billingSuspended: billingSuspendedComposer,
   billingSubscriptionCanceled: billingSubscriptionCanceledComposer,
   sourceSyncReviewReady: sourceSyncReviewReadyComposer,
+  workflowNeedsAttention: workflowNeedsAttentionComposer,
 } as const satisfies Record<ProactiveChatTemplate, ProactiveChatComposer>;

package/src/proactive/templates/workflow-needs-attention.ts

@@ -0,0 +1,35 @@
+/**
+ * The workflow-needs-attention pushed chat — a background run ended in a
+ * failure a person can act on, while nobody was watching.
+ *
+ * THIS COMPOSER FRAMES; IT DOES NOT NARRATE. The sentence is the backend's
+ * deterministic settlement narration (one owner of settlement wording, already
+ * under the call-to-action ban), passed in as `narration`. The composer adds a
+ * title per workflow type and carries the fact-free outcome so its grounded
+ * affordances render as real controls (control ADR affordance-system). It
+ * offers no next step in words and no chips: a chip only sends a chat prompt,
+ * which is not grounded in a control.
+ *
+ * NO COUNTS (INV-PROACTIVE-CONTENT): the outcome's facts are stripped and the
+ * narration is told from the stripped outcome.
+ */
+import type { WorkflowType } from "../../workflows/types";
+import type { ProactiveChatComposer } from "../composer";
+
+const TITLE_OF_WORKFLOW_TYPE = {
+  "source-sync/discover": "The drive search did not finish",
+  "source-sync/synthesize": "The document update did not finish",
+  "org-structure/hris-connect": "The org structure analysis did not finish",
+  "org-structure/reanalyze": "The org structure analysis did not finish",
+} as const satisfies Record<WorkflowType, string>;
+
+export const workflowNeedsAttentionComposer: ProactiveChatComposer<"workflowNeedsAttention"> =
+  {
+    template: "workflowNeedsAttention",
+    compose: (facts) => ({
+      title: TITLE_OF_WORKFLOW_TYPE[facts.outcome.outcome.workflowType],
+      text: facts.narration,
+      replies: [],
+      outcome: facts.outcome,
+    }),
+  };

package/src/root-exports/README.md

@@ -48,6 +48,7 @@ documented in its owning domain (`src/org/`, `src/chat/`, `src/comments/`, …).
 **Internal domains:**
 
 - `action-items`
+- `affordances`
 - `api`
 - `autotune`
 - `chat`

package/src/root-exports/delivery.ts

@@ -201,6 +201,8 @@ export type {
   ProactiveEventDefinition,
   OrgBecameSharedFacts,
   MorningBriefFacts,
+  ExplainedWorkflowOutcomeData,
+  WorkflowNeedsAttentionFacts,
   ProactiveChatFacts,
   ProactiveChatComposer,
   ProactiveChatMessage,
@@ -219,31 +221,60 @@ export type { WorkflowType } 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
-// once by the backend and frozen. See src/workflows/outcome.ts.
+// once by the backend and frozen. Each ending also freezes the next steps its
+// reason offers (control ADR affordance-system); `affordancesOfOutcome` is the
+// one projection consumers render from. An ending with no launching
+// conversation takes its reason's deferred route (explained | notice | covered
+// | silent). See src/workflows/outcome.ts and src/workflows/deferred-route.ts.
 export {
+  DEFERRED_ROUTES,
+  DISCOVER_AFFORDANCES_OF_REASON,
+  DISCOVER_DEFERRED_ROUTE_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
+  DeferredRouteSchema,
   DiscoverOutcomeFactsSchema,
   DiscoverWorkflowOutcomeSchema,
   HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   OrgStructureOutcomeFactsSchema,
   ReanalyzeWorkflowOutcomeSchema,
+  SETTLEMENT_AUDIENCE_POLICIES,
+  SETTLEMENT_COVERING_KINDS,
+  SETTLEMENT_SILENT_REASONS,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   SynthesizeOutcomeFactsSchema,
   SynthesizeWorkflowOutcomeSchema,
+  WORKFLOW_AFFORDANCES_OF_REASON,
+  WORKFLOW_DEFERRED_ROUTE_OF_REASON,
   WORKFLOW_OUTCOME_KINDS,
   WorkflowOutcomeDispositionSchema,
   WorkflowOutcomeSchema,
+  affordancesOfOutcome,
+  affordancesOfReason,
+  deferredRouteOf,
+  toExplainedOutcome,
 } from "../workflows/index";
 
 export type {
+  DeferredRoute,
+  DeferredRouteKind,
   DiscoverOutcomeFacts,
   DiscoverOutcomeReason,
   DiscoverWorkflowOutcome,
+  ExplainedDiscoverReason,
+  ExplainedOrgStructureReason,
+  ExplainedSynthesizeReason,
+  ExplainedWorkflowOutcome,
   HrisConnectWorkflowOutcome,
   OrgStructureOutcomeFacts,
   OrgStructureOutcomeReason,
   ReanalyzeWorkflowOutcome,
+  SettlementAudiencePolicy,
+  SettlementCoveringKind,
   SynthesizeOutcomeFacts,
   SynthesizeOutcomeReason,
   SynthesizeWorkflowOutcome,
@@ -252,3 +283,40 @@ export type {
   WorkflowOutcomeKind,
   WorkflowOutcomeOf,
 } from "../workflows/index";
+
+// Affordances (control ADR affordance-system): the closed vocabulary of next
+// steps the product may offer, as INSTANCES ({ id, args? }), with each one's
+// binding kind and live availability condition. An affordance is offered only
+// by a domain-owned deterministic rule; existing here never offers it. See
+// src/affordances/README.md.
+export {
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_ARGS,
+  AFFORDANCE_BINDING_KINDS,
+  AFFORDANCE_BINDING_KIND_OF,
+  AFFORDANCE_IDS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  AffordanceAvailabilityIdSchema,
+  AffordanceAvailabilitySchema,
+  AffordanceIdSchema,
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+  NO_ARG_AFFORDANCE_IDS,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  ReviewOpenArgsSchema,
+  sameAffordances,
+} from "../affordances/index";
+
+export type {
+  Affordance,
+  AffordanceArgs,
+  AffordanceAvailability,
+  AffordanceAvailabilityId,
+  AffordanceBindingKind,
+  AffordanceId,
+  AffordanceUnavailableReason,
+  OfferedAffordance,
+  ProjectedAffordanceId,
+} from "../affordances/index";

package/src/user-notifications/README.md

@@ -78,6 +78,14 @@ that renders them alongside action items at the top of `/me/work`.
 - **`proactive.org_structure_review_ready` is the org structure notice's row.**
   It arrives UNREAD, because a `notice` has no other surface to hold the badge.
   The renderer links it to the place the review is opened.
+- **`proactive.workflow_needs_attention` and `proactive.workflow_finished` are
+  the workflow settlement rows** (control ADR-CTRL-540 phase 2), the durable
+  twins of `workflow.needs_attention` (explained, so born READ) and
+  `workflow.finished` (a notice, so UNREAD). A row holds identifiers only — the
+  workflow id and type; a finished run's counts render at read time under the
+  reader's authority. Both supersede per workflow type (condition field
+  `workflowType`, renewing): one active row per workflow type per reader, and a
+  newer settlement is news again.
 - **This is a mention row, not a chat-unread model.** Being named is a discrete
   fact you come back to; "this chat has new messages" is not modeled here or
   anywhere, and the proactive `unread` flag on a chat summary stays a one-time

package/src/user-notifications/kinds.ts

@@ -229,6 +229,19 @@ export const USER_NOTIFICATION_KINDS = [
    * where the review is opened.
    */
   "proactive.org_structure_review_ready",
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2)
+  // ===========================================================================
+  //
+  // The durable twins of `workflow.needs_attention` / `workflow.finished`,
+  // rendered by `src/proactive/` in the backend, DISTINCT from the kind strings.
+  // A row holds identifiers only (the workflow id and type); a `notice` row's
+  // counts render at read time under the reader's authority.
+  /** A failure a person can act on. Explained: the chat holds the badge, born read. */
+  "proactive.workflow_needs_attention",
+  /** A finished run nobody watched. A notice: this row IS the attention, unread. */
+  "proactive.workflow_finished",
 ] as const;
 
 export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];

package/src/user-notifications/lifecycle-registry.ts

@@ -32,6 +32,14 @@ const STANDING = {
   resolution: RESOLVED_FOR_ALL,
   retention: "standard",
 } as const;
+/** One active row per workflow type per reader; a newer settlement renews it. */
+const PER_WORKFLOW_TYPE = {
+  condition: { scope: "fields", fields: ["workflowType"] },
+  supersedes: true,
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+} as const;
 
 /**
  * Every kind's lifecycle. Annotated (not `satisfies`) so a missing kind and an
@@ -120,4 +128,6 @@ export const NOTIFICATION_LIFECYCLE: Readonly<Record<UserNotificationKind, Notif
     resolution: RESOLVED_FOR_ALL,
     retention: "standard",
   },
+  "proactive.workflow_needs_attention": PER_WORKFLOW_TYPE,
+  "proactive.workflow_finished": PER_WORKFLOW_TYPE,
 };

package/src/workflows/README.md

@@ -40,6 +40,30 @@ so every producer, validator and renderer agrees on it.
   adding its outcome member; the union must cover every registered type.
 - **`unknown` is a safety valve, not a status.** It names an unrecognized
   terminal transition, never a workflow whose state could not be read.
+- **The offer is a function of reason** (control ADR affordance-system). Every
+  outcome carries a REQUIRED `affordances` list — the ordered next steps the
+  ending offers — fixed by its reason's per-type `*_AFFORDANCES_OF_REASON`
+  table and frozen with the outcome. The tables are total (an empty list is an
+  explicit decision) and the schema refuses any other list, a missing key and
+  more than `MAX_OFFERED_AFFORDANCES`. Producers read the offer through
+  `affordancesOfReason` only.
+- **`review.open` is projected, never stored.** It is derived from a `review`
+  disposition; an offer that contains it is refused. `affordancesOfOutcome` is
+  the single projection every consumer renders from: the frozen offer, then
+  `review.open` when the disposition is `review`.
+- **A deferred settlement's route is a function of reason** (control
+  ADR-CTRL-540 phase 2). An ending with no launching conversation takes its
+  reason's entry in the total per-type `*_DEFERRED_ROUTE_OF_REASON` table:
+  `explained` only for a `failed` or `abandoned` ending that offers at least one
+  affordance (told fact-free via `toExplainedOutcome`), `notice` for anything
+  whose telling needs counts, `covered` when a domain proactive kind normally
+  announces it (always with a `fallback: "notice"` and an audience, because
+  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.
+- **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
 
@@ -47,8 +71,20 @@ so every producer, validator and renderer agrees on it.
 - `WorkflowOutcomeSchema` / `WorkflowOutcome` and the per-type member schemas,
   reason tables, fact schemas and `WorkflowOutcomeDispositionSchema`
   (`outcome.ts`).
+- `DISCOVER_AFFORDANCES_OF_REASON`, `SYNTHESIZE_AFFORDANCES_OF_REASON`,
+  `ORG_STRUCTURE_AFFORDANCES_OF_REASON` (`outcome.ts`).
+- `WORKFLOW_AFFORDANCES_OF_REASON`, `affordancesOfReason`,
+  `affordancesOfOutcome` (`affordances-of-outcome.ts`).
+- `SETTLEMENT_AUDIENCE_POLICIES`, `SETTLEMENT_COVERING_KINDS`,
+  `SETTLEMENT_SILENT_REASONS`, `DEFERRED_ROUTES`, `DeferredRouteSchema` /
+  `DeferredRoute`, the `*_DEFERRED_ROUTE_OF_REASON` tables,
+  `WORKFLOW_DEFERRED_ROUTE_OF_REASON`, `ExplainedWorkflowOutcome` and its
+  `Explained*Reason` types, `deferredRouteOf`, `toExplainedOutcome`
+  (`deferred-route.ts`).
 
 ## Dependencies
 
-`zod` (outcome schemas) and `../input-requests/types` (the review
-disposition's request type). Otherwise pure vocabulary data and one guard.
+`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
+guard and pure helpers.

package/src/workflows/__tests__/README.md

@@ -17,7 +17,24 @@ wire value against it.
   (compile-time), each reason table's kinds are valid, the schema accepts a
   well-formed member and refuses a kind that does not match its reason, a
   review disposition on a non-produced outcome, a reason from another type,
-  and extra keys (the facts stay closed).
+  and extra keys (the facts stay closed). Every reason has an explicit offer
+  of offerable affordances, and the schema refuses an offer that differs from
+  its reason's table, a missing `affordances` key, `review.open` inside a
+  frozen offer and more than `MAX_OFFERED_AFFORDANCES` entries.
+
+- `affordances-of-outcome.test.ts` — `affordancesOfOutcome` projects
+  `review.open` after the frozen offer for a `review` disposition and nothing
+  extra for `narrate`; `affordancesOfReason` returns each workflow type's
+  table entry (both org-structure types share one table); every projected
+  list is a valid `Affordance` list.
+
+- `deferred-route.test.ts` — every reason of every workflow type has a valid
+  deferred route; `explained` only for a `failed`/`abandoned` ending with a
+  non-empty offer; `produced`/`empty`/`partial` never explained; `silent` ⇔
+  `stopped_by_user`; every covering kind is a real proactive kind and every
+  covered route falls back to a notice with an audience; `toExplainedOutcome`
+  strips facts and stays schema-valid; and no `src/workflows/*.ts` file
+  imports from proactive.
 
 ## Invariants
 
@@ -33,4 +50,6 @@ None — test-only.
 
 ## Dependencies
 
-`vitest` and `../types`.
+`vitest`, `node:fs`, `../types`, `../outcome`, `../affordances-of-outcome`,
+`../deferred-route`, `../../affordances/affordance` and
+`../../proactive/kinds` (test-only: pins the covering kinds).

package/src/workflows/__tests__/affordances-of-outcome.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import { AffordanceSchema } from "../../affordances/affordance";
+import {
+  WORKFLOW_AFFORDANCES_OF_REASON,
+  affordancesOfOutcome,
+  affordancesOfReason,
+} from "../affordances-of-outcome";
+import {
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  WorkflowOutcomeSchema,
+  type WorkflowOutcome,
+} from "../outcome";
+import { ANALYSIS_WORKFLOW_TYPES } from "../types";
+
+const review = {
+  kind: "review",
+  requestType: "source-sync/candidates",
+  requestId: "set-1",
+} as const;
+
+const produced: WorkflowOutcome = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 0,
+  kind: "produced",
+  reason: "candidates_found",
+  facts: null,
+  disposition: review,
+  affordances: [],
+};
+
+const partial: WorkflowOutcome = {
+  ...produced,
+  kind: "partial",
+  reason: "budget_exhausted",
+};
+
+const driveAuth: WorkflowOutcome = {
+  ...produced,
+  kind: "failed",
+  reason: "drive_auth",
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "integrations.connectGoogleDrive" }],
+};
+
+const REVIEW_OPEN = {
+  id: "review.open",
+  args: { requestType: "source-sync/candidates", requestId: "set-1" },
+};
+
+describe("affordancesOfOutcome", () => {
+  it("fixtures are valid outcomes", () => {
+    for (const outcome of [produced, partial, driveAuth]) {
+      expect(WorkflowOutcomeSchema.safeParse(outcome).success).toBe(true);
+    }
+  });
+
+  it("projects review.open from a review disposition, after the frozen offer", () => {
+    expect(affordancesOfOutcome(produced)).toEqual([REVIEW_OPEN]);
+    expect(affordancesOfOutcome(partial)).toEqual([
+      ...partial.affordances,
+      REVIEW_OPEN,
+    ]);
+  });
+
+  it("projects nothing extra from a narrate disposition", () => {
+    expect(affordancesOfOutcome(driveAuth)).toEqual([
+      { id: "integrations.connectGoogleDrive" },
+    ]);
+  });
+
+  it("affordancesOfReason returns the table entry for each workflow type", () => {
+    for (const workflowType of ANALYSIS_WORKFLOW_TYPES) {
+      const table: Record<string, unknown> =
+        WORKFLOW_AFFORDANCES_OF_REASON[workflowType];
+      for (const [reason, offer] of Object.entries(table)) {
+        expect(affordancesOfReason(workflowType, reason as never)).toEqual(
+          offer,
+        );
+      }
+    }
+    // Both org-structure types read the one shared table.
+    expect(WORKFLOW_AFFORDANCES_OF_REASON["org-structure/hris-connect"]).toBe(
+      ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+    );
+    expect(WORKFLOW_AFFORDANCES_OF_REASON["org-structure/reanalyze"]).toBe(
+      ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+    );
+  });
+
+  it("every projected list is a valid Affordance list", () => {
+    for (const outcome of [produced, driveAuth]) {
+      expect(
+        AffordanceSchema.array().safeParse(affordancesOfOutcome(outcome))
+          .success,
+      ).toBe(true);
+    }
+  });
+});

package/src/workflows/__tests__/deferred-route.test.ts

@@ -0,0 +1,168 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { PROACTIVE_EVENT_KIND_IDS } from "../../proactive/kinds";
+import {
+  DISCOVER_DEFERRED_ROUTE_OF_REASON,
+  DeferredRouteSchema,
+  ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
+  SETTLEMENT_AUDIENCE_POLICIES,
+  SETTLEMENT_COVERING_KINDS,
+  SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
+  deferredRouteOf,
+  toExplainedOutcome,
+  type DeferredRoute,
+} from "../deferred-route";
+import {
+  DISCOVER_AFFORDANCES_OF_REASON,
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  WorkflowOutcomeSchema,
+  type WorkflowOutcome,
+} from "../outcome";
+
+// (kind table, offer table, route table) per outcome family. Built here rather
+// than exported so the rules stay pinned without widening the public surface.
+const TABLES: ReadonlyArray<
+  readonly [
+    Record<string, string>,
+    Record<string, readonly unknown[]>,
+    Record<string, DeferredRoute>,
+  ]
+> = [
+  [
+    DISCOVER_OUTCOME_KIND_OF_REASON,
+    DISCOVER_AFFORDANCES_OF_REASON,
+    DISCOVER_DEFERRED_ROUTE_OF_REASON,
+  ],
+  [
+    SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+    SYNTHESIZE_AFFORDANCES_OF_REASON,
+    SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
+  ],
+  [
+    ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+    ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+    ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
+  ],
+];
+
+const discoverFacts = {
+  probesTotal: 12,
+  probesDone: 3,
+  filesSeen: 0,
+  filesShown: 0,
+  filesHidden: 0,
+  filesDropped: 0,
+  coveragePercent: 25,
+};
+
+const driveAuth = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 2,
+  kind: "failed",
+  reason: "drive_auth",
+  facts: discoverFacts,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "integrations.connectGoogleDrive" }],
+} as const satisfies WorkflowOutcome;
+
+const nothingFound = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 0,
+  kind: "empty",
+  reason: "nothing_found",
+  facts: discoverFacts,
+  disposition: { kind: "narrate" },
+  affordances: [],
+} as const satisfies WorkflowOutcome;
+
+describe("deferred settlement routes", () => {
+  it("every reason of every workflow type has a deferred route", () => {
+    for (const [kinds, , routes] of TABLES) {
+      expect(Object.keys(routes).sort()).toEqual(Object.keys(kinds).sort());
+      for (const route of Object.values(routes)) {
+        expect(DeferredRouteSchema.safeParse(route).success).toBe(true);
+      }
+    }
+  });
+
+  it("an explained route is a fact-free failure that offers at least one affordance", () => {
+    for (const [kinds, offers, routes] of TABLES) {
+      for (const [reason, route] of Object.entries(routes)) {
+        if (route.route !== "explained") continue;
+        expect(["failed", "abandoned"]).toContain(kinds[reason]);
+        expect(offers[reason]?.length ?? 0).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("a produced, empty or partial ending is never explained", () => {
+    for (const [kinds, , routes] of TABLES) {
+      for (const [reason, kind] of Object.entries(kinds)) {
+        if (!["produced", "empty", "partial"].includes(kind)) continue;
+        expect(["notice", "covered"]).toContain(routes[reason]?.route);
+      }
+    }
+  });
+
+  it("silent is reserved for a person stopping the run", () => {
+    for (const [, , routes] of TABLES) {
+      for (const [reason, route] of Object.entries(routes)) {
+        expect(route.route === "silent").toBe(reason === "stopped_by_user");
+      }
+    }
+  });
+
+  it("covered names a real proactive kind", () => {
+    for (const kind of SETTLEMENT_COVERING_KINDS) {
+      expect(PROACTIVE_EVENT_KIND_IDS).toContain(kind);
+    }
+  });
+
+  it("a covered route falls back to a notice with an audience", () => {
+    let covered = 0;
+    for (const [, , routes] of TABLES) {
+      for (const route of Object.values(routes)) {
+        if (route.route !== "covered") continue;
+        covered += 1;
+        expect(route.fallback).toBe("notice");
+        expect(SETTLEMENT_AUDIENCE_POLICIES).toContain(route.audience);
+      }
+    }
+    expect(covered).toBeGreaterThan(0);
+    const by = "sourceSync.review_ready";
+    for (const partial of [
+      { route: "covered", by },
+      { route: "covered", by, fallback: "notice" },
+      { route: "covered", by, audience: "creator" },
+    ]) {
+      expect(DeferredRouteSchema.safeParse(partial).success).toBe(false);
+    }
+  });
+
+  it("toExplainedOutcome strips facts and returns null for a route that is not explained", () => {
+    expect(deferredRouteOf(driveAuth).route).toBe("explained");
+    const explained = toExplainedOutcome(driveAuth);
+    expect(explained).toEqual({ ...driveAuth, facts: null });
+    expect(explained?.affordances).toEqual(driveAuth.affordances);
+    expect(WorkflowOutcomeSchema.safeParse(explained).success).toBe(true);
+    expect(toExplainedOutcome(nothingFound)).toBeNull();
+  });
+
+  it("the workflow module imports nothing from proactive", () => {
+    const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const sources = readdirSync(dir).filter((f) => f.endsWith(".ts"));
+    expect(sources.length).toBeGreaterThan(0);
+    for (const file of sources) {
+      const text = readFileSync(join(dir, file), "utf8");
+      expect(text).not.toMatch(/from\s+["']\.\.\/proactive/);
+    }
+  });
+});

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

@@ -1,9 +1,16 @@
 import { describe, expect, it } from "vitest";
 
+import {
+  MAX_OFFERED_AFFORDANCES,
+  OfferedAffordanceSchema,
+} from "../../affordances/affordance";
 import type { WorkflowType } from "../types";
 import {
+  DISCOVER_AFFORDANCES_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   WORKFLOW_OUTCOME_KINDS,
   WorkflowOutcomeSchema,
@@ -41,6 +48,7 @@ const empty = {
   reason: "nothing_found",
   facts: discoverFacts,
   disposition: { kind: "narrate" },
+  affordances: [],
 } as const;
 
 describe("WorkflowOutcome", () => {
@@ -73,6 +81,7 @@ describe("WorkflowOutcome", () => {
       kind: "abandoned",
       reason: "abandoned",
       facts: null,
+      affordances: [{ id: "sourceSync.findFiles" }],
     };
     expect(WorkflowOutcomeSchema.safeParse(abandoned).success).toBe(true);
   });
@@ -127,4 +136,61 @@ describe("WorkflowOutcome", () => {
       }).success,
     ).toBe(false);
   });
+
+  it("every reason has an explicit offer, and every offer names an offerable affordance", () => {
+    for (const [kinds, offers] of [
+      [DISCOVER_OUTCOME_KIND_OF_REASON, DISCOVER_AFFORDANCES_OF_REASON],
+      [SYNTHESIZE_OUTCOME_KIND_OF_REASON, SYNTHESIZE_AFFORDANCES_OF_REASON],
+      [
+        ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+        ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+      ],
+    ] as const) {
+      expect(Object.keys(offers).sort()).toEqual(Object.keys(kinds).sort());
+      for (const offer of Object.values(offers)) {
+        for (const affordance of offer) {
+          expect(OfferedAffordanceSchema.safeParse(affordance).success).toBe(
+            true,
+          );
+        }
+      }
+    }
+  });
+
+  it("refuses an offer that differs from its reason's table", () => {
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...empty,
+        affordances: [{ id: "sourceSync.findFiles" }],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a missing affordances key", () => {
+    const { affordances: _omitted, ...withoutOffer } = empty;
+    expect(WorkflowOutcomeSchema.safeParse(withoutOffer).success).toBe(false);
+  });
+
+  it("refuses review.open inside a frozen offer", () => {
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...empty,
+        affordances: [
+          {
+            id: "review.open",
+            args: { requestType: "source-sync/candidates", requestId: "s" },
+          },
+        ],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses more than MAX_OFFERED_AFFORDANCES offers", () => {
+    const many = Array.from({ length: MAX_OFFERED_AFFORDANCES + 1 }, () => ({
+      id: "billing.open",
+    }));
+    expect(
+      WorkflowOutcomeSchema.safeParse({ ...empty, affordances: many }).success,
+    ).toBe(false);
+  });
 });