@getstrata/core 2.2.9 → 2.2.10

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @getstrata/core changelog
 
+## 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/postgresReadOnlyCollector.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 createPostgresReadOnlyCollector<T>(name: string, timeoutMs: number, collect: (remaining: () => number) => Promise<T>): ReadOnlyCollector<T>;
+export { createPostgresReadOnlyCollector };

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/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/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;

package/dist/entries/jobs/exportAuditLogsJob.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;
 });