@company-semantics/contracts 90.0.0 → 91.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/package.json +2 -2
  2. package/src/affordances/README.md +65 -0
  3. package/src/affordances/__tests__/README.md +30 -0
  4. package/src/affordances/__tests__/affordances.test.ts +251 -0
  5. package/src/affordances/affordance.ts +124 -0
  6. package/src/affordances/args.ts +59 -0
  7. package/src/affordances/availability.ts +78 -0
  8. package/src/affordances/ids.ts +45 -0
  9. package/src/affordances/index.ts +39 -0
  10. package/src/api/generated-spec-hash.ts +2 -2
  11. package/src/api/generated.ts +59 -1
  12. package/src/generated/openapi-routes.ts +1 -0
  13. package/src/proactive/README.md +26 -4
  14. package/src/proactive/__tests__/README.md +10 -0
  15. package/src/proactive/__tests__/chat-templates.test.ts +8 -0
  16. package/src/proactive/__tests__/vocabulary.test.ts +11 -0
  17. package/src/proactive/__tests__/workflow-attention-fixtures.ts +49 -0
  18. package/src/proactive/__tests__/workflow-attention.test.ts +146 -0
  19. package/src/proactive/composer.ts +8 -0
  20. package/src/proactive/facts.ts +36 -0
  21. package/src/proactive/index.ts +2 -0
  22. package/src/proactive/kinds.ts +29 -0
  23. package/src/proactive/registry.ts +22 -0
  24. package/src/proactive/surfaces.ts +2 -0
  25. package/src/proactive/templates/README.md +9 -1
  26. package/src/proactive/templates/index.ts +2 -0
  27. package/src/proactive/templates/workflow-needs-attention.ts +35 -0
  28. package/src/root-exports/README.md +1 -0
  29. package/src/root-exports/delivery.ts +69 -1
  30. package/src/user-notifications/README.md +8 -0
  31. package/src/user-notifications/kinds.ts +13 -0
  32. package/src/user-notifications/lifecycle-registry.ts +10 -0
  33. package/src/workflows/README.md +38 -2
  34. package/src/workflows/__tests__/README.md +21 -2
  35. package/src/workflows/__tests__/affordances-of-outcome.test.ts +99 -0
  36. package/src/workflows/__tests__/deferred-route.test.ts +168 -0
  37. package/src/workflows/__tests__/outcome.test.ts +66 -0
  38. package/src/workflows/affordances-of-outcome.ts +65 -0
  39. package/src/workflows/deferred-route.ts +240 -0
  40. package/src/workflows/index.ts +34 -0
  41. package/src/workflows/outcome.ts +114 -1
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The workflow-settlement offer rule and its projection (control ADR
3
+ * affordance-system; control ADR-CTRL-540).
4
+ *
5
+ * `affordancesOfReason` is the ONE place a producer reads the frozen offer for
6
+ * an ending (the backend's outcome builder calls it). `affordancesOfOutcome` is
7
+ * the ONE projection every consumer renders from — the settlement message, the
8
+ * proactive chat and the agent's context alike — so the Review control and the
9
+ * offered next steps are one list built one way.
10
+ */
11
+ import type { Affordance, OfferedAffordance } from "../affordances/affordance";
12
+ import {
13
+ DISCOVER_AFFORDANCES_OF_REASON,
14
+ ORG_STRUCTURE_AFFORDANCES_OF_REASON,
15
+ SYNTHESIZE_AFFORDANCES_OF_REASON,
16
+ type WorkflowOutcome,
17
+ type WorkflowOutcomeOf,
18
+ } from "./outcome";
19
+ import type { WorkflowType } from "./types";
20
+
21
+ /** Every workflow type's offer table, total over the type union. */
22
+ export const WORKFLOW_AFFORDANCES_OF_REASON = {
23
+ "source-sync/discover": DISCOVER_AFFORDANCES_OF_REASON,
24
+ "source-sync/synthesize": SYNTHESIZE_AFFORDANCES_OF_REASON,
25
+ "org-structure/hris-connect": ORG_STRUCTURE_AFFORDANCES_OF_REASON,
26
+ "org-structure/reanalyze": ORG_STRUCTURE_AFFORDANCES_OF_REASON,
27
+ } as const satisfies {
28
+ readonly [T in WorkflowType]: Record<
29
+ WorkflowOutcomeOf<T>["reason"],
30
+ readonly OfferedAffordance[]
31
+ >;
32
+ };
33
+
34
+ /** The frozen offer an ending of one workflow type carries. */
35
+ export function affordancesOfReason<T extends WorkflowType>(
36
+ workflowType: T,
37
+ reason: WorkflowOutcomeOf<T>["reason"],
38
+ ): readonly OfferedAffordance[] {
39
+ const table = WORKFLOW_AFFORDANCES_OF_REASON[workflowType] as Record<
40
+ string,
41
+ readonly OfferedAffordance[]
42
+ >;
43
+ return table[reason as string] ?? [];
44
+ }
45
+
46
+ /**
47
+ * Everything an outcome offers, in render order: the frozen offer, then the
48
+ * `review.open` projected from a `review` disposition. Pure; never persisted.
49
+ */
50
+ export function affordancesOfOutcome(
51
+ outcome: WorkflowOutcome,
52
+ ): readonly Affordance[] {
53
+ const { disposition } = outcome;
54
+ if (disposition.kind !== "review") return [...outcome.affordances];
55
+ return [
56
+ ...outcome.affordances,
57
+ {
58
+ id: "review.open",
59
+ args: {
60
+ requestType: disposition.requestType,
61
+ requestId: disposition.requestId,
62
+ },
63
+ },
64
+ ];
65
+ }
@@ -0,0 +1,240 @@
1
+ /**
2
+ * Where a settlement goes when there is no launching conversation to write it
3
+ * into (control ADR-CTRL-540 phase 2; control ADR affordance-system).
4
+ *
5
+ * A scheduled rediscovery, an upkeep re-synthesis or a launch nobody docked
6
+ * into a chat settles with no anchor. Its route is decided per REASON, frozen by
7
+ * the backend onto the settlement row when it defers, and never re-derived.
8
+ *
9
+ * THE DOCTRINE (control docs/proactive-delivery.md): a pushed `explained` chat
10
+ * is frozen, so it may contain only material that stays non-privileged after
11
+ * the recipient's authority changes. A settlement told WITHOUT FACTS (its
12
+ * reason only, `facts: null`) plus its affordance ids qualifies — affordances
13
+ * are re-gated per viewer at render and executed by the server. An ending whose
14
+ * telling needs authority-sensitive facts (counts) goes to a `notice` inbox row,
15
+ * which re-renders under the reader's current authority.
16
+ *
17
+ * RULES (pinned by the deferred-route test):
18
+ * - `explained` only for a `failed` or `abandoned` ending that offers at least
19
+ * one affordance. A `produced`, `empty` or `partial` ending is never explained.
20
+ * - `covered` when a domain kind normally announces that ending. Covering is
21
+ * verified, not assumed: the backend checks that the covering occurrence
22
+ * exists for this workflow and epoch at route time, and otherwise routes the
23
+ * `fallback` notice to the stated audience. Nothing is ever said twice, and
24
+ * nothing falls silent because a domain kind declined.
25
+ * - `silent` only for `stopped_by_user`: the person who stopped it acted.
26
+ * - Audiences are policies the backend resolves and freezes at emit; an empty
27
+ * resolved audience routes silent.
28
+ */
29
+ import { z } from "zod";
30
+
31
+ import type {
32
+ DiscoverOutcomeReason,
33
+ DiscoverWorkflowOutcome,
34
+ HrisConnectWorkflowOutcome,
35
+ OrgStructureOutcomeReason,
36
+ ReanalyzeWorkflowOutcome,
37
+ SynthesizeOutcomeReason,
38
+ SynthesizeWorkflowOutcome,
39
+ WorkflowOutcome,
40
+ WorkflowOutcomeOf,
41
+ } from "./outcome";
42
+ import type { WorkflowType } from "./types";
43
+
44
+ /** Who a routed settlement is addressed to; resolved and frozen by the backend. */
45
+ export const SETTLEMENT_AUDIENCE_POLICIES = [
46
+ /** The person who launched the workflow, while still an active member. */
47
+ "creator",
48
+ /** The launcher plus the org owner and admins (who manage integrations). */
49
+ "creator_and_owner_admins",
50
+ ] as const;
51
+ export type SettlementAudiencePolicy =
52
+ (typeof SETTLEMENT_AUDIENCE_POLICIES)[number];
53
+
54
+ /**
55
+ * The proactive kinds that already announce some endings. Literal strings, not
56
+ * an import: workflows never imports proactive (proactive imports workflows).
57
+ * The test pins each one as a real PROACTIVE_EVENT_KIND_IDS member.
58
+ */
59
+ export const SETTLEMENT_COVERING_KINDS = [
60
+ "sourceSync.review_ready",
61
+ "sourceSync.docs_updated",
62
+ "orgStructure.review_ready",
63
+ ] as const;
64
+ export type SettlementCoveringKind = (typeof SETTLEMENT_COVERING_KINDS)[number];
65
+
66
+ /** Why a routed settlement says nothing. Closed. */
67
+ export const SETTLEMENT_SILENT_REASONS = ["stopped_by_person"] as const;
68
+
69
+ export const DEFERRED_ROUTES = [
70
+ "explained",
71
+ "notice",
72
+ "covered",
73
+ "silent",
74
+ ] as const;
75
+ export type DeferredRouteKind = (typeof DEFERRED_ROUTES)[number];
76
+
77
+ export const DeferredRouteSchema = z.discriminatedUnion("route", [
78
+ z
79
+ .object({
80
+ route: z.literal("explained"),
81
+ audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
82
+ })
83
+ .strict(),
84
+ z
85
+ .object({
86
+ route: z.literal("notice"),
87
+ audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
88
+ })
89
+ .strict(),
90
+ z
91
+ .object({
92
+ route: z.literal("covered"),
93
+ by: z.enum(SETTLEMENT_COVERING_KINDS),
94
+ /**
95
+ * Covering is not literal on every path (a domain kind may decline: e.g.
96
+ * sourceSync.review_ready fires on scheduled rediscovery only when new
97
+ * candidates exist). The backend verifies the covering occurrence exists
98
+ * for this workflow/epoch at route time; otherwise it routes the notice.
99
+ */
100
+ fallback: z.literal("notice"),
101
+ /** Who the fallback notice is addressed to. */
102
+ audience: z.enum(SETTLEMENT_AUDIENCE_POLICIES),
103
+ })
104
+ .strict(),
105
+ z
106
+ .object({
107
+ route: z.literal("silent"),
108
+ why: z.enum(SETTLEMENT_SILENT_REASONS),
109
+ })
110
+ .strict(),
111
+ ]);
112
+ export type DeferredRoute = z.infer<typeof DeferredRouteSchema>;
113
+
114
+ const EXPLAINED = {
115
+ route: "explained",
116
+ audience: "creator_and_owner_admins",
117
+ } as const;
118
+ const NOTICE_CREATOR = { route: "notice", audience: "creator" } as const;
119
+ const NOTICE_ADMINS = {
120
+ route: "notice",
121
+ audience: "creator_and_owner_admins",
122
+ } as const;
123
+ const STOPPED = { route: "silent", why: "stopped_by_person" } as const;
124
+
125
+ export const DISCOVER_DEFERRED_ROUTE_OF_REASON = {
126
+ // prettier-ignore
127
+ candidates_found: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
128
+ nothing_found: NOTICE_CREATOR,
129
+ nothing_relevant: NOTICE_CREATOR,
130
+ budget_exhausted: NOTICE_CREATOR,
131
+ file_ceiling: NOTICE_CREATOR,
132
+ stopped_by_user: STOPPED,
133
+ plan_coverage_refused: NOTICE_ADMINS,
134
+ billing_refused: EXPLAINED,
135
+ drive_auth: EXPLAINED,
136
+ drive_unavailable: EXPLAINED,
137
+ no_connection: EXPLAINED,
138
+ source_sync_off: EXPLAINED,
139
+ internal_error: EXPLAINED,
140
+ abandoned: EXPLAINED,
141
+ unrecognized_terminal_state: NOTICE_ADMINS,
142
+ } as const satisfies Record<DiscoverOutcomeReason, DeferredRoute>;
143
+
144
+ export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
145
+ // prettier-ignore
146
+ updates_ready: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
147
+ // prettier-ignore
148
+ updates_applied: { route: "covered", by: "sourceSync.docs_updated", fallback: "notice", audience: "creator" },
149
+ stopped_by_user: STOPPED,
150
+ paused_billing: EXPLAINED,
151
+ synthesis_incomplete: NOTICE_ADMINS,
152
+ approval_mismatch: NOTICE_ADMINS,
153
+ landing_refused: NOTICE_ADMINS,
154
+ standing_order_refused: NOTICE_ADMINS,
155
+ no_connection: EXPLAINED,
156
+ source_sync_off: EXPLAINED,
157
+ internal_error: NOTICE_ADMINS,
158
+ abandoned: NOTICE_ADMINS,
159
+ unrecognized_terminal_state: NOTICE_ADMINS,
160
+ } as const satisfies Record<SynthesizeOutcomeReason, DeferredRoute>;
161
+
162
+ export const ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON = {
163
+ // prettier-ignore
164
+ proposal_ready: { route: "covered", by: "orgStructure.review_ready", fallback: "notice", audience: "creator" },
165
+ directory_synced: NOTICE_CREATOR,
166
+ analysis_already_running: NOTICE_CREATOR,
167
+ proposal_blocked: NOTICE_ADMINS,
168
+ // `empty`, so never explained, even though it offers a directory sync.
169
+ no_sync_run: NOTICE_ADMINS,
170
+ no_persons: NOTICE_CREATOR,
171
+ reporting_not_keyed: NOTICE_CREATOR,
172
+ stopped_by_user: STOPPED,
173
+ sync_failed: EXPLAINED,
174
+ snapshot_too_large: NOTICE_ADMINS,
175
+ model_failed: EXPLAINED,
176
+ run_too_large: NOTICE_ADMINS,
177
+ placement_failed: EXPLAINED,
178
+ internal_error: EXPLAINED,
179
+ abandoned: EXPLAINED,
180
+ unrecognized_terminal_state: NOTICE_ADMINS,
181
+ } as const satisfies Record<OrgStructureOutcomeReason, DeferredRoute>;
182
+
183
+ /** Every workflow type's route table, total over the type union. */
184
+ export const WORKFLOW_DEFERRED_ROUTE_OF_REASON = {
185
+ "source-sync/discover": DISCOVER_DEFERRED_ROUTE_OF_REASON,
186
+ "source-sync/synthesize": SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
187
+ "org-structure/hris-connect": ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
188
+ "org-structure/reanalyze": ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
189
+ } as const satisfies {
190
+ readonly [T in WorkflowType]: Record<
191
+ WorkflowOutcomeOf<T>["reason"],
192
+ DeferredRoute
193
+ >;
194
+ };
195
+
196
+ type ExplainedReasonOf<T> = {
197
+ [R in keyof T]: T[R] extends { readonly route: "explained" } ? R : never;
198
+ }[keyof T];
199
+
200
+ export type ExplainedDiscoverReason = ExplainedReasonOf<
201
+ typeof DISCOVER_DEFERRED_ROUTE_OF_REASON
202
+ >;
203
+ export type ExplainedSynthesizeReason = ExplainedReasonOf<
204
+ typeof SYNTHESIZE_DEFERRED_ROUTE_OF_REASON
205
+ >;
206
+ export type ExplainedOrgStructureReason = ExplainedReasonOf<
207
+ typeof ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON
208
+ >;
209
+
210
+ type FactFree<O, R> = Omit<O, "reason" | "facts"> & {
211
+ readonly reason: R;
212
+ readonly facts: null;
213
+ };
214
+
215
+ /** An outcome a pushed chat may carry: an explained reason, facts stripped. */
216
+ export type ExplainedWorkflowOutcome =
217
+ | FactFree<DiscoverWorkflowOutcome, ExplainedDiscoverReason>
218
+ | FactFree<SynthesizeWorkflowOutcome, ExplainedSynthesizeReason>
219
+ | FactFree<HrisConnectWorkflowOutcome, ExplainedOrgStructureReason>
220
+ | FactFree<ReanalyzeWorkflowOutcome, ExplainedOrgStructureReason>;
221
+
222
+ /** The route an outcome takes when it has no launching conversation. */
223
+ export function deferredRouteOf(outcome: WorkflowOutcome): DeferredRoute {
224
+ const table = WORKFLOW_DEFERRED_ROUTE_OF_REASON[
225
+ outcome.workflowType
226
+ ] as Record<string, DeferredRoute>;
227
+ return table[outcome.reason] as DeferredRoute;
228
+ }
229
+
230
+ /**
231
+ * The fact-free outcome a pushed chat may carry, or null when the ending's
232
+ * route is not `explained`. Stripping facts keeps the outcome schema-valid
233
+ * (`facts` is nullable) and leaves the frozen affordances untouched.
234
+ */
235
+ export function toExplainedOutcome(
236
+ outcome: WorkflowOutcome,
237
+ ): ExplainedWorkflowOutcome | null {
238
+ if (deferredRouteOf(outcome).route !== "explained") return null;
239
+ return { ...outcome, facts: null } as ExplainedWorkflowOutcome;
240
+ }
@@ -29,13 +29,16 @@ export type {
29
29
  } from "./outcome";
30
30
 
31
31
  export {
32
+ DISCOVER_AFFORDANCES_OF_REASON,
32
33
  DISCOVER_OUTCOME_KIND_OF_REASON,
33
34
  DiscoverOutcomeFactsSchema,
34
35
  DiscoverWorkflowOutcomeSchema,
35
36
  HrisConnectWorkflowOutcomeSchema,
37
+ ORG_STRUCTURE_AFFORDANCES_OF_REASON,
36
38
  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
37
39
  OrgStructureOutcomeFactsSchema,
38
40
  ReanalyzeWorkflowOutcomeSchema,
41
+ SYNTHESIZE_AFFORDANCES_OF_REASON,
39
42
  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
40
43
  SynthesizeOutcomeFactsSchema,
41
44
  SynthesizeWorkflowOutcomeSchema,
@@ -43,3 +46,34 @@ export {
43
46
  WorkflowOutcomeDispositionSchema,
44
47
  WorkflowOutcomeSchema,
45
48
  } from "./outcome";
49
+
50
+ export {
51
+ WORKFLOW_AFFORDANCES_OF_REASON,
52
+ affordancesOfOutcome,
53
+ affordancesOfReason,
54
+ } from "./affordances-of-outcome";
55
+
56
+ export type {
57
+ DeferredRoute,
58
+ DeferredRouteKind,
59
+ ExplainedDiscoverReason,
60
+ ExplainedOrgStructureReason,
61
+ ExplainedSynthesizeReason,
62
+ ExplainedWorkflowOutcome,
63
+ SettlementAudiencePolicy,
64
+ SettlementCoveringKind,
65
+ } from "./deferred-route";
66
+
67
+ export {
68
+ DEFERRED_ROUTES,
69
+ DISCOVER_DEFERRED_ROUTE_OF_REASON,
70
+ DeferredRouteSchema,
71
+ ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
72
+ SETTLEMENT_AUDIENCE_POLICIES,
73
+ SETTLEMENT_COVERING_KINDS,
74
+ SETTLEMENT_SILENT_REASONS,
75
+ SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
76
+ WORKFLOW_DEFERRED_ROUTE_OF_REASON,
77
+ deferredRouteOf,
78
+ toExplainedOutcome,
79
+ } from "./deferred-route";
@@ -22,6 +22,11 @@
22
22
  * on; `narrate` means the ending is told, not reviewed. `produced` does not
23
23
  * imply a review surface, and only a `produced` or `partial` outcome may carry
24
24
  * `review`.
25
+ * - THE OFFER IS A FUNCTION OF REASON. `affordances` is the ordered list of
26
+ * next steps the ending offers (control ADR affordance-system), fixed by the
27
+ * per-type `*_AFFORDANCES_OF_REASON` table and frozen with the outcome. The
28
+ * schema refuses any other list. A projected affordance (`review.open`) is
29
+ * never stored here: it is derived from the `review` disposition.
25
30
  * - `unknown` IS A SAFETY VALVE for a terminal transition the classifier did not
26
31
  * recognize. It is never used for a failure to OBSERVE a workflow: a workflow
27
32
  * whose state cannot be read has no outcome yet.
@@ -32,6 +37,12 @@
32
37
  */
33
38
  import { z } from "zod";
34
39
 
40
+ import {
41
+ MAX_OFFERED_AFFORDANCES,
42
+ OfferedAffordanceSchema,
43
+ sameAffordances,
44
+ type OfferedAffordance,
45
+ } from "../affordances/affordance";
35
46
  import { INPUT_REQUEST_TYPES } from "../input-requests/types";
36
47
 
37
48
  /** The shape of an ending, shared by every workflow type. */
@@ -74,6 +85,14 @@ export type WorkflowOutcomeDisposition = z.infer<
74
85
 
75
86
  const Count = z.number().int().nonnegative();
76
87
 
88
+ // The affordances an ending may offer, named once for the tables below.
89
+ const FIND_FILES = { id: "sourceSync.findFiles" } as const;
90
+ const CONNECT_GOOGLE_DRIVE = { id: "integrations.connectGoogleDrive" } as const;
91
+ const ENABLE_SOURCE_SYNC = { id: "sourceSync.enable" } as const;
92
+ const OPEN_BILLING = { id: "billing.open" } as const;
93
+ const REANALYZE_STRUCTURE = { id: "orgStructure.reanalyze" } as const;
94
+ const RESYNC_DIRECTORY = { id: "hris.resyncDirectory" } as const;
95
+
77
96
  // ---------------------------------------------------------------------------
78
97
  // source-sync/discover
79
98
  // ---------------------------------------------------------------------------
@@ -100,6 +119,32 @@ export const DISCOVER_OUTCOME_KIND_OF_REASON = {
100
119
  export type DiscoverOutcomeReason =
101
120
  keyof typeof DISCOVER_OUTCOME_KIND_OF_REASON;
102
121
 
122
+ /**
123
+ * What each discovery ending offers (control ADR affordance-system). TOTAL: an
124
+ * empty list is a decision that no grounded action changes that ending — a
125
+ * re-run of the same search is not "broadening" it, and nothing raises a budget.
126
+ */
127
+ export const DISCOVER_AFFORDANCES_OF_REASON = {
128
+ candidates_found: [],
129
+ nothing_found: [],
130
+ nothing_relevant: [],
131
+ budget_exhausted: [],
132
+ file_ceiling: [],
133
+ stopped_by_user: [],
134
+ plan_coverage_refused: [],
135
+ billing_refused: [OPEN_BILLING],
136
+ drive_auth: [CONNECT_GOOGLE_DRIVE],
137
+ drive_unavailable: [FIND_FILES],
138
+ no_connection: [CONNECT_GOOGLE_DRIVE],
139
+ source_sync_off: [ENABLE_SOURCE_SYNC],
140
+ internal_error: [FIND_FILES],
141
+ abandoned: [FIND_FILES],
142
+ unrecognized_terminal_state: [],
143
+ } as const satisfies Record<
144
+ DiscoverOutcomeReason,
145
+ readonly OfferedAffordance[]
146
+ >;
147
+
103
148
  /** The counts a discovery run reports at its end. */
104
149
  export const DiscoverOutcomeFactsSchema = z
105
150
  .object({
@@ -139,6 +184,26 @@ export const SYNTHESIZE_OUTCOME_KIND_OF_REASON = {
139
184
  export type SynthesizeOutcomeReason =
140
185
  keyof typeof SYNTHESIZE_OUTCOME_KIND_OF_REASON;
141
186
 
187
+ /** What each synthesis ending offers. TOTAL; an empty list is explicit. */
188
+ export const SYNTHESIZE_AFFORDANCES_OF_REASON = {
189
+ updates_ready: [],
190
+ updates_applied: [],
191
+ stopped_by_user: [],
192
+ paused_billing: [OPEN_BILLING],
193
+ synthesis_incomplete: [],
194
+ approval_mismatch: [],
195
+ landing_refused: [],
196
+ standing_order_refused: [],
197
+ no_connection: [CONNECT_GOOGLE_DRIVE],
198
+ source_sync_off: [ENABLE_SOURCE_SYNC],
199
+ internal_error: [],
200
+ abandoned: [],
201
+ unrecognized_terminal_state: [],
202
+ } as const satisfies Record<
203
+ SynthesizeOutcomeReason,
204
+ readonly OfferedAffordance[]
205
+ >;
206
+
142
207
  /** The counts a synthesis run reports at its end. */
143
208
  export const SynthesizeOutcomeFactsSchema = z
144
209
  .object({
@@ -185,6 +250,32 @@ export const ORG_STRUCTURE_OUTCOME_KIND_OF_REASON = {
185
250
  export type OrgStructureOutcomeReason =
186
251
  keyof typeof ORG_STRUCTURE_OUTCOME_KIND_OF_REASON;
187
252
 
253
+ /**
254
+ * What each org-structure ending offers; shared by both org-structure workflow
255
+ * types, like the kind table. TOTAL; an empty list is explicit.
256
+ */
257
+ export const ORG_STRUCTURE_AFFORDANCES_OF_REASON = {
258
+ proposal_ready: [],
259
+ directory_synced: [],
260
+ analysis_already_running: [],
261
+ proposal_blocked: [],
262
+ no_sync_run: [RESYNC_DIRECTORY],
263
+ no_persons: [],
264
+ reporting_not_keyed: [],
265
+ stopped_by_user: [],
266
+ sync_failed: [RESYNC_DIRECTORY],
267
+ snapshot_too_large: [],
268
+ model_failed: [REANALYZE_STRUCTURE],
269
+ run_too_large: [],
270
+ placement_failed: [REANALYZE_STRUCTURE],
271
+ internal_error: [REANALYZE_STRUCTURE],
272
+ abandoned: [REANALYZE_STRUCTURE],
273
+ unrecognized_terminal_state: [],
274
+ } as const satisfies Record<
275
+ OrgStructureOutcomeReason,
276
+ readonly OfferedAffordance[]
277
+ >;
278
+
188
279
  /** The counts a finished org-structure proposal carries. */
189
280
  export const OrgStructureOutcomeFactsSchema = z
190
281
  .object({
@@ -207,7 +298,12 @@ function memberSchema<
207
298
  T extends string,
208
299
  R extends Record<string, WorkflowOutcomeKind>,
209
300
  F extends z.ZodTypeAny,
210
- >(workflowType: T, kindOfReason: R, facts: F) {
301
+ >(
302
+ workflowType: T,
303
+ kindOfReason: R,
304
+ facts: F,
305
+ affordancesOfReason: Record<keyof R, readonly OfferedAffordance[]>,
306
+ ) {
211
307
  const reasons = Object.keys(kindOfReason) as [
212
308
  keyof R & string,
213
309
  ...(keyof R & string)[],
@@ -221,6 +317,10 @@ function memberSchema<
221
317
  reason: z.enum(reasons),
222
318
  facts: facts.nullable(),
223
319
  disposition: WorkflowOutcomeDispositionSchema,
320
+ /** The next steps this ending offers, frozen with it (see the table). */
321
+ affordances: z
322
+ .array(OfferedAffordanceSchema)
323
+ .max(MAX_OFFERED_AFFORDANCES),
224
324
  })
225
325
  .strict()
226
326
  .superRefine((outcome, ctx) => {
@@ -243,6 +343,15 @@ function memberSchema<
243
343
  message: "only a produced or partial outcome may hand off to review",
244
344
  });
245
345
  }
346
+ const offered = affordancesOfReason[outcome.reason as keyof R];
347
+ if (!sameAffordances(outcome.affordances, offered)) {
348
+ ctx.addIssue({
349
+ code: z.ZodIssueCode.custom,
350
+ path: ["affordances"],
351
+ message:
352
+ "an outcome offers exactly its reason's affordances, in order",
353
+ });
354
+ }
246
355
  });
247
356
  }
248
357
 
@@ -250,21 +359,25 @@ export const DiscoverWorkflowOutcomeSchema = memberSchema(
250
359
  "source-sync/discover",
251
360
  DISCOVER_OUTCOME_KIND_OF_REASON,
252
361
  DiscoverOutcomeFactsSchema,
362
+ DISCOVER_AFFORDANCES_OF_REASON,
253
363
  );
254
364
  export const SynthesizeWorkflowOutcomeSchema = memberSchema(
255
365
  "source-sync/synthesize",
256
366
  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
257
367
  SynthesizeOutcomeFactsSchema,
368
+ SYNTHESIZE_AFFORDANCES_OF_REASON,
258
369
  );
259
370
  export const HrisConnectWorkflowOutcomeSchema = memberSchema(
260
371
  "org-structure/hris-connect",
261
372
  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
262
373
  OrgStructureOutcomeFactsSchema,
374
+ ORG_STRUCTURE_AFFORDANCES_OF_REASON,
263
375
  );
264
376
  export const ReanalyzeWorkflowOutcomeSchema = memberSchema(
265
377
  "org-structure/reanalyze",
266
378
  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
267
379
  OrgStructureOutcomeFactsSchema,
380
+ ORG_STRUCTURE_AFFORDANCES_OF_REASON,
268
381
  );
269
382
 
270
383
  export type DiscoverWorkflowOutcome = z.infer<