@volter/world-runtime 2.0.0

package/src/fixture-env.ts

@@ -0,0 +1,230 @@
+// World fixture env — STRUCTURALLY VALID fake credentials for the env a world hands the app
+// under test.
+//
+// The failure this fixes (feature-sweep): fake env values in a world config are hand-authored
+// scalars (`sk_test_fake_…`), which is exactly right for credentials an SDK treats as an opaque
+// bearer token — the twin accepts anything, the value's SHAPE never matters. But some
+// credentials are PARSED AND USED CLIENT-SIDE before any request leaves the process: a Google
+// service-account JSON is loaded by google-auth-library, which signs a JWT assertion with its
+// `private_key` locally and only then calls the (twin-served) token endpoint. A faked
+// `GOOGLE_VERTEX_JSON` lacking `private_key` therefore throws inside the app and blocks every
+// Google-auth path — no twin ever sees a request. The fix is not a smarter twin; it is a
+// STRUCTURALLY VALID fake: all required fields, and a REAL throwaway RSA key the client library
+// can genuinely sign with. The signature is verified by nothing (the twin's token endpoint
+// accepts any well-formed assertion), so a throwaway key is safe by construction — it
+// corresponds to no real account anywhere.
+//
+// THE PATTERN (document + reuse for any future structurally-parsed credential):
+//   1. find what the CLIENT SDK does with the value before the first network call;
+//   2. fake every field it reads, with material that genuinely works (a real keypair, a
+//      well-formed JWT, …) — never placeholder strings in cryptographic positions;
+//   3. keep the fake obviously fake in the IDENTIFYING fields (project id, email) so it can
+//      never be mistaken for a real credential;
+//   4. mint keys per process (throwaway), never commit them — a committed key looks real to
+//      scanners and to attackers alike.
+// Precedents in-repo: gcs-sdk.integration.test.ts (throwaway RSA key lets the unmodified
+// @google-cloud/storage SDK sign V4 URLs offline), clerk-jwt.ts / fal-webhooks.ts (generated
+// signing keypairs).
+import { generateKeyPairSync } from 'node:crypto';
+
+export type FakeServiceAccountOptions = {
+  /** identifying project id — defaults to an unmistakably fake twin project. */
+  projectId?: string;
+  /** client_email — defaults to a twin address under the fake project. */
+  clientEmail?: string;
+};
+
+// RSA-2048 generation costs ~100ms — mint ONCE per process and reuse. Throwaway by design: never
+// persisted, never committed, corresponds to no real account.
+let cachedPrivateKeyPem: string | undefined;
+function throwawayPrivateKeyPem(): string {
+  if (!cachedPrivateKeyPem) {
+    const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+    cachedPrivateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  }
+  return cachedPrivateKeyPem;
+}
+
+/**
+ * A STRUCTURALLY VALID fake Google service-account JSON: every field a real
+ * `service_account` key file carries, with a REAL throwaway RSA private key — so
+ * google-auth-library (and every SDK built on it: Vertex, GCS, @ai-sdk/google-vertex, …)
+ * loads it, signs its JWT assertion locally, and proceeds to the twin-served token
+ * endpoint instead of throwing before the first request.
+ */
+export function fakeGoogleServiceAccountJson(opts: FakeServiceAccountOptions = {}): string {
+  const projectId = opts.projectId ?? 'twin-project';
+  const clientEmail = opts.clientEmail ?? `twin-fake@${projectId}.iam.gserviceaccount.com`;
+  return JSON.stringify(
+    {
+      type: 'service_account',
+      project_id: projectId,
+      private_key_id: 'twinfake0000000000000000000000000000dead',
+      private_key: throwawayPrivateKeyPem(),
+      client_email: clientEmail,
+      client_id: '000000000000000000000',
+      auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+      token_uri: 'https://oauth2.googleapis.com/token',
+      auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+      client_x509_cert_url: `https://www.googleapis.com/robot/v1/metadata/x509/${encodeURIComponent(clientEmail)}`,
+      universe_domain: 'googleapis.com',
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * A STRUCTURALLY VALID fake Google OAUTH WEB-CLIENT JSON — the `{"web":{...}}` shape a
+ * Google-Cloud-console "OAuth client" download has, which is what OAuth-APP consumers parse
+ * (cal.com: `JSON.parse(GOOGLE_API_CREDENTIALS)?.web`, then a zod schema over
+ * client_id/client_secret/redirect_uris). This is a DIFFERENT credential species from the
+ * service-account JSON above: faking the SA shape for these names passes the consumer's
+ * "valid JSON" check and then yields `?.web === undefined`, so the integration silently
+ * degrades instead of erroring — the worst failure mode for a fake credential (Cal.com blind
+ * run, friction #4). No cryptographic material is needed: the client secret is an opaque
+ * bearer the twin accepts; identifying fields are unmistakably fake.
+ */
+export function fakeGoogleOAuthClientJson(): string {
+  return JSON.stringify(
+    {
+      web: {
+        client_id: '000000000000-twinfake.apps.googleusercontent.com',
+        project_id: 'twin-project',
+        auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+        token_uri: 'https://oauth2.googleapis.com/token',
+        auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+        client_secret: 'twin-fake-google-oauth-client-secret',
+        redirect_uris: ['http://localhost:3000/api/auth/callback/google'],
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Does this env NAME carry an INLINE Google OAUTH-CLIENT JSON (the `{"web":{...}}` shape)?
+ *  Matches a GOOGLE stem combined with an OAuth-app marker: `API_CREDENTIALS` (cal.com's
+ *  GOOGLE_API_CREDENTIALS — the name that motivated this), `OAUTH_*`, or `*_CLIENT_JSON` /
+ *  `CLIENT_CREDENTIALS` forms. Deliberately NOT the SERVICE_ACCOUNT-marked names, NOT the
+ *  GCP/GCLOUD/VERTEX stems (cloud-platform credentials are service accounts), and NOT bare
+ *  GOOGLE_CREDENTIALS (ambiguous; historically ADC, i.e. SA-shaped — kept on the SA fake). */
+export function isGoogleOAuthClientEnvName(name: string): boolean {
+  const n = name.toUpperCase();
+  if (!/(^|_)GOOGLE(_|$)/.test(n)) return false;
+  if (n === 'GOOGLE_APPLICATION_CREDENTIALS') return false; // a path, not inline JSON
+  if (/SERVICE_ACCOUNT/.test(n)) return false; // explicitly SA-shaped
+  return /(API_CREDENTIALS|OAUTH_(CLIENT|CREDENTIALS|JSON)|CLIENT_(JSON|CREDENTIALS))/.test(n);
+}
+
+/** Does this env NAME carry an INLINE Google service-account JSON (the structurally-parsed
+ *  kind)? Matches a Google-ish stem (GOOGLE/GCP/GCLOUD/VERTEX) combined with a JSON/
+ *  credentials/service-account marker — e.g. GOOGLE_VERTEX_JSON, GCP_SERVICE_ACCOUNT_JSON,
+ *  GOOGLE_APPLICATION_CREDENTIALS_JSON. Deliberately NOT GOOGLE_MAPS_API_KEY (opaque scalar),
+ *  NOT GOOGLE_APPLICATION_CREDENTIALS (a FILE PATH — point it at a file whose contents
+ *  come from fakeGoogleServiceAccountJson instead), and NOT the OAuth-client names above —
+ *  those need the `{"web":{...}}` shape, not SA JSON. */
+export function isGoogleServiceAccountEnvName(name: string): boolean {
+  const n = name.toUpperCase();
+  if (!/(^|_)(GOOGLE|GCP|GCLOUD|VERTEX)(_|$)/.test(n)) return false;
+  if (n === 'GOOGLE_APPLICATION_CREDENTIALS') return false; // a path, not inline JSON
+  if (isGoogleOAuthClientEnvName(name)) return false; // OAuth-client shape, handled separately
+  return /(_JSON$|_JSON_|CREDENTIALS|SERVICE_ACCOUNT)/.test(n);
+}
+
+/**
+ * A structurally valid fake value for one env NAME. Google OAuth-client-shaped names get the
+ * `{"web":{...}}` client JSON; Google service-account-shaped names get the full SA JSON (real
+ * throwaway key); endpoint-shaped names get a parseable vendor-host URL that the injector can
+ * claim; everything else gets an unmistakably fake opaque scalar (`twin-fake-<name>`), which is
+ * sufficient for bearer-token credentials because the twin accepts any value — shape only
+ * matters when the CLIENT parses it (rule of thumb: if a blind adoption run shows an SDK throwing
+ * on a fake before any request is made, that env var needs a structural fake; add its rule here).
+ */
+/** Endpoint values whose SHAPE is consumed before the first network call.
+ *
+ * `new URL(value)` runs inside each client SDK before the injector can see a request, so an opaque
+ * `twin-fake-*` scalar fails even though the vendor is otherwise perfectly intercepted. These
+ * values are deliberately real-vendor-HOST-SHAPED but credential-free: the injector claims the
+ * hostname and sends the request to the local twin, while the slug remains unmistakably fake.
+ *
+ * Like CREDENTIAL_SHAPES below, this is duplicated kernel data with an explicit canonical source:
+ * world-runtime must not import a pack, and the tests pin every value against the injector's actual
+ * VENDOR_HOSTS predicate so either side changing makes the contract fail loudly. */
+const ENDPOINT_SHAPES: Array<{ match: RegExp; value: string; source: string }> = [
+  {
+    match: /(^|_)UPSTASH_REDIS_REST_URL$/,
+    value: 'https://twin-fake.upstash.io',
+    source: 'packages/world-core/inject.cjs VENDOR_HOSTS.upstash',
+  },
+  {
+    match: /(^|_)UPSTASH_VECTOR_REST_URL$/,
+    value: 'https://twin-fake-us1-vector.upstash.io',
+    source: 'packages/world-core/inject.cjs VENDOR_HOSTS.upstashvector',
+  },
+  {
+    match: /(^|_)TINYBIRD_API_URL$/,
+    value: 'https://api.tinybird.co',
+    source: 'packages/world-core/inject.cjs VENDOR_HOSTS.tinybird',
+  },
+];
+
+/** Credentials whose SHAPE the receiving twin actually checks.
+ *
+ * The generic `twin-fake-<name>` value is inert everywhere it lands — except at a twin that
+ * validates its own vendor's key format. Then the world is fully covered and the app still gets a
+ * 401, which reads as "the twin doesn't work" and is the most confusing failure this system can
+ * produce (measured: it cost two of four subjects a clean boot in PROOF-2026-08-20.md, finding F3).
+ * A minted fake must satisfy the twin that will receive it — the minter and the twin are two halves
+ * of one contract.
+ *
+ * These literals are DUPLICATED from the packs on purpose: the kernel must not import a pack
+ * (docs/contributing/architecture.md). Each entry names its source so the pair can be re-checked by hand. */
+const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string; source: string }> = [
+  // A Discord bot token is three dot-separated base64 segments; a library parses the first for the
+  // application id, so a structurally wrong fake breaks before any call reaches the twin.
+  { match: /(^|_)DISCORD_[A-Z0-9_]*(TOKEN|SECRET)$/, value: () => `${btoa('1'.repeat(18)).replace(/=+$/, '')}.Gtwinf.${'t'.repeat(38)}`, source: 'a Discord bot token: three dot-separated base64 segments, the first the application id' },
+  // resend-twin.ts enforces bearer auth of the form `re_<...>` whenever a key is presented.
+  { match: /(^|_)RESEND_[A-Z0-9_]*(KEY|TOKEN|SECRET)$/, value: (name) => `re_twinfake_${name.toLowerCase().replace(/_/g, '')}`, source: 'packages/twin/resend/src/resend-twin.ts' },
+  // The vercel twin answers only a bearer it minted, its bootstrap token first (`vercel.platform.token_identity`); any
+  // other value is Vercel's 403 "invalid token", so every call an app makes to its Vercel project fails.
+  { match: /(^|_)VERCEL_[A-Z0-9_]*(TOKEN|API_KEY)$/, value: () => 'vercel_twin_bootstrap_token', source: 'packages/twin/vercel/src/vercel-runtime.ts VERCEL_TWIN_TOKEN' },
+  // The tremendous twin takes a key of the shape Tremendous issues, `TEST_` for the sandbox organization at
+  // testflight.tremendous.com and `PROD_` for production (manifest.ts `auth.keyFormat`); any other value is Tremendous's
+  // 401. The `TEST_` prefix is what selects the sandbox host in clients that branch on it (dub's
+  // lib/tremendous/configuration.ts).
+  { match: /(^|_)TREMENDOUS_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'TEST_twin_sandbox_api_key', source: 'packages/twin/tremendous/src/manifest.ts auth.keyFormat' },
+  // Clerk: the SECRET key is opaque to the twin (any sk_ shape), but the PUBLISHABLE key is parsed by
+  // clerk-js — `pk_test_<base64(frontendApiHost$)>` names the frontend-API host the browser calls.
+  // The world issues one naming the dev-instance family the clerk pack CLAIMS by suffix
+  // (`.clerk.accounts.dev`, packages/twin/clerk/src/index.ts hosts), so the boundary — the injector
+  // server-side, the browser proxy browser-side — resolves it to the twin, and an app CSP that
+  // allowlists that host stays legal (peak drive 2026-08-26).
+  { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'packages/twin/clerk/src/clerk-twin.ts' },
+  { match: /(^|_)CLERK_[A-Z0-9_]*PUBLISHABLE[A-Z0-9_]*$/, value: () => `pk_test_${Buffer.from('twin.clerk.accounts.dev$').toString('base64')}`, source: 'packages/twin/clerk/src/index.ts' },
+];
+
+/** Keys the APPLICATION parses before it can use them: a fake that is not the shape its own code decodes throws at the
+ *  first use, far from any vendor. Each entry names the reader it satisfies; names differ in what they need (cal.com's
+ *  CALENDSO_ENCRYPTION_KEY is 32 raw characters), so a rule matches the name exactly. */
+const APP_KEY_SHAPES: Array<{ match: RegExp; value: () => string; source: string }> = [
+  // AES-256-GCM: the key base64-decodes to 32 bytes ("ENCRYPTION_KEY must be 32 bytes (base64-encoded)"); the 32 bytes
+  // spell out that they are fake
+  { match: /^ENCRYPTION_KEY$/, value: () => Buffer.from('twin-fake-encryption-key-32bytes').toString('base64'), source: "dubinc/dub apps/web/lib/encryption.ts" },
+];
+
+export function fakeEnvValue(name: string): string {
+  if (isGoogleOAuthClientEnvName(name)) return fakeGoogleOAuthClientJson();
+  for (const shape of APP_KEY_SHAPES) if (shape.match.test(name)) return shape.value();
+  if (isGoogleServiceAccountEnvName(name)) return fakeGoogleServiceAccountJson();
+  for (const shape of ENDPOINT_SHAPES) if (shape.match.test(name)) return shape.value;
+  for (const shape of CREDENTIAL_SHAPES) if (shape.match.test(name)) return shape.value(name);
+  const slug = name.toLowerCase().replace(/_/g, '-');
+  // A URL-shaped name must be faked as a URL (F4). An SDK handed `twin-fake-x` where it expects an
+  // endpoint throws while CONSTRUCTING its client — before it ever issues the request the world
+  // could have intercepted, so the failure looks like a twin bug and no ledger entry exists to
+  // contradict that. `.invalid` is reserved (RFC 2606) and never resolves, so an untwinned vendor
+  // still fails — but as an unreachable HOST, which the diagnostics can name.
+  if (/(^|_)(URL|URI|ENDPOINT|HOST)$/.test(name)) return `https://${slug}.invalid`;
+  return `twin-fake-${slug}`;
+}

package/src/host-cli.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// volter-world-host: run a set of twins co-located in this single process. The world
+// runtime spawns ONE of these (instead of one bin per twin) when a world selects
+// 'colocated'/'worker' isolation. Each twin is named by a module specifier + export so
+// this stays vendor-agnostic (no pack imports here — dynamic import() resolves them).
+//
+//   volter-world-host --isolation worker \
+//     --spec stripe|@volter/twin-stripe|createStripeTwinServer|12111|/data/stripe \
+//     --spec github|@volter/twin-github|createGithubTwinServer|12112|/data/github
+//
+// Prints one `ready id=<id> port=<port>` line per twin, then `host ready (<n> twins)`.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { startColocatedHost, type ColocatedTwinSpec, type HostIsolation } from './host.ts';
+
+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; };
+
+const isolation = (opt('--isolation', 'shared') as HostIsolation);
+if (isolation !== 'shared' && isolation !== 'worker') {
+  process.stderr.write(`invalid --isolation "${isolation}" (want shared|worker)\n`);
+  process.exit(2);
+}
+
+const specs: ColocatedTwinSpec[] = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] !== '--spec') continue;
+  const raw = argv[i + 1] ?? '';
+  const [id, module, exportName, port, root, ...flags] = raw.split('|');
+  const ro = flags.find((f) => f === 'ro');
+  const scenarioPath = flags.find((f) => f.startsWith('scenario='))?.slice('scenario='.length);
+  if (!id || !module || !exportName || !port || !root) {
+    process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>])\n`);
+    process.exit(2);
+  }
+  specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}) });
+}
+if (specs.length === 0) { process.stderr.write('no --spec given\n'); process.exit(2); }
+
+// A worker give-up (host.ts fires it on the first crash — never restarted) must be discoverable
+// AFTER the fact, not just as a
+// stdout line — this process IS the world's `instance.json` host child, but it is a SEPARATE OS
+// process from the runtime that wrote instance.json, so it must not rewrite that file directly
+// (the parent may still be mid-write, or rewrite it later — share/unshare both call
+// saveWorldInstance). Instead it writes a small sidecar (`host-gaveup.json`) next to instance.json
+// in the SAME instance dir (already created by upWorld before this child is spawned); `readWorldInstance`
+// merges the sidecar into `services[<id>].workerGaveUp` so every reader (doctor, status, tests) sees
+// the record as if it were in instance.json, without any cross-process write contention.
+// The instance file path is threaded in via VOLTER_WORLD_INSTANCE (set by upWorld for every co-located
+// child). Absent it (e.g. this CLI driven standalone in a unit test), give-up persistence is a no-op —
+// host.test.ts covers shared mode in-process; the give-up mechanics themselves (worker crash →
+// `gaveup` event, never respawned) are covered by the host-isolation / colocated-world integration
+// tests, which spawn this CLI and observe it from the outside.
+const instanceFile = process.env.VOLTER_WORLD_INSTANCE;
+const gaveUpSidecar = instanceFile ? join(dirname(instanceFile), 'host-gaveup.json') : undefined;
+
+function recordGaveUp(twin: string, exits: number, detail: string): void {
+  if (!gaveUpSidecar) return;
+  let all: Record<string, { at: string; exits: number; detail: string }> = {};
+  try {
+    if (existsSync(gaveUpSidecar)) all = JSON.parse(readFileSync(gaveUpSidecar, 'utf8'));
+  } catch {
+    // A torn/partial read (e.g. we crashed mid-write previously) — start fresh rather than
+    // let a corrupt sidecar wedge future give-ups from ever being recorded.
+  }
+  all[twin] = { at: new Date().toISOString(), exits, detail };
+  // Atomic publish (temp→rename in the SAME dir), the same discipline the kernel/instance.json
+  // writers use — a reader never observes a partially-written sidecar.
+  mkdirSync(dirname(gaveUpSidecar), { recursive: true });
+  const tmp = `${gaveUpSidecar}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(all, null, 2)}\n`);
+  renameSync(tmp, gaveUpSidecar);
+}
+
+// deploy: auto is the kernel's head (core head.ts): a twin performs its own `auto` writes as they happen
+const host = await startColocatedHost(specs, {
+  isolation,
+  onEvent: (e) => {
+    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 ?? '');
+  },
+});
+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`);
+
+const shutdown = async () => { await host.stop(); process.exit(0); };
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+await keepProcessAlive();

package/src/host-worker.ts

@@ -0,0 +1,23 @@
+// Worker entry for 'worker' isolation: one Worker thread per twin. It owns its event
+// loop + heap, so a CPU hog / leak / hard crash here is contained to this thread — the
+// 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';
+
+const spec = workerData as ColocatedTwinSpec;
+
+type TwinServer = { port: number; stop: () => void | Promise<void> };
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
+
+const mod = (await import(spec.module)) as Record<string, unknown>;
+const factory = mod[spec.export] as TwinServerFactory | undefined;
+if (typeof factory !== 'function') {
+  throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
+}
+
+// Awaited: an async factory (fly) must post `ready` only once its listener is bound.
+const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly });
+parentPort?.postMessage({ type: 'ready', port: server.port });
+
+// The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/src/host.ts

@@ -0,0 +1,169 @@
+// 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
+// mounts N of them behind their own ports/URLs (the world env + instance.json are
+// byte-identical to the spawned path — only the process model changes).
+//
+// Isolation is a DIAL, not a binary (the runtime stays minimal — this is still just
+// "bring services up / tear them down", one child process):
+//   - 'shared' : all twins share one event loop + heap. Lightest. A thrown request
+//                handler is isolated (Bun.serve returns 500; siblings serve on), but a
+//                CPU hog / OOM / process.exit in one twin hits all. Default for CI/dev.
+//   - 'worker' : one Worker thread per twin → own event loop + own heap, independently
+//                isolated. A sibling can spin, leak, or hard-exit without taking the
+//                host down — but a crashed twin stays down (doctor red), it is never
+//                respawned. Still ONE OS process to the orchestrator.
+// ('process' isolation — one OS process per twin — is the world runtime's existing
+//  spawn path; it remains the oracle and the choice for share/sealed/hosted worlds.)
+//
+// ARCHITECTURE: the runtime never imports vendor packs. A twin is named by a module
+// SPECIFIER + export resolved with dynamic import() at boot, so this host (and the
+// world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
+import { Worker } from 'node:worker_threads';
+import { siblingScript } from './sibling.ts';
+import { pathToFileURL } from 'node:url';
+
+/** 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). */
+export type ColocatedTwinSpec = {
+  id: string;
+  module: string;
+  export: string;
+  port: number;
+  root: string;
+  readOnly?: boolean;
+  /** The world's handlers file for a scenario-carrying (generative) twin — the colocate contract's
+   *  scenarioPath (R2a): the same file the spawn path passes as --scenario. */
+  scenarioPath?: string;
+};
+
+export type HostIsolation = 'shared' | 'worker';
+
+export type ColocatedHost = {
+  isolation: HostIsolation;
+  /** Resolved listening port per twin id (equals the requested port). */
+  ports: Record<string, number>;
+  stop: () => Promise<void>;
+};
+
+// `stop` returns void OR a promise (76 of 78 packs return Bun's async server.stop) and the
+// factory itself may be async (fly's createFlyTwinServer) — both shapes are awaited, so
+// "resolves once every twin is listening" is true for async factories and shutdown actually
+// WAITS instead of fire-and-forgetting (§9 skeptic finding M1, 2026-08-31: an async factory
+// made host.stop() throw `s.stop is not a function`, turning every SIGTERM into downWorld's
+// SIGKILL escalation for the whole world).
+type TwinServer = { port: number; stop: () => void | Promise<void> };
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string }) => TwinServer | Promise<TwinServer>;
+
+async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
+  const mod = (await import(spec.module)) as Record<string, unknown>;
+  const factory = mod[spec.export];
+  if (typeof factory !== 'function') {
+    throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
+  }
+  return factory as TwinServerFactory;
+}
+
+const workerEntry = (): URL => pathToFileURL(siblingScript(import.meta.url, 'host-worker'));
+
+/** Per-twin stop budget inside host.stop(). Must stay comfortably under downWorld's 5s
+ *  SIGTERM→SIGKILL grace (DOWN_GRACE_MS_DEFAULT): the host must reach process.exit(0) even
+ *  when a twin's stop hangs, or the whole co-located world dies by SIGKILL. */
+const STOP_TIMEOUT_MS = 3000;
+
+/**
+ * Start a co-located host. Resolves once every twin is listening. The returned `stop()`
+ * tears the whole host down (all servers / all workers).
+ *
+ * `onEvent` is an optional observability hook (logged by the CLI) — it surfaces a twin
+ * worker crashing (and being given up on), and stray rejections swallowed in shared mode,
+ * so a degraded twin is never a silent fake-success.
+ */
+export async function startColocatedHost(
+  specs: ColocatedTwinSpec[],
+  options: { isolation?: HostIsolation; onEvent?: (e: { twin: string; kind: string; detail?: string; exits?: number }) => void } = {},
+): Promise<ColocatedHost> {
+  const isolation = options.isolation ?? 'shared';
+  const onEvent = options.onEvent ?? (() => {});
+  const ports: Record<string, number> = {};
+  for (const spec of specs) ports[spec.id] = spec.port;
+
+  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.)
+    // We log and attribute rather than exit — state stays consistent because every kernel write
+    // is atomic (temp→rename) and root-keyed, so a swallowed error can't corrupt a sibling.
+    const onRejection = (reason: unknown) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: String(reason) });
+    const onUncaught = (err: unknown) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: String(err) });
+    process.on('unhandledRejection', onRejection);
+    process.on('uncaughtException', onUncaught);
+
+    const servers: TwinServer[] = [];
+    for (const spec of specs) {
+      const factory = await loadFactory(spec);
+      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}) }));
+    }
+    return {
+      isolation,
+      ports,
+      stop: async () => {
+        process.off('unhandledRejection', onRejection);
+        process.off('uncaughtException', onUncaught);
+        // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
+        // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
+        // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
+        // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
+        // cleanup throws on a failed container removal — left siblings unstopped and the host
+        // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
+        await Promise.allSettled(servers.map((s) =>
+          Promise.race([
+            Promise.resolve().then(() => s.stop()),
+            new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
+          ]),
+        ));
+      },
+    };
+  }
+
+  // worker isolation — one Worker thread per twin, given up on crash — never respawned.
+  const stopping = { value: false };
+  const workers = new Map<string, Worker>();
+
+  const spawnWorker = (spec: ColocatedTwinSpec): Promise<void> =>
+    new Promise<void>((resolveReady, rejectReady) => {
+      const worker = new Worker(workerEntry(), { workerData: spec });
+      // Pure observability, symmetric with `gaveup` below — NOT a supervision hook. Fired exactly
+      // once per spawnWorker() call (there's no counter/timer/keep-alive here), so it doubles as a
+      // direct tamper guard: a stealth respawn re-adding `spawnWorker(spec)` in the exit handler
+      // 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 }) => {
+        if (msg?.type === 'ready') { ready = true; resolveReady(); }
+      });
+      worker.on('error', (err) => {
+        onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
+        if (!ready) rejectReady(err);
+      });
+      worker.on('exit', (code) => {
+        workers.delete(spec.id);
+        if (stopping.value || code === 0) return;
+        // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
+        // respawned — record the give-up (host-cli persists it → doctor red) and stay dead.
+        onEvent({ twin: spec.id, kind: 'gaveup', detail: `exit code ${code} — not restarted`, exits: 1 });
+      });
+      workers.set(spec.id, worker);
+    });
+
+  for (const spec of specs) await spawnWorker(spec);
+
+  return {
+    isolation,
+    ports,
+    stop: async () => {
+      stopping.value = true;
+      await Promise.all([...workers.values()].map((w) => w.terminate()));
+    },
+  };
+}