@volter/world-core 2.0.7 → 2.0.8

package/app-route.cjs

@@ -15,39 +15,66 @@
 // so a host or URL recorded after the process started applies.
 
 // node's own modules are required where used: importing this module does nothing (a pack's egress imports it)
-const APP_ROUTES = new Map(); // cache: instance file -> { checkedAt, mtimeMs, route }
+const APP_ROUTES = new Map(); // cache: instance file -> { checkedAt, mtimeMs, routes, services, twins }
 
-/** The application's route in the instance `instanceFile`: { origin, hosts } or null when none is recorded. */
-function appRoute(instanceFile) {
-  if (!instanceFile) return null;
+/** Each application's route of one record entry: its name, its URL (null: the World's service of its name), its hosts. */
+function entryRoute(name, entry) {
+  if (!entry || !Array.isArray(entry.hosts) || !entry.hosts.length) return null;
+  return { name, url: typeof entry.url === 'string' ? entry.url : null, hosts: new Set(entry.hosts.map((h) => String(h).toLowerCase())) };
+}
+
+/** The instance's applications (`app-url.json`: the top-level record is the application named `app`, `apps` holds the
+ *  others by name) with their origins, and the twins the World runs by vendor key, read from the instance's own env:
+ *  a process's env is the World's as it stood when that process started, which a twin started before others (or the
+ *  twin itself) lacks. Read at most once a second. */
+function readRoutes(instanceFile) {
+  if (!instanceFile) return { routes: [], twins: {} };
   const now = Date.now();
   let held = APP_ROUTES.get(instanceFile);
-  if (held && now - held.checkedAt < 1000) return held.route && held.route.origin ? held.route : null;
-  if (!held) { held = { checkedAt: 0, mtimeMs: -1, route: null }; APP_ROUTES.set(instanceFile, held); }
+  if (held && now - held.checkedAt < 1000) return held;
+  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
   held.checkedAt = now;
   const fs = require('fs');
   const path = require('path');
   const file = path.join(path.dirname(instanceFile), 'app-url.json');
+  // the instance (its services, and the World env its twins' URLs are in); one caught mid-write keeps the last read
+  try {
+    const instance = JSON.parse(fs.readFileSync(instanceFile, 'utf8'));
+    held.services = instance.services || {};
+    held.twins = require('./vendor-hosts.cjs').twinOrigins(instance.env || {});
+  } catch { /* no instance yet, or mid-write */ }
   try {
     const mtimeMs = fs.statSync(file).mtimeMs;
     if (mtimeMs !== held.mtimeMs) {
       held.mtimeMs = mtimeMs;
       const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-      held.route = Array.isArray(record.hosts) && record.hosts.length
-        ? { url: typeof record.url === 'string' ? record.url : null, hosts: new Set(record.hosts.map((h) => String(h).toLowerCase())) }
-        : null;
+      const others = record.apps && typeof record.apps === 'object' ? Object.entries(record.apps) : [];
+      held.routes = [entryRoute('app', record), ...others.map(([name, entry]) => entryRoute(name, entry))].filter(Boolean);
+    }
+    // a route with hosts and no URL names the World's service of the application's name, wherever this boot put it
+    const services = held.services;
+    for (const route of held.routes) {
+      const at = route.url ?? services[route.name]?.url;
+      route.origin = typeof at === 'string' ? at.replace(/\/$/, '') : null;
     }
-    // a record with hosts and no URL names the World's own `app` service, wherever this boot put it
-    if (held.route && !held.route.url) {
-      const service = JSON.parse(fs.readFileSync(instanceFile, 'utf8')).services?.app;
-      held.route.origin = typeof service?.url === 'string' ? service.url.replace(/\/$/, '') : null;
-    } else if (held.route) held.route.origin = held.route.url.replace(/\/$/, '');
   } catch (error) {
     // gone: no route; caught mid-write: the last one read stands until the next look
     held.mtimeMs = -1;
-    if (error && error.code === 'ENOENT') held.route = null;
+    if (error && error.code === 'ENOENT') held.routes = [];
   }
-  return held.route && held.route.origin ? held.route : null;
+  return held;
+}
+
+/** The application that answers `host` in the instance `instanceFile`, or null: never a name a vendor's host rule gives
+ *  a twin the World runs, which the twin answers instead. The twins are those the instance's env points at, with the
+ *  caller's own (`twins`: vendor keys as `twinOrigins` reads them, the injector's map). */
+function appRouteFor(instanceFile, host, twins = {}) {
+  const bare = String(host || '').toLowerCase().replace(/\.$/, '');
+  const held = readRoutes(instanceFile);
+  const route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  if (!route) return null;
+  const runs = (vendor) => Object.hasOwn(held.twins, vendor) || Object.hasOwn(twins, vendor);
+  return require('./vendor-hosts.cjs').vendorsOfHost(bare).some(runs) ? null : route;
 }
 
 /** Whether `host` is one of the app's recorded hostnames: named exactly, or under a recorded wildcard (`*.dub.link`),
@@ -70,10 +97,8 @@ function appDestination(value, env = process.env) {
   let url;
   try { url = new URL(String(value)); } catch { return null; }
   if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
-  const route = appRoute(env.VOLTER_WORLD_INSTANCE);
-  const host = url.hostname.toLowerCase().replace(/\.$/, '');
-  // never a name a vendor's host rule gives its twin, as the injector's resolveTwin rules
-  return route && appHostMatch(route.hosts, host) && !require('./vendor-hosts.cjs').isVendorHost(host) ? route : null;
+  // never a name a vendor's host rule gives a twin the World runs, as the injector's resolveTwin rules
+  return appRouteFor(env.VOLTER_WORLD_INSTANCE, url.hostname, require('./vendor-hosts.cjs').twinOrigins(env));
 }
 
 let SESSION_CA = undefined; // lazily read once; NODE_EXTRA_CA_CERTS set after process start
@@ -240,4 +265,4 @@ async function appFetch(value, init = {}) {
   }
 }
 
-module.exports = { appRoute, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, sessionCa };
+module.exports = { appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, sessionCa };

package/app-route.d.cts

@@ -1,6 +1,6 @@
-export interface AppRoute { readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
+export interface AppRoute { readonly name: string; readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
 export interface AppAnswer { readonly status: number; readonly headers: Record<string, string>; readonly body: string }
-export function appRoute(instanceFile: string | undefined): AppRoute | null;
+export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>): AppRoute | null;
 export function appHostMatch(hosts: ReadonlySet<string>, host: string): boolean;
 export function appForwardHeaders(url: URL): Record<string, string>;
 export function appDestination(value: string | URL, env?: Readonly<Record<string, string | undefined>>): AppRoute | null;

package/dist/app-route.cjs

@@ -15,39 +15,66 @@
 // so a host or URL recorded after the process started applies.
 
 // node's own modules are required where used: importing this module does nothing (a pack's egress imports it)
-const APP_ROUTES = new Map(); // cache: instance file -> { checkedAt, mtimeMs, route }
+const APP_ROUTES = new Map(); // cache: instance file -> { checkedAt, mtimeMs, routes, services, twins }
 
-/** The application's route in the instance `instanceFile`: { origin, hosts } or null when none is recorded. */
-function appRoute(instanceFile) {
-  if (!instanceFile) return null;
+/** Each application's route of one record entry: its name, its URL (null: the World's service of its name), its hosts. */
+function entryRoute(name, entry) {
+  if (!entry || !Array.isArray(entry.hosts) || !entry.hosts.length) return null;
+  return { name, url: typeof entry.url === 'string' ? entry.url : null, hosts: new Set(entry.hosts.map((h) => String(h).toLowerCase())) };
+}
+
+/** The instance's applications (`app-url.json`: the top-level record is the application named `app`, `apps` holds the
+ *  others by name) with their origins, and the twins the World runs by vendor key, read from the instance's own env:
+ *  a process's env is the World's as it stood when that process started, which a twin started before others (or the
+ *  twin itself) lacks. Read at most once a second. */
+function readRoutes(instanceFile) {
+  if (!instanceFile) return { routes: [], twins: {} };
   const now = Date.now();
   let held = APP_ROUTES.get(instanceFile);
-  if (held && now - held.checkedAt < 1000) return held.route && held.route.origin ? held.route : null;
-  if (!held) { held = { checkedAt: 0, mtimeMs: -1, route: null }; APP_ROUTES.set(instanceFile, held); }
+  if (held && now - held.checkedAt < 1000) return held;
+  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
   held.checkedAt = now;
   const fs = require('fs');
   const path = require('path');
   const file = path.join(path.dirname(instanceFile), 'app-url.json');
+  // the instance (its services, and the World env its twins' URLs are in); one caught mid-write keeps the last read
+  try {
+    const instance = JSON.parse(fs.readFileSync(instanceFile, 'utf8'));
+    held.services = instance.services || {};
+    held.twins = require('./vendor-hosts.cjs').twinOrigins(instance.env || {});
+  } catch { /* no instance yet, or mid-write */ }
   try {
     const mtimeMs = fs.statSync(file).mtimeMs;
     if (mtimeMs !== held.mtimeMs) {
       held.mtimeMs = mtimeMs;
       const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-      held.route = Array.isArray(record.hosts) && record.hosts.length
-        ? { url: typeof record.url === 'string' ? record.url : null, hosts: new Set(record.hosts.map((h) => String(h).toLowerCase())) }
-        : null;
+      const others = record.apps && typeof record.apps === 'object' ? Object.entries(record.apps) : [];
+      held.routes = [entryRoute('app', record), ...others.map(([name, entry]) => entryRoute(name, entry))].filter(Boolean);
+    }
+    // a route with hosts and no URL names the World's service of the application's name, wherever this boot put it
+    const services = held.services;
+    for (const route of held.routes) {
+      const at = route.url ?? services[route.name]?.url;
+      route.origin = typeof at === 'string' ? at.replace(/\/$/, '') : null;
     }
-    // a record with hosts and no URL names the World's own `app` service, wherever this boot put it
-    if (held.route && !held.route.url) {
-      const service = JSON.parse(fs.readFileSync(instanceFile, 'utf8')).services?.app;
-      held.route.origin = typeof service?.url === 'string' ? service.url.replace(/\/$/, '') : null;
-    } else if (held.route) held.route.origin = held.route.url.replace(/\/$/, '');
   } catch (error) {
     // gone: no route; caught mid-write: the last one read stands until the next look
     held.mtimeMs = -1;
-    if (error && error.code === 'ENOENT') held.route = null;
+    if (error && error.code === 'ENOENT') held.routes = [];
   }
-  return held.route && held.route.origin ? held.route : null;
+  return held;
+}
+
+/** The application that answers `host` in the instance `instanceFile`, or null: never a name a vendor's host rule gives
+ *  a twin the World runs, which the twin answers instead. The twins are those the instance's env points at, with the
+ *  caller's own (`twins`: vendor keys as `twinOrigins` reads them, the injector's map). */
+function appRouteFor(instanceFile, host, twins = {}) {
+  const bare = String(host || '').toLowerCase().replace(/\.$/, '');
+  const held = readRoutes(instanceFile);
+  const route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  if (!route) return null;
+  const runs = (vendor) => Object.hasOwn(held.twins, vendor) || Object.hasOwn(twins, vendor);
+  return require('./vendor-hosts.cjs').vendorsOfHost(bare).some(runs) ? null : route;
 }
 
 /** Whether `host` is one of the app's recorded hostnames: named exactly, or under a recorded wildcard (`*.dub.link`),
@@ -70,10 +97,8 @@ function appDestination(value, env = process.env) {
   let url;
   try { url = new URL(String(value)); } catch { return null; }
   if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
-  const route = appRoute(env.VOLTER_WORLD_INSTANCE);
-  const host = url.hostname.toLowerCase().replace(/\.$/, '');
-  // never a name a vendor's host rule gives its twin, as the injector's resolveTwin rules
-  return route && appHostMatch(route.hosts, host) && !require('./vendor-hosts.cjs').isVendorHost(host) ? route : null;
+  // never a name a vendor's host rule gives a twin the World runs, as the injector's resolveTwin rules
+  return appRouteFor(env.VOLTER_WORLD_INSTANCE, url.hostname, require('./vendor-hosts.cjs').twinOrigins(env));
 }
 
 let SESSION_CA = undefined; // lazily read once; NODE_EXTRA_CA_CERTS set after process start
@@ -240,4 +265,4 @@ async function appFetch(value, init = {}) {
   }
 }
 
-module.exports = { appRoute, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, sessionCa };
+module.exports = { appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, sessionCa };

package/dist/app-route.d.cts

@@ -1,6 +1,6 @@
-export interface AppRoute { readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
+export interface AppRoute { readonly name: string; readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
 export interface AppAnswer { readonly status: number; readonly headers: Record<string, string>; readonly body: string }
-export function appRoute(instanceFile: string | undefined): AppRoute | null;
+export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>): AppRoute | null;
 export function appHostMatch(hosts: ReadonlySet<string>, host: string): boolean;
 export function appForwardHeaders(url: URL): Record<string, string>;
 export function appDestination(value: string | URL, env?: Readonly<Record<string, string | undefined>>): AppRoute | null;

package/dist/inject.cjs

@@ -42,7 +42,7 @@ const { createPublicKey, createVerify } = require('crypto');
 
 // the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
 // serves it) has its own home, shared with the application route
-const { VENDOR_HOSTS, isVendorHost } = require('./vendor-hosts.cjs');
+const { VENDOR_HOSTS, twinEnvStem, twinOrigins } = require('./vendor-hosts.cjs');
 const dns = require('dns');
 
 function decodeBase64UrlJson(part) {
@@ -186,9 +186,6 @@ function installPrismaAdapterShim() {
 // answers as s3/dynamodb/timestream/sesv2/secretsmanager/bedrock — there IS no 'aws' vendor key, which is exactly the
 // silent-inert-env trap this helper exists to make checkable). Shared with world-runtime so
 // its "this injectEnv var is inert" warning can never drift from what readMap actually reads.
-function twinEnvStem(vendor) {
-  return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
-}
 
 function twinUrlVendor(name) {
   const match = /^([A-Z][A-Z0-9_]*)_TWIN_URL$/.exec(String(name || ''));
@@ -200,20 +197,7 @@ function readMap(env) {
   const map = {};
   // the World instance whose recorded app hosts this map routes (APP HOSTS, below); not a vendor, so not a key
   if (env.VOLTER_WORLD_INSTANCE) Object.defineProperty(map, APP_INSTANCE, { value: env.VOLTER_WORLD_INSTANCE, enumerable: false });
-  for (const vendor of Object.keys(VENDOR_HOSTS)) {
-    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
-    if (url) map[vendor] = url.replace(/\/$/, '');
-  }
-  if (env.TWIN_INJECT) {
-    for (const pair of env.TWIN_INJECT.split(',')) {
-      const eq = pair.indexOf('=');
-      if (eq <= 0) continue;
-      const vendor = pair.slice(0, eq).trim();
-      const url = pair.slice(eq + 1).trim();
-      if (vendor && url && VENDOR_HOSTS[vendor]) map[vendor] = url.replace(/\/$/, '');
-    }
-  }
-  return map;
+  return Object.assign(map, twinOrigins(env));
 }
 
 /**
@@ -237,11 +221,12 @@ function resolveTwin(hostname, map, pathname) {
   }
   // last, the application's own production hostnames, routed to where it listens in the World; never the World's own
   // origin or a twin's, whose requests carry the World key
-  const app = appRoute(map[APP_INSTANCE]);
   const bare = host.replace(/\.$/, '');
   const base = worldBase();
-  // a name a vendor's host rule gives its twin is never the application's, whether or not that twin runs here
-  if (app && appHostMatch(app.hosts, bare) && !isVendorHost(bare) && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
+  // a name a vendor's host rule gives a twin running here is that twin's, never an application's (a vendor with no
+  // twin here can be one of the World's applications: the product itself)
+  const app = appRouteFor(map[APP_INSTANCE], bare, map);
+  if (app && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
     return { vendor: 'app', origin: app.origin };
   }
   return null;
@@ -254,7 +239,7 @@ function resolveTwin(hostname, map, pathname) {
 // was made with (appForwardHeaders), so an application serving several hostnames answers each as in production.
 const APP_INSTANCE = Symbol.for('volter.inject.appInstance');
 // the route itself (the record, its wildcards, the forwarded headers) has one home, shared with the twins' deliveries
-const { appRoute, appHostMatch, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
+const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
 
 // HOSTS A TWIN CLAIMS WHILE IT RUNS (packRegistry `hostsClaimed`): no descriptor can list a name a person makes answer
 // to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the

package/dist/vendor-hosts.cjs

@@ -198,4 +198,36 @@ function isVendorHost(host) {
   return Object.keys(VENDOR_HOSTS).some((vendor) => VENDOR_HOSTS[vendor](h));
 }
 
-module.exports = { VENDOR_HOSTS, isVendorHost };
+/** The vendors whose host rule names `host` (any path): the twins that answer it while they run. */
+function vendorsOfHost(host) {
+  const h = String(host || '').toLowerCase().replace(/\.$/, '');
+  return Object.keys(VENDOR_HOSTS).filter((vendor) => VENDOR_HOSTS[vendor](h));
+}
+
+/** A vendor key's env stem: `S3_TWIN_URL` is s3's; `googleauth` → GOOGLEAUTH. */
+function twinEnvStem(vendor) {
+  return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
+/** The vendors whose twin `env` points at, each with its origin: `<STEM>_TWIN_URL`, then `TWIN_INJECT` pairs
+ *  (`vendor=url,…`). The one reading of it: the injector's map is this, and so is "the twins the World runs" wherever a
+ *  route asks it (a service's id is not its vendor key: the aws service serves s3, dynamodb and others). */
+function twinOrigins(env) {
+  const map = {};
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
+    if (url) map[vendor] = url.replace(/\/$/, '');
+  }
+  if (env.TWIN_INJECT) {
+    for (const pair of String(env.TWIN_INJECT).split(',')) {
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      const vendor = pair.slice(0, eq).trim();
+      const url = pair.slice(eq + 1).trim();
+      if (vendor && url && Object.hasOwn(VENDOR_HOSTS, vendor)) map[vendor] = url.replace(/\/$/, '');
+    }
+  }
+  return map;
+}
+
+module.exports = { VENDOR_HOSTS, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/inject.cjs

@@ -42,7 +42,7 @@ const { createPublicKey, createVerify } = require('crypto');
 
 // the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
 // serves it) has its own home, shared with the application route
-const { VENDOR_HOSTS, isVendorHost } = require('./vendor-hosts.cjs');
+const { VENDOR_HOSTS, twinEnvStem, twinOrigins } = require('./vendor-hosts.cjs');
 const dns = require('dns');
 
 function decodeBase64UrlJson(part) {
@@ -186,9 +186,6 @@ function installPrismaAdapterShim() {
 // answers as s3/dynamodb/timestream/sesv2/secretsmanager/bedrock — there IS no 'aws' vendor key, which is exactly the
 // silent-inert-env trap this helper exists to make checkable). Shared with world-runtime so
 // its "this injectEnv var is inert" warning can never drift from what readMap actually reads.
-function twinEnvStem(vendor) {
-  return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
-}
 
 function twinUrlVendor(name) {
   const match = /^([A-Z][A-Z0-9_]*)_TWIN_URL$/.exec(String(name || ''));
@@ -200,20 +197,7 @@ function readMap(env) {
   const map = {};
   // the World instance whose recorded app hosts this map routes (APP HOSTS, below); not a vendor, so not a key
   if (env.VOLTER_WORLD_INSTANCE) Object.defineProperty(map, APP_INSTANCE, { value: env.VOLTER_WORLD_INSTANCE, enumerable: false });
-  for (const vendor of Object.keys(VENDOR_HOSTS)) {
-    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
-    if (url) map[vendor] = url.replace(/\/$/, '');
-  }
-  if (env.TWIN_INJECT) {
-    for (const pair of env.TWIN_INJECT.split(',')) {
-      const eq = pair.indexOf('=');
-      if (eq <= 0) continue;
-      const vendor = pair.slice(0, eq).trim();
-      const url = pair.slice(eq + 1).trim();
-      if (vendor && url && VENDOR_HOSTS[vendor]) map[vendor] = url.replace(/\/$/, '');
-    }
-  }
-  return map;
+  return Object.assign(map, twinOrigins(env));
 }
 
 /**
@@ -237,11 +221,12 @@ function resolveTwin(hostname, map, pathname) {
   }
   // last, the application's own production hostnames, routed to where it listens in the World; never the World's own
   // origin or a twin's, whose requests carry the World key
-  const app = appRoute(map[APP_INSTANCE]);
   const bare = host.replace(/\.$/, '');
   const base = worldBase();
-  // a name a vendor's host rule gives its twin is never the application's, whether or not that twin runs here
-  if (app && appHostMatch(app.hosts, bare) && !isVendorHost(bare) && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
+  // a name a vendor's host rule gives a twin running here is that twin's, never an application's (a vendor with no
+  // twin here can be one of the World's applications: the product itself)
+  const app = appRouteFor(map[APP_INSTANCE], bare, map);
+  if (app && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
     return { vendor: 'app', origin: app.origin };
   }
   return null;
@@ -254,7 +239,7 @@ function resolveTwin(hostname, map, pathname) {
 // was made with (appForwardHeaders), so an application serving several hostnames answers each as in production.
 const APP_INSTANCE = Symbol.for('volter.inject.appInstance');
 // the route itself (the record, its wildcards, the forwarded headers) has one home, shared with the twins' deliveries
-const { appRoute, appHostMatch, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
+const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
 
 // HOSTS A TWIN CLAIMS WHILE IT RUNS (packRegistry `hostsClaimed`): no descriptor can list a name a person makes answer
 // to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/vendor-hosts.cjs

@@ -198,4 +198,36 @@ function isVendorHost(host) {
   return Object.keys(VENDOR_HOSTS).some((vendor) => VENDOR_HOSTS[vendor](h));
 }
 
-module.exports = { VENDOR_HOSTS, isVendorHost };
+/** The vendors whose host rule names `host` (any path): the twins that answer it while they run. */
+function vendorsOfHost(host) {
+  const h = String(host || '').toLowerCase().replace(/\.$/, '');
+  return Object.keys(VENDOR_HOSTS).filter((vendor) => VENDOR_HOSTS[vendor](h));
+}
+
+/** A vendor key's env stem: `S3_TWIN_URL` is s3's; `googleauth` → GOOGLEAUTH. */
+function twinEnvStem(vendor) {
+  return String(vendor).toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
+/** The vendors whose twin `env` points at, each with its origin: `<STEM>_TWIN_URL`, then `TWIN_INJECT` pairs
+ *  (`vendor=url,…`). The one reading of it: the injector's map is this, and so is "the twins the World runs" wherever a
+ *  route asks it (a service's id is not its vendor key: the aws service serves s3, dynamodb and others). */
+function twinOrigins(env) {
+  const map = {};
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    const url = env[`${twinEnvStem(vendor)}_TWIN_URL`];
+    if (url) map[vendor] = url.replace(/\/$/, '');
+  }
+  if (env.TWIN_INJECT) {
+    for (const pair of String(env.TWIN_INJECT).split(',')) {
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      const vendor = pair.slice(0, eq).trim();
+      const url = pair.slice(eq + 1).trim();
+      if (vendor && url && Object.hasOwn(VENDOR_HOSTS, vendor)) map[vendor] = url.replace(/\/$/, '');
+    }
+  }
+  return map;
+}
+
+module.exports = { VENDOR_HOSTS, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };