@volter/world-core 3.0.29 → 3.0.31

package/dist/src/runtime.d.ts

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

package/dist/src/runtime.js

@@ -12,7 +12,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
+export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
@@ -103,3 +103,4 @@ export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, w
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";
 export { volterHome } from "./volter-home.js";
+export { boardFrameKey } from "./board-keys.js";

package/dist/src/serve.d.ts

@@ -168,7 +168,9 @@ export declare function recordedInput(input: unknown): Promise<unknown>;
  * Use this when acceptance or the new fields depend on current projected state; a caller-side
  * read followed by `applyTwinWrite` is not atomic across processes.
  */
-export declare function applyTwinWriteAtomic<T>(service: string, prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>, root?: string): Promise<{
+export declare 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;
 }>;

package/dist/src/serve.js

@@ -498,7 +498,9 @@ function actionForTwinWrite(service, write) {
  * Use this when acceptance or the new fields depend on current projected state; a caller-side
  * read followed by `applyTwinWrite` is not atomic across processes.
  */
-export async function applyTwinWriteAtomic(service, prepare, root) {
+export async function applyTwinWriteAtomic(service, prepare, root, 
+/** A type index when the decision and its preconditions need only that type, read inside the state lock. */
+read) {
     // 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.
     const committed = decideAndAppendAction(service, (resources) => {
@@ -511,7 +513,7 @@ export async function applyTwinWriteAtomic(service, prepare, root) {
             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/dist/src/twin-fetch.d.ts

@@ -17,7 +17,7 @@ export declare const TWIN_SITES_HEADER = "x-volter-world-sites";
 export declare const siteLabel: (hostname: string) => string;
 /** 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 declare function siteUrlOf(template: string, hostname: string): string | null;
+export declare function siteUrlOf(template: string, hostname: string, browser?: string): string | null;
 /** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
  *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
  *  mints its own URLs from twinPublicBase. */

package/dist/src/twin-fetch.js

@@ -1,3 +1,4 @@
+import { assertBrowserName } from "./browser-state.js";
 // 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
@@ -50,13 +51,22 @@ export const TWIN_SITES_HEADER = 'x-volter-world-sites';
 export const siteLabel = (hostname) => hostname.toLowerCase().replace(/\./g, '-');
 /** 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, hostname) {
+export function siteUrlOf(template, hostname, browser) {
     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;
     }
@@ -69,7 +79,16 @@ export function siteUrlOf(template, hostname) {
  *  mints its own URLs from twinPublicBase. */
 export function twinSiteUrl(request, hostname) {
     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()}`;
 }
 /** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
  *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every

package/dist/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/dist/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;

package/host-routing.cjs

@@ -0,0 +1,106 @@
+'use strict';
+// Host routing is data in, answer out. No imports, environment reads or module-load table construction.
+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))),
+  };
+}
+
+/** Build one independent host table, in the proxy's key order, from supplied pack facts and overlays. */
+function createHostTable(packs, installed = []) {
+  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',
+  };
+  const COMPILED = new Map();
+  const HAND = new Set(Object.keys(VENDOR_HOSTS));
+  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 overlays = new Set(installed);
+  compilePackHosts(Object.fromEntries(Object.entries(packs).filter(([vendor]) => !overlays.has(vendor))), false);
+  compilePackHosts(Object.fromEntries(Object.entries(packs).filter(([vendor]) => overlays.has(vendor))), true);
+  return { hosts: VENDOR_HOSTS, addPackHosts: packs => compilePackHosts(packs || {}, true) };
+}
+
+/** Static host/path rules first, then supplied claimed hosts. */
+function resolveTwinHost(rules, hostname, map, pathname, claimed = {}) {
+  for (const vendor of Object.keys(rules)) {
+    if (map[vendor] && rules[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
+  }
+  const host = String(hostname || '').toLowerCase();
+  for (const vendor of Object.keys(claimed)) {
+    if (!map[vendor]) continue;
+    const hosts = typeof claimed[vendor] === 'function' ? claimed[vendor]() : claimed[vendor];
+    if (hosts.has(host)) return { vendor, origin: map[vendor] };
+  }
+  return null;
+}
+
+module.exports = { createHostTable, hostRules, resolveTwinHost };

package/host-routing.d.cts

@@ -0,0 +1,7 @@
+/** Pure host rules and resolution: supplied data only, safe in an isolate. */
+export type HostRuleData = { host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true };
+export type HostPredicate = (hostname: string, pathname?: string) => boolean;
+export type HostFacts = Readonly<Record<string, { hosts?: ReadonlyArray<HostRuleData> }>>;
+export function hostRules(rules: ReadonlyArray<HostRuleData> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };
+export function createHostTable(packs: HostFacts, installed?: Iterable<string>): { hosts: Record<string, HostPredicate>; addPackHosts(packs: HostFacts): void };
+export function resolveTwinHost(rules: Readonly<Record<string, HostPredicate>>, hostname: string, map: Readonly<Record<string, string>>, pathname?: string, claimed?: Readonly<Record<string, ReadonlySet<string> | (() => ReadonlySet<string>)>>): { vendor: string; origin: string } | null;

package/inject.cjs

@@ -47,6 +47,7 @@ const { createPublicKey, createVerify } = require('crypto');
 
 // the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
 // serves it) has its own home, shared with the application route
+const { resolveTwinHost } = require('./host-routing.cjs');
 const { VENDOR_HOSTS, twinEnvStem, twinOrigins } = require('./vendor-hosts.cjs');
 const dns = require('dns');
 const http2 = require('http2');
@@ -216,15 +217,11 @@ function readMap(env) {
  * sees only the SNI name) omit it and get host-level candidacy.
  */
 function resolveTwin(hostname, map, pathname) {
-  for (const vendor of Object.keys(VENDOR_HOSTS)) {
-    if (map[vendor] && VENDOR_HOSTS[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
-  }
-  // then a host a running twin claims (a custom domain a person connected), as DNS would route it; never one a
-  // descriptor's hosts name, which the loop above has already answered
+  const target = resolveTwinHost(VENDOR_HOSTS, hostname, map, pathname, Object.fromEntries(
+    Object.keys(CLAIMERS).map(vendor => [vendor, () => claimsAt(map[vendor], CLAIMERS[vendor]).hosts])
+  ));
+  if (target) return target;
   const host = String(hostname || '').toLowerCase();
-  for (const vendor of Object.keys(CLAIMERS)) {
-    if (map[vendor] && claimsAt(map[vendor], CLAIMERS[vendor]).hosts.has(host)) return { vendor, origin: map[vendor] };
-  }
   // last, the application's own production hostnames, routed to where it listens in the World; never the World's own
   // origin or a twin's, whose requests carry the World key
   const bare = host.replace(/\.$/, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.29",
+  "version": "3.0.31",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -29,6 +29,8 @@
     "network-policy.d.cts",
     "app-route.cjs",
     "vendor-hosts.cjs",
+    "host-routing.cjs",
+    "host-routing.d.cts",
     "pack-facts.cjs",
     "vendor-hosts.d.cts",
     "world-clock.cjs",
@@ -61,6 +63,10 @@
       "types": "./dist/src/runtime.d.ts",
       "default": "./dist/src/runtime.js"
     },
+    "./browser": {
+      "types": "./dist/src/browser.d.ts",
+      "default": "./dist/src/browser.js"
+    },
     "./args": {
       "types": "./dist/src/args.d.ts",
       "default": "./dist/src/args.js"
@@ -86,6 +92,10 @@
       "default": "./app-route.cjs"
     },
     "./vendor-hosts": "./vendor-hosts.cjs",
+    "./host-routing": {
+      "types": "./host-routing.d.cts",
+      "default": "./host-routing.cjs"
+    },
     "./pack-facts": "./pack-facts.cjs",
     "./world-clock": {
       "types": "./world-clock.d.cts",

package/src/actions.ts

@@ -361,9 +361,11 @@ export function decideAndAppendAction<T>(
   service: string,
   decide: (resources: TwinResource[]) => AtomicActionDecision<T>,
   root?: string,
+  /** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+  read: () => TwinResource[] = () => projectResources(service, root),
 ): { value: T; action?: TwinAction; appended: boolean; placeholder?: true } {
   return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
-    const resources = projectResources(service, root);
+    const resources = read();
     const decision = decide(resources);
     if (decision.kind === 'skip') return { value: decision.value, appended: false };
     refuseReadOnlyWrite(service); // a decision to write is the write a read-only request may not make

package/src/board-keys.ts

@@ -0,0 +1,4 @@
+/** A page's key, shared by its World and console. Browser keys cannot equal vendor-prefixed plain keys. */
+export function boardFrameKey(frame: { vendor: string; id: string; browser?: string }): string {
+  return frame.browser ? `~browser:${encodeURIComponent(frame.browser)}:${frame.vendor}:${frame.id}` : `${frame.vendor}:${frame.id}`;
+}

package/src/browser-cookie-jar.ts

@@ -0,0 +1,77 @@
+import suffixes from './public-suffixes.json' with { type: 'json' };
+import { cookieMatchesHost, type BrowserCookie } from './browser-state.ts';
+
+/** Cookie domain acceptance uses the public suffix list, including its wildcard and exception rules. */
+let rules: Set<string> | undefined;
+function publicSuffix(domain: string): boolean {
+  rules ??= new Set(suffixes.rules.map(rule => {
+    const prefix = rule.startsWith('!') ? '!' : rule.startsWith('*.') ? '*.' : '';
+    return `${prefix}${new URL(`https://${rule.slice(prefix.length)}`).hostname}`;
+  }));
+  const labels = domain.split('.');
+  let size = 1;
+  for (let i = 0; i < labels.length; i++) {
+    const suffix = labels.slice(i).join('.');
+    if (rules.has(`!${suffix}`)) return labels.length === labels.length - i - 1;
+    if (rules.has(suffix)) size = Math.max(size, labels.length - i);
+    if (i > 0 && rules.has(`*.${suffix}`)) size = Math.max(size, labels.length - i + 1);
+  }
+  return labels.length === size;
+}
+const domainMatches = (host: string, domain: string): boolean => host === domain || host.endsWith(`.${domain}`);
+const pathMatches = (path: string, scope: string): boolean => path === scope || (path.startsWith(scope) && (scope.endsWith('/') || path[scope.length] === '/'));
+
+/** A seed's HTTP cookie jar; cookies remain at the real URL even when transport goes to a twin. */
+export class BrowserCookieJar {
+  private cookies: BrowserCookie[];
+  constructor(cookies: BrowserCookie[] = []) { this.cookies = structuredClone(cookies); }
+  snapshot(now: number): BrowserCookie[] {
+    this.cookies = this.cookies.filter(c => c.expires === -1 || c.expires > now / 1000);
+    return structuredClone(this.cookies);
+  }
+  header(url: URL, now: number): string {
+    return this.snapshot(now).filter(c => (!c.secure || url.protocol === 'https:') &&
+      cookieMatchesHost(c, url.hostname) && pathMatches(url.pathname, c.path))
+      .sort((a, b) => b.path.length - a.path.length).map(c => `${c.name}=${c.value}`).join('; ');
+  }
+  set(line: string, url: URL, now: number): void {
+    const [pair = '', ...attributes] = line.split(';');
+    const eq = pair.indexOf('=');
+    if (eq < 1) return;
+    const name = pair.slice(0, eq).trim(); const value = pair.slice(eq + 1).trim();
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || /[\x00-\x1f\x7f;\u0100-\uffff]/.test(value)) return;
+    const attrs = new Map<string, string>();
+    for (const part of attributes) { const at = part.indexOf('='); attrs.set((at < 0 ? part : part.slice(0, at)).trim().toLowerCase(), at < 0 ? '' : part.slice(at + 1).trim()); }
+    let domain = url.hostname;
+    const asked = attrs.get('domain');
+    if (asked) {
+      if (/[\s:/\\?#@%]/.test(asked)) return;
+      let normalized: string;
+      try { normalized = new URL(`https://${asked.replace(/^\./, '')}`).hostname; } catch { return; }
+      if (!domainMatches(url.hostname, normalized) || publicSuffix(normalized)) return;
+      domain = `.${normalized}`;
+    }
+    const last = url.pathname.lastIndexOf('/');
+    const fallback = last > 0 ? url.pathname.slice(0, last) : '/';
+    const path = attrs.get('path')?.startsWith('/') ? attrs.get('path')! : fallback;
+    if (/[\x00-\x20\x7f;\u0100-\uffff]/.test(path)) return;
+    const secure = attrs.has('secure');
+    if (secure && url.protocol !== 'https:') return;
+    const same = attrs.get('samesite')?.toLowerCase();
+    const sameSite = same === 'strict' ? 'Strict' : same === 'none' ? 'None' : 'Lax';
+    if (sameSite === 'None' && !secure) return;
+    if (name.startsWith('__Secure-') && !secure) return;
+    if (name.startsWith('__Host-') && (!secure || asked || attrs.get('path') !== '/')) return;
+    let expires = -1;
+    const date = attrs.get('expires');
+    if (date && Number.isFinite(Date.parse(date))) expires = Date.parse(date) / 1000;
+    const age = attrs.get('max-age');
+    if (age && /^-?\d+$/.test(age)) { const seconds = Number(age); expires = seconds <= 0 ? 0 : Math.min(8640000000000, now / 1000 + seconds); }
+    const existing = this.cookies.findIndex(c => c.name === name && c.domain.replace(/^\./, '') === domain.replace(/^\./, '') && c.path === path);
+    // An insecure response cannot replace a secure cookie with an overlapping scope.
+    if (url.protocol !== 'https:' && this.cookies.some(c => c.name === name && c.secure && domainMatches(domain.replace(/^\./, ''), c.domain.replace(/^\./, '')) && pathMatches(path, c.path))) return;
+    const cookie: BrowserCookie = { name, value, domain, path, expires, secure, httpOnly: attrs.has('httponly'), sameSite };
+    if (existing < 0) this.cookies.push(cookie); else this.cookies[existing] = cookie;
+    this.snapshot(now);
+  }
+}

package/src/browser-session.ts

@@ -0,0 +1,31 @@
+// A vendor's browser session: the bookkeeping used by its own sign-in and sign-out pages.
+import type { HandlerContext } from './derived-core.ts';
+
+type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
+
+/** The named cookie, without interpreting any other vendor's cookie. */
+export function browserSessionToken(request: Request, name: string): string | undefined {
+  for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+    const at = part.indexOf('=');
+    if (at > 0 && part.slice(0, at).trim() === name) {
+      try { return decodeURIComponent(part.slice(at + 1).trim()); } catch { return undefined; }
+    }
+  }
+  return undefined;
+}
+
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export async function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string> {
+  const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });
+  const token = await ctx.secret(`web-session:${issued}`);
+  await ctx.record('_web_session', { token, email, ...(scope !== undefined ? { scope } : {}), created_at: ctx.occurredAt }, `websession:${token}`);
+  return `${cookie}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export async function endBrowserSession(ctx: Pick<HandlerContext, 'call' | 'record' | 'rowsRaw' | 'occurredAt'>, cookie: string): Promise<string> {
+  const token = browserSessionToken(ctx.call.request, cookie);
+  const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+  if (session) await ctx.record('_web_session', { token: null, ended_at: ctx.occurredAt }, String(session.id));
+  return `${cookie}=; path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}