@company-semantics/contracts 62.6.0 → 62.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.6.0",
+  "version": "62.8.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 = '52d89a463432' as const;
-export const SPEC_HASH_FULL = '52d89a4634328ae80200c221d6aa25d8c34c9d09208a2c460d82a523ec79144d' as const;
+export const SPEC_HASH = '71dd78eccef8' as const;
+export const SPEC_HASH_FULL = '71dd78eccef89c2b48c1ac446802164817d850a8c3a5680a3096956f17e59f08' as const;

package/src/api/generated.ts

@@ -4298,6 +4298,11 @@ export interface components {
                 kind: "structure-review";
                 /** Format: uuid */
                 proposalId: string;
+            } | {
+                /** @constant */
+                kind: "workflow";
+                /** Format: uuid */
+                workflowId: string;
             };
         } | {
             /** @constant */
@@ -4326,6 +4331,39 @@ export interface components {
                 kind: "structure-review";
                 /** Format: uuid */
                 proposalId: string;
+            } | {
+                /** @constant */
+                kind: "workflow";
+                /** Format: uuid */
+                workflowId: string;
+            };
+        } | {
+            /** @constant */
+            trigger: "launch";
+            id?: string;
+            message?: unknown;
+            messageId?: unknown;
+            messages?: unknown;
+            runtimeProfile?: string;
+            pageContext?: {
+                route: string;
+                /** @enum {string} */
+                view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "org-settings" | "settings" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                /** @enum {string} */
+                scope: "none" | "me" | "org";
+                entity?: {
+                    /** @enum {string} */
+                    type: "document" | "person" | "chat" | "execution" | "work-item";
+                    id: string;
+                };
+            };
+            /** @enum {string} */
+            origin?: "user" | "proactive";
+            launch: {
+                /** @constant */
+                kind: "workflow";
+                /** Format: uuid */
+                workflowId: string;
             };
         };
         ProactiveChatResolution: {

package/src/index.ts

@@ -367,6 +367,17 @@ export type {
   ProactiveChatMessage,
 } from "./proactive/index";
 
+// Analysis workflows — the registered types a durable long-running analysis
+// can be (PRD-00976). The workflow primitive itself is domain-agnostic; its
+// TYPE is the one place a domain names itself, and that name is a public wire
+// discriminator carried on the workflow row, in the data-workflow-progress
+// chat part and by the generic projection read. Namespaced `<domain>/<flow>`
+// so domains cannot collide, and a CLOSED const array so the discriminator is
+// validated and handled exhaustively. See src/workflows/README.md.
+export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "./workflows/index";
+
+export type { WorkflowType } from "./workflows/index";
+
 // Comment wire contract — where a thread hangs (the anchor union), what a
 // thread and its comments look like on the wire, and who a comment may name.
 // The anchor is the single most load-bearing shape in this package: the backend
@@ -1032,6 +1043,10 @@ export type {
   SuggestedRepliesData,
   SuggestedRepliesPart,
   SuggestedRepliesDataPart,
+  // Workflow progress surface types (non-governed anchor, data-workflow-progress, PRD-00976)
+  WorkflowProgressData,
+  WorkflowProgressPart,
+  WorkflowProgressDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,

package/src/message-parts/README.md

@@ -15,6 +15,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - Execution results carry `state` resolved from ExecutionState (single authority, no redundant status)
 - Undo creates append-only audit rows — original execution is never mutated
 - `SuggestedRepliesPart` is a surface but NOT a governed one: a chip fires an ordinary user turn (no `executionId`, no `submitEndpoint`), is stateless (clicking never consumes it) and advisory (the composer stays enabled) — so it is outside the at-most-one-governed-surface-per-turn rule
+- `WorkflowProgressPart` is the second non-governed surface: a two-field ANCHOR (`workflowId`, `workflowType`) to a durable background workflow. It presents no decision, carries no result snapshot (minted at t=0; parts are never rewritten) and no `startedAt` (operational state stays off immutable content), and names no domain vocabulary — live state is hydrated from the generic workflow projection read
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
@@ -82,6 +83,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.
+- `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).
 - `addPart` — Add any message part to the builder.
 - `addSurface` — Add a surface part to the builder.
 - `addText` — Add a text part to the builder.
@@ -102,6 +106,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 
 - `execution`
 - `mcp`
+- `workflows`
 
 **External packages:**
 

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

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { WireSurfaceBuilder } from "../wire";
+import { isSurfacePart, isTextPart } from "../types";
+import type { AssistantMessagePart, SurfacePart } from "../types";
+import { createPartBuilder, addSurface, addText } from "../builder";
+import type {
+  WorkflowProgressData,
+  WorkflowProgressPart,
+} from "../workflow-progress";
+
+describe("WireSurfaceBuilder.workflowProgress", () => {
+  const data: WorkflowProgressData = {
+    workflowId: "3f1c2d4e-0000-0000-0000-000000000000",
+    workflowType: "org-structure/hris-connect",
+  };
+
+  it("returns data part with type data-workflow-progress", () => {
+    const result = WireSurfaceBuilder.workflowProgress(data);
+    expect(result.type).toBe("data-workflow-progress");
+  });
+
+  it("data matches input WorkflowProgressData exactly", () => {
+    const result = WireSurfaceBuilder.workflowProgress(data);
+    expect(result.data).toEqual(data);
+  });
+
+  // The part is an ANCHOR: a handle plus a discriminator and nothing else.
+  // Pinning the key set catches the two documented regressions — a `result`
+  // snapshot (minted at t=0, it could only ever be empty or stale) or a
+  // `startedAt` (operational state duplicated into immutable content) creeping
+  // onto a durably persisted, share-visible payload.
+  it("workflow-progress carries exactly the anchor keys", () => {
+    const result = WireSurfaceBuilder.workflowProgress(data);
+    expect(Object.keys(result.data).sort()).toEqual([
+      "workflowId",
+      "workflowType",
+    ]);
+    expect(result.data).not.toHaveProperty("result");
+    expect(result.data).not.toHaveProperty("startedAt");
+  });
+
+  // Non-governed: nothing on the payload would make it count against the
+  // at-most-one-governed-surface-per-turn budget.
+  it("carries no governed-surface fields (no executionId, no submitEndpoint)", () => {
+    const result = WireSurfaceBuilder.workflowProgress(data);
+    expect(result.data).not.toHaveProperty("executionId");
+    expect(result.data).not.toHaveProperty("submitEndpoint");
+  });
+
+  // Stateless: building twice from the same facts yields identical output, so
+  // a historical message re-rendered later cannot differ from the original.
+  it("is deterministic across repeated builds", () => {
+    expect(WireSurfaceBuilder.workflowProgress(data)).toEqual(
+      WireSurfaceBuilder.workflowProgress(data),
+    );
+  });
+});
+
+// The semantic part is what the app renders after normalizing the wire part.
+// Typing the fixture as WorkflowProgressPart and then assigning it to
+// SurfacePart is the compile-time proof that the union gained the member.
+const anchor: WorkflowProgressPart = {
+  type: "workflow-progress",
+  data: {
+    workflowId: "3f1c2d4e-0000-0000-0000-000000000000",
+    workflowType: "org-structure/reanalyse",
+  },
+};
+
+describe("WorkflowProgressPart in the SurfacePart union", () => {
+  it("is assignable to SurfacePart and AssistantMessagePart", () => {
+    const asSurface: SurfacePart = anchor;
+    const asPart: AssistantMessagePart = anchor;
+    expect(asSurface.type).toBe("workflow-progress");
+    expect(asPart.type).toBe("workflow-progress");
+  });
+
+  it("is classified as a surface part, not a text part", () => {
+    expect(isSurfacePart(anchor)).toBe(true);
+    expect(isTextPart(anchor)).toBe(false);
+  });
+
+  // The builder's narrative-before-surface state machine applies to the anchor
+  // like any other surface: it is emitted after the prose, never streamed.
+  it("is accepted by addSurface after narrative text", () => {
+    let state = createPartBuilder();
+    state = addText(state, "Analysing your org structure now.").state;
+    const result = addSurface(state, anchor);
+    expect(result.accepted).toBe(true);
+    expect(result.state.parts).toEqual([
+      { type: "text", text: "Analysing your org structure now." },
+      anchor,
+    ]);
+  });
+});

package/src/message-parts/index.ts

@@ -71,6 +71,13 @@ export type {
   SuggestedRepliesDataPart,
 } from "./suggested-replies";
 
+// Workflow progress surface types (non-governed anchor to a durable workflow)
+export type {
+  WorkflowProgressData,
+  WorkflowProgressPart,
+  WorkflowProgressDataPart,
+} from "./workflow-progress";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -19,6 +19,7 @@ import type { ConfirmationPart } from "./confirmation";
 import type { InteractiveTaskPart } from "./interactive";
 import type { StructureReviewPart } from "./structure-review";
 import type { SuggestedRepliesPart } from "./suggested-replies";
+import type { WorkflowProgressPart } from "./workflow-progress";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -118,6 +119,10 @@ export interface TablePart {
  * SuggestedRepliesPart is a surface part but NOT a governed one: a chip fires
  * an ordinary user turn, so it is outside the preview/confirmation/interactive
  * triad and its at-most-one-governed-surface-per-turn rule.
+ *
+ * WorkflowProgressPart is the second non-governed member: it anchors a durable
+ * background workflow to the occurrence and presents no decision, so it must
+ * not consume the governed-surface budget either.
  */
 export type SurfacePart =
   | ToolListPart
@@ -128,7 +133,8 @@ export type SurfacePart =
   | PreviewPart
   | InteractiveTaskPart
   | StructureReviewPart
-  | SuggestedRepliesPart;
+  | SuggestedRepliesPart
+  | WorkflowProgressPart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -25,6 +25,10 @@ import type {
   SuggestedRepliesData,
   SuggestedRepliesDataPart,
 } from "./suggested-replies";
+import type {
+  WorkflowProgressData,
+  WorkflowProgressDataPart,
+} from "./workflow-progress";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -164,6 +168,31 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build a workflow-progress data part for streaming.
+   * The anchor for a durable background workflow attached to this assistant
+   * occurrence: a handle plus the namespaced workflow type, hydrated
+   * client-side from the generic workflow projection read.
+   *
+   * INVARIANTS:
+   * - Not a governed surface: presents no decision, no executionId, no
+   *   submitEndpoint — so it does not count against the
+   *   at-most-one-governed-surface-per-turn rule
+   * - Anchor only: no result snapshot (minted at t=0, parts are never
+   *   rewritten) and no startedAt (operational state stays off immutable
+   *   content)
+   * - Emission is orchestration-driven (a typed launch), never a model choice
+   *
+   * @param data - Workflow progress data (workflowId + workflowType)
+   * @returns Wire-format workflow progress part ready for stream
+   */
+  workflowProgress(data: WorkflowProgressData): WorkflowProgressDataPart {
+    return {
+      type: "data-workflow-progress",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

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

@@ -0,0 +1,66 @@
+/**
+ * Workflow Progress Surface Types
+ *
+ * A durable background workflow attached to an assistant occurrence. The part
+ * tells a renderer "there is long-running work behind this message; render its
+ * progress surface" — and deliberately says nothing about what that work is
+ * analysing. It is a SIBLING of `suggested-replies`: a surface part, but NOT a
+ * governed one.
+ *
+ * WORKFLOW PROGRESS INVARIANTS:
+ * - AN ANCHOR, NOT A PAYLOAD. Chat message parts are persisted verbatim and
+ *   shipped verbatim to token-only share readers, so this carries a handle and
+ *   a type and nothing else. Live and settled state come from one authorized
+ *   read keyed on `workflowId` (the generic workflow projection), never from
+ *   the part.
+ * - NO `result`. The part is minted at t=0, before the workflow has produced
+ *   anything, and `chat_messages.parts` is written once and never rewritten.
+ *   A result snapshot here would be permanently empty or permanently stale.
+ * - NO `startedAt`. It would duplicate operational state into immutable
+ *   message content, and nothing renders it without hydrating the workflow
+ *   anyway.
+ * - NON-GOVERNED. It presents no decision: no `executionId`, no
+ *   `submitEndpoint`, no side effect of its own. So it must NOT count against
+ *   the at-most-one-governed-surface-per-turn budget the chat bridge enforces
+ *   over the preview/confirmation/interactive triad.
+ * - NO DOMAIN VOCABULARY. `workflowType` is the namespaced discriminator from
+ *   `ANALYSIS_WORKFLOW_TYPES`; the part never names a department, proposal,
+ *   provider or person. A domain adapter on the consuming side owns that.
+ * - Emission is orchestration-driven (a typed launch), never a model choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part
+ * types to null, so it drops the anchor and still renders the prose.
+ *
+ * @see ../workflows/types.ts for the registered workflow types
+ * @see decisions/ADR-CONT-026.md for the message-parts design
+ */
+
+import type { WorkflowType } from "../workflows/types";
+
+/**
+ * Workflow progress surface data payload — the anchor's handle and its
+ * discriminator. Both fields required; nothing else is ever carried.
+ */
+export interface WorkflowProgressData {
+  /** The durable workflow this occurrence is attached to. */
+  workflowId: string;
+  /** Which registered flow it is — the namespaced wire discriminator. */
+  workflowType: WorkflowType;
+}
+
+/**
+ * Workflow progress message part (semantic type, as rendered).
+ */
+export interface WorkflowProgressPart {
+  type: "workflow-progress";
+  data: WorkflowProgressData;
+}
+
+/**
+ * Workflow progress data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface WorkflowProgressDataPart {
+  type: "data-workflow-progress";
+  data: WorkflowProgressData;
+}

package/src/workflows/README.md

@@ -0,0 +1,35 @@
+# workflows/
+
+The registry of analysis-workflow types — the one place a domain names the
+long-running work it hands to the durable workflow primitive.
+
+## Purpose
+
+An analysis workflow is a durable, domain-agnostic record of long-running AI
+work (the backend's `analysis_workflows` table). Its lifecycle
+(`pending | running | draining | stopped | complete | failed`) knows nothing
+about departments, proposals or providers. The workflow's TYPE is where a
+domain names itself, and that name travels on the wire: it is stored on the
+workflow row, carried by the `data-workflow-progress` chat message part, and
+answered by the generic projection read. This directory holds that vocabulary
+so every producer, validator and renderer agrees on it.
+
+## Invariants
+
+- **Namespaced as `<domain>/<flow>`.** `org-structure/hris-connect` and a
+  future `org-deck/ingest` cannot collide, and neither learns the other's
+  vocabulary.
+- **Centrally registered.** A second consumer adds one member to
+  `ANALYSIS_WORKFLOW_TYPES` and a progress adapter on its own side; it touches
+  no generic file. These are public wire discriminators, so the coupling is the
+  point — a closed const array gives wire validation and exhaustive handling.
+- **Closed and append-only.** A member is persisted on durable rows and inside
+  immutable chat parts; removing one orphans every record that carries it.
+- **Activity-free.** A type says WHICH flow, never what the flow is currently
+  doing. Activity is domain progress, carried opaquely by the domain.
+- **`isWorkflowType` accepts exact members only.** A bare `hris-connect`
+  without its namespace is rejected.
+
+## Dependencies
+
+None. Pure vocabulary data and one pure guard; no `zod`, no runtime imports.

package/src/workflows/__tests__/README.md

@@ -0,0 +1,30 @@
+# workflows/\_\_tests\_\_/
+
+## Purpose
+
+Locks the registry of analysis-workflow types and the guard that validates a
+wire value against it.
+
+- `types.test.ts` — pins the exact membership of `ANALYSIS_WORKFLOW_TYPES`, so
+  an append or removal is a deliberate diff here rather than a silent change
+  to a public wire discriminator. Asserts every member is namespaced as
+  `<domain>/<flow>` with exactly one separator, which is the collision guard
+  between domains. For `isWorkflowType`, the load-bearing cases are the
+  rejections: a bare `hris-connect` without its namespace, the namespace on
+  its own, a trailing separator, an unknown flow, and non-string inputs.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behaviour. What a workflow of a
+  given type does belongs in the owning domain's suites in backend.
+- The membership test is intentionally exact. Loosening it to "contains" would
+  let a removed member (which orphans persisted rows and immutable chat parts)
+  pass unnoticed.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest` and `../types`.

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

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "../types";
+
+describe("ANALYSIS_WORKFLOW_TYPES", () => {
+  it("contains exactly the two registered org-structure flows", () => {
+    expect([...ANALYSIS_WORKFLOW_TYPES]).toEqual([
+      "org-structure/hris-connect",
+      "org-structure/reanalyse",
+    ]);
+  });
+
+  it("has no duplicates", () => {
+    expect(new Set(ANALYSIS_WORKFLOW_TYPES).size).toBe(
+      ANALYSIS_WORKFLOW_TYPES.length,
+    );
+  });
+
+  // Namespacing is the collision guard between domains: every member must be
+  // `<domain>/<flow>`, with exactly one separator and no empty half.
+  it("every member is namespaced as <domain>/<flow>", () => {
+    for (const type of ANALYSIS_WORKFLOW_TYPES) {
+      expect(type).toMatch(/^[a-z0-9-]+\/[a-z0-9-]+$/);
+    }
+  });
+});
+
+describe("isWorkflowType", () => {
+  it("returns true for every member of ANALYSIS_WORKFLOW_TYPES", () => {
+    for (const type of ANALYSIS_WORKFLOW_TYPES) {
+      expect(isWorkflowType(type)).toBe(true);
+    }
+  });
+
+  it("rejects a bare flow name without its namespace", () => {
+    expect(isWorkflowType("hris-connect")).toBe(false);
+    expect(isWorkflowType("reanalyse")).toBe(false);
+  });
+
+  it("rejects the namespace on its own and unknown flows", () => {
+    expect(isWorkflowType("org-structure")).toBe(false);
+    expect(isWorkflowType("org-structure/")).toBe(false);
+    expect(isWorkflowType("org-structure/unknown")).toBe(false);
+  });
+
+  it("rejects non-string and empty values", () => {
+    expect(isWorkflowType("")).toBe(false);
+    expect(isWorkflowType(undefined)).toBe(false);
+    expect(isWorkflowType(null)).toBe(false);
+    expect(isWorkflowType(42)).toBe(false);
+    expect(isWorkflowType({ type: "org-structure/hris-connect" })).toBe(false);
+  });
+});

package/src/workflows/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Analysis-workflow vocabulary barrel — the registered types a durable
+ * long-running analysis can be.
+ *
+ * Import from '@company-semantics/contracts' (root).
+ *
+ * @see ./types.ts for why the list is namespaced, central and closed
+ */
+
+export type { WorkflowType } from "./types";
+
+export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "./types";

package/src/workflows/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Registered analysis-workflow types.
+ *
+ * An analysis workflow is a durable record of long-running AI work
+ * (`analysis_workflows` in the backend). Its lifecycle is domain-agnostic;
+ * its TYPE is the one place a domain names itself, and that name is a public
+ * wire discriminator: it is stored on the workflow row, carried by the
+ * `data-workflow-progress` chat message part, and returned by the generic
+ * projection read. Public wire values are validated and handled exhaustively,
+ * which is why the list is a closed const array rather than an open string.
+ *
+ * INVARIANTS:
+ * - NAMESPACED as `<domain>/<flow>`. Two domains cannot collide on a bare
+ *   name: `org-structure/hris-connect` and a future `org-deck/ingest` can both
+ *   exist without either learning the other's vocabulary.
+ * - CENTRALLY REGISTERED. A new consumer adds one member here and a domain
+ *   progress adapter on its own side; it touches nothing generic. Central
+ *   registration is the intended coupling, not an accident — the discriminator
+ *   must be knowable to every renderer and validator at once.
+ * - CLOSED and append-only. A member is a persisted value on durable rows and
+ *   in immutable chat parts; removing one orphans every record that carries it.
+ * - Activity-free. A type says WHICH flow; what the flow is currently doing is
+ *   domain progress and never lives in this vocabulary.
+ */
+export const ANALYSIS_WORKFLOW_TYPES = [
+  /** Analyse an org structure freshly connected from an HRIS provider. */
+  "org-structure/hris-connect",
+  /** Re-run the org-structure analysis against an already-connected source. */
+  "org-structure/reanalyse",
+] as const;
+
+/** One registered analysis-workflow type — the wire discriminator. */
+export type WorkflowType = (typeof ANALYSIS_WORKFLOW_TYPES)[number];
+
+/**
+ * Runtime guard for an untrusted value claiming to be a {@link WorkflowType}.
+ * Accepts only exact, namespaced members; a bare flow name is rejected.
+ */
+export function isWorkflowType(value: unknown): value is WorkflowType {
+  return (
+    typeof value === "string" &&
+    (ANALYSIS_WORKFLOW_TYPES as readonly string[]).includes(value)
+  );
+}