@company-semantics/contracts 0.81.0 → 0.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/chat/runtime-profile.ts

@@ -27,7 +27,7 @@ export interface ChatRuntimeProfileInfo {
 export const CHAT_RUNTIME_PROFILES: readonly ChatRuntimeProfileInfo[] = [
   { id: 'fast', label: 'Fast', description: 'Single-step, no tools', model: 'gpt-3.5-turbo' },
   { id: 'balanced', label: 'Balanced', description: 'Multi-step with tools', model: 'gpt-4o' },
-  { id: 'agentic', label: 'Agentic', description: 'Agent loop, full reasoning', model: 'claude-sonnet-4' },
+  { id: 'agentic', label: 'Agentic', description: 'Agent loop, full reasoning', model: 'claude-sonnet-4-20250514' },
 ] as const
 
 /**

package/src/execution/audit-export.ts

@@ -0,0 +1,67 @@
+import type { ExecutionEventType } from './events';
+import type { ExecutionIntent } from './types';
+import type { HashChainVerificationResult } from './hash-chain';
+
+/**
+ * Immutable governance snapshot captured at execution creation time.
+ * Stored in execution_audit.frozen_intent JSONB column.
+ *
+ * Semantically distinct from ExecutionIntent: this represents what was true
+ * at creation time, not what the registry currently says.
+ * frozenIntentHash enables tamper detection if JSONB is modified by privileged DBA.
+ */
+export type FrozenExecutionIntent = Readonly<ExecutionIntent> & {
+  /** ISO 8601 timestamp of when this snapshot was captured */
+  frozenAt: string;
+  /** SHA-256 of canonicalized frozen intent — for tamper detection */
+  frozenIntentHash: string;
+};
+
+/**
+ * Per-event shape within an audit export bundle.
+ * Events MUST be ordered by eventSequence ascending.
+ */
+export interface AuditExportEvent {
+  eventSequence: number;
+  eventType: ExecutionEventType;
+  stateAfter: string;
+  actorId: string;
+  actorType: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  eventHash: string;
+  previousHash: string | null;
+}
+
+/**
+ * Top-level audit export bundle for a single execution.
+ *
+ * Threat model:
+ * - hashChainValid: Detects internal DB tampering (single-row mutation)
+ * - frozenIntentHashValid: Detects frozen intent JSONB mutation
+ * - exportSignature (HMAC-SHA256): Proves this export was generated by this server.
+ *   Does NOT prove DB was not tampered prior to export.
+ *   Hash chaining + frozen intent hashing detect pre-export tampering.
+ */
+export interface AuditExportBundle {
+  /** Schema version for forward compatibility */
+  version: '1.0';
+  /** ISO 8601 timestamp of export generation */
+  exportedAt: string;
+  /** Execution ID */
+  executionId: string;
+  /** Organization ID */
+  orgId: string;
+  /** Frozen governance snapshot from execution_audit */
+  frozenIntent: FrozenExecutionIntent;
+  /** Whether frozen_intent_hash matches recomputed SHA-256(canonicalize(frozen_intent)) */
+  frozenIntentHashValid: boolean;
+  /** Event chain ordered by eventSequence ascending, with hash fields */
+  events: AuditExportEvent[];
+  /** Whether all event hashes recompute correctly */
+  hashChainValid: boolean;
+  /** Detailed chain verification result */
+  hashChainVerification: HashChainVerificationResult;
+  /** HMAC-SHA256 of bundle content. Present only if AUDIT_EXPORT_SIGNING_KEY is configured. */
+  exportSignature?: string;
+}

package/src/execution/event-metadata.ts

@@ -0,0 +1,103 @@
+import type { ExecutionEventType } from './events';
+import type { ExecutionIntent } from './types';
+
+/** Metadata for execution_created event. Frozen governance snapshot. */
+export interface ExecutionCreatedMetadata {
+  /** Full ExecutionIntent frozen at creation time — authoritative governance snapshot (INV-18) */
+  executionIntent: ExecutionIntent;
+  /** Number of artifacts in the execution */
+  artifactCount: number;
+  /** ISO 8601 confirmation deadline. Present when requiresConfirmation=true. */
+  expiresAt?: string;
+}
+
+/** Metadata for execution_started event. Intentionally empty. */
+export type ExecutionStartedMetadata = Record<string, never>;
+
+/** Metadata for confirmation_approved event. */
+export interface ConfirmationApprovedMetadata {
+  /** userId of the user who confirmed */
+  confirmedBy: string;
+}
+
+/** Metadata for confirmation_rejected event. */
+export interface ConfirmationRejectedMetadata {
+  /** userId of the user who rejected */
+  rejectedBy: string;
+  /** Optional reason for rejection */
+  reason?: string;
+}
+
+/** Metadata for confirmation_expired event. */
+export interface ConfirmationExpiredMetadata {
+  /** What triggered the expiration */
+  trigger: 'job' | 'confirm_attempt';
+  /** ISO 8601 timestamp when expiration was recorded */
+  expiredAt: string;
+  /** ISO 8601 original confirmation deadline */
+  originalExpiresAt: string;
+}
+
+/** Metadata for approval_requested event. Governance-metadata event. */
+export interface ApprovalRequestedMetadata {
+  /** Reason approval is required */
+  reason: string;
+  /** userId who triggered the approval request */
+  requestedBy: string;
+}
+
+/** Metadata for execution_completed event. Forward-compatible. */
+export interface ExecutionCompletedMetadata {
+  /** Human-readable result summary */
+  resultSummary?: string;
+  /** Number of artifacts executed */
+  artifactCount?: number;
+}
+
+/** Metadata for execution_failed event. Forward-compatible. */
+export interface ExecutionFailedMetadata {
+  /** Machine-readable error code */
+  errorCode?: string;
+  /** Error classification for retry decisions */
+  errorClass?: 'retryable' | 'terminal';
+  /** Human-readable error message */
+  message?: string;
+}
+
+/** Metadata for undo_completed event. Forward-compatible. */
+export interface UndoCompletedMetadata {
+  /** userId who initiated the undo */
+  undoneBy: string;
+}
+
+/** Metadata for cancelled event. Forward-compatible. */
+export interface CancelledMetadata {
+  /** userId who cancelled */
+  cancelledBy: string;
+  /** Optional cancellation reason */
+  reason?: string;
+}
+
+/**
+ * Exhaustive mapping from ExecutionEventType to its metadata interface.
+ * TypeScript enforces completeness — adding a new event type without
+ * a metadata definition here is a compile error.
+ */
+export interface ExecutionEventMetadataMap {
+  execution_created: ExecutionCreatedMetadata;
+  execution_started: ExecutionStartedMetadata;
+  confirmation_approved: ConfirmationApprovedMetadata;
+  confirmation_rejected: ConfirmationRejectedMetadata;
+  confirmation_expired: ConfirmationExpiredMetadata;
+  approval_requested: ApprovalRequestedMetadata;
+  execution_completed: ExecutionCompletedMetadata;
+  execution_failed: ExecutionFailedMetadata;
+  undo_completed: UndoCompletedMetadata;
+  cancelled: CancelledMetadata;
+}
+
+// Compile-time exhaustiveness check: this line errors if
+// ExecutionEventMetadataMap keys don't match ExecutionEventType
+type _ExhaustivenessCheck = {
+  [K in ExecutionEventType]: ExecutionEventMetadataMap[K];
+};

package/src/execution/events.ts

@@ -0,0 +1,37 @@
+/**
+ * Enumerates all valid event_type values for the execution_events table.
+ *
+ * Currently emitted: execution_created, execution_started, confirmation_approved,
+ * confirmation_rejected, confirmation_expired, approval_requested.
+ *
+ * Forward-compatible: execution_completed, execution_failed, undo_completed, cancelled.
+ * These are defined here for type exhaustiveness but not yet emitted by backend.
+ */
+export type ExecutionEventType =
+  | 'execution_created'
+  | 'execution_started'
+  | 'confirmation_approved'
+  | 'confirmation_rejected'
+  | 'confirmation_expired'
+  | 'approval_requested'
+  | 'execution_completed'
+  | 'execution_failed'
+  | 'undo_completed'
+  | 'cancelled';
+
+export const EXECUTION_EVENT_TYPES: readonly ExecutionEventType[] = [
+  'execution_created',
+  'execution_started',
+  'confirmation_approved',
+  'confirmation_rejected',
+  'confirmation_expired',
+  'approval_requested',
+  'execution_completed',
+  'execution_failed',
+  'undo_completed',
+  'cancelled',
+] as const;
+
+export function isExecutionEventType(value: string): value is ExecutionEventType {
+  return (EXECUTION_EVENT_TYPES as readonly string[]).includes(value);
+}

package/src/execution/hash-chain.ts

@@ -0,0 +1,40 @@
+/**
+ * Hash chain fields for tamper-evident execution events.
+ *
+ * Algorithm: SHA-256 over RFC 8785 JCS (JSON Canonicalization Scheme) input.
+ * Input: executionId + eventSequence + eventType + stateAfter + actorId + canonicalize(metadata) + (previousHash ?? 'NULL')
+ * created_at intentionally excluded — clock drift across replicas could break verification.
+ *
+ * Threat model: Detects single-row mutation where attacker does not recompute downstream hashes.
+ * Does NOT defend against fully malicious DBA who recomputes entire chain.
+ * External anchoring (periodic anchor hash stored outside DB) is a future enhancement.
+ */
+export interface EventHashFields {
+  /** SHA-256 hex digest (64 characters) of this event's canonicalized content */
+  eventHash: string;
+  /** SHA-256 hex digest of the previous event in this execution's chain, or null for the first event */
+  previousHash: string | null;
+}
+
+/**
+ * Result of verifying a hash chain for a single execution.
+ * If valid=false, brokenAtSequence indicates where the chain first breaks.
+ */
+export interface HashChainVerificationResult {
+  /** True if all event hashes recompute correctly and chain links are valid */
+  valid: boolean;
+  /** Event sequence number where chain integrity first fails (present only if valid=false) */
+  brokenAtSequence?: number;
+  /** What the recomputed hash should be (present only if valid=false) */
+  expectedHash?: string;
+  /** What was stored in the database (present only if valid=false) */
+  actualHash?: string;
+  /** True if frozen_intent_hash verification failed (present only if checked) */
+  frozenIntentMismatch?: boolean;
+}
+
+/** Hash algorithm used for event chain integrity */
+export const HASH_ALGORITHM = 'sha256' as const;
+
+/** Encoding for hash output */
+export const HASH_ENCODING = 'hex' as const;

package/src/execution/index.ts

@@ -7,12 +7,71 @@
  * @see ADR-CONT-029 for design rationale
  */
 
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export type { ExecutionEventType } from './events'
+
+export {
+  EXECUTION_EVENT_TYPES,
+  isExecutionEventType,
+} from './events'
+
+// =============================================================================
+// Event Metadata Schemas
+// =============================================================================
+
+export type {
+  ExecutionCreatedMetadata,
+  ExecutionStartedMetadata,
+  ConfirmationApprovedMetadata,
+  ConfirmationRejectedMetadata,
+  ConfirmationExpiredMetadata,
+  ApprovalRequestedMetadata,
+  ExecutionCompletedMetadata,
+  ExecutionFailedMetadata,
+  UndoCompletedMetadata,
+  CancelledMetadata,
+  ExecutionEventMetadataMap,
+} from './event-metadata'
+
+// =============================================================================
+// Hash Chain Types
+// =============================================================================
+
+export type {
+  EventHashFields,
+  HashChainVerificationResult,
+} from './hash-chain'
+
+export {
+  HASH_ALGORITHM,
+  HASH_ENCODING,
+} from './hash-chain'
+
+// =============================================================================
+// Audit Export Types
+// =============================================================================
+
+export type {
+  FrozenExecutionIntent,
+  AuditExportEvent,
+  AuditExportBundle,
+} from './audit-export'
+
 // =============================================================================
 // Kind Types
 // =============================================================================
 
 export type { ExecutionKind } from './kinds'
 
+// =============================================================================
+// Lifecycle State
+// =============================================================================
+
+export type { ExecutionState } from './status'
+
 // =============================================================================
 // Definition Types
 // =============================================================================
@@ -22,6 +81,7 @@ export type {
   IconName,
   ExecutionDomain,
   ExecutionKindDefinition,
+  ExecutionIntent,
 } from './types'
 
 // =============================================================================

package/src/execution/kinds.ts

@@ -25,3 +25,5 @@
 export type ExecutionKind =
   | 'integration.connect'
   | 'integration.disconnect'
+  | 'profile.update'
+  | 'slack.send'

package/src/execution/registry.ts

@@ -76,6 +76,48 @@ export const EXECUTION_KINDS = {
       templateId: 'integration.disconnect',
     },
   },
+  'profile.update': {
+    kind: 'profile.update',
+    domain: 'profile',
+    display: {
+      label: 'Update Profile',
+      pastTenseLabel: 'Profile updated',
+      icon: 'pencil',
+    },
+    governance: {
+      visibility: 'user',
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: 'profile.update',
+    },
+  },
+  'slack.send': {
+    kind: 'slack.send',
+    domain: 'communication',
+    display: {
+      label: 'Send Slack Message',
+      pastTenseLabel: 'Slack message sent',
+      icon: 'send',
+    },
+    governance: {
+      visibility: 'user',
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: 'slack.send',
+    },
+  },
 } as const satisfies Record<ExecutionKind, ExecutionKindDefinition>
 
 // =============================================================================

package/src/execution/status.ts

@@ -0,0 +1,57 @@
+/**
+ * ExecutionState — First-class contract for execution lifecycle state.
+ *
+ * This type is the sole authority (INV-1) for lifecycle state across all repos.
+ * Backend MUST import from contracts, not define locally.
+ *
+ * ## State Machine
+ *
+ * ```
+ * pending_confirmation ──→ blocked_pending_approval ──→ ready ──→ executing
+ *         │                         │                     ↑          │
+ *         │                         │                     │          ├──→ completed
+ *         │                         │                     │          ├──→ completed_with_rollbacks
+ *         │                         │                     │          ├──→ failed_retryable ──→ ready (retry)
+ *         │                         │                     │          ├──→ failed_terminal
+ *         │                         │                     │          ├──→ failed_with_partial_execution
+ *         │                         │                     │          └──→ cancelled
+ *         └──→ cancelled            └──→ cancelled        │
+ *         └──→ expired              └──→ expired          └──→ expired
+ * ```
+ *
+ * ## Key Semantics
+ *
+ * - **pending_confirmation** and **blocked_pending_approval** are orthogonal
+ *   stackable gates that compose. pending_confirmation is the self-attestation
+ *   gate; blocked_pending_approval is the cross-principal authorization gate.
+ *
+ * - **ready** is a distinct state separating authorization from execution.
+ *   All governance gates are cleared. Enables future queueing, backpressure,
+ *   rate limiting, and scheduling.
+ *
+ * - **execution_started** is the sole event transitioning to **executing**.
+ *   Mandatory for all execution paths including retries.
+ *
+ * - Retry is same-execution: failed_retryable → ready → executing reuses
+ *   the same executionId.
+ *
+ * ## Ordering Invariant
+ *
+ * State transitions are ordered by event_sequence (monotonic per-execution
+ * bigint), not timestamps. UNIQUE(execution_id, event_sequence) enforced
+ * at database level. event_sequence for ordering, created_at for duration —
+ * distinct concerns.
+ */
+export type ExecutionState =
+  | 'pending_confirmation'
+  | 'blocked_pending_approval'
+  | 'ready'
+  | 'executing'
+  | 'completed'
+  | 'completed_with_rollbacks'
+  | 'failed_retryable'
+  | 'failed_terminal'
+  | 'failed_with_partial_execution'
+  | 'cancelled'
+  | 'expired'
+  | 'undone';

package/src/execution/types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ExecutionKind } from './kinds'
+import type { ConfirmationRiskLevel } from '../message-parts/confirmation'
 
 // =============================================================================
 // Utility Types
@@ -22,7 +23,7 @@ export type ISO8601Timestamp = string
  * Icon names for execution kinds.
  * Must be supported by the frontend icon system.
  */
-export type IconName = 'plug' | 'unlink'
+export type IconName = 'plug' | 'unlink' | 'pencil' | 'send'
 
 // =============================================================================
 // Execution Domain
@@ -31,7 +32,7 @@ export type IconName = 'plug' | 'unlink'
 /**
  * Domain categories for execution kinds.
  */
-export type ExecutionDomain = 'integration' | 'policy' | 'data' | 'system'
+export type ExecutionDomain = 'integration' | 'policy' | 'data' | 'system' | 'profile' | 'communication'
 
 // =============================================================================
 // Execution Kind Definition
@@ -90,3 +91,33 @@ export interface ExecutionKindDefinition {
     templateId: string
   }
 }
+
+// =============================================================================
+// Execution Intent
+// =============================================================================
+
+/**
+ * Governance requirements for an execution.
+ *
+ * Executors declare this explicitly when proposing an execution.
+ * The bridge transports ExecutionIntent as-is — it never infers governance
+ * requirements. The system fails loudly if ExecutionIntent is missing.
+ *
+ * Invariants:
+ * - executionKind MUST exist in EXECUTION_KINDS registry
+ * - If requiresConfirmation is false, no confirmation part is emitted
+ *   and execution starts at 'ready'
+ * - If requiresApproval is true, a 'blocked_pending_approval' gate is
+ *   inserted after confirmation (cross-principal authorization)
+ * - risk is used for UI styling and future behavioral hooks
+ *
+ * NAMING NOTE: This is DIFFERENT from the CI Envelope ExecutionIntent
+ * (a string union in ci-envelope/types.ts). This interface is exported
+ * from the execution domain barrel only, NOT from root index.ts.
+ */
+export interface ExecutionIntent {
+  executionKind: ExecutionKind
+  requiresConfirmation: boolean
+  requiresApproval: boolean
+  risk: ConfirmationRiskLevel
+}

package/src/index.ts

@@ -303,12 +303,10 @@ export type {
   PreviewDataPart,
   // Confirmation types (Phase 4)
   ConfirmationChoice,
-  ConfirmationRisk,
+  ConfirmationRiskLevel,
   ConfirmationData,
-  ConfirmationDataPart,
   ConfirmationResponseData,
-  ConfirmationResponsePart,
-  ConfirmationResponseDataPart,
+  ConfirmationDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,
@@ -344,12 +342,16 @@ export {
   buildParts,
   getDroppedCount,
   WireSurfaceBuilder,
+  CONFIRMATION_LABELS,
+  getConfirmationLabel,
 } from './message-parts/index'
 
 // Execution kind types and registry
 // @see ADR-CONT-029 for design rationale
 export type {
   ExecutionKind,
+  ExecutionState,
+  ExecutionEventType,
   ISO8601Timestamp,
   IconName,
   ExecutionDomain,
@@ -368,35 +370,10 @@ export {
   EXECUTION_KINDS,
   getExecutionKindDefinition,
   isValidExecutionKind,
+  EXECUTION_EVENT_TYPES,
+  isExecutionEventType,
 } from './execution/index'
 
-// CI Execution Envelope types
-// @see ADR-CONT-033 for contracts boundary rationale
-export type {
-  // Actor & Session
-  CIActorInfo,
-  CISessionInfo,
-  // Intent
-  ExecutionIntent,
-  CIIntentDeclaration,
-  // Scope
-  CIChangeKind,
-  CIExecutionScope,
-  // Authority
-  CIAuthorityGrant,
-  // Guard Plan
-  CIGuardPlan,
-  // Status
-  CIEnvelopeStatus,
-  // Outcome
-  CIGuardViolation,
-  CIExecutionOutcome,
-  // Core Envelope
-  CIExecutionEnvelope,
-} from './ci-envelope/index'
-
-export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'
-
 // Ralph autonomous coding loop types
 // @see company-semantics-control/docs/ralph.md for usage
 export type {
@@ -493,3 +470,30 @@ export type {
   BudgetCheck,
   OrgBudgetSettings,
 } from './usage/execution-types'
+
+// CI Execution Envelope types
+// @see ADR-CONT-033 for contracts boundary rationale
+export type {
+  // Actor & Session
+  CIActorInfo,
+  CISessionInfo,
+  // Intent
+  ExecutionIntent,
+  CIIntentDeclaration,
+  // Scope
+  CIChangeKind,
+  CIExecutionScope,
+  // Authority
+  CIAuthorityGrant,
+  // Guard Plan
+  CIGuardPlan,
+  // Status
+  CIEnvelopeStatus,
+  // Outcome
+  CIGuardViolation,
+  CIExecutionOutcome,
+  // Core Envelope
+  CIExecutionEnvelope,
+} from './ci-envelope/index'
+
+export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'

package/src/message-parts/__tests__/confirmation.test.ts

@@ -1,14 +1,17 @@
 import { describe, it, expect } from 'vitest'
 import { WireSurfaceBuilder } from '../wire.js'
-import type { ConfirmationData, ConfirmationResponseData } from '../confirmation.js'
+import type { ConfirmationData, ConfirmationRiskLevel } from '../confirmation.js'
+import { CONFIRMATION_LABELS, getConfirmationLabel } from '../confirmation.js'
+import type { ExecutionKind } from '../../execution/kinds.js'
+import { EXECUTION_KINDS } from '../../execution/registry.js'
 
 describe('WireSurfaceBuilder.confirmation', () => {
-  it('creates a confirmation data part', () => {
+  it('creates a confirmation data part with new shape', () => {
     const data: ConfirmationData = {
       actionId: 'msg-123',
-      title: 'Send Slack message to #sales',
-      prompt: 'Confirm sending this message?',
+      executorKind: 'slack.send',
       risk: 'low',
+      executionId: 'exec-abc-001',
     }
 
     const result = WireSurfaceBuilder.confirmation(data)
@@ -20,8 +23,9 @@ describe('WireSurfaceBuilder.confirmation', () => {
   it('preserves actionId exactly', () => {
     const data: ConfirmationData = {
       actionId: 'complex-action-id-12345',
-      title: 'Test',
-      prompt: 'Confirm?',
+      executorKind: 'integration.connect',
+      risk: 'moderate',
+      executionId: 'exec-xyz-789',
     }
 
     const result = WireSurfaceBuilder.confirmation(data)
@@ -29,28 +33,15 @@ describe('WireSurfaceBuilder.confirmation', () => {
     expect(result.data.actionId).toBe('complex-action-id-12345')
   })
 
-  it('handles confirmation without optional risk level', () => {
-    const data: ConfirmationData = {
-      actionId: 'no-risk-specified',
-      title: 'Simple action',
-      prompt: 'Do you want to proceed?',
-    }
-
-    const result = WireSurfaceBuilder.confirmation(data)
-
-    expect(result.type).toBe('data-confirmation')
-    expect(result.data.risk).toBeUndefined()
-  })
-
-  it('preserves all risk levels', () => {
-    const risks: Array<'low' | 'medium' | 'high'> = ['low', 'medium', 'high']
+  it('preserves all ConfirmationRiskLevel values', () => {
+    const risks: ConfirmationRiskLevel[] = ['low', 'moderate', 'high', 'irreversible']
 
     for (const risk of risks) {
       const data: ConfirmationData = {
         actionId: `risk-${risk}`,
-        title: `${risk} risk action`,
-        prompt: 'Confirm?',
+        executorKind: 'profile.update',
         risk,
+        executionId: `exec-risk-${risk}`,
       }
 
       const result = WireSurfaceBuilder.confirmation(data)
@@ -58,42 +49,47 @@ describe('WireSurfaceBuilder.confirmation', () => {
       expect(result.data.risk).toBe(risk)
     }
   })
-})
 
-describe('WireSurfaceBuilder.confirmationResponse', () => {
-  it('creates a confirmation response for confirm choice', () => {
-    const data: ConfirmationResponseData = {
-      actionId: 'msg-123',
-      choice: 'confirm',
+  it('preserves executionId and executorKind', () => {
+    const data: ConfirmationData = {
+      actionId: 'action-001',
+      executorKind: 'integration.disconnect',
+      risk: 'high',
+      executionId: 'exec-lifecycle-001',
     }
 
-    const result = WireSurfaceBuilder.confirmationResponse(data)
+    const result = WireSurfaceBuilder.confirmation(data)
 
-    expect(result.type).toBe('data-confirmation-response')
-    expect(result.data.actionId).toBe('msg-123')
-    expect(result.data.choice).toBe('confirm')
+    expect(result.data.executionId).toBe('exec-lifecycle-001')
+    expect(result.data.executorKind).toBe('integration.disconnect')
   })
+})
 
-  it('creates a confirmation response for cancel choice', () => {
-    const data: ConfirmationResponseData = {
-      actionId: 'msg-123',
-      choice: 'cancel',
-    }
-
-    const result = WireSurfaceBuilder.confirmationResponse(data)
+describe('getConfirmationLabel', () => {
+  it('returns correct label for known ExecutionKind', () => {
+    expect(getConfirmationLabel('integration.connect')).toBe('Connect Integration')
+    expect(getConfirmationLabel('integration.disconnect')).toBe('Disconnect Integration')
+    expect(getConfirmationLabel('profile.update')).toBe('Update Profile')
+    expect(getConfirmationLabel('slack.send')).toBe('Send Slack Message')
+  })
 
-    expect(result.type).toBe('data-confirmation-response')
-    expect(result.data.choice).toBe('cancel')
+  it('returns default fallback for undefined', () => {
+    expect(getConfirmationLabel(undefined)).toBe('Confirm Action')
   })
 
-  it('preserves actionId exactly in response', () => {
-    const data: ConfirmationResponseData = {
-      actionId: 'complex-action-id-12345',
-      choice: 'confirm',
-    }
+  it('returns custom fallback title when provided', () => {
+    expect(getConfirmationLabel(undefined, 'Custom Fallback')).toBe('Custom Fallback')
+  })
+})
 
-    const result = WireSurfaceBuilder.confirmationResponse(data)
+describe('CONFIRMATION_LABELS', () => {
+  it('has an entry for every ExecutionKind', () => {
+    const executionKinds = Object.keys(EXECUTION_KINDS) as ExecutionKind[]
 
-    expect(result.data.actionId).toBe('complex-action-id-12345')
+    for (const kind of executionKinds) {
+      expect(CONFIRMATION_LABELS[kind]).toBeDefined()
+      expect(typeof CONFIRMATION_LABELS[kind]).toBe('string')
+      expect(CONFIRMATION_LABELS[kind].length).toBeGreaterThan(0)
+    }
   })
 })

package/src/message-parts/confirmation.ts

@@ -17,6 +17,8 @@
  * @see DECISIONS.md for design rationale
  */
 
+import type { ExecutionKind } from '../execution/kinds'
+
 /**
  * Choice options for confirmation.
  */
@@ -24,26 +26,60 @@ 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';
+
+/**
+ * Human-readable confirmation dialog titles for each execution kind.
+ * Exhaustive — TypeScript enforces completeness via Record type.
  */
-export type ConfirmationRisk = 'low' | 'medium' | 'high';
+export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
+  'integration.connect': 'Connect Integration',
+  'integration.disconnect': 'Disconnect Integration',
+  'profile.update': 'Update Profile',
+  'slack.send': 'Send Slack Message',
+};
 
 /**
- * Confirmation request data payload.
+ * Look up the human-readable confirmation label for an execution kind.
  */
+export function getConfirmationLabel(
+  executorKind: ExecutionKind | undefined,
+  fallbackTitle?: string,
+): string {
+  if (executorKind && executorKind in CONFIRMATION_LABELS) {
+    return CONFIRMATION_LABELS[executorKind];
+  }
+  return fallbackTitle ?? 'Confirm Action';
+}
+
 export interface ConfirmationData {
   /** Must match the active preview's actionId */
   actionId: string;
-  /** Summary of the action being confirmed */
-  title: string;
-  /** The confirmation prompt, e.g. "Confirm sending this Slack message?" */
-  prompt: string;
-  /** Optional risk level for UI styling */
-  risk?: ConfirmationRisk;
+  /** Execution kind for label derivation via getConfirmationLabel() */
+  executorKind: ExecutionKind;
+  /** Risk level — required for UI styling and future governance hooks */
+  risk: ConfirmationRiskLevel;
+  /** Lifecycle record ID — must exist before confirmation part is emitted */
+  executionId: string;
 }
 
 /**
  * Confirmation request message part (semantic type).
  */
+/**
+ * Data sent by the client to confirm or cancel a proposed action.
+ * Structured response only — no natural language inference.
+ */
+export interface ConfirmationResponseData {
+  /** Must match the active preview's actionId */
+  actionId: string;
+  /** User's explicit decision */
+  choice: ConfirmationChoice;
+}
+
 export interface ConfirmationPart {
   type: 'confirmation';
   data: ConfirmationData;
@@ -57,31 +93,3 @@ export interface ConfirmationDataPart {
   data: ConfirmationData;
 }
 
-// === Confirmation Response Types (New in Phase 4) ===
-
-/**
- * Confirmation response data payload.
- * Sent by the user (via UI button or structured message) to confirm/cancel.
- */
-export interface ConfirmationResponseData {
-  /** Must match the active confirmation's actionId */
-  actionId: string;
-  /** The user's decision */
-  choice: ConfirmationChoice;
-}
-
-/**
- * Confirmation response message part (semantic type).
- */
-export interface ConfirmationResponsePart {
-  type: 'confirmation-response';
-  data: ConfirmationResponseData;
-}
-
-/**
- * Confirmation response data part (wire format).
- */
-export interface ConfirmationResponseDataPart {
-  type: 'data-confirmation-response';
-  data: ConfirmationResponseData;
-}

package/src/message-parts/index.ts

@@ -33,15 +33,16 @@ export type {
 // Confirmation types
 export type {
   ConfirmationChoice,
-  ConfirmationRisk,
+  ConfirmationRiskLevel,
   ConfirmationData,
+  ConfirmationResponseData,
   ConfirmationPart,
   ConfirmationDataPart,
-  ConfirmationResponseData,
-  ConfirmationResponsePart,
-  ConfirmationResponseDataPart,
 } from './confirmation'
 
+// Confirmation runtime values
+export { CONFIRMATION_LABELS, getConfirmationLabel } from './confirmation'
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -15,7 +15,7 @@
 
 import type { ToolListMessagePart } from '../mcp/index'
 import type { PreviewPart } from './preview'
-import type { ConfirmationPart, ConfirmationResponsePart } from './confirmation'
+import type { ConfirmationPart } from './confirmation'
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -111,9 +111,6 @@ export interface TablePart {
 /**
  * Surface parts are rendered atomically (never streamed).
  * Extensible: add new surface types to this union.
- *
- * Note: ConfirmationResponsePart is user-originated but included
- * here for uniform parsing. Do not render as UI surface.
  */
 export type SurfacePart =
   | ToolListPart
@@ -121,7 +118,6 @@ export type SurfacePart =
   | ChartPart
   | TablePart
   | ConfirmationPart
-  | ConfirmationResponsePart
   | PreviewPart
 
 /**

package/src/message-parts/wire.ts

@@ -15,8 +15,6 @@ import type { PreviewDataPart, PreviewData } from './preview'
 import type {
   ConfirmationData,
   ConfirmationDataPart,
-  ConfirmationResponseData,
-  ConfirmationResponseDataPart,
 } from './confirmation'
 import type {
   ExecutionResultData,
@@ -92,24 +90,6 @@ export const WireSurfaceBuilder = {
     }
   },
 
-  /**
-   * Build a confirmation response data part.
-   * Used when processing user's confirm/cancel decision.
-   *
-   * INVARIANTS:
-   * - actionId must match the active confirmation
-   * - choice must be 'confirm' or 'cancel'
-   *
-   * @param data - Response data containing actionId and choice
-   * @returns Wire-format confirmation response part
-   */
-  confirmationResponse(data: ConfirmationResponseData): ConfirmationResponseDataPart {
-    return {
-      type: 'data-confirmation-response',
-      data,
-    }
-  },
-
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.