@volter/world-runtime 3.0.162 → 3.0.164

package/src/go-mysql-binding.ts

@@ -0,0 +1,49 @@
+/** Source-declared Go MySQL connection bindings; architecture, managed infrastructure. */
+export type GoMysqlBinding = { dsnFormat: 'go-mysql'; endpoint: 'explicit-port' | 'default-port'; dsnPrefix: '' | 'mysql://'; dsnProtocol: '' | 'tcp' };
+
+/** Only versioned, explicitly typed data selects a driver grammar. */
+export function goMysqlBinding(entry: Record<string, unknown>, version: unknown, name: string, declaredPort: number): Partial<GoMysqlBinding> {
+  if (entry.dsnFormat === undefined) {
+    if (entry.endpoint !== undefined || entry.dsnPrefix !== undefined || entry.dsnProtocol !== undefined) throw new Error(`volter init: ${name} has DSN fields without a declared format`);
+    return {};
+  }
+  if ((version !== 6 && version !== 7) || entry.dsnFormat !== 'go-mysql' || entry.scheme !== 'mysql' || entry.withPort !== undefined
+    || (entry.endpoint !== 'explicit-port' && entry.endpoint !== 'default-port') || (entry.dsnPrefix !== '' && entry.dsnPrefix !== 'mysql://')
+    || (entry.dsnProtocol !== '' && entry.dsnProtocol !== 'tcp') || !Number.isInteger(entry.containerPort) || Number(entry.containerPort) < 1 || Number(entry.containerPort) > 65535
+    || (entry.endpoint === 'default-port' && entry.containerPort !== declaredPort)
+    || (entry.dsnPrefix === 'mysql://' && entry.endpoint === 'explicit-port')
+    || (entry.query !== undefined && (typeof entry.query !== 'string' || /[\u0000-\u001f\u007f]/u.test(entry.query)))) {
+    throw new Error(`volter init: ${name} needs a valid stack-needs version6/7 Go MySQL binding`);
+  }
+  return { dsnFormat: 'go-mysql', endpoint: entry.endpoint as GoMysqlBinding['endpoint'],
+    dsnPrefix: entry.dsnPrefix as GoMysqlBinding['dsnPrefix'], dsnProtocol: entry.dsnProtocol as GoMysqlBinding['dsnProtocol'] };
+}
+
+export function renderGoMysqlBinding(entry: GoMysqlBinding & { name: string; containerPort?: number; query?: string }, connection: URL, port: number): string {
+  if (connection.protocol !== 'mysql:' || entry.containerPort === undefined) throw new Error(`volter init: ${entry.name} needs a supplied MySQL endpoint and declared vendor port`);
+  if (entry.endpoint === 'default-port' && port !== entry.containerPort) throw new Error(`volter init: ${entry.name} needs a per-service host serving its declared default port; the shared-host high-port allocation cannot supply it`);
+  const user = decodeURIComponent(connection.username), password = decodeURIComponent(connection.password), database = decodeURIComponent(connection.pathname.slice(1));
+  if (!user || !password || !database || /[:\u0000-\u001f\u007f]/u.test(user) || /[\u0000-\u001f\u007f]/u.test(password)) throw new Error(`volter init: ${entry.name} cannot represent the supplied MySQL credentials in its declared driver grammar`);
+  if (entry.dsnPrefix === 'mysql://' && (entry.endpoint === 'explicit-port'
+    || !/^[A-Za-z0-9\-._~!$&'()*+,;=:%@]*$/u.test(`${user}:${password}`) || /%(?![A-Fa-f0-9]{2})/u.test(`${user}:${password}`))) {
+    throw new Error(`volter init: ${entry.name} cannot preserve its raw credentials/port through the declared mysql:// URL preparse`);
+  }
+  const address = `${connection.hostname}${entry.endpoint === 'explicit-port' ? `:${port}` : ''}`;
+  return `${entry.dsnPrefix}${user}:${password}@${entry.dsnProtocol}(${address})/${encodeURIComponent(database)}${entry.query !== undefined ? `?${entry.query}` : ''}`;
+}
+
+
+/** Match a declared DSN against its owned listener, never infer a grammar. */
+export function goMysqlEndpoint(value: string, binding: GoMysqlBinding, declaredPort: number): { host: string; port: number } | undefined {
+  if (/[\u0000-\u001f\u007f]/u.test(value) || !value.startsWith(binding.dsnPrefix)) return undefined;
+  const body = value.slice(binding.dsnPrefix.length), slash = body.lastIndexOf('/');
+  if (slash < 0) return undefined;
+  const authority = body.slice(0, slash), at = authority.lastIndexOf('@');
+  const transport = authority.slice(at + 1), begin = `${binding.dsnProtocol}(`;
+  if (!transport.startsWith(begin) || !transport.endsWith(')')) return undefined;
+  const endpoint = /^(?:\[([^\]\s]+)\]|([^:\s/?#()]+))(?::([0-9]{1,5}))?$/u.exec(transport.slice(begin.length, -1));
+  if (!endpoint || (binding.endpoint === 'default-port' && endpoint[3] !== undefined)
+    || (binding.endpoint === 'explicit-port' && endpoint[3] === undefined)) return undefined;
+  const port = endpoint[3] === undefined ? declaredPort : Number(endpoint[3]);
+  return port >= 1 && port <= 65535 ? { host: endpoint[1] ?? endpoint[2]!, port } : undefined;
+}

package/src/guest-processes.d.mts

@@ -5,5 +5,5 @@ export interface GuestProcessLaunch { path: string; record: Omit<GuestProcessRec
 export function guestProcessDirectory(instanceDir: string): string;
 export function beginGuestProcess(directory: string, instance: string, guest: string, kind: GuestProcessRecord['kind']): GuestProcessLaunch;
 export function retainGuestProcess(receipt: GuestProcessLaunch, identity: SpawnIdentity): void;
-export function readGuestProcesses(instanceDir: string, expectedInstance?: string): GuestProcessReceipt[];
+export function readGuestProcesses(instanceDir: string, expectedInstance?: string, onError?: (error: unknown) => void): GuestProcessReceipt[];
 export function releaseGuestProcesses(receipts: Array<{ path: string }>): void;

package/src/guest-processes.mjs

@@ -16,7 +16,9 @@ export function retainGuestProcess(receipt, identity) {
   receipt.record = { ...receipt.record, launching: false, ...identity };
   publishProcessReceipt(receipt.path, JSON.stringify(receipt.record));
 }
-export function readGuestProcesses(instanceDir, expectedInstance) {
+// Teardown can retain each refusal while joining the other independently valid receipts.
+// Other readers remain strict unless they explicitly collect these errors.
+export function readGuestProcesses(instanceDir, expectedInstance, onError) {
   const directory = guestProcessDirectory(instanceDir);
   if (!existsSync(directory)) return [];
   if (lstatSync(directory).isSymbolicLink()) throw new Error('Guest receipt directory is a symbolic link; ownership retained');
@@ -26,19 +28,25 @@ export function readGuestProcesses(instanceDir, expectedInstance) {
     try { expectedInstance = JSON.parse(readFileSync(join(instanceDir, 'instance.json'), 'utf8')).instance; }
     catch { throw new Error('Guest instance identity unreadable; ownership retained'); }
   }
-  return names.map(name => {
-    const path = join(directory, name);
-    if (!/^[0-9a-f-]+\.json$/.test(name) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw new Error('Unresolved guest receipt publication; ownership retained');
-    const receipt = readProcessReceipt(path, text => {
-      const r = JSON.parse(text);
-      if (r.instance !== expectedInstance || typeof r.guest !== 'string' || !['agent', 'command', 'pty'].includes(r.kind)
-        || r.launching || !Number.isInteger(r.pid) || r.pid < 1 || (r.start !== undefined && (typeof r.start !== 'string' || !r.start))) {
-        throw new Error('Guest launch or spawn identity unresolved');
-      }
-      return r;
-    });
-    if (receipt.error || !receipt.value) throw receipt.error ?? new Error('Guest receipt disappeared during inspection; ownership retained');
-    return { path, record: receipt.value };
+  return names.flatMap(name => {
+    try {
+      const path = join(directory, name);
+      if (!/^[0-9a-f-]+\.json$/.test(name) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw new Error('Unresolved guest receipt publication; ownership retained');
+      const receipt = readProcessReceipt(path, text => {
+        const r = JSON.parse(text);
+        if (r.instance !== expectedInstance || typeof r.guest !== 'string' || !['agent', 'command', 'pty'].includes(r.kind)
+          || r.launching || !Number.isInteger(r.pid) || r.pid < 1 || (r.start !== undefined && (typeof r.start !== 'string' || !r.start))) {
+          throw new Error('Guest launch or spawn identity unresolved');
+        }
+        return r;
+      });
+      if (receipt.error || !receipt.value) throw receipt.error ?? new Error('Guest receipt disappeared during inspection; ownership retained');
+      return [{ path, record: receipt.value }];
+    } catch (error) {
+      if (!onError) throw error;
+      onError(error);
+      return [];
+    }
   });
 }
 // The caller must have confirmed each recorded group absent before releasing these receipts.

package/src/host-cli.ts

@@ -15,6 +15,9 @@ import { dirname, join } from 'node:path';
 import { startColocatedHost, type ColocatedTwinSpec, type HostIsolation } from './host.ts';
 import { publishHostReady } from './host-ready.ts';
 
+// When this entry runs: the host's own modules are loaded; each twin's are loaded by its factory (S2 R38).
+const began = Date.now();
+const startedAt: Record<string, number> = {};
 const argv = process.argv.slice(2);
 const opt = (name: string, fb = ''): string => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1]! : fb; };
 
@@ -82,6 +85,7 @@ function recordGaveUp(twin: string, exits: number, detail: string): void {
 const host = await startColocatedHost(specs, {
   isolation,
   onEvent: (e) => {
+    if (e.kind === 'started') startedAt[e.twin] = Date.now();
     process.stdout.write(`event twin=${e.twin} kind=${e.kind}${e.detail ? ` detail=${e.detail}` : ''}\n`);
     if (e.kind === 'gaveup') recordGaveUp(e.twin, e.exits ?? 0, e.detail ?? '');
   },
@@ -91,9 +95,11 @@ process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
 const readyFile = opt('--ready-file');
 if (readyFile) {
-  try { publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports); }
+  try { publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports, { began, started: startedAt }, host.streams); }
   catch (error) { await host.stop(); throw error; }
 }
+// the twins' cold first requests, taken in the host's idle time after its receipt rather than by the application's first calls
+void host.warm();
 for (const [id, port] of Object.entries(host.ports)) process.stdout.write(`ready id=${id} port=${port}\n`);
 process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 await keepProcessAlive();

package/src/host-ready.ts

@@ -1,12 +1,22 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { type FSWatcher, mkdirSync, readFileSync, renameSync, watch, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
+/** When the host's own start reached each step, in epoch milliseconds: its entry running (its static modules loaded),
+ *  and each twin's factory returning. */
+export type HostStartTimes = { began: number; started: Record<string, number> };
+
+/** What a receipt says of the host's start, for the runtime's progress line, and which of its twins' main ports are byte
+ *  streams (host.ts servesByteStream), for their admission; absent from a host that predates it. */
+export type HostReadyTimes = { at?: number; streams?: string[] } & Partial<HostStartTimes>;
+
 /** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
-export function publishHostReady(path: string, boot: string, ports: Record<string, number>): void {
+export function publishHostReady(path: string, boot: string, ports: Record<string, number>, times?: HostStartTimes, streams?: readonly string[]): void {
   if (!boot) throw new Error('A co-located host readiness receipt requires its World boot identity.');
   mkdirSync(dirname(path), { recursive: true });
   const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
+  // `at`, when it was published, lets the runtime say how long its read came after, and `times` where the host's own
+  // start went before it (S2 R28, R38).
+  writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports, at: Date.now(), ...times, ...(streams?.length ? { streams } : {}) })}\n`, { mode: 0o600 });
   renameSync(temporary, path);
 }
 
@@ -16,35 +26,56 @@ export function publishHostReady(path: string, boot: string, ports: Record<strin
  * one: each change in `progress` (the host log's size, which grows with every
  * twin it starts) begins the bound again, so a host still starting its twins
  * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ * Resolves with what the receipt says of the host's start: when it was published, its steps before, and which declared
+ * twins' main ports are byte streams.
  */
-export async function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress: () => number = () => 0): Promise<void> {
-  let started = Date.now();
-  let seen = progress();
-  for (;;) {
-    abort.throwIfAborted();
-    let bytes: Buffer | undefined;
-    try { bytes = readFileSync(path); }
-    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
-    if (bytes) {
-      if (bytes.byteLength > 256 * 1024) throw new Error('The co-located host readiness receipt exceeds its bounds.');
-      const value = JSON.parse(bytes.toString('utf8')) as { version?: unknown; boot?: unknown; ports?: unknown } | null;
-      if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
-        throw new Error('The co-located host readiness receipt does not belong to this boot.');
-      }
-      const answered = value.ports as Record<string, unknown>;
-      if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
-        throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+export async function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress: () => number = () => 0): Promise<HostReadyTimes> {
+  // A change in the receipt's directory (the host's rename is one) wakes the wait at once, where the 25 ms timer
+  // alone left a published receipt unread for up to a tick (S2 R28). The timer stays: a filesystem that gives no
+  // change events is read as before. Any other write in the directory wakes it too, and costs one read.
+  let wake: (() => void) | undefined;
+  let watcher: FSWatcher | undefined;
+  try {
+    watcher = watch(dirname(path), { persistent: false }, () => wake?.());
+    watcher.on('error', () => { watcher?.close(); watcher = undefined; });
+  } catch { /* no change events here: the timer alone */ }
+  try {
+    let started = Date.now();
+    let seen = progress();
+    for (;;) {
+      abort.throwIfAborted();
+      let bytes: Buffer | undefined;
+      try { bytes = readFileSync(path); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (bytes) {
+        if (bytes.byteLength > 256 * 1024) throw new Error('The co-located host readiness receipt exceeds its bounds.');
+        const value = JSON.parse(bytes.toString('utf8')) as { version?: unknown; boot?: unknown; ports?: unknown; at?: unknown; began?: unknown; started?: unknown; streams?: unknown } | null;
+        if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
+          throw new Error('The co-located host readiness receipt does not belong to this boot.');
+        }
+        const answered = value.ports as Record<string, unknown>;
+        if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
+          throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+        }
+        const when = (time: unknown): number | undefined => typeof time === 'number' && Number.isFinite(time) ? time : undefined;
+        // only the declared twins' times: an id the runtime did not declare never reaches its progress line
+        const twinStarts = value.started && typeof value.started === 'object' && !Array.isArray(value.started)
+          ? Object.fromEntries(Object.entries(value.started as Record<string, unknown>).flatMap(([id, time]) => !ports.has(id) || when(time) === undefined ? [] : [[id, time as number]]))
+          : undefined;
+        const streams = Array.isArray(value.streams) ? value.streams.filter((id): id is string => typeof id === 'string' && ports.has(id)) : [];
+        return { at: when(value.at), began: when(value.began), ...(twinStarts ? { started: twinStarts } : {}), ...(streams.length ? { streams } : {}) };
       }
-      return;
+      const now = progress();
+      if (now !== seen) { seen = now; started = Date.now(); }
+      if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host made no progress for ${timeoutMs} ms before completing every declared start.`);
+      await new Promise<void>((resolve, reject) => {
+        const settle = (): void => { clearTimeout(timer); wake = undefined; abort.removeEventListener('abort', cancel); };
+        const cancel = (): void => { settle(); reject(abort.reason); };
+        const timer = setTimeout(() => { settle(); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
+        wake = () => { settle(); resolve(); };
+        abort.addEventListener('abort', cancel, { once: true });
+        if (abort.aborted) cancel();
+      });
     }
-    const now = progress();
-    if (now !== seen) { seen = now; started = Date.now(); }
-    if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host made no progress for ${timeoutMs} ms before completing every declared start.`);
-    await new Promise<void>((resolve, reject) => {
-      const cancel = (): void => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
-      const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
-      abort.addEventListener('abort', cancel, { once: true });
-      if (abort.aborted) cancel();
-    });
-  }
+  } finally { watcher?.close(); }
 }

package/src/host-worker.ts

@@ -4,7 +4,7 @@ import { getPack, registerPack, type TwinPack } from '@volter/world-core/runtime
 // host does NOT restart it: it gives up on the worker (fires a `gaveup` event → doctor
 // red) without disturbing sibling twins. Posts {type:'ready'} once listening.
 import { parentPort, workerData } from 'node:worker_threads';
-import type { ColocatedTwinSpec } from './host.ts';
+import { servesByteStream, servesDiscovery, warmInProcess, type ColocatedTwinSpec } from './host.ts';
 import { importModule } from './import-module.ts';
 
 const spec = workerData as ColocatedTwinSpec;
@@ -23,6 +23,10 @@ if (typeof factory !== 'function') {
 
 // Awaited: an async factory (fly) must post `ready` only once its listener is bound.
 const server = await factory({ ...(spec.sideOptions ?? {}), port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.database !== undefined ? { database: spec.database } : {}) });
-parentPort?.postMessage({ type: 'ready', port: server.port });
+parentPort?.postMessage({ type: 'ready', port: server.port, byteStream: servesByteStream(mod, descriptor), discovery: servesDiscovery(mod, descriptor) });
+// the host's warm-up, taken here where this twin's server and its handler are (host.ts warmInProcess)
+parentPort?.on('message', (msg: { type?: string }) => {
+  if (msg?.type === 'warm') void warmInProcess(server.port).then(() => parentPort?.postMessage({ type: 'warmed' }));
+});
 
 // The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/src/host.ts

@@ -1,5 +1,5 @@
 import { errorMessage } from './error-message.ts';
-import { getPack, registerPack, type TwinPack } from '@volter/world-core/runtime';
+import { getPack, registerPack, servedHandlerOf, type TwinPack } from '@volter/world-core/runtime';
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
 // `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
@@ -53,6 +53,12 @@ export type ColocatedHost = {
   isolation: HostIsolation;
   /** Resolved listening port per twin id (equals the requested port). */
   ports: Record<string, number>;
+  /** The twins whose main port is a byte stream (servesByteStream). */
+  streams: string[];
+  /** The twins whose main port answers the discovery door (GET /twin: the manifest declares `discovery`), warmed by it. */
+  discoverable: string[];
+  /** Warm every discoverable twin (warmInProcess, in its own thread under worker isolation); never needed for readiness. */
+  warm: () => Promise<void>;
   stop: () => Promise<void>;
 };
 
@@ -65,7 +71,58 @@ export type ColocatedHost = {
 type TwinServer = { port: number; stop: () => void | Promise<void> };
 type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string; database?: string; [side: string]: unknown }) => TwinServer | Promise<TwinServer>;
 
-async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
+/** Whether a twin's main port is a byte stream: a raw-tcp pack exporting exactly one `create<Name>TwinStream` is taken
+ *  to serve that stream there (world-core serveStream: an SMTP relay greets, a Redis server answers RESP). Such a port
+ *  cannot answer an HTTP request, so the runtime admits it by its TCP answer (runtime.ts, startColocatedServices). Read
+ *  off the module's own exports, as its serve factory is (twin-standard pack-facts.ts serveExport). A pack whose main
+ *  port serves HTTP or gRPC must not declare raw-tcp with a stream export (create-pack refuses it). */
+export function servesByteStream(mod: Record<string, unknown>, descriptor: TwinPack): boolean {
+  return descriptor.transport === 'raw-tcp'
+    && Object.keys(mod).filter((key) => /^create\w*TwinStream$/.test(key) && typeof mod[key] === 'function').length === 1;
+}
+
+/** Whether a twin's main port answers the discovery door: its manifest declares `discovery`, and its port is HTTP. */
+export function servesDiscovery(mod: Record<string, unknown>, descriptor: TwinPack): boolean {
+  const manifest = mod.manifest as { discovery?: unknown } | undefined;
+  return manifest?.discovery !== undefined && !servesByteStream(mod, descriptor);
+}
+
+/** The most twins warmed at once (S2 R41). */
+const WARM_CONCURRENCY = 2;
+/** A warm-up's bound: one that has not finished by then is left, its twin as it is. */
+const WARM_TIMEOUT_MS = 2000;
+
+/**
+ * Each twin's first request pays its pipeline's cold start (decoding, routing, the pack's front, first-run code), which
+ * otherwise falls on the application's first call to it. Its size for an HTTP twin is unmeasured (a byte-stream twin's
+ * first SMTP greeting took 57 ms against 1.8 ms later, e946aa4c run 3 on the mini, but that twin is skipped here); the
+ * R38 timing lap sizes it. The host takes it in its own idle time once its
+ * receipt is published: one GET of the twin's discovery door, handed in this process to the handler serving its port
+ * (world-core servedHandlerOf), never on the wire and never in its request journal. Bounded, its answer and any failure
+ * ignored; a request the application sends first is served as it would have been, and simply is that twin's warm-up.
+ * The discovery door reads no stored state, so a twin's first state read stays cold.
+ */
+export async function warmInProcess(port: number): Promise<void> {
+  const handler = servedHandlerOf(port);
+  if (!handler) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      (async () => { const response = await handler(new Request(`http://127.0.0.1:${port}/twin`)); await response?.arrayBuffer(); })(),
+      new Promise<void>((resolve) => { timer = setTimeout(resolve, WARM_TIMEOUT_MS); timer.unref?.(); }),
+    ]);
+  } catch { /* a warm-up that fails leaves its twin as it was */ } finally { if (timer !== undefined) clearTimeout(timer); }
+}
+
+/** Each of `ids` warmed by `warm`, at most WARM_CONCURRENCY at once. */
+async function warmEach(ids: readonly string[], warm: (id: string) => Promise<void>): Promise<void> {
+  const queue = [...ids];
+  await Promise.all(Array.from({ length: Math.min(WARM_CONCURRENCY, queue.length) }, async () => {
+    for (let id = queue.shift(); id !== undefined; id = queue.shift()) await warm(id);
+  }));
+}
+
+async function loadFactory(spec: ColocatedTwinSpec): Promise<{ factory: TwinServerFactory; byteStream: boolean; discovery: boolean }> {
   const mod = await importModule(spec.module);
   const descriptor = mod.pack as TwinPack | undefined ?? getPack(spec.id);
   if (!descriptor || descriptor.vendor !== spec.id) throw new Error(`Twin ${spec.id}: the loaded module declares no matching pack descriptor`);
@@ -74,7 +131,7 @@ async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory>
   if (typeof factory !== 'function') {
     throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
   }
-  return factory as TwinServerFactory;
+  return { factory: factory as TwinServerFactory, byteStream: servesByteStream(mod, descriptor), discovery: servesDiscovery(mod, descriptor) };
 }
 
 const workerEntry = (): URL => pathToFileURL(siblingScript(import.meta.url, 'host-worker'));
@@ -100,6 +157,8 @@ export async function startColocatedHost(
   const onEvent = options.onEvent ?? (() => {});
   const ports: Record<string, number> = {};
   for (const spec of specs) ports[spec.id] = spec.port;
+  const streams: string[] = [];
+  const discoverable: string[] = [];
 
   if (isolation === 'shared') {
     // Keep one twin's stray async rejection / uncaught throw from killing every other twin in
@@ -128,7 +187,9 @@ export async function startColocatedHost(
     };
     try {
       await parallelStartup(specs, async (spec) => {
-        const factory = await loadFactory(spec);
+        const { factory, byteStream, discovery } = await loadFactory(spec);
+        if (byteStream) streams.push(spec.id);
+        if (discovery) discoverable.push(spec.id);
         const server = await factory({ ...(spec.sideOptions ?? {}), port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
         // Record the handle before validating it, so rollback also owns a bad factory result.
         servers.push(server);
@@ -148,6 +209,9 @@ export async function startColocatedHost(
     return {
       isolation,
       ports,
+      streams,
+      discoverable,
+      warm: () => warmEach(discoverable, (id) => warmInProcess(ports[id]!)),
       stop: async () => {
         // Every stop runs, even when a sibling hangs or throws. Host shutdown
         // still resolves within its budget so the owning runtime can retire it.
@@ -169,13 +233,18 @@ export async function startColocatedHost(
       // below would emit a 2nd `spawn` for the same twin, which the isolation test asserts against.
       onEvent({ twin: spec.id, kind: 'spawn', detail: 'worker started' });
       let ready = false;
-      worker.on('message', (msg: { type?: string; port?: number }) => {
+      worker.on('message', (msg: { type?: string; port?: number; byteStream?: boolean; discovery?: boolean }) => {
         if (msg?.type === 'ready') {
           if (typeof msg.port !== 'number' || !Number.isInteger(msg.port) || msg.port < 1 || msg.port > 65535 || (spec.port !== 0 && msg.port !== spec.port)) {
             rejectReady(new Error(`Twin "${spec.id}" bound port ${msg.port}, requested ${spec.port}.`)); return;
           }
           ports[spec.id] = msg.port;
-          ready = true; resolveReady();
+          if (msg.byteStream === true) streams.push(spec.id);
+          if (msg.discovery === true) discoverable.push(spec.id);
+          ready = true;
+          // the same progress, and the same start time for the receipt (host-cli.ts), as a shared twin's start
+          onEvent({ twin: spec.id, kind: 'started', detail: `port ${msg.port} at ${Math.round(performance.now())} ms` });
+          resolveReady();
         }
       });
       worker.on('error', (err) => {
@@ -205,6 +274,19 @@ export async function startColocatedHost(
   return {
     isolation,
     ports,
+    streams,
+    discoverable,
+    // a worker twin is warmed in its own thread, where its server's handler is: asked, and answered once done
+    warm: () => warmEach(discoverable, (id) => new Promise<void>((resolve) => {
+      const worker = workers.get(id);
+      if (!worker) { resolve(); return; }
+      const done = (): void => { clearTimeout(timer); worker.off('message', warmed); worker.off('exit', done); resolve(); };
+      const warmed = (msg: { type?: string }): void => { if (msg?.type === 'warmed') done(); };
+      const timer = setTimeout(done, WARM_TIMEOUT_MS);
+      worker.on('message', warmed);
+      worker.once('exit', done);
+      try { worker.postMessage({ type: 'warm' }); } catch { done(); }
+    })),
     stop: async () => {
       stopping.value = true;
       await Promise.all([...workers.values()].map((w) => w.terminate()));

package/src/infra-definition.ts

@@ -0,0 +1,135 @@
+import { goMysqlBinding, goMysqlEndpoint, type GoMysqlBinding } from './go-mysql-binding.ts';
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+// Definition metadata is independent of database host lifetimes.
+import { createRequire } from 'node:module';
+import { nativeMariaDBReference } from './mariadb-supplier.ts';
+import { mariaDBCredentials } from './mariadb-bootstrap.ts';
+import type { NativeMariaDBService } from './native-mariadb-backing.ts';
+
+export interface InfraService { kind: string; hostPort: number; nativeMariaDB?: NativeMariaDBService; virtualTcpEndpoint?: { version: 1; host: string; port: number; targetPort: number }; connectionBindings?: Record<string, GoMysqlBinding & { containerPort: number }>; originalInputs?: managedOriginalInputs.OriginalInputReference; sides?: Record<string, { hostPort: number; containerPort: number }>; configuration?: Record<string, unknown>; replicaSet?: string; postgres?: { user: string; database: string; password?: string } }
+
+/** Read the generated definition's loopback port mappings and backing-independent options.
+ *  The Compose extension carries a MongoDB replica-set name. Older generated commands remain readable. */
+export function parseInfraDefinition(text: string): InfraService[] {
+  const { parse } = createRequire(import.meta.url)('yaml') as typeof import('yaml');
+  const definition = parse(text);
+  const services: InfraService[] = [];
+  for (const [kind, value] of Object.entries(definition?.services ?? {})) {
+    const declared = value as { image?: unknown; ports?: unknown[]; command?: unknown; entrypoint?: unknown; volumes?: unknown; 'x-volter-native-server'?: unknown; 'x-volter-replica-set'?: unknown; environment?: Record<string, unknown>; 'x-volter-interfaces'?: unknown; 'x-volter-side-ports'?: unknown; 'x-volter-configuration'?: unknown; 'x-volter-original-inputs'?: unknown; 'x-volter-issued-dsn-bindings'?: unknown; 'x-volter-virtual-tcp-endpoint'?: unknown };
+    const nativeReference = declared['x-volter-native-server'] === undefined ? undefined : nativeMariaDBReference(declared['x-volter-native-server']);
+    if (nativeReference && (kind !== 'mysql' || declared['x-volter-interfaces'] !== 3 || typeof declared.image !== 'string'
+      || !/^(?:docker\.io\/)?(?:library\/)?mariadb(?::[^@]+)?@sha256:[a-f0-9]{64}$/u.test(declared.image)))
+      throw new Error('Managed native MariaDB needs mysql, infrastructure interface3 and its exact declared image');
+    const originalInputs = declared['x-volter-original-inputs'] === undefined ? undefined : managedOriginalInputs.referenceOf(declared['x-volter-original-inputs']);
+    if (originalInputs && declared['x-volter-interfaces'] !== 2) throw new Error('Managed original inputs require infrastructure interface2');
+    const option = declared['x-volter-replica-set'];
+    if (option !== undefined && (kind !== 'mongodb' || typeof option !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(option))) {
+      throw new Error('World-managed replica-set metadata must name one valid MongoDB replica set');
+    }
+    let replicaSet = option as string | undefined;
+    if (kind === 'mongodb' && declared.command !== undefined) {
+      const command = declared.command;
+      if (!Array.isArray(command) || command.length !== 3 || command[0] !== 'mongod' || command[1] !== '--replSet'
+        || typeof command[2] !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(command[2])) {
+        throw new Error('World-managed MongoDB command must be ["mongod", "--replSet", "<name>"] or absent for standalone');
+      }
+      if (replicaSet !== undefined && replicaSet !== command[2]) throw new Error('World-managed MongoDB command and replica-set metadata disagree');
+      replicaSet = command[2];
+    }
+    const mapped = (declared.ports ?? []).flatMap((port) => {
+      const match = typeof port === 'string' ? port.match(/^127\.0\.0\.1:(\d+):(\d+)$/) : null;
+      if ((kind === 'clickhouse' || nativeReference) && (!match || ![Number(match[1]), Number(match[2])].every(value => Number.isInteger(value) && value > 0 && value <= 65535))) throw new Error(`managed infrastructure ${kind} has an invalid loopback port`);
+      // Other kinds retain their earlier reader: unrecognized mappings are skipped.
+      return match ? [{ hostPort: Number(match[1]), containerPort: Number(match[2]) }] : [];
+    });
+    let sides: InfraService['sides'], configuration: InfraService['configuration'];
+    if (kind === 'clickhouse') {
+      if (declared['x-volter-interfaces'] !== (originalInputs ? 2 : 1) || mapped.length !== 2 || mapped[0]!.containerPort !== 8123 || mapped[1]!.containerPort !== 9000 || mapped[0]!.hostPort === mapped[1]!.hostPort)
+        throw new Error('Managed ClickHouse needs named-interface version1, HTTP8123 and native9000 mappings');
+      const raw = declared['x-volter-side-ports'] as Record<string, unknown> | undefined;
+      const native = raw?.native as { hostPort?: unknown; containerPort?: unknown } | undefined;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw) || Object.keys(raw).join() !== 'native' || !native || native.hostPort !== mapped[1]!.hostPort || native.containerPort !== 9000)
+        throw new Error('Managed ClickHouse native side metadata differs from its declared port');
+      sides = { native: mapped[1]! };
+      const input = declared['x-volter-configuration'];
+      if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Managed ClickHouse needs explicit operator configuration');
+      configuration = input as Record<string, unknown>;
+    } else if (mapped.length !== 1 || declared['x-volter-interfaces'] !== (nativeReference ? 3 : originalInputs ? 2 : undefined) || declared['x-volter-side-ports'] !== undefined || declared['x-volter-configuration'] !== undefined) {
+      throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port and no multiwire metadata`);
+    }
+    const ports = mapped.map(port => port.hostPort);
+    let nativeMariaDB: NativeMariaDBService | undefined;
+    if (nativeReference) {
+      if (mapped[0]!.containerPort !== 3306 || originalInputs || declared.command !== undefined || declared.entrypoint !== undefined)
+        throw new Error('Managed native MariaDB has an unconsumed port, original-input, command or entrypoint requirement');
+      const volumes = declared.volumes;
+      if (volumes !== undefined && (!Array.isArray(volumes) || volumes.length !== 1
+        || volumes[0] !== '${VOLTER_WORLD_DATA:?}/native-mariadb-data:/var/lib/mysql'))
+        throw new Error('Managed native MariaDB has an unconsumed source mount requirement');
+      nativeMariaDB = { hostPort: ports[0]!, image: declared.image as string,
+        reference: nativeReference, credentials: mariaDBCredentials(declared.environment ?? {}) };
+    }
+    const virtual = declared['x-volter-virtual-tcp-endpoint'] as Record<string, unknown> | undefined;
+    let virtualTcpEndpoint: InfraService['virtualTcpEndpoint'];
+    if (virtual !== undefined) {
+      if (!virtual || typeof virtual !== 'object' || Array.isArray(virtual) || Object.keys(virtual).sort().join() !== 'host,port,targetPort,version'
+        || virtual.version !== 1 || typeof virtual.host !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}\.world\.volter\.internal$/.test(virtual.host)
+        || virtual.port !== mapped[0]!.containerPort || virtual.targetPort !== mapped[0]!.hostPort) throw new Error(`Managed ${kind} virtual TCP endpoint differs from its owned listener`);
+      virtualTcpEndpoint = { version: 1, host: virtual.host, port: Number(virtual.port), targetPort: Number(virtual.targetPort) };
+    }
+    let postgres: InfraService['postgres'];
+    if (kind === 'postgres') {
+      const environment = declared.environment ?? {};
+      const user = environment.POSTGRES_USER ?? 'postgres';
+      const database = environment.POSTGRES_DB ?? user;
+      const password = environment.POSTGRES_PASSWORD;
+      if ([user, database, password].some(value => value !== undefined && (typeof value !== 'string' || !value || /[\r\n\0]|\$\{/.test(value)))) {
+        throw new Error('World-managed PGlite requires literal POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD');
+      }
+      if ([user, database].some(value => Buffer.byteLength(value as string, 'utf8') > 63)) throw new Error('World-managed PGlite identifiers must fit PostgreSQL\'s 63-byte name limit');
+      postgres = { user: user as string, database: database as string, ...(password !== undefined ? { password: password as string } : {}) };
+    }
+    const typed = declared['x-volter-issued-dsn-bindings'];
+    let connectionBindings: Record<string, GoMysqlBinding & { containerPort: number }> | undefined;
+    if (typed !== undefined) {
+      if (kind !== 'mysql' || !typed || typeof typed !== 'object' || Array.isArray(typed)) throw new Error('Managed DSN bindings need a declared MySQL service');
+      connectionBindings = Object.create(null);
+      for (const [name, value] of Object.entries(typed)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid managed DSN binding');
+        const row = value as Record<string, unknown>;
+        const parsed = goMysqlBinding({ ...row, scheme: 'mysql' }, 6, name, mapped[0]!.containerPort);
+        if (!parsed.dsnFormat || Object.keys(row).some(key => !['dsnFormat', 'endpoint', 'dsnPrefix', 'dsnProtocol', 'containerPort', 'query'].includes(key))) throw new Error(`Invalid managed DSN declaration for ${name}`);
+        connectionBindings![name] = { ...parsed as GoMysqlBinding, containerPort: mapped[0]!.containerPort };
+      }
+    }
+    services.push({ kind, ...(nativeMariaDB ? { nativeMariaDB } : {}), ...(virtualTcpEndpoint ? { virtualTcpEndpoint } : {}), ...(connectionBindings ? { connectionBindings } : {}), ...(originalInputs ? { originalInputs } : {}), hostPort: ports[0]!, ...(sides ? { sides } : {}), ...(configuration ? { configuration } : {}), ...(replicaSet ? { replicaSet } : {}), ...(postgres ? { postgres } : {}) });
+  }
+  return services;
+}
+
+/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
+ * whose protocol and loopback port match a declared service belong to this lifecycle. */
+export function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string> {
+  const connections: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) continue;
+    const typed = services.filter(service => service.connectionBindings?.[name] !== undefined);
+    if (typed.length > 1) throw new Error(`Managed DSN ${name} belongs to multiple infrastructure services`);
+    if (typed.length === 1) {
+      const service = typed[0]!, endpoint = goMysqlEndpoint(value, service.connectionBindings![name]!, service.connectionBindings![name]!.containerPort);
+      const virtual = service.virtualTcpEndpoint, binding = service.connectionBindings![name]!;
+      const expectedHost = binding.endpoint === 'default-port' && virtual ? virtual.host : '127.0.0.1';
+      const expectedPort = binding.endpoint === 'default-port' && virtual ? virtual.port : service.hostPort;
+      if (!endpoint || endpoint.host !== expectedHost || endpoint.port !== expectedPort) throw new Error(`Managed DSN ${name} does not match its owned endpoint`);
+      connections[name] = value;
+      continue;
+    }
+    try {
+      const url = new URL(value);
+      if (url.hostname !== '127.0.0.1') continue;
+      const kind = url.protocol === 'postgresql:' ? 'postgres' : url.protocol.slice(0, -1);
+      if (services.some((service) => (service.kind === kind && service.hostPort === Number(url.port)) || (service.kind === 'clickhouse' && ((url.protocol === 'http:' && service.hostPort === Number(url.port)) || (url.protocol === 'clickhouse:' && service.sides?.native?.hostPort === Number(url.port)))))) connections[name] = value;
+    } catch { /* not an infrastructure endpoint */ }
+  }
+  return connections;
+}