@volter/world-core 3.0.154 → 3.0.156

package/src/redis/member-storage.ts

@@ -1,7 +1,7 @@
 // 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 { applyTwinWrites, type TwinWriteInput } from '../serve.ts';
 import { projectResources } from '../actions.ts';
 import { treeStamp, treeChangesSince } from '../log.ts';
 import { getActiveWorldStore } from '../world-store.ts';
@@ -9,7 +9,9 @@ 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 }>>();
+// `byKey` holds each key's member subjects in `subjects`' own order, so rebuilding one key reads its members, not every
+// subject of the service (S2 R19: the image phase was up to 560 ms of a 2 s window of Twenty's queue twin).
+const held = new WeakMap<object, Map<string, { stamp: string; subjects: Map<string, any>; byKey: Map<string, 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')}`;
 
@@ -21,8 +23,11 @@ export const memberStorage = {
     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);
+    if (!h || !delta || delta.removed.length) h = { stamp, subjects: new Map(), byKey: 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);
+      if (r.type === 'member') { let of = h.byKey.get(r.key); if (!of) h.byKey.set(r.key, of = new Map()); of.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()];
@@ -37,22 +42,25 @@ export const memberStorage = {
       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;
+      const v = collections.has(meta.kind) ? [...(h.byKey.get(name)?.values() ?? [])].filter((r) => r.id.startsWith(scope(ctx)) && 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);
+    // a run's writes land together, in this order, as they landed one at a time (serve.ts applyTwinWrites)
+    const writes: TwinWriteInput[] = [];
+    const write = (type: string, id: string, operation: string, fields: any) => { writes.push({ operation, subjectType: type, subjectId: id, fields, occurredAt: ctx.occurredAt, actor: { kind: 'agent' } }); };
     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) });
+        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) });
+      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 });
+    for (const { sha, body, operation } of space.pendingScriptWrites()) write('script', `${scope(ctx)}script:${sha}`, operation, { sha, body: body ?? '', gone: body === null });
+    await applyTwinWrites(ctx.service, writes, ctx.root);
   },
 };

package/src/redis/service-times.ts

@@ -0,0 +1,81 @@
+// A Redis twin's own account of its service, from its own clock: what a command costs from its bytes' arrival to its
+// reply, and which part of the twin holds that time. One line every two seconds while commands are served, none
+// while there are none. It is read to name where a slow request's time is, which a CPU profile's seconds are not
+// (a profile credits the gap between two samples to the later one).
+//
+// A stream serves one command at a time (stream.ts `ordered`), so one command is open at a time and a phase belongs
+// to it. The phases: `image` (the keyspace's image, with the tree's stamp), `execute` (the command itself), `flush`
+// (its writes: the append and its locks), `reply` (the write of the answer to the connection), and `context`, which
+// is the rest of the pack's run around those three (its fetch, the World's clock, the request's context). `other`
+// is what is left of the command's own time: the stream's own work and its waits between those.
+type Phase = 'image' | 'execute' | 'flush' | 'reply' | 'run';
+const PHASES: readonly Phase[] = ['image', 'execute', 'flush', 'reply', 'run'];
+const SAY_EVERY_MS = 2000;
+const now = (): number => performance.now();
+
+type Command = { session: number; command: string };
+type Slowest = Command & { threw: boolean; serviceMs: number; waitedMs: number; ownMs: number };
+type Window = { service: number[]; waited: number; waitedMax: number; own: number; phases: Record<Phase, number>; runs: number; queueMax: number; writes: number; laps: Record<string, number>; slowest?: Slowest };
+const fresh = (): Window => ({ service: [], waited: 0, waitedMax: 0, own: 0, phases: { image: 0, execute: 0, flush: 0, reply: 0, run: 0 }, runs: 0, queueMax: 0, writes: 0, laps: {} });
+// THE PARTS OF ONE RUN, in the order it passes them: a run is the pack's own request to itself, carried through the
+// whole of a pack's fetch (pack-fetch.ts) to the command and back. Each `lap` names the stretch that ended there,
+// from the lap before it; the stretches of a window's runs are summed by name as `runPartsMs`. A stretch holds
+// whatever else this realm did between its two ends: under traffic that is other connections' bytes arriving.
+let lapAt = 0;
+let window = fresh();
+let open: { received: number; started: number; command: Command } | undefined;
+let timer: ReturnType<typeof setTimeout> | undefined;
+let served = 0;
+
+function say(): void {
+  timer = undefined;
+  const w = window; window = fresh();
+  if (w.service.length === 0) return;
+  const sorted = [...w.service].sort((a, b) => a - b);
+  const at = (share: number): number => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * share))]!;
+  const ms = (value: number): number => Math.round(value * 10) / 10;
+  const inRun = w.phases.image + w.phases.execute + w.phases.flush;
+  console.error('[redis-twin]', JSON.stringify({
+    commands: w.service.length, servedSoFar: served, runs: w.runs, wrote: w.writes,
+    // from a command's bytes read to its reply written, its wait behind the commands before it included
+    serviceMs: { total: ms(w.service.reduce((sum, each) => sum + each, 0)), p50: ms(at(0.5)), p95: ms(at(0.95)), max: ms(sorted[sorted.length - 1]!) },
+    waitedMs: { total: ms(w.waited), max: ms(w.waitedMax) },
+    phasesMs: { context: ms(w.phases.run - inRun), image: ms(w.phases.image), execute: ms(w.phases.execute), flush: ms(w.phases.flush), reply: ms(w.phases.reply), other: ms(w.own - w.phases.run - w.phases.reply) },
+    runPartsMs: Object.fromEntries(Object.entries(w.laps).map(([name, value]) => [name, ms(value)])),
+    queueMax: w.queueMax,
+    slowest: w.slowest ? { ...w.slowest, serviceMs: ms(w.slowest.serviceMs), waitedMs: ms(w.slowest.waitedMs), ownMs: ms(w.slowest.ownMs) } : null,
+  }));
+}
+
+export const redisServiceTimes = {
+  now,
+  /** A command starts: `received` is when its bytes were read, `waiting` the commands read and not yet started. */
+  begin(received: number, waiting: number, command: Command): void {
+    open = { received, started: now(), command };
+    if (waiting > window.queueMax) window.queueMax = waiting;
+    if (!timer) { timer = setTimeout(say, SAY_EVERY_MS); (timer as { unref?: () => void }).unref?.(); }
+  },
+  /** Time of the open command in one phase. */
+  add(phase: Phase, ms: number): void { if (open) { window.phases[phase] += ms; if (phase === 'run') window.runs += 1; } },
+  wrote(): void { if (open) window.writes += 1; },
+  /** A run begins: its first stretch is counted from here. */
+  lapFrom(): void { lapAt = now(); },
+  /** The stretch of the open command's run that ends here, by name. Outside a served command it is nothing. */
+  lap(name: string): void { if (!open || lapAt === 0) return; const at = now(); window.laps[name] = (window.laps[name] ?? 0) + (at - lapAt); lapAt = at; },
+  /** A run has ended: nothing after it is a stretch of it. */
+  lapEnd(name: string): void { this.lap(name); lapAt = 0; },
+  /** The open command has answered (or blocked, or failed with its error answered). */
+  end(threw = false): void {
+    if (!open) return;
+    const ended = now(), waited = open.started - open.received;
+    const serviceMs = ended - open.received;
+    if (!window.slowest || serviceMs > window.slowest.serviceMs) {
+      window.slowest = { ...open.command, threw, serviceMs, waitedMs: waited, ownMs: ended - open.started };
+    }
+    window.service.push(ended - open.received); window.waited += waited; if (waited > window.waitedMax) window.waitedMax = waited;
+    window.own += ended - open.started; served += 1; open = undefined;
+  },
+  /** `work`, its time counted in `phase` of the open command. */
+  timed<T>(phase: Phase, work: () => T): T { const began = now(); try { return work(); } finally { this.add(phase, now() - began); } },
+  phases: PHASES,
+};

package/src/redis/stream.ts

@@ -3,17 +3,26 @@
 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';
+import { worldNow } from '../world-clock.ts';
+import { redisServiceTimes as times } from './service-times.ts';
 export type RedisStreamOptions = {
   dialect: RedisDialect; version: string; password?: string; databases: number;
-  run(commands: string[][], database: string): Promise<{ items: RunItem[]; wrote: boolean; instant?: number }>;
+  run(commands: string[][], database: string): Promise<{ items: RunItem[]; wrote: boolean; instant?: number; touched?: string[] }>;
 };
-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();
+export function createRedisStream(given: RedisStreamOptions): TwinStream {
+  // The pack's run, its time counted for the command it serves (service-times.ts).
+  const options: RedisStreamOptions = { ...given, run: async (commands, database) => { const began = times.now(); times.lapFrom(); try { const ran = await given.run(commands, database); if (ran.wrote) times.wrote(); return ran; } finally { times.lapEnd('8 answer read by the stream'); times.add('run', times.now() - began); } } };
+  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; received: number; answered: number; pump?: () => Promise<void>; blocked?: { command: string[]; deadline: number; timer?: ReturnType<typeof setTimeout> } };
+  const sessions = new Set<Session>(); let nextId = 0, commandCount = 0, waiting = 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 connectionTrace = (s: Session, stage: string, command?: string) => {
+    try { console.error('[redis-twin-connection]', JSON.stringify({ at: performance.timeOrigin + times.now(), pid: (globalThis as { process?: { pid?: number } }).process?.pid ?? 0,
+      session: s.id, stage, received: s.received, answered: s.answered, ...(command ? { command } : {}) })); }
+    catch { /* diagnostic output cannot change a connection */ }
+  };
+  const answer = (s: Session, v: any) => { if (!s.closed) { times.timed('reply', () => s.sink.write(binaryBytes(respReply(v)))); s.answered += 1; } };
+  const close = (s: Session) => { if (!s.closed) connectionTrace(s, 'closed'); 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') {
@@ -21,7 +30,22 @@ export function createRedisStream(options: RedisStreamOptions): TwinStream {
     }
     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); } };
+  // A CLIENT BLOCKED ON KEYS IS ASKED AGAIN ONLY WHEN ONE OF ITS KEYS WAS WRITTEN. Every write asked every blocked
+  // client again, each ask a whole run for each of its keys: Twenty's queue workers hold a blocked client apiece, and
+  // its twin made 59 to 89 runs for 31 to 41 commands in a two-second window, each run about 20 ms, with every
+  // other command waiting behind them (Twenty 51: commands waited 0.6 to 5.9 s). `touched` is the keys the run
+  // wrote, by name, whatever its database (a name written in another database asks a client that then finds
+  // nothing, never the reverse). Without it (an EXEC's queue, a run that does not say, a command that writes
+  // another database's keys) every blocked client is asked, as before.
+  const wake = async (touched?: readonly string[]) => {
+    for (const s of sessions) {
+      if (!s.blocked) continue;
+      if (touched && !s.blocked.command.slice(1, -1).some((key) => touched.includes(key))) continue;
+      const v = await blockRun(s, s.blocked.command); if (v !== null) unblock(s, v);
+    }
+  };
+  /** Commands that write keys of a database other than their session's: their run's `touched` does not name them all. */
+  const CROSS_DATABASE = new Set(['MOVE', 'COPY', 'SWAPDB']);
   const command = async (s: Session, argv: string[], executing = false): Promise<void> => {
     if (!argv.length || s.closed) return;
     commandCount++;
@@ -85,20 +109,48 @@ export function createRedisStream(options: RedisStreamOptions): TwinStream {
         // 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;
+        // A BLOCKED CLIENT WAITS FOR A WRITE OR ITS DEADLINE, AND ASKS THE TREE NOTHING MEANWHILE. A write through this
+        // twin wakes it (wake, after every command that wrote). Its deadline is in the World's time, so the timer
+        // reads the World's clock (world-clock.ts worldNow: one check of the clock file, kept while it stands) and
+        // nothing else. It ran a whole empty request every 50 ms to read that time: the pack's fetch, its context
+        // and the keyspace's image with its tree stamp, for every blocked client, the whole time it was blocked.
+        // Twenty's queue workers each hold one blocked client: its Redis twin made about 18,700 stamps in a run, 56,145
+        // stat requests, and spent 55 s of 114 busy in them, with no command to answer. No timeout is no timer; a
+        // deadline far off is checked less often, never more than a second apart, and to 50 ms as it nears.
+        const poll = (): void => {
+          if (!s.blocked || s.closed || s.blocked.deadline === Infinity) return;
+          let left: number;
+          try { left = s.blocked.deadline - Date.parse(worldNow()); }
+          catch (cause) { unblock(s, error(`ERR twin: ${cause instanceof Error ? cause.message : String(cause)}`.replace(/[\r\n]+/g, ' '))); return; }
+          if (left <= 0) { void ordered(async () => { if (s.blocked) unblock(s, null); }); return; }
+          s.blocked.timer = setTimeout(poll, Math.max(50, Math.min(1000, left / 2)));
+        };
+        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(); }
+      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(CROSS_DATABASE.has(cmd) ? undefined : res.touched); }
     }
   };
   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()!)); };
+    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, received: 0, answered: 0 }; sessions.add(s);
+    connectionTrace(s, 'opened');
+    let buffer = '', chain: Promise<any> = Promise.resolve(); const pending: Array<{ argv: string[]; received: number }> = [];
+    // A command whose storage fails (a World storage lock that timed out, a write that could not be made) answers its
+    // client with an error and the session goes on, as Redis answers one failed command: it was an unhandled
+    // rejection, and the twin's process exited with every client's connection (Twenty 46).
+    const pump = async () => {
+      while (pending.length && !s.blocked && !s.closed) {
+        const { argv, received } = pending.shift()!;
+        try { await ordered(async () => { waiting -= 1; times.begin(received, waiting, { session: s.id, command: argv[0]?.toUpperCase().slice(0, 32) ?? '' });
+          let threw = false;
+          try { await command(s, argv); } catch (cause) { threw = true; throw cause; } finally { times.end(threw); } }); }
+        catch (cause) { if (!s.closed) answer(s, error(`ERR twin: ${cause instanceof Error ? cause.message : String(cause)}`.replace(/[\r\n]+/g, ' '))); }
+      }
+    };
     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(); } },
+      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, received: times.now() }); waiting += 1; s.received += 1; if (s.received === 1) connectionTrace(s, 'first-command', argv[0]?.toUpperCase().slice(0, 32)); } chain = chain.then(pump); } catch (e) { answer(s, error(`ERR ${(e as Error).message}`)); close(s); sink.end(); } },
       settled: () => chain,
-      close: () => close(s),
+      close: () => { waiting -= pending.length; pending.length = 0; close(s); },
     };
   };
 }

package/src/runtime-state.ts

@@ -0,0 +1,14 @@
+// The lifecycle's state/identity primitives. Re-export their canonical modules
+// so the active store, locks and scopes are shared with the full runtime and packs.
+// Booting an empty World does not require pack registration or derived engines.
+export { getActiveWorldStore, removeCarriedLocks } from './world-store.ts';
+export type { WorldStore } from './world-store.ts';
+export { stateDirName, withFileLock, worldPaths, worldStateRoot, WORLD_DATA_ENV } from './storage.ts';
+export { assertStateRemovable, withAncestryLock, withStateRemoval } from './ancestry.ts';
+export { readBranchMeta } from './log.ts';
+export { volterHome } from './volter-home.ts';
+export { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository, vendorOfPackModule } from './pack-paths.ts';
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './protocol.ts';
+export { WORLD_BOOT_PATH } from './serve-http.ts';
+export { WORLD_ENV_NAMES_ENV } from './world-env.ts';
+export { beginPlaceholderPull, endPlaceholderPull, placeholderPullActive } from './placeholder-remote.ts';

package/src/runtime.ts

@@ -161,6 +161,7 @@ export {
 export type { BlobStore } from './blob-store.ts';
 export {
   applyTwinWrite,
+  applyTwinWrites,
   applyTwinWriteAtomic,
   createTwinServer,
   CALLER_HEADER,
@@ -297,6 +298,8 @@ export { installedPackageDir, installedVendorPacks, packVendor, packRepository,
 export * as git from './git/index.ts';
 // S3's wire (contract "S3's wire is a kernel library too"): its XML, CORS, lifecycle, delete batches, ETags, body bytes.
 export * as s3 from './s3/wire.ts';
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from './xml.ts';
 
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 
@@ -323,7 +326,7 @@ 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, connectWebSocket, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
+export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, servedHandlerOf, 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';
@@ -347,3 +350,5 @@ export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFi
 
 
 export { boardFrameKey } from './board-keys.ts';
+
+export * as managedOriginalInputs from './managed-original-inputs.ts';

package/src/serve-http.ts

@@ -4,11 +4,12 @@
 // as a standard Request and the handler's Response written back. Async, because binding a port is
 // 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`
+// Nothing here runs at module scope (the served-handler registry is made on first use), and `node:http` is reached through `process.getBuiltinModule`
 // 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';
+import { worldBootAnswer } from './world-boot.ts';
 
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
@@ -64,6 +65,24 @@ const bunRuntime = (): BunLike | undefined => { const b = (globalThis as { Bun?:
 /** The path a World asks a service it booted, when that service's port answers, which boot it belongs to. */
 export const WORLD_BOOT_PATH = '/__volter/world-boot';
 
+/** Each listening server's own handler, by its port, as the seam serves it (the boot door answered, nothing journaled):
+ *  the World's co-located host warms a twin in-process through it (world-runtime host.ts warmInProcess), so its warm-up is
+ *  never a request on the wire nor in any journal. A server leaves it when it stops. Kept on globalThis under a registered
+ *  symbol, as the reference registry is (references.ts), so a pack that resolved its own copy of this module shares it. */
+const servedHandlers = (): Map<number, HttpHandler> =>
+  ((globalThis as Record<symbol, unknown>)[Symbol.for('volter.servedHandlers')] ??= new Map<number, HttpHandler>()) as Map<number, HttpHandler>;
+
+/** The handler serving `port` in this process, when a server made through the seam listens there. */
+export function servedHandlerOf(port: number): HttpHandler | undefined { return servedHandlers().get(port); }
+
+/** A server's handler kept by its port until the server stops. */
+function keepHandler(server: HttpServer, handler: HttpHandler): HttpServer {
+  const port = server.port;
+  if (!port) return server;
+  servedHandlers().set(port, handler);
+  return { ...server, stop: async (closeActive?: boolean) => { if (servedHandlers().get(port) === handler) servedHandlers().delete(port); await server.stop(closeActive); } };
+}
+
 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.
@@ -76,7 +95,7 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
   const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
   if (worldBoot) {
     const served = options.fetch;
-    options = { ...options, fetch: (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Response.json({ boot: worldBoot }) : served(request)) };
+    options = { ...options, fetch: (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? worldBootAnswer(worldBoot) : served(request)) };
   }
   // loopback by default: an unnamed interface is never every interface
   const hostname = options.hostname ?? '127.0.0.1';
@@ -102,9 +121,9 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
       } : {}),
     });
     const port = server.port ?? 0;
-    return { hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => { await server.stop(closeActive); } };
+    return keepHandler({ hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => { await server.stop(closeActive); } }, options.fetch);
   }
-  return serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch });
+  return keepHandler(await serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch }), options.fetch);
 }
 
 type NodeHttp = typeof import('node:http');

package/src/serve.ts

@@ -12,13 +12,14 @@ import { parseExactJson } from './exact-json.ts';
 // reality). Forking is a separate data operation (fork.ts), never a serve mode.
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { serveHttp, setServeDecorator, WORLD_BOOT_PATH, type HttpHandler } from './serve-http.ts';
-import { performAtHead } from './head.ts';
+import { performAtHead, performsAtHeadNow } from './head.ts';
 import { withHeaders } from './with-headers.ts';
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import type { SubjectFields } from './hash.ts';
 import { hashFieldValue } from './hash.ts';
-import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from './actions.ts';
+import { appendActionIfAbsent, appendActionOccurrence, appendActionOccurrences, decideAndAppendAction, projectResources } from './actions.ts';
+import { readSubject } from './log.ts';
 import type { ActionProjection, TwinAction, TwinActionPrecondition } from './actions.ts';
 import { observeWorldPaths, worldPaths } from './storage.ts';
 import { getActiveWorldStore } from './world-store.ts';
@@ -699,12 +700,53 @@ export async function applyTwinWrite(
   return {
     result,
     get resource(): TwinResource {
-      return resolved ??= projectResources(service, root).find((r) => r.type === write.subjectType && r.id === answerId)
+      return resolved ??= readSubject(service, write.subjectType, answerId, root)
         ?? ({ id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields } as TwinResource);
     },
   };
 }
 
+/**
+ * Several local writes of one service, landed as `applyTwinWrite` lands each called in turn — the same actions, ids and
+ * order — under one lock and one append (actions.ts `appendActionOccurrences`). Writes that need the one-at-a-time
+ * path take it: a caller's identity (`idempotencyKey`/`actionId`), preconditions, or a head that performs each entry as
+ * it lands. An input is offloaded once per distinct value, as each write's own offload would name it.
+ */
+export async function applyTwinWrites(
+  service: string,
+  writes: readonly TwinWriteInput[],
+  root?: string,
+): Promise<Array<{ result: TwinWriteResult; resource: TwinResource }>> {
+  if (writes.length <= 1 || performsAtHeadNow(service, root) || writes.some((write) => write.idempotencyKey || write.actionId || write.preconditions?.length)) {
+    const out: Array<{ result: TwinWriteResult; resource: TwinResource }> = [];
+    for (const write of writes) out.push(await applyTwinWrite(service, write, root));
+    return out;
+  }
+  // Each distinct input offloaded once (S2 R17): `offloadInput` is content-addressed (a string's blob is named by its
+  // SHA-256), so the result is the one each write's own offload would give, and a command's writes, which share one
+  // recorded request, hash and look up its blob once instead of once per write.
+  const offloaded = new Map<unknown, unknown>();
+  for (const write of writes) if (write.input !== undefined && !offloaded.has(write.input)) offloaded.set(write.input, await offloadInput(service, write.input, root));
+  const committed = appendActionOccurrences(writes.map((write) => actionForTwinWrite(service,
+    write.input === undefined ? write : { ...write, input: offloaded.get(write.input) as TwinWriteInput['input'] })), root);
+  const out: Array<{ result: TwinWriteResult; resource: TwinResource }> = [];
+  for (const [index, { appended, action: landed, placeholder }] of committed.entries()) {
+    const write = writes[index]!;
+    // the head does not perform here (`performsAtHeadNow` was false): this marks the request's deferred group as written
+    if (appended && !placeholder) await performAtHead(service, landed, root);
+    const answerId = write.subjectId;
+    let resolved: TwinResource | undefined;
+    out.push({
+      result: { status: appended ? 'performed' : 'replayed', actionId: landed.id },
+      get resource(): TwinResource {
+        return resolved ??= readSubject(service, write.subjectType, answerId, root)
+          ?? ({ id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields } as TwinResource);
+      },
+    });
+  }
+  return out;
+}
+
 export async function createTwinServer(options: { service: string; root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
   const readOnly = options.readOnly ?? false;
   const serveOptions = {

package/src/storage.ts

@@ -6,7 +6,7 @@ import {
   GenericWorldStateSchema,
   WorldServiceEventSchema,
 } from './schemas.ts';
-import { getActiveWorldStore } from './world-store.ts';
+import { getActiveWorldStore, storageLockScope, TREE_GENERATION, type WorldLockOptions } from './world-store.ts';
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { parentEntries, toEvent } from './log.ts';
 import type {
@@ -198,8 +198,8 @@ function appendJsonl(path: string, value: unknown): void {
  *  single-instance store it is a synchronous pass-through. Used to make read-then-append
  *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
  *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
-export function withFileLock<T>(lockPath: string, fn: () => T): T {
-  return withStateLock(lockPath, fn);
+export function withFileLock<T>(lockPath: string, fn: () => T, options: WorldLockOptions = {}): T {
+  return withStateLock(lockPath, fn, storageLockScope(options));
 }
 
 function writeJsonAtomic(path: string, value: unknown): void {
@@ -385,6 +385,8 @@ const KNOWN_SERVICE_ENTRIES = new Set([
 function isKnownServiceEntry(name: string): boolean {
   // log.ts: the branch pointer and the checkpoint
   if (name === 'branch.json' || name === 'checkpoints') return true;
+  // world-store.ts: the generation a file store keeps beside a tree's files
+  if (name === TREE_GENERATION) return true;
   return KNOWN_SERVICE_ENTRIES.has(name) || name.endsWith('.tmp') || /\.stale\.\d+\.\d+$/.test(name);
 }
 

package/src/world-boot.ts

@@ -0,0 +1,6 @@
+// One private boot answer for the kernel's HTTP and gRPC serve seams.
+// Reading process identity happens on request; importing this helper has no side effects.
+export function worldBootAnswer(boot: string): Response {
+  const pid = (globalThis as { process?: { pid?: number } }).process?.pid;
+  return Response.json({ boot, pid });
+}

package/src/world-clock.ts

@@ -26,10 +26,14 @@ const machineNow = (): number => {
  *  now); real wall-clock time otherwise. */
 export function worldNow(): string {
   const file = process.env[WORLD_CLOCK_ENV];
-  if (file && getActiveWorldStore().exists(file)) {
+  // One read answers both whether the clock file is there and what it holds.
+  // Kept while the clock file's own facts stand (world-store.ts readKept): every operation asks the time.
+  const store = getActiveWorldStore();
+  const held = file ? (store.readKept ? store.readKept(file) : store.read(file)) : null;
+  if (held !== null) {
     // A configured-but-corrupt clock is a WORLD defect — parseClock fails loudly, never silently drifting back to
     // wall-clock (two services disagreeing about now breaks the world).
-    const clock = clockForm.parseClock(getActiveWorldStore().read(file) ?? '');
+    const clock = clockForm.parseClock(held);
     return new Date(clockForm.clockNowMs(clock, machineNow())).toISOString();
   }
   return new Date(machineNow()).toISOString();