@shibbirweb/mcp-db-read-only 0.1.0 → 0.2.0

package/dist/drivers/keyvalue/RedisDriver.js

@@ -25,8 +25,8 @@ export class RedisDriver extends BaseDriver {
     /** Long strings are cut in samples; the length is reported so nothing is hidden silently. */
     static MAX_STRING_PREVIEW = 4096;
     client;
-    constructor(target, tuning, logger, guard = new RedisCommandFlagsGuard()) {
-        super(target);
+    constructor(target, tuning, tracer, logger, guard = new RedisCommandFlagsGuard()) {
+        super(target, tracer);
         this.tuning = tuning;
         this.logger = logger;
         this.guard = guard;
@@ -111,9 +111,12 @@ export class RedisDriver extends BaseDriver {
                 return { key: name, type, note: "No sample reader for this type; use redis_command." };
         }
     }
+    /**
+     * The guard's COMMAND INFO lookups go through `call` too, so the log shows
+     * the server being asked before the command itself is sent.
+     */
     async command(name, args) {
-        const client = await this.client.get();
-        const call = (command, ...rest) => client.call(command, ...rest);
+        const call = (command, ...rest) => this.call(command, ...rest);
         const subcommand = this.isContainer(name) ? args[0]?.toUpperCase() : undefined;
         await this.guard.assertReadOnly(call, name, subcommand);
         return call(name, ...args);
@@ -172,9 +175,21 @@ export class RedisDriver extends BaseDriver {
     isContainer(name) {
         return ["OBJECT", "MEMORY", "XINFO"].includes(name);
     }
+    /** Every command this driver sends passes through here, so every one is traced. */
     async call(command, ...args) {
         const client = await this.client.get();
-        return client.call(command, ...args);
+        return this.traced([command, ...args].join(" "), undefined, () => client.call(command, ...args), RedisDriver.describeReply);
+    }
+    /** Arrays by length, short scalars by value, so `GET` and `DBSIZE` read naturally in the log. */
+    static describeReply(reply) {
+        if (Array.isArray(reply)) {
+            return `${reply.length} item${reply.length === 1 ? "" : "s"}`;
+        }
+        if (reply === null) {
+            return "nil";
+        }
+        const text = String(reply);
+        return text.length <= 40 ? text : `${text.length} characters`;
     }
     databaseIndex() {
         const parsed = Number.parseInt(this.target.database, 10);

package/dist/drivers/search/ElasticsearchDriver.js

@@ -18,10 +18,10 @@ export class ElasticsearchDriver extends BaseDriver {
     tuning;
     fetcher;
     family = "search";
-    constructor(target, tuning, 
+    constructor(target, tuning, tracer, 
     // Wrapped so fetch is never invoked with this driver as its receiver.
     fetcher = (input, init) => fetch(input, init)) {
-        super(target);
+        super(target, tracer);
         this.tuning = tuning;
         this.fetcher = fetcher;
     }
@@ -80,13 +80,17 @@ export class ElasticsearchDriver extends BaseDriver {
     }
     async send(request, timeoutMs = this.tuning.queryTimeoutMs) {
         const { method, path, body } = this.route(request);
-        const response = await this.fetcher(`${this.baseUrl()}${path}`, {
-            method,
-            headers: this.headers(),
-            body: body === undefined ? undefined : JSON.stringify(body),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        const text = await response.text();
+        // Traced as the request line, with the body as its parameters. The
+        // authorization header is never part of what is traced.
+        const { response, text } = await this.traced(`${method} ${path}`, body, async () => {
+            const answer = await this.fetcher(`${this.baseUrl()}${path}`, {
+                method,
+                headers: this.headers(),
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            return { response: answer, text: await answer.text() };
+        }, (result) => `HTTP ${result.response.status}`);
         const parsed = text ? this.parse(text) : null;
         if (response.status === 404 && request.kind !== "cluster" && request.kind !== "indices") {
             throw new ObjectNotFoundError(this.objectNoun, request.index);

package/dist/drivers/sql/ClickHouseDriver.js

@@ -29,8 +29,8 @@ export class ClickHouseDriver extends BaseDriver {
      */
     static MAX_RESULT_ROWS = 10000;
     client;
-    constructor(target, tuning) {
-        super(target);
+    constructor(target, tuning, tracer) {
+        super(target, tracer);
         this.tuning = tuning;
         this.client = new LazyResource(() => this.open(), (opened) => opened.client.close());
     }
@@ -77,13 +77,15 @@ export class ClickHouseDriver extends BaseDriver {
     }
     async run(sql, params) {
         const { client, settings } = await this.client.get();
-        const result = await client.query({
-            query: sql,
-            format: "JSONEachRow",
-            query_params: params,
-            clickhouse_settings: settings,
+        return this.traced(sql, params, async () => {
+            const result = await client.query({
+                query: sql,
+                format: "JSONEachRow",
+                query_params: params,
+                clickhouse_settings: settings,
+            });
+            return (await result.json());
         });
-        return (await result.json());
     }
     async assertExists(database, table) {
         const rows = await this.run("SELECT 1 AS found FROM system.tables WHERE database = {database:String} AND name = {table:String}", { database, table });
@@ -133,11 +135,8 @@ export class ClickHouseDriver extends BaseDriver {
      * attaching any is exactly what a read-only account refuses.
      */
     async negotiateSettings(client) {
-        const result = await client.query({
-            query: "SELECT toUInt8(getSetting('readonly')) AS readonly",
-            format: "JSONEachRow",
-        });
-        const rows = (await result.json());
+        const probe = "SELECT toUInt8(getSetting('readonly')) AS readonly";
+        const rows = (await this.traced(probe, undefined, async () => (await client.query({ query: probe, format: "JSONEachRow" })).json()));
         const level = Number(rows[0]?.readonly ?? 0);
         const limits = {
             max_execution_time: Math.max(1, Math.ceil(this.tuning.queryTimeoutMs / 1000)),

package/dist/drivers/sql/MsSqlDriver.js

@@ -23,8 +23,8 @@ export class MsSqlDriver extends BaseDriver {
     dialect = "mssql";
     static SYSTEM_DATABASES = new Set(["master", "tempdb", "model", "msdb"]);
     pool;
-    constructor(target, tuning) {
-        super(target);
+    constructor(target, tuning, tracer) {
+        super(target, tracer);
         this.tuning = tuning;
         this.pool = new LazyResource(() => this.createPool(), (opened) => opened.pool.close());
     }
@@ -95,17 +95,17 @@ export class MsSqlDriver extends BaseDriver {
     async run(text, inputs = {}) {
         const { pool, sql } = await this.pool.get();
         const transaction = new sql.Transaction(pool);
-        await transaction.begin();
+        await this.traced("BEGIN TRANSACTION", undefined, () => transaction.begin(), () => "ok");
         try {
             const request = new sql.Request(transaction);
             for (const [name, value] of Object.entries(inputs)) {
                 request.input(name, value);
             }
-            const result = await request.query(text);
-            return (result.recordset ?? []);
+            const params = Object.keys(inputs).length > 0 ? inputs : undefined;
+            return await this.traced(text, params, async () => ((await request.query(text)).recordset ?? []));
         }
         finally {
-            await transaction.rollback().catch(() => undefined);
+            await this.traced("ROLLBACK", undefined, () => transaction.rollback(), () => "ok").catch(() => undefined);
         }
     }
     async assertExists(name) {

package/dist/drivers/sql/MySqlDriver.js

@@ -31,8 +31,8 @@ export class MySqlDriver extends BaseDriver {
     WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL`;
     static NO_SUCH_TABLE = 1146;
     pool;
-    constructor(target, tuning, logger) {
-        super(target);
+    constructor(target, tuning, tracer, logger) {
+        super(target, tracer);
         this.tuning = tuning;
         this.logger = logger;
         this.pool = new LazyResource(() => this.createPool(), (pool) => pool.end());
@@ -78,8 +78,10 @@ export class MySqlDriver extends BaseDriver {
     /** Placeholders for values wherever the statement allows; identifiers are quoted. */
     async run(sql, params) {
         const pool = await this.pool.get();
-        const [rows] = await pool.query(sql, params);
-        return rows;
+        return this.traced(sql, params, async () => {
+            const [rows] = await pool.query(sql, params);
+            return rows;
+        });
     }
     /**
      * Runs work against one table, turning MySQL's "table doesn't exist" (error
@@ -127,7 +129,7 @@ export class MySqlDriver extends BaseDriver {
             dateStrings: true,
             ssl: this.sslOptions(),
         });
-        new MySqlSessionInitializer(this.tuning.queryTimeoutMs, this.logger).attachTo(pool);
+        new MySqlSessionInitializer(this.tuning.queryTimeoutMs, this.logger, this.tracer, this.label).attachTo(pool);
         return pool;
     }
     /** `?ssl=true` requires TLS; `?ssl-mode=REQUIRED` is accepted as the MySQL spelling. */

package/dist/drivers/sql/MySqlSessionInitializer.js

@@ -12,6 +12,8 @@
 export class MySqlSessionInitializer {
     queryTimeoutMs;
     logger;
+    tracer;
+    engineLabel;
     /**
      * Removes the two sql_mode flags that change how quotes are read, so the
      * server lexes a statement exactly as the validator did.
@@ -38,9 +40,17 @@ export class MySqlSessionInitializer {
     ].reduce((expression, mode) => `REPLACE(${expression}, ',${mode},', ',')`, "CONCAT(',', @@SESSION.sql_mode, ',')")})`;
     /** MariaDB's name for the variable; MySQL rejects it with error 1193. */
     static UNKNOWN_VARIABLE = 1193;
-    constructor(queryTimeoutMs, logger) {
+    /**
+     * @param tracer records each setup statement in the call log, when it is
+     *   on. They run on the pool's own schedule, so they usually appear as
+     *   entries of their own rather than under the call that opened the
+     *   connection.
+     */
+    constructor(queryTimeoutMs, logger, tracer, engineLabel) {
         this.queryTimeoutMs = queryTimeoutMs;
         this.logger = logger;
+        this.tracer = tracer;
+        this.engineLabel = engineLabel;
     }
     /**
      * Hooks the pool's `connection` event, which fires once per physical
@@ -70,7 +80,10 @@ export class MySqlSessionInitializer {
      * gap affects only the timeout, never the read-only mode set above.
      */
     applyTimeout(connection) {
-        connection.query(`SET SESSION MAX_EXECUTION_TIME = ${this.queryTimeoutMs}`, (error) => {
+        const sql = `SET SESSION MAX_EXECUTION_TIME = ${this.queryTimeoutMs}`;
+        const started = Date.now();
+        connection.query(sql, (error) => {
+            this.tracer.record(this.engineLabel, { text: sql }, Date.now() - started, error ?? undefined);
             if (!error) {
                 return;
             }
@@ -91,7 +104,9 @@ export class MySqlSessionInitializer {
      * not.
      */
     apply(connection, sql, description) {
+        const started = Date.now();
         connection.query(sql, (error) => {
+            this.tracer.record(this.engineLabel, { text: sql }, Date.now() - started, error ?? undefined);
             if (error) {
                 this.logger(`could not ${description}: ${String(error)}`);
             }

package/dist/drivers/sql/PostgresDriver.js

@@ -32,8 +32,8 @@ export class PostgresDriver extends BaseDriver {
      */
     static RAW_TEXT_TYPES = new Set([1082, 1083, 1114, 1184, 1266]);
     pool;
-    constructor(target, tuning) {
-        super(target);
+    constructor(target, tuning, tracer) {
+        super(target, tracer);
         this.tuning = tuning;
         this.pool = new LazyResource(() => this.createPool(), (pool) => pool.end());
     }
@@ -106,10 +106,10 @@ export class PostgresDriver extends BaseDriver {
         const client = await pool.connect();
         let broken;
         try {
-            await client.query(`BEGIN TRANSACTION READ ONLY; SET LOCAL statement_timeout = ${this.tuning.queryTimeoutMs}; SET LOCAL standard_conforming_strings = on`);
+            const opening = `BEGIN TRANSACTION READ ONLY; SET LOCAL statement_timeout = ${this.tuning.queryTimeoutMs}; SET LOCAL standard_conforming_strings = on`;
+            await this.traced(opening, undefined, () => client.query(opening), () => "ok");
             const config = { text, values, queryMode: "extended" };
-            const result = await client.query(config);
-            return result.rows;
+            return await this.traced(text, values, async () => (await client.query(config)).rows);
         }
         finally {
             broken = await this.rollback(client);
@@ -120,7 +120,7 @@ export class PostgresDriver extends BaseDriver {
     }
     async rollback(client) {
         try {
-            await client.query("ROLLBACK");
+            await this.traced("ROLLBACK", undefined, () => client.query("ROLLBACK"), () => "ok");
             return undefined;
         }
         catch (error) {

package/dist/drivers/sql/SqliteDriver.js

@@ -134,8 +134,8 @@ export class SqliteDriver extends BaseDriver {
     family = "sql";
     dialect = "sqlite";
     worker;
-    constructor(target, tuning) {
-        super(target);
+    constructor(target, tuning, tracer) {
+        super(target, tracer);
         this.tuning = tuning;
         this.worker = new LazyResource(() => SqliteWorkerHandle.start({ path: target.database, busyTimeoutMs: tuning.connectTimeoutMs }, tuning.connectTimeoutMs), (handle) => handle.terminate());
     }
@@ -190,7 +190,7 @@ export class SqliteDriver extends BaseDriver {
     async run(sql, params = []) {
         const handle = await this.worker.get();
         try {
-            return await handle.run(sql, params, this.tuning.queryTimeoutMs);
+            return await this.traced(sql, params.length > 0 ? params : undefined, () => handle.run(sql, params, this.tuning.queryTimeoutMs));
         }
         catch (error) {
             if (handle.dead) {

package/dist/formatting/JsonSerializer.js

@@ -14,7 +14,8 @@
 export class JsonSerializer {
     /** Enough bytes to recognise a value; the length says how much was omitted. */
     static BINARY_PREVIEW_BYTES = 32;
-    stringify(value) {
+    /** @param indent 2 for reading, 0 for one-line JSON such as a log entry. */
+    stringify(value, indent = 2) {
         const serializer = this;
         return JSON.stringify(value, 
         // A function rather than an arrow, because the replacer receives the
@@ -22,7 +23,7 @@ export class JsonSerializer {
         // the original Buffer.
         function (key, replaced) {
             return serializer.replace(this[key], replaced);
-        }, 2) ?? "null";
+        }, indent || undefined) ?? "null";
     }
     replace(original, replaced) {
         if (typeof original === "bigint") {

package/dist/logging/CallLogger.js

@@ -0,0 +1,139 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Redactor } from "./Redactor.js";
+/**
+ * The call log: one entry per tool call, with every statement the drivers
+ * sent while serving it.
+ *
+ * It is both halves of the logging interface. BaseTool hands it each call as
+ * a ToolCallObserver, and drivers report each statement to it as a
+ * StatementTracer. The two meet through AsyncLocalStorage: a call runs inside
+ * its own context, so a statement reported anywhere beneath it, however many
+ * awaits deep, lands on the right call without any id being passed through
+ * the drivers. Calls handled concurrently each keep their own statements.
+ *
+ * A statement reported with no call around it (a MySQL connection's session
+ * setup, fired by the pool) is written as an entry of its own.
+ *
+ * Each record goes to every channel: text to stderr or a file, the live
+ * browser viewer, or both.
+ *
+ * Logging can never break a call. Any failure in a channel is caught; the
+ * first one is reported once through the diagnostic logger and that channel
+ * is then switched off for the rest of the process, rather than failing, say,
+ * on every call once a disk fills up. The other channels carry on.
+ */
+export class CallLogger {
+    channels;
+    describeConnection;
+    warn;
+    describeClient;
+    redactor;
+    clock;
+    context = new AsyncLocalStorage();
+    nextId = 1;
+    disabled = new Set();
+    constructor(channels, describeConnection, warn, 
+    /** The MCP client's name, known once it has completed the handshake. */
+    describeClient = () => null, redactor = new Redactor(), clock = () => Date.now()) {
+        this.channels = channels;
+        this.describeConnection = describeConnection;
+        this.warn = warn;
+        this.describeClient = describeClient;
+        this.redactor = redactor;
+        this.clock = clock;
+    }
+    async observe(tool, args, run) {
+        const id = this.nextId++;
+        const started = this.clock();
+        const connection = this.safely(() => this.describeConnection(), null);
+        const context = { statements: [] };
+        const result = await this.context.run(context, run);
+        const record = this.safely(() => ({
+            id,
+            tool,
+            pid: process.pid,
+            client: this.safely(() => this.describeClient(), null),
+            at: new Date(started),
+            durationMs: this.clock() - started,
+            connection,
+            input: this.redactor.redact(args),
+            output: result.content.map((block) => block.text).join("\n"),
+            failed: Boolean(result.isError),
+            statements: context.statements,
+        }), null);
+        if (record) {
+            this.publish((channel) => channel.onCall(record));
+        }
+        return result;
+    }
+    async trace(engine, statement, run, describe = CallLogger.describe) {
+        const started = this.clock();
+        try {
+            const result = await run();
+            this.add(engine, statement, started, this.safely(() => describe(result), "ok"), false);
+            return result;
+        }
+        catch (error) {
+            this.add(engine, statement, started, CallLogger.reason(error), true);
+            throw error;
+        }
+    }
+    record(engine, statement, durationMs, error) {
+        const started = this.clock() - durationMs;
+        this.add(engine, statement, started, error ? CallLogger.reason(error) : "ok", Boolean(error));
+    }
+    /** The default outcome: a row count for arrays, "ok" for everything else. */
+    static describe(result) {
+        if (Array.isArray(result)) {
+            return `${result.length} row${result.length === 1 ? "" : "s"}`;
+        }
+        if (typeof result === "number") {
+            return String(result);
+        }
+        return "ok";
+    }
+    add(engine, statement, started, outcome, failed) {
+        const record = {
+            pid: process.pid,
+            client: this.safely(() => this.describeClient(), null),
+            engine,
+            text: statement.text,
+            params: statement.params,
+            at: new Date(started),
+            durationMs: this.clock() - started,
+            outcome,
+            failed,
+        };
+        const current = this.context.getStore();
+        if (current) {
+            current.statements.push(record);
+            return;
+        }
+        this.publish((channel) => channel.onStatement(record));
+    }
+    publish(deliver) {
+        for (const channel of this.channels) {
+            if (this.disabled.has(channel)) {
+                continue;
+            }
+            try {
+                deliver(channel);
+            }
+            catch (error) {
+                this.disabled.add(channel);
+                this.warn(`call logging to ${channel.description} stopped after a failure: ${CallLogger.reason(error)}`);
+            }
+        }
+    }
+    safely(read, fallback) {
+        try {
+            return read();
+        }
+        catch {
+            return fallback;
+        }
+    }
+    static reason(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}

package/dist/logging/LogChannel.js

@@ -0,0 +1,18 @@
+/** Formats records as text and writes them to a sink. */
+export class TextLogChannel {
+    sink;
+    formatter;
+    constructor(sink, formatter) {
+        this.sink = sink;
+        this.formatter = formatter;
+    }
+    get description() {
+        return this.sink.description;
+    }
+    onCall(call) {
+        this.sink.write(this.formatter.formatCall(call));
+    }
+    onStatement(statement) {
+        this.sink.write(this.formatter.formatStatement(statement));
+    }
+}

package/dist/logging/LogFormatter.js

@@ -0,0 +1,80 @@
+import { JsonSerializer } from "../formatting/JsonSerializer.js";
+import { RecordJson } from "./RecordJson.js";
+/**
+ * For reading: one boxed block per call, with the input, every statement the
+ * drivers sent, and the full output, each indented under its heading.
+ *
+ * ```
+ * ┌─ #3 run_query · ok · 38 ms · 2026-09-25T10:14:03.221Z
+ * │ connection  dev (MySQL) mysql://root@127.0.0.1:3306/app
+ * │ input
+ * │   { "query": "SELECT COUNT(*) AS n FROM members" }
+ * │ statements (1)
+ * │   1. MySQL · 12 ms · 1 row
+ * │      SELECT COUNT(*) AS n FROM members
+ * │ output
+ * │   [ { "n": 17440 } ]
+ * └─
+ * ```
+ */
+export class PrettyLogFormatter {
+    serializer;
+    constructor(serializer = new JsonSerializer()) {
+        this.serializer = serializer;
+    }
+    formatCall(call) {
+        const lines = [];
+        const status = call.failed ? "FAILED" : "ok";
+        lines.push(`┌─ #${call.id} ${call.tool} · ${status} · ${call.durationMs} ms · ${call.at.toISOString()}`);
+        lines.push(`│ connection  ${call.connection ?? "none"}`);
+        lines.push(`│ process     ${call.client ?? "unknown client"}, pid ${call.pid}`);
+        lines.push("│ input");
+        lines.push(...this.indent(this.serializer.stringify(call.input), "│   "));
+        if (call.statements.length > 0) {
+            lines.push(`│ statements (${call.statements.length})`);
+            call.statements.forEach((statement, index) => {
+                lines.push(`│   ${index + 1}. ${this.summary(statement)}`);
+                lines.push(...this.statementBody(statement, "│      "));
+            });
+        }
+        lines.push(call.failed ? "│ error" : "│ output");
+        lines.push(...this.indent(call.output, "│   "));
+        lines.push("└─");
+        return `${lines.join("\n")}\n`;
+    }
+    formatStatement(statement) {
+        const lines = [`· statement outside a tool call · ${this.summary(statement)} · ${statement.at.toISOString()}`];
+        lines.push(...this.statementBody(statement, "    "));
+        return `${lines.join("\n")}\n`;
+    }
+    summary(statement) {
+        const outcome = statement.failed ? `FAILED: ${statement.outcome}` : statement.outcome;
+        return `${statement.engine} · ${statement.durationMs} ms · ${outcome}`;
+    }
+    statementBody(statement, prefix) {
+        const lines = this.indent(statement.text, prefix);
+        if (statement.params !== undefined) {
+            lines.push(...this.indent(`params ${this.serializer.stringify(statement.params, 0)}`, prefix));
+        }
+        return lines;
+    }
+    indent(text, prefix) {
+        return text.split("\n").map((line) => `${prefix}${line}`);
+    }
+}
+/**
+ * For machines: one JSON object per line, so `grep`, `jq` and log shippers
+ * can read it without knowing anything about this server.
+ */
+export class JsonLogFormatter {
+    serializer;
+    constructor(serializer = new JsonSerializer()) {
+        this.serializer = serializer;
+    }
+    formatCall(call) {
+        return `${this.serializer.stringify(RecordJson.call(call), 0)}\n`;
+    }
+    formatStatement(statement) {
+        return `${this.serializer.stringify(RecordJson.statement(statement), 0)}\n`;
+    }
+}

package/dist/logging/LogRecords.js

@@ -0,0 +1,7 @@
+/**
+ * What the call log records, independent of how it is written out.
+ *
+ * Kept as plain data so the two formatters (pretty and JSON) render exactly
+ * the same facts, and a test can assert on a record without parsing text.
+ */
+export {};

package/dist/logging/LogSink.js

@@ -0,0 +1,38 @@
+import { appendFileSync } from "node:fs";
+/**
+ * The MCP client's own log.
+ *
+ * stderr, never stdout: stdout carries the JSON-RPC stream, and one log line
+ * there would corrupt the protocol. Claude Code, for one, keeps each MCP
+ * server's stderr in its MCP logs.
+ */
+export class StderrSink {
+    description = "stderr";
+    write(entry) {
+        process.stderr.write(entry.endsWith("\n") ? entry : `${entry}\n`);
+    }
+}
+/**
+ * A file, appended to.
+ *
+ * Synchronous on purpose. Shutdown ends with `process.exit`, which does not
+ * wait for a buffered stream to drain, so an asynchronous writer loses the
+ * last calls of a session: usually the ones someone opened the log to find.
+ * The cost is a blocking write per call, which is small next to a database
+ * round trip.
+ *
+ * Created readable by the owner only, since with logging on it holds every
+ * query and every result.
+ */
+export class FileSink {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    get description() {
+        return this.path;
+    }
+    write(entry) {
+        appendFileSync(this.path, entry.endsWith("\n") ? entry : `${entry}\n`, { mode: 0o600 });
+    }
+}

package/dist/logging/RecordJson.js

@@ -0,0 +1,39 @@
+/**
+ * The one JSON shape of a record, used everywhere a record leaves the process
+ * as data: JSON log lines, the saved files, and the live viewer.
+ *
+ * One definition, so a file written today reads back in the viewer exactly
+ * as a live entry does, and a field added here appears in all three.
+ */
+export class RecordJson {
+    static call(call) {
+        return {
+            type: "call",
+            id: call.id,
+            tool: call.tool,
+            at: call.at.toISOString(),
+            durationMs: call.durationMs,
+            failed: call.failed,
+            pid: call.pid,
+            client: call.client,
+            connection: call.connection,
+            input: call.input,
+            statements: call.statements.map((statement) => RecordJson.statementFields(statement)),
+            output: call.output,
+        };
+    }
+    static statement(statement) {
+        return { type: "statement", ...RecordJson.statementFields(statement), pid: statement.pid, client: statement.client };
+    }
+    static statementFields(statement) {
+        return {
+            engine: statement.engine,
+            at: statement.at.toISOString(),
+            durationMs: statement.durationMs,
+            failed: statement.failed,
+            outcome: statement.outcome,
+            text: statement.text,
+            params: statement.params,
+        };
+    }
+}