@sincpro/mobile 0.3.1 → 0.4.2

package/README.md

@@ -9,6 +9,8 @@ Enterprise mobile development has always been hard. Applications need to work wi
 **Sincpro maintains this.** The source is open and anyone can read it. What Sincpro provides is the commitment behind it: stable contracts, long-term API support, updates as platforms evolve, and people accountable for the behaviors your business depends on. This is not a project that gets abandoned. It is infrastructure for the new era of enterprise mobile development, and Sincpro intends to maintain it for the teams and clients that build on top of it.
 
 > **AI agent?** Read [`AGENTS.md`](AGENTS.md) first — ecosystem orientation, patterns, and traps. Known runtime issues live in [`docs/GOTCHAS.md`](docs/GOTCHAS.md).
+>
+> **Deep engineering docs** (component + sequence diagrams, design rationale) live in [`docs/`](docs/README.md): [core architecture](docs/architecture-core.md), [telemetry](docs/architecture-telemetry.md), and the [consumer app structure](docs/architecture-consumer.md). This README is the summary.
 
 ---
 
@@ -66,8 +68,9 @@ export default createAppShell({
 7. [Theme Configuration](#theme-configuration)
 8. [Brand Font Configuration](#brand-font-configuration)
 9. [Public API](#public-api)
-10. [Subpaths](#subpaths)
-11. [Development](#development)
+10. [Telemetry Architecture](#telemetry-architecture)
+11. [Subpaths](#subpaths)
+12. [Development](#development)
 
 ---
 
@@ -136,6 +139,56 @@ The framework is organized in strict layers with enforced one-way dependency flo
 - **Offline-First.** Every domain event is persisted to SQLite before it is processed. Events survive app restarts and process them on recovery.
 - **Strict layer boundaries.** A lower layer cannot import from a higher one. `mobile-ui` has no imports from `@sincpro/mobile`.
 
+### Base infrastructure — events, queues, repositories, orchestrator
+
+`createApp` configures the **Orchestrator**, which bootstraps the **Kernel** (the set of `DomainModule`s). Each module contributes subscribers, crons, repositories and migrations; the orchestrator wires them and starts the workers. Everything durable is a SQLite-backed queue drained by a worker — offline-first by construction.
+
+```mermaid
+flowchart TB
+    createApp["createApp(config)"] --> orch["Orchestrator<br/>configure · bootstrap"]
+    orch --> kernel["Kernel<br/>aggregates DomainModules"]
+
+    subgraph MODULES["DomainModule(s) — bounded contexts"]
+        mod["module.key / name<br/>subscribers() · crons()<br/>repositories() · migrations()"]
+    end
+    kernel --> mod
+
+    subgraph WORKERS["Background workers"]
+        qp["EventBus / QueueProcessor<br/>polls + dispatches, connectivity-gated"]
+        crons["CronWorker(s)<br/>cron.sync — setInterval &lt;15m / OS task ≥15m"]
+    end
+
+    subgraph STORE["SQLite (migrations on bootstrap)"]
+        ev[("event_queue")]
+        de[("domain_events")]
+        dlq[("dead_letter_queue")]
+        ddl[("domain_events_dead_letter")]
+        settings[("settings")]
+        tq[("telemetry_queue")]
+        sq[("spans_queue")]
+    end
+
+    subgraph REPOS["Repositories (adapters/ports)"]
+        repo["Entity & queue repositories<br/>DomainEventDeadLetterRepository · …"]
+    end
+
+    netcron["CHECK_NETWORK cron"] -->|emits| netev["InternetIsUp / Down<br/>(UIEventBus)"]
+    netev -.->|gates draining| qp
+
+    orch --> qp
+    orch --> crons
+    kernel -->|migrations| STORE
+    mod -->|subscribers| qp
+    mod -->|crons| crons
+    mod -->|repositories| repo
+
+    qp -->|read/ack| de
+    qp -->|on failure| ddl
+    repo --> de
+    repo --> dlq
+    entity["Domain Entity<br/>addDomainEvent()"] -->|persist before process| de
+```
+
 ---
 
 ## 🗂️ Ecosystem
@@ -368,6 +421,71 @@ const status = await networkUseCases.getNetworkStatus();
 
 The EventBus subscribes to `InternetIsDownEvent` / `InternetIsUpEvent` internally — when connectivity is lost it increases the poll interval, and when it is restored it resets to 800ms and drains any held events immediately.
 
+### ✅ Telemetry & Observability (OpenTelemetry + Loki)
+
+Distributed tracing and structured logs, **offline-first**, built on the OpenTelemetry SDK. Spans buffer to SQLite and ship to any OTLP/HTTP collector (Grafana Alloy, Tempo, Jaeger); logs ship to Loki. Telemetry is **opt-in** — pass a `telemetry` config to `createApp`.
+
+```tsx
+await createApp({
+  telemetry: {
+    loki: {
+      endpoint: "https://loki.acme.com",
+      labels: { app: "pos", env: "prod", tenant: "acme" },
+      // Standard auth shortcut…
+      auth: { type: "bearer", token: "…" },
+      // …or any custom gateway headers (merged after auth, win on conflict)
+      headers: { "sincpro-api-key": "…", "X-Scope-OrgID": "acme" },
+    },
+    otlp: {
+      endpoint: "https://alloy.acme.com",
+      headers: { Authorization: "Bearer …" },
+    },
+    flush: {
+      backgroundIntervalMin: 15, // 0 disables the background cron
+      onConnectivityEvents: true, // drain the backlog the moment the network returns
+      sendTimeoutMs: 4000, // fail fast instead of hanging while offline
+    },
+  },
+});
+```
+
+**One import, simple API.** The `Tracing` facade is the single entry point for custom instrumentation:
+
+```tsx
+import { Tracing } from "@sincpro/mobile/infrastructure/telemetry";
+
+// Manual span block — start/end/error handled for you
+await Tracing.withSpan("checkout.process", async (span) => {
+  span.setAttribute("order.id", order.id);
+  await processOrder(order);
+});
+
+// Or decorate — a span per invocation, parent context propagated automatically
+class CheckoutUseCase {
+  @Tracing.Trace()
+  async process(order: Order) {
+    /* … */
+  }
+}
+
+@Tracing.TraceClass("checkout") // a span per public method + context propagation
+class InventoryService {
+  /* … */
+}
+
+// Correlate your own logs with the active trace
+logger.info("charge attempt" + Tracing.logSuffix()); // → " trace_id=… span_id=…"
+
+// Inspect offline backlog pressure (health checks / dashboards)
+const stats = await Tracing.bufferStats();
+// { logs:  { rows, approxBytes, dropped, sampled },
+//   spans: { rows, approxBytes, dropped, sampled } }
+// dropped = evicted after buffering (back-pressure);
+// sampled = refused at ingest by head sampling (load shed, spans only)
+```
+
+See [Telemetry Architecture](#telemetry-architecture) for the delivery and retention design and the reasoning behind it.
+
 ### ✅ Bluetooth Printer Integration
 
 The printer port (`IPrinterDriver`) is defined by the framework; the concrete driver is registered by the app. The `PrinterService` wraps it with connection management, permission handling, and a grace-reconnect strategy.
@@ -816,6 +934,120 @@ Built-in COMMON module. Always registered automatically — do not pass it to `d
 
 ---
 
+## 📡 Telemetry Architecture
+
+This section documents how the telemetry pipeline is built and **why**. The design target is an enterprise device fleet that is frequently offline, must never block the UI thread, and must never lose business-critical data to observability.
+
+### Layering
+
+Telemetry depends on the context manager one-directionally; nothing in the context manager imports telemetry (no cycles).
+
+```
+@Trace / @TraceClass / withSpan          ← instrumentation surface (Tracing facade)
+        │  starts spans, sets parent via the OTel Context
+        ▼
+ContextManager (stack-based)             ← carries the active OTel context across calls
+        │  Hermes has no AsyncLocalStorage → an explicit push/pop stack
+        ▼
+OpenTelemetry SDK (BasicTracerProvider)
+        │  SimpleSpanProcessor → SQLiteSpanExporter
+        ▼
+SQLite buffers  (spans_queue, telemetry_queue)
+        │  drained by the single FlushTelemetry use case
+        ▼
+OTLP/HTTP collector  +  Loki
+```
+
+**Why a stack-based context manager.** Hermes (React Native's engine) has no `AsyncLocalStorage`, so the framework carries the active OpenTelemetry context in an explicit push/pop stack (`StackContextManager`). Spans created inside a `withSpan`/`@Trace` body see the enclosing span as their parent because the parent context sits on top of the stack. The trade-off — concurrent `Promise.all` branches share the top of stack — is documented and acceptable for the sequential flows mobile apps actually run.
+
+**Why we wrap OpenTelemetry instead of reinventing it.** Spans, context propagation and OTLP serialization are standards with sharp edges; the framework uses the official OTel SDK for all of it. The only custom piece is the `SQLiteSpanExporter` (an OTel `SpanExporter` that writes to SQLite instead of the network) plus a thin DX layer — the `Tracing` / `ContextManager` facades — so application developers get one import and a small, hard-to-misuse API.
+
+### Component diagram
+
+```mermaid
+flowchart TB
+    app["App code<br/>@Trace · @TraceClass · withSpan · logger"]
+
+    subgraph FACADE["Public facades (one import)"]
+        tracing["Tracing<br/>init · withSpan · Trace · TraceClass<br/>activeSpan · logSuffix · bufferStats"]
+        ctx["ContextManager<br/>StackContextManager · OTEL_CTX_KEY"]
+    end
+
+    subgraph SDK["OpenTelemetry SDK (Hermes-safe)"]
+        provider["BasicTracerProvider"]
+        proc["SimpleSpanProcessor"]
+        exporter["SQLiteSpanExporter<br/>(custom — writes to SQLite)"]
+    end
+
+    subgraph BUFFERS["Offline buffers (SQLite)"]
+        spanRepo["SpanQueueRepository<br/>+ SpanSampler (head sampling)<br/>trace-coherent eviction"]
+        logRepo["LogQueueRepository<br/>severity / byte eviction"]
+        spansTbl[("spans_queue")]
+        logsTbl[("telemetry_queue")]
+    end
+
+    subgraph DELIVERY["Delivery — one use case, three triggers"]
+        signal["TelemetrySignal<br/>(debounced, in-memory)"]
+        worker["TelemetryFlushWorker<br/>signal · InternetIsUp · bg cron"]
+        flush["FlushTelemetry.run()"]
+        conn["ConnectivityState"]
+        loki["LokiClient<br/>push (opportunistic) · deliver (batch)"]
+        otlp["OtlpClient"]
+    end
+
+    collector[["OTLP/HTTP collector<br/>(Alloy · Tempo · Jaeger)"]]
+    lokiSrv[["Loki"]]
+
+    app --> tracing
+    app -->|logger.push| loki
+    tracing --> provider
+    tracing -.->|active context| ctx
+    provider --> proc
+    proc --> exporter
+    exporter --> spanRepo
+    spanRepo --> spansTbl
+    exporter -->|onEnqueued / store-first| signal
+    loki -->|on failure| logRepo
+    logRepo --> logsTbl
+
+    signal --> flush
+    worker --> flush
+    flush -->|drain logs| logRepo
+    flush -->|drain spans| spanRepo
+    flush --> loki
+    loki -->|batch| lokiSrv
+    flush --> otlp
+    otlp --> collector
+    flush -.->|updates online flag| conn
+    spanRepo -.->|bufferStats| tracing
+    logRepo -.->|bufferStats| tracing
+```
+
+### Delivery — event-driven, not a fixed timer
+
+Telemetry is delivered by a single `FlushTelemetry` use case that drains **both** queues. Three independent triggers funnel into it; **none is required**, so the framework never depends on the host app's connectivity cron or its event bus:
+
+1. **Production signal (always on, primary).** Producing telemetry schedules a _debounced_ in-memory flush (`TelemetrySignal`, ~3 s). A burst of spans collapses into one delivery attempt. Spans are persisted to SQLite first, _then_ the signal fires — **store-first**, so a crash mid-send never loses data and batches stay efficient.
+2. **Reconnect events (opt-in).** If the app emits `InternetIsUp/Down`, reconnecting drains the backlog immediately.
+3. **Background cron (opt-in).** A long-interval (≥15 min → real OS background task) safety net for whatever the other two missed.
+
+**Why not a 1-minute timer.** A fixed timer fires whether or not there is anything to send and whether or not the device is online, wasting work and hammering a dead network. Offline recovery instead rides the jobs' own **exponential backoff**: a failed delivery backs off and retries, so the pipeline self-heals when the network returns even with no cron and no events. A hard `fetch` timeout (`AbortController`) prevents a flush from hanging while offline — that is the "is there internet?" check, without coupling to a connectivity service.
+
+### Retention — bounded, coherent, severity-aware
+
+Telemetry is **best-effort and bounded by nature** — a device offline for days cannot buffer forever. The framework's job is to lose data _intelligently and visibly_, never silently. Business-critical data does **not** belong here; it goes through the durable `event_queue` / `domain_events` path with its dead-letter queue.
+
+Both buffers are capped by **row count and payload bytes** (predictable storage regardless of attribute size). When a cap is exceeded:
+
+- **Spans evict whole traces.** The oldest _entire trace_ is dropped, never individual spans. FIFO-by-row would evict root/parent spans first and leave orphaned children that render as broken traces downstream — the exact failure that makes a trace backend untrustworthy. Survivors are always complete.
+- **Logs evict by severity (count pressure) or size (byte pressure).** When there are too many rows, the lowest-severity oldest-first go first (`debug → info → warn → error`), so `error`/`warn` survive a flood of `debug`/`info`. When the byte budget is the constraint, the **largest** payloads go first — a single oversized blob is the cause of byte pressure and is shed directly, keeping the maximum number of small, information-dense entries (so keep large blobs out of logs).
+- **Spans head-sample under pressure.** Once the buffer passes 80 % of either budget, whole _new_ traces are dropped at ingest (a coherent per-trace decision via a deterministic hash, cached so a mid-trace pressure change can't split a trace). This stops the buffer thrashing insert→evict and keeps a coherent _sample_ instead of churning fragments.
+- **The loss is observable.** `Tracing.bufferStats()` exposes `rows`, `approxBytes`, `dropped` (evicted after buffering — back-pressure) and `sampled` (refused at ingest — load shed) so a rising backlog is a dashboard signal, not a silent gap.
+
+The eviction scan is **amortized** (runs once every N enqueues), so the hot path stays cheap under offline bursts; the bound is therefore soft (may transiently exceed by up to N rows).
+
+---
+
 ## 📦 Subpaths
 
 ```ts

package/dist/entrypoints/cron/EBuiltinCron.d.ts

@@ -0,0 +1,4 @@
+export declare enum EBuiltinCron {
+    CHECK_NETWORK = "CHECK_NETWORK",
+    TELEMETRY_FLUSH = "TELEMETRY_FLUSH"
+}

package/dist/entrypoints/cron/EBuiltinCron.js

@@ -0,0 +1,5 @@
+export var EBuiltinCron;
+(function (EBuiltinCron) {
+    EBuiltinCron["CHECK_NETWORK"] = "CHECK_NETWORK";
+    EBuiltinCron["TELEMETRY_FLUSH"] = "TELEMETRY_FLUSH";
+})(EBuiltinCron || (EBuiltinCron = {}));

package/dist/entrypoints/cron/checkNetworkStatus.cron.js

@@ -1,3 +1,4 @@
+import { EBuiltinCron } from "../../entrypoints/cron/EBuiltinCron";
 import { loggerCronJobs } from "../../infrastructure/logger";
 import { CronWorker } from "../../infrastructure/workers";
 import { networkUseCases } from "../../services/network.service";
@@ -6,5 +7,5 @@ async function checkNetworkStatus() {
     await networkUseCases.getNetworkStatus();
     loggerCronJobs.info("Finished checking network status");
 }
-const cronCheckNetworkStatus = new CronWorker("CHECK_NETWORK", checkNetworkStatus, 2.5);
+const cronCheckNetworkStatus = new CronWorker(EBuiltinCron.CHECK_NETWORK, checkNetworkStatus, 2.5);
 export default cronCheckNetworkStatus;

package/dist/entrypoints/db/migrations.d.ts

@@ -4,7 +4,9 @@ export declare enum DATABASE_TABLES {
     EVENT_QUEUE = "event_queue",
     DEAD_LETTER_QUEUE = "dead_letter_queue",
     DOMAIN_EVENTS = "domain_events",
-    DOMAIN_EVENTS_DEAD_LETTER = "domain_events_dead_letter"
+    DOMAIN_EVENTS_DEAD_LETTER = "domain_events_dead_letter",
+    TELEMETRY_QUEUE = "telemetry_queue",
+    SPANS_QUEUE = "spans_queue"
 }
 declare const MIGRATIONS: IMigration[];
 export default MIGRATIONS;

package/dist/entrypoints/db/migrations.js

@@ -6,6 +6,8 @@ export var DATABASE_TABLES;
     DATABASE_TABLES["DEAD_LETTER_QUEUE"] = "dead_letter_queue";
     DATABASE_TABLES["DOMAIN_EVENTS"] = "domain_events";
     DATABASE_TABLES["DOMAIN_EVENTS_DEAD_LETTER"] = "domain_events_dead_letter";
+    DATABASE_TABLES["TELEMETRY_QUEUE"] = "telemetry_queue";
+    DATABASE_TABLES["SPANS_QUEUE"] = "spans_queue";
 })(DATABASE_TABLES || (DATABASE_TABLES = {}));
 async function createSettingsTable() {
     await DBCursor.execAsync(`
@@ -110,6 +112,49 @@ async function createDomainEventsDeadLetterTable() {
     CREATE INDEX IF NOT EXISTS idx_dead_letter_failed ON ${DATABASE_TABLES.DOMAIN_EVENTS_DEAD_LETTER}(failed_at);
   `);
 }
+async function createTelemetryQueueTable() {
+    await DBCursor.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${DATABASE_TABLES.TELEMETRY_QUEUE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      level TEXT NOT NULL,
+      message TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_telemetry_queue_created
+    ON ${DATABASE_TABLES.TELEMETRY_QUEUE}(created_at);
+  `);
+}
+async function createSpansQueueTable() {
+    await DBCursor.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${DATABASE_TABLES.SPANS_QUEUE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      trace_id TEXT NOT NULL,
+      span_id TEXT NOT NULL,
+      parent_span_id TEXT,
+      name TEXT NOT NULL,
+      kind INTEGER NOT NULL DEFAULT 0,
+      start_time_unixnano TEXT NOT NULL,
+      end_time_unixnano TEXT NOT NULL,
+      attributes TEXT NOT NULL DEFAULT '{}',
+      status_code INTEGER NOT NULL DEFAULT 0,
+      status_message TEXT NOT NULL DEFAULT '',
+      resource_attrs TEXT NOT NULL DEFAULT '{}',
+      events TEXT NOT NULL DEFAULT '[]',
+      links TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_spans_queue_created
+    ON ${DATABASE_TABLES.SPANS_QUEUE}(created_at);
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_spans_queue_trace
+    ON ${DATABASE_TABLES.SPANS_QUEUE}(trace_id);
+  `);
+}
 const MIGRATIONS = [
     { name: DATABASE_TABLES.SETTINGS, migrationFn: createSettingsTable },
     { name: DATABASE_TABLES.EVENT_QUEUE, migrationFn: createEventQueueTable },
@@ -119,5 +164,7 @@ const MIGRATIONS = [
         name: DATABASE_TABLES.DOMAIN_EVENTS_DEAD_LETTER,
         migrationFn: createDomainEventsDeadLetterTable,
     },
+    { name: DATABASE_TABLES.TELEMETRY_QUEUE, migrationFn: createTelemetryQueueTable },
+    { name: DATABASE_TABLES.SPANS_QUEUE, migrationFn: createSpansQueueTable },
 ];
 export default MIGRATIONS;

package/dist/entrypoints/queue/QueueProcessor.js

@@ -1,33 +1,9 @@
 import { loggerQueueProcessor } from "../../infrastructure/logger";
 import { EventBus } from "../../infrastructure/workers";
+import { calculateDesiredSubscribers, statesAreEqual, } from "./subscriber_filter";
 let isRunning = false;
 let lastSyncState = null;
 let currentSubscribers = new Set();
-function statesAreEqual(a, b) {
-    if (!a)
-        return false;
-    if (a.isAuthenticated !== b.isAuthenticated)
-        return false;
-    if (a.domains.size !== b.domains.size)
-        return false;
-    for (const domain of a.domains) {
-        if (!b.domains.has(domain))
-            return false;
-    }
-    return true;
-}
-function calculateDesiredSubscribers(domains, isAuthenticated, subscribersByKey) {
-    const desired = new Set();
-    for (const domain of domains) {
-        const domainSubscribers = subscribersByKey[domain] ?? [];
-        for (const subscriber of domainSubscribers) {
-            if (isAuthenticated || !subscriber.requiresAuth) {
-                desired.add(subscriber);
-            }
-        }
-    }
-    return desired;
-}
 export const QueueProcessor = {
     start: () => {
         if (isRunning)

package/dist/entrypoints/queue/subscriber_filter.d.ts

@@ -0,0 +1,9 @@
+export interface HasRequiresAuth {
+    readonly requiresAuth: boolean;
+}
+export interface SyncState {
+    domains: Set<string>;
+    isAuthenticated: boolean;
+}
+export declare function statesAreEqual(a: SyncState | null, b: SyncState): boolean;
+export declare function calculateDesiredSubscribers<T extends HasRequiresAuth>(domains: Set<string>, isAuthenticated: boolean, subscribersByKey: Record<string, T[]>): Set<T>;

package/dist/entrypoints/queue/subscriber_filter.js

@@ -0,0 +1,25 @@
+export function statesAreEqual(a, b) {
+    if (!a)
+        return false;
+    if (a.isAuthenticated !== b.isAuthenticated)
+        return false;
+    if (a.domains.size !== b.domains.size)
+        return false;
+    for (const domain of a.domains) {
+        if (!b.domains.has(domain))
+            return false;
+    }
+    return true;
+}
+export function calculateDesiredSubscribers(domains, isAuthenticated, subscribersByKey) {
+    const desired = new Set();
+    for (const domain of domains) {
+        const domainSubscribers = subscribersByKey[domain] ?? [];
+        for (const subscriber of domainSubscribers) {
+            if (isAuthenticated || !subscriber.requiresAuth) {
+                desired.add(subscriber);
+            }
+        }
+    }
+    return desired;
+}

package/dist/entrypoints/ui/common_provider.js

@@ -191,12 +191,12 @@ export function CommonProvider({ children, lightTheme, darkTheme }) {
         function handleCronStart(payload) {
             if (!payload || typeof payload !== "object" || !("task" in payload))
                 return;
-            const { task } = payload;
+            const { task, label } = payload;
             setCronTasks((prev) => {
                 const next = new Map(prev);
                 next.set(task, {
                     id: task,
-                    label: task,
+                    label: label ?? task,
                     type: "cron",
                     status: "running",
                     startedAt: Date.now(),

package/dist/framework/base_module.d.ts

@@ -10,5 +10,6 @@ export declare class BaseModule extends DomainModule {
     migrations(): IMigration[];
     subscribers(): Subscriber[];
     crons(): CronWorker[];
+    persistOnReset(): string[];
 }
 export declare const baseModule: BaseModule;

package/dist/framework/base_module.js

@@ -4,7 +4,7 @@ import { DomainEventDeadLetterRepository } from "../adapters/repositories/domain
 import { SettingsRepository } from "../adapters/repositories/setting.repository";
 import { ECommonRepository } from "../domain/repositories";
 import cronCheckNetworkStatus from "../entrypoints/cron/checkNetworkStatus.cron";
-import MIGRATIONS from "../entrypoints/db/migrations";
+import MIGRATIONS, { DATABASE_TABLES } from "../entrypoints/db/migrations";
 import { ActivateDomainSubscriber } from "../entrypoints/queue/activateDomain.subscriber";
 import { NewAppSettingsSubscriber } from "../entrypoints/queue/newAppSettings.handler";
 import { PrintImageSubscriber } from "../entrypoints/queue/printImage.subscriber";
@@ -36,5 +36,10 @@ export class BaseModule extends DomainModule {
     crons() {
         return [cronCheckNetworkStatus];
     }
+    // Both telemetry tables survive restartDatabase() — data generated during
+    // logout must still be delivered; the flush cron runs independently of auth state.
+    persistOnReset() {
+        return [DATABASE_TABLES.TELEMETRY_QUEUE, DATABASE_TABLES.SPANS_QUEUE];
+    }
 }
 export const baseModule = new BaseModule();

package/dist/framework/createApp.d.ts

@@ -1,6 +1,20 @@
+import type { TelemetryConfig } from "../infrastructure/telemetry";
+import type { CronWorkerOpts } from "../infrastructure/workers";
 import type { DomainModule } from "./domain_module";
 import { Kernel } from "./kernel";
 export interface AppConfig {
     domains?: DomainModule[];
+    /**
+     * Opt-in telemetry. When provided, the Loki client and flush cron start automatically
+     * after migrations complete — so the `telemetry_queue` table is guaranteed to exist.
+     */
+    telemetry?: TelemetryConfig;
+    /**
+     * Override display options for any cron by taskName.
+     * Useful for showing/hiding toasts on internal crons (CHECK_NETWORK, TELEMETRY_FLUSH, etc.).
+     * @example
+     * crons: { CHECK_NETWORK: { showToast: true, label: "Verificando conexión" } }
+     */
+    crons?: Record<string, Partial<CronWorkerOpts>>;
 }
 export declare function createApp(config?: AppConfig): Promise<Kernel>;

package/dist/framework/createApp.js

@@ -1,9 +1,15 @@
+import { initTelemetry } from "../infrastructure/telemetry";
 import { baseModule } from "./base_module";
 import { Kernel } from "./kernel";
 import { orchestrator } from "./orchestrator";
 export async function createApp(config = {}) {
     const kernel = new Kernel([baseModule, ...(config.domains ?? [])]);
+    if (config.crons)
+        kernel.applyCronConfig(config.crons);
     orchestrator.configure(kernel);
     await orchestrator.bootstrap();
+    if (config.telemetry) {
+        await initTelemetry(config.telemetry);
+    }
     return kernel;
 }

package/dist/framework/kernel.d.ts

@@ -1,6 +1,6 @@
 import type { IMigration } from "../domain/database";
 import type { Subscriber } from "../domain/event_sourcing";
-import type { CronWorker } from "../infrastructure/workers";
+import type { CronWorker, CronWorkerOpts } from "../infrastructure/workers";
 import type { DomainModule } from "./domain_module";
 export declare class Kernel {
     private readonly modules;
@@ -12,6 +12,7 @@ export declare class Kernel {
     persistedTables(): string[];
     subscribersByKey(): Record<string, Subscriber[]>;
     cronsByKey(): Record<string, CronWorker[]>;
+    applyCronConfig(config: Record<string, Partial<CronWorkerOpts>>): void;
     runMigrations(): Promise<void>;
     bootstrap(): Promise<void>;
     restartDatabase(): Promise<void>;

package/dist/framework/kernel.js

@@ -36,6 +36,14 @@ export class Kernel {
         }
         return map;
     }
+    applyCronConfig(config) {
+        for (const crons of Object.values(this.cronsByKey())) {
+            for (const cron of crons) {
+                if (config[cron.taskName])
+                    cron.configure(config[cron.taskName]);
+            }
+        }
+    }
     async runMigrations() {
         for (const { name, migrationFn } of this.migrations()) {
             logger.info(`Running migration: ${name}`);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { EBuiltinCron } from "./entrypoints/cron/EBuiltinCron";
 export type { AppShellConfig } from "./entrypoints/ui/AppShell";
 export { createAppShell } from "./entrypoints/ui/AppShell";
 export type { TimezoneLocale } from "./entrypoints/ui/common_provider";
@@ -13,3 +14,9 @@ export { DomainModule } from "./framework/domain_module";
 export { Kernel } from "./framework/kernel";
 export { orchestrator } from "./framework/orchestrator";
 export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export type { InterceptorHooks, MethodCall, } from "./infrastructure/interceptor/intercept";
+export { interceptClass, interceptFunction, interceptInstance, } from "./infrastructure/interceptor/intercept";
+export type { Logger } from "./infrastructure/interceptor/logging_hooks";
+export { loggingHooks } from "./infrastructure/interceptor/logging_hooks";
+export type { LokiAuth, LokiConfig, TelemetryConfig, } from "./infrastructure/telemetry";
+export { initTelemetry } from "./infrastructure/telemetry";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { EBuiltinCron } from "./entrypoints/cron/EBuiltinCron";
 export { createAppShell } from "./entrypoints/ui/AppShell";
 export { CommonProvider, useCommon } from "./entrypoints/ui/common_provider";
 export { ActiveDomainApp, DomainSwitcherProvider, useDomainSwitcher, } from "./entrypoints/ui/domain_switcher";
@@ -8,3 +9,6 @@ export { DomainModule } from "./framework/domain_module";
 export { Kernel } from "./framework/kernel";
 export { orchestrator } from "./framework/orchestrator";
 export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export { interceptClass, interceptFunction, interceptInstance, } from "./infrastructure/interceptor/intercept";
+export { loggingHooks } from "./infrastructure/interceptor/logging_hooks";
+export { initTelemetry } from "./infrastructure/telemetry";

package/dist/infrastructure/context_manager/context.d.ts

@@ -0,0 +1,16 @@
+import type { ContextKey } from "./context_key";
+/**
+ * Immutable execution-scoped key-value store.
+ *
+ * Every modification returns a new Context — the original is never mutated.
+ * This makes it safe to pass across async boundaries without defensive copies.
+ */
+export declare class Context {
+    private readonly _map;
+    private constructor();
+    static readonly ROOT: Context;
+    get<T>(key: ContextKey<T>): T | undefined;
+    set<T>(key: ContextKey<T>, value: T): Context;
+    delete<T>(key: ContextKey<T>): Context;
+    describe(): string;
+}

package/dist/infrastructure/context_manager/context.js

@@ -0,0 +1,37 @@
+/**
+ * Immutable execution-scoped key-value store.
+ *
+ * Every modification returns a new Context — the original is never mutated.
+ * This makes it safe to pass across async boundaries without defensive copies.
+ */
+export class Context {
+    _map;
+    constructor(map) {
+        this._map = map;
+    }
+    static ROOT = new Context(new Map());
+    get(key) {
+        return this._map.get(key._symbol);
+    }
+    set(key, value) {
+        const next = new Map(this._map);
+        next.set(key._symbol, value);
+        return new Context(next);
+    }
+    delete(key) {
+        const next = new Map(this._map);
+        next.delete(key._symbol);
+        return new Context(next);
+    }
+    describe() {
+        const parts = [];
+        for (const [sym, val] of this._map) {
+            const name = sym.description ?? "unknown";
+            const repr = val !== null && typeof val === "object"
+                ? (val.constructor?.name ?? "Object")
+                : String(val);
+            parts.push(`${name}: ${repr}`);
+        }
+        return `Context { ${parts.join(", ") || "empty"} }`;
+    }
+}