@volter/world-core 3.0.155 → 3.0.157

package/src/managed-original-inputs.ts

@@ -0,0 +1,163 @@
+/** Source-bound files at a managed replacement. No vendor interpretation or host paths. */
+import * as nodeCrypto from 'node:crypto';
+const digest = (algorithm: 'sha1' | 'sha256', value: string | Uint8Array): string => nodeCrypto.createHash(algorithm).update(value).digest('hex');
+export interface OriginalInputReference {
+  version: 1;
+  /** Relative to the needs file, or to the World configuration after init copies it. */
+  root: string;
+  manifest: "manifest.json";
+  sha256: string;
+  inventoryDigest: string;
+}
+
+export interface OriginalInputCapability {
+  version: 1;
+  manifestArg: "--original-inputs";
+  rootArg: "--original-root";
+  digestArg: "--original-inputs-sha256";
+  /** Image paths whose complete overlay contents the consumer requires. */
+  paths: string[];
+}
+
+export interface OriginalInputEntry {
+  target: string;
+  type: "file" | "directory" | "link";
+  mode: number;
+  bytes?: number;
+  sha256?: string;
+  object?: string;
+  link?: string;
+  source: { kind: "image" | "project"; path: string; layer?: string; blob?: string };
+}
+
+export interface ManagedOriginalInputs {
+  kind: "volter.managed-original-inputs";
+  version: 1;
+  service: string;
+  family: string;
+  /** Canonical selected service declaration; used to refuse a different stack on reuse. */
+  declaration: string;
+  source: { image: string; manifest: string; config: string; layers: string[]; commit: string; compose: string; composeSha256: string; composeBytes: number; composeObject: string };
+  /** Authenticated complete image metadata, before the declared mounts overlay it. */
+  imageInventory: Array<{ target: string; type: string; mode: number; bytes: number; layer: string; link?: string }>;
+  imageInventoryDigest: string;
+  projectInventory: Array<{ path: string; mode: number; blob: string }>;
+  projectInventoryDigest: string;
+  roots: string[];
+  /** Complete contents beneath roots, plus every original project bind mount. */
+  inventory: OriginalInputEntry[];
+  inventoryDigest: string;
+  start: {
+    imageConfig: Record<string, unknown>;
+    service: Record<string, unknown>;
+    imageEntrypoint: string[] | null;
+    imageCommand: string[] | null;
+    command?: string[];
+    entrypoint?: string[];
+    environment: Record<string, string>;
+    envFiles: Array<{ path: string; bytes: number; sha256: string; object: string }>;
+    unset: string[];
+    selfHosts: string[];
+    mounts: Array<{ kind: string; source?: string; target: string; readOnly: boolean }>;
+  };
+}
+
+export const originalTarget = (path: string): boolean => path === "/" || (path.startsWith("/") && !path.slice(1).split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\]/u.test(part)));
+export const originalRelative = (path: string): boolean => !!path && !path.split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\:]/u.test(part));
+
+const hex = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const oci = (value: unknown): value is string => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const bytesOf = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
+const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every(entry => typeof entry === 'string' && !/[\0\r\n]/.test(entry));
+const bound = 128 * 1024 * 1024;
+
+export function referenceOf(value: unknown): OriginalInputReference {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Original inputs need a versioned reference');
+  const ref = value as OriginalInputReference;
+  if (ref.version !== 1 || ref.manifest !== 'manifest.json' || typeof ref.root !== 'string' || !originalRelative(ref.root) || !hex(ref.sha256) || !hex(ref.inventoryDigest)
+    || Object.keys(ref).some(key => !['version', 'root', 'manifest', 'sha256', 'inventoryDigest'].includes(key))) throw new Error('Invalid original-input reference');
+  return { ...ref };
+}
+
+/** Hash and validate neutral carrier data. The caller supplies I/O; no pack/vendor behavior or import effects. */
+export function readSnapshot(bytes: Uint8Array, expected: string, readObject: (path: string, bytes: number) => Uint8Array): { manifest: ManagedOriginalInputs; objects: ReadonlyMap<string, Uint8Array> } {
+  if (!(bytes instanceof Uint8Array) || bytes.length > 64 * 1024 * 1024 || !hex(expected) || digest('sha256', bytes) !== expected) throw new Error('Original-input manifest identity differs');
+  const manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as ManagedOriginalInputs;
+  const source = manifest.source, start = manifest.start;
+  if (manifest.kind !== 'volter.managed-original-inputs' || manifest.version !== 1 || typeof manifest.service !== 'string' || !manifest.service || typeof manifest.family !== 'string' || !/^[a-z][a-z0-9-]*$/.test(manifest.family)
+    || typeof manifest.declaration !== 'string' || !source || !/^[a-f0-9]{40}$/.test(source.commit) || !/^[A-Za-z0-9./:_-]+@sha256:[a-f0-9]{64}$/.test(source.image)
+    || !oci(source.manifest) || !oci(source.config) || !Array.isArray(source.layers) || !source.layers.every(oci) || !originalRelative(source.compose)
+    || !Array.isArray(manifest.imageInventory) || !Array.isArray(manifest.projectInventory) || !Array.isArray(manifest.inventory) || !strings(manifest.roots) || !manifest.roots.length || !manifest.roots.every(originalTarget) || new Set(manifest.roots).size !== manifest.roots.length
+    || !hex(manifest.imageInventoryDigest) || digest('sha256', JSON.stringify(manifest.imageInventory)) !== manifest.imageInventoryDigest
+    || !hex(manifest.inventoryDigest) || digest('sha256', JSON.stringify(manifest.inventory)) !== manifest.inventoryDigest
+    || !hex(manifest.projectInventoryDigest) || digest('sha256', JSON.stringify(manifest.projectInventory)) !== manifest.projectInventoryDigest
+    || !start || !start.imageConfig || typeof start.imageConfig !== 'object' || Array.isArray(start.imageConfig) || !start.service || typeof start.service !== 'object' || Array.isArray(start.service)
+    || !strings(start.selfHosts) || !start.selfHosts.length || !strings(start.unset) || !Array.isArray(start.envFiles) || !Array.isArray(start.mounts)
+    || !start.environment || typeof start.environment !== 'object' || Array.isArray(start.environment) || Object.entries(start.environment).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string')
+    || [start.imageEntrypoint, start.imageCommand].some(value => value !== null && !strings(value)) || [start.command, start.entrypoint].some(value => value !== undefined && !strings(value))) throw new Error('Invalid original-input manifest');
+  if (JSON.stringify(JSON.parse(manifest.declaration)) !== JSON.stringify(start.service) || start.service.name !== manifest.service
+    || JSON.stringify(start.command) !== JSON.stringify(start.service.command) || JSON.stringify(start.entrypoint) !== JSON.stringify(start.service.entrypoint)
+    || JSON.stringify(start.imageEntrypoint) !== JSON.stringify(start.imageConfig.Entrypoint ?? null) || JSON.stringify(start.imageCommand) !== JSON.stringify(start.imageConfig.Cmd ?? null)
+    || !Array.isArray(start.service.volumes)
+    || JSON.stringify(start.mounts.map(mount => [mount.kind, mount.source ?? null, mount.target, mount.readOnly])) !== JSON.stringify((start.service.volumes as ManagedOriginalInputs['start']['mounts']).map(mount => [mount.kind, mount.source ?? null, mount.target, mount.readOnly]))) throw new Error('Original-input start declaration differs');
+  const project = new Map<string, ManagedOriginalInputs['projectInventory'][number]>();
+  for (const entry of manifest.projectInventory) {
+    if (!entry || !originalRelative(entry.path) || project.has(entry.path) || ![0o100644, 0o100755, 0o120000, 0o160000].includes(entry.mode) || !/^[a-f0-9]{40}$/.test(entry.blob)) throw new Error('Invalid original project inventory');
+    project.set(entry.path, entry);
+  }
+  const image = new Map<string, ManagedOriginalInputs['imageInventory'][number]>();
+  for (const entry of manifest.imageInventory) {
+    if (!entry || !originalTarget(entry.target) || image.has(entry.target) || !['file', 'directory', 'link', 'other'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777 || !bytesOf(entry.bytes) || !source.layers.includes(entry.layer)
+      || (entry.type === 'link' && (typeof entry.link !== 'string' || /[\0\r\n\\]/.test(entry.link)))) throw new Error('Invalid original image inventory');
+    image.set(entry.target, entry);
+  }
+  const targets = new Set<string>(), selected = new Map<string, OriginalInputEntry>(), expectedObjects = new Map<string, number>();
+  const hold = (entry: { sha256?: string; bytes?: number; object?: string }): void => {
+    if (!hex(entry.sha256) || !bytesOf(entry.bytes) || entry.object !== `objects/${entry.sha256}` || (expectedObjects.has(entry.sha256) && expectedObjects.get(entry.sha256) !== entry.bytes)) throw new Error('Invalid original-input payload identity');
+    expectedObjects.set(entry.sha256, entry.bytes);
+  };
+  for (const entry of manifest.inventory) {
+    if (!entry || !originalTarget(entry.target) || targets.has(entry.target) || !['file', 'directory', 'link'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777 || !entry.source || !['image', 'project'].includes(entry.source.kind)) throw new Error('Invalid original-input inventory');
+    targets.add(entry.target);
+    selected.set(entry.target, entry);
+    if (entry.source.kind === 'image') {
+      const original = image.get(entry.source.path);
+      if (!original || original.layer !== entry.source.layer || original.type !== entry.type || original.mode !== entry.mode || (entry.type === 'file' && original.bytes !== entry.bytes) || (entry.type === 'link' && original.link !== entry.link)) throw new Error('Original-input image provenance differs');
+    } else {
+      const original = project.get(entry.source.path);
+      if (!originalRelative(entry.source.path) || (entry.type === 'file' && (!original || original.blob !== entry.source.blob || (original.mode & 0o777) !== entry.mode))) throw new Error('Original-input project provenance differs');
+    }
+    if (entry.type === 'file') hold(entry);
+    else if (entry.object !== undefined || entry.bytes !== undefined || entry.sha256 !== undefined || (entry.type === 'link' && (typeof entry.link !== 'string' || /[\0\r\n\\]/.test(entry.link)))) throw new Error('Invalid original-input non-file');
+  }
+  for (const mount of start.mounts) if (!mount || !['bind', 'named', 'anonymous'].includes(mount.kind) || !originalTarget(mount.target) || typeof mount.readOnly !== 'boolean' || (mount.source !== undefined && typeof mount.source !== 'string')) throw new Error('Invalid original-input mount declaration');
+  const roots = new Set(manifest.roots), mounted = new Set(start.mounts.filter(mount => mount.kind === 'bind').map(mount => mount.target));
+  const under = (path: string, roots: ReadonlySet<string>): boolean => {
+    for (let at = path;; at = at.slice(0, at.lastIndexOf('/')) || '/') {
+      if (roots.has(at)) return true;
+      if (at === '/') return false;
+    }
+  };
+  for (const entry of image.values()) if (under(entry.target, roots) && !under(entry.target, mounted)) {
+    const captured = selected.get(entry.target);
+    if (!captured || captured.source.kind !== 'image' || captured.source.path !== entry.target) throw new Error('Original image input was omitted from its declared root');
+  }
+  hold({ sha256: source.composeSha256, bytes: source.composeBytes, object: source.composeObject });
+  for (const file of start.envFiles) {
+    if (!file || !originalRelative(file.path)) throw new Error('Invalid original-input env_file');
+    hold(file);
+  }
+  if ([...expectedObjects.values()].reduce((sum, bytes) => sum + bytes, 0) > bound) throw new Error('Original-input snapshot exceeds its byte bound');
+  const objects = new Map<string, Uint8Array>();
+  for (const [sha256, size] of expectedObjects) {
+    const data = readObject(`objects/${sha256}`, size);
+    if (!(data instanceof Uint8Array) || data.length !== size || digest('sha256', data) !== sha256) throw new Error('Original-input payload bytes differ');
+    objects.set(sha256, data.slice());
+  }
+  for (const entry of manifest.inventory) if (entry.type === 'file' && entry.source.kind === 'project') {
+    const data = objects.get(entry.sha256!)!, header = new TextEncoder().encode(`blob ${data.length}\0`), blob = new Uint8Array(header.length + data.length);
+    blob.set(header); blob.set(data, header.length);
+    if (digest('sha1', blob) !== entry.source.blob) throw new Error('Original-input project blob identity differs');
+  }
+  return { manifest, objects };
+}

package/src/mongodb/client.ts

@@ -0,0 +1,27 @@
+// A MongoDB client over any byte exchange: the other side of ./stream.ts, so a journey speaks the wire as an
+// application's driver does. It sends one command document as an OP_MSG and returns the document the server
+// answered; it reads what the protocol answers and decides nothing.
+// source: archive:https://registry.npmjs.org/mongodb/-/mongodb-6.20.0.tgz#sha256=a12bd599cb4f39cdf222b32380ea3efd1f60c6d88615e0700632a303a9006b02!/package/src/cmap/commands.ts "moreToCome is an OP_MSG only concept"
+import { MongoOp, decodeMsg, encodeMsg, type MongoCodec, type MongoDocument } from './stream.ts';
+
+/** Sends bytes and returns every byte the server answered to them. */
+export type MongoExchange = (bytes: Uint8Array) => Promise<Uint8Array>;
+
+/** A client on one connection: `command` sends a document to `database` and resolves with the reply document,
+ *  whatever its `ok`. A reply that is not one whole OP_MSG answering this request is an error. */
+export function mongoClient(exchange: MongoExchange, codec: MongoCodec): { command(database: string, command: MongoDocument): Promise<MongoDocument> } {
+  let nextRequest = 0;
+  return {
+    async command(database, command) {
+      const requestId = ++nextRequest;
+      const answered = await exchange(encodeMsg(codec, { ...command, $db: database }, requestId, 0));
+      if (answered.length < 16) throw new Error('the server answered no message');
+      const view = new DataView(answered.buffer, answered.byteOffset, answered.byteLength);
+      const length = view.getInt32(0, true), responseTo = view.getInt32(8, true), opcode = view.getInt32(12, true);
+      if (length !== answered.length) throw new Error(`the server answered ${answered.length} bytes, and its message says ${length}`);
+      if (opcode !== MongoOp.MSG) throw new Error(`the server answered opcode ${opcode}, not OP_MSG`);
+      if (responseTo !== requestId) throw new Error(`the server answered request ${responseTo}, not ${requestId}`);
+      return decodeMsg(codec, answered).document;
+    },
+  };
+}

package/src/mongodb/index.ts

@@ -0,0 +1,5 @@
+// THE KERNEL'S MONGODB WIRE (`@volter/world-core/mongodb`): MongoDB's message framing as a TwinStream, and its client.
+// A pack that serves MongoDB passes what a command means (its engine) and the document codec; the kernel names no vendor.
+// docs/contributing/architecture.md, "Other wires", the MongoDB wire.
+export * from './stream.ts';
+export * from './client.ts';

package/src/mongodb/stream.ts

@@ -0,0 +1,223 @@
+// THE KERNEL'S MONGODB WIRE (`@volter/world-core/mongodb`): MongoDB's client/server message framing as a TwinStream,
+// so an unmodified MongoDB driver connects to a twin as to a server. The kernel holds the framing, which every
+// MongoDB-speaking vendor shares; the pack holds what a command means (it answers each command document from its own
+// engine over the tree) and the document codec (BSON, a library the pack installs). The messages served are what the
+// vendor's own driver sends, by citation (docs/contributing/architecture.md, "Other wires", the MongoDB wire): OP_MSG
+// with a body section and document-sequence sections, and the legacy OP_QUERY a driver's first hello may use, answered
+// with OP_REPLY. Any other message ends the connection.
+// source: archive:https://registry.npmjs.org/mongodb/-/mongodb-6.20.0.tgz#sha256=a12bd599cb4f39cdf222b32380ea3efd1f60c6d88615e0700632a303a9006b02!/package/src/cmap/commands.ts "moreToCome is an OP_MSG only concept"
+import type { TwinStream, TwinStreamSink } from '../twin-fetch.ts';
+
+/** A command or reply document as the pack's codec gives it: the pack decides how BSON's types appear in it. */
+export type MongoDocument = Record<string, unknown>;
+/** BSON, as the pack supplies it (the `bson` library, installed by the pack's package.json). The kernel frames
+ *  documents and never reads inside one but for a command's `$db`. */
+export type MongoCodec = { serialize(document: MongoDocument): Uint8Array; deserialize(bytes: Uint8Array): MongoDocument };
+/** What a pack's stream reads of the `bson` library its generated fetch's `loadBson` resolves from the pack: the codec,
+ *  extended JSON, and the number kinds a reply names. The kernel declares the shape and imports nothing of it. */
+export type BsonLibrary = {
+  serialize(document: MongoDocument): Uint8Array;
+  deserialize(bytes: Uint8Array, options?: { promoteValues?: boolean; promoteLongs?: boolean; bsonRegExp?: boolean }): MongoDocument;
+  EJSON: { serialize(value: unknown, options?: { relaxed?: boolean }): MongoDocument; deserialize(value: unknown, options?: { relaxed?: boolean }): MongoDocument };
+  Double: new (value: number) => unknown;
+  Int32: new (value: number) => unknown;
+  Long: { fromNumber(value: number): unknown };
+};
+
+/** What the sender's message said beside its command: whether it will take more than one reply to it (OP_MSG's exhaustAllowed). */
+export type MongoAsked = { exhaustAllowed: boolean };
+const TIMED = Symbol('mongodb timed reply');
+/**
+ * An answer the wire sends LATER, or goes on sending: the vendor's protocol does this in real time (an awaitable
+ * `hello` is held for the sender's maxAwaitTimeMS, and one sent with exhaustAllowed is answered again every such
+ * interval, each reply marked moreToCome). The pack says WHAT and WHEN as data and holds no clock: the same request
+ * gets the same answer every time. The wire does the holding and the repeating on the wall clock, and the delay is
+ * never read back into state (architecture, "The MongoDB wire").
+ */
+export type MongoTimedReply = { readonly [TIMED]: true; reply: MongoDocument; afterMs: number; everyMs?: number };
+/**
+ * `reply` after `afterMs` (0: at once); with `everyMs`, again each `everyMs` until the peer closes, where the sender
+ * allowed more than one reply. The two differ in the vendor's own answers: a hello naming the server's current
+ * topology is first answered after the wait, one naming another process at once, and both then repeat at the wait.
+ */
+export const timedReply = (reply: MongoDocument, afterMs: number, everyMs?: number): MongoTimedReply => ({ [TIMED]: true, reply, afterMs, ...(everyMs !== undefined ? { everyMs } : {}) });
+const isTimed = (answer: MongoDocument | MongoTimedReply): answer is MongoTimedReply => (answer as MongoTimedReply)[TIMED] === true;
+
+export type MongoStreamOptions<Session> = {
+  codec: MongoCodec;
+  /** A connection opened: what the pack keeps for it (its sessions, an open transaction); never the tree. */
+  open(peer: string): Session;
+  /** Answer ONE command document sent to `database`. A document sequence (an insert's `documents`, an update's
+   *  `updates`) arrives as that field holding the array. The answer is the reply document, `ok: 1` or the vendor's
+   *  error document; a command the pack does not serve is the pack's to answer as the vendor answers an unknown one. */
+  command(session: Session, database: string, command: MongoDocument, asked: MongoAsked): Promise<MongoDocument | MongoTimedReply>;
+  /** The connection went away: abort what it left open. */
+  close?(session: Session): void;
+  /** Told why a connection is ended by this stream and not by its peer: the pack threw answering a command, or a
+   *  message was one this wire does not serve. Ending the connection is all the wire can say to the client, so the
+   *  reason is said here; unset, it is written to the process's error output. A stream that ends connections in
+   *  silence leaves its operator with a client that hangs and nothing to read. */
+  ended?(reason: string, peer: string): void;
+  /** The largest message accepted; the vendor's server names 48,000,000 in its hello (`maxMessageSizeBytes`). */
+  maxMessageSizeBytes?: number;
+};
+
+export const MongoOp = { REPLY: 1, QUERY: 2004, MSG: 2013 } as const;
+/** OP_MSG's flag bits. */
+export const MongoMsgFlag = { CHECKSUM_PRESENT: 1 << 0, MORE_TO_COME: 1 << 1, EXHAUST_ALLOWED: 1 << 16 } as const;
+const HEADER = 16;
+const dec = new TextDecoder();
+const enc = new TextEncoder();
+
+const view = (bytes: Uint8Array): DataView => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+function concat(parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+function header(length: number, requestId: number, responseTo: number, opcode: number): Uint8Array {
+  const out = new Uint8Array(HEADER), v = view(out);
+  v.setInt32(0, length, true); v.setInt32(4, requestId, true); v.setInt32(8, responseTo, true); v.setInt32(12, opcode, true);
+  return out;
+}
+
+/** An OP_MSG message carrying one document as its body section. */
+export function encodeMsg(codec: MongoCodec, document: MongoDocument, requestId: number, responseTo: number, flags = 0): Uint8Array {
+  const body = codec.serialize(document), bits = new Uint8Array(5);
+  view(bits).setUint32(0, flags, true);
+  return concat([header(HEADER + 4 + 1 + body.length, requestId, responseTo, MongoOp.MSG), bits, body]);
+}
+/** The command of an OP_MSG message: its body section, with each document sequence as the field it names. */
+export function decodeMsg(codec: MongoCodec, message: Uint8Array): { flags: number; document: MongoDocument } {
+  const v = view(message), flags = v.getUint32(HEADER, true), end = message.length - (flags & MongoMsgFlag.CHECKSUM_PRESENT ? 4 : 0);
+  let document: MongoDocument | undefined; const sequences: Record<string, MongoDocument[]> = {};
+  for (let at = HEADER + 4; at < end;) {
+    const kind = message[at]!; at += 1;
+    if (kind === 0) {
+      const size = v.getInt32(at, true);
+      if (size < 5 || at + size > end) throw new Error('OP_MSG body section runs past the message');
+      document = codec.deserialize(message.subarray(at, at + size)); at += size;
+    } else if (kind === 1) {
+      const size = v.getInt32(at, true), stop = at + size;
+      if (size < 4 || stop > end) throw new Error('OP_MSG document sequence runs past the message');
+      const nameEnd = message.indexOf(0, at + 4);
+      if (nameEnd < 0 || nameEnd >= stop) throw new Error('OP_MSG document sequence names no field');
+      const name = dec.decode(message.subarray(at + 4, nameEnd)), documents: MongoDocument[] = [];
+      for (let cursor = nameEnd + 1; cursor < stop;) {
+        const length = v.getInt32(cursor, true);
+        if (length < 5 || cursor + length > stop) throw new Error('OP_MSG document sequence holds a document that runs past it');
+        documents.push(codec.deserialize(message.subarray(cursor, cursor + length))); cursor += length;
+      }
+      sequences[name] = documents; at = stop;
+    } else throw new Error(`OP_MSG section kind ${kind} is unknown`);
+  }
+  if (!document) throw new Error('OP_MSG carries no body section');
+  return { flags, document: { ...document, ...sequences } };
+}
+
+/** MongoDB's wire, served: each command document answered by the pack, in arrival order, on one connection. */
+export function createMongoStream<Session>(options: MongoStreamOptions<Session>): TwinStream {
+  const limit = options.maxMessageSizeBytes ?? 48_000_000;
+  let nextResponse = 0;
+  return (sink: TwinStreamSink, peer: string) => {
+    const session = options.open(peer);
+    let buffer: Uint8Array = new Uint8Array(0);
+    let closed = false;
+    let chain: Promise<void> = Promise.resolve();
+    // A reply being held or repeated (a timed reply): its timer, and the messages that arrived meanwhile. A
+    // connection serves one command at a time, so nothing else is answered until a held reply is sent, and nothing
+    // at all while a repeating one runs (recording:hello-awaitable-exhaust-then-command.json: a ping sent into the
+    // stream has no reply). The timer is not work: `settled` does not wait for it, it does not keep the process
+    // alive (unref), and a close from either side clears it at once.
+    let held: ReturnType<typeof setTimeout> | undefined;
+    const parked: Uint8Array[] = [];
+    const release = (): void => { if (held !== undefined) { clearTimeout(held); held = undefined; } parked.length = 0; };
+    const hold = (ms: number, then: () => void): void => {
+      held = setTimeout(() => { held = undefined; if (!closed) then(); }, Math.max(0, ms));
+      (held as { unref?: () => void }).unref?.();
+    };
+    const end = (reason: string): void => {
+      if (closed) return;
+      closed = true; release();
+      (options.ended ?? ((why, from) => console.error(`mongodb wire: ended the connection from ${from}: ${why}`)))(reason, peer);
+      options.close?.(session); sink.end();
+    };
+
+    const answer = async (message: Uint8Array): Promise<void> => {
+      const v = view(message), requestId = v.getInt32(4, true), opcode = v.getInt32(12, true);
+      if (opcode === MongoOp.MSG) {
+        const { flags, document } = decodeMsg(options.codec, message);
+        const database = typeof document.$db === 'string' ? document.$db : 'admin';
+        const exhaustAllowed = (flags & MongoMsgFlag.EXHAUST_ALLOWED) !== 0;
+        const answered = await options.command(session, database, document, { exhaustAllowed });
+        // the sender waits for no reply to a message it marked moreToCome
+        if (flags & MongoMsgFlag.MORE_TO_COME) return;
+        if (!isTimed(answered)) { sink.write(encodeMsg(options.codec, answered, ++nextResponse, requestId)); return; }
+        if (answered.everyMs === undefined || !exhaustAllowed) {
+          // held once: one reply after the wait, with no flag; then what arrived meanwhile is answered in order
+          // source: recording:hello-awaitable-no-exhaust.json "received"
+          hold(answered.afterMs, () => {
+            sink.write(encodeMsg(options.codec, answered.reply, ++nextResponse, requestId));
+            for (const message of parked.splice(0)) take(message);
+          });
+          return;
+        }
+        // repeated: each reply marked moreToCome; the first answers the request, each later one answers this
+        // wire's own previous reply, until the peer closes
+        // source: recording:hello-awaitable-exhaust.json "received"
+        let answers = requestId;
+        const again = (): void => {
+          const id = ++nextResponse;
+          sink.write(encodeMsg(options.codec, answered.reply, id, answers, MongoMsgFlag.MORE_TO_COME));
+          answers = id;
+          hold(answered.everyMs!, again);
+        };
+        // source: recording:hello-stale-process-exhaust.json "received" (the first at once, the rest at the wait)
+        hold(answered.afterMs, again);
+        return;
+      }
+      if (opcode === MongoOp.QUERY) {
+        // the legacy form a driver's first hello may take: a query on `<database>.$cmd` whose document is the command
+        const nameEnd = message.indexOf(0, HEADER + 4);
+        if (nameEnd < 0) throw new Error('OP_QUERY names no collection');
+        const namespace = dec.decode(message.subarray(HEADER + 4, nameEnd));
+        if (!namespace.endsWith('.$cmd')) throw new Error(`OP_QUERY on ${namespace}: only a command on <database>.$cmd is served`);
+        const command = options.codec.deserialize(message.subarray(nameEnd + 1 + 8));
+        // the legacy form has no flags of OP_MSG's: nothing is held or repeated for it
+        const legacy = await options.command(session, namespace.slice(0, -'.$cmd'.length), command, { exhaustAllowed: false });
+        const reply = options.codec.serialize(isTimed(legacy) ? legacy.reply : legacy);
+        // OP_REPLY: responseFlags (AwaitCapable), cursorID 0, startingFrom 0, numberReturned 1, then the document
+        const fixed = new Uint8Array(20), f = view(fixed);
+        f.setInt32(0, 8, true); f.setInt32(16, 1, true);
+        sink.write(concat([header(HEADER + 20 + reply.length, ++nextResponse, requestId, MongoOp.REPLY), fixed, reply]));
+        return;
+      }
+      throw new Error(`opcode ${opcode} is not served`);
+    };
+
+    // One message, in arrival order: parked while a reply is held, answered otherwise.
+    const take = (message: Uint8Array): void => {
+      chain = chain.then(() => (closed ? undefined : held !== undefined ? void parked.push(message) : answer(message))).catch((error) => end(error instanceof Error ? error.message : String(error)));
+    };
+    return {
+      data(chunk: Uint8Array): void {
+        if (closed) return;
+        buffer = buffer.length ? concat([buffer, chunk]) : chunk;
+        while (buffer.length >= 4) {
+          const length = view(buffer).getInt32(0, true);
+          // where the citation stops: what the vendor's server does with a malformed or oversized message is not
+          // read; this ends the connection, which no driver's well-formed message reaches
+          if (length < HEADER || length > limit) { end(`a message of ${length} bytes (accepted: ${HEADER} to ${limit})`); return; }
+          if (buffer.length < length) break;
+          const message = buffer.subarray(0, length); buffer = buffer.subarray(length);
+          take(message.slice());
+        }
+      },
+      settled: () => chain,
+      close: () => { if (!closed) { closed = true; release(); options.close?.(session); } },
+    };
+  };
+}
+
+/** The bytes of a C string, for a client's OP_QUERY. */
+export const cstring = (text: string): Uint8Array => concat([enc.encode(text), new Uint8Array(1)]);

package/src/observe.ts

@@ -145,5 +145,5 @@ function foldResources(service: string, resources: ObservedResource[], opts: { r
     }
   }
   return report;
-  });
+  }, { operation: 'observation batch' });
 }

package/src/pack-fetch.ts

@@ -1,4 +1,5 @@
 import { parseExactJson } from './exact-json.ts';
+import { redisServiceTimes } from './redis/service-times.ts';
 import { readHostPort } from './host-port.ts';
 // 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
@@ -11,7 +12,7 @@ import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
+import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type ScreenDecl, type VendorManifest } from './derived-core.ts';
 import { compileSurface, createDerivedFetch, matchOperation, pathParams, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
@@ -26,7 +27,7 @@ import { hostRules } from '../host-routing.cjs';
 
 /** A descriptor's host rules, as data. */
 type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
-import { socketUpgrade, type SocketEngine } from './sockets.ts';
+import { expireSocketWaits, socketUpgrade, type SocketEngine } from './sockets.ts';
 import { liveIngest } from './live/ingest.ts';
 import type { LiveEngine } from './live/types.ts';
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
@@ -143,6 +144,29 @@ function hostMatcher(pattern: string): (host: string) => Match | undefined {
 /** The host a request is for: the vendor host the World's injector names, else its own. */
 const hostOf = (request: Request): string => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
 
+/** Where a workspace asked `?show=<type>:<id>` opens the record (architecture, "Workspace"): the built workspace page
+ *  that shows that type, its parameter the id; else the one that lists the type; else the workspace's home (its root
+ *  page). Every other parameter a page's path names is the asking page's, and a page that cannot be filled is passed
+ *  over. Undefined when nothing is asked; the path (with no `show`) otherwise. */
+export function shownRecord(url: URL, workspaces: ReadonlyArray<ScreenDecl>, params: Record<string, string>): string | undefined {
+  const asked = /^([^:]+):(.+)$/.exec(url.searchParams.get('show') ?? '');
+  if (!asked) return undefined;
+  const [, type, id] = asked;
+  const fill = (path: string, extra: Record<string, string>): string | undefined => {
+    let unfilled = false;
+    const filled = path.replace(/\{([^}]+)\}|<([^>]+)>/g, (_, a?: string, b?: string) => {
+      const v = { ...params, ...extra }[(a ?? b)!];
+      if (v === undefined || v === '') { unfilled = true; return ''; }
+      return encodeURIComponent(v);
+    });
+    return unfilled ? undefined : filled;
+  };
+  const shows = workspaces.filter((s) => s.shows?.type === type).map((s) => fill(s.path, { [s.shows!.param]: id! })).find((p) => p !== undefined);
+  const lists = workspaces.filter((s) => s.lists?.includes(type!)).map((s) => fill(s.path, {})).find((p) => p !== undefined);
+  const home = workspaces.find((s) => s.path.replace(/\/+$/, '') === '') ? '/' : undefined;
+  return shows ?? lists ?? home ?? url.pathname;
+}
+
 /** The answer for a path no operation, door or screen serves, and for an operation nothing models: the manifest's
  *  `gap`, its `{method}` and `{path}` filled, else the manifest's not-found refusal. */
 function gapAnswer(m: DerivedManifest, request: Request, otherMethod = false): Response {
@@ -194,6 +218,16 @@ async function encoded(m: DerivedManifest, request: Request, res: Response): Pro
 /** A door's path as it is served and listed: under `/_twin/`, whether the manifest writes the prefix or not. */
 const doorPath = (path: string): string => (path.startsWith('/_twin/') ? path : `/_twin${path.startsWith('/') ? '' : '/'}${path}`);
 
+/** A request with its path's repeated slashes merged, as a front that merges them routes it (the manifest's
+ *  `mergeSlashes`); one with none is itself. */
+function slashesMerged(request: Request): Request {
+  const url = new URL(request.url);
+  const merged = url.pathname.replace(/\/{2,}/g, '/');
+  if (merged === url.pathname) return request;
+  url.pathname = merged;
+  return new Request(url, request);
+}
+
 export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}): DerivedFetch {
   const m = parts.manifest;
   const scope: CoreScope = {
@@ -310,8 +344,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     } catch { return false; }
   };
   // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
-  const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>): Promise<HandlerContext> =>
-    contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params }, scope);
+  const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>, streamed?: true): Promise<HandlerContext> =>
+    contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params, ...(streamed ? { streamed } : {}) }, scope);
   const advanceClock = async (request: Request): Promise<void> => {
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
   };
@@ -408,7 +442,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const asked = options.readOnly && !isReadOnlyRequest(there) ? withHeaders(there, new Headers([...there.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : there;
     if (method === 'POST' && ((options.readOnly ?? false) || isReadOnlyRequest(asked))) return refusedReadOnly();
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(asked.url, m.tenant ? { headers: asked.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
-    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }));
+    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }, true));
   };
   /** A request as the kernel reads it: the headers only the kernel names taken off, its body decoded (undefined when it
    *  does not decode as its Content-Encoding says). */
@@ -430,7 +464,9 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const readable = await prepared(arrived);
     return readable instanceof Response ? readable : readable ? atContentHost(readable) : undecodable(arrived);
   };
-  const fetch = async (arrived: Request): Promise<Response> => {
+  const fetch = async (received: Request): Promise<Response> => {
+    const arrived = m.mergeSlashes ? slashesMerged(received) : received;
+    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');
@@ -460,6 +496,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     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? } } }.' }] : [])];
@@ -496,6 +533,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
     // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
     await advanceClock(request);
+    // a reply a session awaits that the World's clock has run out (sockets.ts)
+    if (m.sockets?.length) expireSocketWaits(m.service, options.root);
     if (path.startsWith('/_twin/')) {
       // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
       if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
@@ -544,8 +583,10 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
       ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? (addressed ? undefined : hits.find((x) => !rooted(x))
         ?? (placed ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined)));
     if (byPath) {
+      const asked = byPath.s.decl.kind === 'workspace' && request.method === 'GET' ? shownRecord(url, screens.filter((x) => x.decl.kind === 'workspace').map((x) => x.decl), { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }) : undefined;
+      if (asked !== undefined && asked !== path) return new Response(null, { status: 302, headers: { location: `${(request.headers.get(TWIN_PREFIX_HEADER) ?? '').replace(/\/+$/, '')}${asked}` } });
       if (readOnly && request.method !== 'GET' && request.method !== 'HEAD') return refusedReadOnly();
-      return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }));
+      return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }, true));
     }
     for (const route of m.machineRoutes ?? []) {
       const host = request.headers.get('x-volter-twin-original-host') ?? new URL(request.url).hostname;
@@ -562,12 +603,19 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (!parts.around) 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' } as DerivedOperation);
+    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
@@ -612,7 +660,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   // request that opened it (operation `socket:<id>`)
   for (const d of m.sockets ?? []) if (!parts.sockets?.[d.id]) throw new Error(`${m.vendor}: the manifest declares the socket ${d.id}, and semantics/sockets.ts exports no ${d.id}`);
   const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets!,
-    (request, d) => open(request, `socket:${d.id}`, 'GET', d.path, {}), hostOf, (request) => new URL(routed(request).url).pathname,
+    (request, d, params) => open(request, `socket:${d.id}`, 'GET', d.path, params), hostOf, (request) => new URL(routed(request).url).pathname,
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
     async (asked) => engineOf()?.serve(asked)) : undefined;
   const upgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
@@ -743,8 +791,16 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
   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: Request): Promise<Response> => {
-    for (const part of Object.values(lanes)) await (part.fetch as typeof part.fetch & { advanceClock?: (request: Request) => Promise<void> }).advanceClock?.(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 as typeof part.fetch & { advanceClock?: (request: Request) => Promise<void> }).advanceClock?.(request);
     // 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: BoardFrame[] = [];
@@ -758,12 +814,6 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
       const draws = (url: string): boolean => 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) return Response.json({ vendor: manifest.vendor, lanes: laneScenarios });