@company-semantics/contracts 89.0.0 → 89.1.0

package/src/workflows/outcome.ts

@@ -0,0 +1,299 @@
+/**
+ * The typed outcome of an analysis workflow's terminal transition
+ * (control ADR-CTRL-540, the Workflow Outcome Settlement Invariant).
+ *
+ * The workflow lifecycle says THAT a run ended (`stopped | complete | failed`);
+ * this says WHAT KIND of ending it was, in a vocabulary a renderer, a narrator
+ * and the model can all switch on exhaustively. The backend classifies it ONCE,
+ * atomically with the terminal transition, and persists it immutably; delivery
+ * and every reader consume the frozen value and never re-decide it.
+ *
+ * Zod-canonical: the schemas are the source of truth, the types are inferred.
+ *
+ * INVARIANTS:
+ * - PER-TYPE AND CLOSED. Every workflow type has its own closed `reason` union
+ *   and its own typed `facts`. There is no free-form reason and no open facts
+ *   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.
+ * - 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`.
+ * - `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.
+ * - FACTS ARE COUNTS. Counts and closed codes only, never names, titles, paths
+ *   or content: a settled outcome is persisted into chat parts that token-only
+ *   share readers receive verbatim. `facts` is null when the execution reported
+ *   none (a reconciler abandon, a refusal before the run began).
+ */
+import { z } from "zod";
+
+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];
+
+const KindSchema = z.enum(WORKFLOW_OUTCOME_KINDS);
+
+/** What delivering the outcome does. */
+export const WorkflowOutcomeDispositionSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("review"),
+      requestType: z.enum(INPUT_REQUEST_TYPES),
+      requestId: z.string().min(1),
+    })
+    .strict(),
+  z.object({ kind: z.literal("narrate") }).strict(),
+]);
+
+export type WorkflowOutcomeDisposition = z.infer<
+  typeof WorkflowOutcomeDispositionSchema
+>;
+
+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
+// ---------------------------------------------------------------------------
+
+function memberSchema<
+  T extends string,
+  R extends Record<string, WorkflowOutcomeKind>,
+  F extends z.ZodTypeAny,
+>(workflowType: T, kindOfReason: R, facts: F) {
+  const reasons = Object.keys(kindOfReason) as [
+    keyof R & string,
+    ...(keyof R & string)[],
+  ];
+  return z
+    .object({
+      workflowType: z.literal(workflowType),
+      /** The execution epoch this ending closes (Continue begins the next). */
+      executionEpoch: Count,
+      kind: KindSchema,
+      reason: z.enum(reasons),
+      facts: facts.nullable(),
+      disposition: WorkflowOutcomeDispositionSchema,
+    })
+    .strict()
+    .superRefine((outcome, ctx) => {
+      const expected = kindOfReason[outcome.reason as keyof R];
+      if (outcome.kind !== expected) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["kind"],
+          message: `reason '${String(outcome.reason)}' has kind '${expected}'`,
+        });
+      }
+      if (
+        outcome.disposition.kind === "review" &&
+        outcome.kind !== "produced" &&
+        outcome.kind !== "partial"
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["disposition"],
+          message: "only a produced or partial outcome may hand off to review",
+        });
+      }
+    });
+}
+
+export const DiscoverWorkflowOutcomeSchema = memberSchema(
+  "source-sync/discover",
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  DiscoverOutcomeFactsSchema,
+);
+export const SynthesizeWorkflowOutcomeSchema = memberSchema(
+  "source-sync/synthesize",
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
+);
+export const HrisConnectWorkflowOutcomeSchema = memberSchema(
+  "org-structure/hris-connect",
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+);
+export const ReanalyzeWorkflowOutcomeSchema = memberSchema(
+  "org-structure/reanalyze",
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+);
+
+export type DiscoverWorkflowOutcome = z.infer<
+  typeof DiscoverWorkflowOutcomeSchema
+>;
+export type SynthesizeWorkflowOutcome = z.infer<
+  typeof SynthesizeWorkflowOutcomeSchema
+>;
+export type HrisConnectWorkflowOutcome = z.infer<
+  typeof HrisConnectWorkflowOutcomeSchema
+>;
+export type ReanalyzeWorkflowOutcome = z.infer<
+  typeof ReanalyzeWorkflowOutcomeSchema
+>;
+
+/**
+ * The outcome of one terminal transition of any registered workflow type.
+ * Validate untrusted values (persisted jsonb, wire parts) with
+ * {@link WorkflowOutcomeSchema}.
+ */
+export const WorkflowOutcomeSchema = z.union([
+  DiscoverWorkflowOutcomeSchema,
+  SynthesizeWorkflowOutcomeSchema,
+  HrisConnectWorkflowOutcomeSchema,
+  ReanalyzeWorkflowOutcomeSchema,
+]);
+
+export type WorkflowOutcome = z.infer<typeof WorkflowOutcomeSchema>;
+
+/** The outcome member for one workflow type. */
+export type WorkflowOutcomeOf<T extends WorkflowOutcome["workflowType"]> =
+  Extract<WorkflowOutcome, { workflowType: T }>;