@company-semantics/contracts 27.6.0 → 27.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.6.0",
+  "version": "27.8.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/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 = '628fe99ff916' as const;
-export const SPEC_HASH_FULL = '628fe99ff9166b9eb6c0b2bab2794f4e730ceabff0785b7b54b8015897e9551d' as const;
+export const SPEC_HASH = '1c5dcd23d461' as const;
+export const SPEC_HASH_FULL = '1c5dcd23d46109024a008dea6440892f9a1ccd0b725fc6e0ed0bb3abe28bf78d' as const;

package/src/api/generated.ts

@@ -3962,6 +3962,12 @@ export interface components {
             /** Format: uuid */
             positionId: string;
             title: string;
+        } | {
+            /** @constant */
+            kind: "reporting.setManagerBulk";
+            reportPositionIds: string[];
+            /** Format: uuid */
+            managerPositionId: string;
         };
         MoveApplyRequest: {
             mutations: ({

package/src/email/__tests__/registry.test.ts

@@ -62,6 +62,24 @@ describe("EMAIL_KINDS golden snapshot", () => {
         plainTextRequired: true,
         htmlSupported: true,
       },
+      "companyMd.access_requested": {
+        kind: "companyMd.access_requested",
+        subject: "Someone requested access to a document",
+        plainTextRequired: true,
+        htmlSupported: true,
+      },
+      "companyMd.access_request_approved": {
+        kind: "companyMd.access_request_approved",
+        subject: "Your access request was approved",
+        plainTextRequired: true,
+        htmlSupported: true,
+      },
+      "companyMd.access_request_denied": {
+        kind: "companyMd.access_request_denied",
+        subject: "Your access request was reviewed",
+        plainTextRequired: true,
+        htmlSupported: true,
+      },
     });
   });
 });

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/__tests__/transformation.test.ts

@@ -106,6 +106,55 @@ describe("OrgIntentSchema", () => {
       }).success,
     ).toBe(false);
   });
+
+  it("accepts a reporting.setManagerBulk intent (N seats -> one manager)", () => {
+    const intent = {
+      kind: "reporting.setManagerBulk" as const,
+      reportPositionIds: [REPORT, POSITION],
+      managerPositionId: MANAGER,
+    };
+    expect(OrgIntentSchema.parse(intent)).toEqual(intent);
+  });
+
+  it("rejects an empty bulk reportPositionIds array", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "reporting.setManagerBulk",
+        reportPositionIds: [],
+        managerPositionId: MANAGER,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a bulk array beyond the 500-seat transport cap", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "reporting.setManagerBulk",
+        reportPositionIds: Array.from({ length: 501 }, () => REPORT),
+        managerPositionId: MANAGER,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid entry in the bulk report set", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "reporting.setManagerBulk",
+        reportPositionIds: [REPORT, "x"],
+        managerPositionId: MANAGER,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a null bulk managerPositionId (intents always set a manager)", () => {
+    expect(
+      OrgIntentSchema.safeParse({
+        kind: "reporting.setManagerBulk",
+        reportPositionIds: [REPORT],
+        managerPositionId: null,
+      }).success,
+    ).toBe(false);
+  });
 });
 
 describe("FactMutationSchema", () => {
@@ -436,4 +485,23 @@ describe("TransformationPreviewSchema", () => {
       false,
     );
   });
+
+  it("accepts a multi-headline preview carrying primaryMutations (bulk intent)", () => {
+    const second = { ...setManagerMutation, reportPositionId: POSITION };
+    expect(
+      TransformationPreviewSchema.safeParse({
+        ...preview,
+        primaryMutations: [setManagerMutation, second],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects a single-element primaryMutations (single moves omit the field)", () => {
+    expect(
+      TransformationPreviewSchema.safeParse({
+        ...preview,
+        primaryMutations: [setManagerMutation],
+      }).success,
+    ).toBe(false);
+  });
 });

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"

package/src/org/transformation.ts

@@ -95,6 +95,25 @@ export const OrgIntentSchema = z.discriminatedUnion("kind", [
     /** The new human-facing title for the seat (non-empty, matching PositionSchema.title). */
     title: z.string().min(1),
   }),
+  // reporting.setManagerBulk — N reporting seats re-pointed at ONE manager as a
+  // single atomic intent (the org-chart cluster-pill drop). The engine expands
+  // it into N `reporting.setManager` FactMutations — the existing
+  // Intent-vs-Mutation asymmetry; no bulk mutation kind exists or is needed.
+  // Cross-field rules (manager ∉ reports, dedupe) are enforced at the route: a
+  // discriminatedUnion member cannot carry a ZodEffects refinement.
+  z.object({
+    kind: z.literal("reporting.setManagerBulk"),
+    /**
+     * The reporting seats being re-pointed together (e.g. a unit cluster's
+     * direct members; their subtrees follow implicitly). Order-insensitive;
+     * the engine treats the set as one atomic intent. The cap mirrors the
+     * bulk-reparent transport bound (ADR-BE-318).
+     */
+    reportPositionIds: z.array(z.string().uuid()).min(1).max(500),
+    /** The ONE manager seat every report re-points to. Non-null on an intent
+     * (un-setting is a mutation concern, exactly as on `reporting.setManager`). */
+    managerPositionId: z.string().uuid(),
+  }),
 ]);
 export type OrgIntent = z.infer<typeof OrgIntentSchema>;
 
@@ -336,6 +355,15 @@ export const TransformationPreviewSchema = z.object({
   intentLabel: z.string().min(1),
   /** The headline fact change the preview is centered on. */
   primary: FactMutationSchema,
+  /**
+   * Present only when the intent expands into MORE THAN ONE headline mutation
+   * (e.g. `reporting.setManagerBulk`): the full primary bundle, of which
+   * `primary` is the first element. Absent on single-mutation previews so
+   * existing consumers and goldens see byte-identical output. These are the
+   * INTENT's own edges — engine repair splices stay in the strategies'
+   * recommendations, never here.
+   */
+  primaryMutations: z.array(FactMutationSchema).min(2).optional(),
   /** The strategy the engine recommends by default. */
   defaultStrategy: TransformStrategySchema,
   /** Other viable strategies the operator may pick instead. */