@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/control-plane/persistence/workflow-content-store.ts

@@ -0,0 +1,98 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve, sep } from 'path';
+import {
+  materializeWorkflowAsset,
+  validateWorkflowAsset,
+  type WorkflowAssetDefinition,
+  type WorkflowAssetDraft,
+} from '../../../../packages/workflow-runtime/api/index';
+import { ensureControllerWorkflowContentRoot } from '../../../cli/repositories/controller-home';
+
+export interface ProjectWorkflowAssetContract {
+  schemaVersion: 1;
+  projectId: string;
+  projectRoot: string;
+  /** Project-root-relative human content directory. */
+  workflowAssetDirectory: string;
+}
+
+export type WorkflowAssetContentLocation =
+  | { kind: 'controller'; controllerHome: string }
+  | { kind: 'project'; contract: ProjectWorkflowAssetContract };
+
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/;
+
+function safeSegment(value: string, label: string): string {
+  if (!SAFE_SEGMENT.test(value)) throw new Error(`WORKFLOW_CONTENT_${label.toUpperCase()}_INVALID: ${value}`);
+  return value;
+}
+
+function projectContentRoot(contract: ProjectWorkflowAssetContract): string {
+  if (contract.schemaVersion !== 1 || !SAFE_SEGMENT.test(contract.projectId)) {
+    throw new Error('WORKFLOW_PROJECT_CONTRACT_INVALID');
+  }
+  const projectRoot = resolve(contract.projectRoot);
+  if (!contract.workflowAssetDirectory.trim()) throw new Error('WORKFLOW_PROJECT_ASSET_DIRECTORY_REQUIRED');
+  const contentRoot = resolve(projectRoot, contract.workflowAssetDirectory);
+  const rel = relative(projectRoot, contentRoot);
+  if (!rel || rel === '.' || rel.startsWith(`..${sep}`) || rel === '..') {
+    throw new Error('WORKFLOW_PROJECT_ASSET_DIRECTORY_OUTSIDE_PROJECT');
+  }
+  const normalized = rel.split(sep).join('/');
+  if (normalized === '.forge' || normalized.startsWith('.forge/')
+    || normalized === '_ops' || normalized.startsWith('_ops/')
+    || normalized === '.ai/harness' || normalized.startsWith('.ai/harness/')) {
+    throw new Error('WORKFLOW_PROJECT_ASSET_DIRECTORY_HIDDEN_RUNTIME_STATE_FORBIDDEN');
+  }
+  return contentRoot;
+}
+
+export function workflowAssetContentRoot(location: WorkflowAssetContentLocation): string {
+  return location.kind === 'controller'
+    ? ensureControllerWorkflowContentRoot(location.controllerHome)
+    : projectContentRoot(location.contract);
+}
+
+export function workflowAssetContentPath(
+  location: WorkflowAssetContentLocation,
+  workflowId: string,
+  version: string,
+): string {
+  return join(workflowAssetContentRoot(location), safeSegment(workflowId, 'workflow_id'), safeSegment(version, 'version'), 'workflow.json');
+}
+
+function writeAtomically(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(temporary, content, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    try { rmSync(temporary, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+export function writeWorkflowAssetContent(
+  location: WorkflowAssetContentLocation,
+  draft: WorkflowAssetDraft,
+): { asset: WorkflowAssetDefinition; path: string } {
+  const asset = materializeWorkflowAsset(draft);
+  const path = workflowAssetContentPath(location, asset.workflowId, asset.version);
+  writeAtomically(path, `${JSON.stringify(asset, null, 2)}\n`);
+  return { asset, path };
+}
+
+export function readWorkflowAssetContent(
+  location: WorkflowAssetContentLocation,
+  workflowId: string,
+  version: string,
+): { asset: WorkflowAssetDefinition; path: string } {
+  const path = workflowAssetContentPath(location, workflowId, version);
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as WorkflowAssetDefinition;
+  return { asset: validateWorkflowAsset(parsed), path };
+}
+
+export function readWorkflowAssetContentFile(path: string): WorkflowAssetDefinition {
+  const parsed = JSON.parse(readFileSync(resolve(path), 'utf8')) as WorkflowAssetDefinition;
+  return validateWorkflowAsset(parsed);
+}

package/src/runtime/control-plane/persistence/workflow-registry-store.ts

@@ -0,0 +1,186 @@
+import {
+  sameWorkflowContentIdentity,
+  workflowContentIdentity,
+  type WorkflowAssetDefinition,
+  type WorkflowContentIdentity,
+} from '../../../../packages/workflow-runtime/api/index';
+import {
+  listControlPlaneRecords,
+  readControlPlaneRecord,
+  writeControlPlaneRecord,
+  type ControlPlaneRecord,
+} from './sqlite-store';
+
+export const WORKFLOW_REGISTRY_NAMESPACE = 'workflow_registry';
+const SCHEMA_VERSION = 1 as const;
+
+export type WorkflowRegistryScope =
+  | { kind: 'controller' }
+  | { kind: 'project'; projectId: string };
+
+export interface WorkflowCapabilityBinding {
+  capabilityId: string;
+  providerId?: string;
+  integrationId?: string;
+  /** Concrete existing typed action target. Workflow Runtime does not own plugin authorization. */
+  pluginId?: string;
+  actionId?: string;
+}
+
+export interface WorkflowRegistryEntry extends WorkflowContentIdentity {
+  schemaVersion: typeof SCHEMA_VERSION;
+  scope: WorkflowRegistryScope;
+  status: 'installed' | 'active' | 'inactive';
+  contentLocation: { kind: 'controller' | 'project'; path: string; projectId?: string };
+  capabilityGrantRefs: string[];
+  bindings: WorkflowCapabilityBinding[];
+  executionReceiptReuseRefs: string[];
+  updatedAt: string;
+}
+
+function registryScopeKey(scope: WorkflowRegistryScope): string {
+  if (scope.kind === 'controller') return '__controller__';
+  if (!scope.projectId.trim() || scope.projectId.length > 128) throw new Error('WORKFLOW_REGISTRY_PROJECT_ID_INVALID');
+  return `project:${scope.projectId}`;
+}
+
+function boundedRef(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 512) throw new Error(`WORKFLOW_REGISTRY_${label}_INVALID`);
+  return trimmed;
+}
+
+function validateBinding(binding: WorkflowCapabilityBinding): WorkflowCapabilityBinding {
+  const capabilityId = boundedRef(binding.capabilityId, 'CAPABILITY_ID');
+  const providerId = binding.providerId === undefined ? undefined : boundedRef(binding.providerId, 'PROVIDER_ID');
+  const integrationId = binding.integrationId === undefined ? undefined : boundedRef(binding.integrationId, 'INTEGRATION_ID');
+  const pluginId = binding.pluginId === undefined ? undefined : boundedRef(binding.pluginId, 'PLUGIN_ID');
+  const actionId = binding.actionId === undefined ? undefined : boundedRef(binding.actionId, 'ACTION_ID');
+  if (providerId && integrationId) throw new Error('WORKFLOW_REGISTRY_BINDING_PROVIDER_INTEGRATION_CONFLICT');
+  if (Boolean(pluginId) !== Boolean(actionId)) throw new Error('WORKFLOW_REGISTRY_BINDING_PLUGIN_ACTION_PAIR_REQUIRED');
+  return { capabilityId, providerId, integrationId, pluginId, actionId };
+}
+
+function validateBindings(bindings: WorkflowCapabilityBinding[]): WorkflowCapabilityBinding[] {
+  const seenCapabilities = new Set<string>();
+  return bindings.map((binding) => {
+    const validated = validateBinding(binding);
+    if (seenCapabilities.has(validated.capabilityId)) {
+      throw new Error(`WORKFLOW_REGISTRY_BINDING_CAPABILITY_DUPLICATE: ${validated.capabilityId}`);
+    }
+    seenCapabilities.add(validated.capabilityId);
+    return validated;
+  });
+}
+
+function validateEntry(value: WorkflowRegistryEntry): WorkflowRegistryEntry {
+  if (value.schemaVersion !== SCHEMA_VERSION) throw new Error('WORKFLOW_REGISTRY_SCHEMA_VERSION_UNSUPPORTED');
+  boundedRef(value.workflowId, 'WORKFLOW_ID');
+  boundedRef(value.version, 'VERSION');
+  boundedRef(value.contentDigest, 'CONTENT_DIGEST');
+  boundedRef(value.contentLocation.path, 'CONTENT_LOCATION');
+  if (!['installed', 'active', 'inactive'].includes(value.status)) throw new Error('WORKFLOW_REGISTRY_STATUS_INVALID');
+  if (!Array.isArray(value.capabilityGrantRefs) || !Array.isArray(value.bindings) || !Array.isArray(value.executionReceiptReuseRefs)) {
+    throw new Error('WORKFLOW_REGISTRY_MACHINE_STATE_INVALID');
+  }
+  value.capabilityGrantRefs.forEach((ref) => boundedRef(ref, 'GRANT_REF'));
+  value.executionReceiptReuseRefs.forEach((ref) => boundedRef(ref, 'RECEIPT_REF'));
+  validateBindings(value.bindings);
+  if (!Number.isFinite(Date.parse(value.updatedAt))) throw new Error('WORKFLOW_REGISTRY_UPDATED_AT_INVALID');
+  return value;
+}
+
+export function readWorkflowRegistryEntry(
+  controllerHome: string,
+  scope: WorkflowRegistryScope,
+  workflowId: string,
+): ControlPlaneRecord<WorkflowRegistryEntry> | undefined {
+  const record = readControlPlaneRecord<WorkflowRegistryEntry>(
+    controllerHome,
+    WORKFLOW_REGISTRY_NAMESPACE,
+    registryScopeKey(scope),
+    workflowId,
+  );
+  if (!record) return undefined;
+  validateEntry(record.value);
+  return record;
+}
+
+export function listWorkflowRegistryEntries(
+  controllerHome: string,
+  scope: WorkflowRegistryScope,
+): ControlPlaneRecord<WorkflowRegistryEntry>[] {
+  const records = listControlPlaneRecords<WorkflowRegistryEntry>(controllerHome, {
+    namespace: WORKFLOW_REGISTRY_NAMESPACE,
+    scope: registryScopeKey(scope),
+  });
+  records.forEach((record) => validateEntry(record.value));
+  return records;
+}
+
+export function registerWorkflowAsset(input: {
+  controllerHome: string;
+  scope: WorkflowRegistryScope;
+  asset: WorkflowAssetDefinition;
+  contentLocation: WorkflowRegistryEntry['contentLocation'];
+  status?: WorkflowRegistryEntry['status'];
+  expectedRevision?: number | null;
+  now?: Date;
+}): ControlPlaneRecord<WorkflowRegistryEntry> {
+  const identity = workflowContentIdentity(input.asset);
+  const existing = readWorkflowRegistryEntry(input.controllerHome, input.scope, identity.workflowId);
+  const sameIdentity = existing ? sameWorkflowContentIdentity(existing.value, identity) : false;
+  const entry: WorkflowRegistryEntry = {
+    schemaVersion: SCHEMA_VERSION,
+    scope: input.scope,
+    ...identity,
+    status: input.status ?? existing?.value.status ?? 'installed',
+    contentLocation: input.contentLocation,
+    capabilityGrantRefs: sameIdentity ? [...existing!.value.capabilityGrantRefs] : [],
+    bindings: sameIdentity ? validateBindings(existing!.value.bindings).map((binding) => ({ ...binding })) : [],
+    executionReceiptReuseRefs: sameIdentity ? [...existing!.value.executionReceiptReuseRefs] : [],
+    updatedAt: (input.now ?? new Date()).toISOString(),
+  };
+  return writeControlPlaneRecord(input.controllerHome, {
+    namespace: WORKFLOW_REGISTRY_NAMESPACE,
+    scope: registryScopeKey(input.scope),
+    key: identity.workflowId,
+    schemaVersion: SCHEMA_VERSION,
+    value: entry,
+    action: sameIdentity ? 'workflow_registry_refresh' : existing ? 'workflow_registry_content_identity_changed' : 'workflow_registry_install',
+    expectedRevision: input.expectedRevision,
+  });
+}
+
+export function recordWorkflowBindings(input: {
+  controllerHome: string;
+  scope: WorkflowRegistryScope;
+  expectedIdentity: WorkflowContentIdentity;
+  capabilityGrantRefs?: string[];
+  bindings?: WorkflowCapabilityBinding[];
+  executionReceiptReuseRefs?: string[];
+  expectedRevision?: number;
+  now?: Date;
+}): ControlPlaneRecord<WorkflowRegistryEntry> {
+  const existing = readWorkflowRegistryEntry(input.controllerHome, input.scope, input.expectedIdentity.workflowId);
+  if (!existing) throw new Error('WORKFLOW_REGISTRY_ENTRY_REQUIRED');
+  if (!sameWorkflowContentIdentity(existing.value, input.expectedIdentity)) {
+    throw new Error('WORKFLOW_REGISTRY_CONTENT_IDENTITY_CHANGED');
+  }
+  const entry: WorkflowRegistryEntry = {
+    ...existing.value,
+    capabilityGrantRefs: (input.capabilityGrantRefs ?? existing.value.capabilityGrantRefs).map((ref) => boundedRef(ref, 'GRANT_REF')),
+    bindings: validateBindings(input.bindings ?? existing.value.bindings),
+    executionReceiptReuseRefs: (input.executionReceiptReuseRefs ?? existing.value.executionReceiptReuseRefs).map((ref) => boundedRef(ref, 'RECEIPT_REF')),
+    updatedAt: (input.now ?? new Date()).toISOString(),
+  };
+  return writeControlPlaneRecord(input.controllerHome, {
+    namespace: WORKFLOW_REGISTRY_NAMESPACE,
+    scope: registryScopeKey(input.scope),
+    key: input.expectedIdentity.workflowId,
+    schemaVersion: SCHEMA_VERSION,
+    value: entry,
+    action: 'workflow_registry_bindings_update',
+    expectedRevision: input.expectedRevision ?? existing.revision,
+  });
+}

package/src/runtime/control-plane/persistence/workflow-run-store.ts

@@ -0,0 +1,123 @@
+import { createHash } from 'crypto';
+import type { WorkflowCheckpoint, WorkflowJsonValue, WorkflowStepReceipt, WorkflowPublicationReceipt } from '../../../../packages/workflow-runtime/api/index';
+import { readControlPlaneRecord, writeControlPlaneRecord, type ControlPlaneRecord } from './sqlite-store';
+import { assertControlPlaneMetadataPayload } from './metadata-payload-policy';
+
+export const WORKFLOW_RUN_NAMESPACE = 'workflow_run';
+const SCHEMA_VERSION = 1 as const;
+const MAX_RECEIPTS = 128;
+
+export interface WorkflowRunRecord {
+  schemaVersion: typeof SCHEMA_VERSION;
+  workId: string;
+  runId: string;
+  workflowId: string;
+  version: string;
+  contentDigest: string;
+  inputDigest: string;
+  evidenceRef: string;
+  status: WorkflowCheckpoint['status'];
+  nextStepIndex: number;
+  receipts: WorkflowStepReceipt[];
+  reconcileStepId?: string;
+  reconcileWithCapabilityId?: string;
+  updatedAt: string;
+  outputs: Record<string, Record<string, unknown>>;
+  inFlightStepId?: string;
+  publicationReceipt?: WorkflowPublicationReceipt;
+}
+
+function bounded(value: string, code: string): string {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > 512) throw new Error(code);
+  return trimmed;
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => [key, canonical(entry)]));
+}
+
+export function workflowInputDigest(inputs: Record<string, WorkflowJsonValue> = {}): string {
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical(inputs))).digest('hex')}`;
+}
+
+function evidenceContent(value: Omit<WorkflowRunRecord, 'evidenceRef'>): string {
+  return JSON.stringify(canonical(value));
+}
+
+export function workflowRunEvidenceRef(value: Omit<WorkflowRunRecord, 'evidenceRef'> | WorkflowRunRecord): string {
+  const { evidenceRef: _ignored, ...content } = value as WorkflowRunRecord;
+  return `workflow-run-${createHash('sha256').update(evidenceContent(content)).digest('hex')}`;
+}
+
+function validRecord(value: WorkflowRunRecord): WorkflowRunRecord {
+  if (value.schemaVersion !== SCHEMA_VERSION) throw new Error('WORKFLOW_RUN_SCHEMA_VERSION_UNSUPPORTED');
+  bounded(value.workId, 'WORKFLOW_RUN_WORK_ID_INVALID');
+  bounded(value.runId, 'WORKFLOW_RUN_ID_INVALID');
+  bounded(value.workflowId, 'WORKFLOW_RUN_WORKFLOW_ID_INVALID');
+  bounded(value.version, 'WORKFLOW_RUN_VERSION_INVALID');
+  bounded(value.contentDigest, 'WORKFLOW_RUN_CONTENT_DIGEST_INVALID');
+  bounded(value.inputDigest, 'WORKFLOW_RUN_INPUT_DIGEST_INVALID');
+  bounded(value.evidenceRef, 'WORKFLOW_RUN_EVIDENCE_REF_INVALID');
+  if (workflowRunEvidenceRef(value) !== value.evidenceRef) throw new Error('WORKFLOW_RUN_EVIDENCE_REF_MISMATCH');
+  if (!['running', 'reconcile_required', 'failed', 'succeeded'].includes(value.status)) throw new Error('WORKFLOW_RUN_STATUS_INVALID');
+  if (!Number.isInteger(value.nextStepIndex) || value.nextStepIndex < 0) throw new Error('WORKFLOW_RUN_NEXT_STEP_INVALID');
+  if (!Array.isArray(value.receipts) || value.receipts.length > MAX_RECEIPTS) throw new Error('WORKFLOW_RUN_RECEIPTS_INVALID');
+  if (!Number.isFinite(Date.parse(value.updatedAt))) throw new Error('WORKFLOW_RUN_UPDATED_AT_INVALID');
+  assertControlPlaneMetadataPayload(value, 'workflow_run', 256 * 1024);
+  return value;
+}
+
+export function readWorkflowRun(
+  controllerHome: string,
+  workId: string,
+  runId: string,
+): ControlPlaneRecord<WorkflowRunRecord> | undefined {
+  const record = readControlPlaneRecord<WorkflowRunRecord>(controllerHome, WORKFLOW_RUN_NAMESPACE, bounded(workId, 'WORKFLOW_RUN_WORK_ID_INVALID'), bounded(runId, 'WORKFLOW_RUN_ID_INVALID'));
+  if (!record) return undefined;
+  validRecord(record.value);
+  return record;
+}
+
+export function writeWorkflowRunCheckpoint(input: {
+  controllerHome: string;
+  checkpoint: WorkflowCheckpoint;
+  inputs?: Record<string, WorkflowJsonValue>;
+  expectedRevision?: number | null;
+  now?: Date;
+}): ControlPlaneRecord<WorkflowRunRecord> {
+  if (input.checkpoint.receipts.length > MAX_RECEIPTS) throw new Error('WORKFLOW_RUN_RECEIPT_BUDGET_EXCEEDED');
+  const content: Omit<WorkflowRunRecord, 'evidenceRef'> = {
+    schemaVersion: SCHEMA_VERSION,
+    workId: input.checkpoint.binding.workId,
+    runId: input.checkpoint.binding.runId,
+    workflowId: input.checkpoint.workflowId,
+    version: input.checkpoint.version,
+    contentDigest: input.checkpoint.contentDigest,
+    inputDigest: workflowInputDigest(input.inputs),
+    status: input.checkpoint.status,
+    nextStepIndex: input.checkpoint.nextStepIndex,
+    receipts: input.checkpoint.receipts.map((receipt) => ({ ...receipt })),
+    reconcileStepId: input.checkpoint.reconcileStepId,
+    reconcileWithCapabilityId: input.checkpoint.reconcileWithCapabilityId,
+    updatedAt: (input.now ?? new Date()).toISOString(),
+    outputs: input.checkpoint.outputs,
+    inFlightStepId: input.checkpoint.inFlightStepId,
+    publicationReceipt: input.checkpoint.publicationReceipt,
+  };
+  const value: WorkflowRunRecord = { ...content, evidenceRef: workflowRunEvidenceRef(content) };
+  validRecord(value);
+  return writeControlPlaneRecord(input.controllerHome, {
+    namespace: WORKFLOW_RUN_NAMESPACE,
+    scope: value.workId,
+    key: value.runId,
+    schemaVersion: SCHEMA_VERSION,
+    value,
+    action: `workflow_run_${value.status}`,
+    expectedRevision: input.expectedRevision,
+  });
+}

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

@@ -7,6 +7,7 @@ import {
   rmSync,
 } from 'fs';
 import { basename, dirname, join, relative, resolve } from 'path';
+import { measureReclaimablePath } from './lifecycle-retention-metrics';
 
 const DEFAULT_RELEASE_RETENTION_GRACE_MS = 30 * 60_000;
 const DEFAULT_STAGING_RETENTION_GRACE_MS = 6 * 60 * 60_000;
@@ -23,6 +24,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>;
@@ -55,6 +61,24 @@ function canonical(path: string): string {
   }
 }
 
+/**
+ * Canonicalize a path even when its leaf has already been removed by resolving
+ * the nearest existing ancestor first and then projecting the missing suffix.
+ * This preserves filesystem identity across logical aliases such as macOS
+ * /var -> /private/var without requiring historical artifacts to still exist.
+ */
+function canonicalProjectedPath(path: string): string {
+  let cursor = resolve(path);
+  const missingSuffix: string[] = [];
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return resolve(path);
+    missingSuffix.unshift(basename(cursor));
+    cursor = parent;
+  }
+  return resolve(canonical(cursor), ...missingSuffix);
+}
+
 function directChild(root: string, path: string): boolean {
   return dirname(canonical(path)) === canonical(root);
 }
@@ -127,10 +151,9 @@ function loadPackageConnectorReleaseProtection(controllerHome: string, releasesR
   return canonical(releaseRoot);
 }
 
-function loadRecoveryKnownGoodReleaseProtection(controllerHome: string, releasesRoot: string): Set<string> {
+function validateRecoveryKnownGoodHistory(controllerHome: string, releasesRoot: string): void {
   const knownGoodPath = join(controllerHome, 'recovery', 'state', 'known-good.json');
-  const protectedPaths = new Set<string>();
-  if (!existsSync(knownGoodPath)) return protectedPaths;
+  if (!existsSync(knownGoodPath)) return;
   const parsed = JSON.parse(readFileSync(knownGoodPath, 'utf8')) as Record<string, unknown>;
   if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.releases)) {
     throw new Error('standalone recovery known-good authority is invalid');
@@ -143,21 +166,16 @@ function loadRecoveryKnownGoodReleaseProtection(controllerHome: string, releases
     if (!releaseId || !manifestPathValue) throw new Error('standalone recovery known-good release identity is incomplete');
     const manifestPath = resolve(manifestPathValue);
     const releaseRoot = dirname(manifestPath);
+    const exactHistoricalManifestPath = resolve(canonical(releasesRoot), releaseId, 'manifest.json');
+    const historicalManifestPath = canonicalProjectedPath(manifestPath);
     if (
       basename(manifestPath) !== 'manifest.json'
       || basename(releaseRoot) !== releaseId
-      || !directChild(releasesRoot, releaseRoot)
+      || historicalManifestPath !== exactHistoricalManifestPath
     ) {
       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));
   }
-  return protectedPaths;
 }
 
 function loadRuntimeProtection(controllerHome: string): RuntimeProtection | undefined {
@@ -180,9 +198,15 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   }
   const connectorRelease = loadPackageConnectorReleaseProtection(controllerHome, releasesRoot);
   if (connectorRelease) releasePaths.add(connectorRelease);
-  for (const knownGoodRelease of loadRecoveryKnownGoodReleaseProtection(controllerHome, releasesRoot)) {
-    releasePaths.add(knownGoodRelease);
-  }
+  // Recovery known-good is append-only attestation evidence, not a storage
+  // ownership authority. Recovery itself only accepts a known-good entry when
+  // it still matches the current active/previous release authority, both of
+  // which are already protected above. Keeping every extant historical entry
+  // here creates a circular retention leak: the artifact can never disappear
+  // because its historical evidence exists, while the evidence is allowed to
+  // outlive the artifact. Validate the ledger fail-closed, but do not grant old
+  // attestations independent retention authority.
+  validateRecoveryKnownGoodHistory(controllerHome, releasesRoot);
 
   const backupPaths = new Set<string>();
   let backupAuthoritySafe = true;
@@ -249,6 +273,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 +285,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));
   }
@@ -393,7 +428,7 @@ function scanRuntimeReleases(
       continue;
     }
 
-    removeCandidate(controllerHome, path, false, state);
+    removeCandidate(controllerHome, path, false, state, 'recovery_backup');
   }
 }
 
@@ -486,6 +521,11 @@ export function cleanupControllerReleaseHistory(
     eligible: 0,
     attempted: 0,
     removedPaths: [],
+    removedBackupPaths: [],
+    reclaimedBytes: 0,
+    reclaimedBackupBytes: 0,
+    unknownReclaimedByteCount: 0,
+    unknownReclaimedBackupByteCount: 0,
     retained: 0,
     skipped: 0,
     skippedByReason: {},