@volter/world-core 2.0.7 → 2.0.9

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/src/rateBudget.d.ts

@@ -301,6 +301,11 @@ export declare class RateBudget {
      */
     private now;
     private lockPath;
+    /** The store the ledger persists through where there is no filesystem of this machine's to hold it: a hosted World's
+     *  (its SQL store, one instance serializing its requests). Null on the filesystem, where the ledger is the file below,
+     *  locked across processes as it always was. A hosted World's ledger is its own: two hosted Worlds sealed with one
+     *  credential each keep an allowance, where a machine's Worlds share one per credential. */
+    private store;
     /** Acquire the exclusive lock, run `fn`, always release. Bounded wait, dead locks broken. */
     private withLock;
     /** Remove a lock whose owner is provably gone. Never removes one that might still be live. */

package/dist/src/rateBudget.js

@@ -72,6 +72,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { volterHome } from "./volter-home.js";
 import { dirname, join } from 'node:path';
 import { worldPaths } from "./storage.js";
+import { FsWorldStore, getActiveWorldStore } from "./world-store.js";
 // ── bounds the kernel enforces on ANY declaration ───────────────────────────────────────────
 /** Shortest window a declaration may claim. A sub-second window is a counter reset, not a budget. */
 export const MIN_RATE_BUDGET_WINDOW_MS = 1_000;
@@ -538,8 +539,19 @@ export class RateBudget {
     }
     // ── locking + durable IO ──────────────────────────────────────────────────────────────────
     lockPath() { return `${this.path}.lock`; }
+    /** The store the ledger persists through where there is no filesystem of this machine's to hold it: a hosted World's
+     *  (its SQL store, one instance serializing its requests). Null on the filesystem, where the ledger is the file below,
+     *  locked across processes as it always was. A hosted World's ledger is its own: two hosted Worlds sealed with one
+     *  credential each keep an allowance, where a machine's Worlds share one per credential. */
+    store() {
+        const active = getActiveWorldStore();
+        return active instanceof FsWorldStore ? null : active;
+    }
     /** Acquire the exclusive lock, run `fn`, always release. Bounded wait, dead locks broken. */
     withLock(fn) {
+        const held = this.store();
+        if (held)
+            return held.withLock(this.lockPath(), fn);
         const lock = this.lockPath();
         mkdirSync(dirname(this.path), { recursive: true });
         let fd;
@@ -613,11 +625,12 @@ export class RateBudget {
      * window instead of needing a human to delete a file.
      */
     load(now) {
-        if (!existsSync(this.path))
+        const held = this.store();
+        if (held ? !held.exists(this.path) : !existsSync(this.path))
             return { v: 1, cooldownUntil: 0, entries: [] };
         let raw;
         try {
-            raw = readFileSync(this.path, 'utf8');
+            raw = held ? (held.read(this.path) ?? '') : readFileSync(this.path, 'utf8');
         }
         catch (e) {
             throw this.quarantine(now, `unreadable (${e.message})`);
@@ -668,6 +681,16 @@ export class RateBudget {
     }
     /** Atomic replace: write a temp file, then rename over the target. No partial ledger is visible. */
     save(ledger) {
+        const held = this.store();
+        if (held) {
+            try {
+                held.writeAtomic(this.path, `${JSON.stringify(ledger)}\n`);
+            }
+            catch (e) {
+                throw new RateBudgetError('ledger-unwritable', this.vendor, `${this.vendor} budget: cannot persist ${this.path} (${e.message}) — refusing rather than tracking nothing`, this.windowMs);
+            }
+            return;
+        }
         const tmp = `${this.path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
         try {
             mkdirSync(dirname(this.path), { recursive: true });

package/dist/src/twin-fetch.js

@@ -22,8 +22,17 @@ export const TWIN_PREFIX_HEADER = 'x-forwarded-prefix';
  *  callback) from this, never from the bare origin, so the URL works behind a served World. */
 export function twinPublicBase(request) {
     const prefix = request.headers.get(TWIN_PREFIX_HEADER);
-    if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix))
-        return new URL(request.url).origin;
+    if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) {
+        // a twin reached at its vendor's host through the World's proxy, which ends the caller's TLS and forwards the
+        // request in the clear: the scheme the caller used is the one its links carry (a page's form posting to
+        // http://accounts.google.com from an https page is one a browser warns about), the host the request's own
+        // A twin reached at its own listener (a loopback or an address: the injector's route, a direct client) is that
+        // listener, whatever scheme a caller's forwarded headers claim
+        const proto = request.headers.get('x-forwarded-proto');
+        const own = new URL(request.url);
+        const listener = own.hostname === 'localhost' || own.hostname.endsWith('.localhost') || /^[\d.]+$/.test(own.hostname) || own.hostname.startsWith('[');
+        return !listener && (proto === 'https' || proto === 'http') ? `${proto}://${own.host}` : own.origin;
+    }
     // the host that mounted the twin says where it is reached: a local World forwards to the twin's
     // own port, so the request's own origin is not the public one
     const host = request.headers.get('x-forwarded-host');

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.9",
   "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/src/rateBudget.ts

@@ -72,6 +72,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { volterHome } from './volter-home.ts';
 import { dirname, join } from 'node:path';
 import { worldPaths } from './storage.ts';
+import { FsWorldStore, getActiveWorldStore, type WorldStore } from './world-store.ts';
 
 // ── bounds the kernel enforces on ANY declaration ───────────────────────────────────────────
 
@@ -706,8 +707,19 @@ export class RateBudget {
 
   private lockPath(): string { return `${this.path}.lock`; }
 
+  /** The store the ledger persists through where there is no filesystem of this machine's to hold it: a hosted World's
+   *  (its SQL store, one instance serializing its requests). Null on the filesystem, where the ledger is the file below,
+   *  locked across processes as it always was. A hosted World's ledger is its own: two hosted Worlds sealed with one
+   *  credential each keep an allowance, where a machine's Worlds share one per credential. */
+  private store(): WorldStore | null {
+    const active = getActiveWorldStore();
+    return active instanceof FsWorldStore ? null : active;
+  }
+
   /** Acquire the exclusive lock, run `fn`, always release. Bounded wait, dead locks broken. */
   private withLock<T>(fn: () => T): T {
+    const held = this.store();
+    if (held) return held.withLock(this.lockPath(), fn);
     const lock = this.lockPath();
     mkdirSync(dirname(this.path), { recursive: true });
     let fd: number | undefined;
@@ -764,10 +776,11 @@ export class RateBudget {
    * window instead of needing a human to delete a file.
    */
   private load(now: number): Ledger {
-    if (!existsSync(this.path)) return { v: 1, cooldownUntil: 0, entries: [] };
+    const held = this.store();
+    if (held ? !held.exists(this.path) : !existsSync(this.path)) return { v: 1, cooldownUntil: 0, entries: [] };
     let raw: string;
     try {
-      raw = readFileSync(this.path, 'utf8');
+      raw = held ? (held.read(this.path) ?? '') : readFileSync(this.path, 'utf8');
     } catch (e) {
       throw this.quarantine(now, `unreadable (${(e as Error).message})`);
     }
@@ -819,6 +832,13 @@ export class RateBudget {
 
   /** Atomic replace: write a temp file, then rename over the target. No partial ledger is visible. */
   private save(ledger: Ledger): void {
+    const held = this.store();
+    if (held) {
+      try { held.writeAtomic(this.path, `${JSON.stringify(ledger)}\n`); } catch (e) {
+        throw new RateBudgetError('ledger-unwritable', this.vendor, `${this.vendor} budget: cannot persist ${this.path} (${(e as Error).message}) — refusing rather than tracking nothing`, this.windowMs);
+      }
+      return;
+    }
     const tmp = `${this.path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
     try {
       mkdirSync(dirname(this.path), { recursive: true });

package/src/twin-fetch.ts

@@ -24,7 +24,17 @@ export const TWIN_PREFIX_HEADER = 'x-forwarded-prefix';
  *  callback) from this, never from the bare origin, so the URL works behind a served World. */
 export function twinPublicBase(request: Request): string {
   const prefix = request.headers.get(TWIN_PREFIX_HEADER);
-  if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) return new URL(request.url).origin;
+  if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) {
+    // a twin reached at its vendor's host through the World's proxy, which ends the caller's TLS and forwards the
+    // request in the clear: the scheme the caller used is the one its links carry (a page's form posting to
+    // http://accounts.google.com from an https page is one a browser warns about), the host the request's own
+    // A twin reached at its own listener (a loopback or an address: the injector's route, a direct client) is that
+    // listener, whatever scheme a caller's forwarded headers claim
+    const proto = request.headers.get('x-forwarded-proto');
+    const own = new URL(request.url);
+    const listener = own.hostname === 'localhost' || own.hostname.endsWith('.localhost') || /^[\d.]+$/.test(own.hostname) || own.hostname.startsWith('[');
+    return !listener && (proto === 'https' || proto === 'http') ? `${proto}://${own.host}` : own.origin;
+  }
   // the host that mounted the twin says where it is reached: a local World forwards to the twin's
   // own port, so the request's own origin is not the public one
   const host = request.headers.get('x-forwarded-host');

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 };