@volter/world-core 3.0.155 → 3.0.157

package/dist/src/managed-go-programs.d.ts

@@ -0,0 +1,55 @@
+export interface NativeGoKitReference {
+    package: {
+        name: string;
+        version: string;
+    };
+    target: 'wasm32-wali-go-single-thread';
+    releaseSha256: string;
+    producerSha256: string;
+    sourceSha256: string;
+    selection: {
+        path: string;
+        sha256: string;
+    };
+    recipe: {
+        path: string;
+        sha256: string;
+    };
+    installedRoot: string;
+}
+export interface NativeGoOperation {
+    sourceService: string;
+    role: 'server' | 'prerequisite' | 'health';
+    kit: string;
+    program: {
+        name: string;
+        version: string;
+        manifestId: string;
+        manifestSha256: string;
+        path: string;
+    };
+    /** Resolved arguments require separate comparison with the full source. */
+    args: string[];
+    /** Names of existing World values, never caller secrets in this record. */
+    environmentBindings: Record<string, string>;
+    requires: {
+        service: string;
+        condition: 'service_started' | 'service_healthy' | 'service_completed_successfully';
+    }[];
+}
+export interface NativeGoReference {
+    version: 2;
+    implementation: string;
+    release: string;
+    directory: string;
+    snapshotSha256: string;
+    declarationSha256: string;
+    image: string;
+    kits: Record<string, NativeGoKitReference>;
+    server: NativeGoOperation;
+    prerequisites: NativeGoOperation[];
+    health: NativeGoOperation;
+}
+/** All fields are declared data. The later owned consumer must authenticate
+ * the complete source, kit, original image and admitted installed manifests. */
+export declare function nativeGoReference(value: unknown): NativeGoReference;

package/dist/src/managed-go-programs.js

@@ -0,0 +1,133 @@
+/** Tagged managed Go operation metadata. This structural reader grants no
+ * source/image correspondence, filesystem custody, catalog admission or exec. */
+import { posix } from 'node:path';
+const fail = (field) => { throw new Error('Native Go operation metadata is invalid: ' + field); };
+function object(value, fields, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail(label);
+    const row = value;
+    if (Object.keys(row).length !== fields.length || fields.some(key => !Object.hasOwn(row, key)))
+        return fail(label);
+    return row;
+}
+function text(value, label) {
+    if (typeof value !== 'string' || !value || value.includes('\0'))
+        return fail(label);
+    return value;
+}
+function digest(value, label) {
+    const out = text(value, label);
+    if (!/^[a-f0-9]{64}$/u.test(out))
+        return fail(label);
+    return out;
+}
+function relativePath(value, label) {
+    const out = text(value, label);
+    if (out.startsWith('/') || out.includes('\\') || posix.normalize(out) !== out
+        || out.split('/').some(part => !part || part === '.' || part === '..'))
+        return fail(label);
+    return out;
+}
+function installedPath(value, label) {
+    const out = text(value, label);
+    if (!out.startsWith('/opt/programs/') || out.includes('\\') || posix.normalize(out) !== out
+        || out.split('/').slice(1).some(part => !part || part === '.' || part === '..'))
+        return fail(label);
+    return out;
+}
+function pin(value, label) {
+    const row = object(value, ['path', 'sha256'], label);
+    return { path: relativePath(row.path, label + '.path'), sha256: digest(row.sha256, label + '.sha256') };
+}
+function kit(value, label) {
+    const row = object(value, ['package', 'target', 'releaseSha256', 'producerSha256', 'sourceSha256', 'selection', 'recipe', 'installedRoot'], label);
+    const pack = object(row.package, ['name', 'version'], label + '.package');
+    if (row.target !== 'wasm32-wali-go-single-thread')
+        return fail(label + '.target');
+    return { package: { name: text(pack.name, label + '.package.name'), version: text(pack.version, label + '.package.version') },
+        target: row.target, releaseSha256: digest(row.releaseSha256, label + '.releaseSha256'),
+        producerSha256: digest(row.producerSha256, label + '.producerSha256'), sourceSha256: digest(row.sourceSha256, label + '.sourceSha256'),
+        selection: pin(row.selection, label + '.selection'), recipe: pin(row.recipe, label + '.recipe'),
+        installedRoot: installedPath(row.installedRoot, label + '.installedRoot') };
+}
+function operation(value, role, kits, label) {
+    const row = object(value, ['sourceService', 'role', 'kit', 'program', 'args', 'environmentBindings', 'requires'], label);
+    const selected = text(row.kit, label + '.kit');
+    if (row.role !== role || !Object.hasOwn(kits, selected))
+        return fail(label + '.role/kit');
+    const provider = kits[selected];
+    const command = object(row.program, ['name', 'version', 'manifestId', 'manifestSha256', 'path'], label + '.program');
+    const path = installedPath(command.path, label + '.program.path'), version = text(command.version, label + '.program.version');
+    if (version !== provider.package.version || !path.startsWith(provider.installedRoot + '/'))
+        return fail(label + '.program placement/version');
+    if (!Array.isArray(row.args))
+        return fail(label + '.args');
+    const args = [];
+    for (const arg of row.args) {
+        if (typeof arg !== 'string' || arg.includes('\0'))
+            return fail(label + '.args.' + args.length);
+        args.push(arg);
+    }
+    if (!row.environmentBindings || typeof row.environmentBindings !== 'object' || Array.isArray(row.environmentBindings))
+        return fail(label + '.environmentBindings');
+    const bindings = Object.create(null);
+    for (const [name, value] of Object.entries(row.environmentBindings)) {
+        const source = text(value, label + '.environmentBindings.' + name);
+        if (![name, source].every(item => /^[A-Za-z_][A-Za-z0-9_]*$/u.test(item)))
+            return fail(label + '.environmentBindings name');
+        bindings[name] = source;
+    }
+    if (!Array.isArray(row.requires))
+        return fail(label + '.requires');
+    const dependencies = [];
+    for (const value of row.requires) {
+        const edge = object(value, ['service', 'condition'], label + '.requires');
+        if (edge.condition !== 'service_started' && edge.condition !== 'service_healthy' && edge.condition !== 'service_completed_successfully')
+            return fail(label + '.requires.condition');
+        const service = text(edge.service, label + '.requires.service');
+        if (dependencies.some(prior => prior.service === service))
+            return fail(label + '.requires duplicate service');
+        dependencies.push({ service, condition: edge.condition });
+    }
+    return { sourceService: text(row.sourceService, label + '.sourceService'), role, kit: selected,
+        program: { name: text(command.name, label + '.program.name'), version, manifestId: text(command.manifestId, label + '.program.manifestId'),
+            manifestSha256: digest(command.manifestSha256, label + '.program.manifestSha256'), path },
+        args, environmentBindings: bindings, requires: dependencies };
+}
+/** All fields are declared data. The later owned consumer must authenticate
+ * the complete source, kit, original image and admitted installed manifests. */
+export function nativeGoReference(value) {
+    const row = object(value, ['version', 'implementation', 'release', 'directory', 'snapshotSha256', 'declarationSha256', 'image', 'kits', 'server', 'prerequisites', 'health'], 'reference');
+    if (row.version !== 2)
+        return fail('version');
+    const image = text(row.image, 'image');
+    if (!/^[^\s@]+@sha256:[a-f0-9]{64}$/u.test(image))
+        return fail('image');
+    if (!row.kits || typeof row.kits !== 'object' || Array.isArray(row.kits) || !Object.keys(row.kits).length)
+        return fail('kits');
+    const kits = Object.create(null);
+    for (const [name, value] of Object.entries(row.kits))
+        kits[text(name, 'kit name')] = kit(value, 'kits.' + name);
+    const server = operation(row.server, 'server', kits, 'server'), health = operation(row.health, 'health', kits, 'health');
+    const implementation = text(row.implementation, 'implementation'), release = text(row.release, 'release');
+    if (kits[server.kit].package.name !== implementation || kits[server.kit].package.version !== release
+        || health.sourceService !== server.sourceService)
+        return fail('server/health implementation');
+    if (!Array.isArray(row.prerequisites))
+        return fail('prerequisites');
+    const prerequisites = [];
+    for (const value of row.prerequisites)
+        prerequisites.push(operation(value, 'prerequisite', kits, 'prerequisites.' + prerequisites.length));
+    if (new Set(prerequisites.map(item => item.sourceService)).size !== prerequisites.length
+        || prerequisites.some(item => item.sourceService === server.sourceService))
+        return fail('prerequisite service');
+    const usedKits = new Set([server.kit, health.kit, ...prerequisites.map(item => item.kit)]);
+    if (Object.keys(kits).some(name => !usedKits.has(name)))
+        return fail('unconsumed kit');
+    for (const item of prerequisites)
+        if (!server.requires.some(edge => edge.service === item.sourceService && edge.condition === 'service_completed_successfully'))
+            return fail('server prerequisite completion edge');
+    return { version: 2, implementation, release, directory: relativePath(row.directory, 'directory'),
+        snapshotSha256: digest(row.snapshotSha256, 'snapshotSha256'), declarationSha256: digest(row.declarationSha256, 'declarationSha256'),
+        image, kits, server, prerequisites, health };
+}

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,97 @@
+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 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;
+};
+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 {};