@mongrov/analytics 0.6.0 → 0.7.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,EAgHzC,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,68 @@ 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 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":"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"}
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"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"}

package/dist/core/schemas.d.ts

@@ -23,13 +23,82 @@
  */
 import type { HybridDuckDB } from './engine';
 /** Ordered list of every warehouse table. Order = creation order. */
-export declare const TABLE_NAMES: readonly ["hrv", "heart_rate", "spo2", "temperature", "activity", "activity_bucket", "sleep_session", "sleep_stage", "sleep_raw", "device_event", "device_battery", "device_config", "insight", "sync_watermark", "tool_call_audit"];
+export declare const TABLE_NAMES: readonly ["hrv", "heart_rate", "spo2", "temperature", "activity", "activity_bucket", "sleep_session", "sleep_stage", "sleep_raw", "device_event", "device_battery", "device_config", "insight", "sync_watermark", "tool_call_audit", "user_baseline"];
 export type TableName = (typeof TABLE_NAMES)[number];
+/**
+ * Tables that exist only in the local catalog and are never created in the
+ * attached R2 zone.
+ *
+ * `user_baseline` is derived data: it is recomputed from the union views
+ * after each sync cycle and is cheap to rebuild, so pushing it would add an
+ * Iceberg table nobody reads and invite two devices in the same family to
+ * race on the same composite PK.
+ *
+ * `sync_watermark` is deliberately NOT here, despite being per-device
+ * bookkeeping that is never pushed (`TABLE_METADATA.syncable: false`).
+ * Excluding it broke the T-18 retention integration cases, which exercise
+ * the sweep against the real attached Iceberg catalog and need the table
+ * present there. An empty remote copy is harmless; a failing sweep is not.
+ */
+export declare const LOCAL_ONLY_TABLES: ReadonlySet<TableName>;
 /**
  * Frozen DDL for every warehouse table. Copied verbatim from spec §Table
  * schema; rewrite happens in `ensureSchemas` at issue time.
  */
 export declare const SCHEMAS: Readonly<Record<TableName, string>>;
+/**
+ * Lookup index for the `insight` table (spec §Table schema). Local catalog
+ * only — Iceberg has no CREATE INDEX; remote-side query pruning comes from
+ * the `day(ts)` partition instead. Issued by migration step 3.
+ */
+export declare function insightIndexDdl(catalog: string): string;
+/**
+ * Sensor tables exposed through a `v_{table}` union view (Sprint 5 §3).
+ *
+ * Registry queries, rule SQL, and tool SQL all target `v_{table}` and never
+ * `local.{table}` or `r2.default.{table}` directly (principle 19). Internal
+ * tables are absent deliberately: `insight`, `sync_watermark`,
+ * `tool_call_audit`, `user_baseline` and `device_config` are local-authoritative
+ * or local-only, so a union would either duplicate rows or read a remote
+ * copy that is never authoritative.
+ */
+export declare const VIEWED_TABLES: readonly ["hrv", "heart_rate", "spo2", "temperature", "activity", "activity_bucket", "sleep_session", "sleep_stage", "device_event", "device_battery"];
+export type ViewedTable = (typeof VIEWED_TABLES)[number];
+/** Timestamp column the watermark partitions on, per table. */
+export declare function watermarkColumnFor(table: ViewedTable): string;
+/**
+ * Build the `CREATE OR REPLACE VIEW v_{table}` DDL for one sensor table.
+ *
+ * The view is what makes freshness honest: rows the device has flushed
+ * locally but not yet pushed to R2 are invisible in `r2.default.{table}`,
+ * and rows already pushed exist in BOTH catalogs. The push watermark
+ * partitions the two sources exactly —
+ *
+ *   local:  rows strictly AFTER the watermark  (not yet pushed)
+ *   remote: everything                          (pushed)
+ *
+ * — so the union is complete with no duplicates at the boundary, and a row
+ * becomes remote-visible at the same instant it stops being local-visible.
+ *
+ * The watermark subquery reads `sync_watermark` rather than taking a bound
+ * parameter because DuckDB views cannot close over query-time params; the
+ * view must resolve the current cursor on every scan. `$brand` /
+ * `$family_id` are likewise unavailable inside a view body, so the tenant
+ * filter is baked in at creation time from the attach context — which is
+ * safe precisely because views are dropped and recreated on every attach
+ * (T-06), so a brand switch cannot leave a view scoped to the old tenant.
+ *
+ * `remoteCatalog` omitted (local mode) produces a local-only view with no
+ * UNION, so consumers write one SQL string that works in both modes.
+ */
+export declare function generateViewDdl(table: ViewedTable, ctx: {
+    brand: string;
+    familyId: string;
+    localCatalog: string;
+    remoteCatalog?: string;
+}): string;
+/** `DROP VIEW IF EXISTS v_{table}` for detach + brand switch. */
+export declare function dropViewDdl(table: ViewedTable): string;
 /**
  * Rewrite one base DDL to `CREATE TABLE IF NOT EXISTS <catalog>.<table>`.
  *
@@ -62,5 +131,7 @@ export declare const LOCAL_SCHEMAS: Readonly<Record<TableName, string>>;
  * catalog (without). Default is `SCHEMAS` for back-compat with 0.4.x
  * callers that only wrote to the attached remote.
  */
-export declare function ensureSchemas(db: HybridDuckDB, catalog: string, schemas?: Readonly<Record<TableName, string>>): Promise<void>;
+export declare function ensureSchemas(db: HybridDuckDB, catalog: string, schemas?: Readonly<Record<TableName, string>>, opts?: {
+    skipLocalOnly?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=schemas.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,qEAAqE;AACrE,eAAO,MAAM,WAAW,sOAgBd,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAEpD;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CA0KtD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAI7D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAW,GACrD,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,qEAAqE;AACrE,eAAO,MAAM,WAAW,uPAiBd,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,SAAS,CAEnD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAwMtD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,wJAWhB,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF,MAAM,CA0BR;AAkBD,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAI7D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAW,EACtD,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,OAAO,CAAC,IAAI,CAAC,CAmBf"}