@volter/world-core 3.0.38 → 3.0.39

package/src/redis/lua-libs.ts

@@ -0,0 +1,62 @@
+// Redis's Lua JSON/MessagePack runtime libraries. Values only; no state or vendor names.
+// https://redis.io/docs/latest/develop/programmability/lua-api/ (cjson, cmsgpack, bit)
+import { LuaTable, LuaError, LUA_NULL, luaPattern, numberToLuaString, luaTypeName, type LuaValue, type LuaHost } from './lua.ts';
+const bytes = (s: string) => Uint8Array.from(s, (c) => c.charCodeAt(0));
+const text = (b: Uint8Array) => Array.from(b, (v) => String.fromCharCode(v)).join('');
+const objectTable = (v: any): LuaTable => { const t = new LuaTable(); for (const [k, x] of Object.entries(v)) t.set(k, from(x)); return t; };
+const from = (v: any): LuaValue => v === null ? LUA_NULL : Array.isArray(v) ? LuaTable.fromArray(v.map(from)) : typeof v === 'object' ? objectTable(v) : v;
+const to = (v: LuaValue): any => v === LUA_NULL || v === null ? null : v instanceof LuaTable ? v.length > 0 ? v.toArray().map(to) : Object.fromEntries([...v.map.entries()].map(([k, x]) => [String(k), to(x)])) : v;
+export function unpackMessage(s: string): LuaValue {
+  const b = bytes(s), d = new DataView(b.buffer); let i = 0;
+  const n = (width: number, signed = false): number => { let v: number; if (i + width > b.length) throw new LuaError('Bad data format in input.'); if (width === 1) v = signed ? d.getInt8(i) : d.getUint8(i); else if (width === 2) v = signed ? d.getInt16(i) : d.getUint16(i); else if (width === 4) v = signed ? d.getInt32(i) : d.getUint32(i); else v = Number(signed ? d.getBigInt64(i) : d.getBigUint64(i)); i += width; return v; };
+  const string = (len: number) => { const out = text(b.subarray(i, i + len)); i += len; if (i > b.length) throw new LuaError('Bad data format in input.'); return out; };
+  const array = (len: number) => LuaTable.fromArray(Array.from({ length: len }, read));
+  const map = (len: number) => { const t = new LuaTable(); for (let j = 0; j < len; j++) t.set(read(), read()); return t; };
+  function read(): LuaValue {
+    const c = n(1); if (c < 128) return c; if (c >= 224) return c - 256;
+    if ((c & 0xe0) === 0xa0) return string(c & 31); if ((c & 0xf0) === 0x90) return array(c & 15); if ((c & 0xf0) === 0x80) return map(c & 15);
+    switch (c) {
+      case 0xc0: return null; case 0xc2: return false; case 0xc3: return true;
+      case 0xc4: case 0xd9: return string(n(1)); case 0xc5: case 0xda: return string(n(2)); case 0xc6: case 0xdb: return string(n(4));
+      case 0xcc: return n(1); case 0xcd: return n(2); case 0xce: return n(4); case 0xcf: return n(8);
+      case 0xd0: return n(1, true); case 0xd1: return n(2, true); case 0xd2: return n(4, true); case 0xd3: return n(8, true);
+      case 0xca: { const v = d.getFloat32(i); i += 4; return v; } case 0xcb: { const v = d.getFloat64(i); i += 8; return v; }
+      case 0xdc: return array(n(2)); case 0xdd: return array(n(4)); case 0xde: return map(n(2)); case 0xdf: return map(n(4));
+      default: throw new LuaError('Bad data format in input.');
+    }
+  }
+  const value = read(); if (i !== b.length) throw new LuaError('Extra bytes in input.'); return value;
+}
+export function packMessage(value: LuaValue): string {
+  const out: number[] = [];
+  const len = (tag: number, size: number, n: number) => { out.push(tag); for (let j = size - 1; j >= 0; j--) out.push(Math.floor(n / 2 ** (j * 8)) & 255); };
+  const put = (v: LuaValue): void => {
+    if (v === null || v === LUA_NULL) { out.push(0xc0); return; } if (typeof v === 'boolean') { out.push(v ? 0xc3 : 0xc2); return; }
+    if (typeof v === 'number') { if (Number.isInteger(v) && v >= 0 && v < 128 || v >= -32 && v < 0 && Number.isInteger(v)) out.push(v & 255); else { const b = new Uint8Array(8); new DataView(b.buffer).setFloat64(0, v); out.push(0xcb, ...b); } return; }
+    if (typeof v === 'string') { if (v.length < 32) out.push(0xa0 | v.length); else len(v.length < 256 ? 0xd9 : 0xda, v.length < 256 ? 1 : 2, v.length); out.push(...bytes(v)); return; }
+    if (!(v instanceof LuaTable)) throw new LuaError('Unsupported type');
+    if (v.length > 0) { const a = v.toArray(); if (a.length < 16) out.push(0x90 | a.length); else len(0xdc, 2, a.length); a.forEach(put); }
+    else { if (v.map.size < 16) out.push(0x80 | v.map.size); else len(0xde, 2, v.map.size); for (const [k, x] of v.map) { put(k as LuaValue); put(x); } }
+  };
+  put(value); return text(Uint8Array.from(out));
+}
+export const standardLuaLibraries: NonNullable<LuaHost['extend']> = ({ get, set, commandApi }) => {
+  // Lua 5.1 string.match is a selected script runtime capability, not a base-library change.
+  // source: https://www.lua.org/manual/5.1/manual.html "Returns the captures from the pattern"
+  const string = get('string') as LuaTable;
+  string.set('match', (a) => {
+    const str = (i: number): string => { const v = a[i] ?? null; if (typeof v === 'string') return v; if (typeof v === 'number') return numberToLuaString(v); throw new LuaError(`bad argument #${i + 1} to 'string.match' (string expected, got ${luaTypeName(v)})`); };
+    const value = str(0), pattern = str(1);
+    const start = a[2] === undefined ? 0 : Math.max(0, Number(a[2]) - 1);
+    const match = new RegExp(luaPattern(pattern)).exec(value.slice(start));
+    return match ? match.length > 1 ? match.slice(1) : [match[0]] : [null];
+  });
+  set('redis', commandApi); set('server', commandApi);
+  const json = new LuaTable(); json.set('null', LUA_NULL);
+  json.set('encode', (a) => [text(new TextEncoder().encode(JSON.stringify(to(a[0] ?? null))))]);
+  json.set('decode', (a) => { try { return [from(JSON.parse(new TextDecoder().decode(bytes(String(a[0])))))]; } catch { throw new LuaError('Expected value but found invalid token'); } }); set('cjson', json);
+  const msg = new LuaTable(); msg.set('unpack', (a) => [unpackMessage(String(a[0]))]); msg.set('pack', (a) => [packMessage(a[0] ?? null)]); set('cmsgpack', msg);
+  const bit = new LuaTable(); const ns = (a: LuaValue[]) => a.map(Number);
+  bit.set('band', (a) => [ns(a).reduce((x, y) => x & y, -1)]); bit.set('bor', (a) => [ns(a).reduce((x, y) => x | y, 0)]); bit.set('bxor', (a) => [ns(a).reduce((x, y) => x ^ y, 0)]);
+  bit.set('bnot', (a) => [~Number(a[0])]); bit.set('lshift', (a) => [Number(a[0]) << Number(a[1])]); bit.set('rshift', (a) => [Number(a[0]) >>> Number(a[1])]); bit.set('arshift', (a) => [Number(a[0]) >> Number(a[1])]); set('bit', bit);
+};

package/src/redis/lua.ts

@@ -559,6 +559,26 @@ class Scope {
 const BREAK = Symbol('lua-break');
 type Signal = typeof BREAK | { ret: LuaValue[] } | null;
 
+// Lua pattern subset used by command-language scripts; unsupported balanced/frontier patterns refuse explicitly.
+export function luaPattern(pattern: string): string {
+  const classes: Record<string, string> = { a: 'A-Za-z', d: '0-9', l: 'a-z', u: 'A-Z', w: 'A-Za-z0-9', s: '\\s', x: 'A-Fa-f0-9', p: '!-/:-@[-`{-~', c: '\\x00-\\x1f\\x7f', z: '\\x00' };
+  let out = '', inClass = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]!;
+    if (c === '%') {
+      const next = pattern[++i]!; if (next === 'b' || next === 'f') throw new LuaError('unsupported Lua balanced/frontier pattern');
+      if (classes[next.toLowerCase()]) { const content = classes[next.toLowerCase()]!; out += inClass ? content : `[${next === next.toUpperCase() ? '^' : ''}${content}]`; }
+      else if (/\d/.test(next)) out += `\\${next}`;
+      else out += next.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+    } else if (c === '[') { inClass = true; out += c; }
+    else if (c === ']') { inClass = false; out += c; }
+    else if (!inClass && c === '-') out += '*?';
+    else if ('\\{}|'.includes(c)) out += `\\${c}`;
+    else out += c;
+  }
+  return out;
+}
+
 export function luaTruthy(v: LuaValue): boolean {
   return v !== null && v !== false;
 }

package/src/redis/member-storage.ts

@@ -0,0 +1,58 @@
+// Redis's collection layout over the World tree. First need: the managed Redis queue's growing events stream.
+// Key metadata and each hash field/set member/sorted-set member/stream entry are separate subjects.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite } from '../serve.ts';
+import { projectResources } from '../actions.ts';
+import { treeStamp, treeChangesSince } from '../log.ts';
+import { getActiveWorldStore } from '../world-store.ts';
+import type { RedisContext, KeyRow, KeyspaceImage, KeySpace } from './engine.ts';
+
+const scope = (c: RedisContext) => c.database === undefined ? '' : `db:${c.database}:`;
+const collections = new Set(['hash', 'set', 'zset', 'stream', 'list']);
+const held = new WeakMap<object, Map<string, { stamp: string; subjects: Map<string, any>; image: KeyspaceImage }>>();
+const members = (r: KeyRow | null): Map<string, unknown> => !r || !collections.has(r.kind) ? new Map() : new Map((r.v as any[]).map((x, i) => r.kind === 'list' ? [String(i), x] : r.kind === 'set' ? [x, x] : [x[0], x[1]]));
+const memberId = (c: RedisContext, name: string, field: string) => `${scope(c)}member:${createHash('sha256').update(JSON.stringify([name, field])).digest('hex')}`;
+
+export const memberStorage = {
+  image(ctx: RedisContext): KeyspaceImage {
+    const cache = held.get(getActiveWorldStore()) ?? new Map(); held.set(getActiveWorldStore(), cache);
+    const key = `${ctx.service}\0${ctx.root ?? ''}\0${scope(ctx)}`;
+    let h = cache.get(key);
+    const stamp = treeStamp(ctx.service, ctx.root);
+    if (h?.stamp === stamp) return h.image;
+    const delta = h && treeChangesSince(ctx.service, ctx.root, h.stamp);
+    if (!h || !delta || delta.removed.length) h = { stamp, subjects: new Map(), image: { rows: new Map(), scripts: new Map(), revs: new Map() } };
+    for (const r of delta && !delta.removed.length ? delta.changed : projectResources(ctx.service, ctx.root)) h.subjects.set(r.id, r);
+    // Reconstruct only keys affected by the tree delta, not every member on every read.
+    const affected = new Set<string>();
+    const changed = delta && !delta.removed.length ? delta.changed : [...h.subjects.values()];
+    for (const r of changed) {
+      if (!r.id.startsWith(scope(ctx))) continue;
+      if (r.type === 'key') affected.add(r.name);
+      if (r.type === 'member') affected.add(r.key);
+      if (r.type === 'script') { if (r.gone) h.image.scripts.delete(r.sha); else h.image.scripts.set(r.sha, r.body); }
+    }
+    for (const name of affected) {
+      const meta = h.subjects.get(`${scope(ctx)}key:${name}`);
+      if (!meta) continue;
+      h.image.revs.set(name, meta._rev ?? 0);
+      if (meta.gone) { h.image.rows.delete(name); continue; }
+      const v = collections.has(meta.kind) ? [...h.subjects.values()].filter((r) => r.type === 'member' && r.id.startsWith(scope(ctx)) && r.key === name && r.gone !== true).sort((a, b) => meta.kind === 'list' ? Number(a.field) - Number(b.field) : 0).map((r) => meta.kind === 'list' ? r.value : meta.kind === 'set' ? r.field : [r.field, r.value]) : meta.v;
+      h.image.rows.set(name, { name, kind: meta.kind, v, pexpireAt: meta.pexpire_at == null ? null : String(meta.pexpire_at), lastId: meta.last_id, _rev: meta._rev });
+    }
+    h.stamp = stamp; cache.set(key, h); return h.image;
+  },
+  async flush(space: KeySpace): Promise<void> {
+    const ctx = space.ctx;
+    const write = async (type: string, id: string, operation: string, fields: any) => applyTwinWrite(ctx.service, { operation, subjectType: type, subjectId: id, fields, occurredAt: ctx.occurredAt, actor: { kind: 'agent' } }, ctx.root);
+    for (const { name, row, operation } of space.pendingWrites()) {
+      const before = members(space.image.rows.get(name) ?? null), after = members(row);
+      for (const field of new Set([...before.keys(), ...after.keys()])) {
+        if (before.has(field) && after.has(field) && JSON.stringify(before.get(field)) === JSON.stringify(after.get(field))) continue;
+        await write('member', memberId(ctx, name, field), operation, { key: name, field, value: after.get(field) ?? null, gone: !after.has(field) });
+      }
+      await write('key', `${scope(ctx)}key:${name}`, operation, { name, kind: row?.kind ?? 'string', v: row && !collections.has(row.kind) ? row.v : null, pexpire_at: row?.pexpireAt ?? null, last_id: row?.lastId ?? '', gone: row === null, _rev: space.nextRev(name) });
+    }
+    for (const { sha, body, operation } of space.pendingScriptWrites()) await write('script', `${scope(ctx)}script:${sha}`, operation, { sha, body: body ?? '', gone: body === null });
+  },
+};

package/src/redis/resp2.ts

@@ -0,0 +1,25 @@
+// A reply as RESP2 writes it (https://redis.io/docs/latest/develop/reference/protocol-spec/): a status as a simple string,
+// an error as a simple error, an integer as an integer, a string as a bulk string (its length in bytes), a null as the
+// null bulk string, an array as an array of its elements' replies. RESP2 has no float or double: a number that is not an
+// integer is its bulk string, as Redis sends INCRBYFLOAT's. "Simple strings never contain carriage return ( \r ) or line
+// feed ( \n ) characters" (the page), and an error is a simple string's form: Redis writes a status's text with each CR
+// and LF mapped to a space (script_lua.c, `sdsmapchars(ok,"\r\n","  ",2)` before `addReplyStatusLength`), and an
+// error's with the CRs and LFs at its ends trimmed and each one left inside mapped to a space (networking.c,
+// `addReplyErrorFormatInternal`: `sdstrim(s, "\r\n")`, then `sdsmapchars(s, "\r\n", "  ",  2)`), so a message holding
+// one never ends the reply early. Source: https://raw.githubusercontent.com/redis/redis/7.4.0/src/networking.c and
+// https://raw.githubusercontent.com/redis/redis/7.4.0/src/script_lua.c.
+// Shared by every wire that answers a Redis reply as RESP2 bytes.
+import { RedisInteger, RedisStatus, type RedisValue } from './engine.ts';
+
+const spaced = (text: string): string => text.replace(/[\r\n]/g, ' ');
+const trimmed = (text: string): string => text.replace(/^[\r\n]+|[\r\n]+$/g, '');
+
+export function resp2(value: RedisValue | { error: string }): string {
+  if (value instanceof RedisInteger) return `:${value.integer}\r\n`;
+  if (value === null) return '$-1\r\n';
+  if (value instanceof RedisStatus) return `+${spaced(value.value)}\r\n`;
+  if (Array.isArray(value)) return `*${value.length}\r\n${value.map((v) => resp2(v)).join('')}`;
+  if (typeof value === 'number') return Number.isInteger(value) ? `:${value}\r\n` : resp2(String(value));
+  if (typeof value === 'string') return `$${new TextEncoder().encode(value).length}\r\n${value}\r\n`;
+  return `-${spaced(trimmed(value.error))}\r\n`;
+}

package/src/redis/stream.ts

@@ -0,0 +1,102 @@
+// Connection-local Redis request/reply machinery. The pack supplies its dialect and executes through its own context.
+// https://redis.io/docs/latest/develop/reference/protocol-spec/; commands AUTH, CLIENT, MULTI, EXEC, BZPOPMIN.
+import type { TwinStream, TwinStreamSink } from '../twin-fetch.ts';
+import { RedisStatus, commandInteger, commandShapeError, globMatch, type RedisDialect, type RunItem } from './engine.ts';
+import { binaryBytes, binaryText, inlineCommand, readResp, respReply } from './frames.ts';
+export type RedisStreamOptions = {
+  dialect: RedisDialect; version: string; password?: string; databases: number;
+  run(commands: string[][], database: string): Promise<{ items: RunItem[]; wrote: boolean; instant?: number }>;
+};
+export function createRedisStream(options: RedisStreamOptions): TwinStream {
+  type Session = { id: number; name: string; lib: Record<string, string>; database: string; authenticated: boolean; queue: string[][] | null; dirty: boolean; subscriptions: Set<string>; patterns: Set<string>; sink: TwinStreamSink; closed: boolean; pump?: () => Promise<void>; blocked?: { command: string[]; deadline: number; timer?: ReturnType<typeof setTimeout> } };
+  const sessions = new Set<Session>(); let nextId = 0, commandCount = 0; let serial: Promise<any> = Promise.resolve();
+  const ordered = <T>(f: () => Promise<T>): Promise<T> => { const p = serial.then(f); serial = p.catch(() => {}); return p; };
+  const error = (message: string) => ({ error: message }); const ok = new RedisStatus('OK');
+  const answer = (s: Session, v: any) => { if (!s.closed) s.sink.write(binaryBytes(respReply(v))); };
+  const close = (s: Session) => { s.closed = true; if (s.blocked?.timer) clearTimeout(s.blocked.timer); sessions.delete(s); };
+  const unblock = (s: Session, v: any) => { if (s.blocked?.timer) clearTimeout(s.blocked.timer); s.blocked = undefined; answer(s, v); queueMicrotask(() => { void s.pump?.(); }); };
+  const blockRun = async (s: Session, argv: string[]): Promise<any> => {
+    if (argv[0]!.toUpperCase() === 'BZPOPMIN') {
+      for (const key of argv.slice(1, -1)) { const res = (await options.run([['ZPOPMIN', key]], s.database)).items[0]!; if ('error' in res) return res; if (Array.isArray(res.result) && res.result.length) return [key, ...res.result]; } return null;
+    }
+    throw new Error('the blocking command has no executor');
+  };
+  const wake = async () => { for (const s of sessions) if (s.blocked) { const v = await blockRun(s, s.blocked.command); if (v !== null) unblock(s, v); } };
+  const command = async (s: Session, argv: string[], executing = false): Promise<void> => {
+    if (!argv.length || s.closed) return;
+    commandCount++;
+    const cmd = argv[0]!.toUpperCase(), a = argv.slice(1);
+    const shape = commandShapeError(argv, options.dialect); if (shape) { if (s.queue) s.dirty = true; answer(s, error(shape)); return; }
+    if (!executing && !s.authenticated && !['AUTH', 'QUIT'].includes(cmd)) { answer(s, error('NOAUTH Authentication required.')); return; }
+    if (!executing && s.subscriptions.size + s.patterns.size > 0 && !['SUBSCRIBE', 'PSUBSCRIBE', 'UNSUBSCRIBE', 'PUNSUBSCRIBE', 'PING', 'QUIT'].includes(cmd)) { answer(s, error(`ERR Can't execute '${cmd.toLowerCase()}': only (P|S)SUBSCRIBE / (P|S)UNSUBSCRIBE / PING / QUIT / RESET are allowed in this context`)); return; }
+    if (s.queue && !['EXEC', 'MULTI', 'DISCARD', 'QUIT'].includes(cmd)) { s.queue.push(argv); answer(s, new RedisStatus('QUEUED')); return; }
+    switch (cmd) {
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/acl.c "Only two or three argument forms are allowed."
+      case 'AUTH': {
+        if (a.length > 2) { answer(s, error("ERR syntax error")); return; }
+        if (!options.password && a.length === 1) { answer(s, error('ERR AUTH <password> called without any password configured for the default user. Are you sure your configuration is correct?')); return; }
+        if (a.length === 2 && a[0] !== 'default' || options.password && a.at(-1) !== options.password) { answer(s, error('WRONGPASS invalid username-password pair or user is disabled.')); return; }
+        s.authenticated = true; answer(s, ok); return;
+      }
+      case 'SELECT': { let db: number; try { db = commandInteger(a[0]!); } catch { answer(s, error('ERR value is not an integer or out of range')); return; } if (db < -2147483648 || db > 2147483647) { answer(s, error('ERR value is out of range, value must between -2147483648 and 2147483647')); return; } if (db < 0 || db >= options.databases) { answer(s, error('ERR DB index is out of range')); return; } s.database = String(db); answer(s, ok); return; }
+      case 'CLIENT': {
+        const sub = a[0]!.toUpperCase();
+        if (sub === 'SETNAME') { if (/[^\x21-\x7e]/.test(a[1] ?? '')) { answer(s, error('ERR Client names cannot contain spaces, newlines or special characters.')); return; } s.name = a[1] ?? ''; answer(s, ok); }
+        else if (sub === 'SETINFO') { if (!['LIB-NAME', 'LIB-VER'].includes(a[1]!.toUpperCase())) { answer(s, error(`ERR Unrecognized option '${a[1]}'`)); return; } if (/[^\x21-\x7e]/.test(a[2]!)) { answer(s, error(`ERR ${a[1]} cannot contain spaces, newlines or special characters.`)); return; } s.lib[a[1]!.toUpperCase()] = a[2]!; answer(s, ok); }
+        else if (sub === 'LIST') {
+          let clients = [...sessions];
+          // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/networking.c "Invalid client ID"
+          if (a[1]?.toUpperCase() === 'ID' && a.length > 2) { let ids: number[]; try { ids = a.slice(2).map((raw) => commandInteger(raw, 'ERR Invalid client ID')); } catch (e) { answer(s, error((e as Error).message)); return; } clients = ids.flatMap((id) => [...sessions].filter((x) => x.id === id)); }
+          else if (a[1]?.toUpperCase() === 'TYPE' && a.length === 3) { const type = a[2]!.toLowerCase(); if (!['normal', 'pubsub', 'master', 'replica'].includes(type)) { answer(s, error(`ERR Unknown client type '${a[2]}'`)); return; } clients = clients.filter((x) => type === (x.subscriptions.size + x.patterns.size ? 'pubsub' : 'normal')); }
+          else if (a.length !== 1) { answer(s, error('ERR syntax error')); return; }
+          answer(s, clients.map((x) => `id=${x.id} addr=127.0.0.1:0 name=${x.name} db=${x.database} flags=${x.subscriptions.size + x.patterns.size ? 'P' : 'N'} lib-name=${x.lib['LIB-NAME'] ?? ''} lib-ver=${x.lib['LIB-VER'] ?? ''}\n`).join(''));
+        }
+        else answer(s, error(options.dialect.unknownCommand(argv))); return;
+      }
+      // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/server.c "It works in a different way if the client is in"
+      case 'PING': if (a.length > 1) { answer(s, error("ERR wrong number of arguments for 'ping' command")); return; } answer(s, s.subscriptions.size + s.patterns.size ? ['pong', a[0] ?? ''] : a.length ? a[0] : new RedisStatus('PONG')); return;
+      case 'INFO': {
+        const blocks: Record<string, string> = { server: `# Server\r\nredis_version:${options.version}\r\nredis_mode:standalone\r\n`, clients: `# Clients\r\nconnected_clients:${sessions.size}\r\nblocked_clients:${[...sessions].filter((x) => x.blocked).length}\r\n`, memory: `# Memory\r\nmaxmemory:0\r\nmaxmemory_policy:noeviction\r\n`, stats: `# Stats\r\ntotal_connections_received:${nextId}\r\ntotal_commands_processed:${commandCount}\r\n`, persistence: '# Persistence\r\nloading:0\r\n' };
+        answer(s, a.length && !['ALL', 'DEFAULT'].includes(a[0]!.toUpperCase()) ? a.map((x) => blocks[x.toLowerCase()] ?? '').join('') : Object.values(blocks).join('\r\n')); return;
+      }
+      case 'MULTI': if (s.queue) answer(s, error('ERR MULTI calls can not be nested')); else { s.queue = []; s.dirty = false; answer(s, ok); } return;
+      case 'DISCARD': if (!s.queue) answer(s, error('ERR DISCARD without MULTI')); else { s.queue = null; s.dirty = false; answer(s, ok); } return;
+      case 'EXEC': { if (!s.queue) { answer(s, error('ERR EXEC without MULTI')); return; } const q = s.queue; s.queue = null; if (s.dirty) { s.dirty = false; answer(s, error('EXECABORT Transaction discarded because of previous errors.')); return; } // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/multi.c "Exec all the queued commands"
+        // Redis writes the queue length before dispatch; pub/sub may write multiple acknowledgement frames.
+        s.sink.write(binaryBytes(`*${q.length}\r\n`)); for (const queued of q) await command(s, queued, true); await wake(); return; }
+      case 'QUIT': answer(s, ok); close(s); s.sink.end(); return;
+      case 'SUBSCRIBE': case 'PSUBSCRIBE': case 'UNSUBSCRIBE': case 'PUNSUBSCRIBE': {
+        const target = cmd.includes('PSUB') || cmd.includes('PUNSUB') ? s.patterns : s.subscriptions; const removing = cmd.includes('UNSUB'); const names = a.length ? a : [...target];
+        for (const name of names.length ? names : [null]) { if (name !== null) { if (removing) target.delete(name); else target.add(name); } answer(s, [cmd.toLowerCase(), name, s.subscriptions.size + s.patterns.size]); } return;
+      }
+      case 'PUBLISH': { let count = 0; for (const target of sessions) { if (target.subscriptions.has(a[0]!)) { answer(target, ['message', a[0]!, a[1]!]); count++; } for (const pattern of target.patterns) if (globMatch(pattern, a[0]!)) { answer(target, ['pmessage', pattern, a[0]!, a[1]!]); count++; } } answer(s, count); return; }
+      case 'BZPOPMIN': {
+        // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/timeout.c "timeout is negative"
+        const raw = a.at(-1)!;
+        const infinite = /^[+-]?inf(?:inity)?$/i.test(raw);
+        if (raw !== raw.trim() || raw === '' || !infinite && !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(raw)) { answer(s, error('ERR timeout is not a float or out of range')); return; }
+        const millis = (infinite ? raw.startsWith('-') ? -Infinity : Infinity : Number(raw)) * 1000;
+        if (millis > 9223372036854775807) { answer(s, error('ERR timeout is out of range')); return; }
+        const timeout = Math.ceil(millis);
+        if (!Number.isFinite(timeout) || timeout < 0) { answer(s, error('ERR timeout is negative')); return; }
+        const v = await blockRun(s, argv); if (v !== null) { answer(s, v); return; }
+        // source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/multi.c "we do not want to allow blocking commands inside multi"
+        if (executing) { answer(s, null); return; }
+        const initial = await options.run([], s.database); s.blocked = { command: argv, deadline: timeout === 0 ? Infinity : (initial.instant ?? 0) + timeout };
+        const poll = () => { if (!s.blocked || s.closed) return; s.blocked.timer = setTimeout(() => { void ordered(async () => { if (!s.blocked) return; const now = await options.run([], s.database); if ((now.instant ?? 0) >= s.blocked.deadline) unblock(s, null); else poll(); }); }, 50); }; poll(); return;
+      }
+      default: { const res = await options.run([argv], s.database); const item = res.items[0]!; answer(s, 'error' in item ? item : item.result); if (res.wrote && !executing) await wake(); }
+    }
+  };
+  return (sink) => {
+    const s: Session = { id: ++nextId, name: '', lib: {}, database: '0', authenticated: !options.password, queue: null, dirty: false, subscriptions: new Set(), patterns: new Set(), sink, closed: false }; sessions.add(s);
+    let buffer = '', chain: Promise<any> = Promise.resolve(); const pending: string[][] = [];
+    const pump = async () => { while (pending.length && !s.blocked && !s.closed) await ordered(() => command(s, pending.shift()!)); };
+    s.pump = pump;
+    return {
+      data(chunk) { if (s.closed) return; buffer += binaryText(chunk); try { while (buffer.length) { let argv: string[]; let end: number; if (buffer[0] === '*') { const f = readResp(buffer); if (!f) break; if (!Array.isArray(f.value) || f.value.some((x: unknown) => typeof x !== 'string')) throw new Error('Protocol error: expected bulk string'); argv = f.value; end = f.end; } else { const at = buffer.indexOf('\r\n'); if (at < 0) break; argv = inlineCommand(buffer.slice(0, at)); end = at + 2; } buffer = buffer.slice(end); pending.push(argv); } chain = chain.then(pump); } catch (e) { answer(s, error(`ERR ${(e as Error).message}`)); close(s); sink.end(); } },
+      settled: () => chain,
+      close: () => close(s),
+    };
+  };
+}

package/src/remote-execute.ts

@@ -3,6 +3,8 @@
 // packs can adapt their vendor-specific executors to it; BUILDING one (origin +
 // sealed-credential egress) is the twins service's job, never a pack's.
 export type RemoteExecuteRequest = {
+  /** The lane of a vendor of lanes that sends the call: the descriptor's `lanes` strategy picks its own by it. */
+  lane?: string;
   method: string;
   path: string;
   headers?: Record<string, string>;
@@ -20,8 +22,6 @@ export type RemoteExecuteRequest = {
    *  that its upload calls carry instead of the API token), on the root's own origin: it is sent as the request's
    *  Authorization and the sealed credential does not go with it. */
   issued?: string;
-  /** the lane of a vendor of lanes the request is (its strategy, when its lanes authenticate apart) */
-  lane?: string;
 };
 export type RemoteExecuteResponse = {
   status: number;

package/src/request-body.ts

@@ -0,0 +1,12 @@
+/** Compressed-request output only: Node's plain requests remain uncapped; Bun retains its own plain-body limit.
+ * The default is Bun's existing largest plain body (128 MiB), so both runtimes decode the same.
+ * Source: bun-types/serve.d.ts, ServeOptions.maxRequestBodySize (@default 1024 * 1024 * 128),
+ * https://github.com/oven-sh/bun/blob/main/packages/bun-types/serve.d.ts .
+ * A pack's descriptor.maxRequestBodySize overrides decoded output as it does Bun's plain-body limit. */
+export const DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE = 128 * 1024 * 1024;
+
+export class RequestBodyTooLargeError extends Error {
+  constructor() { super('Payload Too Large'); this.name = 'RequestBodyTooLargeError'; }
+}
+export const oversizedBody = (): Response => new Response('Payload Too Large', { status: 413 });
+export const decodedBodyLimit = (declared?: number): number => declared ?? DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE;

package/src/runtime.ts

@@ -20,7 +20,7 @@ export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTracepar
 export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
-export { deliverEvents, fillEnvelope, signEvent, signEventAll, verifyEvent } from './events.ts';
+export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.ts';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
 export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.ts';
@@ -323,17 +323,17 @@ export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntr
 
 export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.ts';
 // the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
-export { serveHttp, serveStream, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
+export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
 // two runtime-neutral helpers for a serve path: a file as a Response, a page's client bundle
 export { fileResponse, contentTypeOf } from './file-response.ts';
 export { bundleClient, filePathOf } from './client-bundle.ts';
 // the brand's tokens and faces for a Volter page (the console, the site, the UI kit), fetched at build
 export { brandTokensResponse } from './brand-tokens.ts';
 
-export { multipartBoundary, multipartParts, type MultipartPart } from './multipart.ts';
+export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern, type MultipartPart, type MultipartFramedPart, type MultipartEnvelope } from './multipart.ts';
 export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
-export { vendorFetch, VendorUnreachableError } from './vendor-call.ts';
-export { closeManagedDatabases, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, WORLD_CLOCK_SETTING, worldClockSql, type DatabaseDriver } from './managed-database.ts';
+export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
+export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
 
@@ -343,6 +343,7 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
 export { foldHistory } from './log.ts';
 export { volterHome } from './volter-home.ts';
+export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat, GuestImage, LightPoolOptions } from './machines.ts';
 
 
 export { boardFrameKey } from './board-keys.ts';

package/src/s3/wire.ts

@@ -1,3 +1,4 @@
+import { exactInteger } from '../exact-json.ts';
 // 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
@@ -6,6 +7,8 @@
 // ported from the aws pack's S3 code; a pack may import neither (B4). Importing this module does nothing.
 import { createHash } from 'node:crypto';
 
+const wireInteger = (text: string): number | string => /^[+-]?\d+$/.test(text) ? exactInteger(text) : Number(text);
+
 // ── XML ──────────────────────────────────────────────────────────────────────────────────────
 
 const DECL = '<?xml version="1.0" encoding="UTF-8"?>';
@@ -36,14 +39,14 @@ export const oneOf = (xml: string, tag: string): string | undefined => allOf(xml
 
 // ── CORS (https://developers.cloudflare.com/r2/buckets/cors/) ──────────────────────────────────
 
-export type CorsRule = { id?: string; allowedOrigins: string[]; allowedMethods: string[]; allowedHeaders: string[]; exposeHeaders: string[]; maxAgeSeconds?: number };
+export type CorsRule = { id?: string; allowedOrigins: string[]; allowedMethods: string[]; allowedHeaders: string[]; exposeHeaders: string[]; maxAgeSeconds?: number | string };
 
 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) } : {}) };
+    return { ...(id ? { id } : {}), allowedOrigins: allOf(b, 'AllowedOrigin'), allowedMethods: allOf(b, 'AllowedMethod'), allowedHeaders: allOf(b, 'AllowedHeader'), exposeHeaders: allOf(b, 'ExposeHeader'), ...(age ? { maxAgeSeconds: wireInteger(age) } : {}) };
   });
 }
 export function corsXml(rules: CorsRule[]): string {
@@ -85,7 +88,7 @@ export const requestedHeaders = (request: Request): string[] => (request.headers
  *  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 type LifecycleRule = { id: string; enabled: boolean; prefix: string; prefixOnRule?: boolean; noPrefix?: boolean; expireDays?: number | string; expireDate?: string; abortMultipartDays?: number | string; transitions?: Array<{ days?: number | string; date?: string; storageClass: string }> };
 
 export function parseLifecycle(xml: string): LifecycleRule[] {
   return [...xml.matchAll(/<Rule>([\s\S]*?)<\/Rule>/g)].map((m) => {
@@ -98,11 +101,11 @@ export function parseLifecycle(xml: string): LifecycleRule[] {
     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 { ...(d !== undefined ? { days: wireInteger(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 } : {}),
+      ...(days ? { expireDays: wireInteger(days) } : {}), ...(date ? { expireDate: date } : {}), ...(after ? { abortMultipartDays: wireInteger(after) } : {}), ...(transitions.length ? { transitions } : {}),
     };
   });
 }

package/src/scenario.ts

@@ -1,3 +1,4 @@
+import { exactInteger, compareExactNumbers, isExactIntegerValue } from './exact-json.ts';
 // THE scenario engine — System 2 of the twin programming model (one grammar, per-pack
 // vocabulary). See company-repo BRIEFS/TWIN-PROGRAMMING-MODEL.md (LOCKED, 2026-08-27).
 //
@@ -59,6 +60,8 @@ export type PackScenarioAdapter<Req> = {
   scopeKey?: (req: Req) => string;
   /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
    *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
+  /** Opt-in scope check for post-admission model generation failures; absent rejects them. */
+  validateGenerationFault?: (fault: ScenarioGenerationFault, handler: ScenarioHandler) => string | null;
   renderFault?: (fault: ScenarioStatusFault, req: Req) => { body: unknown; headers?: Record<string, string> };
 };
 
@@ -70,13 +73,16 @@ export type PackScenarioAdapter<Req> = {
  *    status — answer this HTTP status instead of serving: a 4xx/5xx the vendor's own envelope
  *             (the pack's adapter renders it; a kernel envelope when it declares none), with
  *             `Retry-After` when `retryAfterSeconds` is set;
+ *    generation — opt-in post-admission compute failure, carried to the handler for its SDK error wire;
  *    drop   — never answer: the request hangs until the client's own timeout ends it (what an
  *             outage looks like from the client; a TCP reset is not something a fetch can do),
  *             released after `holdMs` (default 300 000) so a socket is not held forever. */
 export type ScenarioFault =
   | { kind: "slow"; ms: number }
-  | { kind: "status"; status: number; retryAfterSeconds?: number; message?: string }
+  | { kind: "status"; status: number; retryAfterSeconds?: number; message?: string; errorType?: string; metadata?: Record<string, unknown> }
+  | { kind: "generation"; status: number; message: string; errorType: string; metadata?: Record<string, unknown>; partialText?: string; event?: string }
   | { kind: "drop"; holdMs?: number };
+export type ScenarioGenerationFault = Extract<ScenarioFault, { kind: "generation" }>;
 export type ScenarioStatusFault = Extract<ScenarioFault, { kind: "status" }>;
 /** What a `status` fault serves: the pack's rendered envelope, or the kernel's. */
 export type ScenarioFaultResult = { status: number; headers: Record<string, string>; body: unknown };
@@ -203,15 +209,24 @@ function parseHandler<Req>(raw: unknown, index: number, adapter: PackScenarioAda
   if (onRefusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${onRefusal}`);
   if (h.fault !== undefined) {
     const f = h.fault as Record<string, unknown>;
-    if (typeof f !== "object" || f === null || Array.isArray(f)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault is an object { kind: "slow" | "status" | "drop", ... }`);
-    const kinds = ["slow", "status", "drop"];
+    if (typeof f !== "object" || f === null || Array.isArray(f)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault is an object { kind: "slow" | "status" | "drop" | "generation", ... }`);
+    const kinds = ["slow", "status", "drop", "generation"];
     if (!kinds.includes(f.kind as string)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.kind is one of ${kinds.join(", ")}, got ${JSON.stringify(f.kind)}`);
-    const keysFor: Record<string, string[]> = { slow: ["kind", "ms"], status: ["kind", "status", "retryAfterSeconds", "message"], drop: ["kind", "holdMs"] };
+    const keysFor: Record<string, string[]> = { slow: ["kind", "ms"], status: ["kind", "status", "retryAfterSeconds", "message", "metadata", "errorType"], generation: ["kind", "status", "message", "errorType", "metadata", "partialText", "event"], drop: ["kind", "holdMs"] };
     for (const key of Object.keys(f)) if (!keysFor[f.kind as string]!.includes(key)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is not a key of a ${String(f.kind)} fault (valid: ${keysFor[f.kind as string]!.join(", ")})`);
     if (f.kind === "slow" && !(Number.isInteger(f.ms) && (f.ms as number) >= 0 && (f.ms as number) <= 600_000)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.ms is an integer 0..600000 (milliseconds)`);
-    if (f.kind === "status" && !(Number.isInteger(f.status) && (f.status as number) >= 400 && (f.status as number) <= 599)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.status is an integer 400..599 — a fault is a refusal or a failure, never a success`);
+    if ((f.kind === "status" || f.kind === "generation") && !(Number.isInteger(f.status) && (f.status as number) >= 400 && (f.status as number) <= 599)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.status is an integer 400..599 — a fault is a refusal or a failure, never a success`);
     if (f.kind === "status" && f.retryAfterSeconds !== undefined && !(Number.isInteger(f.retryAfterSeconds) && (f.retryAfterSeconds as number) >= 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.retryAfterSeconds is a non-negative integer`);
     if (f.kind === "status" && f.message !== undefined && typeof f.message !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.message is a string`);
+    if ((f.kind === "status" || f.kind === "generation") && f.metadata !== undefined && (typeof f.metadata !== "object" || f.metadata === null || Array.isArray(f.metadata))) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.metadata is an object`);
+    if (f.kind === "status" && f.errorType !== undefined && typeof f.errorType !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.errorType is a string`);
+    if (f.kind === "generation") {
+      if (typeof f.message !== "string" || typeof f.errorType !== "string" || !f.errorType) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation fault requires message and nonempty errorType`);
+      for (const key of ["partialText", "event"]) if (f[key] !== undefined && typeof f[key] !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is a string`);
+      if (!adapter.validateGenerationFault) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation faults require a compute-only adapter`);
+      const refusal = adapter.validateGenerationFault(f as ScenarioGenerationFault, h as unknown as ScenarioHandler);
+      if (refusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
+    }
     if (f.kind === "drop" && f.holdMs !== undefined && !(Number.isInteger(f.holdMs) && (f.holdMs as number) >= 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.holdMs is a non-negative integer`);
     if (f.kind !== "slow" && "respond" in h) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: a ${String(f.kind)} fault serves no content — drop \`respond\` (only a slow fault may carry one)`);
   }
@@ -257,9 +272,10 @@ function adapterKind<Req>(adapter: PackScenarioAdapter<Req>, kind: string): { va
 function applyTransform(value: string | number, transform: string | undefined, vendor: string, where: string): string | number {
   if (!transform) return value;
   const [op, rawN] = transform.slice(1).split(":") as [string, string];
-  if (typeof value !== "number") throw new ScenarioError(`${vendor} scenario: ${where} applies |${op}:${rawN} to a non-numeric extractor value ${JSON.stringify(value)}`);
-  const n = Number(rawN);
-  return op === "min" ? Math.min(value, n) : Math.max(value, n);
+  if (typeof value !== "number" && !(typeof value === "string" && isExactIntegerValue(value))) throw new ScenarioError(`${vendor} scenario: ${where} applies |${op}:${rawN} to a non-numeric extractor value ${JSON.stringify(value)}`);
+  const n = /^-?\d+$/.test(rawN) ? exactInteger(rawN) : Number(rawN);
+  const cmp = compareExactNumbers(value, n);
+  return op === "min" ? (cmp <= 0 ? value : n) : (cmp >= 0 ? value : n);
 }
 
 type ScopeState = { calls: number; phase: string | undefined; onceFired: Set<string> };
@@ -382,7 +398,7 @@ export class ScenarioEngine<Req> {
       if (!m) throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": pattern did not match the request (the handler demanded a value the request never stated)`);
       const captured = m[1] ?? m[0]!;
       if (tp.as === "number") {
-        const n = Number(captured);
+        const n = /^-?\d+$/.test(captured) ? exactInteger(captured) : Number(captured);
         if (Number.isNaN(n)) throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": captured "${captured}" is not a number`);
         value = n;
       } else value = captured;
@@ -434,6 +450,7 @@ function waitForScenarioFault(ms: number, signal?: AbortSignal): Promise<void> {
 
 export async function scenarioFaultResult(fault: ScenarioFault, render?: () => { body: unknown; headers?: Record<string, string> } | undefined, signal?: AbortSignal): Promise<ScenarioFaultResult | null> {
   throwIfScenarioAborted(signal);
+  if (fault.kind === "generation") return null; // compute handler renders the admitted generation failure
   if (fault.kind === "slow") { await waitForScenarioFault(fault.ms, signal); throwIfScenarioAborted(signal); return null; }
   if (fault.kind === "drop") {
     await waitForScenarioFault(fault.holdMs ?? 300_000, signal);
@@ -447,19 +464,23 @@ export async function scenarioFaultResult(fault: ScenarioFault, render?: () => {
   return { status: fault.status, headers, body: rendered?.body ?? { error: { message: fault.message ?? `twin fault: ${fault.status}`, type: "twin_fault" } } };
 }
 
-export function statefulTwinManifest(input: { vendor: string; twinOf: string; stores: string; identity?: string; notes?: string }): Record<string, unknown> {
+export function statefulTwinManifest(input: { vendor: string; twinOf: string; stores: string; identity?: string; behavior?: string; notes?: string; doors?: ReadonlyArray<{ method: string; path: string; note?: string }> }): Record<string, unknown> {
+  // the World's doors the pack declares (what the vendor's own pages do that its API does not: issuing an account's key)
+  const doors = input.doors ?? [];
   return {
     twin: true,
     vendor: input.vendor,
     twinOf: input.twinOf,
     program: {
-      state: `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here — there is no fixture language and no write door besides the vendor's.`,
+      state: doors.length
+        ? `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here; what the vendor does on its own pages (not its API) is a door of the World, listed under doors. There is no fixture language.`
+        : `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here — there is no fixture language and no write door besides the vendor's.`,
       identity: input.identity ?? 'Authenticate as the vendor does; the twin accepts any non-sentinel credential.',
       time: 'Writes are stamped from the WORLD CLOCK (volter-world clock <world> set/advance) — deterministic history is clock-set, seed, clock-advance.',
-      behavior: 'This twin is state, not scripting — answers are functions of what you seeded. Judgment/fault scripting lives on the scripted vendor twins (their GET /twin explains).',
+      behavior: input.behavior ?? 'This twin is state, not scripting — answers are functions of what you seeded. Judgment/fault scripting lives on the scripted vendor twins (their GET /twin explains).',
       ...(input.notes ? { notes: input.notes } : {}),
     },
-    doors: { manifest: 'GET /twin' },
+    doors: { manifest: 'GET /twin', ...Object.fromEntries(doors.map((d) => [`${d.method} ${d.path}`, d.note ?? 'a door of the World'])) },
   };
 }
 

package/src/serve-http.ts

@@ -10,6 +10,13 @@
 
 import type { TwinStream } from './twin-fetch.ts';
 
+/** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
+const socketLibrary = () => import('ws');
+export async function connectWebSocket(url: string, headers: Record<string, string>, protocols: string[] = []): Promise<WebSocket> {
+  const { WebSocket: Client } = await socketLibrary();
+  return new Client(url, protocols, { headers }) as unknown as WebSocket;
+}
+
 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 = {
@@ -33,7 +40,7 @@ export type ServeHttpOptions = {
   fetch: HttpHandler;
   /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
   idleTimeout?: number;
-  /** the largest request body accepted, in bytes (Bun's default is 128 MB; Node sets none) */
+  /** Explicit transport limit in bytes; absent, Bun retains its 128 MiB default. */
   maxRequestBodySize?: number;
   /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
   error?: (error: Error) => Response | Promise<Response>;
@@ -62,6 +69,8 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
   // 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 declaredCap = (options.fetch as { maxRequestBodySize?: number }).maxRequestBodySize;
+  if (options.maxRequestBodySize === undefined && declaredCap !== undefined) options = { ...options, maxRequestBodySize: declaredCap };
   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;
@@ -301,7 +310,7 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
   });
   let socketServer: import('ws').WebSocketServer | undefined;
   if (options.upgrade) {
-    const { WebSocketServer } = await import('ws');
+    const { WebSocketServer } = await socketLibrary();
     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