@company-semantics/contracts 9.0.0 → 9.2.0

package/src/message-parts/builder.ts

@@ -18,7 +18,7 @@
  * @see decisions/ADR-CONT-026.md for design rationale
  */
 
-import type { AssistantMessagePart, TextPart, SurfacePart } from './types'
+import type { AssistantMessagePart, TextPart, SurfacePart } from "./types";
 
 // =============================================================================
 // Builder State
@@ -30,13 +30,13 @@ import type { AssistantMessagePart, TextPart, SurfacePart } from './types'
  */
 export interface PartBuilderState {
   /** Collected parts in order */
-  readonly parts: readonly AssistantMessagePart[]
+  readonly parts: readonly AssistantMessagePart[];
   /** Whether any surface part has been added (true = SurfaceState) */
-  readonly hasSurface: boolean
+  readonly hasSurface: boolean;
   /** Whether dev mode is enabled (throws on invariant violation) */
-  readonly devMode: boolean
+  readonly devMode: boolean;
   /** Count of dropped text parts (for logging) */
-  readonly droppedCount: number
+  readonly droppedCount: number;
 }
 
 /**
@@ -44,9 +44,9 @@ export interface PartBuilderState {
  */
 export interface AddPartResult {
   /** Updated builder state */
-  state: PartBuilderState
+  state: PartBuilderState;
   /** Whether the part was accepted (false = dropped) */
-  accepted: boolean
+  accepted: boolean;
 }
 
 // =============================================================================
@@ -68,7 +68,7 @@ export function createPartBuilder(devMode = false): PartBuilderState {
     hasSurface: false,
     devMode,
     droppedCount: 0,
-  }
+  };
 }
 
 // =============================================================================
@@ -92,27 +92,27 @@ export function createPartBuilder(devMode = false): PartBuilderState {
  * state = result.state;
  */
 export function addText(state: PartBuilderState, text: string): AddPartResult {
-  const part: TextPart = { type: 'text', text }
+  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}`
-      )
+        "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,
-  }
+  };
 }
 
 /**
@@ -131,7 +131,7 @@ export function addText(state: PartBuilderState, text: string): AddPartResult {
  */
 export function addSurface(
   state: PartBuilderState,
-  part: SurfacePart
+  part: SurfacePart,
 ): AddPartResult {
   return {
     state: {
@@ -140,7 +140,7 @@ export function addSurface(
       hasSurface: true,
     },
     accepted: true,
-  }
+  };
 }
 
 /**
@@ -153,12 +153,12 @@ export function addSurface(
  */
 export function addPart(
   state: PartBuilderState,
-  part: AssistantMessagePart
+  part: AssistantMessagePart,
 ): AddPartResult {
-  if (part.type === 'text') {
-    return addText(state, part.text)
+  if (part.type === "text") {
+    return addText(state, part.text);
   }
-  return addSurface(state, part)
+  return addSurface(state, part);
 }
 
 // =============================================================================
@@ -172,7 +172,7 @@ export function addPart(
  * @returns Array of message parts in correct order
  */
 export function buildParts(state: PartBuilderState): AssistantMessagePart[] {
-  return [...state.parts]
+  return [...state.parts];
 }
 
 /**
@@ -182,5 +182,5 @@ export function buildParts(state: PartBuilderState): AssistantMessagePart[] {
  * @returns Number of parts dropped due to invariant violations
  */
 export function getDroppedCount(state: PartBuilderState): number {
-  return state.droppedCount
+  return state.droppedCount;
 }

package/src/message-parts/confirmation.ts

@@ -17,32 +17,36 @@
  * @see decisions/ADR-CONT-037.md for design rationale
  */
 
-import type { ExecutionKind } from '../execution/kinds'
+import type { ExecutionKind } from "../execution/kinds";
 
 /**
  * Choice options for confirmation.
  */
-export type ConfirmationChoice = 'confirm' | 'cancel';
+export type ConfirmationChoice = "confirm" | "cancel";
 
 /**
  * Risk level for confirmation prompts.
  * Uses 'moderate' (not 'medium') for semantic precision.
  * 'irreversible' indicates destructive operations that cannot be undone.
  */
-export type ConfirmationRiskLevel = 'low' | 'moderate' | 'high' | 'irreversible';
+export type ConfirmationRiskLevel =
+  | "low"
+  | "moderate"
+  | "high"
+  | "irreversible";
 
 /**
  * Human-readable confirmation dialog titles for each execution kind.
  * Exhaustive — TypeScript enforces completeness via Record type.
  */
 export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
-  'integration.connect': 'Connect Integration',
-  'integration.disconnect': 'Disconnect Integration',
-  'profile.update': 'Update Profile',
-  'slack.send': 'Send Slack Message',
-  'data.ingest': 'Import Channel',
-  'data.scope': 'Update Scope',
-  'system.cleanup': 'Cleanup Connections',
+  "integration.connect": "Connect Integration",
+  "integration.disconnect": "Disconnect Integration",
+  "profile.update": "Update Profile",
+  "slack.send": "Send Slack Message",
+  "data.ingest": "Import Channel",
+  "data.scope": "Update Scope",
+  "system.cleanup": "Cleanup Connections",
 };
 
 /**
@@ -55,7 +59,7 @@ export function getConfirmationLabel(
   if (executorKind && executorKind in CONFIRMATION_LABELS) {
     return CONFIRMATION_LABELS[executorKind];
   }
-  return fallbackTitle ?? 'Confirm Action';
+  return fallbackTitle ?? "Confirm Action";
 }
 
 export interface ConfirmationData {
@@ -86,7 +90,7 @@ export interface ConfirmationResponseData {
 }
 
 export interface ConfirmationPart {
-  type: 'confirmation';
+  type: "confirmation";
   data: ConfirmationData;
 }
 
@@ -94,7 +98,6 @@ export interface ConfirmationPart {
  * Confirmation request data part (wire format).
  */
 export interface ConfirmationDataPart {
-  type: 'data-confirmation';
+  type: "data-confirmation";
   data: ConfirmationData;
 }
-

package/src/message-parts/execution.ts

@@ -27,7 +27,7 @@
  * @see decisions/ADR-CONT-037.md for design rationale
  */
 
-import type { PreviewArtifactKind } from './preview';
+import type { PreviewArtifactKind } from "./preview";
 
 /**
  * Status of a single artifact's execution.
@@ -35,7 +35,7 @@ import type { PreviewArtifactKind } from './preview';
 export interface ExecutionArtifactStatus {
   kind: PreviewArtifactKind;
   label: string;
-  status: 'success' | 'failed' | 'skipped';
+  status: "success" | "failed" | "skipped";
   error?: string;
   /** Human-readable result summary, e.g. 'Preferred name set to Ian' */
   resultLabel?: string;
@@ -70,7 +70,7 @@ export interface ExecutionResultData {
   /** Execution row ID — required for undo endpoint dispatch */
   executionId: string;
   /** Resolved from ExecutionState — single authority (INV-1) */
-  state: 'completed' | 'failed';
+  state: "completed" | "failed";
   artifacts: ExecutionArtifactStatus[];
   /** Structured summary for generic UI rendering (executor-provided) */
   summary: ExecutionResultSummary;
@@ -82,7 +82,7 @@ export interface ExecutionResultData {
  * Execution result message part (semantic type).
  */
 export interface ExecutionResultPart {
-  type: 'execution-result';
+  type: "execution-result";
   data: ExecutionResultData;
 }
 
@@ -90,7 +90,7 @@ export interface ExecutionResultPart {
  * Execution result data part (wire format).
  */
 export interface ExecutionResultDataPart {
-  type: 'data-execution-result';
+  type: "data-execution-result";
   data: ExecutionResultData;
 }
 
@@ -109,7 +109,7 @@ export interface UndoResultData {
   executionId: string;
   /** New undo audit row ID (append-only, INV-2) */
   undoExecutionId: string;
-  status: 'success' | 'failed';
+  status: "success" | "failed";
   error?: string;
 }
 
@@ -117,6 +117,6 @@ export interface UndoResultData {
  * Undo result data part (wire format).
  */
 export interface UndoResultDataPart {
-  type: 'data-undo-result';
+  type: "data-undo-result";
   data: UndoResultData;
 }

package/src/message-parts/index.ts

@@ -16,7 +16,7 @@ export type {
   TablePart,
   SurfacePart,
   AssistantMessagePart,
-} from './types'
+} from "./types";
 
 // Preview types
 export type {
@@ -28,7 +28,7 @@ export type {
   PreviewData,
   PreviewPart,
   PreviewDataPart,
-} from './preview'
+} from "./preview";
 
 // Confirmation types
 export type {
@@ -38,10 +38,10 @@ export type {
   ConfirmationResponseData,
   ConfirmationPart,
   ConfirmationDataPart,
-} from './confirmation'
+} from "./confirmation";
 
 // Confirmation runtime values
-export { CONFIRMATION_LABELS, getConfirmationLabel } from './confirmation'
+export { CONFIRMATION_LABELS, getConfirmationLabel } from "./confirmation";
 
 // Execution result types
 export type {
@@ -53,7 +53,7 @@ export type {
   ExecutionResultDataPart,
   UndoResultData,
   UndoResultDataPart,
-} from './execution'
+} from "./execution";
 
 // Lifecycle types (Phase 1 streaming)
 export type {
@@ -68,13 +68,13 @@ export type {
   MessageStartDataPart,
   MessageDeltaDataPart,
   MessageCompleteDataPart,
-} from './lifecycle'
+} from "./lifecycle";
 
 // Type guards
-export { isTextPart, isSurfacePart } from './types'
+export { isTextPart, isSurfacePart } from "./types";
 
 // Builder functions
-export type { PartBuilderState, AddPartResult } from './builder'
+export type { PartBuilderState, AddPartResult } from "./builder";
 export {
   createPartBuilder,
   addText,
@@ -82,7 +82,7 @@ export {
   addPart,
   buildParts,
   getDroppedCount,
-} from './builder'
+} from "./builder";
 
 // Wire format builder
-export { WireSurfaceBuilder } from './wire'
+export { WireSurfaceBuilder } from "./wire";

package/src/message-parts/lifecycle.ts

@@ -24,7 +24,7 @@
  * - streaming: Between message.start and message.complete
  * - complete: After message.complete received
  */
-export type StreamPhase = 'idle' | 'streaming' | 'complete'
+export type StreamPhase = "idle" | "streaming" | "complete";
 
 // =============================================================================
 // Lifecycle Event Types
@@ -34,9 +34,9 @@ export type StreamPhase = 'idle' | 'streaming' | 'complete'
  * Lifecycle event type discriminator.
  */
 export type MessageLifecycleEventType =
-  | 'message.start'
-  | 'message.delta'
-  | 'message.complete'
+  | "message.start"
+  | "message.delta"
+  | "message.complete";
 
 /**
  * Base interface for all message lifecycle events.
@@ -47,10 +47,10 @@ export type MessageLifecycleEventType =
  * @property timestamp - ISO 8601 timestamp of event emission
  */
 export interface MessageLifecycleEvent {
-  type: MessageLifecycleEventType
-  version: 1
-  messageId: string
-  timestamp: string
+  type: MessageLifecycleEventType;
+  version: 1;
+  messageId: string;
+  timestamp: string;
 }
 
 /**
@@ -58,7 +58,7 @@ export interface MessageLifecycleEvent {
  * Emitted when a new message stream begins.
  */
 export interface MessageStartEvent extends MessageLifecycleEvent {
-  type: 'message.start'
+  type: "message.start";
 }
 
 /**
@@ -67,9 +67,9 @@ export interface MessageStartEvent extends MessageLifecycleEvent {
  * Only contains narrative text, not surface parts.
  */
 export interface MessageDeltaEvent extends MessageLifecycleEvent {
-  type: 'message.delta'
+  type: "message.delta";
   /** The text delta (narrative content only) */
-  delta: string
+  delta: string;
 }
 
 /**
@@ -78,9 +78,9 @@ export interface MessageDeltaEvent extends MessageLifecycleEvent {
  * Signals that all narrative content has been streamed.
  */
 export interface MessageCompleteEvent extends MessageLifecycleEvent {
-  type: 'message.complete'
+  type: "message.complete";
   /** Total length of narrative content for validation */
-  narrativeLength: number
+  narrativeLength: number;
 }
 
 // =============================================================================
@@ -99,21 +99,21 @@ export interface MessageCompleteEvent extends MessageLifecycleEvent {
  *   Examples: tool lists, cards, dashboards, MCP UI components
  *   Atomic, deterministic, never stream
  */
-export type ToolResultRenderClass = 'inline' | 'surface'
+export type ToolResultRenderClass = "inline" | "surface";
 
 /**
  * Tool result part with rendering classification.
  */
 export interface ToolResultPart {
-  type: 'tool-result'
+  type: "tool-result";
   /** Tool identifier */
-  toolName: string
+  toolName: string;
   /** Rendering classification */
-  render: ToolResultRenderClass
+  render: ToolResultRenderClass;
   /** Tool-specific payload */
-  payload: unknown
+  payload: unknown;
   /** Optional message correlation (enables out-of-band arrival, multi-message chains) */
-  messageId?: string
+  messageId?: string;
 }
 
 // =============================================================================
@@ -125,8 +125,8 @@ export interface ToolResultPart {
  * Follows AI SDK's data-{name} convention.
  */
 export interface MessageStartDataPart {
-  type: 'data-message-start'
-  data: Omit<MessageStartEvent, 'type'>
+  type: "data-message-start";
+  data: Omit<MessageStartEvent, "type">;
 }
 
 /**
@@ -134,14 +134,14 @@ export interface MessageStartDataPart {
  * Note: Standard text-delta may be used instead for AI SDK compatibility.
  */
 export interface MessageDeltaDataPart {
-  type: 'data-message-delta'
-  data: Omit<MessageDeltaEvent, 'type'>
+  type: "data-message-delta";
+  data: Omit<MessageDeltaEvent, "type">;
 }
 
 /**
  * Wire format for message complete event.
  */
 export interface MessageCompleteDataPart {
-  type: 'data-message-complete'
-  data: Omit<MessageCompleteEvent, 'type'>
+  type: "data-message-complete";
+  data: Omit<MessageCompleteEvent, "type">;
 }

package/src/message-parts/preview.ts

@@ -22,18 +22,18 @@
  * Each kind represents a different type of action that could be executed.
  */
 export type PreviewArtifactKind =
-  | 'message' // Slack/chat message to send
-  | 'api_call' // External API call
-  | 'diff' // File or document change
-  | 'notification' // Notification to user/team
-  | 'task' // Task creation
-  | 'calendar' // Calendar event
-  | 'integration' // Integration connect/disconnect action
+  | "message" // Slack/chat message to send
+  | "api_call" // External API call
+  | "diff" // File or document change
+  | "notification" // Notification to user/team
+  | "task" // Task creation
+  | "calendar" // Calendar event
+  | "integration"; // Integration connect/disconnect action
 
 /**
  * Integration provider types.
  */
-export type IntegrationProvider = 'slack' | 'google' | 'zoom'
+export type IntegrationProvider = "slack" | "google" | "zoom";
 
 /**
  * Application-level composite integration identifier.
@@ -43,7 +43,7 @@ export type IntegrationProvider = 'slack' | 'google' | 'zoom'
  * - 'google_meet' → provider='google', service='meet'
  * - 'zoom' → provider='zoom', service=''
  */
-export type IntegrationKey = 'slack' | 'google_drive' | 'google_meet' | 'zoom'
+export type IntegrationKey = "slack" | "google_drive" | "google_meet" | "zoom";
 
 /**
  * Content structure for integration artifacts.
@@ -52,15 +52,15 @@ export type IntegrationKey = 'slack' | 'google_drive' | 'google_meet' | 'zoom'
  */
 export interface IntegrationArtifactContent {
   /** The integration action to perform */
-  action: 'connect' | 'disconnect'
+  action: "connect" | "disconnect";
   /** Target provider */
-  provider: IntegrationProvider
+  provider: IntegrationProvider;
   /** Service within the provider (e.g. 'drive' for Google Drive). Empty string for monolithic providers. */
-  service?: string
+  service?: string;
   /** Connection ID for disconnect (required for disconnect) */
-  connectionId?: string
+  connectionId?: string;
   /** Workspace ID for multi-workspace providers */
-  workspaceId?: string
+  workspaceId?: string;
 }
 
 /**
@@ -69,18 +69,18 @@ export interface IntegrationArtifactContent {
  */
 export interface PreviewArtifact {
   /** The kind of action this artifact represents */
-  kind: PreviewArtifactKind
+  kind: PreviewArtifactKind;
   /** Human-readable label for this artifact */
-  label: string
+  label: string;
   /** The exact payload that would be executed - must be JSON-safe */
-  content: unknown
+  content: unknown;
   /** Optional metadata for display purposes */
   metadata?: {
     /** Target system (e.g., "slack", "google-calendar") */
-    target?: string
+    target?: string;
     /** Estimated impact level */
-    impact?: 'low' | 'medium' | 'high'
-  }
+    impact?: "low" | "medium" | "high";
+  };
 }
 
 /**
@@ -88,26 +88,26 @@ export interface PreviewArtifact {
  */
 export interface PreviewData {
   /** Stable identifier for this preview - used for confirmation tracking */
-  actionId: string
+  actionId: string;
   /** Human-readable summary of what will happen */
-  title: string
+  title: string;
   /** Optional detailed explanation */
-  description?: string
+  description?: string;
   /** The artifacts that would be created/sent/modified */
-  artifacts: PreviewArtifact[]
+  artifacts: PreviewArtifact[];
   /** Action type for bridge routing and executor dispatch (e.g. 'update_profile', 'send_message', 'manage_integration') */
-  actionType?: string
+  actionType?: string;
   /** Top-level execution target for bridge routing and executor dispatch.
    *  Distinct from PreviewArtifact.metadata.target (per-artifact UI metadata). */
-  target?: string
+  target?: string;
 }
 
 /**
  * Preview message part (semantic type).
  */
 export interface PreviewPart {
-  type: 'preview'
-  data: PreviewData
+  type: "preview";
+  data: PreviewData;
 }
 
 /**
@@ -115,6 +115,6 @@ export interface PreviewPart {
  * Uses AI SDK's data-{name} convention.
  */
 export interface PreviewDataPart {
-  type: 'data-preview'
-  data: PreviewData
+  type: "data-preview";
+  data: PreviewData;
 }