@company-semantics/contracts 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -53,12 +53,17 @@
     "guard:scripts-deps": "npx tsx scripts/ci/scripts-deps-guard.ts",
     "guard:version-tag": "npx tsx scripts/ci/version-tag-guard.ts",
     "guard:version-tag:json": "npx tsx scripts/ci/version-tag-guard.ts --json",
+    "guard:decisions-deprecation": "npx tsx scripts/ci/decisions-deprecation-guard.ts",
+    "guard:decisions-deprecation:json": "npx tsx scripts/ci/decisions-deprecation-guard.ts --json",
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
     "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

@@ -8,7 +8,7 @@
  * Each repo provides its own config values; shared guards consume them.
  */
 
-import type { CheckResult } from './types.js';
+import type { CheckResult, Soc2ControlArea } from './types.js';
 
 // =============================================================================
 // Size Limits
@@ -376,6 +376,115 @@ export interface SubdirectoryAffinityBaseline {
   ignoredDirectories?: string[];
 }
 
+// =============================================================================
+// SOC 2 Guard Configuration Types
+// =============================================================================
+
+/**
+ * Configuration for the secrets detection guard.
+ * This is a blocking control for SOC 2 Access Control (AC).
+ */
+export interface SecretsDetectionConfig {
+  /** Source directory to scan (relative to repo root) */
+  srcDir?: string;
+  /** Additional directories to scan */
+  additionalDirs?: string[];
+  /** File patterns to exclude (globs) */
+  excludePatterns?: string[];
+  /** Additional secret patterns to detect (regex strings) */
+  additionalPatterns?: string[];
+}
+
+/**
+ * Configuration for the structured logging guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface StructuredLoggingConfig {
+  /** Entry point files to check (relative to repo root) */
+  entryPoints?: string[];
+  /** Source directory to scan for logging (fallback if no entry points) */
+  srcDir?: string;
+  /** Recognized logging libraries */
+  loggingLibraries?: string[];
+  /** Logger instantiation patterns (regex strings) */
+  instantiationPatterns?: string[];
+}
+
+/**
+ * Configuration for the alerts config guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface AlertsConfigGuardConfig {
+  /**
+   * Files or directories to check for alerting configuration.
+   * Supports both file paths and directory paths.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't have alerting (e.g., pure libraries).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when alerting is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * Configuration for the backup config guard.
+ * This is a non-blocking control for SOC 2 Backup & Recovery (BR).
+ */
+export interface BackupConfigGuardConfig {
+  /**
+   * Files or directories to check for backup configuration.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't manage backups (e.g., frontend-only).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when backup check is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * SOC 2 compliance baselines.
+ * Configures SOC 2 control guards for a repository.
+ *
+ * Design: Product repos provide data only; CI orchestrator owns guard implementations.
+ */
+export interface Soc2Baselines {
+  /** Enable SOC 2 compliance reporting */
+  enabled?: boolean;
+  /** Advisory mode: all controls become non-blocking for visibility-only rollout */
+  advisoryMode?: boolean;
+  /** Repository name (for evidence) */
+  repository?: string;
+  /** Secrets detection configuration */
+  secretsDetection?: SecretsDetectionConfig;
+  /** Structured logging configuration */
+  structuredLogging?: StructuredLoggingConfig;
+  /** Alerts config configuration */
+  alertsConfig?: AlertsConfigGuardConfig;
+  /** Backup config configuration */
+  backupConfig?: BackupConfigGuardConfig;
+  /** Controls to explicitly skip (with evidence) */
+  skipControls?: {
+    area: Soc2ControlArea;
+    evidence: string;
+  }[];
+  /**
+   * Controls that remain blocking even in advisory mode.
+   * Use to gradually promote controls from advisory to blocking.
+   * Example: ['AC'] to make secrets-detection blocking first.
+   */
+  alwaysBlockingControls?: Soc2ControlArea[];
+}
+
 /**
  * Registry of checks grouped by tier.
  * Each repo exports this from guard-entries.ts for universal orchestration.

package/src/guards/index.ts

@@ -54,6 +54,12 @@ export type {
   FileClusterBaseline,
   SubdirectoryAffinityBaseline,
   MetaBaselines,
+  // SOC 2 Guard Configuration types
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
 } from './config.js';
 
 // Config constants (type-level defaults)

package/src/index.ts

@@ -70,6 +70,17 @@ export type {
   ContractsFreshnessBaseline,
   CoverageBaseline,
   MetaBaselines,
+  // SOC 2 Compliance types
+  Soc2ControlArea,
+  Soc2ControlStatus,
+  Soc2ControlResult,
+  Soc2ComplianceOutput,
+  // SOC 2 Guard Configuration types
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
 } from './guards/index.js'
 
 export {
@@ -78,6 +89,11 @@ export {
   DEFAULT_SKIP_DIRECTORIES,
   DEFAULT_DOMAIN_SECTIONS,
   DEFAULT_INFRA_SECTIONS,
+  // SOC 2 Compliance constants
+  SOC2_CONTROL_NAMES,
+  REQUIRED_SOC2_CONTROLS,
+  BLOCKING_SOC2_CONTROLS,
+  SOC2_SCHEMA_VERSION,
 } from './guards/index.js'
 
 // Compatibility manifest (CI guard vocabulary)
@@ -99,4 +115,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

@@ -87,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