@volter/world-core 2.0.37 → 3.0.0

package/README.md

@@ -18,12 +18,11 @@ execution. Payloads use the [blob storage contract](../../docs/contributing/arch
 
 ## Building a twin
 
-A protocol-2 twin implements its vendor's request/response semantics while the shared kernel
+A twin implements its vendor's request/response semantics while the shared kernel
 owns log ordering, checkpoints, branching and the head's state system. Use the tree readers and
 write path exported by [`src/index.ts`](./src/index.ts); do not reconstruct a serve-time view by
 folding the log or use removed v1 confirmation/suppression APIs.
 
-[Architecture](../../docs/contributing/architecture.md) owns the boundaries and
-[adding a twin](../../docs/contributing/adding-a-twin.md) owns the implementation and verification
-process. Package protocol standing is recorded in the [generated index](../../generated/INDEX.md).
-Conformance tooling is a development dependency in `@volter/world-tooling`.
+[Architecture](../../docs/contributing/architecture.md) owns the boundaries and the procedure a twin is built by
+([Creating a pack](../../docs/contributing/architecture.md#creating-a-pack)); [gates](../../docs/contributing/gates.md)
+owns verification. Development tooling is in `@volter/world-tooling`.

package/app-route.cjs

@@ -32,7 +32,7 @@ function readRoutes(instanceFile) {
   const now = Date.now();
   let held = APP_ROUTES.get(instanceFile);
   if (held && now - held.checkedAt < 1000) return held;
-  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
+  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], app: null, services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
   held.checkedAt = now;
   const fs = require('fs');
   const path = require('path');
@@ -50,28 +50,34 @@ function readRoutes(instanceFile) {
       const record = JSON.parse(fs.readFileSync(file, 'utf8'));
       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);
+      // the application itself, hosts recorded or not: where a name a hosting twin serves as it (claimedAppHosts) goes
+      held.app = { name: 'app', url: typeof record.url === 'string' ? record.url : null, hosts: new Set() };
     }
     // 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) {
+    for (const route of [...held.routes, ...(held.app ? [held.app] : [])]) {
       const at = route.url ?? services[route.name]?.url;
       route.origin = typeof at === 'string' ? at.replace(/\/$/, '') : null;
     }
   } 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.routes = [];
+    if (error && error.code === 'ENOENT') { held.routes = []; held.app = 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 = {}) {
+ *  caller's own (`twins`: vendor keys as `twinOrigins` reads them, the injector's map). A host no record names that a
+ *  hosting twin serves as the customer's application (`claimedAppHosts`, the `appHosts` its hostsClaimed door lists: a
+ *  domain the app added to its own Vercel project) answers as the application itself, as the host's DNS sends it to
+ *  the deployment in production. */
+function appRouteFor(instanceFile, host, twins = {}, claimedAppHosts = null) {
   const bare = String(host || '').toLowerCase().replace(/\.$/, '');
   const held = readRoutes(instanceFile);
-  const route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  let route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  if (!route && claimedAppHosts && held.app && held.app.origin && appHostMatch(claimedAppHosts, bare)) route = held.app;
   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;

package/app-route.d.cts

@@ -1,6 +1,6 @@
 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 appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>): AppRoute | null;
+export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>, claimedAppHosts?: ReadonlySet<string> | null): 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

@@ -32,7 +32,7 @@ function readRoutes(instanceFile) {
   const now = Date.now();
   let held = APP_ROUTES.get(instanceFile);
   if (held && now - held.checkedAt < 1000) return held;
-  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
+  if (!held) { held = { checkedAt: 0, mtimeMs: -1, routes: [], app: null, services: {}, twins: {} }; APP_ROUTES.set(instanceFile, held); }
   held.checkedAt = now;
   const fs = require('fs');
   const path = require('path');
@@ -50,28 +50,34 @@ function readRoutes(instanceFile) {
       const record = JSON.parse(fs.readFileSync(file, 'utf8'));
       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);
+      // the application itself, hosts recorded or not: where a name a hosting twin serves as it (claimedAppHosts) goes
+      held.app = { name: 'app', url: typeof record.url === 'string' ? record.url : null, hosts: new Set() };
     }
     // 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) {
+    for (const route of [...held.routes, ...(held.app ? [held.app] : [])]) {
       const at = route.url ?? services[route.name]?.url;
       route.origin = typeof at === 'string' ? at.replace(/\/$/, '') : null;
     }
   } 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.routes = [];
+    if (error && error.code === 'ENOENT') { held.routes = []; held.app = 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 = {}) {
+ *  caller's own (`twins`: vendor keys as `twinOrigins` reads them, the injector's map). A host no record names that a
+ *  hosting twin serves as the customer's application (`claimedAppHosts`, the `appHosts` its hostsClaimed door lists: a
+ *  domain the app added to its own Vercel project) answers as the application itself, as the host's DNS sends it to
+ *  the deployment in production. */
+function appRouteFor(instanceFile, host, twins = {}, claimedAppHosts = null) {
   const bare = String(host || '').toLowerCase().replace(/\.$/, '');
   const held = readRoutes(instanceFile);
-  const route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  let route = held.routes.find((r) => r.origin && appHostMatch(r.hosts, bare));
+  if (!route && claimedAppHosts && held.app && held.app.origin && appHostMatch(claimedAppHosts, bare)) route = held.app;
   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;

package/dist/app-route.d.cts

@@ -1,6 +1,6 @@
 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 appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>): AppRoute | null;
+export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>, claimedAppHosts?: ReadonlySet<string> | null): 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;