@company-semantics/contracts 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -28,6 +28,10 @@
       "types": "./src/mcp/index.ts",
       "default": "./src/mcp/index.ts"
     },
+    "./execution": {
+      "types": "./src/execution/index.ts",
+      "default": "./src/execution/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/execution/README.md

@@ -0,0 +1,46 @@
+# execution/
+
+## Purpose
+
+TypeScript types and registry for execution kinds and their governance metadata.
+
+## Invariants
+
+- Types only; minimal runtime code (pure functions for registry lookup)
+- No external dependencies (contracts policy)
+- `ExecutionKind` union MUST match keys in `EXECUTION_KINDS` registry
+- `EXECUTION_KINDS` is the single source of truth for display, governance, and UI metadata
+- `ExecutionSummary` and `TimelineUIEvent` are **projection contracts** (derived at query time, not stored)
+- `visibility` is derived from `EXECUTION_KINDS[kind].governance.visibility`, never independently authored
+- Unknown execution kinds MUST be rejected at API boundaries via `isValidExecutionKind()`
+
+## Public API
+
+### Types
+
+- `ExecutionKind` — Union of valid execution kind identifiers
+- `ExecutionKindDefinition` — Full definition schema for a kind
+- `ExecutionDomain` — Domain category (`integration`, `policy`, `data`, `system`)
+- `ISO8601Timestamp` — ISO 8601 timestamp string alias
+- `IconName` — Icon identifiers for UI
+
+### Projection Contracts
+
+- `ExecutionSummary` — Admin-facing execution view (derived from audit records)
+- `ExecutionTarget` — Target of execution (e.g., Slack workspace)
+- `ExecutionInitiator` — Who initiated the execution
+- `ExecutionStatus` — Execution status (`pending`, `succeeded`, `failed`)
+- `TimelineUIEvent` — User-facing timeline entry (derived from audit records)
+- `TimelineStatus` — Timeline-specific status mapping
+- `TimelineIcon` — Timeline-specific icon subset
+
+### Registry & Functions
+
+- `EXECUTION_KINDS` — Registry of all execution kinds
+- `getExecutionKindDefinition(kind)` — Type-safe registry lookup
+- `isValidExecutionKind(kind)` — Validate string is ExecutionKind
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-backend, company-semantics-app

package/src/execution/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Execution Domain Barrel
+ *
+ * Re-exports execution kind vocabulary types and registry.
+ * Import from '@company-semantics/contracts/execution'.
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+// =============================================================================
+// Kind Types
+// =============================================================================
+
+export type { ExecutionKind } from './kinds.js'
+
+// =============================================================================
+// Definition Types
+// =============================================================================
+
+export type {
+  ISO8601Timestamp,
+  IconName,
+  ExecutionDomain,
+  ExecutionKindDefinition,
+} from './types.js'
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+export {
+  EXECUTION_KINDS,
+  getExecutionKindDefinition,
+  isValidExecutionKind,
+} from './registry.js'
+
+// =============================================================================
+// Projection Contracts
+// =============================================================================
+
+// ExecutionSummary (admin-facing projection)
+export type {
+  ExecutionTarget,
+  ExecutionInitiator,
+  ExecutionStatus,
+  ExecutionSummary,
+} from './summary.js'
+
+// TimelineUIEvent (user-facing projection)
+export type {
+  TimelineStatus,
+  TimelineIcon,
+  TimelineUIEvent,
+} from './timeline-ui.js'

package/src/execution/kinds.ts

@@ -0,0 +1,27 @@
+/**
+ * Execution Kind Vocabulary
+ *
+ * Canonical type for execution kinds across Company Semantics.
+ * Each kind represents a discrete, auditable action in the system.
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+// =============================================================================
+// ExecutionKind Union
+// =============================================================================
+
+/**
+ * ExecutionKind identifies the type of execution action.
+ *
+ * Naming convention: `{domain}.{verb}`
+ * - domain: integration, policy, data, system
+ * - verb: action being performed (connect, disconnect, etc.)
+ *
+ * New kinds MUST be added to:
+ * 1. This union type
+ * 2. EXECUTION_KINDS registry in registry.ts
+ */
+export type ExecutionKind =
+  | 'integration.connect'
+  | 'integration.disconnect'

package/src/execution/registry.ts

@@ -0,0 +1,101 @@
+/**
+ * Execution Kind Registry
+ *
+ * Central registry of all execution kinds and their definitions.
+ * This is the single source of truth for execution metadata.
+ *
+ * Invariants:
+ * - Every ExecutionKind MUST have an entry in EXECUTION_KINDS
+ * - Registry keys MUST match definition.kind
+ * - Registry is exhaustive (satisfies Record<ExecutionKind, ...>)
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+import type { ExecutionKind } from './kinds.js'
+import type { ExecutionKindDefinition } from './types.js'
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+/**
+ * EXECUTION_KINDS is the authoritative registry.
+ *
+ * All display text, governance rules, and UI hints are derived from here.
+ * Backend executors and frontend components MUST use this registry
+ * rather than hardcoding values.
+ *
+ * To add a new kind:
+ * 1. Add to ExecutionKind union in kinds.ts
+ * 2. Add entry to this registry
+ * 3. Implement executor in backend
+ * 4. Add explanation template
+ */
+export const EXECUTION_KINDS = {
+  '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',
+    },
+  },
+} as const satisfies Record<ExecutionKind, ExecutionKindDefinition>
+
+// =============================================================================
+// Registry Helpers
+// =============================================================================
+
+/**
+ * Type-safe registry lookup.
+ * Returns the definition for a given execution kind.
+ */
+export function getExecutionKindDefinition(
+  kind: ExecutionKind
+): ExecutionKindDefinition {
+  return EXECUTION_KINDS[kind]
+}
+
+/**
+ * Check if a string is a valid ExecutionKind.
+ * Use at API boundaries to reject unknown kinds.
+ */
+export function isValidExecutionKind(kind: string): kind is ExecutionKind {
+  return kind in EXECUTION_KINDS
+}

package/src/execution/summary.ts

@@ -0,0 +1,101 @@
+/**
+ * Execution Summary Projection
+ *
+ * ExecutionSummary is a PROJECTION CONTRACT, not a storage contract.
+ * It describes what UI consumers receive, not what backends persist.
+ * Backend services derive this from audit records at query time.
+ *
+ * DERIVATION RULES:
+ * - ExecutionSummary.visibility MUST be derived from
+ *   EXECUTION_KINDS[kind].governance.visibility + execution facts.
+ * - It MUST NOT be independently authored or stored.
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+import type { ExecutionKind } from './kinds.js'
+import type { ISO8601Timestamp } from './types.js'
+
+// =============================================================================
+// Execution Target
+// =============================================================================
+
+/**
+ * Target of an execution action.
+ * Currently supports Slack integration; extensible for future integrations.
+ */
+export type ExecutionTarget =
+  | { type: 'slack'; workspaceId?: string }
+
+// =============================================================================
+// Initiator
+// =============================================================================
+
+/**
+ * Who initiated the execution.
+ */
+export interface ExecutionInitiator {
+  /** Actor type (user or automated system) */
+  actorType: 'user' | 'system'
+  /** Actor identifier (userId or system identifier) */
+  actorId: string
+  /** Human-readable name for display */
+  displayName: string
+}
+
+// =============================================================================
+// Execution Status
+// =============================================================================
+
+/**
+ * Status of an execution.
+ */
+export type ExecutionStatus = 'pending' | 'succeeded' | 'failed'
+
+// =============================================================================
+// Execution Summary
+// =============================================================================
+
+/**
+ * ExecutionSummary is a PROJECTION CONTRACT.
+ *
+ * This type represents the admin-facing view of an execution.
+ * It is derived from audit records, not stored directly.
+ *
+ * Invariants:
+ * - executionId is globally unique
+ * - visibility is derived from EXECUTION_KINDS[kind].governance.visibility
+ * - explanationAvailable reflects whether explanation can be generated
+ */
+export interface ExecutionSummary {
+  /** Unique execution identifier */
+  executionId: string
+
+  /** Type of execution */
+  kind: ExecutionKind
+
+  /** What the execution targeted */
+  target: ExecutionTarget
+
+  /** Current status */
+  status: ExecutionStatus
+
+  /** Who initiated the execution */
+  initiatedBy: ExecutionInitiator
+
+  /** When the execution was initiated (decision point) */
+  decidedAt: ISO8601Timestamp
+
+  /** When the execution completed (if finished) */
+  completedAt?: ISO8601Timestamp
+
+  /**
+   * Visibility level for this execution.
+   * Derived from EXECUTION_KINDS[kind].governance.visibility.
+   * Used for filtering in queries.
+   */
+  visibility: 'admin' | 'user'
+
+  /** Whether an explanation can be generated for this execution */
+  explanationAvailable: boolean
+}

package/src/execution/timeline-ui.ts

@@ -0,0 +1,77 @@
+/**
+ * Timeline UI Event Projection
+ *
+ * TimelineUIEvent is a PROJECTION CONTRACT, not a storage contract.
+ * It describes what the Timeline UI receives, not what backends persist.
+ * Backend services derive this from audit records at query time.
+ *
+ * DERIVATION RULES:
+ * - icon: Derived from EXECUTION_KINDS[kind].display.icon
+ * - label: Derived from EXECUTION_KINDS[kind].display.pastTenseLabel
+ * - These are NEVER independently authored or stored
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+import type { ISO8601Timestamp } from './types.js'
+
+// =============================================================================
+// Timeline Status
+// =============================================================================
+
+/**
+ * Status for timeline display.
+ * Maps from ExecutionStatus for UI-specific presentation.
+ */
+export type TimelineStatus = 'success' | 'failed' | 'pending'
+
+// =============================================================================
+// Timeline Icon
+// =============================================================================
+
+/**
+ * Icon for timeline items.
+ * Must match IconName but constrained to timeline-relevant icons.
+ */
+export type TimelineIcon = 'plug' | 'unlink'
+
+// =============================================================================
+// Timeline UI Event
+// =============================================================================
+
+/**
+ * TimelineUIEvent is a PROJECTION CONTRACT.
+ *
+ * This type represents a single event in the user-facing timeline.
+ * All display values are derived from EXECUTION_KINDS, not stored.
+ *
+ * Invariants:
+ * - label is derived from EXECUTION_KINDS[kind].display.pastTenseLabel
+ * - icon is derived from EXECUTION_KINDS[kind].display.icon
+ * - expandable indicates whether details can be fetched
+ */
+export interface TimelineUIEvent {
+  /** Execution ID for correlation and detail fetching */
+  executionId: string
+
+  /**
+   * Display label (past tense).
+   * Derived from EXECUTION_KINDS[kind].display.pastTenseLabel
+   */
+  label: string
+
+  /**
+   * Icon identifier.
+   * Derived from EXECUTION_KINDS[kind].display.icon
+   */
+  icon: TimelineIcon
+
+  /** Visual status indicator */
+  status: TimelineStatus
+
+  /** When this event occurred */
+  timestamp: ISO8601Timestamp
+
+  /** Whether this event has expandable details */
+  expandable: boolean
+}

package/src/execution/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Execution Types
+ *
+ * Interfaces for execution kind definitions and governance.
+ *
+ * @see ADR-CONT-029 for design rationale
+ */
+
+import type { ExecutionKind } from './kinds.js'
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/**
+ * ISO 8601 timestamp string.
+ * Example: "2026-01-08T14:30:00.000Z"
+ */
+export type ISO8601Timestamp = string
+
+/**
+ * Icon names for execution kinds.
+ * Must be supported by the frontend icon system.
+ */
+export type IconName = 'plug' | 'unlink'
+
+// =============================================================================
+// Execution Domain
+// =============================================================================
+
+/**
+ * Domain categories for execution kinds.
+ */
+export type ExecutionDomain = 'integration' | 'policy' | 'data' | 'system'
+
+// =============================================================================
+// Execution Kind Definition
+// =============================================================================
+
+/**
+ * Complete definition for an execution kind.
+ *
+ * This interface is the schema for entries in EXECUTION_KINDS registry.
+ * It captures display, governance, UI, and explanation metadata.
+ *
+ * Invariants:
+ * - kind field MUST match the registry key
+ * - reversibleBy (if set) MUST be a valid ExecutionKind
+ */
+export interface ExecutionKindDefinition {
+  /** The execution kind this definition describes */
+  kind: ExecutionKind
+
+  /** Domain category for grouping and filtering */
+  domain: ExecutionDomain
+
+  /** Display metadata for UI rendering */
+  display: {
+    /** Label shown on buttons/actions (imperative: "Connect Slack") */
+    label: string
+    /** Label for completed actions (past tense: "Slack connected") */
+    pastTenseLabel: string
+    /** Icon identifier for UI */
+    icon: IconName
+  }
+
+  /** Governance constraints */
+  governance: {
+    /** Who can see this execution in lists/timelines */
+    visibility: 'admin' | 'user'
+    /** Whether admin role is required to initiate */
+    requiresAdmin: boolean
+    /** If reversible, which kind reverses this action */
+    reversibleBy?: ExecutionKind
+  }
+
+  /** UI behavior hints */
+  ui: {
+    /** Show in admin settings panel */
+    showInAdmin: boolean
+    /** Show in user-facing timeline */
+    showInTimeline: boolean
+    /** Require confirmation dialog before execution */
+    confirmBeforeRun?: boolean
+  }
+
+  /** Explanation generation metadata */
+  explanation: {
+    /** Template ID for explanation builder */
+    templateId: string
+  }
+}

package/src/index.ts

@@ -181,3 +181,27 @@ export {
   getDroppedCount,
   WireSurfaceBuilder,
 } from './message-parts/index.js'
+
+// Execution kind types and registry
+// @see ADR-CONT-029 for design rationale
+export type {
+  ExecutionKind,
+  ISO8601Timestamp,
+  IconName,
+  ExecutionDomain,
+  ExecutionKindDefinition,
+  // Projection contracts
+  ExecutionTarget,
+  ExecutionInitiator,
+  ExecutionStatus,
+  ExecutionSummary,
+  TimelineStatus,
+  TimelineIcon,
+  TimelineUIEvent,
+} from './execution/index.js'
+
+export {
+  EXECUTION_KINDS,
+  getExecutionKindDefinition,
+  isValidExecutionKind,
+} from './execution/index.js'