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

package/dist/adapters/storeHost.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The seam an App store stands on: what a dialect adapter lends the stores
+ * that live in its database — the notification inbox, branding, the record
+ * history, the command journal and a public placement's — without knowing
+ * any of them.
+ *
+ * The stores are the App framework's (packages/mistri/src/server/stores/appStores.ts and
+ * the store folders under src/adapters); the adapter is the engine's, and the
+ * database browser opens the same adapter with no App framework installed.
+ * So the adapter offers its clients, its write queue and the schema-epoch
+ * cache it already keeps, and a store names its own meta row when it asks
+ * for an attested read. The adapter learns no store's tables from here.
+ *
+ * A host is kept beside its adapter rather than on it: a facade or a proxy
+ * that forwards an adapter's methods does not forward its host, so only the
+ * adapter that was constructed can lend its writer.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { TransactionOperations, WriteTransaction } from './adapter.js';
+import type { PostgresReadSnapshot, PostgresTransactionVerifier } from './postgres.js';
+import type { PgQuery } from './postgresPool.js';
+import type { PostgresScopeCatalog } from './scoped/postgresScopeCatalog.js';
+import type { SqliteScopeCatalog } from './scoped/sqliteScopeCatalog.js';
+import type { DatabaseSchema } from '../shared/schema.js';
+import type { RowScope } from '../shared/rowScope.js';
+/** A reserved store's meta row: the one row whose version says the layout, and the cache key its attestation is kept under. */
+export interface StoreMeta {
+    readonly name: string;
+    readonly table: string;
+    readonly version: number;
+}
+/**
+ * A journal kept in a write transaction beside its records: the command
+ * journal, or a public placement's. The adapter runs the transaction — its
+ * BEGIN, the schema epoch, the scope, the drain, the COMMIT and the outcome —
+ * and the journal is the App framework's: its tables, the SQL that attests
+ * them and the object a command writes its receipt through.
+ */
+interface TransactionJournal<W, C, J> {
+    /** The meta row read with the schema epoch, so the layout is attested once per epoch; without one, it is attested in every transaction. */
+    readonly meta?: StoreMeta;
+    /** The layout attested on the writer, after BEGIN and before the scope catalog is read: an unmigrated or altered layout refuses without a write. */
+    attest(writer: W): void | Promise<void>;
+    /** A scoped transaction's admission, after the scope catalog is read and verified, before the callback. */
+    admit?(writer: W, catalog: C, scope: RowScope): void | Promise<void>;
+    /** A journal that writes exactly fixed rows (a public intake's): its scoped records pass through this, and no new parent is counted into the principal's scope. */
+    fixedRecords?(records: WriteTransaction): WriteTransaction;
+    /** The journal over the writer and the operation queue its records share; `verified` is a verified scoped transaction's fence. */
+    open(writer: W, operations: TransactionOperations, verified?: () => void): J;
+    /** What a failed transaction throws, told whether it might have committed. */
+    failure(error: unknown, outcome: 'unknown' | 'not_applied'): unknown;
+    /**
+     * The statements the journal's first lookup of `receipt` sends, exactly, so
+     * they leave behind the transaction's BEGIN (writeAhead.ts): none for a
+     * receipt it would refuse. Its shape is the journal's own.
+     */
+    ahead?(receipt: unknown): readonly (string | Readonly<{
+        text: string;
+        values?: readonly unknown[];
+    }>)[];
+}
+export type PostgresTransactionJournal<J> = TransactionJournal<PgQuery, PostgresScopeCatalog, J>;
+export type SqliteTransactionJournal<J> = TransactionJournal<DatabaseSync, SqliteScopeCatalog, J>;
+/** How a journal transaction is shaped: ordinary, or over a row scope. */
+export interface JournalTransactionOptions<V> {
+    /** A row-scoped transaction: the scope's records, with the catalog evidence handed to the callback. */
+    readonly scope?: RowScope;
+    /** The outer bound the scope sits inside (scopedTransaction.ts ScopeBound), over the same tables. */
+    readonly bound?: RowScope;
+    /** A verified scoped transaction's trusted host check; its failures are not the journal's. */
+    readonly verify?: V;
+    /** A verified ordinary transaction's trusted host check, after BEGIN and again before COMMIT. */
+    readonly ordinaryVerify?: () => unknown;
+}
+/** The callback: the records, the journal, and a scoped transaction's catalog evidence (absent in an ordinary one). */
+export type JournalRun<J, T> = (records: WriteTransaction, journal: J, catalog?: DatabaseSchema) => Promise<T>;
+export interface PostgresStoreHost {
+    readonly dialect: 'postgres';
+    withReadClient<T>(work: (client: PgQuery) => Promise<T>): Promise<T>;
+    withWriteClient<T>(work: (client: PgQuery) => Promise<T>): Promise<T>;
+    /** `read`, told whether the store's layout stands attested under the schema epoch read first on `client`. */
+    attestedStore<T>(client: PgQuery, store: StoreMeta, read: (attested: boolean) => Promise<T>): Promise<T>;
+    /** Whether this is the constructed adapter over the connections it was built with: the only one a verified transaction runs on. */
+    verifiedSource(): boolean;
+    /** Records and a journal in one transaction (PostgresAdapter.journalTransaction). */
+    journalTransaction<J, T>(journal: PostgresTransactionJournal<J>, run: JournalRun<J, T>, options?: JournalTransactionOptions<PostgresTransactionVerifier>): Promise<T>;
+    /** Whether the connection names any replica: where it names none, `onHealthyReplicas` can only answer nothing, and a caller can skip the question that needs it. */
+    hasReplicas(): boolean;
+    /** `work` on each healthy replica, failures left out; none where the connection names no replicas. */
+    onHealthyReplicas<T>(work: (client: PgQuery) => Promise<T>): Promise<T[]>;
+    /** One read-only snapshot on an observed reader (PostgresAdapter.readSnapshot). */
+    readSnapshot<T>(run: (snapshot: PostgresReadSnapshot) => Promise<T>): Promise<T>;
+}
+export interface SqliteStoreHost {
+    readonly dialect: 'sqlite';
+    /** The read-only handle. */
+    reader(): DatabaseSync;
+    /** `work` in the write queue, on the writer. */
+    queueWrite<T>(work: (write: DatabaseSync) => T | Promise<T>): Promise<T>;
+    /** As PostgresStoreHost's, synchronous, on `db` (the reader unless a writer is named). */
+    attestedStore<T>(store: StoreMeta, read: (attested: boolean) => T, db?: DatabaseSync): T;
+    /** The file, for a reader of its own (a receipt's recovery). */
+    file(): string;
+    closed(): boolean;
+    /** Refuses once the path names another file than the one opened. */
+    assertWriteIdentity(): void;
+    /** Records and a journal in one transaction (SqliteAdapter.transact). */
+    journalTransaction<J, T>(journal: SqliteTransactionJournal<J>, run: JournalRun<J, T>, options?: JournalTransactionOptions<(db: DatabaseSync, catalog: SqliteScopeCatalog) => void>): Promise<T>;
+}
+export type StoreHost = PostgresStoreHost | SqliteStoreHost;
+/** The adapter's constructor only: the host it lends its stores. */
+export declare function lendStoreHost(adapter: object, host: StoreHost): void;
+/** The host a constructed adapter lent, or undefined for anything else (a facade, a proxy, an HTTP source). */
+export declare const storeHostOf: (adapter: unknown) => StoreHost | undefined;
+/**
+ * An engine wrapper that narrows what an adapter's writes may touch (hidden
+ * columns) lends the view here, so a store that runs work in its own
+ * transactions — the command journal — hands that work the narrowed records
+ * and catalog and never the adapter's own. The wrapper cannot carry the
+ * store's members itself: the engine does not name the stores.
+ */
+interface WriteView {
+    readonly over: object;
+    records(records: WriteTransaction): WriteTransaction;
+    catalog(catalog: DatabaseSchema): DatabaseSchema;
+}
+/** The wrapper's constructor only. */
+export declare function lendWriteView(wrapped: object, view: WriteView): void;
+export declare const writeViewOf: (wrapped: unknown) => WriteView | undefined;
+export {};

package/dist/adapters/storeHost.js

@@ -0,0 +1,13 @@
+const hosts = new WeakMap();
+/** The adapter's constructor only: the host it lends its stores. */
+export function lendStoreHost(adapter, host) {
+    hosts.set(adapter, Object.freeze(host));
+}
+/** The host a constructed adapter lent, or undefined for anything else (a facade, a proxy, an HTTP source). */
+export const storeHostOf = (adapter) => typeof adapter === 'object' && adapter !== null ? hosts.get(adapter) : undefined;
+const views = new WeakMap();
+/** The wrapper's constructor only. */
+export function lendWriteView(wrapped, view) {
+    views.set(wrapped, Object.freeze(view));
+}
+export const writeViewOf = (wrapped) => typeof wrapped === 'object' && wrapped !== null ? views.get(wrapped) : undefined;

package/dist/adapters/telemetry/drivers.d.ts

@@ -0,0 +1,21 @@
+/** The plan of a statement the observer recorded, run read-only; undefined when it can no longer be asked. */
+export declare function explainStatement(spanId: string): Promise<string[] | undefined>;
+/** Wrap the drivers once, for the life of the process. */
+export declare function instrumentDrivers(): void;
+interface PgClientLike {
+    query(...args: unknown[]): unknown;
+    connectionParameters?: Record<string, unknown>;
+}
+type PgClientClass = {
+    prototype: PgClientLike;
+} & (new (config: unknown) => PgClientLike & {
+    connect(): Promise<void>;
+    end(): Promise<void>;
+});
+export declare function instrumentPg(pg: {
+    Client?: PgClientClass;
+    Pool?: {
+        prototype: Record<string, unknown>;
+    };
+}): void;
+export {};

package/dist/adapters/telemetry/drivers.js

@@ -0,0 +1,321 @@
+/**
+ * A span for every statement the process runs, whichever of the three
+ * drivers runs it: node:sqlite and pg.
+ *
+ * At the driver, not in each adapter, because statements reach the database
+ * from dozens of places — the adapters, the command journal, the auth store,
+ * the job and event stores — and a span added to each would be a span
+ * forgotten in the next. Wrapping the driver's own `query` is also how the
+ * vendors' agents do it (dd-trace, OneAgent), and the wrappers chain: each
+ * keeps the function it found, so an agent loaded first or last still sees
+ * every call, and the modules keep their identity.
+ *
+ * Installed only when something listens (start.ts), and a statement is a
+ * span only inside another one — a request, a job, a command. Startup's
+ * catalog reads are not a trace anyone asked for.
+ *
+ * What travels: `db.system.name`, `db.operation.name`, `db.collection.name`,
+ * `db.query.summary` (statement.ts). What stays local, for the dev observer:
+ * the text, the parameters, the rows returned, the transaction, and a way to
+ * EXPLAIN it later.
+ */
+import { AsyncResource } from 'node:async_hooks';
+import { createRequire } from 'node:module';
+import { DatabaseSync, StatementSync } from 'node:sqlite';
+import { startSpan, observing, currentSpan } from './trace.js';
+import { summarizeStatement } from './statement.js';
+/** How to EXPLAIN a statement the observer shows, by its span. Bounded, and filled only while observing. */
+const explainers = new Map();
+const EXPLAINERS = 4000;
+function keepExplainer(spanId, explain) {
+    explainers.set(spanId, explain);
+    if (explainers.size > EXPLAINERS)
+        explainers.delete(explainers.keys().next().value);
+}
+/** The plan of a statement the observer recorded, run read-only; undefined when it can no longer be asked. */
+export async function explainStatement(spanId) {
+    const explain = explainers.get(spanId);
+    return explain ? explain() : undefined;
+}
+const EXPLAINABLE = new Set(['SELECT', 'WITH']);
+/** A statement's span, begun but not made current: a statement has no children. The caller ends it. */
+function beginStatement(dialect, text, params, explain) {
+    const { operation, table, summary } = summarizeStatement(text);
+    const span = startSpan(summary, {
+        kind: 'client',
+        childOnly: true,
+        attributes: {
+            'db.system.name': dialect,
+            'db.operation.name': operation,
+            'db.collection.name': table,
+            'db.query.summary': summary,
+        },
+    });
+    if (span.recording) {
+        span.detail(() => ({
+            sql: text.length > 20_000 ? `${text.slice(0, 20_000)}…` : text,
+            ...(params !== undefined ? { params: Array.isArray(params) ? params.slice(0, 200) : params } : {}),
+        }));
+        if (observing() && EXPLAINABLE.has(operation)) {
+            const explainer = explain?.(span);
+            if (explainer)
+                keepExplainer(span.spanId, explainer);
+        }
+    }
+    return span;
+}
+/** Settle a statement's span with its promise. */
+function settle(span, out) {
+    if (!out || typeof out.then !== 'function') {
+        span.end();
+        return out;
+    }
+    return out.then((result) => {
+        noteRows(span, result);
+        span.end();
+        return result;
+    }, (error) => {
+        span.fail(errorKind(error), error);
+        span.end();
+        throw error;
+    });
+}
+const rowsOf = (result) => {
+    if (Array.isArray(result))
+        return result.length;
+    if (result && typeof result === 'object') {
+        const r = result;
+        if (typeof r.rowCount === 'number')
+            return r.rowCount;
+        if (Array.isArray(r.rows))
+            return r.rows.length;
+        if (typeof r.affectedRows === 'number')
+            return r.affectedRows;
+        if (typeof r.changes === 'number' || typeof r.changes === 'bigint')
+            return Number(r.changes);
+    }
+    return undefined;
+};
+const noteRows = (span, result) => {
+    const rows = rowsOf(result);
+    if (rows !== undefined) {
+        span.setAttribute('db.response.returned_rows', rows);
+        span.detail(() => ({ rows }));
+    }
+};
+let installed = false;
+/** Wrap the drivers once, for the life of the process. */
+export function instrumentDrivers() {
+    if (installed)
+        return;
+    installed = true;
+    instrumentSqlite();
+    const require = createRequire(import.meta.url);
+    try {
+        instrumentPg(require('pg'));
+    }
+    catch {
+        /* pg is optional */
+    }
+}
+/**
+ * A pool's checkout, bound to whoever asked for it. A pool that is full
+ * queues the waiter and calls it back when another request releases its
+ * connection — from inside that request's release, and so inside its async
+ * context. `pool.query` asks through that callback, so without this its
+ * statement was counted in the releasing request's trace (a finished one,
+ * often) and never in its own, and a busy row-policy App's traces showed
+ * N+1 patterns that were only other requests' lookups. A promise checkout
+ * needs nothing: `await` resumes in the awaiting context.
+ */
+function bindCheckouts(proto, method) {
+    const original = proto?.[method];
+    if (!proto || typeof original !== 'function')
+        return;
+    proto[method] = function (...args) {
+        const at = args.findIndex((arg) => typeof arg === 'function');
+        // Bound whether or not a span is current: a waiter outside any request must not land in the releaser's either.
+        if (at >= 0)
+            args[at] = AsyncResource.bind(args[at]);
+        return original.apply(this, args);
+    };
+}
+/* ---------- node:sqlite ---------- */
+const statementDb = new WeakMap();
+const sqliteTx = new WeakMap();
+let sqliteIds = 0;
+function sqliteTransaction(db) {
+    if (!db)
+        return undefined;
+    let state = sqliteTx.get(db);
+    if (!state)
+        sqliteTx.set(db, (state = { n: 0, open: false, id: ++sqliteIds }));
+    let inside = false;
+    try {
+        inside = db.isTransaction;
+    }
+    catch {
+        return undefined;
+    }
+    if (inside && !state.open)
+        state.n++;
+    state.open = inside;
+    return inside ? `sqlite:${state.id}/tx${state.n}` : undefined;
+}
+function instrumentSqlite() {
+    const prepare = DatabaseSync.prototype.prepare;
+    DatabaseSync.prototype.prepare = function (...args) {
+        const statement = prepare.apply(this, args);
+        if (currentSpan())
+            statementDb.set(statement, new WeakRef(this));
+        return statement;
+    };
+    const exec = DatabaseSync.prototype.exec;
+    DatabaseSync.prototype.exec = function (sql) {
+        if (!currentSpan())
+            return exec.call(this, sql);
+        const span = beginStatement('sqlite', sql, undefined);
+        try {
+            const out = exec.call(this, sql);
+            const tx = sqliteTransaction(this);
+            if (tx)
+                span.detail(() => ({ transaction: tx }));
+            return out;
+        }
+        catch (error) {
+            span.fail(errorKind(error), error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    };
+    for (const method of ['all', 'get', 'run']) {
+        const original = StatementSync.prototype[method];
+        StatementSync.prototype[method] = function (...args) {
+            if (!currentSpan())
+                return original.apply(this, args);
+            const db = statementDb.get(this)?.deref();
+            const text = this.sourceSQL;
+            const ref = statementDb.get(this);
+            const span = beginStatement('sqlite', text, args, () => ref
+                ? () => {
+                    const target = ref.deref();
+                    if (!target || !target.isOpen)
+                        return Promise.resolve(['The database this ran on is closed.']);
+                    const rows = prepare.call(target, `EXPLAIN QUERY PLAN ${text}`).all(...args);
+                    const depth = new Map();
+                    return Promise.resolve(rows.map((row) => {
+                        const level = (depth.get(row.parent) ?? -1) + 1;
+                        depth.set(row.id, level);
+                        return `${'  '.repeat(level)}${row.detail}`;
+                    }));
+                }
+                : undefined);
+            try {
+                const tx = sqliteTransaction(db);
+                const result = original.apply(this, args);
+                if (method === 'get') {
+                    span.setAttribute('db.response.returned_rows', result === undefined ? 0 : 1);
+                    span.detail(() => ({ rows: result === undefined ? 0 : 1 }));
+                }
+                else
+                    noteRows(span, result);
+                if (tx)
+                    span.detail(() => ({ transaction: tx }));
+                return result;
+            }
+            catch (error) {
+                span.fail(errorKind(error), error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        };
+    }
+}
+const pgTx = new WeakMap();
+let pgIds = 0;
+export function instrumentPg(pg) {
+    bindCheckouts(pg?.Pool?.prototype, 'connect');
+    const Client = pg?.Client;
+    if (!Client?.prototype?.query)
+        return;
+    const query = Client.prototype.query;
+    Client.prototype.query = function (...args) {
+        const [config, values] = args;
+        const submittable = config && typeof config === 'object' && typeof config.submit === 'function';
+        if (!currentSpan() || submittable)
+            return query.apply(this, args);
+        const text = typeof config === 'string' ? config : String(config?.text ?? '');
+        const params = typeof values === 'function' || values === undefined ? config?.values : values;
+        let state = pgTx.get(this);
+        if (!state)
+            pgTx.set(this, (state = { n: 0, open: false, id: ++pgIds }));
+        const head = text.trimStart().slice(0, 20).toUpperCase();
+        if (/^(BEGIN|START TRANSACTION)/.test(head)) {
+            state.n++;
+            state.open = true;
+        }
+        const tx = state.open ? `pg:${state.id}/tx${state.n}` : undefined;
+        if (/^(COMMIT|ROLLBACK|END)\b/.test(head) && !head.startsWith('ROLLBACK TO'))
+            state.open = false;
+        const settings = this.connectionParameters;
+        const span = beginStatement('postgresql', text, params, () => settings ? pgExplainer(Client, { ...settings }, text, params) : undefined);
+        if (tx)
+            span.detail(() => ({ transaction: tx }));
+        const callbackAt = args.findIndex((arg) => typeof arg === 'function');
+        if (callbackAt >= 0) {
+            const done = args[callbackAt];
+            args[callbackAt] = (error, result) => {
+                if (error)
+                    span.fail(errorKind(error), error);
+                else
+                    noteRows(span, result);
+                span.end();
+                done(error, result);
+            };
+            try {
+                return query.apply(this, args);
+            }
+            catch (error) {
+                span.fail(errorKind(error), error);
+                span.end();
+                throw error;
+            }
+        }
+        return settle(span, query.apply(this, args));
+    };
+}
+function pgExplainer(Client, settings, text, params) {
+    return async () => {
+        // Its own connection, read-only: the one the statement ran on may be in someone's transaction now.
+        const probe = new Client({
+            user: settings.user,
+            password: settings.password,
+            host: settings.host,
+            port: settings.port,
+            database: settings.database,
+            ssl: settings.ssl,
+            options: settings.options,
+            connectionTimeoutMillis: 5000,
+        });
+        await probe.connect();
+        try {
+            await probe.query('BEGIN READ ONLY');
+            await probe.query("SET LOCAL statement_timeout = '5s'");
+            const plan = (await probe.query(`EXPLAIN ${text}`, Array.isArray(params) ? params : []));
+            return plan.rows.map((row) => String(Object.values(row)[0]));
+        }
+        finally {
+            await probe.query('ROLLBACK').catch(() => { });
+            await probe.end().catch(() => { });
+        }
+    };
+}
+/** A driver error's travelling name: its SQLSTATE or errno name when it has one (never its message). */
+function errorKind(error) {
+    const code = error?.code;
+    return typeof code === 'string' && /^[A-Z0-9_]{1,40}$/.test(code) ? code : 'DatabaseError';
+}

package/dist/adapters/telemetry/metrics.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The process's metrics, kept only while an exporter wants them.
+ *
+ * Instruments are declared here, once, with their OpenTelemetry names and
+ * units, so a dashboard built on Datadog or Dynatrace finds the standard
+ * `http.server.request.duration` where it looks for it. Their attributes are
+ * the same travelling kind a span's are — a route template, a status, a
+ * command id, an outcome — and never a value from a request: every series
+ * is bounded by what the App declares.
+ *
+ * With no exporter, `record` returns at its first line. Cumulative
+ * temporality, which every OTLP backend accepts; the exporter reads a
+ * snapshot on its interval.
+ */
+import type { AttributeValue } from './trace.js';
+import type { Metric, MetricPoint } from './otlpEncode.js';
+type Attrs = Readonly<Record<string, AttributeValue | undefined>>;
+type Kind = Metric['kind'];
+declare const gauges: Array<() => Array<{
+    name: string;
+    description: string;
+    unit: string;
+    kind: 'gauge' | 'updown';
+    points: MetricPoint[];
+}>>;
+declare class Instrument {
+    readonly name: string;
+    readonly description: string;
+    readonly unit: string;
+    readonly kind: Kind;
+    readonly bounds: readonly number[];
+    readonly series: Map<string, {
+        attributes: Record<string, AttributeValue>;
+        value: number;
+        count: number;
+        sum: number;
+        buckets: number[];
+        min: number;
+        max: number;
+    }>;
+    constructor(name: string, description: string, unit: string, kind: Kind, bounds?: readonly number[]);
+    record(value: number, attributes?: Attrs): void;
+    snapshot(time: number): Metric | undefined;
+}
+export declare const metrics: {
+    /** `http.server.request.duration`: by method, route template and status. */
+    httpDuration: Instrument;
+    /** Business commands by id and outcome (applied, replayed, not_applied, unknown) and refusal code. */
+    commands: Instrument;
+    commandDuration: Instrument;
+    /** `db.client.operation.duration`: by system, operation and table. */
+    dbDuration: Instrument;
+    /** Job attempts by job and outcome code; lag from due to claimed. */
+    jobAttempts: Instrument;
+    jobLag: Instrument;
+    /** Outbound calls (webhooks, HTTP sources, email) by kind and outcome. */
+    outbound: Instrument;
+};
+/** A gauge read when the exporter reads: the pools, the caches, the sessions. */
+export declare function observeGauges(read: (typeof gauges)[number]): () => void;
+export declare function enableMetrics(): void;
+export declare function snapshotMetrics(): Metric[];
+export {};

package/dist/adapters/telemetry/metrics.js

@@ -0,0 +1,122 @@
+/** Seconds, as the conventions ask for durations; the bounds are theirs for HTTP. */
+const DURATION_BOUNDS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
+/** Series per instrument. Past it a new combination is dropped, not a process's memory. */
+const SERIES = 2000;
+let on = false;
+const started = Date.now();
+const instruments = new Map();
+const gauges = [];
+class Instrument {
+    name;
+    description;
+    unit;
+    kind;
+    bounds;
+    series = new Map();
+    constructor(name, description, unit, kind, bounds = DURATION_BOUNDS) {
+        this.name = name;
+        this.description = description;
+        this.unit = unit;
+        this.kind = kind;
+        this.bounds = bounds;
+    }
+    record(value, attributes = {}) {
+        if (!on || !Number.isFinite(value))
+            return;
+        const clean = Object.fromEntries(Object.entries(attributes).filter(([, v]) => v !== undefined));
+        const key = JSON.stringify(Object.entries(clean).sort(([a], [b]) => a.localeCompare(b)));
+        let entry = this.series.get(key);
+        if (!entry) {
+            if (this.series.size >= SERIES)
+                return;
+            entry = {
+                attributes: clean,
+                value: 0,
+                count: 0,
+                sum: 0,
+                buckets: Array.from({ length: this.bounds.length + 1 }, () => 0),
+                min: Infinity,
+                max: -Infinity,
+            };
+            this.series.set(key, entry);
+        }
+        if (this.kind === 'histogram') {
+            entry.count++;
+            entry.sum += value;
+            entry.min = Math.min(entry.min, value);
+            entry.max = Math.max(entry.max, value);
+            let slot = this.bounds.findIndex((bound) => value <= bound);
+            if (slot < 0)
+                slot = this.bounds.length;
+            entry.buckets[slot]++;
+        }
+        else
+            entry.value += value;
+    }
+    snapshot(time) {
+        if (!this.series.size)
+            return undefined;
+        const points = [...this.series.values()].map((entry) => this.kind === 'histogram'
+            ? {
+                attributes: entry.attributes,
+                count: entry.count,
+                sum: entry.sum,
+                bounds: this.bounds,
+                buckets: entry.buckets,
+                ...(entry.count ? { min: entry.min, max: entry.max } : {}),
+            }
+            : { attributes: entry.attributes, value: entry.value });
+        return { name: this.name, description: this.description, unit: this.unit, kind: this.kind, points, start: started, time };
+    }
+}
+function instrument(name, description, unit, kind, bounds) {
+    const made = new Instrument(name, description, unit, kind, bounds);
+    instruments.set(name, made);
+    return made;
+}
+export const metrics = {
+    /** `http.server.request.duration`: by method, route template and status. */
+    httpDuration: instrument('http.server.request.duration', 'Duration of HTTP server requests.', 's', 'histogram'),
+    /** Business commands by id and outcome (applied, replayed, not_applied, unknown) and refusal code. */
+    commands: instrument('mistri.command.executions', 'Business command executions by outcome.', '{execution}', 'counter'),
+    commandDuration: instrument('mistri.command.duration', 'Duration of business command executions.', 's', 'histogram'),
+    /** `db.client.operation.duration`: by system, operation and table. */
+    dbDuration: instrument('db.client.operation.duration', 'Duration of database client operations.', 's', 'histogram'),
+    /** Job attempts by job and outcome code; lag from due to claimed. */
+    jobAttempts: instrument('mistri.job.attempts', 'Job attempts by outcome.', '{attempt}', 'counter'),
+    jobLag: instrument('mistri.job.lag', 'Time from a job being due to its attempt starting.', 's', 'histogram', [0.1, 0.5, 1, 5, 10, 30, 60, 300, 900, 3600]),
+    /** Outbound calls (webhooks, HTTP sources, email) by kind and outcome. */
+    outbound: instrument('mistri.outbound.calls', 'Outbound calls by kind and outcome.', '{call}', 'counter'),
+};
+/** A gauge read when the exporter reads: the pools, the caches, the sessions. */
+export function observeGauges(read) {
+    gauges.push(read);
+    return () => {
+        const at = gauges.indexOf(read);
+        if (at >= 0)
+            gauges.splice(at, 1);
+    };
+}
+export function enableMetrics() {
+    on = true;
+}
+export function snapshotMetrics() {
+    const time = Date.now();
+    const out = [];
+    for (const each of instruments.values()) {
+        const metric = each.snapshot(time);
+        if (metric)
+            out.push(metric);
+    }
+    for (const read of gauges) {
+        try {
+            for (const gauge of read())
+                if (gauge.points.length)
+                    out.push({ ...gauge, start: started, time });
+        }
+        catch {
+            /* a gauge that cannot be read is left out */
+        }
+    }
+    return out;
+}