@volter/world-runtime 2.0.55 → 3.0.1

package/src/configs.ts

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

package/src/console-apart.ts

@@ -1,11 +1,11 @@
 // 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.
+// The console opens a World's pages (a vendor's screens) on the Worlds' origin, which it is told.
 
-import { serveHttp, type HttpServer } from '@volter/world-core';
+import { serveHttp, 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?: { worlds?: string; names?: string[]; worldOrigin?: boolean }) => Promise<Response | null> };
@@ -40,7 +40,7 @@ export async function serveConsoleApart(mount: ConsoleMount, opts: { upstream: s
 
 /** 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: string, opts: { hostname?: string; port?: number } = {}): Promise<{ url: string; worlds: string; servers: HttpServer[] }> {
@@ -71,7 +71,7 @@ export async function serveConsoleFor(target: string, opts: { hostname?: string;
       const out = new Headers(); for (const [k, v] of answer.headers) if (!['content-encoding', 'content-length', 'set-cookie'].includes(k)) out.append(k, v);
       // 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)}`);
       const csp = out.get('content-security-policy');

package/src/consumers.ts

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

package/src/covers.ts

@@ -22,15 +22,16 @@
 //             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.ts';
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from './inject-map.ts';
-import { connectionProtocol, projectConnections, projectDependencies, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from './project-inspect.ts';
+import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from './project-inspect.ts';
 import { overlayCoversMaps, packFacts } from './pack-facts.ts';
 import { statusWorld } from './runtime.ts';
-import { worldSelectionIncludes, type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.ts';
+import { ISSUE_ENV_PREFIX, worldSelectionIncludes, type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.ts';
 
 export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged' | 'excluded';
 
@@ -114,7 +115,7 @@ export function injectorEnvNameForKey(key: string): string {
 /** 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).
@@ -163,6 +164,22 @@ function envVendorStem(name: string, suffix: RegExp): string | 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: string, suffix: RegExp): string | undefined {
+  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
@@ -170,7 +187,7 @@ function envVendorStem(name: string, suffix: RegExp): string | null {
  * 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: string): boolean {
-  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
@@ -188,8 +205,7 @@ export function envNameVendor(name: string): string | null {
   // 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
@@ -220,7 +236,7 @@ function isSmtpEnvSignal(name: string): boolean {
 const SDK_SCOPE_VENDORS: Record<string, string> = {
   // (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
@@ -258,7 +274,7 @@ export 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
@@ -365,10 +381,11 @@ function servicePackNames(service: { package?: string; command?: string | string
     ...(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 is string => name !== undefined);
+    const fromManifest = /\.(?:[cm]?js|tsx?)$/.test(part) ? vendorOfPackModule(part) : undefined;
+    return [fromManifest, fromPath?.[1], fromBin?.[1], fromPkg?.[1]].filter((name): name is string => name !== undefined);
   });
 }
 
@@ -389,14 +406,10 @@ function serviceConnections(
     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) {
@@ -425,7 +438,7 @@ function serviceConnections(
         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)` });
       }
     }
   }
@@ -483,11 +496,7 @@ function addServiceIds(
     .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') {
@@ -524,7 +533,13 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
     const { path, config } = loadWorldConfig(world, root);
     const ids = new Map<string, WorldTwinId>();
     for (const service of config.services as WorldServiceConfig[]) 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);
     throw new Error(
@@ -645,8 +660,7 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
       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}`]);
   }
 
@@ -693,6 +707,44 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
     }
   }
 
+  // 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: unknown;
+        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: string): boolean => {
+      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.
@@ -713,7 +765,7 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
     if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name)) continue;
     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)) continue;
+    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
     // dep-side checks consulted the registry (§9 round two H4, 2026-08-31: 17 of 18 formally
@@ -849,9 +901,10 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
     // 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: CoverageStatus = 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/src/env-output.ts

@@ -17,9 +17,9 @@ function inspect(path: string): Buffer | undefined {
 }
 
 /** Refuse a custody/input file before any World service or lifecycle mutation starts. */
-export function claimEnvOutput(path: string, backupDir: string, prior?: PriorOutput, force = false): EnvOutputClaim {
+export function claimEnvOutput(path: string, backupDir: string, priors: PriorOutput[] = [], force = false): EnvOutputClaim {
   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/src/fixture-env.ts

@@ -149,28 +149,20 @@ export function isGoogleServiceAccountEnvName(name: string): boolean {
  * 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: Array<{ match: RegExp; value: string; source: string }> = [
-  // 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)',
   },
 ];
 
@@ -190,19 +182,20 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   // 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
@@ -210,15 +203,14 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   { 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

package/src/host-cli.ts

@@ -33,11 +33,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'); process.exit(2); }
 

package/src/host-ready.ts

@@ -10,9 +10,16 @@ export function publishHostReady(path: string, boot: string, ports: Record<strin
   renameSync(temporary, path);
 }
 
-/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
-export async function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void> {
-  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: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal, progress: () => number = () => 0): Promise<void> {
+  let started = Date.now();
+  let seen = progress();
   for (;;) {
     abort.throwIfAborted();
     let bytes: Buffer | undefined;
@@ -30,7 +37,9 @@ export async function waitForHostReady(path: string, boot: string, ports: Readon
       }
       return;
     }
-    if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+    const now = progress();
+    if (now !== seen) { seen = now; started = Date.now(); }
+    if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host made no progress for ${timeoutMs} ms before completing every declared start.`);
     await new Promise<void>((resolve, reject) => {
       const cancel = (): void => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
       const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));

package/src/host-worker.ts

@@ -1,3 +1,4 @@
+import { getPack, registerPack, type TwinPack } 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
@@ -9,16 +10,19 @@ import { importModule } from './import-module.ts';
 const spec = workerData as ColocatedTwinSpec;
 
 type TwinServer = { port: number; stop: () => void | Promise<void> };
-type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; database?: string }) => TwinServer | Promise<TwinServer>;
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; database?: string; [side: string]: unknown }) => TwinServer | Promise<TwinServer>;
 
 const mod = await importModule(spec.module);
+const descriptor = mod.pack as TwinPack | undefined ?? getPack(spec.id);
+if (!descriptor || descriptor.vendor !== spec.id) throw new Error(`Twin ${spec.id}: the loaded module declares no matching pack descriptor`);
+registerPack(descriptor);
 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, ...(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/src/host.ts

@@ -1,3 +1,4 @@
+import { getPack, registerPack, type TwinPack } from '@volter/world-core/runtime';
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
 // `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
@@ -41,6 +42,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';
@@ -59,10 +62,13 @@ export type ColocatedHost = {
 // 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; database?: string }) => TwinServer | Promise<TwinServer>;
+type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string; database?: string; [side: string]: unknown }) => TwinServer | Promise<TwinServer>;
 
 async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
   const mod = await importModule(spec.module);
+  const descriptor = mod.pack as TwinPack | undefined ?? getPack(spec.id);
+  if (!descriptor || descriptor.vendor !== spec.id) throw new Error(`Twin ${spec.id}: the loaded module declares no matching pack descriptor`);
+  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}"`);
@@ -122,13 +128,16 @@ export async function startColocatedHost(
     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) {
       const cleanup = await stop();

package/src/index.ts

@@ -99,9 +99,9 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 // world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
 export { STATE_GITIGNORE } from './init.ts';
-export { clockFile } from './runtime.ts';
+export { clockFile, instanceDir } from './runtime.ts';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.ts';
-export { MINT_ENV } from './schema.ts';
+export { ISSUE_ENV_PREFIX, MINT_ENV } from './schema.ts';
 export type {
   EnvDisposition,
   InitEnvRow,