@volter/world-runtime 2.0.54 → 3.0.0

package/dist/src/configs.js

@@ -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';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime';
 import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument } from "./schema.js";
 export function resolveConfigPath(config, root = process.cwd()) {
     const candidates = config.includes('/') || config.endsWith('.json')

package/dist/src/console-apart.d.ts

@@ -1,4 +1,4 @@
-import { type HttpServer } from '@volter/world-core';
+import { type HttpServer } from '@volter/world-core/runtime';
 /** What a console offers a host: its shell and assets under `base`, told where the Worlds are served. */
 export type ConsoleMount = {
     handle: (request: Request, base: string, opts?: {
@@ -23,7 +23,7 @@ export declare function serveConsoleApart(mount: ConsoleMount, opts: {
 }>;
 /** The console for a World served elsewhere (a hosted World), on this machine. Two local listeners, as
  *  `volter world serve` has: the console on one origin, its doors forwarded to the host; and the Worlds'
- *  origin on the next port, forwarding everything (a twin's mirror, the session door) to the host, so
+ *  origin on the next port, forwarding everything (a vendor's screens, the session door) to the host, so
  *  the console and the pages twins serve are same-site as they are locally, and still two origins. A
  *  host keeps its tenants' names to itself, so the World is named by the URL: `<origin>/<org>/<world>`. */
 export declare function serveConsoleFor(target: string, opts?: {

package/dist/src/console-apart.js

@@ -1,10 +1,10 @@
 // THE CONSOLE ON AN ORIGIN OF ITS OWN. The console keeps the token a person types in its tab's
-// storage; the Worlds' origin serves what twins serve (a mirror bundle, a tunnel's visitor pages,
+// storage; the Worlds' origin serves what twins serve (a vendor's screens, a tunnel's visitor pages,
 // an app's own HTML), and a script there could read any storage of that origin. So a host serves the
 // console on a listener of its own: the console's shell and bundle, and the host's `/-/` doors
 // forwarded to the host — never a twin's path, so no twin-served script ever runs on this origin.
-// The console opens a World's pages (a twin's mirror) on the Worlds' origin, which it is told.
-import { serveHttp } from '@volter/world-core';
+// The console opens a World's pages (a vendor's screens) on the Worlds' origin, which it is told.
+import { serveHttp } from '@volter/world-core/runtime';
 export const CONSOLE_BASE = '/-/console';
 /** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
 /** `upstream`: where this listener reaches the host's doors (its own address); `worlds`: the origin the
@@ -41,7 +41,7 @@ export async function serveConsoleApart(mount, opts) {
 }
 /** The console for a World served elsewhere (a hosted World), on this machine. Two local listeners, as
  *  `volter world serve` has: the console on one origin, its doors forwarded to the host; and the Worlds'
- *  origin on the next port, forwarding everything (a twin's mirror, the session door) to the host, so
+ *  origin on the next port, forwarding everything (a vendor's screens, the session door) to the host, so
  *  the console and the pages twins serve are same-site as they are locally, and still two origins. A
  *  host keeps its tenants' names to itself, so the World is named by the URL: `<origin>/<org>/<world>`. */
 export async function serveConsoleFor(target, opts = {}) {
@@ -86,7 +86,7 @@ export async function serveConsoleFor(target, opts = {}) {
             // the World session's cookie, kept on this plain-http loopback origin (a Secure cookie is https-only)
             for (const c of answer.headers.getSetCookie())
                 out.append('set-cookie', c.replace(/;\s*Secure/i, ''));
-            // the host's own redirects (the session door's, a twin root's to its mirror) stay on this origin
+            // the host's own redirects (the session door's) stay on this origin
             const location = out.get('location');
             if (location?.startsWith(origin))
                 out.set('location', `${url.origin}${location.slice(origin.length)}`);

package/dist/src/consumers.js

@@ -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';
+import { stateDirName, withFileLock } from '@volter/world-core/runtime';
 export const CONSUMER_HEARTBEAT_MS = 5000;
 const STALE_MS = 30_000;
 export function checkedOwner(owner) {

package/dist/src/covers.d.ts

@@ -77,7 +77,7 @@ export declare function isMappedScopeSibling(name: string): boolean;
  * `'acknowledged'` was adjudicated acceptable and auto-acknowledges with its recorded
  * reason); `notExternal` suppresses vendor-adjacent glue (protocol/type/UI helpers, auth
  * libraries); `patterns` are the external-shape heuristics. AN ENTRY DIES THE DAY ITS PACK
- * IS BORN — scripts/packless-claims.test.ts enforces disjointness with pack adoption and
+ * IS BORN — scripts/packless-claims.ts enforces disjointness with pack adoption and
  * SDK_TWINS (the `@planetscale/database`/twin#255 lesson, mechanized). Lazy + cached like
  * pack-facts.ts's loader — though note this module ALREADY does module-scope I/O via the
  * overlayCoversMaps call below, so laziness here is consistency, not a load-bearing

package/dist/src/covers.js

@@ -21,15 +21,16 @@
 //             coverage. An external-service-shaped dep/env var with no vendor mapping →
 //             unknown-sdk → exit 1 by default (`--allow-unknown` downgrades to a warning:
 //             unknowns still print, but stop failing the proof).
-import { readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { vendorOfPackModule } from '@volter/world-core/runtime';
 import { loadWorldConfig } from "./configs.js";
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from "./inject-map.js";
-import { connectionProtocol, projectConnections, projectDependencies, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from "./project-inspect.js";
+import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from "./project-inspect.js";
 import { overlayCoversMaps, packFacts } from "./pack-facts.js";
 import { statusWorld } from "./runtime.js";
-import { worldSelectionIncludes } from "./schema.js";
+import { ISSUE_ENV_PREFIX, worldSelectionIncludes } from "./schema.js";
 /** identifiers are compared case/punctuation-insensitively: 's3', 'S3_TWIN_URL' stem,
  * a 'stripe' service id and the 'ai-gateway' pack name all normalize cleanly. */
 function normalizeId(text) {
@@ -71,7 +72,7 @@ export function injectorEnvNameForKey(key) {
 /** Vendor-shaped env var detection (the secondary signal). The var must end in a
  * credential/endpoint suffix; the remaining stem (framework prefixes stripped,
  * normalized) is looked up here. */
-// Exported for scripts/packless-claims.test.ts, which checks the packless registry against
+// Exported for scripts/packless-claims.ts, which checks the packless registry against
 // the OVERLAID map (legacy entries + descriptor adoption.envStems in one view) — importing
 // the real map is unbreakable by formatting, unlike the source-parsing it replaced (§9
 // skeptic M3, 2026-08-31: a reflow or quote-style change silently emptied the parsed set).
@@ -114,6 +115,24 @@ function envVendorStem(name, suffix) {
         return null;
     return normalizeId(stripped.slice(0, match.index));
 }
+/** The vendor a credential-shaped env name's stem names: the stem left once the suffix is stripped, or else the longest
+ *  declared stem the name begins with (googleoauth's GOOGLE_CLIENT for GOOGLE_CLIENT_ID, whose `_CLIENT_ID` suffix
+ *  leaves only GOOGLE). */
+function envStemVendor(name, suffix) {
+    const stem = envVendorStem(name, suffix);
+    if (stem === null)
+        return undefined;
+    if (ENV_STEM_VENDORS[stem])
+        return ENV_STEM_VENDORS[stem];
+    const words = name.replace(ENV_FRAMEWORK_PREFIX, '').split('_');
+    // a declared stem of more than one word: a one-word stem (X's `X`) would claim every name it begins
+    for (let k = words.length - 1; k >= 2; k--) {
+        const vendor = ENV_STEM_VENDORS[normalizeId(words.slice(0, k).join('_'))];
+        if (vendor)
+            return vendor;
+    }
+    return undefined;
+}
 /** Is this env NAME shaped like a CREDENTIAL/endpoint at all (any broad vendor suffix)? The
  * question `init` asks before deciding whether a value in a repo's `.env.example` may be copied
  * verbatim: `APP_NAME` may, `ANYTHING_SECRET` may not — a committed example file is exactly where
@@ -121,7 +140,7 @@ function envVendorStem(name, suffix) {
  * ALWAYS replaced by a fake, whether or not its stem maps to a vendor this repo twins. Exported
  * from here so the emission path and the proof read ONE definition of "credential-shaped". */
 export function isCredentialShapedEnvName(name) {
-    return ENV_SUFFIX_BROAD.test(name.replace(ENV_FRAMEWORK_PREFIX, ''));
+    return name === 'GOOGLE_APPLICATION_CREDENTIALS' || ENV_SUFFIX_BROAD.test(name.replace(ENV_FRAMEWORK_PREFIX, ''));
 }
 /** The vendor a credential-shaped env NAME betrays, or null. Same broad-suffix route the
  * coverage proof's secondary signal uses (`STRIPE_SECRET_KEY` → 'stripe'). */
@@ -138,8 +157,7 @@ export function envNameVendor(name) {
     // So: this asks "is this name a VENDOR CREDENTIAL that must be faked?" (a hostname is not), while
     // `detectRepoVendors` asks "which vendors does this repo talk to?" (the mail path certainly is
     // one). Same string, two honest answers.
-    const stem = envVendorStem(name, ENV_SUFFIX_BROAD);
-    return stem === null ? null : ENV_STEM_VENDORS[stem] ?? null;
+    return envStemVendor(name, ENV_SUFFIX_BROAD) ?? null;
 }
 /** SMTP-shaped env names — the raw-protocol mail path (nodemailer et al.) the HTTP-vendor
  * heuristics above are structurally blind to. The Cal.com blind run's booking-confirmation
@@ -168,7 +186,7 @@ function isSmtpEnvSignal(name) {
 const SDK_SCOPE_VENDORS = {
 // (empty — every entry has moved onto its pack descriptor. See the note below.)
 };
-// descriptor-first migration (adding-a-twin.md §3), COMPLETE for these three tables: every pack declares its own
+// descriptor-first migration (architecture.md, "The descriptor"), COMPLETE for these three tables: every pack declares its own
 // scopes / env stems / world ids (`adoption` on its descriptor, compiled into the committed
 // pack-facts artifact), and all three literals above are now empty — they are populated entirely
 // by the overlay below. They are kept as the overlay's targets, not as homes: the object identity
@@ -261,10 +279,11 @@ function servicePackNames(service) {
         ...(service.colocate?.module ? [service.colocate.module] : []),
     ];
     return commandParts.flatMap((part) => {
-        const fromPath = part.match(/packages\/twin\/([a-z0-9-]+)\//);
+        const fromPath = part.match(/(?:^|[/\\])twin-packs-p[23][/\\]([a-z0-9-]+)[/\\]/);
         const fromBin = part.match(/^world-([a-z0-9-]+)$/);
         const fromPkg = part.match(/(?:^|[/\\])@volter\/twin-([a-z0-9-]+)(?:[/\\]|$)/);
-        return [fromPath?.[1], fromBin?.[1], fromPkg?.[1]].filter((name) => name !== undefined);
+        const fromManifest = /\.(?:[cm]?js|tsx?)$/.test(part) ? vendorOfPackModule(part) : undefined;
+        return [fromManifest, fromPath?.[1], fromBin?.[1], fromPkg?.[1]].filter((name) => name !== undefined);
     });
 }
 /** Endpoint wiring owned by a service, never a random URL from global config/env. Config
@@ -282,15 +301,10 @@ function serviceConnections(services, effectiveEnv) {
         const values = instance ? service.env : config?.injectEnvTemplates ?? {};
         for (const [name, value] of Object.entries(values)) {
             const protocol = connectionProtocol(value);
-            const command = [...(Array.isArray(service.command) ? service.command : []), ...('args' in service ? service.args ?? [] : [])];
             // The pack-transport veto is about NATIVE schemes (a mysql:// template on an HTTP twin); an
             // http(s) endpoint template on any twin is that twin's own HTTP door.
-            const incompatiblePack = protocol !== null && facts.some((fact) => {
-                if (fact.nativeTransport?.protocol === protocol && command.includes(fact.nativeTransport.flag))
-                    return false;
-                return fact.transport !== 'raw-tcp' || !Object.values(fact.endpointEnv?.templates ?? {})
-                    .some((template) => connectionProtocol(template) === protocol && protocol !== null);
-            });
+            const incompatiblePack = protocol !== null && facts.some((fact) => fact.transport !== 'raw-tcp' || !Object.values(fact.endpointEnv?.templates ?? {})
+                .some((template) => connectionProtocol(template) === protocol && protocol !== null));
             let routed = false;
             if (protocol !== null && !incompatiblePack) {
                 if (instance) {
@@ -323,7 +337,7 @@ function serviceConnections(services, effectiveEnv) {
                 bindings.set(name, { protocol: template.includes('${url}') || /^https?:/.test(template) ? 'http' : null, label: `${service.id} (${name}; cliRedirect)` });
             }
             for (const mapping of config?.external?.discover ?? []) {
-                bindings.set(mapping.as, { protocol: null, label: `${service.id} (${mapping.as}; discover after up)` });
+                bindings.set(mapping.as, { protocol: mapping.protocol ?? null, label: `${service.id} (${mapping.as}; discover after up)` });
             }
         }
     }
@@ -362,11 +376,7 @@ function addServiceIds(ids, service) {
         .some(([name, value]) => httpNames.has(name) && (/^(?:https?|wss?):/.test(value) || value === '${url}'));
     const nativeOnly = packNames.length === 0 && endpointValues.some((value) => connectionProtocol(value) !== null) &&
         !vendorHttpEndpoint;
-    const nativeMode = packNames.some((name) => {
-        const mode = packFacts()[name]?.nativeTransport;
-        return mode && [...(Array.isArray(service.command) ? service.command : []), ...(service.args ?? [])].includes(mode.flag);
-    });
-    const interceptable = !nativeOnly && !nativeMode && (injectorReads || appConfigured || hostMatched);
+    const interceptable = !nativeOnly && (injectorReads || appConfigured || hostMatched);
     // twin + external services cover their vendor by identity; a plain 'process'
     // service only counts via an explicit twin marker (injectEnv/*_TWIN_URL, pack path).
     if (type === 'twin' || type === 'external') {
@@ -407,7 +417,14 @@ export function worldTwinInventory(world, root) {
         const ids = new Map();
         for (const service of config.services)
             addServiceIds(ids, service);
-        return { source: 'config', path, ids, connections: serviceConnections(config.services), selection: config.selection, declared: declaredTwin(config.services) };
+        const connections = serviceConnections(config.services);
+        // a name the World's env leaves to a twin's credential door (`$issue:<service>`) is that twin's, whatever scheme the
+        // issued value has: the twin that issues it serves it
+        for (const [name, value] of Object.entries(config.env ?? {})) {
+            if (value.startsWith(ISSUE_ENV_PREFIX))
+                connections.set(name, { protocol: 'issued', label: `${value.slice(ISSUE_ENV_PREFIX.length)} (${name}; issued)` });
+        }
+        return { source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services) };
     }
     catch (error) {
         const configError = error instanceof Error ? error.message : String(error);
@@ -495,8 +512,7 @@ export function detectRepoVendors(repoPath) {
             detected.set('smtp', [...(detected.get('smtp') ?? []), `env: ${name}`]);
             continue;
         }
-        const stem = envVendorStem(name, ENV_SUFFIX_BROAD);
-        const vendor = stem === null ? undefined : ENV_STEM_VENDORS[stem];
+        const vendor = envStemVendor(name, ENV_SUFFIX_BROAD);
         if (vendor)
             detected.set(vendor, [...(detected.get(vendor) ?? []), `env: ${name}`]);
     }
@@ -545,6 +561,53 @@ export function detectRepoVendors(repoPath) {
             detected.set(vendor, [...(detected.get(vendor) ?? []), source]);
         }
     }
+    // a platform's config file that betrays the vendor (a vercel.json declaring crons: the platform calls the app's routes)
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        for (const config of facts.adoption?.configFiles ?? []) {
+            for (const dir of projectManifestDirs(repo)) {
+                const path = join(dir, config.file);
+                if (!existsSync(path))
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(readFileSync(path, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                if (config.when !== undefined && !(parsed && typeof parsed === 'object' && config.when in parsed))
+                    continue;
+                const where = relative(repo, path) || config.file;
+                const evidence = config.usage === 'application' ? `config: ${where}${config.when ? ` (${config.when})` : ''}` : `${config.usage}-tool: config: ${where}`;
+                detected.set(vendor, [...(detected.get(vendor) ?? []), evidence]);
+            }
+        }
+    }
+    // Exact names a descriptor's credential door fills are evidence too (ADC names a file, not a _KEY scalar), when the
+    // name names the vendor: its first word is the first word of one of the vendor's env stems (GOOGLE_APPLICATION_CREDENTIALS
+    // for GOOGLE_OAUTH), or it holds one of the stems whole (SUPERCODE_TUNNEL_SERVER_URL for TUNNEL). A generic name a door
+    // also fills (DATABASE_URL, NODE_AUTH_TOKEN) is every vendor's and so no vendor's evidence; a name that already is the
+    // vendor's evidence is not counted twice.
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        const stems = facts.adoption?.envStems ?? [];
+        const words = new Set(stems.map((stem) => stem.split('_')[0]));
+        const names = (name) => {
+            const bare = name.replace(ENV_FRAMEWORK_PREFIX, '');
+            return words.has(bare.split('_')[0]) || stems.some((stem) => `_${bare}_`.includes(`_${stem}_`));
+        };
+        for (const name of Object.keys(facts.credentialDoor?.fill ?? {})) {
+            if (!envNames.includes(name) || !names(name))
+                continue;
+            if (!(detected.get(vendor) ?? []).includes(`env: ${name}`))
+                detected.set(vendor, [...(detected.get(vendor) ?? []), `env: ${name} (credential issuer)`]);
+        }
+    }
+    // Expand the declared issuer relation transitively, once per vendor; cycles cannot keep detection running.
+    for (const vendor of detected.keys()) {
+        const issuer = packFacts()[vendor]?.credentialIssuer;
+        if (issuer && !detected.has(issuer))
+            detected.set(issuer, [`credential issuer: ${vendor}`]);
+    }
     // unknown external-service-shaped signals (no vendor mapping). A dep from a scope with a
     // twin-mapped sibling counts even when its own name is not service-shaped — the Dub run's
     // @upstash/redis + @upstash/ratelimit disappeared exactly here while @upstash/qstash mapped.
@@ -569,7 +632,7 @@ export function detectRepoVendors(repoPath) {
         if (isSmtpEnvSignal(name))
             continue; // now a DETECTED vendor (above), no longer an unknown
         const stem = envVendorStem(name, ENV_SUFFIX_STRICT);
-        if (stem === null || ENV_STEM_VENDORS[stem] || ENV_STEM_IGNORE.has(stem))
+        if (stem === null || envStemVendor(name, ENV_SUFFIX_STRICT) || ENV_STEM_IGNORE.has(stem))
             continue;
         // The registry's notExternal suppressions apply to ENV STEMS too — the census adjudicated
         // 40 app-internal stems ("names no vendor") that this loop kept flagging because only the
@@ -709,9 +772,10 @@ export function coverWorld(world, repoPath, options = {}) {
         // An HTTP-valued endpoint variable the world injects from a twin (its endpoint env or a
         // template) is routed to that twin; only an HTTP URL nobody in the world supplies stays unknown.
         const injectedHttp = requirement.protocol === null && binding?.protocol === 'http';
-        const unresolved = !injectedHttp && (requirement.protocol === null || requirement.env === undefined || (binding !== undefined && binding.protocol === null));
+        const issued = binding?.protocol === 'issued';
+        const unresolved = !injectedHttp && !issued && (requirement.protocol === null || requirement.env === undefined || (binding !== undefined && binding.protocol === null));
         let status = unresolved ? 'unknown-sdk'
-            : injectedHttp || binding?.protocol === requirement.protocol ? 'covered' : 'missing';
+            : injectedHttp || issued || binding?.protocol === requirement.protocol ? 'covered' : 'missing';
         if (status !== 'covered' && acknowledge[vendor] !== undefined) {
             status = 'acknowledged';
             acknowledged.push({ vendor, reason: acknowledge[vendor] });

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

@@ -9,6 +9,6 @@ export type EnvOutputClaim = {
     backupDir: string;
 };
 /** Refuse a custody/input file before any World service or lifecycle mutation starts. */
-export declare function claimEnvOutput(path: string, backupDir: string, prior?: PriorOutput, force?: boolean): EnvOutputClaim;
+export declare function claimEnvOutput(path: string, backupDir: string, priors?: PriorOutput[], force?: boolean): EnvOutputClaim;
 export declare function publishEnvOutput(claim: EnvOutputClaim, contents: string): void;
 export {};

package/dist/src/env-output.js

@@ -15,9 +15,9 @@ function inspect(path) {
     }
 }
 /** Refuse a custody/input file before any World service or lifecycle mutation starts. */
-export function claimEnvOutput(path, backupDir, prior, force = false) {
+export function claimEnvOutput(path, backupDir, priors = [], force = false) {
     const contents = inspect(path);
-    if (contents !== undefined && !force && !(prior?.path === path && Buffer.from(prior.contents).equals(contents))) {
+    if (contents !== undefined && !force && !priors.some((prior) => prior.path === path && Buffer.from(prior.contents).equals(contents))) {
         throw new Error(`World refuses existing --env-out file it does not own: ${path}. Choose a new output path; never use a custody file. --force explicitly replaces a file with a private backup.`);
     }
     if (force && contents !== undefined) {

package/dist/src/fixture-env.js

@@ -134,28 +134,20 @@ export function isGoogleServiceAccountEnvName(name) {
  * 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. */
+ * world-runtime must not import a pack, and the tests pin every value against the injector's host
+ * rules (the pack's facts) so either side changing makes the contract fail loudly. */
 const ENDPOINT_SHAPES = [
-    // the vendor's own API URL, which the World routes to its twin: an app that reads a base-URL override (empty in its
-    // example, the vendor's URL as its default) gets the vendor's URL, never an unreachable fake
-    { match: /^DYNADOT_BASE_URL$/, value: 'https://api.dynadot.com/api3.json', source: 'packages/twin/dynadot/src/index.ts hosts (api.dynadot.com); dubinc/dub apps/web/lib/dynadot/client.ts default' },
     // Vercel KV's REST URL (the Upstash Redis REST API under Vercel's names): an upstash host the twin serves
-    { match: /(^|_)KV_REST_API_URL$/, value: 'https://twin-fake.upstash.io', source: 'packages/world-core inject VENDOR_HOSTS.upstash; lukevella/rallly KV_REST_API_URL' },
+    { match: /(^|_)KV_REST_API_URL$/, value: 'https://twin-fake.upstash.io', source: 'the upstash pack\'s host rules (.upstash.io); lukevella/rallly KV_REST_API_URL' },
     {
         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',
+        source: 'the upstash pack\'s host rules (.upstash.io)',
     },
     {
         match: /(^|_)TINYBIRD_API_URL$/,
         value: 'https://api.tinybird.co',
-        source: 'packages/world-core/inject.cjs VENDOR_HOSTS.tinybird',
+        source: 'the tinybird pack\'s host rules (api.tinybird.co)',
     },
 ];
 /** Credentials whose SHAPE the receiving twin actually checks.
@@ -174,19 +166,20 @@ const CREDENTIAL_SHAPES = [
     // 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' },
+    { match: /(^|_)RESEND_[A-Z0-9_]*(KEY|TOKEN|SECRET)$/, value: (name) => `re_twinfake_${name.toLowerCase().replace(/_/g, '')}`, source: 'earlier @volter/twin-resend 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' },
+    { match: /(^|_)VERCEL_[A-Z0-9_]*(TOKEN|API_KEY)$/, value: () => 'vercel_twin_bootstrap_token', source: 'earlier @volter/twin-vercel 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
+    { match: /(^|_)TREMENDOUS_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'TEST_twin_sandbox_api_key', source: 'earlier @volter/twin-tremendous manifest.ts auth.keyFormat' },
+    // Clerk: the SECRET key is the instance's own (the clerk twin takes this one and the keys its API Keys door makes,
+    // earlier @volter/twin-clerk server.ts CLERK_TWIN_SECRET_KEY), and 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
+    // (`.clerk.accounts.dev`, earlier @volter/twin-clerk 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).
     // Stripe's keys carry their kind in their prefix, and applications check it before calling (Cal.com's Stripe app
@@ -194,15 +187,14 @@ const CREDENTIAL_SHAPES = [
     { match: /(^|_)STRIPE_[A-Z0-9_]*WEBHOOK_SECRET$/, value: () => 'whsec_twinfake0000000000000000000000000000', source: 'https://docs.stripe.com/webhooks#verify-events' },
     { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
     { match: /(^|_)STRIPE_[A-Z0-9_]*(PUBLISHABLE|PUBLIC)(_API)?_KEY$/, value: () => 'pk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (pk_test_)' },
-    // The slack twin answers a bearer that is none of Slack's token kinds with `invalid_auth`, as Slack does; any `xoxb-`
-    // acts as the workspace bot, and an app-level token is `xapp-`.
-    { match: /(^|_)SLACK_[A-Z0-9_]*APP_TOKEN$/, value: () => 'xapp-1-twinfake', source: 'packages/twin/slack/src/slack-server.ts (bearer /^(xox|xapp-)/)' },
-    { match: /(^|_)SLACK_([A-Z0-9_]*_)?BOT_TOKEN$|(^|_)SLACK_TOKEN$/, value: () => 'xoxb-twinfake', source: 'packages/twin/slack/src/slack-server.ts (bearer /^(xox|xapp-)/); GET /twin identity (any other xoxb-* is the workspace bot)' },
     // tavily-auth.ts and firecrawl-auth.ts refuse a key without the vendor's prefix with the vendor's 401
-    { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'packages/twin/tavily/src/tavily-auth.ts' },
-    { match: /(^|_)FIRECRAWL_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'fc-twinfake00000000000000000000000', source: 'packages/twin/firecrawl/src/firecrawl-auth.ts FIRECRAWL_KEY_PREFIX' },
-    { 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' },
+    { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'earlier @volter/twin-tavily tavily-auth.ts' },
+    { match: /(^|_)FIRECRAWL_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'fc-twinfake00000000000000000000000', source: 'earlier @volter/twin-firecrawl firecrawl-auth.ts FIRECRAWL_KEY_PREFIX' },
+    // a Clerk webhook's signing secret is Svix's (`whsec_` and base64), which the app's verifier decodes; the World registers
+    // its endpoint with the same secret (the Clerk twin's webhooks door takes `signing_secret`)
+    { match: /(^|_)CLERK_WEBHOOK(_SIGNING)?_SECRET$/, value: () => `whsec_${Buffer.from('twin-fake-clerk-webhook-secret!!').toString('base64')}`, source: 'https://clerk.com/docs/webhooks/sync-data (CLERK_WEBHOOK_SIGNING_SECRET, whsec_); https://docs.svix.com/receiving/verifying-payloads/how-manual' },
+    { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'earlier @volter/twin-clerk manifest.ts' },
+    { match: /(^|_)CLERK_[A-Z0-9_]*PUBLISHABLE[A-Z0-9_]*$/, value: () => `pk_test_${Buffer.from('twin.clerk.accounts.dev$').toString('base64')}`, source: 'earlier @volter/twin-clerk 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

package/dist/src/host-cli.js

@@ -31,11 +31,13 @@ for (let i = 0; i < argv.length; i++) {
     const scenarioPath = flags.find((f) => f.startsWith('scenario='))?.slice('scenario='.length);
     // the World's managed database a pack declaring `managedDatabase` is bound to (runtime.ts, managedDatabaseFor)
     const database = flags.find((f) => f.startsWith('database='))?.slice('database='.length);
+    // the twin's side ports the runtime allocated (TwinPack.sidePorts): `side.<factory option>=<port>`
+    const sideOptions = Object.fromEntries(flags.filter((f) => /^side\.[A-Za-z0-9]+=\d+$/.test(f)).map((f) => { const [k, v] = f.slice('side.'.length).split('='); return [k, Number(v)]; }));
     if (!id || !module || !exportName || !port || !root) {
-        process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>][|database=<url>])\n`);
+        process.stderr.write(`bad --spec "${raw}" (want id|module|export|port|root[|ro][|scenario=<handlers file>][|database=<url>][|side.<option>=<port>…])\n`);
         process.exit(2);
     }
-    specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}), ...(database ? { database } : {}) });
+    specs.push({ id, module, export: exportName, port: Number(port), root, readOnly: ro === 'ro', ...(scenarioPath ? { scenarioPath } : {}), ...(database ? { database } : {}), ...(Object.keys(sideOptions).length ? { sideOptions } : {}) });
 }
 if (specs.length === 0) {
     process.stderr.write('no --spec given\n');

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

@@ -11,6 +11,12 @@
 //   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';
+import { registerPack } from '@volter/world-core/runtime';
+// The host checks the loaded descriptor before it invokes a factory (architecture, "The catalog"): each twin id the host
+// tests serve with this fixture is a Protocol 3 pack, registered at import in whichever process or worker loads it.
+for (const vendor of ['a', 'b', 'async', 'fixed', 'flaky', 'pending', 'recording', 'rejecting']) {
+    registerPack({ vendor, protocol: '3', transport: 'rest', resources: [] });
+}
 export function createFaultTwinServer(options = {}) {
     const root = options.root;
     const countFile = root ? join(root, 'count') : undefined;

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

@@ -1,4 +1,10 @@
 /** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
 export declare function publishHostReady(path: string, boot: string, ports: Record<string, number>): void;
-/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
-export declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void>;
+/**
+ * Receipt admission is cancellation-aware; stale or malformed state is never
+ * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
+ * one: each change in `progress` (the host log's size, which grows with every
+ * twin it starts) begins the bound again, so a host still starting its twins
+ * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ */
+export declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress?: () => number): Promise<void>;

package/dist/src/host-ready.js

@@ -9,9 +9,16 @@ export function publishHostReady(path, boot, ports) {
     writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
     renameSync(temporary, path);
 }
-/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
-export async function waitForHostReady(path, boot, ports, timeoutMs, abort) {
-    const started = Date.now();
+/**
+ * Receipt admission is cancellation-aware; stale or malformed state is never
+ * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
+ * one: each change in `progress` (the host log's size, which grows with every
+ * twin it starts) begins the bound again, so a host still starting its twins
+ * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ */
+export async function waitForHostReady(path, boot, ports, timeoutMs, abort, progress = () => 0) {
+    let started = Date.now();
+    let seen = progress();
     for (;;) {
         abort.throwIfAborted();
         let bytes;
@@ -35,8 +42,13 @@ export async function waitForHostReady(path, boot, ports, timeoutMs, abort) {
             }
             return;
         }
+        const now = progress();
+        if (now !== seen) {
+            seen = now;
+            started = Date.now();
+        }
         if (Date.now() - started >= timeoutMs)
-            throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+            throw new Error(`The co-located host made no progress for ${timeoutMs} ms before completing every declared start.`);
         await new Promise((resolve, reject) => {
             const cancel = () => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
             const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));

package/dist/src/host-worker.js

@@ -1,3 +1,4 @@
+import { getPack, registerPack } from '@volter/world-core/runtime';
 // 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
@@ -6,11 +7,15 @@ import { parentPort, workerData } from 'node:worker_threads';
 import { importModule } from "./import-module.js";
 const spec = workerData;
 const mod = await importModule(spec.module);
+const descriptor = mod.pack ?? getPack(spec.id);
+if (!descriptor || descriptor.vendor !== spec.id)
+    throw new Error(`Twin ${spec.id}: the loaded module declares no matching pack descriptor`);
+registerPack(descriptor);
 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, ...(spec.database !== undefined ? { database: spec.database } : {}) });
+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 });
 // The Bun.serve listener keeps this worker's event loop alive; nothing else to do.

package/dist/src/host.d.ts

@@ -14,6 +14,8 @@ export type ColocatedTwinSpec = {
     /** The World's managed database a pack declaring `managedDatabase` serves over (runtime.ts, managedDatabaseFor):
      *  the colocated form of the spawn path's `serve <arg> <url>`. */
     database?: string;
+    /** The twin's side ports the runtime allocated (TwinPack.sidePorts), as the factory's options (`inspectPort`). */
+    sideOptions?: Record<string, number>;
 };
 export type HostIsolation = 'shared' | 'worker';
 export type ColocatedHost = {

package/dist/src/host.js

@@ -1,3 +1,4 @@
+import { getPack, registerPack } from '@volter/world-core/runtime';
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
 // `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
@@ -26,6 +27,10 @@ import { pathToFileURL } from 'node:url';
 import { parallelStartup } from "./startup.js";
 async function loadFactory(spec) {
     const mod = await importModule(spec.module);
+    const descriptor = mod.pack ?? getPack(spec.id);
+    if (!descriptor || descriptor.vendor !== spec.id)
+        throw new Error(`Twin ${spec.id}: the loaded module declares no matching pack descriptor`);
+    registerPack(descriptor);
     const factory = mod[spec.export];
     if (typeof factory !== 'function') {
         throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);
@@ -82,13 +87,16 @@ export async function startColocatedHost(specs, options = {}) {
         try {
             await parallelStartup(specs, async (spec) => {
                 const factory = await loadFactory(spec);
-                const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
+                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);
                 if (!Number.isInteger(server.port) || server.port < 1 || server.port > 65535 || (spec.port !== 0 && server.port !== spec.port)) {
                     throw new Error(`Twin "${spec.id}" bound port ${server.port}, requested ${spec.port}.`);
                 }
                 ports[spec.id] = server.port;
+                // Each start is progress the runtime's readiness wait counts (host-ready.ts); the line says when,
+                // in milliseconds since the host process began, since the log's own lines carry no time.
+                onEvent({ twin: spec.id, kind: 'started', detail: `port ${server.port} at ${Math.round(performance.now())} ms` });
             });
         }
         catch (error) {

package/dist/src/index.d.ts

@@ -21,9 +21,9 @@ export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, inj
 export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.js';
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
 export { STATE_GITIGNORE } from './init.js';
-export { clockFile } from './runtime.js';
+export { clockFile, instanceDir } from './runtime.js';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.js';
-export { MINT_ENV } from './schema.js';
+export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.js';
 export type { EnvDisposition, InitEnvRow, InitInfraStub, InitOptions, InitPlan, InitResult, InitVendorPlan, InitWiring, } from './init.js';
 export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from './attach.js';
 export type { ResolvedWorldRef, WorldManifest, WorldRefSource } from './attach.js';

package/dist/src/index.js

@@ -19,9 +19,9 @@ export { coverWorld, detectRepoVendors, envNameVendor, formatCoverageReport, inj
 // world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";
 export { STATE_GITIGNORE } from "./init.js";
-export { clockFile } from "./runtime.js";
+export { clockFile, instanceDir } from "./runtime.js";
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, packCli, packEntry } from "./catalog.js";
-export { MINT_ENV } from "./schema.js";
+export { ISSUE_ENV_PREFIX, MINT_ENV } from "./schema.js";
 export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRef, WORLD_REF_FILE, worldManifest, } from "./attach.js";
 export { parseSni, readReflectRoutes, reflectRoutesPath, reflectManifestPath, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, CA_TRUST_ENV, ATTACHED_CA_PATH, startReflectFront, startReflectResolver, writeReflectRoutes, } from "./reflect.js";
 export { startColocatedHost } from "./host.js";