@volter/world-runtime 2.0.18 → 2.0.19

package/dist/src/host-cli.js

@@ -28,11 +28,13 @@ for (let i = 0; i < argv.length; i++) {
     const [id, module, exportName, port, root, ...flags] = raw.split('|');
     const ro = flags.find((f) => f === 'ro');
     const scenarioPath = flags.find((f) => f.startsWith('scenario='))?.slice('scenario='.length);
+    // the World's managed database a pack declaring `managedDatabase` is bound to (runtime.ts, managedDatabaseFor)
+    const database = flags.find((f) => f.startsWith('database='))?.slice('database='.length);
     if (!id || !module || !exportName || !port || !root) {
-        process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>])\n`);
+        process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>][|database=<url>])\n`);
         process.exit(2);
     }
-    specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}) });
+    specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}), ...(database ? { database } : {}) });
 }
 if (specs.length === 0) {
     process.stderr.write('no --spec given\n');

package/dist/src/host-worker.js

@@ -11,6 +11,6 @@ if (typeof factory !== 'function') {
     throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
 }
 // Awaited: an async factory (fly) must post `ready` only once its listener is bound.
-const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly });
+const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.database !== undefined ? { database: spec.database } : {}) });
 parentPort?.postMessage({ type: 'ready', port: server.port });
 // The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/dist/src/host.d.ts

@@ -11,6 +11,9 @@ export type ColocatedTwinSpec = {
     /** The world's handlers file for a scenario-carrying (generative) twin — the colocate contract's
      *  scenarioPath (R2a): the same file the spawn path passes as --scenario. */
     scenarioPath?: string;
+    /** The World's managed database a pack declaring `managedDatabase` serves over (runtime.ts, managedDatabaseFor):
+     *  the colocated form of the spawn path's `serve <arg> <url>`. */
+    database?: string;
 };
 export type HostIsolation = 'shared' | 'worker';
 export type ColocatedHost = {

package/dist/src/host.js

@@ -62,7 +62,7 @@ export async function startColocatedHost(specs, options = {}) {
         const servers = [];
         for (const spec of specs) {
             const factory = await loadFactory(spec);
-            servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}) }));
+            servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
         }
         return {
             isolation,

package/dist/src/init.d.ts

@@ -184,9 +184,6 @@ export declare function packCatalog(root: string): string[];
  *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
  *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
  *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   supabase                  `SUPABASE_MGMT_TWIN_URL` — the MANAGEMENT (control-plane) twin only,
- *                             which is what this pack is; the DATA plane is the real local Supabase
- *                             stack and is emitted as an infra stub, not faked.
  *   livekit                   `LIVEKIT_URL` as a ws:// template — the media plane is a WebSocket
  *                             URL the SDK takes as its first constructor argument.
  *

package/dist/src/init.js

@@ -63,9 +63,6 @@ export function packCatalog(root) {
  *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
  *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
  *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   supabase                  `SUPABASE_MGMT_TWIN_URL` — the MANAGEMENT (control-plane) twin only,
- *                             which is what this pack is; the DATA plane is the real local Supabase
- *                             stack and is emitted as an infra stub, not faked.
  *   livekit                   `LIVEKIT_URL` as a ws:// template — the media plane is a WebSocket
  *                             URL the SDK takes as its first constructor argument.
  *
@@ -86,12 +83,6 @@ export const APP_READ_ENDPOINT_ENV = {
         injectEnv: 'AI_GATEWAY_BASE_URL',
         note: 'no injector entry: @ai-sdk/gateway is base-URL-configured through AI_GATEWAY_BASE_URL.',
     },
-    supabase: {
-        injectEnv: 'SUPABASE_MGMT_TWIN_URL',
-        note: 'CONTROL PLANE ONLY — this twin is the Supabase MANAGEMENT API. The DATA plane (Postgres/PostgREST/Storage) '
-            + 'is the REAL local Supabase stack: see the `//infra` supabase stub, fill in its `supabase start` lifecycle, and '
-            + 'move it into "services". Until then the proof reports supabase UNINTERCEPTABLE, which is the truth.',
-    },
     livekit: {
         injectEnvTemplates: { LIVEKIT_URL: 'ws://${host}:${port}' },
         note: 'no injector entry: LIVEKIT_URL is a ws:// endpoint the SDK takes directly — WebSocket media is outside the HTTP injector\'s reach.',

package/dist/src/pack-facts.d.ts

@@ -38,6 +38,12 @@ export type PackFacts = {
      *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
      *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
     serveExport?: string;
+    /** The World's managed database the runtime binds the twin to at boot (TwinPack.managedDatabase). */
+    managedDatabase?: {
+        kind: 'postgres';
+        arg: string;
+        note: string;
+    };
     /** R16: the protocol major the package targets and its standing against the kernel that compiled the artifact. */
     protocol?: {
         declared?: string;

package/dist/src/runtime.d.ts

@@ -75,6 +75,18 @@ export declare function sharingClaimAlive(claim: SharingClaim): boolean;
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
 export declare function saveWorldInstance(instance: WorldInstance): void;
+/**
+ * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
+ * twin whose pack declares `managedDatabase`, the URL of the World's own managed postgres — the service its
+ * `world.infrastructure.yml` declares, reached at the loopback URL the World's environment gives it (the connection
+ * `volter-world-infra` publishes, infraConnections). Read from the config beside the definition, never from the
+ * caller's environment; a World that declares no managed postgres, or whose database URL points outside it, binds
+ * nothing (undefined), and the twin refuses its data plane.
+ */
+export declare function managedDatabaseFor(vendor: string, configPath: string | undefined, env: Record<string, string | undefined>): {
+    arg: string;
+    url: string;
+} | undefined;
 export declare function upWorld(configId: string, options?: UpWorldOptions, abort?: AbortSignal): Promise<WorldInstance>;
 export declare function downWorld(name: string, root?: string, options?: {
     graceMs?: number;

package/dist/src/runtime.js

@@ -15,6 +15,7 @@ import { constants as osConstants, hostname as osHostname } from 'node:os';
 import { accessSync, appendFileSync, chmodSync, closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync, existsSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from "./pack-facts.js";
+import { infraConnections, parseInfraDefinition } from "./pglite-backing.js";
 import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
 import { Socket } from 'node:net';
 import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
@@ -1035,6 +1036,11 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
     const spawnedModule = (service.type ?? 'twin') === 'twin' ? spawnedTwinModule(service, paths.root) : undefined;
     const mounted = spawnedModule !== undefined ? lockfileCheck(service, spawnedModule) : {};
     const args = [...(service.args ?? [])];
+    if ((service.type ?? 'twin') === 'twin') {
+        const binding = managedDatabaseFor(vendorOfModule(spawnedModule, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
+        if (binding !== undefined)
+            args.push(binding.arg, binding.url);
+    }
     if (service.portArg !== false)
         args.push(service.portArg ?? '--port', String(port));
     if (service.rootArg !== false)
@@ -1185,6 +1191,33 @@ function spawnedTwinModule(service, root) {
     const first = (service.args ?? []).find((a) => /packages\/twin\/[^/]+\//.test(a) || /@volter\/twin-[^/]+\//.test(a));
     return first === undefined ? undefined : (first.startsWith('/') ? first : resolve(root, first));
 }
+/** The vendor a twin module belongs to (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>/…`), else the service id. */
+function vendorOfModule(modulePath, serviceId) {
+    const m = modulePath === undefined ? null : (/\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)(\/|$)/.exec(modulePath));
+    return m?.[1] ?? serviceId;
+}
+/**
+ * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
+ * twin whose pack declares `managedDatabase`, the URL of the World's own managed postgres — the service its
+ * `world.infrastructure.yml` declares, reached at the loopback URL the World's environment gives it (the connection
+ * `volter-world-infra` publishes, infraConnections). Read from the config beside the definition, never from the
+ * caller's environment; a World that declares no managed postgres, or whose database URL points outside it, binds
+ * nothing (undefined), and the twin refuses its data plane.
+ */
+export function managedDatabaseFor(vendor, configPath, env) {
+    const declared = packFacts()[vendor]?.managedDatabase;
+    if (declared === undefined || configPath === undefined)
+        return undefined;
+    const definition = join(dirname(configPath), 'world.infrastructure.yml');
+    if (!existsSync(definition))
+        return undefined;
+    const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((service) => service.kind === declared.kind);
+    if (services.length === 0)
+        return undefined;
+    const connections = infraConnections(services, env);
+    const url = Object.keys(connections).sort().map((name) => connections[name])[0];
+    return url === undefined ? undefined : { arg: declared.arg, url };
+}
 /**
  * The config as the runtime boots it (docs/concepts/worlds.md#the-config-and-the-running-world): a service
  * naming a `package` gets its entry and colocate module resolved from the world root NOW, by
@@ -1247,7 +1280,8 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         // catalog recorded for the package (pack-facts), refused two majors back, warned one back.
         const mounted = lockfileCheck(service, module);
         const scenario = service.colocate.scenarioPath;
-        args.push('--spec', [service.id, module, service.colocate.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : [])].join('|'));
+        const binding = managedDatabaseFor(vendorOfModule(module, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
+        args.push('--spec', [service.id, module, service.colocate.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : []), ...(binding !== undefined ? [`database=${binding.url}`] : [])].join('|'));
         allocated.push({ service, port, mounted });
     }
     const log = join(paths.logs, 'host.log');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.18",
+  "version": "2.0.19",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.11",
+    "@volter/world-core": "2.0.12",
     "@volter/world-console": "2.0.9"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.11",
+    "@volter/world-core": "2.0.12",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.11"
+    "@volter/twin-mongodb": "0.1.12"
   }
 }

package/src/host-cli.ts

@@ -30,11 +30,13 @@ for (let i = 0; i < argv.length; i++) {
   const [id, module, exportName, port, root, ...flags] = raw.split('|');
   const ro = flags.find((f) => f === 'ro');
   const scenarioPath = flags.find((f) => f.startsWith('scenario='))?.slice('scenario='.length);
+  // the World's managed database a pack declaring `managedDatabase` is bound to (runtime.ts, managedDatabaseFor)
+  const database = flags.find((f) => f.startsWith('database='))?.slice('database='.length);
   if (!id || !module || !exportName || !port || !root) {
-    process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>])\n`);
+    process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>][|database=<url>])\n`);
     process.exit(2);
   }
-  specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}) });
+  specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}), ...(database ? { database } : {}) });
 }
 if (specs.length === 0) { process.stderr.write('no --spec given\n'); process.exit(2); }
 

package/src/host-worker.ts

@@ -9,7 +9,7 @@ import { importModule } from './import-module.ts';
 const spec = workerData as ColocatedTwinSpec;
 
 type TwinServer = { port: number; stop: () => void | Promise<void> };
-type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; database?: string }) => TwinServer | Promise<TwinServer>;
 
 const mod = await importModule(spec.module);
 const factory = mod[spec.export] as TwinServerFactory | undefined;
@@ -18,7 +18,7 @@ if (typeof factory !== 'function') {
 }
 
 // Awaited: an async factory (fly) must post `ready` only once its listener is bound.
-const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly });
+const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.database !== undefined ? { database: spec.database } : {}) });
 parentPort?.postMessage({ type: 'ready', port: server.port });
 
 // The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/src/host.ts

@@ -37,6 +37,9 @@ export type ColocatedTwinSpec = {
   /** The world's handlers file for a scenario-carrying (generative) twin — the colocate contract's
    *  scenarioPath (R2a): the same file the spawn path passes as --scenario. */
   scenarioPath?: string;
+  /** The World's managed database a pack declaring `managedDatabase` serves over (runtime.ts, managedDatabaseFor):
+   *  the colocated form of the spawn path's `serve <arg> <url>`. */
+  database?: string;
 };
 
 export type HostIsolation = 'shared' | 'worker';
@@ -55,7 +58,7 @@ export type ColocatedHost = {
 // made host.stop() throw `s.stop is not a function`, turning every SIGTERM into downWorld's
 // SIGKILL escalation for the whole world).
 type TwinServer = { port: number; stop: () => void | Promise<void> };
-type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string }) => TwinServer | Promise<TwinServer>;
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string; database?: string }) => TwinServer | Promise<TwinServer>;
 
 async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
   const mod = await importModule(spec.module);
@@ -103,7 +106,7 @@ export async function startColocatedHost(
     const servers: TwinServer[] = [];
     for (const spec of specs) {
       const factory = await loadFactory(spec);
-      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}) }));
+      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
     }
     return {
       isolation,

package/src/init.ts

@@ -244,9 +244,6 @@ export function packCatalog(root: string): string[] {
  *   inngest                   `INNGEST_BASE_URL` (+ `INNGEST_EVENT_API_BASE_URL` for the event API)
  *                             — inngest@4's own apiBaseUrl/eventBaseUrl getters.
  *   ai-gateway                `AI_GATEWAY_BASE_URL` — `@ai-sdk/gateway`'s baseURL env.
- *   supabase                  `SUPABASE_MGMT_TWIN_URL` — the MANAGEMENT (control-plane) twin only,
- *                             which is what this pack is; the DATA plane is the real local Supabase
- *                             stack and is emitted as an infra stub, not faked.
  *   livekit                   `LIVEKIT_URL` as a ws:// template — the media plane is a WebSocket
  *                             URL the SDK takes as its first constructor argument.
  *
@@ -267,12 +264,6 @@ export const APP_READ_ENDPOINT_ENV: Record<string, { injectEnv?: string; injectE
     injectEnv: 'AI_GATEWAY_BASE_URL',
     note: 'no injector entry: @ai-sdk/gateway is base-URL-configured through AI_GATEWAY_BASE_URL.',
   },
-  supabase: {
-    injectEnv: 'SUPABASE_MGMT_TWIN_URL',
-    note: 'CONTROL PLANE ONLY — this twin is the Supabase MANAGEMENT API. The DATA plane (Postgres/PostgREST/Storage) '
-      + 'is the REAL local Supabase stack: see the `//infra` supabase stub, fill in its `supabase start` lifecycle, and '
-      + 'move it into "services". Until then the proof reports supabase UNINTERCEPTABLE, which is the truth.',
-  },
   livekit: {
     injectEnvTemplates: { LIVEKIT_URL: 'ws://${host}:${port}' },
     note: 'no injector entry: LIVEKIT_URL is a ws:// endpoint the SDK takes directly — WebSocket media is outside the HTTP injector\'s reach.',

package/src/pack-facts.ts

@@ -25,6 +25,8 @@ export type PackFacts = {
    *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
    *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
   serveExport?: string;
+  /** The World's managed database the runtime binds the twin to at boot (TwinPack.managedDatabase). */
+  managedDatabase?: { kind: 'postgres'; arg: string; note: string };
   /** R16: the protocol major the package targets and its standing against the kernel that compiled the artifact. */
   protocol?: { declared?: string; major: number; standing: 'current' | 'deprecated' | 'refused' | 'assumed' };
 };

package/src/runtime.ts

@@ -15,6 +15,7 @@ import { constants as osConstants, hostname as osHostname } from 'node:os';
 import { accessSync, appendFileSync, chmodSync, closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync, existsSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from './pack-facts.ts';
+import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
 import { describeServiceEnd, readServiceEnd, serviceOutput } from './service-exit.ts';
 import { Socket } from 'node:net';
 import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
@@ -1073,6 +1074,10 @@ async function startService(
   const mounted: MountedPackage = spawnedModule !== undefined ? lockfileCheck(service, spawnedModule) : {};
 
   const args = [...(service.args ?? [])];
+  if ((service.type ?? 'twin') === 'twin') {
+    const binding = managedDatabaseFor(vendorOfModule(spawnedModule, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
+    if (binding !== undefined) args.push(binding.arg, binding.url);
+  }
   if (service.portArg !== false) args.push(service.portArg ?? '--port', String(port));
   if (service.rootArg !== false) args.push(service.rootArg ?? '--root', serviceDataDir);
 
@@ -1205,6 +1210,32 @@ function spawnedTwinModule(service: WorldServiceConfig, root: string): string |
   return first === undefined ? undefined : (first.startsWith('/') ? first : resolve(root, first));
 }
 
+/** The vendor a twin module belongs to (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>/…`), else the service id. */
+function vendorOfModule(modulePath: string | undefined, serviceId: string): string {
+  const m = modulePath === undefined ? null : (/\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)(\/|$)/.exec(modulePath));
+  return m?.[1] ?? serviceId;
+}
+
+/**
+ * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
+ * twin whose pack declares `managedDatabase`, the URL of the World's own managed postgres — the service its
+ * `world.infrastructure.yml` declares, reached at the loopback URL the World's environment gives it (the connection
+ * `volter-world-infra` publishes, infraConnections). Read from the config beside the definition, never from the
+ * caller's environment; a World that declares no managed postgres, or whose database URL points outside it, binds
+ * nothing (undefined), and the twin refuses its data plane.
+ */
+export function managedDatabaseFor(vendor: string, configPath: string | undefined, env: Record<string, string | undefined>): { arg: string; url: string } | undefined {
+  const declared = packFacts()[vendor]?.managedDatabase;
+  if (declared === undefined || configPath === undefined) return undefined;
+  const definition = join(dirname(configPath), 'world.infrastructure.yml');
+  if (!existsSync(definition)) return undefined;
+  const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((service) => service.kind === declared.kind);
+  if (services.length === 0) return undefined;
+  const connections = infraConnections(services, env);
+  const url = Object.keys(connections).sort().map((name) => connections[name]!)[0];
+  return url === undefined ? undefined : { arg: declared.arg, url };
+}
+
 /**
  * The config as the runtime boots it (docs/concepts/worlds.md#the-config-and-the-running-world): a service
  * naming a `package` gets its entry and colocate module resolved from the world root NOW, by
@@ -1272,7 +1303,8 @@ async function startColocatedServices(
     // catalog recorded for the package (pack-facts), refused two majors back, warned one back.
     const mounted = lockfileCheck(service, module);
     const scenario = service.colocate!.scenarioPath;
-    args.push('--spec', [service.id, module, service.colocate!.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : [])].join('|'));
+    const binding = managedDatabaseFor(vendorOfModule(module, service.id), worldEnv.VOLTER_WORLD_CONFIG, config.env ?? {});
+    args.push('--spec', [service.id, module, service.colocate!.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : []), ...(binding !== undefined ? [`database=${binding.url}`] : [])].join('|'));
     allocated.push({ service, port, mounted });
   }