@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/execution/managed-workspace.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -14,6 +14,7 @@ import { branchSlugSegment, validateBranchName } from '../../cli/repositories/br
 import { withControllerLock } from '../../cli/repositories/locks';
 import { resolveGitExecutable } from '../../effects/git-executable';
 import { runProcess } from '../../effects/process-runner';
+import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../shared/process-environment';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
 
 export interface EnsureManagedWorkspaceInput {
@@ -21,6 +22,24 @@ export interface EnsureManagedWorkspaceInput {
   title: string;
   baseRef?: string;
   branchName?: string;
+  /** Explicitly materialize lockfile-backed Node dependencies in this isolated worktree. */
+  prepareDependencies?: boolean;
+}
+
+export interface ManagedWorkspaceDependencyBootstrap {
+  packageManager: 'bun' | 'pnpm' | 'npm' | 'yarn';
+  lockfile: string;
+  command: string[];
+}
+
+export interface ManagedWorkspaceDependencyPreparation {
+  mode: 'already_ready' | 'canonical_reuse' | 'installed';
+  nodeModulesRoot: string;
+  canonicalRoot?: string;
+}
+
+export interface ManagedWorkspaceDependencies {
+  materializeDependencies?: (workspaceRoot: string) => void;
 }
 
 export interface ManagedWorkspace {
@@ -73,6 +92,180 @@ function assertBranch(root: string, branch: string): string {
   return normalized;
 }
 
+export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  const lockCandidates = [
+    ['bun', 'bun.lock', ['bun', 'install', '--frozen-lockfile']],
+    ['bun', 'bun.lockb', ['bun', 'install', '--frozen-lockfile']],
+    ['pnpm', 'pnpm-lock.yaml', ['pnpm', 'install', '--frozen-lockfile']],
+    ['npm', 'package-lock.json', ['npm', 'ci']],
+    ['yarn', 'yarn.lock', ['yarn', 'install', '--frozen-lockfile']],
+  ] as const;
+  const detected = lockCandidates.find(([, lockfile]) => existsSync(join(repoRoot, lockfile)));
+  if (!detected) return undefined;
+  return { packageManager: detected[0], lockfile: detected[1], command: [...detected[2]] };
+}
+
+const DEPENDENCY_REUSE_CONFIG_PATHS = [
+  '.npmrc',
+  'bunfig.toml',
+  'pnpm-workspace.yaml',
+  '.yarnrc.yml',
+] as const;
+
+function dependencyInputMatches(leftRoot: string, rightRoot: string, path: string): boolean {
+  const left = join(leftRoot, path);
+  const right = join(rightRoot, path);
+  const leftExists = existsSync(left);
+  const rightExists = existsSync(right);
+  if (leftExists !== rightExists) return false;
+  return !leftExists || readFileSync(left).equals(readFileSync(right));
+}
+
+function linkedWorkspaceCanonicalRoot(repoRoot: string): string | undefined {
+  const common = runProcess(resolveGitExecutable(), ['-C', repoRoot, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!common.ok || !common.stdout.trim()) return undefined;
+  const canonicalRoot = dirname(resolve(common.stdout.trim()));
+  if (!existsSync(canonicalRoot)) return undefined;
+  try {
+    if (realpathSync(canonicalRoot) === realpathSync(repoRoot)) return undefined;
+  } catch {
+    return undefined;
+  }
+  const topLevel = runProcess(resolveGitExecutable(), ['-C', canonicalRoot, 'rev-parse', '--show-toplevel'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!topLevel.ok || !topLevel.stdout.trim()) return undefined;
+  try {
+    return realpathSync(topLevel.stdout.trim()) === realpathSync(canonicalRoot) ? canonicalRoot : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string): {
+  canonicalRoot: string;
+  nodeModulesRoot: string;
+} | undefined {
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) return undefined;
+  const canonicalRoot = linkedWorkspaceCanonicalRoot(repoRoot);
+  if (!canonicalRoot) return undefined;
+  const nodeModulesRoot = join(canonicalRoot, 'node_modules');
+  if (!existsSync(nodeModulesRoot)) return undefined;
+  const dependencyInputs = ['package.json', bootstrap.lockfile, ...DEPENDENCY_REUSE_CONFIG_PATHS];
+  if (!dependencyInputs.every((path) => dependencyInputMatches(repoRoot, canonicalRoot, path))) return undefined;
+  return { canonicalRoot, nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+function packageManifestRequiresDependencyMaterialization(repoRoot: string): boolean {
+  const packagePath = join(repoRoot, 'package.json');
+  if (!existsSync(packagePath)) return false;
+  let manifest: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return true;
+    manifest = parsed as Record<string, unknown>;
+  } catch {
+    // Preserve fail-closed dependency preparation for malformed manifests. The
+    // package manager remains the authority for the concrete parse error once a
+    // supported frozen lockfile is present.
+    return true;
+  }
+
+  const dependencyFields = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+    'bundleDependencies',
+    'bundledDependencies',
+  ] as const;
+  if (dependencyFields.some((field) => {
+    const value = manifest[field];
+    return Array.isArray(value)
+      ? value.length > 0
+      : Boolean(value && typeof value === 'object' && Object.keys(value as Record<string, unknown>).length > 0);
+  })) return true;
+
+  const workspaces = manifest.workspaces;
+  if (Array.isArray(workspaces)) return workspaces.length > 0;
+  if (workspaces && typeof workspaces === 'object') {
+    const packages = (workspaces as Record<string, unknown>).packages;
+    if (Array.isArray(packages)) return packages.length > 0;
+    return Object.keys(workspaces as Record<string, unknown>).length > 0;
+  }
+  return false;
+}
+
+function reuseManagedWorkspaceCanonicalDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  const reusable = resolveManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (!reusable) return undefined;
+  try {
+    symlinkSync(reusable.nodeModulesRoot, nodeModulesRoot, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (!existsSync(nodeModulesRoot)) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_REUSE_FAILED: ${detail}`);
+    }
+  }
+  return {
+    mode: 'canonical_reuse',
+    nodeModulesRoot: realpathSync(nodeModulesRoot),
+    canonicalRoot: reusable.canonicalRoot,
+  };
+}
+
+export function materializeManagedWorkspaceDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json'))) return undefined;
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  if (existsSync(nodeModulesRoot)) {
+    return { mode: 'already_ready', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+  }
+  // A linked worktree may safely reuse canonical dependencies even when the
+  // package manifest itself declares no dependencies. The supported lockfile
+  // and dependency-reuse inputs remain the authority for proving equivalence.
+  const reused = reuseManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (reused) return reused;
+  // A package manifest can define dependency-free scripts (for example a
+  // built-in `node -e` check). Such checks do not need node_modules and must not
+  // be rejected merely because the repository intentionally has no lockfile.
+  if (!packageManifestRequiresDependencyMaterialization(repoRoot)) return undefined;
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) {
+    throw new Error('MANAGED_WORKSPACE_DEPENDENCY_LOCK_REQUIRED: package.json declares dependencies but no supported lockfile was found');
+  }
+  const childEnv = repositoryChildProcessEnvironment();
+  const executable = bootstrap.packageManager === 'bun'
+    ? resolveBunExecutable(process.execPath, childEnv)
+    : bootstrap.command[0]!;
+  const result = runProcess(executable, bootstrap.command.slice(1), {
+    cwd: repoRoot,
+    env: childEnv,
+    timeoutMs: 10 * 60_000,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  if (!result.ok) {
+    const detail = result.stderr || result.error || `exit ${result.status}`;
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_FAILED: ${bootstrap.command.join(' ')}: ${detail}`);
+  }
+  if (!existsSync(nodeModulesRoot)) {
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_INCOMPLETE: ${bootstrap.command.join(' ')} completed without node_modules`);
+  }
+  return { mode: 'installed', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+export function materializeManagedWorkspaceCheckDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  if (!linkedWorkspaceCanonicalRoot(repoRoot)) return undefined;
+  return materializeManagedWorkspaceDependencies(repoRoot);
+}
+
 function existingWorkspace(path: string, branch: string): boolean {
   if (!existsSync(path)) return false;
   const root = runProcess(resolveGitExecutable(), ['-C', path, 'rev-parse', '--show-toplevel'], {
@@ -109,6 +302,7 @@ export function ensureManagedWorkspace(
   controllerHome: string,
   repository: RepositoryRecord,
   input: EnsureManagedWorkspaceInput,
+  dependencies: ManagedWorkspaceDependencies = {},
 ): ManagedWorkspace {
   const requestId = input.requestId.trim();
   if (!requestId) throw new Error('MANAGED_WORKSPACE_REQUEST_ID_REQUIRED');
@@ -159,6 +353,14 @@ export function ensureManagedWorkspace(
       if (!repositoryCheckoutRootMatches(repository, path)) {
         throw new Error(`MANAGED_WORKSPACE_REPOSITORY_MISMATCH: ${path}`);
       }
+      if (input.prepareDependencies === true) {
+        (dependencies.materializeDependencies ?? materializeManagedWorkspaceDependencies)(path);
+      } else {
+        // Reusing a byte-equivalent canonical dependency tree is cheap and
+        // deterministic, so isolated Work checkouts should get it even when a
+        // full package-manager install was not explicitly requested.
+        reuseManagedWorkspaceCanonicalDependencies(path);
+      }
 
       const record = addRepositoryCheckout({
         repoId: repository.repoId,

package/src/runtime/execution/process-runtime/check-facade.ts

@@ -1,8 +1,9 @@
 /**
  * Lightweight run_check facade.
  *
- * Short checks complete via Process Runtime and return results directly.
- * Long checks return a Managed Process handle for the same OS process.
+ * Ordinary checks execute through an in-memory lightweight handle and return
+ * within the interactive budget without creating Process/Lease state. Checks
+ * with real Work/Edit/verification consumers keep persisted Process receipts.
  * Multi-phase and release checks require explicit external Controller handling.
  */
 
@@ -15,6 +16,12 @@ import {
 } from '../../../cli/controller/check-runner';
 import { claimsForCheck, scopeResourceClaims, toProcessClaims } from './resource-claims';
 import { spawnManagedProcess, waitForProcess, getProcessHandle } from './runtime';
+import {
+  getLightweightProcessHandle,
+  isLightweightProcessId,
+  startLightweightControllerCheck,
+  waitForLightweightProcess,
+} from './lightweight-managed';
 import type { ProcessHandle } from './types';
 import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
@@ -37,10 +44,14 @@ export interface RunCheckFacadeInput {
    */
   leaseWaitMs?: number;
   requestId?: string;
+  /** Stable caller-owned semantic identity for safely reattaching the same request before rebuilding ephemeral execution inputs. */
+  requestSemanticFingerprint?: string;
   workId?: string;
   commandId?: string;
   /** Force durable workflow (release / multi-phase). */
   forceDurable?: boolean;
+  /** Internal-only: allow an already-authorized external Work Controller to execute a durable-class check through persisted Process Runtime. */
+  allowDurableCheckExecution?: boolean;
   signal?: AbortSignal;
   /** Immutable resolved identity — required; never inferred from main/active/cwd. */
   executionIdentity: ResolvedExecutionIdentity;
@@ -64,16 +75,7 @@ export function processCheckSemanticScopeKey(
   input: Pick<RunCheckFacadeInput, 'workId' | 'verificationBinding' | 'checkoutId'>,
   reuseScope: 'repository' | 'checkout',
 ): string {
-  const base = reuseScope === 'repository' ? 'repository' : `checkout:${input.checkoutId ?? 'unknown'}`;
-  const binding = input.verificationBinding;
-  const owner = [
-    input.workId ? `work:${input.workId}` : undefined,
-    binding?.executionSessionId ? `execution:${binding.executionSessionId}` : undefined,
-    binding?.editSessionId ? `edit:${binding.editSessionId}:r${binding.editRevision ?? 'unknown'}` : undefined,
-    binding?.issueId ? `issue:${binding.issueId}` : undefined,
-    binding?.taskId ? `task:${binding.taskId}` : undefined,
-  ].filter(Boolean).join('|') || 'unbound';
-  return `${base}|owner:${owner}`;
+  return reuseScope === 'repository' ? 'repository' : `checkout:${input.checkoutId ?? 'unknown'}`;
 }
 
 export interface RunCheckFacadeResult {
@@ -152,8 +154,9 @@ export async function runCheckViaProcessRuntime(
     };
   }
 
-  // Most checks are builds/tests; return their existing Process handle at once.
-  // Only predictable shell primitives keep a short synchronous admission.
+  // The wait budget is an interaction preference, not a persistence reason.
+  // Ordinary checks stay in memory; only a real durable evidence consumer may
+  // allocate Process/Lease state.
   const interactiveWaitMs = durationAwareInteractiveWaitMs(
     check.command,
     input.interactiveWaitMs,
@@ -165,6 +168,14 @@ export async function runCheckViaProcessRuntime(
       ? Math.max(1_000, Math.trunc(input.timeoutMs))
       : check.timeoutMs,
   );
+  const durableVerificationBinding = Boolean(
+    input.workId
+    || input.verificationSnapshot
+    || input.verificationBinding?.executionSessionId
+    || input.verificationBinding?.editSessionId
+    || input.verificationBinding?.issueId
+    || input.verificationBinding?.taskId,
+  );
   if (!input.executionIdentity) {
     throw new Error('EXECUTION_IDENTITY_REQUIRED: run_check requires an immutable executionIdentity');
   }
@@ -179,6 +190,27 @@ export async function runCheckViaProcessRuntime(
       `CHECKOUT_ROUTE_MISMATCH: check checkout ${input.checkoutId} differs from identity ${executionIdentity.checkoutId}`,
     );
   }
+  if (!durableVerificationBinding) {
+    const lightweight = await startLightweightControllerCheck({
+      controllerHome: input.controllerHome,
+      repoId: input.repoId,
+      repoRoot: input.repoRoot,
+      checkId: input.checkId,
+      interactiveWaitMs,
+      timeoutMs,
+      workId: input.workId,
+      commandId: input.commandId ?? input.requestId,
+    });
+    const handle = lightweight.handle;
+    return {
+      mode: handle.completed ? 'direct' : 'managed',
+      checkId: input.checkId,
+      check,
+      process: handle,
+      ok: handle.completed ? handle.ok : undefined,
+      durableSideEffects: emptyEffects,
+    };
+  }
   const claims = scopeResourceClaims(
     claimsForCheck(
       input.checkId,
@@ -261,6 +293,9 @@ export async function waitForCheckProcess(
   processId: string,
   timeoutMs?: number,
 ): Promise<ProcessHandle> {
+  if (isLightweightProcessId(processId)) {
+    return waitForLightweightProcess(controllerHome, repoId, processId, { timeoutMs });
+  }
   return waitForProcess(controllerHome, repoId, processId, { timeoutMs });
 }
 
@@ -269,6 +304,9 @@ export function getCheckProcessHandle(
   repoId: string,
   processId: string,
 ): ProcessHandle | undefined {
+  if (isLightweightProcessId(processId)) {
+    return getLightweightProcessHandle(controllerHome, repoId, processId);
+  }
   return getProcessHandle(controllerHome, repoId, processId);
 }
 

package/src/runtime/execution/process-runtime/check-result.ts

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { processLogDir } from './store';
+import type { ManagedProcessRecord } from './types';
 
 export interface PersistedCheckResultReceipt {
   schemaVersion: 1;
@@ -18,10 +19,18 @@ export interface PersistedCheckResultReceipt {
   cacheHit?: boolean;
 }
 
-export function allocatePersistedCheckResultReceiptPath(controllerHome: string, repoId: string): string {
+export function allocatePersistedCheckResultReceiptPath(
+  controllerHome: string,
+  repoId: string,
+  requestId?: string,
+): string {
   const root = join(processLogDir(controllerHome, repoId), 'check-results');
   mkdirSync(root, { recursive: true });
-  return join(root, `${randomUUID()}.json`);
+  const stableRequestId = requestId?.trim();
+  const receiptId = stableRequestId
+    ? `request-${createHash('sha256').update(stableRequestId).digest('hex').slice(0, 32)}`
+    : randomUUID();
+  return join(root, `${receiptId}.json`);
 }
 
 export function writePersistedCheckResultReceipt(path: string, input: Omit<PersistedCheckResultReceipt, 'schemaVersion' | 'receiptId'>): PersistedCheckResultReceipt {
@@ -43,3 +52,55 @@ export function readPersistedCheckResultReceipt(path: string | undefined): Persi
     return undefined;
   }
 }
+
+export type PersistedCheckTerminalEvidenceState =
+  | 'matched'
+  | 'process_runtime_failed_before_result'
+  | 'missing'
+  | 'mismatch';
+
+export interface PersistedCheckTerminalEvidence {
+  state: PersistedCheckTerminalEvidenceState;
+  failureClass?: PersistedCheckResultReceipt['failureClass'];
+  warning?: string;
+  infrastructureReason?: string;
+}
+
+/**
+ * Classify one terminal Check Process using the structured result emitted by
+ * the check-runner sidecar. A Process Runtime/admission failure can terminate
+ * before that result exists (for example PROCESS_LEASE_CONFLICT); such a
+ * Process is infrastructure failure, never evidence that repository checks
+ * rejected the candidate. Missing/mismatched result identity also fails closed
+ * as infrastructure rather than manufacturing acceptance evidence.
+ */
+export function classifyPersistedCheckTerminalEvidence(
+  record: ManagedProcessRecord,
+  expectedCheckId: string,
+): PersistedCheckTerminalEvidence {
+  const structured = readPersistedCheckResultReceipt(record.origin?.checkResultReceiptPath);
+  const structuredMatches = Boolean(
+    structured
+    && record.checkExecution
+    && structured.checkId === expectedCheckId
+    && structured.cacheKey === record.checkExecution.cacheKey,
+  );
+  if (structuredMatches) {
+    return { state: 'matched', failureClass: structured?.failureClass };
+  }
+  if (!structured && record.error?.message?.trim()) {
+    const reason = record.error.message.trim().slice(0, 512);
+    return {
+      state: 'process_runtime_failed_before_result',
+      warning: `check process failed before structured result receipt: ${reason}`,
+      infrastructureReason: reason,
+    };
+  }
+  if (structured) {
+    return {
+      state: 'mismatch',
+      warning: 'check result receipt did not match the terminal Process semantic identity',
+    };
+  }
+  return { state: 'missing', warning: 'check result receipt is missing for the terminal Check Process' };
+}

package/src/runtime/execution/process-runtime/check-scheduling.ts

@@ -0,0 +1,114 @@
+import type { ControllerCheck } from '../../../cli/controller/check-runner';
+import type { ResourceClaimSpec } from '../jobs/types';
+import { resourceClaimsConflict } from '../../resources/claims/conflicts';
+import { claimsForCheck } from './resource-claims';
+
+export interface CheckExecutionWave {
+  wave: number;
+  checkIds: string[];
+  parallelSafe: boolean;
+}
+
+export interface CheckExecutionConflict {
+  leftCheckId: string;
+  rightCheckId: string;
+  resources: Array<{
+    left: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+    right: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+  }>;
+}
+
+interface ScheduledCheck {
+  check: ControllerCheck;
+  claims: ResourceClaimSpec[];
+}
+
+function conflictingResources(left: ScheduledCheck, right: ScheduledCheck): CheckExecutionConflict['resources'] {
+  const conflicts: CheckExecutionConflict['resources'] = [];
+  for (const leftClaim of left.claims) {
+    for (const rightClaim of right.claims) {
+      if (!resourceClaimsConflict(leftClaim, rightClaim)) continue;
+      conflicts.push({
+        left: { resourceKey: leftClaim.resourceKey, mode: leftClaim.mode },
+        right: { resourceKey: rightClaim.resourceKey, mode: rightClaim.mode },
+      });
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * Produce deterministic execution waves from the exact same resource-claim model
+ * used by Process Runtime. Checks in one wave may overlap; waves run in order.
+ * This is advisory scheduling metadata, not a second lease authority.
+ */
+export function buildCheckExecutionSchedule(input: {
+  checks: ControllerCheck[];
+  requestedCheckIds: string[];
+  repoId: string;
+  checkoutId?: string;
+}): {
+  waves: CheckExecutionWave[];
+  conflicts: CheckExecutionConflict[];
+  invalidCheckIds: string[];
+  maxParallel: number;
+  guidance: string[];
+  claimsByCheck: Array<{ checkId: string; claims: Array<Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>> }>;
+} {
+  const byId = new Map(input.checks.map((check) => [check.id, check]));
+  const requested = [...new Set(input.requestedCheckIds.filter(Boolean))];
+  const invalidCheckIds = requested.filter((checkId) => !byId.has(checkId));
+  const scheduled: ScheduledCheck[] = requested.flatMap((checkId) => {
+    const check = byId.get(checkId);
+    if (!check) return [];
+    return [{
+      check,
+      claims: claimsForCheck(check.id, check.command, input.repoId, input.checkoutId, check.effects),
+    }];
+  });
+
+  const conflicts: CheckExecutionConflict[] = [];
+  for (let leftIndex = 0; leftIndex < scheduled.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < scheduled.length; rightIndex += 1) {
+      const left = scheduled[leftIndex]!;
+      const right = scheduled[rightIndex]!;
+      const resources = conflictingResources(left, right);
+      if (resources.length === 0) continue;
+      conflicts.push({ leftCheckId: left.check.id, rightCheckId: right.check.id, resources });
+    }
+  }
+
+  const waves: ScheduledCheck[][] = [];
+  for (const entry of scheduled) {
+    const compatible = waves.find((wave) => wave.every((other) => conflictingResources(entry, other).length === 0));
+    if (compatible) compatible.push(entry);
+    else waves.push([entry]);
+  }
+
+  const projectedWaves = waves.map((wave, index) => ({
+    wave: index + 1,
+    checkIds: wave.map((entry) => entry.check.id),
+    parallelSafe: wave.length > 1,
+  }));
+  const maxParallel = projectedWaves.reduce((max, wave) => Math.max(max, wave.checkIds.length), 0);
+  const guidance: string[] = [];
+  if (projectedWaves.length > 1) {
+    guidance.push('Run check waves in order; only checks within the same wave are resource-compatible for overlap.');
+  } else if (maxParallel > 1) {
+    guidance.push('Requested checks are resource-compatible and may run concurrently for this checkout.');
+  } else if (maxParallel === 1) {
+    guidance.push('Run the requested check as one focused verification unit.');
+  }
+
+  return {
+    waves: projectedWaves,
+    conflicts,
+    invalidCheckIds,
+    maxParallel,
+    guidance,
+    claimsByCheck: scheduled.map((entry) => ({
+      checkId: entry.check.id,
+      claims: entry.claims.map((claim) => ({ resourceKey: claim.resourceKey, mode: claim.mode })),
+    })),
+  };
+}