@company-semantics/contracts 0.92.0 → 0.94.0

package/package.json

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

package/src/chat/__tests__/runtime-profile.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest'
+import { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from '../runtime-profile.js'
+
+describe('CHAT_RUNTIME_PROFILES golden snapshot', () => {
+  it('exact values are frozen', () => {
+    expect(CHAT_RUNTIME_PROFILES).toStrictEqual([
+      { 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-20250514' },
+    ])
+  })
+})
+
+describe('CHAT_RUNTIME_PROFILES invariants', () => {
+  it('covers all ChatRuntimeProfile values', () => {
+    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
+    expect(ids).toContain('fast')
+    expect(ids).toContain('balanced')
+    expect(ids).toContain('agentic')
+  })
+
+  it('has no duplicate profile IDs', () => {
+    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('all entries have non-empty label and description', () => {
+    for (const profile of CHAT_RUNTIME_PROFILES) {
+      expect(profile.label.length).toBeGreaterThan(0)
+      expect(profile.description.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('all entries have non-empty model strings', () => {
+    for (const profile of CHAT_RUNTIME_PROFILES) {
+      expect(profile.model.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe('DEFAULT_CHAT_RUNTIME_PROFILE', () => {
+  it('is agentic', () => {
+    expect(DEFAULT_CHAT_RUNTIME_PROFILE).toBe('agentic')
+  })
+
+  it('exists in CHAT_RUNTIME_PROFILES', () => {
+    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
+    expect(ids).toContain(DEFAULT_CHAT_RUNTIME_PROFILE)
+  })
+
+  it('is a valid ChatRuntimeProfile value', () => {
+    const validIds = CHAT_RUNTIME_PROFILES.map(p => p.id) as readonly string[]
+    expect(validIds).toContain(DEFAULT_CHAT_RUNTIME_PROFILE)
+  })
+})

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__/lifecycle.test.ts

@@ -172,7 +172,7 @@ describe('applyIntent', () => {
     expect(applyIntent('undone', 'confirm')).toBe('conflict')
   })
 
-  it('pending_confirmation + reject = approve', () => {
+  it('pending_confirmation + reject resolves as approve (rejection uses same cancel path)', () => {
     expect(applyIntent('pending_confirmation', 'reject')).toBe('approve')
   })
 

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/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',
+    })
+  })
 })

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

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest'
+import { WireSurfaceBuilder } from '../wire.js'
+import type { ExecutionResultData } from '../execution.js'
+import type { UndoResultData } from '../execution.js'
+
+describe('WireSurfaceBuilder.toolList', () => {
+  it('returns data part with type data-tool-list', () => {
+    const tools = [{ name: 'search', description: 'Search tool', inputSchema: {} }] as any
+    const result = WireSurfaceBuilder.toolList(tools)
+    expect(result.type).toBe('data-tool-list')
+  })
+
+  it('data.tools matches input array exactly', () => {
+    const tools = [
+      { name: 'search', description: 'Search tool', inputSchema: {} },
+      { name: 'fetch', description: 'Fetch tool', inputSchema: { type: 'object' } },
+    ] as any
+    const result = WireSurfaceBuilder.toolList(tools)
+    expect(result.data.tools).toEqual(tools)
+  })
+
+  it('works with empty tools array', () => {
+    const result = WireSurfaceBuilder.toolList([])
+    expect(result.type).toBe('data-tool-list')
+    expect(result.data.tools).toEqual([])
+  })
+})
+
+describe('WireSurfaceBuilder.executionResult', () => {
+  const data: ExecutionResultData = {
+    actionId: 'act-1',
+    executionId: 'exec-001',
+    state: 'completed',
+    artifacts: [{ kind: 'profile_name', label: 'Name', status: 'success' }],
+    summary: { title: 'Profile Updated' },
+  }
+
+  it('returns data part with type data-execution-result', () => {
+    const result = WireSurfaceBuilder.executionResult(data)
+    expect(result.type).toBe('data-execution-result')
+  })
+
+  it('data matches input ExecutionResultData exactly', () => {
+    const result = WireSurfaceBuilder.executionResult(data)
+    expect(result.data).toEqual(data)
+  })
+
+  it('preserves actionId from input', () => {
+    const result = WireSurfaceBuilder.executionResult(data)
+    expect(result.data.actionId).toBe('act-1')
+  })
+})
+
+describe('WireSurfaceBuilder.undoResult', () => {
+  const data: UndoResultData = {
+    actionId: 'act-1',
+    executionId: 'exec-001',
+    undoExecutionId: 'undo-exec-002',
+    status: 'success',
+  }
+
+  it('returns data part with type data-undo-result', () => {
+    const result = WireSurfaceBuilder.undoResult(data)
+    expect(result.type).toBe('data-undo-result')
+  })
+
+  it('data matches input UndoResultData exactly', () => {
+    const result = WireSurfaceBuilder.undoResult(data)
+    expect(result.data).toEqual(data)
+  })
+
+  it('preserves undoExecutionId from input', () => {
+    const result = WireSurfaceBuilder.undoResult(data)
+    expect(result.data.undoExecutionId).toBe('undo-exec-002')
+  })
+})
+
+describe('WireSurfaceBuilder.messageStart', () => {
+  it('returns data part with type data-message-start', () => {
+    const result = WireSurfaceBuilder.messageStart('msg-123')
+    expect(result.type).toBe('data-message-start')
+  })
+
+  it('data.messageId matches input', () => {
+    const result = WireSurfaceBuilder.messageStart('msg-456')
+    expect(result.data.messageId).toBe('msg-456')
+  })
+
+  it('data.version is 1', () => {
+    const result = WireSurfaceBuilder.messageStart('msg-789')
+    expect(result.data.version).toBe(1)
+  })
+
+  it('data.timestamp is a valid ISO 8601 string', () => {
+    const result = WireSurfaceBuilder.messageStart('msg-ts')
+    const parsed = new Date(result.data.timestamp)
+    expect(parsed.toISOString()).toBe(result.data.timestamp)
+  })
+})
+
+describe('WireSurfaceBuilder.messageComplete', () => {
+  it('returns data part with type data-message-complete', () => {
+    const result = WireSurfaceBuilder.messageComplete('msg-123', 500)
+    expect(result.type).toBe('data-message-complete')
+  })
+
+  it('data.messageId matches input', () => {
+    const result = WireSurfaceBuilder.messageComplete('msg-456', 200)
+    expect(result.data.messageId).toBe('msg-456')
+  })
+
+  it('data.narrativeLength matches input', () => {
+    const result = WireSurfaceBuilder.messageComplete('msg-789', 1234)
+    expect(result.data.narrativeLength).toBe(1234)
+  })
+
+  it('data.version is 1', () => {
+    const result = WireSurfaceBuilder.messageComplete('msg-v', 100)
+    expect(result.data.version).toBe(1)
+  })
+
+  it('data.timestamp is a valid ISO 8601 string', () => {
+    const result = WireSurfaceBuilder.messageComplete('msg-ts', 300)
+    const parsed = new Date(result.data.timestamp)
+    expect(parsed.toISOString()).toBe(result.data.timestamp)
+  })
+})

package/src/org/__tests__/view-scopes.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest'
+import { VIEW_SCOPE_MAP, getViewScope } from '../view-scopes.js'
+
+describe('VIEW_SCOPE_MAP golden snapshot', () => {
+  it('exact values are frozen', () => {
+    expect(VIEW_SCOPE_MAP).toStrictEqual({
+      workspace: 'org.view_workspace',
+      timeline: 'org.view_timeline',
+      activity: 'org.view_activity',
+      strategy: 'org.view_strategy',
+      'internal-admin': 'internal.view_admin',
+      chat: null,
+      settings: null,
+      chats: null,
+      upgrade: null,
+    })
+  })
+})
+
+describe('getViewScope', () => {
+  it('returns the required scope for protected views', () => {
+    expect(getViewScope('workspace')).toBe('org.view_workspace')
+    expect(getViewScope('timeline')).toBe('org.view_timeline')
+    expect(getViewScope('activity')).toBe('org.view_activity')
+    expect(getViewScope('strategy')).toBe('org.view_strategy')
+    expect(getViewScope('internal-admin')).toBe('internal.view_admin')
+  })
+
+  it('returns null for public views', () => {
+    expect(getViewScope('chat')).toBeNull()
+    expect(getViewScope('settings')).toBeNull()
+    expect(getViewScope('chats')).toBeNull()
+    expect(getViewScope('upgrade')).toBeNull()
+  })
+
+  it('returns null for unknown view string', () => {
+    expect(getViewScope('nonexistent-view')).toBeNull()
+  })
+
+  it('returns null for empty string', () => {
+    expect(getViewScope('')).toBeNull()
+  })
+
+  it('returns null for view name that is a substring of a real view', () => {
+    expect(getViewScope('work')).toBeNull()
+  })
+})

package/src/ralph/__tests__/prd.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest'
+import { REPO_PRECEDENCE } from '../prd.js'
+
+describe('REPO_PRECEDENCE', () => {
+  it('has contracts first (dependency source)', () => {
+    expect(REPO_PRECEDENCE[0]).toBe('company-semantics-contracts')
+  })
+
+  it('exact values and order are frozen (golden snapshot)', () => {
+    expect(REPO_PRECEDENCE).toStrictEqual([
+      'company-semantics-contracts',
+      'company-semantics-control',
+      'company-semantics-ci',
+      'company-semantics-backend',
+      'company-semantics-edge',
+      'company-semantics-app',
+      'company-semantics-site',
+    ])
+  })
+
+  it('has exactly 7 entries (all known repos)', () => {
+    expect(REPO_PRECEDENCE).toHaveLength(7)
+  })
+
+  it('has no duplicates', () => {
+    expect(new Set(REPO_PRECEDENCE).size).toBe(REPO_PRECEDENCE.length)
+  })
+
+  it('all entries start with company-semantics- prefix', () => {
+    for (const repo of REPO_PRECEDENCE) {
+      expect(repo).toMatch(/^company-semantics-/)
+    }
+  })
+
+  it('all entries are non-empty strings', () => {
+    for (const repo of REPO_PRECEDENCE) {
+      expect(typeof repo).toBe('string')
+      expect(repo.length).toBeGreaterThan(0)
+    }
+  })
+})