@volter/twin-standard 1.0.147 → 1.0.149

package/src/protocol-3.ts

@@ -88,7 +88,7 @@ function filesUnder(dir: string, base = dir): string[] {
     if (run.status !== 0 || run.error) {
       throw new Error(`git ls-files failed: directory=${JSON.stringify(top)} status=${run.status} signal=${JSON.stringify(run.signal)} error=${JSON.stringify(run.error?.message ?? null)} stderr=${JSON.stringify(String(run.stderr ?? ''))}`);
     }
-    files = [...new Set(String(run.stdout).split('\0').filter(Boolean))];
+    files = [...new Set(String(run.stdout).split('\0').filter(f => f && !f.split('/').includes('.metadata_never_index')))];
     listing?.set(top, files);
   }
   const under = rel(top, dir);
@@ -100,6 +100,8 @@ function allFilesUnder(dir: string, base = dir, excludeArtifacts = false): strin
   if (!existsSync(dir)) return [];
   const out: string[] = [];
   for (const name of readdirSync(dir)) {
+    // macOS directory bookkeeping is not a pack source or release output.
+    if (name === '.metadata_never_index') continue;
     const path = join(dir, name);
     if (excludeArtifacts && isPackArtifact(rel(base, path))) continue;
     if (statSync(path).isDirectory()) out.push(...allFilesUnder(path, base, excludeArtifacts));
@@ -275,7 +277,9 @@ const criteria: Criterion[] = [
       }
       // the pack's own path and the scratch directory are this checkout's, not the pack's: the verdict names neither, so
       // a standing written from one checkout reads the same from any other
-      if (run.status !== 0) return fail(`derive-pack refused: ${String(run.stderr || run.stdout).split(unit.dir).join('.').split(tmp).join('<out>').trim().split('\n').slice(-2).join(' ').slice(0, 200)}`);
+      if (run.status === null || run.signal !== null || run.error) return { pass: false, cacheable: false,
+        reason: `derive-pack interrupted: status=${run.status} signal=${run.signal} error=${run.error?.message ?? ''}` };
+      if (run.status !== 0) return { ...fail(`derive-pack refused: ${String(run.stderr || run.stdout).split(unit.dir).join('.').split(tmp).join('<out>').trim().split('\n').slice(-2).join(' ').slice(0, 200)}`), cacheable: run.status === 2 };
       return changed.length ? fail(`derive-pack writes differently: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ` and ${changed.length - 5} more` : ''}`) : pass(`${filesUnder(gen).length} files reproduced`);
     },
   },
@@ -452,7 +456,7 @@ const criteria: Criterion[] = [
   },
   {
     id: 'kernel-contract', section: 'form',
-    asks: "every file of src/ imports the kernel through its root, the pack contract, and nothing past it: no `@volter/world-core/runtime` or other entry (cli.ts alone takes args and lifecycle), no node builtin, no other package but @volter/world-ui",
+    asks: "every file of src/ imports the kernel through its root, the pack contract, and nothing past it: no `@volter/world-core/runtime` or other entry (cli.ts alone takes args and lifecycle), no node builtin, no other package but @volter/world-ui and the generated GraphQL library loader",
     check(unit) {
       const src = join(unit.dir, 'src');
       if (!existsSync(src)) return fail('src/ is missing');
@@ -460,7 +464,29 @@ const criteria: Criterion[] = [
       for (const f of filesUnder(src).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x) && !x.startsWith('generated/'))) {
         // the file's imports, re-exports and dynamic imports as TypeScript reads them (a string that only reads like one,
         // an error message's "from '<name>'", is none)
-        const specifiers = ts.preProcessFile(readFileSync(join(src, f), 'utf8'), true, true).importedFiles.map((i) => i.fileName);
+        let text = readFileSync(join(src, f), 'utf8');
+        if (f === 'fetch.ts') {
+          // The generated fetch supplies the kernel wire with the pack-local parser library.
+          // Exempt only that exact factory part; other static or dynamic imports still count.
+          const source = ts.createSourceFile(f, text, ts.ScriptTarget.Latest, true);
+          const loaders: Array<{ start: number; end: number }> = [];
+          const visit = (node: ts.Node): void => {
+            if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+              node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0]!) && node.arguments[0]!.text === 'graphql') {
+              const arrow = node.parent, property = arrow.parent;
+              const graphql = property.parent?.parent, factory = graphql?.parent?.parent;
+              if (ts.isArrowFunction(arrow) && arrow.parameters.length === 0 && arrow.body === node &&
+                ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'loadLibrary' &&
+                graphql && ts.isPropertyAssignment(graphql) && ts.isIdentifier(graphql.name) && graphql.name.text === 'graphql' &&
+                factory && ts.isCallExpression(factory) && ts.isIdentifier(factory.expression) && factory.expression.text === 'createPackFetch' &&
+                factory.arguments[0] === graphql.parent) loaders.push({ start: node.getStart(source), end: node.end });
+            }
+            ts.forEachChild(node, visit);
+          };
+          visit(source);
+          for (const loader of loaders.sort((a, b) => b.start - a.start)) text = text.slice(0, loader.start) + 'undefined' + text.slice(loader.end);
+        }
+        const specifiers = ts.preProcessFile(text, true, true).importedFiles.map((i) => i.fileName);
         for (const from of specifiers) {
           if (from.startsWith('.')) continue;
           if (from === '@volter/world-core' || from === '@volter/world-ui') continue;
@@ -530,13 +556,13 @@ const criteria: Criterion[] = [
       const manifestPath = join(unit.dir, 'src', 'manifest.ts');
       const statesPath = join(unit.dir, 'src', 'semantics', 'states.ts');
       let manifest: { resources?: Record<string, { state?: unknown; notState?: unknown }> } | undefined;
-      try { manifest = ((await import(manifestPath)) as { manifest?: typeof manifest }).manifest; } catch (e) { return fail(`manifest.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      try { manifest = ((await import(manifestPath)) as { manifest?: typeof manifest }).manifest; } catch (e) { return { ...fail(`manifest.ts does not load: ${(e as Error).message.slice(0, 120)}`), cacheable: false }; }
       const resources = Object.entries(manifest?.resources ?? {});
       const ruled = resources.filter(([, r]) => (r.state && Object.keys(r.state as object).length) || (Array.isArray(r.notState) && r.notState.length));
       if (!ruled.length) return pass('the pack declares no state machine and rules no candidate');
       if (!existsSync(statesPath)) return fail(`${ruled.length} resources carry states or rulings, and there is no semantics/states.ts`);
       let states: Record<string, { state?: unknown; notState?: unknown }> | undefined;
-      try { states = ((await import(statesPath)) as { states?: typeof states }).states; } catch (e) { return fail(`semantics/states.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      try { states = ((await import(statesPath)) as { states?: typeof states }).states; } catch (e) { return { ...fail(`semantics/states.ts does not load: ${(e as Error).message.slice(0, 120)}`), cacheable: false }; }
       if (!states) return fail('semantics/states.ts exports no `states`');
       const off = ruled.filter(([name, r]) => (r.state !== undefined && r.state !== states![name]?.state) || (r.notState !== undefined && r.notState !== states![name]?.notState)).map(([name]) => name);
       return off.length ? fail(`resources whose states or rulings are not states.ts's own: ${off.join(', ')}`) : pass(`${ruled.length} resources, their states and rulings from states.ts`);

package/src/spec-ir-client.ts

@@ -1,8 +1,9 @@
 // A vendor that publishes no spec of its API but ships its own client: the API as that client calls it. Tinybird
 // publishes no OpenAPI of its platform API (its reference pages omit endpoints its own CLI calls: /v0/tags,
 // /v0/sql_tables), and its Python client (`tinybird/client.py`, class TinyB, in tinybird-cli on PyPI) makes every
-// request through `_req(url, method=..., data=...)`. Each such call, read from the client's syntax tree (the pack's
-// `spec/extract-client-ops.py`), is vendored as data in `spec/client-ops.json`: its method, its URL as the client
+// request through `_req(url, method=..., data=...)`. Each such call, read from the client's syntax tree, is vendored as
+// data in `spec/client-ops.json` (the program that read it is not in the pack: a pack keeps no converter in its
+// `spec/`, Creating a pack, step 2): its method, its URL as the client
 // builds it (a label is the Python expression the client interpolates), the query keys it sends (literal, or the keys
 // of the dict it urlencodes) and its body's keys, each typed by the client's own annotation of the value (`null`
 // where the client does not say). A spec patch corrects the table as it corrects a JSON spec (derive-pack): what the

package/src/spec-ir-commands.ts

@@ -48,3 +48,84 @@ export function fromRedisCommands(files: Record<string, RedisCommandFile>, versi
   commands.sort((a, b) => a.id.localeCompare(b.id));
   return { format: 'command-table', version, commands };
 }
+
+// ── A command language whose commands are DOCUMENTS ─────────────────────────────────────────────────────────────
+// A command of MongoDB's wire protocol is not words with an arity: it is a document whose first key names the
+// command and whose other keys are named fields, some of them lists of statements (an update's `updates`) with
+// fields of their own, and every command also carries the fields the layers under it add (the session's, the
+// connection's). The vendor publishes no table of these that a pack may derive from (its reference and its driver
+// specifications are licensed NonCommercial); its own client is Apache-2.0 and builds every one of them. So the
+// table is the client's statement: the client's syntax tree is read by a program (as Tinybird's Python client's is,
+// spec-ir-client.ts) and what it read is the pack's vendored document, `spec/command-builders.json`; this reads that
+// data into the command table. The program is kept beside that document in the pack's `spec/`, as the table's
+// provenance, and is never a kernel script (Creating a pack, step 2).
+//
+// What the table says and does not: which commands a client can send and, for each, every field, its declared
+// type, and the condition the client sends it under. It says nothing of what a server does with them. A field's
+// condition is recorded, never evaluated: `always`; `given` (the condition tests only the option itself);
+// `wire-version` (it depends on what the server's hello says); `other`, kept as the client wrote it.
+
+export type FieldCondition = { form: 'always' | 'given' | 'wire-version' | 'other'; text?: string };
+/** A field of a command document: where the client sets it and under what condition. `by` names a helper that sets
+ *  it; `from` the builder it was read in, where that is not the command's own (a base class, a subclass). */
+export type CommandField = { name: string; type: string; optional?: boolean; sentWhen: FieldCondition; source: { file: string; line: number }; by?: string; from?: string };
+/** A command that is a document. `statements`: for a field that is a list of statements, the fields of one. */
+export type DocumentCommandDef = { id: string; fields: CommandField[]; statements?: Record<string, CommandField[]> };
+export type DocumentCommandTableSpec = { format: 'command-table'; language: 'document'; version: string; source: { package: string; commit: string; licence: string }; commands: DocumentCommandDef[]; envelope: CommandField[] };
+
+type BuilderField = CommandField & { typeFrom?: string; value?: string; also?: unknown[]; spreadUnder?: string };
+type Builder = { builder: string; kind: 'command' | 'statement'; file: string; line: number; command: string | null; class?: string; extends?: string; addsTo?: string; fields: BuilderField[] };
+export type DriverCommandBuilders = {
+  format: 'driver-command-builders';
+  driver: { package: string; version: string; commit: string; licence: string };
+  builders: Builder[];
+  envelope: Array<{ layer: string; file: string; line: number; fields: BuilderField[] }>;
+};
+
+const fieldOf = (f: BuilderField, from?: string): CommandField => ({
+  name: f.name, type: f.type, ...(f.optional ? { optional: true } : {}), sentWhen: f.sentWhen, source: f.source,
+  ...(f.by ? { by: f.by } : {}), ...(from ? { from } : {}),
+});
+
+/** The command table of a client's command builders: each command with its own fields, the fields its subclasses
+ *  add, the fields a base class adds to the commands that descend from it, and the fields of its statements. A builder this cannot place is
+ *  an error naming it; a table with a silent hole is never returned. */
+export function fromDriverCommandBuilders(doc: DriverCommandBuilders): DocumentCommandTableSpec {
+  const named = doc.builders.filter((b) => b.kind === 'command' && b.command !== null);
+  const classOf = new Map(named.filter((b) => b.class).map((b) => [b.class!, b.command!]));
+  const commands = new Map<string, DocumentCommandDef>();
+  const add = (id: string, fields: BuilderField[], from?: string): void => {
+    const held = commands.get(id) ?? { id, fields: [] };
+    for (const f of fields) if (!held.fields.some((h) => h.name === f.name)) held.fields.push(fieldOf(f, from));
+    commands.set(id, held);
+  };
+  for (const b of named) add(b.command!, b.fields);
+  // what a subclass adds to its parent's document, and what the base of every command adds to all of them
+  const everyCommand: Builder[] = [];
+  for (const b of doc.builders.filter((b) => b.kind === 'command' && b.command === null)) {
+    if (b.addsTo === undefined) throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) names no command and adds to none`);
+    const parent = classOf.get(b.addsTo);
+    if (parent !== undefined) add(parent, b.fields, b.builder);
+    else if (b.class === b.addsTo) everyCommand.push(b);
+    else throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) adds to ${b.addsTo}, which builds no named command`);
+  }
+  // the base's fields go to the commands whose class descends from it, and to no other (a getMore is not one)
+  const parentOf = new Map(doc.builders.filter((b) => b.class && b.extends).map((b) => [b.class!, b.extends!]));
+  const descends = (cls: string | undefined, base: string): boolean => { for (let at = cls, hops = 0; at !== undefined && hops < 16; at = parentOf.get(at), hops += 1) if (at === base) return true; return false; };
+  for (const b of everyCommand) for (const n of named) if (descends(n.extends, b.class!)) add(n.command!, b.fields, b.builder);
+  // a statement builder's fields belong to the command of its file that carries the statement list
+  for (const b of doc.builders.filter((b) => b.kind === 'statement')) {
+    const owner = named.find((n) => n.file === b.file && n.fields.some((f) => f.value === 'this.statements'));
+    const list = owner?.fields.find((f) => f.value === 'this.statements');
+    if (!owner || !list) throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) builds a statement and no command of its file carries a statement list`);
+    (commands.get(owner.command!)!.statements ??= {})[list.name] = b.fields.map((f) => fieldOf(f));
+  }
+  const envelope: CommandField[] = [];
+  for (const layer of doc.envelope) for (const f of layer.fields) if (!envelope.some((h) => h.name === f.name)) envelope.push(fieldOf(f, layer.layer));
+  if (commands.size === 0) throw new Error('command-builders: no command was read');
+  return {
+    format: 'command-table', language: 'document', version: doc.driver.version,
+    source: { package: doc.driver.package, commit: doc.driver.commit, licence: doc.driver.licence },
+    commands: [...commands.values()].sort((a, b) => a.id.localeCompare(b.id)), envelope,
+  };
+}

package/src/types.ts

@@ -29,6 +29,8 @@ export interface ScoreReport {
 
 export interface CriterionResult {
   pass: boolean;
+  /** An interrupted check is not a verdict about unchanged source. */
+  cacheable?: boolean;
   /** why it failed, or what it measured when it passed */
   reason: string;
 }

package/src/walk/behavior-journey.ts

@@ -9,7 +9,8 @@ import { attributionName } from '../verdict.ts';
 //
 // The caller names the pack repository first (usePacks).
 
-import { mysql, redis } from '@volter/world-core';
+import { mongodb, mysql, redis } from '@volter/world-core';
+import { createRequire } from 'node:module';
 import { gzipSync } from 'node:zlib';
 import { parse, visit } from 'graphql';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
@@ -17,7 +18,7 @@ import { join } from 'node:path';
 import { databaseSession, type DatabaseSession, getActivePackAssets, getActiveWorldStore, LocalPackAssets, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActivePackAssets, setActiveWorldStore, setDeliveryObserver, setInProcessTwins, type InProcessTwin, type TwinStream, type TwinStreamConnection } from '@volter/world-core/runtime';
 import { createHostTable, type HostFacts } from '@volter/world-core/host-routing';
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
-import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type SocketStep, type SqlStep, type RespStep, type MysqlStep, isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from './journey-kit.ts';
+import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type SocketStep, type SqlStep, type RespStep, type MysqlStep, type MongoStep, isMongo, isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from './journey-kit.ts';
 import { lanesOf, lineShape, shapeChecker, type LineConnection, type ShapeChecker } from './shape.ts';
 import { walkPackDirectory } from './pack-directory.ts';
 import { xmlMembers } from './xml-view.ts';
@@ -446,6 +447,61 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     finally { opts.hooks?.after?.(step as never, link, answered, collect.slice(before)); }
   };
 
+  // A MongoDB step speaks the pack's MongoDB wire as an application's driver does (@volter/world-core/mongodb's client), on
+  // the same byte-stream adapter the owned TCP listener serves. The document codec is BSON, the library the pack
+  // installs: the walk loads it from the pack's own dependencies, so a step is encoded by the library the pack decodes with.
+  const mongoLinks = new Map<string, { client: ReturnType<typeof mongodb.mongoClient>; database: string; close: () => void }>();
+  type Bson = { serialize(document: Record<string, unknown>): Uint8Array; deserialize(bytes: Uint8Array, options: Record<string, unknown>): Record<string, unknown>; EJSON: { deserialize(value: unknown, options: { relaxed: boolean }): Record<string, unknown>; serialize(value: unknown, options: { relaxed: boolean }): Record<string, unknown> } };
+  let bson: Bson | undefined;
+  const bareNumber = (value: unknown, at = 'mongo'): string | undefined => {
+    if (typeof value === 'number') return at;
+    if (Array.isArray(value)) { for (const [i, item] of value.entries()) { const found = bareNumber(item, `${at}[${i}]`); if (found) return found; } return undefined; }
+    if (value && typeof value === 'object') for (const [key, item] of Object.entries(value)) { const found = bareNumber(item, `${at}.${key}`); if (found) return found; }
+    return undefined;
+  };
+  const mongoStep = async (step: MongoStep): Promise<void> => {
+    const before = collect.length; let answered: { status: number; body: unknown } = { status: 0, body: undefined };
+    const link = step.link ?? 'mongo';
+    opts.hooks?.before?.(step as never, link, step.mongo);
+    try {
+      if (!bson) {
+        const pack = walkPackDirectory(packsDir(), journey.vendor, dependenciesDir());
+        if (!pack) throw new Error(`no pack directory for ${journey.vendor} to load its BSON library from`);
+        bson = createRequire(join(pack, 'package.json'))('bson') as Bson;
+      }
+      const codec: mongodb.MongoCodec = { serialize: (document) => bson!.serialize(document), deserialize: (bytes) => bson!.deserialize(bytes, { promoteValues: false, promoteLongs: false, bsonRegExp: true }) };
+      let held = mongoLinks.get(link);
+      if (!held) {
+        if (!served?.stream) streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
+        const factory = served?.stream ?? streams?.(root, {}); if (!factory) throw new Error(`no create<Name>TwinStream adapter enrolled for ${journey.vendor}`);
+        let out: number[] = [];
+        const conn = factory({ write: (b) => { out.push(...b); }, end: () => {} }, '127.0.0.1');
+        const exchange: mongodb.MongoExchange = async (bytes) => { conn.data(bytes); await conn.settled(); const got = Uint8Array.from(out); out = []; return got; };
+        held = { client: mongodb.mongoClient(exchange, codec), database: 'test', close: () => conn.close() };
+        mongoLinks.set(link, held);
+      }
+      if (step.database) held.database = fill(step.database, captured);
+      const written = fillJson(step.mongo, captured);
+      const bare = bareNumber(written);
+      if (bare) throw new Error(`${bare} is a bare JSON number: write its kind ({ "$numberInt": "…" }, $numberLong or $numberDouble)`);
+      const reply = await held.client.command(held.database, bson.EJSON.deserialize(written, { relaxed: false }));
+      const body = bson.EJSON.serialize(reply, { relaxed: false });
+      const ok = (body.ok as Record<string, unknown> | undefined), failed = !ok || Number(Object.values(ok)[0]) !== 1;
+      const code = failed ? Number(Object.values((body.code as Record<string, unknown> | undefined) ?? { none: Number.NaN })[0]) : undefined;
+      answered = { status: code ?? 0, body };
+      if (opts.verbose) console.log(`  ${String(code ?? 'OK').padEnd(5)} ${link.padEnd(6)} ${String(Object.keys(step.mongo)[0] ?? '').padEnd(20)} ${step.name}`);
+      if (step.refused !== undefined ? code !== step.refused : failed) {
+        collect.push({ step: step.name, beat: 'STATUS', detail: failed ? `MongoDB refused it: ${code} ${String(body.codeName ?? '')} ${String(body.errmsg ?? '')}${step.refused ? ` (wanted ${step.refused})` : ''}` : `MongoDB completed it, wanted ${step.refused}` });
+        return;
+      }
+      for (const [name, dot] of Object.entries(step.capture ?? {})) { const value = captureAt(body, dot); if (value === undefined || value === null) collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` }); else remember(name, value); }
+      try { for (const detail of expectFailures(step.expect ?? [], body, captured)) collect.push({ step: step.name, beat: 'EXPECT', detail }); }
+      catch (e) { collect.push({ step: step.name, beat: 'CAPTURE', detail: (e as Error).message }); }
+      if (step.close) { mongoLinks.get(link)?.close(); mongoLinks.delete(link); }
+    } catch (e) { collect.push({ step: step.name, beat: 'MONGO', detail: (e as Error).message }); }
+    finally { opts.hooks?.after?.(step as never, link, answered, collect.slice(before)); }
+  };
+
   // A git step is a git client's clone or push on the pack's smart-HTTP plane (packages/twin-standard/src/walk/git-client.ts); its answer is
   // checked as a request's is (status, captures, expectations).
   const gitStep = async (step: GitStep): Promise<void> => {
@@ -679,6 +735,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
   try {
   for (const step of journey.steps) {
     stepNow = step.name;
+    if (isMongo(step)) { await mongoStep(step); continue; }
     if (isMysql(step)) { await mysqlStep(step); continue; }
     if (isResp(step)) { await respStep(step); continue; }
     if (isLine(step)) { await speak(step); continue; }

package/src/walk/journey-kit.ts

@@ -327,7 +327,7 @@ export type Journey = {
   steps: Step[];
 };
 
-export type Step = JourneyStep | WaitStep | LineStep | GitStep | SocketStep | SqlStep | RespStep | MysqlStep;
+export type Step = JourneyStep | WaitStep | LineStep | GitStep | SocketStep | SqlStep | RespStep | MysqlStep | MongoStep;
 
 /** A step on a MySQL wire (the kernel's @volter/world-core/mysql, a pack's `create<Name>TwinStream`), spoken as an
  *  application's driver speaks it. `signIn` opens a named connection (`link`, `mysql` by default) with a user and
@@ -342,6 +342,19 @@ export type MysqlStep = {
 };
 export const isMysql = (step: Step): step is MysqlStep => 'mysql' in step || 'signIn' in step;
 
+/** A step on a pack's MongoDB wire, sent as an application's driver sends it (`@volter/world-core/mongodb`'s client)
+ *  on a named `link`, opened by the first step that names it. `mongo` is ONE command document, written in
+ *  canonical extended JSON so that what a document holds is written as it is: an ObjectId as `{ "$oid": … }`, a date
+ *  as `{ "$date": … }`, and a number with its kind (`{ "$numberInt": "1" }`, `$numberLong`, `$numberDouble`); a bare
+ *  JSON number is refused, because JSON does not say which of three kinds it is. `database` is the database it is
+ *  sent to (the link's last one, else `test`). Its answer is the reply document in the same form. A reply whose
+ *  `ok` is 0 fails the step unless `refused` names its `code`. */
+export type MongoStep = {
+  name: string; mongo: Record<string, unknown>; database?: string; link?: string; close?: boolean;
+  refused?: number; capture?: JourneyStep['capture']; expect?: JourneyStep['expect']; example?: string; exampleDiffers?: Record<string, string>;
+};
+export const isMongo = (step: Step): step is MongoStep => 'mongo' in step;
+
 /** A typed request/reply stream step. `resp` is one command or a pipeline of commands, on a named connection.
  * Captures and expectations see `{ replies, last, error }`; binary arguments use `{ base64 }`.
  * `read` drains pushes or a blocking command's answer without sending bytes. */