@company-semantics/contracts 62.5.0 → 62.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.5.0",
+  "version": "62.7.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -139,8 +139,8 @@
     "node": "22.x"
   },
   "dependencies": {
-    "@slack/types": "^3.0.0",
-    "zod": "^4.4.3"
+    "@slack/types": "^3.1.0",
+    "zod": "^4.5.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -149,13 +149,13 @@
     "culori": "^4.0.2",
     "eslint": "^10.9.0",
     "husky": "^9.1.7",
-    "lint-staged": "^17.3.0",
+    "lint-staged": "^17.4.1",
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
     "tsx": "^4.23.12",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",
     "yaml": "^2.9.0"

package/src/__tests__/iso-datetime.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import {
+  ISO_DATETIME_OFFSET_PATTERN,
+  ISO_DATETIME_PATTERN,
+  IsoDateTime,
+  IsoDateTimeWithOffset,
+} from "../api/primitives";
+
+/**
+ * These are drift alarms, not unit tests.
+ *
+ * `IsoDateTime` delegates to zod's built-in RFC 3339 regex, and zod is advanced
+ * automatically by Dependabot inside a grouped `minor`/`patch` bump. That is
+ * exactly how the seconds-optional -> seconds-mandatory tightening reached
+ * production undocumented (backend #520). If zod moves this regex again, the
+ * documented format of every `format: date-time` field on the public API moves
+ * with it — so it fails here first and gets ratified deliberately.
+ *
+ * If one of these fails: do not update the constant to make it green. Work out
+ * what zod changed, decide whether we want it, and record the decision.
+ */
+describe("the RFC 3339 wire contract is pinned, not inherited", () => {
+  it("emits the pinned pattern for the Z-only form", () => {
+    expect(z.toJSONSchema(IsoDateTime, { io: "input" }).pattern).toBe(
+      ISO_DATETIME_PATTERN,
+    );
+  });
+
+  it("emits the pinned pattern for the offset-allowing form", () => {
+    expect(z.toJSONSchema(IsoDateTimeWithOffset, { io: "input" }).pattern).toBe(
+      ISO_DATETIME_OFFSET_PATTERN,
+    );
+  });
+
+  it("still emits format: date-time, which the pattern alone would not carry", () => {
+    expect(z.toJSONSchema(IsoDateTime, { io: "input" }).format).toBe(
+      "date-time",
+    );
+  });
+});
+
+describe("seconds are mandatory (ADR-CONTRACTS-156)", () => {
+  it.each([
+    "2026-09-01T12:00:00Z",
+    "2026-09-01T12:00:00.000Z",
+    "2024-02-29T23:59:59Z",
+  ])("accepts %s", (value) => {
+    expect(IsoDateTime.safeParse(value).success).toBe(true);
+  });
+
+  it.each(["2026-09-01T12:00Z", "2026-09-01T12Z", "2026-09-01"])(
+    "rejects %s",
+    (value) => {
+      expect(IsoDateTime.safeParse(value).success).toBe(false);
+    },
+  );
+
+  it("rejects a numeric offset on the Z-only form", () => {
+    expect(IsoDateTime.safeParse("2026-09-01T12:00:00+02:00").success).toBe(
+      false,
+    );
+  });
+
+  it("accepts a numeric offset on the offset-allowing form", () => {
+    expect(
+      IsoDateTimeWithOffset.safeParse("2026-09-01T12:00:00+02:00").success,
+    ).toBe(true);
+  });
+});

package/src/admin/direct-grants.ts

@@ -7,12 +7,13 @@
  * direct-grant-audit-trail and the `direct-grant-audit` CI guard).
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 export const DirectGrantCreate = z.object({
   subject_id: z.string().uuid(),
   scope_pattern: z.string(),
   resource_filter: z.record(z.string(), z.unknown()).optional(),
-  expires_at: z.string().datetime().optional(),
+  expires_at: IsoDateTime.optional(),
 });
 
 export type DirectGrantCreate = z.infer<typeof DirectGrantCreate>;
@@ -24,8 +25,8 @@ export const DirectGrant = z.object({
   scope_pattern: z.string(),
   source: z.literal("direct"),
   granted_by: z.string().uuid(),
-  granted_at: z.string().datetime(),
-  expires_at: z.string().datetime().nullable(),
+  granted_at: IsoDateTime,
+  expires_at: IsoDateTime.nullable(),
 });
 
 export type DirectGrant = z.infer<typeof DirectGrant>;

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 = '2933a0834a99' as const;
-export const SPEC_HASH_FULL = '2933a0834a99c8c5e38751cc8127ead37642d7e57bd91f5ab37aae991bfd5a3b' as const;
+export const SPEC_HASH = '52d89a463432' as const;
+export const SPEC_HASH_FULL = '52d89a4634328ae80200c221d6aa25d8c34c9d09208a2c460d82a523ec79144d' as const;

package/src/api/generated.ts

@@ -6795,9 +6795,8 @@ export interface components {
                     p95ContextTokens: number;
                     medianReadsAfterFirstEdit: number;
                 }[];
-                bySource: ({
+                bySource: {
                     source: string;
-                } & {
                     p95Reads?: number;
                     p50Reads?: number;
                     p95ContextTokens?: number;
@@ -6809,7 +6808,7 @@ export interface components {
                     navMapUsageBySource?: {
                         [key: string]: number;
                     };
-                })[];
+                }[];
                 trend: {
                     recent: {
                         p95Reads?: number;

package/src/api/primitives.ts

@@ -25,3 +25,47 @@ export type CursorPage<T> = {
   hasMore: boolean;
 };
 export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+
+// =============================================================================
+// The RFC 3339 timestamp contract
+// =============================================================================
+//
+// Every `format: date-time` field on the public API surface is built from one of
+// the two schemas below, so the wire contract has exactly one definition site.
+//
+// The validators delegate to zod's built-in `.datetime()` rather than
+// reimplementing RFC 3339 by hand: that keeps `format: date-time` in the emitted
+// OpenAPI document and avoids a hand-rolled regex drifting from the runtime
+// check. The regex zod produces is therefore an *input* to our published
+// contract, and zod is a transitive dependency that Dependabot advances
+// automatically — so the emitted pattern is pinned below and asserted in
+// `src/__tests__/iso-datetime.test.ts`.
+//
+// That assertion is the point. A zod release that changes this regex changes the
+// documented format of 52 public fields; it must fail a test and be ratified,
+// not land silently inside a grouped `minor`/`patch` bump. See ADR-CONTRACTS-156.
+
+/** Emitted `pattern` for {@link IsoDateTime}. Pinned — see the note above. */
+export const ISO_DATETIME_PATTERN =
+  "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$";
+
+/** Emitted `pattern` for {@link IsoDateTimeWithOffset}. Pinned — see the note above. */
+export const ISO_DATETIME_OFFSET_PATTERN =
+  "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$";
+
+/**
+ * A UTC RFC 3339 timestamp — `2026-09-01T12:00:00.000Z`.
+ *
+ * Seconds are mandatory. `2026-09-01T12:00Z` is rejected: it is not valid
+ * RFC 3339, and the backend has rejected it since zod 4.5.x.
+ */
+export const IsoDateTime = z.string().datetime();
+
+/**
+ * An RFC 3339 timestamp that may carry a numeric UTC offset instead of `Z` —
+ * `2026-09-01T12:00:00.000+02:00`.
+ *
+ * Use only where a client legitimately reports local wall-clock time with its
+ * offset. Prefer {@link IsoDateTime} for anything the server mints.
+ */
+export const IsoDateTimeWithOffset = z.string().datetime({ offset: true });

package/src/chat/README.md

@@ -89,7 +89,6 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `InvalidateChatListEventSchema`
 - `InvalidationReason` _(type)_ — Reason for cache invalidation.
 - `InvalidationReasonSchema`
-- `IsoDateString` — ISO 8601 datetime string — the runtime safety net for date serialization.
 - `ListSharesResponse` _(type)_ — Response for GET /api/chats/:chatId/shares
 - `ListSharesResponseSchema` — Response for GET /api/chats/:chatId/shares
 - `ProactiveChatResolution` _(type)_ — Resolving an occurrence id to the CURRENT reader's chat — one of the four bounded states `ready` (with…
@@ -117,6 +116,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 
 **Internal domains:**
 
+- `api`
 - `proactive`
 
 **External packages:**

package/src/chat/index.ts

@@ -61,7 +61,6 @@ export type {
 // =============================================================================
 
 export {
-  IsoDateString,
   ChatVisibilitySchema,
   TitleSourceSchema,
   InvalidationReasonSchema,

package/src/chat/schemas.ts

@@ -1,11 +1,5 @@
 import { z } from "zod";
-
-// =============================================================================
-// Reusable Primitives
-// =============================================================================
-
-/** ISO 8601 datetime string — the runtime safety net for date serialization. */
-export const IsoDateString = z.string().datetime();
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // Enums
@@ -78,15 +72,15 @@ export const ChatSummarySchema = z.object({
   id: z.string(),
   title: z.string().nullable(),
   messageCount: z.number().int(),
-  createdAt: IsoDateString,
-  updatedAt: IsoDateString,
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
   isShared: z.boolean(),
 });
 
 export const ChatSummaryExtendedSchema = ChatSummarySchema.extend({
-  pinnedAt: IsoDateString.nullable(),
+  pinnedAt: IsoDateTime.nullable(),
   titleSource: TitleSourceSchema.nullable(),
-  titleGeneratedAt: IsoDateString.nullable(),
+  titleGeneratedAt: IsoDateTime.nullable(),
   ...proactiveChatFields,
 });
 
@@ -129,7 +123,7 @@ export const ChatShareInfoSchema = z.object({
   shareUrl: z.string().optional(),
   messageCountAtShare: z.number().int(),
   titleAtShare: z.string(),
-  createdAt: IsoDateString,
+  createdAt: IsoDateTime,
   createdByName: z.string(),
   isRevoked: z.boolean(),
 });
@@ -137,7 +131,7 @@ export const ChatShareInfoSchema = z.object({
 export const SharedChatViewSchema = z.object({
   title: z.string(),
   messages: z.array(SharedChatMessageSchema),
-  sharedAt: IsoDateString,
+  sharedAt: IsoDateTime,
   sharedByName: z.string(),
   visibility: ChatVisibilitySchema,
 });
@@ -148,7 +142,7 @@ export const SharedChatViewSchema = z.object({
 
 export const BaseEventSchema = z.object({
   v: z.literal(1),
-  timestamp: IsoDateString,
+  timestamp: IsoDateTime,
   eventId: z.string().optional(),
 });
 
@@ -167,10 +161,10 @@ export const ChatCreatedEventSchema = BaseEventSchema.extend({
     interactionId: z.string().optional(),
     title: z.string(),
     titleSource: TitleSourceSchema,
-    pinnedAt: IsoDateString.nullable(),
+    pinnedAt: IsoDateTime.nullable(),
     messageCount: z.number().int(),
-    createdAt: IsoDateString,
-    updatedAt: IsoDateString,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
     isShared: z.boolean(),
     ...proactiveChatFields,
   }),
@@ -182,11 +176,11 @@ export const ChatUpdatedEventSchema = BaseEventSchema.extend({
     chatId: z.string(),
     title: z.string(),
     titleSource: TitleSourceSchema.nullable(),
-    titleGeneratedAt: IsoDateString.nullable(),
-    pinnedAt: IsoDateString.nullable(),
+    titleGeneratedAt: IsoDateTime.nullable(),
+    pinnedAt: IsoDateTime.nullable(),
     messageCount: z.number().int(),
-    createdAt: IsoDateString,
-    updatedAt: IsoDateString,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
     isShared: z.boolean(),
     ...proactiveChatFields,
   }),
@@ -245,7 +239,7 @@ export const ChatMessageSchema = z.object({
   content: z.string(),
   parts: z.array(z.unknown()).optional(),
   sequenceNumber: z.number().int(),
-  createdAt: IsoDateString,
+  createdAt: IsoDateTime,
 });
 
 // =============================================================================
@@ -325,11 +319,11 @@ export const ChatDetailSchema = z.object({
   id: z.string(),
   title: z.string(),
   interactionId: z.string(),
-  pinnedAt: IsoDateString.nullable().optional(),
+  pinnedAt: IsoDateTime.nullable().optional(),
   titleSource: TitleSourceSchema.nullable().optional(),
-  titleGeneratedAt: IsoDateString.nullable().optional(),
-  createdAt: IsoDateString,
-  updatedAt: IsoDateString,
+  titleGeneratedAt: IsoDateTime.nullable().optional(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
   // Opening the detail is what clears `unread`; the detail carries the flag so
   // the reader can tell a first open from a return visit. `proactiveKind` is
   // a list concern (the sidebar row) and does not ride the detail.

package/src/execution/README.md

@@ -102,6 +102,7 @@ TypeScript types and registry for execution kinds and their governance metadata.
 
 **Internal domains:**
 
+- `api`
 - `message-parts`
 
 **External packages:**

package/src/execution/schemas.ts

@@ -8,6 +8,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 
 import type { ExecutionResultData } from "../message-parts/execution";
 import type { ExecutionKind } from "./kinds";
@@ -22,8 +23,8 @@ export const ExecutionSummarySchema = z.object({
   executionId: z.string().uuid(),
   kind: z.string(),
   status: z.enum(["pending", "succeeded", "failed"]),
-  decidedAt: z.string().datetime({ offset: true }),
-  completedAt: z.string().datetime({ offset: true }).optional(),
+  decidedAt: IsoDateTimeWithOffset,
+  completedAt: IsoDateTimeWithOffset.optional(),
   target: z.object({ type: z.string() }),
 });
 

package/src/execution/sse.ts

@@ -15,6 +15,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 import { ExecutionEventTypeSchema } from "./events";
 import { ExecutionStateSchema } from "./status";
 
@@ -27,7 +28,7 @@ export const ExecutionSseEventSchema = z.object({
   /** Coarse actor class that produced the event (e.g. `user`, `system`). */
   actorType: z.string(),
   /** DB insert time of the event, ISO-8601 with offset. */
-  createdAt: z.string().datetime({ offset: true }),
+  createdAt: IsoDateTimeWithOffset,
 });
 
 export type ExecutionSseEvent = z.infer<typeof ExecutionSseEventSchema>;

package/src/identity/README.md

@@ -88,6 +88,7 @@ TypeScript types and functions for user identity and display name resolution.
 
 **Internal domains:**
 
+- `api`
 - `org`
 
 **External packages:**

package/src/identity/identity-link.ts

@@ -17,6 +17,7 @@
  * @see ADR-CONT-032 for identity vocabulary design rationale
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // IdentityLink — external system id → Person
@@ -31,8 +32,8 @@ export const IdentityLinkSchema = z.object({
   externalId: z.string().min(1),
   // The Person this external identity resolves to (Person.id).
   personId: z.string().uuid(),
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
 });
 
 export type IdentityLink = z.infer<typeof IdentityLinkSchema>;

package/src/impersonation/schemas.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 
 export const ImpersonationSessionSchema = z.object({
   impersonationSessionId: z.string(),
@@ -16,9 +17,9 @@ export const ImpersonationSessionSchema = z.object({
   targetUserId: z.string(),
   reason: z.string(),
   reasonHash: z.string(),
-  startedAt: z.string().datetime({ offset: true }),
-  expiresAt: z.string().datetime({ offset: true }),
-  endedAt: z.string().datetime({ offset: true }).nullable(),
+  startedAt: IsoDateTimeWithOffset,
+  expiresAt: IsoDateTimeWithOffset,
+  endedAt: IsoDateTimeWithOffset.nullable(),
   ipAddress: z.string(),
   userAgent: z.string(),
 });
@@ -48,9 +49,9 @@ export const ImpersonationSessionWireDtoSchema = z
   .object({
     id: z.string(),
     targetUserId: z.string(),
-    startedAt: z.string().datetime({ offset: true }),
-    expiresAt: z.string().datetime({ offset: true }),
-    endedAt: z.string().datetime({ offset: true }).nullable(),
+    startedAt: IsoDateTimeWithOffset,
+    expiresAt: IsoDateTimeWithOffset,
+    endedAt: IsoDateTimeWithOffset.nullable(),
   })
   .strict();
 

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/integrations/README.md

@@ -47,7 +47,7 @@ alongside `Meetings`, `Comms`, and `Docs`.
 
 **Internal domains:**
 
-_None._
+- `api`
 
 **External packages:**
 

package/src/integrations/schemas.ts

@@ -16,6 +16,7 @@
  * stringified JSON blobs on the schema.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // HR connection status
@@ -87,7 +88,7 @@ export const HrConnectionStatusSchema = z
       description:
         "Departments mirrored from the HR provider; null when never synced.",
     }),
-    lastSyncAt: z.string().datetime().nullable().meta({
+    lastSyncAt: IsoDateTime.nullable().meta({
       description: "ISO timestamp of the last successful sync; null if never.",
     }),
     syncHealth: z.enum(["healthy", "degraded", "error"]).nullable().meta({

package/src/meetings/schemas.ts

@@ -21,6 +21,7 @@
  * stringified JSON blobs on the schema.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // Recording identity
@@ -237,7 +238,7 @@ export const TranscriptionSessionGrantSchema = z
     sessionId: RecordingIdSchema,
     connectUrl: z.string().url(),
     authHeaders: z.record(z.string(), z.string()),
-    expiresAt: z.string().datetime(),
+    expiresAt: IsoDateTime,
     audioConfig: z.object({
       sampleRateHz: z.literal(16000),
       channels: z.literal(2),
@@ -279,8 +280,8 @@ export const MeetingMetadataProjectionSchema = z
     visibility: MeetingVisibilitySchema,
     status: RecordingStatusSchema,
     quality: RecordingQualitySchema,
-    startedAt: z.string().datetime(),
-    endedAt: z.string().datetime().nullable(),
+    startedAt: IsoDateTime,
+    endedAt: IsoDateTime.nullable(),
     durationMs: z.number().int().nonnegative(),
     participantUserIds: z.array(z.string().uuid()),
     transcriptAvailable: z.boolean(),

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/org/occupancy.ts

@@ -25,6 +25,7 @@
  * account.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 import { FactProvenanceSchema } from "./structure-facts";
 
@@ -60,9 +61,9 @@ export const OccupancySchema = z.object({
   /** Lifecycle of this hold; only `active` makes the position occupied. */
   status: OccupancyStatusSchema,
   /** ISO start of the hold; `null`/absent when unknown or open-started. */
-  startsAt: z.string().datetime().nullable().optional(),
+  startsAt: IsoDateTime.nullable().optional(),
   /** ISO end of the hold; `null`/absent while the hold is still open. */
-  endsAt: z.string().datetime().nullable().optional(),
+  endsAt: IsoDateTime.nullable().optional(),
   /** Provenance of this occupancy fact (truth hierarchy + supersede model). */
   provenance: FactProvenanceSchema,
 });

package/src/org/reasoning-review.ts

@@ -20,6 +20,7 @@
  * `inferenceType` and is not part of the stable contract surface.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // OrgStructureReviewInference — one pending ('review') structure inference
@@ -43,7 +44,7 @@ export const OrgStructureReviewInferenceSchema = z.object({
   /** Human-meaningful WHY the engine proposed this change. */
   reason: z.string(),
   /** ISO timestamp the inference was created. */
-  createdAt: z.string().datetime(),
+  createdAt: IsoDateTime,
 });
 
 export type OrgStructureReviewInference = z.infer<

package/src/org/reconciliation.ts

@@ -39,6 +39,7 @@
  * remove an entry is the two sides agreeing.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 import { FactSourceTierSchema } from "./structure-facts";
 
@@ -92,7 +93,7 @@ export const OrgDivergenceSchema = z.object({
    */
   reason: z.string().max(2000).nullable(),
   /** ISO timestamp the workspace's current word on this field was recorded. */
-  recordedAt: z.string().datetime(),
+  recordedAt: IsoDateTime,
   /**
    * ISO timestamp someone in this workspace ACKNOWLEDGED this entry, or `null`.
    *
@@ -102,7 +103,7 @@ export const OrgDivergenceSchema = z.object({
    * the entry — arrives unacknowledged, which is the right default for a
    * statement nobody has read yet.
    */
-  acknowledgedAt: z.string().datetime().nullable(),
+  acknowledgedAt: IsoDateTime.nullable(),
   /** Who acknowledged it. `null` when nobody has, or when that user is gone. */
   acknowledgedByUserId: z.string().uuid().nullable(),
 });
@@ -146,7 +147,7 @@ export const ResolveOrgDivergenceResultSchema = z.object({
   /** How it was resolved. Local decisions only — see the module docblock. */
   resolution: OrgDivergenceResolutionSchema,
   /** ISO timestamp the decision was recorded in this workspace. */
-  resolvedAt: z.string().datetime(),
+  resolvedAt: IsoDateTime,
   /**
    * Whether anything was written back to the source system. Pinned to the
    * literal `false`: the HRIS client is read-only and no write scope is

package/src/org/schemas.ts

@@ -11,7 +11,7 @@
  *  - scope-check.ts (GET /api/scope/check, POST /api/scope/check-batch)
  */
 import { z } from "zod";
-import { CursorPageSchema } from "../api/primitives";
+import { CursorPageSchema, IsoDateTime } from "../api/primitives";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 import { PositionRefSchema } from "../identity/position-ref";
 
@@ -1757,7 +1757,7 @@ export const OwnerAuthoritySchema = z.object({
    * the projection read filters `expires_at > now()` — so a present value is
    * always in the future.
    */
-  expiresAt: z.string().datetime().nullable().optional(),
+  expiresAt: IsoDateTime.nullable().optional(),
 });
 export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
 
@@ -1817,7 +1817,7 @@ export const CreateDelegationRequestSchema = z.object({
    * Optional ISO-8601 expiry. Omitted or `null` ⇒ a permanent delegation. The
    * UI captures a date and sends end-of-day in the user's timezone.
    */
-  expiresAt: z.string().datetime().nullable().optional(),
+  expiresAt: IsoDateTime.nullable().optional(),
   /**
    * When true, the granted user is emailed a notification (carrying `note` as
    * the message). Not persisted — it only gates the side-effect email. Omitted
@@ -1836,7 +1836,7 @@ export type CreateDelegationRequest = z.infer<
  * on an existing delegate row.
  */
 export const UpdateDelegationRequestSchema = z.object({
-  expiresAt: z.string().datetime().nullable(),
+  expiresAt: IsoDateTime.nullable(),
 });
 export type UpdateDelegationRequest = z.infer<
   typeof UpdateDelegationRequestSchema

package/src/org/sync-run.ts

@@ -26,6 +26,7 @@
  * nullable string rather than wrapped in a page envelope.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // SyncRunSummary — the outcome record of one adapter sync run
@@ -35,9 +36,9 @@ export const SyncRunSummarySchema = z.object({
   /** Unique identifier for this sync run within the org graph. */
   id: z.string().uuid(),
   /** ISO start of the run. Always set once a run has begun. */
-  startedAt: z.string().datetime(),
+  startedAt: IsoDateTime,
   /** ISO end of the run; `null`/absent while the run is still in progress. */
-  endedAt: z.string().datetime().nullable().optional(),
+  endedAt: IsoDateTime.nullable().optional(),
   /** Count of facts examined by the run (the denominator). */
   processed: z.number().int().nonnegative(),
   /** Count of facts that resulted in a real mutation (insert/supersede). */

package/src/permissions/permission-introspection.ts

@@ -18,6 +18,7 @@
  * permission_decisions; the UI never re-derives.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import { AccessLevelSchema } from "./access-levels";
 import { AccessSourceSchema } from "./access-source";
 import { PrincipalSchema } from "./share-api";
@@ -51,7 +52,7 @@ export const RecentDecisionSchema = z.object({
   allow: z.boolean(),
   reason: z.string(),
   source_chain: z.array(AccessSourceSchema),
-  decided_at: z.string().datetime(),
+  decided_at: IsoDateTime,
 });
 export type RecentDecision = z.infer<typeof RecentDecisionSchema>;
 

package/src/permissions/share-api.ts

@@ -21,6 +21,7 @@
  * changing (ADR-CONTRACTS-093).
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import { AccessLevelSchema } from "./access-levels";
 import { AccessSourceSchema } from "./access-source";
 
@@ -77,7 +78,7 @@ export const AclGrantResponseSchema = z.object({
   principal: PrincipalSchema,
   access_level: GrantableAccessLevelSchema,
   granted_by_user_id: z.string().uuid(),
-  granted_at: z.string().datetime(),
+  granted_at: IsoDateTime,
 });
 export type AclGrantResponse = z.infer<typeof AclGrantResponseSchema>;
 

package/src/security/org-secrets.ts

@@ -13,6 +13,7 @@
  * `./secret.ts`) before storage / encryption.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 /**
  * Usage class of an org secret. Drives which resolver layer is allowed to read
@@ -75,10 +76,10 @@ export const OrgSecretSummarySchema = z.object({
   maskedPrefix: z.string().min(1).max(64),
   version: z.number().int().positive(),
   enabled: z.boolean(),
-  lastUsedAt: z.string().datetime().nullable(),
+  lastUsedAt: IsoDateTime.nullable(),
   usageCount: z.string(),
-  rotatedAt: z.string().datetime().nullable(),
-  createdAt: z.string().datetime(),
+  rotatedAt: IsoDateTime.nullable(),
+  createdAt: IsoDateTime,
 });
 export type OrgSecretSummary = z.infer<typeof OrgSecretSummarySchema>;
 

package/src/user-events/schemas.ts

@@ -29,6 +29,7 @@
  *   stream without first giving it a real commit-ordered log.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import type { ResourceKey } from "../resource-keys";
 import { isResourceKeyShape } from "../resource-keys";
 
@@ -36,7 +37,6 @@ import { isResourceKeyShape } from "../resource-keys";
  * Local, not chat's. `chat/schemas.ts` owns a structurally identical helper;
  * importing it would make a chat frame change a user-events breaking change.
  */
-const IsoDateString = z.string().datetime();
 
 /**
  * Fields every frame carries.
@@ -47,7 +47,7 @@ const IsoDateString = z.string().datetime();
  */
 export const UserEventBaseSchema = z.object({
   v: z.literal(1),
-  timestamp: IsoDateString,
+  timestamp: IsoDateTime,
 });
 
 // =============================================================================

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)
+  );
+}