@volter/world-core 3.0.29 → 3.0.31

package/src/runtime.ts

@@ -13,7 +13,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
 export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
+export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
@@ -343,3 +343,6 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
 export { foldHistory } from './log.ts';
 export { volterHome } from './volter-home.ts';
+
+
+export { boardFrameKey } from './board-keys.ts';

package/src/serve.ts

@@ -594,6 +594,8 @@ export async function applyTwinWriteAtomic<T>(
   service: string,
   prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>,
   root?: string,
+  /** A type index when the decision and its preconditions need only that type, read inside the state lock. */
+  read?: () => TwinResource[],
 ): Promise<{ value: T; result?: TwinWriteResult }> {
   // Same ruling as applyTwinWrite: a local write is an OCCURRENCE unless the caller supplied
   // identity. The mode rides on the decision because only the callback knows which write it chose.
@@ -606,7 +608,7 @@ export async function applyTwinWriteAtomic<T>(
       action: actionForTwinWrite(service, decision.write),
       identity: decision.write.idempotencyKey || decision.write.actionId ? 'caller' : 'occurrence',
     };
-  }, root);
+  }, root, read);
   // as applyTwinWrite: a seed's write is the placeholder's default data, never performed
   const head = committed.action && committed.appended && !committed.placeholder ? await performAtHead(service, committed.action, root) : { performed: false };
   return {

package/src/twin-fetch.ts

@@ -1,3 +1,4 @@
+import { assertBrowserName } from './browser-state.ts';
 // THE ONE HTTP ADAPTATION (runtime contract R12b): most packs' serve path is the same
 // ~20 lines of glue — the keyless GET /twin manifest door, the body read, a header map,
 // the dispatch into `handle<Vendor>TwinRequest` with the WORLD instant, and a JSON
@@ -55,12 +56,14 @@ export const siteLabel = (hostname: string): string => hostname.toLowerCase().re
 
 /** The address a sites template gives `hostname`, or null where the template is not one or the name makes no address
  *  (a label over 63 characters). */
-export function siteUrlOf(template: string, hostname: string): string | null {
+export function siteUrlOf(template: string, hostname: string, browser?: string): string | null {
   const host = hostname.toLowerCase();
+  if (browser) { try { assertBrowserName(browser); } catch { return null; } }
+  const label = `${browser ? `${browser}--` : ''}${siteLabel(host)}`;
   if (!/^[a-z0-9.-]+$/.test(host)) return null;
   // a one-label site is never an IDN's (`xn--…` would be read as punycode, and is no address)
-  const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', host)
-    : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', siteLabel(host)) : null;
+  const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', browser ? label : host)
+    : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', label) : null;
   try { return filled && new URL(filled).hostname.split('.').every((l) => l.length > 0 && l.length <= 63) ? filled : null; } catch { return null; }
 }
 
@@ -69,7 +72,9 @@ export function siteUrlOf(template: string, hostname: string): string | null {
  *  mints its own URLs from twinPublicBase. */
 export function twinSiteUrl(request: Request, hostname: string): string {
   const at = request.headers.get(TWIN_SITES_HEADER);
-  return (at ? siteUrlOf(at, hostname) : null) ?? `https://${hostname.toLowerCase()}`;
+  let browser = request.headers.get('x-volter-world-browser') ?? undefined;
+  if (browser) { try { assertBrowserName(browser); } catch { browser = undefined; } }
+  return (at ? siteUrlOf(at, hostname, browser) : null) ?? `https://${hostname.toLowerCase()}`;
 }
 
 /** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves

package/vendor-hosts.cjs

@@ -1,8 +1,8 @@
 'use strict';
 // THE VENDOR HOST TABLE — which vendor's twin serves a hostname (and, where two vendors share a host, which path), the
-// one home of that fact in a process, dependency-free and side-effect free. The injector (inject.cjs) routes by it; the
+// Node process's loaded facts. The pure compiler and resolver are host-routing.cjs; this loader reads Node facts.
+// The injector (inject.cjs) routes by the table; the
 // application route (app-route.cjs) never answers a name it gives a vendor, in the injector or in a twin's delivery.
-// Moved out of inject.cjs unchanged (2026-09-27).
 // ── PATH-AWARE DISAMBIGUATION (the shared-host case) ─────────────────────────────────────────
 // A predicate is called as `(hostname, pathname)`. `pathname` is OPTIONAL and is `undefined`
 // wherever the caller genuinely does not have one yet — most importantly the proxy's CONNECT
@@ -25,108 +25,12 @@
 // `browserassets` and `googlefavicon`; kernel packages carry no pack descriptor). Every vendor
 // pack's hosts live on its descriptor as DATA — host | suffix | hostPattern, pathPattern,
 // exclude, key — compiled from pack-facts.json.
-const VENDOR_HOSTS = {
-  googlefavicon: (h) => h === 'www.google.com' || h === 'google.com' || h === 't2.gstatic.com',
-  browserassets: (h) =>
-    h === 'cdnjs.cloudflare.com' ||
-    h === 'www.googletagmanager.com' ||
-    h === 'www.google-analytics.com' ||
-    h === 'connect.facebook.net' ||
-    h === 'snap.licdn.com' ||
-    h === 'px.ads.linkedin.com' ||
-    h === 'static.hotjar.com' ||
-    h === 'fonts.googleapis.com' ||
-    h === 'fonts.gstatic.com' ||
-    h === 'api.fontshare.com' ||
-    h === 'images.subscribe.dev' ||
-    h === 'www.youtube.com' ||
-    h === 'www.youtube-nocookie.com' ||
-    h === 'i.ytimg.com',
-};
-
-// descriptor-first migration (architecture.md, "The descriptor"): packs now declare their hosts as DATA on their descriptor
-// (`hosts` on TwinPack), compiled into the committed pack-facts artifact — a plain JSON this
-// preloaded, dependency-free module can `require` natively. The hand table above shrinks toward
-// empty as entries move; a vendor present in both homes throws (dual declaration is the drift
-// this migration ends, and a broken checkout should refuse to inject rather than half-route).
-/** The keys each pack's compiled rules answer under, by vendor: a pack's own facts learned later (addPackHosts) replace
- *  that vendor's rules, never another's. */
-const COMPILED = new Map();
-/** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
- *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
-const HAND = new Set(Object.keys(VENDOR_HOSTS));
-/** One host rule as a predicate over (hostname, pathname?): its one selector (host | suffix | hostPattern) and its
- *  pathPattern, a path left out matching any. */
-function compileHostRule(rule, where) {
-  const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
-  if (selectors !== 1) throw new Error(`inject: ${where} rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
-  const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
-  const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
-  return (h, p) =>
-    (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
-    && (pathRe === null || p === undefined || pathRe.test(p));
-}
-
-/** A pack's host rules (its descriptor's `hosts`) read as the injector reads them: `names(host)`, whether any include
- *  rule's selector names the host, whatever the path; `takes(host, path)`, whether the request is the pack's (under
- *  one of its keys, an include matches and no exclude does). The content route at a World's place holds a
- *  `<base>/@<host>/<path>` to it (pack-fetch.ts). */
-function hostRules(rules) {
-  const byKey = new Map();
-  for (const rule of rules || []) {
-    const key = rule.key === undefined ? '' : rule.key;
-    if (!byKey.has(key)) byKey.set(key, []);
-    byKey.get(key).push(rule);
-  }
-  const keys = [...byKey.values()].map((keyRules) => ({
-    includes: keyRules.filter((r) => r.exclude !== true).map((r) => compileHostRule(r, 'a pack')),
-    excludes: keyRules.filter((r) => r.exclude === true).map((r) => compileHostRule(r, 'a pack')),
-  }));
-  return {
-    names: (h) => keys.some((k) => k.includes.some((m) => m(h))),
-    takes: (h, p) => keys.some((k) => k.includes.some((m) => m(h, p)) && !k.excludes.some((m) => m(h, p))),
-  };
-}
-
-function compilePackHosts(packs, overlay) {
-  for (const vendor of Object.keys(packs)) {
-    const rules = packs[vendor].hosts;
-    if (!rules || rules.length === 0) continue;
-    for (const key of COMPILED.get(vendor) || []) delete VENDOR_HOSTS[key];
-    COMPILED.delete(vendor);
-    if (VENDOR_HOSTS[vendor] && !(overlay && HAND.has(vendor))) {
-      throw new Error(`inject: vendor "${vendor}" declares hosts on its pack descriptor AND in the hand VENDOR_HOSTS table — one home per fact; delete the hand entry.`);
-    }
-    // Rules group by `key` (default: the vendor id) — aws's descriptor declares the s3 and
-    // secretsmanager routing identities its twin answers under. A key matches when ANY include
-    // rule matches AND NO exclude rule matches.
-    const byKey = new Map();
-    for (const rule of rules) {
-      const key = rule.key === undefined ? vendor : rule.key;
-      if (!byKey.has(key)) byKey.set(key, []);
-      byKey.get(key).push(rule);
-    }
-    for (const [key, keyRules] of byKey) {
-      if (VENDOR_HOSTS[key] && !(overlay && HAND.has(key))) {
-        throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
-      }
-      const compile = (rule) => compileHostRule(rule, `key "${key}" (pack ${vendor})`);
-      const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
-      const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
-      VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
-      COMPILED.set(vendor, [...(COMPILED.get(vendor) || []), key]);
-    }
-  }
-}
-{
-  const facts = require('./pack-facts.cjs').packFacts();
-  const installed = new Set(facts.installed || []);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => !installed.has(vendor))), false);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => installed.has(vendor))), true);
-}
-/** Rules from packs' facts learned after this module loaded (a runtime told the facts of the World it boots): each
- *  vendor's replace its earlier rules. */
-function addPackHosts(packs) { compilePackHosts(packs || {}, true); }
+const routing = require('./host-routing.cjs');
+const facts = require('./pack-facts.cjs').packFacts();
+const table = routing.createHostTable(facts.packs, facts.installed);
+const VENDOR_HOSTS = table.hosts;
+const hostRules = routing.hostRules;
+function addPackHosts(packs) { table.addPackHosts(packs); }
 
 /** Whether any vendor's host rule names `host` (at the host level, whatever the path), whether or not its twin runs. */
 function isVendorHost(host) {
@@ -166,4 +70,8 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+/** Resolve using this Node process's loaded facts. */
+function resolveTwinHost(hostname, map, pathname, claimed) {
+  return routing.resolveTwinHost(VENDOR_HOSTS, hostname, map, pathname, claimed);
+}
+module.exports = { resolveTwinHost, VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/vendor-hosts.d.cts

@@ -9,3 +9,6 @@ export function twinOrigins(env: Readonly<Record<string, string | undefined>>):
 /** A pack's host rules (its descriptor's `hosts`, as data) read as the injector reads them: whether any include names a
  *  host whatever the path, and whether a request to a host and path is the pack's. */
 export function hostRules(rules: ReadonlyArray<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };
+
+/** Resolve an active twin exactly as the proxy, first declared host/path rules, then claimed hosts. */
+export function resolveTwinHost(hostname: string, map: Readonly<Record<string, string>>, pathname?: string, claimed?: Readonly<Record<string, ReadonlySet<string> | (() => ReadonlySet<string>)>>): { vendor: string; origin: string } | null;