@mongrov/analytics 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/sync/factory.js

@@ -0,0 +1,279 @@
+/**
+ * T-26 — `createSyncManager()` factory.
+ *
+ * Zod-validates config at construction time (fail-fast), then assembles the
+ * full sync stack:
+ *
+ *   OverflowStore ← storage KV
+ *   SensorBuffer  ← OverflowStore + policy + byte budget
+ *   BatchFlusher  ← engine + buffer + columnOrder + optional event bus
+ *   FlushTriggers ← buffer + flusher + row/age thresholds
+ *   WatermarkStore← storage KV
+ *   R2Pusher      ← engine + WatermarkStore + optional refreshToken + event bus
+ *   R2Fetcher     ← engine + WatermarkStore + tables + prefetchPolicy
+ *   SyncScheduler ← wires flush + push + fetch into a background cycle
+ *
+ * The returned `SyncManager` exposes a compact `SensorSink` + scheduler
+ * controls; hooks in `hooks.ts` subscribe to state transitions.
+ */
+import { z } from 'zod';
+import { SensorBuffer } from './buffer';
+import { bindFlushEvents, bindPushEvents } from './events';
+import { R2Fetcher } from './fetcher';
+import { BatchFlusher } from './flusher';
+import { mapFirmwareExport } from './mapper/firmware';
+import { OverflowStore } from './overflow';
+import { R2Pusher } from './pusher';
+import { SyncScheduler, } from './scheduler';
+import { FlushTriggers } from './triggers';
+import { WatermarkStore } from './watermark';
+const overflowPolicyEnum = z.enum(['drop-oldest', 'drop-newest', 'block']);
+const prefetchPolicySchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('all-family-on-attach'), windowDays: z.number().int().positive() }),
+    z.object({
+        kind: z.literal('recent-active-only'),
+        activeDays: z.number().int().positive(),
+        windowDays: z.number().int().positive(),
+    }),
+    z.object({ kind: z.literal('lazy') }),
+]);
+const configSchema = z.object({
+    tables: z.array(z.string().min(1)).min(1),
+    columnOrder: z.record(z.string(), z.array(z.string()).readonly()),
+    prefetchPolicy: prefetchPolicySchema,
+    flush: z.object({
+        maxRows: z.number().int().positive().optional(),
+        maxAgeMs: z.number().int().positive().optional(),
+        concurrency: z.number().int().positive().optional(),
+    }).optional(),
+    overflow: z.object({
+        maxBufferBytes: z.number().int().positive().optional(),
+        policy: overflowPolicyEnum.optional(),
+    }).optional(),
+    scheduler: z.object({
+        requiresCharging: z.boolean().optional(),
+        requiresWifi: z.boolean().optional(),
+        taskName: z.string().optional(),
+    }).optional(),
+});
+/**
+ * Assemble a fully wired `SyncManager`. Throws `z.ZodError` if the config is
+ * malformed (e.g., missing columnOrder entries or negative row limits).
+ */
+export function createSyncManager(config) {
+    configSchema.parse({
+        tables: config.tables,
+        columnOrder: config.columnOrder,
+        prefetchPolicy: config.prefetchPolicy,
+        flush: config.flush,
+        overflow: config.overflow,
+        scheduler: config.scheduler,
+    });
+    const overflow = new OverflowStore(config.storage);
+    const buffer = new SensorBuffer({
+        overflow,
+        maxBufferBytes: config.overflow?.maxBufferBytes,
+        policy: config.overflow?.policy,
+    });
+    const progress = { pendingByTable: {} };
+    const busFlushEmit = config.eventBus ? bindFlushEvents(config.eventBus) : undefined;
+    // Compose the flusher emitter with local progress tracking so hooks + the
+    // event bus both see every event. When a rules engine is provided, `flushed`
+    // events also drive `evaluateOnBatch` — fire-and-forget so a slow evaluator
+    // never stalls sync.
+    const rulesEngine = config.rulesEngine;
+    const rulesLogger = config.logger;
+    const flushEmitter = (event) => {
+        if (event.type === 'flushed') {
+            progress.pendingByTable[event.payload.table] = 0;
+            progress.lastFlushAt = Date.now();
+            if (rulesEngine && event.payload.affectedUserIds.length > 0) {
+                rulesEngine.evaluateOnBatch({
+                    affectedUserIds: event.payload.affectedUserIds,
+                    affectedTables: [event.payload.table],
+                }).catch((err) => {
+                    rulesLogger?.warn('sync.factory: rulesEngine.evaluateOnBatch threw', {
+                        table: event.payload.table,
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+        }
+        busFlushEmit?.(event);
+    };
+    const engineAsHybrid = config.analytics;
+    const flusher = new BatchFlusher({
+        engine: engineAsHybrid,
+        buffer,
+        columnOrder: config.columnOrder,
+        concurrency: config.flush?.concurrency,
+        emit: flushEmitter,
+    });
+    const triggers = new FlushTriggers({
+        buffer,
+        flusher,
+        maxRows: config.flush?.maxRows,
+        maxAgeMs: config.flush?.maxAgeMs,
+    });
+    const watermark = new WatermarkStore({ kv: config.storage });
+    const busPushEmit = config.eventBus ? bindPushEvents(config.eventBus) : undefined;
+    const pusher = new R2Pusher({
+        engine: engineAsHybrid,
+        watermark,
+        refreshToken: config.refreshToken,
+        emit: (result) => {
+            if (result.ok && result.rowsPushed > 0) {
+                progress.lastSyncCompleteAt = Date.now();
+            }
+            busPushEmit?.(result);
+        },
+    });
+    const fetcher = new R2Fetcher({
+        engine: engineAsHybrid,
+        watermark,
+        tables: [...config.tables],
+    });
+    const scheduler = new SyncScheduler({
+        backgroundTask: config.backgroundTask ?? noopBackgroundTask(),
+        constraints: config.constraints ?? alwaysAllowedConstraints(),
+        coordinator: {
+            flushAll: async () => {
+                await Promise.all(config.tables.map(t => flusher.flush(t, 'scheduled')));
+            },
+            pushAll: async (tables, ctx) => pusher.pushAll(tables, ctx),
+            fetchIncremental: async (ctx) => fetcher.fetchIncremental(ctx),
+            // Scheduled rules pass runs after the cycle's flush/push/fetch. Fire-
+            // and-forget — a throw here would surface as a cycle error, but the
+            // catch keeps the scheduler idle.
+            onCycleComplete: rulesEngine
+                ? async () => {
+                    try {
+                        await rulesEngine.evaluateScheduled();
+                    }
+                    catch (err) {
+                        rulesLogger?.warn('sync.factory: rulesEngine.evaluateScheduled threw', {
+                            err: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+                : undefined,
+        },
+        tables: [...config.tables],
+        ctx: config.ctx,
+        taskName: config.scheduler?.taskName,
+        constraintPolicy: {
+            requireCharging: config.scheduler?.requiresCharging,
+            requireWifi: config.scheduler?.requiresWifi,
+        },
+        logger: config.logger,
+    });
+    const state = {
+        scheduler: 'idle',
+    };
+    const subscribers = new Set();
+    const notify = () => {
+        for (const fn of subscribers)
+            fn(state);
+    };
+    scheduler.subscribe((next) => {
+        state.scheduler = next;
+        notify();
+    });
+    const sink = createSensorSink({ buffer, flusher, triggers, tables: config.tables });
+    return {
+        analytics: config.analytics,
+        sink,
+        flusher,
+        pusher,
+        fetcher,
+        scheduler,
+        state: () => ({ ...state }),
+        progress: () => ({
+            pendingByTable: { ...progress.pendingByTable },
+            lastFlushAt: progress.lastFlushAt,
+            lastSyncCompleteAt: progress.lastSyncCompleteAt,
+        }),
+        subscribe: (fn) => {
+            subscribers.add(fn);
+            return () => subscribers.delete(fn);
+        },
+        start: async () => {
+            await scheduler.start();
+        },
+        stop: async () => {
+            await scheduler.stop();
+        },
+        triggerNow: () => scheduler.triggerNow(),
+        prefetch: (ctx) => fetcher.prefetchOnAttach(ctx, config.prefetchPolicy),
+    };
+}
+function createSensorSink({ buffer, flusher, triggers, tables }) {
+    return {
+        push: async (batch) => {
+            await buffer.push(batch);
+            triggers.noteEnqueue(batch.table, Date.now());
+        },
+        pushFirmware: async (fw, ctx) => {
+            const mapped = mapFirmwareExport(fw, ctx);
+            const asRows = (rows) => rows;
+            const mappedTables = [
+                ['hrv', asRows(mapped.hrv)],
+                ['heart_rate', asRows(mapped.heart_rate)],
+                ['spo2', asRows(mapped.spo2)],
+                ['temperature', asRows(mapped.temperature)],
+                ['activity', asRows(mapped.activity)],
+                ['activity_bucket', asRows(mapped.activity_bucket)],
+                ['sleep_session', asRows(mapped.sleep_session)],
+                ['sleep_stage', asRows(mapped.sleep_stage)],
+                ['sleep_raw', asRows(mapped.sleep_raw)],
+                ['device_event', asRows(mapped.device_event)],
+                ['device_config', asRows(mapped.device_config)],
+            ];
+            for (const [table, rows] of mappedTables) {
+                if (!rows || rows.length === 0)
+                    continue;
+                await buffer.push({
+                    table,
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                    userId: ctx.userId,
+                    deviceId: ctx.deviceId,
+                    rows,
+                });
+                triggers.noteEnqueue(table, Date.now());
+            }
+        },
+        flush: async () => {
+            const results = [];
+            for (const table of tables) {
+                results.push(await flusher.flush(table, 'manual'));
+                triggers.noteDrain(table);
+            }
+            return results;
+        },
+        pendingRowCount: async (table) => {
+            const s = await buffer.size(table);
+            return s.inMemory + s.overflow;
+        },
+        clear: async () => {
+            await buffer.clear();
+            for (const t of tables)
+                triggers.noteDrain(t);
+        },
+    };
+}
+function noopBackgroundTask() {
+    const handlers = new Map();
+    return {
+        register: async (name, handler) => { handlers.set(name, handler); },
+        unregister: async (name) => { handlers.delete(name); },
+        isRegistered: async (name) => handlers.has(name),
+    };
+}
+function alwaysAllowedConstraints() {
+    return {
+        isCharging: async () => true,
+        isOnWifi: async () => true,
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/sync/factory.js.map

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

package/dist/sync/fetcher.d.ts

@@ -0,0 +1,74 @@
+/**
+ * R2 fetcher (T-19 + T-20 + T-21).
+ *
+ * Reads-back path from the attached R2 Iceberg zone into the local DuckDB
+ * warehouse.
+ *
+ * Three modes:
+ *   - `prefetchOnAttach(ctx, policy)` — one-shot bulk pull immediately after
+ *     `analytics.attach()`, driven by a policy:
+ *       * `all-family-on-attach` — every family row within `windowDays`
+ *       * `recent-active-only`   — active users first (CTE)
+ *       * `lazy`                 — no-op
+ *   - `fetchIncremental(ctx)`  — pulls only rows newer than the fetch
+ *     watermark; `ON CONFLICT DO NOTHING` keeps re-runs idempotent.
+ *   - `fetchOnDemand(ctx, params)` — bypasses watermark; caller-supplied
+ *     bounds (`since`, optional `until`, optional `limit`).
+ *
+ * Every path advances the fetch watermark on success so subsequent
+ * incremental pulls stay bounded.
+ */
+import type { HybridDuckDB } from '../core/engine';
+import type { AttachContext } from '../core/types';
+import { SyncError } from './errors';
+import type { WatermarkStore } from './watermark';
+export type PrefetchPolicy = {
+    kind: 'all-family-on-attach';
+    windowDays: number;
+} | {
+    kind: 'recent-active-only';
+    activeDays: number;
+    windowDays: number;
+} | {
+    kind: 'lazy';
+};
+export interface FetchResult {
+    table: string;
+    rowsFetched: number;
+    ok: boolean;
+    error?: SyncError;
+}
+export interface FetchParams {
+    table: string;
+    since: Date;
+    until?: Date;
+    limit?: number;
+}
+export interface R2FetcherConfig {
+    engine: HybridDuckDB;
+    watermark: WatermarkStore;
+    /** Tables that participate in prefetch / incremental fetch. */
+    tables: readonly string[];
+    now?: () => Date;
+    localTable?: (ctx: AttachContext, table: string) => string;
+    remoteTable?: (ctx: AttachContext, table: string) => string;
+}
+export declare class R2Fetcher {
+    #private;
+    constructor(config: R2FetcherConfig);
+    /**
+     * T-19: one-shot bulk fetch keyed by policy. Returns per-table results so
+     * partial failure is observable.
+     */
+    prefetchOnAttach(ctx: AttachContext, policy: PrefetchPolicy): Promise<FetchResult[]>;
+    /**
+     * T-20: pulls only rows newer than the fetch watermark; idempotent.
+     */
+    fetchIncremental(ctx: AttachContext): Promise<FetchResult[]>;
+    /**
+     * T-21: caller-driven fetch that bypasses the watermark. Advances the
+     * fetch watermark only if the pulled range extends past the current one.
+     */
+    fetchOnDemand(ctx: AttachContext, params: FetchParams): Promise<FetchResult>;
+}
+//# sourceMappingURL=fetcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/sync/fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,MAAM,MAAM,cAAc,GACpB;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,IAAI,CAAA;IACX,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,cAAc,CAAA;IACzB,+DAA+D;IAC/D,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAC5D;AAMD,qBAAa,SAAS;;gBAQR,MAAM,EAAE,eAAe;IASnC;;;OAGG;IACG,gBAAgB,CACpB,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,WAAW,EAAE,CAAC;IAoBzB;;OAEG;IACG,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAWlE;;;OAGG;IACG,aAAa,CACjB,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC;CAuIxB"}

package/dist/sync/fetcher.js

@@ -0,0 +1,166 @@
+/**
+ * R2 fetcher (T-19 + T-20 + T-21).
+ *
+ * Reads-back path from the attached R2 Iceberg zone into the local DuckDB
+ * warehouse.
+ *
+ * Three modes:
+ *   - `prefetchOnAttach(ctx, policy)` — one-shot bulk pull immediately after
+ *     `analytics.attach()`, driven by a policy:
+ *       * `all-family-on-attach` — every family row within `windowDays`
+ *       * `recent-active-only`   — active users first (CTE)
+ *       * `lazy`                 — no-op
+ *   - `fetchIncremental(ctx)`  — pulls only rows newer than the fetch
+ *     watermark; `ON CONFLICT DO NOTHING` keeps re-runs idempotent.
+ *   - `fetchOnDemand(ctx, params)` — bypasses watermark; caller-supplied
+ *     bounds (`since`, optional `until`, optional `limit`).
+ *
+ * Every path advances the fetch watermark on success so subsequent
+ * incremental pulls stay bounded.
+ */
+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 _R2Fetcher_instances, _R2Fetcher_engine, _R2Fetcher_watermark, _R2Fetcher_tables, _R2Fetcher_now, _R2Fetcher_localTable, _R2Fetcher_remoteTable, _R2Fetcher_prefetchOne, _R2Fetcher_fetchIncrementalOne, _R2Fetcher_countFetched, _R2Fetcher_toFailure;
+import { SyncError } from './errors';
+const DEFAULT_LOCAL = (_c, table) => `main.${table}`;
+const DEFAULT_REMOTE = (c, table) => `zone_${c.tenantId}.${table}`;
+export class R2Fetcher {
+    constructor(config) {
+        _R2Fetcher_instances.add(this);
+        _R2Fetcher_engine.set(this, void 0);
+        _R2Fetcher_watermark.set(this, void 0);
+        _R2Fetcher_tables.set(this, void 0);
+        _R2Fetcher_now.set(this, void 0);
+        _R2Fetcher_localTable.set(this, void 0);
+        _R2Fetcher_remoteTable.set(this, void 0);
+        __classPrivateFieldSet(this, _R2Fetcher_engine, config.engine, "f");
+        __classPrivateFieldSet(this, _R2Fetcher_watermark, config.watermark, "f");
+        __classPrivateFieldSet(this, _R2Fetcher_tables, config.tables, "f");
+        __classPrivateFieldSet(this, _R2Fetcher_now, config.now ?? (() => new Date()), "f");
+        __classPrivateFieldSet(this, _R2Fetcher_localTable, config.localTable ?? DEFAULT_LOCAL, "f");
+        __classPrivateFieldSet(this, _R2Fetcher_remoteTable, config.remoteTable ?? DEFAULT_REMOTE, "f");
+    }
+    /**
+     * T-19: one-shot bulk fetch keyed by policy. Returns per-table results so
+     * partial failure is observable.
+     */
+    async prefetchOnAttach(ctx, policy) {
+        if (policy.kind === 'lazy') {
+            return __classPrivateFieldGet(this, _R2Fetcher_tables, "f").map(t => ({ table: t, rowsFetched: 0, ok: true }));
+        }
+        const cutoffMs = __classPrivateFieldGet(this, _R2Fetcher_now, "f").call(this).getTime() - policy.windowDays * 24 * 60 * 60 * 1000;
+        const cutoff = new Date(cutoffMs).toISOString();
+        const settled = await Promise.allSettled(__classPrivateFieldGet(this, _R2Fetcher_tables, "f").map(table => __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_prefetchOne).call(this, ctx, table, policy, cutoff)));
+        return settled.map((r, i) => {
+            const table = __classPrivateFieldGet(this, _R2Fetcher_tables, "f")[i];
+            if (r.status === 'fulfilled')
+                return r.value;
+            return __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_toFailure).call(this, table, r.reason);
+        });
+    }
+    /**
+     * T-20: pulls only rows newer than the fetch watermark; idempotent.
+     */
+    async fetchIncremental(ctx) {
+        const settled = await Promise.allSettled(__classPrivateFieldGet(this, _R2Fetcher_tables, "f").map(table => __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_fetchIncrementalOne).call(this, ctx, table)));
+        return settled.map((r, i) => {
+            const table = __classPrivateFieldGet(this, _R2Fetcher_tables, "f")[i];
+            if (r.status === 'fulfilled')
+                return r.value;
+            return __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_toFailure).call(this, table, r.reason);
+        });
+    }
+    /**
+     * T-21: caller-driven fetch that bypasses the watermark. Advances the
+     * fetch watermark only if the pulled range extends past the current one.
+     */
+    async fetchOnDemand(ctx, params) {
+        try {
+            const local = __classPrivateFieldGet(this, _R2Fetcher_localTable, "f").call(this, ctx, params.table);
+            const remote = __classPrivateFieldGet(this, _R2Fetcher_remoteTable, "f").call(this, ctx, params.table);
+            const bindings = {
+                since: params.since.toISOString(),
+                familyId: ctx.tenantId,
+            };
+            let where = 'ts >= $since AND family_id = $familyId';
+            if (params.until) {
+                where += ' AND ts <= $until';
+                bindings.until = params.until.toISOString();
+            }
+            const limitClause = params.limit ? ` LIMIT ${Math.max(1, Math.floor(params.limit))}` : '';
+            const sql = `INSERT INTO ${local} SELECT * FROM ${remote} WHERE ${where}${limitClause} ON CONFLICT DO NOTHING`;
+            await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(sql, bindings);
+            const countRows = await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(`SELECT COUNT(*) AS c FROM ${remote} WHERE ${where}${limitClause}`, bindings);
+            const rowsFetched = Number(countRows[0]?.c ?? 0);
+            const upperBound = params.until ?? __classPrivateFieldGet(this, _R2Fetcher_now, "f").call(this);
+            await __classPrivateFieldGet(this, _R2Fetcher_watermark, "f").advance(ctx.brand, ctx.tenantId, params.table, 'fetch', upperBound);
+            return { table: params.table, rowsFetched, ok: true };
+        }
+        catch (err) {
+            return __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_toFailure).call(this, params.table, err);
+        }
+    }
+}
+_R2Fetcher_engine = new WeakMap(), _R2Fetcher_watermark = new WeakMap(), _R2Fetcher_tables = new WeakMap(), _R2Fetcher_now = new WeakMap(), _R2Fetcher_localTable = new WeakMap(), _R2Fetcher_remoteTable = new WeakMap(), _R2Fetcher_instances = new WeakSet(), _R2Fetcher_prefetchOne = async function _R2Fetcher_prefetchOne(ctx, table, policy, cutoff) {
+    const local = __classPrivateFieldGet(this, _R2Fetcher_localTable, "f").call(this, ctx, table);
+    const remote = __classPrivateFieldGet(this, _R2Fetcher_remoteTable, "f").call(this, ctx, table);
+    if (policy.kind === 'all-family-on-attach') {
+        const sql = `INSERT INTO ${local} SELECT * FROM ${remote} WHERE family_id = $familyId AND ts >= $cutoff ON CONFLICT DO NOTHING`;
+        await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(sql, {
+            familyId: ctx.tenantId,
+            cutoff,
+        });
+    }
+    else if (policy.kind === 'recent-active-only') {
+        const activeCutoffMs = __classPrivateFieldGet(this, _R2Fetcher_now, "f").call(this).getTime() - policy.activeDays * 24 * 60 * 60 * 1000;
+        const activeCutoff = new Date(activeCutoffMs).toISOString();
+        // CTE picks user_ids seen in the recent window, then filters the window
+        // pull down to those users.
+        const sql = `WITH active AS (SELECT DISTINCT user_id FROM ${remote} WHERE family_id = $familyId AND ts >= $activeCutoff) INSERT INTO ${local} SELECT r.* FROM ${remote} r JOIN active a ON r.user_id = a.user_id WHERE r.family_id = $familyId AND r.ts >= $cutoff ON CONFLICT DO NOTHING`;
+        await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(sql, {
+            familyId: ctx.tenantId,
+            cutoff,
+            activeCutoff,
+        });
+    }
+    const rowsFetched = await __classPrivateFieldGet(this, _R2Fetcher_instances, "m", _R2Fetcher_countFetched).call(this, remote, ctx, cutoff);
+    await __classPrivateFieldGet(this, _R2Fetcher_watermark, "f").advance(ctx.brand, ctx.tenantId, table, 'fetch', __classPrivateFieldGet(this, _R2Fetcher_now, "f").call(this));
+    return { table, rowsFetched, ok: true };
+}, _R2Fetcher_fetchIncrementalOne = async function _R2Fetcher_fetchIncrementalOne(ctx, table) {
+    const watermark = await __classPrivateFieldGet(this, _R2Fetcher_watermark, "f").get(ctx.brand, ctx.tenantId, table, 'fetch');
+    const local = __classPrivateFieldGet(this, _R2Fetcher_localTable, "f").call(this, ctx, table);
+    const remote = __classPrivateFieldGet(this, _R2Fetcher_remoteTable, "f").call(this, ctx, table);
+    const sql = `INSERT INTO ${local} SELECT * FROM ${remote} WHERE ts > $watermark AND family_id = $familyId ON CONFLICT DO NOTHING`;
+    await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(sql, {
+        watermark: watermark.toISOString(),
+        familyId: ctx.tenantId,
+    });
+    const maxRows = await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(`SELECT MAX(ts) AS max_ts, COUNT(*) AS row_count FROM ${remote} WHERE ts > $watermark AND family_id = $familyId`, { watermark: watermark.toISOString(), familyId: ctx.tenantId });
+    const first = maxRows[0];
+    const rowsFetched = Number(first?.row_count ?? 0);
+    if (first?.max_ts) {
+        const nextWatermark = new Date(first.max_ts);
+        if (!Number.isNaN(nextWatermark.getTime())) {
+            await __classPrivateFieldGet(this, _R2Fetcher_watermark, "f").advance(ctx.brand, ctx.tenantId, table, 'fetch', nextWatermark);
+        }
+    }
+    return { table, rowsFetched, ok: true };
+}, _R2Fetcher_countFetched = async function _R2Fetcher_countFetched(remote, ctx, cutoff) {
+    const rows = await __classPrivateFieldGet(this, _R2Fetcher_engine, "f").execute(`SELECT COUNT(*) AS c FROM ${remote} WHERE family_id = $familyId AND ts >= $cutoff`, { familyId: ctx.tenantId, cutoff });
+    return Number(rows[0]?.c ?? 0);
+}, _R2Fetcher_toFailure = function _R2Fetcher_toFailure(table, cause) {
+    const err = cause instanceof SyncError
+        ? cause
+        : new SyncError('fetch_failed', `fetch failed for ${table}`, cause);
+    return { table, rowsFetched: 0, ok: false, error: err };
+};
+//# sourceMappingURL=fetcher.js.map

package/dist/sync/fetcher.js.map

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

package/dist/sync/flusher.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+import type { HybridDuckDB } from '../core/engine';
+import type { SensorBuffer } from './buffer';
+import { SyncError } from './errors';
+import type { FlushResult } from './types';
+export type FlushReason = 'row-count' | 'age' | 'foreground' | 'background' | 'manual' | 'scheduled';
+/** Exponential backoff in ms, per attempt index (0-based). Capped at 60s. */
+export declare const BACKOFF_SEQUENCE_MS: readonly number[];
+export declare const MAX_CONSECUTIVE_FAILURES = 5;
+export declare const FLUSH_TIMEOUT_MS = 30000;
+export type FlusherState = 'idle' | 'flushing' | 'error';
+export interface FlushedEvent {
+    table: string;
+    rowsFlushed: number;
+    reason: FlushReason;
+    /**
+     * Distinct userIds observed across drained buffer entries. Empty when the
+     * flush drained zero rows. Consumed by the rules engine to gate
+     * `evaluateOnBatch`.
+     */
+    affectedUserIds: string[];
+}
+export type SyncEmitter = (event: {
+    type: 'flushed';
+    payload: FlushedEvent;
+} | {
+    type: 'flush-failed';
+    payload: {
+        table: string;
+        error: SyncError;
+    };
+}) => void;
+export interface BatchFlusherConfig {
+    engine: HybridDuckDB;
+    buffer: SensorBuffer;
+    /**
+     * Column order per table. Row objects are projected into positional
+     * `appendRow(values[])` calls using this order. Missing tables raise
+     * `flush_failed` before a single row is written.
+     */
+    columnOrder: Record<string, readonly string[]>;
+    /** Concurrent flush workers. Default 2 (spec §Retry orchestration). */
+    concurrency?: number;
+    /** Optional test hook. Defaults to `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Optional test hook. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Optional emitter for `flushed` / `flush-failed` events. */
+    emit?: SyncEmitter;
+}
+export declare class BatchFlusher {
+    #private;
+    constructor(config: BatchFlusherConfig);
+    /** Runtime state for a table. `idle` if we've never touched it. */
+    stateOf(table: string): FlusherState;
+    lastErrorOf(table: string): SyncError | undefined;
+    /** Consecutive failures (reset on any success). */
+    failureCountOf(table: string): number;
+    /**
+     * Single flush attempt (no retry). Used directly by explicit user code and
+     * indirectly by `scheduleFlush` for the retry loop.
+     */
+    flush(table: string, reason?: FlushReason): Promise<FlushResult>;
+    /**
+     * Enqueue a flush with retry orchestration. Non-blocking — returns the
+     * promise for callers that want to await final resolution.
+     */
+    scheduleFlush(table: string, reason: FlushReason): Promise<FlushResult>;
+    /** Wait until every in-flight + queued flush settles. */
+    drainQueue(): Promise<void>;
+    /** Pause the queue — new `scheduleFlush()` calls enqueue but don't run. */
+    pauseQueue(): void;
+    /** Resume a paused queue. */
+    resumeQueue(): void;
+}
+//# sourceMappingURL=flusher.d.ts.map