@sincpro/mobile 0.3.1 → 0.4.1

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>;
+}

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

@@ -0,0 +1,147 @@
+/** Max rows kept in telemetry_queue before eviction kicks in. */
+export const MAX_LOG_QUEUE_SIZE = 5_000;
+/** Max approximate payload bytes kept in telemetry_queue (~2 MB). */
+export const MAX_LOG_QUEUE_BYTES = 2_000_000;
+/** Run the (scanning) eviction check once every N enqueues — see class doc. */
+export 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 const LOG_LEVEL_DROP_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const DEFAULT_DROP_PRIORITY = 1; // treat unknown levels like "info"
+/**
+ * SQL `CASE` mapping level → drop priority, built from {@link LOG_LEVEL_DROP_PRIORITY}
+ * so the policy has a single source of truth. Values are integers and keys are
+ * fixed lowercase ASCII from our own constant — no injection surface.
+ */
+function severityCaseSql() {
+    const whens = Object.entries(LOG_LEVEL_DROP_PRIORITY)
+        .map(([level, rank]) => `WHEN '${level}' THEN ${rank}`)
+        .join(" ");
+    return `CASE lower(level) ${whens} ELSE ${DEFAULT_DROP_PRIORITY} END`;
+}
+/**
+ * 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 class LogQueueRepository {
+    db;
+    maxRows;
+    maxBytes;
+    evictEvery;
+    ops = 0;
+    dropped = 0;
+    constructor(db, maxRows = MAX_LOG_QUEUE_SIZE, maxBytes = MAX_LOG_QUEUE_BYTES, evictEvery = EVICT_CHECK_EVERY) {
+        this.db = db;
+        this.maxRows = maxRows;
+        this.maxBytes = maxBytes;
+        this.evictEvery = Math.max(1, evictEvery);
+    }
+    async enqueue(level, message) {
+        await this.db.mutateDatabase(`INSERT INTO telemetry_queue (level, message) VALUES (?, ?)`, level, message);
+        if (++this.ops >= this.evictEvery) {
+            this.ops = 0;
+            await this.evict();
+        }
+    }
+    /**
+     * 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.
+     */
+    async evict() {
+        for (;;) {
+            const { rows, approxBytes } = await this.measure();
+            if (rows <= this.maxRows && approxBytes <= this.maxBytes)
+                return;
+            const removed = rows > this.maxRows
+                ? await this.dropBySeverity(rows - this.maxRows)
+                : await this.dropLargestUntilBytesFreed(approxBytes - this.maxBytes);
+            if (removed === 0)
+                return;
+            this.dropped += removed;
+        }
+    }
+    /** Deletes `n` rows lowest-severity-first, oldest-first within a tier. */
+    async dropBySeverity(n) {
+        const res = await this.db.mutateDatabase(`DELETE FROM telemetry_queue WHERE id IN (
+         SELECT id FROM telemetry_queue ORDER BY ${severityCaseSql()} ASC, id ASC LIMIT ?
+       )`, n);
+        return res?.changes ?? 0;
+    }
+    /**
+     * Deletes the largest rows (oldest as tiebreak) until at least `overage` bytes
+     * are reclaimed, using each row's ACTUAL size. Returns rows removed.
+     */
+    async dropLargestUntilBytesFreed(overage) {
+        const candidates = await this.db.getAllAsync(`SELECT id, (length(level) + length(message)) AS len
+         FROM telemetry_queue ORDER BY (length(level) + length(message)) DESC, id ASC LIMIT 500`);
+        if (candidates.length === 0)
+            return 0;
+        const ids = [];
+        let freed = 0;
+        for (const c of candidates) {
+            ids.push(c.id);
+            freed += c.len;
+            if (freed >= overage)
+                break;
+        }
+        const placeholders = ids.map(() => "?").join(", ");
+        const res = await this.db.mutateDatabase(`DELETE FROM telemetry_queue WHERE id IN (${placeholders})`, ...ids);
+        return res?.changes ?? ids.length;
+    }
+    async measure() {
+        const row = await this.db.getFirstAsync(`SELECT COUNT(*) AS rows,
+        COALESCE(SUM(length(level) + length(message)), 0) AS bytes
+       FROM telemetry_queue`);
+        return { rows: row?.rows ?? 0, approxBytes: row?.bytes ?? 0 };
+    }
+    async stats() {
+        const { rows, approxBytes } = await this.measure();
+        // Logs are not head-sampled — `sampled` is always 0.
+        return { rows, approxBytes, dropped: this.dropped, sampled: 0 };
+    }
+    async findPending(limit = 100) {
+        return this.db.getAllAsync(`SELECT id, level, message, created_at FROM telemetry_queue ORDER BY id ASC LIMIT ?`, limit);
+    }
+    async removeMany(ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => "?").join(", ");
+        await this.db.mutateDatabase(`DELETE FROM telemetry_queue WHERE id IN (${placeholders})`, ...ids);
+    }
+    /** Deletes entries older than `days` days. Called before each flush to bound queue growth. */
+    async pruneExpired(days = 7) {
+        await this.db.mutateDatabase(`DELETE FROM telemetry_queue WHERE created_at < datetime('now', ?)`, `-${days} days`);
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { LokiConfig } from "../types";
+import type { LogEntry, LogQueueRepository } from "./log_queue_repository";
+/** @internal — exposed for compliance testing only */
+export declare function _nowNs(): string;
+/**
+ * HTTP client for Loki's push API (`POST /loki/api/v1/push`).
+ *
+ * `push()` is fire-and-forget: on failure it enqueues to the outbox (if provided) so the
+ * flush cron can retry. `deliver()` is the awaitable batch-send used by the flush cron.
+ */
+export declare class LokiClient {
+    private readonly config;
+    private readonly queue;
+    private readonly timeoutMs;
+    constructor(config: LokiConfig, queue?: LogQueueRepository, timeoutMs?: number);
+    push(level: string, message: string): void;
+    /**
+     * Batch-delivers outbox entries to Loki. Groups entries by level into separate streams.
+     * Throws on network error or non-2xx response — caller must not remove entries from the
+     * outbox unless this resolves successfully.
+     */
+    deliver(entries: LogEntry[]): Promise<void>;
+    /**
+     * Builds the headers for every request: the `auth` shortcut, then any custom
+     * `headers` (which win on conflict — e.g. a gateway API key, or an explicit
+     * Authorization overriding `auth`), then a non-negotiable `Content-Type`.
+     * The body is always JSON, so a custom `content-type` (any casing) must not
+     * override it — Loki would reject the push.
+     */
+    private requestHeaders;
+    private authHeader;
+}