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

package/dist/core/machine.js

@@ -0,0 +1,228 @@
+/**
+ * XState v5 state machine that drives the analytics engine lifecycle.
+ *
+ * `idle → opening → ready → attaching → attached → detaching → error`
+ *
+ * The machine owns lifecycle transitions only; side effects live in injected
+ * actors (`openEngine`, `attachEngine`, `detachEngine`, `refreshToken`) so
+ * tests can substitute fakes without a real DuckDB.
+ *
+ * Token refresh runs silently on `attached` via a delayed self-transition
+ * to `refreshing`, computed as 75% of the remaining TTL (spec §Token
+ * refresh policy). Refresh success re-enters `attached` and re-arms the
+ * timer; failure lands in `error`.
+ *
+ * Consumers (T-10 factory + T-11 hook) drive the machine via `send` and
+ * observe via `subscribe`.
+ */
+import { assign, fromPromise, setup } from 'xstate';
+import { AnalyticsError } from './errors';
+// -------------------- token TTL math --------------------
+/**
+ * Compute the delay before firing `TOKEN_REFRESH_TICK`. Spec calls for 75%
+ * TTL. Falls back to a 30-minute default when the vendor's `expiresAt` is
+ * missing or already in the past — the refresh will fail loudly rather than
+ * silently skipping.
+ */
+export function computeRefreshDelay(now, expiresAt) {
+    if (typeof expiresAt !== 'number' || expiresAt <= now) {
+        return 30 * 60 * 1000;
+    }
+    const ttl = expiresAt - now;
+    return Math.max(Math.floor(ttl * 0.75), 1);
+}
+// -------------------- error normalisation --------------------
+function toAnalyticsError(cause, fallbackCode) {
+    if (cause instanceof AnalyticsError) {
+        return cause;
+    }
+    return new AnalyticsError(fallbackCode, `machine actor failed: ${String(cause)}`, cause);
+}
+// -------------------- machine --------------------
+export const analyticsMachine = setup({
+    types: {
+        context: {},
+        events: {},
+        input: {},
+    },
+    actors: {
+        openEngine: fromPromise(async ({ input }) => {
+            await input.deps.openEngine();
+        }),
+        attachEngine: fromPromise(async ({ input }) => input.deps.attachEngine({ ctx: input.ctx })),
+        detachEngine: fromPromise(async ({ input }) => {
+            await input.deps.detachEngine({ ctx: input.ctx });
+        }),
+        refreshToken: fromPromise(async ({ input }) => input.deps.refreshToken({ ctx: input.ctx })),
+    },
+    actions: {
+        assignAttachCtx: assign(({ event }) => {
+            if (event.type !== 'ATTACH')
+                return {};
+            return { ctx: event.ctx };
+        }),
+        assignAttachSuccess: assign((_, params) => ({
+            warehouseSecret: params.output.warehouseSecret,
+            tokenExpiresAt: params.output.tokenExpiresAt,
+            lastError: undefined,
+        })),
+        assignRefreshSuccess: assign((_, params) => ({
+            tokenExpiresAt: params.output.tokenExpiresAt,
+            lastError: undefined,
+        })),
+        assignOpenError: assign((_, params) => ({
+            lastError: toAnalyticsError(params.error, 'engine_open_failed'),
+        })),
+        assignAttachError: assign((_, params) => ({
+            lastError: toAnalyticsError(params.error, 'attach_failed'),
+        })),
+        assignRefreshError: assign((_, params) => ({
+            lastError: toAnalyticsError(params.error, 'token_vendor_failed'),
+        })),
+        clearError: assign({ lastError: undefined }),
+        clearAttachState: assign({
+            ctx: undefined,
+            tokenExpiresAt: undefined,
+            warehouseSecret: undefined,
+        }),
+    },
+    guards: {
+        hasAttachCtx: ({ context }) => context.ctx !== undefined,
+    },
+    delays: {
+        tokenRefresh: ({ context }) => computeRefreshDelay(Date.now(), context.tokenExpiresAt),
+    },
+}).createMachine({
+    id: 'analytics',
+    initial: 'idle',
+    context: ({ input }) => ({
+        deps: input.deps,
+        ctx: undefined,
+        tokenExpiresAt: undefined,
+        warehouseSecret: undefined,
+        lastError: undefined,
+    }),
+    on: {
+        CLOSE: {
+            target: '.idle',
+            actions: ['clearAttachState', 'clearError'],
+        },
+    },
+    states: {
+        idle: {
+            on: {
+                OPEN: 'opening',
+            },
+        },
+        opening: {
+            invoke: {
+                src: 'openEngine',
+                input: ({ context }) => ({ deps: context.deps }),
+                onDone: 'ready',
+                onError: {
+                    target: 'error',
+                    actions: {
+                        type: 'assignOpenError',
+                        params: ({ event }) => ({ error: event.error }),
+                    },
+                },
+            },
+        },
+        ready: {
+            on: {
+                ATTACH: {
+                    target: 'attaching',
+                    actions: 'assignAttachCtx',
+                },
+            },
+        },
+        attaching: {
+            invoke: {
+                src: 'attachEngine',
+                input: ({ context }) => ({ deps: context.deps, ctx: context.ctx }),
+                onDone: {
+                    target: 'attached',
+                    actions: {
+                        type: 'assignAttachSuccess',
+                        params: ({ event }) => ({ output: event.output }),
+                    },
+                },
+                onError: {
+                    target: 'error',
+                    actions: {
+                        type: 'assignAttachError',
+                        params: ({ event }) => ({ error: event.error }),
+                    },
+                },
+            },
+        },
+        attached: {
+            after: {
+                tokenRefresh: {
+                    target: 'refreshing',
+                },
+            },
+            on: {
+                TOKEN_REFRESH_TICK: 'refreshing',
+                DETACH: 'detaching',
+            },
+        },
+        refreshing: {
+            invoke: {
+                src: 'refreshToken',
+                input: ({ context }) => ({ deps: context.deps, ctx: context.ctx }),
+                onDone: {
+                    target: 'attached',
+                    actions: {
+                        type: 'assignRefreshSuccess',
+                        params: ({ event }) => ({ output: event.output }),
+                    },
+                },
+                onError: {
+                    target: 'error',
+                    actions: {
+                        type: 'assignRefreshError',
+                        params: ({ event }) => ({ error: event.error }),
+                    },
+                },
+            },
+        },
+        detaching: {
+            invoke: {
+                src: 'detachEngine',
+                input: ({ context }) => ({ deps: context.deps, ctx: context.ctx }),
+                onDone: {
+                    target: 'ready',
+                    actions: 'clearAttachState',
+                },
+                onError: {
+                    target: 'error',
+                    actions: {
+                        type: 'assignAttachError',
+                        params: ({ event }) => ({ error: event.error }),
+                    },
+                },
+            },
+        },
+        error: {
+            on: {
+                OPEN: {
+                    target: 'opening',
+                    actions: 'clearError',
+                },
+                ATTACH: [
+                    {
+                        guard: 'hasAttachCtx',
+                        target: 'attaching',
+                        actions: ['assignAttachCtx', 'clearError'],
+                    },
+                    {
+                        target: 'attaching',
+                        actions: ['assignAttachCtx', 'clearError'],
+                    },
+                ],
+            },
+        },
+    },
+});
+//# sourceMappingURL=machine.js.map

package/dist/core/machine.js.map

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

package/dist/core/metric_metadata.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Metric registry (spec §Metric metadata).
+ *
+ * `METRIC_METADATA` maps every consumer-facing metric id to the warehouse
+ * column that stores it, the sampling cadence, and the exposure tier
+ * (`full` vs `collected_only`). Rules engine + UI decide which metrics to
+ * surface based on `exposure`; retention logic (T-14) uses the same table
+ * mapping to sweep by column.
+ */
+import type { TableName } from './schemas';
+export type MetricExposure = 'full' | 'collected_only';
+/**
+ * Sampling cadence in minutes, or the sentinel `'per_session'` for metrics
+ * emitted once per sleep session. Keeps the discriminant explicit rather
+ * than shoehorning it into a number.
+ */
+export type MetricSamplingMinutes = number | 'per_session';
+export interface MetricMetadataEntry {
+    table: TableName;
+    column: string;
+    sampling_minutes: MetricSamplingMinutes;
+    exposure: MetricExposure;
+}
+/**
+ * Frozen metric registry, verbatim from spec §Metric metadata.
+ *
+ * v0.1.0 apps consume this for exposure gating; adding metrics is a spec
+ * change (bump metadata; add DDL column if new).
+ */
+export declare const METRIC_METADATA: Readonly<{
+    readonly hrv_ms: {
+        readonly table: "hrv";
+        readonly column: "hrv_ms";
+        readonly sampling_minutes: 60;
+        readonly exposure: "full";
+    };
+    readonly stress: {
+        readonly table: "hrv";
+        readonly column: "stress";
+        readonly sampling_minutes: 60;
+        readonly exposure: "full";
+    };
+    readonly systolic_bp: {
+        readonly table: "hrv";
+        readonly column: "systolic_bp";
+        readonly sampling_minutes: 60;
+        readonly exposure: "collected_only";
+    };
+    readonly diastolic_bp: {
+        readonly table: "hrv";
+        readonly column: "diastolic_bp";
+        readonly sampling_minutes: 60;
+        readonly exposure: "collected_only";
+    };
+    readonly vascular_aging: {
+        readonly table: "hrv";
+        readonly column: "vascular_aging";
+        readonly sampling_minutes: 60;
+        readonly exposure: "collected_only";
+    };
+    readonly hr_bpm: {
+        readonly table: "heart_rate";
+        readonly column: "bpm";
+        readonly sampling_minutes: 10;
+        readonly exposure: "full";
+    };
+    readonly spo2: {
+        readonly table: "spo2";
+        readonly column: "spo2";
+        readonly sampling_minutes: 30;
+        readonly exposure: "full";
+    };
+    readonly temp_c: {
+        readonly table: "temperature";
+        readonly column: "temp_c";
+        readonly sampling_minutes: 30;
+        readonly exposure: "full";
+    };
+    readonly activity_steps: {
+        readonly table: "activity";
+        readonly column: "steps";
+        readonly sampling_minutes: 1;
+        readonly exposure: "full";
+    };
+    readonly calories: {
+        readonly table: "activity_bucket";
+        readonly column: "calories";
+        readonly sampling_minutes: 10;
+        readonly exposure: "full";
+    };
+    readonly distance_km: {
+        readonly table: "activity_bucket";
+        readonly column: "distance_km";
+        readonly sampling_minutes: 10;
+        readonly exposure: "full";
+    };
+    readonly sleep_total_minutes: {
+        readonly table: "sleep_session";
+        readonly column: "total_minutes";
+        readonly sampling_minutes: "per_session";
+        readonly exposure: "full";
+    };
+    readonly sleep_score: {
+        readonly table: "sleep_session";
+        readonly column: "avg_confidence";
+        readonly sampling_minutes: "per_session";
+        readonly exposure: "full";
+    };
+    readonly device_battery: {
+        readonly table: "device_event";
+        readonly column: "payload";
+        readonly sampling_minutes: 240;
+        readonly exposure: "full";
+    };
+}>;
+export type MetricId = keyof typeof METRIC_METADATA;
+/**
+ * Whether an app should surface this metric to end users. Metrics marked
+ * `collected_only` (BP, vascular aging) are captured for later research but
+ * kept out of consumer UI in v0.1.0.
+ */
+export declare function isMetricExposed(id: MetricId): boolean;
+/**
+ * List of every metric id where `exposure === 'full'` — convenience for
+ * UI code that iterates the visible surface.
+ */
+export declare function getExposedMetricIds(): MetricId[];
+//# sourceMappingURL=metric_metadata.d.ts.map

package/dist/core/metric_metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric_metadata.d.ts","sourceRoot":"","sources":["../../src/core/metric_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,gBAAgB,CAAA;AAEtD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,aAAa,CAAA;AAE1D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,qBAAqB,CAAA;IACvC,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeuC,CAAA;AAEnE,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,eAAe,CAAA;AAEnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAErD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,QAAQ,EAAE,CAEhD"}

package/dist/core/metric_metadata.js

@@ -0,0 +1,47 @@
+/**
+ * Metric registry (spec §Metric metadata).
+ *
+ * `METRIC_METADATA` maps every consumer-facing metric id to the warehouse
+ * column that stores it, the sampling cadence, and the exposure tier
+ * (`full` vs `collected_only`). Rules engine + UI decide which metrics to
+ * surface based on `exposure`; retention logic (T-14) uses the same table
+ * mapping to sweep by column.
+ */
+/**
+ * Frozen metric registry, verbatim from spec §Metric metadata.
+ *
+ * v0.1.0 apps consume this for exposure gating; adding metrics is a spec
+ * change (bump metadata; add DDL column if new).
+ */
+export const METRIC_METADATA = Object.freeze({
+    hrv_ms: { table: 'hrv', column: 'hrv_ms', sampling_minutes: 60, exposure: 'full' },
+    stress: { table: 'hrv', column: 'stress', sampling_minutes: 60, exposure: 'full' },
+    systolic_bp: { table: 'hrv', column: 'systolic_bp', sampling_minutes: 60, exposure: 'collected_only' },
+    diastolic_bp: { table: 'hrv', column: 'diastolic_bp', sampling_minutes: 60, exposure: 'collected_only' },
+    vascular_aging: { table: 'hrv', column: 'vascular_aging', sampling_minutes: 60, exposure: 'collected_only' },
+    hr_bpm: { table: 'heart_rate', column: 'bpm', sampling_minutes: 10, exposure: 'full' },
+    spo2: { table: 'spo2', column: 'spo2', sampling_minutes: 30, exposure: 'full' },
+    temp_c: { table: 'temperature', column: 'temp_c', sampling_minutes: 30, exposure: 'full' },
+    activity_steps: { table: 'activity', column: 'steps', sampling_minutes: 1, exposure: 'full' },
+    calories: { table: 'activity_bucket', column: 'calories', sampling_minutes: 10, exposure: 'full' },
+    distance_km: { table: 'activity_bucket', column: 'distance_km', sampling_minutes: 10, exposure: 'full' },
+    sleep_total_minutes: { table: 'sleep_session', column: 'total_minutes', sampling_minutes: 'per_session', exposure: 'full' },
+    sleep_score: { table: 'sleep_session', column: 'avg_confidence', sampling_minutes: 'per_session', exposure: 'full' },
+    device_battery: { table: 'device_event', column: 'payload', sampling_minutes: 240, exposure: 'full' },
+});
+/**
+ * Whether an app should surface this metric to end users. Metrics marked
+ * `collected_only` (BP, vascular aging) are captured for later research but
+ * kept out of consumer UI in v0.1.0.
+ */
+export function isMetricExposed(id) {
+    return METRIC_METADATA[id].exposure === 'full';
+}
+/**
+ * List of every metric id where `exposure === 'full'` — convenience for
+ * UI code that iterates the visible surface.
+ */
+export function getExposedMetricIds() {
+    return Object.keys(METRIC_METADATA).filter(isMetricExposed);
+}
+//# sourceMappingURL=metric_metadata.js.map

package/dist/core/metric_metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric_metadata.js","sourceRoot":"","sources":["../../src/core/metric_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IAClF,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IAClF,WAAW,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;IACtG,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;IACxG,cAAc,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;IAC5G,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IACtF,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IAC/E,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IAC1F,cAAc,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE;IAC7F,QAAQ,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IAClG,WAAW,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;IACxG,mBAAmB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE;IAC3H,WAAW,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE;IACpH,cAAc,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE;CACrC,CAAC,CAAA;AAInE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,EAAY;IAC1C,OAAO,eAAe,CAAC,EAAE,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAA;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAQ,MAAM,CAAC,IAAI,CAAC,eAAe,CAAgB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;AAC7E,CAAC"}

package/dist/core/migrations.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Schema migrations for the warehouse.
+ *
+ * Version is tracked per `(brand, tenantId)` in KVStore. v0.1.0 has a single
+ * baseline migration (step 1: `ensureSchemas`) — future migrations append to
+ * `MIGRATIONS` in order; each `up(db)` receives the attached catalog name.
+ *
+ * `ensureMigrations` is idempotent and safe to call on every attach.
+ */
+import type { HybridDuckDB } from './engine';
+import type { KVStore } from './types';
+export interface MigrationContext {
+    brand: string;
+    tenantId: string;
+}
+export interface Migration {
+    /** Sequential integer, starting at 1. */
+    version: number;
+    /** Human name shown in errors + logs. */
+    name: string;
+    /** Idempotent DDL — called with the attached catalog alias. */
+    up(db: HybridDuckDB, catalog: string): Promise<void>;
+}
+/**
+ * Ordered list of migrations. Each entry's `version` must equal its
+ * (1-based) position; `CURRENT_VERSION` is derived from the tail.
+ */
+export declare const MIGRATIONS: readonly Migration[];
+/** Version of the latest known migration — target for every attach. */
+export declare const CURRENT_VERSION: number;
+/**
+ * Compute the KV key holding the applied schema version for a
+ * `(brand, tenantId)` pair.
+ */
+export declare function schemaVersionKey(brand: string, tenantId: string): string;
+export interface EnsureMigrationsResult {
+    from: number;
+    to: number;
+}
+/**
+ * Run every migration between the persisted version and `CURRENT_VERSION`.
+ *
+ * - First launch: `from = 0`, applies every migration.
+ * - Same-version rerun: no-op, KV unchanged, returns `from === to`.
+ * - Upgrade path: applies only newer migrations in order.
+ * - Any failure at step N surfaces as
+ *   `AnalyticsError('migration_failed', 'step-<n>', cause)`. KV is only
+ *   advanced after each successful step so a partial upgrade leaves the
+ *   version at the last successful step (subsequent runs retry from there).
+ */
+export declare function ensureMigrations(db: HybridDuckDB, kv: KVStore, ctx: MigrationContext, catalog: string): Promise<EnsureMigrationsResult>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/core/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/core/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAQzC,CAAA;AAEF,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,MAA0B,CAAA;AAExD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,sBAAsB,CAAC,CA2BjC"}

package/dist/core/migrations.js

@@ -0,0 +1,66 @@
+/**
+ * Schema migrations for the warehouse.
+ *
+ * Version is tracked per `(brand, tenantId)` in KVStore. v0.1.0 has a single
+ * baseline migration (step 1: `ensureSchemas`) — future migrations append to
+ * `MIGRATIONS` in order; each `up(db)` receives the attached catalog name.
+ *
+ * `ensureMigrations` is idempotent and safe to call on every attach.
+ */
+import { AnalyticsError } from './errors';
+import { ensureSchemas } from './schemas';
+/**
+ * Ordered list of migrations. Each entry's `version` must equal its
+ * (1-based) position; `CURRENT_VERSION` is derived from the tail.
+ */
+export const MIGRATIONS = Object.freeze([
+    {
+        version: 1,
+        name: 'baseline schemas',
+        async up(db, catalog) {
+            await ensureSchemas(db, catalog);
+        },
+    },
+]);
+/** Version of the latest known migration — target for every attach. */
+export const CURRENT_VERSION = MIGRATIONS.length;
+/**
+ * Compute the KV key holding the applied schema version for a
+ * `(brand, tenantId)` pair.
+ */
+export function schemaVersionKey(brand, tenantId) {
+    return `analytics:schema-version:${brand}:${tenantId}`;
+}
+/**
+ * Run every migration between the persisted version and `CURRENT_VERSION`.
+ *
+ * - First launch: `from = 0`, applies every migration.
+ * - Same-version rerun: no-op, KV unchanged, returns `from === to`.
+ * - Upgrade path: applies only newer migrations in order.
+ * - Any failure at step N surfaces as
+ *   `AnalyticsError('migration_failed', 'step-<n>', cause)`. KV is only
+ *   advanced after each successful step so a partial upgrade leaves the
+ *   version at the last successful step (subsequent runs retry from there).
+ */
+export async function ensureMigrations(db, kv, ctx, catalog) {
+    const key = schemaVersionKey(ctx.brand, ctx.tenantId);
+    const stored = await kv.get(key);
+    const from = typeof stored === 'number' ? stored : 0;
+    if (from >= CURRENT_VERSION) {
+        return { from, to: from };
+    }
+    for (const migration of MIGRATIONS) {
+        if (migration.version <= from) {
+            continue;
+        }
+        try {
+            await migration.up(db, catalog);
+        }
+        catch (cause) {
+            throw new AnalyticsError('migration_failed', `migration step-${migration.version} (${migration.name}) failed`, cause);
+        }
+        await kv.set(key, migration.version);
+    }
+    return { from, to: CURRENT_VERSION };
+}
+//# sourceMappingURL=migrations.js.map

package/dist/core/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/core/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAiBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAyB,MAAM,CAAC,MAAM,CAAC;IAC5D;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,kBAAkB;QACxB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO;YAClB,MAAM,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;QAClC,CAAC;KACF;CACF,CAAC,CAAA;AAEF,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAW,UAAU,CAAC,MAAM,CAAA;AAExD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,QAAgB;IAC9D,OAAO,4BAA4B,KAAK,IAAI,QAAQ,EAAE,CAAA;AACxD,CAAC;AAOD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAgB,EAChB,EAAW,EACX,GAAqB,EACrB,OAAe;IAEf,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAA;IACrD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAS,GAAG,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpD,IAAI,IAAI,IAAI,eAAe,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;IAC3B,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YAC9B,SAAQ;QACV,CAAC;QACD,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;QACjC,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,kBAAkB,EAClB,kBAAkB,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,IAAI,UAAU,EAChE,KAAK,CACN,CAAA;QACH,CAAC;QACD,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IACtC,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,eAAe,EAAE,CAAA;AACtC,CAAC"}

package/dist/core/persistence.d.ts

@@ -0,0 +1,50 @@
+/**
+ * KVStore-backed persistence for analytics state.
+ *
+ * Two concerns:
+ *
+ *   1. **Last-attach ctx** — persisted on every successful attach and cleared
+ *      on detach. `loadLastAttach` returns the ctx only if it was written
+ *      within `LAST_ATTACH_TTL_MS` (24h per spec §Testing) so apps can safely
+ *      auto-reattach after a crash / cold start without silently reviving a
+ *      stale multi-day-old context.
+ *
+ *   2. **Retention override** — `setRetention(days)` persists the user
+ *      override layer per spec §Retention precedence at
+ *      `analytics:retention:override:{brand}:{tenantId}:{userId}`. v0.1.0
+ *      resolves via `resolveEffectiveRetention` (retention.ts) but does not
+ *      surface UX to write it (`analytics.setRetention` is the escape hatch).
+ *
+ * All keys use the `analytics:` prefix so consumers can namespace-clear.
+ */
+import type { AttachContext, KVStore } from './types';
+/** 24h in ms — freshness bound for the persisted attach ctx. */
+export declare const LAST_ATTACH_TTL_MS: number;
+/**
+ * Persist the ctx that just successfully attached. Overwrites any prior
+ * entry for the same brand.
+ */
+export declare function saveLastAttach(kv: KVStore, ctx: AttachContext, now?: number): Promise<void>;
+/**
+ * Load the last attach ctx for `brand` if it was written within the TTL.
+ * Returns `null` for missing entries or entries older than
+ * `LAST_ATTACH_TTL_MS`. Stale entries are also deleted as a side effect so
+ * repeated reads don't keep resurfacing them.
+ */
+export declare function loadLastAttach(kv: KVStore, brand: string, now?: number): Promise<AttachContext | null>;
+/**
+ * Clear the persisted attach ctx for `brand`. Invoked on `detach()` so a
+ * subsequent open doesn't auto-restore a context the app deliberately left.
+ */
+export declare function clearLastAttach(kv: KVStore, brand: string): Promise<void>;
+/**
+ * Persist the user-override retention for the current attach context.
+ * Overwrites any prior override for the same `(brand, tenantId, userId)`.
+ */
+export declare function saveRetentionOverride(kv: KVStore, ctx: AttachContext, days: number, now?: number): Promise<void>;
+/**
+ * Load the user-override retention (days) for `(brand, tenantId, userId)`,
+ * or `null` when none is stored.
+ */
+export declare function loadRetentionOverride(kv: KVStore, ctx: AttachContext): Promise<number | null>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/core/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/core/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAIrD,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,QAAsB,CAAA;AAiBrD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,aAAa,EAClB,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAY/B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E;AASD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB"}