@volter/world-core 3.0.155 → 3.0.157

package/src/pack-paths.ts

@@ -102,13 +102,17 @@ export function installedPackageDir(from: string, name: string): string | undefi
   }
 }
 
-/** A pack repository itself, or the P3 repository beside a platform checkout. Applications do not acquire a
+/** A pack repository itself, or a platform checkout's P3 repository: the one `VOLTER_PACKS` names (a worktree's own
+ *  pinned packs, as the repository's scripts read it), else the one beside it. Applications do not acquire a
  *  sibling checkout merely because one happens to be beside them. */
 export function packRepository(from: string): string | undefined {
   let dir = resolve(from);
   for (;;) {
     if (packageName(dir) === 'twin-packs-p3') return dir;
     if (packageName(join(dir, 'packages', 'world-core')) === '@volter/world-core') {
+      const env = globalThis.process?.env?.VOLTER_PACKS;
+      const named = env ? resolve(env) : undefined;
+      if (named && packageName(named) === 'twin-packs-p3') return named;
       const sibling = join(dirname(dir), 'twin-packs-p3');
       if (packageName(sibling) === 'twin-packs-p3') return sibling;
     }

package/src/packRegistry.ts

@@ -15,6 +15,8 @@ import type { DerivedManifest, VendorManifest } from './derived-core.ts';
 import type { DerivedSurface } from './derived.ts';
 import type { TwinEmitter } from './emit.ts';
 import { registerAuthStrategy, registerStateSystem, type StateSystemAdapters } from './state-system.ts';
+import { PROTOCOL_VERSION, protocolStanding } from './protocol.ts';
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './protocol.ts';
 
 /**
  * How a pack's clients ADDRESS it. The first three are HTTP API styles; `raw-tcp` is the
@@ -49,20 +51,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 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: string | undefined): { major: number; standing: 'current' | 'refused' } {
-  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'] as const;
 export type PackArchetype = (typeof PACK_ARCHETYPES)[number];
 
@@ -237,7 +225,7 @@ export type TwinPack = {
   /** Another pack of this vendor issues the API's credentials; architecture, descriptor World wiring. */
   credentialIssuer?: string;
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };
-  managedService?: { kind: 'redis' | 'mongodb'; scheme: string; note: string };
+  managedService?: { 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'; arg: string; note: string };
   sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; scheme?: string; note: string }>;
   stateSystem?: StateSystemAdapters;

package/src/protocol.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 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: string | undefined): { major: number; standing: 'current' | 'refused' } {
+  const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
+  return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { major, standing: 'refused' };
+}

package/src/redis/engine.ts

@@ -46,7 +46,8 @@
 import { createHash } from 'node:crypto';
 import { projectResources } from '../actions.ts';
 import { treeChangesSince, treeStamp } from '../log.ts';
-import { applyTwinWrite, type TwinResource } from '../serve.ts';
+import { redisServiceTimes as times } from './service-times.ts';
+import { applyTwinWrites, type TwinResource, type TwinWriteInput } from '../serve.ts';
 import { getActiveWorldStore } from '../world-store.ts';
 import { LUA_NULL, luaScriptSha1, LuaError, LuaTable, runLua, type LuaHost, type LuaValue } from './lua.ts';
 import { inlineCommand } from './frames.ts';
@@ -110,7 +111,7 @@ 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>; touched: Map<string, string>; scripts: Map<string, string>; touchedScripts: Map<string, string> };
+type Snapshot = { rows: OverlayState<KeyRow>; touched: Map<string, string>; scripts: OverlayState<string>; touchedScripts: Map<string, string> };
 
 export type KeyRow = {
   name: string;
@@ -399,29 +400,71 @@ function patchImage(image: KeyspaceImage, changed: readonly TwinResource[], remo
   return true;
 }
 
+const GONE: unique symbol = Symbol('gone');
+type OverlayState<V> = { own: Map<string, V | typeof GONE>; moved: Set<string> };
+/**
+ * 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<V> {
+  private own = new Map<string, V | typeof GONE>();
+  private moved = new Set<string>();
+  constructor(private readonly base: ReadonlyMap<string, V>) {}
+  get(key: string): V | undefined {
+    const mine = this.own.get(key);
+    return mine === GONE ? undefined : mine !== undefined || this.own.has(key) ? mine as V : this.base.get(key);
+  }
+  has(key: string): boolean { return this.own.has(key) ? this.own.get(key) !== GONE : this.base.has(key); }
+  set(key: string, value: V): void {
+    if (this.own.get(key) === GONE) { this.own.delete(key); this.moved.add(key); }
+    this.own.set(key, value);
+  }
+  delete(key: string): void {
+    this.own.delete(key);
+    this.moved.delete(key);
+    if (this.base.has(key)) this.own.set(key, GONE);
+  }
+  *entries(): IterableIterator<[string, V]> {
+    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(): IterableIterator<string> { for (const [key] of this.entries()) yield key; }
+  *values(): IterableIterator<V> { 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(): OverlayState<V> { return { own: new Map(this.own), moved: new Set(this.moved) }; }
+  load(state: OverlayState<V>): void { 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 {
-  private readonly rows: Map<string, KeyRow>;
+  private readonly rows: Overlay<KeyRow>;
   private readonly touched = new Map<string, string>(); // key → the operation label to record
-  private readonly scripts: Map<string, string>; // sha1 → script source (a SEPARATE namespace)
+  private readonly scripts: Overlay<string>; // sha1 → script source (a SEPARATE namespace)
   private readonly touchedScripts = new Map<string, string>();
   /** name → the last write ordinal seen, INCLUDING for keys currently deleted or expired. */
-  private readonly revs: Map<string, number>;
-  /** The keyspace as the tree held it when this run began: shared, never changed in place. */
+  private readonly revs: Overlay<number>;
+  /** The shared base maps are patched by the next image(); a KeySpace must finish reading its base before it yields. */
   readonly image: KeyspaceImage;
   constructor(readonly ctx: RedisContext, readonly nowMs: number) {
-    // 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.
@@ -470,15 +513,13 @@ export class KeySpace {
   }
   /** A point-in-time copy, so a failed script can be rolled back to exactly where it started. */
   snapshot(): 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: Snapshot): void {
-    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);
   }
@@ -524,39 +565,34 @@ export async function restoreKeyspace(image: readonly KeyImage[], ctx: RedisCont
 }
 
 async function flushKeySpace(space: KeySpace): Promise<void> {
+  // a run's writes land together, in this order, as they landed one at a time (serve.ts applyTwinWrites)
+  const writes: TwinWriteInput[] = [];
   for (const { name, operation, row } of space.pendingWrites()) {
-    await applyTwinWrite(
-      space.ctx.service,
-      {
-        operation,
-        subjectType: 'key',
-        subjectId: `${scopeOf(space.ctx)}key:${name}`,
-        // The kernel MERGES fields, so a delete must write EVERY field back to its "nothing here"
-        // value — leaving `v`/`pexpire_at` behind would let a later recreate inherit a dead value
-        // or a dead TTL.
-        fields: row === null
-          ? { name, kind: 'string', v: '', pexpire_at: null, last_id: '', gone: true, _rev: space.nextRev(name) }
-          : { name, kind: row.kind, v: row.v as never, pexpire_at: row.pexpireAt, last_id: row.lastId ?? '', gone: false, _rev: space.nextRev(name) },
-        occurredAt: space.ctx.occurredAt,
-        actor: { kind: 'agent' },
-      },
-      space.ctx.root,
-    );
+    writes.push({
+      operation,
+      subjectType: 'key',
+      subjectId: `${scopeOf(space.ctx)}key:${name}`,
+      // The kernel MERGES fields, so a delete must write EVERY field back to its "nothing here"
+      // value — leaving `v`/`pexpire_at` behind would let a later recreate inherit a dead value
+      // or a dead TTL.
+      fields: row === null
+        ? { name, kind: 'string', v: '', pexpire_at: null, last_id: '', gone: true, _rev: space.nextRev(name) }
+        : { name, kind: row.kind, v: row.v as never, pexpire_at: row.pexpireAt, last_id: row.lastId ?? '', gone: false, _rev: space.nextRev(name) },
+      occurredAt: space.ctx.occurredAt,
+      actor: { kind: 'agent' },
+    });
   }
   for (const { sha, operation, body } of space.pendingScriptWrites()) {
-    await applyTwinWrite(
-      space.ctx.service,
-      {
-        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,
-    );
+    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' },
+    });
   }
+  await applyTwinWrites(space.ctx.service, writes, space.ctx.root);
 }
 
 // ── typed value accessors (each asserts the key's type first) ─────────────────────────────────
@@ -1608,21 +1644,28 @@ export type RunItem = { result: RedisValue } | { error: string };
  * an unavailable command or a bad arity — are QUEUE-time and DO discard the whole batch, but the
  * caller (`upstash-twin.ts`) rejects those before this function is ever reached.
  */
-export async function execRedisRun(commands: string[][], ctx: RedisContext): Promise<{ items: RunItem[]; wrote: boolean; instant: number }> {
+export async function execRedisRun(commands: string[][], ctx: RedisContext): Promise<{ items: RunItem[]; wrote: boolean; instant: number; touched: string[] }> {
   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: RunItem[] = [];
-  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;
+  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;
+      }
     }
-  }
+  } 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/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/resource-blob.ts

@@ -1,5 +1,5 @@
 import { isAbsolute, join, relative } from 'node:path';
-import { getActiveBlobStore, readBlobRange } from './blob-store.ts';
+import { type BlobWritten, getActiveBlobStore, readBlobRange, streamChunks, writeBlobStream } from './blob-store.ts';
 import { readBranchMeta } from './log.ts';
 import { worldPaths } from './storage.ts';
 
@@ -19,6 +19,14 @@ export async function writeResourceBlob(service: string, key: string, bytes: Uin
   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: string, key: string, body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, accept: (written: BlobWritten) => boolean, root?: string): Promise<boolean> {
+  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: string, key: string, root?: string): Promise<void> {

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';