@company-semantics/contracts 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/guards/config.ts

@@ -281,6 +281,26 @@ export interface EvolutionBaselines {
    * @see ADR-2025-12-014
    */
   contractsFreshness?: ContractsFreshnessBaseline;
+
+  /**
+   * Coverage drift check configuration.
+   * CI injects checkCoverageDrift based on this config.
+   * Errors when coverage drops below baseline (enforced).
+   */
+  coverage?: CoverageBaseline;
+}
+
+/**
+ * Coverage baseline configuration.
+ * Used by CI orchestrator to inject coverage drift guard.
+ */
+export interface CoverageBaseline {
+  /** Path to coverage-summary.json (default: 'coverage/coverage-summary.json') */
+  coverageFile?: string;
+  /** Baseline coverage percentage (lines) */
+  baseline: number;
+  /** Allowed drop threshold before error (default: 0 = any drop errors) */
+  dropThreshold?: number;
 }
 
 /**
@@ -299,11 +319,6 @@ export interface GuardCheckRegistry {
     structural?: BoundGuardCheck[];
     behavioral?: BoundGuardCheck[];
     invariants?: BoundGuardCheck[];
-    /**
-     * @deprecated Evolution guards are CI-owned. Use evolutionBaselines instead.
-     * Product repos should not provide evolution check implementations.
-     */
-    evolution?: BoundGuardCheck[];
     /** Meta-guards: protect the guard system itself (coverage correctness) */
     meta?: BoundGuardCheck[];
   };

package/src/guards/index.ts

@@ -18,10 +18,23 @@ export type {
   GuardOutput,
   KnownVulnerability,
   VulnerabilityConfig,
+  // SOC 2 Compliance types
+  Soc2ControlArea,
+  Soc2ControlStatus,
+  Soc2ControlResult,
+  Soc2ComplianceOutput,
 } from './types.js';
 
 // Constants (these are type-level, not runtime)
-export { GUARD_SCHEMA_VERSION, GUARD_TIERS } from './types.js';
+export {
+  GUARD_SCHEMA_VERSION,
+  GUARD_TIERS,
+  // SOC 2 Compliance constants
+  SOC2_CONTROL_NAMES,
+  REQUIRED_SOC2_CONTROLS,
+  BLOCKING_SOC2_CONTROLS,
+  SOC2_SCHEMA_VERSION,
+} from './types.js';
 
 // Config types
 export type {
@@ -36,6 +49,7 @@ export type {
   VulnerabilitiesBaseline,
   EvolutionBaselines,
   ContractsFreshnessBaseline,
+  CoverageBaseline,
   MetaBaselines,
 } from './config.js';
 

package/src/guards/types.ts

@@ -158,3 +158,114 @@ export interface VulnerabilityConfig {
   /** Baseline of known/accepted vulnerabilities (grandfathered) */
   knownVulnerabilities?: KnownVulnerability[];
 }
+
+// =============================================================================
+// SOC 2 Compliance Types
+// =============================================================================
+
+/**
+ * SOC 2 control area identifiers.
+ * - CM: Change Management
+ * - AC: Access Control
+ * - LM: Logging & Monitoring
+ * - SD: Secure SDLC
+ * - BR: Backup & Recovery
+ */
+export type Soc2ControlArea = 'CM' | 'AC' | 'LM' | 'SD' | 'BR';
+
+/**
+ * Control status semantics:
+ * - PASS: Control asserted and within bounds
+ * - WARN: Control exists but has drift/open findings
+ * - FAIL: Control invariant broken
+ * - SKIP: Control explicitly out-of-scope for this repo (requires evidence)
+ *
+ * SKIP rules:
+ * - Must include an evidence string explaining why out-of-scope
+ * - Is never blocking
+ * - Must be explicit (configured in soc2Baselines), not implicit
+ */
+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',
+} as const;
+
+/**
+ * All required SOC 2 controls.
+ * Aggregator fails if any control is missing from the output.
+ */
+export const REQUIRED_SOC2_CONTROLS: readonly Soc2ControlArea[] = [
+  'CM',
+  'AC',
+  'LM',
+  'SD',
+  'BR',
+] 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;
+
+/**
+ * A single SOC 2 control assertion result.
+ */
+export interface Soc2ControlResult {
+  /** Control area code (e.g., 'CM', 'AC') */
+  area: Soc2ControlArea;
+  /** Human-readable control name (e.g., 'Change Management') */
+  name: string;
+  /** Control status */
+  status: Soc2ControlStatus;
+  /**
+   * Evidence describes PROCESS or EXISTENCE, not outcomes.
+   * Good: "PR reviews enforced on main", "Backup config present"
+   * Bad: "Secure", "Compliant", "Safe"
+   */
+  evidence: string;
+  /** Whether this control blocks CI when status is FAIL */
+  blocking: boolean;
+  /**
+   * Control version for SOC 2 Type II audit trail.
+   * Increment when control definition changes materially.
+   */
+  controlVersion: number;
+  /** Underlying guard messages that contributed to this status (if any) */
+  messages?: GuardMessage[];
+}
+
+/**
+ * SOC 2 compliance snapshot output.
+ * This is the top-level structure emitted when --soc2 flag is used.
+ */
+export interface Soc2ComplianceOutput {
+  /** ISO 8601 timestamp of when the compliance check ran */
+  timestamp: string;
+  /** Repository name */
+  repository: string;
+  /** Git commit SHA */
+  commitSha: string;
+  /** CI run ID (if available) */
+  ciRunId?: string;
+  /** CI run URL (if available) */
+  ciRunUrl?: string;
+  /** All control results (must include all REQUIRED_SOC2_CONTROLS) */
+  controls: Soc2ControlResult[];
+  /** Overall pass/fail based on blocking controls only */
+  overallStatus: 'PASS' | 'FAIL';
+}
+
+/**
+ * Current SOC 2 compliance schema version.
+ * Bump on breaking schema changes.
+ */
+export const SOC2_SCHEMA_VERSION = '1.0.0';

package/src/index.ts

@@ -30,16 +30,23 @@ export type {
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
-  // Graph-based diagram spec (v0.18.0)
+  // Graph-based diagram spec (v0.19.0)
   DiagramNodeKind,
   DiagramEdgeRelation,
   EdgeDirection,
   FlowStage,
+  PipelinePhase,
   DiagramMode,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
   DiagramSnapshot,
+  // Repository capability types (v0.20.0)
+  RepoId,
+  CapabilityInvariants,
+  RepoCapability,
+  CapabilityManifest,
+  AggregatedCapabilities,
 } from './system/index.js'
 
 // Guard types (CI guard vocabulary)
@@ -61,6 +68,7 @@ export type {
   ScriptsDepsBaseline,
   EvolutionBaselines,
   ContractsFreshnessBaseline,
+  CoverageBaseline,
   MetaBaselines,
 } from './guards/index.js'
 
@@ -76,3 +84,19 @@ export {
 // @see ADR-2025-12-011 for design rationale
 export { COMPATIBILITY } from './compatibility.js'
 export type { Compatibility, Deprecation } from './compatibility.js'
+
+// User identity types and functions
+// @see ADR-2026-01-020 for design rationale
+export type { ISODateString, UserIdentity } from './identity/index.js'
+export { deriveFullName, resolveDisplayName } from './identity/index.js'
+
+// MCP tool discovery types
+// @see company-semantics-backend/src/interfaces/mcp/ for implementation
+export type {
+  ToolCategory,
+  ToolVisibility,
+  ToolInvocationMode,
+  MCPToolDescriptor,
+  ToolDiscoveryResponse,
+  ToolListMessagePart,
+} from './mcp/index.js'

package/src/mcp/index.ts

@@ -0,0 +1,85 @@
+/**
+ * MCP Tool Discovery Types
+ *
+ * Types for tool discovery flow (read-only, UI-first).
+ * Same descriptor used for discovery and invocation, different fields matter.
+ *
+ * INVARIANTS:
+ * - Discovery is descriptive (never executes)
+ * - Invocation is authoritative (runtime is executor)
+ * - Tool discovery output must be runtime-sourced
+ * - Tool discovery must not be streamed char-by-char
+ *
+ * @see company-semantics-backend/src/interfaces/mcp/ for implementation
+ */
+
+/**
+ * Tool categories for grouping in UI.
+ * Maps to user mental model, not implementation.
+ */
+export type ToolCategory =
+  | 'system' // System status, health checks
+  | 'data' // Data access, ingestion, queries
+  | 'connections' // OAuth, integrations
+  | 'automation' // Scheduled tasks, triggers
+  | 'developer' // Debug, internal tools
+
+/**
+ * Tool visibility levels.
+ * Controls who can see the tool in discovery.
+ */
+export type ToolVisibility = 'user' | 'admin'
+
+/**
+ * How the tool can be invoked.
+ * - manual: User must explicitly request
+ * - assistant: AI can invoke proactively
+ * - hybrid: Both manual and assistant invocation
+ */
+export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
+
+/**
+ * Complete tool descriptor for discovery and invocation.
+ *
+ * Discovery uses: id, name, description, category
+ * Invocation uses: id, requiresConfirmation, invocationMode
+ */
+export interface MCPToolDescriptor {
+  /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
+  id: string
+  /** Human-readable name for display */
+  name: string
+  /** User-facing description (what it does, not how) */
+  description: string
+  /** Grouping category for UI organization */
+  category: ToolCategory
+  /** Whether user confirmation is required before execution */
+  requiresConfirmation: boolean
+  /** How the tool can be triggered */
+  invocationMode: ToolInvocationMode
+  /** Who can see this tool */
+  visibility: ToolVisibility
+}
+
+/**
+ * Response shape for tool discovery endpoint.
+ * Used by GET /api/capabilities/tools
+ *
+ * Transport-level type (HTTP API response).
+ * No timestamp - ephemeral, regenerated often.
+ */
+export interface ToolDiscoveryResponse {
+  /** Tools available to the current user */
+  tools: MCPToolDescriptor[]
+}
+
+/**
+ * Structured message part for protocol-level rendering.
+ *
+ * Conversation-level type (chat protocol part).
+ * Rendered atomically, not streamed char-by-char.
+ */
+export interface ToolListMessagePart {
+  type: 'tool-list'
+  tools: MCPToolDescriptor[]
+}

package/src/system/capabilities.ts

@@ -0,0 +1,139 @@
+/**
+ * Repository Capability Types
+ *
+ * Types for cross-repo capability registration and aggregation.
+ * Used by the system diagram to render repo-level features.
+ *
+ * Promoted from company-semantics-control/system-diagram/contracts/
+ *
+ * INVARIANTS:
+ * - RepoCapability is a strict superset of DiagramNode
+ * - Aggregation transforms RepoCapability → DiagramNode (validate + normalize only)
+ * - No semantic changes during aggregation
+ * - flowStage is required on repo-level nodes (primary organizing axis)
+ *
+ * @see ADR-CONTRACTS-NNN in DECISIONS.md
+ */
+
+import type { DiagramNode, FlowStage, FeatureStatus } from './index.js'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Valid repository identifiers.
+ * Add new repos here as the system grows.
+ */
+export type RepoId =
+  | 'backend'
+  | 'edge'
+  | 'app'
+  | 'site'
+  | 'ci'
+  | 'contracts'
+  | 'control'
+
+/**
+ * Semantic invariants for a capability.
+ * Used for CI drift detection and diagram styling.
+ */
+export interface CapabilityInvariants {
+  /** Does this capability invoke LLM/AI APIs? */
+  llmCalls: boolean
+
+  /** Is this an authority boundary (trust/gateway)? */
+  authority: boolean
+
+  /** Can this capability write to strategy/goals? */
+  writesStrategy: boolean
+}
+
+/**
+ * Repository Capability
+ *
+ * Extends DiagramNode with repo-specific fields.
+ * This is what each repo declares in their capabilities.ts.
+ *
+ * CRITICAL: This extends DiagramNode — do NOT add fields that duplicate
+ * or conflict with DiagramNode fields.
+ */
+export interface RepoCapability extends DiagramNode {
+  /**
+   * Which repository owns this capability.
+   * Used for aggregation grouping and validation.
+   */
+  repo: RepoId
+
+  /**
+   * Whether this capability should appear in public diagrams.
+   * - true: visible on marketing site, docs
+   * - false: internal only, visible in app
+   */
+  public: boolean
+
+  /**
+   * Architecture layer for horizontal organization.
+   * Required for repo-level nodes. The primary organizing axis.
+   * Children inherit unless explicitly overridden.
+   */
+  flowStage?: FlowStage
+
+  /**
+   * Stage-level edges for flow projection.
+   * References other capability IDs in format: `repo:domain:capability`
+   *
+   * Example: ['backend:semantic:processing', 'backend:graph:storage']
+   */
+  flowsTo?: string[]
+
+  /**
+   * Whether this capability is exported at the architecture level.
+   * Exported capabilities represent repo boundaries and API surfaces.
+   * Visible in 'architecture' mode.
+   */
+  exported?: boolean
+
+  /**
+   * Semantic invariants for CI validation.
+   * Optional - defaults applied per-repo during aggregation.
+   */
+  invariants?: Partial<CapabilityInvariants>
+}
+
+/**
+ * Manifest of capabilities from a single repository.
+ *
+ * NOTE: No version field — add when actually needed for:
+ * - CI compatibility checks
+ * - Schema evolution
+ * - Breaking capability changes
+ */
+export interface CapabilityManifest {
+  /** Which repository this manifest is from */
+  repo: RepoId
+
+  /** All capabilities declared by this repo */
+  capabilities: RepoCapability[]
+}
+
+/**
+ * Aggregated capabilities from all repositories.
+ * Output of the aggregation step.
+ */
+export interface AggregatedCapabilities {
+  /** All capabilities from all repos, validated */
+  capabilities: RepoCapability[]
+
+  /** Which repos contributed to this aggregation */
+  repos: RepoId[]
+
+  /** ISO timestamp of aggregation */
+  aggregatedAt: string
+}
+
+// =============================================================================
+// Re-exports for convenience
+// =============================================================================
+
+export type { FeatureStatus, FlowStage }

package/src/system/index.ts

@@ -80,3 +80,12 @@ export type {
   DiagramSpec,
   DiagramSnapshot,
 } from './diagram.js'
+
+// Repository capability types
+export type {
+  RepoId,
+  CapabilityInvariants,
+  RepoCapability,
+  CapabilityManifest,
+  AggregatedCapabilities,
+} from './capabilities.js'