@mongrov/analytics 0.6.0 → 0.8.0

package/dist/core/metric_metadata.js

@@ -14,18 +14,18 @@
  * 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' },
+    hrv_ms: { table: 'hrv', column: 'hrv_ms', sampling_minutes: 60, exposure: 'full', baselineDailyAggregate: 'avg' },
+    stress: { table: 'hrv', column: 'stress', sampling_minutes: 60, exposure: 'full', baselineDailyAggregate: 'avg' },
     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' },
+    hr_bpm: { table: 'heart_rate', column: 'bpm', sampling_minutes: 10, exposure: 'full', baselineDailyAggregate: 'avg' },
+    spo2: { table: 'spo2', column: 'spo2', sampling_minutes: 30, exposure: 'full', baselineDailyAggregate: 'avg' },
+    temp_c: { table: 'temperature', column: 'temp_c', sampling_minutes: 30, exposure: 'full', baselineDailyAggregate: 'avg' },
+    activity_steps: { table: 'activity', column: 'steps', sampling_minutes: 1, exposure: 'full', baselineDailyAggregate: 'sum' },
     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_total_minutes: { table: 'sleep_session', column: 'total_minutes', sampling_minutes: 'per_session', exposure: 'full', baselineDailyAggregate: 'session' },
     sleep_score: { table: 'sleep_session', column: 'avg_confidence', sampling_minutes: 'per_session', exposure: 'full' },
     device_battery: { table: 'device_battery', column: 'battery_pct', sampling_minutes: 240, exposure: 'full' },
 });
@@ -44,4 +44,32 @@ export function isMetricExposed(id) {
 export function getExposedMetricIds() {
     return Object.keys(METRIC_METADATA).filter(isMetricExposed);
 }
+/**
+ * Metric ids that carry a `user_baseline` row — those declaring a
+ * `baselineDailyAggregate`. Seven in v0.2.0, which at three windows each
+ * (7d / 30d / 90d) is the 21-baselines-per-user figure in the Sprint 5
+ * design.
+ */
+export function getBaselineMetricIds() {
+    return Object.keys(METRIC_METADATA).filter(id => baselineAggregateFor(id) !== undefined);
+}
+/**
+ * `baselineDailyAggregate` for a metric, or `undefined` when it carries no
+ * baseline. Accessor rather than a direct property read because the
+ * `as const` registry narrows each entry to its own literal type, and the
+ * field is genuinely absent — not `undefined` — on entries without one.
+ */
+export function baselineAggregateFor(id) {
+    const entry = METRIC_METADATA[id];
+    return entry.baselineDailyAggregate;
+}
+/** Baseline windows computed per metric (Sprint 5 §7). */
+export const BASELINE_WINDOW_DAYS = [7, 30, 90];
+/**
+ * Minimum distinct local DAYS before a baseline row is written
+ * (principle 27). Counting readings instead of days is the classic
+ * mis-implementation: 15 days of 30-minute SpO₂ sampling is 720 readings
+ * but still only 15 days, and must NOT populate a baseline.
+ */
+export const BASELINE_MIN_DAYS = 20;
 //# sourceMappingURL=metric_metadata.js.map

package/dist/core/metric_metadata.js.map

@@ -1 +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,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE;CAC3C,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"}
+{"version":3,"file":"metric_metadata.js","sourceRoot":"","sources":["../../src/core/metric_metadata.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/core/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;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,iBAAiB;IAChC,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAmCzC,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;AAWD,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,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CAyCjC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/core/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;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,iBAAiB;IAChC,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAgKzC,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;AAWD,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,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CAyCjC"}

package/dist/core/migrations.js

@@ -20,7 +20,7 @@
  * `ensureMigrations` is idempotent and safe to call on every attach.
  */
 import { AnalyticsError } from './errors';
-import { ensureSchemas, LOCAL_SCHEMAS, qualifyDdl, SCHEMAS } from './schemas';
+import { ensureSchemas, insightIndexDdl, LOCAL_SCHEMAS, qualifyDdl, SCHEMAS } from './schemas';
 /**
  * Iceberg namespace remote DDL is issued under — remote tables live at
  * `<secret>.default.<table>` (spec §Attach Protocol). Local DDL stays
@@ -46,7 +46,7 @@ export const MIGRATIONS = Object.freeze([
             // namespace explicitly — 2-part `zone_x.<table>` fails with
             // "Schema with name ... not found" on an attached Iceberg catalog.
             if (catalogs.remote) {
-                await ensureSchemas(db, `${catalogs.remote}.${REMOTE_NAMESPACE}`, SCHEMAS);
+                await ensureSchemas(db, `${catalogs.remote}.${REMOTE_NAMESPACE}`, SCHEMAS, { skipLocalOnly: true });
             }
         },
     },
@@ -66,6 +66,107 @@ export const MIGRATIONS = Object.freeze([
             }
         },
     },
+    {
+        version: 3,
+        name: 'insight v2 (insight_id / metric / kind / dismissed_at)',
+        // Fix CO-2: the pre-0.7.0 `insight` table used an `id` PK and lacked
+        // the spec's `metric`, `kind`, and `dismissed_at` columns, so the
+        // registry contract (queries.ts worthALookInsight) could never match.
+        // Recreates the LOCAL table to the spec shape, preserving rows:
+        //   id → insight_id, kind defaults to 'threshold', severity
+        //   'critical' → 'urgent' (spec enum is info|warn|urgent).
+        // Idempotent: skips the recreate when `metric` is already present
+        // (fresh installs get the new shape from the baseline ensureSchemas).
+        // The remote zone gets CREATE IF NOT EXISTS only — the client never
+        // destructively rewrites the attached Iceberg catalog; schema
+        // evolution of pre-existing remote tables is a server-side operation.
+        async up(db, catalogs) {
+            const cols = await db.execute(`SELECT column_name FROM information_schema.columns `
+                + `WHERE table_catalog = $catalog AND table_name = 'insight'`, { catalog: catalogs.local });
+            const hasMetric = cols.some(c => c.column_name === 'metric');
+            if (!hasMetric) {
+                // Re-entrancy: a prior partially-failed run may have left the
+                // scratch table behind (KV only advances after full success).
+                await db.execute(`DROP TABLE IF EXISTS ${catalogs.local}.insight_v2;`);
+                const tmpDdl = LOCAL_SCHEMAS.insight.replace('CREATE TABLE insight', `CREATE TABLE ${catalogs.local}.insight_v2`);
+                await db.execute(tmpDdl);
+                // Old rows had no metric column; the package never wrote rows
+                // pre-v2 (rules only emitted events), so 'unknown' only tags
+                // app-authored legacy rows.
+                await db.execute(`INSERT INTO ${catalogs.local}.insight_v2 `
+                    + `(insight_id, ts, brand, family_id, user_id, rule_id, metric, kind, `
+                    + `severity, title, body, evidence, acknowledged_at, dismissed_at) `
+                    + `SELECT id, ts, brand, family_id, user_id, rule_id, 'unknown', 'threshold', `
+                    + `CASE WHEN severity = 'critical' THEN 'urgent' ELSE severity END, `
+                    + `title, body, evidence, acknowledged_at, NULL `
+                    + `FROM ${catalogs.local}.insight;`);
+                await db.execute(`DROP TABLE ${catalogs.local}.insight;`);
+                await db.execute(`ALTER TABLE ${catalogs.local}.insight_v2 RENAME TO insight;`);
+            }
+            await db.execute(insightIndexDdl(catalogs.local));
+            if (catalogs.remote) {
+                await db.execute(qualifyDdl(SCHEMAS.insight, 'insight', `${catalogs.remote}.${REMOTE_NAMESPACE}`));
+            }
+        },
+    },
+    {
+        version: 4,
+        name: 'user_baseline table (Sprint 5 §7)',
+        // Shared day-first baseline store for rules, tools, and screens.
+        //
+        // NOTE ON NUMBERING: the Sprint 5 spec (§33 / tasks T-03) calls this
+        // "migration v3". Versions 2 and 3 were already spent on the
+        // device_battery table and the insight v2 rebuild before Sprint 5
+        // started, so it lands at 4 instead. Same for the spec's "migration v4"
+        // (insight.dismissed_at), which is already satisfied — the column ships
+        // in the baseline DDL and step 3 backfills it, so no ALTER is needed.
+        //
+        // Local-only: baselines are derived from local+R2 union views and are
+        // cheap to recompute, so there is no value in pushing them to R2 and
+        // no correctness story for two devices racing to write the same row.
+        async up(db, catalogs) {
+            await db.execute(qualifyDdl(LOCAL_SCHEMAS.user_baseline, 'user_baseline', catalogs.local));
+        },
+    },
+    {
+        version: 5,
+        name: 'device_config: data_type -> metric (Sprint 5 §2)',
+        // Principle 21 — firmware enums do not belong in the schema. Converts
+        // existing rows using the JStyle J2301A automatic-monitoring enum
+        // (1=heartRate, 2=spo2, 3=temperature, 4=HRV), which is what the old
+        // `data_type` column actually held.
+        //
+        // Numbered 5, not the spec's 2: versions 2-4 were spent before this
+        // landed (device_battery, insight v2, user_baseline).
+        //
+        // Idempotent: skips when `metric` already exists. Local only — the
+        // client never destructively rewrites the attached Iceberg catalog;
+        // remote schema evolution is a server-side operation.
+        async up(db, catalogs) {
+            const cols = await db.execute(`SELECT column_name FROM information_schema.columns `
+                + `WHERE table_catalog = $catalog AND table_name = 'device_config'`, { catalog: catalogs.local });
+            if (cols.length === 0)
+                return; // table absent; baseline will create it
+            if (cols.some(c => c.column_name === 'metric'))
+                return;
+            await db.execute(`DROP TABLE IF EXISTS ${catalogs.local}.device_config_v2;`);
+            const tmpDdl = LOCAL_SCHEMAS.device_config.replace('CREATE TABLE device_config', `CREATE TABLE ${catalogs.local}.device_config_v2`);
+            await db.execute(tmpDdl);
+            await db.execute(`INSERT INTO ${catalogs.local}.device_config_v2 `
+                + `(device_id, brand, family_id, user_id, metric, interval_minutes, `
+                + `start_time, end_time, weeks, valid_from, valid_to) `
+                + `SELECT device_id, brand, family_id, user_id, `
+                + `CASE data_type WHEN 1 THEN 'heart_rate' WHEN 2 THEN 'spo2' `
+                + `WHEN 3 THEN 'temperature' WHEN 4 THEN 'hrv' `
+                // Unknown codes are preserved rather than dropped, so a firmware
+                // revision that added one is diagnosable instead of invisible.
+                + `ELSE 'unknown_' || data_type::VARCHAR END, `
+                + `interval_minutes, start_time, end_time, weeks, valid_from, valid_to `
+                + `FROM ${catalogs.local}.device_config;`);
+            await db.execute(`DROP TABLE ${catalogs.local}.device_config;`);
+            await db.execute(`ALTER TABLE ${catalogs.local}.device_config_v2 RENAME TO device_config;`);
+        },
+    },
 ]);
 /** Version of the latest known migration — target for every attach. */
 export const CURRENT_VERSION = MIGRATIONS.length;

package/dist/core/migrations.js.map

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

package/dist/core/retention.d.ts

@@ -9,9 +9,18 @@
  *      that would preserve data wins.
  *
  *   2. **Sweep** the warehouse via `runRetentionSweep` — issues one DELETE
- *      per retention-managed table, guarded by the per-table push watermark
- *      from `sync_watermark` so rows still awaiting server sync are never
- *      dropped (spec Fix 9).
+ *      per retention-managed table in the LOCAL catalog. The client never
+ *      sweeps the remote R2 zone (principles 17/53): device-side compaction
+ *      prunes local data only; server-side retention is R2 snapshot
+ *      expiration, configured externally.
+ *
+ * Watermark guard (fix CO-1): tables the pusher pushes (`syncable` in
+ * `table_metadata.ts`) are bounded by their KVStore push watermark —
+ * `ts < LEAST(now() - retention, $pushWatermark)` — so rows still awaiting
+ * R2 push are never dropped. No watermark yet (nothing pushed) means the
+ * table is skipped entirely. In `'local'` mode there is no push and never
+ * will be — data is local-forever by design — so the plain retention
+ * cutoff applies without any watermark guard.
  *
  * Internal tables have fixed defaults independent of brand/user config:
  *   - `insight`          → 90 days
@@ -22,6 +31,7 @@
  */
 import type { HybridDuckDB } from './engine';
 import type { TableName } from './schemas';
+import type { AnalyticsMode } from './types';
 export interface EffectiveRetentionInput {
     /** Brand-level default (v0.1.0 active layer) — from `AnalyticsConfig.retention[brand].days`. */
     brandDefault: number;
@@ -42,9 +52,28 @@ export declare function resolveEffectiveRetention(input: EffectiveRetentionInput
 export declare const INSIGHT_RETENTION_DAYS = 90;
 /** Fixed retention for the `tool_call_audit` table — spec §Retention. */
 export declare const AUDIT_RETENTION_DAYS = 30;
+/**
+ * Push-watermark accessor injected by the factory. Resolves the highest
+ * `ts` successfully pushed to R2 for `table` — read from the KVStore key
+ * the pusher writes (`analytics:watermark:{brand}:{familyId}:{table}:push`,
+ * see sync/watermark.ts). `null` means nothing pushed yet.
+ */
+export type PushWatermarkAccessor = (table: TableName) => Promise<Date | null>;
 export interface RetentionSweepInput {
     /** Effective retention days for sensor tables (see `resolveEffectiveRetention`). */
     effectiveDays: number;
+    /**
+     * Attach mode. `'local'` applies plain retention cutoffs — there is no
+     * push in local mode, so nothing ever "reaches R2" and the watermark
+     * guard would block deletion forever. Defaults to `'r2'`.
+     */
+    mode?: AnalyticsMode;
+    /**
+     * Required in r2 mode to sweep syncable tables. Missing accessor or a
+     * `null` watermark ⇒ the table is skipped (spec: no data deleted before
+     * it reaches R2).
+     */
+    getPushWatermark?: PushWatermarkAccessor;
 }
 export interface RetentionSweepEntry {
     table: TableName;
@@ -52,25 +81,25 @@ export interface RetentionSweepEntry {
 }
 export interface RetentionSweepResult {
     swept: RetentionSweepEntry[];
+    /** Syncable tables left untouched because no push watermark exists yet. */
+    skipped: TableName[];
 }
 /**
- * Delete expired rows across every retention-managed table under `catalog`,
- * bounded by each table's push watermark (`sync_watermark.cursor_ts`).
+ * Delete expired rows across every retention-managed table under `catalog`
+ * (the LOCAL DuckDB catalog — never the attached R2 zone).
  *
  * SQL shape per table:
  *
  * ```sql
+ * -- pushed (syncable) tables, r2 mode:
  * DELETE FROM {catalog}.{table}
- *  WHERE {tsCol} < LEAST(
- *    now() - INTERVAL '{days} days',
- *    (SELECT MAX(cursor_ts) FROM {catalog}.sync_watermark
- *      WHERE table_name = '{table}')
- *  );
+ *  WHERE {tsCol} < LEAST(now() - INTERVAL '{days} days',
+ *                        CAST($pushWatermark AS TIMESTAMP));
+ * -- non-pushed tables, and every table in local mode:
+ * DELETE FROM {catalog}.{table}
+ *  WHERE {tsCol} < now() - INTERVAL '{days} days';
  * ```
  *
- * When no watermark exists, `MAX` returns NULL, `LEAST` becomes NULL and the
- * comparison drops to false — safest default (no deletion on unsynced data).
- *
  * Failure at any table surfaces as `AnalyticsError('retention_failed', …)`;
  * the caller decides whether to swallow-and-log or bubble.
  */
@@ -80,6 +109,8 @@ interface DeleteSqlInput {
     table: TableName;
     tsCol: string;
     days: number;
+    /** Bound by `$pushWatermark` (ISO string param, cast to TIMESTAMP). */
+    watermarkBound?: boolean;
 }
 /**
  * Compose the retention DELETE for one table. Extracted so tests can snapshot

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

@@ -1 +1 @@
-{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAI1C,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAMhF;AA6CD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAItC,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,EAAE,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;AAaD,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAS5D"}
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAI5C,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAMhF;AAgDD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAItC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;AAE9E,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAA;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,EAAE,CAAA;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAqC/B;AAaD,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAO5D"}

package/dist/core/retention.js

@@ -9,9 +9,18 @@
  *      that would preserve data wins.
  *
  *   2. **Sweep** the warehouse via `runRetentionSweep` — issues one DELETE
- *      per retention-managed table, guarded by the per-table push watermark
- *      from `sync_watermark` so rows still awaiting server sync are never
- *      dropped (spec Fix 9).
+ *      per retention-managed table in the LOCAL catalog. The client never
+ *      sweeps the remote R2 zone (principles 17/53): device-side compaction
+ *      prunes local data only; server-side retention is R2 snapshot
+ *      expiration, configured externally.
+ *
+ * Watermark guard (fix CO-1): tables the pusher pushes (`syncable` in
+ * `table_metadata.ts`) are bounded by their KVStore push watermark —
+ * `ts < LEAST(now() - retention, $pushWatermark)` — so rows still awaiting
+ * R2 push are never dropped. No watermark yet (nothing pushed) means the
+ * table is skipped entirely. In `'local'` mode there is no push and never
+ * will be — data is local-forever by design — so the plain retention
+ * cutoff applies without any watermark guard.
  *
  * Internal tables have fixed defaults independent of brand/user config:
  *   - `insight`          → 90 days
@@ -21,6 +30,7 @@
  * are skipped.
  */
 import { AnalyticsError } from './errors';
+import { isSyncable } from './table_metadata';
 /**
  * Resolve effective retention days per spec §Retention precedence — returns
  * `max(userOverride ?? 0, familySetting ?? 0, brandDefault)`.
@@ -49,6 +59,11 @@ const TABLE_RETENTION = Object.freeze({
     insight: { tsColumn: 'ts', kind: 'insight' },
     sync_watermark: null,
     tool_call_audit: { tsColumn: 'ts', kind: 'audit' },
+    // Never swept: one row per (user, metric, window) that the baseline
+    // job UPSERTs in place. There is no growth to reclaim, and deleting
+    // by `computed_at` would drop live baselines for any metric whose
+    // recompute is stale.
+    user_baseline: null,
 });
 // -------------------- constants --------------------
 /** Fixed retention for the `insight` table — spec §Retention. */
@@ -56,44 +71,56 @@ export const INSIGHT_RETENTION_DAYS = 90;
 /** Fixed retention for the `tool_call_audit` table — spec §Retention. */
 export const AUDIT_RETENTION_DAYS = 30;
 /**
- * Delete expired rows across every retention-managed table under `catalog`,
- * bounded by each table's push watermark (`sync_watermark.cursor_ts`).
+ * Delete expired rows across every retention-managed table under `catalog`
+ * (the LOCAL DuckDB catalog — never the attached R2 zone).
  *
  * SQL shape per table:
  *
  * ```sql
+ * -- pushed (syncable) tables, r2 mode:
+ * DELETE FROM {catalog}.{table}
+ *  WHERE {tsCol} < LEAST(now() - INTERVAL '{days} days',
+ *                        CAST($pushWatermark AS TIMESTAMP));
+ * -- non-pushed tables, and every table in local mode:
  * DELETE FROM {catalog}.{table}
- *  WHERE {tsCol} < LEAST(
- *    now() - INTERVAL '{days} days',
- *    (SELECT MAX(cursor_ts) FROM {catalog}.sync_watermark
- *      WHERE table_name = '{table}')
- *  );
+ *  WHERE {tsCol} < now() - INTERVAL '{days} days';
  * ```
  *
- * When no watermark exists, `MAX` returns NULL, `LEAST` becomes NULL and the
- * comparison drops to false — safest default (no deletion on unsynced data).
- *
  * Failure at any table surfaces as `AnalyticsError('retention_failed', …)`;
  * the caller decides whether to swallow-and-log or bubble.
  */
 export async function runRetentionSweep(db, catalog, input) {
+    const mode = input.mode ?? 'r2';
     const swept = [];
+    const skipped = [];
     const tableNames = Object.keys(TABLE_RETENTION);
     for (const table of tableNames) {
         const cfg = TABLE_RETENTION[table];
         if (!cfg)
             continue;
         const days = daysForKind(cfg.kind, input.effectiveDays);
-        const sql = buildDeleteSql({ catalog, table, tsCol: cfg.tsColumn, days });
+        const guarded = mode !== 'local' && isSyncable(table);
+        let params;
+        if (guarded) {
+            const watermark = (await input.getPushWatermark?.(table)) ?? null;
+            if (!watermark) {
+                // Nothing pushed yet — deleting would lose data that never
+                // reached R2. Leave the table alone until the pusher advances.
+                skipped.push(table);
+                continue;
+            }
+            params = { pushWatermark: watermark.toISOString() };
+        }
+        const sql = buildDeleteSql({ catalog, table, tsCol: cfg.tsColumn, days, watermarkBound: guarded });
         try {
-            await db.execute(sql);
+            await db.execute(sql, params);
             swept.push({ table, days });
         }
         catch (cause) {
             throw new AnalyticsError('retention_failed', `runRetentionSweep failed on table ${table}`, cause);
         }
     }
-    return { swept };
+    return { swept, skipped };
 }
 function daysForKind(kind, effective) {
     switch (kind) {
@@ -110,11 +137,11 @@ function daysForKind(kind, effective) {
  * the exact SQL issued without a live engine.
  */
 export function buildDeleteSql(input) {
-    const { catalog, table, tsCol, days } = input;
-    return (`DELETE FROM ${catalog}.${table} `
-        + `WHERE ${tsCol} < LEAST(`
-        + `now() - INTERVAL '${days} days', `
-        + `(SELECT MAX(cursor_ts) FROM ${catalog}.sync_watermark WHERE table_name = '${table}')`
-        + `);`);
+    const { catalog, table, tsCol, days, watermarkBound } = input;
+    const cutoff = `now() - INTERVAL '${days} days'`;
+    const bound = watermarkBound
+        ? `LEAST(${cutoff}, CAST($pushWatermark AS TIMESTAMP))`
+        : cutoff;
+    return `DELETE FROM ${catalog}.${table} WHERE ${tsCol} < ${bound};`;
 }
 //# sourceMappingURL=retention.js.map

package/dist/core/retention.js.map

@@ -1 +1 @@
-{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAezC;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA8B;IACtE,OAAO,IAAI,CAAC,GAAG,CACb,KAAK,CAAC,YAAY,IAAI,CAAC,EACvB,KAAK,CAAC,aAAa,IAAI,CAAC,EACxB,KAAK,CAAC,YAAY,CACnB,CAAA;AACH,CAAC;AAuBD,MAAM,eAAe,GAAuD,MAAM,CAAC,MAAM,CAAC;IACxF,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IACvC,UAAU,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC9C,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxC,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC/C,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC5C,eAAe,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IACnD,4EAA4E;IAC5E,mDAAmD;IACnD,aAAa,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;IACrD,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC/C,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC7C,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAChD,cAAc,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;IAClD,aAAa,EAAE,IAAI;IACnB,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;IAC5C,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE;CACnD,CAAC,CAAA;AAEF,sDAAsD;AAEtD,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAA;AACxC,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAkBtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAgB,EAChB,OAAe,EACf,KAA0B;IAE1B,MAAM,KAAK,GAA0B,EAAE,CAAA;IACvC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAgB,CAAA;IAC9D,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;QAClC,IAAI,CAAC,GAAG;YAAE,SAAQ;QAElB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;QACvD,MAAM,GAAG,GAAG,cAAc,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;QACzE,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YACrB,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAC7B,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,kBAAkB,EAClB,qCAAqC,KAAK,EAAE,EAC5C,KAAK,CACN,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAA;AAClB,CAAC;AAED,SAAS,WAAW,CAAC,IAA4B,EAAE,SAAiB;IAClE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,SAAS,CAAA;QAClB,KAAK,SAAS;YACZ,OAAO,sBAAsB,CAAA;QAC/B,KAAK,OAAO;YACV,OAAO,oBAAoB,CAAA;IAC/B,CAAC;AACH,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IAC7C,OAAO,CACL,eAAe,OAAO,IAAI,KAAK,GAAG;UAChC,SAAS,KAAK,WAAW;UACzB,qBAAqB,IAAI,UAAU;UACnC,+BAA+B,OAAO,uCAAuC,KAAK,IAAI;UACtF,IAAI,CACP,CAAA;AACH,CAAC"}
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"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"}

package/dist/core/sampling.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Effective sampling cadence (Sprint 5 T-41, principle 22).
+ *
+ * > **Hardware-agnostic cadence.** Chart rendering, rule evaluation windows,
+ * > and gap detection derive sampling interval from
+ * > `device_config.interval_minutes`, never from constants.
+ *
+ * The point is that a firmware upgrade changing sampling rate should
+ * propagate to charts and rules without an app release. A chart that
+ * hard-codes "SpO₂ every 30 minutes" draws the wrong gaps the day a ring
+ * ships at 5-minute sampling; a rule whose window was sized against 30
+ * minutes silently stops being satisfiable.
+ *
+ * `metric_metadata.sampling_minutes` remains the fallback — it is what we
+ * know before a device has ever reported its schedule, which is every
+ * install until the first sync.
+ *
+ * ## Why this is a runtime read, not a constant
+ *
+ * `device_config` is SCD-2: one open row per (device, metric), with history.
+ * The effective cadence is therefore a property of a *device*, not of the
+ * metric, and two family members on one account can legitimately differ.
+ *
+ * ## Caching
+ *
+ * Memoized per `(deviceId, metric)`. Ring config changes rarely — it only
+ * moves when the user or firmware alters the schedule — so a long TTL is
+ * safe, and `invalidate()` covers the case where a sync just wrote a new
+ * config row.
+ */
+import { type MetricId, type MetricSamplingMinutes } from './metric_metadata';
+import type { AnalyticsEngine, AnalyticsLogger } from './types';
+/** Default memo lifetime. Ring schedules change on the order of never. */
+export declare const SAMPLING_CACHE_TTL_MS: number;
+export interface EffectiveSampling {
+    /** Minutes between samples, or `'per_session'` for sleep metrics. */
+    minutes: MetricSamplingMinutes;
+    /** Where the number came from — surfaced for diagnostics and tests. */
+    source: 'device_config' | 'metric_metadata';
+}
+export interface SamplingResolverConfig {
+    analytics: Pick<AnalyticsEngine, 'execute'>;
+    logger?: AnalyticsLogger;
+    ttlMs?: number;
+    now?: () => number;
+}
+export interface SamplingResolver {
+    /**
+     * Effective cadence for a metric on a device.
+     *
+     * Omitting `deviceId` returns the `metric_metadata` fallback without
+     * touching the database — the right behaviour for register-time
+     * validation, which runs before any device context exists.
+     */
+    resolve(metric: MetricId, deviceId?: string): Promise<EffectiveSampling>;
+    /** Drop memoized entries for a device (all metrics), or everything. */
+    invalidate(deviceId?: string): void;
+}
+/** The fallback, with no I/O. */
+export declare function fallbackSampling(metric: MetricId): EffectiveSampling;
+export declare function createSamplingResolver(config: SamplingResolverConfig): SamplingResolver;
+/**
+ * Minimum window, in minutes, that can hold `consecutive` samples at a
+ * given cadence. Used by the rules validator and by gap detection.
+ *
+ * `per_session` metrics return `null` — "consecutive nights" is bounded by
+ * the rule's window in days, not by a sampling interval.
+ */
+export declare function minimumWindowMinutes(sampling: MetricSamplingMinutes, consecutive: number): number | null;
+//# sourceMappingURL=sampling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","sourceRoot":"","sources":["../../src/core/sampling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE/D,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,QAAiB,CAAA;AAEnD,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,OAAO,EAAE,qBAAqB,CAAA;IAC9B,uEAAuE;IACvE,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAAA;CAC5C;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,CAAA;IAC3C,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACxE,uEAAuE;IACvE,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;AAWD,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,iBAAiB,CAKpE;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,gBAAgB,CA2DlB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,qBAAqB,EAC/B,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAGf"}