@company-semantics/contracts 89.2.0 → 91.0.0

package/src/workflows/index.ts

@@ -29,13 +29,16 @@ export type {
 } from "./outcome";
 
 export {
+  DISCOVER_AFFORDANCES_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
   DiscoverOutcomeFactsSchema,
   DiscoverWorkflowOutcomeSchema,
   HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   OrgStructureOutcomeFactsSchema,
   ReanalyzeWorkflowOutcomeSchema,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   SynthesizeOutcomeFactsSchema,
   SynthesizeWorkflowOutcomeSchema,
@@ -43,3 +46,34 @@ export {
   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.ts

@@ -22,6 +22,11 @@
  *   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,6 +37,12 @@
  */
 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. */
@@ -74,6 +85,14 @@ export type WorkflowOutcomeDisposition = z.infer<
 
 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
 // ---------------------------------------------------------------------------
@@ -100,6 +119,32 @@ export const DISCOVER_OUTCOME_KIND_OF_REASON = {
 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({
@@ -139,6 +184,26 @@ export const SYNTHESIZE_OUTCOME_KIND_OF_REASON = {
 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({
@@ -185,6 +250,32 @@ export const ORG_STRUCTURE_OUTCOME_KIND_OF_REASON = {
 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({
@@ -207,7 +298,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 +317,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 +343,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 +359,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<