@volter/world-runtime 3.0.162 → 3.0.164

package/dist/src/infra.js

@@ -7,8 +7,9 @@
 // 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.js";
 import { signalChild } from './process-signal.mjs';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -142,11 +143,48 @@ export async function runInfrastructure(phase, env, io, signal) {
         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.js")).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`);
@@ -244,7 +282,7 @@ export async function runInfrastructure(phase, env, io, signal) {
         const { unsupportedKinds } = await import("./pglite-backing.js");
         const { nativePostgresTools } = await import("./native-postgres-backing.js");
         const postgres = declared.filter(s => s.kind === 'postgres');
-        if (postgres.length !== 1 || unsupportedKinds(declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s))).length)
+        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'));
@@ -287,7 +325,7 @@ export async function runInfrastructure(phase, env, io, signal) {
                 io.err(`managed infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
                 return 1;
             }
-            io.out('managed infrastructure ready\n');
+            sayReady();
             return 0;
         }
         if (phase === 'status') {
@@ -305,18 +343,76 @@ export async function runInfrastructure(phase, env, io, signal) {
         io.out('managed infrastructure stopped\n');
         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.js");
-    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'].filter(kind => declared.some(service => service.kind === kind));
+    const managed = env.VOLTER_WORLD_INFRA_BACKING === 'docker' || kinds.length === 0
+        ? undefined : await import("./twin-backing.js");
+    const protocols = {};
+    if (managed) {
+        if (kinds.includes('redis'))
+            protocols.redis = (await import("./redis-backing.js")).REDIS_PROTOCOL;
+        if (kinds.includes('mongodb'))
+            protocols.mongodb = (await import("./mongodb-backing.js")).MONGODB_PROTOCOL;
+        if (kinds.includes('clickhouse'))
+            protocols.clickhouse = (await import("./clickhouse-backing.js")).CLICKHOUSE_PROTOCOL;
+    }
+    const expectedTwinPackages = new Map();
+    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[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.js");
@@ -339,119 +435,293 @@ export async function runInfrastructure(phase, env, io, signal) {
             return 1;
         }
     }
-    if (twinned.length > 0) {
-        const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import("./redis-backing.js");
-        const cli = twinCli;
-        if (phase === 'up') {
-            io.out('managed infrastructure backing: redis twin (containerless)\n');
+    // 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;
+    /** 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 () => {
+        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.js")).nativeMariaDBStatus(mariaDB[0], worldData, worldConfig, launch))
+            return;
+        if (composed?.length === 0) {
+            io.verified(`${JSON.stringify(twinServedStatus())}\n`);
+            return;
+        }
+        if (!nativeProof)
+            return;
+        let text;
+        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;
+    // 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 = () => {
+        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 = () => { if (twinsPending)
+        readyHeld = true;
+    else
+        io.out('managed infrastructure ready\n'); };
+    const twinsPhase = async () => {
+        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);
+            }
+        }
+        return 0;
+    };
+    if (phase === 'up' && twins.length > 0)
+        twinsPending = true;
+    else {
+        const code = await twinsPhase();
+        if (code !== 0)
+            return code;
+    }
+    const databasePhase = async () => {
+        if (mariaDB.length) {
+            const { nativeMariaDBUp, nativeMariaDBStatus, nativeMariaDBDown } = await import("./native-mariadb-backing.js");
+            if (mariaDB.length !== 1) {
+                io.err('managed MariaDB needs one explicit native provider per World\n');
+                return 1;
+            }
             try {
-                await redisTwinUp(twinned, worldData, cli, launch);
+                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 infrastructure up failed: ${diagnostic(errorMessage(error))}\n`);
+                io.err(`managed MariaDB ${phase} failed: ${diagnostic(errorMessage(error))}\n`);
                 return 1;
             }
         }
+        if (composed?.length === 0) {
+            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.js");
+            const postgres = declared.filter(s => s.kind === 'postgres');
+            const others = declared.filter(s => s.kind !== 'postgres' && !s.nativeMariaDB && !twinned.includes(s));
+            const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import("./pglite-backing.js");
+            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 () => {
+                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')} (${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;
+                    }
+                    nativeProof = nativeStatus;
+                    sayReady();
+                }
+                else if (phase === 'status') {
+                    const text = await nativeStatus();
+                    if (text === undefined)
+                        return 1;
+                    io.out(text);
+                }
+                else {
+                    await pgliteDown(others, 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;
+            }
+            catch (error) {
+                io.err(`managed infrastructure ${phase} failed: ${diagnostic(errorMessage(error))}\n`);
+                return 1;
+            }
+        }
+        const only = composed ?? [];
+        if (phase === 'up') {
+            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);
+            sayReady();
+        }
         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`);
+            const expected = await run(['config', '--services']);
+            if (expected.status !== 0)
+                return fail(expected);
+            const running = await run(['ps', '--status', 'running', '--services']);
+            if (running.status !== 0)
+                return fail(running);
+            const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
+            const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
+            if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
+                io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length + native.length}/${expectedNames.length + twinned.length + native.length} declared services are ready\n`);
                 return 1;
             }
+            io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length + native.length, connections: infraConnections(declared, env), ...backingFact('docker'), ...databaseFacts() })}\n`);
         }
         else {
-            await redisTwinDown(twinned, worldData);
-        }
-    }
-    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`);
-        else
+            const result = await run(['down', '--remove-orphans']);
+            if (result.status !== 0)
+                return fail(result);
             io.out('managed infrastructure stopped\n');
+        }
         return 0;
+    };
+    let code;
+    try {
+        code = await databasePhase();
     }
-    const backing = await containerlessPostgres(await selectBacking());
-    if (typeof backing === 'number')
-        return backing;
-    if (backing === 'pglite')
-        return runPglite();
-    if (backing === 'native') {
-        const { nativePostgresUp, nativePostgresStatus, nativePostgresDown } = await import("./native-postgres-backing.js");
-        const postgres = declared.filter(s => s.kind === 'postgres');
-        const others = declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s));
-        const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import("./pglite-backing.js");
-        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;
-        }
-        try {
-            if (phase === 'up') {
-                io.out(`managed infrastructure backing: native PostgreSQL (multi-session)${forcedBy('native')}\n`);
-                await nativePostgresUp(postgres, worldData, readFileSync(definition, 'utf8'), launch);
-                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');
-            }
-            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`);
+    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');
             }
-            else {
-                await pgliteDown(others, worldData);
-                await nativePostgresDown(worldData);
-                io.out('managed infrastructure stopped\n');
+            catch (cleanup) {
+                throw new AggregateError([error, cleanup], 'native MariaDB sibling startup and retirement failed');
             }
-            return 0;
         }
-        catch (error) {
-            io.err(`managed infrastructure ${phase} failed: ${diagnostic(errorMessage(error))}\n`);
-            return 1;
+        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`);
         }
     }
-    const only = composed ?? [];
-    if (phase === 'up') {
-        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');
+    if (!twinsPending) {
+        if (code === 0)
+            await handOver();
+        return code;
     }
-    else if (phase === 'status') {
-        const expected = await run(['config', '--services']);
-        if (expected.status !== 0)
-            return fail(expected);
-        const running = await run(['ps', '--status', 'running', '--services']);
-        if (running.status !== 0)
-            return fail(running);
-        const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
-        const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
-        if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
-            io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length + native.length}/${expectedNames.length + twinned.length + native.length} declared services are ready\n`);
-            return 1;
+    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 */ }
         }
-        io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length + native.length, connections: infraConnections(declared, env), ...backingFact('docker'), ...databaseFacts() })}\n`);
+        return code;
     }
-    else {
-        const result = await run(['down', '--remove-orphans']);
-        if (result.status !== 0)
-            return fail(result);
-        io.out('managed infrastructure stopped\n');
+    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;
 }

package/dist/src/init.d.ts

@@ -1,3 +1,6 @@
+import { type NativeServerInputs } from './native-server-inputs.js';
+import { type GoMysqlBinding } from './go-mysql-binding.js';
+import { type OriginalInputReference } from './original-inputs.js';
 import { type CoverageReport } from './covers.js';
 import { type ProjectMigrationTool } from './project-inspect.js';
 import { type WorldConfig, type WorldServiceConfig } from './schema.js';
@@ -84,9 +87,31 @@ export type InitInfraStub = {
 export type InitComposeService = {
     kind: string;
     image: string;
+    /** An explicit MongoDB connection mode, also carried to the selected backing. */
+    replicaSet?: string;
     /** deterministic host port, derived from the world name (see composePort) */
     hostPort: number;
     containerPort: number;
+    virtualTcpEndpoint?: {
+        version: 1;
+        host: string;
+        port: number;
+        targetPort: number;
+    };
+    connectionBindings?: Record<string, GoMysqlBinding & {
+        containerPort: number;
+        query?: string;
+    }>;
+    sides?: Record<string, {
+        hostPort: number;
+        containerPort: number;
+    }>;
+    configuration?: Record<string, unknown>;
+    originalInputs?: OriginalInputReference;
+    originalInputsFrom?: string;
+    nativeServerInputs?: NativeServerInputs;
+    nativeServerInputsFrom?: string;
+    nativeCredentialAliases?: string[];
     memoryMiB: number;
     /** compose volume key, or null (the on-disk docker volume is `<project>_<key>` — the compose
      * project name carries the world name, so volumes are named per world) */
@@ -118,6 +143,12 @@ export type InitPlan = {
      *  (runtime.database.prepare): reported, never written, and no part of the vendor-coverage verdict */
     undeclaredMigrations: ProjectMigrationTool[];
     infra: InitInfraStub[];
+    /** each service of the project's own stack and what was made of it, where `--needs` gave the stack */
+    stackNeeds?: InitStackNeed[];
+    /** The same declared application names used by selection and its coverage proof. */
+    stackEnvironmentNames?: string[];
+    /** the project files a World made for an image left unread: the source does not hold them, so they are the person's own */
+    leftAsThePersonsOwn?: string[];
     /** the services emitted into the private managed-infrastructure definition */
     compose: InitComposeService[];
     /** private managed-infrastructure definition, or null when no detected infra has a recipe */
@@ -195,6 +226,21 @@ export type InitOptions = {
     sources?: Record<string, string>;
     /** A world with no app: served as `/<org>/<world>/`. */
     bare?: string;
+    /** The project's own stack as its image builder read it (`needs.json`): architecture, "The project's own stack as evidence". */
+    needs?: string;
+};
+/** One service of the project's stack, as `init` took it. */
+export type InitStackNeed = {
+    service: string;
+    image?: string;
+    family?: string;
+    /** the managed kind it is, or null where the World has none for it */
+    kind: string | null;
+    /** the application's variables given this service's address */
+    names: string[];
+    /** true where the stack named no variable and the conventional names were supplied */
+    conventional: boolean;
+    note: string;
 };
 /** The twins available at `root`, sorted — a deterministic input (catalog.ts: this checkout's
  * vendor directories in the pack repository, or the `@volter/twin-<vendor>` packages installed above root). */