@company-semantics/contracts 0.80.0 → 0.82.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.80.0",
+  "version": "0.82.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/index.ts

@@ -13,6 +13,12 @@
 
 export type { ExecutionKind } from './kinds'
 
+// =============================================================================
+// Lifecycle State
+// =============================================================================
+
+export type { ExecutionState } from './status'
+
 // =============================================================================
 // Definition Types
 // =============================================================================
@@ -22,6 +28,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,9 @@ export type {
   PreviewDataPart,
   // Confirmation types (Phase 4)
   ConfirmationChoice,
-  ConfirmationRisk,
+  ConfirmationRiskLevel,
   ConfirmationData,
   ConfirmationDataPart,
-  ConfirmationResponseData,
-  ConfirmationResponsePart,
-  ConfirmationResponseDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,
@@ -344,12 +341,15 @@ 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,
   ISO8601Timestamp,
   IconName,
   ExecutionDomain,
@@ -370,33 +370,6 @@ export {
   isValidExecutionKind,
 } 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 {
@@ -489,4 +462,34 @@ export type {
   DailyExecutionStats,
   ExecutionByUser,
   ExecutionDetail,
+  // Budget governance types (PRD-00232)
+  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,21 +26,44 @@ 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 ConfirmationRisk = 'low' | 'medium' | 'high';
+export type ConfirmationRiskLevel = 'low' | 'moderate' | 'high' | 'irreversible';
 
 /**
- * Confirmation request data payload.
+ * Human-readable confirmation dialog titles for each execution kind.
+ * Exhaustive — TypeScript enforces completeness via Record type.
  */
+export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
+  'integration.connect': 'Connect Integration',
+  'integration.disconnect': 'Disconnect Integration',
+  'profile.update': 'Update Profile',
+  'slack.send': 'Send Slack Message',
+};
+
+/**
+ * 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;
 }
 
 /**
@@ -57,31 +82,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,15 @@ export type {
 // Confirmation types
 export type {
   ConfirmationChoice,
-  ConfirmationRisk,
+  ConfirmationRiskLevel,
   ConfirmationData,
   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.

package/src/usage/execution-types.ts

@@ -89,3 +89,20 @@ export interface ExecutionDetail {
     toolCalls: number
   }>
 }
+
+// --- Budget governance types (PRD-00232) ---
+
+export interface BudgetCheck {
+  allowed: boolean
+  reason?: 'monthly_budget_exceeded' | 'approaching_limit'
+  remainingBudgetUsd?: string
+  usedThisMonthUsd?: string
+}
+
+export interface OrgBudgetSettings {
+  monthlyBudgetUsd: string | null
+  maxCostPerExecution: string | null
+  agenticMaxSteps: number | null
+  alertThresholdPct: number
+  enabled: boolean
+}