@sincpro/mobile 0.3.1 → 0.4.2

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

@@ -0,0 +1,101 @@
+function encodeValue(v) {
+    if (typeof v === "string")
+        return { stringValue: v };
+    // intValue is a string in OTLP/JSON (uint64 can exceed JS Number precision)
+    if (typeof v === "number" && Number.isInteger(v))
+        return { intValue: String(v) };
+    if (typeof v === "number")
+        return { doubleValue: v };
+    if (typeof v === "boolean")
+        return { boolValue: v };
+    return { stringValue: String(v) };
+}
+function encodeAttrs(json) {
+    try {
+        const obj = JSON.parse(json);
+        return Object.entries(obj).map(([key, value]) => ({ key, value: encodeValue(value) }));
+    }
+    catch {
+        return [];
+    }
+}
+function parseEvents(json) {
+    try {
+        const raw = JSON.parse(json);
+        return raw.map((e) => ({
+            name: e.name,
+            timeUnixNano: e.timeUnixNano,
+            attributes: Object.entries(e.attributes ?? {}).map(([key, value]) => ({
+                key,
+                value: encodeValue(value),
+            })),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function parseLinks(json) {
+    try {
+        const raw = JSON.parse(json);
+        return raw.map((l) => ({
+            traceId: l.traceId,
+            spanId: l.spanId,
+            attributes: Object.entries(l.attributes ?? {}).map(([key, value]) => ({
+                key,
+                value: encodeValue(value),
+            })),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Serializer
+// ---------------------------------------------------------------------------
+/**
+ * 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 function serializeToOtlp(spans) {
+    // Group by resource_attrs to minimize payload size
+    const byResource = new Map();
+    for (const span of spans) {
+        const key = span.resource_attrs;
+        const group = byResource.get(key) ?? [];
+        group.push(span);
+        byResource.set(key, group);
+    }
+    const resourceSpans = [];
+    for (const [resourceJson, group] of byResource) {
+        const otlpSpans = group.map((s) => {
+            const span = {
+                traceId: s.trace_id,
+                spanId: s.span_id,
+                name: s.name,
+                kind: s.kind,
+                startTimeUnixNano: s.start_time_unixnano,
+                endTimeUnixNano: s.end_time_unixnano,
+                attributes: encodeAttrs(s.attributes),
+                events: parseEvents(s.events ?? "[]"),
+                links: parseLinks(s.links ?? "[]"),
+                status: { code: s.status_code, message: s.status_message || undefined },
+            };
+            if (s.parent_span_id)
+                span.parentSpanId = s.parent_span_id;
+            return span;
+        });
+        resourceSpans.push({
+            resource: { attributes: encodeAttrs(resourceJson) },
+            scopeSpans: [{ scope: { name: "@sincpro/mobile" }, spans: otlpSpans }],
+        });
+    }
+    return { resourceSpans };
+}

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

@@ -0,0 +1,25 @@
+import type { FlushResult } from "../logging/flush_job";
+import type { SpanRow } from "./span_queue_repository";
+export declare const SPAN_FLUSH_BATCH_SIZE = 100;
+export declare const SPAN_MAX_BATCHES_PER_TICK = 5;
+export interface SpanFlushJobState {
+    consecutiveFailures: number;
+    skipTicksRemaining: number;
+}
+export declare function createSpanFlushJobState(): SpanFlushJobState;
+export interface SpanFlushClient {
+    deliver(spans: SpanRow[]): Promise<void>;
+}
+export interface SpanFlushQueue {
+    pruneExpired(): Promise<void>;
+    findPending(limit: number): Promise<SpanRow[]>;
+    removeMany(ids: number[]): Promise<void>;
+}
+/**
+ * One tick of the span flush cron.
+ *
+ * Mirrors runLogFlushJob (logs) — same at-least-once guarantee:
+ * deliver() always precedes removeMany(). A span delivered twice to the
+ * collector is preferable to a span never delivered.
+ */
+export declare function runSpanFlushJob(client: SpanFlushClient, queue: SpanFlushQueue, state: SpanFlushJobState): Promise<FlushResult>;

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

@@ -0,0 +1,42 @@
+export const SPAN_FLUSH_BATCH_SIZE = 100;
+export const SPAN_MAX_BATCHES_PER_TICK = 5;
+const MAX_SKIP_TICKS = 32;
+export function createSpanFlushJobState() {
+    return { consecutiveFailures: 0, skipTicksRemaining: 0 };
+}
+/**
+ * One tick of the span flush cron.
+ *
+ * Mirrors runLogFlushJob (logs) — same at-least-once guarantee:
+ * deliver() always precedes removeMany(). A span delivered twice to the
+ * collector is preferable to a span never delivered.
+ */
+export async function runSpanFlushJob(client, queue, state) {
+    if (state.skipTicksRemaining > 0) {
+        state.skipTicksRemaining -= 1;
+        return { delivered: 0, failed: false };
+    }
+    await queue.pruneExpired();
+    let batchesDelivered = 0;
+    while (batchesDelivered < SPAN_MAX_BATCHES_PER_TICK) {
+        const spans = await queue.findPending(SPAN_FLUSH_BATCH_SIZE);
+        if (spans.length === 0)
+            break;
+        try {
+            await client.deliver(spans);
+        }
+        catch {
+            state.consecutiveFailures += 1;
+            state.skipTicksRemaining = Math.min(Math.pow(2, state.consecutiveFailures - 1), MAX_SKIP_TICKS);
+            return { delivered: batchesDelivered, failed: true };
+        }
+        await queue.removeMany(spans.map((s) => s.id));
+        batchesDelivered += 1;
+        if (spans.length < SPAN_FLUSH_BATCH_SIZE)
+            break;
+    }
+    if (batchesDelivered > 0) {
+        state.consecutiveFailures = 0;
+    }
+    return { delivered: batchesDelivered, failed: false };
+}

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

@@ -0,0 +1,82 @@
+import type { DBCursor } from "../../../infrastructure/database";
+import type { BufferStats } from "../types";
+import type { SpanSampler } from "./span_sampler";
+export interface SpanRow {
+    id: number;
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    kind: number;
+    start_time_unixnano: string;
+    end_time_unixnano: string;
+    attributes: string;
+    status_code: number;
+    status_message: string;
+    resource_attrs: string;
+    /** JSON array of {name, timeUnixNano, attributes} — from span.recordException() etc. */
+    events: string;
+    /** JSON array of {traceId, spanId, attributes} — cross-service links. */
+    links: string;
+    created_at: string;
+}
+export type SpanInput = Omit<SpanRow, "id" | "created_at">;
+/** Max rows kept in spans_queue before eviction kicks in. */
+export declare const MAX_SPANS_QUEUE_SIZE = 5000;
+/** Max approximate payload bytes kept in spans_queue (~6 MB). */
+export declare const MAX_SPANS_QUEUE_BYTES = 6000000;
+/** Run the (scanning) eviction check once every N enqueues — see class doc. */
+export declare const EVICT_CHECK_EVERY = 32;
+/** Fraction of either budget above which head sampling activates. */
+export declare const PRESSURE_FRACTION = 0.8;
+/**
+ * Offline-first span buffer with **trace-coherent** eviction.
+ *
+ * Spans are bounded by BOTH a row count and a payload-byte budget. When either
+ * is exceeded the OLDEST WHOLE TRACE is dropped — never individual spans —
+ * so survivors are always complete, usable traces. Dropping spans by row (FIFO)
+ * would evict root/parent spans first and leave orphaned children that render
+ * as broken traces downstream.
+ *
+ * The budget check scans the table (COUNT + SUM of lengths), so it runs
+ * **amortized** — once every `evictEvery` enqueues — to keep the hot path cheap
+ * under offline bursts. The bound is therefore soft: the queue may transiently
+ * exceed the cap by up to `evictEvery` rows before the next trim.
+ *
+ * When a {@link SpanSampler} is supplied, head sampling kicks in once the buffer
+ * passes {@link PRESSURE_FRACTION} of either budget: whole traces are dropped at
+ * ingest (coherently) so the buffer stops thrashing instead of inserting spans
+ * it would immediately evict. Pressure is read from the last amortized
+ * measurement — no extra scan on the hot path.
+ *
+ * Telemetry is best-effort: under sustained offline pressure data IS dropped,
+ * but coherently and visibly (see {@link stats}).
+ */
+export declare class SpanQueueRepository {
+    private readonly db;
+    private readonly maxRows;
+    private readonly maxBytes;
+    private readonly evictEvery;
+    private readonly sampler;
+    private ops;
+    private dropped;
+    private sampledOut;
+    private lastRows;
+    private lastBytes;
+    private measuredOnce;
+    constructor(db: typeof DBCursor, maxRows?: number, maxBytes?: number, evictEvery?: number, sampler?: SpanSampler | null);
+    enqueue(span: SpanInput): Promise<void>;
+    /** Cheap pressure check from the last amortized measurement (no scan). */
+    private underPressure;
+    /**
+     * Drops the oldest whole traces until both row and byte budgets are met.
+     * Terminates: each pass either returns (under budget / empty) or removes ≥1
+     * row, and the row count strictly decreases.
+     */
+    private evict;
+    private measure;
+    stats(): Promise<BufferStats>;
+    findPending(limit?: number): Promise<SpanRow[]>;
+    removeMany(ids: number[]): Promise<void>;
+    pruneExpired(days?: number): Promise<void>;
+}

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

@@ -0,0 +1,134 @@
+/** Max rows kept in spans_queue before eviction kicks in. */
+export const MAX_SPANS_QUEUE_SIZE = 5_000;
+/** Max approximate payload bytes kept in spans_queue (~6 MB). */
+export const MAX_SPANS_QUEUE_BYTES = 6_000_000;
+/** Run the (scanning) eviction check once every N enqueues — see class doc. */
+export const EVICT_CHECK_EVERY = 32;
+/** Fraction of either budget above which head sampling activates. */
+export const PRESSURE_FRACTION = 0.8;
+/**
+ * Offline-first span buffer with **trace-coherent** eviction.
+ *
+ * Spans are bounded by BOTH a row count and a payload-byte budget. When either
+ * is exceeded the OLDEST WHOLE TRACE is dropped — never individual spans —
+ * so survivors are always complete, usable traces. Dropping spans by row (FIFO)
+ * would evict root/parent spans first and leave orphaned children that render
+ * as broken traces downstream.
+ *
+ * The budget check scans the table (COUNT + SUM of lengths), so it runs
+ * **amortized** — once every `evictEvery` enqueues — to keep the hot path cheap
+ * under offline bursts. The bound is therefore soft: the queue may transiently
+ * exceed the cap by up to `evictEvery` rows before the next trim.
+ *
+ * When a {@link SpanSampler} is supplied, head sampling kicks in once the buffer
+ * passes {@link PRESSURE_FRACTION} of either budget: whole traces are dropped at
+ * ingest (coherently) so the buffer stops thrashing instead of inserting spans
+ * it would immediately evict. Pressure is read from the last amortized
+ * measurement — no extra scan on the hot path.
+ *
+ * Telemetry is best-effort: under sustained offline pressure data IS dropped,
+ * but coherently and visibly (see {@link stats}).
+ */
+export class SpanQueueRepository {
+    db;
+    maxRows;
+    maxBytes;
+    evictEvery;
+    sampler;
+    ops = 0;
+    dropped = 0;
+    sampledOut = 0;
+    // Last measured size — drives the cheap pressure check on the hot path.
+    lastRows = 0;
+    lastBytes = 0;
+    // Whether the buffer size has been measured at least once (cold-start guard).
+    measuredOnce = false;
+    constructor(db, maxRows = MAX_SPANS_QUEUE_SIZE, maxBytes = MAX_SPANS_QUEUE_BYTES, evictEvery = EVICT_CHECK_EVERY, sampler = null) {
+        this.db = db;
+        this.maxRows = maxRows;
+        this.maxBytes = maxBytes;
+        this.evictEvery = Math.max(1, evictEvery);
+        this.sampler = sampler;
+    }
+    async enqueue(span) {
+        // Head sampling — drop whole traces at ingest while under pressure, so we
+        // don't insert spans only to evict them moments later. Coherent per trace.
+        if (this.sampler) {
+            // Cold-start guard: measure once before the first sampling decision so a
+            // buffer that booted already-full (SQLite persists) is seen as pressured.
+            if (!this.measuredOnce)
+                await this.measure();
+            if (!this.sampler.shouldKeep(span.trace_id, this.underPressure())) {
+                this.sampledOut += 1;
+                return;
+            }
+        }
+        await this.db.mutateDatabase(`INSERT INTO spans_queue
+        (trace_id, span_id, parent_span_id, name, kind,
+         start_time_unixnano, end_time_unixnano,
+         attributes, status_code, status_message, resource_attrs,
+         events, links)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, span.trace_id, span.span_id, span.parent_span_id, span.name, span.kind, span.start_time_unixnano, span.end_time_unixnano, span.attributes, span.status_code, span.status_message, span.resource_attrs, span.events, span.links);
+        if (++this.ops >= this.evictEvery) {
+            this.ops = 0;
+            await this.evict();
+        }
+    }
+    /** Cheap pressure check from the last amortized measurement (no scan). */
+    underPressure() {
+        return (this.lastRows >= this.maxRows * PRESSURE_FRACTION ||
+            this.lastBytes >= this.maxBytes * PRESSURE_FRACTION);
+    }
+    /**
+     * Drops the oldest whole traces until both row and byte budgets are met.
+     * Terminates: each pass either returns (under budget / empty) or removes ≥1
+     * row, and the row count strictly decreases.
+     */
+    async evict() {
+        for (;;) {
+            const { rows, approxBytes } = await this.measure();
+            if (rows <= this.maxRows && approxBytes <= this.maxBytes)
+                return;
+            const res = await this.db.mutateDatabase(`DELETE FROM spans_queue WHERE trace_id = (
+           SELECT trace_id FROM spans_queue GROUP BY trace_id ORDER BY MIN(id) ASC LIMIT 1
+         )`);
+            const removed = res?.changes ?? 0;
+            if (removed === 0)
+                return; // queue empty — nothing left to evict
+            this.dropped += removed;
+        }
+    }
+    async measure() {
+        const row = await this.db.getFirstAsync(`SELECT COUNT(*) AS rows,
+        COALESCE(SUM(
+          length(trace_id) + length(span_id) + length(COALESCE(parent_span_id, ''))
+          + length(name) + length(start_time_unixnano) + length(end_time_unixnano)
+          + length(attributes) + length(status_message) + length(resource_attrs)
+          + length(events) + length(links)
+        ), 0) AS bytes
+       FROM spans_queue`);
+        const rows = row?.rows ?? 0;
+        const approxBytes = row?.bytes ?? 0;
+        // Cache for the hot-path pressure check.
+        this.lastRows = rows;
+        this.lastBytes = approxBytes;
+        this.measuredOnce = true;
+        return { rows, approxBytes };
+    }
+    async stats() {
+        const { rows, approxBytes } = await this.measure();
+        return { rows, approxBytes, dropped: this.dropped, sampled: this.sampledOut };
+    }
+    async findPending(limit = 100) {
+        return this.db.getAllAsync(`SELECT * FROM spans_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 spans_queue WHERE id IN (${placeholders})`, ...ids);
+    }
+    async pruneExpired(days = 7) {
+        await this.db.mutateDatabase(`DELETE FROM spans_queue WHERE created_at < datetime('now', ?)`, `-${days} days`);
+    }
+}

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

@@ -0,0 +1,40 @@
+/** Keep 1 of every N traces while under pressure (default). */
+export declare const DEFAULT_KEEP_ONE_IN_N = 4;
+/** Bounded size of the per-trace decision cache. */
+export declare const DEFAULT_DECISION_CACHE_SIZE = 2000;
+/**
+ * Head sampler for spans, applied at ingest under sustained buffer pressure.
+ *
+ * The decision is **per trace and coherent**: every span sharing a `traceId`
+ * gets the same keep/drop verdict, even if buffer pressure changes between the
+ * arrival of one span and the next. This is what prevents partial/orphaned
+ * traces — the failure mode that makes a trace backend show broken graphs.
+ *
+ * Coherence is achieved two ways:
+ *  - the keep verdict for a new trace is a deterministic hash of its id
+ *    (no RNG), so the same id always hashes the same bucket; and
+ *  - the first verdict for a trace is cached, so a mid-trace pressure flip can
+ *    never change an already-made decision.
+ *
+ * When NOT under pressure every trace is kept. The cache is bounded (oldest
+ * decision evicted first). The cache is **LRU**: reading a trace's verdict
+ * refreshes it, so a trace still actively receiving spans keeps its decision
+ * resident and cannot be split by eviction. Only a trace idle long enough to
+ * fall out of the cache *and* hitting a pressure change can be re-decided —
+ * acceptable for best-effort telemetry.
+ */
+export declare class SpanSampler {
+    private readonly keepOneInN;
+    private readonly cacheSize;
+    private readonly decisions;
+    constructor(keepOneInN?: number, cacheSize?: number);
+    /**
+     * Returns whether the span belonging to `traceId` should be buffered.
+     * @param underPressure - true when the buffer is near its budget; only then
+     *   does sampling drop anything.
+     */
+    shouldKeep(traceId: string, underPressure: boolean): boolean;
+    /** Current number of cached trace decisions (for observability / tests). */
+    size(): number;
+    private remember;
+}

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

@@ -0,0 +1,75 @@
+/** Keep 1 of every N traces while under pressure (default). */
+export const DEFAULT_KEEP_ONE_IN_N = 4;
+/** Bounded size of the per-trace decision cache. */
+export const DEFAULT_DECISION_CACHE_SIZE = 2_000;
+/**
+ * Head sampler for spans, applied at ingest under sustained buffer pressure.
+ *
+ * The decision is **per trace and coherent**: every span sharing a `traceId`
+ * gets the same keep/drop verdict, even if buffer pressure changes between the
+ * arrival of one span and the next. This is what prevents partial/orphaned
+ * traces — the failure mode that makes a trace backend show broken graphs.
+ *
+ * Coherence is achieved two ways:
+ *  - the keep verdict for a new trace is a deterministic hash of its id
+ *    (no RNG), so the same id always hashes the same bucket; and
+ *  - the first verdict for a trace is cached, so a mid-trace pressure flip can
+ *    never change an already-made decision.
+ *
+ * When NOT under pressure every trace is kept. The cache is bounded (oldest
+ * decision evicted first). The cache is **LRU**: reading a trace's verdict
+ * refreshes it, so a trace still actively receiving spans keeps its decision
+ * resident and cannot be split by eviction. Only a trace idle long enough to
+ * fall out of the cache *and* hitting a pressure change can be re-decided —
+ * acceptable for best-effort telemetry.
+ */
+export class SpanSampler {
+    keepOneInN;
+    cacheSize;
+    // insertion-ordered Map used as an LRU: most-recently-used key sits last.
+    decisions = new Map();
+    constructor(keepOneInN = DEFAULT_KEEP_ONE_IN_N, cacheSize = DEFAULT_DECISION_CACHE_SIZE) {
+        this.keepOneInN = Math.max(1, keepOneInN);
+        this.cacheSize = Math.max(1, cacheSize);
+    }
+    /**
+     * Returns whether the span belonging to `traceId` should be buffered.
+     * @param underPressure - true when the buffer is near its budget; only then
+     *   does sampling drop anything.
+     */
+    shouldKeep(traceId, underPressure) {
+        const cached = this.decisions.get(traceId);
+        if (cached !== undefined) {
+            // Touch — move to MRU position so active traces are never evicted.
+            this.decisions.delete(traceId);
+            this.decisions.set(traceId, cached);
+            return cached;
+        }
+        // keepOneInN === 1 means "keep all" even under pressure.
+        const keep = !underPressure || this.keepOneInN === 1 || hash(traceId) % this.keepOneInN === 0;
+        this.remember(traceId, keep);
+        return keep;
+    }
+    /** Current number of cached trace decisions (for observability / tests). */
+    size() {
+        return this.decisions.size;
+    }
+    remember(traceId, keep) {
+        if (this.decisions.size >= this.cacheSize) {
+            // Evict the least-recently-used decision (first key in insertion order).
+            const lru = this.decisions.keys().next().value;
+            if (lru !== undefined)
+                this.decisions.delete(lru);
+        }
+        this.decisions.set(traceId, keep);
+    }
+}
+/** FNV-1a 32-bit — deterministic, fast, no allocations. */
+function hash(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0; // unsigned
+}

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

@@ -0,0 +1,48 @@
+import type { SpanInput } from "./span_queue_repository";
+/**
+ * OTel HrTime: [seconds: number, nanoseconds: number].
+ * BigInt required — seconds alone can be ~1.7e9, multiplied by 1e9 = 1.7e18,
+ * which exceeds Number.MAX_SAFE_INTEGER (~9e15).
+ */
+export declare function hrTimeToNanoString(hrTime: [number, number]): string;
+/**
+ * Minimal shape of OTel ReadableSpan needed for serialization.
+ * Using a local interface instead of importing from sdk-trace-base so this
+ * module stays importable in the Node test runner (OTel packages are CJS).
+ */
+export interface SerializableSpanEvent {
+    name: string;
+    time: [number, number];
+    attributes?: Record<string, unknown>;
+}
+export interface SerializableSpanLink {
+    context: {
+        traceId: string;
+        spanId: string;
+    };
+    attributes?: Record<string, unknown>;
+}
+export interface SerializableSpan {
+    name: string;
+    kind: number;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+    parentSpanContext?: {
+        spanId: string;
+    } | undefined;
+    startTime: [number, number];
+    endTime: [number, number];
+    attributes: Record<string, unknown>;
+    status: {
+        code: number;
+        message?: string;
+    };
+    resource?: {
+        attributes: Record<string, unknown>;
+    };
+    events?: SerializableSpanEvent[];
+    links?: SerializableSpanLink[];
+}
+export declare function serializeSpan(span: SerializableSpan): SpanInput;

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

@@ -0,0 +1,36 @@
+/**
+ * OTel HrTime: [seconds: number, nanoseconds: number].
+ * BigInt required — seconds alone can be ~1.7e9, multiplied by 1e9 = 1.7e18,
+ * which exceeds Number.MAX_SAFE_INTEGER (~9e15).
+ */
+export function hrTimeToNanoString(hrTime) {
+    return String(BigInt(hrTime[0]) * 1000000000n + BigInt(hrTime[1]));
+}
+export function serializeSpan(span) {
+    const ctx = span.spanContext();
+    const events = (span.events ?? []).map((e) => ({
+        name: e.name,
+        timeUnixNano: hrTimeToNanoString(e.time),
+        attributes: e.attributes ?? {},
+    }));
+    const links = (span.links ?? []).map((l) => ({
+        traceId: l.context.traceId,
+        spanId: l.context.spanId,
+        attributes: l.attributes ?? {},
+    }));
+    return {
+        trace_id: ctx.traceId,
+        span_id: ctx.spanId,
+        parent_span_id: span.parentSpanContext?.spanId ?? null,
+        name: span.name,
+        kind: span.kind,
+        start_time_unixnano: hrTimeToNanoString(span.startTime),
+        end_time_unixnano: hrTimeToNanoString(span.endTime),
+        attributes: JSON.stringify(span.attributes ?? {}),
+        status_code: span.status.code,
+        status_message: span.status.message ?? "",
+        resource_attrs: JSON.stringify(span.resource?.attributes ?? {}),
+        events: JSON.stringify(events),
+        links: JSON.stringify(links),
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { ExportResult } from "@opentelemetry/core";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import type { SpanQueueRepository } from "./span_queue_repository";
+/**
+ * OTel SpanExporter that persists spans to SQLite instead of sending them
+ * directly over the network. The flush cron drains the queue when online.
+ *
+ * Pass `enabled: false` to register the provider without storing anything —
+ * useful when tracing is initialized but no OTLP destination is configured yet.
+ *
+ * Fire-and-forget: export() never blocks the instrumented code path.
+ * Failures are swallowed — a span dropped from the queue is preferable to
+ * crashing the application.
+ */
+export declare class SQLiteSpanExporter implements SpanExporter {
+    private readonly queue;
+    private readonly enabled;
+    private readonly onEnqueued?;
+    /**
+     * @param onEnqueued - called after spans are persisted, so the pipeline can
+     *   opportunistically attempt delivery (store-first, then try to send).
+     */
+    constructor(queue: SpanQueueRepository, enabled?: boolean, onEnqueued?: () => void);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}

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

@@ -0,0 +1,47 @@
+import { ExportResultCode } from "@opentelemetry/core";
+import { serializeSpan } from "./span_serializer";
+/**
+ * OTel SpanExporter that persists spans to SQLite instead of sending them
+ * directly over the network. The flush cron drains the queue when online.
+ *
+ * Pass `enabled: false` to register the provider without storing anything —
+ * useful when tracing is initialized but no OTLP destination is configured yet.
+ *
+ * Fire-and-forget: export() never blocks the instrumented code path.
+ * Failures are swallowed — a span dropped from the queue is preferable to
+ * crashing the application.
+ */
+export class SQLiteSpanExporter {
+    queue;
+    enabled;
+    onEnqueued;
+    /**
+     * @param onEnqueued - called after spans are persisted, so the pipeline can
+     *   opportunistically attempt delivery (store-first, then try to send).
+     */
+    constructor(queue, enabled = true, onEnqueued) {
+        this.queue = queue;
+        this.enabled = enabled;
+        this.onEnqueued = onEnqueued;
+    }
+    export(spans, resultCallback) {
+        if (!this.enabled) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        const persist = async () => {
+            for (const span of spans) {
+                await this.queue.enqueue(serializeSpan(span));
+            }
+        };
+        persist()
+            .then(() => {
+            this.onEnqueued?.();
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        })
+            .catch(() => resultCallback({ code: ExportResultCode.FAILED }));
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}