@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/control-plane/release-retention.ts

@@ -7,6 +7,8 @@ import {
   rmSync,
 } from 'fs';
 import { basename, dirname, join, relative, resolve } from 'path';
+import { measureReclaimablePath } from './lifecycle-retention-metrics';
+import { inspectKnownGoodRecoveryBundle, type KnownGoodReleaseIdentity } from '../root/known-good-recovery';
 
 const DEFAULT_RELEASE_RETENTION_GRACE_MS = 30 * 60_000;
 const DEFAULT_STAGING_RETENTION_GRACE_MS = 6 * 60 * 60_000;
@@ -23,6 +25,11 @@ export interface ReleaseRetentionReport {
   eligible: number;
   attempted: number;
   removedPaths: string[];
+  removedBackupPaths: string[];
+  reclaimedBytes: number;
+  reclaimedBackupBytes: number;
+  unknownReclaimedByteCount: number;
+  unknownReclaimedBackupByteCount: number;
   retained: number;
   skipped: number;
   skippedByReason: Record<string, number>;
@@ -42,6 +49,14 @@ interface RuntimeProtection {
   backupAuthoritySafe: boolean;
 }
 
+interface RuntimeReleasePublicationLease {
+  schemaVersion: 1;
+  pid: number;
+  operationId: string;
+  candidateReleasePath: string;
+  backupPath?: string;
+}
+
 interface LinkedReleaseProtection {
   releasesRoot: string;
   releasePaths: Set<string>;
@@ -56,7 +71,16 @@ function canonical(path: string): string {
 }
 
 function directChild(root: string, path: string): boolean {
-  return dirname(canonical(path)) === canonical(root);
+  // Resolve the parent rather than the child: a reclaimed path may no longer
+  // exist, while its managed parent still does (and may itself be a symlink).
+  // An existing child must not itself be a symlink; otherwise a lexical child
+  // under Controller Home could retain or delete an external target.
+  if (canonical(dirname(path)) !== canonical(root)) return false;
+  try {
+    return !lstatSync(path).isSymbolicLink();
+  } catch {
+    return true;
+  }
 }
 
 function entryExists(path: string): boolean {
@@ -127,39 +151,83 @@ function loadPackageConnectorReleaseProtection(controllerHome: string, releasesR
   return canonical(releaseRoot);
 }
 
-function loadRecoveryKnownGoodReleaseProtection(controllerHome: string, releasesRoot: string): Set<string> {
-  const knownGoodPath = join(controllerHome, 'recovery', 'state', 'known-good.json');
+function loadRecoveryKnownGoodProtection(
+  controllerHome: string,
+  releasesRoot: string,
+  rollbackReleasePaths: ReadonlySet<string>,
+): Set<string> {
   const protectedPaths = new Set<string>();
+  const knownGoodPath = join(controllerHome, 'recovery', 'state', 'known-good.json');
   if (!existsSync(knownGoodPath)) return protectedPaths;
   const parsed = JSON.parse(readFileSync(knownGoodPath, 'utf8')) as Record<string, unknown>;
-  if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.releases)) {
+  // Schema v1 was metadata-only evidence. It deliberately has no retention
+  // authority: only v2 entries pass the same release + DB + service-contract
+  // recoverability check that Recovery uses before attesting known-good.
+  if (parsed.schemaVersion === 1) return protectedPaths;
+  if (parsed.schemaVersion !== 2 || !Array.isArray(parsed.releases)) {
     throw new Error('standalone recovery known-good authority is invalid');
   }
   for (const raw of parsed.releases) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('standalone recovery known-good release record is invalid');
-    const record = raw as Record<string, unknown>;
-    const releaseId = typeof record.revision === 'string' ? record.revision.trim() : '';
-    const manifestPathValue = typeof record.path === 'string' ? record.path.trim() : '';
-    if (!releaseId || !manifestPathValue) throw new Error('standalone recovery known-good release identity is incomplete');
-    const manifestPath = resolve(manifestPathValue);
-    const releaseRoot = dirname(manifestPath);
+    const entry = raw as Record<string, unknown>;
+    const manifestPath = typeof entry.path === 'string' ? entry.path.trim() : '';
+    const revision = typeof entry.revision === 'string' ? entry.revision.trim() : '';
+    const releaseRoot = manifestPath ? dirname(resolve(manifestPath)) : '';
     if (
-      basename(manifestPath) !== 'manifest.json'
-      || basename(releaseRoot) !== releaseId
+      !manifestPath
+      || !revision
+      || basename(manifestPath) !== 'manifest.json'
+      || basename(releaseRoot) !== revision
       || !directChild(releasesRoot, releaseRoot)
-    ) {
+    ) throw new Error('standalone recovery known-good release is outside runtime releases');
+    // Historical records are not protection. Do not inspect them after their
+    // release tree has been reclaimed, or one old record would block cleanup
+    // of every later candidate in the same pass.
+    if (!rollbackReleasePaths.has(canonical(releaseRoot))) continue;
+    let inspected;
+    try {
+      inspected = inspectKnownGoodRecoveryBundle(controllerHome, raw as KnownGoodReleaseIdentity);
+    } catch (error) {
+      throw new Error(`standalone recovery known-good bundle is not recoverable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const inspectedReleaseRoot = canonical(dirname(inspected.releaseRoot));
+    if (inspectedReleaseRoot !== canonical(releasesRoot)) {
       throw new Error('standalone recovery known-good release is outside runtime releases');
     }
-    // Known-good history is append-only recovery evidence. A historical record
-    // may legitimately outlive the retained release directory after a bounded
-    // cleanup pass. Missing historical artifacts therefore protect nothing and
-    // must not disable retention for the remaining authoritative releases.
-    if (!existsSync(manifestPath) || !existsSync(releaseRoot)) continue;
-    protectedPaths.add(canonical(releaseRoot));
+    // Historical attestations are evidence, not rollback authority. Recovery
+    // can only target releases currently named by the committed Runtime.
+    protectedPaths.add(canonical(inspected.releaseRoot));
   }
   return protectedPaths;
 }
 
+function loadPinnedRuntimeReleaseProtection(controllerHome: string, releasesRoot: string): string | undefined {
+  const pinPath = join(controllerHome, 'recovery', 'state', 'runtime-pin.json');
+  if (!existsSync(pinPath)) return undefined;
+  let parsed: Record<string, unknown>;
+  try { parsed = JSON.parse(readFileSync(pinPath, 'utf8')) as Record<string, unknown>; }
+  catch (error) { throw new Error(`runtime pin authority is invalid: ${error instanceof Error ? error.message : String(error)}`); }
+  const release = parsed.release;
+  if (parsed.schemaVersion !== 1 || !release || typeof release !== 'object' || Array.isArray(release)) {
+    throw new Error('runtime pin authority is invalid');
+  }
+  const record = release as Record<string, unknown>;
+  const releaseId = typeof record.revision === 'string' ? record.revision.trim() : '';
+  const manifestPathValue = typeof record.path === 'string' ? record.path.trim() : '';
+  if (!releaseId || !manifestPathValue) throw new Error('runtime pin release identity is incomplete');
+  const manifestPath = resolve(manifestPathValue);
+  const releaseRoot = dirname(manifestPath);
+  if (
+    basename(manifestPath) !== 'manifest.json'
+    || basename(releaseRoot) !== releaseId
+    || !directChild(releasesRoot, releaseRoot)
+    || !existsSync(releaseRoot)
+  ) {
+    throw new Error('runtime pin release is outside runtime release authority or missing');
+  }
+  return canonical(releaseRoot);
+}
+
 function loadRuntimeProtection(controllerHome: string): RuntimeProtection | undefined {
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   if (!existsSync(releasesRoot)) return undefined;
@@ -168,11 +236,12 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   if (!existsSync(authorityPath)) throw new Error('runtime release authority is missing');
 
   const parsed = JSON.parse(readFileSync(authorityPath, 'utf8')) as Record<string, unknown>;
-  if (parsed.schemaVersion !== 1 || parsed.status !== 'committed') {
-    throw new Error('runtime release authority is not committed schemaVersion=1');
+  if (parsed.schemaVersion !== 2 || parsed.status !== 'committed') {
+    throw new Error('runtime release authority is not committed schemaVersion=2');
   }
 
   const releasePaths = new Set<string>();
+  const backupPaths = new Set<string>();
   releasePaths.add(releasePathFromAuthorityRecord(releasesRoot, parsed.active, 'active'));
   const previous = parsed.previous;
   if (previous !== undefined) {
@@ -180,11 +249,54 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   }
   const connectorRelease = loadPackageConnectorReleaseProtection(controllerHome, releasesRoot);
   if (connectorRelease) releasePaths.add(connectorRelease);
-  for (const knownGoodRelease of loadRecoveryKnownGoodReleaseProtection(controllerHome, releasesRoot)) {
+  const pinnedRelease = loadPinnedRuntimeReleaseProtection(controllerHome, releasesRoot);
+  if (pinnedRelease) releasePaths.add(pinnedRelease);
+  // Only known-good entries that are also named by the committed Runtime
+  // authority are rollback protection. Older attestations are historical
+  // evidence and must not pin immutable release trees.
+  for (const knownGoodRelease of loadRecoveryKnownGoodProtection(controllerHome, releasesRoot, releasePaths)) {
     releasePaths.add(knownGoodRelease);
   }
 
-  const backupPaths = new Set<string>();
+  // A publication writes the rollback backup before it atomically updates
+  // authority.json. Keep both the candidate tree and backup leased for the
+  // lifetime of that publication, so periodic cleanup cannot win the race.
+  const publicationLeasesRoot = join(releasesRoot, '.publication-leases');
+  if (existsSync(publicationLeasesRoot)) {
+    for (const entry of readdirSync(publicationLeasesRoot, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      const leasePath = join(publicationLeasesRoot, entry.name);
+      let lease: RuntimeReleasePublicationLease;
+      try {
+        lease = JSON.parse(readFileSync(leasePath, 'utf8')) as RuntimeReleasePublicationLease;
+      } catch (error) {
+        throw new Error(`runtime release publication lease is invalid: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      if (
+        lease.schemaVersion !== 1
+        || !Number.isInteger(lease.pid)
+        || lease.pid <= 0
+        || typeof lease.operationId !== 'string'
+        || !lease.operationId.trim()
+        || typeof lease.candidateReleasePath !== 'string'
+        || !directChild(releasesRoot, resolve(lease.candidateReleasePath))
+      ) throw new Error('runtime release publication lease is invalid');
+      let alive = true;
+      try { process.kill(lease.pid, 0); } catch (error) {
+        alive = (error as NodeJS.ErrnoException).code === 'EPERM';
+      }
+      if (!alive) {
+        rmSync(leasePath, { force: true });
+        continue;
+      }
+      releasePaths.add(canonical(lease.candidateReleasePath));
+      if (lease.backupPath !== undefined) {
+        if (!directChild(backupsRoot, resolve(lease.backupPath))) throw new Error('runtime release publication lease backup is invalid');
+        backupPaths.add(canonical(lease.backupPath));
+      }
+    }
+  }
+
   let backupAuthoritySafe = true;
   if (previous && typeof previous === 'object' && !Array.isArray(previous)) {
     const databaseBackup = (previous as Record<string, unknown>).databaseBackup;
@@ -249,6 +361,7 @@ function removeCandidate(
   path: string,
   recursive: boolean,
   state: MutableRetentionState,
+  lifecycleClass: 'release_artifact' | 'recovery_backup' = 'release_artifact',
 ): void {
   state.eligible += 1;
   if (state.remainingRemovals <= 0) {
@@ -260,9 +373,19 @@ function removeCandidate(
 
   state.remainingRemovals -= 1;
   state.attempted += 1;
+  const measurement = measureReclaimablePath(path);
   try {
     rmSync(path, { recursive, force: true });
-    state.removedPaths.push(relativeHomePath(controllerHome, path));
+    const relativePath = relativeHomePath(controllerHome, path);
+    state.removedPaths.push(relativePath);
+    if (lifecycleClass === 'recovery_backup') state.removedBackupPaths.push(relativePath);
+    if (measurement.complete) {
+      state.reclaimedBytes += measurement.bytes;
+      if (lifecycleClass === 'recovery_backup') state.reclaimedBackupBytes += measurement.bytes;
+    } else {
+      state.unknownReclaimedByteCount += 1;
+      if (lifecycleClass === 'recovery_backup') state.unknownReclaimedBackupByteCount += 1;
+    }
   } catch (error) {
     state.errors.push(errorText(`release retention ${relativeHomePath(controllerHome, path)}`, error));
   }
@@ -286,7 +409,7 @@ function scanRuntimeReleases(
   if (!protection) return;
 
   for (const entry of readdirSync(protection.releasesRoot, { withFileTypes: true })) {
-    if (entry.name === 'backups' || entry.name === 'authority.json') continue;
+    if (entry.name === 'backups' || entry.name === 'authority.json' || entry.name === '.publication-leases') continue;
     const path = join(protection.releasesRoot, entry.name);
     state.inspected += 1;
 
@@ -393,7 +516,7 @@ function scanRuntimeReleases(
       continue;
     }
 
-    removeCandidate(controllerHome, path, false, state);
+    removeCandidate(controllerHome, path, false, state, 'recovery_backup');
   }
 }
 
@@ -486,6 +609,11 @@ export function cleanupControllerReleaseHistory(
     eligible: 0,
     attempted: 0,
     removedPaths: [],
+    removedBackupPaths: [],
+    reclaimedBytes: 0,
+    reclaimedBackupBytes: 0,
+    unknownReclaimedByteCount: 0,
+    unknownReclaimedBackupByteCount: 0,
     retained: 0,
     skipped: 0,
     skippedByReason: {},

package/src/runtime/control-plane/repository-namespace-retention.ts

@@ -0,0 +1,208 @@
+import { existsSync, lstatSync, rmSync } from 'fs';
+import { join, relative } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { listRepositories } from '../../cli/repositories/registry';
+import { listActiveExecutionJobs } from '../execution/jobs/store';
+import { listActiveProcessIds } from '../execution/process-runtime/store';
+import { listActiveLeases } from '../resources/leases/store';
+import { isTerminalSemanticWorkState, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { listControlPlaneRecords } from './persistence/sqlite-store';
+import { measureReclaimablePath } from './lifecycle-retention-metrics';
+
+const DEFAULT_RETIRED_REPOSITORY_GRACE_MS = 7 * 24 * 60 * 60_000;
+const DEFAULT_SCAN_BUDGET = 512;
+const DEFAULT_REMOVAL_BUDGET = 16;
+const BROWSER_SESSION_SCAN_LIMIT = 5_000;
+
+/**
+ * Only Forge-owned, rebuildable/disposable repository namespace children belong
+ * here. Semantic/audit/migration authorities are deliberately absent.
+ */
+export const RETIRED_REPOSITORY_DISPOSABLE_CHILDREN = Object.freeze([
+  'artifacts',
+  'browser',
+  'edit-sessions',
+  'ephemeral-issues',
+  'hook-state',
+  'indexes',
+  'leases',
+  'local-bridge',
+  'processes',
+  'projections',
+  'results',
+  'verification-snapshots',
+  'worktrees',
+] as const);
+
+interface BrowserSessionRetentionEntry {
+  status?: string;
+  repositoryIds?: unknown;
+}
+
+export interface RetiredRepositoryNamespaceRetentionOptions {
+  nowMs?: number;
+  graceMs?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+}
+
+export interface RetiredRepositoryNamespaceRetentionReport {
+  policyVersion: 'repository-namespace-retention-v1';
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  removedPaths: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  retained: number;
+  skippedByReason: Record<string, number>;
+  errors: string[];
+  budgetExhausted: boolean;
+}
+
+function increment(target: Record<string, number>, reason: string, count = 1): void {
+  target[reason] = (target[reason] ?? 0) + count;
+}
+
+function browserSessionBlocksRetirement(controllerHome: string, repoId: string): { blocked: boolean; uncertain: boolean } {
+  const records = listControlPlaneRecords<BrowserSessionRetentionEntry>(controllerHome, {
+    namespace: 'browser_session',
+    scope: 'controller',
+    limit: BROWSER_SESSION_SCAN_LIMIT,
+  });
+  if (records.length >= BROWSER_SESSION_SCAN_LIMIT) return { blocked: false, uncertain: true };
+  return {
+    blocked: records.some((record) => {
+      if (record.value?.status !== 'active' || !Array.isArray(record.value?.repositoryIds)) return false;
+      return record.value.repositoryIds.some((value) => String(value) === repoId);
+    }),
+    uncertain: false,
+  };
+}
+
+function activeAuthorityBlockers(controllerHome: string, repoId: string): string[] {
+  const blockers: string[] = [];
+  if (listActiveExecutionJobs(controllerHome, repoId).length > 0) blockers.push('active_execution_job');
+  if (listActiveProcessIds(controllerHome, repoId).length > 0) blockers.push('active_process');
+  if (listActiveLeases(controllerHome, repoId).length > 0) blockers.push('active_lease');
+
+  const workStore = readWorkContractStore({ controllerHome, repoId });
+  for (const work of workStore.contracts) {
+    if (!isTerminalSemanticWorkState(work.semanticState)) {
+      blockers.push('active_work');
+      break;
+    }
+    if (work.phaseEvidence?.cleanup?.state !== 'satisfied') {
+      blockers.push('work_cleanup_incomplete');
+      break;
+    }
+  }
+
+  const browser = browserSessionBlocksRetirement(controllerHome, repoId);
+  if (browser.blocked) blockers.push('active_browser_session');
+  if (browser.uncertain) blockers.push('browser_session_scan_truncated');
+  return blockers;
+}
+
+export function cleanupRetiredRepositoryNamespaces(
+  controllerHome: string,
+  options: RetiredRepositoryNamespaceRetentionOptions = {},
+): RetiredRepositoryNamespaceRetentionReport {
+  const nowMs = options.nowMs ?? Date.now();
+  const graceMs = Math.max(60_000, Math.floor(options.graceMs ?? DEFAULT_RETIRED_REPOSITORY_GRACE_MS));
+  let scanRemaining = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_SCAN_BUDGET));
+  let removalRemaining = Math.max(0, Math.floor(options.maxRemovals ?? DEFAULT_REMOVAL_BUDGET));
+  const report: RetiredRepositoryNamespaceRetentionReport = {
+    policyVersion: 'repository-namespace-retention-v1',
+    inspected: 0,
+    eligible: 0,
+    attempted: 0,
+    removedPaths: [],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    retained: 0,
+    skippedByReason: {},
+    errors: [],
+    budgetExhausted: false,
+  };
+
+  const removed = listRepositories(controllerHome, { includeRemoved: true })
+    .filter((repository) => Boolean(repository.removedAt))
+    .sort((left, right) => String(left.removedAt).localeCompare(String(right.removedAt)) || left.repoId.localeCompare(right.repoId));
+
+  for (const repository of removed) {
+    if (scanRemaining <= 0) {
+      report.budgetExhausted = true;
+      increment(report.skippedByReason, 'scan_budget_exhausted');
+      break;
+    }
+    scanRemaining -= 1;
+    report.inspected += 1;
+    const removedAtMs = Date.parse(String(repository.removedAt));
+    if (!Number.isFinite(removedAtMs) || nowMs - removedAtMs < graceMs) {
+      report.retained += 1;
+      increment(report.skippedByReason, 'retention_grace');
+      continue;
+    }
+
+    let blockers: string[];
+    try {
+      blockers = activeAuthorityBlockers(controllerHome, repository.repoId);
+    } catch (error) {
+      report.retained += 1;
+      increment(report.skippedByReason, 'authority_state_unavailable');
+      report.errors.push(`${repository.repoId}:authority_state_unavailable:${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    if (blockers.length > 0) {
+      report.retained += 1;
+      for (const blocker of blockers) increment(report.skippedByReason, blocker);
+      continue;
+    }
+
+    const root = repositoryControllerRoot(controllerHome, repository.repoId);
+    for (const child of RETIRED_REPOSITORY_DISPOSABLE_CHILDREN) {
+      if (scanRemaining <= 0) {
+        report.budgetExhausted = true;
+        increment(report.skippedByReason, 'scan_budget_exhausted');
+        break;
+      }
+      scanRemaining -= 1;
+      report.inspected += 1;
+      const path = join(root, child);
+      if (!existsSync(path)) continue;
+      let stat;
+      try { stat = lstatSync(path); } catch (error) {
+        report.retained += 1;
+        increment(report.skippedByReason, 'ownership_unproven');
+        report.errors.push(`${repository.repoId}:${child}:${error instanceof Error ? error.message : String(error)}`);
+        continue;
+      }
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        report.retained += 1;
+        increment(report.skippedByReason, 'ownership_unproven');
+        continue;
+      }
+      report.eligible += 1;
+      if (removalRemaining <= 0) {
+        report.retained += 1;
+        report.budgetExhausted = true;
+        increment(report.skippedByReason, 'cleanup_budget_exhausted');
+        continue;
+      }
+      report.attempted += 1;
+      const measurement = measureReclaimablePath(path);
+      try {
+        rmSync(path, { recursive: true, force: true });
+        removalRemaining -= 1;
+        report.removedPaths.push(relative(controllerHome, path).replace(/\\/g, '/'));
+        if (measurement.complete) report.reclaimedBytes += measurement.bytes;
+        else report.unknownReclaimedByteCount += 1;
+      } catch (error) {
+        report.retained += 1;
+        report.errors.push(`${repository.repoId}:${child}:${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  return report;
+}