@getstrata/core 2.2.9 → 2.2.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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.
+- Add bounded Postgres failed-job counts using ORM ID projections, with schema guards, native acquisition deadlines and read-only collector draining.
+- Observe Streams retry promotion lateness using Redis time; cancellation cleanup sentinels omit unavailable age instead of reporting age since epoch.
+- Generate typed runtimeMetrics opt-in and provider-owned SQL collector draining, including startup cleanup; HTTP-only defaults and borrowed tracing ownership remain intact.
+- Keep additional SQL observation dialects, sustained operational qualification and encryption rotation explicit follow-up work.
+
 ## 2.2.9
 
 - Support native cancellable transaction acquisition

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

@@ -0,0 +1,23 @@
+declare const outcomes: readonly ["acquired", "failed", "aborted"];
+type AcquisitionOutcome = (typeof outcomes)[number];
+interface AcquisitionHistogram {
+    outcome: AcquisitionOutcome;
+    count: number;
+    sumSeconds: number;
+    buckets: readonly number[];
+}
+interface TransactionAcquisitionSnapshot {
+    inflight: number;
+    outcomes: readonly AcquisitionHistogram[];
+}
+declare const metricsBrand: unique symbol;
+interface TransactionAcquisitionMetrics {
+    readonly [metricsBrand]: true;
+    snapshot(): TransactionAcquisitionSnapshot;
+}
+declare function createTransactionAcquisitionMetrics(): TransactionAcquisitionMetrics;
+/** Internal native-reservation boundary, never a business/BEGIN/savepoint timer. */
+declare function observeTransactionAcquisition<T>(metrics: TransactionAcquisitionMetrics, acquire: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+declare function renderTransactionAcquisitionMetrics(snapshot: TransactionAcquisitionSnapshot): string;
+export type { TransactionAcquisitionMetrics, TransactionAcquisitionSnapshot };
+export { createTransactionAcquisitionMetrics, observeTransactionAcquisition, renderTransactionAcquisitionMetrics, };

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/database/transaction.d.ts

@@ -1,9 +1,14 @@
+import { type TransactionAcquisitionMetrics } from "./acquisitionMetrics.ts";
 import type { DatabaseConnection } from "./baseRepository.ts";
 import { hasActiveTransaction, requestTransactionRollback } from "./transactionControl.ts";
 interface TransactionOptions {
     /** Cancel admission/pool checkout only. Does not cancel SQL or an admitted business callback. */
     acquisitionSignal?: AbortSignal;
+    /** Observe native checkout only; requires a reserve-capable adapter. */
+    acquisitionMetrics?: TransactionAcquisitionMetrics;
 }
 declare function runInTransaction<TValue>(operation: (connection: DatabaseConnection) => Promise<TValue>, options?: TransactionOptions): Promise<TValue>;
+export type { TransactionAcquisitionMetrics, TransactionAcquisitionSnapshot, } from "./acquisitionMetrics.ts";
+export { createTransactionAcquisitionMetrics, renderTransactionAcquisitionMetrics, } from "./acquisitionMetrics.ts";
 export type { TransactionOptions };
 export { hasActiveTransaction, requestTransactionRollback, runInTransaction };

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/core/queue/failedJobMetrics.d.ts

@@ -0,0 +1,17 @@
+interface FailedJobMetricsSnapshot {
+    sampleLimit: number;
+    count: number;
+    capped: boolean;
+}
+interface FailedJobMetricsOptions {
+    timeoutMs?: number;
+    sampleLimit?: number;
+}
+interface FailedJobMetricsCollector {
+    collect(): Promise<FailedJobMetricsSnapshot>;
+    close(): Promise<void>;
+}
+declare function createFailedJobMetricsCollector(options?: FailedJobMetricsOptions): FailedJobMetricsCollector;
+declare function renderFailedJobMetrics(snapshot: FailedJobMetricsSnapshot): string;
+export type { FailedJobMetricsCollector, FailedJobMetricsOptions, FailedJobMetricsSnapshot };
+export { createFailedJobMetricsCollector, renderFailedJobMetrics };

package/dist/core/queue/queueMetrics.d.ts

@@ -26,6 +26,8 @@ interface QueuePrioritySnapshot {
     inflightCapped: boolean;
     retryDue: number;
     retryWaiting: number;
+    /** Oldest positive due-score lateness; unavailable for lists or cancellation sentinels. */
+    retryActionableLatenessSeconds?: number | null;
     quarantined: number;
     /** Residence age of the oldest current stream entry, not original job age across retries. */
     oldestStreamEntryAgeSeconds: number | null;
@@ -39,5 +41,7 @@ declare const INFLIGHT_SAMPLE_LIMIT = 500;
 declare function readRedisQueueSnapshot(redisUrl: string, options?: RedisQueueSnapshotOptions): Promise<RedisQueueSnapshot>;
 /** Fixed metric/label vocabulary; no job IDs, tenant IDs, payloads or credentials. */
 declare function renderRedisQueueMetrics(snapshot: RedisQueueSnapshot): string;
+export type { FailedJobMetricsCollector, FailedJobMetricsOptions, FailedJobMetricsSnapshot, } from "./failedJobMetrics";
+export { createFailedJobMetricsCollector, renderFailedJobMetrics } from "./failedJobMetrics";
 export type { QueuePrioritySnapshot, RedisQueueSnapshot, RedisQueueSnapshotOptions };
 export { INFLIGHT_SAMPLE_LIMIT, readRedisQueueSnapshot, renderRedisQueueMetrics };

package/dist/core/tracing/health.d.ts

@@ -0,0 +1,27 @@
+import { type MeterProvider } from "@opentelemetry/api";
+import type { SpanExporter } from "@opentelemetry/sdk-trace-base";
+interface TracingMetricsSnapshot {
+    enabled: boolean;
+    exporterConfigured: boolean;
+    active: boolean;
+    queueSize: number | null;
+    queueCapacity: number | null;
+    droppedSpans: number;
+    exportedBatches: number;
+    failedBatches: number;
+    exportedSpans: number;
+    failedSpans: number;
+    exportDeadlineExceededBatches: number;
+    flushFailures: number;
+    shutdownFailures: number;
+}
+/** A fixed projection of SDK self-observations, not a general metric registry. */
+declare function createTracingHealth(enabled: boolean, exporterConfigured: boolean, timeoutMillis: number): {
+    state: TracingMetricsSnapshot;
+    meterProvider: MeterProvider;
+    snapshot(): TracingMetricsSnapshot;
+    wrap(exporter: SpanExporter): SpanExporter;
+};
+declare function renderTracingMetrics(snapshot: TracingMetricsSnapshot): string;
+export type { TracingMetricsSnapshot };
+export { createTracingHealth, renderTracingMetrics };

package/dist/core/tracing/otel.d.ts

@@ -1,6 +1,7 @@
 import { type Context, type Tracer } from "@opentelemetry/api";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { type SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { type TracingMetricsSnapshot } from "./health";
 type TracingOptions = {
     exporter?: SpanExporter;
     endpoint?: string;
@@ -15,6 +16,7 @@ type TracingRuntime = {
     tracer: Tracer;
     propagator: W3CTraceContextPropagator;
     run<T>(parent: Context, callback: () => T): T;
+    metrics(): TracingMetricsSnapshot;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
 };

package/dist/core/tracing/tracingMiddleware.d.ts

@@ -1,6 +1,8 @@
 import type { Middleware } from "@getstrata/core/http/middleware";
 import { type TracingRuntime } from "./otel";
 declare function createTracingMiddleware(runtime?: TracingRuntime): Middleware;
+export type { TracingMetricsSnapshot } from "./health";
+export { renderTracingMetrics } from "./health";
 export type { TracingOptions, TracingRuntime } from "./otel";
 export { acquireTracingRuntime, createTracingRuntime, getTracingRuntime } from "./otel";
 export { createTracingMiddleware };

package/dist/entries/audit/exportAuditLogs.js

@@ -129,6 +129,9 @@ function unwrapTransactionRollback(error, depth = 0) {
   }
   return unwrapTransactionRollback(error.cause, depth + 1);
 }
+function hasActiveTransaction() {
+  return hasActiveDatabaseConnection() && (transactionScopes.getStore()?.rollback.length ?? 0) > 0;
+}
 function requestTransactionRollback() {
   const state = transactionScopes.getStore();
   const index = state ? state.rollback.length - 1 : -1;
@@ -344,6 +347,55 @@ var init_deferredModelEvents = __esm(() => {
   deferredModelEvents = createAsyncContextStore("@getstrata/deferredModelEvents");
 });
 
+// ../../src/core/database/acquisitionMetrics.ts
+async function observeTransactionAcquisition(metrics, acquire, signal) {
+  const state = states.get(metrics);
+  if (!state)
+    throw new TypeError("Transaction acquisition metrics must be created by the framework factory.");
+  const started = performance.now();
+  state.inflight++;
+  let outcome = "acquired";
+  try {
+    return await acquire();
+  } catch (error) {
+    outcome = signal?.aborted ? "aborted" : "failed";
+    throw error;
+  } finally {
+    state.inflight--;
+    const elapsed = Math.max(0, performance.now() - started) / 1000;
+    const histogram = state.outcomes[outcomes.indexOf(outcome)];
+    if (histogram) {
+      histogram.count++;
+      histogram.sumSeconds += elapsed;
+      for (let index = 0;index < ACQUISITION_BUCKETS_SECONDS.length; index++) {
+        const bound = ACQUISITION_BUCKETS_SECONDS[index];
+        if (bound !== undefined && elapsed <= bound)
+          histogram.buckets[index] = (histogram.buckets[index] ?? 0) + 1;
+      }
+    }
+  }
+}
+var ACQUISITION_BUCKETS_SECONDS, outcomes, metricsBrand, states;
+var init_acquisitionMetrics = __esm(() => {
+  ACQUISITION_BUCKETS_SECONDS = [
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10
+  ];
+  outcomes = ["acquired", "failed", "aborted"];
+  metricsBrand = Symbol("transaction acquisition metrics");
+  states = new WeakMap;
+});
+
 // ../../src/core/database/connection.ts
 function createDatabaseConnection(source) {
   return {
@@ -712,9 +764,13 @@ async function runInTransaction(operation, options = {}) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    if (signal && !pool.reserve)
-      throw new Error("Active database connection does not support cancellable transaction acquisition.");
-    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    let reserved;
+    if (signal || options.acquisitionMetrics) {
+      if (!pool.reserve)
+        throw new Error(signal ? "Active database connection does not support cancellable transaction acquisition." : "Active database connection does not support observable transaction acquisition.");
+      const reserve = pool.reserve.bind(pool);
+      reserved = options.acquisitionMetrics ? await observeTransactionAcquisition(options.acquisitionMetrics, () => reserve({ signal }), signal) : await reserve({ signal });
+    }
     const connection = reserved ?? pool;
     try {
       signal?.throwIfAborted();
@@ -732,10 +788,12 @@ var transactionFrame, outerFrames;
 var init_transaction = __esm(() => {
   init_deferredModelEvents();
   init_asyncContextStore();
+  init_acquisitionMetrics();
   init_connection();
   init_connectionContext();
   init_repositoryConnection();
   init_transactionControl();
+  init_acquisitionMetrics();
   transactionFrame = createAsyncContextStore("@getstrata/transactionFrame");
   outerFrames = new WeakMap;
 });

package/dist/entries/auth/scimAuthMiddleware.js

@@ -74,6 +74,9 @@ function unwrapTransactionRollback(error, depth = 0) {
   }
   return unwrapTransactionRollback(error.cause, depth + 1);
 }
+function hasActiveTransaction() {
+  return hasActiveDatabaseConnection() && (transactionScopes.getStore()?.rollback.length ?? 0) > 0;
+}
 function requestTransactionRollback() {
   const state = transactionScopes.getStore();
   const index = state ? state.rollback.length - 1 : -1;
@@ -300,6 +303,55 @@ var init_deferredModelEvents = __esm(() => {
   deferredModelEvents = createAsyncContextStore("@getstrata/deferredModelEvents");
 });
 
+// ../../src/core/database/acquisitionMetrics.ts
+async function observeTransactionAcquisition(metrics, acquire, signal) {
+  const state = states.get(metrics);
+  if (!state)
+    throw new TypeError("Transaction acquisition metrics must be created by the framework factory.");
+  const started = performance.now();
+  state.inflight++;
+  let outcome = "acquired";
+  try {
+    return await acquire();
+  } catch (error) {
+    outcome = signal?.aborted ? "aborted" : "failed";
+    throw error;
+  } finally {
+    state.inflight--;
+    const elapsed = Math.max(0, performance.now() - started) / 1000;
+    const histogram = state.outcomes[outcomes.indexOf(outcome)];
+    if (histogram) {
+      histogram.count++;
+      histogram.sumSeconds += elapsed;
+      for (let index = 0;index < ACQUISITION_BUCKETS_SECONDS.length; index++) {
+        const bound = ACQUISITION_BUCKETS_SECONDS[index];
+        if (bound !== undefined && elapsed <= bound)
+          histogram.buckets[index] = (histogram.buckets[index] ?? 0) + 1;
+      }
+    }
+  }
+}
+var ACQUISITION_BUCKETS_SECONDS, outcomes, metricsBrand, states;
+var init_acquisitionMetrics = __esm(() => {
+  ACQUISITION_BUCKETS_SECONDS = [
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10
+  ];
+  outcomes = ["acquired", "failed", "aborted"];
+  metricsBrand = Symbol("transaction acquisition metrics");
+  states = new WeakMap;
+});
+
 // ../../src/core/database/connection.ts
 function createDatabaseConnection(source) {
   return {
@@ -668,9 +720,13 @@ async function runInTransaction(operation, options = {}) {
     throw new Error("Active database connection does not support transactions. Bind a client with begin() via bindDatabaseConnection.");
   }
   return await settleTransaction(() => runWithDeferredModelEvents(async () => {
-    if (signal && !pool.reserve)
-      throw new Error("Active database connection does not support cancellable transaction acquisition.");
-    const reserved = signal ? await pool.reserve?.({ signal }) : undefined;
+    let reserved;
+    if (signal || options.acquisitionMetrics) {
+      if (!pool.reserve)
+        throw new Error(signal ? "Active database connection does not support cancellable transaction acquisition." : "Active database connection does not support observable transaction acquisition.");
+      const reserve = pool.reserve.bind(pool);
+      reserved = options.acquisitionMetrics ? await observeTransactionAcquisition(options.acquisitionMetrics, () => reserve({ signal }), signal) : await reserve({ signal });
+    }
     const connection = reserved ?? pool;
     try {
       signal?.throwIfAborted();
@@ -688,10 +744,12 @@ var transactionFrame, outerFrames;
 var init_transaction = __esm(() => {
   init_deferredModelEvents();
   init_asyncContextStore();
+  init_acquisitionMetrics();
   init_connection();
   init_connectionContext();
   init_repositoryConnection();
   init_transactionControl();
+  init_acquisitionMetrics();
   transactionFrame = createAsyncContextStore("@getstrata/transactionFrame");
   outerFrames = new WeakMap;
 });

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/http/response.js

@@ -52,6 +52,9 @@ function unwrapTransactionRollback(error, depth = 0) {
   }
   return unwrapTransactionRollback(error.cause, depth + 1);
 }
+function hasActiveTransaction() {
+  return hasActiveDatabaseConnection() && (transactionScopes.getStore()?.rollback.length ?? 0) > 0;
+}
 function requestTransactionRollback() {
   const state = transactionScopes.getStore();
   const index = state ? state.rollback.length - 1 : -1;