@company-semantics/contracts 27.6.0 → 27.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.6.0",
+  "version": "27.7.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -128,12 +128,12 @@
     "@types/node": "^22.20.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
-    "markdownlint-cli2": "^0.22.1",
+    "markdownlint-cli2": "^0.23.0",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.4",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.0",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   },
   "pnpm": {

package/src/guards/config.ts

@@ -8,7 +8,36 @@
  * Each repo provides its own config values; shared guards consume them.
  */
 
-import type { CheckResult, Soc2ControlArea } from "./types";
+import type { CheckResult } from "./types";
+// The EvolutionBaselines interface below references these evolution baseline
+// types, which now live in ./evolution-config.
+import type {
+  CoverageBaseline,
+  FileClusterBaseline,
+  SubdirectoryAffinityBaseline,
+} from "./evolution-config";
+
+// SOC 2 guard configuration types live in a sibling module (extracted to keep
+// this file within its size envelope). Re-exported here so the package public
+// surface — consumed via the guards barrel — is unchanged.
+export type {
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
+} from "./soc2-config";
+
+// Evolution & drift-detection baseline config types live in a sibling module
+// (extracted to keep this file within its size envelope). Re-exported here so
+// the package public surface — consumed via the guards barrel — is unchanged.
+export type {
+  DomainAggregateBaseline,
+  AggregateEvolutionConfig,
+  CoverageBaseline,
+  FileClusterBaseline,
+  SubdirectoryAffinityBaseline,
+} from "./evolution-config";
 
 // =============================================================================
 // Size Limits
@@ -299,222 +328,6 @@ export interface EvolutionBaselines {
   subdirectoryAffinity?: SubdirectoryAffinityBaseline;
 }
 
-// =============================================================================
-// Aggregate Evolution Types
-// =============================================================================
-
-/**
- * Domain-level aggregate baseline for evolution tracking.
- * Replaces per-file baselines with domain-aggregated metrics.
- *
- * Design: Domains are extracted from file paths (first 2 segments).
- * Example: 'src/chat/execution/types.ts' → domain 'chat/execution'
- */
-export interface DomainAggregateBaseline {
-  /** Total exports across all files in domain */
-  exports: number;
-  /** Total imports across all files in domain */
-  imports: number;
-  /** Diagnostic only, not thresholded */
-  fileCount: number;
-  /** ISO timestamp when baseline was captured */
-  capturedAt?: string;
-}
-
-/**
- * Configuration for aggregate evolution guard.
- * Uses domain-level metrics instead of per-file tracking.
- *
- * Benefits over per-file:
- * - ~22 entries vs ~300 entries
- * - Stable under refactors within domains
- * - Grows O(domains) not O(files)
- */
-export interface AggregateEvolutionConfig {
-  /** Source directory to scan */
-  srcDir: string;
-  /** Domain baselines keyed by domain path */
-  domains: Record<string, DomainAggregateBaseline>;
-  /** Global totals for sanity checking */
-  totals?: {
-    exports: number;
-    imports: number;
-    files: number;
-    capturedAt?: string;
-  };
-  /** Warning thresholds (sensible defaults applied if omitted) */
-  thresholds?: {
-    /** Absolute export growth before warning (default: 10) */
-    domainExportGrowth?: number;
-    /** Percentage growth before warning (default: 0.25 = 25%) */
-    domainGrowthPercent?: number;
-  };
-}
-
-// =============================================================================
-// Coverage Baseline Types
-// =============================================================================
-
-/**
- * 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;
-}
-
-/**
- * File cluster detection configuration.
- * Detects clusters of related files that could benefit from
- * parent-child folder organization.
- *
- * @see ADR-CI-010
- */
-export interface FileClusterBaseline {
-  /** Minimum files to form a cluster */
-  minClusterSize?: number;
-  /** Minimum stragglers to suggest reorganization */
-  minStragglers?: number;
-  /** Suffixes to strip when detecting clusters (e.g., '.test', '.spec') */
-  stripSuffixes?: string[];
-  /** Role words to strip (e.g., 'Service', 'Handler') */
-  stripRoleWords?: string[];
-  /** Directories to ignore */
-  ignoredDirectories?: string[];
-}
-
-/**
- * Subdirectory affinity detection configuration.
- * Detects files in a parent directory that are only imported by
- * files within a single subdirectory, suggesting they should move.
- */
-export interface SubdirectoryAffinityBaseline {
-  /** Minimum importers required */
-  minImporters?: number;
-  /** Maximum non-subdirectory imports allowed */
-  maxNonSubdirImports?: number;
-  /** Patterns to exclude from analysis */
-  excludePatterns?: RegExp[];
-  /** Importer patterns to ignore */
-  ignoredImporterPatterns?: RegExp[];
-  /** Directories to ignore */
-  ignoredDirectories?: string[];
-}
-
-// =============================================================================
-// SOC 2 Guard Configuration Types
-// =============================================================================
-
-/**
- * Configuration for the secrets detection guard.
- * This is a blocking control for SOC 2 Access Control (AC).
- */
-export interface SecretsDetectionConfig {
-  /** Source directory to scan (relative to repo root) */
-  srcDir?: string;
-  /** Additional directories to scan */
-  additionalDirs?: string[];
-  /** File patterns to exclude (globs) */
-  excludePatterns?: string[];
-  /** Additional secret patterns to detect (regex strings) */
-  additionalPatterns?: string[];
-}
-
-/**
- * Configuration for the structured logging guard.
- * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
- */
-export interface StructuredLoggingConfig {
-  /** Entry point files to check (relative to repo root) */
-  entryPoints?: string[];
-  /** Source directory to scan for logging (fallback if no entry points) */
-  srcDir?: string;
-  /** Recognized logging libraries */
-  loggingLibraries?: string[];
-  /** Logger instantiation patterns (regex strings) */
-  instantiationPatterns?: string[];
-}
-
-/**
- * Configuration for the alerts config guard.
- * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
- */
-export interface AlertsConfigGuardConfig {
-  /**
-   * Files or directories to check for alerting configuration.
-   * Supports both file paths and directory paths.
-   */
-  files?: string[];
-  /**
-   * Whether this check should be skipped.
-   * Use for repos that don't have alerting (e.g., pure libraries).
-   */
-  skip?: boolean;
-  /**
-   * Evidence string when alerting is explicitly skipped.
-   */
-  skipEvidence?: string;
-}
-
-/**
- * Configuration for the backup config guard.
- * This is a non-blocking control for SOC 2 Backup & Recovery (BR).
- */
-export interface BackupConfigGuardConfig {
-  /**
-   * Files or directories to check for backup configuration.
-   */
-  files?: string[];
-  /**
-   * Whether this check should be skipped.
-   * Use for repos that don't manage backups (e.g., frontend-only).
-   */
-  skip?: boolean;
-  /**
-   * Evidence string when backup check is explicitly skipped.
-   */
-  skipEvidence?: string;
-}
-
-/**
- * SOC 2 compliance baselines.
- * Configures SOC 2 control guards for a repository.
- *
- * Design: Product repos provide data only; CI orchestrator owns guard implementations.
- */
-export interface Soc2Baselines {
-  /** Enable SOC 2 compliance reporting */
-  enabled?: boolean;
-  /** Advisory mode: all controls become non-blocking for visibility-only rollout */
-  advisoryMode?: boolean;
-  /** Repository name (for evidence) */
-  repository?: string;
-  /** Secrets detection configuration */
-  secretsDetection?: SecretsDetectionConfig;
-  /** Structured logging configuration */
-  structuredLogging?: StructuredLoggingConfig;
-  /** Alerts config configuration */
-  alertsConfig?: AlertsConfigGuardConfig;
-  /** Backup config configuration */
-  backupConfig?: BackupConfigGuardConfig;
-  /** Controls to explicitly skip (with evidence) */
-  skipControls?: {
-    area: Soc2ControlArea;
-    evidence: string;
-  }[];
-  /**
-   * Controls that remain blocking even in advisory mode.
-   * Use to gradually promote controls from advisory to blocking.
-   * Example: ['AC'] to make secrets-detection blocking first.
-   */
-  alwaysBlockingControls?: Soc2ControlArea[];
-}
-
 /**
  * Registry of checks grouped by tier.
  * Each repo exports this from guard-entries.ts for universal orchestration.

package/src/guards/evolution-config.ts

@@ -0,0 +1,123 @@
+/**
+ * Evolution & Drift-Detection Guard Configuration Vocabulary
+ *
+ * Polymorphic configuration types for the evolution/drift guards: domain-level
+ * aggregate tracking plus the coverage, file-cluster, and subdirectory-affinity
+ * baselines referenced by EvolutionBaselines.
+ *
+ * Extracted from ./config.ts as a cohesive sub-module (the evolution guard
+ * baseline family) to keep config.ts within its file-size envelope. This is a
+ * pure, behavior-preserving move: the identifiers are re-exported from
+ * ./config.ts so the package public surface is unchanged.
+ *
+ * Design principle: Configuration is data, not code.
+ *
+ * @architecture-role universal
+ */
+
+// =============================================================================
+// Aggregate Evolution Types
+// =============================================================================
+
+/**
+ * Domain-level aggregate baseline for evolution tracking.
+ * Replaces per-file baselines with domain-aggregated metrics.
+ *
+ * Design: Domains are extracted from file paths (first 2 segments).
+ * Example: 'src/chat/execution/types.ts' → domain 'chat/execution'
+ */
+export interface DomainAggregateBaseline {
+  /** Total exports across all files in domain */
+  exports: number;
+  /** Total imports across all files in domain */
+  imports: number;
+  /** Diagnostic only, not thresholded */
+  fileCount: number;
+  /** ISO timestamp when baseline was captured */
+  capturedAt?: string;
+}
+
+/**
+ * Configuration for aggregate evolution guard.
+ * Uses domain-level metrics instead of per-file tracking.
+ *
+ * Benefits over per-file:
+ * - ~22 entries vs ~300 entries
+ * - Stable under refactors within domains
+ * - Grows O(domains) not O(files)
+ */
+export interface AggregateEvolutionConfig {
+  /** Source directory to scan */
+  srcDir: string;
+  /** Domain baselines keyed by domain path */
+  domains: Record<string, DomainAggregateBaseline>;
+  /** Global totals for sanity checking */
+  totals?: {
+    exports: number;
+    imports: number;
+    files: number;
+    capturedAt?: string;
+  };
+  /** Warning thresholds (sensible defaults applied if omitted) */
+  thresholds?: {
+    /** Absolute export growth before warning (default: 10) */
+    domainExportGrowth?: number;
+    /** Percentage growth before warning (default: 0.25 = 25%) */
+    domainGrowthPercent?: number;
+  };
+}
+
+// =============================================================================
+// Coverage Baseline Types
+// =============================================================================
+
+/**
+ * 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;
+}
+
+/**
+ * File cluster detection configuration.
+ * Detects clusters of related files that could benefit from
+ * parent-child folder organization.
+ *
+ * @see ADR-CI-010
+ */
+export interface FileClusterBaseline {
+  /** Minimum files to form a cluster */
+  minClusterSize?: number;
+  /** Minimum stragglers to suggest reorganization */
+  minStragglers?: number;
+  /** Suffixes to strip when detecting clusters (e.g., '.test', '.spec') */
+  stripSuffixes?: string[];
+  /** Role words to strip (e.g., 'Service', 'Handler') */
+  stripRoleWords?: string[];
+  /** Directories to ignore */
+  ignoredDirectories?: string[];
+}
+
+/**
+ * Subdirectory affinity detection configuration.
+ * Detects files in a parent directory that are only imported by
+ * files within a single subdirectory, suggesting they should move.
+ */
+export interface SubdirectoryAffinityBaseline {
+  /** Minimum importers required */
+  minImporters?: number;
+  /** Maximum non-subdirectory imports allowed */
+  maxNonSubdirImports?: number;
+  /** Patterns to exclude from analysis */
+  excludePatterns?: RegExp[];
+  /** Importer patterns to ignore */
+  ignoredImporterPatterns?: RegExp[];
+  /** Directories to ignore */
+  ignoredDirectories?: string[];
+}

package/src/guards/soc2-config.ts

@@ -0,0 +1,122 @@
+/**
+ * SOC 2 Guard Configuration Vocabulary
+ *
+ * Polymorphic configuration types for the SOC 2 compliance guards.
+ * Each repo provides its own control config values; shared guards consume them.
+ *
+ * Extracted from ./config.ts as a cohesive sub-module (the SOC 2 control
+ * config family) to keep config.ts within its file-size envelope. This is a
+ * pure, behavior-preserving move: the identifiers are re-exported from
+ * ./config.ts so the package public surface is unchanged.
+ *
+ * Design principle: Configuration is data, not code.
+ *
+ * @architecture-role universal
+ */
+
+import type { Soc2ControlArea } from "./types";
+
+/**
+ * Configuration for the secrets detection guard.
+ * This is a blocking control for SOC 2 Access Control (AC).
+ */
+export interface SecretsDetectionConfig {
+  /** Source directory to scan (relative to repo root) */
+  srcDir?: string;
+  /** Additional directories to scan */
+  additionalDirs?: string[];
+  /** File patterns to exclude (globs) */
+  excludePatterns?: string[];
+  /** Additional secret patterns to detect (regex strings) */
+  additionalPatterns?: string[];
+}
+
+/**
+ * Configuration for the structured logging guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface StructuredLoggingConfig {
+  /** Entry point files to check (relative to repo root) */
+  entryPoints?: string[];
+  /** Source directory to scan for logging (fallback if no entry points) */
+  srcDir?: string;
+  /** Recognized logging libraries */
+  loggingLibraries?: string[];
+  /** Logger instantiation patterns (regex strings) */
+  instantiationPatterns?: string[];
+}
+
+/**
+ * Configuration for the alerts config guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface AlertsConfigGuardConfig {
+  /**
+   * Files or directories to check for alerting configuration.
+   * Supports both file paths and directory paths.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't have alerting (e.g., pure libraries).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when alerting is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * Configuration for the backup config guard.
+ * This is a non-blocking control for SOC 2 Backup & Recovery (BR).
+ */
+export interface BackupConfigGuardConfig {
+  /**
+   * Files or directories to check for backup configuration.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't manage backups (e.g., frontend-only).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when backup check is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * SOC 2 compliance baselines.
+ * Configures SOC 2 control guards for a repository.
+ *
+ * Design: Product repos provide data only; CI orchestrator owns guard implementations.
+ */
+export interface Soc2Baselines {
+  /** Enable SOC 2 compliance reporting */
+  enabled?: boolean;
+  /** Advisory mode: all controls become non-blocking for visibility-only rollout */
+  advisoryMode?: boolean;
+  /** Repository name (for evidence) */
+  repository?: string;
+  /** Secrets detection configuration */
+  secretsDetection?: SecretsDetectionConfig;
+  /** Structured logging configuration */
+  structuredLogging?: StructuredLoggingConfig;
+  /** Alerts config configuration */
+  alertsConfig?: AlertsConfigGuardConfig;
+  /** Backup config configuration */
+  backupConfig?: BackupConfigGuardConfig;
+  /** Controls to explicitly skip (with evidence) */
+  skipControls?: {
+    area: Soc2ControlArea;
+    evidence: string;
+  }[];
+  /**
+   * Controls that remain blocking even in advisory mode.
+   * Use to gradually promote controls from advisory to blocking.
+   * Example: ['AC'] to make secrets-detection blocking first.
+   */
+  alwaysBlockingControls?: Soc2ControlArea[];
+}

package/src/org/sharing.ts

@@ -31,10 +31,20 @@ export interface AclEntry {
  * unit via the authority projection (ADR-BE-169). Distinct from
  * `unit_baseline` (which is membership-role-based) — delegations live on the
  * `org_unit_authority_grants` table and carry an explicit scope set.
+ *
+ * `visibility` covers the general-access band (`private` | `unit` | `org` on
+ * the entity's `visibility` column) — the "General access" tier in the share
+ * dialog. `unit` grants viewer to everyone home-in or matrixed-into the owning
+ * unit's subtree (members ∪ contributors, flowing down); at the org root `unit`
+ * normalizes to org-wide. `org` grants viewer to every org member. This is a
+ * first-class source so the deterministic evaluator, the in-memory open gate,
+ * and the materialized grant-compiler all resolve the band identically. See
+ * ADR-CONTRACTS-075 and backend ADR-BE-374.
  */
 export type AccessSource =
   | "org_rbac"
   | "sharing_policy"
+  | "visibility"
   | "unit_baseline"
   | "unit_delegation"
   | "acl_grant"