@company-semantics/contracts 0.41.1 → 0.43.0

package/package.json

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

package/src/ci-envelope/index.ts

@@ -0,0 +1,38 @@
+/**
+ * CI Envelope Types Barrel
+ *
+ * Re-exports all CI execution envelope vocabulary types.
+ * Import from '@company-semantics/contracts/ci-envelope' or '@company-semantics/contracts'.
+ *
+ * Note: This module exports types only (no runtime code per contracts policy).
+ * Builder, validation, and policy logic live in company-semantics-ci/envelope/.
+ *
+ * @see ADR-CONT-033 for contracts boundary rationale
+ */
+
+// Types
+export type {
+  // Actor & Session
+  CIActorInfo,
+  CISessionInfo,
+  // Intent
+  ExecutionIntent,
+  CIIntentDeclaration,
+  // Scope
+  CIChangeKind,
+  CIExecutionScope,
+  // Authority
+  CIAuthorityGrant,
+  // Guard Plan
+  CIGuardPlan,
+  // Status
+  CIEnvelopeStatus,
+  // Outcome
+  CIGuardViolation,
+  CIExecutionOutcome,
+  // Core Envelope
+  CIExecutionEnvelope,
+} from './types';
+
+// Constants (documentation/type-level, not runtime)
+export { ENVELOPE_TRANSITIONS } from './types';

package/src/ci-envelope/types.ts

@@ -0,0 +1,216 @@
+/**
+ * CI Execution Envelope Type Vocabulary (v1.0.0)
+ *
+ * Canonical types for CI execution envelopes — first-class, append-only records
+ * that capture AI intent, scope, and authority before mutations occur.
+ *
+ * Design invariants:
+ * - Types only — no validation logic, no policy mappings (those live in CI repo)
+ * - Envelope is append-only (status transitions, no field deletions)
+ * - Schema version enables future migration
+ *
+ * @see ADR-CONT-033 for design rationale
+ * @see company-semantics-ci/envelope/ for builder and validation logic
+ */
+
+// =============================================================================
+// Actor & Session Types
+// =============================================================================
+
+/**
+ * Actor information for audit trail.
+ * Currently Claude-only, extensible for future actor types.
+ */
+export type CIActorInfo = {
+  kind: 'claude';
+  model: string;
+};
+
+/**
+ * Session context for correlating envelope to conversation.
+ */
+export type CISessionInfo = {
+  conversationId: string;
+  turnId: string;
+};
+
+// =============================================================================
+// Intent Types
+// =============================================================================
+
+/**
+ * Execution intent categories.
+ * Defines the semantic "why" of an execution.
+ *
+ * Note: Policy mappings (intent → required guards) live in CI repo,
+ * not here. This type defines vocabulary only.
+ */
+export type ExecutionIntent =
+  | 'feature_extension'
+  | 'bug_fix'
+  | 'refactor_structural'
+  | 'guard_update'
+  | 'policy_update'
+  | 'schema_change'
+  | 'doc_update'
+  | 'cleanup'
+  | 'experimental';
+
+/**
+ * Intent declaration with optional ADR references.
+ */
+export type CIIntentDeclaration = {
+  primary: ExecutionIntent;
+  secondary?: ExecutionIntent[];
+  description: string;
+  adrRefs?: string[];
+};
+
+// =============================================================================
+// Scope Types
+// =============================================================================
+
+/**
+ * Change kind for scope declarations.
+ */
+export type CIChangeKind = 'add' | 'modify' | 'delete';
+
+/**
+ * Execution scope defining affected repos and paths.
+ */
+export type CIExecutionScope = {
+  repos: string[];
+  /** Glob patterns for affected paths */
+  paths: string[];
+  changeKinds: CIChangeKind[];
+};
+
+// =============================================================================
+// Authority Types
+// =============================================================================
+
+/**
+ * Authority grant documenting permission basis.
+ */
+export type CIAuthorityGrant = {
+  /** References to CLAUDE.md / AI_AUTONOMY.md sections */
+  allowedBy: string[];
+  requiresConfirmation: boolean;
+};
+
+// =============================================================================
+// Guard Plan Types
+// =============================================================================
+
+/**
+ * Guard execution plan resolved from intent + scope.
+ * Populated by guard plan resolver in CI repo.
+ */
+export type CIGuardPlan = {
+  /** Guard IDs that MUST pass */
+  required: string[];
+  /** Guard IDs allowed to warn (advisory) */
+  advisory: string[];
+};
+
+// =============================================================================
+// Status Types
+// =============================================================================
+
+/**
+ * Envelope lifecycle status.
+ *
+ * State machine:
+ * - proposed → validated | blocked
+ * - validated → executing | blocked
+ * - executing → finalized | blocked
+ * - blocked → (terminal)
+ * - finalized → (terminal)
+ *
+ * Note: Transition validation logic lives in CI repo, not here.
+ */
+export type CIEnvelopeStatus =
+  | 'proposed'
+  | 'validated'
+  | 'blocked'
+  | 'executing'
+  | 'finalized';
+
+// =============================================================================
+// Outcome Types
+// =============================================================================
+
+/**
+ * A single guard violation for post-execution audit.
+ */
+export type CIGuardViolation = {
+  guardId: string;
+  severity: 'error' | 'warning';
+  message: string;
+  file?: string;
+  line?: number;
+};
+
+/**
+ * Execution outcome populated on finalization.
+ */
+export type CIExecutionOutcome = {
+  filesChanged: number;
+  commits: string[];
+  violations?: CIGuardViolation[];
+};
+
+// =============================================================================
+// Core Envelope Type
+// =============================================================================
+
+/**
+ * CI Execution Envelope — the atomic unit of governed execution.
+ *
+ * Created before mutations, finalized after. Enables:
+ * - Pre-execution gating (intent/scope/authority check)
+ * - Post-hoc audit (what was planned vs what happened)
+ * - Deterministic explanation (no LLM guesswork)
+ */
+export type CIExecutionEnvelope = {
+  /** Schema version for migration (bump on breaking changes) */
+  envelopeVersion: 1;
+  /** Unique identifier (UUID v7 recommended) */
+  executionId: string;
+  /** ISO 8601 timestamp */
+  createdAt: string;
+  actor: CIActorInfo;
+  session: CISessionInfo;
+  intent: CIIntentDeclaration;
+  scope: CIExecutionScope;
+  authority: CIAuthorityGrant;
+  guardPlan: CIGuardPlan;
+  status: CIEnvelopeStatus;
+  /** Structured reason when status='blocked' */
+  blockedReason?: string;
+  /** Populated on finalization */
+  outcome?: CIExecutionOutcome;
+};
+
+// =============================================================================
+// Transition Graph (Documentation Only)
+// =============================================================================
+
+/**
+ * Valid status transitions (documentation only).
+ *
+ * This const documents the state machine for reference.
+ * Actual transition validation logic lives in CI repo.
+ *
+ * Terminal states: blocked, finalized (empty transition arrays)
+ */
+export const ENVELOPE_TRANSITIONS: Record<
+  CIEnvelopeStatus,
+  readonly CIEnvelopeStatus[]
+> = {
+  proposed: ['validated', 'blocked'],
+  validated: ['executing', 'blocked'],
+  blocked: [],
+  executing: ['finalized', 'blocked'],
+  finalized: [],
+} as const;

package/src/email/README.md

@@ -0,0 +1,35 @@
+# email/
+
+## Purpose
+
+TypeScript types and registry for transactional email kinds and their metadata.
+
+## Invariants
+
+- Types only; minimal runtime code (pure functions for registry lookup)
+- No external dependencies (contracts policy)
+- `EmailKind` union MUST match keys in `EMAIL_KINDS` registry
+- `EMAIL_KINDS` is the single source of truth for subjects and rendering rules
+- OTP values MUST NEVER appear in contracts (security: logged if leaked)
+- Subjects are owned by the registry, never duplicated in templates
+- Unknown email kinds MUST be rejected at API boundaries via `isValidEmailKind()`
+
+## Public API
+
+### Types
+
+- `EmailKind` — Union of valid email kind identifiers
+- `EmailPayloads` — Type-safe payload mapping for each kind
+- `SendEmailInput<K>` — Type-safe input for sending emails
+- `EmailKindDefinition` — Full definition schema for a kind
+
+### Registry & Functions
+
+- `EMAIL_KINDS` — Registry of all email kinds
+- `getEmailKindDefinition(kind)` — Type-safe registry lookup
+- `isValidEmailKind(kind)` — Validate string is EmailKind
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-backend (email service, templates)

package/src/email/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Email Domain Barrel
+ *
+ * Re-exports email kind vocabulary types and registry.
+ * Import from '@company-semantics/contracts/email'.
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+// =============================================================================
+// Kind Types
+// =============================================================================
+
+export type { EmailKind, EmailPayloads, SendEmailInput } from './types'
+
+// =============================================================================
+// Definition Types
+// =============================================================================
+
+export type { EmailKindDefinition } from './registry'
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+export {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from './registry'

package/src/email/registry.ts

@@ -0,0 +1,105 @@
+/**
+ * Email Kind Registry
+ *
+ * Central registry of all email kinds and their definitions.
+ * This is the single source of truth for email metadata.
+ *
+ * Invariants:
+ * - Every EmailKind MUST have an entry in EMAIL_KINDS
+ * - Registry keys MUST match definition.kind
+ * - Registry is exhaustive (satisfies Record<EmailKind, ...>)
+ * - Subjects are owned here, not duplicated in templates
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+import type { EmailKind } from './types'
+
+// =============================================================================
+// Email Kind Definition
+// =============================================================================
+
+/**
+ * Complete definition for an email kind.
+ *
+ * This interface is the schema for entries in EMAIL_KINDS registry.
+ * It captures subject, rendering requirements, and domain metadata.
+ *
+ * Invariants:
+ * - kind field MUST match the registry key
+ * - subject is the authoritative source (templates import from here)
+ */
+export interface EmailKindDefinition {
+  /** The email kind this definition describes */
+  kind: EmailKind
+  /** Email subject line (single source of truth) */
+  subject: string
+  /** Whether plain text body is required */
+  plainTextRequired: boolean
+  /** Whether HTML body is supported */
+  htmlSupported: boolean
+}
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+/**
+ * EMAIL_KINDS is the authoritative registry.
+ *
+ * All subjects, rendering rules, and domain metadata are derived from here.
+ * Backend email templates MUST use this registry for subjects
+ * rather than hardcoding values.
+ *
+ * To add a new kind:
+ * 1. Add to EmailKind union in types.ts
+ * 2. Add entry to this registry
+ * 3. Add payload to EmailPayloads if needed
+ * 4. Implement template in backend
+ */
+export const EMAIL_KINDS = {
+  'auth.otp': {
+    kind: 'auth.otp',
+    subject: 'Your login code',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+  'auth.magic_link': {
+    kind: 'auth.magic_link',
+    subject: 'Your login link',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+  'org.invite': {
+    kind: 'org.invite',
+    subject: 'You have been invited to join a workspace',
+    plainTextRequired: true,
+    htmlSupported: true,
+  },
+  'security.alert': {
+    kind: 'security.alert',
+    subject: 'Security alert for your account',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+} as const satisfies Record<EmailKind, EmailKindDefinition>
+
+// =============================================================================
+// Registry Helpers
+// =============================================================================
+
+/**
+ * Type-safe registry lookup.
+ * Returns the definition for a given email kind.
+ */
+export function getEmailKindDefinition(kind: EmailKind): EmailKindDefinition {
+  return EMAIL_KINDS[kind]
+}
+
+/**
+ * Check if a string is a valid EmailKind.
+ * Use at API boundaries to reject unknown kinds.
+ */
+export function isValidEmailKind(kind: string): kind is EmailKind {
+  return kind in EMAIL_KINDS
+}

package/src/email/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Email Domain Types
+ *
+ * Shared types for transactional email across Company Semantics codebases.
+ * Types only - no runtime code, no business logic.
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+// =============================================================================
+// EmailKind Union
+// =============================================================================
+
+/**
+ * EmailKind identifies the type of transactional email.
+ *
+ * Naming convention: `{domain}.{type}`
+ * - domain: auth, org, security
+ * - type: specific email variant
+ *
+ * New kinds MUST be added to:
+ * 1. This union type
+ * 2. EMAIL_KINDS registry in registry.ts
+ * 3. EmailPayloads interface (if kind has payload)
+ */
+export type EmailKind =
+  | 'auth.otp'
+  | 'auth.magic_link' // future
+  | 'org.invite' // future
+  | 'security.alert' // future
+
+// =============================================================================
+// Email Payloads
+// =============================================================================
+
+/**
+ * Type-safe payload mapping for each email kind.
+ *
+ * Each key is an EmailKind, and the value is the required payload shape.
+ * Kinds without entries here have empty payloads.
+ */
+export interface EmailPayloads {
+  'auth.otp': {
+    /** The 6-digit OTP code */
+    otp: string
+    /** How long until the code expires */
+    expiresInMinutes: number
+    /** IP address of the request (for security context) */
+    requestIp?: string
+    /** User agent of the request (for security context) */
+    userAgent?: string
+  }
+}
+
+// =============================================================================
+// Send Email Input
+// =============================================================================
+
+/**
+ * Type-safe input for sending emails.
+ *
+ * The payload type is inferred from the kind.
+ * If the kind is in EmailPayloads, that payload is required.
+ */
+export interface SendEmailInput<K extends EmailKind> {
+  /** The type of email to send */
+  kind: K
+  /** Recipient email address (will be normalized) */
+  to: string
+  /** Type-safe payload for this email kind */
+  payload: K extends keyof EmailPayloads ? EmailPayloads[K] : never
+  /** Idempotency key to prevent duplicate sends */
+  idempotencyKey: string
+}

package/src/index.ts

@@ -112,6 +112,21 @@ export { extractFirstWord, resolveDisplayName, deriveFullName } from './identity
 // Auth domain types
 export { OTPErrorCode } from './auth/index'
 
+// Email domain types
+// @see ADR-CONT-034 for design rationale
+export type {
+  EmailKind,
+  EmailPayloads,
+  SendEmailInput,
+  EmailKindDefinition,
+} from './email/index'
+
+export {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from './email/index'
+
 // Organization domain types
 // @see ADR-BE-XXX for design rationale (Personal vs Shared Organization Model)
 export type {
@@ -260,3 +275,30 @@ export {
   getExecutionKindDefinition,
   isValidExecutionKind,
 } from './execution/index'
+
+// CI Execution Envelope types
+// @see ADR-CONT-033 for contracts boundary rationale
+export type {
+  // Actor & Session
+  CIActorInfo,
+  CISessionInfo,
+  // Intent
+  ExecutionIntent,
+  CIIntentDeclaration,
+  // Scope
+  CIChangeKind,
+  CIExecutionScope,
+  // Authority
+  CIAuthorityGrant,
+  // Guard Plan
+  CIGuardPlan,
+  // Status
+  CIEnvelopeStatus,
+  // Outcome
+  CIGuardViolation,
+  CIExecutionOutcome,
+  // Core Envelope
+  CIExecutionEnvelope,
+} from './ci-envelope/index'
+
+export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'