@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -0,0 +1,132 @@
+import { existsSync, lstatSync, opendirSync, statSync, unlinkSync } from 'fs';
+import { join, relative } from 'path';
+import { isTerminalWorkContractStatus, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { listControlPlaneRecords } from '../../control-plane/persistence/sqlite-store';
+import { processLogDir } from './store';
+import { readPersistedCheckResultReceipt } from './check-result';
+
+const DEFAULT_CHECK_RESULT_TTL_MS = 30 * 24 * 60 * 60_000;
+const DEFAULT_MAX_RETAINED_CHECK_RESULTS = 500;
+const DEFAULT_MAX_REMOVALS = 50;
+
+export interface CheckResultRetentionReport {
+  policyVersion: 'check-result-retention-v1';
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  removed: number;
+  retained: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  removedPaths: string[];
+  blockers: string[];
+  budgetExhausted: boolean;
+  scanTruncated: boolean;
+}
+
+export function cleanupPersistedCheckResults(
+  controllerHome: string,
+  repoId: string,
+  options: { nowMs?: number; ttlMs?: number; maxRetained?: number; maxRemovals?: number; maxScan?: number } = {},
+): CheckResultRetentionReport {
+  const report: CheckResultRetentionReport = {
+    policyVersion: 'check-result-retention-v1', inspected: 0, eligible: 0, attempted: 0, removed: 0, retained: 0,
+    reclaimedBytes: 0, unknownReclaimedByteCount: 0, removedPaths: [], blockers: [], budgetExhausted: false, scanTruncated: false,
+  };
+  const root = join(processLogDir(controllerHome, repoId), 'check-results');
+  if (!existsSync(root)) return report;
+  const nowMs = options.nowMs ?? Date.now();
+  const ttlMs = Math.max(60_000, Math.floor(options.ttlMs ?? DEFAULT_CHECK_RESULT_TTL_MS));
+  const maxRetained = Math.max(1, Math.floor(options.maxRetained ?? DEFAULT_MAX_RETAINED_CHECK_RESULTS));
+  let remaining = Math.max(0, Math.floor(options.maxRemovals ?? DEFAULT_MAX_REMOVALS));
+  const maxScan = Math.max(1, Math.min(Math.floor(options.maxScan ?? 5_000), 5_000));
+
+  const protectedCacheKeys = new Set<string>();
+  const workRecords = listControlPlaneRecords<WorkContract>(controllerHome, { namespace: 'work_contract', scope: repoId, limit: 5_000 });
+  if (workRecords.length >= 5_000) {
+    report.scanTruncated = true;
+    report.blockers.push('work_scan_truncated');
+    return report;
+  }
+  for (const record of workRecords) {
+    const work = record.value;
+    if (isTerminalWorkContractStatus(work.status)) continue;
+    for (const verification of work.checkRefs ?? []) {
+      const key = verification.receipt?.checkCacheKey?.trim();
+      if (key) protectedCacheKeys.add(key);
+    }
+  }
+
+  const candidates: Array<{ path: string; name: string; cacheKey: string; executedAtMs: number; bytes?: number }> = [];
+  let directory: ReturnType<typeof opendirSync>;
+  try { directory = opendirSync(root); } catch { return report; }
+  try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      if (report.inspected >= maxScan) { report.scanTruncated = true; break; }
+      const name = entry.name;
+      report.inspected += 1;
+      const path = join(root, name);
+    try {
+      if (lstatSync(path).isSymbolicLink()) {
+        report.blockers.push(`symlink:${name}`);
+        continue;
+      }
+      const receipt = readPersistedCheckResultReceipt(path);
+      if (!receipt) {
+        report.blockers.push(`invalid_receipt:${name}`);
+        continue;
+      }
+      const executedAtMs = Date.parse(receipt.originalExecutedAt ?? receipt.executedAt);
+      if (!Number.isFinite(executedAtMs)) {
+        report.blockers.push(`invalid_time:${name}`);
+        continue;
+      }
+      let bytes: number | undefined;
+      try { bytes = statSync(path).size; } catch { /* retained if removal succeeds but size is unknown */ }
+      candidates.push({ path, name, cacheKey: receipt.cacheKey, executedAtMs, bytes });
+      } catch {
+        report.blockers.push(`inspect_failed:${name}`);
+      }
+    }
+  } finally {
+    directory.closeSync();
+  }
+
+  candidates.sort((left, right) => right.executedAtMs - left.executedAtMs || left.name.localeCompare(right.name));
+  let unprotectedRank = 0;
+  for (const candidate of candidates) {
+    if (protectedCacheKeys.has(candidate.cacheKey)) {
+      report.retained += 1;
+      continue;
+    }
+    const overCount = !report.scanTruncated && unprotectedRank >= maxRetained;
+    unprotectedRank += 1;
+    const ageExpired = nowMs - candidate.executedAtMs >= ttlMs;
+    if (!overCount && !ageExpired) {
+      report.retained += 1;
+      continue;
+    }
+    report.eligible += 1;
+    if (remaining <= 0) {
+      report.budgetExhausted = true;
+      report.retained += 1;
+      continue;
+    }
+    report.attempted += 1;
+    try {
+      unlinkSync(candidate.path);
+      remaining -= 1;
+      report.removed += 1;
+      report.removedPaths.push(relative(controllerHome, candidate.path));
+      if (candidate.bytes === undefined) report.unknownReclaimedByteCount += 1;
+      else report.reclaimedBytes += candidate.bytes;
+    } catch {
+      report.blockers.push(`remove_failed:${candidate.name}`);
+      report.retained += 1;
+    }
+  }
+  return report;
+}

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

@@ -4,6 +4,68 @@ import { dirname, join } from 'path';
 import { processLogDir } from './store';
 import type { ManagedProcessRecord } from './types';
 
+export const STRUCTURED_CHECK_RESULT_PATH_ENV = 'FORGE_CHECK_STRUCTURED_RESULT_PATH';
+export const MAX_STRUCTURED_CHECK_FAILURE_DETAILS = 32;
+
+export type StructuredCheckFailureDetailClass = 'source' | 'fixture' | 'infrastructure' | 'interrupted';
+
+export interface StructuredCheckFailureDetail {
+  file: string;
+  failureClass: StructuredCheckFailureDetailClass;
+  failureCode: string;
+  attempts: number;
+  durationMs: number;
+  signal?: string;
+}
+
+export interface StructuredCheckFailureEvidence {
+  schemaVersion: 1;
+  producer: 'test-governance';
+  gate: string;
+  status: 'passed' | 'failed';
+  failures: number;
+  failureClasses: StructuredCheckFailureDetailClass[];
+  failureDetails: StructuredCheckFailureDetail[];
+  failureDetailsTruncated: boolean;
+  contaminated: boolean;
+}
+
+const STRUCTURED_FAILURE_CLASSES = new Set<StructuredCheckFailureDetailClass>(['source', 'fixture', 'infrastructure', 'interrupted']);
+
+export function isStructuredCheckFailureEvidence(value: unknown): value is StructuredCheckFailureEvidence {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as StructuredCheckFailureEvidence;
+  if (candidate.schemaVersion !== 1 || candidate.producer !== 'test-governance') return false;
+  if (typeof candidate.gate !== 'string' || !candidate.gate.trim() || candidate.gate.length > 64) return false;
+  if (candidate.status !== 'passed' && candidate.status !== 'failed') return false;
+  if (!Number.isInteger(candidate.failures) || candidate.failures < 0 || candidate.failures > 1_000_000) return false;
+  if (!Array.isArray(candidate.failureClasses) || candidate.failureClasses.length > STRUCTURED_FAILURE_CLASSES.size) return false;
+  if (candidate.failureClasses.some((entry) => !STRUCTURED_FAILURE_CLASSES.has(entry))) return false;
+  if (new Set(candidate.failureClasses).size !== candidate.failureClasses.length) return false;
+  if (!Array.isArray(candidate.failureDetails) || candidate.failureDetails.length > MAX_STRUCTURED_CHECK_FAILURE_DETAILS) return false;
+  if (typeof candidate.failureDetailsTruncated !== 'boolean' || typeof candidate.contaminated !== 'boolean') return false;
+  for (const detail of candidate.failureDetails) {
+    if (!detail || typeof detail !== 'object' || Array.isArray(detail)) return false;
+    if (typeof detail.file !== 'string' || !detail.file.startsWith('tests/') || detail.file.length > 512) return false;
+    if (!STRUCTURED_FAILURE_CLASSES.has(detail.failureClass)) return false;
+    if (typeof detail.failureCode !== 'string' || !/^TEST_[A-Z0-9_]+$/.test(detail.failureCode) || detail.failureCode.length > 128) return false;
+    if (!Number.isInteger(detail.attempts) || detail.attempts < 1 || detail.attempts > 100) return false;
+    if (!Number.isFinite(detail.durationMs) || detail.durationMs < 0 || detail.durationMs > 24 * 60 * 60_000) return false;
+    if (detail.signal !== undefined && (typeof detail.signal !== 'string' || detail.signal.length > 32)) return false;
+    if (!candidate.failureClasses.includes(detail.failureClass)) return false;
+  }
+  if (candidate.failureDetails.length > candidate.failures) return false;
+  if (candidate.failureDetailsTruncated !== (candidate.failures > candidate.failureDetails.length)) return false;
+  if (candidate.status === 'passed') {
+    return candidate.failures === 0
+      && candidate.failureClasses.length === 0
+      && candidate.failureDetails.length === 0
+      && candidate.failureDetailsTruncated === false
+      && candidate.contaminated === false;
+  }
+  return (candidate.failures > 0 || candidate.contaminated) && candidate.failureClasses.length > 0;
+}
+
 export interface PersistedCheckResultReceipt {
   schemaVersion: 1;
   receiptId: string;
@@ -13,6 +75,7 @@ export interface PersistedCheckResultReceipt {
   status: number;
   timedOut: boolean;
   failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  failureEvidence?: StructuredCheckFailureEvidence;
   validatedRevision?: string;
   executedAt: string;
   originalExecutedAt?: string;
@@ -47,7 +110,9 @@ export function readPersistedCheckResultReceipt(path: string | undefined): Persi
   if (!path || !existsSync(path)) return undefined;
   try {
     const value = JSON.parse(readFileSync(path, 'utf8')) as PersistedCheckResultReceipt;
-    return value?.schemaVersion === 1 && typeof value.receiptId === 'string' && typeof value.cacheKey === 'string' ? value : undefined;
+    if (value?.schemaVersion !== 1 || typeof value.receiptId !== 'string' || typeof value.cacheKey !== 'string') return undefined;
+    if (value.failureEvidence !== undefined && !isStructuredCheckFailureEvidence(value.failureEvidence)) return undefined;
+    return value;
   } catch {
     return undefined;
   }
@@ -62,6 +127,7 @@ export type PersistedCheckTerminalEvidenceState =
 export interface PersistedCheckTerminalEvidence {
   state: PersistedCheckTerminalEvidenceState;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
+  failureEvidence?: StructuredCheckFailureEvidence;
   warning?: string;
   infrastructureReason?: string;
 }
@@ -108,6 +174,7 @@ export function classifyTerminalCheckEvidence(
 export interface LegacyCheckEvidenceLike {
   cacheKey?: string;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
+  failureEvidence?: StructuredCheckFailureEvidence;
 }
 
 export function classifyPersistedCheckTerminalEvidence(
@@ -136,6 +203,10 @@ export function classifyPersistedCheckTerminalEvidence(
     legacyMatches,
   });
   return classified.state === 'matched'
-    ? { ...classified, failureClass: structuredMatches ? structured?.failureClass : legacy?.failureClass }
+    ? {
+      ...classified,
+      failureClass: structuredMatches ? structured?.failureClass : legacy?.failureClass,
+      failureEvidence: structuredMatches ? structured?.failureEvidence : legacy?.failureEvidence,
+    }
     : classified;
 }

package/src/runtime/execution/process-runtime/check-runner-sidecar.ts

@@ -6,17 +6,24 @@ import {
   controllerCheckExecutionIdentity,
   runControllerCheckAsync,
   snapshotControllerCheck,
+  type ControllerCheckSnapshot,
 } from '../../../cli/controller/check-runner';
 import { writePersistedCheckResultReceipt } from './check-result';
+import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from './canary';
 
 interface ParsedArgs {
   repo: string;
+  controllerHome: string;
+  repoId: string;
   checkId: string;
   timeoutMs?: number;
   expectedCheckFingerprint: string;
+  checkSnapshot?: ControllerCheckSnapshot;
   resultReceiptPath?: string;
   cleanupRoot?: string;
   isolatedControllerHome?: string;
+  liveControllerHome: boolean;
+  executionStateFingerprint?: string;
 }
 
 function requiredValue(argv: string[], flag: string): string {
@@ -26,6 +33,20 @@ function requiredValue(argv: string[], flag: string): string {
   return value;
 }
 
+
+function decodeCheckSnapshot(value: string): ControllerCheckSnapshot {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('PERSISTED_CHECK_USAGE: invalid --check-snapshot');
+  }
+  if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
+    throw new Error('PERSISTED_CHECK_USAGE: invalid --check-snapshot');
+  }
+  return decoded as ControllerCheckSnapshot;
+}
+
 function parseArgs(argv: string[]): ParsedArgs {
   const timeoutRaw = argv.includes('--timeout-ms') ? requiredValue(argv, '--timeout-ms') : undefined;
   const timeoutMs = timeoutRaw === undefined ? undefined : Number(timeoutRaw);
@@ -34,29 +55,46 @@ function parseArgs(argv: string[]): ParsedArgs {
   }
   return {
     repo: requiredValue(argv, '--repo'),
+    controllerHome: requiredValue(argv, '--controller-home'),
+    repoId: requiredValue(argv, '--repo-id'),
     checkId: requiredValue(argv, '--check-id'),
     timeoutMs,
     expectedCheckFingerprint: requiredValue(argv, '--expected-check-fingerprint'),
+    checkSnapshot: argv.includes('--check-snapshot') ? decodeCheckSnapshot(requiredValue(argv, '--check-snapshot')) : undefined,
     resultReceiptPath: argv.includes('--result-receipt') ? requiredValue(argv, '--result-receipt') : undefined,
     cleanupRoot: argv.includes('--cleanup-root') ? requiredValue(argv, '--cleanup-root') : undefined,
     isolatedControllerHome: argv.includes('--isolated-controller-home') ? requiredValue(argv, '--isolated-controller-home') : undefined,
+    liveControllerHome: argv.includes('--live-controller-home'),
+    executionStateFingerprint: argv.includes('--execution-state-fingerprint') ? requiredValue(argv, '--execution-state-fingerprint') : undefined,
   };
 }
 
 export async function runPersistedCheckSidecar(argv = process.argv.slice(2)): Promise<number> {
+  if (argv.includes(PROCESS_RUNTIME_RELEASE_CANARY_ARG)) {
+    process.stdout.write('forge check-runner release canary\n');
+    return 0;
+  }
   const args = parseArgs(argv);
   const root = resolve(args.repo);
   try {
-    const snapshot = snapshotControllerCheck(root, args.checkId);
+    // New callers carry the exact definition resolved from canonical repository
+    // authority. The fallback keeps older package releases compatible.
+    const snapshot = args.checkSnapshot ?? snapshotControllerCheck(root, args.checkId);
     const actualFingerprint = createHash('sha256').update(JSON.stringify(snapshot)).digest('hex');
     if (actualFingerprint !== args.expectedCheckFingerprint) {
       throw new Error('CHECK_SNAPSHOT_CHANGED: registered check changed before Process Runtime execution');
     }
-    const identity = controllerCheckExecutionIdentity(root, args.checkId, args.timeoutMs, snapshot);
+    if (args.liveControllerHome && !args.executionStateFingerprint) {
+      throw new Error('LIVE_CHECK_EXECUTION_STATE_REQUIRED');
+    }
+    const identity = controllerCheckExecutionIdentity(root, args.checkId, args.timeoutMs, snapshot, args.executionStateFingerprint);
     const result = await runControllerCheckAsync(root, args.checkId, {
       requestedTimeoutMs: args.timeoutMs,
       snapshot,
-      isolatedControllerHome: args.isolatedControllerHome,
+      storageAuthority: { controllerHome: args.controllerHome, repoId: args.repoId },
+      isolatedControllerHome: args.liveControllerHome ? undefined : args.isolatedControllerHome,
+      liveControllerHome: args.liveControllerHome ? args.controllerHome : undefined,
+      executionStateFingerprint: args.executionStateFingerprint,
     });
     if (args.resultReceiptPath) {
       writePersistedCheckResultReceipt(args.resultReceiptPath, {
@@ -66,6 +104,7 @@ export async function runPersistedCheckSidecar(argv = process.argv.slice(2)): Pr
         status: result.status,
         timedOut: result.timedOut,
         failureClass: result.failureClass,
+        failureEvidence: result.failureEvidence,
         validatedRevision: result.validatedRevision,
         executedAt: result.executedAt,
         originalExecutedAt: result.originalExecutedAt,

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

@@ -0,0 +1,187 @@
+import { cpSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { durableControllerHome, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { findRegisteredRepositoryByCheckoutRoot } from '../../../cli/repositories/registry';
+
+export interface RepositoryCheckStorageAuthority {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface ResolvedRepositoryCheckStorage extends RepositoryCheckStorageAuthority {
+  repoRoot: string;
+  physicalRoot: string;
+  lockRoot: string;
+}
+
+function pathEntryExists(path: string): boolean {
+  try { lstatSync(path); return true; } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return Boolean(error && typeof error === 'object' && 'code' in error
+    && String((error as { code?: unknown }).code ?? '') === 'ENOENT');
+}
+
+function nextLegacyCheckQuarantinePath(storage: ResolvedRepositoryCheckStorage): string {
+  const root = join(dirname(storage.physicalRoot), 'quarantine', 'legacy-checks');
+  const stem = `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+  let index = 0;
+  while (true) {
+    const suffix = index === 0 ? stem : `${stem}-${index}`;
+    const candidate = join(root, suffix);
+    if (!pathEntryExists(candidate)) return candidate;
+    index += 1;
+  }
+}
+
+function moveLegacyCheckDirectory(source: string, target: string): void {
+  try {
+    renameSync(source, target);
+    return;
+  } catch (error) {
+    const code = error && typeof error === 'object' && 'code' in error
+      ? String((error as { code?: unknown }).code ?? '')
+      : '';
+    if (code !== 'EXDEV') throw error;
+  }
+  mkdirSync(target, { recursive: true });
+  try {
+    cpSync(source, target, { recursive: true, force: false, errorOnExist: true });
+    rmSync(source, { recursive: true, force: true });
+  } catch (error) {
+    rmSync(target, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * Retire the pre-Controller-Home check directory only when the repository has
+ * an explicit registry authority. The old bytes are moved into a bounded
+ * Controller-Home quarantine so a stale project-local directory cannot block
+ * the current runner and no legacy evidence is silently discarded. Unknown or
+ * unregistered paths remain fail-closed because their ownership is unproven.
+ */
+function retireRegisteredLegacyCheckStorage(storage: ResolvedRepositoryCheckStorage): void {
+  const repositoryPath = join(storage.repoRoot, '.ai', 'harness', 'checks');
+  if (!pathEntryExists(repositoryPath)) return;
+
+  const registered = findRegisteredRepositoryByCheckoutRoot(storage.repoRoot, storage.controllerHome);
+  if (!registered || registered.repoId !== storage.repoId) {
+    throw new Error(`CHECK_STORAGE_REPOSITORY_PATH_FORBIDDEN: ${repositoryPath}`);
+  }
+
+  let stat;
+  try {
+    stat = lstatSync(repositoryPath);
+  } catch (error) {
+    // Another Runner may have retired the directory after the existence
+    // probe. Treat that interleaving as successful convergence.
+    if (isMissingPathError(error)) return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    let target: string;
+    try {
+      target = realpathSync(repositoryPath);
+    } catch (error) {
+      if (isMissingPathError(error)) return;
+      throw new Error(`CHECK_STORAGE_REPOSITORY_PATH_FORBIDDEN: ${repositoryPath}`);
+    }
+    if (target !== realpathSync(storage.physicalRoot)) {
+      throw new Error(`CHECK_STORAGE_REPOSITORY_PATH_FORBIDDEN: ${repositoryPath}`);
+    }
+    // A retired compatibility link has no independent authority. Remove only
+    // the link; the Controller-Home target remains untouched.
+    try {
+      unlinkSync(repositoryPath);
+    } catch (error) {
+      if (!isMissingPathError(error)) throw error;
+    }
+    return;
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`CHECK_STORAGE_REPOSITORY_PATH_FORBIDDEN: ${repositoryPath}`);
+  }
+
+  let entries: string[];
+  try {
+    entries = readdirSync(repositoryPath);
+  } catch (error) {
+    if (isMissingPathError(error)) return;
+    throw error;
+  }
+  if (entries.length === 0) {
+    try {
+      rmSync(repositoryPath, { recursive: true, force: true });
+    } catch (error) {
+      if (!isMissingPathError(error)) throw error;
+    }
+    return;
+  }
+
+  const quarantine = nextLegacyCheckQuarantinePath(storage);
+  mkdirSync(dirname(quarantine), { recursive: true });
+  try {
+    moveLegacyCheckDirectory(repositoryPath, quarantine);
+  } catch (error) {
+    // A concurrent retire may have won the rename race. Do not turn a
+    // converged Controller-Home state into a spurious check failure.
+    if (isMissingPathError(error)) return;
+    throw error;
+  }
+}
+
+function resolveAuthority(repoRoot: string, explicit?: RepositoryCheckStorageAuthority): RepositoryCheckStorageAuthority {
+  const root = resolve(repoRoot);
+  if (explicit) {
+    const controllerHome = durableControllerHome(explicit.controllerHome);
+    const repoId = explicit.repoId.trim();
+    if (!repoId) throw new Error('CHECK_STORAGE_REPOSITORY_ID_REQUIRED');
+    const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+    if (registered && registered.repoId !== repoId) {
+      throw new Error(`CHECK_STORAGE_REPOSITORY_ID_MISMATCH: expected ${registered.repoId}, received ${repoId}`);
+    }
+    return { controllerHome, repoId };
+  }
+
+  const controllerHome = durableControllerHome();
+  const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+  if (!registered) throw new Error(`CHECK_STORAGE_REPOSITORY_AUTHORITY_REQUIRED: ${root}`);
+  return { controllerHome, repoId: registered.repoId };
+}
+
+/**
+ * Check/cache state is Controller-Home-owned. New execution never creates a
+ * repository-local `.ai/harness/checks` path or compatibility link. Registered
+ * repositories may retire old machine state into Controller-Home quarantine;
+ * unknown paths remain rejected rather than adopted as a second authority.
+ */
+export function resolveRepositoryCheckStorage(
+  repoRoot: string,
+  explicit?: RepositoryCheckStorageAuthority,
+): ResolvedRepositoryCheckStorage {
+  const root = resolve(repoRoot);
+  const authority = resolveAuthority(root, explicit);
+  const physicalRoot = join(repositoryControllerRoot(authority.controllerHome, authority.repoId), 'checks');
+  return {
+    ...authority,
+    repoRoot: root,
+    physicalRoot,
+    lockRoot: join(physicalRoot, 'locks'),
+  };
+}
+
+export function ensureRepositoryCheckStorage(
+  repoRoot: string,
+  explicit?: RepositoryCheckStorageAuthority,
+): ResolvedRepositoryCheckStorage {
+  const storage = resolveRepositoryCheckStorage(repoRoot, explicit);
+  mkdirSync(storage.physicalRoot, { recursive: true });
+  retireRegisteredLegacyCheckStorage(storage);
+  mkdirSync(storage.lockRoot, { recursive: true });
+  return storage;
+}