@company-semantics/contracts 0.87.0 → 0.89.0

package/package.json

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

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

@@ -0,0 +1,222 @@
+import { describe, it, expect } from 'vitest'
+import type { ExecutionState } from '../status.js'
+import {
+  VALID_TRANSITIONS,
+  TERMINAL_STATES,
+  EFFECTIVE_TERMINAL_STATES,
+  assertValidTransition,
+} from '../status.js'
+import { LIFECYCLE_DECISIONS, applyIntent } from '../lifecycle.js'
+import type { ExecutionErrorCode } from '../errors.js'
+import { parseExpiresAt, isConfirmationExpired } from '../expiry.js'
+
+const ALL_STATES: ExecutionState[] = [
+  'pending_confirmation',
+  'blocked_pending_approval',
+  'ready',
+  'executing',
+  'completed',
+  'completed_with_rollbacks',
+  'failed_retryable',
+  'failed_terminal',
+  'failed_with_partial_execution',
+  'cancelled',
+  'expired',
+  'undone',
+]
+
+// ---------------------------------------------------------------------------
+// 1. EXHAUSTIVE TRANSITION MATRIX
+// ---------------------------------------------------------------------------
+describe('exhaustive transition matrix', () => {
+  for (const from of ALL_STATES) {
+    for (const to of ALL_STATES) {
+      const allowed = VALID_TRANSITIONS[from].includes(to)
+      it(`${from} -> ${to} should be ${allowed ? 'valid' : 'invalid'}`, () => {
+        if (allowed) {
+          expect(() => assertValidTransition(from, to)).not.toThrow()
+        } else {
+          expect(() => assertValidTransition(from, to)).toThrow(
+            `Invalid execution state transition: ${from} -> ${to}`,
+          )
+        }
+      })
+    }
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 2. TERMINAL_STATES CONSISTENCY
+// ---------------------------------------------------------------------------
+describe('TERMINAL_STATES consistency', () => {
+  it('contains exactly the states with empty transition arrays', () => {
+    const expectedTerminal = ALL_STATES.filter(
+      (s) => VALID_TRANSITIONS[s].length === 0,
+    )
+    expect(expectedTerminal.length).toBeGreaterThan(0)
+    for (const state of expectedTerminal) {
+      expect(TERMINAL_STATES.has(state)).toBe(true)
+    }
+    expect(TERMINAL_STATES.size).toBe(expectedTerminal.length)
+  })
+
+  it('does not contain states with non-empty transition arrays', () => {
+    const nonTerminal = ALL_STATES.filter(
+      (s) => VALID_TRANSITIONS[s].length > 0,
+    )
+    for (const state of nonTerminal) {
+      expect(TERMINAL_STATES.has(state)).toBe(false)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. EFFECTIVE_TERMINAL_STATES
+// ---------------------------------------------------------------------------
+describe('EFFECTIVE_TERMINAL_STATES', () => {
+  it('contains all TERMINAL_STATES', () => {
+    for (const state of TERMINAL_STATES) {
+      expect(EFFECTIVE_TERMINAL_STATES.has(state)).toBe(true)
+    }
+  })
+
+  it('contains completed', () => {
+    expect(EFFECTIVE_TERMINAL_STATES.has('completed')).toBe(true)
+  })
+
+  it('has size equal to TERMINAL_STATES + 1 (completed)', () => {
+    expect(EFFECTIVE_TERMINAL_STATES.size).toBe(TERMINAL_STATES.size + 1)
+  })
+
+  it('does not contain non-terminal, non-completed states', () => {
+    const nonEffectiveTerminal = ALL_STATES.filter(
+      (s) => !TERMINAL_STATES.has(s) && s !== 'completed',
+    )
+    for (const state of nonEffectiveTerminal) {
+      expect(EFFECTIVE_TERMINAL_STATES.has(state)).toBe(false)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. DECISION TABLE KEY CONSISTENCY
+// ---------------------------------------------------------------------------
+describe('decision table key consistency', () => {
+  it('LIFECYCLE_DECISIONS.confirm keys match VALID_TRANSITIONS keys', () => {
+    const transitionKeys = Object.keys(VALID_TRANSITIONS).sort()
+    const decisionKeys = Object.keys(LIFECYCLE_DECISIONS.confirm).sort()
+    expect(decisionKeys).toEqual(transitionKeys)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 5. APPROVE-TRANSITION DRIFT
+// ---------------------------------------------------------------------------
+describe('approve-transition drift', () => {
+  it('every state with approve decision can transition to ready', () => {
+    for (const state of ALL_STATES) {
+      if (LIFECYCLE_DECISIONS.confirm[state] === 'approve') {
+        expect(
+          VALID_TRANSITIONS[state].includes('ready'),
+        ).toBe(true)
+      }
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 6. APPLY_INTENT UNIT TESTS
+// ---------------------------------------------------------------------------
+describe('applyIntent', () => {
+  it('pending_confirmation + confirm = approve', () => {
+    expect(applyIntent('pending_confirmation', 'confirm')).toBe('approve')
+  })
+
+  it('expired + confirm = expired', () => {
+    expect(applyIntent('expired', 'confirm')).toBe('expired')
+  })
+
+  it('cancelled + confirm = conflict', () => {
+    expect(applyIntent('cancelled', 'confirm')).toBe('conflict')
+  })
+
+  it('ready + confirm = already_confirmed', () => {
+    expect(applyIntent('ready', 'confirm')).toBe('already_confirmed')
+  })
+
+  it('blocked_pending_approval + confirm = awaiting_approval', () => {
+    expect(applyIntent('blocked_pending_approval', 'confirm')).toBe(
+      'awaiting_approval',
+    )
+  })
+
+  it('failed_terminal + confirm = conflict', () => {
+    expect(applyIntent('failed_terminal', 'confirm')).toBe('conflict')
+  })
+
+  it('undone + confirm = conflict', () => {
+    expect(applyIntent('undone', 'confirm')).toBe('conflict')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. EXECUTION_ERROR TYPE TESTS
+// ---------------------------------------------------------------------------
+describe('ExecutionErrorCode', () => {
+  it('covers all expected error codes', () => {
+    const codes: ExecutionErrorCode[] = [
+      'execution_expired',
+      'execution_already_confirmed',
+      'execution_awaiting_approval',
+      'execution_not_found',
+      'execution_forbidden',
+      'execution_invalid_transition',
+    ]
+    expect(codes).toHaveLength(6)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 8. EXPIRY HELPER TESTS
+// ---------------------------------------------------------------------------
+describe('parseExpiresAt', () => {
+  it('returns undefined for undefined input', () => {
+    expect(parseExpiresAt(undefined)).toBeUndefined()
+  })
+
+  it('returns undefined for invalid date string', () => {
+    expect(parseExpiresAt('invalid')).toBeUndefined()
+  })
+
+  it('returns correct epoch ms for valid ISO string', () => {
+    const result = parseExpiresAt('2026-01-01T00:00:00Z')
+    expect(result).toBe(new Date('2026-01-01T00:00:00Z').getTime())
+  })
+
+  it('returns undefined for empty string', () => {
+    expect(parseExpiresAt('')).toBeUndefined()
+  })
+})
+
+describe('isConfirmationExpired', () => {
+  it('returns false for undefined expiresAtMs', () => {
+    expect(isConfirmationExpired(undefined)).toBe(false)
+  })
+
+  it('returns true for past timestamp', () => {
+    const pastMs = Date.now() - 60_000
+    expect(isConfirmationExpired(pastMs)).toBe(true)
+  })
+
+  it('returns false for future timestamp', () => {
+    const futureMs = Date.now() + 60_000
+    expect(isConfirmationExpired(futureMs)).toBe(false)
+  })
+
+  it('works with custom now parameter', () => {
+    const expiresAtMs = 1000
+    expect(isConfirmationExpired(expiresAtMs, 999)).toBe(false)
+    expect(isConfirmationExpired(expiresAtMs, 1000)).toBe(true)
+    expect(isConfirmationExpired(expiresAtMs, 1001)).toBe(true)
+  })
+})

package/src/execution/errors.ts

@@ -0,0 +1,14 @@
+export type ExecutionErrorCode =
+  | 'execution_expired'
+  | 'execution_already_confirmed'
+  | 'execution_awaiting_approval'
+  | 'execution_not_found'
+  | 'execution_forbidden'
+  | 'execution_invalid_transition';
+
+export interface ExecutionError {
+  readonly name: 'ExecutionError';
+  readonly code: ExecutionErrorCode;
+  readonly message: string;
+  readonly httpStatus?: number;
+}

package/src/execution/expiry.ts

@@ -0,0 +1,34 @@
+/**
+ * Centralized expiry check helpers for execution confirmations.
+ *
+ * Expiry logic lives here instead of inline in the confirm endpoint,
+ * the background job, and the client timer. Centralizing prevents drift.
+ *
+ * Uses pre-parsed epoch ms (number) instead of re-parsing ISO strings
+ * to avoid repeated Date construction.
+ */
+
+/**
+ * Parses an ISO 8601 string to epoch ms.
+ * Returns undefined if the input is undefined or an invalid date (NaN guard).
+ * Called once at creation time; the result is compared cheaply thereafter.
+ */
+export function parseExpiresAt(
+  expiresAt: string | undefined,
+): number | undefined {
+  if (expiresAt === undefined) return undefined
+  const ms = new Date(expiresAt).getTime()
+  return Number.isFinite(ms) ? ms : undefined
+}
+
+/**
+ * Compares pre-parsed epoch ms to determine if a confirmation has expired.
+ * Defaults `now` to Date.now(). Returns false if expiresAtMs is undefined.
+ */
+export function isConfirmationExpired(
+  expiresAtMs: number | undefined,
+  now?: number,
+): boolean {
+  if (expiresAtMs === undefined) return false
+  return (now ?? Date.now()) >= expiresAtMs
+}

package/src/execution/index.ts

@@ -72,6 +72,39 @@ export type { ExecutionKind } from './kinds'
 
 export type { ExecutionState } from './status'
 
+export {
+  VALID_TRANSITIONS,
+  TERMINAL_STATES,
+  EFFECTIVE_TERMINAL_STATES,
+  assertValidTransition,
+} from './status'
+
+// =============================================================================
+// Lifecycle Decision Engine
+// =============================================================================
+
+export type {
+  ExecutionIntent as LifecycleIntent,
+  LifecycleDecision,
+} from './lifecycle'
+
+export {
+  LIFECYCLE_DECISIONS,
+  applyIntent,
+} from './lifecycle'
+
+// =============================================================================
+// Expiry Helpers
+// =============================================================================
+
+export { parseExpiresAt, isConfirmationExpired } from './expiry'
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+export type { ExecutionErrorCode, ExecutionError } from './errors'
+
 // =============================================================================
 // Definition Types
 // =============================================================================

package/src/execution/lifecycle.ts

@@ -0,0 +1,39 @@
+import type { ExecutionState } from './status';
+
+export type ExecutionIntent = 'confirm';
+
+export type LifecycleDecision =
+  | 'approve'
+  | 'already_confirmed'
+  | 'awaiting_approval'
+  | 'expired'
+  | 'conflict';
+
+type DecisionTable = Record<
+  ExecutionIntent,
+  Record<ExecutionState, LifecycleDecision>
+>;
+
+export const LIFECYCLE_DECISIONS: DecisionTable = {
+  confirm: {
+    pending_confirmation: 'approve',
+    expired: 'expired',
+    cancelled: 'conflict',
+    blocked_pending_approval: 'awaiting_approval',
+    ready: 'already_confirmed',
+    executing: 'already_confirmed',
+    completed: 'already_confirmed',
+    completed_with_rollbacks: 'already_confirmed',
+    failed_retryable: 'conflict',
+    failed_terminal: 'conflict',
+    failed_with_partial_execution: 'conflict',
+    undone: 'conflict',
+  },
+};
+
+export function applyIntent(
+  state: ExecutionState,
+  intent: ExecutionIntent,
+): LifecycleDecision {
+  return LIFECYCLE_DECISIONS[intent][state];
+}

package/src/execution/status.ts

@@ -41,6 +41,17 @@
  * bigint), not timestamps. UNIQUE(execution_id, event_sequence) enforced
  * at database level. event_sequence for ordering, created_at for duration —
  * distinct concerns.
+ *
+ * ## Execution Invariants
+ *
+ * - **INV-EXEC-1**: Events are append-only. No UPDATE/DELETE on execution_events.
+ * - **INV-EXEC-2**: Current state = stateAfter of latest event (by event_sequence).
+ *   execution_audit.state is a denormalized cache.
+ * - **INV-EXEC-3**: All transitions must satisfy VALID_TRANSITIONS[from].includes(to).
+ * - **INV-EXEC-4**: Transition validation + event insertion within same
+ *   advisory-locked transaction.
+ * - **INV-EXEC-5**: failed_retryable -> ready loop bounded by executor retry budget.
+ *   Retry events must include retryAttempt in metadata.
  */
 export type ExecutionState =
   | 'pending_confirmation'
@@ -55,3 +66,39 @@ export type ExecutionState =
   | 'cancelled'
   | 'expired'
   | 'undone';
+
+export const VALID_TRANSITIONS: Record<ExecutionState, readonly ExecutionState[]> = {
+  pending_confirmation: ['ready', 'blocked_pending_approval', 'cancelled', 'expired'],
+  blocked_pending_approval: ['ready', 'cancelled', 'expired'],
+  ready: ['executing'],
+  executing: [
+    'completed', 'completed_with_rollbacks',
+    'failed_retryable', 'failed_terminal',
+    'failed_with_partial_execution', 'cancelled',
+  ],
+  completed: ['undone'],
+  completed_with_rollbacks: [],
+  failed_retryable: ['ready'],
+  failed_terminal: [],
+  failed_with_partial_execution: [],
+  cancelled: [],
+  expired: [],
+  undone: [],
+};
+
+export const TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set(
+  (Object.entries(VALID_TRANSITIONS) as [ExecutionState, readonly ExecutionState[]][])
+    .filter(([, targets]) => targets.length === 0)
+    .map(([state]) => state)
+);
+
+export const EFFECTIVE_TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set([
+  ...TERMINAL_STATES,
+  'completed',
+]);
+
+export function assertValidTransition(from: ExecutionState, to: ExecutionState): void {
+  if (!VALID_TRANSITIONS[from].includes(to)) {
+    throw new Error(`Invalid execution state transition: ${from} -> ${to}`);
+  }
+}

package/src/index.ts

@@ -2,11 +2,10 @@
  * @company-semantics/contracts
  *
  * Shared semantic vocabulary across Company Semantics codebases.
- * Types only - no runtime code, no business logic.
+ * Types and pure deterministic functions — no runtime code, no business logic.
  *
- * This package intentionally contains only minimal shared vocabulary,
- * not full domain models. Structural types live in individual codebases
- * until they are proven stable.
+ * This package contains shared vocabulary and pure derivation functions.
+ * Structural types live in individual codebases until they are proven stable.
  *
  * @see https://github.com/company-semantics/company-semantics-contracts
  */
@@ -466,6 +465,14 @@ export type {
   UsageByFeature,
   UsageByUser,
   OrgUsageResponse,
+  // Unified usage types (PRD-00276/277)
+  UnifiedUsageSummary,
+  UnifiedDailyUsage,
+  UnifiedProfileUsage,
+  UnifiedUserUsage,
+  UnifiedModelUsage,
+  UnifiedFeatureUsage,
+  UnifiedUsageResponse,
 } from './usage/types'
 
 // Runtime execution telemetry types

package/src/mcp/{capability-graph.test.ts → __tests__/capability-graph.test.ts}

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
-import { buildCapabilityGraph } from './capability-graph'
-import type { MCPToolDescriptor } from './index'
+import { buildCapabilityGraph } from '../capability-graph'
+import type { MCPToolDescriptor } from '../index'
 
 /**
  * Helper to create minimal MCPToolDescriptor for testing.

package/src/mcp/failure-context.ts

@@ -0,0 +1,48 @@
+/**
+ * FailureContext — Structured Recovery for MCP Tool Failures
+ *
+ * When an MCP tool fails, the system emits a FailureContext that constrains
+ * the agent's next action to registered recovery actions only.
+ *
+ * INVARIANTS:
+ * - recoveryActions is exhaustive — the LLM cannot invent alternatives
+ * - 'cancel' is always implicitly available (not declared in recoveryActions)
+ * - No UI strings — labels/hints are the app layer's responsibility
+ * - depth tracks recovery chain length (1 = first failure)
+ * - At most one FailureContext is active at a time (no stacking)
+ */
+
+/**
+ * Structured recovery context emitted when an MCP tool call fails.
+ * Constrains the agent's next action to registered recovery options.
+ */
+export interface FailureContext {
+  /** MCP tool name that failed (e.g., 'cs_post_slack_message') */
+  tool: string;
+  /** Machine-readable error code from the error code registry */
+  reason: string;
+  /** Whether the same call might succeed on retry */
+  retryable: boolean;
+  /**
+   * Exhaustive list of allowed recovery actions.
+   * The agent MUST only invoke tools from this list until resolved.
+   * Empty array = cancel-only (no tool-based recovery available).
+   */
+  recoveryActions: RecoveryAction[];
+  /**
+   * Recovery chain depth. Starts at 1 on first failure.
+   * Incremented when a recovery action itself fails.
+   * When depth exceeds MAX_RECOVERY_DEPTH, only pure (read-only) tools remain available.
+   */
+  depth: number;
+}
+
+/**
+ * A recovery action the agent may take.
+ *
+ * Discriminated union — 'retry' is distinct from calling the same tool.
+ * Retry implies: arguments may change, timing may change, reason awareness.
+ */
+export type RecoveryAction =
+  | { type: 'retry' }
+  | { type: 'tool'; tool: string };

package/src/mcp/index.ts

@@ -1,6 +1,7 @@
 import type { ResourceType } from './resources'
 export type { ResourceType } from './resources'
 export { buildCapabilityGraph } from './capability-graph'
+export type { FailureContext, RecoveryAction } from './failure-context'
 
 /**
  * MCP Tool Discovery Types
@@ -214,7 +215,7 @@ export interface MCPToolDescriptor {
  * Edge in the capability graph connecting two tools via a resource.
  * A tool that produces a resource connects to tools that consume it.
  *
- * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface CapabilityGraphEdge {
   /** Tool ID that produces the resource */
@@ -231,7 +232,7 @@ export interface CapabilityGraphEdge {
  * Named workflow derived from capability graph paths.
  * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
  *
- * @stub Implementation in PRD-00268 (buildCapabilityGraph)
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface ToolWorkflow {
   /** Workflow name (e.g., "Slack Onboarding") */
@@ -246,7 +247,7 @@ export interface ToolWorkflow {
  * Capability graph derived from tool resource flow metadata.
  * Built from produces/consumes fields on MCPToolDescriptor.
  *
- * @stub Type definition only. buildCapabilityGraph() ships in PRD-00268.
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
  */
 export interface CapabilityGraph {
   /** Resource flow edges between tools */
@@ -269,7 +270,7 @@ export interface ToolDiscoveryResponse {
    * Capability graph derived from tool resource flow metadata.
    * Optional — discovery responses may or may not include the computed graph.
    *
-   * @stub Graph computation ships in PRD-00268 (buildCapabilityGraph).
+   * @see capability-graph.ts for buildCapabilityGraph() implementation
    */
   graph?: CapabilityGraph
 }

package/src/message-parts/confirmation.ts

@@ -67,6 +67,8 @@ export interface ConfirmationData {
   risk: ConfirmationRiskLevel;
   /** Lifecycle record ID — must exist before confirmation part is emitted */
   executionId: string;
+  /** ISO 8601 deadline for confirmation window. Absent for legacy messages. */
+  expiresAt?: string;
 }
 
 /**

package/src/usage/types.ts

@@ -46,6 +46,9 @@ export interface UsageByUser {
   requestCount: number;
 }
 
+/**
+ * @deprecated Use UnifiedUsageResponse instead. Will be removed in v1.0.
+ */
 export interface OrgUsageResponse {
   summary: UsageSummary;
   daily: DailyUsage[];
@@ -53,3 +56,64 @@ export interface OrgUsageResponse {
   byFeature: UsageByFeature[];
   topUsers: UsageByUser[];
 }
+
+// ---------------------------------------------------------------------------
+// Unified Usage Response (PRD-00276/277)
+// ---------------------------------------------------------------------------
+
+export interface UnifiedUsageSummary {
+  executions: number;
+  totalCostUsd: string;
+  totalTokens: number;
+  avgDurationMs: number;
+  failureRate: number;
+}
+
+export interface UnifiedDailyUsage {
+  date: string;
+  executions: number;
+  totalCostUsd: string;
+}
+
+export interface UnifiedProfileUsage {
+  profile: string;
+  executions: number;
+  percentOfTotal: number;
+  totalCostUsd: string;
+  avgDurationMs: number;
+  failureRate: number;
+}
+
+export interface UnifiedUserUsage {
+  userId: string;
+  email: string;
+  executions: number;
+  totalCostUsd: string;
+  totalTokens: number;
+  favoriteProfile: string;
+}
+
+export interface UnifiedModelUsage {
+  model: string;
+  provider: string;
+  totalTokens: number;
+  estimatedCostUsd: string;
+  requestCount: number;
+}
+
+export interface UnifiedFeatureUsage {
+  feature: string;
+  totalTokens: number;
+  estimatedCostUsd: string;
+  requestCount: number;
+}
+
+export interface UnifiedUsageResponse {
+  period: { start: string; end: string };
+  summary: UnifiedUsageSummary;
+  daily: UnifiedDailyUsage[];
+  byProfile: UnifiedProfileUsage[];
+  byUser: UnifiedUserUsage[];
+  byModel: UnifiedModelUsage[];
+  byFeature: UnifiedFeatureUsage[];
+}