@volter/world-core 3.0.37 → 3.0.39

package/src/serve.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 // Twin serve layer (the twins architecture notes, increment 1): answer vendor-shaped
 // READS from the local event-sourced state — the "local twin" read path. An app
 // or agent points at this instead of the real vendor; it responds from local
@@ -126,7 +127,7 @@ export function readTwinRequestJournal(service: string, root?: string, options:
   const parse = (file: string): TwinRequestJournalEntry[] => {
     const text = getActiveWorldStore().read(file); if (!text) return [];
     const rows: TwinRequestJournalEntry[] = [];
-    for (const line of text.split('\n')) { if (!line) continue; try { rows.push(JSON.parse(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
+    for (const line of text.split('\n')) { if (!line) continue; try { rows.push(parseExactJson(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
     return rows;
   };
   const kept: TwinRequestJournalEntry[][] = [parse(path)];
@@ -168,7 +169,7 @@ export function readTwinRequestJournalFrom(service: string, root: string | undef
     const text = store.readRange ? store.readRange(file, start) : ((t) => (t === null ? null : Buffer.from(t, 'utf8').subarray(start).toString('utf8')))(store.read(file));
     if (!text) return start;
     const end = whole ? text.length : text.lastIndexOf('\n') + 1;
-    for (const line of text.slice(0, end).split('\n')) { if (!line) continue; try { entries.push(JSON.parse(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
+    for (const line of text.slice(0, end).split('\n')) { if (!line) continue; try { entries.push(parseExactJson(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
     return start + Buffer.byteLength(text.slice(0, end), 'utf8');
   };
   if (cursor === null) {
@@ -414,7 +415,7 @@ function journalingFetch(config: Record<string | symbol, unknown> & { fetch: (..
       try {
         const response = (await identitySlot().run(slot, () => inner.call(this, request, server))) as Response | undefined;
         if (response instanceof Response) status = response.status;
-        else if (response === undefined) return response; // upgraded (websocket) — nothing served
+        else if (response === undefined) { status = 101; return response; } // accepted WebSocket upgrade
         return response;
       } finally {
         // Only an OBSERVED identity is cached: it is the twin's own words. A fallback is

package/src/signing.ts

@@ -1,6 +1,7 @@
+import { parseExactJson, compareExactNumbers } from './exact-json.ts';
 // SIGNING ON THE CONTEXT (docs/contributing/architecture.md, "What an author writes, and how": the tokens-and-keys row)
 // — one deterministic implementation of what vendors sign with, given to handlers as `ctx.crypto`, so no pack reaches
-// `node:crypto` itself: JWTs (RS256 with a pack's instance key, HS256 with a shared secret), their verification, a
+// `node:crypto` itself: JWTs (RS256 or EdDSA with a pack's instance key, HS256 with a shared secret), their verification, a
 // JWKS for a public key, an HMAC and a SHA-256. Nothing here is random: a key is the pack's data (a PEM it declares),
 // and every value a signature carries comes from the call.
 // A namespace, never named imports: a browser client bundles the kernel, and the browser's `node:crypto` polyfill has no
@@ -9,13 +10,14 @@ import * as nodeCrypto from 'node:crypto';
 import { sealedBoxKeyPair, sealedBoxOpen } from './sealed-box.ts';
 
 type Row = Record<string, unknown>;
-export type Jwk = { kty: 'RSA'; use: 'sig'; alg: 'RS256'; kid: string; n: string; e: string };
+export type Jwk = { kty: 'RSA'; use: 'sig'; alg: 'RS256'; kid: string; n: string; e: string } | { kty: 'OKP'; use: 'sig'; alg: 'EdDSA'; crv: 'Ed25519'; kid: string; x: string };
 export type Jwks = { keys: Jwk[] };
-/** A signing key: an RSA private key as a PEM (its public half, given or derived, is what a JWKS serves and names by
- *  `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs none. */
-export type SigningKey = { alg: 'RS256' | 'RS384' | 'RS512'; privatePem: string; publicPem?: string } | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string };
+/** A signing key: an RSA or Ed25519 private key as a PEM (its public half, given or derived, is what a JWKS serves and
+ *  names by `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs
+ *  none; Ed25519's is deterministic (RFC 8032), Better Auth's default (`EdDSA`). */
+export type SigningKey = { alg: 'RS256' | 'RS384' | 'RS512' | 'EdDSA'; privatePem: string; publicPem?: string } | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string };
 /** The algorithms `jwtSign` signs with. */
-export const SIGNING_ALGORITHMS: ReadonlyArray<SigningKey['alg']> = ['RS256', 'RS384', 'RS512', 'HS256', 'HS384', 'HS512'];
+export const SIGNING_ALGORITHMS: ReadonlyArray<SigningKey['alg']> = ['RS256', 'RS384', 'RS512', 'EdDSA', 'HS256', 'HS384', 'HS512'];
 const digestOf = (alg: string): string => `sha${alg.slice(2)}`;
 /** Whether a token holds: its signature and its `exp`/`nbf` at `now` (seconds), with the payload when it does. */
 export type JwtVerdict = { valid: boolean; payload?: Row; reason?: 'malformed' | 'unexpected_alg' | 'no_matching_key' | 'bad_signature' | 'expired' | 'not_yet_valid' };
@@ -31,14 +33,21 @@ export function keyId(publicPem: string, prefix = 'ins_'): string {
 }
 
 /** A JWT: `iat` and `nbf` are `now` (seconds, the World's), `exp` `now` plus the lifetime (60 s when none is given),
- *  unless the claims name their own. RS256 tokens carry the key's `kid`. */
-export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expiresInSeconds?: number; kidPrefix?: string }): string {
+ *  unless the claims name their own. A token of a key pair carries the key's `kid`. */
+export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expiresInSeconds?: number; kidPrefix?: string; typ?: string }): string {
+  // a key of another kind than its algorithm's is refused by name (an RSA key under EdDSA would fail inside the signer)
+  if ('privatePem' in key) {
+    const kind = nodeCrypto.createPrivateKey(key.privatePem).asymmetricKeyType;
+    const wants = key.alg === 'EdDSA' ? 'ed25519' : 'rsa';
+    if (kind !== wants) throw new Error(`jwtSign: ${key.alg} signs with an ${wants === 'rsa' ? 'RSA' : 'Ed25519'} key, and this key is ${kind ?? 'of no known type'}`);
+  }
   const header = 'privatePem' in key
-    ? { alg: key.alg, typ: 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
-    : { alg: key.alg, typ: 'JWT' };
+    ? { alg: key.alg, typ: opts.typ ?? 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
+    : { alg: key.alg, typ: opts.typ ?? 'JWT' };
   const payload = { iat: opts.now, exp: opts.now + (opts.expiresInSeconds ?? 60), nbf: opts.now, ...claims };
   const input = `${jsonPart(header)}.${jsonPart(payload)}`;
   if ('secret' in key) return `${input}.${base64url(nodeCrypto.createHmac(digestOf(key.alg), key.secret).update(input).digest())}`;
+  if (key.alg === 'EdDSA') return `${input}.${base64url(nodeCrypto.sign(null, Buffer.from(input), key.privatePem))}`;
   const signer = nodeCrypto.createSign(`RSA-SHA${key.alg.slice(2)}`);
   signer.update(input);
   signer.end();
@@ -49,17 +58,17 @@ export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expir
 export function jwtDecode(token: string): { header: Row; payload: Row } {
   const parts = token.split('.');
   if (parts.length !== 3) throw new Error('malformed jwt');
-  const part = (s: string): Row => JSON.parse(fromBase64url(s).toString('utf8')) as Row;
+  const part = (s: string): Row => parseExactJson(fromBase64url(s).toString('utf8')) as Row;
   return { header: part(parts[0]!), payload: part(parts[1]!) };
 }
 
 function timely(payload: Row, now: number): JwtVerdict {
-  if (typeof payload.exp === 'number' && now >= payload.exp) return { valid: false, reason: 'expired' };
-  if (typeof payload.nbf === 'number' && now < payload.nbf) return { valid: false, reason: 'not_yet_valid' };
+  if ((typeof payload.exp === 'number' || typeof payload.exp === 'string' && /^-?\d+$/.test(payload.exp)) && compareExactNumbers(now, payload.exp) >= 0) return { valid: false, reason: 'expired' };
+  if ((typeof payload.nbf === 'number' || typeof payload.nbf === 'string' && /^-?\d+$/.test(payload.nbf)) && compareExactNumbers(now, payload.nbf) < 0) return { valid: false, reason: 'not_yet_valid' };
   return { valid: true, payload };
 }
 
-/** A token checked: an RS256 one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
+/** A token checked: an RS256 or EdDSA one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
  *  then its `exp`/`nbf` at `now` (seconds). */
 export function jwtVerify(token: string, key: Jwks | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string }, opts: { now: number }): JwtVerdict {
   let decoded: { header: Row; payload: Row };
@@ -72,10 +81,16 @@ export function jwtVerify(token: string, key: Jwks | { alg: 'HS256' | 'HS384' |
     if (given.length !== expected.length || !nodeCrypto.timingSafeEqual(given, expected)) return { valid: false, reason: 'bad_signature' };
     return timely(decoded.payload, opts.now);
   }
-  if (!['RS256', 'RS384', 'RS512'].includes(String(decoded.header.alg))) return { valid: false, reason: 'unexpected_alg' };
+  if (!['RS256', 'RS384', 'RS512', 'EdDSA'].includes(String(decoded.header.alg))) return { valid: false, reason: 'unexpected_alg' };
   // a token naming a key the set does not hold matches none; one naming no key is tried against the set's only key
   const jwk = decoded.header.kid !== undefined ? key.keys.find((k) => k.kid === decoded.header.kid) : key.keys.length === 1 ? key.keys[0] : undefined;
   if (!jwk) return { valid: false, reason: 'no_matching_key' };
+  if ((jwk.kty === 'OKP') !== (decoded.header.alg === 'EdDSA')) return { valid: false, reason: 'unexpected_alg' };
+  if (jwk.kty === 'OKP') {
+    const edKey = nodeCrypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' });
+    if (!nodeCrypto.verify(null, Buffer.from(`${h}.${p}`), edKey, fromBase64url(s))) return { valid: false, reason: 'bad_signature' };
+    return timely(decoded.payload, opts.now);
+  }
   const verifier = nodeCrypto.createVerify(`RSA-SHA${String(decoded.header.alg).slice(2)}`);
   verifier.update(`${h}.${p}`);
   verifier.end();
@@ -86,7 +101,8 @@ export function jwtVerify(token: string, key: Jwks | { alg: 'HS256' | 'HS384' |
 
 /** The JWKS that verifies every token a public key's pair signs. */
 export function jwks(publicPem: string, kidPrefix?: string): Jwks {
-  const jwk = nodeCrypto.createPublicKey(publicPem).export({ format: 'jwk' }) as { n?: string; e?: string };
+  const jwk = nodeCrypto.createPublicKey(publicPem).export({ format: 'jwk' }) as { kty?: string; n?: string; e?: string; x?: string };
+  if (jwk.kty === 'OKP') return { keys: [{ kty: 'OKP', use: 'sig', alg: 'EdDSA', crv: 'Ed25519', kid: keyId(publicPem, kidPrefix), x: String(jwk.x) }] };
   return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid: keyId(publicPem, kidPrefix), n: String(jwk.n), e: String(jwk.e) }] };
 }
 
@@ -168,6 +184,22 @@ export function lettersFrom(seed: string, count = 20): string {
   return out;
 }
 
+/** `count` base62 characters (0-9A-Za-z) derived from `seed`, the same every run: the opaque tail of an id a vendor
+ *  writes in base62 (OpenAI's `call_unLAR8MvFNptuiZK6K6HCy5k`, 24 after its prefix). */
+export function base62From(seed: string, count = 24): string {
+  const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+  let out = '';
+  for (let round = 0; out.length < count; round += 1) {
+    // each byte below 248 (4 x 62) maps evenly onto the alphabet; the rest are skipped
+    for (const byte of sha256(`${seed}:${round}`).match(/../g)!) {
+      if (out.length === count) break;
+      const b = Number.parseInt(byte, 16);
+      if (b < 248) out += ALPHABET[b % 62];
+    }
+  }
+  return out;
+}
+
 /** Two strings compared in constant time. */
 export function equalSecrets(a: string, b: string): boolean {
   const left = Buffer.from(a, 'utf8');
@@ -227,5 +259,27 @@ export function certificateOf(cert: string | Uint8Array): { der: Uint8Array; sub
 }
 
 /** What a handler signs and hashes with: `ctx.crypto`. */
-export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf } as const;
+export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, base62From, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf } as const;
 export type HandlerCrypto = typeof handlerCrypto;
+
+/** A [KSUID](https://github.com/segmentio/ksuid) as 27 base62 characters (0-9A-Za-z, most significant first): `seconds`
+ *  past KSUID's epoch (1400000000) in four bytes, then `n` in four, then twelve bytes derived from `seed`, so KSUIDs
+ *  made in one second sort by `n`, at `width` characters (27 unless a vendor's id is longer or shorter). Deterministic:
+ *  the same arguments give the same id. */
+export function ksuidFrom(seconds: number, n: number, seed: string, width = 27): string {
+  const bytes = new Uint8Array(20);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, Math.max(0, seconds - 1_400_000_000) >>> 0);
+  view.setUint32(4, n >>> 0);
+  const tail = sha256(seed);
+  for (let i = 0; i < 12; i++) bytes[8 + i] = parseInt(tail.slice(i * 2, i * 2 + 2), 16);
+  const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+  let value = 0n;
+  for (const b of bytes) value = (value << 8n) | BigInt(b);
+  let out = '';
+  while (value > 0n) { out = ALPHABET[Number(value % 62n)]! + out; value /= 62n; }
+  const full = out.padStart(27, '0');
+  // another width than KSUID's 27 (a vendor's id of 24 or 29 characters): its first `width` characters, which keep the
+  // instant and the mint count (and so the order) from 11 on, or more base62 characters derived from the seed after them
+  return width <= 27 ? full.slice(0, width) : `${full}${base62From(`${seed}:ksuid`, width - 27)}`;
+}

package/src/sigv4.ts

@@ -129,9 +129,10 @@ export function signSigV4(input: { method: string; url: string; headers?: Record
 /**
  * A presigned URL signed again with a key: its date, expiry, region, service and signed headers are the URL's own
  * (X-Amz-Date, X-Amz-Expires, X-Amz-Credential's scope, X-Amz-SignedHeaders, `host` when it names none), its key and
- * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it.
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it. A
+ * signed header other than `host` (a Content-Type the URL binds) is signed with the value the request sends (`headers`).
  */
-export function presignSigV4(input: { method: string; url: string; keyId: string; secret: string; host?: string }): string {
+export function presignSigV4(input: { method: string; url: string; keyId: string; secret: string; host?: string; headers?: Record<string, string> }): string {
   const url = new URL(input.url);
   const q = url.searchParams;
   const [, dateStamp = '', region = '', service = ''] = (q.get('X-Amz-Credential') ?? '').split('/');
@@ -148,7 +149,8 @@ export function presignSigV4(input: { method: string; url: string; keyId: string
     .map(([k, v]) => `${k}=${v}`)
     .join('&');
   const names = (q.get('X-Amz-SignedHeaders') ?? 'host').toLowerCase().split(';').filter(Boolean);
-  const canonicalHeaders = names.map((n) => `${n}:${n === 'host' ? (input.host ?? url.host) : ''}\n`).join('');
+  const sent = new Headers(input.headers ?? {});
+  const canonicalHeaders = names.map((n) => `${n}:${(n === 'host' ? (input.host ?? url.host) : sent.get(n) ?? '').trim().replace(/\s+/g, ' ')}\n`).join('');
   const canonicalRequest = [input.method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, names.join(';'), 'UNSIGNED-PAYLOAD'].join('\n');
   const stringToSign = ['AWS4-HMAC-SHA256', amzDate, `${dateStamp}/${region}/${service}/aws4_request`, sha256Hex(canonicalRequest)].join('\n');
   let key: Buffer = hmac(`AWS4${input.secret}`, dateStamp);

package/src/smtp.ts

@@ -45,9 +45,10 @@ const SMTP_TIMEOUT_MS = 10_000;
 export async function sendMail(route: SmtpRoute, mail: Mail, headers: Record<string, string> = {}): Promise<void> {
   const [{ connect }, { worldEgressRefusal }] = await Promise.all([
     import('node:net'),
-    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => string | null }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string, env?: NodeJS.ProcessEnv, method?: string) => string | null }>,
   ]);
-  const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`);
+  // sending mail is a write: an external relay needs a `writes` grant
+  const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`, process.env, 'SMTP');
   if (refusal !== null) throw new Error(refusal);
   const socket = connect(route.port, route.host);
   socket.setTimeout(SMTP_TIMEOUT_MS, () => socket.destroy(new Error(`SMTP ${route.host}:${route.port}: no answer in ${SMTP_TIMEOUT_MS} ms`)));

package/src/sockets.ts

@@ -50,7 +50,9 @@ export type SocketEngine<C> = {
 
 type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }> };
 const sessions = new Map<string, Set<Open>>();
-let nextSession = 1;
+/** A World's next session number, per World (its service and root): a session's id is the World's, never the
+ *  process's, so a life replayed on a fresh World numbers its sessions as it did the first time. */
+const nextSession = new Map<string, number>();
 const keyOf = (service: string, root: string | undefined): string => `${service}\0${root ?? ''}`;
 
 /** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
@@ -101,7 +103,7 @@ export function socketUpgrade<C>(
       const engine = engines[decl.id]! as SocketEngine<unknown>;
       const pending: Open['pending'] = new Map();
       const session: SocketSession = {
-        id: nextSession++, socket: decl.id, state: {},
+        id: (() => { const n = (nextSession.get(key) ?? 0) + 1; nextSession.set(key, n); return n; })(), socket: decl.id, state: {},
         send: (frame) => { peer.send(typeof frame === 'string' || frame instanceof Uint8Array ? frame : JSON.stringify(frame)); },
         close: (code, reason) => { peer.close(code, reason); },
         expect: (key, ms) => new Promise((resolve, reject) => {
@@ -134,7 +136,10 @@ export function socketUpgrade<C>(
       // what awaited this session's replies is told it closed
       for (const [k, p] of o.pending) { clearTimeout(p.timer); p.reject(new Error('the session closed')); o.pending.delete(k); }
       // the end is written after what the session is still doing, over its own context
-      if (o.engine.close) o.queue = o.queue.then(async () => o.engine.close!(o.session, await o.context())).catch(() => {});
+      // the session is gone, so a failure has no frame to go in: it is reported, never swallowed
+      if (o.engine.close) o.queue = o.queue.then(async () => o.engine.close!(o.session, await o.context())).catch((error) => {
+        console.error(`${service}: the ${o.session.socket} socket's end was not written: ${String((error as Error)?.message ?? error)}`);
+      });
     },
   };
 }

package/src/state-system.ts

@@ -60,6 +60,9 @@ export type StateSystemAdapters = {
   perform?: PerformAction;
   refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string; scope?: string }) => Promise<unknown>;
   ingest?: (request: Request, ctx: { root?: string; secret?: string }) => Response | Promise<Response>;
+  /** Why a recorded write is the World's own and sent nowhere, or undefined when perform sends it: a unit of the pack that
+   *  declares `vendorBacked.none` beside lanes that are vendor-backed (PlanetScale's SQL wire beside its API lane). */
+  unsent?: (input: Record<string, unknown> | undefined) => string | undefined;
 };
 
 const adapters = new Map<string, StateSystemAdapters>();

package/src/storage.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { withStateLock, withStateRemoval } from './ancestry.ts';
 import { appendParentEntry, toEntry } from './log.ts';
@@ -137,7 +138,7 @@ function readJsonl<T>(path: string): T[] {
   for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {
     if (!line.trim()) continue;
     try {
-      rows.push(JSON.parse(line) as T);
+      rows.push(parseExactJson(line) as T);
     } catch (error) {
       throw new Error(`${path}:${index + 1}: invalid JSONL row: ${(error as Error).message}`);
     }
@@ -152,7 +153,7 @@ export function readJsonFile<T>(path: string): T {
   try {
     const raw = getActiveWorldStore().read(path);
     if (raw === null) throw new Error('no such file');
-    return JSON.parse(raw) as T;
+    return parseExactJson(raw) as T;
   } catch (error) {
     throw new Error(`${path}: invalid JSON: ${(error as Error).message}`);
   }
@@ -350,6 +351,8 @@ export type ScrubResult = {
  *  one of them so scrubService never demands --force for an ordinary twin. */
 const KNOWN_SERVICE_ENTRIES = new Set([
   'ancestry.json', 'history-format.json', 'views', 'origin.jsonl', 'origin-head.json',
+  'answer-count',
+  'answer-count.lock',
   'events.jsonl',
   'events.jsonl.lock',
   'event-queue.jsonl',

package/src/twin-fetch.ts

@@ -123,14 +123,15 @@ function readOnlyRefusal(error: ReadOnlyRequestError): Response {
 
 /**
  * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
- * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * request carrying the read-only marker, or an instance mounted read-only, runs with the kernel's
+ * write seam refusing its writes, and a
  * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
  * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
  * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
  */
 export function withRequestScopes<F extends (request: Request) => Promise<Response>>(
   fetch: F,
-  opts: { refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response> } = {},
+  opts: { readOnly?: boolean; refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response> } = {},
 ): F {
   const scoped = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
@@ -143,7 +144,7 @@ export function withRequestScopes<F extends (request: Request) => Promise<Respon
     // the request's W3C traceparent follows every entry the fetch writes, as through the kernel's own adapters
     // (a custom fetch never entered it, so the timeline's trace filter missed its entries)
     return runWithRequestTrace(request, async () => {
-      if (!isReadOnlyRequest(request)) return fetch(request);
+      if (!opts.readOnly && !isReadOnlyRequest(request)) return fetch(request);
       const out = await runAsReadOnlyRequest(() => fetch(request));
       if (!out.refused) return out.value;
       return opts.refuse ? await opts.refuse(request, out.refused) : readOnlyRefusal(out.refused);

package/src/vendor-call.ts

@@ -3,13 +3,27 @@
 // Google's token endpoint — and in a World that other vendor is the World's twin of it. The call is addressed as the
 // vendor's own URL and reaches that twin by the same host rules the injector routes an application by (vendor-hosts.cjs),
 // carrying the World's twins key; a vendor the World runs no twin of is refused, never reached: a twin makes no direct
-// vendor call (simulated execution is deterministic and stays inside the World). This is the one network a handler has;
-// importing this module does nothing.
+// vendor call (simulated execution is deterministic and stays inside the World). A twin this process answers itself (a
+// journey walk's companions, `setInProcessTwins`) is reached first, in process; the instance's twins otherwise. This is
+// the one network a handler has; importing this module does nothing.
 import { twinOrigins, VENDOR_HOSTS } from '../vendor-hosts.cjs';
+import type { ApplicationStandIn } from './events.ts';
 
 /** A call to a vendor the World runs no twin of. */
 export class VendorUnreachableError extends Error {
-  constructor(message: string) { super(message); this.name = 'VendorUnreachableError'; }
+  constructor(message: string, options?: ErrorOptions) { super(message, options); this.name = 'VendorUnreachableError'; }
+}
+
+/** A twin answered in this process: its fetch, as a World's server hands it a request. */
+export type InProcessTwin = (request: Request) => Response | Promise<Response>;
+let inProcessTwins: Readonly<Record<string, InProcessTwin>> = {};
+
+/** The twins this process answers itself, by routing key (a key of VENDOR_HOSTS: a journey walk's companions, over the
+ *  walk's own World), consulted before the instance's; returns those set before, which the caller puts back. */
+export function setInProcessTwins(twins: Readonly<Record<string, InProcessTwin>>): Readonly<Record<string, InProcessTwin>> {
+  const previous = inProcessTwins;
+  inProcessTwins = twins;
+  return previous;
 }
 
 /** The World's twins by vendor: the instance's env (every twin's URL, whenever this process started) over this
@@ -27,15 +41,48 @@ async function worldTwins(): Promise<Record<string, string>> {
   return { ...twinOrigins(env), ...twinOrigins(instanceEnv) };
 }
 
-/** `url`, a vendor's own address, answered by the World's twin of that vendor. */
-export async function vendorFetch(url: string | URL, init: RequestInit = {}): Promise<Response> {
-  const target = new URL(String(url));
+/** One URL answered only by a World-held application or vendor twin: the fetch's application stand-in first (its answer
+ *  is the application's; `'unreachable'` leaves no application to reach, the World's twins still reachable). */
+async function worldResponse(target: URL, init: RequestInit, standIn?: ApplicationStandIn): Promise<Response> {
+  const scripted = await standIn?.(target.toString(), init);
+  if (scripted !== undefined && scripted !== 'unreachable') {
+    // A source may answer its headers then lose its body transport. Preserve that failure until the caller reads.
+    const body = scripted.bodyError === undefined ? scripted.body : new ReadableStream<Uint8Array>({
+      start(controller) { controller.error(new TypeError(scripted.bodyError)); },
+    });
+    return new Response([204, 205, 304].includes(scripted.status) || init.method === 'HEAD' ? null : body, { status: scripted.status, headers: scripted.headers });
+  }
+  const local = Object.keys(VENDOR_HOSTS).find(v => inProcessTwins[v] !== undefined && VENDOR_HOSTS[v]!(target.hostname, target.pathname));
+  if (local !== undefined) {
+    const headers = new Headers(init.headers);
+    headers.set('x-volter-twin-original-host', target.host);
+    return inProcessTwins[local]!(new Request(target, { ...init, headers, redirect: 'manual' }));
+  }
   const twins = await worldTwins();
   const vendor = Object.keys(VENDOR_HOSTS).find((v) => twins[v] !== undefined && VENDOR_HOSTS[v]!(target.hostname, target.pathname));
-  if (vendor === undefined) throw new VendorUnreachableError(`${target.host}${target.pathname}: this World runs no twin of it, and a twin calls only the World's twins`);
-  const headers = new Headers(init.headers);
-  headers.set('x-volter-twin-original-host', target.host);
-  const key = process.env.VOLTER_TWINS_KEY;
-  if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
-  return fetch(`${twins[vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers });
+  if (vendor !== undefined) {
+    const headers = new Headers(init.headers);
+    headers.set('x-volter-twin-original-host', target.host);
+    const key = process.env.VOLTER_TWINS_KEY;
+    if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
+    return fetch(`${twins[vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
+  }
+  const { appDestination, appFetch } = await import('../app-route.cjs') as { appDestination: (url: URL) => unknown; appFetch: (url: URL, init: RequestInit) => Promise<Response> };
+  if (scripted !== 'unreachable' && appDestination(target)) return appFetch(target, { ...init, redirect: 'manual' });
+  throw new VendorUnreachableError(`${target.host}${target.pathname}: this World holds no application or vendor twin at this URL`);
+}
+
+/** A vendor URL (or the World's application), including redirects, always answered inside the World; `standIn` is the
+ *  calling fetch's application stand-in (PackFetchOptions.application), consulted at every hop. */
+export async function vendorFetch(url: string | URL, init: RequestInit = {}, standIn?: ApplicationStandIn): Promise<Response> {
+  const { followRedirects } = await import('../app-route.cjs') as {
+    followRedirects: (url: string | URL, init: RequestInit, send: (url: URL, init: RequestInit) => Promise<Response>, dropped?: string[]) => Promise<Response>;
+  };
+  try { return await followRedirects(url, init, async (target, request) => {
+    if (!['http:', 'https:'].includes(target.protocol)) throw new VendorUnreachableError(`A twin cannot fetch ${target.protocol} URLs`);
+    return worldResponse(target, request, standIn);
+  }, ['x-twins-key', 'x-volter-twin-original-host']); } catch (error) {
+    if (error instanceof VendorUnreachableError) throw error;
+    throw new VendorUnreachableError(error instanceof Error ? error.message : String(error), { cause: error });
+  }
 }

package/test-fixtures/attestation.json

@@ -0,0 +1,50 @@
+{
+  "bundle": {
+    "mediaType": "application/vnd.dev.sigstore.bundle+json;version=0.1",
+    "dsseEnvelope": {
+      "payloadType": "application/vnd.in-toto+json",
+      "payload": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLCJzdWJqZWN0IjpbeyJuYW1lIjoicGtnOm5wbS9maXh0dXJlQDEuMC4wIiwiZGlnZXN0Ijp7InNoYTUxMiI6IjZhNzkzMjU0ZjQ0YjMwODY1MDUxZTZjNWQ0ZjRiYmFlMzI3OTc0MzIwZjdhYzYwZjg0ZDEzMWY0N2I3YjQ1MGJlOGRhMmRkNGQ4YzkyNThkNWVjMWJiOWNjNDliY2QzZDlkY2NiNTIyNmY0YjM4ODkyNzQyNWZjODVkNjU0MWRlIn19XSwicHJlZGljYXRlVHlwZSI6Imh0dHBzOi8vc2xzYS5kZXYvcHJvdmVuYW5jZS92MSIsInByZWRpY2F0ZSI6e319",
+      "signatures": [
+        {
+          "keyid": "",
+          "sig": "7nKq9VXFF3a1J7rj4tFMbM6UhafUKaXXtV5yhkubs8U/SocLU7m0E0cgxdr8ixMZbwYExsX1d46kncIZ1wCjBQ=="
+        }
+      ]
+    },
+    "verificationMaterial": {
+      "x509CertificateChain": {
+        "certificates": [
+          {
+            "rawBytes": "MIIDTTCCAv+gAwIBAgIQBUiE8XK0h+xFHqyfZxbTXjAFBgMrZXAwKjEVMBMGA1UECgwMc2lnc3RvcmUuZGV2MREwDwYDVQQDDAhzaWdzdG9yZTAeFw0yNjAxMDYxNDAwMDBaFw0yNjAxMDYxNDEwMDBaMAAwKjAFBgMrZXADIQC4nHlTkS1xW0AQsB+d05CE0PzyBGyWvNGEP+EJHrgYY6OCAmMwggJfMA4GA1UdDwEB/wQEAwIAgDATBgNVHSUEDDAKBggrBgEFBQcDAzBhBgNVHREBAf8EVzBVhlNodHRwczovL2dpdGh1Yi5jb20vZml4dHVyZS9yZXBvc2l0b3J5Ly5naXRodWIvd29ya2Zsb3dzL3JlbGVhc2UueW1sQHJlZnMvaGVhZHMvbWFpbjAQBgorBgEEAYO/MAEIBAIMADBjBgorBgEEAYO/MAEJBFUMU2h0dHBzOi8vZ2l0aHViLmNvbS9maXh0dXJlL3JlcG9zaXRvcnkvLmdpdGh1Yi93b3JrZmxvd3MvcmVsZWFzZS55bWxAcmVmcy9oZWFkcy9tYWluMBAGCisGAQQBg78wAQoEAgwAMBAGCisGAQQBg78wAQsEAgwAMCMGCisGAQQBg78wAQwEFQwTaHR0cHM6Ly9naXRodWIuY29tLzAQBgorBgEEAYO/MAENBAIMADAQBgorBgEEAYO/MAEOBAIMADAQBgorBgEEAYO/MAEPBAIMADAjBgorBgEEAYO/MAEQBBUME2h0dHBzOi8vZ2l0aHViLmNvbS8wEAYKKwYBBAGDvzABEQQCDAAwIwYKKwYBBAGDvzABEgQVDBNodHRwczovL2dpdGh1Yi5jb20vMBAGCisGAQQBg78wARMEAgwAMBAGCisGAQQBg78wARQEAgwAMDsGCisGAQQBg78wARUELQwraHR0cHM6Ly9naXRodWIuY29tLy9hY3Rpb25zL3J1bnMvL2F0dGVtcHRzLzAQBgorBgEEAYO/MAEWBAIMADAQBgorBgEEAYO/MAEYBAIMADAFBgMrZXADQQAwr/lCtMpb0F+w6OzzNVHwjnQtMxTO1WN7W1J3NeIPC8mWcWASE8c41uXJflOk3cXWpV3dFRqZ2c9cjBJszjkI"
+          }
+        ]
+      },
+      "tlogEntries": [
+        {
+          "logIndex": "0",
+          "logId": {
+            "keyId": "dF/sfCyHqi/AtAHN6MyKhdQjWjwmAUydfFFJIBxj/xU="
+          },
+          "kindVersion": {
+            "kind": "dsse",
+            "version": "0.0.1"
+          },
+          "integratedTime": "1767708000",
+          "canonicalizedBody": "eyJhcGlWZXJzaW9uIjoiMC4wLjEiLCJraW5kIjoiZHNzZSIsInNwZWMiOnsiZW52ZWxvcGVIYXNoIjp7ImFsZ29yaXRobSI6InNoYTI1NiIsInZhbHVlIjoiNjEyNGVlZjYyMmQ0MDgwYTVhM2Q2NGMxNWU0NWZjODk3NTBmNzJiYWNmYjEwN2MzMTY5MzY5YTI2OGZhNGIzZSJ9LCJwYXlsb2FkSGFzaCI6eyJhbGdvcml0aG0iOiJzaGEyNTYiLCJ2YWx1ZSI6IjdhOTgyY2I1ZjczMTc5NDhiM2FlZmFlMDljYjNiYzMzNDdkMDFiNTFlNDdjMDJhZTE2ZTk1NjhiODkxMGVlNTEifSwic2lnbmF0dXJlcyI6W3sic2lnbmF0dXJlIjoiN25LcTlWWEZGM2ExSjdyajR0Rk1iTTZVaGFmVUthWFh0VjV5aGt1YnM4VS9Tb2NMVTdtMEUwY2d4ZHI4aXhNWmJ3WUV4c1gxZDQ2a25jSVoxd0NqQlE9PSIsInZlcmlmaWVyIjoiTFMwdExTMUNSVWRKVGlCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2sxSlNVUlVWRU5EUVhZclowRjNTVUpCWjBsUlFsVnBSVGhZU3pCb0szaEdTSEY1WmxwNFlsUllha0ZHUW1kTmNscFlRWGRMYWtWV1RVSk5SMEV4VlVVS1EyZDNUV015Ykc1ak0xSjJZMjFWZFZwSFZqSk5Va1YzUkhkWlJGWlJVVVJFUVdoNllWZGtlbVJIT1hsYVZFRmxSbmN3ZVU1cVFYaE5SRmw0VGtSQmR3cE5SRUpoUm5jd2VVNXFRWGhOUkZsNFRrUkZkMDFFUW1GTlFVRjNTMnBCUmtKblRYSmFXRUZFU1ZGRE5HNUliRlJyVXpGNFZ6QkJVWE5DSzJRd05VTkZDakJRZW5sQ1IzbFhkazVIUlZBclJVcEljbWRaV1RaUFEwRnRUWGRuWjBwbVRVRTBSMEV4VldSRWQwVkNMM2RSUlVGM1NVRm5SRUZVUW1kT1ZraFRWVVVLUkVSQlMwSm5aM0pDWjBWR1FsRmpSRUY2UW1oQ1owNVdTRkpGUWtGbU9FVldla0pXYUd4T2IyUklVbmRqZW05MlRESmtjR1JIYURGWmFUVnFZakl3ZGdwYWJXdzBaRWhXZVZwVE9YbGFXRUoyWXpKc01HSXpTalZNZVRWdVlWaFNiMlJYU1haa01qbDVZVEphYzJJelpIcE1NMHBzWWtkV2FHTXlWWFZsVnpGekNsRklTbXhhYmsxMllVZFdhRnBJVFhaaVYwWndZbXBCVVVKbmIzSkNaMFZGUVZsUEwwMUJSVWxDUVVsTlFVUkNha0puYjNKQ1owVkZRVmxQTDAxQlJVb0tRa1pWVFZVeWFEQmtTRUo2VDJrNGRsb3liREJoU0ZacFRHMU9kbUpUT1cxaFdHZ3daRmhLYkV3elNteGpSemw2WVZoU2RtTnVhM1pNYldSd1pFZG9NUXBaYVRrellqTktjbHB0ZUhaa00wMTJZMjFXYzFwWFJucGFVelUxWWxkNFFXTnRWbTFqZVRsdldsZEdhMk41T1hSWlYyeDFUVUpCUjBOcGMwZEJVVkZDQ21jM09IZEJVVzlGUVdkM1FVMUNRVWREYVhOSFFWRlJRbWMzT0hkQlVYTkZRV2QzUVUxRFRVZERhWE5IUVZGUlFtYzNPSGRCVVhkRlJsRjNWR0ZJVWpBS1kwaE5Oa3g1T1c1aFdGSnZaRmRKZFZreU9YUk1la0ZSUW1kdmNrSm5SVVZCV1U4dlRVRkZUa0pCU1UxQlJFRlJRbWR2Y2tKblJVVkJXVTh2VFVGRlR3cENRVWxOUVVSQlVVSm5iM0pDWjBWRlFWbFBMMDFCUlZCQ1FVbE5RVVJCYWtKbmIzSkNaMFZGUVZsUEwwMUJSVkZDUWxWTlJUSm9NR1JJUW5wUGFUaDJDbG95YkRCaFNGWnBURzFPZG1KVE9IZEZRVmxMUzNkWlFrSkJSMFIyZWtGQ1JWRlJRMFJCUVhkSmQxbExTM2RaUWtKQlIwUjJla0ZDUldkUlZrUkNUbThLWkVoU2QyTjZiM1pNTW1Sd1pFZG9NVmxwTldwaU1qQjJUVUpCUjBOcGMwZEJVVkZDWnpjNGQwRlNUVVZCWjNkQlRVSkJSME5wYzBkQlVWRkNaemM0ZHdwQlVsRkZRV2QzUVUxRWMwZERhWE5IUVZGUlFtYzNPSGRCVWxWRlRGRjNjbUZJVWpCalNFMDJUSGs1Ym1GWVVtOWtWMGwxV1RJNWRFeDVPV2haTTFKd0NtSXlOWHBNTTBveFltNU5ka3d5UmpCa1IxWjBZMGhTZWt4NlFWRkNaMjl5UW1kRlJVRlpUeTlOUVVWWFFrRkpUVUZFUVZGQ1oyOXlRbWRGUlVGWlR5OEtUVUZGV1VKQlNVMUJSRUZHUW1kTmNscFlRVVJSVVVGM2NpOXNRM1JOY0dJd1JpdDNOazk2ZWs1V1NIZHFibEYwVFhoVVR6RlhUamRYTVVvelRtVkpVQXBET0cxWFkxZEJVMFU0WXpReGRWaEtabXhQYXpOaldGZHdWak5rUmxKeFdqSmpPV05xUWtwemVtcHJTUW90TFMwdExVVk9SQ0JEUlZKVVNVWkpRMEZVUlMwdExTMHRDZz09In1dfX0=",
+          "inclusionPromise": {
+            "signedEntryTimestamp": "ak9H7xUyGle+Y9ffFmG7fcJhmuebWzMA20XrRdW8iCoauQr05gHY7SKB/Ol3Eim/PkWbeXEVh6OE8zBFhmjcDA=="
+          }
+        }
+      ]
+    }
+  },
+  "trust": {
+    "certificates": [
+      "-----BEGIN CERTIFICATE-----\nMIIBezCCAS2gAwIBAgIUaz/8CSoFR9V9lm1MgOxfV29zAfQwBQYDK2VwMCoxFTAT\nBgNVBAoMDHNpZ3N0b3JlLmRldjERMA8GA1UEAwwIc2lnc3RvcmUwIBcNMjAwMTAx\nMDAwMDAwWhgPMjEyMDAxMDEwMDAwMDBaMCoxFTATBgNVBAoMDHNpZ3N0b3JlLmRl\ndjERMA8GA1UEAwwIc2lnc3RvcmUwKjAFBgMrZXADIQDE41ebQe3wxijT90pJKpcI\ncMLr3RWwHjbTcE0wFY8MZ6NjMGEwHQYDVR0OBBYEFCCwTCsZsoFzvP8pW8nIipgg\n1APNMB8GA1UdIwQYMBaAFCCwTCsZsoFzvP8pW8nIipgg1APNMA8GA1UdEwEB/wQF\nMAMBAf8wDgYDVR0PAQH/BAQDAgAGMAUGAytlcANBAG5I7Hn72nt51DGymOMMFimq\n7UQ/RqT8zGPUcRC36HTxmW0p5GS62VbT/X9B+Hl/k+xAOMXfD1OdE0zt4N+V3AY=\n-----END CERTIFICATE-----\n"
+    ],
+    "logKeys": [
+      "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6ndE8AARgTs3biA59jhDL22PH2EgZqWnk4I5vugGtl8=\n-----END PUBLIC KEY-----\n"
+    ]
+  },
+  "otherLogKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAE8WDvbqLEaI2gSsDadEZGTtJz1L1qvL8hqLgXFR0qpg=\n-----END PUBLIC KEY-----\n"
+}