@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/operations/diagnostics.js

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { POOL_DURATION_BOUNDS_MS } from '../../adapters/poolMetrics.js';
+import { RequestMetrics } from './requestMetrics.js';
+/** The registry's pools and this process's event loop, now. Cumulative
+ * since start: compare two snapshots for an interval, as with the HTTP metrics. */
+export function collectCapacity(source) {
+    const loop = performance.eventLoopUtilization();
+    return Object.freeze({
+        eventLoop: Object.freeze({ activeMs: Math.round(loop.active), idleMs: Math.round(loop.idle) }),
+        durationBoundsMs: POOL_DURATION_BOUNDS_MS,
+        pools: Object.freeze([...source.poolStats()]),
+    });
+}
+/* These labels are declared here, never copied from a request. App URLs can
+   contain whole database queries, and even an unknown API path can be a secret. */
+const ROUTE_GROUPS = [
+    [
+        'connections',
+        [
+            '/api/connections',
+            '/api/connections/test',
+            '/api/connections/demo',
+            '/api/connections/update',
+            '/api/connections/remove',
+            '/api/connections/save',
+            '/api/connections/select',
+            '/api/connections/refresh',
+        ],
+    ],
+    ['identity', ['/api/whoami']],
+    ['app', ['/api/app']],
+    ['schema', ['/api/schema', '/api/ddl']],
+    [
+        'definitions',
+        [
+            '/api/views',
+            '/api/queries',
+            '/api/layouts',
+            '/api/pages',
+            '/api/pages/relations',
+            '/api/pages/suggested',
+            '/api/pages/saved',
+            '/api/pages/save',
+            '/api/filters',
+            '/api/filters/save',
+        ],
+    ],
+    ['agent', ['/api/agent/tools', '/api/agent/call']],
+    [
+        'query',
+        [
+            '/api/query',
+            '/api/run',
+            '/api/breakdown',
+            '/api/breakdowns',
+            '/api/view/run',
+            '/api/view/compile',
+            '/api/count',
+            '/api/counts',
+            '/api/export',
+            '/api/references',
+            '/api/pages/plan',
+            '/api/pages/compose',
+            '/api/http/operations',
+            '/api/http/operation',
+        ],
+    ],
+    ['update', ['/api/update']],
+    ['insert', ['/api/insert']],
+    ['delete', ['/api/delete']],
+    ['revert', ['/api/revert']],
+    ['sql', ['/api/sql']],
+];
+const ROUTES = new Map(ROUTE_GROUPS.flatMap(([label, paths]) => paths.map((path) => [path, `api.${label}`])));
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+const CAPACITY = 64;
+function routeFor(url) {
+    try {
+        const path = new URL(url ?? '/', 'http://localhost').pathname;
+        if (path === '/api/auth' || path.startsWith('/api/auth/'))
+            return 'api.auth';
+        return ROUTES.get(path) ?? (path.startsWith('/api/') ? 'api.other' : 'web');
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Local, best-effort HTTP diagnostics, separate from the business journal.
+ * The caller owns the stream. No request waits for it, and only one bounded
+ * record is handed to it at a time. A failed stream disables further output. */
+export class RequestDiagnostics {
+    output;
+    queue = [];
+    scheduled = false;
+    writing;
+    failed = false;
+    dropped = 0;
+    metrics = new RequestMetrics();
+    summaryPending = false;
+    summaryRevision;
+    summaryDropped = 0;
+    flushPromise;
+    flushDone;
+    capacity;
+    constructor(output) {
+        this.output = output;
+        output.on('error', this.fail);
+    }
+    get droppedTotal() {
+        return this.dropped;
+    }
+    /** Carry the host's capacity (its pools and event loop) in every summary
+     * from now on. Read when the summary is taken, never per request. */
+    watchCapacity(read) {
+        this.capacity = read;
+    }
+    snapshot() {
+        let capacity;
+        // Instrumentation must not become a new failure path: a capacity that cannot be read is left out.
+        try {
+            capacity = this.capacity?.();
+        }
+        catch {
+            capacity = undefined;
+        }
+        return Object.freeze({
+            event: 'http.metrics',
+            version: 1,
+            ...this.metrics.snapshot(),
+            ...(capacity ? { capacity } : {}),
+            health: Object.freeze({
+                droppedTotal: this.dropped,
+                failed: this.failed,
+                queuedRecords: this.queue.length,
+                writingRecord: this.writing === 'request',
+                writingSummary: this.writing === 'summary',
+                summaryPending: this.summaryPending,
+                summaryDroppedTotal: this.summaryDropped,
+            }),
+        });
+    }
+    get revision() {
+        return `${this.metrics.revision}:${this.dropped}`;
+    }
+    observe(req, res) {
+        try {
+            const requestId = randomUUID();
+            const method = METHODS.has(req.method ?? '') ? req.method : 'OTHER';
+            const route = routeFor(req.url);
+            const started = performance.now();
+            res.setHeader('x-request-id', requestId);
+            const recordMetrics = this.metrics.begin(method, route);
+            let recorded = false;
+            const complete = (outcome) => {
+                if (recorded)
+                    return;
+                recorded = true;
+                res.removeListener('finish', finished);
+                res.removeListener('close', closed);
+                const status = res.headersSent ? res.statusCode : null;
+                const elapsedMs = Math.max(0, performance.now() - started);
+                const durationMs = Math.round(elapsedMs * 100) / 100;
+                recordMetrics(status, elapsedMs, outcome);
+                this.enqueue({
+                    event: 'http.request',
+                    timestamp: new Date().toISOString(),
+                    requestId,
+                    method,
+                    route,
+                    status,
+                    durationMs,
+                    outcome,
+                });
+            };
+            const finished = () => complete('completed');
+            const closed = () => complete(res.writableFinished ? 'completed' : 'aborted');
+            res.once('finish', finished);
+            res.once('close', closed);
+        }
+        catch {
+            // Instrumentation must not become a new request failure path.
+            this.dropped += 1;
+        }
+    }
+    /** A bounded shutdown opportunity, not a delivery guarantee. Does not end
+     * stderr (or a caller's stream), and never participates in a business write. */
+    flush(timeoutMs = 250) {
+        if (this.failed)
+            return Promise.resolve(false);
+        if (this.summaryRevision !== this.revision)
+            this.summaryPending = true;
+        this.schedule();
+        if (this.flushPromise)
+            return this.flushPromise;
+        if (!this.writing && !this.queue.length && !this.summaryPending)
+            return Promise.resolve(true);
+        this.flushPromise = new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.flushDone = undefined;
+                this.flushPromise = undefined;
+                resolve(!this.failed);
+            };
+            const timer = setTimeout(() => {
+                this.flushDone = undefined;
+                this.flushPromise = undefined;
+                resolve(false);
+            }, Number.isFinite(timeoutMs) ? Math.max(0, Math.min(timeoutMs, 1_000)) : 250);
+            this.flushDone = done;
+        });
+        return this.flushPromise;
+    }
+    enqueue(event) {
+        if (this.failed || this.queue.length + Number(this.writing === 'request') >= CAPACITY) {
+            this.dropped += 1;
+            return;
+        }
+        this.queue.push(event);
+        this.schedule();
+    }
+    schedule() {
+        if (this.scheduled || this.writing || this.failed || (!this.queue.length && !this.summaryPending))
+            return;
+        this.scheduled = true;
+        setImmediate(() => {
+            this.scheduled = false;
+            if (this.failed)
+                return;
+            const request = this.queue.shift();
+            let event;
+            if (request) {
+                event = { ...request, droppedTotal: this.dropped };
+                this.writing = 'request';
+            }
+            else if (this.summaryPending && this.summaryRevision !== this.revision) {
+                this.summaryPending = false;
+                event = this.snapshot();
+                this.summaryRevision = this.revision;
+                this.writing = 'summary';
+            }
+            else {
+                this.summaryPending = false;
+                this.notifyIdle();
+                return;
+            }
+            try {
+                this.output.write(`${JSON.stringify(event)}\n`, (error) => {
+                    if (error) {
+                        this.fail();
+                        return;
+                    }
+                    if (this.failed)
+                        return;
+                    this.writing = undefined;
+                    this.schedule();
+                    this.notifyIdle();
+                });
+            }
+            catch {
+                this.fail();
+            }
+        });
+    }
+    fail = () => {
+        if (this.failed)
+            return;
+        this.failed = true;
+        this.dropped += this.queue.length + Number(this.writing === 'request');
+        this.summaryDropped += Number(this.summaryPending) + Number(this.writing === 'summary');
+        this.summaryPending = false;
+        this.queue.length = 0;
+        this.writing = undefined;
+        this.notifyIdle();
+    };
+    notifyIdle() {
+        if (!this.writing && !this.queue.length && !this.summaryPending)
+            this.flushDone?.();
+    }
+}
+/** Only the exact explicit opt-in enables diagnostics. MCP never calls this. */
+export function diagnosticsFromEnvironment(value, output = process.stderr) {
+    return value === '1' ? new RequestDiagnostics(output) : undefined;
+}

package/dist/server/operations/requestMetrics.d.ts

@@ -0,0 +1,33 @@
+export declare const REQUEST_METHODS: readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "OTHER"];
+export declare const REQUEST_ROUTES: readonly ["api.connections", "api.identity", "api.app", "api.schema", "api.definitions", "api.agent", "api.query", "api.update", "api.insert", "api.delete", "api.revert", "api.sql", "api.auth", "api.other", "web", "unknown"];
+export declare const REQUEST_STATUS_CLASSES: readonly ["1xx", "2xx", "3xx", "4xx", "5xx", "unknown"];
+export declare const REQUEST_DURATION_BOUNDS_MS: readonly number[];
+interface RequestMetricSeries {
+    readonly method: (typeof REQUEST_METHODS)[number];
+    readonly route: (typeof REQUEST_ROUTES)[number];
+    readonly statusClass: (typeof REQUEST_STATUS_CLASSES)[number];
+    readonly count: number;
+    readonly completed: number;
+    readonly aborted: number;
+    /** Disjoint inclusive-upper-bound buckets, followed by an overflow bucket. */
+    readonly durationBuckets: readonly number[];
+    readonly invalidDurationTotal: number;
+}
+export interface RequestMetricsSnapshot {
+    readonly started: number;
+    readonly completed: number;
+    readonly aborted: number;
+    readonly inFlight: number;
+    readonly durationBoundsMs: readonly number[];
+    readonly series: readonly RequestMetricSeries[];
+}
+export declare class RequestMetrics {
+    private started;
+    private completed;
+    private aborted;
+    private readonly series;
+    get revision(): number;
+    begin(method: string, route: string): (status: number | null, durationMs: number, outcome: 'completed' | 'aborted') => void;
+    snapshot(): RequestMetricsSnapshot;
+}
+export {};

package/dist/server/operations/requestMetrics.js

@@ -0,0 +1,94 @@
+/* Only declared dimensions enter storage. There are at most 8 × 16 × 6
+   series, regardless of the number of requests or distinct private URLs. */
+export const REQUEST_METHODS = Object.freeze(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'OTHER']);
+export const REQUEST_ROUTES = Object.freeze([
+    'api.connections',
+    'api.identity',
+    'api.app',
+    'api.schema',
+    'api.definitions',
+    'api.agent',
+    'api.query',
+    'api.update',
+    'api.insert',
+    'api.delete',
+    'api.revert',
+    'api.sql',
+    'api.auth',
+    'api.other',
+    'web',
+    'unknown',
+]);
+export const REQUEST_STATUS_CLASSES = Object.freeze(['1xx', '2xx', '3xx', '4xx', '5xx', 'unknown']);
+export const REQUEST_DURATION_BOUNDS_MS = Object.freeze([1, 5, 10, 25, 50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000]);
+export class RequestMetrics {
+    started = 0;
+    completed = 0;
+    aborted = 0;
+    series = new Map();
+    get revision() {
+        return this.started + this.completed + this.aborted;
+    }
+    begin(method, route) {
+        const methodIndex = REQUEST_METHODS.findIndex((value) => value === method);
+        const routeIndex = REQUEST_ROUTES.findIndex((value) => value === route);
+        const safeMethod = methodIndex < 0 ? REQUEST_METHODS.length - 1 : methodIndex;
+        const safeRoute = routeIndex < 0 ? REQUEST_ROUTES.length - 1 : routeIndex;
+        this.started += 1;
+        let finished = false;
+        return (status, durationMs, outcome) => {
+            if (finished)
+                return;
+            finished = true;
+            if (outcome === 'completed')
+                this.completed += 1;
+            else
+                this.aborted += 1;
+            const statusIndex = status !== null && Number.isInteger(status) && status >= 100 && status < 600
+                ? Math.floor(status / 100) - 1
+                : REQUEST_STATUS_CLASSES.length - 1;
+            const key = (safeMethod * REQUEST_ROUTES.length + safeRoute) * REQUEST_STATUS_CLASSES.length + statusIndex;
+            let series = this.series.get(key);
+            if (!series) {
+                series = {
+                    method: REQUEST_METHODS[safeMethod],
+                    route: REQUEST_ROUTES[safeRoute],
+                    statusClass: REQUEST_STATUS_CLASSES[statusIndex],
+                    count: 0,
+                    completed: 0,
+                    aborted: 0,
+                    durationBuckets: Array(REQUEST_DURATION_BOUNDS_MS.length + 1).fill(0),
+                    invalidDurationTotal: 0,
+                };
+                this.series.set(key, series);
+            }
+            series.count += 1;
+            if (outcome === 'completed')
+                series.completed += 1;
+            else
+                series.aborted += 1;
+            if (!Number.isFinite(durationMs) || durationMs < 0) {
+                series.invalidDurationTotal += 1;
+            }
+            else {
+                const bucket = REQUEST_DURATION_BOUNDS_MS.findIndex((bound) => durationMs <= bound);
+                series.durationBuckets[bucket < 0 ? REQUEST_DURATION_BOUNDS_MS.length : bucket] += 1;
+            }
+        };
+    }
+    snapshot() {
+        return Object.freeze({
+            started: this.started,
+            completed: this.completed,
+            aborted: this.aborted,
+            inFlight: this.started - this.completed - this.aborted,
+            durationBoundsMs: REQUEST_DURATION_BOUNDS_MS,
+            series: Object.freeze([...this.series.entries()]
+                .sort(([a], [b]) => a - b)
+                .map(([, series]) => Object.freeze({
+                ...series,
+                durationBuckets: Object.freeze([...series.durationBuckets]),
+            }))),
+        });
+    }
+}

package/dist/server/packageVersion.d.ts

@@ -0,0 +1 @@
+export declare function runtimeVersion(): string;

package/dist/server/packageVersion.js

@@ -0,0 +1,11 @@
+/**
+ * This runtime's version, read from its own package.json: what `--version`
+ * prints, what MCP's serverInfo says and what a build is pinned to. A module
+ * of its own so a start that only needs the number does not load the build.
+ */
+import { readFileSync } from 'node:fs';
+let version;
+export function runtimeVersion() {
+    version ??= JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    return version;
+}

package/dist/server/poolConfig.d.ts

@@ -0,0 +1,34 @@
+/** A connection's pool as its entry sizes it; what it leaves out is the process default. */
+export interface PoolSize {
+    read?: number;
+    write?: number;
+}
+/**
+ * Refused rather than clamped or ignored, as `writable` is: a number quietly
+ * overridden is a capacity plan that is not the one in the file. An HTTP
+ * connection has no pool, and neither has a URL that plainly names another
+ * engine; one that is still a `${VAR}` reference is checked when it opens
+ * (Registry.dial), once the environment has said what it names. `write`
+ * sizes the writers an App writes through; the database browser writes
+ * through one whatever it says (writeLanes.ts).
+ */
+export declare function poolOf(entry: Record<string, unknown>, http: boolean, path: string): PoolSize | undefined;
+/**
+ * A connection's `"replicas"`: `["postgres://…", "${REPLICA_URL}", …]`, read
+ * replicas of the database `url` names, each a URL of the same engine and
+ * each resolved as `url` is (`${VAR}`, keychain, credentials file). Up to
+ * MAX_REPLICAS. Refused for SQLite and HTTP, where nothing could replicate,
+ * rather than quietly ignored: a replica plan that is not happening is a
+ * capacity plan that is not the one in the file. A URL that is still a
+ * reference is checked when it opens (Registry.dial).
+ */
+export declare function replicasOf(entry: Record<string, unknown>, http: boolean, path: string): string[] | undefined;
+/**
+ * A connection's `"listen"`: a direct PostgreSQL URL (`"postgres://app@db:5432/app"`, or `${VAR}`) a jobs host
+ * holds its `LISTEN` on. Behind a transaction-mode pooler a session keeps no server connection between
+ * statements, so the main `url` cannot listen; this one names the database without the pooler. Refused for
+ * anything but PostgreSQL rather than ignored: a wake that is not happening is a 30-second wait nobody chose.
+ */
+export declare function listenOf(entry: Record<string, unknown>, http: boolean, path: string): string | undefined;
+/** Which engine a URL names, for a replica's agreement with its primary; undefined for anything else. */
+export declare function replicaEngine(url: string): 'PostgreSQL' | undefined;

package/dist/server/poolConfig.js

@@ -0,0 +1,114 @@
+/**
+ * A connection's `"pool"` and `"replicas"` in tablewalk.json, checked where the file is read:
+ * `{ "read": n, "write": m }`, each a whole number from 1 to 64 and either
+ * one optional, on a PostgreSQL connection. Apart from the loader because
+ * the rule is the pool's (postgresPool.ts holds the bounds); the loader only
+ * asks it, as it asks httpConnection.ts about an API's fields.
+ */
+import { isReaderCount, MAX_READERS } from '../adapters/postgresPool.js';
+import { isWriterCount, MAX_WRITERS } from '../adapters/writeLanes.js';
+import { MAX_REPLICAS } from '../adapters/replicas.js';
+/**
+ * Refused rather than clamped or ignored, as `writable` is: a number quietly
+ * overridden is a capacity plan that is not the one in the file. An HTTP
+ * connection has no pool, and neither has a URL that plainly names another
+ * engine; one that is still a `${VAR}` reference is checked when it opens
+ * (Registry.dial), once the environment has said what it names. `write`
+ * sizes the writers an App writes through; the database browser writes
+ * through one whatever it says (writeLanes.ts).
+ */
+export function poolOf(entry, http, path) {
+    const written = entry.pool;
+    if (written === undefined)
+        return undefined;
+    const where = `${path}: connection "${String(entry.name)}"`;
+    if (http)
+        throw new Error(`${where} is an HTTP connection; "pool" sizes database connections.`);
+    if (!written || typeof written !== 'object' || Array.isArray(written)) {
+        throw new Error(`${where} has "pool": ${JSON.stringify(written)}. It must be an object such as { "read": 16, "write": 8 }.`);
+    }
+    const pool = written;
+    const stray = Object.keys(pool).find((key) => key !== 'read' && key !== 'write');
+    if (stray !== undefined)
+        throw new Error(`${where} has "pool.${stray}". A pool takes "read" and "write".`);
+    if (pool.read === undefined && pool.write === undefined) {
+        throw new Error(`${where} has an empty "pool". Say how many connections may read or write at once, such as { "read": 16, "write": 8 }.`);
+    }
+    if (pool.read !== undefined && !isReaderCount(pool.read)) {
+        throw new Error(`${where} has "pool": { "read": ${JSON.stringify(pool.read)} }. It must be a whole number from 1 to ${MAX_READERS}, without quotes.`);
+    }
+    if (pool.write !== undefined && !isWriterCount(pool.write)) {
+        throw new Error(`${where} has "pool": { "write": ${JSON.stringify(pool.write)} }. It must be a whole number from 1 to ${MAX_WRITERS}, without quotes.`);
+    }
+    const url = String(entry.url);
+    if (!url.includes('$')) {
+        if (!/^postgres(ql)?:\/\//i.test(url))
+            throw new Error(`${where} is not a PostgreSQL connection; SQLite has no pool. Remove "pool".`);
+    }
+    return { ...(pool.read !== undefined ? { read: pool.read } : {}), ...(pool.write !== undefined ? { write: pool.write } : {}) };
+}
+/**
+ * A connection's `"replicas"`: `["postgres://…", "${REPLICA_URL}", …]`, read
+ * replicas of the database `url` names, each a URL of the same engine and
+ * each resolved as `url` is (`${VAR}`, keychain, credentials file). Up to
+ * MAX_REPLICAS. Refused for SQLite and HTTP, where nothing could replicate,
+ * rather than quietly ignored: a replica plan that is not happening is a
+ * capacity plan that is not the one in the file. A URL that is still a
+ * reference is checked when it opens (Registry.dial).
+ */
+export function replicasOf(entry, http, path) {
+    const written = entry.replicas;
+    if (written === undefined)
+        return undefined;
+    const where = `${path}: connection "${String(entry.name)}"`;
+    if (http)
+        throw new Error(`${where} is an HTTP connection; "replicas" are copies of a database.`);
+    if (!Array.isArray(written) || !written.length || written.some((url) => typeof url !== 'string' || !url.trim())) {
+        throw new Error(`${where} has "replicas": ${JSON.stringify(written)}. It must be a list of database URLs, such as ["postgres://reader@replica-1/app"].`);
+    }
+    if (written.length > MAX_REPLICAS)
+        throw new Error(`${where} names ${written.length} replicas; at most ${MAX_REPLICAS}.`);
+    const replicas = written.map((url) => url.trim());
+    if (new Set(replicas).size !== replicas.length)
+        throw new Error(`${where} names one replica twice in "replicas".`);
+    const url = String(entry.url);
+    if (!url.includes('$')) {
+        const engine = replicaEngine(url);
+        if (!engine)
+            throw new Error(`${where} is not a PostgreSQL connection; SQLite has no replicas. Remove "replicas".`);
+        const stray = replicas.find((replica) => !replica.includes('$') && replicaEngine(replica) !== engine);
+        if (stray !== undefined)
+            throw new Error(`${where} has a replica that is not a ${engine} URL; a replica is the same engine as "url".`);
+    }
+    return replicas;
+}
+/**
+ * A connection's `"listen"`: a direct PostgreSQL URL (`"postgres://app@db:5432/app"`, or `${VAR}`) a jobs host
+ * holds its `LISTEN` on. Behind a transaction-mode pooler a session keeps no server connection between
+ * statements, so the main `url` cannot listen; this one names the database without the pooler. Refused for
+ * anything but PostgreSQL rather than ignored: a wake that is not happening is a 30-second wait nobody chose.
+ */
+export function listenOf(entry, http, path) {
+    const written = entry.listen;
+    if (written === undefined)
+        return undefined;
+    const where = `${path}: connection "${String(entry.name)}"`;
+    if (http)
+        throw new Error(`${where} is an HTTP connection; "listen" is a database URL to wait for notifications on.`);
+    if (typeof written !== 'string' || !written.trim()) {
+        throw new Error(`${where} has "listen": ${JSON.stringify(written)}. It must be a PostgreSQL URL, such as "postgres://app@db-direct:5432/app".`);
+    }
+    const listen = written.trim();
+    if (!listen.includes('$') && replicaEngine(listen) !== 'PostgreSQL')
+        throw new Error(`${where} has a "listen" that is not a PostgreSQL URL; only PostgreSQL has LISTEN/NOTIFY.`);
+    const url = String(entry.url);
+    if (!url.includes('$') && replicaEngine(url) !== 'PostgreSQL')
+        throw new Error(`${where} is not a PostgreSQL connection, so it has nothing to listen on. Remove "listen".`);
+    return listen;
+}
+/** Which engine a URL names, for a replica's agreement with its primary; undefined for anything else. */
+export function replicaEngine(url) {
+    if (/^postgres(ql)?:\/\//i.test(url))
+        return 'PostgreSQL';
+    return undefined;
+}

package/dist/server/product.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which product this process is: the database browser (`tablewalk`) or the App framework (`mistri`). The engine is
+ * both binaries', and what an operator sets is said in the binary's own name: `TABLEWALK_READ_POOL` for the
+ * browser, `MISTRI_READ_POOL` for an App, read by the same code here. Each main says which it is before it reads a
+ * flag (packages/tablewalk/src/server/cli/browserMain.ts, packages/mistri/src/server/cli/mistriMain.ts); anything
+ * else that runs the engine — an App mounted in a host's server (`createHandler`), a test — is an App's.
+ *
+ * Only the variables both binaries read go through here. A variable one product alone reads names itself.
+ */
+type ProductName = 'tablewalk' | 'mistri';
+/** Say which product this process is. A main calls it first. */
+export declare function setProduct(name: ProductName): void;
+export declare const product: () => ProductName;
+/** The config file a project keeps beside it: `mistri.json` for an App, `tablewalk.json` for the browser. */
+export declare const configFileName: () => string;
+/** The variable an operator sets for `key` (`READ_POOL` → `MISTRI_READ_POOL`), in this product's name. */
+export declare const envName: (key: string) => string;
+/** What the environment holds for `key`, read in this product's name. */
+export declare const productEnv: (key: string, env?: NodeJS.ProcessEnv) => string | undefined;
+export {};

package/dist/server/product.js

@@ -0,0 +1,12 @@
+let current = 'mistri';
+/** Say which product this process is. A main calls it first. */
+export function setProduct(name) {
+    current = name;
+}
+export const product = () => current;
+/** The config file a project keeps beside it: `mistri.json` for an App, `tablewalk.json` for the browser. */
+export const configFileName = () => `${current}.json`;
+/** The variable an operator sets for `key` (`READ_POOL` → `MISTRI_READ_POOL`), in this product's name. */
+export const envName = (key) => `${current.toUpperCase()}_${key}`;
+/** What the environment holds for `key`, read in this product's name. */
+export const productEnv = (key, env = process.env) => env[envName(key)];

package/dist/server/recordHistoryOperations.d.ts

@@ -0,0 +1,39 @@
+import type { JournalEntry } from './journal.js';
+export type HistoryDraft = Omit<JournalEntry, 'id' | 'at' | 'connection'>;
+export type UnknownHistoryDraft = HistoryDraft & {
+    revertible: false;
+    undoState: 'unknown';
+};
+export interface PreparedWrite<R> {
+    result: R;
+    entry: HistoryDraft;
+}
+interface OwnedHistory {
+    publish(entry: HistoryDraft): JournalEntry;
+    /** Captured, synchronous, non-throwing quarantine. No clock or publication. */
+    quarantine(): void;
+}
+type Transaction<Tx, R> = (work: (tx: Tx) => Promise<R>) => Promise<R>;
+interface Preview<Tx, R> {
+    mode: 'preview';
+    transaction: Transaction<Tx, R>;
+    work(tx: Tx): Promise<R>;
+}
+interface Write<Tx, R> {
+    mode: 'write';
+    transaction: Transaction<Tx, PreparedWrite<R>>;
+    work(tx: Tx): Promise<PreparedWrite<R>>;
+    history: OwnedHistory;
+    uncertainty: UnknownHistoryDraft;
+    /** Trusted operation-specific rejection classification, never request data.
+     * It cannot classify unknown transaction acknowledgement as rejection. */
+    isRejection(error: unknown): boolean;
+}
+export declare function runRecordedTransaction<Tx, R>(options: Preview<Tx, R>): Promise<{
+    result: R;
+}>;
+export declare function runRecordedTransaction<Tx, R>(options: Write<Tx, R>): Promise<{
+    result: R;
+    undoId?: number;
+}>;
+export {};