@company-semantics/contracts 91.0.0 → 92.0.0

package/src/source-sync/__tests__/schemas.test.ts

@@ -140,11 +140,6 @@ function candidateSet(overrides: Record<string, unknown> = {}) {
       filesPendingClassification: 0,
     },
     scopes: [],
-    estimate: {
-      lowMicroUsd: "250000",
-      highMicroUsd: "1250000",
-      capMicroUsd: "2000000",
-    },
     discovery: {
       foundThisRun: 12,
       retainedDecisions: 3,
@@ -264,38 +259,16 @@ describe("SourceSyncCandidateItemSchema", () => {
 });
 
 describe("SourceSyncCandidateSetResponseSchema", () => {
-  it("accepts an estimate as integer micro-USD strings and refuses a decimal", () => {
+  it("accepts the draft set", () => {
     expect(
       SourceSyncCandidateSetResponseSchema.safeParse(candidateSet()).success,
     ).toBe(true);
-    const decimal = candidateSet({
-      estimate: {
-        lowMicroUsd: "0.25",
-        highMicroUsd: "1250000",
-        capMicroUsd: "2000000",
-      },
-    });
-    expect(
-      SourceSyncCandidateSetResponseSchema.safeParse(decimal).success,
-    ).toBe(false);
-    const jsonNumber = candidateSet({
-      estimate: {
-        lowMicroUsd: "250000",
-        highMicroUsd: "1250000",
-        capMicroUsd: 2000000,
-      },
-    });
-    expect(
-      SourceSyncCandidateSetResponseSchema.safeParse(jsonNumber).success,
-    ).toBe(false);
   });
 
-  it("accepts a null estimate before the estimator has run", () => {
-    expect(
-      SourceSyncCandidateSetResponseSchema.safeParse(
-        candidateSet({ estimate: null }),
-      ).success,
-    ).toBe(true);
+  it("carries no cost estimate: the review authorizes files, never a spend", () => {
+    expect(SourceSyncCandidateSetResponseSchema.shape).not.toHaveProperty(
+      "estimate",
+    );
   });
 
   it("refuses an unknown set state", () => {

package/src/source-sync/schemas.ts

@@ -30,9 +30,6 @@ import {
 import { CandidateDiscoverySummarySchema } from "./relevance";
 import { SourceSyncCandidateItemSchema } from "./candidate-item";
 
-/** Integer micro-USD as a string — the billing domain's money convention on the wire. */
-const MicroUsd = z.string().regex(/^[0-9]+$/);
-
 /** A person as the review names them: a display label, never an id or an address. */
 const PersonLabel = z.string().min(1).max(255);
 
@@ -109,14 +106,6 @@ export const SourceSyncCandidateSetResponseSchema = z.object({
   totals: SourceSyncCandidateTotalsSchema,
   /** Every scope of the set the caller may see, and where its approval stands. */
   scopes: z.array(SourceSyncScopeApprovalProjectionSchema).max(500),
-  /** A RANGE, and the cap that is the promise. Null until the estimator has run. */
-  estimate: z
-    .object({
-      lowMicroUsd: MicroUsd,
-      highMicroUsd: MicroUsd,
-      capMicroUsd: MicroUsd,
-    })
-    .nullable(),
   /** The last completed discovery run's counts; null before any run completed. */
   discovery: z.nullable(CandidateDiscoverySummarySchema),
 });
@@ -134,13 +123,14 @@ export const SourceSyncAddCandidateRequestSchema = z
 
 /**
  * Approve the set AS REVIEWED. `revision` is the revision the person was looking at; the server
- * refuses a stale one, freezes the items, and hashes them PER SCOPE with that scope's share of the cap.
+ * refuses a stale one, freezes the items, and hashes them PER SCOPE.
+ *
+ * An approval authorizes the files, never a spend: there is no cap and no estimate here. Spend is
+ * bounded by the org's standing spending controls and a server-derived run ceiling.
  */
 export const SourceSyncApproveRequestSchema = z
   .object({
     revision: z.number().int().min(0),
-    /** The promise: synthesis stops at this. Integer micro-USD. */
-    spendCapMicroUsd: MicroUsd,
     /** Absent: every scope the caller may approve (all of them for the single v1 approver). */
     scopeKeys: z.array(z.string().min(1).max(64)).min(1).max(500).optional(),
   })
@@ -151,7 +141,7 @@ export const SourceSyncScopeApprovalSchema = z.object({
   /** 'company' or 'unit:<uuid>'. */
   scopeKey: z.string().min(1).max(64),
   approvalId: z.string().uuid(),
-  /** Hash over THIS scope's ordered (source, target, use, observation) tuples and its share of the cap. */
+  /** Hash over THIS scope's ordered (source, target, use, observation) tuples. */
   candidateSetHash: z.string().regex(/^[0-9a-f]{64}$/),
 });
 
@@ -285,6 +275,7 @@ export const SOURCE_SYNC_SYNTHESIS_PHASES = [
   "drafting",
   "waiting_for_review",
   "paused_billing",
+  "paused_ceiling",
   "applied",
   "applied_partial",
   "failed",

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. */
@@ -148,6 +150,8 @@ export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
   updates_applied: { route: "covered", by: "sourceSync.docs_updated", fallback: "notice", audience: "creator" },
   stopped_by_user: STOPPED,
   paused_billing: EXPLAINED,
+  run_ceiling_reached: NOTICE_ADMINS,
+  pricing_unconfigured: NOTICE_ADMINS,
   synthesis_incomplete: NOTICE_ADMINS,
   approval_mismatch: NOTICE_ADMINS,
   landing_refused: NOTICE_ADMINS,

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,248 @@
+/**
+ * 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",
+  run_ceiling_reached: "failed",
+  pricing_unconfigured: "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],
+  run_ceiling_reached: [],
+  pricing_unconfigured: [],
+  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
+>;