@volter/world-core 3.0.154 → 3.0.156

package/dist/src/managed-original-inputs.d.ts

@@ -0,0 +1,101 @@
+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 declare const originalTarget: (path: string) => boolean;
+export declare const originalRelative: (path: string) => boolean;
+export declare function referenceOf(value: unknown): OriginalInputReference;
+/** Hash and validate neutral carrier data. The caller supplies I/O; no pack/vendor behavior or import effects. */
+export declare function readSnapshot(bytes: Uint8Array, expected: string, readObject: (path: string, bytes: number) => Uint8Array): {
+    manifest: ManagedOriginalInputs;
+    objects: ReadonlyMap<string, Uint8Array>;
+};

package/dist/src/managed-original-inputs.js

@@ -0,0 +1,125 @@
+/** Source-bound files at a managed replacement. No vendor interpretation or host paths. */
+import * as nodeCrypto from 'node:crypto';
+const digest = (algorithm, value) => nodeCrypto.createHash(algorithm).update(value).digest('hex');
+export const originalTarget = (path) => path === "/" || (path.startsWith("/") && !path.slice(1).split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\]/u.test(part)));
+export const originalRelative = (path) => !!path && !path.split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\:]/u.test(part));
+const hex = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const oci = (value) => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const bytesOf = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+const strings = (value) => Array.isArray(value) && value.every(entry => typeof entry === 'string' && !/[\0\r\n]/.test(entry));
+const bound = 128 * 1024 * 1024;
+export function referenceOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Original inputs need a versioned reference');
+    const ref = value;
+    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, expected, readObject) {
+    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));
+    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.map(mount => [mount.kind, mount.source ?? null, mount.target, mount.readOnly])))
+        throw new Error('Original-input start declaration differs');
+    const project = new Map();
+    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();
+    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(), selected = new Map(), expectedObjects = new Map();
+    const hold = (entry) => {
+        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, roots) => {
+        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();
+    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/dist/src/mongodb/client.d.ts

@@ -0,0 +1,8 @@
+import { type MongoCodec, type MongoDocument } from './stream.js';
+/** 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 declare function mongoClient(exchange: MongoExchange, codec: MongoCodec): {
+    command(database: string, command: MongoDocument): Promise<MongoDocument>;
+};

package/dist/src/mongodb/client.js

@@ -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 } from "./stream.js";
+/** 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, codec) {
+    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/dist/src/mongodb/index.d.ts

@@ -0,0 +1,2 @@
+export * from './stream.js';
+export * from './client.js';

package/dist/src/mongodb/index.js

@@ -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.js";
+export * from "./client.js";

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

@@ -0,0 +1,74 @@
+import type { TwinStream } from '../twin-fetch.js';
+/** 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 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;
+};
+declare const TIMED: unique symbol;
+/**
+ * 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 declare const timedReply: (reply: MongoDocument, afterMs: number, everyMs?: number) => MongoTimedReply;
+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 declare const MongoOp: {
+    readonly REPLY: 1;
+    readonly QUERY: 2004;
+    readonly MSG: 2013;
+};
+/** OP_MSG's flag bits. */
+export declare const MongoMsgFlag: {
+    readonly CHECKSUM_PRESENT: number;
+    readonly MORE_TO_COME: number;
+    readonly EXHAUST_ALLOWED: number;
+};
+/** An OP_MSG message carrying one document as its body section. */
+export declare function encodeMsg(codec: MongoCodec, document: MongoDocument, requestId: number, responseTo: number, flags?: number): Uint8Array;
+/** The command of an OP_MSG message: its body section, with each document sequence as the field it names. */
+export declare function decodeMsg(codec: MongoCodec, message: Uint8Array): {
+    flags: number;
+    document: MongoDocument;
+};
+/** MongoDB's wire, served: each command document answered by the pack, in arrival order, on one connection. */
+export declare function createMongoStream<Session>(options: MongoStreamOptions<Session>): TwinStream;
+/** The bytes of a C string, for a client's OP_QUERY. */
+export declare const cstring: (text: string) => Uint8Array;
+export {};

package/dist/src/mongodb/stream.js

@@ -0,0 +1,206 @@
+const TIMED = Symbol('mongodb timed reply');
+/**
+ * `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, afterMs, everyMs) => ({ [TIMED]: true, reply, afterMs, ...(everyMs !== undefined ? { everyMs } : {}) });
+const isTimed = (answer) => answer[TIMED] === true;
+export const MongoOp = { REPLY: 1, QUERY: 2004, MSG: 2013 };
+/** OP_MSG's flag bits. */
+export const MongoMsgFlag = { CHECKSUM_PRESENT: 1 << 0, MORE_TO_COME: 1 << 1, EXHAUST_ALLOWED: 1 << 16 };
+const HEADER = 16;
+const dec = new TextDecoder();
+const enc = new TextEncoder();
+const view = (bytes) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+function concat(parts) {
+    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, requestId, responseTo, opcode) {
+    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, document, requestId, responseTo, flags = 0) {
+    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, message) {
+    const v = view(message), flags = v.getUint32(HEADER, true), end = message.length - (flags & MongoMsgFlag.CHECKSUM_PRESENT ? 4 : 0);
+    let document;
+    const sequences = {};
+    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 = [];
+            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(options) {
+    const limit = options.maxMessageSizeBytes ?? 48_000_000;
+    let nextResponse = 0;
+    return (sink, peer) => {
+        const session = options.open(peer);
+        let buffer = new Uint8Array(0);
+        let closed = false;
+        let chain = 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;
+        const parked = [];
+        const release = () => { if (held !== undefined) {
+            clearTimeout(held);
+            held = undefined;
+        } parked.length = 0; };
+        const hold = (ms, then) => {
+            held = setTimeout(() => { held = undefined; if (!closed)
+                then(); }, Math.max(0, ms));
+            held.unref?.();
+        };
+        const end = (reason) => {
+            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) => {
+            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 = () => {
+                    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) => {
+            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) {
+                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) => concat([enc.encode(text), new Uint8Array(1)]);

package/dist/src/observe.js

@@ -162,5 +162,5 @@ function foldResources(service, resources, opts) {
             }
         }
         return report;
-    });
+    }, { operation: 'observation batch' });
 }

package/dist/src/pack-fetch.d.ts

@@ -5,7 +5,7 @@ import type { ApplicationStandIn } from './events.js';
 import { type SocketEngine } from './sockets.js';
 import type { LiveEngine } from './live/types.js';
 import type { WebSocketUpgrade } from './serve-http.js';
-import { type GraphqlPart } from './graphql-wire.js';
+import { type GraphqlPart, type GraphqlLibraryLoader } from './graphql-wire.js';
 /** What a pack declares and writes, and nothing it assembles itself. */
 export type PackParts = {
     manifest: DerivedManifest;
@@ -39,6 +39,7 @@ export type PackParts = {
      *  state, served at the manifest's `graphql.paths` (graphql-wire.ts). */
     graphql?: GraphqlPart<HandlerContext> & {
         sdl: string;
+        loadLibrary?: GraphqlLibraryLoader;
     };
     /** `semantics/sockets.ts`: each socket's engine, by the id the manifest's `sockets` gives it (sockets.ts). */
     sockets?: Record<string, SocketEngine<HandlerContext>>;