@sincpro/mobile 0.3.1 → 0.4.1

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

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

@@ -0,0 +1,22 @@
+import type { SpanQueueRepository } from "./span_queue_repository";
+export interface TracingResourceConfig {
+    serviceName?: string;
+    serviceVersion?: string;
+    deploymentEnvironment?: string;
+    /** Extra OTel resource attributes (device.*, os.*, tenant, …). */
+    extra?: Record<string, string>;
+}
+/**
+ * @param queue          - repository used by the exporter to buffer spans
+ * @param persist        - when false the TracerProvider is registered (decorators work)
+ *                         but spans are not written to SQLite; pass true only when an
+ *                         OTLP destination is configured and flush is active
+ * @param onEnqueued     - called after spans are buffered, so the pipeline can
+ *                         opportunistically attempt delivery (store-first)
+ * @param resourceConfig - OTel resource attributes; without `serviceName` spans appear
+ *                         as `unknown_service` in Grafana/Tempo
+ */
+export declare function initTracing(queue: SpanQueueRepository, persist?: boolean, onEnqueued?: () => void, resourceConfig?: TracingResourceConfig): void;
+/** @internal — test use only */
+export declare function _resetTracing(): void;
+export declare function getTracer(name: string): import("@opentelemetry/api").Tracer;

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

@@ -0,0 +1,45 @@
+import { trace } from "@opentelemetry/api";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { SQLiteSpanExporter } from "./sqlite_span_exporter";
+let _provider = null;
+/**
+ * @param queue          - repository used by the exporter to buffer spans
+ * @param persist        - when false the TracerProvider is registered (decorators work)
+ *                         but spans are not written to SQLite; pass true only when an
+ *                         OTLP destination is configured and flush is active
+ * @param onEnqueued     - called after spans are buffered, so the pipeline can
+ *                         opportunistically attempt delivery (store-first)
+ * @param resourceConfig - OTel resource attributes; without `serviceName` spans appear
+ *                         as `unknown_service` in Grafana/Tempo
+ */
+export function initTracing(queue, persist = true, onEnqueued, resourceConfig) {
+    _provider?.shutdown().catch(() => { });
+    const rawAttrs = {};
+    if (resourceConfig?.serviceName)
+        rawAttrs["service.name"] = resourceConfig.serviceName;
+    if (resourceConfig?.serviceVersion)
+        rawAttrs["service.version"] = resourceConfig.serviceVersion;
+    if (resourceConfig?.deploymentEnvironment)
+        rawAttrs["deployment.environment"] = resourceConfig.deploymentEnvironment;
+    if (resourceConfig?.extra)
+        Object.assign(rawAttrs, resourceConfig.extra);
+    const resource = Object.keys(rawAttrs).length > 0 ? resourceFromAttributes(rawAttrs) : undefined;
+    const provider = new BasicTracerProvider({
+        resource,
+        spanProcessors: [
+            new SimpleSpanProcessor(new SQLiteSpanExporter(queue, persist, onEnqueued)),
+        ],
+    });
+    trace.setGlobalTracerProvider(provider);
+    _provider = provider;
+}
+/** @internal — test use only */
+export function _resetTracing() {
+    _provider?.shutdown().catch(() => { });
+    _provider = null;
+    trace.disable();
+}
+export function getTracer(name) {
+    return trace.getTracer(name);
+}

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

@@ -0,0 +1,10 @@
+import type { InterceptorHooks } from "../../interceptor/intercept";
+/**
+ * Returns InterceptorHooks that record an OTel span for every intercepted
+ * method call. Parent-child relationships are maintained through the framework
+ * StackContextManager: the OTel context (with the active span) is stored as a
+ * value inside our Context, pushed in `before` and popped in `after`/`onError`.
+ *
+ * @param tracerName - instrumentation scope name, e.g. "sincpro.mobile.checkout"
+ */
+export declare function tracingHooks(tracerName: string): InterceptorHooks;

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

@@ -0,0 +1,59 @@
+import { ROOT_CONTEXT as OTEL_ROOT, SpanStatusCode, trace } from "@opentelemetry/api";
+import { _getContextManager } from "../../context_manager/index";
+import { OTEL_CTX_KEY } from "../context_keys";
+const _spanMap = new WeakMap();
+// Tracks whether `before` successfully pushed a context entry for this call.
+// Guards `after`/`onError` against popping a context they never pushed.
+const _pushedMap = new WeakSet();
+/**
+ * Returns InterceptorHooks that record an OTel span for every intercepted
+ * method call. Parent-child relationships are maintained through the framework
+ * StackContextManager: the OTel context (with the active span) is stored as a
+ * value inside our Context, pushed in `before` and popped in `after`/`onError`.
+ *
+ * @param tracerName - instrumentation scope name, e.g. "sincpro.mobile.checkout"
+ */
+export function tracingHooks(tracerName) {
+    return {
+        before(call) {
+            const manager = _getContextManager();
+            const frameworkCtx = manager.active();
+            // Read the OTel context carried inside our framework context.
+            // Falls back to OTel ROOT if tracing has not been initialized yet.
+            const otelCtx = frameworkCtx.get(OTEL_CTX_KEY) ?? OTEL_ROOT;
+            const spanName = call.className
+                ? `${call.className}.${call.methodName}`
+                : call.methodName;
+            const span = trace.getTracer(tracerName).startSpan(spanName, undefined, otelCtx);
+            _spanMap.set(call, span);
+            // Store the updated OTel context (now containing this span) back into
+            // the framework context and push it onto the stack so nested calls see
+            // this span as their parent.
+            const newOtelCtx = trace.setSpan(otelCtx, span);
+            manager.push(frameworkCtx.set(OTEL_CTX_KEY, newOtelCtx));
+            _pushedMap.add(call);
+        },
+        after(call) {
+            const span = _spanMap.get(call);
+            if (!span)
+                return;
+            _spanMap.delete(call);
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            if (_pushedMap.delete(call))
+                _getContextManager().pop();
+        },
+        onError(call, error) {
+            const span = _spanMap.get(call);
+            if (!span)
+                return;
+            _spanMap.delete(call);
+            if (error instanceof Error)
+                span.recordException(error);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message });
+            span.end();
+            if (_pushedMap.delete(call))
+                _getContextManager().pop();
+        },
+    };
+}