@volter/world-runtime 2.0.0

package/dist/src/fixture-env.d.ts

@@ -0,0 +1,42 @@
+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;
+};
+/**
+ * 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 declare function fakeGoogleServiceAccountJson(opts?: FakeServiceAccountOptions): string;
+/**
+ * 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 declare function fakeGoogleOAuthClientJson(): string;
+/** 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 declare function isGoogleOAuthClientEnvName(name: string): boolean;
+/** 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 declare function isGoogleServiceAccountEnvName(name: string): boolean;
+export declare function fakeEnvValue(name: string): string;

package/dist/src/fixture-env.js

@@ -0,0 +1,221 @@
+// 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';
+// 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;
+function throwawayPrivateKeyPem() {
+    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 = {}) {
+    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() {
+    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) {
+    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) {
+    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 = [
+    {
+        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 = [
+    // 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 = [
+    // 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) {
+    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/dist/src/host-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/host-cli.js

@@ -0,0 +1,92 @@
+#!/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 } from "./host.js";
+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');
+if (isolation !== 'shared' && isolation !== 'worker') {
+    process.stderr.write(`invalid --isolation "${isolation}" (want shared|worker)\n`);
+    process.exit(2);
+}
+const specs = [];
+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, exits, detail) {
+    if (!gaveUpSidecar)
+        return;
+    let all = {};
+    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/dist/src/host-fault-fixture.d.ts

@@ -0,0 +1,32 @@
+type TwinServer = {
+    port: number;
+    stop: () => void;
+};
+export declare function createFaultTwinServer(options?: {
+    port?: number;
+    root?: string;
+    readOnly?: boolean;
+}): TwinServer;
+export declare const stopsInvoked: string[];
+/** ASYNC factory (the fly shape): the host must await it or ports/stop are a Promise. */
+export declare function createAsyncFaultTwinServer(options?: {
+    port?: number;
+    root?: string;
+    readOnly?: boolean;
+}): Promise<TwinServer>;
+/** stop() never resolves — the hang outcome. */
+export declare function createPendingStopTwinServer(options?: {
+    port?: number;
+    root?: string;
+}): TwinServer;
+/** stop() rejects — the throwing outcome (fly's failed container removal). */
+export declare function createRejectingStopTwinServer(options?: {
+    port?: number;
+    root?: string;
+}): TwinServer;
+/** well-behaved async stop that RECORDS being invoked. */
+export declare function createRecordingStopTwinServer(options?: {
+    port?: number;
+    root?: string;
+}): TwinServer;
+export {};

package/dist/src/host-fault-fixture.js

@@ -0,0 +1,100 @@
+// TEST-ONLY fault-injection twin (excluded from the published package via package.json
+// `files`). It is the in-process analog of the runtime suite's inline `node -e` crash
+// fixtures: a real `({port,root,readOnly}) => {port,stop}` twin factory whose handler can
+// be told to fail in a specific way by path, so the co-located host's isolation contract
+// can be proven per tier (shared vs worker):
+//   GET  /ok           → 200            (the neighbor/health endpoint)
+//   GET  /count        → 200 n          (root-keyed counter — proves state isolation)
+//   POST /fault/throw  → handler throws (contained by Bun.serve → 500; process survives)
+//   GET  /fault/spin   → busy-loops ?ms (blocks the event loop — shared: stalls siblings)
+//   POST /fault/reject → stray async rejection (tests the shared rejection guard)
+//   POST /fault/exit   → process.exit(1) (shared: kills host; worker: kills only that worker)
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function createFaultTwinServer(options = {}) {
+    const root = options.root;
+    const countFile = root ? join(root, 'count') : undefined;
+    if (root)
+        mkdirSync(root, { recursive: true });
+    const bump = () => {
+        if (!countFile)
+            return -1;
+        const n = (existsSync(countFile) ? Number(readFileSync(countFile, 'utf8')) || 0 : 0) + 1;
+        const tmp = `${countFile}.${process.pid}.${n}.tmp`;
+        writeFileSync(tmp, String(n));
+        // atomic publish (temp→rename), the same discipline the kernel uses
+        renameSync(tmp, countFile);
+        return n;
+    };
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 30,
+        async fetch(request) {
+            const url = new URL(request.url);
+            const p = url.pathname;
+            if (p === '/ok' || p === '/')
+                return new Response('ok', { status: 200 });
+            if (p === '/count')
+                return new Response(String(bump()), { status: 200 });
+            if (p === '/fault/throw')
+                throw new Error('injected fault: throw');
+            if (p === '/fault/spin') {
+                const ms = Number(url.searchParams.get('ms') ?? '1000');
+                const until = Date.now() + ms;
+                while (Date.now() < until) { /* busy-loop: hog the event loop */ }
+                return new Response('spun', { status: 200 });
+            }
+            if (p === '/fault/reject') {
+                queueMicrotask(() => { void Promise.reject(new Error('injected fault: stray rejection')); });
+                return new Response('scheduled', { status: 202 });
+            }
+            if (p === '/fault/exit') {
+                // Defer so the response flushes, then hard-exit this process/worker.
+                setTimeout(() => process.exit(1), 5);
+                return new Response('exiting', { status: 200 });
+            }
+            return new Response('not found', { status: 404 });
+        },
+        // A real vendor returns 500 on an internal error (not a dropped socket). Surfacing the
+        // throw as a clean 500 is both faithful AND the request-level isolation boundary: the
+        // throw never escapes this handler to disturb a sibling twin.
+        error() {
+            return new Response('internal error', { status: 500 });
+        },
+    });
+    try {
+        if (root)
+            writeFileSync(join(root, 'listening-port'), String(server.port));
+    }
+    catch (error) {
+        server.stop(true);
+        throw error;
+    }
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+// ── shutdown-contract fixtures (§9 round two H2/H3, 2026-08-31) ────────────────────────────
+// The mount/stop contract admits async factories and async stops, and host.stop() must
+// survive every stop OUTCOME: these factories make each outcome constructible. `stopsInvoked`
+// proves "every stop is invoked" independently of what the stops then do.
+export const stopsInvoked = [];
+/** ASYNC factory (the fly shape): the host must await it or ports/stop are a Promise. */
+export async function createAsyncFaultTwinServer(options = {}) {
+    await new Promise((tick) => setTimeout(tick, 10));
+    return createFaultTwinServer(options);
+}
+/** stop() never resolves — the hang outcome. */
+export function createPendingStopTwinServer(options = {}) {
+    const inner = createFaultTwinServer(options);
+    return { port: inner.port, stop: () => { stopsInvoked.push('pending'); void inner.stop(); return new Promise(() => { }); } };
+}
+/** stop() rejects — the throwing outcome (fly's failed container removal). */
+export function createRejectingStopTwinServer(options = {}) {
+    const inner = createFaultTwinServer(options);
+    return { port: inner.port, stop: () => { stopsInvoked.push('rejecting'); void inner.stop(); return Promise.reject(new Error('injected fault: stop rejected')); } };
+}
+/** well-behaved async stop that RECORDS being invoked. */
+export function createRecordingStopTwinServer(options = {}) {
+    const inner = createFaultTwinServer(options);
+    return { port: inner.port, stop: async () => { stopsInvoked.push('recording'); await inner.stop(); } };
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/src/host-worker.js

@@ -0,0 +1,23 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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';
+const spec = workerData;
+const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+const factory = mod[spec.export];
+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/dist/src/host.d.ts

@@ -0,0 +1,38 @@
+/** 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>;
+};
+/**
+ * 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 declare function startColocatedHost(specs: ColocatedTwinSpec[], options?: {
+    isolation?: HostIsolation;
+    onEvent?: (e: {
+        twin: string;
+        kind: string;
+        detail?: string;
+        exits?: number;
+    }) => void;
+}): Promise<ColocatedHost>;