@company-semantics/contracts 0.91.0 → 0.93.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -40,6 +40,10 @@
       "types": "./src/ralph/index.ts",
       "default": "./src/ralph/index.ts"
     },
+    "./auth": {
+      "types": "./src/auth/index.ts",
+      "default": "./src/auth/index.ts"
+    },
     "./chat": {
       "types": "./src/chat/index.ts",
       "default": "./src/chat/index.ts"

package/src/auth/index.ts

@@ -22,4 +22,4 @@ export type AuthStartMode = "otp" | "sso" | "hybrid";
 export type AuthStartResponse =
   | { mode: "otp"; devOtp?: string }
   | { mode: "sso"; providers: string[]; redirectUrl: string }
-  | { mode: "hybrid"; providers: string[]; recommendedProvider?: string; otpAllowed: true; devOtp?: string };
+  | { mode: "hybrid"; providers: string[]; redirectUrl: string; recommendedProvider?: string; otpAllowed: true; devOtp?: string };

package/src/ci-envelope/__tests__/transitions.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import { ENVELOPE_TRANSITIONS } from '../types.js'
+import type { CIEnvelopeStatus } from '../types.js'
+
+const ALL_STATUSES: CIEnvelopeStatus[] = [
+  'proposed',
+  'validated',
+  'blocked',
+  'executing',
+  'finalized',
+]
+
+describe('ENVELOPE_TRANSITIONS terminal states', () => {
+  it('blocked is terminal (empty transition array)', () => {
+    expect(ENVELOPE_TRANSITIONS['blocked']).toEqual([])
+  })
+
+  it('finalized is terminal (empty transition array)', () => {
+    expect(ENVELOPE_TRANSITIONS['finalized']).toEqual([])
+  })
+
+  it('only blocked and finalized are terminal', () => {
+    const nonTerminal = ALL_STATUSES.filter(
+      (s) => s !== 'blocked' && s !== 'finalized'
+    )
+    for (const state of nonTerminal) {
+      expect(ENVELOPE_TRANSITIONS[state].length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe('ENVELOPE_TRANSITIONS state machine', () => {
+  it('proposed can transition to validated and blocked', () => {
+    expect(ENVELOPE_TRANSITIONS['proposed']).toContain('validated')
+    expect(ENVELOPE_TRANSITIONS['proposed']).toContain('blocked')
+  })
+
+  it('validated can transition to executing and blocked', () => {
+    expect(ENVELOPE_TRANSITIONS['validated']).toContain('executing')
+    expect(ENVELOPE_TRANSITIONS['validated']).toContain('blocked')
+  })
+
+  it('executing can transition to finalized and blocked', () => {
+    expect(ENVELOPE_TRANSITIONS['executing']).toContain('finalized')
+    expect(ENVELOPE_TRANSITIONS['executing']).toContain('blocked')
+  })
+
+  it('proposed cannot transition to executing or finalized directly', () => {
+    expect(ENVELOPE_TRANSITIONS['proposed']).not.toContain('executing')
+    expect(ENVELOPE_TRANSITIONS['proposed']).not.toContain('finalized')
+  })
+})
+
+describe('ENVELOPE_TRANSITIONS exhaustiveness', () => {
+  it('has entries for all 5 CIEnvelopeStatus values', () => {
+    for (const status of ALL_STATUSES) {
+      expect(ENVELOPE_TRANSITIONS).toHaveProperty(status)
+    }
+  })
+
+  it('every transition target is a valid CIEnvelopeStatus', () => {
+    for (const state of ALL_STATUSES) {
+      for (const target of ENVELOPE_TRANSITIONS[state]) {
+        expect(ALL_STATUSES).toContain(target)
+      }
+    }
+  })
+})
+
+describe('ENVELOPE_TRANSITIONS forward progression', () => {
+  it('no state can transition to proposed (initial state only)', () => {
+    for (const state of ALL_STATUSES) {
+      expect(ENVELOPE_TRANSITIONS[state]).not.toContain('proposed')
+    }
+  })
+
+  it('no state can transition to itself (no self-loops)', () => {
+    for (const state of ALL_STATUSES) {
+      expect(ENVELOPE_TRANSITIONS[state]).not.toContain(state)
+    }
+  })
+})

package/src/email/__tests__/registry.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest'
+import { EMAIL_KINDS, getEmailKindDefinition, isValidEmailKind } from '../registry.js'
+
+describe('EMAIL_KINDS golden snapshot', () => {
+  it('exact values are frozen', () => {
+    expect(EMAIL_KINDS).toStrictEqual({
+      'auth.otp': {
+        kind: 'auth.otp',
+        subject: 'Your login code',
+        plainTextRequired: true,
+        htmlSupported: false,
+      },
+      'auth.magic_link': {
+        kind: 'auth.magic_link',
+        subject: 'Your login link',
+        plainTextRequired: true,
+        htmlSupported: false,
+      },
+      'org.invite': {
+        kind: 'org.invite',
+        subject: 'You have been invited to join a workspace',
+        plainTextRequired: true,
+        htmlSupported: true,
+      },
+      'security.alert': {
+        kind: 'security.alert',
+        subject: 'Security alert for your account',
+        plainTextRequired: true,
+        htmlSupported: false,
+      },
+      'chat.shared': {
+        kind: 'chat.shared',
+        subject: 'A chat has been shared with you',
+        plainTextRequired: true,
+        htmlSupported: true,
+      },
+    })
+  })
+})
+
+describe('EMAIL_KINDS registry invariants', () => {
+  it('every registry key matches its definition.kind field', () => {
+    for (const [key, def] of Object.entries(EMAIL_KINDS)) {
+      expect(def.kind).toBe(key)
+    }
+  })
+
+  it('all subjects are non-empty strings', () => {
+    for (const def of Object.values(EMAIL_KINDS)) {
+      expect(typeof def.subject).toBe('string')
+      expect(def.subject.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('all entries have required boolean fields plainTextRequired and htmlSupported', () => {
+    for (const def of Object.values(EMAIL_KINDS)) {
+      expect(typeof def.plainTextRequired).toBe('boolean')
+      expect(typeof def.htmlSupported).toBe('boolean')
+    }
+  })
+})
+
+describe('getEmailKindDefinition', () => {
+  it('returns correct definition for auth.otp', () => {
+    const def = getEmailKindDefinition('auth.otp')
+    expect(def).toStrictEqual(EMAIL_KINDS['auth.otp'])
+  })
+
+  it('returns correct definition for auth.magic_link', () => {
+    const def = getEmailKindDefinition('auth.magic_link')
+    expect(def).toStrictEqual(EMAIL_KINDS['auth.magic_link'])
+  })
+
+  it('returns correct definition for org.invite', () => {
+    const def = getEmailKindDefinition('org.invite')
+    expect(def).toStrictEqual(EMAIL_KINDS['org.invite'])
+  })
+
+  it('returns correct definition for security.alert', () => {
+    const def = getEmailKindDefinition('security.alert')
+    expect(def).toStrictEqual(EMAIL_KINDS['security.alert'])
+  })
+
+  it('returns correct definition for chat.shared', () => {
+    const def = getEmailKindDefinition('chat.shared')
+    expect(def).toStrictEqual(EMAIL_KINDS['chat.shared'])
+  })
+
+  it('return value matches registry entry exactly', () => {
+    for (const [key, expected] of Object.entries(EMAIL_KINDS)) {
+      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS)
+      expect(def).toBe(expected)
+    }
+  })
+})
+
+describe('isValidEmailKind', () => {
+  it('returns true for all 5 valid email kinds', () => {
+    for (const kind of Object.keys(EMAIL_KINDS)) {
+      expect(isValidEmailKind(kind)).toBe(true)
+    }
+  })
+
+  it('returns false for unknown string', () => {
+    expect(isValidEmailKind('unknown.kind')).toBe(false)
+  })
+
+  it('returns false for empty string', () => {
+    expect(isValidEmailKind('')).toBe(false)
+  })
+
+  it('returns false for partial match', () => {
+    expect(isValidEmailKind('auth')).toBe(false)
+  })
+})

package/src/execution/__tests__/events.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest'
+import { EXECUTION_EVENT_TYPES, isExecutionEventType } from '../events.js'
+
+describe('EXECUTION_EVENT_TYPES', () => {
+  it('contains exactly 10 entries', () => {
+    expect(EXECUTION_EVENT_TYPES).toHaveLength(10)
+  })
+
+  it('contains all expected event types', () => {
+    const expected = [
+      'execution_created',
+      'execution_started',
+      'confirmation_approved',
+      'confirmation_rejected',
+      'confirmation_expired',
+      'approval_requested',
+      'execution_completed',
+      'execution_failed',
+      'undo_completed',
+      'cancelled',
+    ]
+    for (const evt of expected) {
+      expect(EXECUTION_EVENT_TYPES).toContain(evt)
+    }
+  })
+
+  it('has no duplicates', () => {
+    const unique = new Set(EXECUTION_EVENT_TYPES)
+    expect(unique.size).toBe(EXECUTION_EVENT_TYPES.length)
+  })
+})
+
+describe('isExecutionEventType', () => {
+  it('returns true for every member of EXECUTION_EVENT_TYPES', () => {
+    for (const evt of EXECUTION_EVENT_TYPES) {
+      expect(isExecutionEventType(evt)).toBe(true)
+    }
+  })
+
+  it('returns false for empty string', () => {
+    expect(isExecutionEventType('')).toBe(false)
+  })
+
+  it('returns false for unknown string', () => {
+    expect(isExecutionEventType('not_an_event')).toBe(false)
+  })
+
+  it('returns false for partial match', () => {
+    expect(isExecutionEventType('execution')).toBe(false)
+  })
+
+  it('returns false for similar but wrong string', () => {
+    expect(isExecutionEventType('execution_create')).toBe(false)
+  })
+})

package/src/execution/__tests__/registry.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+import {
+  EXECUTION_KINDS,
+  getExecutionKindDefinition,
+  isValidExecutionKind,
+} from '../registry.js'
+
+describe('EXECUTION_KINDS golden snapshot', () => {
+  it('exact values are frozen', () => {
+    expect(EXECUTION_KINDS).toStrictEqual({
+      'integration.connect': {
+        kind: 'integration.connect',
+        domain: 'integration',
+        display: {
+          label: 'Connect Slack',
+          pastTenseLabel: 'Slack connected',
+          icon: 'plug',
+        },
+        governance: {
+          visibility: 'admin',
+          requiresAdmin: true,
+          reversibleBy: 'integration.disconnect',
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: true,
+          confirmBeforeRun: false,
+        },
+        explanation: {
+          templateId: 'integration.connect',
+        },
+      },
+      'integration.disconnect': {
+        kind: 'integration.disconnect',
+        domain: 'integration',
+        display: {
+          label: 'Disconnect Slack',
+          pastTenseLabel: 'Slack disconnected',
+          icon: 'unlink',
+        },
+        governance: {
+          visibility: 'admin',
+          requiresAdmin: true,
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          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',
+        },
+      },
+      'data.ingest': {
+        kind: 'data.ingest',
+        domain: 'data',
+        display: {
+          label: 'Import Channel',
+          pastTenseLabel: 'Channel imported',
+          icon: 'send',
+        },
+        governance: {
+          visibility: 'user',
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: 'data-ingest',
+        },
+      },
+      'data.scope': {
+        kind: 'data.scope',
+        domain: 'data',
+        display: {
+          label: 'Update Channel Scope',
+          pastTenseLabel: 'Channel scope updated',
+          icon: 'pencil',
+        },
+        governance: {
+          visibility: 'admin',
+          requiresAdmin: true,
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: 'data-scope',
+        },
+      },
+      'system.cleanup': {
+        kind: 'system.cleanup',
+        domain: 'system',
+        display: {
+          label: 'Cleanup Connections',
+          pastTenseLabel: 'Connections cleaned up',
+          icon: 'unlink',
+        },
+        governance: {
+          visibility: 'admin',
+          requiresAdmin: true,
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: false,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: 'system-cleanup',
+        },
+      },
+    })
+  })
+})
+
+describe('registry structural invariants', () => {
+  it('every registry key matches its definition.kind field', () => {
+    for (const [key, def] of Object.entries(EXECUTION_KINDS)) {
+      expect(def.kind).toBe(key)
+    }
+  })
+
+  it('all entries have required display fields as non-empty strings', () => {
+    for (const [, def] of Object.entries(EXECUTION_KINDS)) {
+      expect(typeof def.display.label).toBe('string')
+      expect(def.display.label.length).toBeGreaterThan(0)
+      expect(typeof def.display.pastTenseLabel).toBe('string')
+      expect(def.display.pastTenseLabel.length).toBeGreaterThan(0)
+      expect(typeof def.display.icon).toBe('string')
+      expect(def.display.icon.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('all entries have required governance fields', () => {
+    for (const [, def] of Object.entries(EXECUTION_KINDS)) {
+      expect(typeof def.governance.visibility).toBe('string')
+      expect(typeof def.governance.requiresAdmin).toBe('boolean')
+    }
+  })
+
+  it('all entries have required ui fields as booleans', () => {
+    for (const [, def] of Object.entries(EXECUTION_KINDS)) {
+      expect(typeof def.ui.showInAdmin).toBe('boolean')
+      expect(typeof def.ui.showInTimeline).toBe('boolean')
+      expect(typeof def.ui.confirmBeforeRun).toBe('boolean')
+    }
+  })
+
+  it('admin-required kinds have visibility=admin', () => {
+    for (const [, def] of Object.entries(EXECUTION_KINDS)) {
+      if (def.governance.requiresAdmin) {
+        expect(def.governance.visibility).toBe('admin')
+      }
+    }
+  })
+})
+
+describe('getExecutionKindDefinition', () => {
+  it('returns correct definition for each of the 7 kinds', () => {
+    const kinds = Object.keys(EXECUTION_KINDS) as Array<
+      keyof typeof EXECUTION_KINDS
+    >
+    for (const kind of kinds) {
+      const def = getExecutionKindDefinition(kind)
+      expect(def.kind).toBe(kind)
+    }
+  })
+
+  it('return value matches registry entry (same reference)', () => {
+    const kinds = Object.keys(EXECUTION_KINDS) as Array<
+      keyof typeof EXECUTION_KINDS
+    >
+    for (const kind of kinds) {
+      expect(getExecutionKindDefinition(kind)).toBe(EXECUTION_KINDS[kind])
+    }
+  })
+})
+
+describe('isValidExecutionKind', () => {
+  it('returns true for all 7 valid execution kinds', () => {
+    for (const kind of Object.keys(EXECUTION_KINDS)) {
+      expect(isValidExecutionKind(kind)).toBe(true)
+    }
+  })
+
+  it('returns false for unknown string', () => {
+    expect(isValidExecutionKind('unknown.action')).toBe(false)
+  })
+
+  it('returns false for empty string', () => {
+    expect(isValidExecutionKind('')).toBe(false)
+  })
+
+  it('returns false for partial match', () => {
+    expect(isValidExecutionKind('integration')).toBe(false)
+  })
+})

package/src/identity/__tests__/avatar.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest'
+import { generateInitials, resolveAvatar } from '../avatar.js'
+
+describe('generateInitials', () => {
+  it('returns single uppercase initial for single-word name', () => {
+    expect(generateInitials('Madonna')).toBe('M')
+  })
+
+  it('returns first+last uppercase initials for two-word name', () => {
+    expect(generateInitials('Ian Heidt')).toBe('IH')
+  })
+
+  it('returns first+last initials, skipping middle for multi-word name', () => {
+    expect(generateInitials('Mary Jane Doe')).toBe('MD')
+  })
+
+  it('returns empty string for empty input', () => {
+    expect(generateInitials('')).toBe('')
+  })
+
+  it('returns empty string for whitespace-only input', () => {
+    expect(generateInitials('   ')).toBe('')
+  })
+
+  it('handles name with extra whitespace', () => {
+    expect(generateInitials('  Ian   Heidt  ')).toBe('IH')
+  })
+
+  it('returns single character for single character name', () => {
+    expect(generateInitials('X')).toBe('X')
+  })
+
+  it('returns uppercase for lowercase input', () => {
+    expect(generateInitials('ian heidt')).toBe('IH')
+  })
+})
+
+describe('resolveAvatar', () => {
+  it('initials is always populated when source is slack (critical invariant)', () => {
+    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
+    expect(result.source).toBe('slack')
+    expect(result.url).toBe('https://example.com/img.jpg')
+    // INVARIANT: initials is ALWAYS populated, regardless of source.
+    // This prevents UI regressions when Slack avatars fail to load.
+    expect(typeof result.initials).toBe('string')
+    expect(result.initials).toBe('IH')
+  })
+
+  it('returns initials source when no slackAvatarUrl', () => {
+    const result = resolveAvatar({ fullName: 'Ian Heidt' } as any)
+    expect(result.source).toBe('initials')
+    expect(result.initials).toBe('IH')
+    expect(result.url).toBeUndefined()
+  })
+
+  it('returns slack source with empty initials when fullName is empty', () => {
+    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: '' })
+    expect(result.source).toBe('slack')
+    expect(result.url).toBe('https://example.com/img.jpg')
+    // Empty is valid — just not undefined
+    expect(result.initials).toBe('')
+  })
+
+  it('returns initials source when slackAvatarUrl is explicitly undefined', () => {
+    const result = resolveAvatar({ slackAvatarUrl: undefined, fullName: 'Ian Heidt' })
+    expect(result.source).toBe('initials')
+    expect(result.initials).toBe('IH')
+  })
+
+  it('returns initials source when slackAvatarUrl is empty string (falsy)', () => {
+    const result = resolveAvatar({ slackAvatarUrl: '', fullName: 'Ian Heidt' })
+    expect(result.source).toBe('initials')
+    expect(result.initials).toBe('IH')
+  })
+})

package/src/index.ts

@@ -121,6 +121,7 @@ export type { AvatarSource, ResolvedAvatar } from './identity/index'
 export { generateInitials, resolveAvatar } from './identity/index'
 
 // Auth domain types
+export type { AuthStartMode, AuthStartResponse } from './auth/index'
 export { OTPErrorCode } from './auth/index'
 
 // Email domain types

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

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest'
+import {
+  createPartBuilder,
+  addText,
+  addSurface,
+  addPart,
+  buildParts,
+  getDroppedCount,
+} from '../builder.js'
+import type { SurfacePart, TextPart } from '../types.js'
+
+const mockSurface: SurfacePart = {
+  type: 'tool-list',
+  tools: [],
+} as unknown as SurfacePart
+
+const anotherSurface: SurfacePart = {
+  type: 'status-panel',
+  title: 'Status',
+  entries: [],
+}
+
+// =============================================================================
+// Builder Creation
+// =============================================================================
+
+describe('createPartBuilder', () => {
+  it('returns initial state with defaults', () => {
+    const state = createPartBuilder()
+    expect(state.parts).toEqual([])
+    expect(state.hasSurface).toBe(false)
+    expect(state.devMode).toBe(false)
+    expect(state.droppedCount).toBe(0)
+  })
+
+  it('returns state with devMode=true when passed true', () => {
+    const state = createPartBuilder(true)
+    expect(state.devMode).toBe(true)
+    expect(state.parts).toEqual([])
+    expect(state.hasSurface).toBe(false)
+    expect(state.droppedCount).toBe(0)
+  })
+})
+
+// =============================================================================
+// NarrativeState (before any surface)
+// =============================================================================
+
+describe('NarrativeState', () => {
+  it('addText is accepted and appends text part', () => {
+    const state = createPartBuilder()
+    const result = addText(state, 'hello')
+    expect(result.accepted).toBe(true)
+    expect(result.state.parts).toEqual([{ type: 'text', text: 'hello' }])
+  })
+
+  it('multiple addText calls accumulate parts in order', () => {
+    let state = createPartBuilder()
+    state = addText(state, 'first').state
+    state = addText(state, 'second').state
+    state = addText(state, 'third').state
+    expect(state.parts).toEqual([
+      { type: 'text', text: 'first' },
+      { type: 'text', text: 'second' },
+      { type: 'text', text: 'third' },
+    ])
+  })
+
+  it('addSurface is accepted and transitions hasSurface to true', () => {
+    const state = createPartBuilder()
+    const result = addSurface(state, mockSurface)
+    expect(result.accepted).toBe(true)
+    expect(result.state.hasSurface).toBe(true)
+  })
+})
+
+// =============================================================================
+// SurfaceState — THE CRITICAL INVARIANT
+// =============================================================================
+
+describe('SurfaceState (text after surface)', () => {
+  it('silently drops text in prod mode (devMode=false)', () => {
+    let state = createPartBuilder(false)
+    state = addSurface(state, mockSurface).state
+    const partsBefore = state.parts.length
+
+    const result = addText(state, 'dropped')
+    expect(result.accepted).toBe(false)
+    expect(result.state.droppedCount).toBe(1)
+    expect(result.state.parts.length).toBe(partsBefore)
+  })
+
+  it('throws invariant violation in dev mode (devMode=true)', () => {
+    let state = createPartBuilder(true)
+    state = addSurface(state, mockSurface).state
+
+    expect(() => addText(state, 'illegal')).toThrow('invariant violation')
+  })
+
+  it('addSurface after addSurface is always accepted', () => {
+    let state = createPartBuilder()
+    state = addSurface(state, mockSurface).state
+    const result = addSurface(state, anotherSurface)
+    expect(result.accepted).toBe(true)
+    expect(result.state.parts.length).toBe(2)
+  })
+
+  it('droppedCount accumulates across multiple drops in prod mode', () => {
+    let state = createPartBuilder(false)
+    state = addSurface(state, mockSurface).state
+
+    state = addText(state, 'drop1').state
+    state = addText(state, 'drop2').state
+    state = addText(state, 'drop3').state
+
+    expect(state.droppedCount).toBe(3)
+  })
+})
+
+// =============================================================================
+// addPart dispatch
+// =============================================================================
+
+describe('addPart', () => {
+  it('dispatches TextPart to addText behavior', () => {
+    const state = createPartBuilder()
+    const textPart: TextPart = { type: 'text', text: 'dispatched' }
+    const result = addPart(state, textPart)
+    expect(result.accepted).toBe(true)
+    expect(result.state.parts).toEqual([{ type: 'text', text: 'dispatched' }])
+  })
+
+  it('dispatches SurfacePart to addSurface behavior', () => {
+    const state = createPartBuilder()
+    const result = addPart(state, mockSurface)
+    expect(result.accepted).toBe(true)
+    expect(result.state.hasSurface).toBe(true)
+  })
+})
+
+// =============================================================================
+// Finalization
+// =============================================================================
+
+describe('buildParts', () => {
+  it('returns array copy — mutating result does not affect builder', () => {
+    let state = createPartBuilder()
+    state = addText(state, 'text1').state
+    state = addSurface(state, mockSurface).state
+
+    const parts = buildParts(state)
+    parts.push({ type: 'text', text: 'injected' })
+
+    expect(buildParts(state)).toHaveLength(2)
+  })
+
+  it('preserves correct part ordering (text before surfaces)', () => {
+    let state = createPartBuilder()
+    state = addText(state, 'narrative').state
+    state = addSurface(state, mockSurface).state
+
+    const parts = buildParts(state)
+    expect(parts[0].type).toBe('text')
+    expect(parts[1].type).not.toBe('text')
+  })
+})
+
+describe('getDroppedCount', () => {
+  it('returns current droppedCount from state', () => {
+    let state = createPartBuilder(false)
+    state = addSurface(state, mockSurface).state
+    state = addText(state, 'dropped').state
+
+    expect(getDroppedCount(state)).toBe(1)
+  })
+
+  it('returns 0 when no drops have occurred', () => {
+    const state = createPartBuilder()
+    expect(getDroppedCount(state)).toBe(0)
+  })
+})

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

@@ -71,6 +71,9 @@ describe('getConfirmationLabel', () => {
     expect(getConfirmationLabel('integration.disconnect')).toBe('Disconnect Integration')
     expect(getConfirmationLabel('profile.update')).toBe('Update Profile')
     expect(getConfirmationLabel('slack.send')).toBe('Send Slack Message')
+    expect(getConfirmationLabel('data.ingest')).toBe('Import Channel')
+    expect(getConfirmationLabel('data.scope')).toBe('Update Scope')
+    expect(getConfirmationLabel('system.cleanup')).toBe('Cleanup Connections')
   })
 
   it('returns default fallback for undefined', () => {
@@ -92,4 +95,16 @@ describe('CONFIRMATION_LABELS', () => {
       expect(CONFIRMATION_LABELS[kind].length).toBeGreaterThan(0)
     }
   })
+
+  it('values are exact and stable (golden snapshot)', () => {
+    expect(CONFIRMATION_LABELS).toStrictEqual({
+      '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',
+    })
+  })
 })