@volter/world-runtime 3.0.162 → 3.0.164

package/src/infra.ts

@@ -7,13 +7,15 @@
 // that owns the World's lifetime, as every other service's recorder is, and not of a tool that exits once they
 // serve. A process layer where a child does not outlive its parent (a browser tab's) otherwise ended the PGlite host
 // the moment `volter-world-infra up` returned, and the World's readiness probe never saw it.
-import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { accessSync, constants, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { delimiter, dirname, join } from 'node:path';
+import { setWorldEventsFile, worldEvent } from './process-groups.ts';
 import { signalChild } from './process-signal.mjs';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { containerlessDataDirectory, infraConnections, liveDatabaseBehind, liveDatabaseMigration, developmentMigratesAtRuntime, DEVELOPMENT_MIGRATION_NOTICE, parseInfraDefinition } from './pglite-backing.ts';
 import { errorMessage } from './error-message.ts';
+import type { ManagedProtocol } from './twin-backing.ts';
 
 /** Whether a program is on PATH, read from the file system without starting a process: where a missing program
  *  still costs a process round trip (a browser tab's kernel), the container probe is not spawned at all. */
@@ -24,7 +26,13 @@ function onPath(name: string, env: NodeJS.ProcessEnv): boolean {
   });
 }
 
-export interface InfrastructureIo { out: (text: string) => void; err: (text: string) => void }
+export interface InfrastructureIo {
+  out: (text: string) => void;
+  err: (text: string) => void;
+  /** The runtime's own in-process `up` (runtime.ts): handed the status its `status` would print, when this `up` itself
+   *  proved everything that status proves (every service twin-served, each held and serving). */
+  verified?: (status: string) => void;
+}
 
 interface Ran { status: number | null; stdout: string; stderr: string; error?: Error }
 
@@ -122,11 +130,39 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     io.err('managed infrastructure: missing World lifecycle context\n');
     return 2;
   }
+  // What this command does to a backing's process is said in the World's own log, beside its services' events.
+  setWorldEventsFile(join(dirname(worldData), 'logs', 'events.jsonl'));
+  const phaseAsked = Date.now();
+  // Retirement follows retained ownership even if the definition or supplier
+  // can no longer be read. Other infrastructure still reports its own refusal.
+  let retainedMariaDB = false;
+  if (phase === 'down') {
+    try {
+      retainedMariaDB = existsSync(join(worldData, 'native-mariadb.owner.json'))
+        || existsSync(join(worldData, 'native-mariadb.owner.json.spawn.json'))
+        || existsSync(join(worldData, 'native-mariadb.starting.json'))
+        // install-db can outlive its caller before any server receipt exists.
+        // Either half of a helper pair enters retirement; a missing birth
+        // token remains an explicit uncertainty in nativeMariaDBDown.
+        || (existsSync(worldData) && readdirSync(worldData).some(name => /^native-mariadb-tool-.*\.json(?:\.spawn\.json)?$/u.test(name)));
+    } catch (error) { io.err(`managed MariaDB ownership inventory is unreadable: ${errorMessage(error)}\n`); return 1; }
+  }
+  if (retainedMariaDB) {
+    try { await (await import('./native-mariadb-backing.ts')).nativeMariaDBDown(worldData); }
+    catch (error) { io.err(`managed MariaDB down failed: ${errorMessage(error)}\n`); return 1; }
+  }
   const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
   if (!existsSync(definition)) {
     io.err('managed infrastructure: declared definition is missing\n');
     return 2;
   }
+  const declared = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  // Both the CLI and the World's in-process up enter here. Endpoint metadata cannot supply host DNS or a native
+  // default-port listener: refuse before choosing or starting any backing when the substrate carrier is absent.
+  if (phase === 'up' && declared.some(service => service.virtualTcpEndpoint) && env.VOLTER_WORLD_VIRTUAL_TCP !== '1') {
+    io.err('managed infrastructure up: virtual TCP endpoints require the substrate network carrier; native host DNS/default ports are not supplied\n');
+    return 2;
+  }
   // A development World says so every time it comes up: its use is never silent.
   if (phase === 'up' && developmentMigratesAtRuntime(worldConfig)) io.out(`${DEVELOPMENT_MIGRATION_NOTICE}\n`);
 
@@ -218,7 +254,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     const { unsupportedKinds } = await import('./pglite-backing.ts');
     const { nativePostgresTools } = await import('./native-postgres-backing.ts');
     const postgres = declared.filter(s => s.kind === 'postgres');
-    if (postgres.length !== 1 || unsupportedKinds(declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s))).length) return selected;
+    if (postgres.length !== 1 || unsupportedKinds(declared.filter(s => s.kind !== 'postgres' && !s.nativeMariaDB && !twinned.includes(s))).length) return selected;
     const native = existsSync(join(worldData!, 'native-postgres-data'));
     const pglite = existsSync(join(worldData!, 'pglite-postgres-data'));
     if (native && pglite) {
@@ -257,7 +293,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
         io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
         return 1;
       }
-      io.out('managed infrastructure ready\n');
+      sayReady();
       return 0;
     }
     if (phase === 'status') {
@@ -275,18 +311,68 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     return 0;
   }
 
-  // ---- redis: the twin, containerless ----------------------------------------
-  // A redis service is served by the redis twin (redis-backing.ts) on every machine, container runtime or not,
-  // unless the operator forces the container backing; the other services take the backing chosen above. Where the
-  // twin is not installed (@volter/twin-redis is not this runtime's dependency), redis goes to that backing too:
-  // the container where there is one, else the backing's refusal naming redis.
-  const declared = parseInfraDefinition(readFileSync(definition, 'utf8'));
-  const { redisTwinCli } = await import('./redis-backing.ts');
-  const twinCli = redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)]);
-  const twinned = env.VOLTER_WORLD_INFRA_BACKING === 'docker' || twinCli === undefined ? [] : declared.filter((s) => s.kind === 'redis');
+  // ---- a kind a twin serves: the twin, containerless --------------------------
+  // A service whose kind an installed pack declares (`managedService` in pack facts; twin-backing.ts) is served by
+  // that pack on every machine, container runtime or not, unless the operator forces the container backing; the
+  // other services take the backing chosen above. Which pack is the pack's declaration, never a name here. Where no
+  // pack declares the kind, or the one that does is not installed, the kind goes to that backing too: the container
+  // where there is one, else the backing's refusal naming the kind (the vendor's own server for MongoDB).
+  // The kinds listed are those whose protocol this runtime can ask its two questions in (ManagedProtocol).
+  const mariaDB = declared.flatMap(service => service.nativeMariaDB ? [service.nativeMariaDB] : []);
+  if (phase !== 'down' && mariaDB.length && ['docker', 'pglite'].includes(env.VOLTER_WORLD_INFRA_BACKING ?? '')) {
+    io.err('managed MariaDB: explicit native selection cannot be replaced by the forced backing\n');
+    return 1;
+  }
+  // Resolve only kinds the definition actually asks for. Looking up a pack before filtering its services made a
+  // PostgreSQL-only World scan installed Redis/MongoDB packs and their CLI graphs on every infrastructure phase.
+  const kinds = (['redis', 'mongodb', 'clickhouse'] as const).filter(kind => declared.some(service => service.kind === kind));
+  const managed = env.VOLTER_WORLD_INFRA_BACKING === 'docker' || kinds.length === 0
+    ? undefined : await import('./twin-backing.ts');
+  const protocols: { redis?: ManagedProtocol; mongodb?: ManagedProtocol; clickhouse?: ManagedProtocol } = {};
+  if (managed) {
+    if (kinds.includes('redis')) protocols.redis = (await import('./redis-backing.ts')).REDIS_PROTOCOL;
+    if (kinds.includes('mongodb')) protocols.mongodb = (await import('./mongodb-backing.ts')).MONGODB_PROTOCOL;
+    if (kinds.includes('clickhouse')) protocols.clickhouse = (await import('./clickhouse-backing.ts')).CLICKHOUSE_PROTOCOL;
+  }
+  const expectedTwinPackages = new Map<string, string>();
+  const twins = !managed ? [] : kinds.flatMap((kind) => {
+    const services = declared.filter((s) => s.kind === kind);
+    const beside = [dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)];
+    const twin = managed.managedTwin(kind, protocols[kind]!, beside, phase !== 'down' && services.some(service => service.originalInputs !== undefined));
+    if (twin) expectedTwinPackages.set(kind, twin.package);
+    const cli = twin && managed.twinBackingCli(twin, beside);
+    return twin && (cli || phase === 'down') ? [{ twin, cli: cli ?? '', services }] : [];
+  });
+  const twinned = twins.flatMap((served) => served.services);
+  // A declared original-input carrier cannot fall through to a backing that drops it.
+  // Down still retires established owners even when a pack or source snapshot is unavailable.
+  if (phase !== 'down') {
+    try {
+      for (const service of declared) if (service.originalInputs) {
+        const consumer = twins.find(entry => entry.services.includes(service));
+        if (!managed || !consumer) throw new Error(`managed ${service.kind} has original inputs and no installed declaring consumer`);
+        managed.originalInputArguments(consumer.twin, service, worldConfig);
+      }
+    } catch (error) {
+      io.err(`managed infrastructure ${phase} refused original inputs: ${diagnostic(errorMessage(error))}\n`);
+      return 1;
+    }
+  }
   /** The services the backing below answers for: every one, or those the twin does not serve (by compose service name). */
-  const native = declared.filter((s) => s.kind === 'mongodb');
-  const composed = twinned.length === 0 && native.length === 0 ? null : declared.filter((s) => !twinned.includes(s) && !native.includes(s)).map((s) => s.kind);
+  const native = declared.filter((s) => s.kind === 'mongodb' && !twinned.includes(s));
+  // Tab hosts expose their kernel tree on this symbol (world-store.ts). Redis/MongoDB's managed kinds need
+  // their installed declaring twins there; a missing pack is an input refusal, never a native-server attempt.
+  // PostgreSQL is separate: its available WALI server tools or PGlite still own that declared backing.
+  const inTab = (process as unknown as Record<symbol, unknown>)[Symbol.for('tabnode.run.vfs')] !== undefined;
+  if (inTab && phase !== 'down') {
+    const missing = kinds.filter(kind => !twinned.some(service => service.kind === kind)
+      && (env.VOLTER_WORLD_INFRA_BACKING !== 'docker' || native.some(service => service.kind === kind)));
+    if (missing.length) {
+      for (const kind of missing) io.err(`managed ${kind} needs ${expectedTwinPackages.get(kind) ?? `@volter/twin-${kind}`} installed in this tab World\n`);
+      return 1;
+    }
+  }
+  const composed = twinned.length === 0 && native.length === 0 && mariaDB.length === 0 ? null : declared.filter((s) => !twinned.includes(s) && !native.includes(s) && !s.nativeMariaDB).map((s) => s.kind);
   // A database's native wire and storage are its vendor server's. MongoDB never needs a Docker probe or container.
   if (native.length > 0) {
     const { pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
@@ -305,65 +391,146 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       return 1;
     }
   }
-  if (twinned.length > 0) {
-    const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import('./redis-backing.ts');
-    const cli = twinCli!;
-    if (phase === 'up') {
-      io.out('managed infrastructure backing: redis twin (containerless)\n');
-      try {
-        await redisTwinUp(twinned, worldData!, cli, launch);
-      } catch (error) {
-        io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
-        return 1;
-      }
-    } else if (phase === 'status') {
-      const ready = await redisTwinStatus(twinned, worldData!);
-      if (ready !== twinned.length) {
-        io.err(`managed infrastructure status failed: ${ready}/${declared.length} declared services are ready\n`);
-        return 1;
+  // THE TWIN-SERVED KINDS WAIT FOR THE DATABASE'S CLUSTER PLACEMENT. A store staged with a prepared cluster is placed where its
+  // twin serves from, and only beside a database that carries the same migration (takePreparedStore). Brought up
+  // first, a twin's store was placed before the database's backing was chosen, and where that backing then
+  // declined the prepared cluster (its programs' stamp, PGlite serving a native cluster) the World had an
+  // unprepared database and a prepared store. On `up` with the native backing, its onPlaced starts the twins once
+  // the cluster is placed, beside readiness; otherwise they start after the database. The live cluster is then
+  // there to be read; `status` and `down` keep their order. The ready line is said once,
+  // after both.
+  /** What `status` prints when every declared service is twin-served: one fact, said by status and handed over by up. */
+  const twinServedStatus = () => ({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...databaseFacts() });
+  /** The native backing's status, its proof asked as status asks it: set by the native branch's `up` once it is ready. */
+  let nativeProof: (() => Promise<string | undefined>) | undefined;
+  /** What this `up` has proved, handed to the runtime's own in-process up (InfrastructureIo.verified) as the status its
+   *  `status` would print, its proofs asked again now: every twin held (twinBackingHeld), and then either every service
+   *  twin-served or, with no MongoDB native, the native backing's own status proof (nativeStatus: the containerless
+   *  others serving, pgliteStatus, and the postmaster's, nativePostgresStatus). It does not repeat status's choice of
+   *  backing (selectBacking, a `docker info` probe): the backing is the one this up just brought up. Any doubt hands
+   *  nothing over, and the runtime's probe runs. */
+  const handOver = async (): Promise<void> => {
+    if (!io.verified || phase !== 'up' || native.length !== 0) return;
+    for (const { twin, services } of twins) if (!await managed!.twinBackingHeld(twin, services, worldData!)) return;
+    if (mariaDB.length && !await (await import('./native-mariadb-backing.ts')).nativeMariaDBStatus(mariaDB[0]!, worldData, worldConfig, launch)) return;
+    if (composed?.length === 0) { io.verified(`${JSON.stringify(twinServedStatus())}\n`); return; }
+    if (!nativeProof) return;
+    let text: string | undefined;
+    try { text = await nativeProof(); } catch { return; }
+    if (text) io.verified(text);
+  };
+  let twinsPending = false;
+  let readyHeld = false;
+  // THE TWINS COME UP BESIDE THE DATABASE'S READINESS (S2 R79), not after it: Twenty's redis twin began only when the
+  // postmaster answered (+1.36 s) and held up 330 ms more. 840a1ae3's rule stands: a twin's staged store is placed beside
+  // the cluster the backing chose, so the twins start no earlier than the native backing's onPlaced, said after the
+  // cluster is placed (or made by initdb) and its server spawned. Every other backing still runs them after it returns.
+  let twinsBeside: Promise<number> | undefined;
+  // A twin that fails beside the readiness wait ends that wait (its signal), so the up fails then, not at the
+  // database's readiness or deadline: the native start retires its postmaster as on any abort, and the failed-database
+  // path below brings the rest down.
+  const twinFailed = new AbortController();
+  const startTwinsBeside = (): void => {
+    if (!twinsPending || twinsBeside) return;
+    io.out('managed infrastructure: twins started beside the database\'s readiness (its cluster placed)\n');
+    twinsBeside = twinsPhase().then((code) => {
+      if (code !== 0) twinFailed.abort(new Error('a twin failed beside the database\'s readiness, so its start was ended'));
+      return code;
+    });
+  };
+  const sayReady = (): void => { if (twinsPending) readyHeld = true; else io.out('managed infrastructure ready\n'); };
+  const twinsPhase = async (): Promise<number> => {
+    if (!managed) return 0;
+    for (const { twin, cli, services } of twins) {
+      if (phase === 'up') {
+        io.out(`managed infrastructure backing: ${twin.id} twin (containerless)\n`);
+        try {
+          await managed.twinBackingUp(twin, services, worldData!, cli, launch);
+        } catch (error) {
+          io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
+          return 1;
+        }
+      } else if (phase === 'status') {
+        const ready = await managed.twinBackingStatus(twin, services, worldData!);
+        if (ready !== services.length) {
+          io.err(`managed infrastructure status failed: ${ready}/${declared.length} declared services are ready\n`);
+          return 1;
+        }
+      } else {
+        await managed.twinBackingDown(twin, services, worldData!);
       }
-    } else {
-      await redisTwinDown(twinned, worldData!);
     }
+    return 0;
+  };
+  if (phase === 'up' && twins.length > 0) twinsPending = true;
+  else { const code = await twinsPhase(); if (code !== 0) return code; }
+  const databasePhase = async (): Promise<number> => {
+  if (mariaDB.length) {
+    const { nativeMariaDBUp, nativeMariaDBStatus, nativeMariaDBDown } = await import('./native-mariadb-backing.ts');
+    if (mariaDB.length !== 1) { io.err('managed MariaDB needs one explicit native provider per World\n'); return 1; }
+    try {
+      if (phase === 'up') {
+        io.out(`managed infrastructure backing: native MariaDB ${mariaDB[0]!.reference.release}, exact declared provider\n`);
+        await nativeMariaDBUp(mariaDB[0]!, worldData, worldConfig, launch);
+      } else if (phase === 'status') {
+        if (!await nativeMariaDBStatus(mariaDB[0]!, worldData, worldConfig, launch)) {
+          io.err('managed MariaDB status: owned server, installed supply or authenticated readiness is not confirmed\n');
+          return 1;
+        }
+      } else await nativeMariaDBDown(worldData);
+    } catch (error) { io.err(`managed MariaDB ${phase} failed: ${diagnostic(errorMessage(error))}\n`); return 1; }
   }
   if (composed?.length === 0) {
-    if (phase === 'up') io.out('managed infrastructure ready\n');
-    else if (phase === 'status') io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...databaseFacts() })}\n`);
+    if (phase === 'up') sayReady();
+    else if (phase === 'status') io.out(`${JSON.stringify(twinServedStatus())}\n`);
     else io.out('managed infrastructure stopped\n');
     return 0;
   }
 
+  // How long the choice of backing took, and how far into the phase it was made (S2, Twenty's World up): Twenty's up spent 220 ms between
+  // its infrastructure starting beside the host and the backing's line, none of it said.
+  const choosing = Date.now();
   const backing = await containerlessPostgres(await selectBacking());
+  const chosen = `backing chosen in ${Date.now() - choosing} ms, ${Date.now() - phaseAsked} ms into the phase`;
   if (typeof backing === 'number') return backing;
   if (backing === 'pglite') return runPglite();
   if (backing === 'native') {
     const { nativePostgresUp, nativePostgresStatus, nativePostgresDown } = await import('./native-postgres-backing.ts');
     const postgres = declared.filter(s => s.kind === 'postgres');
-    const others = declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s));
+    const others = declared.filter(s => s.kind !== 'postgres' && !s.nativeMariaDB && !twinned.includes(s));
     const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
     if (postgres.length !== 1 || unsupportedKinds(others).length) {
       io.err('managed infrastructure native backing requires one postgres and only supported containerless services alongside it\n');
       return 1;
     }
+    /** The native backing's status: its containerless others serving and the postmaster's own proof (ownership, its
+     *  live group and identity, its port answering), then the status line; undefined when either does not hold. */
+    const nativeStatus = async (): Promise<string | undefined> => {
+      const ready = others.length === 0 || (await pgliteStatus(others, worldData)).ok;
+      if (!ready || !await nativePostgresStatus(worldData, signal)) return undefined;
+      postgresData = join(worldData, 'native-postgres-data');
+      return `${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...backingFact('native'), ...databaseFacts() })}\n`;
+    };
     try {
       if (phase === 'up') {
-        io.out(`managed infrastructure backing: native PostgreSQL (multi-session)${forcedBy('native')}\n`);
-        await nativePostgresUp(postgres, worldData, readFileSync(definition, 'utf8'), launch);
+        io.out(`managed infrastructure backing: native PostgreSQL (multi-session)${forcedBy('native')} (${chosen})\n`);
+        await nativePostgresUp(postgres, worldData, readFileSync(definition, 'utf8'), { ...launch, signal: launch.signal ? AbortSignal.any([launch.signal, twinFailed.signal]) : twinFailed.signal, onPlaced: startTwinsBeside });
         try { await pgliteUp(others, worldData, launch); }
         catch (error) {
           try { await nativePostgresDown(worldData); }
           catch (cleanup) { throw new AggregateError([error, cleanup], 'managed infrastructure startup and native cleanup failed'); }
           throw error;
         }
-        io.out('managed infrastructure ready\n');
+        nativeProof = nativeStatus;
+        sayReady();
       } else if (phase === 'status') {
-        const ready = others.length === 0 || (await pgliteStatus(others, worldData)).ok;
-        if (!ready || !await nativePostgresStatus(worldData)) return 1;
-        postgresData = join(worldData, 'native-postgres-data');
-        io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env), ...backingFact('native'), ...databaseFacts() })}\n`);
+        const text = await nativeStatus();
+        if (text === undefined) return 1;
+        io.out(text);
       } else {
         await pgliteDown(others, worldData);
-        await nativePostgresDown(worldData);
+        await nativePostgresDown(worldData, 'infra down');
+        worldEvent({ event: 'world.infra.down', backing: 'native', ms: Date.now() - phaseAsked });
         io.out('managed infrastructure stopped\n');
       }
       return 0;
@@ -379,7 +546,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     if (forcedBy('docker')) io.out(`managed infrastructure backing: container runtime${forcedBy('docker')}\n`);
     const result = await run(['up', '-d', '--wait', ...only]);
     if (result.status !== 0) return fail(result);
-    io.out('managed infrastructure ready\n');
+    sayReady();
   } else if (phase === 'status') {
     const expected = await run(['config', '--services']);
     if (expected.status !== 0) return fail(expected);
@@ -398,4 +565,42 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     io.out('managed infrastructure stopped\n');
   }
   return 0;
+  };
+  let code: number;
+  try { code = await databasePhase(); }
+  catch (error) {
+    if (phase === 'up' && mariaDB.length) {
+      try {
+        if (await runInfrastructure('down', env, { out: () => {}, err: io.err }) !== 0)
+          throw new Error('managed infrastructure failed-start teardown is unconfirmed');
+      } catch (cleanup) { throw new AggregateError([error, cleanup], 'native MariaDB sibling startup and retirement failed'); }
+    }
+    throw error;
+  }
+  if (code !== 0 && phase === 'up' && mariaDB.length) {
+    try {
+      if (await runInfrastructure('down', env, { out: () => {}, err: io.err }) !== 0)
+        io.err('managed infrastructure failed-start teardown is unconfirmed; ownership retained\n');
+    } catch (cleanup) { io.err(`managed MariaDB failed-start retirement: ${diagnostic(errorMessage(cleanup))}\n`); }
+  }
+  if (!twinsPending) { if (code === 0) await handOver(); return code; }
+  twinsPending = false;
+  if (code !== 0) {
+    // A database that failed after its twins began: they finish starting or fail (each retires its own half-started
+    // child, twinBackingUp), then come down with the rest, as when a twin fails, so no twin's process or receipt stays.
+    if (twinsBeside) {
+      await twinsBeside;
+      try { await runInfrastructure('down', env, { out: () => {}, err: io.err }, signal); } catch { /* the failure above is the one to report */ }
+    }
+    return code;
+  }
+  const twinsCode = await (twinsBeside ?? twinsPhase());
+  if (twinsCode !== 0) {
+    // The database came up and a twin did not: nothing of this `up` is left serving.
+    try { await runInfrastructure('down', env, { out: () => {}, err: io.err }, signal); } catch { /* the failure above is the one to report */ }
+    return twinsCode;
+  }
+  await handOver();
+  if (readyHeld) io.out('managed infrastructure ready\n');
+  return 0;
 }