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

package/dist/core/warehouse.js

@@ -0,0 +1,116 @@
+/**
+ * Warehouse attach / detach for a single tenant zone.
+ *
+ * Attaches R2 Iceberg data as a named DuckDB catalog, so downstream code can
+ * `SELECT ... FROM zone_<tenantId>.<table>`. The full sequence lives here so
+ * the state machine (T-09) can invoke it as a single actor step.
+ *
+ * Sequence per spec §Attach Protocol:
+ *   1. Build warehouse URI via `warehouseUriBuilder(brand, scope, tenantId)`.
+ *   2. Fetch bearer token via `tokenVendor.fetch({ brand, scope, tenantId })`.
+ *   3. `CREATE OR REPLACE SECRET` bound to the catalog endpoint + bearer token.
+ *   4. `ATTACH '<warehouseUri>' AS zone_<tenantId> (TYPE ICEBERG)`.
+ *   5. If `tenantScope === 'family'`, prime member ids via
+ *      `familyMembersProvider({ brand, familyId })` (for retention math).
+ *
+ * All failures map to `AnalyticsError('attach_failed' | 'token_vendor_failed',
+ * <phase>, cause)`.
+ */
+import { AnalyticsError } from './errors';
+/**
+ * Peel one layer of `AnalyticsError('query_failed')` off engine-wrapped
+ * errors so the outer `attach_failed` error's `cause` chain surfaces the
+ * root native failure, not our own intermediate wrap.
+ */
+function rootCause(err) {
+    if (err instanceof AnalyticsError && err.code === 'query_failed') {
+        return err.cause ?? err;
+    }
+    return err;
+}
+/**
+ * Derive the DuckDB catalog alias for a tenant. Also used as the SECRET name.
+ *
+ * Sanitised to `[A-Za-z0-9_]` so it's always a valid DuckDB identifier.
+ */
+export function warehouseSecretName(tenantId) {
+    return `zone_${tenantId.replace(/[^A-Za-z0-9_]/g, '_')}`;
+}
+/**
+ * Attach a warehouse for a single tenant zone.
+ *
+ * Steps are surfaced explicitly in the error message so callers (machine,
+ * logger) can see which phase failed.
+ */
+export async function attachWarehouse(db, ctx, deps) {
+    const secretName = warehouseSecretName(ctx.tenantId);
+    // Step 1: warehouse URI
+    let uri;
+    try {
+        uri = deps.warehouseUriBuilder(ctx.brand, ctx.tenantScope, ctx.tenantId);
+    }
+    catch (cause) {
+        throw new AnalyticsError('attach_failed', `warehouseUriBuilder failed for ${ctx.tenantId}`, cause);
+    }
+    // Step 2: bearer token
+    let token;
+    try {
+        token = await deps.tokenVendor.fetch({
+            brand: ctx.brand,
+            tenantScope: ctx.tenantScope,
+            tenantId: ctx.tenantId,
+        });
+    }
+    catch (cause) {
+        throw new AnalyticsError('token_vendor_failed', `tokenVendor.fetch failed for ${ctx.tenantId}`, cause);
+    }
+    // Step 3: CREATE OR REPLACE SECRET
+    try {
+        await db.execute(`CREATE OR REPLACE SECRET ${secretName} (TYPE ICEBERG, TOKEN $token, ENDPOINT $endpoint);`, { token: token.token, endpoint: deps.catalogEndpoint });
+    }
+    catch (cause) {
+        throw new AnalyticsError('attach_failed', `CREATE SECRET failed for ${secretName}`, rootCause(cause));
+    }
+    // Step 4: ATTACH
+    try {
+        await db.execute(`ATTACH '${uri}' AS ${secretName} (TYPE ICEBERG);`);
+    }
+    catch (cause) {
+        throw new AnalyticsError('attach_failed', `ATTACH failed for ${secretName}`, rootCause(cause));
+    }
+    // Step 5: prime family members (retention math in T-14)
+    let familyMemberIds;
+    if (ctx.tenantScope === 'family') {
+        try {
+            familyMemberIds = await deps.familyMembersProvider({
+                brand: ctx.brand,
+                familyId: ctx.tenantId,
+            });
+        }
+        catch (cause) {
+            throw new AnalyticsError('attach_failed', `familyMembersProvider failed for ${ctx.tenantId}`, cause);
+        }
+    }
+    return {
+        warehouseSecret: secretName,
+        warehouseUri: uri,
+        tokenExpiresAt: token.expiresAt,
+        familyMemberIds,
+    };
+}
+/**
+ * Reverse of `attachWarehouse`: `DETACH` the catalog then drop its secret.
+ * Idempotent from the caller's perspective — a `DETACH` of an unknown alias
+ * throws in DuckDB, but the machine only calls this from `attached`.
+ */
+export async function detachWarehouse(db, tenantId) {
+    const secretName = warehouseSecretName(tenantId);
+    try {
+        await db.execute(`DETACH ${secretName};`);
+        await db.execute(`DROP SECRET ${secretName};`);
+    }
+    catch (cause) {
+        throw new AnalyticsError('detach_failed', `detach failed for ${secretName}`, rootCause(cause));
+    }
+}
+//# sourceMappingURL=warehouse.js.map

package/dist/core/warehouse.js.map

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

package/dist/sync/buffer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sensor buffer (T-10 + T-12).
+ *
+ * In-memory ring per table with byte-budget accounting and pluggable overflow
+ * policies. All ops are synchronous except `push` (which may await overflow
+ * writes when the ring exceeds its byte budget).
+ *
+ * Byte accounting: we estimate a row's contribution as
+ * `JSON.stringify(rows).length` at push time. This is a rough proxy for the
+ * DuckDB Appender's actual memory footprint but is stable and cheap. The
+ * budget is a soft limit — one push at a time can exceed it before overflow
+ * fires.
+ *
+ * Overflow policies (T-12):
+ *   - `drop-oldest`: when the ring is full, spill the oldest ring entries to
+ *     `OverflowStore` until the incoming push fits in memory. Overflow is
+ *     durable (MMKV via KVStore) so nothing is actually dropped.
+ *   - `drop-newest`: reject the incoming push and increment a dropped
+ *     counter. Warning event is emitted via the injected `onDrop` callback.
+ *     Data is lost — used only when the app opts in for battery-only sync.
+ *   - `block`: `push` awaits an external drain. Implemented via a
+ *     `Promise`-based backpressure signal.
+ */
+import type { OverflowStore } from './overflow';
+import type { BufferEntry, BufferSize, OverflowPolicy, SensorBatch } from './types';
+export interface SensorBufferConfig {
+    overflow: OverflowStore;
+    maxBufferBytes?: number;
+    policy?: OverflowPolicy;
+    /** Fired when a `drop-newest` policy discards an incoming push. */
+    onDrop?: (entry: {
+        table: string;
+        droppedRowCount: number;
+        reason: 'drop-newest';
+    }) => void;
+    /** Optional clock injection for deterministic tests. */
+    now?: () => number;
+}
+export declare class SensorBuffer {
+    #private;
+    constructor(config: SensorBufferConfig);
+    push(batch: SensorBatch): Promise<void>;
+    /**
+     * Drain the buffer for a single table. Overflow entries are drained first
+     * so FIFO order across in-memory + overflow is preserved.
+     */
+    drain(table: string): Promise<BufferEntry[]>;
+    size(table?: string): Promise<BufferSize>;
+    clear(table?: string): Promise<void>;
+}
+//# sourceMappingURL=buffer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/sync/buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACZ,MAAM,SAAS,CAAA;AAIhB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,aAAa,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;QACf,KAAK,EAAE,MAAM,CAAA;QACb,eAAe,EAAE,MAAM,CAAA;QACvB,MAAM,EAAE,aAAa,CAAA;KACtB,KAAK,IAAI,CAAA;IACV,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,qBAAa,YAAY;;gBAWX,MAAM,EAAE,kBAAkB;IAQhC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7C;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAU5C,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBzC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqG3C"}

package/dist/sync/buffer.js

@@ -0,0 +1,188 @@
+/**
+ * Sensor buffer (T-10 + T-12).
+ *
+ * In-memory ring per table with byte-budget accounting and pluggable overflow
+ * policies. All ops are synchronous except `push` (which may await overflow
+ * writes when the ring exceeds its byte budget).
+ *
+ * Byte accounting: we estimate a row's contribution as
+ * `JSON.stringify(rows).length` at push time. This is a rough proxy for the
+ * DuckDB Appender's actual memory footprint but is stable and cheap. The
+ * budget is a soft limit — one push at a time can exceed it before overflow
+ * fires.
+ *
+ * Overflow policies (T-12):
+ *   - `drop-oldest`: when the ring is full, spill the oldest ring entries to
+ *     `OverflowStore` until the incoming push fits in memory. Overflow is
+ *     durable (MMKV via KVStore) so nothing is actually dropped.
+ *   - `drop-newest`: reject the incoming push and increment a dropped
+ *     counter. Warning event is emitted via the injected `onDrop` callback.
+ *     Data is lost — used only when the app opts in for battery-only sync.
+ *   - `block`: `push` awaits an external drain. Implemented via a
+ *     `Promise`-based backpressure signal.
+ */
+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 _SensorBuffer_instances, _SensorBuffer_overflow, _SensorBuffer_maxBytes, _SensorBuffer_policy, _SensorBuffer_onDrop, _SensorBuffer_now, _SensorBuffer_rings, _SensorBuffer_inMemoryBytes, _SensorBuffer_blockWaiters, _SensorBuffer_pushEntry, _SensorBuffer_appendInMemory, _SensorBuffer_sizeOne, _SensorBuffer_waitForDrain, _SensorBuffer_wakeBlockers;
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+export class SensorBuffer {
+    constructor(config) {
+        _SensorBuffer_instances.add(this);
+        _SensorBuffer_overflow.set(this, void 0);
+        _SensorBuffer_maxBytes.set(this, void 0);
+        _SensorBuffer_policy.set(this, void 0);
+        _SensorBuffer_onDrop.set(this, void 0);
+        _SensorBuffer_now.set(this, void 0);
+        _SensorBuffer_rings.set(this, new Map());
+        _SensorBuffer_inMemoryBytes.set(this, new Map());
+        _SensorBuffer_blockWaiters.set(this, new Map());
+        __classPrivateFieldSet(this, _SensorBuffer_overflow, config.overflow, "f");
+        __classPrivateFieldSet(this, _SensorBuffer_maxBytes, config.maxBufferBytes ?? DEFAULT_MAX_BYTES, "f");
+        __classPrivateFieldSet(this, _SensorBuffer_policy, config.policy ?? 'drop-oldest', "f");
+        __classPrivateFieldSet(this, _SensorBuffer_onDrop, config.onDrop, "f");
+        __classPrivateFieldSet(this, _SensorBuffer_now, config.now ?? (() => Date.now()), "f");
+    }
+    async push(batch) {
+        const entry = {
+            rows: batch.rows,
+            brand: batch.brand,
+            familyId: batch.familyId,
+            userId: batch.userId,
+            deviceId: batch.deviceId,
+            enqueuedAt: __classPrivateFieldGet(this, _SensorBuffer_now, "f").call(this),
+            byteSize: estimateBytes(batch.rows),
+        };
+        await __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_pushEntry).call(this, batch.table, entry);
+    }
+    /**
+     * Drain the buffer for a single table. Overflow entries are drained first
+     * so FIFO order across in-memory + overflow is preserved.
+     */
+    async drain(table) {
+        const overflow = await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").drain(table);
+        const ring = __classPrivateFieldGet(this, _SensorBuffer_rings, "f").get(table) ?? [];
+        __classPrivateFieldGet(this, _SensorBuffer_rings, "f").set(table, []);
+        __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").set(table, 0);
+        // Wake any block-policy waiters now that room is available.
+        __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_wakeBlockers).call(this, table);
+        return [...overflow, ...ring];
+    }
+    async size(table) {
+        if (table)
+            return __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_sizeOne).call(this, table);
+        let inMemory = 0;
+        let inMemoryBytes = 0;
+        let overflow = 0;
+        const tables = new Set([
+            ...__classPrivateFieldGet(this, _SensorBuffer_rings, "f").keys(),
+            ...__classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").keys(),
+        ]);
+        for (const t of tables) {
+            const s = await __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_sizeOne).call(this, t);
+            inMemory += s.inMemory;
+            inMemoryBytes += s.inMemoryBytes;
+            overflow += s.overflow;
+        }
+        return { inMemory, inMemoryBytes, overflow };
+    }
+    async clear(table) {
+        if (table) {
+            __classPrivateFieldGet(this, _SensorBuffer_rings, "f").delete(table);
+            __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").set(table, 0);
+            await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").clear(table);
+            __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_wakeBlockers).call(this, table);
+            return;
+        }
+        for (const t of __classPrivateFieldGet(this, _SensorBuffer_rings, "f").keys())
+            await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").clear(t);
+        __classPrivateFieldGet(this, _SensorBuffer_rings, "f").clear();
+        __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").clear();
+        for (const t of __classPrivateFieldGet(this, _SensorBuffer_blockWaiters, "f").keys())
+            __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_wakeBlockers).call(this, t);
+    }
+}
+_SensorBuffer_overflow = new WeakMap(), _SensorBuffer_maxBytes = new WeakMap(), _SensorBuffer_policy = new WeakMap(), _SensorBuffer_onDrop = new WeakMap(), _SensorBuffer_now = new WeakMap(), _SensorBuffer_rings = new WeakMap(), _SensorBuffer_inMemoryBytes = new WeakMap(), _SensorBuffer_blockWaiters = new WeakMap(), _SensorBuffer_instances = new WeakSet(), _SensorBuffer_pushEntry = async function _SensorBuffer_pushEntry(table, entry) {
+    const currentBytes = __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").get(table) ?? 0;
+    const wouldOverflow = currentBytes + entry.byteSize > __classPrivateFieldGet(this, _SensorBuffer_maxBytes, "f");
+    if (!wouldOverflow) {
+        __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_appendInMemory).call(this, table, entry);
+        return;
+    }
+    switch (__classPrivateFieldGet(this, _SensorBuffer_policy, "f")) {
+        case 'drop-oldest': {
+            // Spill oldest ring entries to overflow until the incoming push fits.
+            const ring = __classPrivateFieldGet(this, _SensorBuffer_rings, "f").get(table) ?? [];
+            while (ring.length > 0
+                && (__classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").get(table) ?? 0) + entry.byteSize
+                    > __classPrivateFieldGet(this, _SensorBuffer_maxBytes, "f")) {
+                const oldest = ring.shift();
+                __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").set(table, (__classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").get(table) ?? 0) - oldest.byteSize);
+                await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").push(table, oldest);
+            }
+            __classPrivateFieldGet(this, _SensorBuffer_rings, "f").set(table, ring);
+            // If the incoming entry itself exceeds the budget, park it in
+            // overflow directly rather than blowing the ring.
+            if (entry.byteSize > __classPrivateFieldGet(this, _SensorBuffer_maxBytes, "f")) {
+                await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").push(table, entry);
+            }
+            else {
+                __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_appendInMemory).call(this, table, entry);
+            }
+            return;
+        }
+        case 'drop-newest': {
+            __classPrivateFieldGet(this, _SensorBuffer_onDrop, "f")?.call(this, {
+                table,
+                droppedRowCount: entry.rows.length,
+                reason: 'drop-newest',
+            });
+            return;
+        }
+        case 'block': {
+            // Wait for someone to drain; then retry the push.
+            await __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_waitForDrain).call(this, table);
+            return __classPrivateFieldGet(this, _SensorBuffer_instances, "m", _SensorBuffer_pushEntry).call(this, table, entry);
+        }
+    }
+}, _SensorBuffer_appendInMemory = function _SensorBuffer_appendInMemory(table, entry) {
+    const ring = __classPrivateFieldGet(this, _SensorBuffer_rings, "f").get(table) ?? [];
+    ring.push(entry);
+    __classPrivateFieldGet(this, _SensorBuffer_rings, "f").set(table, ring);
+    __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").set(table, (__classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").get(table) ?? 0) + entry.byteSize);
+}, _SensorBuffer_sizeOne = async function _SensorBuffer_sizeOne(table) {
+    const ring = __classPrivateFieldGet(this, _SensorBuffer_rings, "f").get(table) ?? [];
+    const inMemoryRows = ring.reduce((a, e) => a + e.rows.length, 0);
+    const overflowCount = await __classPrivateFieldGet(this, _SensorBuffer_overflow, "f").count(table);
+    return {
+        inMemory: inMemoryRows,
+        inMemoryBytes: __classPrivateFieldGet(this, _SensorBuffer_inMemoryBytes, "f").get(table) ?? 0,
+        overflow: overflowCount,
+    };
+}, _SensorBuffer_waitForDrain = function _SensorBuffer_waitForDrain(table) {
+    return new Promise((resolve) => {
+        const q = __classPrivateFieldGet(this, _SensorBuffer_blockWaiters, "f").get(table) ?? [];
+        q.push(resolve);
+        __classPrivateFieldGet(this, _SensorBuffer_blockWaiters, "f").set(table, q);
+    });
+}, _SensorBuffer_wakeBlockers = function _SensorBuffer_wakeBlockers(table) {
+    const q = __classPrivateFieldGet(this, _SensorBuffer_blockWaiters, "f").get(table);
+    if (!q || q.length === 0)
+        return;
+    __classPrivateFieldGet(this, _SensorBuffer_blockWaiters, "f").set(table, []);
+    for (const resolve of q)
+        resolve();
+};
+function estimateBytes(rows) {
+    // Approximation: rough byte count of the JSON encoding. Fast and stable.
+    return JSON.stringify(rows).length;
+}
+//# sourceMappingURL=buffer.js.map

package/dist/sync/buffer.js.map

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

package/dist/sync/context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * React context for the SyncManager.
+ *
+ * `SyncProvider` wires an already-constructed `SyncManager` into the subtree;
+ * hooks (`useSyncState`, `useSensorSink`, `useSyncProgress`) resolve it via
+ * `useSyncManager()`.
+ */
+import * as React from 'react';
+import type { SyncManager } from './manager';
+export interface SyncProviderProps {
+    manager: SyncManager;
+    children: React.ReactNode;
+}
+export declare function SyncProvider({ manager, children }: SyncProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Resolves the SyncManager. Throws when used outside `<SyncProvider>`. */
+export declare function useSyncManager(): SyncManager;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/sync/context.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAI5C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,CAAA;IACpB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,wBAAgB,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,iBAAiB,2CAMpE;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,WAAW,CAS5C"}

package/dist/sync/context.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React context for the SyncManager.
+ *
+ * `SyncProvider` wires an already-constructed `SyncManager` into the subtree;
+ * hooks (`useSyncState`, `useSensorSink`, `useSyncProgress`) resolve it via
+ * `useSyncManager()`.
+ */
+import * as React from 'react';
+const SyncContext = React.createContext(null);
+export function SyncProvider({ manager, children }) {
+    return (_jsx(SyncContext.Provider, { value: manager, children: children }));
+}
+/** Resolves the SyncManager. Throws when used outside `<SyncProvider>`. */
+export function useSyncManager() {
+    const manager = React.useContext(SyncContext);
+    if (!manager) {
+        throw new Error('@mongrov/analytics/sync: hook used outside <SyncProvider>. '
+            + 'Wrap your app with <SyncProvider manager={createSyncManager(...)}>.');
+    }
+    return manager;
+}
+//# sourceMappingURL=context.js.map

package/dist/sync/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/sync/context.tsx"],"names":[],"mappings":";AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,CAAqB,IAAI,CAAC,CAAA;AAOjE,MAAM,UAAU,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAqB;IACnE,OAAO,CACL,KAAC,WAAW,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YACjC,QAAQ,GACY,CACxB,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAA;IAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6DAA6D;cAC3D,qEAAqE,CACxE,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/sync/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SyncError taxonomy (design.md §Errors).
+ *
+ * Codes:
+ *   - `flush_failed` — Appender write failed (all retries exhausted or fatal)
+ *   - `push_failed` — R2 push failed (all retries exhausted)
+ *   - `fetch_failed` — R2 fetch failed
+ *   - `overflow_dropped` — drop-newest policy discarded a batch
+ *   - `token_expired` — 401 from R2 after token refresh
+ *   - `constraint_not_met` — scheduler skipped a cycle (battery / network)
+ *   - `mapper_failed` — firmware mapper raised
+ */
+export type SyncErrorCode = 'flush_failed' | 'push_failed' | 'fetch_failed' | 'overflow_dropped' | 'token_expired' | 'constraint_not_met' | 'mapper_failed';
+export declare class SyncError extends Error {
+    readonly code: SyncErrorCode;
+    readonly cause: unknown;
+    constructor(code: SyncErrorCode, message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/sync/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,aAAa,GACnB,cAAc,GACd,aAAa,GACb,cAAc,GACd,kBAAkB,GAClB,eAAe,GACf,oBAAoB,GACpB,eAAe,CAAA;AAErB,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;gBAEX,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMlE"}

package/dist/sync/errors.js

@@ -0,0 +1,21 @@
+/**
+ * SyncError taxonomy (design.md §Errors).
+ *
+ * Codes:
+ *   - `flush_failed` — Appender write failed (all retries exhausted or fatal)
+ *   - `push_failed` — R2 push failed (all retries exhausted)
+ *   - `fetch_failed` — R2 fetch failed
+ *   - `overflow_dropped` — drop-newest policy discarded a batch
+ *   - `token_expired` — 401 from R2 after token refresh
+ *   - `constraint_not_met` — scheduler skipped a cycle (battery / network)
+ *   - `mapper_failed` — firmware mapper raised
+ */
+export class SyncError extends Error {
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'SyncError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/sync/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/sync/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAIlC,YAAY,IAAmB,EAAE,OAAe,EAAE,KAAe;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF"}

package/dist/sync/events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * T-25 — Event bus integration.
+ *
+ * The sync layer publishes two families of invalidation events:
+ *   `{table}:insert`        — emitted after a successful flush of local rows.
+ *   `{table}:sync_complete` — emitted after a successful push to the remote R2
+ *                             zone completes with rows written.
+ *
+ * The `EventBus` is injected by the app (typically `@mongrov/core`'s event bus).
+ * Consumers use these events to invalidate caches / re-run subscriptions.
+ */
+import type { FlushedEvent, SyncEmitter } from './flusher';
+import type { PushResult } from './pusher';
+/**
+ * Minimal event-bus contract. Kept narrow so any host (React Query cache,
+ * mitt, EventEmitter, custom fan-out) satisfies it structurally.
+ */
+export interface EventBus {
+    emit: (name: string, payload?: unknown) => void;
+}
+export interface FlushInsertPayload {
+    table: string;
+    rowsFlushed: number;
+    reason: string;
+}
+export interface SyncCompletePayload {
+    table: string;
+    rowsPushed: number;
+}
+/**
+ * Adapts an `EventBus` into a `SyncEmitter` (as consumed by `BatchFlusher.emit`).
+ * Only successful flushes produce an `${table}:insert` event; failures pass
+ * through silently at the bus layer (the flusher already emits `flush-failed`
+ * to any co-subscribed emitter).
+ */
+export declare function bindFlushEvents(bus: EventBus): SyncEmitter;
+export type PushEmitter = (result: PushResult) => void;
+/**
+ * Adapts an `EventBus` into a `PushEmitter`. Only successful pushes with at
+ * least one row published produce `${table}:sync_complete`; ok-but-empty pushes
+ * are silent (no downstream invalidation is needed).
+ */
+export declare function bindPushEvents(bus: EventBus): PushEmitter;
+/**
+ * Re-export the FlushedEvent shape for callers that need to type-narrow their
+ * bus payloads.
+ */
+export type { FlushedEvent };
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/sync/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,CAW1D;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,CAUzD;AAED;;;GAGG;AACH,YAAY,EAAE,YAAY,EAAE,CAAA"}

package/dist/sync/events.js

@@ -0,0 +1,46 @@
+/**
+ * T-25 — Event bus integration.
+ *
+ * The sync layer publishes two families of invalidation events:
+ *   `{table}:insert`        — emitted after a successful flush of local rows.
+ *   `{table}:sync_complete` — emitted after a successful push to the remote R2
+ *                             zone completes with rows written.
+ *
+ * The `EventBus` is injected by the app (typically `@mongrov/core`'s event bus).
+ * Consumers use these events to invalidate caches / re-run subscriptions.
+ */
+/**
+ * Adapts an `EventBus` into a `SyncEmitter` (as consumed by `BatchFlusher.emit`).
+ * Only successful flushes produce an `${table}:insert` event; failures pass
+ * through silently at the bus layer (the flusher already emits `flush-failed`
+ * to any co-subscribed emitter).
+ */
+export function bindFlushEvents(bus) {
+    return (event) => {
+        if (event.type === 'flushed') {
+            const payload = {
+                table: event.payload.table,
+                rowsFlushed: event.payload.rowsFlushed,
+                reason: event.payload.reason,
+            };
+            bus.emit(`${event.payload.table}:insert`, payload);
+        }
+    };
+}
+/**
+ * Adapts an `EventBus` into a `PushEmitter`. Only successful pushes with at
+ * least one row published produce `${table}:sync_complete`; ok-but-empty pushes
+ * are silent (no downstream invalidation is needed).
+ */
+export function bindPushEvents(bus) {
+    return (result) => {
+        if (result.ok && result.rowsPushed > 0) {
+            const payload = {
+                table: result.table,
+                rowsPushed: result.rowsPushed,
+            };
+            bus.emit(`${result.table}:sync_complete`, payload);
+        }
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/sync/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/sync/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwBH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAa;IAC3C,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAuB;gBAClC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK;gBAC1B,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW;gBACtC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;aAC7B,CAAA;YACD,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,OAAO,CAAC,CAAA;QACpD,CAAC;IACH,CAAC,CAAA;AACH,CAAC;AAID;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IAC1C,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,OAAO,GAAwB;gBACnC,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAA;YACD,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,gBAAgB,EAAE,OAAO,CAAC,CAAA;QACpD,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/sync/factory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { AnalyticsEngine, AttachContext, KVStore } from '../core/types';
+import type { EventBus } from './events';
+import type { PrefetchPolicy } from './fetcher';
+import { type BackgroundTaskPort, type ConstraintPort, type SchedulerLogger } from './scheduler';
+import type { SyncManager } from './manager';
+import type { OverflowPolicy } from './types';
+export interface CreateSyncManagerConfig {
+    analytics: AnalyticsEngine;
+    storage: KVStore;
+    ctx: AttachContext;
+    tables: readonly string[];
+    columnOrder: Record<string, readonly string[]>;
+    prefetchPolicy: PrefetchPolicy;
+    eventBus?: EventBus;
+    refreshToken?: () => Promise<void>;
+    backgroundTask?: BackgroundTaskPort;
+    constraints?: ConstraintPort;
+    flush?: {
+        maxRows?: number;
+        maxAgeMs?: number;
+        concurrency?: number;
+    };
+    overflow?: {
+        maxBufferBytes?: number;
+        policy?: OverflowPolicy;
+    };
+    scheduler?: {
+        requiresCharging?: boolean;
+        requiresWifi?: boolean;
+        taskName?: string;
+    };
+    logger?: SchedulerLogger;
+}
+/**
+ * Assemble a fully wired `SyncManager`. Throws `z.ZodError` if the config is
+ * malformed (e.g., missing columnOrder entries or negative row limits).
+ */
+export declare function createSyncManager(config: CreateSyncManagerConfig): SyncManager;
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/sync/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAG5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAO/C,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EAGrB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAc,WAAW,EAAkC,MAAM,WAAW,CAAA;AAExF,OAAO,KAAK,EAAe,cAAc,EAAe,MAAM,SAAS,CAAA;AAmCvE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,eAAe,CAAA;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,EAAE,aAAa,CAAA;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;IAC9C,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,MAAM,CAAC,EAAE,cAAc,CAAA;KACxB,CAAA;IACD,SAAS,CAAC,EAAE;QACV,gBAAgB,CAAC,EAAE,OAAO,CAAA;QAC1B,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,WAAW,CAgI9E"}