@company-semantics/contracts 9.1.0 → 9.2.0

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

@@ -1,25 +1,25 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect } from "vitest";
 import {
   EXECUTION_KINDS,
   getExecutionKindDefinition,
   isValidExecutionKind,
-} from '../registry.js'
+} from "../registry.js";
 
-describe('EXECUTION_KINDS golden snapshot', () => {
-  it('exact values are frozen', () => {
+describe("EXECUTION_KINDS golden snapshot", () => {
+  it("exact values are frozen", () => {
     expect(EXECUTION_KINDS).toStrictEqual({
-      '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,
@@ -27,19 +27,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -48,19 +48,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -69,19 +69,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -90,19 +90,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -111,19 +111,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -132,19 +132,19 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           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: {
@@ -153,92 +153,92 @@ describe('EXECUTION_KINDS golden snapshot', () => {
           confirmBeforeRun: true,
         },
         explanation: {
-          templateId: 'system-cleanup',
+          templateId: "system-cleanup",
         },
       },
-    })
-  })
-})
+    });
+  });
+});
 
-describe('registry structural invariants', () => {
-  it('every registry key matches its definition.kind field', () => {
+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)
+      expect(def.kind).toBe(key);
     }
-  })
+  });
 
-  it('all entries have required display fields as non-empty strings', () => {
+  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)
+      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', () => {
+  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')
+      expect(typeof def.governance.visibility).toBe("string");
+      expect(typeof def.governance.requiresAdmin).toBe("boolean");
     }
-  })
+  });
 
-  it('all entries have required ui fields as booleans', () => {
+  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')
+      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', () => {
+  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')
+        expect(def.governance.visibility).toBe("admin");
       }
     }
-  })
-})
+  });
+});
 
-describe('getExecutionKindDefinition', () => {
-  it('returns correct definition for each of the 7 kinds', () => {
+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)
+      const def = getExecutionKindDefinition(kind);
+      expect(def.kind).toBe(kind);
     }
-  })
+  });
 
-  it('return value matches registry entry (same reference)', () => {
+  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])
+      expect(getExecutionKindDefinition(kind)).toBe(EXECUTION_KINDS[kind]);
     }
-  })
-})
+  });
+});
 
-describe('isValidExecutionKind', () => {
-  it('returns true for all 7 valid execution kinds', () => {
+describe("isValidExecutionKind", () => {
+  it("returns true for all 7 valid execution kinds", () => {
     for (const kind of Object.keys(EXECUTION_KINDS)) {
-      expect(isValidExecutionKind(kind)).toBe(true)
+      expect(isValidExecutionKind(kind)).toBe(true);
     }
-  })
+  });
 
-  it('returns false for unknown string', () => {
-    expect(isValidExecutionKind('unknown.action')).toBe(false)
-  })
+  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 empty string", () => {
+    expect(isValidExecutionKind("")).toBe(false);
+  });
 
-  it('returns false for partial match', () => {
-    expect(isValidExecutionKind('integration')).toBe(false)
-  })
-})
+  it("returns false for partial match", () => {
+    expect(isValidExecutionKind("integration")).toBe(false);
+  });
+});

package/src/execution/audit-export.ts

@@ -1,6 +1,6 @@
-import type { ExecutionEventType } from './events';
-import type { ExecutionIntent } from './types';
-import type { HashChainVerificationResult } from './hash-chain';
+import type { ExecutionEventType } from "./events";
+import type { ExecutionIntent } from "./types";
+import type { HashChainVerificationResult } from "./hash-chain";
 
 /**
  * Immutable governance snapshot captured at execution creation time.
@@ -45,7 +45,7 @@ export interface AuditExportEvent {
  */
 export interface AuditExportBundle {
   /** Schema version for forward compatibility */
-  version: '1.0';
+  version: "1.0";
   /** ISO 8601 timestamp of export generation */
   exportedAt: string;
   /** Execution ID */

package/src/execution/errors.ts

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

package/src/execution/event-metadata.ts

@@ -1,5 +1,5 @@
-import type { ExecutionEventType } from './events';
-import type { ExecutionIntent } from './types';
+import type { ExecutionEventType } from "./events";
+import type { ExecutionIntent } from "./types";
 
 /** Metadata for execution_created event. Frozen governance snapshot. */
 export interface ExecutionCreatedMetadata {
@@ -31,7 +31,7 @@ export interface ConfirmationRejectedMetadata {
 /** Metadata for confirmation_expired event. */
 export interface ConfirmationExpiredMetadata {
   /** What triggered the expiration */
-  trigger: 'job' | 'confirm_attempt';
+  trigger: "job" | "confirm_attempt";
   /** ISO 8601 timestamp when expiration was recorded */
   expiredAt: string;
   /** ISO 8601 original confirmation deadline */
@@ -59,7 +59,7 @@ export interface ExecutionFailedMetadata {
   /** Machine-readable error code */
   errorCode?: string;
   /** Error classification for retry decisions */
-  errorClass?: 'retryable' | 'terminal';
+  errorClass?: "retryable" | "terminal";
   /** Human-readable error message */
   message?: string;
 }

package/src/execution/events.ts

@@ -8,30 +8,32 @@
  * These are defined here for type exhaustiveness but not yet emitted by backend.
  */
 export type ExecutionEventType =
-  | 'execution_created'
-  | 'execution_started'
-  | 'confirmation_approved'
-  | 'confirmation_rejected'
-  | 'confirmation_expired'
-  | 'approval_requested'
-  | 'execution_completed'
-  | 'execution_failed'
-  | 'undo_completed'
-  | 'cancelled';
+  | "execution_created"
+  | "execution_started"
+  | "confirmation_approved"
+  | "confirmation_rejected"
+  | "confirmation_expired"
+  | "approval_requested"
+  | "execution_completed"
+  | "execution_failed"
+  | "undo_completed"
+  | "cancelled";
 
 export const EXECUTION_EVENT_TYPES: readonly ExecutionEventType[] = [
-  'execution_created',
-  'execution_started',
-  'confirmation_approved',
-  'confirmation_rejected',
-  'confirmation_expired',
-  'approval_requested',
-  'execution_completed',
-  'execution_failed',
-  'undo_completed',
-  'cancelled',
+  "execution_created",
+  "execution_started",
+  "confirmation_approved",
+  "confirmation_rejected",
+  "confirmation_expired",
+  "approval_requested",
+  "execution_completed",
+  "execution_failed",
+  "undo_completed",
+  "cancelled",
 ] as const;
 
-export function isExecutionEventType(value: string): value is ExecutionEventType {
+export function isExecutionEventType(
+  value: string,
+): value is ExecutionEventType {
   return (EXECUTION_EVENT_TYPES as readonly string[]).includes(value);
 }

package/src/execution/expiry.ts

@@ -16,9 +16,9 @@
 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
+  if (expiresAt === undefined) return undefined;
+  const ms = new Date(expiresAt).getTime();
+  return Number.isFinite(ms) ? ms : undefined;
 }
 
 /**
@@ -29,6 +29,6 @@ export function isConfirmationExpired(
   expiresAtMs: number | undefined,
   now?: number,
 ): boolean {
-  if (expiresAtMs === undefined) return false
-  return (now ?? Date.now()) >= expiresAtMs
+  if (expiresAtMs === undefined) return false;
+  return (now ?? Date.now()) >= expiresAtMs;
 }

package/src/execution/hash-chain.ts

@@ -34,7 +34,7 @@ export interface HashChainVerificationResult {
 }
 
 /** Hash algorithm used for event chain integrity */
-export const HASH_ALGORITHM = 'sha256' as const;
+export const HASH_ALGORITHM = "sha256" as const;
 
 /** Encoding for hash output */
-export const HASH_ENCODING = 'hex' as const;
+export const HASH_ENCODING = "hex" as const;

package/src/execution/index.ts

@@ -11,12 +11,9 @@
 // Event Types
 // =============================================================================
 
-export type { ExecutionEventType } from './events'
+export type { ExecutionEventType } from "./events";
 
-export {
-  EXECUTION_EVENT_TYPES,
-  isExecutionEventType,
-} from './events'
+export { EXECUTION_EVENT_TYPES, isExecutionEventType } from "./events";
 
 // =============================================================================
 // Event Metadata Schemas
@@ -34,7 +31,7 @@ export type {
   UndoCompletedMetadata,
   CancelledMetadata,
   ExecutionEventMetadataMap,
-} from './event-metadata'
+} from "./event-metadata";
 
 // =============================================================================
 // Hash Chain Types
@@ -43,12 +40,9 @@ export type {
 export type {
   EventHashFields,
   HashChainVerificationResult,
-} from './hash-chain'
+} from "./hash-chain";
 
-export {
-  HASH_ALGORITHM,
-  HASH_ENCODING,
-} from './hash-chain'
+export { HASH_ALGORITHM, HASH_ENCODING } from "./hash-chain";
 
 // =============================================================================
 // Audit Export Types
@@ -58,26 +52,26 @@ export type {
   FrozenExecutionIntent,
   AuditExportEvent,
   AuditExportBundle,
-} from './audit-export'
+} from "./audit-export";
 
 // =============================================================================
 // Kind Types
 // =============================================================================
 
-export type { ExecutionKind } from './kinds'
+export type { ExecutionKind } from "./kinds";
 
 // =============================================================================
 // Lifecycle State
 // =============================================================================
 
-export type { ExecutionState } from './status'
+export type { ExecutionState } from "./status";
 
 export {
   VALID_TRANSITIONS,
   TERMINAL_STATES,
   EFFECTIVE_TERMINAL_STATES,
   assertValidTransition,
-} from './status'
+} from "./status";
 
 // =============================================================================
 // Lifecycle Decision Engine
@@ -86,24 +80,21 @@ export {
 export type {
   ExecutionIntent as LifecycleIntent,
   LifecycleDecision,
-} from './lifecycle'
+} from "./lifecycle";
 
-export {
-  LIFECYCLE_DECISIONS,
-  applyIntent,
-} from './lifecycle'
+export { LIFECYCLE_DECISIONS, applyIntent } from "./lifecycle";
 
 // =============================================================================
 // Expiry Helpers
 // =============================================================================
 
-export { parseExpiresAt, isConfirmationExpired } from './expiry'
+export { parseExpiresAt, isConfirmationExpired } from "./expiry";
 
 // =============================================================================
 // Error Types
 // =============================================================================
 
-export type { ExecutionErrorCode, ExecutionError } from './errors'
+export type { ExecutionErrorCode, ExecutionError } from "./errors";
 
 // =============================================================================
 // Definition Types
@@ -115,7 +106,7 @@ export type {
   ExecutionDomain,
   ExecutionKindDefinition,
   ExecutionIntent,
-} from './types'
+} from "./types";
 
 // =============================================================================
 // Registry
@@ -125,7 +116,7 @@ export {
   EXECUTION_KINDS,
   getExecutionKindDefinition,
   isValidExecutionKind,
-} from './registry'
+} from "./registry";
 
 // =============================================================================
 // Projection Contracts
@@ -137,14 +128,14 @@ export type {
   ExecutionInitiator,
   ExecutionStatus,
   ExecutionSummary,
-} from './summary'
+} from "./summary";
 
 // TimelineUIEvent (user-facing projection)
 export type {
   TimelineStatus,
   TimelineIcon,
   TimelineUIEvent,
-} from './timeline-ui'
+} from "./timeline-ui";
 
 // =============================================================================
 // HTTP Response Schemas (Zod)
@@ -158,7 +149,7 @@ export {
   ConfirmExecutionResponseSchema,
   RejectExecutionResponseSchema,
   StartExecutionResponseSchema,
-} from './schemas'
+} from "./schemas";
 
 export type {
   ExecutionSummaryResponse,
@@ -168,4 +159,4 @@ export type {
   ConfirmExecutionResponse,
   RejectExecutionResponse,
   StartExecutionResponse,
-} from './schemas'
+} from "./schemas";