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

package/dist/sync/flusher.js

@@ -0,0 +1,234 @@
+/**
+ * Batch flusher (T-13 + T-15).
+ *
+ * Drains a `SensorBuffer` into a DuckDB Appender. Successful flushes are
+ * durably observable (buffer.drain() removes both in-memory and overflow
+ * copies), and a `SyncEmitter` fan-out surfaces `flushed` events for hooks +
+ * downstream invalidation.
+ *
+ * Retry / concurrency (T-15):
+ *   - Wrapped in a `p-queue` (concurrency=2 by default) so multi-table flushes
+ *     run in parallel without hammering the CPU.
+ *   - Priorities: `foreground` (0) > `manual` (1) > `scheduled` (5) >
+ *     `background` (10). Lower numeric priority = runs sooner.
+ *   - Backoff schedule: 1s, 2s, 4s, 8s, 16s, 32s, 60s (capped). 5 consecutive
+ *     failures per table → the flusher stops re-enqueuing and surfaces
+ *     `error` state until the next explicit `flush()`.
+ *   - Per-attempt timeout: 30s. Timeout aborts the attempt and counts as a
+ *     failure toward the 5-failure limit.
+ *
+ * Data safety: attempts do *not* remove rows from the buffer until the
+ * appender reports success. On failure the drained entries are re-pushed onto
+ * the in-memory ring (front of queue) so subsequent retries see the same
+ * batch.
+ */
+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 _BatchFlusher_instances, _BatchFlusher_engine, _BatchFlusher_buffer, _BatchFlusher_columnOrder, _BatchFlusher_queue, _BatchFlusher_sleep, _BatchFlusher_now, _BatchFlusher_emit, _BatchFlusher_tables, _BatchFlusher_runWithRetry, _BatchFlusher_flushWithTimeout, _BatchFlusher_writeToAppender, _BatchFlusher_restore, _BatchFlusher_ensureState;
+import PQueue from 'p-queue';
+import { SyncError } from './errors';
+// p-queue: HIGHER priority values run first. Foreground / manual sit at the
+// top; background sits at the floor.
+const PRIORITY_BY_REASON = {
+    foreground: 100,
+    manual: 90,
+    'row-count': 50,
+    age: 40,
+    scheduled: 10,
+    background: 0,
+};
+/** Exponential backoff in ms, per attempt index (0-based). Capped at 60s. */
+export const BACKOFF_SEQUENCE_MS = [
+    1000,
+    2000,
+    4000,
+    8000,
+    16000,
+    32000,
+    60000,
+];
+export const MAX_CONSECUTIVE_FAILURES = 5;
+export const FLUSH_TIMEOUT_MS = 30000;
+export class BatchFlusher {
+    constructor(config) {
+        _BatchFlusher_instances.add(this);
+        _BatchFlusher_engine.set(this, void 0);
+        _BatchFlusher_buffer.set(this, void 0);
+        _BatchFlusher_columnOrder.set(this, void 0);
+        _BatchFlusher_queue.set(this, void 0);
+        _BatchFlusher_sleep.set(this, void 0);
+        _BatchFlusher_now.set(this, void 0);
+        _BatchFlusher_emit.set(this, void 0);
+        _BatchFlusher_tables.set(this, new Map());
+        __classPrivateFieldSet(this, _BatchFlusher_engine, config.engine, "f");
+        __classPrivateFieldSet(this, _BatchFlusher_buffer, config.buffer, "f");
+        __classPrivateFieldSet(this, _BatchFlusher_columnOrder, config.columnOrder, "f");
+        __classPrivateFieldSet(this, _BatchFlusher_sleep, config.sleep ?? defaultSleep, "f");
+        __classPrivateFieldSet(this, _BatchFlusher_now, config.now ?? (() => Date.now()), "f");
+        __classPrivateFieldSet(this, _BatchFlusher_emit, config.emit, "f");
+        __classPrivateFieldSet(this, _BatchFlusher_queue, new PQueue({ concurrency: config.concurrency ?? 2 }), "f");
+    }
+    /** Runtime state for a table. `idle` if we've never touched it. */
+    stateOf(table) {
+        return __classPrivateFieldGet(this, _BatchFlusher_tables, "f").get(table)?.state ?? 'idle';
+    }
+    lastErrorOf(table) {
+        return __classPrivateFieldGet(this, _BatchFlusher_tables, "f").get(table)?.lastError;
+    }
+    /** Consecutive failures (reset on any success). */
+    failureCountOf(table) {
+        return __classPrivateFieldGet(this, _BatchFlusher_tables, "f").get(table)?.failureCount ?? 0;
+    }
+    /**
+     * Single flush attempt (no retry). Used directly by explicit user code and
+     * indirectly by `scheduleFlush` for the retry loop.
+     */
+    async flush(table, reason = 'manual') {
+        const state = __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_ensureState).call(this, table);
+        state.state = 'flushing';
+        const drained = await __classPrivateFieldGet(this, _BatchFlusher_buffer, "f").drain(table);
+        if (drained.length === 0) {
+            state.state = state.failureCount > 0 ? 'error' : 'idle';
+            return { table, rowsFlushed: 0, ok: true };
+        }
+        try {
+            const rowsFlushed = __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_writeToAppender).call(this, table, drained);
+            state.failureCount = 0;
+            state.lastError = undefined;
+            state.state = 'idle';
+            __classPrivateFieldGet(this, _BatchFlusher_emit, "f")?.call(this, { type: 'flushed', payload: { table, rowsFlushed, reason } });
+            return { table, rowsFlushed, ok: true };
+        }
+        catch (cause) {
+            // Return drained rows to the front of the ring so retries see them.
+            await __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_restore).call(this, table, drained);
+            const err = cause instanceof SyncError
+                ? cause
+                : new SyncError('flush_failed', `flush failed for ${table}`, cause);
+            state.failureCount += 1;
+            state.lastError = err;
+            state.state = 'error';
+            __classPrivateFieldGet(this, _BatchFlusher_emit, "f")?.call(this, { type: 'flush-failed', payload: { table, error: err } });
+            return { table, rowsFlushed: 0, ok: false, error: err };
+        }
+    }
+    /**
+     * Enqueue a flush with retry orchestration. Non-blocking — returns the
+     * promise for callers that want to await final resolution.
+     */
+    scheduleFlush(table, reason) {
+        const priority = PRIORITY_BY_REASON[reason];
+        return __classPrivateFieldGet(this, _BatchFlusher_queue, "f").add(() => __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_runWithRetry).call(this, table, reason), { priority })
+            // p-queue's typings make add() return `Promise<T | void>`; we always
+            // resolve with a FlushResult so this cast is safe.
+            .then(r => r);
+    }
+    /** Wait until every in-flight + queued flush settles. */
+    async drainQueue() {
+        await __classPrivateFieldGet(this, _BatchFlusher_queue, "f").onIdle();
+    }
+    /** Pause the queue — new `scheduleFlush()` calls enqueue but don't run. */
+    pauseQueue() {
+        __classPrivateFieldGet(this, _BatchFlusher_queue, "f").pause();
+    }
+    /** Resume a paused queue. */
+    resumeQueue() {
+        __classPrivateFieldGet(this, _BatchFlusher_queue, "f").start();
+    }
+}
+_BatchFlusher_engine = new WeakMap(), _BatchFlusher_buffer = new WeakMap(), _BatchFlusher_columnOrder = new WeakMap(), _BatchFlusher_queue = new WeakMap(), _BatchFlusher_sleep = new WeakMap(), _BatchFlusher_now = new WeakMap(), _BatchFlusher_emit = new WeakMap(), _BatchFlusher_tables = new WeakMap(), _BatchFlusher_instances = new WeakSet(), _BatchFlusher_runWithRetry = async function _BatchFlusher_runWithRetry(table, reason) {
+    let lastResult = { table, rowsFlushed: 0, ok: false };
+    for (let attempt = 0; attempt < BACKOFF_SEQUENCE_MS.length; attempt++) {
+        const result = await __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_flushWithTimeout).call(this, table, reason);
+        lastResult = result;
+        if (result.ok)
+            return result;
+        const failures = this.failureCountOf(table);
+        if (failures >= MAX_CONSECUTIVE_FAILURES) {
+            // Terminal for this scheduled run. The `error` state persists on the
+            // table until an explicit `flush()` succeeds.
+            return result;
+        }
+        await __classPrivateFieldGet(this, _BatchFlusher_sleep, "f").call(this, BACKOFF_SEQUENCE_MS[attempt]);
+    }
+    return lastResult;
+}, _BatchFlusher_flushWithTimeout = async function _BatchFlusher_flushWithTimeout(table, reason) {
+    const attempt = this.flush(table, reason);
+    let timeoutId;
+    const timeout = new Promise((resolve) => {
+        timeoutId = setTimeout(() => {
+            const err = new SyncError('flush_failed', `flush timed out after ${FLUSH_TIMEOUT_MS}ms for ${table}`);
+            const state = __classPrivateFieldGet(this, _BatchFlusher_instances, "m", _BatchFlusher_ensureState).call(this, table);
+            state.failureCount += 1;
+            state.lastError = err;
+            state.state = 'error';
+            __classPrivateFieldGet(this, _BatchFlusher_emit, "f")?.call(this, { type: 'flush-failed', payload: { table, error: err } });
+            resolve({ table, rowsFlushed: 0, ok: false, error: err });
+        }, FLUSH_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([attempt, timeout]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}, _BatchFlusher_writeToAppender = function _BatchFlusher_writeToAppender(table, entries) {
+    const cols = __classPrivateFieldGet(this, _BatchFlusher_columnOrder, "f")[table];
+    if (!cols) {
+        throw new SyncError('flush_failed', `no columnOrder registered for table "${table}"`);
+    }
+    const appender = __classPrivateFieldGet(this, _BatchFlusher_engine, "f").createAppender(table);
+    let rowsWritten = 0;
+    try {
+        for (const entry of entries) {
+            for (const row of entry.rows) {
+                appender.appendRow(cols.map(c => row[c] ?? null));
+                rowsWritten += 1;
+            }
+        }
+        appender.flush();
+        return rowsWritten;
+    }
+    finally {
+        try {
+            appender.close();
+        }
+        catch {
+            // Swallow close errors — the surfaced error should be the write.
+        }
+    }
+}, _BatchFlusher_restore = async function _BatchFlusher_restore(table, entries) {
+    // Cheapest recovery: re-push each entry as a fresh batch. Preserves rows
+    // but reorders enqueuedAt — acceptable, since data survives.
+    for (const entry of entries) {
+        await __classPrivateFieldGet(this, _BatchFlusher_buffer, "f").push({
+            table,
+            brand: entry.brand,
+            familyId: entry.familyId,
+            userId: entry.userId,
+            deviceId: entry.deviceId,
+            rows: entry.rows,
+        });
+    }
+}, _BatchFlusher_ensureState = function _BatchFlusher_ensureState(table) {
+    let state = __classPrivateFieldGet(this, _BatchFlusher_tables, "f").get(table);
+    if (!state) {
+        state = { failureCount: 0, state: 'idle' };
+        __classPrivateFieldGet(this, _BatchFlusher_tables, "f").set(table, state);
+    }
+    return state;
+};
+function defaultSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=flusher.js.map

package/dist/sync/flusher.js.map

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

package/dist/sync/hooks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * T-27 — React hooks over the SyncManager.
+ *
+ * `useSensorSink` returns the manager's memoised sink handle.
+ * `useSyncState` / `useSyncProgress` bind `useSyncExternalStore` to the manager
+ * subscribe fan-out. Each hook keeps a cached snapshot updated only inside the
+ * subscribe callback so `getSnapshot` returns a stable reference between
+ * transitions (React's snapshot-equality check requires this).
+ */
+import type { SensorSink, SyncManagerState, SyncProgress } from './manager';
+/** Subscribe to the manager's aggregate scheduler state. */
+export declare function useSyncState(): SyncManagerState;
+/** Returns the SensorSink handle — memoised for the lifetime of the manager. */
+export declare function useSensorSink(): SensorSink;
+/** Progress snapshot: pending row counts + last flush / sync-complete stamps. */
+export declare function useSyncProgress(): SyncProgress;
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/sync/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAe,gBAAgB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExF,4DAA4D;AAC5D,wBAAgB,YAAY,IAAI,gBAAgB,CAI/C;AAED,gFAAgF;AAChF,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED,iFAAiF;AACjF,wBAAgB,eAAe,IAAI,YAAY,CAI9C"}

package/dist/sync/hooks.js

@@ -0,0 +1,48 @@
+/**
+ * T-27 — React hooks over the SyncManager.
+ *
+ * `useSensorSink` returns the manager's memoised sink handle.
+ * `useSyncState` / `useSyncProgress` bind `useSyncExternalStore` to the manager
+ * subscribe fan-out. Each hook keeps a cached snapshot updated only inside the
+ * subscribe callback so `getSnapshot` returns a stable reference between
+ * transitions (React's snapshot-equality check requires this).
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+import { useSyncManager } from './context';
+/** Subscribe to the manager's aggregate scheduler state. */
+export function useSyncState() {
+    const manager = useSyncManager();
+    const cache = useMemo(() => makeStateCache(manager), [manager]);
+    return useSyncExternalStore(cache.subscribe, cache.get, cache.get);
+}
+/** Returns the SensorSink handle — memoised for the lifetime of the manager. */
+export function useSensorSink() {
+    return useSyncManager().sink;
+}
+/** Progress snapshot: pending row counts + last flush / sync-complete stamps. */
+export function useSyncProgress() {
+    const manager = useSyncManager();
+    const cache = useMemo(() => makeProgressCache(manager), [manager]);
+    return useSyncExternalStore(cache.subscribe, cache.get, cache.get);
+}
+function makeStateCache(manager) {
+    let snapshot = manager.state();
+    return {
+        subscribe: (onStoreChange) => manager.subscribe((next) => {
+            snapshot = next;
+            onStoreChange();
+        }),
+        get: () => snapshot,
+    };
+}
+function makeProgressCache(manager) {
+    let snapshot = manager.progress();
+    return {
+        subscribe: (onStoreChange) => manager.subscribe(() => {
+            snapshot = manager.progress();
+            onStoreChange();
+        }),
+        get: () => snapshot,
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/sync/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/sync/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAG1C,4DAA4D;AAC5D,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAA;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/D,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;AACpE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa;IAC3B,OAAO,cAAc,EAAE,CAAC,IAAI,CAAA;AAC9B,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,cAAc,EAAE,CAAA;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;IAClE,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;AACpE,CAAC;AAOD,SAAS,cAAc,CAAC,OAAoB;IAC1C,IAAI,QAAQ,GAAG,OAAO,CAAC,KAAK,EAAE,CAAA;IAC9B,OAAO;QACL,SAAS,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACvD,QAAQ,GAAG,IAAI,CAAA;YACf,aAAa,EAAE,CAAA;QACjB,CAAC,CAAC;QACF,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ;KACpB,CAAA;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAoB;IAC7C,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAA;IACjC,OAAO;QACL,SAAS,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE;YACnD,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAA;YAC7B,aAAa,EAAE,CAAA;QACjB,CAAC,CAAC;QACF,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ;KACpB,CAAA;AACH,CAAC"}

package/dist/sync/index.d.ts

@@ -1,2 +1,33 @@
-export {};
+/**
+ * @mongrov/analytics/sync — public barrel.
+ *
+ * Phases A–C: mapper + buffer + flusher surfaces. Pusher/fetcher/scheduler
+ * ship in subsequent phases (see `.specifica/features/analytics-sync/tasks.md`).
+ */
+export { SensorBuffer, type SensorBufferConfig } from './buffer';
+export { OverflowStore } from './overflow';
+export type { BufferEntry, BufferSize, FlushResult, OverflowPolicy, SensorBatch, } from './types';
+export { type WatermarkKind, WatermarkStore, type WatermarkStoreConfig, } from './watermark';
+export { type PushResult, R2Pusher, type R2PusherConfig, } from './pusher';
+export { type FetchParams, type FetchResult, type PrefetchPolicy, R2Fetcher, type R2FetcherConfig, } from './fetcher';
+export { BACKOFF_SEQUENCE_MS, BatchFlusher, type BatchFlusherConfig, FLUSH_TIMEOUT_MS, type FlushReason, type FlushedEvent, MAX_CONSECUTIVE_FAILURES, type FlusherState, type SyncEmitter, } from './flusher';
+export { SyncError, type SyncErrorCode } from './errors';
+export { DEFAULT_MAX_AGE_MS, DEFAULT_MAX_ROWS, FlushTriggers, type FlushTriggersConfig, } from './triggers';
+export { createSyncManager, type CreateSyncManagerConfig } from './factory';
+export type { SensorSink, SyncManager, SyncManagerState, SyncProgress, } from './manager';
+export { SyncProvider, type SyncProviderProps, useSyncManager } from './context';
+export { useSensorSink, useSyncProgress, useSyncState } from './hooks';
+export { bindFlushEvents, bindPushEvents, type EventBus, type FlushInsertPayload, type PushEmitter, type SyncCompletePayload, } from './events';
+export { type BackgroundTaskPort, type ConstraintPort, type CycleResult, type SchedulerConstraints, type SchedulerLogger, type SchedulerState, type SyncCoordinator, SyncScheduler, type SyncSchedulerConfig, } from './scheduler';
+export { mapActivity, type MapActivityResult } from './mapper/activity';
+export { BATTERY_EVENT, mapBattery } from './mapper/battery';
+export { type FirmwareMappedBatch, mapFirmwareExport, type MapFirmwareOptions, } from './mapper/firmware';
+export { mapHeartRate } from './mapper/heart-rate';
+export { mapHrv } from './mapper/hrv';
+export { type MapRingConfigResult, mapRingConfig, type RingConfigClose, } from './mapper/ring-config';
+export { type ReconstructSleepResult, reconstructSleepSessions, } from './mapper/sleep';
+export { mapSpo2 } from './mapper/spo2';
+export { mapTemperature } from './mapper/temperature';
+export { computeNightOf, parseTimestamp } from './mapper/time';
+export type { ActivityBucketRow, ActivityRow, DeviceConfigRow, DeviceEventRow, FirmwareActivityRow, FirmwareBatteryRow, FirmwareExport, FirmwareHRRow, FirmwareHRVRow, FirmwareMonitoringWindow, FirmwareRingConfig, FirmwareSleepRow, FirmwareSpO2Row, FirmwareTempRow, HeartRateRow, HrvRow, MappedBatch, MapperContext, SleepRawRow, SleepSessionRow, SleepStageRow, Spo2Row, TemperatureRow, } from './mapper/types';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/sync/index.js

@@ -1,2 +1,37 @@
-export {};
+/**
+ * @mongrov/analytics/sync — public barrel.
+ *
+ * Phases A–C: mapper + buffer + flusher surfaces. Pusher/fetcher/scheduler
+ * ship in subsequent phases (see `.specifica/features/analytics-sync/tasks.md`).
+ */
+// Buffer + overflow (Phase B).
+export { SensorBuffer } from './buffer';
+export { OverflowStore } from './overflow';
+// Watermark + pusher + fetcher (Phase D+E+F).
+export { WatermarkStore, } from './watermark';
+export { R2Pusher, } from './pusher';
+export { R2Fetcher, } from './fetcher';
+// Flusher + triggers (Phase C).
+export { BACKOFF_SEQUENCE_MS, BatchFlusher, FLUSH_TIMEOUT_MS, MAX_CONSECUTIVE_FAILURES, } from './flusher';
+export { SyncError } from './errors';
+export { DEFAULT_MAX_AGE_MS, DEFAULT_MAX_ROWS, FlushTriggers, } from './triggers';
+// Factory + hooks + provider (Phase I).
+export { createSyncManager } from './factory';
+export { SyncProvider, useSyncManager } from './context';
+export { useSensorSink, useSyncProgress, useSyncState } from './hooks';
+// Event bus integration (Phase H).
+export { bindFlushEvents, bindPushEvents, } from './events';
+// Scheduler (Phase G).
+export { SyncScheduler, } from './scheduler';
+// Mappers (Phase A).
+export { mapActivity } from './mapper/activity';
+export { BATTERY_EVENT, mapBattery } from './mapper/battery';
+export { mapFirmwareExport, } from './mapper/firmware';
+export { mapHeartRate } from './mapper/heart-rate';
+export { mapHrv } from './mapper/hrv';
+export { mapRingConfig, } from './mapper/ring-config';
+export { reconstructSleepSessions, } from './mapper/sleep';
+export { mapSpo2 } from './mapper/spo2';
+export { mapTemperature } from './mapper/temperature';
+export { computeNightOf, parseTimestamp } from './mapper/time';
 //# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+BAA+B;AAC/B,OAAO,EAAE,YAAY,EAA2B,MAAM,UAAU,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAS1C,8CAA8C;AAC9C,OAAO,EAEL,cAAc,GAEf,MAAM,aAAa,CAAA;AACpB,OAAO,EAEL,QAAQ,GAET,MAAM,UAAU,CAAA;AACjB,OAAO,EAIL,SAAS,GAEV,MAAM,WAAW,CAAA;AAElB,gCAAgC;AAChC,OAAO,EACL,mBAAmB,EACnB,YAAY,EAEZ,gBAAgB,EAGhB,wBAAwB,GAGzB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAsB,MAAM,UAAU,CAAA;AACxD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GAEd,MAAM,YAAY,CAAA;AAEnB,wCAAwC;AACxC,OAAO,EAAE,iBAAiB,EAAgC,MAAM,WAAW,CAAA;AAO3E,OAAO,EAAE,YAAY,EAA0B,cAAc,EAAE,MAAM,WAAW,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtE,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,cAAc,GAKf,MAAM,UAAU,CAAA;AAEjB,uBAAuB;AACvB,OAAO,EAQL,aAAa,GAEd,MAAM,aAAa,CAAA;AAEpB,qBAAqB;AACrB,OAAO,EAAE,WAAW,EAA0B,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAEL,iBAAiB,GAElB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAEL,aAAa,GAEd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,wBAAwB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/dist/sync/manager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * T-26 — `createSyncManager` return type + shared interfaces.
+ *
+ * The `SyncManager` is the composition root the app holds. It owns the
+ * buffer, flusher, triggers, pusher, fetcher, scheduler, and event bus
+ * plumbing. `SensorSink` is the ergonomic write-side surface consumers see.
+ */
+import type { AnalyticsEngine, AttachContext } from '../core/types';
+import type { BatchFlusher } from './flusher';
+import type { FetchResult, R2Fetcher } from './fetcher';
+import type { FirmwareExport, MapperContext } from './mapper/types';
+import type { R2Pusher } from './pusher';
+import type { CycleResult, SchedulerState, SyncScheduler } from './scheduler';
+import type { FlushResult, SensorBatch } from './types';
+/**
+ * Ergonomic write-side API the app calls from adapters. Matches spec §SensorSink.
+ */
+export interface SensorSink {
+    push: (batch: SensorBatch) => Promise<void>;
+    pushFirmware: (fw: FirmwareExport, ctx: MapperContext) => Promise<void>;
+    flush: () => Promise<FlushResult[]>;
+    pendingRowCount: (table?: string) => Promise<number>;
+    clear: () => Promise<void>;
+}
+export interface SyncManagerState {
+    scheduler: SchedulerState;
+}
+export interface SyncProgress {
+    pendingByTable: Record<string, number>;
+    lastFlushAt?: number;
+    lastSyncCompleteAt?: number;
+}
+export interface SyncManager {
+    readonly analytics: AnalyticsEngine;
+    readonly sink: SensorSink;
+    readonly flusher: BatchFlusher;
+    readonly pusher: R2Pusher;
+    readonly fetcher: R2Fetcher;
+    readonly scheduler: SyncScheduler;
+    state: () => SyncManagerState;
+    progress: () => SyncProgress;
+    subscribe: (fn: (state: SyncManagerState) => void) => () => void;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    triggerNow: () => Promise<CycleResult>;
+    prefetch: (ctx: AttachContext) => Promise<FetchResult[]>;
+}
+//# sourceMappingURL=manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/sync/manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,YAAY,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvE,KAAK,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IACnC,eAAe,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,cAAc,CAAA;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,KAAK,EAAE,MAAM,gBAAgB,CAAA;IAC7B,QAAQ,EAAE,MAAM,YAAY,CAAA;IAC5B,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAChE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,UAAU,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;CACzD"}

package/dist/sync/manager.js

@@ -0,0 +1,9 @@
+/**
+ * T-26 — `createSyncManager` return type + shared interfaces.
+ *
+ * The `SyncManager` is the composition root the app holds. It owns the
+ * buffer, flusher, triggers, pusher, fetcher, scheduler, and event bus
+ * plumbing. `SensorSink` is the ergonomic write-side surface consumers see.
+ */
+export {};
+//# sourceMappingURL=manager.js.map

package/dist/sync/manager.js.map

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

package/dist/sync/mapper/activity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Activity mapper (T-05).
+ *
+ * Firmware `activitydetails` rows aggregate 10 minutes of steps in
+ * `arraySteps[10]` alongside a 10-minute bucket `step` (total), `calories`,
+ * and `distance` (km). We want both granularities in the warehouse:
+ *
+ *   - `activity`         — 1-min rows via `arraySteps` unnest
+ *   - `activity_bucket`  — 10-min rows preserving calories + distance
+ *
+ * Timestamp policy: the firmware `timestamp` marks the start of the 10-min
+ * block. Each unnested activity row is stamped at `base + i minutes` where
+ * `i` is the index into `arraySteps`.
+ *
+ * Known 1.3% mismatch: sum(arraySteps) can drift from `step` (firmware
+ * quirk). Spec calls for "flag in log" — deferred until the SyncLogger wire
+ * lands in Phase C. For now the mapper produces both outputs and the ground
+ * truth in the warehouse is the sum of `activity.steps` per user per
+ * 10-minute window.
+ *
+ * Distance unit: firmware `distance` is passed through as-is into
+ * `distance_km`. If field measurement shows the firmware reports metres, this
+ * mapper is the single place to divide.
+ */
+import type { ActivityBucketRow, ActivityRow, FirmwareActivityRow, MapperContext } from './types';
+export interface MapActivityResult {
+    activity: ActivityRow[];
+    activity_bucket: ActivityBucketRow[];
+}
+export declare function mapActivity(rows: readonly FirmwareActivityRow[], ctx: MapperContext): MapActivityResult;
+//# sourceMappingURL=activity.d.ts.map

package/dist/sync/mapper/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/sync/mapper/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACd,MAAM,SAAS,CAAA;AAEhB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,eAAe,EAAE,iBAAiB,EAAE,CAAA;CACrC;AAID,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,mBAAmB,EAAE,EACpC,GAAG,EAAE,aAAa,GACjB,iBAAiB,CA8BnB"}

package/dist/sync/mapper/activity.js

@@ -0,0 +1,56 @@
+/**
+ * Activity mapper (T-05).
+ *
+ * Firmware `activitydetails` rows aggregate 10 minutes of steps in
+ * `arraySteps[10]` alongside a 10-minute bucket `step` (total), `calories`,
+ * and `distance` (km). We want both granularities in the warehouse:
+ *
+ *   - `activity`         — 1-min rows via `arraySteps` unnest
+ *   - `activity_bucket`  — 10-min rows preserving calories + distance
+ *
+ * Timestamp policy: the firmware `timestamp` marks the start of the 10-min
+ * block. Each unnested activity row is stamped at `base + i minutes` where
+ * `i` is the index into `arraySteps`.
+ *
+ * Known 1.3% mismatch: sum(arraySteps) can drift from `step` (firmware
+ * quirk). Spec calls for "flag in log" — deferred until the SyncLogger wire
+ * lands in Phase C. For now the mapper produces both outputs and the ground
+ * truth in the warehouse is the sum of `activity.steps` per user per
+ * 10-minute window.
+ *
+ * Distance unit: firmware `distance` is passed through as-is into
+ * `distance_km`. If field measurement shows the firmware reports metres, this
+ * mapper is the single place to divide.
+ */
+import { parseTimestamp } from './time';
+const MINUTE_MS = 60000;
+export function mapActivity(rows, ctx) {
+    const activity = [];
+    const activity_bucket = [];
+    for (const row of rows) {
+        const baseTs = parseTimestamp(row.timestamp);
+        const steps = row.arraySteps ?? [];
+        for (let i = 0; i < steps.length; i++) {
+            activity.push({
+                ts: new Date(baseTs.getTime() + i * MINUTE_MS),
+                brand: ctx.brand,
+                family_id: ctx.familyId,
+                user_id: ctx.userId,
+                device_id: ctx.deviceId,
+                steps: steps[i],
+            });
+        }
+        activity_bucket.push({
+            ts: baseTs,
+            brand: ctx.brand,
+            family_id: ctx.familyId,
+            user_id: ctx.userId,
+            device_id: ctx.deviceId,
+            steps: row.step,
+            calories: row.calories,
+            distance_km: row.distance,
+        });
+    }
+    return { activity, activity_bucket };
+}
+//# sourceMappingURL=activity.js.map

package/dist/sync/mapper/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../../../src/sync/mapper/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAavC,MAAM,SAAS,GAAG,KAAM,CAAA;AAExB,MAAM,UAAU,WAAW,CACzB,IAAoC,EACpC,GAAkB;IAElB,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAClC,MAAM,eAAe,GAAwB,EAAE,CAAA;IAE/C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAA;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,QAAQ,CAAC,IAAI,CAAC;gBACZ,EAAE,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;gBAC9C,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS,EAAE,GAAG,CAAC,QAAQ;gBACvB,OAAO,EAAE,GAAG,CAAC,MAAM;gBACnB,SAAS,EAAE,GAAG,CAAC,QAAQ;gBACvB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;aAChB,CAAC,CAAA;QACJ,CAAC;QACD,eAAe,CAAC,IAAI,CAAC;YACnB,EAAE,EAAE,MAAM;YACV,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,SAAS,EAAE,GAAG,CAAC,QAAQ;YACvB,OAAO,EAAE,GAAG,CAAC,MAAM;YACnB,SAAS,EAAE,GAAG,CAAC,QAAQ;YACvB,KAAK,EAAE,GAAG,CAAC,IAAI;YACf,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,WAAW,EAAE,GAAG,CAAC,QAAQ;SAC1B,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAA;AACtC,CAAC"}

package/dist/sync/mapper/battery.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Battery mapper (T-07).
+ *
+ * Firmware `battery_table` rows lift into the generic `device_event` stream
+ * with `event_type='battery_sample'`. The battery level lives in the JSON
+ * payload column so the `device_event` table doesn't grow bespoke columns
+ * for every metric variant.
+ */
+import type { DeviceEventRow, FirmwareBatteryRow, MapperContext } from './types';
+export declare const BATTERY_EVENT = "battery_sample";
+export declare function mapBattery(rows: readonly FirmwareBatteryRow[], ctx: MapperContext): DeviceEventRow[];
+//# sourceMappingURL=battery.d.ts.map

package/dist/sync/mapper/battery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"battery.d.ts","sourceRoot":"","sources":["../../../src/sync/mapper/battery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,aAAa,EACd,MAAM,SAAS,CAAA;AAEhB,eAAO,MAAM,aAAa,mBAAmB,CAAA;AAE7C,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,GAAG,EAAE,aAAa,GACjB,cAAc,EAAE,CAUlB"}

package/dist/sync/mapper/battery.js

@@ -0,0 +1,22 @@
+/**
+ * Battery mapper (T-07).
+ *
+ * Firmware `battery_table` rows lift into the generic `device_event` stream
+ * with `event_type='battery_sample'`. The battery level lives in the JSON
+ * payload column so the `device_event` table doesn't grow bespoke columns
+ * for every metric variant.
+ */
+import { parseTimestamp } from './time';
+export const BATTERY_EVENT = 'battery_sample';
+export function mapBattery(rows, ctx) {
+    return rows.map(row => ({
+        ts: parseTimestamp(row.timestamp),
+        brand: ctx.brand,
+        family_id: ctx.familyId,
+        user_id: ctx.userId,
+        device_id: ctx.deviceId,
+        event_type: BATTERY_EVENT,
+        payload: { battery: row.battery },
+    }));
+}
+//# sourceMappingURL=battery.js.map

package/dist/sync/mapper/battery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"battery.js","sourceRoot":"","sources":["../../../src/sync/mapper/battery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAOvC,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAE7C,MAAM,UAAU,UAAU,CACxB,IAAmC,EACnC,GAAkB;IAElB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtB,EAAE,EAAE,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC;QACjC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,GAAG,CAAC,QAAQ;QACvB,OAAO,EAAE,GAAG,CAAC,MAAM;QACnB,SAAS,EAAE,GAAG,CAAC,QAAQ;QACvB,UAAU,EAAE,aAAa;QACzB,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;KAClC,CAAC,CAAC,CAAA;AACL,CAAC"}