@company-semantics/contracts 9.0.0 → 9.2.0

package/src/execution/kinds.ts

@@ -23,10 +23,10 @@
  * 2. EXECUTION_KINDS registry in registry.ts
  */
 export type ExecutionKind =
-  | 'integration.connect'
-  | 'integration.disconnect'
-  | 'profile.update'
-  | 'slack.send'
-  | 'data.ingest'
-  | 'data.scope'
-  | 'system.cleanup'
+  | "integration.connect"
+  | "integration.disconnect"
+  | "profile.update"
+  | "slack.send"
+  | "data.ingest"
+  | "data.scope"
+  | "system.cleanup";

package/src/execution/lifecycle.ts

@@ -1,13 +1,13 @@
-import type { ExecutionState } from './status';
+import type { ExecutionState } from "./status";
 
-export type ExecutionIntent = 'confirm' | 'reject';
+export type ExecutionIntent = "confirm" | "reject";
 
 export type LifecycleDecision =
-  | 'approve'
-  | 'already_confirmed'
-  | 'awaiting_approval'
-  | 'expired'
-  | 'conflict';
+  | "approve"
+  | "already_confirmed"
+  | "awaiting_approval"
+  | "expired"
+  | "conflict";
 
 type DecisionTable = Record<
   ExecutionIntent,
@@ -16,34 +16,34 @@ type DecisionTable = Record<
 
 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_exhausted: 'conflict',
-    failed_terminal: 'conflict',
-    failed_with_partial_execution: 'conflict',
-    undone: 'conflict',
+    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_exhausted: "conflict",
+    failed_terminal: "conflict",
+    failed_with_partial_execution: "conflict",
+    undone: "conflict",
   },
   reject: {
-    pending_confirmation: 'approve',
-    expired: 'expired',
-    cancelled: 'conflict',
-    blocked_pending_approval: 'conflict',
-    ready: 'conflict',
-    executing: 'conflict',
-    completed: 'conflict',
-    completed_with_rollbacks: 'conflict',
-    failed_retryable: 'conflict',
-    failed_exhausted: 'conflict',
-    failed_terminal: 'conflict',
-    failed_with_partial_execution: 'conflict',
-    undone: 'conflict',
+    pending_confirmation: "approve",
+    expired: "expired",
+    cancelled: "conflict",
+    blocked_pending_approval: "conflict",
+    ready: "conflict",
+    executing: "conflict",
+    completed: "conflict",
+    completed_with_rollbacks: "conflict",
+    failed_retryable: "conflict",
+    failed_exhausted: "conflict",
+    failed_terminal: "conflict",
+    failed_with_partial_execution: "conflict",
+    undone: "conflict",
   },
 };
 

package/src/execution/registry.ts

@@ -12,8 +12,8 @@
  * @see ADR-CONT-029 for design rationale
  */
 
-import type { ExecutionKind } from './kinds'
-import type { ExecutionKindDefinition } from './types'
+import type { ExecutionKind } from "./kinds";
+import type { ExecutionKindDefinition } from "./types";
 
 // =============================================================================
 // Registry
@@ -33,18 +33,18 @@ import type { ExecutionKindDefinition } from './types'
  * 4. Add explanation template
  */
 export const EXECUTION_KINDS = {
-  'integration.connect': {
-    kind: 'integration.connect',
-    domain: 'integration',
+  "integration.connect": {
+    kind: "integration.connect",
+    domain: "integration",
     display: {
-      label: 'Connect Slack',
-      pastTenseLabel: 'Slack connected',
-      icon: 'plug',
+      label: "Connect Slack",
+      pastTenseLabel: "Slack connected",
+      icon: "plug",
     },
     governance: {
-      visibility: 'admin',
+      visibility: "admin",
       requiresAdmin: true,
-      reversibleBy: 'integration.disconnect',
+      reversibleBy: "integration.disconnect",
     },
     ui: {
       showInAdmin: true,
@@ -52,19 +52,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: false,
     },
     explanation: {
-      templateId: 'integration.connect',
+      templateId: "integration.connect",
     },
   },
-  'integration.disconnect': {
-    kind: 'integration.disconnect',
-    domain: 'integration',
+  "integration.disconnect": {
+    kind: "integration.disconnect",
+    domain: "integration",
     display: {
-      label: 'Disconnect Slack',
-      pastTenseLabel: 'Slack disconnected',
-      icon: 'unlink',
+      label: "Disconnect Slack",
+      pastTenseLabel: "Slack disconnected",
+      icon: "unlink",
     },
     governance: {
-      visibility: 'admin',
+      visibility: "admin",
       requiresAdmin: true,
     },
     ui: {
@@ -73,19 +73,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'integration.disconnect',
+      templateId: "integration.disconnect",
     },
   },
-  'profile.update': {
-    kind: 'profile.update',
-    domain: 'profile',
+  "profile.update": {
+    kind: "profile.update",
+    domain: "profile",
     display: {
-      label: 'Update Profile',
-      pastTenseLabel: 'Profile updated',
-      icon: 'pencil',
+      label: "Update Profile",
+      pastTenseLabel: "Profile updated",
+      icon: "pencil",
     },
     governance: {
-      visibility: 'user',
+      visibility: "user",
       requiresAdmin: false,
     },
     ui: {
@@ -94,19 +94,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'profile.update',
+      templateId: "profile.update",
     },
   },
-  'slack.send': {
-    kind: 'slack.send',
-    domain: 'communication',
+  "slack.send": {
+    kind: "slack.send",
+    domain: "communication",
     display: {
-      label: 'Send Slack Message',
-      pastTenseLabel: 'Slack message sent',
-      icon: 'send',
+      label: "Send Slack Message",
+      pastTenseLabel: "Slack message sent",
+      icon: "send",
     },
     governance: {
-      visibility: 'user',
+      visibility: "user",
       requiresAdmin: false,
     },
     ui: {
@@ -115,19 +115,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'slack.send',
+      templateId: "slack.send",
     },
   },
-  'data.ingest': {
-    kind: 'data.ingest',
-    domain: 'data',
+  "data.ingest": {
+    kind: "data.ingest",
+    domain: "data",
     display: {
-      label: 'Import Channel',
-      pastTenseLabel: 'Channel imported',
-      icon: 'send',
+      label: "Import Channel",
+      pastTenseLabel: "Channel imported",
+      icon: "send",
     },
     governance: {
-      visibility: 'user',
+      visibility: "user",
       requiresAdmin: false,
     },
     ui: {
@@ -136,19 +136,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'data-ingest',
+      templateId: "data-ingest",
     },
   },
-  'data.scope': {
-    kind: 'data.scope',
-    domain: 'data',
+  "data.scope": {
+    kind: "data.scope",
+    domain: "data",
     display: {
-      label: 'Update Channel Scope',
-      pastTenseLabel: 'Channel scope updated',
-      icon: 'pencil',
+      label: "Update Channel Scope",
+      pastTenseLabel: "Channel scope updated",
+      icon: "pencil",
     },
     governance: {
-      visibility: 'admin',
+      visibility: "admin",
       requiresAdmin: true,
     },
     ui: {
@@ -157,19 +157,19 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'data-scope',
+      templateId: "data-scope",
     },
   },
-  'system.cleanup': {
-    kind: 'system.cleanup',
-    domain: 'system',
+  "system.cleanup": {
+    kind: "system.cleanup",
+    domain: "system",
     display: {
-      label: 'Cleanup Connections',
-      pastTenseLabel: 'Connections cleaned up',
-      icon: 'unlink',
+      label: "Cleanup Connections",
+      pastTenseLabel: "Connections cleaned up",
+      icon: "unlink",
     },
     governance: {
-      visibility: 'admin',
+      visibility: "admin",
       requiresAdmin: true,
     },
     ui: {
@@ -178,10 +178,10 @@ export const EXECUTION_KINDS = {
       confirmBeforeRun: true,
     },
     explanation: {
-      templateId: 'system-cleanup',
+      templateId: "system-cleanup",
     },
   },
-} as const satisfies Record<ExecutionKind, ExecutionKindDefinition>
+} as const satisfies Record<ExecutionKind, ExecutionKindDefinition>;
 
 // =============================================================================
 // Registry Helpers
@@ -192,9 +192,9 @@ export const EXECUTION_KINDS = {
  * Returns the definition for a given execution kind.
  */
 export function getExecutionKindDefinition(
-  kind: ExecutionKind
+  kind: ExecutionKind,
 ): ExecutionKindDefinition {
-  return EXECUTION_KINDS[kind]
+  return EXECUTION_KINDS[kind];
 }
 
 /**
@@ -202,5 +202,5 @@ export function getExecutionKindDefinition(
  * Use at API boundaries to reject unknown kinds.
  */
 export function isValidExecutionKind(kind: string): kind is ExecutionKind {
-  return kind in EXECUTION_KINDS
+  return kind in EXECUTION_KINDS;
 }

package/src/execution/schemas.ts

@@ -7,7 +7,7 @@
  * @see ADR-CONT-029 for design rationale
  */
 
-import { z } from 'zod'
+import { z } from "zod";
 
 // =============================================================================
 // Execution Summary
@@ -16,13 +16,13 @@ import { z } from 'zod'
 export const ExecutionSummarySchema = z.object({
   executionId: z.string().uuid(),
   kind: z.string(),
-  status: z.enum(['pending', 'succeeded', 'failed']),
+  status: z.enum(["pending", "succeeded", "failed"]),
   decidedAt: z.string().datetime({ offset: true }),
   completedAt: z.string().datetime({ offset: true }).optional(),
   target: z.object({ type: z.string() }),
-})
+});
 
-export type ExecutionSummaryResponse = z.infer<typeof ExecutionSummarySchema>
+export type ExecutionSummaryResponse = z.infer<typeof ExecutionSummarySchema>;
 
 // =============================================================================
 // Execution List Response
@@ -32,9 +32,9 @@ export const ExecutionListResponseSchema = z.object({
   executions: z.array(ExecutionSummarySchema),
   nextCursor: z.string().nullable().optional(),
   hasMore: z.boolean().optional(),
-})
+});
 
-export type ExecutionListResponse = z.infer<typeof ExecutionListResponseSchema>
+export type ExecutionListResponse = z.infer<typeof ExecutionListResponseSchema>;
 
 // =============================================================================
 // Timeline Event
@@ -45,7 +45,7 @@ const TimelineRelatedIdsSchema = z.object({
   artifactId: z.string().optional(),
   rollbackId: z.string().optional(),
   provenanceIds: z.array(z.string()).optional(),
-})
+});
 
 export const TimelineEventSchema = z.object({
   eventId: z.string(),
@@ -56,10 +56,10 @@ export const TimelineEventSchema = z.object({
   summary: z.string(),
   details: z.record(z.string(), z.unknown()).optional(),
   relatedIds: TimelineRelatedIdsSchema.optional(),
-  visibilityLevel: z.enum(['system', 'oversight', 'org_admin', 'user']),
-})
+  visibilityLevel: z.enum(["system", "oversight", "org_admin", "user"]),
+});
 
-export type TimelineEvent = z.infer<typeof TimelineEventSchema>
+export type TimelineEvent = z.infer<typeof TimelineEventSchema>;
 
 // =============================================================================
 // Execution Timeline Response
@@ -67,9 +67,11 @@ export type TimelineEvent = z.infer<typeof TimelineEventSchema>
 
 export const ExecutionTimelineResponseSchema = z.object({
   events: z.array(TimelineEventSchema),
-})
+});
 
-export type ExecutionTimelineResponse = z.infer<typeof ExecutionTimelineResponseSchema>
+export type ExecutionTimelineResponse = z.infer<
+  typeof ExecutionTimelineResponseSchema
+>;
 
 // =============================================================================
 // Execution Lifecycle Responses
@@ -77,26 +79,32 @@ export type ExecutionTimelineResponse = z.infer<typeof ExecutionTimelineResponse
 
 export const ConfirmExecutionResponseSchema = z.object({
   status: z.enum([
-    'executing',
-    'blocked_pending_approval',
-    'already_confirmed',
-    'awaiting_approval',
+    "executing",
+    "blocked_pending_approval",
+    "already_confirmed",
+    "awaiting_approval",
   ]),
   code: z.string().optional(),
   executionId: z.string().optional(),
-})
+});
 
-export type ConfirmExecutionResponse = z.infer<typeof ConfirmExecutionResponseSchema>
+export type ConfirmExecutionResponse = z.infer<
+  typeof ConfirmExecutionResponseSchema
+>;
 
 export const RejectExecutionResponseSchema = z.object({
-  status: z.literal('cancelled'),
-})
+  status: z.literal("cancelled"),
+});
 
-export type RejectExecutionResponse = z.infer<typeof RejectExecutionResponseSchema>
+export type RejectExecutionResponse = z.infer<
+  typeof RejectExecutionResponseSchema
+>;
 
 export const StartExecutionResponseSchema = z.object({
   executionId: z.string().uuid(),
   redirectUrl: z.string().optional(),
-})
+});
 
-export type StartExecutionResponse = z.infer<typeof StartExecutionResponseSchema>
+export type StartExecutionResponse = z.infer<
+  typeof StartExecutionResponseSchema
+>;

package/src/execution/status.ts

@@ -55,32 +55,43 @@
  *   Retry events must include retryAttempt in metadata.
  */
 export type ExecutionState =
-  | 'pending_confirmation'
-  | 'blocked_pending_approval'
-  | 'ready'
-  | 'executing'
-  | 'completed'
-  | 'completed_with_rollbacks'
-  | 'failed_retryable'
-  | 'failed_exhausted'
-  | 'failed_terminal'
-  | 'failed_with_partial_execution'
-  | 'cancelled'
-  | 'expired'
-  | 'undone';
+  | "pending_confirmation"
+  | "blocked_pending_approval"
+  | "ready"
+  | "executing"
+  | "completed"
+  | "completed_with_rollbacks"
+  | "failed_retryable"
+  | "failed_exhausted"
+  | "failed_terminal"
+  | "failed_with_partial_execution"
+  | "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'],
+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",
+    "completed_with_rollbacks",
+    "failed_retryable",
+    "failed_terminal",
+    "failed_with_partial_execution",
+    "cancelled",
   ],
-  completed: ['undone'],
+  completed: ["undone"],
   completed_with_rollbacks: [],
-  failed_retryable: ['ready', 'failed_exhausted'],
+  failed_retryable: ["ready", "failed_exhausted"],
   failed_exhausted: [],
   failed_terminal: [],
   failed_with_partial_execution: [],
@@ -90,17 +101,25 @@ export const VALID_TRANSITIONS: Record<ExecutionState, readonly ExecutionState[]
 };
 
 export const TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set(
-  (Object.entries(VALID_TRANSITIONS) as [ExecutionState, readonly ExecutionState[]][])
+  (
+    Object.entries(VALID_TRANSITIONS) as [
+      ExecutionState,
+      readonly ExecutionState[],
+    ][]
+  )
     .filter(([, targets]) => targets.length === 0)
-    .map(([state]) => state)
+    .map(([state]) => state),
 );
 
 export const EFFECTIVE_TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set([
   ...TERMINAL_STATES,
-  'completed',
+  "completed",
 ]);
 
-export function assertValidTransition(from: ExecutionState, to: ExecutionState): void {
+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/execution/summary.ts

@@ -13,8 +13,8 @@
  * @see ADR-CONT-029 for design rationale
  */
 
-import type { ExecutionKind } from './kinds'
-import type { ISO8601Timestamp } from './types'
+import type { ExecutionKind } from "./kinds";
+import type { ISO8601Timestamp } from "./types";
 
 // =============================================================================
 // Execution Target
@@ -24,8 +24,7 @@ import type { ISO8601Timestamp } from './types'
  * Target of an execution action.
  * Currently supports Slack integration; extensible for future integrations.
  */
-export type ExecutionTarget =
-  | { type: 'slack'; workspaceId?: string }
+export type ExecutionTarget = { type: "slack"; workspaceId?: string };
 
 // =============================================================================
 // Initiator
@@ -36,11 +35,11 @@ export type ExecutionTarget =
  */
 export interface ExecutionInitiator {
   /** Actor type (user or automated system) */
-  actorType: 'user' | 'system'
+  actorType: "user" | "system";
   /** Actor identifier (userId or system identifier) */
-  actorId: string
+  actorId: string;
   /** Human-readable name for display */
-  displayName: string
+  displayName: string;
 }
 
 // =============================================================================
@@ -50,7 +49,7 @@ export interface ExecutionInitiator {
 /**
  * Status of an execution.
  */
-export type ExecutionStatus = 'pending' | 'succeeded' | 'failed'
+export type ExecutionStatus = "pending" | "succeeded" | "failed";
 
 // =============================================================================
 // Execution Summary
@@ -69,33 +68,33 @@ export type ExecutionStatus = 'pending' | 'succeeded' | 'failed'
  */
 export interface ExecutionSummary {
   /** Unique execution identifier */
-  executionId: string
+  executionId: string;
 
   /** Type of execution */
-  kind: ExecutionKind
+  kind: ExecutionKind;
 
   /** What the execution targeted */
-  target: ExecutionTarget
+  target: ExecutionTarget;
 
   /** Current status */
-  status: ExecutionStatus
+  status: ExecutionStatus;
 
   /** Who initiated the execution */
-  initiatedBy: ExecutionInitiator
+  initiatedBy: ExecutionInitiator;
 
   /** When the execution was initiated (decision point) */
-  decidedAt: ISO8601Timestamp
+  decidedAt: ISO8601Timestamp;
 
   /** When the execution completed (if finished) */
-  completedAt?: ISO8601Timestamp
+  completedAt?: ISO8601Timestamp;
 
   /**
    * Visibility level for this execution.
    * Derived from EXECUTION_KINDS[kind].governance.visibility.
    * Used for filtering in queries.
    */
-  visibility: 'admin' | 'user'
+  visibility: "admin" | "user";
 
   /** Whether an explanation can be generated for this execution */
-  explanationAvailable: boolean
+  explanationAvailable: boolean;
 }