@sincpro/mobile 0.3.1 → 0.4.1

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,65 @@
+import { InternetIsDownEvent, InternetIsUpEvent, } from "../../domain/connectivity/events";
+import { UIEventBus } from "../../infrastructure/ui/UIEventBus";
+import { CronWorker } from "../../infrastructure/workers/CronWorker";
+/** 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("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 {};

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