@volter/world-runtime 3.0.163 → 3.0.164

package/src/clickhouse-backing.ts

@@ -0,0 +1,70 @@
+// ClickHouse's managed ownership questions: HTTP ping, this child's kernel boot answer,
+// and a native Hello/Ping. No SQL is executed by readiness.
+// Packet fields: clickhouse-docs/docs/native-protocol/{client,server,basics}.md;
+// revision54429 uses the reached clickhouse-driver0.2.10 layout retained with the pack.
+import { connect } from 'node:net';
+import { WORLD_BOOT_PATH } from '@volter/world-core/runtime';
+import type { ManagedProtocol } from './twin-backing.ts';
+import type { InfraService } from './infra-definition.ts';
+
+async function answer(port: number, path: string): Promise<string | undefined> {
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 1000);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}${path}`, { signal: controller.signal, redirect: 'error' });
+    if (!response.ok || !response.body) return undefined;
+    // This private proof contains a UUID boot nonce and a JavaScript-safe PID; ping is four bytes.
+    const reader = response.body.getReader(); let text = '', bytes = 0;
+    try { while (true) { const part = await reader.read(); if (part.done) break; bytes += part.value.length; if (bytes > 256) return undefined; text += new TextDecoder().decode(part.value); } }
+    finally { await reader.cancel().catch(() => undefined); }
+    return text;
+  } catch { return undefined; } finally { clearTimeout(timer); }
+}
+function number(value: number): number[] { const result: number[] = []; do { const byte = value % 128; value = Math.floor(value / 128); result.push(byte | (value ? 128 : 0)); } while (value); return result; }
+function string(value: string): number[] { const bytes = new TextEncoder().encode(value); return [...number(bytes.length), ...bytes]; }
+function nativeAnswers(service: InfraService): Promise<boolean> {
+  const port = service.sides?.native?.hostPort; if (!port) return Promise.resolve(false);
+  const users = service.configuration?.users as Record<string, string> | undefined;
+  const [user, password] = users && Object.hasOwn(users, 'default') ? ['default', users.default!] : Object.entries(users ?? { default: '' })[0] ?? [];
+  if (typeof user !== 'string' || typeof password !== 'string') return Promise.resolve(false);
+  const hello = Uint8Array.from([0, ...string('World ownership'), 1, 0, ...number(54429), ...string('default'), ...string(user), ...string(password)]);
+  return new Promise(resolve => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 }); let bytes = new Uint8Array(), phase = 'hello', settled = false;
+    const end = (valid: boolean) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); resolve(valid); };
+    // One complete ownership question has one deadline; incoming fragments never extend it.
+    const timer = setTimeout(() => end(false), 1000);
+    const missing = Symbol('incomplete');
+    socket.once('connect', () => socket.write(hello));
+    socket.on('data', chunk => {
+      // The declaring pack fixes its Hello name, timezone and display name;64KiB is beyond that packet domain.
+      if (bytes.length + chunk.length > 65536) { end(false); return; }
+      const joined = new Uint8Array(bytes.length + chunk.length); joined.set(bytes); joined.set(chunk, bytes.length); bytes = joined;
+      let at = 0;
+      const read = (): number => {
+        let value = 0n;
+        for (let shift = 0; shift < 70; shift += 7) { if (at >= bytes.length) throw missing; const byte = bytes[at++]!; value |= BigInt(byte & 127) << BigInt(shift); if (!(byte & 128)) { if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('Invalid native integer'); return Number(value); } }
+        throw new Error('Invalid native integer');
+      };
+      const text = (): string => { const length = read(); if (length > bytes.length - at) throw missing; const result = new TextDecoder().decode(bytes.subarray(at, at + length)); at += length; return result; };
+      try {
+        if (phase === 'hello') {
+          if (read() !== 0 || text() !== 'ClickHouse') { end(false); return; }
+          read(); read(); const revision = read(); if (revision !== 54429) { end(false); return; }
+          text(); text(); read(); bytes = bytes.slice(at); phase = 'pong'; socket.write(Uint8Array.of(4));
+          if (!bytes.length) return; at = 0;
+        }
+        end(read() === 4);
+      } catch (error) { if (error !== missing) end(false); }
+    });
+    socket.once('error', () => end(false)); socket.once('timeout', () => end(false)); socket.once('close', () => end(false));
+  });
+}
+export const CLICKHOUSE_PROTOCOL: ManagedProtocol = {
+  name: 'ClickHouse', bootProof: true,
+  async answers(port) { return await answer(port, '/ping') === 'Ok.\n'; },
+  async serves(port, pid, service, boot) {
+    if (!service || !boot || await answer(port, '/ping') !== 'Ok.\n') return false;
+    const body = await answer(port, WORLD_BOOT_PATH); if (!body) return false;
+    try { const held = JSON.parse(body); if (held.boot !== boot || held.pid !== pid) return false; } catch { return false; }
+    return nativeAnswers(service);
+  },
+};

package/src/command-lifetime.d.mts

@@ -4,7 +4,7 @@ export const COMMAND_GRACE_MS: number;
 export const COMMAND_CONFIRM_MS: number;
 export const commandProcessGroup: boolean;
 export class CommandRetirementError extends Error {}
-export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean): {
+export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean, graceMs?: number): {
   identity: Promise<SpawnIdentity | undefined>;
   cancel(signal: NodeJS.Signals): void;
   readonly forwarded: NodeJS.Signals | undefined;

package/src/command-lifetime.mjs

@@ -9,7 +9,10 @@ export class CommandRetirementError extends Error {}
 
 /** The child owns a private POSIX group. A bounded retirement requires both closed output and
  * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
-export function commandLifetime(child, abort, preserveOnSuccess = false) {
+/** `graceMs` is how long a cancelled child is awaited before SIGKILL. A command gets the default; a STORE (a
+ *  database, a twin that holds state) is given its lifecycle's budget, since what it does between the signal and
+ *  its exit is write its state down, and a SIGKILL in the middle of that leaves a store nothing may take. */
+export function commandLifetime(child, abort, preserveOnSuccess = false, graceMs = COMMAND_GRACE_MS) {
   const identity = child.pid && commandProcessGroup ? childIdentity(child) : Promise.resolve(undefined);
   let signalFailure;
   let pendingSignals = 0;
@@ -62,7 +65,7 @@ export function commandLifetime(child, abort, preserveOnSuccess = false) {
     }
   };
   const watch = () => {
-    if (!deadline) deadline = Date.now() + COMMAND_GRACE_MS;
+    if (!deadline) deadline = Date.now() + graceMs;
     timer ??= setInterval(check, 20);
     check();
   };

package/src/configs.ts

@@ -1,6 +1,6 @@
 import { copyFileSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime-state';
 import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument, type WorldChangesetRules, type WorldConfig } from './schema.ts';
 
 export function resolveConfigPath(config: string, root = process.cwd()): string {

package/src/consumers.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { join } from 'node:path';
-import { stateDirName, withFileLock } from '@volter/world-core/runtime';
+import { stateDirName, withFileLock } from '@volter/world-core/runtime-state';
 
 export type WorldConsumer = {
   id: string;

package/src/covers.ts

@@ -627,6 +627,8 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
 export type CoverageOptions = {
   root?: string;
   allowUnknown?: boolean;
+  /** Application environment names already read from its declared stack. */
+  declaredEnvironmentNames?: readonly string[];
   /**
    * vendor → reason: vendors the operator ACKNOWLEDGES need no twin in this world — e.g. an SDK
    * used verifier-only (svix's Webhook verifies incoming signatures locally and never calls out).
@@ -685,11 +687,11 @@ function usesOf(signals: Map<string, string[]>): Map<string, Array<{ usage: Worl
 
 /** 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: string, services: Array<WorldServiceConfig | WorldServiceInstance> = []): RepoVendorSignals {
+export function detectRepoVendors(repoPath: string, services: Array<WorldServiceConfig | WorldServiceInstance> = [], declaredEnvironmentNames: readonly string[] = []): RepoVendorSignals {
   // Application aliases are names the selected backing actually injects, never global vendor adoption.
   const backingEnvVendors = new Map<string, string>();
   for (const service of services) {
@@ -703,7 +705,10 @@ export function detectRepoVendors(repoPath: string, services: Array<WorldService
   // 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
@@ -871,7 +876,7 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
   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

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()));