@apisurf/wire-db 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Luka Vidakovic
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @apisurf/wire-db
+
+The SQLite store behind [`@apisurf/wire`](https://www.npmjs.com/package/@apisurf/wire):
+schema, migrations, the run writer and the read queries.
+
+**You probably want `@apisurf/wire` instead.** That package is the `wire` CLI —
+it records a script's HTTP traffic and gives you `wire ls`, `wire get` and
+`wire sql` to read it back. This one is the library underneath, published so
+that anything else reading a `wire.sqlite` file agrees with the CLI about what
+is in it rather than re-deriving the schema.
+
+```bash
+pnpm add @apisurf/wire-db
+```
+
+Needs Node >= 20. `better-sqlite3` is a native addon, so installing this
+compiles or downloads a prebuilt binary.
+
+## Opening a database
+
+```ts
+import { openDb, resolveDbPath } from "@apisurf/wire-db";
+
+const db = openDb({ path: "./wire.sqlite" }); // created and migrated
+const reader = openDb({ path: "./wire.sqlite", mustExist: true, skipMigrations: true });
+```
+
+`openDb` returns a `better-sqlite3` `Database`. It creates the file and brings
+it up to the current schema version unless you opt out:
+
+| Option           |                                                                            |
+| ---------------- | -------------------------------------------------------------------------- |
+| `path`           | Database file. Relative paths resolve against `cwd`. Default `wire.sqlite` |
+| `cwd`            | Base for a relative `path`. Default `process.cwd()`                        |
+| `mustExist`      | Throw instead of creating the file                                         |
+| `skipMigrations` | Do not migrate — for readers that expect an already-migrated file          |
+
+It sets WAL, `synchronous=NORMAL`, a 64 MiB page cache, memory temp store and
+foreign keys. WAL is what lets a reader open the file while a run is still
+writing to it.
+
+`resolveDbPath` applies the same path rules without opening anything.
+
+## Reading
+
+Query the views, not the base tables: `v_runs`, `v_requests`, `v_headers`,
+`v_bodies`, `v_messages`, `v_checks`, plus the `tags` table and the `body_fts`
+full-text index.
+
+The query helpers are the statements the CLI and the UI share:
+
+```ts
+import { openDb, listRuns, listRequests, getRequestDetail } from "@apisurf/wire-db";
+
+const db = openDb({ mustExist: true, skipMigrations: true });
+const runs = listRuns(db, 20); // limit defaults to 200
+const requests = listRequests(db, runs[0].id);
+const detail = getRequestDetail(db, requests[0].id);
+```
+
+`getRun`, `getRunAnalytics`, `getRequestDetail`, `listRuns`, `listRunsForEntry`,
+`listRequests`, `listMessages`, `listChecks`, `listRunTags`, `listScripts`.
+
+### Projected reads
+
+`ENTITIES` is the entity map behind `wire get` and `wire ls` — six entities
+(`run`, `request`, `check`, `body`, `message`, `header`), each with the view it
+reads, the column it keys on, its default field set and the filters it accepts.
+`selectEntity` runs a projected read against one; `findEntity` resolves
+`request`, `requests` or `v_requests` to the same definition.
+
+```ts
+import { openDb, findEntity, selectEntity } from "@apisurf/wire-db";
+
+const entity = findEntity("requests");
+const rows = selectEntity(db, entity, {
+  fields: entity.defaultFields,
+  filters: { run: 7 }, // filter names, not columns — validated against entity.filters
+  limit: 20,
+});
+```
+
+A field name the entity does not have throws `UnknownFieldError`, which carries
+the entity and the valid names. `PREVIEW_CHARS` is the width of the bounded
+`preview` field that stands in for a payload.
+
+### Describing the file
+
+`listRelations`, `relationExists`, `describeRelation`, `entityFields` and
+`untypedColumns` read the schema out of the file at runtime — this is what
+`wire schema` prints, so it describes the database in hand rather than the
+schema this build was compiled against.
+
+## Writing
+
+`RunWriter` is the write path: one instance per run, batched inserts, interned
+strings and content-addressed payloads.
+
+```ts
+import { openDb, RunWriter } from "@apisurf/wire-db";
+
+const writer = new RunWriter(db, {
+  uid: randomUUID(),
+  label: "nightly",
+  entry: "/abs/path/to/flow.ts",
+  cwd: process.cwd(),
+  nodeVersion: process.versions.node,
+  startedAt: Date.now(),
+});
+
+writer.write(records); // captured requests, messages and headers
+writer.writeChecks(checks); // check() / assert() outcomes
+writer.finish({ finishedAt: Date.now(), exitStatus: "ok" });
+```
+
+Payloads are deduped by SHA-256, so the same response body recorded a hundred
+times is stored once. Text payloads are indexed into `body_fts`.
+
+## Schema version
+
+```ts
+import { SCHEMA_VERSION } from "@apisurf/wire-db";
+```
+
+`SCHEMA_VERSION` is the migration count this build writes, and it is what
+`wire --version` reports. A file written by a newer build refuses to open on an
+older one — comparing these two numbers is the explanation for that error.
+
+Migrations are forward-only and applied in order on open.
+
+## License
+
+ISC. Full documentation: <https://github.com/apisurf/wire#readme>

package/dist/index.d.ts

@@ -0,0 +1,547 @@
+import Database from 'better-sqlite3';
+import { MessageDirection, CapturedKind, HeaderPair, CapturedRecord } from './types.js';
+export { CapturedBody, CapturedKind, CapturedMessage, CapturedRecord, CapturedRequest, CapturedTimings, HeaderPair, MessageDirection } from './types.js';
+
+type Db = Database.Database;
+interface OpenOptions {
+    /** Path to the database file. Relative paths resolve against `cwd`. */
+    path?: string;
+    cwd?: string;
+    /** Fail instead of creating the file when it does not exist. */
+    mustExist?: boolean;
+    /** Skip migrations (readers that expect an already-migrated file). */
+    skipMigrations?: boolean;
+}
+declare function resolveDbPath(options?: OpenOptions): string;
+/**
+ * Open (and by default create + migrate) the local database.
+ *
+ * The pragmas below are the difference between "a SQLite file" and "a SQLite
+ * file that keeps up with a script hammering an API":
+ *   - WAL lets the web UI read while a run is still writing.
+ *   - synchronous=NORMAL skips an fsync per commit. On a crash we can lose the
+ *     last transaction; for captured dev traffic that trade is obviously right.
+ *   - a 64 MiB page cache and memory temp storage keep sorts and the FTS merge
+ *     off disk.
+ */
+declare function openDb(options?: OpenOptions): Db;
+
+/** Schema version this build writes. Equals the number of migrations. */
+declare const SCHEMA_VERSION: number;
+
+/**
+ * The named surface behind `wire schema`, `wire get` and `wire ls`.
+ *
+ * `wire sql` is the complete interface and always will be, but it asks the
+ * caller to already know that `v_requests` exists, that the column is
+ * `duration_ms` and not `duration`, and that a payload lives behind
+ * `response_body_id`. This module is the smaller surface that answers those
+ * questions instead of assuming them: a fixed set of entities, each mapped to a
+ * view, each with a curated default field set.
+ *
+ * Two rules shape everything here.
+ *
+ * **The schema is read from the database, never from a list kept alongside it.**
+ * The real schema is a set of embedded migration strings, and any second
+ * description of it rots the first time a migration lands. Column names and
+ * types come from `pragma_table_info` at runtime. The only hand-maintained
+ * facts are one prose line per view and the type map below.
+ *
+ * **No field is ever selected that the caller did not ask for.** That is a
+ * context-window rule first — an agent must not be handed a 2 MB body it did
+ * not request — but it is also a query-cost rule. The views are not
+ * materialized, and `v_runs`'s counters are correlated subqueries; SQLite
+ * prunes the ones a projection never references, so a narrow field list is
+ * measurably cheaper (~160 ms vs ~1 ms across 5k runs). Projection is the
+ * mechanism for both.
+ */
+
+type Row = Record<string, unknown>;
+interface ColumnInfo {
+    name: string;
+    /** SQLite's declared type, or the one from {@link COMPUTED_TYPES}. */
+    type: string;
+    /**
+     * True when the type came from the map below rather than from SQLite —
+     * i.e. the column is an expression in the view and has no origin column.
+     */
+    computed: boolean;
+}
+interface RelationInfo {
+    name: string;
+    type: "view" | "table";
+    description: string | null;
+}
+/**
+ * Every relation worth querying.
+ *
+ * Views only by default, because that is the documented surface and the raw
+ * tables store interned ids rather than the strings anyone wants to read.
+ * `all` adds the base tables — minus FTS5's shadow tables, which are storage
+ * for `body_fts` and not something to query directly.
+ */
+declare function listRelations(db: Db, options?: {
+    all?: boolean;
+}): RelationInfo[];
+/** True when a relation of that name exists. Guards every interpolation below. */
+declare function relationExists(db: Db, name: string): boolean;
+/**
+ * Columns of a view or table, with types.
+ *
+ * Uses the `pragma_table_info` table-valued function rather than the `PRAGMA`
+ * statement so the relation name is a bound parameter and never string
+ * interpolation.
+ */
+declare function describeRelation(db: Db, name: string): ColumnInfo[];
+/**
+ * Every computed column that has no entry in {@link COMPUTED_TYPES}.
+ *
+ * Exported for the test that keeps the map honest: a migration that adds an
+ * expression column to a view should fail the suite, not ship an untyped
+ * column into `wire schema`.
+ */
+declare function untypedColumns(db: Db): string[];
+interface EntityDef {
+    /** Singular name, as typed: `wire get request 42`. */
+    readonly name: string;
+    /** Plural, as typed: `wire ls requests`. */
+    readonly plural: string;
+    readonly view: string;
+    /** Column `get <entity> <id>` matches on. Not always unique — see `header`. */
+    readonly key: string;
+    readonly defaultFields: readonly string[];
+    readonly description: string;
+    /** `--run` / `--request` narrowing for `ls`, mapped to real columns. */
+    readonly filters: Readonly<Record<string, string>>;
+    /** Default ORDER BY for `ls`. */
+    readonly order: string;
+    /**
+     * Fields computed in this module rather than selected from the view, mapped
+     * to the column they derive from. They are not columns and `wire schema` does
+     * not report them as such.
+     */
+    readonly derived: Readonly<Record<string, string>>;
+}
+/**
+ * Default field sets are the whole feature: defaults are what an agent
+ * actually uses, so what is left out matters more than what is in.
+ *
+ * Two exclusions are deliberate. No default set contains a payload column
+ * (`text`) — a body is reached through `preview`, or by asking for `text` by
+ * name. And `run` carries only `request_count` of the six counters on `v_runs`,
+ * so the common listing costs one correlated subquery per row instead of six.
+ */
+declare const ENTITIES: readonly EntityDef[];
+/** Resolve `request`, `requests`, or `v_requests` to one entity. */
+declare function findEntity(name: string): EntityDef | null;
+/** Every field name `--fields` accepts for an entity: real columns, then derived. */
+declare function entityFields(db: Db, entity: EntityDef): string[];
+declare class UnknownFieldError extends Error {
+    readonly entity: EntityDef;
+    readonly field: string;
+    readonly available: string[];
+    constructor(entity: EntityDef, field: string, available: string[]);
+}
+/** How many characters of a payload a derived `preview` keeps. */
+declare const PREVIEW_CHARS = 120;
+interface SelectOptions {
+    fields: readonly string[];
+    /** `get`: the ids to match on {@link EntityDef.key}. */
+    ids?: readonly (number | string)[];
+    /** `ls`: `{run: 7}` etc., validated against {@link EntityDef.filters}. */
+    filters?: Readonly<Record<string, number>>;
+    limit?: number;
+}
+/**
+ * Read an entity, selecting only the requested fields.
+ *
+ * Every identifier reaching SQL is first matched against the live column list,
+ * so a field name is either a column that exists or an error — there is no path
+ * from user input to interpolated SQL. Values are always bound.
+ */
+declare function selectEntity(db: Db, entity: EntityDef, options: SelectOptions): Row[];
+
+/**
+ * The shapes that cross the package boundaries.
+ *
+ * The WRITE contract (`Captured*`, `HeaderPair`) belongs to @wire/capture, which
+ * produces it; {@link import("./writer.js").RunWriter} persists it. It is
+ * re-exported here so a consumer that only stores traffic never has to name the
+ * capture package. Everything below is the READ contract, consumed by the CLI
+ * and the web UI.
+ */
+
+/** Everything known about a run at the moment it starts. */
+interface RunStart {
+    uid: string;
+    label: string | null;
+    /** Absolute path of the executed file, or `<inline>` for `execute -e`. */
+    entry: string;
+    /** The snippet, when the run had no file behind it. */
+    entrySource?: string | null;
+    cwd: string;
+    /** Environment the run was made against, when one was selected. */
+    env?: string | null;
+    nodeVersion: string;
+    startedAt: number;
+}
+/** How a run ended. */
+interface RunEnd {
+    finishedAt: number;
+    exitStatus: "ok" | "error";
+    errorName?: string | null;
+    errorMessage?: string | null;
+}
+/**
+ * Which of the two check functions made a judgement.
+ *
+ * `check` records and returns; `assert` records and throws, so an `assert` row
+ * with `status = 'fail'` is always the last check of its run.
+ */
+type CheckMode = "check" | "assert";
+type CheckStatus = "pass" | "fail";
+/** One assertion, as handed to {@link import("./writer.js").RunWriter.writeChecks}. */
+interface CheckRecord {
+    /** What was being checked, in the author's words. */
+    name: string;
+    mode: CheckMode;
+    status: CheckStatus;
+    /** Epoch ms at the moment the check ran. */
+    ts: number;
+    /**
+     * The author's failure message. Only meaningful on a failure, and only when
+     * one was passed — it is stored as NULL otherwise.
+     */
+    message?: string | null;
+}
+/** A row of `v_runs`. */
+interface RunRow {
+    id: number;
+    uid: string;
+    label: string | null;
+    entry: string;
+    entry_source: string | null;
+    cwd: string;
+    env: string | null;
+    node_version: string;
+    started_at: number;
+    finished_at: number | null;
+    exit_status: string | null;
+    error_name: string | null;
+    error_message: string | null;
+    request_count: number;
+    error_count: number;
+    /** Requests that were WebSocket or SSE connections rather than plain HTTP. */
+    connection_count: number;
+    /** Frames and events across every connection in the run. */
+    message_count: number;
+    /** Assertions the run made, passing and failing. */
+    check_count: number;
+    failed_check_count: number;
+    total_duration_ms: number | null;
+    total_bytes: number | null;
+}
+/** A row of `v_checks`: one assertion the run made. */
+interface CheckRow {
+    id: number;
+    run_id: number;
+    /** Order within the run, from 0. */
+    seq: number;
+    ts: number;
+    name: string;
+    mode: CheckMode;
+    status: CheckStatus;
+    /** The author's message. Null on a pass, and null when none was given. */
+    message: string | null;
+}
+/**
+ * One executed file, folded across every run of it.
+ *
+ * `entry` is the identity: the absolute path of the script that was executed.
+ * A label can change between runs (`--label`), the path cannot, so grouping on
+ * it is the only grouping that stays stable.
+ */
+interface ScriptRow {
+    entry: string;
+    /** Working directory of the most recent run. */
+    cwd: string;
+    /** Label of the most recent run. */
+    label: string | null;
+    run_count: number;
+    /** Runs that ended with `exit_status = 'error'`. */
+    failed_run_count: number;
+    /** The most recent run, so a script row can link straight to it. */
+    last_run_id: number;
+    last_started_at: number;
+    last_exit_status: string | null;
+    /**
+     * Totals across every run of this script. `request_count` counts connections
+     * too, exactly as `v_runs` does — subtract `connection_count` for the plain
+     * HTTP calls, the way the CLI summary reports them.
+     */
+    request_count: number;
+    connection_count: number;
+    message_count: number;
+    error_count: number;
+    /** Assertions across every run of this script, and how many of them failed. */
+    check_count: number;
+    failed_check_count: number;
+    total_bytes: number | null;
+}
+/** The columns of `v_requests` needed for the request list. */
+interface RequestListRow {
+    id: number;
+    seq: number;
+    ts: number;
+    /** `http`, `ws` or `sse`. */
+    kind: CapturedKind;
+    /** Frames or events on this connection; 0 for plain HTTP. */
+    message_count: number;
+    method: string;
+    host: string;
+    path: string;
+    status: number | null;
+    ok: number | null;
+    error_name: string | null;
+    duration_ms: number;
+    request_bytes: number;
+    response_bytes: number;
+}
+/** A full row of `v_requests`. */
+interface RequestRow extends RequestListRow {
+    run_id: number;
+    query: string | null;
+    url: string;
+    error_message: string | null;
+    /** Connection phases. All null on a reused connection — nothing was set up. */
+    dns_ms: number | null;
+    connect_ms: number | null;
+    tls_ms: number | null;
+    ttfb_ms: number | null;
+    download_ms: number | null;
+    request_content_type: string | null;
+    response_content_type: string | null;
+    request_body_id: number | null;
+    response_body_id: number | null;
+}
+/**
+ * How a payload should be drawn.
+ *
+ * Decided here rather than in the UI, because the decision needs the raw bytes
+ * and the `is_text` flag — neither of which survives the trip to a component.
+ */
+type BodyKind = "empty" | "text" | "json" | "image" | "binary";
+/** Anything `JSON.parse` can return — spelled out, so a `BodyView` stays serializable. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A payload shaped for display. */
+interface BodyView {
+    kind: BodyKind;
+    present: boolean;
+    /**
+     * The payload decoded. Null for anything not readable as text — and for JSON,
+     * which travels parsed, in `json`, rather than as text as well.
+     */
+    text: string | null;
+    /** The parsed payload when `kind` is `"json"`, else null. Always an object or an array. */
+    json: JsonValue | null;
+    /** A `data:` URL when `kind` is `"image"`, else null. */
+    dataUrl: string | null;
+    contentType: string | null;
+    size: number | null;
+    truncated: boolean;
+    /** Set when there is nothing to show and the reason is worth stating. */
+    note: string | null;
+}
+interface RequestDetail {
+    request: RequestRow;
+    requestHeaders: HeaderPair[];
+    responseHeaders: HeaderPair[];
+    requestBody: BodyView;
+    responseBody: BodyView;
+    tags: {
+        key: string;
+        value: string;
+    }[];
+    /** Frames and events, in order. Empty for plain HTTP. */
+    messages: MessageRow[];
+}
+/**
+ * A row of `v_messages`: one WebSocket frame or SSE event.
+ *
+ * `text` is the payload decoded, or null when it was binary or absent —
+ * `bytes` still says how big it was.
+ */
+interface MessageRow {
+    id: number;
+    request_id: number;
+    seq: number;
+    ts: number;
+    direction: MessageDirection;
+    /** `text` | `binary` | `close` for WebSockets; the event name for SSE. */
+    name: string;
+    /** WebSocket close code. */
+    code: number | null;
+    /** SSE event id. */
+    event_id: string | null;
+    bytes: number;
+    body_id: number | null;
+    truncated: number | null;
+    text: string | null;
+}
+interface StatusMixRow {
+    status_class: string;
+    count: number;
+}
+interface RunAnalytics {
+    total: number;
+    /** How many rows the latency figures cover — HTTP requests, not connections. */
+    latencySamples: number;
+    statusMix: StatusMixRow[];
+    p50: number | null;
+    p95: number | null;
+    p99: number | null;
+    slowest: {
+        id: number;
+        method: string;
+        host: string;
+        path: string;
+        duration_ms: number;
+    }[];
+    byHost: {
+        host: string;
+        count: number;
+        p95: number | null;
+        errors: number;
+    }[];
+}
+
+/**
+ * Persists one run's captures.
+ *
+ * Two things make this fast enough to sit behind a script making thousands of
+ * requests:
+ *
+ *  1. Every write goes through a prepared statement, and a whole batch commits
+ *     in ONE transaction. Committing per request would fsync per request.
+ *  2. The dimension tables are cached in-process, so the second time a run sees
+ *     `api.example.com` there is no SQL at all — just a Map hit.
+ *
+ * All of it is synchronous, which is a feature: capture already runs off the
+ * caller's request path, and a sync write means no interleaving and no
+ * partially-written run if the script exits abruptly.
+ */
+declare class RunWriter {
+    readonly runId: number;
+    private readonly db;
+    private seq;
+    /** Check ordering is its own sequence: checks and requests interleave freely. */
+    private checkSeq;
+    private readonly methodIds;
+    private readonly hostIds;
+    private readonly contentTypeIds;
+    private readonly headerNameIds;
+    private readonly messageNameIds;
+    private readonly bodyIds;
+    private readonly connectionIds;
+    private readonly stmt;
+    private readonly writeBatch;
+    private readonly writeCheckBatch;
+    constructor(db: Db, run: RunStart);
+    /** Persist a batch of captures in a single transaction. */
+    write(records: CapturedRecord[]): void;
+    /**
+     * Persist a batch of assertions in a single transaction.
+     *
+     * Separate from {@link RunWriter.write} because checks are not traffic: they
+     * arrive from the script itself rather than from a capture, and they carry no
+     * bodies, headers or interning. `seq` is assigned here, in arrival order, so
+     * a run's checks read back in the order the script made them.
+     */
+    writeChecks(records: CheckRecord[]): void;
+    /** Record how the run ended. */
+    finish(end: RunEnd): void;
+    /**
+     * Write one exchange. For a connection this runs twice — once at open, once
+     * at close — and the second pass updates the row rather than adding one.
+     */
+    private insertRequest;
+    /** The closing pass over a connection: outcome and timings, onto the open row. */
+    private updateConnection;
+    private requestRow;
+    /**
+     * Write one frame or event against the connection that carried it.
+     *
+     * A message whose connection is unknown is dropped: records reach a sink in
+     * order, so the only way here is a sink that reordered them, and half a
+     * connection is worse than none.
+     */
+    private insertMessage;
+    private insertHeaders;
+    private intern;
+    private internContentType;
+    /**
+     * Store a payload once per distinct content. The SHA-256 is over the bytes as
+     * stored, so a run that polls the same unchanged endpoint 500 times keeps one
+     * copy of the response and 500 integer references to it.
+     */
+    private internBody;
+}
+
+/** Runs, newest first. */
+declare function listRuns(db: Db, limit?: number): RunRow[];
+declare function getRun(db: Db, id: number): RunRow | null;
+/**
+ * Every script that has been run, one row each, most recently run first.
+ *
+ * Grouping is on `entry` — the absolute path of the executed file — because
+ * that is the only stable identity a script has. `--label` is per run and the
+ * default label is a basename, which collides the moment two folders hold a
+ * `sync.ts`.
+ *
+ * `label`, `id` and `exit_status` are bare columns under a GROUP BY, which
+ * SQLite answers from the row that produced the query's single MAX() — so they
+ * describe the latest run, not an arbitrary one. That is a documented SQLite
+ * guarantee (one min/max aggregate, bare columns come from that row), not an
+ * accident of the query plan.
+ */
+declare function listScripts(db: Db): ScriptRow[];
+/** Runs of one script, newest first — the sessions behind a script row. */
+declare function listRunsForEntry(db: Db, entry: string, limit?: number): RunRow[];
+/** Requests for a run, in capture order. */
+declare function listRequests(db: Db, runId: number): RequestListRow[];
+declare function getRequestDetail(db: Db, id: number): RequestDetail | null;
+/**
+ * Every tag on a run's requests, once each.
+ *
+ * `execute --tag` attaches the same pairs to every capture in the run, so read
+ * back per request they are the same two or three facts repeated a hundred
+ * times — they describe the run, not the call. The DISTINCT is what makes this
+ * honest for the one case that is not uniform: a library caller can configure
+ * two recorders differently inside one run, and then the union is the answer.
+ */
+declare function listRunTags(db: Db, runId: number): {
+    key: string;
+    value: string;
+}[];
+/** Every assertion a run made, in the order the script made them. */
+declare function listChecks(db: Db, runId: number): CheckRow[];
+/** Every frame or event on one connection, in the order it happened. */
+declare function listMessages(db: Db, requestId: number): MessageRow[];
+/**
+ * Per-run aggregates.
+ *
+ * SQLite has no `quantile()`, so percentiles use the nearest-rank definition:
+ * order the durations, take the row at ceil(q * n). One ordered CTE serves all
+ * three, and with `idx_requests_run_seq` narrowing to the run first the sort is
+ * over that run's rows only.
+ *
+ * Latency figures cover HTTP requests only. A connection's `duration_ms` is how
+ * long it stayed open, so letting one WebSocket sit in the same distribution
+ * would make "p95" mean nothing. `latencySamples` says how many rows they are
+ * computed over; the status mix and totals still count everything.
+ */
+declare function getRunAnalytics(db: Db, runId: number): RunAnalytics;
+
+export { type BodyKind, type BodyView, type CheckMode, type CheckRecord, type CheckRow, type CheckStatus, type ColumnInfo, type Db, ENTITIES, type EntityDef, type JsonValue, type MessageRow, PREVIEW_CHARS, type RelationInfo, type RequestDetail, type RequestListRow, type RequestRow, type Row, type RunAnalytics, type RunEnd, type RunRow, type RunStart, RunWriter, SCHEMA_VERSION, type ScriptRow, type SelectOptions, type StatusMixRow, UnknownFieldError, describeRelation, entityFields, findEntity, getRequestDetail, getRun, getRunAnalytics, listChecks, listMessages, listRelations, listRequests, listRunTags, listRuns, listRunsForEntry, listScripts, openDb, relationExists, resolveDbPath, selectEntity, untypedColumns };