@volter/world-runtime 3.0.163 → 3.0.164

package/dist/src/covers.js

@@ -528,11 +528,11 @@ function usesOf(signals) {
 }
 /** Detect every vendor (and every unmapped external-service-shaped signal) an application repo
  * betrays: mapped npm dependencies across the root + all workspace members, vendor-shaped env
- * names in committed `.env*` files, the SMTP/raw-protocol signal, and literal vendor URLs passed
+ * names in committed `.env*` files or its declared stack, the SMTP/raw-protocol signal, and literal vendor URLs passed
  * directly to fetch in production source. URL attribution reads the injector's VENDOR_HOSTS table
  * rather than re-encoding host rules here. Insertion order follows the sorted dependency, env-name,
  * and source lists, so callers that preserve it are deterministic. */
-export function detectRepoVendors(repoPath, services = []) {
+export function detectRepoVendors(repoPath, services = [], declaredEnvironmentNames = []) {
     // Application aliases are names the selected backing actually injects, never global vendor adoption.
     const backingEnvVendors = new Map();
     for (const service of services) {
@@ -548,7 +548,11 @@ export function detectRepoVendors(repoPath, services = []) {
     // A Volter package a pack names as its vendor's SDK is one (`@volter/identity`, the Volter identity
     // service's client, is the volteridentity twin's), as any vendor's SDK is.
     const dependencies = projectDependencies(repo).filter((dep) => Object.hasOwn(SDK_TWINS, dep) || (!dep.startsWith('@volter/') && !dep.startsWith('pypi:volter')));
-    const envNames = projectEnvNames(repo);
+    for (const name of declaredEnvironmentNames) {
+        if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new Error('Declared vendor environment name must be an identifier');
+    }
+    const envNames = [...new Set([...projectEnvNames(repo), ...declaredEnvironmentNames])].sort();
     const npmRegistries = projectNpmRegistries(repo);
     // vendor → detection sources
     const detected = new Map();
@@ -734,7 +738,7 @@ export function coverWorld(world, repoPath, options = {}) {
     }
     const repo = resolve(repoPath);
     const inventory = worldTwinInventory(world, root);
-    const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services);
+    const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services, options.declaredEnvironmentNames);
     // Does ANY injector vendor key exist for this vendor? Decides whether an UNINTERCEPTABLE
     // finding is acknowledgeable: a key that exists means the twin COULD be intercepted and the
     // wiring is merely wrong (fix it, don't acknowledge it); no key at all means the pack is a

package/dist/src/go-mysql-binding.d.ts

@@ -0,0 +1,19 @@
+/** 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 declare function goMysqlBinding(entry: Record<string, unknown>, version: unknown, name: string, declaredPort: number): Partial<GoMysqlBinding>;
+export declare function renderGoMysqlBinding(entry: GoMysqlBinding & {
+    name: string;
+    containerPort?: number;
+    query?: string;
+}, connection: URL, port: number): string;
+/** Match a declared DSN against its owned listener, never infer a grammar. */
+export declare function goMysqlEndpoint(value: string, binding: GoMysqlBinding, declaredPort: number): {
+    host: string;
+    port: number;
+} | undefined;

package/dist/src/go-mysql-binding.js

@@ -0,0 +1,51 @@
+/** Only versioned, explicitly typed data selects a driver grammar. */
+export function goMysqlBinding(entry, version, name, declaredPort) {
+    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,
+        dsnPrefix: entry.dsnPrefix, dsnProtocol: entry.dsnProtocol };
+}
+export function renderGoMysqlBinding(entry, connection, port) {
+    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, binding, declaredPort) {
+    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/dist/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/dist/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/dist/src/host-cli.js

@@ -14,6 +14,9 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { dirname, join } from 'node:path';
 import { startColocatedHost } from "./host.js";
 import { publishHostReady } from "./host-ready.js";
+// 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 = {};
 const argv = process.argv.slice(2);
 const opt = (name, fb = '') => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fb; };
 const isolation = opt('--isolation', 'shared');
@@ -83,6 +86,8 @@ function recordGaveUp(twin, exits, detail) {
 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 ?? '');
@@ -94,13 +99,15 @@ process.on('SIGINT', shutdown);
 const readyFile = opt('--ready-file');
 if (readyFile) {
     try {
-        publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports);
+        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`);

package/dist/src/host-ready.d.ts

@@ -1,10 +1,24 @@
+/** 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 declare function publishHostReady(path: string, boot: string, ports: Record<string, number>): void;
+export declare function publishHostReady(path: string, boot: string, ports: Record<string, number>, times?: HostStartTimes, streams?: readonly string[]): void;
 /**
  * Receipt admission is cancellation-aware; stale or malformed state is never
  * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
  * 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 declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress?: () => number): Promise<void>;
+export declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress?: () => number): Promise<HostReadyTimes>;

package/dist/src/host-ready.js

@@ -1,12 +1,14 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, watch, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 /** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
-export function publishHostReady(path, boot, ports) {
+export function publishHostReady(path, boot, ports, times, streams) {
     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);
 }
 /**
@@ -15,46 +17,71 @@ export function publishHostReady(path, boot, ports) {
  * 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, boot, ports, timeoutMs, abort, progress = () => 0) {
-    let started = Date.now();
-    let seen = progress();
-    for (;;) {
-        abort.throwIfAborted();
-        let bytes;
-        try {
-            bytes = readFileSync(path);
-        }
-        catch (error) {
-            if (error.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'));
-            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.');
+    // 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;
+    let watcher;
+    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;
+            try {
+                bytes = readFileSync(path);
             }
-            const answered = value.ports;
-            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.');
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
             }
-            return;
-        }
-        const now = progress();
-        if (now !== seen) {
-            seen = now;
-            started = Date.now();
+            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'));
+                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;
+                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) => 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).flatMap(([id, time]) => !ports.has(id) || when(time) === undefined ? [] : [[id, time]]))
+                    : undefined;
+                const streams = Array.isArray(value.streams) ? value.streams.filter((id) => typeof id === 'string' && ports.has(id)) : [];
+                return { at: when(value.at), began: when(value.began), ...(twinStarts ? { started: twinStarts } : {}), ...(streams.length ? { streams } : {}) };
+            }
+            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((resolve, reject) => {
+                const settle = () => { clearTimeout(timer); wake = undefined; abort.removeEventListener('abort', cancel); };
+                const cancel = () => { 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();
+            });
         }
-        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((resolve, reject) => {
-            const cancel = () => { 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/dist/src/host-worker.js

@@ -4,6 +4,7 @@ import { getPack, registerPack } 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 { servesByteStream, servesDiscovery, warmInProcess } from "./host.js";
 import { importModule } from "./import-module.js";
 const spec = workerData;
 const mod = await importModule(spec.module);
@@ -17,5 +18,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) => {
+    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/dist/src/host.d.ts

@@ -1,3 +1,4 @@
+import { type TwinPack } from '@volter/world-core/runtime';
 /** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
  *  factory (every pack ships one, e.g. `createStripeTwinServer`). `module` is anything import()
  *  resolves: a package name (`@volter/twin-stripe`) or an absolute file path (tests/fixtures). */
@@ -22,8 +23,33 @@ 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>;
 };
+/** 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 declare function servesByteStream(mod: Record<string, unknown>, descriptor: TwinPack): boolean;
+/** Whether a twin's main port answers the discovery door: its manifest declares `discovery`, and its port is HTTP. */
+export declare function servesDiscovery(mod: Record<string, unknown>, descriptor: TwinPack): boolean;
+/**
+ * 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 declare function warmInProcess(port: number): Promise<void>;
 /**
  * Start a co-located host. Resolves once every twin is listening. The returned `stop()`
  * tears the whole host down (all servers / all workers).

package/dist/src/host.js

@@ -1,5 +1,5 @@
 import { errorMessage } from "./error-message.js";
-import { getPack, registerPack } from '@volter/world-core/runtime';
+import { getPack, registerPack, servedHandlerOf } 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
@@ -26,6 +26,59 @@ import { siblingScript } from "./sibling.js";
 import { importModule } from "./import-module.js";
 import { pathToFileURL } from 'node:url';
 import { parallelStartup } from "./startup.js";
+/** 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, descriptor) {
+    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, descriptor) {
+    const manifest = mod.manifest;
+    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) {
+    const handler = servedHandlerOf(port);
+    if (!handler)
+        return;
+    let timer;
+    try {
+        await Promise.race([
+            (async () => { const response = await handler(new Request(`http://127.0.0.1:${port}/twin`)); await response?.arrayBuffer(); })(),
+            new Promise((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, warm) {
+    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) {
     const mod = await importModule(spec.module);
     const descriptor = mod.pack ?? getPack(spec.id);
@@ -36,7 +89,7 @@ async function loadFactory(spec) {
     if (typeof factory !== 'function') {
         throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
     }
-    return factory;
+    return { factory: factory, byteStream: servesByteStream(mod, descriptor), discovery: servesDiscovery(mod, descriptor) };
 }
 const workerEntry = () => pathToFileURL(siblingScript(import.meta.url, 'host-worker'));
 /** Per-twin stop budget inside host.stop(). Must stay comfortably under downWorld's 5s
@@ -57,6 +110,8 @@ export async function startColocatedHost(specs, options = {}) {
     const ports = {};
     for (const spec of specs)
         ports[spec.id] = spec.port;
+    const streams = [];
+    const discoverable = [];
     if (isolation === 'shared') {
         // Keep one twin's stray async rejection / uncaught throw from killing every other twin in
         // the shared process. (A thrown *request* handler is already contained by Bun.serve → 500.)
@@ -87,7 +142,11 @@ export async function startColocatedHost(specs, options = {}) {
         };
         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);
@@ -109,6 +168,9 @@ export async function startColocatedHost(specs, options = {}) {
         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.
@@ -135,7 +197,13 @@ export async function startColocatedHost(specs, options = {}) {
                     return;
                 }
                 ports[spec.id] = msg.port;
+                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();
             }
         });
@@ -170,6 +238,28 @@ export async function startColocatedHost(specs, options = {}) {
     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((resolve) => {
+            const worker = workers.get(id);
+            if (!worker) {
+                resolve();
+                return;
+            }
+            const done = () => { clearTimeout(timer); worker.off('message', warmed); worker.off('exit', done); resolve(); };
+            const warmed = (msg) => { 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/dist/src/infra-definition.d.ts

@@ -0,0 +1,35 @@
+import { type GoMysqlBinding } from './go-mysql-binding.js';
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+import type { NativeMariaDBService } from './native-mariadb-backing.js';
+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 declare function parseInfraDefinition(text: string): InfraService[];
+/** 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 declare function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string>;