@volter/world-core 2.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,29 @@
+# @volter/world-core
+
+The shared state kernel and vendor-independent runtime libraries used by `@volter/twin-<vendor>`.
+The product CLI and SDK are in [`@volter/world`](../cli/README.md).
+
+## State and branching
+
+[The model](../../docs/concepts/the-model.md) is the canonical explanation: one logical log,
+checkpoints, a branch's parent position and its own entries, and simulated or real execution at
+the head. Push lands entries in a parent; deploy performs them against the vendor and records
+receipts. The Git-inspired verbs do not imply staging, commits or a Git object database.
+
+The file store has inherited entries (`events.jsonl`), branch entries (`actions.jsonl`),
+`branch.json`, a fetched URL-parent cache (`origin.jsonl`) and checkpoints. These are storage
+segments of that model, not independent observed-state and local-action truth systems.
+See [`log.ts`](./src/log.ts) for the format and [`state-system.ts`](./src/state-system.ts) for
+execution. Payloads use the [blob storage contract](../../docs/contributing/architecture.md#portable-host-and-immutable-payloads).
+
+## Building a twin
+
+A protocol-2 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`.

package/app-route.cjs

@@ -0,0 +1,154 @@
+'use strict';
+// THE APPLICATION'S OWN HOSTNAMES IN THE WORLD — the one home of the app route (dependency-free, side-effect free).
+//
+// `volter-world app-url <world> --host <name>` records the hostnames an application answers as in production beside
+// its URL (`app-url.json` in the instance); inside the World they reach the application, as DNS routes them to its
+// host in production (architecture.md, "The application's own production hostnames"). Two kinds of process route
+// them, and both read the route here:
+//   · a process the injector is installed in (the application, a script, the redirect proxy): inject.cjs's
+//     resolveTwin answers a recorded host with the application's origin, after twins and the hosts twins claim;
+//   · a twin's own outbound request (a QStash delivery, a webhook) from the colocated twin host, which runs without the
+//     injector: `appDestination` names the application for a URL on one of its hosts, and `deliverToApp` makes the
+//     request there, so a vendor's delivery to https://app.example.com/... reaches the application as it would reach
+//     its production deployment.
+// The record is read from the instance the process's World env names (VOLTER_WORLD_INSTANCE), at most once a second,
+// 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 }
+
+/** The application's route in the instance `instanceFile`: { origin, hosts } or null when none is recorded. */
+function appRoute(instanceFile) {
+  if (!instanceFile) return null;
+  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); }
+  held.checkedAt = now;
+  const fs = require('fs');
+  const path = require('path');
+  const file = path.join(path.dirname(instanceFile), 'app-url.json');
+  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;
+    }
+    // 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;
+  }
+  return held.route && held.route.origin ? held.route : null;
+}
+
+/** Whether `host` is one of the app's recorded hostnames: named exactly, or under a recorded wildcard (`*.dub.link`),
+ *  which, as a DNS wildcard, answers every name below its parent and never the parent itself. */
+function appHostMatch(hosts, host) {
+  if (hosts.has(host)) return true;
+  for (let dot = host.indexOf('.'); dot > 0; dot = host.indexOf('.', dot + 1)) {
+    if (hosts.has(`*${host.slice(dot)}`)) return true;
+  }
+  return false;
+}
+
+/** The headers a request routed to the application carries beside its own Host: the host and scheme it was made with. */
+function appForwardHeaders(url) {
+  return { 'x-forwarded-host': url.host, 'x-forwarded-proto': url.protocol === 'https:' ? 'https' : 'http' };
+}
+
+/** The application a URL reaches inside the World, when its host is one the application answers as: the route, or null. */
+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;
+}
+
+let SESSION_CA = undefined; // lazily read once; NODE_EXTRA_CA_CERTS set after process start
+/** The World's session CA (NODE_EXTRA_CA_CERTS), which an https origin inside the World is signed by, or null. */
+function sessionCa() {
+  if (SESSION_CA === undefined) {
+    const caPath = process.env.NODE_EXTRA_CA_CERTS;
+    try { SESSION_CA = caPath ? require('fs').readFileSync(caPath) : null; } catch { SESSION_CA = null; }
+  }
+  return SESSION_CA;
+}
+
+// What never reaches the application from a World process: the World's key and its routing marks, the caller's own
+// Host and forwarded host and scheme (replaced by the ones the request was made with), and an accepted encoding (the
+// answer is read decoded, as fetch reads it)
+const APP_DROPPED = ['accept-encoding', 'x-twins-key', 'x-volter-twin-original-host', 'proxy-connection', 'host', 'x-forwarded-host', 'x-forwarded-proto'];
+
+/** The node:http(s) request options for `url`, a URL on one of the application's hosts, sent where `route` says it
+ *  listens: the host it was made to as Host, with the forwarded host and scheme, never the World's own headers. */
+function appRequestOptions(route, url, method, headers, extra) {
+  const { isIP } = require('net');
+  const target = new URL(route.origin);
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) if (v !== undefined && !APP_DROPPED.includes(k.toLowerCase())) out[k] = v;
+  Object.assign(out, appForwardHeaders(url), { host: url.host });
+  // credentials in the URL are Basic auth, as fetch and http send them
+  if ((url.username || url.password) && !Object.keys(out).some((k) => k.toLowerCase() === 'authorization')) {
+    out.authorization = `Basic ${Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString('base64')}`;
+  }
+  return {
+    protocol: target.protocol, hostname: target.hostname, port: target.port || (target.protocol === 'https:' ? 443 : 80),
+    method, path: `${target.pathname.replace(/\/$/, '')}${url.pathname}${url.search}`, headers: out,
+    ...(extra && extra.signal ? { signal: extra.signal } : {}), ...(extra && extra.timeout !== undefined ? { timeout: extra.timeout } : {}),
+    ...(target.protocol === 'https:' && sessionCa() ? { ca: sessionCa() } : {}),
+    // the TLS name is the host dialled, not the Host the app answers as (an address has no TLS name: an empty one sends none)
+    ...(target.protocol === 'https:' ? { servername: isIP(target.hostname) ? '' : target.hostname } : {}),
+  };
+}
+
+/** One request to the application for `value`, a URL on one of its hosts, as `route` (appDestination's answer) names
+ *  it, with appRequestOptions' headers. No redirect is followed: the caller decides, as a delivery reports what it got.
+ *  Answers { status, headers (lower-cased), body (decoded text) } within `timeoutMs` overall; a failure rejects. */
+function deliverToApp(route, value, { method = 'POST', headers = {}, body, timeoutMs = 30_000 } = {}) {
+  const url = new URL(String(value));
+  const options = appRequestOptions(route, url, method, headers);
+  const make = (options.protocol === 'https:' ? require('https') : require('http')).request;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error) => { if (!settled) { settled = true; clearTimeout(deadline); req.destroy(); reject(error); } };
+    const req = make(options, (res) => {
+      // a reply cut off mid-body fails the delivery, decoded or not (pipe forwards no error to the decoder)
+      res.on('error', fail);
+      res.on('aborted', () => fail(new Error(`the application's answer to ${url.origin}${url.pathname} was cut off`)));
+      const encoding = String(res.headers['content-encoding'] || '').toLowerCase();
+      const zlib = require('zlib');
+      const decoder = encoding === 'gzip' || encoding === 'x-gzip' ? zlib.createGunzip() : encoding === 'deflate' ? zlib.createInflate() : encoding === 'br' ? zlib.createBrotliDecompress() : null;
+      const stream = decoder ? res.pipe(decoder) : res;
+      const chunks = [];
+      stream.on('data', (c) => chunks.push(c));
+      stream.on('error', fail);
+      stream.on('end', () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(deadline);
+        const answer = {};
+        for (const [k, v] of Object.entries(res.headers)) if (v !== undefined && !(decoder && (k === 'content-encoding' || k === 'content-length'))) answer[k.toLowerCase()] = Array.isArray(v) ? v.join(', ') : String(v);
+        resolve({ status: res.statusCode, headers: answer, body: Buffer.concat(chunks).toString('utf8') });
+      });
+    });
+    // one deadline for the whole exchange, not an idle timeout: an answer that trickles is still cut off
+    const deadline = setTimeout(() => fail(new Error(`the application did not answer ${url.origin}${url.pathname} within ${timeoutMs} ms`)), timeoutMs);
+    req.on('error', fail);
+    if (body != null && method !== 'GET' && method !== 'HEAD') req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { appRoute, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, sessionCa };

package/app-route.d.cts

@@ -0,0 +1,7 @@
+export interface AppRoute { 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 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;
+export function deliverToApp(route: AppRoute, value: string | URL, init?: { method?: string; headers?: Record<string, string>; body?: string | Uint8Array | null; timeoutMs?: number }): Promise<AppAnswer>;

package/attach.cjs

@@ -0,0 +1,80 @@
+// The rung-2 dormant attach (docs/guides/route-a-cli-through-the-world.md): `import '@volter/world-core/attach'`
+// as line 1 of an entrypoint. A NO-OP unless VOLTER_WORLD is set — production
+// behavior is byte-identical. When set:
+//   • a URL ref: fetch the world manifest (blocking child — this runs at
+//     module load, before the app constructs SDK clients), apply the attach
+//     env (vendor twin URLs, suggested fake credentials, CA trust), then load
+//     the injector.
+//   • anything else (a local name whose env the launcher already exported, or
+//     plain twin-URL env vars): just load the injector.
+// The injector itself remains ./inject.cjs — this file only decides whether
+// and how to arm it.
+'use strict';
+
+const ref = process.env.VOLTER_WORLD;
+if (ref) {
+  if (/^https?:\/\//i.test(ref)) {
+    const { spawnSync } = require('node:child_process');
+    const { mkdtempSync, readFileSync, writeFileSync } = require('node:fs');
+    const { tmpdir } = require('node:os');
+    const { join } = require('node:path');
+    const url = ref.replace(/\/$/, '').endsWith('/.well-known/volter-world')
+      ? ref.replace(/\/$/, '')
+      : `${ref.replace(/\/$/, '')}/.well-known/volter-world`;
+    const token = process.env.VOLTER_WORLD_TOKEN;
+    // a blocking fetch at module load: spawn a child that prints the manifest
+    const probe = spawnSync(
+      process.execPath,
+      ['-e', 'fetch(process.argv[1],process.argv[2]?{headers:{authorization:"Bearer "+process.argv[2]}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url, ...(token ? [token] : [])],
+      // the child must NOT inherit NODE_OPTIONS/VOLTER_WORLD — it would
+      // re-run this very file at its own startup (a spawn recursion bomb)
+      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+    );
+    if (probe.status !== 0) {
+      throw new Error(`[twin-attach] could not fetch the world manifest from ${url}: ${(probe.stderr || '').trim()}`);
+    }
+    const manifest = JSON.parse(probe.stdout);
+    for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
+      const key = `${vendor.toUpperCase()}_TWIN_URL`;
+      if (process.env[key] === undefined) process.env[key] = origin;
+    }
+    for (const [key, value] of Object.entries(manifest.env ?? {})) {
+      if (process.env[key] === undefined) process.env[key] = value;
+    }
+    // a World's byte-stream doors (a hosted World's smtp, planetscale's mysql): loopback listeners in
+    // this process, bridged over WebSocket (./stream-bridge.cjs). The env names the listener now, so the
+    // ports are chosen by a blocking child; the listeners bind on the next turn, before any client
+    // can connect, and never hold the process open.
+    const streams = Object.values(manifest.streams ?? {});
+    if (streams.length) {
+      const picked = spawnSync(
+        process.execPath,
+        ['-e', 'const n=require("node:net");const k=+process.argv[1];const s=[];const d=()=>{if(s.length<k){const v=n.createServer().listen(0,"127.0.0.1",()=>{s.push(v);d()})}else{process.stdout.write(s.map(v=>v.address().port).join(","));s.forEach(v=>v.close())}};d()', String(streams.length)],
+        { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      );
+      if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's streams: ${(picked.stderr || '').trim()}`);
+      const ports = picked.stdout.split(',').map(Number);
+      const { bridgeStream, streamEnv } = require('./stream-bridge.cjs');
+      const streamToken = token ?? manifest.env?.VOLTER_TWINS_KEY ?? '';
+      streams.forEach((stream, i) => {
+        for (const [key, value] of Object.entries(streamEnv(stream.env, ports[i]))) {
+          if (process.env[key] === undefined) process.env[key] = value;
+        }
+        bridgeStream(stream.url, streamToken, ports[i]).then((server) => server.unref(), (error) => {
+          process.stderr.write(`[twin-attach] ${stream.url}: could not listen on 127.0.0.1:${ports[i]}: ${error.message}\n`);
+        });
+      });
+    }
+    if (manifest.ca) {
+      const existingCa = process.env.NODE_EXTRA_CA_CERTS
+        ? readFileSync(process.env.NODE_EXTRA_CA_CERTS, 'utf8') : '';
+      const caFile = join(mkdtempSync(join(tmpdir(), 'twin-attach-')), 'ca.pem');
+      writeFileSync(caFile, `${existingCa}\n${manifest.ca}\n`);
+      process.env.NODE_EXTRA_CA_CERTS = caFile;
+      // NODE_EXTRA_CA_CERTS is read at process START — too late for THIS
+      // process's default TLS store. The injector's https forwards accept the
+      // session CA explicitly via this env; child processes inherit it fully.
+    }
+  }
+  require('./inject.cjs');
+}

package/dist/app-route.cjs

@@ -0,0 +1,154 @@
+'use strict';
+// THE APPLICATION'S OWN HOSTNAMES IN THE WORLD — the one home of the app route (dependency-free, side-effect free).
+//
+// `volter-world app-url <world> --host <name>` records the hostnames an application answers as in production beside
+// its URL (`app-url.json` in the instance); inside the World they reach the application, as DNS routes them to its
+// host in production (architecture.md, "The application's own production hostnames"). Two kinds of process route
+// them, and both read the route here:
+//   · a process the injector is installed in (the application, a script, the redirect proxy): inject.cjs's
+//     resolveTwin answers a recorded host with the application's origin, after twins and the hosts twins claim;
+//   · a twin's own outbound request (a QStash delivery, a webhook) from the colocated twin host, which runs without the
+//     injector: `appDestination` names the application for a URL on one of its hosts, and `deliverToApp` makes the
+//     request there, so a vendor's delivery to https://app.example.com/... reaches the application as it would reach
+//     its production deployment.
+// The record is read from the instance the process's World env names (VOLTER_WORLD_INSTANCE), at most once a second,
+// 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 }
+
+/** The application's route in the instance `instanceFile`: { origin, hosts } or null when none is recorded. */
+function appRoute(instanceFile) {
+  if (!instanceFile) return null;
+  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); }
+  held.checkedAt = now;
+  const fs = require('fs');
+  const path = require('path');
+  const file = path.join(path.dirname(instanceFile), 'app-url.json');
+  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;
+    }
+    // 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;
+  }
+  return held.route && held.route.origin ? held.route : null;
+}
+
+/** Whether `host` is one of the app's recorded hostnames: named exactly, or under a recorded wildcard (`*.dub.link`),
+ *  which, as a DNS wildcard, answers every name below its parent and never the parent itself. */
+function appHostMatch(hosts, host) {
+  if (hosts.has(host)) return true;
+  for (let dot = host.indexOf('.'); dot > 0; dot = host.indexOf('.', dot + 1)) {
+    if (hosts.has(`*${host.slice(dot)}`)) return true;
+  }
+  return false;
+}
+
+/** The headers a request routed to the application carries beside its own Host: the host and scheme it was made with. */
+function appForwardHeaders(url) {
+  return { 'x-forwarded-host': url.host, 'x-forwarded-proto': url.protocol === 'https:' ? 'https' : 'http' };
+}
+
+/** The application a URL reaches inside the World, when its host is one the application answers as: the route, or null. */
+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;
+}
+
+let SESSION_CA = undefined; // lazily read once; NODE_EXTRA_CA_CERTS set after process start
+/** The World's session CA (NODE_EXTRA_CA_CERTS), which an https origin inside the World is signed by, or null. */
+function sessionCa() {
+  if (SESSION_CA === undefined) {
+    const caPath = process.env.NODE_EXTRA_CA_CERTS;
+    try { SESSION_CA = caPath ? require('fs').readFileSync(caPath) : null; } catch { SESSION_CA = null; }
+  }
+  return SESSION_CA;
+}
+
+// What never reaches the application from a World process: the World's key and its routing marks, the caller's own
+// Host and forwarded host and scheme (replaced by the ones the request was made with), and an accepted encoding (the
+// answer is read decoded, as fetch reads it)
+const APP_DROPPED = ['accept-encoding', 'x-twins-key', 'x-volter-twin-original-host', 'proxy-connection', 'host', 'x-forwarded-host', 'x-forwarded-proto'];
+
+/** The node:http(s) request options for `url`, a URL on one of the application's hosts, sent where `route` says it
+ *  listens: the host it was made to as Host, with the forwarded host and scheme, never the World's own headers. */
+function appRequestOptions(route, url, method, headers, extra) {
+  const { isIP } = require('net');
+  const target = new URL(route.origin);
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) if (v !== undefined && !APP_DROPPED.includes(k.toLowerCase())) out[k] = v;
+  Object.assign(out, appForwardHeaders(url), { host: url.host });
+  // credentials in the URL are Basic auth, as fetch and http send them
+  if ((url.username || url.password) && !Object.keys(out).some((k) => k.toLowerCase() === 'authorization')) {
+    out.authorization = `Basic ${Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString('base64')}`;
+  }
+  return {
+    protocol: target.protocol, hostname: target.hostname, port: target.port || (target.protocol === 'https:' ? 443 : 80),
+    method, path: `${target.pathname.replace(/\/$/, '')}${url.pathname}${url.search}`, headers: out,
+    ...(extra && extra.signal ? { signal: extra.signal } : {}), ...(extra && extra.timeout !== undefined ? { timeout: extra.timeout } : {}),
+    ...(target.protocol === 'https:' && sessionCa() ? { ca: sessionCa() } : {}),
+    // the TLS name is the host dialled, not the Host the app answers as (an address has no TLS name: an empty one sends none)
+    ...(target.protocol === 'https:' ? { servername: isIP(target.hostname) ? '' : target.hostname } : {}),
+  };
+}
+
+/** One request to the application for `value`, a URL on one of its hosts, as `route` (appDestination's answer) names
+ *  it, with appRequestOptions' headers. No redirect is followed: the caller decides, as a delivery reports what it got.
+ *  Answers { status, headers (lower-cased), body (decoded text) } within `timeoutMs` overall; a failure rejects. */
+function deliverToApp(route, value, { method = 'POST', headers = {}, body, timeoutMs = 30_000 } = {}) {
+  const url = new URL(String(value));
+  const options = appRequestOptions(route, url, method, headers);
+  const make = (options.protocol === 'https:' ? require('https') : require('http')).request;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error) => { if (!settled) { settled = true; clearTimeout(deadline); req.destroy(); reject(error); } };
+    const req = make(options, (res) => {
+      // a reply cut off mid-body fails the delivery, decoded or not (pipe forwards no error to the decoder)
+      res.on('error', fail);
+      res.on('aborted', () => fail(new Error(`the application's answer to ${url.origin}${url.pathname} was cut off`)));
+      const encoding = String(res.headers['content-encoding'] || '').toLowerCase();
+      const zlib = require('zlib');
+      const decoder = encoding === 'gzip' || encoding === 'x-gzip' ? zlib.createGunzip() : encoding === 'deflate' ? zlib.createInflate() : encoding === 'br' ? zlib.createBrotliDecompress() : null;
+      const stream = decoder ? res.pipe(decoder) : res;
+      const chunks = [];
+      stream.on('data', (c) => chunks.push(c));
+      stream.on('error', fail);
+      stream.on('end', () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(deadline);
+        const answer = {};
+        for (const [k, v] of Object.entries(res.headers)) if (v !== undefined && !(decoder && (k === 'content-encoding' || k === 'content-length'))) answer[k.toLowerCase()] = Array.isArray(v) ? v.join(', ') : String(v);
+        resolve({ status: res.statusCode, headers: answer, body: Buffer.concat(chunks).toString('utf8') });
+      });
+    });
+    // one deadline for the whole exchange, not an idle timeout: an answer that trickles is still cut off
+    const deadline = setTimeout(() => fail(new Error(`the application did not answer ${url.origin}${url.pathname} within ${timeoutMs} ms`)), timeoutMs);
+    req.on('error', fail);
+    if (body != null && method !== 'GET' && method !== 'HEAD') req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { appRoute, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, sessionCa };

package/dist/app-route.d.cts

@@ -0,0 +1,7 @@
+export interface AppRoute { 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 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;
+export function deliverToApp(route: AppRoute, value: string | URL, init?: { method?: string; headers?: Record<string, string>; body?: string | Uint8Array | null; timeoutMs?: number }): Promise<AppAnswer>;