@volter/world-core 2.0.37 → 3.0.0

package/src/s3/wire.ts

@@ -0,0 +1,172 @@
+// S3'S WIRE — the XML bodies S3 answers and reads, a bucket's CORS and lifecycle documents, a delete batch, an object's
+// ETag, and a request's body kept as its bytes (docs/contributing/architecture.md, "Other wires": S3's wire is a kernel
+// library, as Redis's command core is). Every vendor that speaks S3's API speaks this wire: AWS S3 itself, Cloudflare
+// R2, and the S3-compatible stores that follow. What differs between them (where a request's account and bucket are,
+// what they refuse, what they implement) is each pack's own. Moved here from the cloudflare pack's R2 lane, which had it
+// ported from the aws pack's S3 code; a pack may import neither (B4). Importing this module does nothing.
+import { createHash } from 'node:crypto';
+
+// ── XML ──────────────────────────────────────────────────────────────────────────────────────
+
+const DECL = '<?xml version="1.0" encoding="UTF-8"?>';
+const NS = 'http://s3.amazonaws.com/doc/2006-03-01/';
+export function esc(s: string | number): string {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+/** An element and its children or text. */
+export const x = (tag: string, inner: string | number | string[]): string => `<${tag}>${Array.isArray(inner) ? inner.join('') : esc(inner)}</${tag}>`;
+export const doc = (root: string, inner: string[]): string => `${DECL}<${root} xmlns="${NS}">${inner.join('')}</${root}>`;
+export const xmlAnswer = (body: string, status = 200, headers: Record<string, string> = {}): Response => new Response(body, { status, headers: { 'content-type': 'application/xml', ...headers } });
+
+export function unesc(s: string): string {
+  return s.replace(/&(?:lt|gt|quot|apos|amp|#\d+|#x[0-9a-fA-F]+);/g, decodeEntity);
+}
+/** One XML entity, named or numeric, as its character. */
+function decodeEntity(m: string): string {
+  const named: Record<string, string> = { '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&amp;': '&' };
+  if (named[m]) return named[m]!;
+  const body = m.slice(2, -1);
+  const code = body[0] === 'x' ? Number.parseInt(body.slice(1), 16) : Number(body);
+  return Number.isInteger(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+}
+/** Every element of a tag's text in an XML body, unescaped. */
+export const allOf = (xml: string, tag: string): string[] => [...xml.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g'))].map((m) => unesc(m[1]!.trim()));
+/** The first. */
+export const oneOf = (xml: string, tag: string): string | undefined => allOf(xml, tag)[0];
+
+// ── CORS (https://developers.cloudflare.com/r2/buckets/cors/) ──────────────────────────────────
+
+export type CorsRule = { id?: string; allowedOrigins: string[]; allowedMethods: string[]; allowedHeaders: string[]; exposeHeaders: string[]; maxAgeSeconds?: number };
+
+export function parseCors(xml: string): CorsRule[] {
+  return [...xml.matchAll(/<CORSRule>([\s\S]*?)<\/CORSRule>/g)].map((m) => {
+    const b = m[1]!;
+    const id = oneOf(b, 'ID');
+    const age = oneOf(b, 'MaxAgeSeconds');
+    return { ...(id ? { id } : {}), allowedOrigins: allOf(b, 'AllowedOrigin'), allowedMethods: allOf(b, 'AllowedMethod'), allowedHeaders: allOf(b, 'AllowedHeader'), exposeHeaders: allOf(b, 'ExposeHeader'), ...(age ? { maxAgeSeconds: Number(age) } : {}) };
+  });
+}
+export function corsXml(rules: CorsRule[]): string {
+  return doc('CORSConfiguration', rules.map((r) => x('CORSRule', [
+    ...(r.id ? [x('ID', r.id)] : []), ...r.allowedOrigins.map((o) => x('AllowedOrigin', o)), ...r.allowedMethods.map((m) => x('AllowedMethod', m)),
+    ...r.allowedHeaders.map((h) => x('AllowedHeader', h)), ...r.exposeHeaders.map((h) => x('ExposeHeader', h)), ...(r.maxAgeSeconds !== undefined ? [x('MaxAgeSeconds', r.maxAgeSeconds)] : []),
+  ])));
+}
+function wildMatch(pattern: string, value: string, fold: boolean): boolean {
+  const p = fold ? pattern.toLowerCase() : pattern;
+  const v = fold ? value.toLowerCase() : value;
+  const star = p.indexOf('*');
+  if (star < 0) return p === v;
+  return v.length >= p.length - 1 && v.startsWith(p.slice(0, star)) && v.endsWith(p.slice(star + 1));
+}
+/** The first rule that allows the origin, the method and the headers a preflight asks for. */
+export function corsRuleFor(rules: CorsRule[], origin: string, method: string, requested: string[]): CorsRule | undefined {
+  return rules.find((r) => r.allowedOrigins.some((o) => wildMatch(o, origin, false))
+    && r.allowedMethods.some((m) => m === '*' || m.toUpperCase() === method.toUpperCase())
+    && requested.every((h) => r.allowedHeaders.some((a) => wildMatch(a, h, true))));
+}
+/** The Access-Control-* headers a matching rule gives an answer ("AllowedOrigins: Specifies the value for the
+ *  Access-Control-Allow-Origin header", and likewise for the methods, headers, exposed headers and max age). */
+export function corsHeaders(rule: CorsRule, origin: string, requested: string[], preflight: boolean): Record<string, string> {
+  return {
+    'access-control-allow-origin': origin,
+    'access-control-allow-methods': rule.allowedMethods.join(', '),
+    vary: 'Origin, Access-Control-Request-Headers, Access-Control-Request-Method',
+    ...(preflight && requested.length ? { 'access-control-allow-headers': requested.join(', ') } : {}),
+    ...(preflight && rule.maxAgeSeconds !== undefined ? { 'access-control-max-age': String(rule.maxAgeSeconds) } : {}),
+    ...(rule.exposeHeaders.length ? { 'access-control-expose-headers': rule.exposeHeaders.join(', ') } : {}),
+  };
+}
+export const requestedHeaders = (request: Request): string[] => (request.headers.get('access-control-request-headers') ?? '').split(',').map((h) => h.trim()).filter(Boolean);
+
+// ── lifecycle (https://developers.cloudflare.com/r2/buckets/object-lifecycles/) ──────────────────
+
+/** A rule's prefix is sent in its Filter or, in S3's older form, on the rule itself, or not at all (R2's lifecycle page
+ *  sends a transition rule with neither, for the whole bucket); it is answered as it was sent. A
+ *  transition moves an object to Infrequent Access (Object lifecycles: "transition objects to Infrequent Access storage
+ *  after 30 days", its example `Transitions: [{ Days: 30, StorageClass: "STANDARD_IA" }]`). */
+export type LifecycleRule = { id: string; enabled: boolean; prefix: string; prefixOnRule?: boolean; noPrefix?: boolean; expireDays?: number; expireDate?: string; abortMultipartDays?: number; transitions?: Array<{ days?: number; date?: string; storageClass: string }> };
+
+export function parseLifecycle(xml: string): LifecycleRule[] {
+  return [...xml.matchAll(/<Rule>([\s\S]*?)<\/Rule>/g)].map((m) => {
+    const b = m[1]!;
+    const expiration = /<Expiration>([\s\S]*?)<\/Expiration>/.exec(b)?.[1];
+    const abort = /<AbortIncompleteMultipartUpload>([\s\S]*?)<\/AbortIncompleteMultipartUpload>/.exec(b)?.[1];
+    const days = expiration ? oneOf(expiration, 'Days') : undefined;
+    const date = expiration ? oneOf(expiration, 'Date') : undefined;
+    const after = abort ? oneOf(abort, 'DaysAfterInitiation') : undefined;
+    const transitions = [...b.matchAll(/<Transition>([\s\S]*?)<\/Transition>/g)].map((x) => {
+      const d = oneOf(x[1]!, 'Days');
+      const on = oneOf(x[1]!, 'Date');
+      return { ...(d !== undefined ? { days: Number(d) } : {}), ...(on !== undefined ? { date: on } : {}), storageClass: oneOf(x[1]!, 'StorageClass') ?? '' };
+    });
+    return {
+      id: oneOf(b, 'ID') ?? '', enabled: (oneOf(b, 'Status') ?? 'Enabled') === 'Enabled', prefix: oneOf(b, 'Prefix') ?? '', ...(/<Filter>/.test(b) ? {} : /<Prefix>/.test(b) ? { prefixOnRule: true } : { noPrefix: true }),
+      ...(days ? { expireDays: Number(days) } : {}), ...(date ? { expireDate: date } : {}), ...(after ? { abortMultipartDays: Number(after) } : {}), ...(transitions.length ? { transitions } : {}),
+    };
+  });
+}
+export function lifecycleXml(rules: LifecycleRule[]): string {
+  return doc('LifecycleConfiguration', rules.map((r) => x('Rule', [
+    x('ID', r.id), ...(r.noPrefix ? [] : [r.prefixOnRule ? x('Prefix', r.prefix) : x('Filter', [x('Prefix', r.prefix)])]), x('Status', r.enabled ? 'Enabled' : 'Disabled'),
+    ...(r.transitions ?? []).map((tr) => x('Transition', [...(tr.date !== undefined ? [x('Date', tr.date)] : [x('Days', tr.days ?? 0)]), x('StorageClass', tr.storageClass)])),
+    ...(r.expireDays !== undefined ? [x('Expiration', [x('Days', r.expireDays)])] : r.expireDate !== undefined ? [x('Expiration', [x('Date', r.expireDate)])] : []),
+    ...(r.abortMultipartDays !== undefined ? [x('AbortIncompleteMultipartUpload', [x('DaysAfterInitiation', r.abortMultipartDays)])] : []),
+  ])));
+}
+
+// ── bodies ───────────────────────────────────────────────────────────────────────────────────
+
+export function parseDelete(xml: string): { keys: string[]; quiet: boolean } {
+  return { keys: [...xml.matchAll(/<Object>([\s\S]*?)<\/Object>/g)].map((m) => oneOf(m[1]!, 'Key') ?? ''), quiet: /<Quiet>\s*true\s*<\/Quiet>/i.test(xml) };
+}
+export const locationConstraintOf = (xml: string): string | undefined => oneOf(xml, 'LocationConstraint');
+
+export const md5Etag = (bytes: Uint8Array): string => `"${createHash('md5').update(bytes).digest('hex')}"`;
+
+/** A request's body as the bytes it carried. The derived dispatch reads a body as text to find its parameters, which no
+ *  binary object survives, so the lane's fetch reads the bytes first and keeps them here for the handler. */
+const BODIES = new WeakMap<Request, Uint8Array>();
+export async function withBytes(request: Request): Promise<Request> {
+  if (request.method === 'GET' || request.method === 'HEAD' || request.method === 'OPTIONS') return request;
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  const kept = new Request(request.url, { method: request.method, headers: request.headers, body: bytes });
+  BODIES.set(kept, bytes);
+  return kept;
+}
+export const bytesOf = (request: Request): Uint8Array => BODIES.get(request) ?? new Uint8Array(0);
+
+/** Concatenate exact wire bytes; no text conversion is involved in multipart assembly. */
+export function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((size, part) => size + part.byteLength, 0));
+  let offset = 0;
+  for (const part of parts) { out.set(part, offset); offset += part.byteLength; }
+  return out;
+}
+export type ChecksumAlgorithm = 'MD5' | 'SHA1' | 'SHA256' | 'CRC32' | 'CRC32C' | 'CRC64NVME';
+/** S3's base64 digest; CRC bytes are big-endian on the wire. No streaming framing is decoded here. */
+export function checksum(algorithm: ChecksumAlgorithm, bytes: Uint8Array): string {
+  if (algorithm === 'MD5' || algorithm === 'SHA1' || algorithm === 'SHA256') {
+    return createHash(algorithm.toLowerCase()).update(bytes).digest('base64');
+  }
+  if (algorithm === 'CRC64NVME') {
+    // AWS's reflected NVME polynomial: aws-checksums/tests/crc64_test.c.
+    let crc = 0xffffffffffffffffn;
+    for (const byte of bytes) {
+      crc ^= BigInt(byte);
+      for (let bit = 0; bit < 8; bit++) crc = (crc >> 1n) ^ (crc & 1n ? 0x9a6c9329ac4bc9b5n : 0n);
+    }
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, crc ^ 0xffffffffffffffffn, false);
+    return Buffer.from(out).toString('base64');
+  }
+  const polynomial = algorithm === 'CRC32C' ? 0x82f63b78 : 0xedb88320;
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (crc & 1 ? polynomial : 0);
+  }
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, (crc ^ 0xffffffff) >>> 0, false);
+  return Buffer.from(out).toString('base64');
+}

package/src/scenario.ts

@@ -42,6 +42,9 @@ export type PackScenarioAdapter<Req> = {
    *  This is ALSO where a pack refuses success-shaped handlers on stateful routes
    *  ("seed that through the vendor's API instead"). */
   validateRespond?: (respond: unknown, handler: ScenarioHandler) => string | null;
+  /** Whether the request admits a handler's answer (OpenAI's `tool_choice: 'none'` admits no tool call): a handler whose
+   *  answer it does not admit is passed over, and the next that matches answers, else the stub. Absent, every answer. */
+  admits?: (req: Req, respond: unknown) => boolean;
   /** The request's text corpus for `textPattern` extractors (packs with text requests). */
   text?: (req: Req) => string;
   /** Pack-defined extractor KINDS beyond the builtins (feature, textPattern). A pack kind with
@@ -303,6 +306,7 @@ export class ScenarioEngine<Req> {
       if (r.handler.phase !== undefined && scope.phase !== r.handler.phase) continue;
       if (r.handler.once && scope.onceFired.has(r.id)) continue;
       if (!this.matches(r.handler, req, scope)) continue;
+      if ("respond" in r.handler && this.adapter.admits && !this.adapter.admits(req, r.handler.respond)) continue;
       if (r.handler.once) scope.onceFired.add(r.id);
       if (r.handler.advancePhase !== undefined) scope.phase = r.handler.advancePhase;
       r.matches += 1;

package/src/schema-sample.ts

@@ -0,0 +1,24 @@
+// A value a schema admits, for a pack that must answer structured output without running a model (a generative pack's
+// labeled stub: the Claude API's JSON-schema output format, Gemini's responseSchema). The schema is JSON Schema, or the
+// OpenAPI subset of it some vendors take (Gemini's upper-case type names, OBJECT and STRING, read as JSON Schema's). The
+// value is the first the schema allows: an enum's first member, a const, the first of anyOf/oneOf, every property of an
+// object, one item of an array, a number's minimum (else 0), false, and for a string a labeled text (a date-time, an
+// email or a URI in its format). Importing it does nothing.
+type Row = Record<string, unknown>;
+
+export function sampleFromSchema(schema: unknown, name = 'value'): unknown {
+  const s = (schema && typeof schema === 'object' ? schema : {}) as Row;
+  if (Array.isArray(s.enum) && s.enum.length) return s.enum[0];
+  if (s.const !== undefined) return s.const;
+  for (const k of ['anyOf', 'oneOf', 'allOf']) if (Array.isArray(s[k]) && (s[k] as unknown[]).length) return sampleFromSchema((s[k] as unknown[])[0], name);
+  const raw = Array.isArray(s.type) ? (s.type as string[]).find((t) => String(t).toLowerCase() !== 'null') : s.type;
+  const type = typeof raw === 'string' ? raw.toLowerCase() : s.properties ? 'object' : s.items ? 'array' : undefined;
+  switch (type) {
+    case 'object': return Object.fromEntries(Object.entries((s.properties as Row | undefined) ?? {}).map(([k, v]) => [k, sampleFromSchema(v, k)]));
+    case 'array': return [sampleFromSchema(s.items, name)];
+    case 'integer': case 'number': return typeof s.minimum === 'number' ? s.minimum : 0;
+    case 'boolean': return false;
+    case 'null': return null;
+    default: return s.format === 'date-time' ? '2026-01-01T00:00:00Z' : s.format === 'email' ? 'twin@example.com' : s.format === 'uri' ? 'https://example.com/' : `twin-stub ${name}`;
+  }
+}

package/src/sealed-box.ts

@@ -0,0 +1,182 @@
+// SEALED BOXES — libsodium's `crypto_box_seal` opened, for a vendor whose API takes a secret encrypted to a public key it
+// published (GitHub's Actions secrets: "Secrets must be encrypted using the libsodium sealed box", with the repository's
+// public key; `gh secret set` does it). The twin holds the key pair, derived from a seed, so it can decrypt what its
+// runner must receive, as the vendor does. Everything here is deterministic: X25519 from Node, and HSalsa20, XSalsa20,
+// Poly1305 and BLAKE2b written from their specifications (the kernel takes no dependency for them: B1).
+//
+// A sealed box is `ephemeral_pk (32) || mac (16) || ciphertext`; its nonce is BLAKE2b-192(ephemeral_pk || recipient_pk),
+// its key crypto_box_beforenm(ephemeral_pk, recipient_sk) = HSalsa20(X25519(sk, epk), 0), and its body XSalsa20-Poly1305
+// (https://doc.libsodium.org/public-key_cryptography/sealed_boxes, "Algorithm details").
+// a namespace, never named imports: signing.ts reaches this from the kernel a browser client bundles, and the browser's
+// `node:crypto` polyfill has no X25519 (signing.ts, the same rule)
+import * as nodeCrypto from 'node:crypto';
+
+const PKCS8_X25519 = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const SPKI_X25519 = Buffer.from('302a300506032b656e032100', 'hex');
+
+/** A key pair from a seed: the secret key is SHA-256 of the seed (X25519 clamps it), the public key its X25519 point. */
+export function sealedBoxKeyPair(seed: string): { publicKey: Uint8Array; secretKey: Uint8Array } {
+  const secretKey = new Uint8Array(nodeCrypto.createHash('sha256').update(`sealed-box:${seed}`).digest());
+  const priv = nodeCrypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519, secretKey]), format: 'der', type: 'pkcs8' });
+  const spki = nodeCrypto.createPublicKey(priv).export({ type: 'spki', format: 'der' }) as Buffer;
+  return { publicKey: new Uint8Array(spki.subarray(spki.length - 32)), secretKey };
+}
+
+function x25519(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array {
+  const privateKey = nodeCrypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519, secretKey]), format: 'der', type: 'pkcs8' });
+  const pub = nodeCrypto.createPublicKey({ key: Buffer.concat([SPKI_X25519, publicKey]), format: 'der', type: 'spki' });
+  return new Uint8Array(nodeCrypto.diffieHellman({ privateKey, publicKey: pub }));
+}
+
+// ── Salsa20 (https://cr.yp.to/snuffle/spec.pdf) ─────────────────────────────────────────────
+
+const rotl = (v: number, c: number): number => ((v << c) | (v >>> (32 - c))) >>> 0;
+const u32 = (b: Uint8Array, i: number): number => (b[i]! | (b[i + 1]! << 8) | (b[i + 2]! << 16) | (b[i + 3]! << 24)) >>> 0;
+const SIGMA = new TextEncoder().encode('expand 32-byte k');
+
+/** The Salsa20 state for a key, a 16-byte input (nonce and counter, or HSalsa20's nonce) and the constants. */
+function state(key: Uint8Array, input: Uint8Array): Uint32Array {
+  const s = new Uint32Array(16);
+  s[0] = u32(SIGMA, 0); s[5] = u32(SIGMA, 4); s[10] = u32(SIGMA, 8); s[15] = u32(SIGMA, 12);
+  for (let i = 0; i < 4; i++) { s[1 + i] = u32(key, i * 4); s[11 + i] = u32(key, 16 + i * 4); }
+  for (let i = 0; i < 4; i++) s[6 + i] = u32(input, i * 4);
+  return s;
+}
+/** Twenty rounds (ten double rounds) over a state, in place. */
+function rounds(x: Uint32Array): void {
+  for (let i = 0; i < 10; i++) {
+    x[4] ^= rotl((x[0]! + x[12]!) >>> 0, 7); x[8] ^= rotl((x[4]! + x[0]!) >>> 0, 9); x[12] ^= rotl((x[8]! + x[4]!) >>> 0, 13); x[0] ^= rotl((x[12]! + x[8]!) >>> 0, 18);
+    x[9] ^= rotl((x[5]! + x[1]!) >>> 0, 7); x[13] ^= rotl((x[9]! + x[5]!) >>> 0, 9); x[1] ^= rotl((x[13]! + x[9]!) >>> 0, 13); x[5] ^= rotl((x[1]! + x[13]!) >>> 0, 18);
+    x[14] ^= rotl((x[10]! + x[6]!) >>> 0, 7); x[2] ^= rotl((x[14]! + x[10]!) >>> 0, 9); x[6] ^= rotl((x[2]! + x[14]!) >>> 0, 13); x[10] ^= rotl((x[6]! + x[2]!) >>> 0, 18);
+    x[3] ^= rotl((x[15]! + x[11]!) >>> 0, 7); x[7] ^= rotl((x[3]! + x[15]!) >>> 0, 9); x[11] ^= rotl((x[7]! + x[3]!) >>> 0, 13); x[15] ^= rotl((x[11]! + x[7]!) >>> 0, 18);
+    x[1] ^= rotl((x[0]! + x[3]!) >>> 0, 7); x[2] ^= rotl((x[1]! + x[0]!) >>> 0, 9); x[3] ^= rotl((x[2]! + x[1]!) >>> 0, 13); x[0] ^= rotl((x[3]! + x[2]!) >>> 0, 18);
+    x[6] ^= rotl((x[5]! + x[4]!) >>> 0, 7); x[7] ^= rotl((x[6]! + x[5]!) >>> 0, 9); x[4] ^= rotl((x[7]! + x[6]!) >>> 0, 13); x[5] ^= rotl((x[4]! + x[7]!) >>> 0, 18);
+    x[11] ^= rotl((x[10]! + x[9]!) >>> 0, 7); x[8] ^= rotl((x[11]! + x[10]!) >>> 0, 9); x[9] ^= rotl((x[8]! + x[11]!) >>> 0, 13); x[10] ^= rotl((x[9]! + x[8]!) >>> 0, 18);
+    x[12] ^= rotl((x[15]! + x[14]!) >>> 0, 7); x[13] ^= rotl((x[12]! + x[15]!) >>> 0, 9); x[14] ^= rotl((x[13]! + x[12]!) >>> 0, 13); x[15] ^= rotl((x[14]! + x[13]!) >>> 0, 18);
+  }
+}
+const put32 = (out: Uint8Array, at: number, v: number): void => { out[at] = v & 255; out[at + 1] = (v >>> 8) & 255; out[at + 2] = (v >>> 16) & 255; out[at + 3] = (v >>> 24) & 255; };
+
+/** HSalsa20: a 32-byte subkey from a key and a 16-byte nonce (the rounds' words 0, 5, 10, 15, 6, 7, 8, 9, not added). */
+function hsalsa20(key: Uint8Array, nonce16: Uint8Array): Uint8Array {
+  const x = state(key, nonce16);
+  rounds(x);
+  const out = new Uint8Array(32);
+  [0, 5, 10, 15, 6, 7, 8, 9].forEach((w, i) => put32(out, i * 4, x[w]!));
+  return out;
+}
+
+/** The XSalsa20 keystream of `length` bytes for a key and a 24-byte nonce. */
+function xsalsa20Stream(key: Uint8Array, nonce24: Uint8Array, length: number): Uint8Array {
+  const sub = hsalsa20(key, nonce24.subarray(0, 16));
+  const out = new Uint8Array(length);
+  const input = new Uint8Array(16);
+  input.set(nonce24.subarray(16, 24), 0);
+  for (let block = 0, at = 0; at < length; block++, at += 64) {
+    put32(input, 8, block >>> 0);
+    put32(input, 12, Math.floor(block / 0x100000000) >>> 0);
+    const s = state(sub, input);
+    const x = s.slice();
+    rounds(x);
+    const bytes = new Uint8Array(64);
+    for (let i = 0; i < 16; i++) put32(bytes, i * 4, (x[i]! + s[i]!) >>> 0);
+    out.set(bytes.subarray(0, Math.min(64, length - at)), at);
+  }
+  return out;
+}
+
+// ── Poly1305 (RFC 8439 section 2.5) ─────────────────────────────────────────────────────────
+
+function poly1305(key: Uint8Array, message: Uint8Array): Uint8Array {
+  const le = (b: Uint8Array): bigint => b.reduceRight((acc, v) => (acc << 8n) | BigInt(v), 0n);
+  const r = le(key.subarray(0, 16)) & 0x0ffffffc0ffffffc0ffffffc0fffffffn;
+  const s = le(key.subarray(16, 32));
+  const p = (1n << 130n) - 5n;
+  let acc = 0n;
+  for (let i = 0; i < message.length; i += 16) {
+    const chunk = message.subarray(i, i + 16);
+    const n = le(chunk) + (1n << BigInt(8 * chunk.length));
+    acc = ((acc + n) * r) % p;
+  }
+  acc = (acc + s) & ((1n << 128n) - 1n);
+  const out = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) { out[i] = Number(acc & 255n); acc >>= 8n; }
+  return out;
+}
+
+// ── BLAKE2b (RFC 7693), for the sealed box's 24-byte nonce ────────────────────────────────────
+
+const IV = [0x6a09e667f3bcc908n, 0xbb67ae8584caa73bn, 0x3c6ef372fe94f82bn, 0xa54ff53a5f1d36f1n, 0x510e527fade682d1n, 0x9b05688c2b3e6c1fn, 0x1f83d9abfb41bd6bn, 0x5be0cd19137e2179n];
+const SIGMA_B = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+  [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4], [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+  [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13], [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+  [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11], [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+  [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5], [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+];
+const M64 = (1n << 64n) - 1n;
+const rotr64 = (v: bigint, c: bigint): bigint => ((v >> c) | (v << (64n - c))) & M64;
+
+function blake2b(input: Uint8Array, outlen: number): Uint8Array {
+  const h = IV.slice();
+  h[0] ^= 0x01010000n ^ BigInt(outlen);
+  const blocks = Math.max(1, Math.ceil(input.length / 128));
+  for (let b = 0; b < blocks; b++) {
+    const chunk = new Uint8Array(128);
+    chunk.set(input.subarray(b * 128, b * 128 + 128));
+    const m: bigint[] = [];
+    for (let i = 0; i < 16; i++) { let w = 0n; for (let j = 7; j >= 0; j--) w = (w << 8n) | BigInt(chunk[i * 8 + j]!); m.push(w); }
+    const last = b === blocks - 1;
+    const t = BigInt(last ? input.length : (b + 1) * 128);
+    const v = [...h, ...IV];
+    v[12] ^= t & M64;
+    v[13] ^= t >> 64n;
+    if (last) v[14] ^= M64;
+    const g = (a: number, bb: number, c: number, d: number, x: bigint, y: bigint): void => {
+      v[a] = (v[a]! + v[bb]! + x) & M64; v[d] = rotr64(v[d]! ^ v[a]!, 32n);
+      v[c] = (v[c]! + v[d]!) & M64; v[bb] = rotr64(v[bb]! ^ v[c]!, 24n);
+      v[a] = (v[a]! + v[bb]! + y) & M64; v[d] = rotr64(v[d]! ^ v[a]!, 16n);
+      v[c] = (v[c]! + v[d]!) & M64; v[bb] = rotr64(v[bb]! ^ v[c]!, 63n);
+    };
+    for (let r = 0; r < 12; r++) {
+      const s = SIGMA_B[r % 10]!;
+      g(0, 4, 8, 12, m[s[0]!]!, m[s[1]!]!); g(1, 5, 9, 13, m[s[2]!]!, m[s[3]!]!); g(2, 6, 10, 14, m[s[4]!]!, m[s[5]!]!); g(3, 7, 11, 15, m[s[6]!]!, m[s[7]!]!);
+      g(0, 5, 10, 15, m[s[8]!]!, m[s[9]!]!); g(1, 6, 11, 12, m[s[10]!]!, m[s[11]!]!); g(2, 7, 8, 13, m[s[12]!]!, m[s[13]!]!); g(3, 4, 9, 14, m[s[14]!]!, m[s[15]!]!);
+    }
+    for (let i = 0; i < 8; i++) h[i] = h[i]! ^ v[i]! ^ v[i + 8]!;
+  }
+  const out = new Uint8Array(outlen);
+  for (let i = 0; i < outlen; i++) out[i] = Number((h[i >> 3]! >> BigInt(8 * (i & 7))) & 255n);
+  return out;
+}
+
+/** A sealed box opened with the recipient's key pair: the plaintext, or undefined when it is not one for this key (its
+ *  MAC does not hold). */
+export function sealedBoxOpen(sealed: Uint8Array, keyPair: { publicKey: Uint8Array; secretKey: Uint8Array }): Uint8Array | undefined {
+  if (sealed.length < 48) return undefined;
+  const epk = sealed.subarray(0, 32);
+  const mac = sealed.subarray(32, 48);
+  const body = sealed.subarray(48);
+  const nonce = blake2b(new Uint8Array([...epk, ...keyPair.publicKey]), 24);
+  const key = hsalsa20(x25519(keyPair.secretKey, epk), new Uint8Array(16));
+  const stream = xsalsa20Stream(key, nonce, 32 + body.length);
+  const expected = poly1305(stream.subarray(0, 32), body);
+  let diff = 0;
+  for (let i = 0; i < 16; i++) diff |= expected[i]! ^ mac[i]!;
+  if (diff !== 0) return undefined;
+  const out = new Uint8Array(body.length);
+  for (let i = 0; i < body.length; i++) out[i] = body[i]! ^ stream[32 + i]!;
+  return out;
+}
+
+/** A sealed box for a recipient's public key, as a client makes one (`gh secret set`, libsodium's `crypto_box_seal`): a
+ *  fresh ephemeral key pair from `seed` (random when none is given), then `ephemeral_pk || mac || ciphertext`. */
+export function sealedBoxSeal(message: Uint8Array, recipientPublicKey: Uint8Array, seed?: string): Uint8Array {
+  const ephemeral = sealedBoxKeyPair(seed ?? nodeCrypto.randomBytes(32).toString('hex'));
+  const nonce = blake2b(new Uint8Array([...ephemeral.publicKey, ...recipientPublicKey]), 24);
+  const key = hsalsa20(x25519(ephemeral.secretKey, recipientPublicKey), new Uint8Array(16));
+  const stream = xsalsa20Stream(key, nonce, 32 + message.length);
+  const body = new Uint8Array(message.length);
+  for (let i = 0; i < message.length; i++) body[i] = message[i]! ^ stream[32 + i]!;
+  return new Uint8Array([...ephemeral.publicKey, ...poly1305(stream.subarray(0, 32), body), ...body]);
+}

package/src/serve-http.ts

@@ -5,13 +5,17 @@
 // asynchronous on Node — Bun's synchronous bind is the special case.
 //
 // Nothing here runs at module scope, and `node:http` is reached through `process.getBuiltinModule`
-// rather than a static import: this module rides into mirror-UI client bundles through the kernel's
+// rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
 
+import type { TwinStream } from './twin-fetch.ts';
+
 export type HttpHandler = (request: Request) => Response | Promise<Response>;
 export type WebSocketPeer = { send: (data: string | Uint8Array) => unknown; close: (code?: number, reason?: string) => unknown };
 export type WebSocketUpgrade = {
   accepts: (request: Request) => boolean;
+  /** The subprotocol the server selects for this request, answered in `Sec-WebSocket-Protocol`; none when undefined. */
+  protocol?: (request: Request) => string | undefined;
   open: (peer: WebSocketPeer, request: Request) => void;
   message: (peer: WebSocketPeer, data: string | Uint8Array) => void | Promise<void>;
   close: (peer: WebSocketPeer) => void;
@@ -56,6 +60,10 @@ export const WORLD_BOOT_PATH = '/__volter/world-boot';
 export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer> {
   // Inside a World every server made through the seam answers which boot it belongs to, so the World can tell its own
   // twin from a leftover World's that holds the same port. Outside a World nothing changes.
+  // a pack's fetch carries the upgrade its sockets take (pack-fetch.ts), read before anything wraps the fetch: served on
+  // its own or in a World, its sockets answer
+  const carried = options.upgrade ?? (options.fetch as { upgrade?: WebSocketUpgrade }).upgrade;
+  if (carried) options = { ...options, upgrade: carried };
   const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
   if (worldBoot) {
     const served = options.fetch;
@@ -72,6 +80,8 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
     const server = bun.serve({ ...options, hostname, port: options.port ?? 0,
       ...(upgrade ? {
         fetch: (request: Request, server: { upgrade: (request: Request, options: { data: { request: Request } }) => boolean }) => {
+          // Bun answers the first subprotocol the client offers by itself; a header set here would be a second one, which a
+          // client refuses (measured, Bun 1.2.20: Node's client reads `realtime`; with the header added, a duplicate)
           if (request.headers.get('upgrade')?.toLowerCase() === 'websocket' && upgrade.accepts(request) && server.upgrade(request, { data: { request } })) return undefined;
           return options.fetch(request);
         },
@@ -94,6 +104,22 @@ type NodeStream = typeof import('node:stream');
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export function nodeBuiltin<T = unknown>(name: string): T { return builtin<T>(name); }
+
+/** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
+ *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
+ *  `net` reached at call time, never imported. */
+export async function serveStream(options: { port?: number; hostname?: string; stream: TwinStream }): Promise<{ port: number; stop: () => void }> {
+  const net = builtin<typeof import('node:net')>('node:net');
+  const server = net.createServer((socket) => {
+    const conn = options.stream({ write: (bytes) => { socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '127.0.0.1');
+    socket.on('data', (chunk: Buffer) => conn.data(new Uint8Array(chunk)));
+    socket.on('close', () => conn.close());
+    socket.on('error', () => conn.close());
+  });
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname ?? '127.0.0.1', () => resolve()); });
+  const address = server.address();
+  return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop: () => { server.close(); } };
+}
 function builtin<T>(name: string): T {
   const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
   if (typeof get !== 'function') throw new Error(`serveHttp: this runtime is neither Bun nor a Node with process.getBuiltinModule (Node 22.3+)`);
@@ -276,10 +302,12 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
   let socketServer: import('ws').WebSocketServer | undefined;
   if (options.upgrade) {
     const { WebSocketServer } = await import('ws');
-    socketServer = new WebSocketServer({ noServer: true });
     const upgrade = options.upgrade;
+    const requestOf = (req: import('node:http').IncomingMessage): Request => new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) });
+    // the subprotocol the socket selects, answered as Bun's branch answers it
+    socketServer = new WebSocketServer({ noServer: true, handleProtocols: (_offered, req) => upgrade.protocol?.(requestOf(req)) ?? false });
     server.on('upgrade', (req, socket, head) => {
-      const request = new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) });
+      const request = requestOf(req);
       if (!upgrade.accepts(request)) { socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); return; }
       socketServer!.handleUpgrade(req, socket, head, (peer) => {
         peer.on('message', (data, binary) => { const bytes = Array.isArray(data) ? Buffer.concat(data) : data instanceof ArrayBuffer ? new Uint8Array(data) : data; Promise.resolve(upgrade.message(peer, binary ? new Uint8Array(bytes) : Buffer.from(bytes).toString())).catch(() => peer.close(1011, 'handler failed')); });

package/src/serve.ts

@@ -20,6 +20,7 @@ import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, pr
 import type { ActionProjection, TwinAction, TwinActionPrecondition } from './actions.ts';
 import { observeWorldPaths, worldPaths } from './storage.ts';
 import { getActiveWorldStore } from './world-store.ts';
+import { getActiveBlobStore } from './blob-store.ts';
 import { parseTraceparent } from './trace-context.ts';
 
 // ── the request journal: the INSPECT half of the read path ─────────────────────────────────────
@@ -80,6 +81,10 @@ export type TwinCredentialShape = {
  *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
  *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
 export const CALLER_HEADER = 'x-volter-caller';
+/** The caller as it travels in CALLER_HEADER: percent-encoded, since a key's name is a person's words (`preview pr-8 ·
+ *  org token ci`) and a header carries bytes only. `callerFromHeader` reads it back; a value it cannot decode stands. */
+export const callerForHeader = (caller: string): string => encodeURIComponent(caller);
+export const callerFromHeader = (value: string): string => { try { return decodeURIComponent(value); } catch { return value; } };
 
 export type TwinRequestJournalEntry = {
   at?: string;
@@ -297,9 +302,9 @@ export function journalTwinRequest(service: string, entry: TwinRequestJournalEnt
 // factory's closure. They are recoverable without touching a single pack, because handling a
 // request makes the pack call the kernel, and every kernel state path funnels through
 // `worldPaths(service, root)` (storage.ts). Observing the FIRST such call a server makes is the
-// twin naming itself: `datadog` under `/tmp/world/data/datadog`. It is cached per server, so only
+// twin naming itself: `deepgram` under `/tmp/world/data/deepgram`. It is cached per server, so only
 // the first request pays for it. A server whose first request touches no state falls back to the
-// call site (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>`) and the process's `--root`
+// call site (a catalog checkout or `@volter/twin-<vendor>`) and the process's `--root`
 // argument, which is how the world runtime launches every twin.
 
 export const TWIN_JOURNAL_IDENTITY = Symbol.for('volter.twin.requestJournal.identity');
@@ -310,12 +315,9 @@ export type TwinJournalIdentity = { service: string; root?: string };
 /** One capture slot per in-flight request, so two twins co-located in ONE process (the shared
  *  host) can never read each other's identity off a racing sibling's first request.
  *
- *  LAZY ON PURPOSE, and this is load-bearing rather than style. Mirror-UI packs import their own
- *  server module into the BROWSER bundle and rely on Bun tree-shaking the server-only half away
- *  (see any `*-mirror-ui.ts` header). A module-scope `new AsyncLocalStorage()` is a side effect,
- *  so it survives tree-shaking and lands in the client — where `node:async_hooks` does not
- *  resolve, `new` throws at bundle evaluation, and the React app never mounts. That took out
- *  every mirror UI in the estate at once. Nothing in this module may run at module scope. */
+ *  LAZY ON PURPOSE: kernel modules ride into browser bundles (kernel imports are free of side effects), and a module-scope
+ *  `new AsyncLocalStorage()` survives tree-shaking into a client, where `node:async_hooks` does not resolve and `new`
+ *  throws at bundle evaluation. Nothing in this module may run at module scope. */
 let identityCapture: AsyncLocalStorage<{ identity?: TwinJournalIdentity }> | undefined;
 
 function identitySlot(): AsyncLocalStorage<{ identity?: TwinJournalIdentity }> {
@@ -344,7 +346,7 @@ const INFRA_PACKAGES = new Set(['world-runtime', 'world-tooling', 'world-attach'
 
 export function vendorFromStack(stack: string | undefined): string | undefined {
   if (!stack) return undefined;
-  const pattern = /(?:packages[\\/]twin[\\/]|@volter[\\/]twin-)([A-Za-z0-9_-]+)/g;
+  const pattern = /(?:twin-packs-p[23][\\/]|@volter[\\/]twin-)([A-Za-z0-9_-]+)/g;
   for (const match of stack.matchAll(pattern)) {
     const name = match[1]!;
     if (!INFRA_PACKAGES.has(name)) return name;
@@ -365,7 +367,7 @@ export function vendorFromStack(stack: string | undefined): string | undefined {
  * service is an argument rather than a fact about the pack.
  */
 export function installTwinRequestJournal(): boolean {
-  // a browser bundle (a mirror UI carrying the kernel): nothing to wrap, nothing to touch
+  // a browser bundle carrying the kernel: nothing to wrap, nothing to touch
   if (typeof window !== 'undefined' || typeof document !== 'undefined') return false;
   const bun = (globalThis as { Bun?: { serve?: unknown } }).Bun;
   const original = bun && typeof bun.serve === 'function' ? bun.serve as (...args: unknown[]) => { port?: number } : undefined;
@@ -402,7 +404,7 @@ function journalingFetch(config: Record<string | symbol, unknown> & { fetch: (..
     const inner = config.fetch as (this: unknown, request: Request, server: unknown) => unknown;
     const journaling = async function (this: unknown, request: Request, server: unknown) {
       // who made it is read here and goes no further: no twin's handler (a tunnel's, a proxy's) hands it on
-      const caller = request.headers.get(CALLER_HEADER) ?? undefined;
+      const sent = request.headers.get(CALLER_HEADER); const caller = sent === null ? undefined : callerFromHeader(sent);
       if (caller !== undefined) { const headers = new Headers(request.headers); headers.delete(CALLER_HEADER); request = new Request(request, { headers }); }
       // The World's own boot probe (serve-http.ts, WORLD_BOOT_PATH) is not the app's traffic: never journaled.
       if (!twinRequestJournalEnabled() || new URL(request.url).pathname === WORLD_BOOT_PATH) return inner.call(this, request, server);
@@ -506,6 +508,48 @@ export type AtomicTwinWriteDecision<T> =
   | { kind: 'skip'; value: T }
   | { kind: 'write'; value: T; write: TwinWriteInput };
 
+/** The largest string a write's recorded request keeps in the log itself. */
+const INPUT_INLINE_MAX = 64 * 1024;
+/**
+ * A write's recorded request, with each string longer than INPUT_INLINE_MAX (an attached file's base64: an npm
+ * publish's tarball) kept once as a content-addressed blob under the service's state and named in its place as
+ * `{ $blob, bytes }`. The request stays whole and deterministic, and a body several writes record is kept once, never
+ * copied into the log (docs/contributing/architecture.md, "The log keeps a large request once"). `recordedInput` reads
+ * it back whole.
+ */
+async function offloadInput(service: string, input: unknown, root: string | undefined): Promise<unknown> {
+  if (typeof input === 'string') {
+    if (input.length <= INPUT_INLINE_MAX) return input;
+    // hashed as it is (UTF-8), and encoded only when its blob is new: each write of a request records the same body
+    const key = join(worldPaths(service, root).dir, 'inputs', createHash('sha256').update(input, 'utf8').digest('hex'));
+    const blobs = getActiveBlobStore();
+    if (!(await blobs.exists(key))) await blobs.put(key, Buffer.from(input, 'utf8'));
+    return { $blob: key, bytes: Buffer.byteLength(input, 'utf8') };
+  }
+  if (Array.isArray(input)) return Promise.all(input.map((v) => offloadInput(service, v, root)));
+  if (input && typeof input === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(input)) out[k] = await offloadInput(service, v, root);
+    return out;
+  }
+  return input;
+}
+/** A recorded request as it was sent: each string the log keeps as a blob, read back. */
+export async function recordedInput(input: unknown): Promise<unknown> {
+  if (Array.isArray(input)) return Promise.all(input.map(recordedInput));
+  if (input && typeof input === 'object') {
+    const ref = input as { $blob?: unknown; bytes?: unknown };
+    if (typeof ref.$blob === 'string' && typeof ref.bytes === 'number' && Object.keys(input).length === 2) {
+      const bytes = await getActiveBlobStore().get(ref.$blob);
+      return bytes ? new TextDecoder().decode(bytes) : undefined;
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(input)) out[k] = await recordedInput(v);
+    return out;
+  }
+  return input;
+}
+
 function actionForTwinWrite(service: string, write: TwinWriteInput): TwinAction {
   const occurredAt = write.occurredAt ?? new Date().toISOString();
   // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
@@ -609,7 +653,7 @@ export async function applyTwinWrite(
   write: TwinWriteInput,
   root?: string,
 ): Promise<{ result: TwinWriteResult; resource: TwinResource }> {
-  const action = actionForTwinWrite(service, write);
+  const action = actionForTwinWrite(service, write.input === undefined ? write : { ...write, input: await offloadInput(service, write.input, root) as TwinWriteInput['input'] });
   // A LOCAL VENDOR WRITE IS AN OCCURRENCE. Two calls are two actions, even byte-identical in the
   // same instant, and the ordinal in the action id says which occurrence this is. The kernel used
   // to derive identity from (content + occurredAt millisecond) and drop a repeat as `replayed`,
@@ -617,8 +661,8 @@ export async function applyTwinWrite(
   // under a pinned world clock, where every write in a world shares one instant. That default cost
   // github, slack and jira live defects while the recipe told each pack to defend itself with a
   // per-write ordinal and a fifth of the catalog opted out via `uniqueness`. A default every pack
-  // must remember to defend against is not a default. See docs/contributing/adding-a-twin.md
-  // #5-build-on-the-shared-kernel--dont-reinvent, "A local write is an occurrence".
+  // must remember to defend against is not a default. See docs/contributing/architecture.md,
+  // "The state kernel", "A local write is an occurrence".
   //
   // AT-MOST-ONCE is opt in, by KEY: `idempotencyKey` makes the id a function of the caller's own
   // request identity, so a re-issue collapses onto the first and answers `replayed`. Content can