@company-semantics/contracts 90.0.0 → 91.1.0

package/src/workflows/outcome.ts

@@ -16,12 +16,18 @@
  *   record: a renderer that switches on `reason` is exhaustive, and a new fact is
  *   a schema change, not a new spelling.
  * - KIND IS A FUNCTION OF REASON. `kind` is carried for consumers that only care
- *   about the shape of the ending, but it is fixed by the per-type table below
- *   (`*_OUTCOME_KIND_OF_REASON`) and the schema refuses any other pairing.
+ *   about the shape of the ending, but it is fixed by the per-type table
+ *   (`*_OUTCOME_KIND_OF_REASON` in `./outcome-reasons.ts`) and the schema
+ *   refuses any other pairing.
  * - DISPOSITION IS EXPLICIT. `review` names the input request a person decides
  *   on; `narrate` means the ending is told, not reviewed. `produced` does not
  *   imply a review surface, and only a `produced` or `partial` outcome may carry
  *   `review`.
+ * - THE OFFER IS A FUNCTION OF REASON. `affordances` is the ordered list of
+ *   next steps the ending offers (control ADR affordance-system), fixed by the
+ *   per-type `*_AFFORDANCES_OF_REASON` table and frozen with the outcome. The
+ *   schema refuses any other list. A projected affordance (`review.open`) is
+ *   never stored here: it is derived from the `review` disposition.
  * - `unknown` IS A SAFETY VALVE for a terminal transition the classifier did not
  *   recognize. It is never used for a failure to OBSERVE a workflow: a workflow
  *   whose state cannot be read has no outcome yet.
@@ -32,27 +38,26 @@
  */
 import { z } from "zod";
 
+import {
+  MAX_OFFERED_AFFORDANCES,
+  OfferedAffordanceSchema,
+  sameAffordances,
+  type OfferedAffordance,
+} from "../affordances/affordance";
 import { INPUT_REQUEST_TYPES } from "../input-requests/types";
-
-/** 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];
+import {
+  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,
+  type WorkflowOutcomeKind,
+} from "./outcome-reasons";
 
 const KindSchema = z.enum(WORKFLOW_OUTCOME_KINDS);
 
@@ -74,131 +79,6 @@ export type WorkflowOutcomeDisposition = z.infer<
 
 const Count = z.number().int().nonnegative();
 
-// ---------------------------------------------------------------------------
-// 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;
-
-/** 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;
-
-/** 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;
-
-/** 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
->;
-
 // ---------------------------------------------------------------------------
 // The union
 // ---------------------------------------------------------------------------
@@ -207,7 +87,12 @@ function memberSchema<
   T extends string,
   R extends Record<string, WorkflowOutcomeKind>,
   F extends z.ZodTypeAny,
->(workflowType: T, kindOfReason: R, facts: F) {
+>(
+  workflowType: T,
+  kindOfReason: R,
+  facts: F,
+  affordancesOfReason: Record<keyof R, readonly OfferedAffordance[]>,
+) {
   const reasons = Object.keys(kindOfReason) as [
     keyof R & string,
     ...(keyof R & string)[],
@@ -221,6 +106,10 @@ function memberSchema<
       reason: z.enum(reasons),
       facts: facts.nullable(),
       disposition: WorkflowOutcomeDispositionSchema,
+      /** The next steps this ending offers, frozen with it (see the table). */
+      affordances: z
+        .array(OfferedAffordanceSchema)
+        .max(MAX_OFFERED_AFFORDANCES),
     })
     .strict()
     .superRefine((outcome, ctx) => {
@@ -243,6 +132,15 @@ function memberSchema<
           message: "only a produced or partial outcome may hand off to review",
         });
       }
+      const offered = affordancesOfReason[outcome.reason as keyof R];
+      if (!sameAffordances(outcome.affordances, offered)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["affordances"],
+          message:
+            "an outcome offers exactly its reason's affordances, in order",
+        });
+      }
     });
 }
 
@@ -250,21 +148,25 @@ export const DiscoverWorkflowOutcomeSchema = memberSchema(
   "source-sync/discover",
   DISCOVER_OUTCOME_KIND_OF_REASON,
   DiscoverOutcomeFactsSchema,
+  DISCOVER_AFFORDANCES_OF_REASON,
 );
 export const SynthesizeWorkflowOutcomeSchema = memberSchema(
   "source-sync/synthesize",
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   SynthesizeOutcomeFactsSchema,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
 );
 export const HrisConnectWorkflowOutcomeSchema = memberSchema(
   "org-structure/hris-connect",
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   OrgStructureOutcomeFactsSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
 );
 export const ReanalyzeWorkflowOutcomeSchema = memberSchema(
   "org-structure/reanalyze",
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   OrgStructureOutcomeFactsSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
 );
 
 export type DiscoverWorkflowOutcome = z.infer<