@company-semantics/contracts 91.0.0 → 91.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "91.0.0",
+  "version": "91.1.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'b2a6eec5dea4' as const;
-export const SPEC_HASH_FULL = 'b2a6eec5dea4f72290740a1cf16608a826ece2e3654ba64d2bc5e3794d571809' as const;
+export const SPEC_HASH = '2d074ecfa53c' as const;
+export const SPEC_HASH_FULL = '2d074ecfa53c0f377dfda06d9a46167a9cfc77eb3878e2cd71b8a04149c700b7' as const;

package/src/api/generated.ts

@@ -1566,6 +1566,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/integrations/bamboohr/sync": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Run a BambooHR sync now (returns the run summary) */
+        post: operations["syncBambooHrNow"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/org/reconciliation": {
         parameters: {
             query?: never;
@@ -1666,6 +1683,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org/structure-inference/runs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Launch one org-structure reanalyze workflow and its inference run
+         * @description Mints an org-structure/reanalyze analysis workflow, opens its pending run and schedules the job, all in one transaction (ADR-BE-606, ADR-BE-703): the snapshot, the model calls and the deterministic gate execute on the worker, and the outcome is read back by polling GET /api/org/structure-inference/proposal, whose run field carries this run’s id and status, or GET /api/analysis-workflows/{workflowId} for the workflow. At most one inference is in flight per org — a second POST joins the run already under way. Explicitly operator-triggered: there is no schedule and no sync hook.
+         */
+        post: operations["runOrgStructureInference"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/analysis-workflows/{id}": {
         parameters: {
             query?: never;
@@ -1726,6 +1763,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/affordances/state": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read the live policy and availability of offered affordances
+         * @description For exactly the affordance ids named in `ids` (the ids a settled outcome offered — never the catalog), whether the viewer is shown each one (`policy`, from the same capability derivation as GET /api/capabilities) and whether the org’s current state permits it (`availability`). Entries come back in request order, deduped. NON-AUTHORITATIVE: this answer is advisory UX state; the route each affordance binds to stays the only enforcement and may still refuse. Org-scoped: requires active membership of the session org, because availability discloses org state.
+         */
+        get: operations["getAffordanceState"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -6808,6 +6865,34 @@ export interface components {
                         requiredScope?: string;
                     };
                 };
+                integrations?: {
+                    manage: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                sourceSync?: {
+                    manage: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                billing?: {
+                    view: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                orgStructure?: {
+                    analyze: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
             };
             chatMentions: boolean;
             chatMultiParty: boolean;
@@ -6816,6 +6901,17 @@ export interface components {
                 reason: ("BILLING_INACTIVE" | "SEAT_SUBSCRIPTION_PAST_DUE" | "AI_BALANCE_EXHAUSTED" | "AI_BUDGET_EXHAUSTED" | "BYO_KEY_INVALID") | null;
             };
         };
+        BambooHrSyncRunResponse: {
+            /** Format: uuid */
+            runId: string;
+            processed: number;
+            changed: number;
+            skipped: number;
+            conflicts: number;
+            failures: number;
+            sinceCursor: string | null;
+            status: string;
+        };
         ResolveOrgDivergenceRequest: {
             /** @constant */
             resolution: "acknowledged";
@@ -6993,6 +7089,23 @@ export interface components {
             fingerprint: string;
             note?: string;
         };
+        RunStructureInferenceRefusal: {
+            /** @constant */
+            ran: false;
+            /** @enum {string} */
+            reason: "no_sync_run" | "no_persons" | "reporting_not_keyed";
+            message: string;
+        };
+        RunStructureInferenceAccepted: {
+            /** @constant */
+            ran: true;
+            /** Format: uuid */
+            runId: string;
+            workflowId: string | null;
+            /** @enum {string} */
+            status: "pending" | "running";
+            alreadyRunning: boolean;
+        };
         AnalysisWorkflowProjectionResponse: {
             /** Format: uuid */
             id: string;
@@ -7003,7 +7116,180 @@ export interface components {
             completedAt: string | null;
             progress: unknown | null;
             result: unknown | null;
-            outcome: unknown | null;
+            outcome: ({
+                /** @constant */
+                workflowType: "source-sync/discover";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "candidates_found" | "nothing_found" | "nothing_relevant" | "budget_exhausted" | "file_ceiling" | "stopped_by_user" | "plan_coverage_refused" | "billing_refused" | "drive_auth" | "drive_unavailable" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    probesTotal: number;
+                    probesDone: number;
+                    filesSeen: number;
+                    filesShown: number;
+                    filesHidden: number;
+                    filesDropped: number;
+                    coveragePercent: number | null;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "source-sync/synthesize";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "updates_ready" | "updates_applied" | "stopped_by_user" | "paused_billing" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    scopeCount: number;
+                    violationCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "org-structure/hris-connect";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "proposal_ready" | "directory_synced" | "analysis_already_running" | "proposal_blocked" | "no_sync_run" | "no_persons" | "reporting_not_keyed" | "stopped_by_user" | "sync_failed" | "snapshot_too_large" | "model_failed" | "run_too_large" | "placement_failed" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    departmentCount: number;
+                    teamCount: number;
+                    placedCount: number;
+                    reviewItemCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            } | {
+                /** @constant */
+                workflowType: "org-structure/reanalyze";
+                executionEpoch: number;
+                /** @enum {string} */
+                kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
+                /** @enum {string} */
+                reason: "proposal_ready" | "directory_synced" | "analysis_already_running" | "proposal_blocked" | "no_sync_run" | "no_persons" | "reporting_not_keyed" | "stopped_by_user" | "sync_failed" | "snapshot_too_large" | "model_failed" | "run_too_large" | "placement_failed" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                facts: {
+                    departmentCount: number;
+                    teamCount: number;
+                    placedCount: number;
+                    reviewItemCount: number;
+                } | null;
+                disposition: {
+                    /** @constant */
+                    kind: "review";
+                    /** @enum {string} */
+                    requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                    requestId: string;
+                } | {
+                    /** @constant */
+                    kind: "narrate";
+                };
+                affordances: ({
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                })[];
+            }) | null;
             error?: string;
             capabilities: {
                 canStop: boolean;
@@ -7027,6 +7313,26 @@ export interface components {
             /** @enum {string} */
             result: "delivered" | "deferred" | "busy" | "skipped" | "not_settled";
         };
+        AffordanceStateResponse: {
+            entries: {
+                /** @enum {string} */
+                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "orgStructure.reanalyze" | "hris.resyncDirectory" | "review.open";
+                /** @enum {string} */
+                policy: "allowed" | "blocked";
+                availability: {
+                    /** @constant */
+                    state: "available";
+                } | {
+                    /** @constant */
+                    state: "already_satisfied";
+                } | {
+                    /** @constant */
+                    state: "unavailable";
+                    /** @enum {string} */
+                    reason: "conflicting_operation" | "missing_dependency" | "resource_gone" | "temporarily_disabled";
+                };
+            }[];
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -12949,6 +13255,33 @@ export interface operations {
             };
         };
     };
+    syncBambooHrNow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Sync run summary */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BambooHrSyncRunResponse"];
+                };
+            };
+            /** @description No active BambooHR connection, or BambooHR no longer recognizes the organization */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getOrgReconciliation: {
         parameters: {
             query?: never;
@@ -13096,6 +13429,35 @@ export interface operations {
             };
         };
     };
+    runOrgStructureInference: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A named refusal with its operator-facing next step: no directory imported yet, a sync that imported nobody, or a credential whose sync could not key reporting edges (reporting_not_keyed) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunStructureInferenceRefusal"];
+                };
+            };
+            /** @description A run is under way — freshly launched, or already in flight (alreadyRunning: true). Carries the runId the poll surface matches against and the workflowId of the org-structure/reanalyze workflow it executes (null only when the joined run predates the workflow launch) */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunStructureInferenceAccepted"];
+                };
+            };
+        };
+    };
     getAnalysisWorkflow: {
         parameters: {
             query?: never;
@@ -13213,6 +13575,42 @@ export interface operations {
             };
         };
     };
+    getAffordanceState: {
+        parameters: {
+            query: {
+                ids: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Policy and availability per requested affordance id, in request order */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AffordanceStateResponse"];
+                };
+            };
+            /** @description An id is not a known affordance, the list is empty, or it is too long */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The viewer is not an active member of the session org */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {

package/src/generated/openapi-routes.ts

@@ -9,6 +9,7 @@ export const openApiRoutes = {
   '/api/account/deletion-eligibility': ['GET'],
   '/api/account/sessions': ['GET'],
   '/api/account/sessions/{sessionId}': ['DELETE'],
+  '/api/affordances/state': ['GET'],
   '/api/analysis-workflows/{id}': ['GET'],
   '/api/analysis-workflows/{id}/settlement': ['POST'],
   '/api/analysis-workflows/{id}/stop': ['POST'],
@@ -101,6 +102,7 @@ export const openApiRoutes = {
   '/api/factory/quality/plans/{planId}/decision': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
+  '/api/integrations/bamboohr/sync': ['POST'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],
@@ -181,6 +183,7 @@ export const openApiRoutes = {
   '/api/org/structure-findings': ['GET'],
   '/api/org/structure-findings/{findingId}/dismiss': ['POST'],
   '/api/org/structure-findings/{findingId}/reopen': ['POST'],
+  '/api/org/structure-inference/runs': ['POST'],
   '/api/org/system-events': ['GET'],
   '/api/org/system-events/{id}/acknowledge': ['POST'],
   '/api/org/transfer-eligibility': ['GET'],

package/src/workflows/README.md

@@ -32,7 +32,8 @@ so every producer, validator and renderer agrees on it.
 - **Source Sync registers two flows.** `source-sync/discover` (Stage 1)
   retains nothing; `source-sync/synthesize` (Stage 4) runs only after a person
   approved the exact set it reads.
-- **Every type has a typed outcome** (`outcome.ts`, control ADR-CTRL-540). A
+- **Every type has a typed outcome** (`outcome.ts`, tables in
+  `outcome-reasons.ts`; control ADR-CTRL-540). A
   terminal transition is classified once, by the backend, into a per-type
   member of `WorkflowOutcome`: a closed `reason`, typed count-only `facts`, a
   `kind` that is a function of the reason (`*_OUTCOME_KIND_OF_REASON`), and an
@@ -68,11 +69,12 @@ so every producer, validator and renderer agrees on it.
 ## Public API
 
 - `ANALYSIS_WORKFLOW_TYPES`, `WorkflowType`, `isWorkflowType` (`types.ts`).
-- `WorkflowOutcomeSchema` / `WorkflowOutcome` and the per-type member schemas,
-  reason tables, fact schemas and `WorkflowOutcomeDispositionSchema`
-  (`outcome.ts`).
+- `WorkflowOutcomeSchema` / `WorkflowOutcome`, the per-type member schemas and
+  `WorkflowOutcomeDispositionSchema` (`outcome.ts`).
+- `WORKFLOW_OUTCOME_KINDS` and the per-type reason tables and fact schemas
+  (`outcome-reasons.ts`).
 - `DISCOVER_AFFORDANCES_OF_REASON`, `SYNTHESIZE_AFFORDANCES_OF_REASON`,
-  `ORG_STRUCTURE_AFFORDANCES_OF_REASON` (`outcome.ts`).
+  `ORG_STRUCTURE_AFFORDANCES_OF_REASON` (`outcome-reasons.ts`).
 - `WORKFLOW_AFFORDANCES_OF_REASON`, `affordancesOfReason`,
   `affordancesOfOutcome` (`affordances-of-outcome.ts`).
 - `SETTLEMENT_AUDIENCE_POLICIES`, `SETTLEMENT_COVERING_KINDS`,

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

@@ -6,11 +6,8 @@ import {
   affordancesOfOutcome,
   affordancesOfReason,
 } from "../affordances-of-outcome";
-import {
-  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
-  WorkflowOutcomeSchema,
-  type WorkflowOutcome,
-} from "../outcome";
+import { WorkflowOutcomeSchema, type WorkflowOutcome } from "../outcome";
+import { ORG_STRUCTURE_AFFORDANCES_OF_REASON } from "../outcome-reasons";
 import { ANALYSIS_WORKFLOW_TYPES } from "../types";
 
 const review = {

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

@@ -16,6 +16,7 @@ import {
   toExplainedOutcome,
   type DeferredRoute,
 } from "../deferred-route";
+import { WorkflowOutcomeSchema, type WorkflowOutcome } from "../outcome";
 import {
   DISCOVER_AFFORDANCES_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
@@ -23,9 +24,7 @@ import {
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   SYNTHESIZE_AFFORDANCES_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
-  WorkflowOutcomeSchema,
-  type WorkflowOutcome,
-} from "../outcome";
+} from "../outcome-reasons";
 
 // (kind table, offer table, route table) per outcome family. Built here rather
 // than exported so the rules stay pinned without widening the public surface.

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

@@ -5,6 +5,7 @@ import {
   OfferedAffordanceSchema,
 } from "../../affordances/affordance";
 import type { WorkflowType } from "../types";
+import { WorkflowOutcomeSchema, type WorkflowOutcome } from "../outcome";
 import {
   DISCOVER_AFFORDANCES_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
@@ -13,9 +14,7 @@ import {
   SYNTHESIZE_AFFORDANCES_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   WORKFLOW_OUTCOME_KINDS,
-  WorkflowOutcomeSchema,
-  type WorkflowOutcome,
-} from "../outcome";
+} from "../outcome-reasons";
 
 // Compile-time: every registered workflow type has an outcome member, and the
 // union names no type that is not registered.

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

@@ -9,13 +9,12 @@
  * 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,
-  type WorkflowOutcome,
-  type WorkflowOutcomeOf,
-} from "./outcome";
+} from "./outcome-reasons";
 import type { WorkflowType } from "./types";
 
 /** Every workflow type's offer table, total over the type union. */

package/src/workflows/deferred-route.ts

@@ -29,16 +29,18 @@
 import { z } from "zod";
 
 import type {
-  DiscoverOutcomeReason,
   DiscoverWorkflowOutcome,
   HrisConnectWorkflowOutcome,
-  OrgStructureOutcomeReason,
   ReanalyzeWorkflowOutcome,
-  SynthesizeOutcomeReason,
   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. */

package/src/workflows/index.ts

@@ -14,35 +14,41 @@ export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "./types";
 export type {
   DiscoverOutcomeFacts,
   DiscoverOutcomeReason,
-  DiscoverWorkflowOutcome,
-  HrisConnectWorkflowOutcome,
   OrgStructureOutcomeFacts,
   OrgStructureOutcomeReason,
-  ReanalyzeWorkflowOutcome,
   SynthesizeOutcomeFacts,
   SynthesizeOutcomeReason,
-  SynthesizeWorkflowOutcome,
-  WorkflowOutcome,
-  WorkflowOutcomeDisposition,
   WorkflowOutcomeKind,
-  WorkflowOutcomeOf,
-} from "./outcome";
+} from "./outcome-reasons";
 
 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,
   WORKFLOW_OUTCOME_KINDS,
+} from "./outcome-reasons";
+
+export type {
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  ReanalyzeWorkflowOutcome,
+  SynthesizeWorkflowOutcome,
+  WorkflowOutcome,
+  WorkflowOutcomeDisposition,
+  WorkflowOutcomeOf,
+} from "./outcome";
+
+export {
+  DiscoverWorkflowOutcomeSchema,
+  HrisConnectWorkflowOutcomeSchema,
+  ReanalyzeWorkflowOutcomeSchema,
+  SynthesizeWorkflowOutcomeSchema,
   WorkflowOutcomeDispositionSchema,
   WorkflowOutcomeSchema,
 } from "./outcome";

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

package/src/workflows/outcome.ts

@@ -16,8 +16,9 @@
  *   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
@@ -44,26 +45,19 @@ import {
   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);
 
@@ -85,211 +79,6 @@ 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
-// ---------------------------------------------------------------------------
-
-/** 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
->;
-
 // ---------------------------------------------------------------------------
 // The union
 // ---------------------------------------------------------------------------