@adonis-agora/telescope 0.23.0 → 0.24.0

package/dist/src/stores/lucid.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { currentTraceId } from '../context_accessor.js';
 import { isBatchOrigin } from '../entry.js';
 import { resolveOrigin } from '../origin_scope.js';
+import { runAsTelescopeWork } from '../self_scope.js';
 /**
  * The table {@link LucidTelescopeStore} reads and writes. Override via
  * {@link LucidStoreOptions.tableName} when `telescope_entries` collides with an
@@ -13,31 +14,65 @@ export const DEFAULT_TABLE_NAME = 'telescope_entries';
  * indexes `list` / `prune` / `topFamilies` lean on, as one statement per array
  * element so each can be issued through Lucid's `rawQuery`.
  *
- * Portable across sqlite / Postgres / MySQL (quoted identifiers, no dialect-only
- * column types). A real deployment should still prefer the bundled migration stub
+ * Identifiers are double-quoted (sqlite / Postgres) unless `dialect` is a Lucid
+ * MySQL dialect name (`mysql` / `mysql2`), which gets backticks and plain
+ * `CREATE INDEX`; the column types are portable. A real deployment should still prefer the bundled migration stub
  * so the schema is versioned, but this lets a store stand itself up in tests and
  * scripts without a migration runner.
  */
-export function createTableStatements(tableName = DEFAULT_TABLE_NAME) {
+export function createTableStatements(tableName = DEFAULT_TABLE_NAME, dialect) {
+    const mysql = isMysql(dialect);
+    const q = (identifier) => (mysql ? `\`${identifier}\`` : `"${identifier}"`);
+    // MySQL has no `CREATE INDEX IF NOT EXISTS`; an index that already exists fails with
+    // ER_DUP_KEYNAME, which the store's reconcile treats as done.
+    const index = (suffix, columns) => `CREATE INDEX ${mysql ? '' : 'IF NOT EXISTS '}${q(`${tableName}_${suffix}`)} ON ${q(tableName)} (${columns.map(q).join(', ')})`;
     return [
-        `CREATE TABLE IF NOT EXISTS "${tableName}" (
-      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
-      "type" VARCHAR(255) NOT NULL,
-      "family_hash" VARCHAR(255) NULL,
-      "content" TEXT NOT NULL,
-      "tags" TEXT NOT NULL,
-      "sequence" INTEGER NOT NULL,
-      "duration_ms" INTEGER NULL,
-      "origin" VARCHAR(255) NOT NULL,
-      "trace_id" VARCHAR(255) NULL,
-      "created_at" BIGINT NOT NULL
+        `CREATE TABLE IF NOT EXISTS ${q(tableName)} (
+      ${q('id')} VARCHAR(255) PRIMARY KEY NOT NULL,
+      ${q('type')} VARCHAR(255) NOT NULL,
+      ${q('family_hash')} VARCHAR(255) NULL,
+      ${q('content')} TEXT NOT NULL,
+      ${q('tags')} TEXT NOT NULL,
+      ${q('sequence')} INTEGER NOT NULL,
+      ${q('duration_ms')} INTEGER NULL,
+      ${q('origin')} VARCHAR(255) NOT NULL,
+      ${q('trace_id')} VARCHAR(255) NULL,
+      ${q('created_at')} BIGINT NOT NULL
     )`,
-        `CREATE INDEX IF NOT EXISTS "${tableName}_created_at_idx" ON "${tableName}" ("created_at")`,
-        `CREATE INDEX IF NOT EXISTS "${tableName}_type_idx" ON "${tableName}" ("type")`,
-        `CREATE INDEX IF NOT EXISTS "${tableName}_trace_id_idx" ON "${tableName}" ("trace_id")`,
-        `CREATE INDEX IF NOT EXISTS "${tableName}_family_hash_idx" ON "${tableName}" ("family_hash")`,
+        index('created_at_idx', ['created_at']),
+        index('trace_id_idx', ['trace_id']),
+        // The dashboard's per-type reads are `WHERE type = ? AND created_at > ? ORDER BY
+        // created_at DESC, sequence DESC LIMIT n`: this one index answers them in order.
+        index('type_created_at_sequence_idx', ['type', 'created_at', 'sequence']),
+        index('family_hash_created_at_idx', ['family_hash', 'created_at']),
     ];
 }
+/** MySQL (and MariaDB) quote identifiers with backticks; a double-quoted name is a string there. */
+function isMysql(dialect) {
+    return dialect === 'mysql' || dialect === 'mysql2';
+}
+/** The Lucid dialect name of `db`, from the client itself or the facade's default connection. */
+function dialectOf(db) {
+    return db.dialect?.name ?? db.connection?.().dialect?.name;
+}
+/** Whether `error` is MySQL's "index already exists". */
+function isDuplicateIndex(error) {
+    const { code, errno } = (error ?? {});
+    return code === 'ER_DUP_KEYNAME' || errno === 1061;
+}
+/** Run the DDL for `tableName` on `db`, in its dialect. */
+async function runTableStatements(db, tableName) {
+    const dialect = dialectOf(db);
+    for (const stmt of createTableStatements(tableName, dialect)) {
+        try {
+            await db.rawQuery(stmt);
+        }
+        catch (error) {
+            if (!(isMysql(dialect) && isDuplicateIndex(error)))
+                throw error;
+        }
+    }
+}
 // ── Schema fingerprint gate ──────────────────────────────────────────────────
 //
 // With `autoCreateTable`, `doInit` used to re-issue every `createTableStatements`
@@ -68,11 +103,12 @@ export const SCHEMA_META_TABLE_NAME = 'telescope_schema_meta';
  * and introspection-free, portable across sqlite / Postgres / MySQL (quoted
  * identifiers, portable types) — mirroring {@link createTableStatements}' style.
  */
-function createSchemaMetaTableStatement() {
-    return `CREATE TABLE IF NOT EXISTS "${SCHEMA_META_TABLE_NAME}" (
-      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
-      "fingerprint" VARCHAR(64) NOT NULL,
-      "applied_at" BIGINT NOT NULL
+function createSchemaMetaTableStatement(dialect) {
+    const q = (identifier) => (isMysql(dialect) ? `\`${identifier}\`` : `"${identifier}"`);
+    return `CREATE TABLE IF NOT EXISTS ${q(SCHEMA_META_TABLE_NAME)} (
+      ${q('id')} VARCHAR(255) PRIMARY KEY NOT NULL,
+      ${q('fingerprint')} VARCHAR(64) NOT NULL,
+      ${q('applied_at')} BIGINT NOT NULL
     )`;
 }
 /**
@@ -89,6 +125,31 @@ function computeSchemaFingerprint(tableName) {
     });
     return createHash('sha256').update(payload).digest('hex');
 }
+/** Rows per multi-row INSERT. Ten columns each keeps a statement at 900 bound values,
+ *  under the smallest limit of any dialect Lucid drives (999 on older SQLite builds). */
+const INSERT_BATCH_ROWS = 90;
+/** Serialized bytes per INSERT, so a batch of large entries stays far below MySQL's
+ *  default `max_allowed_packet`. A single entry over it is still written, alone. */
+const INSERT_BATCH_BYTES = 4 * 1024 * 1024;
+/** Entries waiting to be written. Past this, new entries are dropped and counted
+ *  rather than queued: a database that stopped keeping up must not grow the heap. */
+const MAX_PENDING_WRITES = 10_000;
+/** Rows deleted per statement while pruning. */
+const PRUNE_BATCH_ROWS = 5_000;
+/** Rows read per page while counting tags. */
+const TAG_SCAN_PAGE_ROWS = 5_000;
+/** Every column but `content`, for reads that set {@link EntryQuery.omitContent}. */
+const COLUMNS_WITHOUT_CONTENT = [
+    'id',
+    'type',
+    'family_hash',
+    'tags',
+    'sequence',
+    'duration_ms',
+    'origin',
+    'trace_id',
+    'created_at',
+];
 /**
  * A persistent, SQL-backed {@link TelescopeStore} on AdonisJS Lucid. Uses Lucid's
  * **async** query builder directly, so it works on every dialect Lucid supports
@@ -99,6 +160,15 @@ function computeSchemaFingerprint(tableName) {
  * `sequence` is seeded from `MAX(sequence)` on first use so it keeps climbing
  * across process restarts.
  *
+ * Writes are buffered: every entry recorded during one tick of the event loop goes
+ * out in one multi-row INSERT (split to stay under each dialect's bind limit), one
+ * statement at a time, so the store never holds more than one pooled connection
+ * for writing and a burst of watcher events costs a handful of round trips instead
+ * of one each. `record()` still resolves once its entry is persisted.
+ *
+ * Every query the store runs is marked as telescope's own work (see
+ * `self_scope.ts`), so the query watcher never records them.
+ *
  * Usually you don't construct this directly: `config/telescope.ts` selects it via
  * `storage.lucid({ ... })` and the provider builds it for you, lazily importing
  * `@adonisjs/lucid` only when the `lucid` driver is the active one.
@@ -111,14 +181,11 @@ export class LucidTelescopeStore {
     /** Lazily-resolved init (table creation + sequence seed), run at most once. */
     ready = null;
     sequence = 0;
-    /**
-     * Single-flight write chain: every `record()` insert is queued behind the previous one so the
-     * store holds at most ONE pooled connection at a time. A burst of watcher events can therefore
-     * never exhaust the host app's connection pool (which telescope may share). Reads
-     * (`get`/`list`/`prune`) are user-initiated and low-frequency, so they are intentionally NOT
-     * serialized.
-     */
-    writeTail = Promise.resolve();
+    pending = [];
+    /** The running drain, while one is scheduled or writing. */
+    draining = null;
+    dropped = 0;
+    warnedDrop = false;
     constructor(db, options = {}) {
         this.db = db;
         this.tableName = options.tableName ?? DEFAULT_TABLE_NAME;
@@ -158,64 +225,95 @@ export class LucidTelescopeStore {
             trace_id: entry.traceId,
             created_at: entry.createdAt.getTime(),
         };
-        // Queue the insert behind any in-flight write (see `writeTail`): at most one telescope
-        // connection is ever checked out of the pool. The entry is built eagerly above, so
-        // `sequence`/`created_at` reflect event order even though the insert itself is serialized.
-        const write = this.writeTail.then(() => this.db.table(this.tableName).insert(row));
-        // Advance the chain regardless of this write's outcome — a single failed insert must not
-        // wedge every subsequent write.
-        this.writeTail = write.then(() => undefined, () => undefined);
-        await write;
+        if (this.pending.length >= MAX_PENDING_WRITES) {
+            this.dropped += 1;
+            if (!this.warnedDrop) {
+                this.warnedDrop = true;
+                console.warn(`@adonis-agora/telescope: ${MAX_PENDING_WRITES} entries are waiting to be written to ` +
+                    `"${this.tableName}"; new entries are dropped until the database catches up.`);
+            }
+            return entry;
+        }
+        await new Promise((resolve, reject) => {
+            this.pending.push({
+                row,
+                bytes: row.content.length + row.tags.length,
+                resolve,
+                reject,
+            });
+            this.scheduleDrain();
+        });
         return entry;
     }
-    async get(id) {
-        await this.init();
-        const row = await this.db.from(this.tableName).where('id', id).first();
-        return row ? hydrate(row) : null;
+    /** Entries dropped because the write buffer was full. */
+    get droppedCount() {
+        return this.dropped;
     }
-    async list(query = {}) {
-        await this.init();
-        let builder = this.db.from(this.tableName);
-        if (query.type !== undefined)
-            builder = builder.where('type', query.type);
-        if (query.familyHash !== undefined)
-            builder = builder.where('family_hash', query.familyHash);
-        if (query.traceId !== undefined)
-            builder = builder.where('trace_id', query.traceId);
-        if (query.traceIds !== undefined) {
-            // An empty list means "no traces", not "no filter" — whereIn([]) already yields
-            // zero rows, but being explicit keeps a caller's empty page from becoming a scan.
-            if (query.traceIds.length === 0)
-                return [];
-            builder = builder.whereIn('trace_id', query.traceIds);
-        }
-        if (query.before !== undefined)
-            builder = builder.where('created_at', '<', query.before.getTime());
-        if (query.after !== undefined)
-            builder = builder.where('created_at', '>', query.after.getTime());
-        if (query.tag !== undefined) {
-            // A tag is one element of the JSON array text, e.g. `["lib:billing",...]`.
-            // Match the quoted token so `lib:bill` never matches `lib:billing`.
-            builder = builder.whereRaw(`"tags" LIKE ? ESCAPE '\\'`, [
-                `%${likeEscape(JSON.stringify(query.tag))}%`,
-            ]);
-        }
-        if (query.search !== undefined) {
-            const needle = `%${likeEscape(query.search.toLowerCase())}%`;
-            builder = builder.whereRaw(`(LOWER("content") LIKE ? ESCAPE '\\' OR LOWER("tags") LIKE ? ESCAPE '\\')`, [needle, needle]);
-        }
-        // Newest-first: created_at desc, sequence desc as a deterministic tiebreaker.
-        builder = builder.orderBy('created_at', 'desc').orderBy('sequence', 'desc');
-        // `{ page, size }` in, `LIMIT/OFFSET` out: the 1-based page becomes `(page - 1) * size`.
-        if (query.size !== undefined && query.size > 0) {
-            const size = Math.floor(query.size);
-            const page = Math.max(1, Math.floor(query.page ?? 1));
-            builder = builder.limit(size);
-            if (page > 1)
-                builder = builder.offset((page - 1) * size);
-        }
-        const rows = await builder.select('*');
-        return rows.map((r) => hydrate(r));
+    /** Resolves once every entry recorded so far has been written (or has failed). */
+    async flush() {
+        while (this.draining !== null)
+            await this.draining;
+    }
+    get(id) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const row = await this.db.from(this.tableName).where('id', id).first();
+            return row ? hydrate(row) : null;
+        });
+    }
+    list(query = {}) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            let builder = this.db.from(this.tableName);
+            if (query.type !== undefined)
+                builder = builder.where('type', query.type);
+            if (query.familyHash !== undefined)
+                builder = builder.where('family_hash', query.familyHash);
+            if (query.traceId !== undefined)
+                builder = builder.where('trace_id', query.traceId);
+            if (query.traceIds !== undefined) {
+                // An empty list means "no traces", not "no filter" — whereIn([]) already yields
+                // zero rows, but being explicit keeps a caller's empty page from becoming a scan.
+                if (query.traceIds.length === 0)
+                    return [];
+                builder = builder.whereIn('trace_id', query.traceIds);
+            }
+            if (query.before !== undefined)
+                builder = builder.where('created_at', '<', query.before.getTime());
+            if (query.after !== undefined)
+                builder = builder.where('created_at', '>', query.after.getTime());
+            if (query.tag !== undefined) {
+                // A tag is one element of the JSON array text, e.g. `["lib:billing",...]`.
+                // Match the quoted token so `lib:bill` never matches `lib:billing`.
+                builder = builder.whereRaw(`?? LIKE ? ESCAPE '!'`, [
+                    'tags',
+                    `%${likeEscape(JSON.stringify(query.tag))}%`,
+                ]);
+            }
+            if (query.search !== undefined) {
+                const needle = `%${likeEscape(query.search.toLowerCase())}%`;
+                builder = builder.whereRaw(`(LOWER(??) LIKE ? ESCAPE '!' OR LOWER(??) LIKE ? ESCAPE '!')`, [
+                    'content',
+                    needle,
+                    'tags',
+                    needle,
+                ]);
+            }
+            // Newest-first: created_at desc, sequence desc as a deterministic tiebreaker.
+            builder = builder.orderBy('created_at', 'desc').orderBy('sequence', 'desc');
+            // `{ page, size }` in, `LIMIT/OFFSET` out: the 1-based page becomes `(page - 1) * size`.
+            if (query.size !== undefined && query.size > 0) {
+                const size = Math.floor(query.size);
+                const page = Math.max(1, Math.floor(query.page ?? 1));
+                builder = builder.limit(size);
+                if (page > 1)
+                    builder = builder.offset((page - 1) * size);
+            }
+            const rows = await (query.omitContent === true
+                ? builder.select(...COLUMNS_WITHOUT_CONTENT)
+                : builder.select('*'));
+            return rows.map((r) => hydrate(r));
+        });
     }
     /**
      * The page of distinct trace ids, most-recently-seen first — the SQL fast path
@@ -226,110 +324,302 @@ export class LucidTelescopeStore {
      * the window. Entries with a NULL `trace_id` are excluded: they belong to no trace
      * and would collapse into one meaningless bucket.
      */
-    async listTraceIds(query) {
-        await this.init();
-        let builder = this.db.from(this.tableName);
-        if (query.before !== undefined)
-            builder = builder.where('created_at', '<', query.before.getTime());
-        if (query.after !== undefined)
-            builder = builder.where('created_at', '>', query.after.getTime());
-        // `select()` resolves the query, so it goes LAST — every chainable clause
-        // (including the MAX aggregate) has to be applied before it.
-        const rows = await builder
-            .whereNotNull('trace_id')
-            .groupBy('trace_id')
-            .max('created_at as last_at')
-            .orderBy('last_at', 'desc')
-            .limit(query.size)
-            .offset((Math.max(1, Math.floor(query.page ?? 1)) - 1) * Math.max(0, Math.floor(query.size)))
-            .select('trace_id');
-        return rows.map((row) => ({
-            traceId: row.trace_id,
-            lastAt: new Date(toInt(row.last_at)),
-        }));
+    listTraceIds(query) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            let builder = this.db.from(this.tableName);
+            if (query.before !== undefined)
+                builder = builder.where('created_at', '<', query.before.getTime());
+            if (query.after !== undefined)
+                builder = builder.where('created_at', '>', query.after.getTime());
+            // `select()` resolves the query, so it goes LAST — every chainable clause
+            // (including the MAX aggregate) has to be applied before it.
+            const rows = await builder
+                .whereNotNull('trace_id')
+                .groupBy('trace_id')
+                .max('created_at as last_at')
+                .orderBy('last_at', 'desc')
+                .limit(query.size)
+                .offset((Math.max(1, Math.floor(query.page ?? 1)) - 1) * Math.max(0, Math.floor(query.size)))
+                .select('trace_id');
+            return rows.map((row) => ({
+                traceId: row.trace_id,
+                lastAt: new Date(toInt(row.last_at)),
+            }));
+        });
     }
     /**
-     * Per-bucket, per-type counts for the throughput chart.
+     * Per-bucket, per-type counts for the throughput chart, grouped in SQL so one row
+     * per `(bucket, type)` leaves the database instead of one per entry.
      *
-     * The win here is the PROJECTION, not the grouping: the chart needs `created_at`
-     * and `type` and nothing else, but the only way to get them was `list()`, which
-     * does `select('*')` — shipping every row's `content` JSON blob out of the database
-     * and running it through `hydrate()`, to then discard all of it except a timestamp
-     * and a string. Two scalar columns instead of a blob is orders of magnitude less
-     * bytes on the wire and no per-row JSON parse.
-     *
-     * The bucketing itself stays in JS, deliberately. Doing it in SQL needs a raw
-     * select expression (`(created_at - ?) / ?`), and Lucid exposes `groupByRaw` but no
-     * `selectRaw` — the alternative is `rawQuery`, whose result shape differs per driver
-     * (`{ rows }` on Postgres, an array on SQLite). Trading a portability bug for the
-     * second-order win is a bad deal; the row count is what would justify it, and after
-     * the redis-watcher filter that count drops by roughly an order of magnitude. If
-     * this is still hot with a clean table, THAT is when it earns the raw query.
+     * The bucket is `(created_at - start) - ((created_at - start) % bucketMs)`: integer
+     * arithmetic every dialect evaluates the same way, where `/` would be integer
+     * division on some and decimal on MySQL. Each group reports its newest
+     * `created_at`, and the bucket index is computed from that in JS. A builder
+     * without `groupByRaw` gets the per-row projection, bucketed here.
      */
-    async countByBucket(query) {
-        await this.init();
-        const startMs = query.after.getTime();
-        const bucketMs = Math.max(1, Math.floor(query.bucketMs));
-        let builder = this.db
-            .from(this.tableName)
-            .where('created_at', '>', startMs)
-            .where('created_at', '<=', query.before.getTime());
-        if (query.type !== undefined)
-            builder = builder.where('type', query.type);
-        const rows = (await builder.select('created_at', 'type'));
-        const tally = new Map();
-        for (const row of rows) {
-            const index = Math.floor((toInt(row.created_at) - startMs) / bucketMs);
-            const key = `${index}\u0000${row.type}`;
-            const seen = tally.get(key);
-            if (seen === undefined) {
-                tally.set(key, { index, type: row.type, count: 1 });
+    countByBucket(query) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const startMs = query.after.getTime();
+            const bucketMs = Math.max(1, Math.floor(query.bucketMs));
+            let builder = this.db
+                .from(this.tableName)
+                .where('created_at', '>', startMs)
+                .where('created_at', '<=', query.before.getTime());
+            if (query.type !== undefined)
+                builder = builder.where('type', query.type);
+            const tally = new Map();
+            const add = (createdAt, type, count) => {
+                const index = Math.floor((toInt(createdAt) - startMs) / bucketMs);
+                const key = `${index}\u0000${type}`;
+                const seen = tally.get(key);
+                if (seen === undefined)
+                    tally.set(key, { index, type, count });
+                else
+                    seen.count += count;
+            };
+            if (typeof builder.groupByRaw === 'function') {
+                // `type` is a GROUP BY column; MAX() is how this builder surface selects it
+                // next to the aggregates. Aliased apart from the column so MySQL, which
+                // resolves GROUP BY names to select aliases first, still groups by the column.
+                const rows = (await builder
+                    .groupByRaw('(?? - ?) - ((?? - ?) % ?)', [
+                    'created_at',
+                    startMs,
+                    'created_at',
+                    startMs,
+                    bucketMs,
+                ])
+                    .groupBy('type')
+                    .max('type as entry_type')
+                    .max('created_at as last_at')
+                    .count('*', 'total'));
+                for (const row of rows)
+                    add(row.last_at, row.entry_type, toInt(row.total));
             }
             else {
-                seen.count += 1;
+                const rows = (await builder.select('created_at', 'type'));
+                for (const row of rows)
+                    add(row.created_at, row.type, 1);
             }
-        }
-        return [...tally.values()];
+            return [...tally.values()];
+        });
     }
-    async count() {
-        await this.init();
-        const rows = await this.db.from(this.tableName).count('*', 'total');
-        return toInt(rows[0]?.total);
+    /**
+     * The busiest families, counted by `GROUP BY family_hash` — see
+     * {@link TelescopeStore.countFamilies}.
+     */
+    countFamilies(query) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const limit = Math.max(0, Math.floor(query.limit));
+            if (limit === 0)
+                return [];
+            let builder = this.db
+                .from(this.tableName)
+                .whereNotNull('family_hash')
+                .where('family_hash', '<>', '');
+            if (query.type !== undefined)
+                builder = builder.where('type', query.type);
+            // `family_hash` is the GROUP BY column; MAX() selects it next to the aggregates
+            // (see countByBucket for the alias).
+            const rows = (await builder
+                .groupBy('family_hash')
+                .max('family_hash as family_key')
+                .max('created_at as last_at')
+                .max('sequence as last_sequence')
+                .orderBy('total', 'desc')
+                .orderBy('last_at', 'desc')
+                .orderBy('last_sequence', 'desc')
+                .limit(limit)
+                .count('*', 'total'));
+            return rows.map((row) => ({ key: row.family_key, count: toInt(row.total) }));
+        });
     }
-    async prune(olderThan, keepLast) {
-        await this.init();
-        const cutoff = olderThan.getTime();
-        if (keepLast === undefined) {
-            return this.db.from(this.tableName).where('created_at', '<', cutoff).delete();
-        }
-        // Keep the newest `keepLast` of the doomed (older-than-cutoff) entries: find
-        // their ids ordered newest-first, skip the first `keepLast`, delete the rest.
-        const doomed = await this.db
-            .from(this.tableName)
-            .where('created_at', '<', cutoff)
-            .orderBy('created_at', 'desc')
-            .orderBy('sequence', 'desc')
-            .select('id');
-        const toDelete = doomed.slice(keepLast).map((r) => String(r.id));
-        if (toDelete.length === 0)
-            return 0;
-        return this.db
-            .from(this.tableName)
-            .whereRaw(`"id" IN (${toDelete.map(() => '?').join(', ')})`, toDelete)
-            .delete();
+    /**
+     * The most common tags — see {@link TelescopeStore.countTags}. Tags are JSON text,
+     * so they are counted here, reading only the `tags` column a page at a time in
+     * primary-key order.
+     */
+    countTags(query) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const limit = Math.max(0, Math.floor(query.limit));
+            if (limit === 0)
+                return [];
+            const tally = new Map();
+            let afterId = null;
+            for (;;) {
+                let builder = this.db.from(this.tableName);
+                if (afterId !== null)
+                    builder = builder.where('id', '>', afterId);
+                const rows = (await builder
+                    .orderBy('id', 'asc')
+                    .limit(TAG_SCAN_PAGE_ROWS)
+                    .select('id', 'tags', 'created_at', 'sequence'));
+                for (const row of rows) {
+                    const position = { createdAt: toInt(row.created_at), sequence: toInt(row.sequence) };
+                    for (const tag of parseTags(row.tags)) {
+                        if (query.prefix !== undefined && !tag.startsWith(query.prefix))
+                            continue;
+                        const seen = tally.get(tag);
+                        if (seen === undefined) {
+                            tally.set(tag, { count: 1, newest: position });
+                        }
+                        else {
+                            seen.count += 1;
+                            if (isNewer(position, seen.newest))
+                                seen.newest = position;
+                        }
+                    }
+                }
+                if (rows.length < TAG_SCAN_PAGE_ROWS)
+                    break;
+                afterId = String(rows[rows.length - 1].id);
+            }
+            return [...tally.entries()]
+                .sort(([, a], [, b]) => b.count - a.count || (isNewer(a.newest, b.newest) ? -1 : 1))
+                .slice(0, limit)
+                .map(([key, { count }]) => ({ key, count }));
+        });
     }
-    async clear() {
-        await this.init();
-        await this.db.from(this.tableName).whereRaw('1 = 1').delete();
+    count() {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const rows = await this.db.from(this.tableName).count('*', 'total');
+            return toInt(rows[0]?.total);
+        });
+    }
+    /**
+     * Deletes oldest-first, {@link PRUNE_BATCH_ROWS} rows per statement, each batch
+     * addressed by its newest row's position rather than by id: a backlog of any size
+     * is pruned in bounded statements that never approach a bind limit.
+     */
+    prune(olderThan, keepLast) {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            const cutoff = olderThan.getTime();
+            // With `keepLast`, the doomed rows end at the first one past the newest
+            // `keepLast` of those older than the cutoff.
+            let newestDoomed = null;
+            if (keepLast !== undefined) {
+                newestDoomed = await this.position(this.db
+                    .from(this.tableName)
+                    .where('created_at', '<', cutoff)
+                    .orderBy('created_at', 'desc')
+                    .orderBy('sequence', 'desc')
+                    .offset(Math.max(0, Math.floor(keepLast))));
+                if (newestDoomed === null)
+                    return 0;
+            }
+            const doomed = () => {
+                const builder = this.db.from(this.tableName);
+                return newestDoomed === null
+                    ? builder.where('created_at', '<', cutoff)
+                    : atOrBefore(builder, newestDoomed);
+            };
+            let deleted = 0;
+            for (;;) {
+                const batchEdge = await this.position(doomed()
+                    .orderBy('created_at', 'asc')
+                    .orderBy('sequence', 'asc')
+                    .offset(PRUNE_BATCH_ROWS - 1));
+                if (batchEdge === null)
+                    return deleted + toInt(await doomed().delete());
+                deleted += toInt(await atOrBefore(doomed(), batchEdge).delete());
+            }
+        });
+    }
+    clear() {
+        return runAsTelescopeWork(async () => {
+            await this.init();
+            await this.flush();
+            await this.db.from(this.tableName).whereRaw('1 = 1').delete();
+        });
     }
     /** Cap enforcement helper for callers running a scheduled trim. */
     get capacity() {
         return this.maxEntries;
     }
+    /** The first row of an ordered query, as a position. */
+    async position(builder) {
+        const rows = await builder.limit(1).select('created_at', 'sequence');
+        const row = rows[0];
+        return row === undefined
+            ? null
+            : { createdAt: toInt(row.created_at), sequence: toInt(row.sequence) };
+    }
+    /** Start a drain on the next tick unless one is already running. */
+    scheduleDrain() {
+        if (this.draining !== null)
+            return;
+        this.draining = new Promise((resolve) => {
+            setImmediate(() => {
+                void runAsTelescopeWork(() => this.drain()).finally(() => {
+                    this.draining = null;
+                    resolve();
+                    // A write can arrive between the drain emptying the buffer and this callback.
+                    if (this.pending.length > 0)
+                        this.scheduleDrain();
+                });
+            });
+        });
+    }
+    /** Write the buffer out, batch by batch, until it is empty. */
+    async drain() {
+        while (this.pending.length > 0) {
+            await this.writeBatch(this.takeBatch());
+        }
+        this.warnedDrop = false;
+    }
+    /** The oldest pending writes that fit one INSERT. */
+    takeBatch() {
+        let count = 0;
+        let bytes = 0;
+        for (const write of this.pending) {
+            if (count === INSERT_BATCH_ROWS)
+                break;
+            if (count > 0 && bytes + write.bytes > INSERT_BATCH_BYTES)
+                break;
+            count += 1;
+            bytes += write.bytes;
+        }
+        return this.pending.splice(0, count);
+    }
+    /**
+     * One multi-row INSERT. When it fails, its rows are retried one at a time, so a
+     * row the database rejects fails only its own `record()`.
+     */
+    async writeBatch(batch) {
+        try {
+            await this.db
+                .table(this.tableName)
+                .insert(batch.map((write) => write.row));
+            for (const write of batch)
+                write.resolve();
+            return;
+        }
+        catch (error) {
+            if (batch.length === 1) {
+                batch[0].reject(error);
+                return;
+            }
+        }
+        for (const write of batch) {
+            try {
+                await this.db.table(this.tableName).insert(write.row);
+                write.resolve();
+            }
+            catch (error) {
+                write.reject(error);
+            }
+        }
+    }
     /** Run table creation (optional) + sequence seeding exactly once. */
     init() {
         if (!this.ready)
-            this.ready = this.doInit();
+            this.ready = runAsTelescopeWork(() => this.doInit());
         return this.ready;
     }
     async doInit() {
@@ -355,7 +645,7 @@ export class LucidTelescopeStore {
      */
     async reconcileSchema() {
         // (1) Idempotent, introspection-free marker table.
-        await this.db.rawQuery(createSchemaMetaTableStatement());
+        await this.db.rawQuery(createSchemaMetaTableStatement(dialectOf(this.db)));
         // (2) Read the stored fingerprint + (3) compute the expected one in memory.
         const stored = await this.readStoredFingerprint();
         const expected = computeSchemaFingerprint(this.tableName);
@@ -363,9 +653,7 @@ export class LucidTelescopeStore {
         if (stored === expected)
             return;
         // (5) Absent/mismatch ⇒ (re)create the table + indexes, then re-cache.
-        for (const stmt of createTableStatements(this.tableName)) {
-            await this.db.rawQuery(stmt);
-        }
+        await runTableStatements(this.db, this.tableName);
         await this.writeStoredFingerprint(expected);
     }
     /** Reads this table's stored fingerprint, or null when the marker row is absent. */
@@ -393,10 +681,7 @@ export class LucidTelescopeStore {
  * versioned and runs through `node ace migration:run`.
  */
 export async function createTelescopeTable(db, options = {}) {
-    const tableName = options.tableName ?? DEFAULT_TABLE_NAME;
-    for (const stmt of createTableStatements(tableName)) {
-        await db.rawQuery(stmt);
-    }
+    await runTableStatements(db, options.tableName ?? DEFAULT_TABLE_NAME);
 }
 /** Parse JSON text columns back into an {@link Entry}. */
 function hydrate(row) {
@@ -404,7 +689,7 @@ function hydrate(row) {
         id: row.id,
         type: row.type,
         familyHash: row.family_hash ?? null,
-        content: parseJson(row.content),
+        content: 'content' in row ? parseJson(row.content) : null,
         tags: parseTags(row.tags),
         sequence: toInt(row.sequence),
         durationMs: row.duration_ms === null || row.duration_ms === undefined ? null : toInt(row.duration_ms),
@@ -413,6 +698,21 @@ function hydrate(row) {
         createdAt: new Date(toInt(row.created_at)),
     };
 }
+/** Restrict `builder` to rows at or before `position` in oldest-first order. */
+function atOrBefore(builder, position) {
+    return builder.whereRaw('(?? < ? OR (?? = ? AND ?? <= ?))', [
+        'created_at',
+        position.createdAt,
+        'created_at',
+        position.createdAt,
+        'sequence',
+        position.sequence,
+    ]);
+}
+/** Whether `a` comes before `b` in newest-first order. */
+function isNewer(a, b) {
+    return a.createdAt > b.createdAt || (a.createdAt === b.createdAt && a.sequence > b.sequence);
+}
 function safeJson(value) {
     try {
         return JSON.stringify(value) ?? 'null';
@@ -442,8 +742,12 @@ function toInt(value) {
         return Number.parseInt(value, 10) || 0;
     return 0;
 }
-/** Escape LIKE wildcards so user input matches literally (escape char `\`). */
+/**
+ * Escape LIKE wildcards so user input matches literally. The escape character is `!`
+ * rather than a backslash, which MySQL would read as escaping the closing quote of
+ * `ESCAPE '\'`.
+ */
 function likeEscape(value) {
-    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    return value.replace(/[!%_]/g, (ch) => `!${ch}`);
 }
 //# sourceMappingURL=lucid.js.map