@company-semantics/contracts 90.0.0 → 91.1.0

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

@@ -0,0 +1,64 @@
+/**
+ * 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 type { WorkflowOutcome, WorkflowOutcomeOf } from "./outcome";
+import {
+  DISCOVER_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+} from "./outcome-reasons";
+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,242 @@
+/**
+ * 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 {
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  ReanalyzeWorkflowOutcome,
+  SynthesizeWorkflowOutcome,
+  WorkflowOutcome,
+  WorkflowOutcomeOf,
+} from "./outcome";
+import type {
+  DiscoverOutcomeReason,
+  OrgStructureOutcomeReason,
+  SynthesizeOutcomeReason,
+} from "./outcome-reasons";
+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;
+}

package/src/workflows/index.ts

@@ -14,32 +14,72 @@ export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "./types";
 export type {
   DiscoverOutcomeFacts,
   DiscoverOutcomeReason,
-  DiscoverWorkflowOutcome,
-  HrisConnectWorkflowOutcome,
   OrgStructureOutcomeFacts,
   OrgStructureOutcomeReason,
-  ReanalyzeWorkflowOutcome,
   SynthesizeOutcomeFacts,
   SynthesizeOutcomeReason,
+  WorkflowOutcomeKind,
+} from "./outcome-reasons";
+
+export {
+  DISCOVER_AFFORDANCES_OF_REASON,
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  DiscoverOutcomeFactsSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
+  WORKFLOW_OUTCOME_KINDS,
+} from "./outcome-reasons";
+
+export type {
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  ReanalyzeWorkflowOutcome,
   SynthesizeWorkflowOutcome,
   WorkflowOutcome,
   WorkflowOutcomeDisposition,
-  WorkflowOutcomeKind,
   WorkflowOutcomeOf,
 } from "./outcome";
 
 export {
-  DISCOVER_OUTCOME_KIND_OF_REASON,
-  DiscoverOutcomeFactsSchema,
   DiscoverWorkflowOutcomeSchema,
   HrisConnectWorkflowOutcomeSchema,
-  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
-  OrgStructureOutcomeFactsSchema,
   ReanalyzeWorkflowOutcomeSchema,
-  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
-  SynthesizeOutcomeFactsSchema,
   SynthesizeWorkflowOutcomeSchema,
-  WORKFLOW_OUTCOME_KINDS,
   WorkflowOutcomeDispositionSchema,
   WorkflowOutcomeSchema,
 } from "./outcome";
+
+export {
+  WORKFLOW_AFFORDANCES_OF_REASON,
+  affordancesOfOutcome,
+  affordancesOfReason,
+} from "./affordances-of-outcome";
+
+export type {
+  DeferredRoute,
+  DeferredRouteKind,
+  ExplainedDiscoverReason,
+  ExplainedOrgStructureReason,
+  ExplainedSynthesizeReason,
+  ExplainedWorkflowOutcome,
+  SettlementAudiencePolicy,
+  SettlementCoveringKind,
+} from "./deferred-route";
+
+export {
+  DEFERRED_ROUTES,
+  DISCOVER_DEFERRED_ROUTE_OF_REASON,
+  DeferredRouteSchema,
+  ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
+  SETTLEMENT_AUDIENCE_POLICIES,
+  SETTLEMENT_COVERING_KINDS,
+  SETTLEMENT_SILENT_REASONS,
+  SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
+  WORKFLOW_DEFERRED_ROUTE_OF_REASON,
+  deferredRouteOf,
+  toExplainedOutcome,
+} from "./deferred-route";

package/src/workflows/outcome-reasons.ts

@@ -0,0 +1,244 @@
+/**
+ * The per-type vocabulary of a workflow outcome (control ADR-CTRL-540): the
+ * shared `kind` list and, for every workflow type, its closed `reason` union,
+ * the `kind` each reason fixes, the affordances each reason offers, and the
+ * typed `facts` it reports.
+ *
+ * Tables only. `./outcome.ts` builds the outcome schemas from them and states
+ * the invariants they uphold (per-type and closed, kind and offer as functions
+ * of reason, facts are counts).
+ *
+ * An ending is one row in a `*_OUTCOME_KIND_OF_REASON` table and one in the
+ * matching `*_AFFORDANCES_OF_REASON` table, whose `satisfies` refuses a
+ * missing row.
+ */
+import { z } from "zod";
+
+import type { OfferedAffordance } from "../affordances/affordance";
+
+/** The shape of an ending, shared by every workflow type. */
+export const WORKFLOW_OUTCOME_KINDS = [
+  /** The run produced what it is for. */
+  "produced",
+  /** The run finished and produced nothing. */
+  "empty",
+  /** The run finished short of full coverage (a budget or ceiling). */
+  "partial",
+  /** A person stopped the run; Continue may begin a new execution epoch. */
+  "stopped",
+  /** The run failed. */
+  "failed",
+  /** The run went silent and the reconciler closed it. */
+  "abandoned",
+  /** A terminal transition the classifier did not recognize. */
+  "unknown",
+] as const;
+
+export type WorkflowOutcomeKind = (typeof WORKFLOW_OUTCOME_KINDS)[number];
+
+const Count = z.number().int().nonnegative();
+
+// The affordances an ending may offer, named once for the tables below.
+const FIND_FILES = { id: "sourceSync.findFiles" } as const;
+const CONNECT_GOOGLE_DRIVE = { id: "integrations.connectGoogleDrive" } as const;
+const ENABLE_SOURCE_SYNC = { id: "sourceSync.enable" } as const;
+const OPEN_BILLING = { id: "billing.open" } as const;
+const REANALYZE_STRUCTURE = { id: "orgStructure.reanalyze" } as const;
+const RESYNC_DIRECTORY = { id: "hris.resyncDirectory" } as const;
+
+// ---------------------------------------------------------------------------
+// source-sync/discover
+// ---------------------------------------------------------------------------
+
+/** Why a Drive discovery run ended the way it did. */
+export const DISCOVER_OUTCOME_KIND_OF_REASON = {
+  candidates_found: "produced",
+  nothing_found: "empty",
+  nothing_relevant: "empty",
+  budget_exhausted: "partial",
+  file_ceiling: "partial",
+  stopped_by_user: "stopped",
+  plan_coverage_refused: "failed",
+  billing_refused: "failed",
+  drive_auth: "failed",
+  drive_unavailable: "failed",
+  no_connection: "failed",
+  source_sync_off: "failed",
+  internal_error: "failed",
+  abandoned: "abandoned",
+  unrecognized_terminal_state: "unknown",
+} as const satisfies Record<string, WorkflowOutcomeKind>;
+
+export type DiscoverOutcomeReason =
+  keyof typeof DISCOVER_OUTCOME_KIND_OF_REASON;
+
+/**
+ * What each discovery ending offers (control ADR affordance-system). TOTAL: an
+ * empty list is a decision that no grounded action changes that ending — a
+ * re-run of the same search is not "broadening" it, and nothing raises a budget.
+ */
+export const DISCOVER_AFFORDANCES_OF_REASON = {
+  candidates_found: [],
+  nothing_found: [],
+  nothing_relevant: [],
+  budget_exhausted: [],
+  file_ceiling: [],
+  stopped_by_user: [],
+  plan_coverage_refused: [],
+  billing_refused: [OPEN_BILLING],
+  drive_auth: [CONNECT_GOOGLE_DRIVE],
+  drive_unavailable: [FIND_FILES],
+  no_connection: [CONNECT_GOOGLE_DRIVE],
+  source_sync_off: [ENABLE_SOURCE_SYNC],
+  internal_error: [FIND_FILES],
+  abandoned: [FIND_FILES],
+  unrecognized_terminal_state: [],
+} as const satisfies Record<
+  DiscoverOutcomeReason,
+  readonly OfferedAffordance[]
+>;
+
+/** The counts a discovery run reports at its end. */
+export const DiscoverOutcomeFactsSchema = z
+  .object({
+    probesTotal: Count,
+    probesDone: Count,
+    filesSeen: Count,
+    filesShown: Count,
+    filesHidden: Count,
+    filesDropped: Count,
+    coveragePercent: z.number().min(0).max(100).nullable(),
+  })
+  .strict();
+
+export type DiscoverOutcomeFacts = z.infer<typeof DiscoverOutcomeFactsSchema>;
+
+// ---------------------------------------------------------------------------
+// source-sync/synthesize
+// ---------------------------------------------------------------------------
+
+/** Why a synthesis (landing then drafting) run ended the way it did. */
+export const SYNTHESIZE_OUTCOME_KIND_OF_REASON = {
+  updates_ready: "produced",
+  updates_applied: "produced",
+  stopped_by_user: "stopped",
+  paused_billing: "failed",
+  synthesis_incomplete: "failed",
+  approval_mismatch: "failed",
+  landing_refused: "failed",
+  standing_order_refused: "failed",
+  no_connection: "failed",
+  source_sync_off: "failed",
+  internal_error: "failed",
+  abandoned: "abandoned",
+  unrecognized_terminal_state: "unknown",
+} as const satisfies Record<string, WorkflowOutcomeKind>;
+
+export type SynthesizeOutcomeReason =
+  keyof typeof SYNTHESIZE_OUTCOME_KIND_OF_REASON;
+
+/** What each synthesis ending offers. TOTAL; an empty list is explicit. */
+export const SYNTHESIZE_AFFORDANCES_OF_REASON = {
+  updates_ready: [],
+  updates_applied: [],
+  stopped_by_user: [],
+  paused_billing: [OPEN_BILLING],
+  synthesis_incomplete: [],
+  approval_mismatch: [],
+  landing_refused: [],
+  standing_order_refused: [],
+  no_connection: [CONNECT_GOOGLE_DRIVE],
+  source_sync_off: [ENABLE_SOURCE_SYNC],
+  internal_error: [],
+  abandoned: [],
+  unrecognized_terminal_state: [],
+} as const satisfies Record<
+  SynthesizeOutcomeReason,
+  readonly OfferedAffordance[]
+>;
+
+/** The counts a synthesis run reports at its end. */
+export const SynthesizeOutcomeFactsSchema = z
+  .object({
+    /** Approved scopes the run read. */
+    scopeCount: Count,
+    /** Authority or size violations that left the batch incomplete. */
+    violationCount: Count,
+  })
+  .strict();
+
+export type SynthesizeOutcomeFacts = z.infer<
+  typeof SynthesizeOutcomeFactsSchema
+>;
+
+// ---------------------------------------------------------------------------
+// org-structure/hris-connect and org-structure/reanalyze
+// ---------------------------------------------------------------------------
+
+/**
+ * Why an org-structure analysis ended the way it did. Shared by both
+ * org-structure workflow types: they run the same analysis. The directory-only
+ * endings (`directory_synced`, `analysis_already_running`, `sync_failed`) occur
+ * only on `org-structure/hris-connect`, which syncs the directory first.
+ */
+export const ORG_STRUCTURE_OUTCOME_KIND_OF_REASON = {
+  proposal_ready: "produced",
+  directory_synced: "produced",
+  analysis_already_running: "produced",
+  proposal_blocked: "failed",
+  no_sync_run: "empty",
+  no_persons: "empty",
+  reporting_not_keyed: "empty",
+  stopped_by_user: "stopped",
+  sync_failed: "failed",
+  snapshot_too_large: "failed",
+  model_failed: "failed",
+  run_too_large: "failed",
+  placement_failed: "failed",
+  internal_error: "failed",
+  abandoned: "abandoned",
+  unrecognized_terminal_state: "unknown",
+} as const satisfies Record<string, WorkflowOutcomeKind>;
+
+export type OrgStructureOutcomeReason =
+  keyof typeof ORG_STRUCTURE_OUTCOME_KIND_OF_REASON;
+
+/**
+ * What each org-structure ending offers; shared by both org-structure workflow
+ * types, like the kind table. TOTAL; an empty list is explicit.
+ */
+export const ORG_STRUCTURE_AFFORDANCES_OF_REASON = {
+  proposal_ready: [],
+  directory_synced: [],
+  analysis_already_running: [],
+  proposal_blocked: [],
+  no_sync_run: [RESYNC_DIRECTORY],
+  no_persons: [],
+  reporting_not_keyed: [],
+  stopped_by_user: [],
+  sync_failed: [RESYNC_DIRECTORY],
+  snapshot_too_large: [],
+  model_failed: [REANALYZE_STRUCTURE],
+  run_too_large: [],
+  placement_failed: [REANALYZE_STRUCTURE],
+  internal_error: [REANALYZE_STRUCTURE],
+  abandoned: [REANALYZE_STRUCTURE],
+  unrecognized_terminal_state: [],
+} as const satisfies Record<
+  OrgStructureOutcomeReason,
+  readonly OfferedAffordance[]
+>;
+
+/** The counts a finished org-structure proposal carries. */
+export const OrgStructureOutcomeFactsSchema = z
+  .object({
+    departmentCount: Count,
+    teamCount: Count,
+    placedCount: Count,
+    reviewItemCount: Count,
+  })
+  .strict();
+
+export type OrgStructureOutcomeFacts = z.infer<
+  typeof OrgStructureOutcomeFactsSchema
+>;