@sincpro/mobile 0.3.1 → 0.4.2

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

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

@@ -0,0 +1,118 @@
+import { DEFAULT_SEND_TIMEOUT_MS, fetchWithTimeout } from "../fetch_with_timeout";
+// ---------------------------------------------------------------------------
+// Monotonic nanosecond timestamp
+// Loki rejects duplicate timestamps within the same stream (HTTP 400).
+// If two push() calls happen in the same millisecond they'd produce identical
+// ns values — the counter guarantees strict monotonicity.
+// ---------------------------------------------------------------------------
+let _lastMs = 0;
+let _nsSeq = 0;
+/** @internal — exposed for compliance testing only */
+export function _nowNs() {
+    const ms = Date.now();
+    if (ms === _lastMs) {
+        _nsSeq += 1;
+    }
+    else {
+        _lastMs = ms;
+        _nsSeq = 0;
+    }
+    // BigInt required: ms * 1_000_000 ≈ 1.78e18 in 2026, which exceeds Number.MAX_SAFE_INTEGER
+    // (~9e15). Float64 granularity at that magnitude is ~512, so the _nsSeq offset would be
+    // invisible — producing duplicate timestamps that Loki rejects with HTTP 400.
+    return String(BigInt(ms) * 1000000n + BigInt(_nsSeq));
+}
+/**
+ * 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 class LokiClient {
+    config;
+    queue;
+    timeoutMs;
+    constructor(config, queue, timeoutMs = DEFAULT_SEND_TIMEOUT_MS) {
+        this.config = config;
+        this.queue = queue ?? null;
+        this.timeoutMs = timeoutMs;
+    }
+    push(level, message) {
+        const body = JSON.stringify({
+            streams: [
+                {
+                    stream: { ...this.config.labels, level },
+                    values: [[_nowNs(), message]],
+                },
+            ],
+        });
+        fetchWithTimeout(`${this.config.endpoint}/loki/api/v1/push`, {
+            method: "POST",
+            headers: this.requestHeaders(),
+            body,
+        }, this.timeoutMs).catch(() => {
+            const q = this.queue;
+            if (q) {
+                queueMicrotask(() => q.enqueue(level, message).catch(() => { }));
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    async deliver(entries) {
+        if (entries.length === 0)
+            return;
+        const byLevel = new Map();
+        for (const entry of entries) {
+            if (!byLevel.has(entry.level))
+                byLevel.set(entry.level, []);
+            byLevel.get(entry.level).push(entry);
+        }
+        const streams = Array.from(byLevel.entries()).map(([level, levelEntries]) => ({
+            stream: { ...this.config.labels, level },
+            values: levelEntries.map((entry, i) => {
+                const baseNs = BigInt(new Date(entry.created_at.replace(" ", "T") + "Z").getTime()) * 1000000n;
+                return [String(baseNs + BigInt(i)), entry.message];
+            }),
+        }));
+        const res = await fetchWithTimeout(`${this.config.endpoint}/loki/api/v1/push`, {
+            method: "POST",
+            headers: this.requestHeaders(),
+            body: JSON.stringify({ streams }),
+        }, this.timeoutMs);
+        if (!res.ok) {
+            throw new Error(`Loki batch delivery failed: HTTP ${res.status}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    requestHeaders() {
+        const custom = { ...this.config.headers };
+        for (const key of Object.keys(custom)) {
+            if (key.toLowerCase() === "content-type")
+                delete custom[key];
+        }
+        return {
+            ...this.authHeader(),
+            ...custom,
+            "Content-Type": "application/json",
+        };
+    }
+    authHeader() {
+        const auth = this.config.auth;
+        if (!auth)
+            return {};
+        if (auth.type === "basic") {
+            return { Authorization: `Basic ${btoa(`${auth.username}:${auth.password}`)}` };
+        }
+        return { Authorization: `Bearer ${auth.token}` };
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { LokiConfig } from "../types";
+import type { LogQueueRepository } from "./log_queue_repository";
+import { LokiClient } from "./loki_client";
+/**
+ * Low-level client initializer. Prefer `initTelemetry` from the telemetry index, which also
+ * wires the SQLite outbox and the flush cron. Use this directly only in tests.
+ */
+export declare function initLokiClient(config: LokiConfig, queue?: LogQueueRepository, timeoutMs?: number): void;
+/** Returns the active LokiClient, or null if telemetry was not initialized. */
+export declare function getLokiClient(): LokiClient | null;
+/** @internal — test use only */
+export declare function _resetLokiClient(): void;

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

@@ -0,0 +1,17 @@
+import { LokiClient } from "./loki_client";
+let _client = null;
+/**
+ * Low-level client initializer. Prefer `initTelemetry` from the telemetry index, which also
+ * wires the SQLite outbox and the flush cron. Use this directly only in tests.
+ */
+export function initLokiClient(config, queue, timeoutMs) {
+    _client = new LokiClient(config, queue, timeoutMs);
+}
+/** Returns the active LokiClient, or null if telemetry was not initialized. */
+export function getLokiClient() {
+    return _client;
+}
+/** @internal — test use only */
+export function _resetLokiClient() {
+    _client = null;
+}

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

@@ -0,0 +1,35 @@
+import type { ConnectivityState } from "./connectivity_state";
+import type { FlushTelemetry } from "./flush_telemetry";
+import type { TelemetrySignal } from "./telemetry_signal";
+/** Default background-flush interval (minutes). ≥15 → real OS background task. */
+export declare const DEFAULT_BACKGROUND_INTERVAL_MIN = 15;
+export interface FlushWorkerOptions {
+    /** Background cron interval in minutes (≥15 → OS background task). 0 disables it. */
+    backgroundIntervalMin?: number;
+    /** Subscribe to InternetIsUp/Down events when the host app emits them. */
+    onConnectivityEvents?: boolean;
+}
+/**
+ * Orchestrates telemetry delivery from three independent triggers, all funneling
+ * into the same {@link FlushTelemetry} use case — none of them required:
+ *
+ *  1. Production signal (intrinsic, always on): producing telemetry schedules a
+ *     debounced flush. This is the primary path and needs no cron or events.
+ *  2. Connectivity events (opt-in): if the host app emits InternetIsUp/Down,
+ *     reconnecting triggers an immediate backlog drain.
+ *  3. Background cron (opt-in): a long-interval OS background task probes and
+ *     drains, as a safety net for whatever the other two missed.
+ *
+ * The framework never *depends* on the connectivity cron or the event bus.
+ */
+export declare class TelemetryFlushWorker {
+    private readonly flush;
+    private readonly signal;
+    private readonly connectivity;
+    private readonly opts;
+    private cron;
+    private unsubscribe;
+    constructor(flush: FlushTelemetry, signal: TelemetrySignal, connectivity: ConnectivityState, opts?: FlushWorkerOptions);
+    start(): void;
+    stop(): Promise<void>;
+}

package/dist/infrastructure/telemetry/telemetry_flush_worker.js

@@ -0,0 +1,66 @@
+import { InternetIsDownEvent, InternetIsUpEvent, } from "../../domain/connectivity/events";
+import { EBuiltinCron } from "../../entrypoints/cron/EBuiltinCron";
+import { UIEventBus } from "../../infrastructure/ui/UIEventBus";
+import { CronWorker } from "../../infrastructure/workers";
+/** Default background-flush interval (minutes). ≥15 → real OS background task. */
+export const DEFAULT_BACKGROUND_INTERVAL_MIN = 15;
+/**
+ * Orchestrates telemetry delivery from three independent triggers, all funneling
+ * into the same {@link FlushTelemetry} use case — none of them required:
+ *
+ *  1. Production signal (intrinsic, always on): producing telemetry schedules a
+ *     debounced flush. This is the primary path and needs no cron or events.
+ *  2. Connectivity events (opt-in): if the host app emits InternetIsUp/Down,
+ *     reconnecting triggers an immediate backlog drain.
+ *  3. Background cron (opt-in): a long-interval OS background task probes and
+ *     drains, as a safety net for whatever the other two missed.
+ *
+ * The framework never *depends* on the connectivity cron or the event bus.
+ */
+export class TelemetryFlushWorker {
+    flush;
+    signal;
+    connectivity;
+    opts;
+    cron = null;
+    unsubscribe = null;
+    constructor(flush, signal, connectivity, opts = {}) {
+        this.flush = flush;
+        this.signal = signal;
+        this.connectivity = connectivity;
+        this.opts = opts;
+    }
+    start() {
+        // Trigger 2 — reconnect events (opt-in). Up → drain now (reset backoff);
+        // Down → mark offline (informational; delivery still self-recovers via backoff).
+        if (this.opts.onConnectivityEvents) {
+            const offUp = UIEventBus.on(InternetIsUpEvent.name, () => {
+                this.connectivity.markOnline();
+                this.flush.run({ resetBackoff: true }).catch(() => { });
+            });
+            const offDown = UIEventBus.on(InternetIsDownEvent.name, () => {
+                this.connectivity.markOffline();
+            });
+            this.unsubscribe = () => {
+                offUp();
+                offDown();
+            };
+        }
+        // Trigger 3 — background safety net (opt-in). Resets backoff so a long
+        // offline backlog drains promptly when the OS runs the task.
+        const intervalMin = this.opts.backgroundIntervalMin ?? DEFAULT_BACKGROUND_INTERVAL_MIN;
+        if (intervalMin > 0) {
+            this.cron = new CronWorker(EBuiltinCron.TELEMETRY_FLUSH, () => this.flush.run({ resetBackoff: true }), intervalMin);
+            this.cron.start().catch(() => { });
+        }
+    }
+    async stop() {
+        this.signal.dispose();
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        if (this.cron) {
+            await this.cron.unregister().catch(() => { });
+            this.cron = null;
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+/** Default coalescing window for production-triggered flushes. */
+export declare const DEFAULT_SIGNAL_DEBOUNCE_MS = 3000;
+/**
+ * In-memory, debounced trigger. Telemetry is produced far faster than it should
+ * be shipped, so a burst of `notify()` calls collapses into a single `onFlush`
+ * after a quiet window. This is the production trigger — intrinsic to producing
+ * telemetry, with no dependency on crons or the event bus.
+ */
+export declare class TelemetrySignal {
+    private readonly onFlush;
+    private readonly debounceMs;
+    private timer;
+    constructor(onFlush: () => void, debounceMs?: number);
+    /** Schedules a single flush; further calls within the window are coalesced. */
+    notify(): void;
+    /** Cancels a pending flush (used on teardown / re-init). */
+    dispose(): void;
+}

package/dist/infrastructure/telemetry/telemetry_signal.js

@@ -0,0 +1,33 @@
+/** Default coalescing window for production-triggered flushes. */
+export const DEFAULT_SIGNAL_DEBOUNCE_MS = 3000;
+/**
+ * In-memory, debounced trigger. Telemetry is produced far faster than it should
+ * be shipped, so a burst of `notify()` calls collapses into a single `onFlush`
+ * after a quiet window. This is the production trigger — intrinsic to producing
+ * telemetry, with no dependency on crons or the event bus.
+ */
+export class TelemetrySignal {
+    onFlush;
+    debounceMs;
+    timer = null;
+    constructor(onFlush, debounceMs = DEFAULT_SIGNAL_DEBOUNCE_MS) {
+        this.onFlush = onFlush;
+        this.debounceMs = debounceMs;
+    }
+    /** Schedules a single flush; further calls within the window are coalesced. */
+    notify() {
+        if (this.timer)
+            return; // a flush is already scheduled — coalesce
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.onFlush();
+        }, this.debounceMs);
+    }
+    /** Cancels a pending flush (used on teardown / re-init). */
+    dispose() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}

package/dist/infrastructure/telemetry/tracing/active_span.d.ts

@@ -0,0 +1,22 @@
+import type { SpanContext } from "@opentelemetry/api";
+/**
+ * Returns the SpanContext (traceId + spanId + traceFlags) of the span
+ * currently active in the framework context, or null if no span is active.
+ *
+ * Use this to correlate logs with traces — inject traceId/spanId into log
+ * lines so Grafana can link from Loki to Tempo automatically.
+ *
+ * @example
+ * const span = getActiveSpanContext();
+ * logger.info(`payment processed trace_id=${span?.traceId ?? "-"}`);
+ */
+export declare function getActiveSpanContext(): SpanContext | null;
+/**
+ * Formats the active trace context as a log suffix ready to append to any
+ * log line. Returns an empty string when no span is active so callers don't
+ * need to branch.
+ *
+ * Output: " trace_id=<id> span_id=<id>"
+ * Grafana Derived Fields can extract these and link to Tempo automatically.
+ */
+export declare function activeTraceLabel(): string;

package/dist/infrastructure/telemetry/tracing/active_span.js

@@ -0,0 +1,40 @@
+import { trace } from "@opentelemetry/api";
+import { _getContextManager } from "../../context_manager/index";
+import { OTEL_CTX_KEY } from "../context_keys";
+/**
+ * Returns the SpanContext (traceId + spanId + traceFlags) of the span
+ * currently active in the framework context, or null if no span is active.
+ *
+ * Use this to correlate logs with traces — inject traceId/spanId into log
+ * lines so Grafana can link from Loki to Tempo automatically.
+ *
+ * @example
+ * const span = getActiveSpanContext();
+ * logger.info(`payment processed trace_id=${span?.traceId ?? "-"}`);
+ */
+export function getActiveSpanContext() {
+    const otelCtx = _getContextManager().active().get(OTEL_CTX_KEY);
+    if (!otelCtx)
+        return null;
+    const span = trace.getSpan(otelCtx);
+    if (!span)
+        return null;
+    const ctx = span.spanContext();
+    // A NonRecordingSpan has a valid-looking spanContext but isRemote/sampled may
+    // differ. We only return it if the span is actually recording (sampled).
+    return span.isRecording() ? ctx : null;
+}
+/**
+ * Formats the active trace context as a log suffix ready to append to any
+ * log line. Returns an empty string when no span is active so callers don't
+ * need to branch.
+ *
+ * Output: " trace_id=<id> span_id=<id>"
+ * Grafana Derived Fields can extract these and link to Tempo automatically.
+ */
+export function activeTraceLabel() {
+    const ctx = getActiveSpanContext();
+    if (!ctx)
+        return "";
+    return ` trace_id=${ctx.traceId} span_id=${ctx.spanId}`;
+}

package/dist/infrastructure/telemetry/tracing/otlp_client.d.ts

@@ -0,0 +1,13 @@
+import type { OtlpConfig } from "../types";
+import type { SpanRow } from "./span_queue_repository";
+/**
+ * Sends a batch of spans to an OTLP/HTTP collector (Grafana Alloy, Jaeger, etc.).
+ * Throws on non-2xx so the caller (span_flush_job) can apply backoff.
+ */
+export declare class OtlpClient {
+    private readonly config;
+    private readonly timeoutMs;
+    constructor(config: OtlpConfig, timeoutMs?: number);
+    deliver(spans: SpanRow[]): Promise<void>;
+    private requestHeaders;
+}

package/dist/infrastructure/telemetry/tracing/otlp_client.js

@@ -0,0 +1,34 @@
+import { DEFAULT_SEND_TIMEOUT_MS, fetchWithTimeout } from "../fetch_with_timeout";
+import { serializeToOtlp } from "./otlp_serializer";
+/**
+ * Sends a batch of spans to an OTLP/HTTP collector (Grafana Alloy, Jaeger, etc.).
+ * Throws on non-2xx so the caller (span_flush_job) can apply backoff.
+ */
+export class OtlpClient {
+    config;
+    timeoutMs;
+    constructor(config, timeoutMs = DEFAULT_SEND_TIMEOUT_MS) {
+        this.config = config;
+        this.timeoutMs = timeoutMs;
+    }
+    async deliver(spans) {
+        if (spans.length === 0)
+            return;
+        const body = JSON.stringify(serializeToOtlp(spans));
+        const url = `${this.config.endpoint.replace(/\/$/, "")}/v1/traces`;
+        const res = await fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.requestHeaders(),
+            body,
+        }, this.timeoutMs);
+        if (!res.ok) {
+            throw new Error(`OTLP collector responded ${res.status}`);
+        }
+    }
+    requestHeaders() {
+        const custom = this.config.headers ?? {};
+        // Strip any content-type the caller may have set — JSON is always required for OTLP/HTTP.
+        const stripped = Object.fromEntries(Object.entries(custom).filter(([k]) => k.toLowerCase() !== "content-type"));
+        return { ...stripped, "Content-Type": "application/json" };
+    }
+}

package/dist/infrastructure/telemetry/tracing/otlp_serializer.d.ts

@@ -0,0 +1,67 @@
+import type { SpanRow } from "./span_queue_repository";
+type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+};
+interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+interface OtlpEvent {
+    name: string;
+    timeUnixNano: string;
+    attributes: OtlpKeyValue[];
+}
+interface OtlpLink {
+    traceId: string;
+    spanId: string;
+    attributes: OtlpKeyValue[];
+}
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    events: OtlpEvent[];
+    links: OtlpLink[];
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+interface OtlpScopeSpans {
+    scope: {
+        name: string;
+    };
+    spans: OtlpSpan[];
+}
+interface OtlpResourceSpans {
+    resource: {
+        attributes: OtlpKeyValue[];
+    };
+    scopeSpans: OtlpScopeSpans[];
+}
+export interface OtlpExportRequest {
+    resourceSpans: OtlpResourceSpans[];
+}
+/**
+ * Converts a batch of SpanRows (from SQLite) into an OTLP/HTTP JSON payload.
+ *
+ * Grouping strategy: spans sharing the same `resource_attrs` JSON are placed
+ * under the same ResourceSpans entry. All spans are placed under a single
+ * scope named "@sincpro/mobile".
+ *
+ * traceId and spanId are hex strings — OTLP/JSON uses hex (not base64).
+ * Timestamps are nanosecond strings — already stored that way in SQLite.
+ */
+export declare function serializeToOtlp(spans: SpanRow[]): OtlpExportRequest;
+export {};