@sincpro/mobile 0.3.1 → 0.4.2

package/dist/infrastructure/telemetry/buffer_registry.js

@@ -0,0 +1,26 @@
+let _logQueue = null;
+let _spanQueue = null;
+/** @internal — wired by initTelemetry so consumers can inspect buffer pressure. */
+export function _registerBuffers(logQueue, spanQueue) {
+    _logQueue = logQueue;
+    _spanQueue = spanQueue;
+}
+/** @internal — test use only. */
+export function _resetBuffers() {
+    _logQueue = null;
+    _spanQueue = null;
+}
+/**
+ * Current size and drop pressure of the telemetry buffers.
+ *
+ * Use this to surface offline backlog in dashboards or health checks — a high
+ * `dropped` count means the device has been offline long enough to lose data.
+ * Returns null buffers when the corresponding signal is disabled.
+ */
+export async function bufferStats() {
+    const [logs, spans] = await Promise.all([
+        _logQueue?.stats() ?? Promise.resolve(null),
+        _spanQueue?.stats() ?? Promise.resolve(null),
+    ]);
+    return { logs, spans };
+}

package/dist/infrastructure/telemetry/connectivity_state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Self-correcting online/offline flag for the telemetry pipeline.
+ *
+ * The framework does NOT depend on the app's connectivity cron — that is
+ * client-specific and optional. Instead this flag is corrected from two cheap,
+ * always-available sources:
+ *   - the outcome of each delivery attempt (success → online, network failure → offline)
+ *   - optional connectivity events, when the host app emits them
+ *
+ * It exists to skip delivery attempts while known-offline (avoiding hung HTTP
+ * and wasted work); the send timeout in the HTTP clients is the backstop when
+ * the flag is optimistically wrong.
+ */
+export declare class ConnectivityState {
+    private online;
+    constructor(initiallyOnline?: boolean);
+    isOnline(): boolean;
+    markOnline(): void;
+    markOffline(): void;
+}

package/dist/infrastructure/telemetry/connectivity_state.js

@@ -0,0 +1,28 @@
+/**
+ * Self-correcting online/offline flag for the telemetry pipeline.
+ *
+ * The framework does NOT depend on the app's connectivity cron — that is
+ * client-specific and optional. Instead this flag is corrected from two cheap,
+ * always-available sources:
+ *   - the outcome of each delivery attempt (success → online, network failure → offline)
+ *   - optional connectivity events, when the host app emits them
+ *
+ * It exists to skip delivery attempts while known-offline (avoiding hung HTTP
+ * and wasted work); the send timeout in the HTTP clients is the backstop when
+ * the flag is optimistically wrong.
+ */
+export class ConnectivityState {
+    online;
+    constructor(initiallyOnline = true) {
+        this.online = initiallyOnline;
+    }
+    isOnline() {
+        return this.online;
+    }
+    markOnline() {
+        this.online = true;
+    }
+    markOffline() {
+        this.online = false;
+    }
+}

package/dist/infrastructure/telemetry/context_keys.d.ts

@@ -0,0 +1,7 @@
+import type { Context as OtelContext } from "@opentelemetry/api";
+/**
+ * Key under which the active OTel Context (carrying the current Span) is
+ * stored inside the framework Context. Shared between tracing_hooks (writes)
+ * and active_span (reads) so both sides reference the same Symbol.
+ */
+export declare const OTEL_CTX_KEY: import("../context_manager/context_key").ContextKey<OtelContext>;

package/dist/infrastructure/telemetry/context_keys.js

@@ -0,0 +1,7 @@
+import { createContextKey } from "../context_manager/index";
+/**
+ * Key under which the active OTel Context (carrying the current Span) is
+ * stored inside the framework Context. Shared between tracing_hooks (writes)
+ * and active_span (reads) so both sides reference the same Symbol.
+ */
+export const OTEL_CTX_KEY = createContextKey("sincpro.telemetry.otel_context");

package/dist/infrastructure/telemetry/fetch_with_timeout.d.ts

@@ -0,0 +1,8 @@
+/** Default send timeout — fail fast instead of hanging when the network is flaky/offline. */
+export declare const DEFAULT_SEND_TIMEOUT_MS = 4000;
+/**
+ * `fetch` with a hard timeout via AbortController. On timeout the request is
+ * aborted and the returned promise rejects, so an offline/slow network never
+ * blocks the telemetry pipeline indefinitely.
+ */
+export declare function fetchWithTimeout(input: string, init: RequestInit, timeoutMs?: number): Promise<Response>;

package/dist/infrastructure/telemetry/fetch_with_timeout.js

@@ -0,0 +1,17 @@
+/** Default send timeout — fail fast instead of hanging when the network is flaky/offline. */
+export const DEFAULT_SEND_TIMEOUT_MS = 4000;
+/**
+ * `fetch` with a hard timeout via AbortController. On timeout the request is
+ * aborted and the returned promise rejects, so an offline/slow network never
+ * blocks the telemetry pipeline indefinitely.
+ */
+export async function fetchWithTimeout(input, init, timeoutMs = DEFAULT_SEND_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(input, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/infrastructure/telemetry/flush_telemetry.d.ts

@@ -0,0 +1,40 @@
+import type { ConnectivityState } from "./connectivity_state";
+import type { FlushClient, FlushQueue } from "./logging/flush_job";
+import type { SpanFlushClient, SpanFlushQueue } from "./tracing/span_flush_job";
+export interface FlushTelemetryDeps {
+    connectivity: ConnectivityState;
+    logClient?: FlushClient | null;
+    logQueue?: FlushQueue | null;
+    spanClient?: SpanFlushClient | null;
+    spanQueue?: SpanFlushQueue | null;
+}
+/**
+ * The single unit of telemetry delivery. Every trigger — production signal,
+ * reconnect event, background cron — funnels through `run()`, which drains BOTH
+ * the log and span queues.
+ *
+ * Throttling and offline recovery are delegated to the jobs' own exponential
+ * backoff: after a failed delivery a job skips a growing number of runs, then
+ * retries. There is NO sticky offline gate, so the pipeline always recovers
+ * once the network returns — even with no cron and no connectivity events. The
+ * HTTP send timeout prevents a flush from hanging while offline.
+ *
+ * `ConnectivityState` is kept informational (surfaced in stats, fed by events);
+ * it never blocks delivery.
+ */
+export declare class FlushTelemetry {
+    private readonly deps;
+    private logState;
+    private spanState;
+    private running;
+    private pending;
+    constructor(deps: FlushTelemetryDeps);
+    /**
+     * @param resetBackoff - clear the jobs' backoff and retry immediately. Used by
+     *   the reconnect event and the background cron so recovery is instant instead
+     *   of waiting for the current backoff window to elapse.
+     */
+    run({ resetBackoff }?: {
+        resetBackoff?: boolean;
+    }): Promise<void>;
+}

package/dist/infrastructure/telemetry/flush_telemetry.js

@@ -0,0 +1,72 @@
+import { createLogFlushJobState, runLogFlushJob } from "./logging/flush_job";
+import { createSpanFlushJobState, runSpanFlushJob } from "./tracing/span_flush_job";
+/**
+ * The single unit of telemetry delivery. Every trigger — production signal,
+ * reconnect event, background cron — funnels through `run()`, which drains BOTH
+ * the log and span queues.
+ *
+ * Throttling and offline recovery are delegated to the jobs' own exponential
+ * backoff: after a failed delivery a job skips a growing number of runs, then
+ * retries. There is NO sticky offline gate, so the pipeline always recovers
+ * once the network returns — even with no cron and no connectivity events. The
+ * HTTP send timeout prevents a flush from hanging while offline.
+ *
+ * `ConnectivityState` is kept informational (surfaced in stats, fed by events);
+ * it never blocks delivery.
+ */
+export class FlushTelemetry {
+    deps;
+    logState = createLogFlushJobState();
+    spanState = createSpanFlushJobState();
+    running = false;
+    pending = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * @param resetBackoff - clear the jobs' backoff and retry immediately. Used by
+     *   the reconnect event and the background cron so recovery is instant instead
+     *   of waiting for the current backoff window to elapse.
+     */
+    async run({ resetBackoff = false } = {}) {
+        // Re-entrancy guard. A trigger arriving mid-flush sets `pending` so the
+        // current run loops once more — no produced telemetry is silently dropped.
+        if (this.running) {
+            this.pending = true;
+            return;
+        }
+        this.running = true;
+        try {
+            let reset = resetBackoff;
+            do {
+                this.pending = false;
+                if (reset) {
+                    this.logState = createLogFlushJobState();
+                    this.spanState = createSpanFlushJobState();
+                    reset = false;
+                }
+                let delivered = false;
+                let failed = false;
+                if (this.deps.logClient && this.deps.logQueue) {
+                    const r = await runLogFlushJob(this.deps.logClient, this.deps.logQueue, this.logState);
+                    delivered ||= r.delivered > 0;
+                    failed ||= r.failed;
+                }
+                if (this.deps.spanClient && this.deps.spanQueue) {
+                    const r = await runSpanFlushJob(this.deps.spanClient, this.deps.spanQueue, this.spanState);
+                    delivered ||= r.delivered > 0;
+                    failed ||= r.failed;
+                }
+                // A working destination means we are online; only a total failure
+                // (nothing delivered) flips the informational flag offline.
+                if (delivered)
+                    this.deps.connectivity.markOnline();
+                else if (failed)
+                    this.deps.connectivity.markOffline();
+            } while (this.pending);
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}

package/dist/infrastructure/telemetry/index.d.ts

@@ -0,0 +1,17 @@
+export { Tracing } from "./tracing_facade";
+export { initTelemetry } from "./init_telemetry";
+export type { BufferStats, FlushConfig, LokiAuth, LokiConfig, OtlpConfig, TelemetryBufferStats, TelemetryConfig, } from "./types";
+export { bufferStats } from "./buffer_registry";
+export type { LogEntry } from "./logging/log_queue_repository";
+export { LogQueueRepository } from "./logging/log_queue_repository";
+export { LokiClient } from "./logging/loki_client";
+export { getLokiClient } from "./logging/loki_registry";
+export { activeTraceLabel, getActiveSpanContext } from "./tracing/active_span";
+export { OtlpClient } from "./tracing/otlp_client";
+export type { OtlpExportRequest } from "./tracing/otlp_serializer";
+export { serializeToOtlp } from "./tracing/otlp_serializer";
+export type { SpanInput, SpanRow } from "./tracing/span_queue_repository";
+export { SpanQueueRepository } from "./tracing/span_queue_repository";
+export { SQLiteSpanExporter } from "./tracing/sqlite_span_exporter";
+export { getTracer } from "./tracing/tracer";
+export { tracingHooks } from "./tracing/tracing_hooks";

package/dist/infrastructure/telemetry/index.js

@@ -0,0 +1,17 @@
+// Main entry point — public facade for framework consumers
+export { Tracing } from "./tracing_facade";
+// Initialization
+export { initTelemetry } from "./init_telemetry";
+// Buffer observability
+export { bufferStats } from "./buffer_registry";
+export { LogQueueRepository } from "./logging/log_queue_repository";
+export { LokiClient } from "./logging/loki_client";
+export { getLokiClient } from "./logging/loki_registry";
+// Tracing
+export { activeTraceLabel, getActiveSpanContext } from "./tracing/active_span";
+export { OtlpClient } from "./tracing/otlp_client";
+export { serializeToOtlp } from "./tracing/otlp_serializer";
+export { SpanQueueRepository } from "./tracing/span_queue_repository";
+export { SQLiteSpanExporter } from "./tracing/sqlite_span_exporter";
+export { getTracer } from "./tracing/tracer";
+export { tracingHooks } from "./tracing/tracing_hooks";

package/dist/infrastructure/telemetry/init_telemetry.d.ts

@@ -0,0 +1,21 @@
+import type { TelemetryConfig } from "./types";
+/**
+ * Initializes telemetry with offline-first delivery.
+ *
+ * Delivery is event-driven, not a fixed timer:
+ * - Producing telemetry schedules a debounced flush (the primary trigger).
+ * - A single {@link FlushTelemetry} use case drains BOTH the log and span
+ *   queues, gated by a self-correcting connectivity flag + HTTP send timeout.
+ * - Optional triggers (none required): reconnect events drain the backlog
+ *   immediately; a long-interval background cron probes as a safety net.
+ *
+ * Spans always buffer to SQLite only when an OTLP destination is configured;
+ * the TracerProvider is registered regardless so `@Trace`/`withSpan` work.
+ *
+ * Idempotent: safe to call again (hot-reload, config change). The previous
+ * worker (signal + events + cron) is fully torn down — awaited — before the new
+ * one registers, so the shared background task name is never double-registered.
+ *
+ * Call once at app startup after migrations have run (`createApp` handles this).
+ */
+export declare function initTelemetry(config: TelemetryConfig): Promise<void>;

package/dist/infrastructure/telemetry/init_telemetry.js

@@ -0,0 +1,85 @@
+import { DBCursor } from "../../infrastructure/database";
+import { _registerBuffers } from "./buffer_registry";
+import { ConnectivityState } from "./connectivity_state";
+import { FlushTelemetry } from "./flush_telemetry";
+import { LogQueueRepository } from "./logging/log_queue_repository";
+import { _resetLokiClient, getLokiClient, initLokiClient } from "./logging/loki_registry";
+import { TelemetryFlushWorker } from "./telemetry_flush_worker";
+import { TelemetrySignal } from "./telemetry_signal";
+import { OtlpClient } from "./tracing/otlp_client";
+import { EVICT_CHECK_EVERY, MAX_SPANS_QUEUE_BYTES, MAX_SPANS_QUEUE_SIZE, SpanQueueRepository, } from "./tracing/span_queue_repository";
+import { SpanSampler } from "./tracing/span_sampler";
+import { initTracing } from "./tracing/tracer";
+let _worker = null;
+/**
+ * Initializes telemetry with offline-first delivery.
+ *
+ * Delivery is event-driven, not a fixed timer:
+ * - Producing telemetry schedules a debounced flush (the primary trigger).
+ * - A single {@link FlushTelemetry} use case drains BOTH the log and span
+ *   queues, gated by a self-correcting connectivity flag + HTTP send timeout.
+ * - Optional triggers (none required): reconnect events drain the backlog
+ *   immediately; a long-interval background cron probes as a safety net.
+ *
+ * Spans always buffer to SQLite only when an OTLP destination is configured;
+ * the TracerProvider is registered regardless so `@Trace`/`withSpan` work.
+ *
+ * Idempotent: safe to call again (hot-reload, config change). The previous
+ * worker (signal + events + cron) is fully torn down — awaited — before the new
+ * one registers, so the shared background task name is never double-registered.
+ *
+ * Call once at app startup after migrations have run (`createApp` handles this).
+ */
+export async function initTelemetry(config) {
+    // Tear down the previous worker before re-wiring (hot-reload / config change).
+    // Awaited so the old background task is unregistered before we register a new
+    // one under the same task name.
+    await _worker?.stop().catch(() => { });
+    _worker = null;
+    const connectivity = new ConnectivityState();
+    const timeoutMs = config.flush?.sendTimeoutMs;
+    // Logs — opportunistic push (with fallback to SQLite) + batch drain on flush.
+    let logQueue = null;
+    if (config.loki) {
+        logQueue = new LogQueueRepository(DBCursor);
+        initLokiClient(config.loki, logQueue, timeoutMs);
+    }
+    else {
+        // Drop a stale client from a previous init that had Loki configured.
+        _resetLokiClient();
+    }
+    const logClient = config.loki ? getLokiClient() : null;
+    // Spans — always buffered to SQLite; OTLP client only when a destination exists.
+    // Head sampling (default on) drops whole traces at ingest once the buffer is
+    // near full, so sustained offline pressure degrades gracefully instead of
+    // thrashing insert→evict.
+    const spanQueue = new SpanQueueRepository(DBCursor, MAX_SPANS_QUEUE_SIZE, MAX_SPANS_QUEUE_BYTES, EVICT_CHECK_EVERY, new SpanSampler());
+    const spanClient = config.otlp ? new OtlpClient(config.otlp, timeoutMs) : null;
+    // The single delivery use case — all triggers funnel here.
+    const flush = new FlushTelemetry({
+        connectivity,
+        logClient,
+        logQueue,
+        spanClient,
+        spanQueue,
+    });
+    // Production signal: producing telemetry schedules a debounced flush.
+    const signal = new TelemetrySignal(() => {
+        flush.run().catch(() => { });
+    }, config.flush?.debounceMs);
+    // Register the TracerProvider; persist spans (and fire the signal) only when
+    // an OTLP destination is configured.
+    initTracing(spanQueue, !!config.otlp, () => signal.notify(), {
+        serviceName: config.serviceName,
+        serviceVersion: config.serviceVersion,
+        deploymentEnvironment: config.deploymentEnvironment,
+        extra: config.resourceAttributes,
+    });
+    _worker = new TelemetryFlushWorker(flush, signal, connectivity, {
+        backgroundIntervalMin: config.flush?.backgroundIntervalMin,
+        onConnectivityEvents: config.flush?.onConnectivityEvents,
+    });
+    _worker.start();
+    // Expose buffer pressure for health checks / dashboards.
+    _registerBuffers(logQueue, spanQueue);
+}

package/dist/infrastructure/telemetry/logging/flush_job.d.ts

@@ -0,0 +1,44 @@
+import type { LogEntry } from "./log_queue_repository";
+/** Max entries per Loki push request. Keeps payloads well under the 4MB Loki limit. */
+export declare const FLUSH_BATCH_SIZE = 100;
+/**
+ * Max batches drained in a single cron tick.
+ * After an offline period the queue can hold thousands of entries; without this cap
+ * a single tick could run for minutes blocking the CronWorker job slot.
+ * 5 batches × 100 entries = 500 entries max per minute — enough to drain hours of
+ * backlog within a few ticks without saturating the cron.
+ */
+export declare const MAX_BATCHES_PER_TICK = 5;
+/** Mutable backoff state — one instance held by FlushTelemetry. */
+export interface LogFlushJobState {
+    consecutiveFailures: number;
+    skipTicksRemaining: number;
+}
+export declare function createLogFlushJobState(): LogFlushJobState;
+/** Outcome of one flush run — lets callers update connectivity state. */
+export interface FlushResult {
+    /** Batches successfully delivered this run. */
+    delivered: number;
+    /** True if a delivery failed (network/HTTP) — caller may mark offline. */
+    failed: boolean;
+}
+export interface FlushClient {
+    deliver(entries: LogEntry[]): Promise<void>;
+}
+export interface FlushQueue {
+    pruneExpired(): Promise<void>;
+    findPending(limit: number): Promise<LogEntry[]>;
+    removeMany(ids: number[]): Promise<void>;
+}
+/**
+ * One tick of the flush cron.
+ *
+ * Ordering invariant: `deliver()` always runs before `removeMany()`.
+ * A crash between the two means the same entries are retried next tick (at-least-once
+ * delivery). Duplicates in Loki are acceptable for log telemetry; data loss is not.
+ *
+ * Transactions: impossible here — an HTTP call sits between the SQLite read and delete.
+ * The mutex inside DBCursor serialises concurrent DB access, but two overlapping cron
+ * ticks can still deliver the same batch twice. Again: acceptable for logs.
+ */
+export declare function runLogFlushJob(client: FlushClient, queue: FlushQueue, state: LogFlushJobState): Promise<FlushResult>;

package/dist/infrastructure/telemetry/logging/flush_job.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Max entries per Loki push request. Keeps payloads well under the 4MB Loki limit. */
+export const FLUSH_BATCH_SIZE = 100;
+/**
+ * Max batches drained in a single cron tick.
+ * After an offline period the queue can hold thousands of entries; without this cap
+ * a single tick could run for minutes blocking the CronWorker job slot.
+ * 5 batches × 100 entries = 500 entries max per minute — enough to drain hours of
+ * backlog within a few ticks without saturating the cron.
+ */
+export const MAX_BATCHES_PER_TICK = 5;
+/**
+ * Exponential backoff cap in ticks. After repeated Loki failures the cron backs off
+ * up to 32 skipped ticks (32 min at 1-min interval) before retrying.
+ */
+const MAX_SKIP_TICKS = 32;
+export function createLogFlushJobState() {
+    return { consecutiveFailures: 0, skipTicksRemaining: 0 };
+}
+// ---------------------------------------------------------------------------
+// Core flush logic
+// ---------------------------------------------------------------------------
+/**
+ * One tick of the flush cron.
+ *
+ * Ordering invariant: `deliver()` always runs before `removeMany()`.
+ * A crash between the two means the same entries are retried next tick (at-least-once
+ * delivery). Duplicates in Loki are acceptable for log telemetry; data loss is not.
+ *
+ * Transactions: impossible here — an HTTP call sits between the SQLite read and delete.
+ * The mutex inside DBCursor serialises concurrent DB access, but two overlapping cron
+ * ticks can still deliver the same batch twice. Again: acceptable for logs.
+ */
+export async function runLogFlushJob(client, queue, state) {
+    // Backoff — skip this tick if previous deliveries failed repeatedly
+    if (state.skipTicksRemaining > 0) {
+        state.skipTicksRemaining -= 1;
+        return { delivered: 0, failed: false };
+    }
+    await queue.pruneExpired();
+    let batchesDelivered = 0;
+    while (batchesDelivered < MAX_BATCHES_PER_TICK) {
+        const entries = await queue.findPending(FLUSH_BATCH_SIZE);
+        if (entries.length === 0)
+            break;
+        try {
+            await client.deliver(entries);
+        }
+        catch {
+            // Loki is unavailable — keep entries in queue and back off.
+            state.consecutiveFailures += 1;
+            // 1st fail → skip 1 tick (retry in 2 min)
+            // 2nd fail → skip 2 ticks (retry in 3 min)  …capped at 32
+            state.skipTicksRemaining = Math.min(Math.pow(2, state.consecutiveFailures - 1), MAX_SKIP_TICKS);
+            return { delivered: batchesDelivered, failed: true };
+        }
+        await queue.removeMany(entries.map((e) => e.id));
+        batchesDelivered += 1;
+        // Fewer entries than the batch limit → queue is now empty
+        if (entries.length < FLUSH_BATCH_SIZE)
+            break;
+    }
+    if (batchesDelivered > 0) {
+        state.consecutiveFailures = 0;
+    }
+    return { delivered: batchesDelivered, failed: false };
+}

package/dist/infrastructure/telemetry/logging/log_queue_repository.d.ts

@@ -0,0 +1,76 @@
+import type { DBCursor } from "../../../infrastructure/database";
+import type { BufferStats } from "../types";
+export interface LogEntry {
+    id: number;
+    level: string;
+    message: string;
+    created_at: string;
+}
+/** Max rows kept in telemetry_queue before eviction kicks in. */
+export declare const MAX_LOG_QUEUE_SIZE = 5000;
+/** Max approximate payload bytes kept in telemetry_queue (~2 MB). */
+export declare const MAX_LOG_QUEUE_BYTES = 2000000;
+/** Run the (scanning) eviction check once every N enqueues — see class doc. */
+export declare const EVICT_CHECK_EVERY = 32;
+/**
+ * Drop priority by level — LOWER is evicted FIRST. So under pressure debug/info
+ * go before warn, and error survives longest. Unknown levels fall back to
+ * {@link DEFAULT_DROP_PRIORITY}. Keys are the lowercase level strings the logger
+ * persists.
+ */
+export declare const LOG_LEVEL_DROP_PRIORITY: Readonly<Record<string, number>>;
+/**
+ * Offline-first log buffer, bounded by BOTH a row count and a payload-byte
+ * budget. When either is exceeded, rows are evicted **lowest-severity-first**
+ * (debug → info → warn → error), oldest-first within a severity — so error/warn
+ * logs survive longest under sustained offline pressure.
+ *
+ * The budget check scans the table, so it runs **amortized** — once every
+ * `evictEvery` enqueues — to keep the hot path cheap. The bound is therefore
+ * soft: the queue may transiently exceed the cap by up to `evictEvery` rows.
+ *
+ * Telemetry is best-effort: under sustained offline pressure logs ARE dropped,
+ * but the loss is bounded, severity-aware, and observable (see {@link stats}).
+ * Business-critical data must NOT live here.
+ */
+export declare class LogQueueRepository {
+    private readonly db;
+    private readonly maxRows;
+    private readonly maxBytes;
+    private readonly evictEvery;
+    private ops;
+    private dropped;
+    constructor(db: typeof DBCursor, maxRows?: number, maxBytes?: number, evictEvery?: number);
+    enqueue(level: string, message: string): Promise<void>;
+    /**
+     * Brings the queue under both budgets. The two budgets use DIFFERENT victim
+     * policies on purpose:
+     *
+     *  - Row pressure → **severity-aware**: drop lowest-severity, oldest-first.
+     *    Each deletion reduces the count by exactly one, so this is exact.
+     *  - Byte pressure → **largest-first**, reclaiming ACTUAL bytes. Severity is
+     *    deliberately NOT used here: when the overage is caused by one oversized
+     *    payload, protecting it (severity-first) forces deleting everything else
+     *    to free its bytes, annihilating the queue to clear an overage that row
+     *    itself caused. Largest-first targets the cause directly, so the maximum
+     *    number of (small, information-dense) entries survive. Corollary: a huge
+     *    high-severity payload is NOT protected from byte eviction — keep large
+     *    blobs out of logs.
+     *
+     * Terminates: each pass removes ≥1 row (count strictly decreases) or returns.
+     */
+    private evict;
+    /** Deletes `n` rows lowest-severity-first, oldest-first within a tier. */
+    private dropBySeverity;
+    /**
+     * Deletes the largest rows (oldest as tiebreak) until at least `overage` bytes
+     * are reclaimed, using each row's ACTUAL size. Returns rows removed.
+     */
+    private dropLargestUntilBytesFreed;
+    private measure;
+    stats(): Promise<BufferStats>;
+    findPending(limit?: number): Promise<LogEntry[]>;
+    removeMany(ids: number[]): Promise<void>;
+    /** Deletes entries older than `days` days. Called before each flush to bound queue growth. */
+    pruneExpired(days?: number): Promise<void>;
+}