@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -3,6 +3,69 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { dirname, join } from 'path';
 import { processLogDir } from './store';
 import type { ManagedProcessRecord } from './types';
+import type { ProcessCheckCompletionReceipt } from './check-receipt';
+
+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;
@@ -13,6 +76,7 @@ export interface PersistedCheckResultReceipt {
   status: number;
   timedOut: boolean;
   failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  failureEvidence?: StructuredCheckFailureEvidence;
   validatedRevision?: string;
   executedAt: string;
   originalExecutedAt?: string;
@@ -47,7 +111,19 @@ 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.checkId !== 'string'
+      || typeof value.cacheKey !== 'string'
+      || typeof value.ok !== 'boolean'
+      || typeof value.status !== 'number'
+      || typeof value.timedOut !== 'boolean'
+      || typeof value.executedAt !== 'string'
+      || (value.failureClass !== undefined && value.failureClass !== 'acceptance_failure' && value.failureClass !== 'infrastructure_failure')
+    ) return undefined;
+    if (value.failureEvidence !== undefined && !isStructuredCheckFailureEvidence(value.failureEvidence)) return undefined;
+    return value;
   } catch {
     return undefined;
   }
@@ -62,6 +138,10 @@ export type PersistedCheckTerminalEvidenceState =
 export interface PersistedCheckTerminalEvidence {
   state: PersistedCheckTerminalEvidenceState;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
+  failureEvidence?: StructuredCheckFailureEvidence;
+  semanticOk?: boolean;
+  semanticStatus?: number;
+  semanticTimedOut?: boolean;
   warning?: string;
   infrastructureReason?: string;
 }
@@ -107,7 +187,11 @@ export function classifyTerminalCheckEvidence(
  */
 export interface LegacyCheckEvidenceLike {
   cacheKey?: string;
+  ok?: boolean;
+  status?: number;
+  timedOut?: boolean;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
+  failureEvidence?: StructuredCheckFailureEvidence;
 }
 
 export function classifyPersistedCheckTerminalEvidence(
@@ -136,6 +220,97 @@ 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,
+      semanticOk: structuredMatches ? structured?.ok : legacy?.ok,
+      semanticStatus: structuredMatches ? structured?.status : legacy?.status,
+      semanticTimedOut: structuredMatches ? structured?.timedOut : legacy?.timedOut,
+    }
     : classified;
 }
+
+export type TerminalCheckVerificationOutcome = 'valid_pass' | 'valid_fail' | 'infrastructure_failure';
+
+export interface TerminalCheckVerificationProjection {
+  outcome: TerminalCheckVerificationOutcome;
+  failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  isAcceptanceFailure: boolean;
+  isInfrastructureIssue: boolean;
+  boundedStatus: 'pass' | 'fail' | 'infrastructure_failure';
+  evidence: PersistedCheckTerminalEvidence;
+  infrastructureReason?: string;
+}
+
+/**
+ * Canonical Failure Contract projection from one exact terminal Check Process
+ * plus its semantic Check-result evidence into Work verification truth.
+ * Process exit state is necessary evidence, but never acceptance authority by
+ * itself. Missing, mismatched, interrupted, infrastructure, or contradictory
+ * evidence fails closed as infrastructure_failure.
+ */
+export function projectTerminalCheckVerification(
+  record: ManagedProcessRecord,
+  expectedCheckId: string,
+  receipt: ProcessCheckCompletionReceipt,
+  options: { legacyEvidence?: LegacyCheckEvidenceLike } = {},
+): TerminalCheckVerificationProjection {
+  const evidence = classifyPersistedCheckTerminalEvidence(record, expectedCheckId, options);
+  const semanticContradiction = evidence.state === 'matched' && Boolean(
+    (evidence.semanticOk !== undefined && evidence.semanticOk !== receipt.ok)
+    || (evidence.semanticTimedOut !== undefined && evidence.semanticTimedOut !== receipt.timedOut)
+    || (evidence.semanticOk === true && evidence.semanticStatus !== undefined && evidence.semanticStatus !== 0)
+    || (evidence.semanticOk === false && evidence.semanticStatus === 0)
+    || (receipt.ok && evidence.failureClass !== undefined)
+    || (evidence.semanticOk === true && evidence.failureClass !== undefined)
+    || (!receipt.ok && evidence.failureClass === undefined)
+    || (evidence.semanticOk === false && evidence.failureClass === undefined)
+  );
+  const infrastructureReason = evidence.infrastructureReason
+    ?? (semanticContradiction ? 'terminal Check Process and semantic result evidence contradict each other' : undefined);
+  const infrastructure = receipt.timedOut
+    || receipt.cancelled
+    || evidence.state !== 'matched'
+    || semanticContradiction
+    || evidence.failureClass === 'infrastructure_failure';
+  if (infrastructure) {
+    return {
+      outcome: 'infrastructure_failure',
+      failureClass: 'infrastructure_failure',
+      isAcceptanceFailure: false,
+      isInfrastructureIssue: true,
+      boundedStatus: 'infrastructure_failure',
+      evidence,
+      ...(infrastructureReason ? { infrastructureReason } : {}),
+    };
+  }
+  if (receipt.ok) {
+    return {
+      outcome: 'valid_pass',
+      isAcceptanceFailure: false,
+      isInfrastructureIssue: false,
+      boundedStatus: 'pass',
+      evidence,
+    };
+  }
+  if (evidence.failureClass === 'acceptance_failure') {
+    return {
+      outcome: 'valid_fail',
+      failureClass: 'acceptance_failure',
+      isAcceptanceFailure: true,
+      isInfrastructureIssue: false,
+      boundedStatus: 'fail',
+      evidence,
+    };
+  }
+  return {
+    outcome: 'infrastructure_failure',
+    failureClass: 'infrastructure_failure',
+    isAcceptanceFailure: false,
+    isInfrastructureIssue: true,
+    boundedStatus: 'infrastructure_failure',
+    evidence,
+    infrastructureReason: 'terminal Check failure lacks explicit acceptance-failure evidence',
+  };
+}

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

@@ -2,21 +2,23 @@
 import { createHash } from 'crypto';
 import { rmSync } from 'fs';
 import { resolve } from 'path';
-import {
-  controllerCheckExecutionIdentity,
-  runControllerCheckAsync,
-  snapshotControllerCheck,
-} from '../../../cli/controller/check-runner';
-import { writePersistedCheckResultReceipt } from './check-result';
+import type { ControllerCheckSnapshot } from '../../../cli/controller/check-runner';
+import { materializeManagedWorkspaceDependencies } from '../managed-workspace';
+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 +28,19 @@ 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 +49,62 @@ 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);
+    // A Work verification snapshot is disposable execution state. When exact
+    // canonical dependency reuse was unavailable during snapshot construction,
+    // establish the candidate's frozen dependency closure inside this Check
+    // Process before loading the candidate Check Runner module graph.
+    if (args.cleanupRoot && (!args.checkSnapshot || args.checkSnapshot.source === 'package-script')) {
+      materializeManagedWorkspaceDependencies(root);
+    }
+
+    const [
+      { controllerCheckExecutionIdentity, runControllerCheckAsync, snapshotControllerCheck },
+      { writePersistedCheckResultReceipt },
+    ] = await Promise.all([
+      import('../../../cli/controller/check-runner'),
+      import('./check-result'),
+    ]);
+
+    // 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 +114,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;
+}