@company-semantics/contracts 9.1.0 → 9.2.0

package/src/execution/timeline-ui.ts

@@ -13,7 +13,7 @@
  * @see ADR-CONT-029 for design rationale
  */
 
-import type { ISO8601Timestamp } from './types'
+import type { ISO8601Timestamp } from "./types";
 
 // =============================================================================
 // Timeline Status
@@ -23,7 +23,7 @@ import type { ISO8601Timestamp } from './types'
  * Status for timeline display.
  * Maps from ExecutionStatus for UI-specific presentation.
  */
-export type TimelineStatus = 'success' | 'failed' | 'pending'
+export type TimelineStatus = "success" | "failed" | "pending";
 
 // =============================================================================
 // Timeline Icon
@@ -33,7 +33,7 @@ export type TimelineStatus = 'success' | 'failed' | 'pending'
  * Icon for timeline items.
  * Must match IconName but constrained to timeline-relevant icons.
  */
-export type TimelineIcon = 'plug' | 'unlink'
+export type TimelineIcon = "plug" | "unlink";
 
 // =============================================================================
 // Timeline UI Event
@@ -52,26 +52,26 @@ export type TimelineIcon = 'plug' | 'unlink'
  */
 export interface TimelineUIEvent {
   /** Execution ID for correlation and detail fetching */
-  executionId: string
+  executionId: string;
 
   /**
    * Display label (past tense).
    * Derived from EXECUTION_KINDS[kind].display.pastTenseLabel
    */
-  label: string
+  label: string;
 
   /**
    * Icon identifier.
    * Derived from EXECUTION_KINDS[kind].display.icon
    */
-  icon: TimelineIcon
+  icon: TimelineIcon;
 
   /** Visual status indicator */
-  status: TimelineStatus
+  status: TimelineStatus;
 
   /** When this event occurred */
-  timestamp: ISO8601Timestamp
+  timestamp: ISO8601Timestamp;
 
   /** Whether this event has expandable details */
-  expandable: boolean
+  expandable: boolean;
 }

package/src/execution/types.ts

@@ -6,8 +6,8 @@
  * @see ADR-CONT-029 for design rationale
  */
 
-import type { ExecutionKind } from './kinds'
-import type { ConfirmationRiskLevel } from '../message-parts/confirmation'
+import type { ExecutionKind } from "./kinds";
+import type { ConfirmationRiskLevel } from "../message-parts/confirmation";
 
 // =============================================================================
 // Utility Types
@@ -17,13 +17,13 @@ import type { ConfirmationRiskLevel } from '../message-parts/confirmation'
  * ISO 8601 timestamp string.
  * Example: "2026-01-08T14:30:00.000Z"
  */
-export type ISO8601Timestamp = string
+export type ISO8601Timestamp = string;
 
 /**
  * Icon names for execution kinds.
  * Must be supported by the frontend icon system.
  */
-export type IconName = 'plug' | 'unlink' | 'pencil' | 'send'
+export type IconName = "plug" | "unlink" | "pencil" | "send";
 
 // =============================================================================
 // Execution Domain
@@ -32,7 +32,13 @@ export type IconName = 'plug' | 'unlink' | 'pencil' | 'send'
 /**
  * Domain categories for execution kinds.
  */
-export type ExecutionDomain = 'integration' | 'policy' | 'data' | 'system' | 'profile' | 'communication'
+export type ExecutionDomain =
+  | "integration"
+  | "policy"
+  | "data"
+  | "system"
+  | "profile"
+  | "communication";
 
 // =============================================================================
 // Execution Kind Definition
@@ -50,46 +56,46 @@ export type ExecutionDomain = 'integration' | 'policy' | 'data' | 'system' | 'pr
  */
 export interface ExecutionKindDefinition {
   /** The execution kind this definition describes */
-  kind: ExecutionKind
+  kind: ExecutionKind;
 
   /** Domain category for grouping and filtering */
-  domain: ExecutionDomain
+  domain: ExecutionDomain;
 
   /** Display metadata for UI rendering */
   display: {
     /** Label shown on buttons/actions (imperative: "Connect Slack") */
-    label: string
+    label: string;
     /** Label for completed actions (past tense: "Slack connected") */
-    pastTenseLabel: string
+    pastTenseLabel: string;
     /** Icon identifier for UI */
-    icon: IconName
-  }
+    icon: IconName;
+  };
 
   /** Governance constraints */
   governance: {
     /** Who can see this execution in lists/timelines */
-    visibility: 'admin' | 'user'
+    visibility: "admin" | "user";
     /** Whether admin role is required to initiate */
-    requiresAdmin: boolean
+    requiresAdmin: boolean;
     /** If reversible, which kind reverses this action */
-    reversibleBy?: ExecutionKind
-  }
+    reversibleBy?: ExecutionKind;
+  };
 
   /** UI behavior hints */
   ui: {
     /** Show in admin settings panel */
-    showInAdmin: boolean
+    showInAdmin: boolean;
     /** Show in user-facing timeline */
-    showInTimeline: boolean
+    showInTimeline: boolean;
     /** Require confirmation dialog before execution */
-    confirmBeforeRun?: boolean
-  }
+    confirmBeforeRun?: boolean;
+  };
 
   /** Explanation generation metadata */
   explanation: {
     /** Template ID for explanation builder */
-    templateId: string
-  }
+    templateId: string;
+  };
 }
 
 // =============================================================================
@@ -116,8 +122,8 @@ export interface ExecutionKindDefinition {
  * from the execution domain barrel only, NOT from root index.ts.
  */
 export interface ExecutionIntent {
-  executionKind: ExecutionKind
-  requiresConfirmation: boolean
-  requiresApproval: boolean
-  risk: ConfirmationRiskLevel
+  executionKind: ExecutionKind;
+  requiresConfirmation: boolean;
+  requiresApproval: boolean;
+  risk: ConfirmationRiskLevel;
 }

package/src/generated/openapi-routes.ts

@@ -48,6 +48,7 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/timeline': ['GET'],
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
+  '/api/factory/snapshot': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],

package/src/guards/config.ts

@@ -8,7 +8,7 @@
  * Each repo provides its own config values; shared guards consume them.
  */
 
-import type { CheckResult, Soc2ControlArea } from './types';
+import type { CheckResult, Soc2ControlArea } from "./types";
 
 // =============================================================================
 // Size Limits
@@ -101,7 +101,7 @@ export interface GuardConfig {
  */
 export type GuardCheck = (
   repoRoot: string,
-  config: GuardConfig
+  config: GuardConfig,
 ) => Promise<CheckResult>;
 
 /**
@@ -109,7 +109,7 @@ export type GuardCheck = (
  * Factories create check functions with optional overrides.
  */
 export type GuardCheckFactory = (
-  overrides?: Partial<GuardConfig>
+  overrides?: Partial<GuardConfig>,
 ) => GuardCheck;
 
 // =============================================================================
@@ -138,7 +138,11 @@ export interface ContractsFreshnessBaseline {
    */
   compatibility: {
     minSupported: string;
-    deprecations: readonly { range: string; reason: string; removeIn: string }[];
+    deprecations: readonly {
+      range: string;
+      reason: string;
+      removeIn: string;
+    }[];
   };
 
   /**
@@ -563,30 +567,30 @@ export interface GuardCheckRegistry {
  * Default directories to skip when walking file trees.
  */
 export const DEFAULT_SKIP_DIRECTORIES = [
-  'node_modules',
-  'dist',
-  '.git',
-  '.next',
-  'coverage',
-  '.tsbuild',
+  "node_modules",
+  "dist",
+  ".git",
+  ".next",
+  "coverage",
+  ".tsbuild",
 ];
 
 /**
  * Default README sections for domain directories.
  */
 export const DEFAULT_DOMAIN_SECTIONS = [
-  'Purpose',
-  'Invariants',
-  'Public API',
-  'Dependencies',
+  "Purpose",
+  "Invariants",
+  "Public API",
+  "Dependencies",
 ];
 
 /**
  * Default README sections for infrastructure directories.
  */
 export const DEFAULT_INFRA_SECTIONS = [
-  'Purpose',
-  'How it works',
-  'Integration',
-  'Maintenance',
+  "Purpose",
+  "How it works",
+  "Integration",
+  "Maintenance",
 ];

package/src/guards/index.ts

@@ -23,7 +23,7 @@ export type {
   Soc2ControlStatus,
   Soc2ControlResult,
   Soc2ComplianceOutput,
-} from './types';
+} from "./types";
 
 // Constants (these are type-level, not runtime)
 export {
@@ -34,7 +34,7 @@ export {
   REQUIRED_SOC2_CONTROLS,
   BLOCKING_SOC2_CONTROLS,
   SOC2_SCHEMA_VERSION,
-} from './types';
+} from "./types";
 
 // Config types
 export type {
@@ -63,11 +63,11 @@ export type {
   AlertsConfigGuardConfig,
   BackupConfigGuardConfig,
   Soc2Baselines,
-} from './config';
+} from "./config";
 
 // Config constants (type-level defaults)
 export {
   DEFAULT_SKIP_DIRECTORIES,
   DEFAULT_DOMAIN_SECTIONS,
   DEFAULT_INFRA_SECTIONS,
-} from './config';
+} from "./config";

package/src/guards/types.ts

@@ -58,7 +58,12 @@ export interface GuardTierResult {
  * - evolution: uncovered patterns, growth tracking (observational)
  * - meta: guards that protect the guard system itself (coverage correctness)
  */
-export type GuardTier = 'structural' | 'behavioral' | 'invariants' | 'evolution' | 'meta';
+export type GuardTier =
+  | "structural"
+  | "behavioral"
+  | "invariants"
+  | "evolution"
+  | "meta";
 
 /**
  * Full guard results, organized by tier.
@@ -114,18 +119,18 @@ export interface GuardOutput {
  * Current schema version.
  * v2.0.0: Tiered results (breaking change from v1.x flattened structure)
  */
-export const GUARD_SCHEMA_VERSION = '2.0.0';
+export const GUARD_SCHEMA_VERSION = "2.0.0";
 
 /**
  * All guard tiers in order.
  * Useful for iteration when aggregating results.
  */
 export const GUARD_TIERS: readonly GuardTier[] = [
-  'structural',
-  'behavioral',
-  'invariants',
-  'evolution',
-  'meta',
+  "structural",
+  "behavioral",
+  "invariants",
+  "evolution",
+  "meta",
 ] as const;
 
 // =============================================================================
@@ -172,7 +177,7 @@ export interface VulnerabilityConfig {
  * - BR: Backup & Recovery
  * - AI: Audit Integrity
  */
-export type Soc2ControlArea = 'CM' | 'AC' | 'LM' | 'SD' | 'BR' | 'AI';
+export type Soc2ControlArea = "CM" | "AC" | "LM" | "SD" | "BR" | "AI";
 
 /**
  * Control status semantics:
@@ -186,18 +191,18 @@ export type Soc2ControlArea = 'CM' | 'AC' | 'LM' | 'SD' | 'BR' | 'AI';
  * - Is never blocking
  * - Must be explicit (configured in soc2Baselines), not implicit
  */
-export type Soc2ControlStatus = 'PASS' | 'WARN' | 'FAIL' | 'SKIP';
+export type Soc2ControlStatus = "PASS" | "WARN" | "FAIL" | "SKIP";
 
 /**
  * Human-readable names for SOC 2 control areas.
  */
 export const SOC2_CONTROL_NAMES: Record<Soc2ControlArea, string> = {
-  CM: 'Change Management',
-  AC: 'Access Control',
-  LM: 'Logging & Monitoring',
-  SD: 'Secure SDLC',
-  BR: 'Backup & Recovery',
-  AI: 'Audit Integrity',
+  CM: "Change Management",
+  AC: "Access Control",
+  LM: "Logging & Monitoring",
+  SD: "Secure SDLC",
+  BR: "Backup & Recovery",
+  AI: "Audit Integrity",
 } as const;
 
 /**
@@ -205,19 +210,22 @@ export const SOC2_CONTROL_NAMES: Record<Soc2ControlArea, string> = {
  * Aggregator fails if any control is missing from the output.
  */
 export const REQUIRED_SOC2_CONTROLS: readonly Soc2ControlArea[] = [
-  'CM',
-  'AC',
-  'LM',
-  'SD',
-  'BR',
-  'AI',
+  "CM",
+  "AC",
+  "LM",
+  "SD",
+  "BR",
+  "AI",
 ] as const;
 
 /**
  * Controls that block CI when status is FAIL.
  * Non-blocking controls report FAIL but don't set exit code to 1.
  */
-export const BLOCKING_SOC2_CONTROLS: readonly Soc2ControlArea[] = ['CM', 'AC'] as const;
+export const BLOCKING_SOC2_CONTROLS: readonly Soc2ControlArea[] = [
+  "CM",
+  "AC",
+] as const;
 
 /**
  * A single SOC 2 control assertion result.
@@ -264,11 +272,11 @@ export interface Soc2ComplianceOutput {
   /** All control results (must include all REQUIRED_SOC2_CONTROLS) */
   controls: Soc2ControlResult[];
   /** Overall pass/fail based on blocking controls only */
-  overallStatus: 'PASS' | 'FAIL';
+  overallStatus: "PASS" | "FAIL";
 }
 
 /**
  * Current SOC 2 compliance schema version.
  * Bump on breaking schema changes.
  */
-export const SOC2_SCHEMA_VERSION = '1.0.0';
+export const SOC2_SCHEMA_VERSION = "1.0.0";

package/src/identity/__tests__/avatar.test.ts

@@ -1,75 +1,84 @@
-import { describe, it, expect } from 'vitest'
-import { generateInitials, resolveAvatar } from '../avatar.js'
+import { describe, it, expect } from "vitest";
+import { generateInitials, resolveAvatar } from "../avatar.js";
 
-describe('generateInitials', () => {
-  it('returns single uppercase initial for single-word name', () => {
-    expect(generateInitials('Madonna')).toBe('M')
-  })
+describe("generateInitials", () => {
+  it("returns single uppercase initial for single-word name", () => {
+    expect(generateInitials("Madonna")).toBe("M");
+  });
 
-  it('returns first+last uppercase initials for two-word name', () => {
-    expect(generateInitials('Ian Heidt')).toBe('IH')
-  })
+  it("returns first+last uppercase initials for two-word name", () => {
+    expect(generateInitials("Ian Heidt")).toBe("IH");
+  });
 
-  it('returns first+last initials, skipping middle for multi-word name', () => {
-    expect(generateInitials('Mary Jane Doe')).toBe('MD')
-  })
+  it("returns first+last initials, skipping middle for multi-word name", () => {
+    expect(generateInitials("Mary Jane Doe")).toBe("MD");
+  });
 
-  it('returns empty string for empty input', () => {
-    expect(generateInitials('')).toBe('')
-  })
+  it("returns empty string for empty input", () => {
+    expect(generateInitials("")).toBe("");
+  });
 
-  it('returns empty string for whitespace-only input', () => {
-    expect(generateInitials('   ')).toBe('')
-  })
+  it("returns empty string for whitespace-only input", () => {
+    expect(generateInitials("   ")).toBe("");
+  });
 
-  it('handles name with extra whitespace', () => {
-    expect(generateInitials('  Ian   Heidt  ')).toBe('IH')
-  })
+  it("handles name with extra whitespace", () => {
+    expect(generateInitials("  Ian   Heidt  ")).toBe("IH");
+  });
 
-  it('returns single character for single character name', () => {
-    expect(generateInitials('X')).toBe('X')
-  })
+  it("returns single character for single character name", () => {
+    expect(generateInitials("X")).toBe("X");
+  });
 
-  it('returns uppercase for lowercase input', () => {
-    expect(generateInitials('ian heidt')).toBe('IH')
-  })
-})
+  it("returns uppercase for lowercase input", () => {
+    expect(generateInitials("ian heidt")).toBe("IH");
+  });
+});
 
-describe('resolveAvatar', () => {
-  it('initials is always populated when source is photo (critical invariant)', () => {
-    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
-    expect(result.source).toBe('photo')
-    expect(result.url).toBe('https://example.com/img.jpg')
+describe("resolveAvatar", () => {
+  it("initials is always populated when source is photo (critical invariant)", () => {
+    const result = resolveAvatar({
+      avatarUrl: "https://example.com/img.jpg",
+      fullName: "Ian Heidt",
+    });
+    expect(result.source).toBe("photo");
+    expect(result.url).toBe("https://example.com/img.jpg");
     // INVARIANT: initials is ALWAYS populated, regardless of source.
     // This prevents UI regressions when the photo fails to load.
-    expect(typeof result.initials).toBe('string')
-    expect(result.initials).toBe('IH')
-  })
+    expect(typeof result.initials).toBe("string");
+    expect(result.initials).toBe("IH");
+  });
 
-  it('returns initials source when no avatarUrl', () => {
-    const result = resolveAvatar({ fullName: 'Ian Heidt' } as any)
-    expect(result.source).toBe('initials')
-    expect(result.initials).toBe('IH')
-    expect(result.url).toBeUndefined()
-  })
+  it("returns initials source when no avatarUrl", () => {
+    const result = resolveAvatar({ fullName: "Ian Heidt" } as any);
+    expect(result.source).toBe("initials");
+    expect(result.initials).toBe("IH");
+    expect(result.url).toBeUndefined();
+  });
 
-  it('returns photo source with empty initials when fullName is empty', () => {
-    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: '' })
-    expect(result.source).toBe('photo')
-    expect(result.url).toBe('https://example.com/img.jpg')
+  it("returns photo source with empty initials when fullName is empty", () => {
+    const result = resolveAvatar({
+      avatarUrl: "https://example.com/img.jpg",
+      fullName: "",
+    });
+    expect(result.source).toBe("photo");
+    expect(result.url).toBe("https://example.com/img.jpg");
     // Empty is valid — just not undefined
-    expect(result.initials).toBe('')
-  })
+    expect(result.initials).toBe("");
+  });
 
-  it('returns initials source when avatarUrl is explicitly undefined', () => {
-    const result = resolveAvatar({ avatarUrl: undefined, fullName: 'Ian Heidt' })
-    expect(result.source).toBe('initials')
-    expect(result.initials).toBe('IH')
-  })
+  it("returns initials source when avatarUrl is explicitly undefined", () => {
+    const result = resolveAvatar({
+      avatarUrl: undefined,
+      fullName: "Ian Heidt",
+    });
+    expect(result.source).toBe("initials");
+    expect(result.initials).toBe("IH");
+  });
 
-  it('returns initials source when avatarUrl is empty string (falsy)', () => {
-    const result = resolveAvatar({ avatarUrl: '', fullName: 'Ian Heidt' })
-    expect(result.source).toBe('initials')
-    expect(result.initials).toBe('IH')
-  })
-})
+  it("returns initials source when avatarUrl is empty string (falsy)", () => {
+    const result = resolveAvatar({ avatarUrl: "", fullName: "Ian Heidt" });
+    expect(result.source).toBe("initials");
+    expect(result.initials).toBe("IH");
+  });
+});

package/src/identity/avatar.ts

@@ -7,7 +7,7 @@
  * @see ADR-BE-063 for design rationale
  */
 
-import type { UserIdentity } from './types';
+import type { UserIdentity } from "./types";
 
 // =============================================================================
 // Types
@@ -18,7 +18,7 @@ import type { UserIdentity } from './types';
  * - 'photo': Using a resolved profile photo
  * - 'initials': Using generated initials (fallback)
  */
-export type AvatarSource = 'photo' | 'initials';
+export type AvatarSource = "photo" | "initials";
 
 /**
  * Resolved avatar for UI rendering.
@@ -61,16 +61,16 @@ export interface ResolvedAvatar {
  */
 export function generateInitials(fullName: string): string {
   const trimmed = fullName.trim();
-  if (!trimmed) return '';
+  if (!trimmed) return "";
 
   const words = trimmed.split(/\s+/);
-  const firstInitial = words[0]?.[0]?.toUpperCase() ?? '';
+  const firstInitial = words[0]?.[0]?.toUpperCase() ?? "";
 
   if (words.length === 1) {
     return firstInitial;
   }
 
-  const lastInitial = words[words.length - 1]?.[0]?.toUpperCase() ?? '';
+  const lastInitial = words[words.length - 1]?.[0]?.toUpperCase() ?? "";
   return `${firstInitial}${lastInitial}`;
 }
 
@@ -100,20 +100,20 @@ export function generateInitials(fullName: string): string {
  * // { source: 'initials', initials: 'IH' }
  */
 export function resolveAvatar(
-  identity: Pick<UserIdentity, 'avatarUrl' | 'fullName'>
+  identity: Pick<UserIdentity, "avatarUrl" | "fullName">,
 ): ResolvedAvatar {
   const initials = generateInitials(identity.fullName);
 
   if (identity.avatarUrl) {
     return {
-      source: 'photo',
+      source: "photo",
       url: identity.avatarUrl,
       initials,
     };
   }
 
   return {
-    source: 'initials',
+    source: "initials",
     initials,
   };
 }

package/src/identity/display-name.ts

@@ -7,7 +7,7 @@
  * @see ADR-CONT-032 for design rationale
  */
 
-import type { UserIdentity } from './types';
+import type { UserIdentity } from "./types";
 
 // =============================================================================
 // Helper Functions
@@ -28,7 +28,7 @@ import type { UserIdentity } from './types';
  */
 export function extractFirstWord(fullName: string): string {
   const trimmed = fullName.trim();
-  const spaceIndex = trimmed.indexOf(' ');
+  const spaceIndex = trimmed.indexOf(" ");
   return spaceIndex === -1 ? trimmed : trimmed.slice(0, spaceIndex);
 }
 
@@ -57,7 +57,7 @@ export function extractFirstWord(fullName: string): string {
  * resolveDisplayName({ fullName: "Madonna" })                            // "Madonna"
  */
 export function resolveDisplayName(
-  identity: Pick<UserIdentity, 'preferredName' | 'fullName'>
+  identity: Pick<UserIdentity, "preferredName" | "fullName">,
 ): string {
   return identity.preferredName?.trim() || extractFirstWord(identity.fullName);
 }