@company-semantics/contracts 89.2.0 → 91.0.0

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);
+  });
 });

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

@@ -0,0 +1,65 @@
+/**
+ * The workflow-settlement offer rule and its projection (control ADR
+ * affordance-system; control ADR-CTRL-540).
+ *
+ * `affordancesOfReason` is the ONE place a producer reads the frozen offer for
+ * an ending (the backend's outcome builder calls it). `affordancesOfOutcome` is
+ * the ONE projection every consumer renders from — the settlement message, the
+ * proactive chat and the agent's context alike — so the Review control and the
+ * offered next steps are one list built one way.
+ */
+import type { Affordance, OfferedAffordance } from "../affordances/affordance";
+import {
+  DISCOVER_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+  type WorkflowOutcome,
+  type WorkflowOutcomeOf,
+} from "./outcome";
+import type { WorkflowType } from "./types";
+
+/** Every workflow type's offer table, total over the type union. */
+export const WORKFLOW_AFFORDANCES_OF_REASON = {
+  "source-sync/discover": DISCOVER_AFFORDANCES_OF_REASON,
+  "source-sync/synthesize": SYNTHESIZE_AFFORDANCES_OF_REASON,
+  "org-structure/hris-connect": ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  "org-structure/reanalyze": ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+} as const satisfies {
+  readonly [T in WorkflowType]: Record<
+    WorkflowOutcomeOf<T>["reason"],
+    readonly OfferedAffordance[]
+  >;
+};
+
+/** The frozen offer an ending of one workflow type carries. */
+export function affordancesOfReason<T extends WorkflowType>(
+  workflowType: T,
+  reason: WorkflowOutcomeOf<T>["reason"],
+): readonly OfferedAffordance[] {
+  const table = WORKFLOW_AFFORDANCES_OF_REASON[workflowType] as Record<
+    string,
+    readonly OfferedAffordance[]
+  >;
+  return table[reason as string] ?? [];
+}
+
+/**
+ * Everything an outcome offers, in render order: the frozen offer, then the
+ * `review.open` projected from a `review` disposition. Pure; never persisted.
+ */
+export function affordancesOfOutcome(
+  outcome: WorkflowOutcome,
+): readonly Affordance[] {
+  const { disposition } = outcome;
+  if (disposition.kind !== "review") return [...outcome.affordances];
+  return [
+    ...outcome.affordances,
+    {
+      id: "review.open",
+      args: {
+        requestType: disposition.requestType,
+        requestId: disposition.requestId,
+      },
+    },
+  ];
+}

package/src/workflows/deferred-route.ts

@@ -0,0 +1,240 @@
+/**
+ * Where a settlement goes when there is no launching conversation to write it
+ * into (control ADR-CTRL-540 phase 2; control ADR affordance-system).
+ *
+ * A scheduled rediscovery, an upkeep re-synthesis or a launch nobody docked
+ * into a chat settles with no anchor. Its route is decided per REASON, frozen by
+ * the backend onto the settlement row when it defers, and never re-derived.
+ *
+ * THE DOCTRINE (control docs/proactive-delivery.md): a pushed `explained` chat
+ * is frozen, so it may contain only material that stays non-privileged after
+ * the recipient's authority changes. A settlement told WITHOUT FACTS (its
+ * reason only, `facts: null`) plus its affordance ids qualifies — affordances
+ * are re-gated per viewer at render and executed by the server. An ending whose
+ * telling needs authority-sensitive facts (counts) goes to a `notice` inbox row,
+ * which re-renders under the reader's current authority.
+ *
+ * RULES (pinned by the deferred-route test):
+ * - `explained` only for a `failed` or `abandoned` ending that offers at least
+ *   one affordance. A `produced`, `empty` or `partial` ending is never explained.
+ * - `covered` when a domain kind normally announces that ending. Covering is
+ *   verified, not assumed: the backend checks that the covering occurrence
+ *   exists for this workflow and epoch at route time, and otherwise routes the
+ *   `fallback` notice to the stated audience. Nothing is ever said twice, and
+ *   nothing falls silent because a domain kind declined.
+ * - `silent` only for `stopped_by_user`: the person who stopped it acted.
+ * - Audiences are policies the backend resolves and freezes at emit; an empty
+ *   resolved audience routes silent.
+ */
+import { z } from "zod";
+
+import type {
+  DiscoverOutcomeReason,
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  OrgStructureOutcomeReason,
+  ReanalyzeWorkflowOutcome,
+  SynthesizeOutcomeReason,
+  SynthesizeWorkflowOutcome,
+  WorkflowOutcome,
+  WorkflowOutcomeOf,
+} from "./outcome";
+import type { WorkflowType } from "./types";
+
+/** Who a routed settlement is addressed to; resolved and frozen by the backend. */
+export const SETTLEMENT_AUDIENCE_POLICIES = [
+  /** The person who launched the workflow, while still an active member. */
+  "creator",
+  /** The launcher plus the org owner and admins (who manage integrations). */
+  "creator_and_owner_admins",
+] as const;
+export type SettlementAudiencePolicy =
+  (typeof SETTLEMENT_AUDIENCE_POLICIES)[number];
+
+/**
+ * The proactive kinds that already announce some endings. Literal strings, not
+ * an import: workflows never imports proactive (proactive imports workflows).
+ * The test pins each one as a real PROACTIVE_EVENT_KIND_IDS member.
+ */
+export const SETTLEMENT_COVERING_KINDS = [
+  "sourceSync.review_ready",
+  "sourceSync.docs_updated",
+  "orgStructure.review_ready",
+] as const;
+export type SettlementCoveringKind = (typeof SETTLEMENT_COVERING_KINDS)[number];
+
+/** Why a routed settlement says nothing. Closed. */
+export const SETTLEMENT_SILENT_REASONS = ["stopped_by_person"] as const;
+
+export const DEFERRED_ROUTES = [
+  "explained",
+  "notice",
+  "covered",
+  "silent",
+] as const;
+export type DeferredRouteKind = (typeof DEFERRED_ROUTES)[number];
+
+export const DeferredRouteSchema = z.discriminatedUnion("route", [
+  z
+    .object({
+      route: z.literal("explained"),
+      audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
+    })
+    .strict(),
+  z
+    .object({
+      route: z.literal("notice"),
+      audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
+    })
+    .strict(),
+  z
+    .object({
+      route: z.literal("covered"),
+      by: z.enum(SETTLEMENT_COVERING_KINDS),
+      /**
+       * Covering is not literal on every path (a domain kind may decline: e.g.
+       * sourceSync.review_ready fires on scheduled rediscovery only when new
+       * candidates exist). The backend verifies the covering occurrence exists
+       * for this workflow/epoch at route time; otherwise it routes the notice.
+       */
+      fallback: z.literal("notice"),
+      /** Who the fallback notice is addressed to. */
+      audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
+    })
+    .strict(),
+  z
+    .object({
+      route: z.literal("silent"),
+      why: z.enum(SETTLEMENT_SILENT_REASONS),
+    })
+    .strict(),
+]);
+export type DeferredRoute = z.infer<typeof DeferredRouteSchema>;
+
+const EXPLAINED = {
+  route: "explained",
+  audience: "creator_and_owner_admins",
+} as const;
+const NOTICE_CREATOR = { route: "notice", audience: "creator" } as const;
+const NOTICE_ADMINS = {
+  route: "notice",
+  audience: "creator_and_owner_admins",
+} as const;
+const STOPPED = { route: "silent", why: "stopped_by_person" } as const;
+
+export const DISCOVER_DEFERRED_ROUTE_OF_REASON = {
+  // prettier-ignore
+  candidates_found: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
+  nothing_found: NOTICE_CREATOR,
+  nothing_relevant: NOTICE_CREATOR,
+  budget_exhausted: NOTICE_CREATOR,
+  file_ceiling: NOTICE_CREATOR,
+  stopped_by_user: STOPPED,
+  plan_coverage_refused: NOTICE_ADMINS,
+  billing_refused: EXPLAINED,
+  drive_auth: EXPLAINED,
+  drive_unavailable: EXPLAINED,
+  no_connection: EXPLAINED,
+  source_sync_off: EXPLAINED,
+  internal_error: EXPLAINED,
+  abandoned: EXPLAINED,
+  unrecognized_terminal_state: NOTICE_ADMINS,
+} as const satisfies Record<DiscoverOutcomeReason, DeferredRoute>;
+
+export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
+  // prettier-ignore
+  updates_ready: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
+  // prettier-ignore
+  updates_applied: { route: "covered", by: "sourceSync.docs_updated", fallback: "notice", audience: "creator" },
+  stopped_by_user: STOPPED,
+  paused_billing: EXPLAINED,
+  synthesis_incomplete: NOTICE_ADMINS,
+  approval_mismatch: NOTICE_ADMINS,
+  landing_refused: NOTICE_ADMINS,
+  standing_order_refused: NOTICE_ADMINS,
+  no_connection: EXPLAINED,
+  source_sync_off: EXPLAINED,
+  internal_error: NOTICE_ADMINS,
+  abandoned: NOTICE_ADMINS,
+  unrecognized_terminal_state: NOTICE_ADMINS,
+} as const satisfies Record<SynthesizeOutcomeReason, DeferredRoute>;
+
+export const ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON = {
+  // prettier-ignore
+  proposal_ready: { route: "covered", by: "orgStructure.review_ready", fallback: "notice", audience: "creator" },
+  directory_synced: NOTICE_CREATOR,
+  analysis_already_running: NOTICE_CREATOR,
+  proposal_blocked: NOTICE_ADMINS,
+  // `empty`, so never explained, even though it offers a directory sync.
+  no_sync_run: NOTICE_ADMINS,
+  no_persons: NOTICE_CREATOR,
+  reporting_not_keyed: NOTICE_CREATOR,
+  stopped_by_user: STOPPED,
+  sync_failed: EXPLAINED,
+  snapshot_too_large: NOTICE_ADMINS,
+  model_failed: EXPLAINED,
+  run_too_large: NOTICE_ADMINS,
+  placement_failed: EXPLAINED,
+  internal_error: EXPLAINED,
+  abandoned: EXPLAINED,
+  unrecognized_terminal_state: NOTICE_ADMINS,
+} as const satisfies Record<OrgStructureOutcomeReason, DeferredRoute>;
+
+/** Every workflow type's route table, total over the type union. */
+export const WORKFLOW_DEFERRED_ROUTE_OF_REASON = {
+  "source-sync/discover": DISCOVER_DEFERRED_ROUTE_OF_REASON,
+  "source-sync/synthesize": SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
+  "org-structure/hris-connect": ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
+  "org-structure/reanalyze": ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
+} as const satisfies {
+  readonly [T in WorkflowType]: Record<
+    WorkflowOutcomeOf<T>["reason"],
+    DeferredRoute
+  >;
+};
+
+type ExplainedReasonOf<T> = {
+  [R in keyof T]: T[R] extends { readonly route: "explained" } ? R : never;
+}[keyof T];
+
+export type ExplainedDiscoverReason = ExplainedReasonOf<
+  typeof DISCOVER_DEFERRED_ROUTE_OF_REASON
+>;
+export type ExplainedSynthesizeReason = ExplainedReasonOf<
+  typeof SYNTHESIZE_DEFERRED_ROUTE_OF_REASON
+>;
+export type ExplainedOrgStructureReason = ExplainedReasonOf<
+  typeof ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON
+>;
+
+type FactFree<O, R> = Omit<O, "reason" | "facts"> & {
+  readonly reason: R;
+  readonly facts: null;
+};
+
+/** An outcome a pushed chat may carry: an explained reason, facts stripped. */
+export type ExplainedWorkflowOutcome =
+  | FactFree<DiscoverWorkflowOutcome, ExplainedDiscoverReason>
+  | FactFree<SynthesizeWorkflowOutcome, ExplainedSynthesizeReason>
+  | FactFree<HrisConnectWorkflowOutcome, ExplainedOrgStructureReason>
+  | FactFree<ReanalyzeWorkflowOutcome, ExplainedOrgStructureReason>;
+
+/** The route an outcome takes when it has no launching conversation. */
+export function deferredRouteOf(outcome: WorkflowOutcome): DeferredRoute {
+  const table = WORKFLOW_DEFERRED_ROUTE_OF_REASON[
+    outcome.workflowType
+  ] as Record<string, DeferredRoute>;
+  return table[outcome.reason] as DeferredRoute;
+}
+
+/**
+ * The fact-free outcome a pushed chat may carry, or null when the ending's
+ * route is not `explained`. Stripping facts keeps the outcome schema-valid
+ * (`facts` is nullable) and leaves the frozen affordances untouched.
+ */
+export function toExplainedOutcome(
+  outcome: WorkflowOutcome,
+): ExplainedWorkflowOutcome | null {
+  if (deferredRouteOf(outcome).route !== "explained") return null;
+  return { ...outcome, facts: null } as ExplainedWorkflowOutcome;
+}