@volter/world-core 3.0.155 → 3.0.157

package/dist/src/redis/engine.js

@@ -46,7 +46,8 @@
 import { createHash } from 'node:crypto';
 import { projectResources } from "../actions.js";
 import { treeChangesSince, treeStamp } from "../log.js";
-import { applyTwinWrite } from "../serve.js";
+import { redisServiceTimes as times } from "./service-times.js";
+import { applyTwinWrites } from "../serve.js";
 import { getActiveWorldStore } from "../world-store.js";
 import { LUA_NULL, luaScriptSha1, LuaError, LuaTable, runLua } from "./lua.js";
 import { inlineCommand } from "./frames.js";
@@ -311,12 +312,68 @@ function patchImage(image, changed, removed, scope) {
     }
     return true;
 }
+const GONE = Symbol('gone');
+/**
+ * A run's map over the shared image: what the run changed is its own, the rest is read through. Copying the whole image
+ * per run (and again per script, for its rollback) cost every command the size of the keyspace (S2 R19: Twenty's queue
+ * twin, its queue scripts waiting behind each other's copies). Iteration is a `new Map(base)` changed in place's: the
+ * base's order with its changed values, then the keys added, a base key deleted and set again among them at its set.
+ */
+class Overlay {
+    base;
+    own = new Map();
+    moved = new Set();
+    constructor(base) {
+        this.base = base;
+    }
+    get(key) {
+        const mine = this.own.get(key);
+        return mine === GONE ? undefined : mine !== undefined || this.own.has(key) ? mine : this.base.get(key);
+    }
+    has(key) { return this.own.has(key) ? this.own.get(key) !== GONE : this.base.has(key); }
+    set(key, value) {
+        if (this.own.get(key) === GONE) {
+            this.own.delete(key);
+            this.moved.add(key);
+        }
+        this.own.set(key, value);
+    }
+    delete(key) {
+        this.own.delete(key);
+        this.moved.delete(key);
+        if (this.base.has(key))
+            this.own.set(key, GONE);
+    }
+    *entries() {
+        for (const [key, value] of this.base) {
+            if (this.moved.has(key))
+                continue;
+            if (!this.own.has(key)) {
+                yield [key, value];
+                continue;
+            }
+            const mine = this.own.get(key);
+            if (mine !== GONE)
+                yield [key, mine];
+        }
+        for (const [key, mine] of this.own)
+            if (mine !== GONE && (!this.base.has(key) || this.moved.has(key)))
+                yield [key, mine];
+    }
+    *keys() { for (const [key] of this.entries())
+        yield key; }
+    *values() { for (const [, value] of this.entries())
+        yield value; }
+    /** What the run changed, copied: a rollback point the size of the changes, not of the keyspace. */
+    save() { return { own: new Map(this.own), moved: new Set(this.moved) }; }
+    load(state) { this.own = new Map(state.own); this.moved = new Set(state.moved); }
+}
 /**
  * A synchronous, in-memory image of the keyspace for the duration of ONE request.
  *
  * Seeded from the keyspace's image (the tree folded by `projectResources`, memoized per World state — the kernel IS
  * the source of truth); every mutation records the key name in `touched`, and the flush writes exactly those keys
- * back. This run's maps are its own copies: nothing a run changes reaches the image or a later request except
+ * back. This run owns its overlays: nothing a run changes reaches the image or a later request except
  * through the tree.
  */
 export class KeySpace {
@@ -328,16 +385,16 @@ export class KeySpace {
     touchedScripts = new Map();
     /** name → the last write ordinal seen, INCLUDING for keys currently deleted or expired. */
     revs;
-    /** The keyspace as the tree held it when this run began: shared, never changed in place. */
+    /** The shared base maps are patched by the next image(); a KeySpace must finish reading its base before it yields. */
     image;
     constructor(ctx, nowMs) {
         this.ctx = ctx;
         this.nowMs = nowMs;
-        // the image is shared and never changed in place; this run's maps are its own
+        // The base maps are patched by the next image(); finish reading this run's base before yielding.
         const image = this.image = ctx.dialect.storage?.image(ctx) ?? keyspaceImageOf(ctx);
-        this.rows = new Map(image.rows);
-        this.scripts = new Map(image.scripts);
-        this.revs = new Map(image.revs);
+        this.rows = new Overlay(image.rows);
+        this.scripts = new Overlay(image.scripts);
+        this.revs = new Overlay(image.revs);
     }
     /**
      * Is this row expired AS OF NOW? Checked on every read, not merely when the snapshot was built.
@@ -394,18 +451,14 @@ export class KeySpace {
     }
     /** A point-in-time copy, so a failed script can be rolled back to exactly where it started. */
     snapshot() {
-        return { rows: new Map(this.rows), touched: new Map(this.touched), scripts: new Map(this.scripts), touchedScripts: new Map(this.touchedScripts) };
+        return { rows: this.rows.save(), touched: new Map(this.touched), scripts: this.scripts.save(), touchedScripts: new Map(this.touchedScripts) };
     }
     restore(s) {
-        this.rows.clear();
-        for (const [k, v] of s.rows)
-            this.rows.set(k, v);
+        this.rows.load(s.rows);
         this.touched.clear();
         for (const [k, v] of s.touched)
             this.touched.set(k, v);
-        this.scripts.clear();
-        for (const [k, v] of s.scripts)
-            this.scripts.set(k, v);
+        this.scripts.load(s.scripts);
         this.touchedScripts.clear();
         for (const [k, v] of s.touchedScripts)
             this.touchedScripts.set(k, v);
@@ -447,8 +500,10 @@ export async function restoreKeyspace(image, ctx) {
     await flushKeySpace(space);
 }
 async function flushKeySpace(space) {
+    // a run's writes land together, in this order, as they landed one at a time (serve.ts applyTwinWrites)
+    const writes = [];
     for (const { name, operation, row } of space.pendingWrites()) {
-        await applyTwinWrite(space.ctx.service, {
+        writes.push({
             operation,
             subjectType: 'key',
             subjectId: `${scopeOf(space.ctx)}key:${name}`,
@@ -460,18 +515,19 @@ async function flushKeySpace(space) {
                 : { name, kind: row.kind, v: row.v, pexpire_at: row.pexpireAt, last_id: row.lastId ?? '', gone: false, _rev: space.nextRev(name) },
             occurredAt: space.ctx.occurredAt,
             actor: { kind: 'agent' },
-        }, space.ctx.root);
+        });
     }
     for (const { sha, operation, body } of space.pendingScriptWrites()) {
-        await applyTwinWrite(space.ctx.service, {
+        writes.push({
             operation,
             subjectType: 'script',
             subjectId: `${scopeOf(space.ctx)}script:${sha}`,
             fields: body === null ? { sha, body: '', gone: true } : { sha, body, gone: false },
             occurredAt: space.ctx.occurredAt,
             actor: { kind: 'agent' },
-        }, space.ctx.root);
+        });
     }
+    await applyTwinWrites(space.ctx.service, writes, space.ctx.root);
 }
 // ── typed value accessors (each asserts the key's type first) ─────────────────────────────────
 export function expectType(row, kind) {
@@ -1905,23 +1961,38 @@ export async function execRedisRun(commands, ctx) {
     const nowMs = Date.parse(ctx.occurredAt);
     if (!Number.isFinite(nowMs))
         throw new RedisCommandError(`ERR twin: unparseable occurredAt '${ctx.occurredAt}'`);
-    const space = new KeySpace(ctx, nowMs);
+    // The phases a served command's time is counted in (service-times.ts): the image, the commands, their writes.
+    const space = times.timed('image', () => new KeySpace(ctx, nowMs));
     const items = [];
-    for (const argv of commands) {
-        try {
-            items.push({ result: execOne(space, argv) });
-        }
-        catch (e) {
-            if (e instanceof ReadOnlyError)
-                throw e; // surfaces as HTTP 405 for the whole request
-            if (e instanceof RedisCommandError) {
-                items.push({ error: e.message });
-                continue;
+    const began = times.now();
+    try {
+        for (const argv of commands) {
+            try {
+                items.push({ result: execOne(space, argv) });
+            }
+            catch (e) {
+                if (e instanceof ReadOnlyError)
+                    throw e; // surfaces as HTTP 405 for the whole request
+                if (e instanceof RedisCommandError) {
+                    items.push({ error: e.message });
+                    continue;
+                }
+                throw e;
             }
-            throw e;
         }
     }
+    finally {
+        times.add('execute', times.now() - began);
+    }
     const wrote = space.dirty;
-    await (space.ctx.dialect.storage?.flush(space) ?? flushKeySpace(space));
-    return { items, wrote, instant: nowMs };
+    // The keys this run wrote, by name, read before the flush clears them: a stream wakes only the clients blocked on one.
+    const touched = space.touchedNames();
+    const flushing = times.now();
+    try {
+        await (space.ctx.dialect.storage?.flush(space) ?? flushKeySpace(space));
+    }
+    finally {
+        times.add('flush', times.now() - flushing);
+    }
+    return { items, wrote, instant: nowMs, touched };
 }

package/dist/src/redis/member-storage.js

@@ -1,12 +1,14 @@
 // 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.js";
+import { applyTwinWrites } from "../serve.js";
 import { projectResources } from "../actions.js";
 import { treeStamp, treeChangesSince } from "../log.js";
 import { getActiveWorldStore } from "../world-store.js";
 const scope = (c) => c.database === undefined ? '' : `db:${c.database}:`;
 const collections = new Set(['hash', 'set', 'zset', 'stream', 'list']);
+// `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();
 const members = (r) => !r || !collections.has(r.kind) ? new Map() : new Map(r.v.map((x, i) => r.kind === 'list' ? [String(i), x] : r.kind === 'set' ? [x, x] : [x[0], x[1]]));
 const memberId = (c, name, field) => `${scope(c)}member:${createHash('sha256').update(JSON.stringify([name, field])).digest('hex')}`;
@@ -21,9 +23,16 @@ export const memberStorage = {
             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 = { 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();
         const changed = delta && !delta.removed.length ? delta.changed : [...h.subjects.values()];
@@ -50,7 +59,7 @@ export const memberStorage = {
                 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;
@@ -59,17 +68,20 @@ export const memberStorage = {
     },
     async flush(space) {
         const ctx = space.ctx;
-        const write = async (type, id, operation, fields) => 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 = [];
+        const write = (type, id, operation, fields) => { 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 });
+            write('script', `${scope(ctx)}script:${sha}`, operation, { sha, body: body ?? '', gone: body === null });
+        await applyTwinWrites(ctx.service, writes, ctx.root);
     },
 };

package/dist/src/redis/service-times.d.ts

@@ -0,0 +1,25 @@
+type Phase = 'image' | 'execute' | 'flush' | 'reply' | 'run';
+type Command = {
+    session: number;
+    command: string;
+};
+export declare const redisServiceTimes: {
+    now: () => number;
+    /** 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;
+    /** Time of the open command in one phase. */
+    add(phase: Phase, ms: number): void;
+    wrote(): void;
+    /** A run begins: its first stretch is counted from here. */
+    lapFrom(): void;
+    /** The stretch of the open command's run that ends here, by name. Outside a served command it is nothing. */
+    lap(name: string): void;
+    /** A run has ended: nothing after it is a stretch of it. */
+    lapEnd(name: string): void;
+    /** The open command has answered (or blocked, or failed with its error answered). */
+    end(threw?: boolean): void;
+    /** `work`, its time counted in `phase` of the open command. */
+    timed<T>(phase: Phase, work: () => T): T;
+    phases: readonly Phase[];
+};
+export {};

package/dist/src/redis/service-times.js

@@ -0,0 +1,87 @@
+const PHASES = ['image', 'execute', 'flush', 'reply', 'run'];
+const SAY_EVERY_MS = 2000;
+const now = () => performance.now();
+const fresh = () => ({ 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;
+let timer;
+let served = 0;
+function say() {
+    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) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * share))];
+    const ms = (value) => 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, waiting, command) {
+        open = { received, started: now(), command };
+        if (waiting > window.queueMax)
+            window.queueMax = waiting;
+        if (!timer) {
+            timer = setTimeout(say, SAY_EVERY_MS);
+            timer.unref?.();
+        }
+    },
+    /** Time of the open command in one phase. */
+    add(phase, ms) { if (open) {
+        window.phases[phase] += ms;
+        if (phase === 'run')
+            window.runs += 1;
+    } },
+    wrote() { if (open)
+        window.writes += 1; },
+    /** A run begins: its first stretch is counted from here. */
+    lapFrom() { lapAt = now(); },
+    /** The stretch of the open command's run that ends here, by name. Outside a served command it is nothing. */
+    lap(name) { 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) { this.lap(name); lapAt = 0; },
+    /** The open command has answered (or blocked, or failed with its error answered). */
+    end(threw = false) {
+        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(phase, work) { const began = now(); try {
+        return work();
+    }
+    finally {
+        this.add(phase, now() - began);
+    } },
+    phases: PHASES,
+};

package/dist/src/redis/stream.d.ts

@@ -9,6 +9,7 @@ export type RedisStreamOptions = {
         items: RunItem[];
         wrote: boolean;
         instant?: number;
+        touched?: string[];
     }>;
 };
-export declare function createRedisStream(options: RedisStreamOptions): TwinStream;
+export declare function createRedisStream(given: RedisStreamOptions): TwinStream;

package/dist/src/redis/stream.js

@@ -1,15 +1,38 @@
 import { RedisStatus, commandInteger, commandShapeError, globMatch } from "./engine.js";
 import { binaryBytes, binaryText, inlineCommand, readResp, respReply } from "./frames.js";
-export function createRedisStream(options) {
+import { worldNow } from "../world-clock.js";
+import { redisServiceTimes as times } from "./service-times.js";
+export function createRedisStream(given) {
+    // The pack's run, its time counted for the command it serves (service-times.ts).
+    const options = { ...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);
+        } } };
     const sessions = new Set();
-    let nextId = 0, commandCount = 0;
+    let nextId = 0, commandCount = 0, waiting = 0;
     let serial = Promise.resolve();
     const ordered = (f) => { const p = serial.then(f); serial = p.catch(() => { }); return p; };
     const error = (message) => ({ error: message });
     const ok = new RedisStatus('OK');
-    const answer = (s, v) => { if (!s.closed)
-        s.sink.write(binaryBytes(respReply(v))); };
-    const close = (s) => { s.closed = true; if (s.blocked?.timer)
+    const connectionTrace = (s, stage, command) => {
+        try {
+            console.error('[redis-twin-connection]', JSON.stringify({ at: performance.timeOrigin + times.now(), pid: globalThis.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, v) => { if (!s.closed) {
+        times.timed('reply', () => s.sink.write(binaryBytes(respReply(v))));
+        s.answered += 1;
+    } };
+    const close = (s) => { if (!s.closed)
+        connectionTrace(s, 'closed'); s.closed = true; if (s.blocked?.timer)
         clearTimeout(s.blocked.timer); sessions.delete(s); };
     const unblock = (s, v) => { if (s.blocked?.timer)
         clearTimeout(s.blocked.timer); s.blocked = undefined; answer(s, v); queueMicrotask(() => { void s.pump?.(); }); };
@@ -26,12 +49,26 @@ export function createRedisStream(options) {
         }
         throw new Error('the blocking command has no executor');
     };
-    const wake = async () => { for (const s of sessions)
-        if (s.blocked) {
+    // 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) => {
+        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, argv, executing = false) => {
         if (!argv.length || s.closed)
             return;
@@ -272,12 +309,32 @@ export function createRedisStream(options) {
                 }
                 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); };
+                // 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 = () => {
+                    if (!s.blocked || s.closed || s.blocked.deadline === Infinity)
+                        return;
+                    let left;
+                    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;
             }
@@ -286,17 +343,45 @@ export function createRedisStream(options) {
                 const item = res.items[0];
                 answer(s, 'error' in item ? item : item.result);
                 if (res.wrote && !executing)
-                    await wake();
+                    await wake(CROSS_DATABASE.has(cmd) ? undefined : res.touched);
             }
         }
     };
     return (sink) => {
-        const s = { id: ++nextId, name: '', lib: {}, database: '0', authenticated: !options.password, queue: null, dirty: false, subscriptions: new Set(), patterns: new Set(), sink, closed: false };
+        const s = { 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.resolve();
         const pending = [];
-        const pump = async () => { while (pending.length && !s.blocked && !s.closed)
-            await ordered(() => command(s, pending.shift())); };
+        // 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)
@@ -321,7 +406,11 @@ export function createRedisStream(options) {
                         end = at + 2;
                     }
                     buffer = buffer.slice(end);
-                    pending.push(argv);
+                    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);
             }
@@ -331,7 +420,7 @@ export function createRedisStream(options) {
                 sink.end();
             } },
             settled: () => chain,
-            close: () => close(s),
+            close: () => { waiting -= pending.length; pending.length = 0; close(s); },
         };
     };
 }

package/dist/src/resource-blob.d.ts

@@ -1,7 +1,11 @@
+import { type BlobWritten } from './blob-store.js';
 /** Read a resource payload at this branch, then its retained ancestors. */
 export declare function readResourceBlob(service: string, key: string, root?: string): Promise<Uint8Array | null>;
 /** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
 export declare function writeResourceBlob(service: string, key: string, bytes: Uint8Array, root?: string): Promise<void>;
+/** Write a resource payload on this branch from a body as it arrives (a model's weights, an upload's bytes), kept only
+ *  when `accept` holds for its size and SHA-256 (the blob seam's `writeBlobStream`). True when kept. */
+export declare function writeResourceBlobStream(service: string, key: string, body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, accept: (written: BlobWritten) => boolean, root?: string): Promise<boolean>;
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export declare function removeResourceBlob(service: string, key: string, root?: string): Promise<void>;

package/dist/src/resource-blob.js

@@ -1,5 +1,5 @@
 import { isAbsolute, join, relative } from 'node:path';
-import { getActiveBlobStore, readBlobRange } from "./blob-store.js";
+import { getActiveBlobStore, readBlobRange, streamChunks, writeBlobStream } from "./blob-store.js";
 import { readBranchMeta } from "./log.js";
 import { worldPaths } from "./storage.js";
 /** Read a resource payload at this branch, then its retained ancestors. */
@@ -17,6 +17,13 @@ export async function writeResourceBlob(service, key, bytes, root) {
     assertResourceKey(key);
     await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
+/** Write a resource payload on this branch from a body as it arrives (a model's weights, an upload's bytes), kept only
+ *  when `accept` holds for its size and SHA-256 (the blob seam's `writeBlobStream`). True when kept. */
+export async function writeResourceBlobStream(service, key, body, accept, root) {
+    assertResourceKey(key);
+    const chunks = body instanceof ReadableStream ? streamChunks(body) : body;
+    return writeBlobStream(resourceBlobFile(worldPaths(service, root).resources, key), chunks, accept);
+}
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service, key, root) {

package/dist/src/runtime-state.d.ts

@@ -0,0 +1,11 @@
+export { getActiveWorldStore, removeCarriedLocks } from './world-store.js';
+export type { WorldStore } from './world-store.js';
+export { stateDirName, withFileLock, worldPaths, worldStateRoot, WORLD_DATA_ENV } from './storage.js';
+export { assertStateRemovable, withAncestryLock, withStateRemoval } from './ancestry.js';
+export { readBranchMeta } from './log.js';
+export { volterHome } from './volter-home.js';
+export { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository, vendorOfPackModule } from './pack-paths.js';
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './protocol.js';
+export { WORLD_BOOT_PATH } from './serve-http.js';
+export { WORLD_ENV_NAMES_ENV } from './world-env.js';
+export { beginPlaceholderPull, endPlaceholderPull, placeholderPullActive } from './placeholder-remote.js';