@company-semantics/contracts 89.0.0 → 89.1.0

package/src/generated/openapi-routes.ts

@@ -94,6 +94,7 @@ export const openApiRoutes = {
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
   '/api/factory/quality/changes': ['POST'],
+  '/api/factory/quality/corpus': ['GET'],
   '/api/factory/quality/deployments': ['POST'],
   '/api/factory/quality/plans/{planId}': ['GET'],
   '/api/factory/quality/plans/{planId}/decision': ['GET'],
@@ -102,6 +103,19 @@ export const openApiRoutes = {
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],
+  '/api/internal-admin/quality/blocked': ['GET'],
+  '/api/internal-admin/quality/candidates': ['GET'],
+  '/api/internal-admin/quality/candidates/{id}': ['GET'],
+  '/api/internal-admin/quality/candidates/{id}/accept': ['POST'],
+  '/api/internal-admin/quality/candidates/{id}/reject': ['POST'],
+  '/api/internal-admin/quality/changes/manual': ['POST'],
+  '/api/internal-admin/quality/escalations': ['GET'],
+  '/api/internal-admin/quality/escalations/{id}/resolve': ['POST'],
+  '/api/internal-admin/quality/plans/{planId}/status': ['GET'],
+  '/api/internal-admin/quality/references/floor': ['PUT'],
+  '/api/internal-admin/quality/spend': ['GET'],
+  '/api/internal-admin/quality/subjects': ['GET'],
+  '/api/internal-admin/quality/subjects/{subjectKind}/{subjectKey}/timeline': ['GET'],
   '/api/me': ['GET'],
   '/api/me/access-list': ['GET'],
   '/api/me/action-items': ['GET'],
@@ -156,6 +170,7 @@ export const openApiRoutes = {
   '/api/org/cancel-deletion': ['POST'],
   '/api/org/delete': ['POST'],
   '/api/org/deletion-eligibility': ['GET'],
+  '/api/org/improve-with-usage': ['GET', 'PUT'],
   '/api/org/reconciliation': ['GET'],
   '/api/org/reconciliation/divergences/{divergenceId}/resolution': ['POST'],
   '/api/org/structure-findings': ['GET'],

package/src/message-parts/README.md

@@ -91,6 +91,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `UndoResultData` _(type)_ — Undo result data payload.
 - `UndoResultDataPart` _(type)_ — Undo result data part (wire format).
 - `WireSurfaceBuilder` — Factory for creating wire-format surface parts.
+- `WorkflowOutcomeData` _(type)_ — Workflow outcome data payload: which workflow, and how its epoch ended.
+- `WorkflowOutcomeDataPart` _(type)_ — Workflow outcome data part (wire format, as persisted in `chat_messages.parts`).
+- `WorkflowOutcomePart` _(type)_ — Workflow outcome message part (semantic type, as rendered).
 - `WorkflowProgressData` _(type)_ — Workflow progress surface data payload — the anchor's handle and its discriminator.
 - `WorkflowProgressDataPart` _(type)_ — Workflow progress data part (wire format, as persisted in `chat_messages.parts`).
 - `WorkflowProgressPart` _(type)_ — Workflow progress message part (semantic type, as rendered).

package/src/message-parts/__tests__/workflow-outcome.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import { WireSurfaceBuilder } from "../wire";
+import type { WorkflowOutcomeData } from "../workflow-outcome";
+
+describe("WireSurfaceBuilder.workflowOutcome", () => {
+  const data: WorkflowOutcomeData = {
+    workflowId: "3f1c2d4e-0000-0000-0000-000000000000",
+    outcome: {
+      workflowType: "source-sync/discover",
+      executionEpoch: 0,
+      kind: "empty",
+      reason: "nothing_found",
+      facts: {
+        probesTotal: 12,
+        probesDone: 12,
+        filesSeen: 0,
+        filesShown: 0,
+        filesHidden: 0,
+        filesDropped: 0,
+        coveragePercent: 100,
+      },
+      disposition: { kind: "narrate" },
+    },
+  };
+
+  it("returns a data-workflow-outcome part carrying the data verbatim", () => {
+    const part = WireSurfaceBuilder.workflowOutcome(data);
+    expect(part.type).toBe("data-workflow-outcome");
+    expect(part.data).toEqual(data);
+  });
+
+  // Non-governed: nothing on the payload makes it count against the
+  // at-most-one-governed-surface-per-turn budget.
+  it("carries no governed-surface fields", () => {
+    const part = WireSurfaceBuilder.workflowOutcome(data);
+    expect(Object.keys(part.data).sort()).toEqual(["outcome", "workflowId"]);
+    expect(part.data).not.toHaveProperty("executionId");
+    expect(part.data).not.toHaveProperty("submitEndpoint");
+  });
+});

package/src/message-parts/index.ts

@@ -90,6 +90,13 @@ export type {
   WorkflowProgressDataPart,
 } from "./workflow-progress";
 
+// Workflow outcome types (non-governed, the frozen outcome on a settlement message)
+export type {
+  WorkflowOutcomeData,
+  WorkflowOutcomePart,
+  WorkflowOutcomeDataPart,
+} from "./workflow-outcome";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -21,6 +21,7 @@ import type { StructureReviewPart } from "./structure-review";
 import type { InputRequestPart } from "./input-request";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 import type { WorkflowProgressPart } from "./workflow-progress";
+import type { WorkflowOutcomePart } from "./workflow-outcome";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -125,6 +126,10 @@ export interface TablePart {
  * background workflow to the occurrence and presents no decision, so it must
  * not consume the governed-surface budget either.
  *
+ * WorkflowOutcomePart is the third non-governed member: the frozen outcome of a
+ * workflow's execution epoch, carried on its settlement message. It presents no
+ * decision; a review disposition is delivered as its own InputRequestPart.
+ *
  * InputRequestPart is GOVERNED, like StructureReviewPart: it anchors a reviewed
  * request that asks the person to decide, so it counts against the
  * at-most-one-governed-surface-per-turn budget. It is the generic anchor;
@@ -142,7 +147,8 @@ export type SurfacePart =
   | StructureReviewPart
   | InputRequestPart
   | SuggestedRepliesPart
-  | WorkflowProgressPart;
+  | WorkflowProgressPart
+  | WorkflowOutcomePart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -35,6 +35,10 @@ import type {
   WorkflowProgressData,
   WorkflowProgressDataPart,
 } from "./workflow-progress";
+import type {
+  WorkflowOutcomeData,
+  WorkflowOutcomeDataPart,
+} from "./workflow-outcome";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -246,6 +250,28 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build a workflow-outcome data part for a settlement message.
+   * The frozen outcome of one execution epoch, written once at settlement
+   * (control ADR-CTRL-540).
+   *
+   * INVARIANTS:
+   * - Not a governed surface: presents no decision
+   * - The outcome is the classified, immutable value; nothing re-derives it
+   * - Counts and closed codes only, so it is safe on share-visible parts
+   * - Emission is orchestration-driven (settlement delivery), never a model
+   *   choice
+   *
+   * @param data - Workflow outcome data (workflowId + frozen outcome)
+   * @returns Wire-format workflow outcome part
+   */
+  workflowOutcome(data: WorkflowOutcomeData): WorkflowOutcomeDataPart {
+    return {
+      type: "data-workflow-outcome",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/message-parts/workflow-outcome.ts

@@ -0,0 +1,54 @@
+/**
+ * Workflow Outcome Part Types
+ *
+ * The settled outcome of one execution epoch of a durable background workflow,
+ * carried on the settlement message the server writes into the conversation
+ * that launched the workflow (control ADR-CTRL-540). It is the durable,
+ * conversation-level EVIDENCE of how the run ended: the deterministic narration
+ * beside it is built from exactly this value, and a later turn ("what
+ * happened?") is grounded in it.
+ *
+ * WORKFLOW OUTCOME INVARIANTS:
+ * - WRITTEN ONCE, AT SETTLEMENT. Unlike `data-workflow-progress`, which is
+ *   minted at t=0 and so must carry no result, this part is minted only after
+ *   the outcome is frozen, on a message of its own. It can never be stale.
+ * - THE FROZEN OUTCOME, VERBATIM. `outcome` is the value the backend classified
+ *   atomically with the terminal transition. Nothing re-derives it.
+ * - SHARE-SAFE. Chat parts reach token-only share readers verbatim, so the
+ *   outcome holds counts and closed codes only (see `../workflows/outcome.ts`).
+ * - NON-GOVERNED. It presents no decision: no `executionId`, no
+ *   `submitEndpoint`. A `review` disposition is delivered as its own input
+ *   request anchor, not through this part.
+ * - Emission is orchestration-driven (settlement delivery), never a model
+ *   choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part types
+ * to null, drops it, and still renders the narration text.
+ *
+ * @see ../workflows/outcome.ts for the outcome vocabulary
+ */
+
+import type { WorkflowOutcome } from "../workflows/outcome";
+
+/** Workflow outcome data payload: which workflow, and how its epoch ended. */
+export interface WorkflowOutcomeData {
+  /** The durable workflow the outcome settles. */
+  workflowId: string;
+  /** The frozen, typed outcome (carries its workflow type and epoch). */
+  outcome: WorkflowOutcome;
+}
+
+/** Workflow outcome message part (semantic type, as rendered). */
+export interface WorkflowOutcomePart {
+  type: "workflow-outcome";
+  data: WorkflowOutcomeData;
+}
+
+/**
+ * Workflow outcome data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface WorkflowOutcomeDataPart {
+  type: "data-workflow-outcome";
+  data: WorkflowOutcomeData;
+}

package/src/root-exports/agent-runtime.ts

@@ -93,6 +93,10 @@ export type {
   WorkflowProgressData,
   WorkflowProgressPart,
   WorkflowProgressDataPart,
+  // Workflow outcome types (non-governed, frozen outcome on a settlement message, ADR-CTRL-540)
+  WorkflowOutcomeData,
+  WorkflowOutcomePart,
+  WorkflowOutcomeDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,

package/src/root-exports/delivery.ts

@@ -216,3 +216,39 @@ export type {
 export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "../workflows/index";
 
 export type { WorkflowType } from "../workflows/index";
+
+// The typed outcome of a workflow's terminal transition (control ADR-CTRL-540):
+// per-type closed reasons, typed facts and an explicit disposition, classified
+// once by the backend and frozen. See src/workflows/outcome.ts.
+export {
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  DiscoverOutcomeFactsSchema,
+  DiscoverWorkflowOutcomeSchema,
+  HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+  ReanalyzeWorkflowOutcomeSchema,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
+  SynthesizeWorkflowOutcomeSchema,
+  WORKFLOW_OUTCOME_KINDS,
+  WorkflowOutcomeDispositionSchema,
+  WorkflowOutcomeSchema,
+} from "../workflows/index";
+
+export type {
+  DiscoverOutcomeFacts,
+  DiscoverOutcomeReason,
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  OrgStructureOutcomeFacts,
+  OrgStructureOutcomeReason,
+  ReanalyzeWorkflowOutcome,
+  SynthesizeOutcomeFacts,
+  SynthesizeOutcomeReason,
+  SynthesizeWorkflowOutcome,
+  WorkflowOutcome,
+  WorkflowOutcomeDisposition,
+  WorkflowOutcomeKind,
+  WorkflowOutcomeOf,
+} from "../workflows/index";

package/src/workflows/README.md

@@ -32,7 +32,23 @@ 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
+  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
+  explicit `disposition` (`review` or `narrate`). Adding a workflow type means
+  adding its outcome member; the union must cover every registered type.
+- **`unknown` is a safety valve, not a status.** It names an unrecognized
+  terminal transition, never a workflow whose state could not be read.
+
+## 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`).
 
 ## Dependencies
 
-None. Pure vocabulary data and one pure guard; no `zod`, no runtime imports.
+`zod` (outcome schemas) and `../input-requests/types` (the review
+disposition's request type). Otherwise pure vocabulary data and one guard.

package/src/workflows/__tests__/README.md

@@ -13,6 +13,12 @@ wire value against it.
   rejections: a bare `hris-connect` without its namespace, the namespace on
   its own, a trailing separator, an unknown flow, and non-string inputs.
 
+- `outcome.test.ts` — the outcome union covers every registered workflow type
+  (compile-time), each reason table's kinds are valid, the schema accepts a
+  well-formed member and refuses a kind that does not match its reason, a
+  review disposition on a non-produced outcome, a reason from another type,
+  and extra keys (the facts stay closed).
+
 ## Invariants
 
 - These assert VOCABULARY and SHAPE, never behavior. What a workflow of a

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

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+
+import type { WorkflowType } from "../types";
+import {
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  WORKFLOW_OUTCOME_KINDS,
+  WorkflowOutcomeSchema,
+  type WorkflowOutcome,
+} from "../outcome";
+
+// Compile-time: every registered workflow type has an outcome member, and the
+// union names no type that is not registered.
+type MissingOutcome = Exclude<WorkflowType, WorkflowOutcome["workflowType"]>;
+type UnregisteredOutcome = Exclude<
+  WorkflowOutcome["workflowType"],
+  WorkflowType
+>;
+const coversEveryType: [MissingOutcome, UnregisteredOutcome] extends [
+  never,
+  never,
+]
+  ? true
+  : false = true;
+
+const discoverFacts = {
+  probesTotal: 12,
+  probesDone: 12,
+  filesSeen: 0,
+  filesShown: 0,
+  filesHidden: 0,
+  filesDropped: 0,
+  coveragePercent: 100,
+};
+
+const empty = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 0,
+  kind: "empty",
+  reason: "nothing_found",
+  facts: discoverFacts,
+  disposition: { kind: "narrate" },
+} as const;
+
+describe("WorkflowOutcome", () => {
+  it("covers every registered workflow type", () => {
+    expect(coversEveryType).toBe(true);
+  });
+
+  it("maps every reason to a known kind", () => {
+    for (const table of [
+      DISCOVER_OUTCOME_KIND_OF_REASON,
+      SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+      ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+    ]) {
+      for (const kind of Object.values(table)) {
+        expect(WORKFLOW_OUTCOME_KINDS).toContain(kind);
+      }
+      // Every table keeps the two safety endings.
+      expect(table).toHaveProperty("abandoned", "abandoned");
+      expect(table).toHaveProperty("unrecognized_terminal_state", "unknown");
+    }
+  });
+
+  it("accepts a well-formed member", () => {
+    expect(WorkflowOutcomeSchema.safeParse(empty).success).toBe(true);
+  });
+
+  it("accepts null facts (the execution reported none)", () => {
+    const abandoned = {
+      ...empty,
+      kind: "abandoned",
+      reason: "abandoned",
+      facts: null,
+    };
+    expect(WorkflowOutcomeSchema.safeParse(abandoned).success).toBe(true);
+  });
+
+  it("refuses a kind that does not match its reason", () => {
+    expect(
+      WorkflowOutcomeSchema.safeParse({ ...empty, kind: "produced" }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a review disposition on an outcome that produced nothing", () => {
+    const reviewEmpty = {
+      ...empty,
+      disposition: {
+        kind: "review",
+        requestType: "source-sync/candidates",
+        requestId: "set-1",
+      },
+    };
+    expect(WorkflowOutcomeSchema.safeParse(reviewEmpty).success).toBe(false);
+  });
+
+  it("accepts a review disposition on a produced outcome", () => {
+    const produced = {
+      ...empty,
+      kind: "produced",
+      reason: "candidates_found",
+      disposition: {
+        kind: "review",
+        requestType: "source-sync/candidates",
+        requestId: "set-1",
+      },
+    };
+    expect(WorkflowOutcomeSchema.safeParse(produced).success).toBe(true);
+  });
+
+  it("refuses a reason that belongs to another workflow type", () => {
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...empty,
+        kind: "produced",
+        reason: "proposal_ready",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("keeps facts closed: an extra key is refused", () => {
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...empty,
+        facts: { ...discoverFacts, fileNames: 3 },
+      }).success,
+    ).toBe(false);
+  });
+});

package/src/workflows/index.ts

@@ -10,3 +10,36 @@
 export type { WorkflowType } from "./types";
 
 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";
+
+export {
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  DiscoverOutcomeFactsSchema,
+  DiscoverWorkflowOutcomeSchema,
+  HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+  ReanalyzeWorkflowOutcomeSchema,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
+  SynthesizeWorkflowOutcomeSchema,
+  WORKFLOW_OUTCOME_KINDS,
+  WorkflowOutcomeDispositionSchema,
+  WorkflowOutcomeSchema,
+} from "./outcome";