@company-semantics/contracts 27.5.0 → 27.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.5.0",
+  "version": "27.7.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -105,9 +105,11 @@
     "test": "vitest run",
     "test:run": "vitest run",
     "generate:spec-hash": "tsx scripts/generate-spec-hash.ts",
-    "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash",
+    "generate:spec-hash:check": "tsx scripts/generate-spec-hash.ts --check",
+    "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes",
     "generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
+    "generate:openapi-routes:check": "tsx scripts/generate-openapi-routes.ts --check",
     "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts",
     "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts",
     "repo-map": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --write",
@@ -123,15 +125,15 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@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/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '511ebe19b2ad' as const;
-export const SPEC_HASH_FULL = '511ebe19b2adea947b0bfbd6ad39a192a616cf10e2d30606dde9ef8517389eed' as const;
+export const SPEC_HASH = '628fe99ff916' as const;
+export const SPEC_HASH_FULL = '628fe99ff9166b9eb6c0b2bab2794f4e730ceabff0785b7b54b8015897e9551d' as const;

package/src/api/generated.ts

@@ -770,6 +770,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/reporting/move/apply": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Apply a confirmed org-chart reporting move as a governed semantic transform */
+        post: operations["applyReportingMove"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chat/interactive-tasks/submit": {
         parameters: {
             query?: never;
@@ -3927,16 +3944,47 @@ export interface components {
             idempotencyKey: string;
         };
         MovePreviewRequest: {
-            /**
-             * Format: uuid
-             * @description Workspace member (users.id) being moved in the chart
-             */
-            memberId: string;
-            /**
-             * Format: uuid
-             * @description The member (users.id) the dragged member should report to after the move
-             */
-            newManagerUserId: string;
+            /** @constant */
+            kind: "reporting.setManager";
+            /** Format: uuid */
+            reportPositionId: string;
+            /** Format: uuid */
+            managerPositionId: string;
+        } | {
+            /** @constant */
+            kind: "unit.setParent";
+            /** Format: uuid */
+            unitId: string;
+            parentUnitId: string | null;
+        } | {
+            /** @constant */
+            kind: "position.setTitle";
+            /** Format: uuid */
+            positionId: string;
+            title: string;
+        };
+        MoveApplyRequest: {
+            mutations: ({
+                /** @constant */
+                kind: "reporting.setManager";
+                /** Format: uuid */
+                reportPositionId: string;
+                managerPositionId: string | null;
+            } | {
+                /** @constant */
+                kind: "unit.setParent";
+                /** Format: uuid */
+                unitId: string;
+                parentUnitId: string | null;
+            } | {
+                /** @constant */
+                kind: "position.setTitle";
+                /** Format: uuid */
+                positionId: string;
+                title: string;
+            })[];
+            reason: string | null;
+            idempotencyKey: string;
         };
         SubmitInteractiveTaskResponse: {
             executionId: string;
@@ -7101,6 +7149,28 @@ export interface operations {
             };
         };
     };
+    applyReportingMove: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MoveApplyRequest"];
+            };
+        };
+        responses: {
+            /** @description The confirmed transformation was applied through the governed execution */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     submitInteractiveTask: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -126,6 +126,7 @@ export const openApiRoutes = {
   '/api/orgs/{orgId}/level-config': ['GET', 'PUT'],
   '/api/rbac/roles': ['GET'],
   '/api/reporting/bulk-reparent': ['POST'],
+  '/api/reporting/move/apply': ['POST'],
   '/api/reporting/move/preview': ['POST'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],

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"