@volter/world-runtime 2.0.12 → 2.0.13

package/dist/src/app-url.d.ts

@@ -11,6 +11,8 @@ export type AppUrlRecord = {
     /** the application's own production hostnames (`--host`), routed to `url` inside the World as DNS routes them to
      *  its host in production: the injector, the socket backstop and the redirect proxy read them from this record */
     hosts?: string[];
+    /** the application's name in the World (`--app`); absent: `app`, the one a command names without it */
+    app?: string;
 };
 export declare function appUrlFile(root: string, name: string): string;
 /** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
@@ -20,10 +22,12 @@ export declare function setAppUrl(name: string, url: string, options?: {
     root?: string;
     via?: Exclude<AppUrlSource, 'service'>;
     detail?: string;
+    app?: string;
 }): AppUrlRecord;
 /** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
 export declare function addAppHosts(name: string, hosts: string[], options?: {
     root?: string;
+    app?: string;
 }): AppUrlRecord;
 /**
  *`--detect <pid|port>`: resolve the app URL off what is ALREADY listening and record it.
@@ -34,6 +38,7 @@ export declare function addAppHosts(name: string, hosts: string[], options?: {
  */
 export declare function detectAppUrl(name: string, target: string, options?: {
     root?: string;
+    app?: string;
 }): Promise<AppUrlRecord>;
 /**
  * The recorded app URL of `name`, or the `app` service's assigned URL when nothing was recorded
@@ -42,6 +47,7 @@ export declare function detectAppUrl(name: string, target: string, options?: {
  */
 export declare function readAppUrl(name: string, options?: {
     root?: string;
+    app?: string;
 }): AppUrlRecord | null;
 /** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
-export declare function appUrlUnsetMessage(name: string): string;
+export declare function appUrlUnsetMessage(name: string, app?: string): string;

package/dist/src/app-url.js

@@ -19,13 +19,53 @@
 // once, at the caller's request, and stores what it saw. The record lives in the instance dir, so
 // a re-`up` (which wipes the dir) or `down --purge` clears it: a recorded URL never outlives the
 // instance it described.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { withFileLock } from '@volter/world-core';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';
 import { instanceDir, statusWorld } from "./runtime.js";
 import { loadInject } from "./inject-map.js";
 import { packFacts } from "./pack-facts.js";
+const APP_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const DEFAULT_APP = 'app';
+function appName(app) {
+    const name = app ?? DEFAULT_APP;
+    if (!APP_NAME.test(name))
+        throw new Error(`volter-world app-url: --app "${name}" is not an application name (lower-case letters, digits and -)`);
+    return name;
+}
+function readFile(root, name) {
+    const file = appUrlFile(root, name);
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+}
+function entryOf(file, app) {
+    if (app !== DEFAULT_APP)
+        return file.apps && Object.hasOwn(file.apps, app) ? file.apps[app] : undefined;
+    const { apps: _others, ...own } = file;
+    return own.url !== undefined || own.hosts !== undefined ? own : undefined;
+}
+/** Write one application's entry, keeping every other application's: under the record's lock (several booters record
+ *  their applications at once), replaced whole so a reader never meets half a file. */
+function writeEntry(root, name, app, build) {
+    // the whole read, check, merge and write under one lock (withFileLock is not reentrant: nothing inside takes it)
+    return withFileLock(`${appUrlFile(root, name)}.lock`, () => {
+        const file = readFile(root, name);
+        const { entry, result } = build(file);
+        writeEntryLocked(root, name, app, file, entry);
+        return result;
+    });
+}
+function writeEntryLocked(root, name, app, file, entry) {
+    const { app: _name, ...stored } = entry;
+    const next = app === DEFAULT_APP
+        ? { ...stored, ...(file.apps ? { apps: file.apps } : {}) }
+        : { ...Object.fromEntries(Object.entries(file).filter(([k]) => k !== 'apps')), apps: { ...(file.apps ?? {}), [app]: stored } };
+    const target = appUrlFile(root, name);
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(temp, target);
+}
 export function appUrlFile(root, name) {
     return join(instanceDir(root, name), 'app-url.json');
 }
@@ -47,24 +87,27 @@ function assertHttpUrl(url) {
  * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
 export function setAppUrl(name, url, options = {}) {
     const root = options.root ?? process.cwd();
+    const app = appName(options.app);
     const status = statusWorld(name, root); // throws "World instance not found" — the loud path
     assertHttpUrl(url);
-    // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
-    const hosts = existsSync(appUrlFile(root, name)) ? JSON.parse(readFileSync(appUrlFile(root, name), 'utf8')).hosts : undefined;
-    const record = {
-        world: status.name,
-        url,
-        via: options.via ?? 'set',
-        recordedAt: new Date().toISOString(),
-        ...(options.detail === undefined ? {} : { detail: options.detail }),
-        ...(hosts?.length ? { hosts } : {}),
-    };
-    writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
-    return record;
-}
-/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin serves, and not the
- *  host of this World's own origin or of a twin it runs (their requests carry the World key). */
-function assertAppHost(host, world, root) {
+    return writeEntry(root, name, app, (file) => {
+        // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
+        const hosts = entryOf(file, app)?.hosts;
+        const record = {
+            world: status.name,
+            url,
+            via: options.via ?? 'set',
+            recordedAt: new Date().toISOString(),
+            ...(options.detail === undefined ? {} : { detail: options.detail }),
+            ...(hosts?.length ? { hosts } : {}),
+        };
+        return { entry: record, result: app === DEFAULT_APP ? record : { ...record, app } };
+    });
+}
+/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin the World runs serves,
+ *  not the host of this World's own origin or of a twin it runs (their requests carry the World key), and not one
+ *  another of its applications answers. A vendor the World runs no twin of can be the application itself. */
+function assertAppHost(host, world, root, app, file) {
     const name = host.trim().toLowerCase().replace(/\.$/, '');
     // a wildcard (`*.dub.link`) stands for every name below its parent, as a DNS wildcard record does; its parent has two
     // labels at least (never a bare TLD). Whether the parent is a public suffix (co.uk, github.io) is the operator's word:
@@ -75,18 +118,22 @@ function assertAppHost(host, world, root) {
         throw new Error(`volter-world app-url: --host "${host}" is not a DNS hostname the app answers as (e.g. app.example.com, or *.example.com)`);
     }
     const inject = loadInject();
-    let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => inject.VENDOR_HOSTS[v](bare));
+    const status = statusWorld(world, root);
+    // the twins the World runs, by vendor key, as its injector reads them from the World env (a service's id is not its
+    // vendor key: the aws service serves s3, dynamodb and others; a stripe twin may be a service named payments)
+    const twins = inject.readMap(status.env);
+    const runs = (vendor) => Object.hasOwn(twins, vendor);
+    let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => runs(v) && inject.VENDOR_HOSTS[v](bare));
     if (!vendor && wildcard) {
         // a wildcard is refused when any name a vendor's rule can give its twin lies under it, or it lies under a vendor's
         // host suffix: the rules' names, read from the descriptors (a host, a suffix, a pattern's literal tail) and from
         // the hand table's predicates (their quoted names)
         const names = vendorNames(inject.VENDOR_HOSTS);
         const dotted = `.${bare}`;
-        vendor = names.find((n) => n.name === bare || n.name.endsWith(dotted) || (n.suffix && dotted.endsWith(n.name.startsWith('.') ? n.name : `.${n.name}`)))?.vendor;
+        vendor = names.find((n) => runs(n.vendor) && (n.name === bare || n.name.endsWith(dotted) || (n.suffix && dotted.endsWith(n.name.startsWith('.') ? n.name : `.${n.name}`))))?.vendor;
     }
     if (vendor)
-        throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves; an app cannot answer as it`);
-    const status = statusWorld(world, root);
+        throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves in this World; an app cannot answer as it while it runs`);
     const own = [status.env.VOLTER_WORLD ?? '', ...Object.values(status.services).map((service) => service.url ?? '')]
         .flatMap((url) => { try {
         return [new URL(url).hostname.toLowerCase()];
@@ -96,6 +143,17 @@ function assertAppHost(host, world, root) {
     } });
     if (own.some((h) => h === name || (wildcard && h.endsWith(`.${bare}`))))
         throw new Error(`volter-world app-url: --host ${name} is this World's own origin or a twin's; an app cannot answer as it`);
+    // one application per hostname: a name, or a wildcard over it, another application already answers
+    for (const other of [DEFAULT_APP, ...Object.keys(file.apps ?? {})]) {
+        if (other === app)
+            continue;
+        const held = entryOf(file, other)?.hosts ?? [];
+        // a wildcard answers every name below its parent and never the parent, as a DNS wildcard does, so `*.example.org`
+        // and `example.org` are two applications' without overlap
+        const clash = held.find((h) => h === name || (h.startsWith('*.') && name.endsWith(h.slice(1)) && name !== h) || (wildcard && h.endsWith(`.${bare}`)));
+        if (clash)
+            throw new Error(`volter-world app-url: --host ${name} overlaps ${clash}, which the application "${other}" answers; a hostname belongs to one application`);
+    }
     return name;
 }
 /** Every hostname the vendor table can name, with its vendor: a descriptor rule's host, suffix, or a host pattern's
@@ -131,14 +189,20 @@ function vendorNames(table) {
 /** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
 export function addAppHosts(name, hosts, options = {}) {
     const root = options.root ?? process.cwd();
-    const current = readAppUrl(name, { root });
-    if (!current)
-        throw new Error(appUrlUnsetMessage(name));
-    const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root))])].sort();
-    // hosts beside the World's own `app` service keep no URL: they follow the service wherever a boot puts it
-    const record = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } : { ...current, hosts: all };
-    writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
-    return current.via === 'service' ? { ...current, hosts: all } : record;
+    const app = appName(options.app);
+    const status = statusWorld(name, root);
+    return writeEntry(root, name, app, (file) => {
+        // checked against the record as it stands under the lock, so two booters never both take one hostname
+        const current = appUrlOf(file, status, app);
+        if (!current)
+            throw new Error(appUrlUnsetMessage(name, app));
+        const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root, app, file))])].sort();
+        // hosts beside the World's own service of the application's name keep no URL: they follow the service wherever a
+        // boot puts it
+        const { app: _name, ...stored } = current;
+        const entry = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } : { ...stored, hosts: all };
+        return { entry, result: { ...current, hosts: all } };
+    });
 }
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
 function listeningTcpPorts(pid) {
@@ -214,24 +278,33 @@ export async function detectAppUrl(name, target, options = {}) {
  */
 export function readAppUrl(name, options = {}) {
     const root = options.root ?? process.cwd();
+    const app = appName(options.app);
     const status = statusWorld(name, root); // loud when the world does not exist at all
-    const file = appUrlFile(root, name);
-    const app = status.services['app'];
-    if (existsSync(file)) {
-        const record = JSON.parse(readFileSync(file, 'utf8'));
-        // hosts recorded beside the World's own `app` service: its URL is this boot's
-        if (!record.url && app?.url !== undefined)
-            return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service', ...(record.hosts ? { hosts: record.hosts } : {}) };
+    return appUrlOf(readFile(root, name), status, app);
+}
+/** One application's URL from the record `file` and the instance `status`: the recorded URL, or the World's service
+ *  of the application's name. */
+function appUrlOf(file, status, app) {
+    const named = app === DEFAULT_APP ? {} : { app };
+    const service = status.services[app];
+    const record = entryOf(file, app);
+    if (record) {
+        // hosts recorded beside the World's own service of the application's name: its URL is this boot's
+        if (!record.url && service?.url !== undefined)
+            return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service`, ...(record.hosts ? { hosts: record.hosts } : {}), ...named };
         if (record.url)
-            return record;
+            return { ...record, world: status.name, ...named };
     }
-    if (app?.url !== undefined) {
-        return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+    if (service?.url !== undefined) {
+        return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service (nothing was recorded)`, ...named };
     }
     return null;
 }
 /** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
-export function appUrlUnsetMessage(name) {
+export function appUrlUnsetMessage(name, app = DEFAULT_APP) {
+    if (app !== DEFAULT_APP) {
+        return `World ${name} has no URL for the application "${app}": record it with \`volter-world app-url ${name} --app ${app} --set http://127.0.0.1:<port>\`, or declare a service "${app}" in the World's config.`;
+    }
     return (`World ${name} has no recorded app URL.\n`
         + `If the app is booted OUTSIDE the world (the attach pattern), the booter registers it as the LAST boot step:\n`
         + `  volter-world app-url ${name} --set http://127.0.0.1:<port>    # or: --detect <pid|port>\n`

package/dist/src/cli.js

@@ -99,7 +99,7 @@ function printHelp() {
   volter-world urls <name> [--json] [--root <repo>]
   volter-world url <name> [service] [--root <repo>]   # the clean base URL of one running service (no world.env parsing);
                                                         # without a service: every service, one \`<id> <url>\` per line
-  volter-world app-url <world> [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
+  volter-world app-url <world> [--app <name>] [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
                                                   # the recorded APP endpoint of the instance — the attach pattern's
                                                   # missing output. The BOOTER records it as the last boot step
                                                   # (--set, or --detect an already-listening pid/port); consumers
@@ -678,22 +678,26 @@ async function main() {
         if (set && detect)
             throw new Error('volter-world app-url: pass --set OR --detect, not both');
         const json = rest.includes('--json');
+        // --app: which of the World's applications (each with its URL and hostnames); without it, `app`
+        const app = rest.some((arg) => arg === '--app' || arg.startsWith('--app=')) ? optionValue(rest, '--app') : undefined;
+        if (app === '' || app?.startsWith('--'))
+            throw new Error('volter-world app-url: --app needs an application name (--app <name>)');
         // --host (repeatable): a hostname the app answers as in production, routed to it inside the World
         const hosts = rest.flatMap((arg, index) => (arg === '--host' ? [rest[index + 1] ?? ''] : []));
         if (set || detect || hosts.length) {
-            let record = set ? setAppUrl(subject, set, { root }) : detect ? await detectAppUrl(subject, detect, { root }) : undefined;
+            let record = set ? setAppUrl(subject, set, { root, app }) : detect ? await detectAppUrl(subject, detect, { root, app }) : undefined;
             if (hosts.length)
-                record = addAppHosts(subject, hosts, { root });
+                record = addAppHosts(subject, hosts, { root, app });
             if (json)
                 process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
             else
                 process.stdout.write(`Recorded app URL for world ${subject}: ${record.url}${record.detail ? ` (${record.detail})` : ''}${record.hosts?.length ? `; answering as ${record.hosts.join(', ')}` : ''}\n`);
             return;
         }
-        const record = readAppUrl(subject, { root });
+        const record = readAppUrl(subject, { root, app });
         if (record === null) {
             // LOUD when unset — a consumer must never mistake "nobody registered it" for an endpoint.
-            process.stderr.write(`${appUrlUnsetMessage(subject)}\n`);
+            process.stderr.write(`${appUrlUnsetMessage(subject, app)}\n`);
             if (json)
                 process.stdout.write(`${JSON.stringify({ world: subject, url: null }, null, 2)}\n`);
             process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.7",
+    "@volter/world-core": "2.0.8",
     "@volter/world-console": "2.0.7"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.7",
+    "@volter/world-core": "2.0.8",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.7"
+    "@volter/twin-mongodb": "0.1.8"
   }
 }

package/src/app-url.ts

@@ -19,7 +19,8 @@
 // once, at the caller's request, and stores what it saw. The record lives in the instance dir, so
 // a re-`up` (which wipes the dir) or `down --purge` clears it: a recorded URL never outlives the
 // instance it described.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { withFileLock } from '@volter/world-core';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -41,8 +42,56 @@ export type AppUrlRecord = {
   /** the application's own production hostnames (`--host`), routed to `url` inside the World as DNS routes them to
    *  its host in production: the injector, the socket backstop and the redirect proxy read them from this record */
   hosts?: string[];
+  /** the application's name in the World (`--app`); absent: `app`, the one a command names without it */
+  app?: string;
 };
 
+/** `app-url.json`: the application named `app` at the top level (the record's original shape), the others by name. */
+type AppUrlFile = Partial<AppUrlRecord> & { apps?: Record<string, Partial<AppUrlRecord>> };
+
+const APP_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const DEFAULT_APP = 'app';
+
+function appName(app: string | undefined): string {
+  const name = app ?? DEFAULT_APP;
+  if (!APP_NAME.test(name)) throw new Error(`volter-world app-url: --app "${name}" is not an application name (lower-case letters, digits and -)`);
+  return name;
+}
+
+function readFile(root: string, name: string): AppUrlFile {
+  const file = appUrlFile(root, name);
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) as AppUrlFile : {};
+}
+
+function entryOf(file: AppUrlFile, app: string): Partial<AppUrlRecord> | undefined {
+  if (app !== DEFAULT_APP) return file.apps && Object.hasOwn(file.apps, app) ? file.apps[app] : undefined;
+  const { apps: _others, ...own } = file;
+  return own.url !== undefined || own.hosts !== undefined ? own : undefined;
+}
+
+/** Write one application's entry, keeping every other application's: under the record's lock (several booters record
+ *  their applications at once), replaced whole so a reader never meets half a file. */
+function writeEntry<T>(root: string, name: string, app: string, build: (file: AppUrlFile) => { entry: Partial<AppUrlRecord>; result: T }): T {
+  // the whole read, check, merge and write under one lock (withFileLock is not reentrant: nothing inside takes it)
+  return withFileLock(`${appUrlFile(root, name)}.lock`, () => {
+    const file = readFile(root, name);
+    const { entry, result } = build(file);
+    writeEntryLocked(root, name, app, file, entry);
+    return result;
+  });
+}
+
+function writeEntryLocked(root: string, name: string, app: string, file: AppUrlFile, entry: Partial<AppUrlRecord>): void {
+  const { app: _name, ...stored } = entry;
+  const next: AppUrlFile = app === DEFAULT_APP
+    ? { ...stored, ...(file.apps ? { apps: file.apps } : {}) }
+    : { ...Object.fromEntries(Object.entries(file).filter(([k]) => k !== 'apps')), apps: { ...(file.apps ?? {}), [app]: stored } };
+  const target = appUrlFile(root, name);
+  const temp = `${target}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(temp, target);
+}
+
 export function appUrlFile(root: string, name: string): string {
   return join(instanceDir(root, name), 'app-url.json');
 }
@@ -63,27 +112,30 @@ function assertHttpUrl(url: string): URL {
 /** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
  * exist (a record for a world that was never upped would describe nothing); the app itself is
  * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
-export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string } = {}): AppUrlRecord {
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string } = {}): AppUrlRecord {
   const root = options.root ?? process.cwd();
+  const app = appName(options.app);
   const status = statusWorld(name, root); // throws "World instance not found" — the loud path
   assertHttpUrl(url);
-  // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
-  const hosts = existsSync(appUrlFile(root, name)) ? (JSON.parse(readFileSync(appUrlFile(root, name), 'utf8')) as AppUrlRecord).hosts : undefined;
-  const record: AppUrlRecord = {
-    world: status.name,
-    url,
-    via: options.via ?? 'set',
-    recordedAt: new Date().toISOString(),
-    ...(options.detail === undefined ? {} : { detail: options.detail }),
-    ...(hosts?.length ? { hosts } : {}),
-  };
-  writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
-  return record;
-}
-
-/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin serves, and not the
- *  host of this World's own origin or of a twin it runs (their requests carry the World key). */
-function assertAppHost(host: string, world: string, root: string): string {
+  return writeEntry(root, name, app, (file) => {
+    // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
+    const hosts = entryOf(file, app)?.hosts;
+    const record: AppUrlRecord = {
+      world: status.name,
+      url,
+      via: options.via ?? 'set',
+      recordedAt: new Date().toISOString(),
+      ...(options.detail === undefined ? {} : { detail: options.detail }),
+      ...(hosts?.length ? { hosts } : {}),
+    };
+    return { entry: record, result: app === DEFAULT_APP ? record : { ...record, app } };
+  });
+}
+
+/** A hostname the app may answer as: a DNS name (not an address, not loopback) that no twin the World runs serves,
+ *  not the host of this World's own origin or of a twin it runs (their requests carry the World key), and not one
+ *  another of its applications answers. A vendor the World runs no twin of can be the application itself. */
+function assertAppHost(host: string, world: string, root: string, app: string, file: AppUrlFile): string {
   const name = host.trim().toLowerCase().replace(/\.$/, '');
   // a wildcard (`*.dub.link`) stands for every name below its parent, as a DNS wildcard record does; its parent has two
   // labels at least (never a bare TLD). Whether the parent is a public suffix (co.uk, github.io) is the operator's word:
@@ -94,20 +146,33 @@ function assertAppHost(host: string, world: string, root: string): string {
     throw new Error(`volter-world app-url: --host "${host}" is not a DNS hostname the app answers as (e.g. app.example.com, or *.example.com)`);
   }
   const inject = loadInject();
-  let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => inject.VENDOR_HOSTS[v]!(bare));
+  const status = statusWorld(world, root);
+  // the twins the World runs, by vendor key, as its injector reads them from the World env (a service's id is not its
+  // vendor key: the aws service serves s3, dynamodb and others; a stripe twin may be a service named payments)
+  const twins = inject.readMap(status.env);
+  const runs = (vendor: string) => Object.hasOwn(twins, vendor);
+  let vendor = Object.keys(inject.VENDOR_HOSTS).find((v) => runs(v) && inject.VENDOR_HOSTS[v]!(bare));
   if (!vendor && wildcard) {
     // a wildcard is refused when any name a vendor's rule can give its twin lies under it, or it lies under a vendor's
     // host suffix: the rules' names, read from the descriptors (a host, a suffix, a pattern's literal tail) and from
     // the hand table's predicates (their quoted names)
     const names = vendorNames(inject.VENDOR_HOSTS);
     const dotted = `.${bare}`;
-    vendor = names.find((n) => n.name === bare || n.name.endsWith(dotted) || (n.suffix && dotted.endsWith(n.name.startsWith('.') ? n.name : `.${n.name}`)))?.vendor;
+    vendor = names.find((n) => runs(n.vendor) && (n.name === bare || n.name.endsWith(dotted) || (n.suffix && dotted.endsWith(n.name.startsWith('.') ? n.name : `.${n.name}`))))?.vendor;
   }
-  if (vendor) throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves; an app cannot answer as it`);
-  const status = statusWorld(world, root);
+  if (vendor) throw new Error(`volter-world app-url: --host ${name} is ${vendor}'s host, which its twin serves in this World; an app cannot answer as it while it runs`);
   const own = [status.env.VOLTER_WORLD ?? '', ...Object.values(status.services).map((service) => service.url ?? '')]
     .flatMap((url) => { try { return [new URL(url).hostname.toLowerCase()]; } catch { return []; } });
   if (own.some((h) => h === name || (wildcard && h.endsWith(`.${bare}`)))) throw new Error(`volter-world app-url: --host ${name} is this World's own origin or a twin's; an app cannot answer as it`);
+  // one application per hostname: a name, or a wildcard over it, another application already answers
+  for (const other of [DEFAULT_APP, ...Object.keys(file.apps ?? {})]) {
+    if (other === app) continue;
+    const held = entryOf(file, other)?.hosts ?? [];
+    // a wildcard answers every name below its parent and never the parent, as a DNS wildcard does, so `*.example.org`
+    // and `example.org` are two applications' without overlap
+    const clash = held.find((h) => h === name || (h.startsWith('*.') && name.endsWith(h.slice(1)) && name !== h) || (wildcard && h.endsWith(`.${bare}`)));
+    if (clash) throw new Error(`volter-world app-url: --host ${name} overlaps ${clash}, which the application "${other}" answers; a hostname belongs to one application`);
+  }
   return name;
 }
 
@@ -137,15 +202,21 @@ function vendorNames(table: Record<string, (host: string, pathname?: string) =>
 }
 
 /** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
-export function addAppHosts(name: string, hosts: string[], options: { root?: string } = {}): AppUrlRecord {
+export function addAppHosts(name: string, hosts: string[], options: { root?: string; app?: string } = {}): AppUrlRecord {
   const root = options.root ?? process.cwd();
-  const current = readAppUrl(name, { root });
-  if (!current) throw new Error(appUrlUnsetMessage(name));
-  const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root))])].sort();
-  // hosts beside the World's own `app` service keep no URL: they follow the service wherever a boot puts it
-  const record: AppUrlRecord = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } as AppUrlRecord : { ...current, hosts: all };
-  writeFileSync(appUrlFile(root, name), `${JSON.stringify(record, null, 2)}\n`);
-  return current.via === 'service' ? { ...current, hosts: all } : record;
+  const app = appName(options.app);
+  const status = statusWorld(name, root);
+  return writeEntry(root, name, app, (file) => {
+    // checked against the record as it stands under the lock, so two booters never both take one hostname
+    const current = appUrlOf(file, status, app);
+    if (!current) throw new Error(appUrlUnsetMessage(name, app));
+    const all = [...new Set([...(current.hosts ?? []), ...hosts.map((host) => assertAppHost(host, name, root, app, file))])].sort();
+    // hosts beside the World's own service of the application's name keep no URL: they follow the service wherever a
+    // boot puts it
+    const { app: _name, ...stored } = current;
+    const entry = current.via === 'service' ? { world: current.world, via: 'service', hosts: all } as AppUrlRecord : { ...stored, hosts: all };
+    return { entry, result: { ...current, hosts: all } };
+  });
 }
 
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
@@ -193,7 +264,7 @@ function tcpListening(port: number, timeoutMs = 1500): Promise<boolean> {
  * Otherwise the number is tried as a loopback port and must actually be listening. Detection
  * that finds nothing refuses loudly rather than recording a URL nothing serves.
  */
-export async function detectAppUrl(name: string, target: string, options: { root?: string } = {}): Promise<AppUrlRecord> {
+export async function detectAppUrl(name: string, target: string, options: { root?: string; app?: string } = {}): Promise<AppUrlRecord> {
   const numeric = Number(target);
   if (!Number.isInteger(numeric) || numeric <= 0) {
     throw new Error(`volter-world app-url: --detect wants a pid or a port, got "${target}"`);
@@ -225,25 +296,35 @@ export async function detectAppUrl(name: string, target: string, options: { root
  * (the world-boots-the-app convention), or null. Null is the CALLER's loud-error cue — the CLI
  * turns it into exit 1 with the registration recipe; a library consumer decides for itself.
  */
-export function readAppUrl(name: string, options: { root?: string } = {}): AppUrlRecord | null {
+export function readAppUrl(name: string, options: { root?: string; app?: string } = {}): AppUrlRecord | null {
   const root = options.root ?? process.cwd();
+  const app = appName(options.app);
   const status = statusWorld(name, root); // loud when the world does not exist at all
-  const file = appUrlFile(root, name);
-  const app = status.services['app'];
-  if (existsSync(file)) {
-    const record = JSON.parse(readFileSync(file, 'utf8')) as AppUrlRecord;
-    // hosts recorded beside the World's own `app` service: its URL is this boot's
-    if (!record.url && app?.url !== undefined) return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service', ...(record.hosts ? { hosts: record.hosts } : {}) };
-    if (record.url) return record;
+  return appUrlOf(readFile(root, name), status, app);
+}
+
+/** One application's URL from the record `file` and the instance `status`: the recorded URL, or the World's service
+ *  of the application's name. */
+function appUrlOf(file: AppUrlFile, status: { name: string; services: Record<string, { url?: string }> }, app: string): AppUrlRecord | null {
+  const named = app === DEFAULT_APP ? {} : { app };
+  const service = status.services[app];
+  const record = entryOf(file, app);
+  if (record) {
+    // hosts recorded beside the World's own service of the application's name: its URL is this boot's
+    if (!record.url && service?.url !== undefined) return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service`, ...(record.hosts ? { hosts: record.hosts } : {}), ...named };
+    if (record.url) return { ...(record as AppUrlRecord), world: status.name, ...named };
   }
-  if (app?.url !== undefined) {
-    return { world: status.name, url: app.url, via: 'service', detail: 'the world\'s own "app" service (nothing was recorded)' };
+  if (service?.url !== undefined) {
+    return { world: status.name, url: service.url, via: 'service', detail: `the world's own "${app}" service (nothing was recorded)`, ...named };
   }
   return null;
 }
 
 /** The message the CLI prints when no app URL is known — the registration recipe, not a guess. */
-export function appUrlUnsetMessage(name: string): string {
+export function appUrlUnsetMessage(name: string, app = DEFAULT_APP): string {
+  if (app !== DEFAULT_APP) {
+    return `World ${name} has no URL for the application "${app}": record it with \`volter-world app-url ${name} --app ${app} --set http://127.0.0.1:<port>\`, or declare a service "${app}" in the World's config.`;
+  }
   return (
     `World ${name} has no recorded app URL.\n`
     + `If the app is booted OUTSIDE the world (the attach pattern), the booter registers it as the LAST boot step:\n`

package/src/cli.ts

@@ -100,7 +100,7 @@ function printHelp(): void {
   volter-world urls <name> [--json] [--root <repo>]
   volter-world url <name> [service] [--root <repo>]   # the clean base URL of one running service (no world.env parsing);
                                                         # without a service: every service, one \`<id> <url>\` per line
-  volter-world app-url <world> [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
+  volter-world app-url <world> [--app <name>] [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
                                                   # the recorded APP endpoint of the instance — the attach pattern's
                                                   # missing output. The BOOTER records it as the last boot step
                                                   # (--set, or --detect an already-listening pid/port); consumers
@@ -608,19 +608,22 @@ async function main(): Promise<void> {
     const detect = optionValue(rest, '--detect');
     if (set && detect) throw new Error('volter-world app-url: pass --set OR --detect, not both');
     const json = rest.includes('--json');
+    // --app: which of the World's applications (each with its URL and hostnames); without it, `app`
+    const app = rest.some((arg) => arg === '--app' || arg.startsWith('--app=')) ? optionValue(rest, '--app') : undefined;
+    if (app === '' || app?.startsWith('--')) throw new Error('volter-world app-url: --app needs an application name (--app <name>)');
     // --host (repeatable): a hostname the app answers as in production, routed to it inside the World
     const hosts = rest.flatMap((arg, index) => (arg === '--host' ? [rest[index + 1] ?? ''] : []));
     if (set || detect || hosts.length) {
-      let record = set ? setAppUrl(subject, set, { root }) : detect ? await detectAppUrl(subject, detect, { root }) : undefined;
-      if (hosts.length) record = addAppHosts(subject, hosts, { root });
+      let record = set ? setAppUrl(subject, set, { root, app }) : detect ? await detectAppUrl(subject, detect, { root, app }) : undefined;
+      if (hosts.length) record = addAppHosts(subject, hosts, { root, app });
       if (json) process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
       else process.stdout.write(`Recorded app URL for world ${subject}: ${record!.url}${record!.detail ? ` (${record!.detail})` : ''}${record!.hosts?.length ? `; answering as ${record!.hosts.join(', ')}` : ''}\n`);
       return;
     }
-    const record = readAppUrl(subject, { root });
+    const record = readAppUrl(subject, { root, app });
     if (record === null) {
       // LOUD when unset — a consumer must never mistake "nobody registered it" for an endpoint.
-      process.stderr.write(`${appUrlUnsetMessage(subject)}\n`);
+      process.stderr.write(`${appUrlUnsetMessage(subject, app)}\n`);
       if (json) process.stdout.write(`${JSON.stringify({ world: subject, url: null }, null, 2)}\n`);
       process.exit(1);
     }