@getstrata/core 2.2.10 → 2.2.11

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @getstrata/core changelog
 
+## 2.2.11
+
+Add independently interruptible read-only SQLite and MySQL observations; extend bounded failed-job and outbox metrics to file-backed SQLite and URL-backed MySQL with schema/index guards, real-engine regressions and three-process consistency tests. Preserve Postgres RLS and business transaction behavior.
+
 ## 2.2.10
 
 - Add bounded OpenTelemetry SDK health observations and selected native transaction-acquisition histograms through explicit metrics options.

package/dist/core/database/baseRepository.d.ts

@@ -17,6 +17,11 @@ interface DatabaseConnection {
     }): Promise<DatabaseConnection & {
         release(): void | Promise<void>;
     }>;
+    /** Optional independent, interruptible read-only observation; no business transaction or pool slot. */
+    observeReadOnly?<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<T>;
     /** SQLite closes synchronously; pooled drivers return a promise. */
     close?(): void | Promise<void>;
 }

package/dist/core/database/isolatedReadOnlyObservation.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseConnection } from "./baseRepository";
+interface ReadOnlyObservationOptions {
+    signal: AbortSignal;
+    timeoutMs: number;
+}
+declare function observeIsolatedReadOnly<T>(profile: {
+    driver: "sqlite";
+    filename: string;
+} | {
+    driver: "mysql";
+    url: string;
+    module: string;
+}, operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
+export type { ReadOnlyObservationOptions };
+export { observeIsolatedReadOnly };

package/dist/core/database/mysqlConnection.d.ts

@@ -1,4 +1,6 @@
+import type { DatabaseConnection } from "./baseRepository.ts";
 import { type ActiveDatabaseHandle } from "./connectionContext.ts";
+import { type ReadOnlyObservationOptions } from "./isolatedReadOnlyObservation.ts";
 type MysqlExecutable = {
     execute: (sql: string, params?: unknown[]) => Promise<[unknown, unknown]>;
     query?: (sql: string) => Promise<[unknown, unknown]>;
@@ -19,6 +21,7 @@ type MysqlPoolConnection = MysqlExecutable & {
 type MysqlConnection = ActiveDatabaseHandle & {
     begin<T>(callback: (transaction: ActiveDatabaseHandle) => Promise<T>): Promise<T>;
     close(): Promise<void>;
+    observeReadOnly<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
 };
 declare function resetMysqlLoaderForTests(importer?: () => Promise<unknown>): void;
 declare function createMysqlConnectionFromPool(pool: MysqlExecutable): MysqlConnection;

package/dist/core/database/readOnlyCollector.d.ts

@@ -0,0 +1,7 @@
+interface ReadOnlyCollector<T> {
+    collect(): Promise<T>;
+    close(): Promise<void>;
+}
+/** Internal shared observation lifecycle. No bypass, payload or tenant enumeration. */
+declare function createReadOnlyCollector<T>(name: string, timeoutMs: number, collect: (remaining: () => number) => Promise<T>): ReadOnlyCollector<T>;
+export { createReadOnlyCollector };

package/dist/core/database/sqliteConnection.d.ts

@@ -1,6 +1,9 @@
+import type { DatabaseConnection } from "./baseRepository.ts";
 import { type ActiveDatabaseHandle } from "./connectionContext.ts";
+import { type ReadOnlyObservationOptions } from "./isolatedReadOnlyObservation.ts";
 type SqliteConnection = ActiveDatabaseHandle & {
     begin<T>(callback: (transaction: ActiveDatabaseHandle) => Promise<T>): Promise<T>;
+    observeReadOnly<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
     close(): void;
 };
 declare function createSqliteConnection(filename: string): SqliteConnection;

package/dist/core/events/outbox/metrics.d.ts

@@ -19,7 +19,7 @@ interface OutboxMetricsCollector {
 }
 declare const snapshotQuery: string;
 /** Explicit platform observation, using the same transaction-local RLS bypass as coordination.
- * Initially Postgres-only: other engines fail rather than receiving a false empty snapshot.
+ * Postgres uses scoped bypass; official SQLite/MySQL adapters use isolated read-only snapshots.
  */
 declare function createOutboxMetricsCollector(options?: OutboxMetricsOptions): OutboxMetricsCollector;
 declare function renderOutboxMetrics(snapshot: OutboxMetricsSnapshot): string;

package/dist/entries/database/sqliteConnection.js

@@ -45,6 +45,126 @@ var init_connectionContext = __esm(() => {
 // ../../src/core/database/sqliteConnection.ts
 init_connectionContext();
 import { Database } from "bun:sqlite";
+import { resolve } from "path";
+
+// ../../src/core/database/isolatedReadOnlyObservation.ts
+var childSource = `
+import { Database } from 'bun:sqlite';
+let db;
+let mysql;
+process.on('message', async message => {
+  try {
+    if (message.init) {
+      if (message.driver === 'mysql') {
+        const module = await import(message.module);
+        mysql = await module.createConnection({ uri: message.url, timezone: 'Z', connectTimeout: message.timeoutMs });
+        await mysql.query("SET time_zone = '+00:00'");
+        await mysql.query('SET SESSION max_execution_time = ' + message.timeoutMs);
+        await mysql.query('SET SESSION lock_wait_timeout = 1');
+        await mysql.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ');
+        await mysql.query('START TRANSACTION READ ONLY');
+      } else {
+        db = new Database(message.filename, { readonly: true, create: false });
+        db.exec('PRAGMA busy_timeout = 0');
+        db.exec('PRAGMA query_only = ON');
+        db.exec('BEGIN');
+      }
+      process.send({ ok: true, rows: [] });
+    } else {
+      const rows = mysql ? (message.params.length ? await mysql.execute(message.query, message.params) : await mysql.query(message.query))[0] : db.query(message.query).all(...message.params);
+      process.send({ ok: true, rows });
+    }
+  } catch {
+    // No SQL, file paths, payloads or driver exception text crosses the error channel.
+    process.send({ ok: false });
+  }
+});
+`;
+async function observeIsolatedReadOnly(profile, operation, options) {
+  options.signal.throwIfAborted();
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 5000)
+    throw new TypeError("SQL observation timeout must be between 1 and 5000 milliseconds.");
+  const executable = Bun.which("bun", { PATH: process.env.PATH ?? "" });
+  if (!executable)
+    throw new Error("SQL observations require the Bun CLI on PATH.");
+  let pending;
+  let stopped = false;
+  const { promise: aborted, reject: rejectAbort } = Promise.withResolvers();
+  const fail = (error) => {
+    pending?.reject(error);
+    pending = undefined;
+  };
+  const child = Bun.spawn({
+    cmd: [
+      executable,
+      "--no-env-file",
+      `--config=${process.platform === "win32" ? "NUL" : "/dev/null"}`,
+      "-e",
+      childSource
+    ],
+    env: {},
+    stdout: "ignore",
+    stderr: "ignore",
+    serialization: "advanced",
+    ipc(message) {
+      const response = message;
+      const request = pending;
+      pending = undefined;
+      if (response?.ok === true && Array.isArray(response.rows))
+        request?.resolve(response.rows);
+      else
+        request?.reject(new Error("Read-only SQL observation failed."));
+    }
+  });
+  const exited = child.exited.then(() => {
+    fail(new Error("SQL observation process exited."));
+  });
+  const abort = (reason) => {
+    stopped = true;
+    child.kill("SIGKILL");
+    fail(reason);
+    rejectAbort(reason);
+  };
+  const onAbort = () => abort(options.signal.reason);
+  options.signal.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => abort(new Error("SQL observation timed out.")), options.timeoutMs);
+  const request = (message) => {
+    if (stopped)
+      return Promise.reject(new Error("SQL observation is closed."));
+    if (pending)
+      return Promise.reject(new Error("Concurrent SQL observation queries are not supported."));
+    return new Promise((resolve, reject) => {
+      pending = { resolve, reject };
+      child.send(message);
+    });
+  };
+  try {
+    if (options.signal.aborted)
+      onAbort();
+    const work = (async () => {
+      await request({ init: true, ...profile, timeoutMs: options.timeoutMs });
+      options.signal.throwIfAborted();
+      return operation({
+        async unsafe(query, params = []) {
+          return await request({
+            query,
+            params: params.map((value) => profile.driver === "sqlite" && value instanceof Date ? value.toISOString() : value)
+          });
+        }
+      });
+    })();
+    return await Promise.race([work, aborted]);
+  } finally {
+    stopped = true;
+    clearTimeout(timer);
+    options.signal.removeEventListener("abort", onAbort);
+    child.kill("SIGKILL");
+    fail(new Error("SQL observation is closed."));
+    await exited;
+  }
+}
+
+// ../../src/core/database/sqliteConnection.ts
 function isRowReturning(sql) {
   const upper = sql.replace(/\s+/g, " ").trim().toUpperCase();
   if (upper.includes(" RETURNING ")) {
@@ -56,7 +176,8 @@ function createSqliteConnection(filename) {
   if (!filename.trim()) {
     throw new Error("SQLite path is not configured. Pass a filename or :memory:.");
   }
-  const db = new Database(filename, { create: true });
+  const absoluteFilename = filename === ":memory:" ? filename : resolve(filename);
+  const db = new Database(absoluteFilename, { create: true });
   db.exec("PRAGMA foreign_keys = ON");
   db.exec("PRAGMA busy_timeout = 5000");
   if (filename !== ":memory:") {
@@ -119,6 +240,21 @@ function createSqliteConnection(filename) {
         }
       });
     },
+    async observeReadOnly(operation, options) {
+      if (closed)
+        throw new Error("SQLite connection is closed.");
+      if (absoluteFilename === ":memory:")
+        throw new Error("SQL observations require file-backed SQLite.");
+      pending++;
+      try {
+        return await observeIsolatedReadOnly({ driver: "sqlite", filename: absoluteFilename }, async (transaction) => {
+          transactions.add(transaction);
+          return await runWithDatabaseConnection(transaction, () => operation(transaction));
+        }, options);
+      } finally {
+        pending--;
+      }
+    },
     close() {
       if (pending > 0)
         throw new Error("Drain SQLite operations before closing the connection.");

package/dist/entries/queue/queueMetrics.js

@@ -26,22 +26,6 @@ function createAsyncContextStore(key) {
 }
 var init_asyncContextStore = () => {};
 
-// ../../src/core/database/connectionContext.ts
-function runWithDatabaseConnection(connection, callback) {
-  return activeConnection.run(connection, callback);
-}
-function getActiveDatabaseConnection(fallback) {
-  return activeConnection.getStore() ?? fallback;
-}
-function hasActiveDatabaseConnection() {
-  return activeConnection.getStore() !== undefined;
-}
-var activeConnection;
-var init_connectionContext = __esm(() => {
-  init_asyncContextStore();
-  activeConnection = createAsyncContextStore("@getstrata/databaseConnectionContext");
-});
-
 // ../../src/core/database/schema/driver.ts
 function normalizeConnectionName(connection) {
   const normalized = connection.trim().toLowerCase();
@@ -243,6 +227,22 @@ var init_dialect = __esm(() => {
   dialectContext = createAsyncContextStore("@getstrata/sqlDialect");
 });
 
+// ../../src/core/database/connectionContext.ts
+function runWithDatabaseConnection(connection, callback) {
+  return activeConnection.run(connection, callback);
+}
+function getActiveDatabaseConnection(fallback) {
+  return activeConnection.getStore() ?? fallback;
+}
+function hasActiveDatabaseConnection() {
+  return activeConnection.getStore() !== undefined;
+}
+var activeConnection;
+var init_connectionContext = __esm(() => {
+  init_asyncContextStore();
+  activeConnection = createAsyncContextStore("@getstrata/databaseConnectionContext");
+});
+
 // ../../src/core/database/boundConnection.ts
 function boundConnectionState() {
   const globalRecord = globalThis;
@@ -2192,12 +2192,15 @@ function createAppQueue(driver, redisUrl, failedJobs = createFailedJobService(),
   });
 }
 
-// ../../src/core/database/postgresReadOnlyCollector.ts
+// ../../src/core/queue/failedJobMetrics.ts
+init_dialect();
+
+// ../../src/core/database/readOnlyCollector.ts
 init_connectionContext();
 init_dialect();
 init_repositoryConnection();
 init_transaction();
-function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
+function createReadOnlyCollector(name, timeoutMs, collect) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000)
     throw new TypeError(`${name} timeout must be between 1 and 5000 milliseconds.`);
   let active;
@@ -2208,8 +2211,10 @@ function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
         throw new Error(`${name} collector is closed.`);
       if (hasActiveTransaction() || hasActiveDatabaseConnection())
         throw new Error(`${name} require an independent transaction.`);
-      if (currentSqlDialect().driver !== "pgsql")
-        throw new Error(`${name} currently require Postgres.`);
+      const driver = currentSqlDialect().driver;
+      const pool = resolveRepositoryConnection();
+      if (driver !== "pgsql" && driver !== "sqlite" && driver !== "mysql")
+        throw new Error(`${name} require Postgres or an interruptible SQLite/MySQL adapter.`);
       if (active)
         throw new Error(`${name} collection is still settling.`);
       const deadline = performance.now() + timeoutMs;
@@ -2222,14 +2227,25 @@ function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
           throw new Error(`${name} collection timed out.`);
         return value;
       };
-      const work = runInTransaction(async () => {
-        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [`${remaining()}ms`]);
+      const work = driver === "pgsql" ? runInTransaction(async () => {
+        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [
+          `${remaining()}ms`
+        ]);
         await repositoryConnection.unsafe("SET TRANSACTION READ ONLY");
         remaining();
         const result = await collect(remaining);
         remaining();
         return result;
-      }, { acquisitionSignal: acquisition.signal });
+      }, { acquisitionSignal: acquisition.signal }) : (async () => {
+        if (!pool.observeReadOnly)
+          throw new Error(`${name} require Postgres or an interruptible SQLite/MySQL adapter.`);
+        return pool.observeReadOnly(async (connection) => await runWithDatabaseConnection(connection, async () => {
+          remaining();
+          const result = await collect(remaining);
+          remaining();
+          return result;
+        }), { signal: acquisition.signal, timeoutMs: remaining() });
+      })();
       active = work;
       work.finally(() => {
         if (active === work)
@@ -2267,15 +2283,33 @@ var schemaQuery = `SELECT c.relkind = 'r' AND c.relpersistence = 'p' AND NOT c.r
     AND i.indnkeyatts = 1 AND a.attname = 'id' AND NOT a.attisdropped
     AND a.atttypid IN ('int2'::regtype, 'int4'::regtype, 'int8'::regtype)
 ) AS supported FROM pg_class c WHERE c.oid = 'failed_job'::regclass`;
+var sqliteSchemaQuery = `SELECT 1 AS supported FROM main.sqlite_schema
+WHERE name='failed_job' AND type='table' AND rootpage > 0
+AND (SELECT COUNT(*) FROM pragma_table_xinfo('failed_job', 'main') WHERE pk > 0) = 1
+AND EXISTS (SELECT 1 FROM pragma_table_xinfo('failed_job', 'main')
+  WHERE name='id' AND pk=1 AND upper(type)='INTEGER' AND hidden=0) LIMIT 1`;
+var mysqlSchemaQuery = `SELECT 1 AS supported FROM information_schema.TABLES t
+WHERE t.TABLE_SCHEMA=DATABASE() AND t.TABLE_NAME='failed_job' AND t.TABLE_TYPE='BASE TABLE' AND t.ENGINE='InnoDB'
+AND (SELECT COUNT(*) FROM information_schema.STATISTICS i WHERE i.TABLE_SCHEMA=t.TABLE_SCHEMA
+  AND i.TABLE_NAME=t.TABLE_NAME AND i.INDEX_NAME='PRIMARY')=1
+AND EXISTS(SELECT 1 FROM information_schema.STATISTICS i JOIN information_schema.COLUMNS c
+  ON c.TABLE_SCHEMA=i.TABLE_SCHEMA AND c.TABLE_NAME=i.TABLE_NAME AND c.COLUMN_NAME=i.COLUMN_NAME
+  WHERE i.TABLE_SCHEMA=t.TABLE_SCHEMA AND i.TABLE_NAME=t.TABLE_NAME AND i.INDEX_NAME='PRIMARY'
+    AND i.SEQ_IN_INDEX=1 AND i.COLUMN_NAME='id' AND c.DATA_TYPE IN ('tinyint','smallint','mediumint','int','bigint')) LIMIT 1`;
 function createFailedJobMetricsCollector(options = {}) {
   const sampleLimit = options.sampleLimit ?? 500;
   if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 1 || sampleLimit > 1000)
     throw new TypeError("Failed-job metrics sample limit must be between 1 and 1000.");
   const repository = new failedJobRepository_default;
-  return createPostgresReadOnlyCollector("Failed-job metrics", options.timeoutMs ?? 1000, async (remaining) => {
-    await repositoryConnection.unsafe('LOCK TABLE "failed_job" IN ACCESS SHARE MODE');
-    const schema = await repositoryConnection.unsafe(schemaQuery);
-    if (schema.length !== 1 || schema[0]?.supported !== true)
+  return createReadOnlyCollector("Failed-job metrics", options.timeoutMs ?? 1000, async (remaining) => {
+    const driver = currentSqlDialect().driver;
+    const postgres = driver === "pgsql";
+    if (postgres)
+      await repositoryConnection.unsafe('LOCK TABLE "failed_job" IN ACCESS SHARE MODE');
+    if (driver === "mysql")
+      await repositoryConnection.unsafe("SELECT id FROM failed_job LIMIT 0");
+    const schema = await repositoryConnection.unsafe(postgres ? schemaQuery : driver === "mysql" ? mysqlSchemaQuery : sqliteSchemaQuery);
+    if (schema.length !== 1 || schema[0]?.supported !== (postgres ? true : 1))
       throw new Error("Failed-job metrics require the standard global table with an ID primary key and no RLS.");
     remaining();
     const rows = await repository.query().orderBy({ column: "id", direction: "ASC" }).project(["id"], sampleLimit + 1);

package/dist/index.js

@@ -8309,6 +8309,125 @@ function registerModelRepository(model, repository) {
 }
 // ../../src/core/database/mysqlConnection.ts
 init_connectionContext();
+
+// ../../src/core/database/isolatedReadOnlyObservation.ts
+var childSource = `
+import { Database } from 'bun:sqlite';
+let db;
+let mysql;
+process.on('message', async message => {
+  try {
+    if (message.init) {
+      if (message.driver === 'mysql') {
+        const module = await import(message.module);
+        mysql = await module.createConnection({ uri: message.url, timezone: 'Z', connectTimeout: message.timeoutMs });
+        await mysql.query("SET time_zone = '+00:00'");
+        await mysql.query('SET SESSION max_execution_time = ' + message.timeoutMs);
+        await mysql.query('SET SESSION lock_wait_timeout = 1');
+        await mysql.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ');
+        await mysql.query('START TRANSACTION READ ONLY');
+      } else {
+        db = new Database(message.filename, { readonly: true, create: false });
+        db.exec('PRAGMA busy_timeout = 0');
+        db.exec('PRAGMA query_only = ON');
+        db.exec('BEGIN');
+      }
+      process.send({ ok: true, rows: [] });
+    } else {
+      const rows = mysql ? (message.params.length ? await mysql.execute(message.query, message.params) : await mysql.query(message.query))[0] : db.query(message.query).all(...message.params);
+      process.send({ ok: true, rows });
+    }
+  } catch {
+    // No SQL, file paths, payloads or driver exception text crosses the error channel.
+    process.send({ ok: false });
+  }
+});
+`;
+async function observeIsolatedReadOnly(profile, operation, options) {
+  options.signal.throwIfAborted();
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 5000)
+    throw new TypeError("SQL observation timeout must be between 1 and 5000 milliseconds.");
+  const executable = Bun.which("bun", { PATH: process.env.PATH ?? "" });
+  if (!executable)
+    throw new Error("SQL observations require the Bun CLI on PATH.");
+  let pending;
+  let stopped = false;
+  const { promise: aborted, reject: rejectAbort } = Promise.withResolvers();
+  const fail = (error) => {
+    pending?.reject(error);
+    pending = undefined;
+  };
+  const child = Bun.spawn({
+    cmd: [
+      executable,
+      "--no-env-file",
+      `--config=${process.platform === "win32" ? "NUL" : "/dev/null"}`,
+      "-e",
+      childSource
+    ],
+    env: {},
+    stdout: "ignore",
+    stderr: "ignore",
+    serialization: "advanced",
+    ipc(message) {
+      const response = message;
+      const request = pending;
+      pending = undefined;
+      if (response?.ok === true && Array.isArray(response.rows))
+        request?.resolve(response.rows);
+      else
+        request?.reject(new Error("Read-only SQL observation failed."));
+    }
+  });
+  const exited = child.exited.then(() => {
+    fail(new Error("SQL observation process exited."));
+  });
+  const abort = (reason) => {
+    stopped = true;
+    child.kill("SIGKILL");
+    fail(reason);
+    rejectAbort(reason);
+  };
+  const onAbort = () => abort(options.signal.reason);
+  options.signal.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => abort(new Error("SQL observation timed out.")), options.timeoutMs);
+  const request = (message) => {
+    if (stopped)
+      return Promise.reject(new Error("SQL observation is closed."));
+    if (pending)
+      return Promise.reject(new Error("Concurrent SQL observation queries are not supported."));
+    return new Promise((resolve, reject) => {
+      pending = { resolve, reject };
+      child.send(message);
+    });
+  };
+  try {
+    if (options.signal.aborted)
+      onAbort();
+    const work = (async () => {
+      await request({ init: true, ...profile, timeoutMs: options.timeoutMs });
+      options.signal.throwIfAborted();
+      return operation({
+        async unsafe(query, params = []) {
+          return await request({
+            query,
+            params: params.map((value) => profile.driver === "sqlite" && value instanceof Date ? value.toISOString() : value)
+          });
+        }
+      });
+    })();
+    return await Promise.race([work, aborted]);
+  } finally {
+    stopped = true;
+    clearTimeout(timer);
+    options.signal.removeEventListener("abort", onAbort);
+    child.kill("SIGKILL");
+    fail(new Error("SQL observation is closed."));
+    await exited;
+  }
+}
+
+// ../../src/core/database/mysqlConnection.ts
 var MYSQL_SESSION_UTC = "SET time_zone = '+00:00'";
 var mysqlModule;
 var mysqlPending;
@@ -8368,8 +8487,10 @@ async function executeMysql(target, query, params) {
   const [result] = params.length === 0 && target.query ? await target.query(query) : await target.execute(query, [...params]);
   return rowsFromResult(result);
 }
-function createMysqlAdapter(getPool, close) {
+function createMysqlAdapter(getPool, close, observer) {
   const transactions = new WeakSet;
+  const observations = new Set;
+  let observationsClosed = false;
   const connection = {
     async unsafe(query, params = []) {
       const active = getActiveDatabaseConnection(connection);
@@ -8421,7 +8542,27 @@ function createMysqlAdapter(getPool, close) {
           reserved.release();
       }
     },
-    close
+    async observeReadOnly(operation, options) {
+      if (observationsClosed)
+        throw new Error("MySQL observations are closed.");
+      if (!observer)
+        throw new Error("MySQL observations require the URL-backed official adapter.");
+      const work = observer(async (transaction) => {
+        transactions.add(transaction);
+        return await runWithDatabaseConnection(transaction, () => operation(transaction));
+      }, options);
+      observations.add(work);
+      try {
+        return await work;
+      } finally {
+        observations.delete(work);
+      }
+    },
+    async close() {
+      observationsClosed = true;
+      await Promise.allSettled([...observations]);
+      await close();
+    }
   };
   return connection;
 }
@@ -8470,6 +8611,10 @@ function createMysqlConnection(url) {
       return;
     });
     await pool?.end();
+  }, async (operation, options) => {
+    await loadMysql();
+    const module = import.meta.resolve("mysql2/promise");
+    return await observeIsolatedReadOnly({ driver: "mysql", url, module }, operation, options);
   });
 }
 // ../../src/core/database/namedConnections.ts
@@ -9196,6 +9341,7 @@ async function runSeedersFromDirectory(directory, db, options) {
 // ../../src/core/database/sqliteConnection.ts
 init_connectionContext();
 import { Database } from "bun:sqlite";
+import { resolve } from "path";
 function isRowReturning(sql) {
   const upper = sql.replace(/\s+/g, " ").trim().toUpperCase();
   if (upper.includes(" RETURNING ")) {
@@ -9207,7 +9353,8 @@ function createSqliteConnection(filename) {
   if (!filename.trim()) {
     throw new Error("SQLite path is not configured. Pass a filename or :memory:.");
   }
-  const db = new Database(filename, { create: true });
+  const absoluteFilename = filename === ":memory:" ? filename : resolve(filename);
+  const db = new Database(absoluteFilename, { create: true });
   db.exec("PRAGMA foreign_keys = ON");
   db.exec("PRAGMA busy_timeout = 5000");
   if (filename !== ":memory:") {
@@ -9270,6 +9417,21 @@ function createSqliteConnection(filename) {
         }
       });
     },
+    async observeReadOnly(operation, options) {
+      if (closed)
+        throw new Error("SQLite connection is closed.");
+      if (absoluteFilename === ":memory:")
+        throw new Error("SQL observations require file-backed SQLite.");
+      pending++;
+      try {
+        return await observeIsolatedReadOnly({ driver: "sqlite", filename: absoluteFilename }, async (transaction) => {
+          transactions.add(transaction);
+          return await runWithDatabaseConnection(transaction, () => operation(transaction));
+        }, options);
+      } finally {
+        pending--;
+      }
+    },
     close() {
       if (pending > 0)
         throw new Error("Drain SQLite operations before closing the connection.");
@@ -9296,12 +9458,15 @@ init_databaseTenantContext();
 init_tenantContext();
 init_tenantDatabaseScope();
 
-// ../../src/core/database/postgresReadOnlyCollector.ts
+// ../../src/core/events/outbox/metrics.ts
+init_dialect();
+
+// ../../src/core/database/readOnlyCollector.ts
 init_connectionContext();
 init_dialect();
 init_repositoryConnection();
 init_transaction();
-function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
+function createReadOnlyCollector(name, timeoutMs, collect) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000)
     throw new TypeError(`${name} timeout must be between 1 and 5000 milliseconds.`);
   let active;
@@ -9312,8 +9477,10 @@ function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
         throw new Error(`${name} collector is closed.`);
       if (hasActiveTransaction() || hasActiveDatabaseConnection())
         throw new Error(`${name} require an independent transaction.`);
-      if (currentSqlDialect().driver !== "pgsql")
-        throw new Error(`${name} currently require Postgres.`);
+      const driver = currentSqlDialect().driver;
+      const pool = resolveRepositoryConnection();
+      if (driver !== "pgsql" && driver !== "sqlite" && driver !== "mysql")
+        throw new Error(`${name} require Postgres or an interruptible SQLite/MySQL adapter.`);
       if (active)
         throw new Error(`${name} collection is still settling.`);
       const deadline = performance.now() + timeoutMs;
@@ -9326,14 +9493,25 @@ function createPostgresReadOnlyCollector(name, timeoutMs, collect) {
           throw new Error(`${name} collection timed out.`);
         return value;
       };
-      const work = runInTransaction(async () => {
-        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [`${remaining()}ms`]);
+      const work = driver === "pgsql" ? runInTransaction(async () => {
+        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [
+          `${remaining()}ms`
+        ]);
         await repositoryConnection.unsafe("SET TRANSACTION READ ONLY");
         remaining();
         const result = await collect(remaining);
         remaining();
         return result;
-      }, { acquisitionSignal: acquisition.signal });
+      }, { acquisitionSignal: acquisition.signal }) : (async () => {
+        if (!pool.observeReadOnly)
+          throw new Error(`${name} require Postgres or an interruptible SQLite/MySQL adapter.`);
+        return pool.observeReadOnly(async (connection) => await runWithDatabaseConnection(connection, async () => {
+          remaining();
+          const result = await collect(remaining);
+          remaining();
+          return result;
+        }), { signal: acquisition.signal, timeoutMs: remaining() });
+      })();
       active = work;
       work.finally(() => {
         if (active === work)
@@ -9411,32 +9589,78 @@ ${specifications.map((spec, index) => `SELECT '${spec.state}' AS state, COUNT(*)
   FROM sample_${index}`).join(`
 UNION ALL
 `)}`;
+async function readIndexedSnapshot(sampleLimit, remaining) {
+  const mysql = currentSqlDialect().driver === "mysql";
+  if (mysql)
+    await repositoryConnection.unsafe("SELECT event_id FROM strata_outbox_delivery LIMIT 0");
+  const schema = await repositoryConnection.unsafe(mysql ? "SELECT 1 AS valid FROM information_schema.TABLES WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='strata_outbox_delivery' AND TABLE_TYPE='BASE TABLE' AND ENGINE='InnoDB' LIMIT 1" : "SELECT 1 AS valid FROM main.sqlite_schema WHERE name='strata_outbox_delivery' AND type='table' AND rootpage>0 LIMIT 1");
+  if (schema.length !== 1 || schema[0]?.valid !== 1)
+    throw new Error("Outbox metrics require the standard delivery table.");
+  for (const [index, column] of [
+    ["strata_outbox_due", "available_at"],
+    ["strata_outbox_expired", "lease_until"]
+  ]) {
+    const rows = await repositoryConnection.unsafe(mysql ? "SELECT IF(SUB_PART IS NULL AND COLLATION='A' AND IS_VISIBLE='YES', COLUMN_NAME, NULL) AS name, SEQ_IN_INDEX-1 AS seqno FROM information_schema.STATISTICS WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='strata_outbox_delivery' AND INDEX_NAME=? ORDER BY SEQ_IN_INDEX LIMIT 5" : "SELECT name, seqno FROM pragma_index_info(?, 'main') ORDER BY seqno LIMIT 5", [index]);
+    const expected = ["status", column, "event_id", "listener_name"];
+    if (rows.length !== expected.length || rows.some((row, i) => row.seqno !== i || row.name !== expected[i]))
+      throw new Error("Outbox metrics require the standard delivery indexes.");
+    remaining();
+  }
+  const [clock] = await repositoryConnection.unsafe(mysql ? "SELECT CAST(UNIX_TIMESTAMP(CURRENT_TIMESTAMP(3))*1000 AS UNSIGNED) AS now_ms" : "SELECT CAST(unixepoch('subsec') * 1000 AS INTEGER) AS now_ms");
+  if (!Number.isSafeInteger(clock?.now_ms) || !clock || clock.now_ms < 0)
+    throw new Error("Invalid outbox clock.");
+  const rows = [];
+  for (const spec of specifications) {
+    remaining();
+    const index = spec.column === "lease_until" ? "strata_outbox_expired" : "strata_outbox_due";
+    const predicate = spec.predicate ? ` AND ${spec.column} ${spec.predicate}${spec.predicate === "IS NULL" ? "" : " ?"}` : "";
+    const values = await repositoryConnection.unsafe(`SELECT ${spec.column} AS timestamp_ms
+      FROM strata_outbox_delivery ${mysql ? `FORCE INDEX (${index})` : `INDEXED BY ${index}`} WHERE status = ?${predicate}
+      ORDER BY ${spec.column}, event_id, listener_name LIMIT ?`, [
+      spec.status,
+      ...spec.predicate && spec.predicate !== "IS NULL" ? [clock.now_ms] : [],
+      sampleLimit + 1
+    ]);
+    const timestamp = values[0]?.timestamp_ms;
+    if (spec.age && values.length && (!Number.isSafeInteger(timestamp) || timestamp == null || timestamp < 0))
+      throw new Error("Invalid outbox timestamp.");
+    rows.push({
+      state: spec.state,
+      count: values.length,
+      lateness_ms: spec.age ? Math.max(0, clock.now_ms - (timestamp ?? clock.now_ms)) : null
+    });
+  }
+  return rows;
+}
 function createOutboxMetricsCollector(options = {}) {
   const timeoutMs = options.timeoutMs ?? 1000;
   const sampleLimit = options.sampleLimit ?? 500;
   if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 1 || sampleLimit > 1000)
     throw new TypeError("Outbox metrics sample limit must be between 1 and 1000.");
-  return createPostgresReadOnlyCollector("Outbox metrics", timeoutMs, (remaining) => runWithMigrationBypass(async () => {
-    remaining();
-    const rows = await repositoryConnection.unsafe(snapshotQuery, [sampleLimit + 1]);
-    remaining();
-    if (rows.length !== specifications.length)
-      throw new Error("Invalid outbox metrics response.");
-    const states = specifications.map((spec) => {
-      const row = rows.find((value) => value.state === spec.state);
-      const count = Number(row?.count);
-      const lateness = row?.lateness_ms == null ? null : Number(row.lateness_ms);
-      if (!Number.isSafeInteger(count) || count < 0 || count > sampleLimit + 1 || spec.age && (lateness === null || !Number.isFinite(lateness) || lateness < 0))
-        throw new Error("Invalid outbox metrics values.");
-      return {
-        state: spec.state,
-        count: Math.min(count, sampleLimit),
-        capped: count > sampleLimit,
-        actionableLatenessSeconds: lateness === null ? null : lateness / 1000
-      };
-    });
-    return { sampleLimit, states };
-  }));
+  return createReadOnlyCollector("Outbox metrics", timeoutMs, async (remaining) => {
+    const read = async () => {
+      remaining();
+      const rows = currentSqlDialect().driver !== "pgsql" ? await readIndexedSnapshot(sampleLimit, remaining) : await repositoryConnection.unsafe(snapshotQuery, [sampleLimit + 1]);
+      remaining();
+      if (rows.length !== specifications.length)
+        throw new Error("Invalid outbox metrics response.");
+      const states = specifications.map((spec) => {
+        const row = rows.find((value) => value.state === spec.state);
+        const count = Number(row?.count);
+        const lateness = row?.lateness_ms == null ? null : Number(row.lateness_ms);
+        if (!Number.isSafeInteger(count) || count < 0 || count > sampleLimit + 1 || spec.age && (lateness === null || !Number.isFinite(lateness) || lateness < 0))
+          throw new Error("Invalid outbox metrics values.");
+        return {
+          state: spec.state,
+          count: Math.min(count, sampleLimit),
+          capped: count > sampleLimit,
+          actionableLatenessSeconds: lateness === null ? null : lateness / 1000
+        };
+      });
+      return { sampleLimit, states };
+    };
+    return currentSqlDialect().driver === "pgsql" ? runWithMigrationBypass(read) : read();
+  });
 }
 function renderOutboxMetrics(snapshot) {
   if (!Number.isSafeInteger(snapshot.sampleLimit) || snapshot.sampleLimit < 1 || snapshot.sampleLimit > 1000 || snapshot.states.length !== specifications.length)
@@ -10034,7 +10258,7 @@ import { dirname } from "path";
 var {S3Client } = globalThis.Bun;
 
 // ../../src/core/security/safePath.ts
-import { isAbsolute, resolve, sep } from "path";
+import { isAbsolute, resolve as resolve2, sep } from "path";
 function assertPathUnderRoot(rootDirectory, userPath) {
   const trimmed = userPath.trim();
   if (trimmed.length === 0) {
@@ -10043,8 +10267,8 @@ function assertPathUnderRoot(rootDirectory, userPath) {
   if (trimmed.includes("\x00")) {
     throw new Error("Path must not contain a null byte.");
   }
-  const root = resolve(rootDirectory);
-  const candidate = isAbsolute(trimmed) ? resolve(trimmed) : resolve(root, trimmed.replace(/^\/+/u, ""));
+  const root = resolve2(rootDirectory);
+  const candidate = isAbsolute(trimmed) ? resolve2(trimmed) : resolve2(root, trimmed.replace(/^\/+/u, ""));
   if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
     return candidate;
   }
@@ -13002,6 +13226,7 @@ class Notification {
   }
 }
 // ../../src/core/queue/failedJobMetrics.ts
+init_dialect();
 init_repositoryConnection();
 
 // ../../src/core/queue/failedJobTable.ts
@@ -13027,15 +13252,33 @@ var schemaQuery = `SELECT c.relkind = 'r' AND c.relpersistence = 'p' AND NOT c.r
     AND i.indnkeyatts = 1 AND a.attname = 'id' AND NOT a.attisdropped
     AND a.atttypid IN ('int2'::regtype, 'int4'::regtype, 'int8'::regtype)
 ) AS supported FROM pg_class c WHERE c.oid = 'failed_job'::regclass`;
+var sqliteSchemaQuery = `SELECT 1 AS supported FROM main.sqlite_schema
+WHERE name='failed_job' AND type='table' AND rootpage > 0
+AND (SELECT COUNT(*) FROM pragma_table_xinfo('failed_job', 'main') WHERE pk > 0) = 1
+AND EXISTS (SELECT 1 FROM pragma_table_xinfo('failed_job', 'main')
+  WHERE name='id' AND pk=1 AND upper(type)='INTEGER' AND hidden=0) LIMIT 1`;
+var mysqlSchemaQuery = `SELECT 1 AS supported FROM information_schema.TABLES t
+WHERE t.TABLE_SCHEMA=DATABASE() AND t.TABLE_NAME='failed_job' AND t.TABLE_TYPE='BASE TABLE' AND t.ENGINE='InnoDB'
+AND (SELECT COUNT(*) FROM information_schema.STATISTICS i WHERE i.TABLE_SCHEMA=t.TABLE_SCHEMA
+  AND i.TABLE_NAME=t.TABLE_NAME AND i.INDEX_NAME='PRIMARY')=1
+AND EXISTS(SELECT 1 FROM information_schema.STATISTICS i JOIN information_schema.COLUMNS c
+  ON c.TABLE_SCHEMA=i.TABLE_SCHEMA AND c.TABLE_NAME=i.TABLE_NAME AND c.COLUMN_NAME=i.COLUMN_NAME
+  WHERE i.TABLE_SCHEMA=t.TABLE_SCHEMA AND i.TABLE_NAME=t.TABLE_NAME AND i.INDEX_NAME='PRIMARY'
+    AND i.SEQ_IN_INDEX=1 AND i.COLUMN_NAME='id' AND c.DATA_TYPE IN ('tinyint','smallint','mediumint','int','bigint')) LIMIT 1`;
 function createFailedJobMetricsCollector(options = {}) {
   const sampleLimit = options.sampleLimit ?? 500;
   if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 1 || sampleLimit > 1000)
     throw new TypeError("Failed-job metrics sample limit must be between 1 and 1000.");
   const repository = new failedJobRepository_default;
-  return createPostgresReadOnlyCollector("Failed-job metrics", options.timeoutMs ?? 1000, async (remaining) => {
-    await repositoryConnection.unsafe('LOCK TABLE "failed_job" IN ACCESS SHARE MODE');
-    const schema = await repositoryConnection.unsafe(schemaQuery);
-    if (schema.length !== 1 || schema[0]?.supported !== true)
+  return createReadOnlyCollector("Failed-job metrics", options.timeoutMs ?? 1000, async (remaining) => {
+    const driver = currentSqlDialect().driver;
+    const postgres = driver === "pgsql";
+    if (postgres)
+      await repositoryConnection.unsafe('LOCK TABLE "failed_job" IN ACCESS SHARE MODE');
+    if (driver === "mysql")
+      await repositoryConnection.unsafe("SELECT id FROM failed_job LIMIT 0");
+    const schema = await repositoryConnection.unsafe(postgres ? schemaQuery : driver === "mysql" ? mysqlSchemaQuery : sqliteSchemaQuery);
+    if (schema.length !== 1 || schema[0]?.supported !== (postgres ? true : 1))
       throw new Error("Failed-job metrics require the standard global table with an ID primary key and no RLS.");
     remaining();
     const rows = await repository.query().orderBy({ column: "id", direction: "ASC" }).project(["id"], sampleLimit + 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.10",
+  "version": "2.2.11",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",

package/dist/core/database/postgresReadOnlyCollector.d.ts

@@ -1,7 +0,0 @@
-interface ReadOnlyCollector<T> {
-    collect(): Promise<T>;
-    close(): Promise<void>;
-}
-/** Internal shared observation lifecycle. No bypass, payload or tenant enumeration. */
-declare function createPostgresReadOnlyCollector<T>(name: string, timeoutMs: number, collect: (remaining: () => number) => Promise<T>): ReadOnlyCollector<T>;
-export { createPostgresReadOnlyCollector };