@company-semantics/contracts 0.24.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "private": false,
   "repository": {
     "type": "git",
@@ -59,6 +59,9 @@
     "test": "vitest run scripts/ci/__tests__"
   },
   "packageManager": "pnpm@10.25.0",
+  "engines": {
+    "node": "22.x"
+  },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "husky": "^9.1.7",

package/src/guards/config.ts

@@ -392,6 +392,8 @@ export interface GuardCheckRegistry {
     structural?: BoundGuardCheck[];
     behavioral?: BoundGuardCheck[];
     invariants?: BoundGuardCheck[];
+    /** Evolution guards: drift detection (advisory only) */
+    evolution?: BoundGuardCheck[];
     /** Meta-guards: protect the guard system itself (coverage correctness) */
     meta?: BoundGuardCheck[];
   };

package/src/index.ts

@@ -99,4 +99,34 @@ export type {
   MCPToolDescriptor,
   ToolDiscoveryResponse,
   ToolListMessagePart,
+  ToolListDataPart,
 } from './mcp/index.js'
+
+// Message part types and builder functions
+// @see ADR-2026-01-022 for design rationale
+export type {
+  TextPart,
+  ToolListPart,
+  StatusPanelPart,
+  StatusPanelEntry,
+  ChartPart,
+  ChartDataPoint,
+  TablePart,
+  ConfirmationPart,
+  SurfacePart,
+  AssistantMessagePart,
+  PartBuilderState,
+  AddPartResult,
+} from './message-parts/index.js'
+
+export {
+  isTextPart,
+  isSurfacePart,
+  createPartBuilder,
+  addText,
+  addSurface,
+  addPart,
+  buildParts,
+  getDroppedCount,
+  WireSurfaceBuilder,
+} from './message-parts/index.js'

package/src/mcp/index.ts

@@ -4,6 +4,10 @@
  * Types for tool discovery flow (read-only, UI-first).
  * Same descriptor used for discovery and invocation, different fields matter.
  *
+ * TWO SHAPES (same conceptual data, different layers):
+ * - ToolDiscoveryResponse: HTTP transport (GET /api/capabilities/tools response)
+ * - ToolListMessagePart: Chat protocol (atomic message part in conversation)
+ *
  * INVARIANTS:
  * - Discovery is descriptive (never executes)
  * - Invocation is authoritative (runtime is executor)
@@ -83,3 +87,17 @@ export interface ToolListMessagePart {
   type: 'tool-list'
   tools: MCPToolDescriptor[]
 }
+
+/**
+ * Wire protocol type for tool list data part.
+ *
+ * Transport-level type (SSE stream part).
+ * Uses AI SDK's `data-{name}` convention for custom data parts.
+ *
+ * The `data-` prefix signals to the AI SDK that this is a custom data part.
+ * Frontend normalizes this to `tool-list` for semantic handling.
+ */
+export interface ToolListDataPart {
+  type: 'data-tool-list'
+  data: { tools: MCPToolDescriptor[] }
+}

package/src/message-parts/builder.ts

@@ -0,0 +1,186 @@
+/**
+ * Part Builder Functions
+ *
+ * Functional builder for constructing well-ordered message parts.
+ * Enforces invariant: narrative (text) parts before surface parts.
+ *
+ * STATE MACHINE MODEL:
+ * PartBuilder implements a two-state machine:
+ *
+ *   NarrativeState → accepts text or surface
+ *   SurfaceState   → accepts surface only (text rejected)
+ *
+ * Transitions are one-way. Once the first surface is added,
+ * the turn is in "surface phase" permanently.
+ *
+ * This prevents "post-surface commentary" features from sneaking in.
+ *
+ * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ */
+
+import type { AssistantMessagePart, TextPart, SurfacePart } from './types.js'
+
+// =============================================================================
+// Builder State
+// =============================================================================
+
+/**
+ * Immutable state for the part builder.
+ * Tracks collected parts and whether surfaces have been added.
+ */
+export interface PartBuilderState {
+  /** Collected parts in order */
+  readonly parts: readonly AssistantMessagePart[]
+  /** Whether any surface part has been added (true = SurfaceState) */
+  readonly hasSurface: boolean
+  /** Whether dev mode is enabled (throws on invariant violation) */
+  readonly devMode: boolean
+  /** Count of dropped text parts (for logging) */
+  readonly droppedCount: number
+}
+
+/**
+ * Result of adding a part to the builder.
+ */
+export interface AddPartResult {
+  /** Updated builder state */
+  state: PartBuilderState
+  /** Whether the part was accepted (false = dropped) */
+  accepted: boolean
+}
+
+// =============================================================================
+// Builder Creation
+// =============================================================================
+
+/**
+ * Create a new part builder state.
+ *
+ * @param devMode - If true, throws on invariant violations. If false, silently drops.
+ * @returns Initial builder state (NarrativeState)
+ *
+ * @example
+ * const state = createPartBuilder(process.env.NODE_ENV !== 'production');
+ */
+export function createPartBuilder(devMode = false): PartBuilderState {
+  return {
+    parts: [],
+    hasSurface: false,
+    devMode,
+    droppedCount: 0,
+  }
+}
+
+// =============================================================================
+// Part Addition
+// =============================================================================
+
+/**
+ * Add a text part to the builder.
+ *
+ * INVARIANT: Text parts MUST come before surface parts.
+ * - Dev mode: throws Error if text added after surface
+ * - Prod mode: silently drops, increments droppedCount
+ *
+ * @param state - Current builder state
+ * @param text - Text content to add
+ * @returns Result with updated state and acceptance status
+ *
+ * @example
+ * let state = createPartBuilder();
+ * const result = addText(state, "Hello, world!");
+ * state = result.state;
+ */
+export function addText(state: PartBuilderState, text: string): AddPartResult {
+  const part: TextPart = { type: 'text', text }
+
+  if (state.hasSurface) {
+    if (state.devMode) {
+      throw new Error(
+        'PartBuilder invariant violation: text part added after surface part. ' +
+          'Narrative content must come before structured surfaces. ' +
+          `Parts so far: ${state.parts.length}, dropped: ${state.droppedCount}`
+      )
+    }
+    // Prod mode: drop silently
+    return {
+      state: { ...state, droppedCount: state.droppedCount + 1 },
+      accepted: false,
+    }
+  }
+
+  return {
+    state: { ...state, parts: [...state.parts, part] },
+    accepted: true,
+  }
+}
+
+/**
+ * Add a surface part to the builder.
+ *
+ * Surface parts mark the transition from NarrativeState to SurfaceState.
+ * After a surface is added, subsequent text parts are rejected.
+ *
+ * @param state - Current builder state
+ * @param part - Surface part to add
+ * @returns Result with updated state (always accepted)
+ *
+ * @example
+ * let state = createPartBuilder();
+ * state = addSurface(state, { type: 'tool-list', tools: [...] }).state;
+ */
+export function addSurface(
+  state: PartBuilderState,
+  part: SurfacePart
+): AddPartResult {
+  return {
+    state: {
+      ...state,
+      parts: [...state.parts, part],
+      hasSurface: true,
+    },
+    accepted: true,
+  }
+}
+
+/**
+ * Add any message part to the builder.
+ * Dispatches to addText or addSurface based on part type.
+ *
+ * @param state - Current builder state
+ * @param part - Part to add
+ * @returns Result with updated state and acceptance status
+ */
+export function addPart(
+  state: PartBuilderState,
+  part: AssistantMessagePart
+): AddPartResult {
+  if (part.type === 'text') {
+    return addText(state, part.text)
+  }
+  return addSurface(state, part)
+}
+
+// =============================================================================
+// Builder Finalization
+// =============================================================================
+
+/**
+ * Extract the final parts array from the builder.
+ *
+ * @param state - Final builder state
+ * @returns Array of message parts in correct order
+ */
+export function buildParts(state: PartBuilderState): AssistantMessagePart[] {
+  return [...state.parts]
+}
+
+/**
+ * Get count of dropped parts (useful for logging/metrics).
+ *
+ * @param state - Builder state
+ * @returns Number of parts dropped due to invariant violations
+ */
+export function getDroppedCount(state: PartBuilderState): number {
+  return state.droppedCount
+}

package/src/message-parts/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Message Parts Barrel
+ *
+ * Re-exports message part vocabulary types and builder functions.
+ * Import from '@company-semantics/contracts' (root).
+ */
+
+// Types
+export type {
+  TextPart,
+  ToolListPart,
+  StatusPanelPart,
+  StatusPanelEntry,
+  ChartPart,
+  ChartDataPoint,
+  TablePart,
+  ConfirmationPart,
+  SurfacePart,
+  AssistantMessagePart,
+} from './types.js'
+
+// Type guards
+export { isTextPart, isSurfacePart } from './types.js'
+
+// Builder functions
+export type { PartBuilderState, AddPartResult } from './builder.js'
+export {
+  createPartBuilder,
+  addText,
+  addSurface,
+  addPart,
+  buildParts,
+  getDroppedCount,
+} from './builder.js'
+
+// Wire format builder
+export { WireSurfaceBuilder } from './wire.js'

package/src/message-parts/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Message Parts Vocabulary
+ *
+ * Canonical types for structured assistant message output.
+ * Enables rich UI rendering beyond plain text.
+ *
+ * INVARIANTS:
+ * - Narrative (text) parts MUST come before surface parts
+ * - SurfacePart is an extensible union (add new kinds as needed)
+ * - TextPart is the ONLY part type that may be streamed char-by-char
+ * - Once a surface is added, the turn is in "surface phase" permanently
+ *
+ * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ */
+
+import type { ToolListMessagePart } from '../mcp/index.js'
+
+// =============================================================================
+// Narrative Parts (Streamable)
+// =============================================================================
+
+/**
+ * Text content part.
+ * The only part type that MAY be streamed character-by-character.
+ *
+ * Design: Aligns with AI SDK's TextPart for interoperability.
+ */
+export interface TextPart {
+  type: 'text'
+  /** The text content (may be partial during streaming) */
+  text: string
+}
+
+// =============================================================================
+// Surface Parts (Atomic, Non-Streamable)
+// =============================================================================
+
+/**
+ * Re-export ToolListMessagePart as ToolListPart for consistency.
+ */
+export type ToolListPart = ToolListMessagePart
+
+/**
+ * Status panel surface part.
+ * Displays system status, connection states, or progress indicators.
+ */
+export interface StatusPanelPart {
+  type: 'status-panel'
+  /** Panel title */
+  title: string
+  /** Status entries */
+  entries: StatusPanelEntry[]
+}
+
+/**
+ * Single entry in a status panel.
+ */
+export interface StatusPanelEntry {
+  /** Entry label */
+  label: string
+  /** Current status */
+  status: 'ok' | 'warning' | 'error' | 'pending'
+  /** Optional detail text */
+  detail?: string
+}
+
+/**
+ * Chart surface part.
+ * Renders a data visualization.
+ */
+export interface ChartPart {
+  type: 'chart'
+  /** Chart type */
+  chartType: 'bar' | 'line' | 'pie' | 'area'
+  /** Chart title */
+  title?: string
+  /** Data points */
+  data: ChartDataPoint[]
+}
+
+/**
+ * Single data point for charts.
+ */
+export interface ChartDataPoint {
+  label: string
+  value: number
+  /** Optional color (CSS color string) */
+  color?: string
+}
+
+/**
+ * Table surface part.
+ * Renders tabular data.
+ */
+export interface TablePart {
+  type: 'table'
+  /** Table title */
+  title?: string
+  /** Column headers */
+  headers: string[]
+  /** Row data (each row is an array of cell values) */
+  rows: string[][]
+}
+
+/**
+ * Confirmation request surface part.
+ * Requests user confirmation before proceeding.
+ */
+export interface ConfirmationPart {
+  type: 'confirmation'
+  /** What is being confirmed */
+  action: string
+  /** Optional details */
+  details?: string
+  /** Confirmation ID for response tracking */
+  confirmationId: string
+}
+
+// =============================================================================
+// Part Unions
+// =============================================================================
+
+/**
+ * Surface parts are rendered atomically (never streamed).
+ * Extensible: add new surface types to this union.
+ */
+export type SurfacePart =
+  | ToolListPart
+  | StatusPanelPart
+  | ChartPart
+  | TablePart
+  | ConfirmationPart
+
+/**
+ * All assistant message part types.
+ * Union of narrative (text) and surface parts.
+ */
+export type AssistantMessagePart = TextPart | SurfacePart
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Type guard for TextPart.
+ */
+export function isTextPart(part: AssistantMessagePart): part is TextPart {
+  return part.type === 'text'
+}
+
+/**
+ * Type guard for SurfacePart.
+ */
+export function isSurfacePart(part: AssistantMessagePart): part is SurfacePart {
+  return part.type !== 'text'
+}

package/src/message-parts/wire.ts

@@ -0,0 +1,40 @@
+/**
+ * Wire Surface Builder
+ *
+ * Factory functions for creating wire-format surface parts.
+ * These follow AI SDK's `data-{name}` convention for custom data parts.
+ *
+ * Use these in backend code when writing to UIMessageStream.
+ * Frontend normalizes wire format to semantic types.
+ *
+ * @see DECISIONS.md ADR-2026-01-022 for design rationale
+ */
+
+import type { MCPToolDescriptor, ToolListDataPart } from '../mcp/index.js'
+
+/**
+ * Factory for creating wire-format surface parts.
+ *
+ * Wire parts use AI SDK's `data-{name}` type convention.
+ * These are transport-level types, not semantic types.
+ *
+ * @example
+ * // In ChatService.ts
+ * import { WireSurfaceBuilder } from '@company-semantics/contracts';
+ * writer.write(WireSurfaceBuilder.toolList(userTools));
+ */
+export const WireSurfaceBuilder = {
+  /**
+   * Build a tool-list data part for streaming.
+   * Use after LLM text stream completes.
+   *
+   * @param tools - Array of tool descriptors to include
+   * @returns Wire-format tool list part ready for stream
+   */
+  toolList(tools: MCPToolDescriptor[]): ToolListDataPart {
+    return {
+      type: 'data-tool-list',
+      data: { tools },
+    }
+  },
+} as const