@volter/world-core 3.0.154 → 3.0.156

package/dist/src/pack-fetch.js

@@ -1,4 +1,5 @@
 import { parseExactJson } from "./exact-json.js";
+import { redisServiceTimes } from "./redis/service-times.js";
 import { readHostPort } from "./host-port.js";
 // A Protocol 3 pack's whole HTTP surface, served by the kernel from the pack's declarations (docs/contributing/
 // architecture.md, "The pack contract: the kernel's root"): the discovery door (`GET /twin`, the manifest's
@@ -160,7 +161,7 @@ export function createPackFetch(parts, options = {}) {
     // the GraphQL wire over the same state, at the paths the manifest names (graphql-wire.ts)
     const gql = m.graphql && parts.graphql ? m.graphql : undefined;
     const graphql = gql && parts.graphql ? graphqlEndpoint({
-        sdl: parts.graphql.sdl, part: parts.graphql,
+        sdl: parts.graphql.sdl, part: parts.graphql, loadLibrary: parts.graphql.loadLibrary,
         context: async (request) => contextFor(m, { request: request.clone(), operation: { id: 'graphql', method: 'POST', path: gql.paths[0], class: 'action' }, params: {} }, scope),
         unmodeled: ({ type, field }) => Response.json({ errors: [{ ...(gql.unmodeled.type ? { type: gql.unmodeled.type } : {}), message: gql.unmodeled.message.replace('{field}', field).replace('{type}', type) }] }, { status: gql.unmodeled.status ?? 200 }),
         mutationRefused: (request) => ((options.readOnly ?? false) || isReadOnlyRequest(request) ? vendorError(m, m.readOnly) : undefined),
@@ -393,6 +394,7 @@ export function createPackFetch(parts, options = {}) {
         return readable instanceof Response ? readable : readable ? atContentHost(readable) : undecodable(arrived);
     };
     const fetch = async (arrived) => {
+        redisServiceTimes.lap('1 request made by the stream');
         // the discovery door is the pack's own, whichever lane would take its path
         const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
         const discovery = arrived.method === 'GET' && m.discovery !== undefined && (asked === '/twin' || asked === '/twin/scenario');
@@ -427,6 +429,7 @@ export function createPackFetch(parts, options = {}) {
         const url = new URL(request.url);
         const path = url.pathname.replace(/\/+$/, '') || '/';
         const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
+        redisServiceTimes.lap('2 content and lane routes, decoding, routing');
         if (request.method === 'GET' && path === '/twin' && m.discovery) {
             const d = m.discovery;
             const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
@@ -549,12 +552,19 @@ export function createPackFetch(parts, options = {}) {
             return encoded(m, request, await decided(request));
         // The front reads a context before forwarding (possibly with new headers). Materialize a transport body before
         // those independent reads, rather than chaining tees of the incoming stream through the front and the scenario.
+        redisServiceTimes.lap('3 doors, screens and machine routes passed');
         const bytes = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
         const buffered = new Request(request.url, { method: request.method, headers: request.headers, signal: request.signal, ...(bytes ? { body: bytes } : {}) });
         const matched = matchOperation(routes, buffered.method, url.pathname, url.searchParams, buffered.headers);
         const operation = matched?.operation ?? { id: 'unmatched', method: buffered.method, path: url.pathname, class: buffered.method === 'GET' ? 'retrieve' : 'action' };
+        redisServiceTimes.lap('4 body buffered, operation matched');
         const ctx = await contextFor(m, { request: buffered.clone(), operation, params: matched?.params ?? pathParams(routes, url.pathname) }, scope);
-        return encoded(m, buffered, await parts.around(ctx, (rewritten) => decided(rewritten ?? buffered)));
+        redisServiceTimes.lap('5 the around context opened');
+        const answered = await parts.around(ctx, (rewritten) => decided(rewritten ?? buffered));
+        redisServiceTimes.lap('6d the handler, and the around after it');
+        const sent = await encoded(m, buffered, answered);
+        redisServiceTimes.lap('7 answer encoded');
+        return sent;
     };
     // the request's id is the correlation of every entry it appends (runtime contract D3), minted here, always: it is the
     // group a perform sends as one call (the real-system adapters, "Perform"). Under `auto` the group is performed once
@@ -739,9 +749,17 @@ export function createVendorFetch(manifest, lanes) {
     const ingest = Object.values(lanes).find((l) => l.fetch.ingest)?.fetch.ingest;
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+        // the discovery door is answered before any lane's clock moves, as a pack's own is (createPackFetch): reading what
+        // the twin is moves no vendor clock
+        if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
+            // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
+            const screens = lanesWorkspaces(lanes);
+            const laneDiscovery = await laneDoors(lanes, request, '/twin');
+            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) });
+        }
         for (const part of Object.values(lanes))
             await part.fetch.advanceClock?.(request);
-        const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
         // the vendor's board is the frames of the lanes that lay one out, each drawn when any lane's screen takes its url
         if (request.method === 'GET' && path === '/twin/board') {
             const frames = [];
@@ -758,12 +776,6 @@ export function createVendorFetch(manifest, lanes) {
             const draws = (url) => Object.values(lanes).some((l) => l.fetch.draws?.(url) ?? false);
             return Response.json({ frames: frames.map((f) => ({ ...f, drawn: draws(f.url) })) });
         }
-        if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
-            // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
-            const screens = lanesWorkspaces(lanes);
-            const laneDiscovery = await laneDoors(lanes, request, '/twin');
-            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) });
-        }
         if (request.method === 'GET' && path === '/twin/scenario') {
             const laneScenarios = await laneDoors(lanes, request, '/twin/scenario');
             if (Object.keys(laneScenarios).length)

package/dist/src/packRegistry.d.ts

@@ -5,6 +5,7 @@ import type { DerivedManifest } from './derived-core.js';
 import type { DerivedSurface } from './derived.js';
 import type { TwinEmitter } from './emit.js';
 import { type StateSystemAdapters } from './state-system.js';
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './protocol.js';
 /**
  * How a pack's clients ADDRESS it. The first three are HTTP API styles; `raw-tcp` is the
  * RAW-PROTOCOL class — a pack whose clients speak their protocol directly over a TCP socket
@@ -37,19 +38,6 @@ export type PackTransport = 'rest' | 'graphql' | 'web-api' | 'raw-tcp';
  *                       seam (fly's runtime, github's git plane, supabase's external stack).
  *   'proxy'           — the vendor itself is a forwarding plane (tunnel).
  */
-/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
- *  descriptor shape, the factory signature, the doors and the adapter contract a package is
- *  written against, and the build form it is made in (the derived pack); a change that removes or
- *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
- *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
- *  declares another, or none, is refused. */
-export declare const PROTOCOL_VERSION = "3.0";
-export declare const PROTOCOL_MAJOR: number;
-/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
-export declare function protocolStanding(declared: string | undefined): {
-    major: number;
-    standing: 'current' | 'refused';
-};
 export declare const PACK_ARCHETYPES: readonly ["crud", "generative", "signed-protocol", "engine-control", "proxy"];
 export type PackArchetype = (typeof PACK_ARCHETYPES)[number];
 /**
@@ -223,9 +211,17 @@ export type TwinPack = {
         urlEnv: string;
     };
     managedService?: {
-        kind: 'redis' | 'mongodb';
+        kind: string;
         scheme: string;
         note: string;
+        configurationArg?: '--configuration';
+        originalInputs?: {
+            version: 1;
+            manifestArg: '--original-inputs';
+            rootArg: '--original-root';
+            digestArg: '--original-inputs-sha256';
+            paths: string[];
+        };
     };
     managedDatabase?: {
         kind: 'postgres';

package/dist/src/packRegistry.js

@@ -11,6 +11,8 @@ import { declareRateBudget } from "./rateBudget.js";
 import { referenceField, registerReferences } from "./references.js";
 import { deriveStateSystem, deriveVendorStateSystem } from "./derived-real.js";
 import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
+import { PROTOCOL_VERSION, protocolStanding } from "./protocol.js";
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./protocol.js";
 /**
  * The pack's SERVE-FAMILY — the axis the invariant matrix keys strictness off, DECLARED
  * because it is the pack's own claim about what kind of thing it is (a heuristic over file
@@ -26,19 +28,6 @@ import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
  *                       seam (fly's runtime, github's git plane, supabase's external stack).
  *   'proxy'           — the vendor itself is a forwarding plane (tunnel).
  */
-/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
- *  descriptor shape, the factory signature, the doors and the adapter contract a package is
- *  written against, and the build form it is made in (the derived pack); a change that removes or
- *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
- *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
- *  declares another, or none, is refused. */
-export const PROTOCOL_VERSION = '3.0';
-export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
-/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
-export function protocolStanding(declared) {
-    const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
-    return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { major, standing: 'refused' };
-}
 export const PACK_ARCHETYPES = ['crud', 'generative', 'signed-protocol', 'engine-control', 'proxy'];
 /** The posture to assume for a pack that doesn't declare one. Conservative on purpose. */
 export const DEFAULT_PULL_POSTURE = 'on-demand';

package/dist/src/protocol.d.ts

@@ -0,0 +1,13 @@
+/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
+ *  descriptor shape, the factory signature, the doors and the adapter contract a package is
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export declare const PROTOCOL_VERSION = "3.0";
+export declare const PROTOCOL_MAJOR: number;
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
+export declare function protocolStanding(declared: string | undefined): {
+    major: number;
+    standing: 'current' | 'refused';
+};

package/dist/src/protocol.js

@@ -0,0 +1,13 @@
+/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
+ *  descriptor shape, the factory signature, the doors and the adapter contract a package is
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export const PROTOCOL_VERSION = '3.0';
+export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
+export function protocolStanding(declared) {
+    const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
+    return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { major, standing: 'refused' };
+}

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

@@ -45,9 +45,9 @@ type StoredZSet = Array<[string, string]>;
 export type StreamEntries = Array<[string, HashPairs]>;
 /** A point-in-time copy of a run's whole mutable state, for script rollback. */
 type Snapshot = {
-    rows: Map<string, KeyRow>;
+    rows: OverlayState<KeyRow>;
     touched: Map<string, string>;
-    scripts: Map<string, string>;
+    scripts: OverlayState<string>;
     touchedScripts: Map<string, string>;
 };
 export type KeyRow = {
@@ -168,12 +168,17 @@ export type KeyspaceImage = {
     scripts: Map<string, string>;
     revs: Map<string, number>;
 };
+declare const GONE: unique symbol;
+type OverlayState<V> = {
+    own: Map<string, V | typeof GONE>;
+    moved: Set<string>;
+};
 /**
  * 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 declare class KeySpace {
@@ -185,7 +190,7 @@ export declare class KeySpace {
     private readonly touchedScripts;
     /** name → the last write ordinal seen, INCLUDING for keys currently deleted or expired. */
     private readonly 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. */
     readonly image: KeyspaceImage;
     constructor(ctx: RedisContext, nowMs: number);
     /**
@@ -323,5 +328,6 @@ export declare function execRedisRun(commands: string[][], ctx: RedisContext): P
     items: RunItem[];
     wrote: boolean;
     instant: number;
+    touched: string[];
 }>;
 export {};

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;