@mongrov/analytics 0.1.0-alpha.1 → 0.1.0-alpha.7

package/dist/sync/scheduler.d.ts

@@ -0,0 +1,84 @@
+/**
+ * T-22 + T-23 + T-24 — SyncScheduler.
+ *
+ * Wraps `expo-background-task` via an injected `BackgroundTaskPort` so unit
+ * tests can drive registration/dispatch without touching the native module.
+ *
+ * A cycle runs: constraint check → flush → push → fetch → (optional rules).
+ * Constraints (wifi + charging) are queried via `ConstraintPort`; failing
+ * checks emit a debug log and skip the cycle with `SyncError('constraint_not_met')`.
+ * `triggerNow()` bypasses constraints and always runs (T-24).
+ *
+ * Design.md §sync/scheduler.ts is the source of truth for the surface.
+ */
+import { SyncError } from './errors';
+import type { AttachContext } from '../core/types';
+/**
+ * Injected wrapper around `expo-background-task`. Kept minimal — start/stop
+ * plus a fire-once dispatch hook the caller uses to run the cycle for tests.
+ */
+export interface BackgroundTaskPort {
+    register: (taskName: string, handler: () => Promise<void>) => Promise<void>;
+    unregister: (taskName: string) => Promise<void>;
+    isRegistered: (taskName: string) => Promise<boolean>;
+}
+/** Battery + network gates that decide whether a scheduled cycle runs. */
+export interface ConstraintPort {
+    isCharging: () => Promise<boolean>;
+    isOnWifi: () => Promise<boolean>;
+}
+/** Sync operations the scheduler drives per cycle. */
+export interface SyncCoordinator {
+    flushAll: () => Promise<void>;
+    pushAll: (tables: string[], ctx: AttachContext) => Promise<Array<{
+        ok: boolean;
+    }>>;
+    fetchIncremental: (ctx: AttachContext) => Promise<Array<{
+        ok: boolean;
+    }>>;
+    onCycleComplete?: () => Promise<void>;
+}
+/** Debug/info logger — matches `@mongrov/core` shape narrowly. */
+export interface SchedulerLogger {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+}
+export interface SchedulerConstraints {
+    /** Require Wi-Fi (skip on cellular). Default: true. */
+    requireWifi?: boolean;
+    /** Require the device to be charging. Default: false. */
+    requireCharging?: boolean;
+}
+export interface SyncSchedulerConfig {
+    backgroundTask: BackgroundTaskPort;
+    constraints: ConstraintPort;
+    coordinator: SyncCoordinator;
+    /** Tables to push each cycle. */
+    tables: string[];
+    /** Attach context to run against. */
+    ctx: AttachContext;
+    /** Task name registered with the background scheduler. */
+    taskName?: string;
+    constraintPolicy?: SchedulerConstraints;
+    logger?: SchedulerLogger;
+}
+export type SchedulerState = 'idle' | 'running' | 'error';
+export interface CycleResult {
+    ok: boolean;
+    skipped: boolean;
+    reason?: 'constraint_not_met';
+    error?: SyncError;
+}
+export declare class SyncScheduler {
+    #private;
+    constructor(config: SyncSchedulerConfig);
+    get state(): SchedulerState;
+    subscribe(fn: (state: SchedulerState) => void): () => void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRegistered(): Promise<boolean>;
+    /** T-24 — manual trigger bypasses constraints. */
+    triggerNow(): Promise<CycleResult>;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/sync/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/sync/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/sync/scheduler.js

@@ -0,0 +1,132 @@
+/**
+ * T-22 + T-23 + T-24 — SyncScheduler.
+ *
+ * Wraps `expo-background-task` via an injected `BackgroundTaskPort` so unit
+ * tests can drive registration/dispatch without touching the native module.
+ *
+ * A cycle runs: constraint check → flush → push → fetch → (optional rules).
+ * Constraints (wifi + charging) are queried via `ConstraintPort`; failing
+ * checks emit a debug log and skip the cycle with `SyncError('constraint_not_met')`.
+ * `triggerNow()` bypasses constraints and always runs (T-24).
+ *
+ * Design.md §sync/scheduler.ts is the source of truth for the surface.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _SyncScheduler_instances, _SyncScheduler_config, _SyncScheduler_state, _SyncScheduler_subscribers, _SyncScheduler_runCycle, _SyncScheduler_checkConstraints, _SyncScheduler_setState;
+import { SyncError } from './errors';
+const DEFAULT_TASK_NAME = '@mongrov/analytics:sync';
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+};
+export class SyncScheduler {
+    constructor(config) {
+        _SyncScheduler_instances.add(this);
+        _SyncScheduler_config.set(this, void 0);
+        _SyncScheduler_state.set(this, 'idle');
+        _SyncScheduler_subscribers.set(this, new Set());
+        __classPrivateFieldSet(this, _SyncScheduler_config, {
+            backgroundTask: config.backgroundTask,
+            constraints: config.constraints,
+            coordinator: config.coordinator,
+            tables: config.tables,
+            ctx: config.ctx,
+            taskName: config.taskName ?? DEFAULT_TASK_NAME,
+            logger: config.logger ?? noopLogger,
+            constraintPolicy: {
+                requireWifi: config.constraintPolicy?.requireWifi ?? true,
+                requireCharging: config.constraintPolicy?.requireCharging ?? false,
+            },
+        }, "f");
+    }
+    get state() {
+        return __classPrivateFieldGet(this, _SyncScheduler_state, "f");
+    }
+    subscribe(fn) {
+        __classPrivateFieldGet(this, _SyncScheduler_subscribers, "f").add(fn);
+        return () => __classPrivateFieldGet(this, _SyncScheduler_subscribers, "f").delete(fn);
+    }
+    async start() {
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").backgroundTask.register(__classPrivateFieldGet(this, _SyncScheduler_config, "f").taskName, async () => {
+            await __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_runCycle).call(this, false);
+        });
+        __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.info('scheduler.start', { taskName: __classPrivateFieldGet(this, _SyncScheduler_config, "f").taskName });
+    }
+    async stop() {
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").backgroundTask.unregister(__classPrivateFieldGet(this, _SyncScheduler_config, "f").taskName);
+        __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.info('scheduler.stop', { taskName: __classPrivateFieldGet(this, _SyncScheduler_config, "f").taskName });
+    }
+    async isRegistered() {
+        return __classPrivateFieldGet(this, _SyncScheduler_config, "f").backgroundTask.isRegistered(__classPrivateFieldGet(this, _SyncScheduler_config, "f").taskName);
+    }
+    /** T-24 — manual trigger bypasses constraints. */
+    async triggerNow() {
+        return __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_runCycle).call(this, true);
+    }
+}
+_SyncScheduler_config = new WeakMap(), _SyncScheduler_state = new WeakMap(), _SyncScheduler_subscribers = new WeakMap(), _SyncScheduler_instances = new WeakSet(), _SyncScheduler_runCycle = async function _SyncScheduler_runCycle(bypassConstraints) {
+    if (__classPrivateFieldGet(this, _SyncScheduler_state, "f") === 'running') {
+        __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.debug('scheduler.cycle.skip', { reason: 'already_running' });
+        return { ok: false, skipped: true };
+    }
+    if (!bypassConstraints) {
+        const allowed = await __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_checkConstraints).call(this);
+        if (!allowed) {
+            __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.debug('scheduler.cycle.skip', { reason: 'constraint_not_met' });
+            return {
+                ok: false,
+                skipped: true,
+                reason: 'constraint_not_met',
+                error: new SyncError('constraint_not_met', 'Battery/network constraints not satisfied'),
+            };
+        }
+    }
+    __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_setState).call(this, 'running');
+    try {
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").coordinator.flushAll();
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").coordinator.pushAll(__classPrivateFieldGet(this, _SyncScheduler_config, "f").tables, __classPrivateFieldGet(this, _SyncScheduler_config, "f").ctx);
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").coordinator.fetchIncremental(__classPrivateFieldGet(this, _SyncScheduler_config, "f").ctx);
+        await __classPrivateFieldGet(this, _SyncScheduler_config, "f").coordinator.onCycleComplete?.();
+        __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.debug('scheduler.cycle.ok');
+        __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_setState).call(this, 'idle');
+        return { ok: true, skipped: false };
+    }
+    catch (cause) {
+        __classPrivateFieldGet(this, _SyncScheduler_config, "f").logger.warn('scheduler.cycle.error', { error: String(cause) });
+        __classPrivateFieldGet(this, _SyncScheduler_instances, "m", _SyncScheduler_setState).call(this, 'error');
+        return {
+            ok: false,
+            skipped: false,
+            error: new SyncError('flush_failed', 'Sync cycle failed', cause),
+        };
+    }
+}, _SyncScheduler_checkConstraints = async function _SyncScheduler_checkConstraints() {
+    const { requireWifi, requireCharging } = __classPrivateFieldGet(this, _SyncScheduler_config, "f").constraintPolicy;
+    if (requireWifi) {
+        const wifi = await __classPrivateFieldGet(this, _SyncScheduler_config, "f").constraints.isOnWifi();
+        if (!wifi)
+            return false;
+    }
+    if (requireCharging) {
+        const charging = await __classPrivateFieldGet(this, _SyncScheduler_config, "f").constraints.isCharging();
+        if (!charging)
+            return false;
+    }
+    return true;
+}, _SyncScheduler_setState = function _SyncScheduler_setState(next) {
+    __classPrivateFieldSet(this, _SyncScheduler_state, next, "f");
+    for (const fn of __classPrivateFieldGet(this, _SyncScheduler_subscribers, "f"))
+        fn(next);
+};
+//# sourceMappingURL=scheduler.js.map

package/dist/sync/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/sync/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/sync/triggers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Flush triggers (T-14).
+ *
+ * Observes the `SensorBuffer` + app lifecycle and decides when to enqueue a
+ * flush. Triggers are:
+ *   - `row-count`  → any table hits `maxRows`
+ *   - `age`        → oldest entry's `enqueuedAt` older than `maxAgeMs`
+ *   - `foreground` → app-state 'active' transition
+ *   - `background` → app-state 'background' transition (best-effort)
+ *   - `manual`     → caller-invoked
+ *
+ * All triggers ultimately funnel through `BatchFlusher.scheduleFlush(table,
+ * reason)`. Row-count / age evaluations are driven by an external ticker so
+ * the trigger controller stays synchronous + testable — the app wires a
+ * `setInterval` (or the sync scheduler) to `evaluate()`.
+ */
+import type { BatchFlusher, FlushReason } from './flusher';
+import type { SensorBuffer } from './buffer';
+export interface FlushTriggersConfig {
+    buffer: SensorBuffer;
+    flusher: BatchFlusher;
+    /** Row count threshold — any table hitting this triggers a flush. */
+    maxRows?: number;
+    /** Age threshold in ms — oldest entry older than this triggers a flush. */
+    maxAgeMs?: number;
+    /** Test-injected clock. */
+    now?: () => number;
+}
+/** Default from spec §Flush triggers. */
+export declare const DEFAULT_MAX_ROWS = 500;
+export declare const DEFAULT_MAX_AGE_MS = 30000;
+export declare class FlushTriggers {
+    #private;
+    constructor(config: FlushTriggersConfig);
+    /**
+     * Record the oldest-entry age for a table. Called by the buffer's push
+     * pipeline (via the sync manager) so we can evaluate the age trigger
+     * without traversing the ring on every check.
+     */
+    noteEnqueue(table: string, enqueuedAt: number): void;
+    /** Called after a drain empties a table so the age tracker restarts. */
+    noteDrain(table: string): void;
+    /**
+     * Poll the buffer and enqueue flushes for any table that trips a trigger.
+     * Returns the tables that were scheduled so tests can assert directly.
+     */
+    evaluate(): Promise<{
+        table: string;
+        reason: FlushReason;
+    }[]>;
+    /**
+     * App-state transition to `foreground`. Schedules a flush on every tracked
+     * table at priority 0.
+     */
+    onForeground(): void;
+    /**
+     * App-state transition to `background`. Best-effort background flush at
+     * lowest priority.
+     */
+    onBackground(): void;
+    /** Manual `flush()` — the caller decides the table set. */
+    manual(table: string): Promise<unknown>;
+}
+//# sourceMappingURL=triggers.d.ts.map

package/dist/sync/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../src/sync/triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,YAAY,CAAA;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC,eAAO,MAAM,kBAAkB,QAAS,CAAA;AAExC,qBAAa,aAAa;;gBASZ,MAAM,EAAE,mBAAmB;IAQvC;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAMpD,wEAAwE;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IAyBnE;;;OAGG;IACH,YAAY,IAAI,IAAI;IAMpB;;;OAGG;IACH,YAAY,IAAI,IAAI;IAMpB,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGxC"}

package/dist/sync/triggers.js

@@ -0,0 +1,113 @@
+/**
+ * Flush triggers (T-14).
+ *
+ * Observes the `SensorBuffer` + app lifecycle and decides when to enqueue a
+ * flush. Triggers are:
+ *   - `row-count`  → any table hits `maxRows`
+ *   - `age`        → oldest entry's `enqueuedAt` older than `maxAgeMs`
+ *   - `foreground` → app-state 'active' transition
+ *   - `background` → app-state 'background' transition (best-effort)
+ *   - `manual`     → caller-invoked
+ *
+ * All triggers ultimately funnel through `BatchFlusher.scheduleFlush(table,
+ * reason)`. Row-count / age evaluations are driven by an external ticker so
+ * the trigger controller stays synchronous + testable — the app wires a
+ * `setInterval` (or the sync scheduler) to `evaluate()`.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _FlushTriggers_buffer, _FlushTriggers_flusher, _FlushTriggers_maxRows, _FlushTriggers_maxAgeMs, _FlushTriggers_now, _FlushTriggers_oldestByTable;
+/** Default from spec §Flush triggers. */
+export const DEFAULT_MAX_ROWS = 500;
+export const DEFAULT_MAX_AGE_MS = 30000;
+export class FlushTriggers {
+    constructor(config) {
+        _FlushTriggers_buffer.set(this, void 0);
+        _FlushTriggers_flusher.set(this, void 0);
+        _FlushTriggers_maxRows.set(this, void 0);
+        _FlushTriggers_maxAgeMs.set(this, void 0);
+        _FlushTriggers_now.set(this, void 0);
+        /** Tracks the enqueuedAt of the oldest entry per table, seeded on first observation. */
+        _FlushTriggers_oldestByTable.set(this, new Map());
+        __classPrivateFieldSet(this, _FlushTriggers_buffer, config.buffer, "f");
+        __classPrivateFieldSet(this, _FlushTriggers_flusher, config.flusher, "f");
+        __classPrivateFieldSet(this, _FlushTriggers_maxRows, config.maxRows ?? DEFAULT_MAX_ROWS, "f");
+        __classPrivateFieldSet(this, _FlushTriggers_maxAgeMs, config.maxAgeMs ?? DEFAULT_MAX_AGE_MS, "f");
+        __classPrivateFieldSet(this, _FlushTriggers_now, config.now ?? (() => Date.now()), "f");
+    }
+    /**
+     * Record the oldest-entry age for a table. Called by the buffer's push
+     * pipeline (via the sync manager) so we can evaluate the age trigger
+     * without traversing the ring on every check.
+     */
+    noteEnqueue(table, enqueuedAt) {
+        if (!__classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").has(table)) {
+            __classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").set(table, enqueuedAt);
+        }
+    }
+    /** Called after a drain empties a table so the age tracker restarts. */
+    noteDrain(table) {
+        __classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").delete(table);
+    }
+    /**
+     * Poll the buffer and enqueue flushes for any table that trips a trigger.
+     * Returns the tables that were scheduled so tests can assert directly.
+     */
+    async evaluate() {
+        const scheduled = [];
+        const size = await __classPrivateFieldGet(this, _FlushTriggers_buffer, "f").size();
+        // We evaluate per known table by consulting per-table size(). Rather than
+        // introspect the buffer's internals, use the tables the triggers already
+        // know about (via noteEnqueue) plus any table with a positive total.
+        const candidates = new Set(__classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").keys());
+        for (const t of candidates) {
+            const perTable = await __classPrivateFieldGet(this, _FlushTriggers_buffer, "f").size(t);
+            if (perTable.inMemory >= __classPrivateFieldGet(this, _FlushTriggers_maxRows, "f")) {
+                scheduled.push({ table: t, reason: 'row-count' });
+                __classPrivateFieldGet(this, _FlushTriggers_flusher, "f").scheduleFlush(t, 'row-count');
+                continue;
+            }
+            const oldest = __classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").get(t);
+            if (oldest !== undefined && __classPrivateFieldGet(this, _FlushTriggers_now, "f").call(this) - oldest >= __classPrivateFieldGet(this, _FlushTriggers_maxAgeMs, "f")) {
+                scheduled.push({ table: t, reason: 'age' });
+                __classPrivateFieldGet(this, _FlushTriggers_flusher, "f").scheduleFlush(t, 'age');
+            }
+        }
+        // Suppress the unused var warning for size — it may be surfaced later.
+        void size;
+        return scheduled;
+    }
+    /**
+     * App-state transition to `foreground`. Schedules a flush on every tracked
+     * table at priority 0.
+     */
+    onForeground() {
+        for (const t of __classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").keys()) {
+            __classPrivateFieldGet(this, _FlushTriggers_flusher, "f").scheduleFlush(t, 'foreground');
+        }
+    }
+    /**
+     * App-state transition to `background`. Best-effort background flush at
+     * lowest priority.
+     */
+    onBackground() {
+        for (const t of __classPrivateFieldGet(this, _FlushTriggers_oldestByTable, "f").keys()) {
+            __classPrivateFieldGet(this, _FlushTriggers_flusher, "f").scheduleFlush(t, 'background');
+        }
+    }
+    /** Manual `flush()` — the caller decides the table set. */
+    manual(table) {
+        return __classPrivateFieldGet(this, _FlushTriggers_flusher, "f").scheduleFlush(table, 'manual');
+    }
+}
+_FlushTriggers_buffer = new WeakMap(), _FlushTriggers_flusher = new WeakMap(), _FlushTriggers_maxRows = new WeakMap(), _FlushTriggers_maxAgeMs = new WeakMap(), _FlushTriggers_now = new WeakMap(), _FlushTriggers_oldestByTable = new WeakMap();
+//# sourceMappingURL=triggers.js.map

package/dist/sync/triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../../src/sync/triggers.ts"],"names":[],"mappings":"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"}

package/dist/sync/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Sync-specific types shared across buffer/flusher/pusher/fetcher/scheduler.
+ *
+ * Mapper types live under `sync/mapper/types.ts` — this file collects the
+ * runtime infrastructure types (buffer entries, flush results, policies).
+ */
+/**
+ * A raw non-firmware batch of rows for a single table. Emitted by adapters
+ * that already speak the warehouse row shape (e.g. custom telemetry).
+ */
+export interface SensorBatch {
+    table: string;
+    brand: string;
+    familyId: string;
+    userId: string;
+    deviceId: string;
+    rows: Record<string, unknown>[];
+}
+/**
+ * A buffered entry: the row payload plus enough context to route the flush.
+ * Rows keep their per-metric context via the mapper output; SensorBatch rows
+ * inherit context from the enclosing batch, and we snapshot it at push time.
+ */
+export interface BufferEntry {
+    rows: Record<string, unknown>[];
+    brand: string;
+    familyId: string;
+    userId: string;
+    deviceId: string;
+    /** Millis since epoch when the entry entered the buffer — used for age triggers. */
+    enqueuedAt: number;
+    /** Approximate byte size — used for byte-budget accounting. */
+    byteSize: number;
+}
+export type OverflowPolicy = 'drop-oldest' | 'drop-newest' | 'block';
+export interface BufferSize {
+    /** Rows currently in the in-memory ring. */
+    inMemory: number;
+    /** Rows currently persisted in overflow. */
+    overflow: number;
+    /** Total bytes accounted for in-memory (excludes overflow, which is off-heap). */
+    inMemoryBytes: number;
+}
+export interface FlushResult {
+    table: string;
+    rowsFlushed: number;
+    ok: boolean;
+    error?: Error;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAA;AAEpE,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,KAAK,CAAA;CACd"}

package/dist/sync/types.js

@@ -0,0 +1,8 @@
+/**
+ * Sync-specific types shared across buffer/flusher/pusher/fetcher/scheduler.
+ *
+ * Mapper types live under `sync/mapper/types.ts` — this file collects the
+ * runtime infrastructure types (buffer entries, flush results, policies).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/sync/watermark.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Watermark store (T-16).
+ *
+ * Two independent cursors per `(brand, familyId, table)` pair:
+ *   - `push` — highest `ts` we've successfully written to R2. Advances on
+ *     every successful pusher round.
+ *   - `fetch` — highest `ts` we've pulled from R2 into the local warehouse.
+ *     Advances on every successful fetcher round.
+ *
+ * Key convention (spec §Watermark):
+ *   `analytics:watermark:{brand}:{familyId}:{table}:{kind}` → ISO string
+ *
+ * Missing key defaults to `now() - retentionMs`. Default retention is 30 days
+ * so a fresh install pushes/fetches at most the last month rather than
+ * unbounded history.
+ */
+import type { KVStore } from '../core/types';
+export type WatermarkKind = 'push' | 'fetch';
+export interface WatermarkStoreConfig {
+    kv: KVStore;
+    /** Injected clock for tests. Defaults to `() => new Date()`. */
+    now?: () => Date;
+    /** Fresh-install horizon. Defaults to 30 days. */
+    defaultRetentionMs?: number;
+}
+export declare class WatermarkStore {
+    #private;
+    constructor(config: WatermarkStoreConfig);
+    get(brand: string, familyId: string, table: string, kind: WatermarkKind): Promise<Date>;
+    advance(brand: string, familyId: string, table: string, kind: WatermarkKind, ts: Date): Promise<void>;
+}
+//# sourceMappingURL=watermark.d.ts.map

package/dist/sync/watermark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark.d.ts","sourceRoot":"","sources":["../../src/sync/watermark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAK5C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5C,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAA;IACX,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAWD,qBAAa,cAAc;;gBAKb,MAAM,EAAE,oBAAoB;IAMlC,GAAG,CACP,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC;IASV,OAAO,CACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,IAAI,GACP,OAAO,CAAC,IAAI,CAAC;CAMjB"}

package/dist/sync/watermark.js

@@ -0,0 +1,61 @@
+/**
+ * Watermark store (T-16).
+ *
+ * Two independent cursors per `(brand, familyId, table)` pair:
+ *   - `push` — highest `ts` we've successfully written to R2. Advances on
+ *     every successful pusher round.
+ *   - `fetch` — highest `ts` we've pulled from R2 into the local warehouse.
+ *     Advances on every successful fetcher round.
+ *
+ * Key convention (spec §Watermark):
+ *   `analytics:watermark:{brand}:{familyId}:{table}:{kind}` → ISO string
+ *
+ * Missing key defaults to `now() - retentionMs`. Default retention is 30 days
+ * so a fresh install pushes/fetches at most the last month rather than
+ * unbounded history.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _WatermarkStore_kv, _WatermarkStore_now, _WatermarkStore_defaultRetentionMs;
+const KEY_PREFIX = 'analytics:watermark';
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+function key(brand, familyId, table, kind) {
+    return `${KEY_PREFIX}:${brand}:${familyId}:${table}:${kind}`;
+}
+export class WatermarkStore {
+    constructor(config) {
+        _WatermarkStore_kv.set(this, void 0);
+        _WatermarkStore_now.set(this, void 0);
+        _WatermarkStore_defaultRetentionMs.set(this, void 0);
+        __classPrivateFieldSet(this, _WatermarkStore_kv, config.kv, "f");
+        __classPrivateFieldSet(this, _WatermarkStore_now, config.now ?? (() => new Date()), "f");
+        __classPrivateFieldSet(this, _WatermarkStore_defaultRetentionMs, config.defaultRetentionMs ?? DEFAULT_RETENTION_MS, "f");
+    }
+    async get(brand, familyId, table, kind) {
+        const iso = await __classPrivateFieldGet(this, _WatermarkStore_kv, "f").get(key(brand, familyId, table, kind));
+        if (iso && typeof iso === 'string') {
+            const parsed = new Date(iso);
+            if (!Number.isNaN(parsed.getTime()))
+                return parsed;
+        }
+        return new Date(__classPrivateFieldGet(this, _WatermarkStore_now, "f").call(this).getTime() - __classPrivateFieldGet(this, _WatermarkStore_defaultRetentionMs, "f"));
+    }
+    async advance(brand, familyId, table, kind, ts) {
+        // Never regress — only accept advances forward.
+        const current = await this.get(brand, familyId, table, kind);
+        if (ts <= current)
+            return;
+        await __classPrivateFieldGet(this, _WatermarkStore_kv, "f").set(key(brand, familyId, table, kind), ts.toISOString());
+    }
+}
+_WatermarkStore_kv = new WeakMap(), _WatermarkStore_now = new WeakMap(), _WatermarkStore_defaultRetentionMs = new WeakMap();
+//# sourceMappingURL=watermark.js.map

package/dist/sync/watermark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark.js","sourceRoot":"","sources":["../../src/sync/watermark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;;;;;;;;;;;;;AAIH,MAAM,UAAU,GAAG,qBAAqB,CAAA;AACxC,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,UAAU;AAYhE,SAAS,GAAG,CACV,KAAa,EACb,QAAgB,EAChB,KAAa,EACb,IAAmB;IAEnB,OAAO,GAAG,UAAU,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,IAAI,IAAI,EAAE,CAAA;AAC9D,CAAC;AAED,MAAM,OAAO,cAAc;IAKzB,YAAY,MAA4B;QAJ/B,qCAAY;QACZ,sCAAgB;QAChB,qDAA2B;QAGlC,uBAAA,IAAI,sBAAO,MAAM,CAAC,EAAE,MAAA,CAAA;QACpB,uBAAA,IAAI,uBAAQ,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,MAAA,CAAA;QAC5C,uBAAA,IAAI,sCAAuB,MAAM,CAAC,kBAAkB,IAAI,oBAAoB,MAAA,CAAA;IAC9E,CAAC;IAED,KAAK,CAAC,GAAG,CACP,KAAa,EACb,QAAgB,EAChB,KAAa,EACb,IAAmB;QAEnB,MAAM,GAAG,GAAG,MAAM,uBAAA,IAAI,0BAAI,CAAC,GAAG,CAAS,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAA;QACzE,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAAE,OAAO,MAAM,CAAA;QACpD,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,uBAAA,IAAI,2BAAK,MAAT,IAAI,CAAO,CAAC,OAAO,EAAE,GAAG,uBAAA,IAAI,0CAAoB,CAAC,CAAA;IACnE,CAAC;IAED,KAAK,CAAC,OAAO,CACX,KAAa,EACb,QAAgB,EAChB,KAAa,EACb,IAAmB,EACnB,EAAQ;QAER,gDAAgD;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QAC5D,IAAI,EAAE,IAAI,OAAO;YAAE,OAAM;QACzB,MAAM,uBAAA,IAAI,0BAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;IACzE,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mongrov/analytics",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.7",
   "description": "DuckDB + R2 Iceberg local analytics for @mongrov apps",
   "license": "MIT",
   "repository": {
@@ -79,12 +79,22 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "date-fns-tz": "^3.2.0",
+    "p-queue": "^8.0.1",
+    "xstate": "^5.30.0"
+  },
   "devDependencies": {
     "@mongrov/db": "workspace:*",
     "@mongrov/types": "workspace:*",
+    "@testing-library/react": "^14.3.1",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9",
-    "xstate": "^5.30.0",
     "zod": "^3.23.8"
   }
 }