@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/persistence/sqlite-store.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { copyFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from 'fs';
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
 import { durableControllerHome } from '../../../cli/repositories/controller-home';
 
@@ -62,6 +62,36 @@ export interface ControlPlaneDatabaseInspection {
   orphanRecordCount: number;
 }
 
+/**
+ * Ephemeral database-wide change fence. SQLite data_version changes whenever a
+ * different connection commits to the same database, including domain tables
+ * that do not participate in control_plane_audit.
+ */
+export interface ControlPlaneDatabaseChangeObserver {
+  path: string;
+  dataVersion(): number;
+  close(): void;
+}
+
+const CONTROL_PLANE_DATABASE_HASH_CHUNK_BYTES = 1024 * 1024;
+
+/** Full snapshot identity without allocating the whole SQLite file. */
+export function sha256ControlPlaneDatabaseFile(path: string): string {
+  const descriptor = openSync(path, 'r');
+  const hash = createHash('sha256');
+  const buffer = Buffer.allocUnsafe(CONTROL_PLANE_DATABASE_HASH_CHUNK_BYTES);
+  try {
+    for (;;) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+    return hash.digest('hex');
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
 export const CONTROL_PLANE_SQLITE_MAINTENANCE_POLICY_VERSION = 'control-plane-sqlite-maintenance-v1' as const;
 export const DEFAULT_CONTROL_PLANE_SQLITE_VACUUM_MIN_RECLAIMABLE_BYTES = 64 * 1024 * 1024;
 export const DEFAULT_CONTROL_PLANE_SQLITE_VACUUM_MIN_RECLAIMABLE_RATIO = 0.20;
@@ -294,9 +324,10 @@ function openDatabase(controllerHome: string): SqliteDatabase {
     // inspectOpenDatabase(), which is the authoritative integrity boundary.
     // Keep schema fail-closed on every open, but reserve the full integrity scan
     // for those lifecycle/inspection boundaries.
+    let schemaVersion: number | undefined;
     if (existed) {
       try {
-        assertSupportedSchema(database, path);
+        schemaVersion = assertSupportedSchema(database, path);
       } catch (error) {
         const busy = sqliteBusyError(path, error);
         if (busy) throw busy;
@@ -306,8 +337,14 @@ function openDatabase(controllerHome: string): SqliteDatabase {
       }
     }
     database.exec('PRAGMA journal_mode = WAL;');
-    initializeSchema(database);
-    assertSupportedSchema(database, path, true);
+    // Schema DDL is bootstrap work, not transaction work. Existing supported
+    // databases have already crossed the fail-closed schema boundary above;
+    // rerunning CREATE INDEX/TABLE + INSERT OR IGNORE on every write only burns
+    // allocations/SQLite preparation and then validates the same schema twice.
+    if (schemaVersion === undefined) {
+      initializeSchema(database);
+      assertSupportedSchema(database, path, true);
+    }
     return database;
   } catch (error) {
     database.close();
@@ -346,6 +383,27 @@ function openDatabaseForRead(controllerHome: string): SqliteDatabase {
   return openDatabase(controllerHome);
 }
 
+export function openControlPlaneDatabaseChangeObserver(controllerHome: string): ControlPlaneDatabaseChangeObserver {
+  const path = controlPlaneDatabasePath(controllerHome);
+  const database = openDatabaseForRead(controllerHome);
+  let closed = false;
+  const dataVersion = () => {
+    if (closed) throw new Error('CONTROL_PLANE_DATABASE_CHANGE_OBSERVER_CLOSED');
+    return integerPragma(database, 'PRAGMA data_version', 'data_version');
+  };
+  // Prime the connection before returning it so the first caller observation
+  // is relative to an established SQLite connection, not connection startup.
+  dataVersion();
+  return {
+    path,
+    dataVersion,
+    close() {
+      if (closed) return;
+      closed = true;
+      database.close();
+    },
+  };
+}
 
 function withDatabaseForRead<T>(controllerHome: string, operation: (database: SqliteDatabase) => T): T {
   const path = controlPlaneDatabasePath(controllerHome);
@@ -382,6 +440,11 @@ function withDatabaseForRead<T>(controllerHome: string, operation: (database: Sq
   }
 }
 
+/** Read-only snapshot boundary for domain stores that need several indexed lookups in one hot-path operation. */
+export function withControlPlaneReadDatabase<T>(controllerHome: string, operation: (database: SqliteDatabase) => T): T {
+  return withDatabaseForRead(controllerHome, operation);
+}
+
 function rowToRecord<T>(row: StoredRecordRow): ControlPlaneRecord<T> {
   let value: T;
   try {
@@ -508,6 +571,22 @@ export function readControlPlaneRecord<T>(controllerHome: string, namespace: str
     selectRecord<T>(database, namespace, scope, key));
 }
 
+export function listControlPlaneRecordKeys(
+  controllerHome: string,
+  input: { namespace: string; scope: string; limit?: number },
+): string[] {
+  const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 5_000), 5_000));
+  return withDatabaseForRead(controllerHome, (database) =>
+    withSqliteStatement(database, `
+      SELECT record_key
+      FROM control_plane_records
+      WHERE namespace = ? AND scope = ?
+      ORDER BY record_key ASC
+      LIMIT ?
+    `, (statement) => (statement.all(input.namespace, input.scope, limit) as Array<{ record_key: string }>)
+      .map((row) => row.record_key)));
+}
+
 export function writeControlPlaneRecord<T>(
   controllerHome: string,
   input: {
@@ -633,6 +712,24 @@ export function listControlPlaneRecords<T>(
     listControlPlaneRecordsWithinTransaction<T>(database, input));
 }
 
+/** Exact stable-key lookup across scopes. This is a read of the existing Control Plane authority, not a second id registry. */
+export function findControlPlaneRecordsByKey<T>(
+  controllerHome: string,
+  input: { namespace: string; key: string; limit?: number },
+): ControlPlaneRecord<T>[] {
+  const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 2), 100));
+  return withDatabaseForRead(controllerHome, (database) => {
+    const rows = withSqliteStatement(database, `
+      SELECT namespace, scope, record_key, schema_version, revision, payload, created_at, updated_at
+      FROM control_plane_records
+      WHERE namespace = ? AND record_key = ?
+      ORDER BY scope ASC
+      LIMIT ?
+    `, (statement) => statement.all(input.namespace, input.key, limit));
+    return (rows as StoredRecordRow[]).map((row) => rowToRecord<T>(row));
+  });
+}
+
 /**
  * Candidate-only read optimization for top-level JSON text fields. This never
  * establishes domain authority: missing/null/non-text values remain candidates,
@@ -660,6 +757,11 @@ function payloadTextExclusionPredicate(input: PayloadTextExclusion): string {
   return `${namespace} AND (${extraction} IS NULL OR ${extraction} NOT IN (${values.map(literal).join(', ')}))`;
 }
 
+function payloadTextExclusionIndexName(input: PayloadTextExclusion, predicate = payloadTextExclusionPredicate(input)): string {
+  const prefix = `control_plane_candidate_${createHash('sha256').update(`${input.namespace}/${input.field}`).digest('hex').slice(0, 16)}_`;
+  return `${prefix}${createHash('sha256').update(predicate).digest('hex').slice(0, 16)}`;
+}
+
 /** Explicit startup DDL. JSON remains authority; SQLite maintains the derived index in every write transaction. */
 export function initializeControlPlanePayloadTextExclusionIndex(
   controllerHome: string,
@@ -667,7 +769,7 @@ export function initializeControlPlanePayloadTextExclusionIndex(
 ): void {
   const predicate = payloadTextExclusionPredicate(input);
   const prefix = `control_plane_candidate_${createHash('sha256').update(`${input.namespace}/${input.field}`).digest('hex').slice(0, 16)}_`;
-  const name = `${prefix}${createHash('sha256').update(predicate).digest('hex').slice(0, 16)}`;
+  const name = payloadTextExclusionIndexName(input, predicate);
   withControlPlaneTransaction(controllerHome, (database) => {
     database.exec(`CREATE INDEX IF NOT EXISTS ${name} ON control_plane_records (scope, updated_at, record_key) WHERE ${predicate}`);
     // Retire obsolete predicates for this domain field in the same transaction.
@@ -686,11 +788,16 @@ export function listControlPlaneRecordsExcludingPayloadTextValues<T>(
   input: PayloadTextExclusion & { scope: string; limit?: number },
 ): ControlPlaneRecord<T>[] {
   const predicate = payloadTextExclusionPredicate(input);
+  const candidateIndex = payloadTextExclusionIndexName(input, predicate);
   const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 1_000), 5_000));
   return withDatabaseForRead(controllerHome, (database) => {
+    const candidateIndexExists = withSqliteStatement(database,
+      "SELECT 1 AS present FROM sqlite_master WHERE type = 'index' AND name = ? LIMIT 1",
+      (statement) => statement.get(candidateIndex) != null);
+    const indexHint = candidateIndexExists ? ` INDEXED BY ${candidateIndex}` : '';
     const rows = withSqliteStatement(database, `
       SELECT namespace, scope, record_key, schema_version, revision, payload, created_at, updated_at
-      FROM control_plane_records
+      FROM control_plane_records${indexHint}
       WHERE ${predicate} AND scope = ?
       ORDER BY updated_at ASC, record_key ASC
       LIMIT ?

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

@@ -8,6 +8,7 @@ import {
 } 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;
@@ -48,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>;
@@ -61,26 +70,17 @@ 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);
+  // 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 {
@@ -151,31 +151,81 @@ function loadPackageConnectorReleaseProtection(controllerHome: string, releasesR
   return canonical(releaseRoot);
 }
 
-function validateRecoveryKnownGoodHistory(controllerHome: string, releasesRoot: string): void {
+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;
+  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 exactHistoricalManifestPath = resolve(canonical(releasesRoot), releaseId, 'manifest.json');
-    const historicalManifestPath = canonicalProjectedPath(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
-      || historicalManifestPath !== exactHistoricalManifestPath
-    ) {
+      !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');
     }
+    // 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 {
@@ -186,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) {
@@ -198,17 +249,54 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   }
   const connectorRelease = loadPackageConnectorReleaseProtection(controllerHome, releasesRoot);
   if (connectorRelease) releasePaths.add(connectorRelease);
-  // 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 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);
+  }
+
+  // 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));
+      }
+    }
+  }
 
-  const backupPaths = new Set<string>();
   let backupAuthoritySafe = true;
   if (previous && typeof previous === 'object' && !Array.isArray(previous)) {
     const databaseBackup = (previous as Record<string, unknown>).databaseBackup;
@@ -321,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;
 

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

@@ -5,7 +5,7 @@ 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 { isTerminalWorkContractStatus, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { isTerminalSemanticWorkState, readWorkContractStore } from '../../../packages/kernel/work/api/index';
 import { listControlPlaneRecords } from './persistence/sqlite-store';
 import { measureReclaimablePath } from './lifecycle-retention-metrics';
 
@@ -88,7 +88,7 @@ function activeAuthorityBlockers(controllerHome: string, repoId: string): string
 
   const workStore = readWorkContractStore({ controllerHome, repoId });
   for (const work of workStore.contracts) {
-    if (!isTerminalWorkContractStatus(work.status)) {
+    if (!isTerminalSemanticWorkState(work.semanticState)) {
       blockers.push('active_work');
       break;
     }