@getstrata/core 2.2.9 → 2.2.11

package/dist/index.js

@@ -687,6 +687,111 @@ var init_deferredModelEvents = __esm(() => {
   deferredModelEvents = createAsyncContextStore("@getstrata/deferredModelEvents");
 });
 
+// ../../src/core/database/acquisitionMetrics.ts
+function createTransactionAcquisitionMetrics() {
+  const state = {
+    inflight: 0,
+    outcomes: outcomes.map((outcome) => ({
+      outcome,
+      count: 0,
+      sumSeconds: 0,
+      buckets: ACQUISITION_BUCKETS_SECONDS.map(() => 0)
+    }))
+  };
+  const metrics = {
+    [metricsBrand]: true,
+    snapshot: () => ({
+      inflight: state.inflight,
+      outcomes: state.outcomes.map((histogram) => ({
+        ...histogram,
+        buckets: [...histogram.buckets]
+      }))
+    })
+  };
+  states.set(metrics, state);
+  return metrics;
+}
+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;
+      }
+    }
+  }
+}
+function renderTransactionAcquisitionMetrics(snapshot) {
+  const invalid = () => new TypeError("Invalid transaction acquisition metrics.");
+  if (!Number.isSafeInteger(snapshot.inflight) || snapshot.inflight < 0 || snapshot.outcomes.length !== outcomes.length)
+    throw invalid();
+  const name = "strata_database_transaction_acquisition_duration_seconds";
+  const lines = [
+    "# HELP strata_database_acquisition_collector_success Whether transaction acquisition observation succeeded.",
+    "# TYPE strata_database_acquisition_collector_success gauge",
+    "strata_database_acquisition_collector_success 1",
+    "# HELP strata_database_transaction_acquisition_inflight Native transaction checkouts awaiting settlement in this process.",
+    "# TYPE strata_database_transaction_acquisition_inflight gauge",
+    `strata_database_transaction_acquisition_inflight ${snapshot.inflight}`,
+    `# HELP ${name} Native checkout duration, including pool wait and connection establishment, for explicitly observed transactions.`,
+    `# TYPE ${name} histogram`
+  ];
+  for (let i = 0;i < outcomes.length; i++) {
+    const histogram = snapshot.outcomes[i];
+    if (!histogram || histogram.outcome !== outcomes[i] || !Number.isSafeInteger(histogram.count) || histogram.count < 0 || !Number.isFinite(histogram.sumSeconds) || histogram.sumSeconds < 0 || histogram.buckets.length !== ACQUISITION_BUCKETS_SECONDS.length)
+      throw invalid();
+    let previous = 0;
+    for (let index = 0;index < ACQUISITION_BUCKETS_SECONDS.length; index++) {
+      const value = histogram.buckets[index];
+      if (value === undefined || !Number.isSafeInteger(value) || value < previous || value > histogram.count)
+        throw invalid();
+      previous = value;
+      lines.push(`${name}_bucket{outcome="${histogram.outcome}",le="${ACQUISITION_BUCKETS_SECONDS[index]}"} ${value}`);
+    }
+    lines.push(`${name}_bucket{outcome="${histogram.outcome}",le="+Inf"} ${histogram.count}`, `${name}_count{outcome="${histogram.outcome}"} ${histogram.count}`, `${name}_sum{outcome="${histogram.outcome}"} ${histogram.sumSeconds}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+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 {
@@ -745,9 +850,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();
@@ -765,10 +874,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;
 });
@@ -4123,6 +4234,10 @@ var CACHE_TAGS = {
   careers: "careers",
   offers: "offers"
 };
+
+// ../../src/framework/public-api.ts
+init_acquisitionMetrics();
+
 // ../../src/core/database/baseRepository.ts
 init_eventBus();
 
@@ -8194,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;
@@ -8253,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);
@@ -8306,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;
 }
@@ -8355,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
@@ -9081,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 ")) {
@@ -9092,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:") {
@@ -9155,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.");
@@ -9183,8 +9460,89 @@ init_tenantDatabaseScope();
 
 // ../../src/core/events/outbox/metrics.ts
 init_dialect();
+
+// ../../src/core/database/readOnlyCollector.ts
+init_connectionContext();
+init_dialect();
 init_repositoryConnection();
 init_transaction();
+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;
+  let closed = false;
+  return {
+    async collect() {
+      if (closed)
+        throw new Error(`${name} collector is closed.`);
+      if (hasActiveTransaction() || hasActiveDatabaseConnection())
+        throw new Error(`${name} require an independent transaction.`);
+      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;
+      let expired = false;
+      const acquisition = new AbortController;
+      let timer;
+      const remaining = () => {
+        const value = Math.floor(deadline - performance.now());
+        if (expired || value < 1)
+          throw new Error(`${name} collection timed out.`);
+        return value;
+      };
+      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 }) : (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)
+          active = undefined;
+      }).catch(() => {});
+      try {
+        return await Promise.race([
+          work,
+          new Promise((_, reject) => {
+            timer = setTimeout(() => {
+              expired = true;
+              const error = new Error(`${name} collection timed out.`);
+              acquisition.abort(error);
+              reject(error);
+            }, timeoutMs);
+          })
+        ]);
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+      }
+    },
+    async close() {
+      closed = true;
+      await active?.catch(() => {});
+    }
+  };
+}
+
+// ../../src/core/events/outbox/metrics.ts
+init_repositoryConnection();
 init_databaseTenantContext();
 var specifications = [
   { state: "pending_due", status: "pending", column: "available_at", predicate: "<=", age: true },
@@ -9231,87 +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(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000)
-    throw new TypeError("Outbox metrics timeout must be between 1 and 5000 milliseconds.");
   if (!Number.isSafeInteger(sampleLimit) || sampleLimit < 1 || sampleLimit > 1000)
     throw new TypeError("Outbox metrics sample limit must be between 1 and 1000.");
-  let active;
-  let closed = false;
-  return {
-    async collect() {
-      if (closed)
-        throw new Error("Outbox metrics collector is closed.");
-      if (hasActiveTransaction())
-        throw new Error("Outbox metrics require an independent transaction.");
-      if (currentSqlDialect().driver !== "pgsql")
-        throw new Error("Outbox metrics currently require Postgres.");
-      if (active)
-        throw new Error("Outbox metrics collection is still settling.");
-      const deadline = performance.now() + timeoutMs;
-      let expired = false;
-      const acquisition = new AbortController;
-      let timer;
-      const remaining = () => {
-        const value = Math.floor(deadline - performance.now());
-        if (expired || value < 1)
-          throw new Error("Outbox metrics collection timed out.");
-        return value;
-      };
-      const work = runInTransaction(async () => {
-        await repositoryConnection.unsafe("SELECT set_config('statement_timeout', $1, true)", [`${remaining()}ms`]);
-        await repositoryConnection.unsafe("SET TRANSACTION READ ONLY");
-        return 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 };
-        });
-      }, { acquisitionSignal: acquisition.signal });
-      active = work;
-      work.finally(() => {
-        if (active === work)
-          active = undefined;
-      }).catch(() => {});
-      try {
-        return await Promise.race([
-          work,
-          new Promise((_, reject) => {
-            timer = setTimeout(() => {
-              expired = true;
-              const error = new Error("Outbox metrics collection timed out.");
-              acquisition.abort(error);
-              reject(error);
-            }, timeoutMs);
-          })
-        ]);
-      } finally {
-        if (timer !== undefined)
-          clearTimeout(timer);
-      }
-    },
-    async close() {
-      closed = true;
-      await active?.catch(() => {});
-    }
-  };
+  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)
@@ -9909,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) {
@@ -9918,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;
   }
@@ -12876,6 +13225,86 @@ class Notification {
     return null;
   }
 }
+// ../../src/core/queue/failedJobMetrics.ts
+init_dialect();
+init_repositoryConnection();
+
+// ../../src/core/queue/failedJobTable.ts
+var failedJobTable = defineTable({
+  name: "failed_job",
+  primaryKey: "id",
+  columns: ["id", "job_name", "job_id", "payload", "exception", "failed_at"],
+  defaultOrderBy: { column: "failed_at", direction: "DESC" }
+});
+
+// ../../src/core/queue/failedJobRepository.ts
+class FailedJobRepository extends BaseRepository {
+  constructor() {
+    super(failedJobTable);
+  }
+}
+var failedJobRepository_default = FailedJobRepository;
+
+// ../../src/core/queue/failedJobMetrics.ts
+var schemaQuery = `SELECT c.relkind = 'r' AND c.relpersistence = 'p' AND NOT c.relrowsecurity AND EXISTS (
+  SELECT 1 FROM pg_index i JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[0]
+  WHERE i.indrelid = c.oid AND i.indisprimary AND i.indisvalid AND i.indisready
+    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 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);
+    if (rows.length > sampleLimit + 1 || rows.some((row) => row.id == null))
+      throw new Error("Invalid failed-job metrics response.");
+    return {
+      sampleLimit,
+      count: Math.min(rows.length, sampleLimit),
+      capped: rows.length > sampleLimit
+    };
+  });
+}
+function renderFailedJobMetrics(snapshot) {
+  if (!Number.isSafeInteger(snapshot.sampleLimit) || snapshot.sampleLimit < 1 || snapshot.sampleLimit > 1000 || !Number.isSafeInteger(snapshot.count) || snapshot.count < 0 || snapshot.count > snapshot.sampleLimit || typeof snapshot.capped !== "boolean" || snapshot.capped && snapshot.count !== snapshot.sampleLimit)
+    throw new TypeError("Invalid failed-job metrics snapshot.");
+  return `# HELP strata_queue_failed_job_collector_success Whether failed-job collection succeeded.
+# TYPE strata_queue_failed_job_collector_success gauge
+strata_queue_failed_job_collector_success 1
+# HELP strata_queue_failed_jobs_sample Capped retained failed-job count; a lower bound when capped.
+# TYPE strata_queue_failed_jobs_sample gauge
+strata_queue_failed_jobs_sample ${snapshot.count}
+# HELP strata_queue_failed_jobs_sample_capped Whether the failed-job sample is truncated.
+# TYPE strata_queue_failed_jobs_sample_capped gauge
+strata_queue_failed_jobs_sample_capped ${Number(snapshot.capped)}
+`;
+}
 // ../../src/core/queue/jobRegistry.ts
 class JobRegistry {
   factories = new Map;
@@ -12970,22 +13399,6 @@ class AsyncQueue {
 function createQueue(driver) {
   return driver === "async" ? new AsyncQueue : new SyncQueue;
 }
-// ../../src/core/queue/failedJobTable.ts
-var failedJobTable = defineTable({
-  name: "failed_job",
-  primaryKey: "id",
-  columns: ["id", "job_name", "job_id", "payload", "exception", "failed_at"],
-  defaultOrderBy: { column: "failed_at", direction: "DESC" }
-});
-
-// ../../src/core/queue/failedJobRepository.ts
-class FailedJobRepository extends BaseRepository {
-  constructor() {
-    super(failedJobTable);
-  }
-}
-var failedJobRepository_default = FailedJobRepository;
-
 // ../../src/core/queue/failedJobService.ts
 class FailedJobService {
   repository;
@@ -14688,6 +15101,171 @@ function createTenantMiddleware(options = {}) {
     }
   };
 }
+// ../../src/core/tracing/health.ts
+import {
+  createNoopMeter
+} from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+function observeExportDeadline(state, timeoutMillis) {
+  const deadline = setTimeout(() => {
+    state.exportDeadlineExceededBatches++;
+  }, timeoutMillis);
+  deadline.unref();
+  return deadline;
+}
+function createTracingHealth(enabled, exporterConfigured, timeoutMillis) {
+  const state = {
+    enabled,
+    exporterConfigured,
+    active: true,
+    queueSize: null,
+    queueCapacity: null,
+    droppedSpans: 0,
+    exportedBatches: 0,
+    failedBatches: 0,
+    exportedSpans: 0,
+    failedSpans: 0,
+    exportDeadlineExceededBatches: 0,
+    flushFailures: 0,
+    shutdownFailures: 0
+  };
+  let exportQueueFullSpans = 0;
+  let queueCallback;
+  const noop = createNoopMeter();
+  const meter = {
+    createGauge: noop.createGauge.bind(noop),
+    createHistogram: noop.createHistogram.bind(noop),
+    createObservableGauge: noop.createObservableGauge.bind(noop),
+    createObservableCounter: noop.createObservableCounter.bind(noop),
+    addBatchObservableCallback: noop.addBatchObservableCallback.bind(noop),
+    removeBatchObservableCallback: noop.removeBatchObservableCallback.bind(noop),
+    createCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.processed")
+        return noop.createCounter(name, options);
+      return {
+        add(value, attributes) {
+          if (attributes?.["error.type"] === "queue_full")
+            state.droppedSpans += value;
+        }
+      };
+    },
+    createUpDownCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.queue.capacity")
+        return noop.createUpDownCounter(name, options);
+      return {
+        add(value) {
+          state.queueCapacity = (state.queueCapacity ?? 0) + value;
+        }
+      };
+    },
+    createObservableUpDownCounter(name, options) {
+      if (name !== "otel.sdk.processor.span.queue.size")
+        return noop.createObservableUpDownCounter(name, options);
+      return {
+        addCallback(callback) {
+          queueCallback = callback;
+        },
+        removeCallback(callback) {
+          if (queueCallback === callback)
+            queueCallback = undefined;
+        }
+      };
+    }
+  };
+  const meterProvider = { getMeter: () => meter };
+  return {
+    state,
+    meterProvider,
+    snapshot() {
+      let queueSize = null;
+      queueCallback?.({
+        observe(value) {
+          queueSize = value;
+        }
+      });
+      return {
+        ...state,
+        queueSize,
+        droppedSpans: Math.max(0, state.droppedSpans - exportQueueFullSpans)
+      };
+    },
+    wrap(exporter) {
+      return {
+        export(spans, callback) {
+          const count = spans.length;
+          let completed = false;
+          const deadline = observeExportDeadline(state, timeoutMillis);
+          const finish = (success) => {
+            completed = true;
+            clearTimeout(deadline);
+            if (success) {
+              state.exportedBatches++;
+              state.exportedSpans += count;
+            } else {
+              state.failedBatches++;
+              state.failedSpans += count;
+            }
+          };
+          try {
+            exporter.export(spans, (result) => {
+              if (completed)
+                return;
+              finish(result.code === ExportResultCode.SUCCESS);
+              if (result.error?.name === "queue_full")
+                exportQueueFullSpans += count;
+              callback(result);
+            });
+          } catch (error) {
+            if (!completed)
+              finish(false);
+            throw error;
+          }
+        },
+        shutdown: () => exporter.shutdown(),
+        ...exporter.forceFlush ? { forceFlush: exporter.forceFlush.bind(exporter) } : {}
+      };
+    }
+  };
+}
+function renderTracingMetrics(snapshot) {
+  for (const key of ["enabled", "exporterConfigured", "active"])
+    if (typeof snapshot[key] !== "boolean")
+      throw new TypeError("Invalid tracing metrics.");
+  const values = {
+    strata_tracing_enabled: Number(snapshot.enabled),
+    strata_tracing_exporter_configured: Number(snapshot.exporterConfigured),
+    strata_tracing_active: Number(snapshot.active),
+    strata_tracing_queue_size: snapshot.queueSize,
+    strata_tracing_queue_capacity: snapshot.queueCapacity,
+    strata_tracing_dropped_spans_total: snapshot.droppedSpans,
+    strata_tracing_exported_batches_total: snapshot.exportedBatches,
+    strata_tracing_failed_batches_total: snapshot.failedBatches,
+    strata_tracing_exported_spans_total: snapshot.exportedSpans,
+    strata_tracing_failed_spans_total: snapshot.failedSpans,
+    strata_tracing_export_deadline_exceeded_batches_total: snapshot.exportDeadlineExceededBatches,
+    strata_tracing_flush_failures_total: snapshot.flushFailures,
+    strata_tracing_shutdown_failures_total: snapshot.shutdownFailures
+  };
+  let output = `# HELP strata_tracing_collector_success Whether tracing observation succeeded.
+# TYPE strata_tracing_collector_success gauge
+strata_tracing_collector_success 1
+`;
+  for (const [name, value] of Object.entries(values)) {
+    if (value === null) {
+      if (name === "strata_tracing_queue_size" || name === "strata_tracing_queue_capacity")
+        continue;
+      throw new TypeError("Invalid tracing metrics.");
+    }
+    if (!Number.isSafeInteger(value) || value < 0)
+      throw new TypeError("Invalid tracing metrics.");
+    const type = name.endsWith("_total") ? "counter" : "gauge";
+    output += `# HELP ${name} Process-local tracing ${name.slice(15).replaceAll("_", " ")}.
+# TYPE ${name} ${type}
+${name} ${value}
+`;
+  }
+  return output;
+}
 // ../../src/core/tracing/traceContext.ts
 init_asyncContextStore();
 var traceContextStorage = createAsyncContextStore("@getstrata/traceContext");
@@ -14706,10 +15284,10 @@ import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-ho
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace";
 import {
   AlwaysOffSampler,
   AlwaysOnSampler,
-  BatchSpanProcessor,
   ParentBasedSampler,
   TraceIdRatioBasedSampler
 } from "@opentelemetry/sdk-trace-base";
@@ -14763,11 +15341,14 @@ function createTracingRuntime(options = {}) {
       throw new TypeError("Invalid tracing collector endpoint.");
   }
   const exporter = disabled ? undefined : options.exporter ?? (endpoint ? new OTLPTraceExporter({ url: endpoint, timeoutMillis: timeout, concurrencyLimit: 1 }) : undefined);
+  const health = createTracingHealth(!disabled, exporter !== undefined, timeout);
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({ "service.name": options.serviceName ?? otelServiceName() }),
     sampler,
     spanProcessors: exporter ? [
-      new BatchSpanProcessor(exporter, {
+      new BatchSpanProcessor({
+        exporter: health.wrap(exporter),
+        selfObsMeterProvider: health.meterProvider,
         maxQueueSize: queueSize,
         maxExportBatchSize: batchSize,
         scheduledDelayMillis: delay,
@@ -14787,8 +15368,21 @@ function createTracingRuntime(options = {}) {
     tracer: provider.getTracer("@getstrata/http"),
     propagator: new W3CTraceContextPropagator,
     run: (parent, callback) => context.with(parent, callback),
-    forceFlush: () => provider.forceFlush(),
-    shutdown: () => shutdown ??= provider.shutdown()
+    metrics: () => health.snapshot(),
+    async forceFlush() {
+      try {
+        await provider.forceFlush();
+      } catch (error) {
+        health.state.flushFailures++;
+        throw error;
+      }
+    },
+    shutdown: () => shutdown ??= provider.shutdown().catch((error) => {
+      health.state.shutdownFailures++;
+      throw error;
+    }).finally(() => {
+      health.state.active = false;
+    })
   };
 }
 var runtimeKey = Symbol.for("@getstrata/otel-runtime");
@@ -15408,6 +16002,7 @@ export {
   createCsrfTokenCookie,
   createDatabaseConnection,
   createDatabaseQueryProxy,
+  createFailedJobMetricsCollector,
   createFailedJobService,
   createFlashMiddleware,
   createLoginThrottleMiddleware,
@@ -15444,6 +16039,7 @@ export {
   createTracingMiddleware,
   createTracingRuntime,
   createTrackedJob,
+  createTransactionAcquisitionMetrics,
   createValidateSignatureMiddleware,
   createdResponse,
   currentAuthUser,
@@ -15592,9 +16188,12 @@ export {
   registerModelRepository,
   registerNamedConnection,
   registerShutdownHandler,
+  renderFailedJobMetrics,
   renderKernelErrorChrome,
   renderMarkdownMail,
   renderOutboxMetrics,
+  renderTracingMetrics,
+  renderTransactionAcquisitionMetrics,
   renderWebErrorHtml,
   repositoryConnection,
   requestIdMiddleware,