@mongrov/analytics 0.23.1 → 0.24.0

package/dist/sync/sleep-correction/sql.js

@@ -0,0 +1,329 @@
+/**
+ * Sleep correction — Phase 2 SQL, ported from DataFusion to DuckDB.
+ *
+ * Source: ziva_app `sleepCorrectionLayer.ts` v3.1. The query SHAPE is kept as
+ * v3.1 wrote it — same CTEs, same self-joins, same UNION ALL offset generator
+ * — so a diff against the original reads as a list of dialect changes only:
+ *
+ *   - `TO_CHAR(TO_TIMESTAMP(d), fmt)` → `strftime(make_timestamp(d * 1000000), fmt)`.
+ *     make_timestamp is naive UTC; `to_timestamp()` would be TIMESTAMPTZ and
+ *     render in the session zone, breaking Phase 3's UTC parse.
+ *   - `APPROX_PERCENTILE_CONT` → `quantile_cont` (exact). Expect ~1-unit
+ *     drift on the tier/p75/p90 scalars; never retune constants to hide it.
+ *   - The unused nested-window `session_start` column is dropped (DuckDB
+ *     rejects nested windows; the final `start` recomputes it anyway).
+ *   - Confidence literals are CAST to DOUBLE — DuckDB types `0.90` as DECIMAL,
+ *     DataFusion as Float64.
+ *
+ * Numbers are inlined, as v3.1 does: every value is computed by this module
+ * (epochs, tier, percentiles), never user input, and inlining sidesteps
+ * react-native-duckdb's untyped-param bind (zivaone_app#70). `num()` refuses
+ * anything non-finite.
+ *
+ * Relations are the v3.1 raw firmware shapes: sleep(date, quality, start,
+ * "unitLength"), heartrate(date, "singleHR"), activity(date, step), epochs in
+ * seconds. Production supplies staging views over the warehouse; the parity
+ * harness supplies tables loaded from captures.
+ */
+import { CONF_ENVELOPE, CONF_FIRMWARE, CONF_GAP, EXTEND_AFTER, FETCH_AFTER, FETCH_BEFORE, HR_MAX, HR_MIN, LONG_GAP_HR_FRAC, LONG_GAP_MAX, LONG_GAP_MIN, STITCH_GAP_LONG, STITCH_GAP_MED, STITCH_GAP_SHORT, } from './classify';
+export const DEFAULT_RELATIONS = {
+    sleep: 'stg_sleep',
+    heartrate: 'stg_heartrate',
+    activity: 'stg_activity',
+};
+const IDENT_RE = /^[a-z_][\w.]*$/i;
+function rel(name) {
+    if (!IDENT_RE.test(name))
+        throw new Error(`sleep-correction: invalid relation name ${JSON.stringify(name)}`);
+    return name;
+}
+function num(v) {
+    if (!Number.isFinite(v))
+        throw new Error(`sleep-correction: non-finite SQL value ${String(v)}`);
+    return String(v);
+}
+/** Once per sync. `hr_interval_minutes` is 5, 10 or 30 (v3.1 CASE, NULL ⇒ 30). */
+export function detectHrTierSql(r = DEFAULT_RELATIONS) {
+    return `
+WITH hr_numbered AS (
+    SELECT date,
+           ROW_NUMBER() OVER (ORDER BY date) AS rn
+    FROM ${rel(r.heartrate)}
+    WHERE "singleHR" BETWEEN ${HR_MIN} AND ${HR_MAX}
+),
+hr_intervals AS (
+    SELECT cur.date - COALESCE(prv.date, cur.date) AS gap_sec
+    FROM hr_numbered cur
+    LEFT JOIN hr_numbered prv ON prv.rn = cur.rn - 1
+    WHERE cur.date - COALESCE(prv.date, cur.date) BETWEEN 61 AND 3599
+),
+median_gap AS (
+    SELECT quantile_cont(gap_sec, 0.5) AS med
+    FROM hr_intervals
+)
+SELECT
+    med AS median_interval_seconds,
+    CASE WHEN med <= 360  THEN 5
+         WHEN med <= 900  THEN 10
+         ELSE 30
+    END AS hr_interval_minutes
+FROM median_gap;`;
+}
+/** Once per sync. Sleeping-HR p90 / p75 since `cutoffEpoch`; 120 when empty. */
+export function globalBaselinesSql(cutoffEpoch, r = DEFAULT_RELATIONS) {
+    return `
+WITH hr_sleep AS (
+    SELECT h."singleHR" AS hr
+    FROM ${rel(r.heartrate)} h
+    INNER JOIN ${rel(r.sleep)} s ON ABS(h.date - s.date) <= 30
+    WHERE h."singleHR" BETWEEN ${HR_MIN} AND ${HR_MAX}
+      AND CAST(s.quality AS INT) IN (1, 2, 3)
+      AND h.date >= ${num(cutoffEpoch)}
+)
+SELECT
+    COALESCE((SELECT quantile_cont(hr, 0.90) FROM hr_sleep), ${HR_MAX}) AS p90_global,
+    COALESCE((SELECT quantile_cont(hr, 0.75) FROM hr_sleep), ${HR_MAX}) AS p75_global;`;
+}
+/** Per night, before Phase 2: zero firmware sleep ⇒ skip the night entirely. */
+export function hasSleepDataSql(windowStart, windowEnd, r = DEFAULT_RELATIONS) {
+    return `
+SELECT COUNT(*) AS has_data
+FROM ${rel(r.sleep)}
+WHERE date >= ${num(windowStart)}
+  AND date <  ${num(windowEnd)}
+  AND CAST(quality AS INT) IN (1, 2, 3, 5);`;
+}
+/** Phase 2 — envelope extension, gap recovery and session stitching. */
+export function correctNightSql(windowStart, windowEnd, hrIntervalMin, globalP75, globalP90, r = DEFAULT_RELATIONS) {
+    const fetchStart = windowStart - FETCH_BEFORE;
+    const fetchEnd = windowEnd + FETCH_AFTER;
+    const offsets = Array.from({ length: hrIntervalMin }, (_, i) => `SELECT ${i} AS v`).join(' UNION ALL ');
+    const ws = num(windowStart);
+    const we = num(windowEnd);
+    return `
+WITH sleep_raw AS (
+    SELECT
+        date,
+        CAST(quality AS INT)    AS quality,
+        start                   AS fw_start,
+        CAST("unitLength" AS INT) AS unit_length
+    FROM ${rel(r.sleep)}
+    WHERE date >= ${ws}
+      AND date <  ${we}
+      AND CAST(quality AS INT) IN (1, 2, 3, 5)
+),
+
+fw_bounds AS (
+    SELECT
+        COALESCE(MIN(date), ${ws}) AS first_fw,
+        COALESCE(MAX(date), ${we}) AS last_fw
+    FROM sleep_raw
+    WHERE quality IN (1, 2, 3, 5)
+),
+
+night_hr AS (
+    SELECT date, "singleHR" AS hr
+    FROM ${rel(r.heartrate)}
+    WHERE date >= ${num(fetchStart)}
+      AND date <= ${num(fetchEnd)}
+      AND "singleHR" BETWEEN ${HR_MIN} AND ${HR_MAX}
+),
+
+effective AS (
+    SELECT
+        fw_bounds.first_fw AS eff_start,
+        fw_bounds.last_fw + ${EXTEND_AFTER} AS eff_end
+    FROM fw_bounds
+),
+
+fw_trimmed AS (
+    SELECT s.date, s.quality, s.fw_start, s.unit_length,
+           CAST(${CONF_FIRMWARE} AS DOUBLE) AS confidence
+    FROM sleep_raw s
+    CROSS JOIN effective e
+    WHERE s.date >= e.eff_start
+      AND s.quality IN (1, 2, 3, 5)
+),
+
+fw_has_rows AS (
+    SELECT CASE WHEN COUNT(*) > 0 THEN 1 ELSE 0 END AS has_rows
+    FROM sleep_raw
+    WHERE quality IN (1, 2, 3, 5)
+),
+
+envelope_hr AS (
+    SELECT h.date AS hr_epoch
+    FROM night_hr h
+    CROSS JOIN effective e
+    CROSS JOIN fw_has_rows fhr
+    CROSS JOIN fw_bounds fb
+    WHERE fhr.has_rows = 1
+      AND h.date >= fb.first_fw
+      AND h.date <= e.eff_end
+      AND h.hr   <= ${num(globalP90)}
+      AND NOT EXISTS (
+          SELECT 1 FROM sleep_raw fs
+          WHERE ABS(fs.date - h.date) <= 30
+            AND fs.quality IN (1, 2, 3, 5)
+      )
+),
+
+offsets AS (${offsets}),
+
+envelope_expanded AS (
+    SELECT DISTINCT
+        eh.hr_epoch + (o.v * 60) AS date,
+        2                         AS quality,
+        NULL                      AS fw_start,
+        1                         AS unit_length,
+        CAST(${CONF_ENVELOPE} AS DOUBLE) AS confidence
+    FROM envelope_hr eh
+    CROSS JOIN offsets o
+    CROSS JOIN effective e
+    WHERE eh.hr_epoch + (o.v * 60) >= e.eff_start
+      AND eh.hr_epoch + (o.v * 60) <= e.eff_end
+),
+
+fw_sessions AS (
+    SELECT fw_start,
+           MIN(date) AS sess_start,
+           MAX(date) AS sess_end,
+           COUNT(*)  AS sess_len
+    FROM sleep_raw
+    WHERE quality IN (1, 2, 3, 5)
+    GROUP BY fw_start
+),
+
+fw_sess_numbered AS (
+    SELECT *,
+           ROW_NUMBER() OVER (ORDER BY sess_start) AS rn
+    FROM fw_sessions
+),
+
+fw_gaps AS (
+    SELECT
+        cur.sess_end   AS gap_start,
+        nxt.sess_start AS gap_end,
+        nxt.sess_start - cur.sess_end AS gap_sec
+    FROM fw_sess_numbered cur
+    LEFT JOIN fw_sess_numbered nxt ON nxt.rn = cur.rn + 1
+    WHERE nxt.sess_start IS NOT NULL
+      AND nxt.sess_start - cur.sess_end BETWEEN ${LONG_GAP_MIN} AND ${LONG_GAP_MAX}
+),
+
+gap_hr_check AS (
+    SELECT
+        fg.gap_start, fg.gap_end,
+        CASE
+            WHEN (SELECT has_rows FROM fw_has_rows) = 0 THEN 0
+            WHEN COUNT(h.date) >= 3
+             AND CAST(SUM(CASE WHEN h.hr <= ${num(globalP75)} THEN 1 ELSE 0 END) AS DOUBLE)
+               / CAST(COUNT(h.date) AS DOUBLE) >= ${LONG_GAP_HR_FRAC}
+            THEN 1 ELSE 0
+        END AS qualifies
+    FROM fw_gaps fg
+    LEFT JOIN night_hr h
+        ON h.date > fg.gap_start
+       AND h.date < fg.gap_end
+    GROUP BY fg.gap_start, fg.gap_end
+),
+
+gap_recovered AS (
+    SELECT DISTINCT
+        h.date + (o.v * 60) AS date,
+        2                    AS quality,
+        NULL                 AS fw_start,
+        1                    AS unit_length,
+        CAST(${CONF_GAP} AS DOUBLE) AS confidence
+    FROM gap_hr_check gc
+    INNER JOIN night_hr h
+        ON h.date > gc.gap_start
+       AND h.date < gc.gap_end
+    CROSS JOIN offsets o
+    WHERE gc.qualifies = 1
+      AND h.date + (o.v * 60) > gc.gap_start
+      AND h.date + (o.v * 60) < gc.gap_end
+),
+
+combined_raw AS (
+    SELECT date, quality, fw_start, unit_length, confidence, 'firmware' AS source
+    FROM fw_trimmed
+    UNION ALL
+    SELECT date, quality, fw_start, unit_length, confidence, 'envelope' AS source
+    FROM envelope_expanded
+    UNION ALL
+    SELECT date, quality, fw_start, unit_length, confidence, 'gap' AS source
+    FROM gap_recovered
+),
+
+deduped AS (
+    SELECT date, quality, fw_start, unit_length, confidence, source
+    FROM (
+        SELECT *,
+            ROW_NUMBER() OVER (
+                PARTITION BY date
+                ORDER BY CASE source WHEN 'firmware' THEN 0 ELSE 1 END
+            ) AS rn
+        FROM combined_raw
+    )
+    WHERE rn = 1
+),
+
+deduped_numbered AS (
+    SELECT *,
+           ROW_NUMBER() OVER (ORDER BY date) AS rn
+    FROM deduped
+),
+
+with_gaps AS (
+    SELECT
+        cur.date, cur.quality, cur.fw_start, cur.unit_length,
+        cur.confidence, cur.source, cur.rn,
+        cur.date - COALESCE(prv.date, cur.date)           AS gap_to_prev,
+        COALESCE(prv.unit_length, 0)                      AS prev_unit_length,
+        COALESCE(prv.date, cur.date)                      AS prev_date
+    FROM deduped_numbered cur
+    LEFT JOIN deduped_numbered prv ON prv.rn = cur.rn - 1
+),
+
+stitched AS (
+    SELECT
+        date, quality, source, confidence,
+        SUM(CASE
+            WHEN gap_to_prev <= ${STITCH_GAP_SHORT}  THEN 0
+            WHEN prev_unit_length = 120
+             AND gap_to_prev <= ${STITCH_GAP_MED}    THEN 0
+            WHEN gap_to_prev <= ${STITCH_GAP_MED}    THEN 0
+            WHEN gap_to_prev <= ${STITCH_GAP_LONG}   THEN 0
+            ELSE 1
+        END) OVER (ORDER BY rn ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS session_id
+    FROM with_gaps
+)
+
+SELECT
+    strftime(make_timestamp(date * 1000000), '%Y.%m.%d %H:%M:%S') AS date,
+    quality,
+    strftime(make_timestamp(MIN(date) OVER (
+        PARTITION BY session_id
+    ) * 1000000), '%Y.%m.%d %H:%M:%S') AS start,
+    1            AS "unitLength",
+    source,
+    confidence,
+    session_id
+FROM stitched
+ORDER BY date;`;
+}
+/** Phase 3 input — HR + step samples for the Step 5.6 END refinement. */
+export function morningVitalsSql(windowStart, windowEnd, r = DEFAULT_RELATIONS) {
+    return `
+SELECT 'hr' AS kind, date AS epoch, "singleHR" AS value
+FROM ${rel(r.heartrate)}
+WHERE date >= ${num(windowStart)} AND date < ${num(windowEnd + FETCH_AFTER)}
+  AND "singleHR" BETWEEN ${HR_MIN} AND ${HR_MAX}
+UNION ALL
+SELECT 'step' AS kind, date AS epoch, step AS value
+FROM ${rel(r.activity)}
+WHERE date >= ${num(windowStart)} AND date < ${num(windowEnd + FETCH_AFTER)}
+ORDER BY epoch;`;
+}
+//# sourceMappingURL=sql.js.map

package/dist/sync/sleep-correction/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../../src/sync/sleep-correction/sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,aAAa,EACb,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,MAAM,EACN,MAAM,EACN,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAQnB,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,KAAK,EAAE,WAAW;IAClB,SAAS,EAAE,eAAe;IAC1B,QAAQ,EAAE,cAAc;CACzB,CAAA;AAED,MAAM,QAAQ,GAAG,iBAAiB,CAAA;AAElC,SAAS,GAAG,CAAC,IAAY;IACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACpF,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,GAAG,CAAC,CAAS;IACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACxE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAA;AAClB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,IAAoB,iBAAiB;IACnE,OAAO;;;;WAIE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;+BACI,MAAM,QAAQ,MAAM;;;;;;;;;;;;;;;;;;iBAkBlC,CAAA;AACjB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,IAAoB,iBAAiB;IAC3F,OAAO;;;WAGE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;iBACV,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;iCACI,MAAM,QAAQ,MAAM;;sBAE/B,GAAG,CAAC,WAAW,CAAC;;;+DAGyB,MAAM;+DACN,MAAM,kBAAkB,CAAA;AACvF,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,SAAiB,EAAE,IAAoB,iBAAiB;IAC3G,OAAO;;OAEF,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;gBACH,GAAG,CAAC,WAAW,CAAC;gBAChB,GAAG,CAAC,SAAS,CAAC;4CACc,CAAA;AAC5C,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAC7B,WAAmB,EACnB,SAAiB,EACjB,aAAqB,EACrB,SAAiB,EACjB,SAAiB,EACjB,IAAoB,iBAAiB;IAErC,MAAM,UAAU,GAAG,WAAW,GAAG,YAAY,CAAA;IAC7C,MAAM,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAA;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IACvG,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,CAAA;IAC3B,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;IAEzB,OAAO;;;;;;;WAOE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;oBACH,EAAE;oBACF,EAAE;;;;;;8BAMQ,EAAE;8BACF,EAAE;;;;;;;WAOrB,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;oBACP,GAAG,CAAC,UAAU,CAAC;oBACf,GAAG,CAAC,QAAQ,CAAC;+BACF,MAAM,QAAQ,MAAM;;;;;;8BAMrB,YAAY;;;;;;kBAMxB,aAAa;;;;;;;;;;;;;;;;;;;;;;sBAsBT,GAAG,CAAC,SAAS,CAAC;;;;;;;;cAQtB,OAAO;;;;;;;;eAQN,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAgCsB,YAAY,QAAQ,YAAY;;;;;;;;;8CASpC,GAAG,CAAC,SAAS,CAAC;oDACR,gBAAgB;;;;;;;;;;;;;;;;eAgBrD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAwDW,gBAAgB;;kCAEhB,cAAc;kCACd,cAAc;kCACd,eAAe;;;;;;;;;;;;;;;;;eAiBlC,CAAA;AACf,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,SAAiB,EAAE,IAAoB,iBAAiB;IAC5G,OAAO;;OAEF,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;gBACP,GAAG,CAAC,WAAW,CAAC,eAAe,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC;2BAChD,MAAM,QAAQ,MAAM;;;OAGxC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;gBACN,GAAG,CAAC,WAAW,CAAC,eAAe,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC;gBAC3D,CAAA;AAChB,CAAC"}

package/dist/sync/sleep-correction/staging.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Staging views: the warehouse, re-shaped into v3.1's raw firmware relations.
+ *
+ * The pipeline's SQL reads sleep(date, quality, start, "unitLength"),
+ * heartrate(date, "singleHR") and activity(date, step) with epoch-second
+ * dates — the shapes v3.1 was validated on. Rather than rewrite the SQL for
+ * the warehouse columns, these TEMP views rename back at the boundary, so the
+ * ported queries stay as close to v3.1 as the parity suite proved them.
+ *
+ * - sleep comes from the LOCAL `sleep_raw` (not viewed: collected-only, and
+ *   the nights a batch touches are local). Catalog-qualified, because after
+ *   an R2 attach an unqualified name resolves to the remote catalog.
+ * - HR and steps come from `v_heart_rate` / `v_activity`, so a 30-day
+ *   baseline lookback sees remote history too.
+ * - One user and one device: the correction is per ring.
+ *
+ * `sleep_raw.quality` must hold the firmware's own codes (1 deep / 2 light /
+ * 3 rem / 5 awake). That is true only once the producer sends raw rows
+ * (sleep-correction tasks §3); until then these views are exercised by tests.
+ */
+import type { SleepRelations } from './sql';
+export interface StagingScope {
+    brand: string;
+    familyId: string;
+    userId: string;
+    deviceId: string;
+    /** Local DuckDB catalog holding `sleep_raw`. */
+    localCatalog?: string;
+}
+/** `CREATE OR REPLACE TEMP VIEW` statements for the three staging relations. */
+export declare function stagingViewsSql(scope: StagingScope, r?: SleepRelations): string[];
+//# sourceMappingURL=staging.d.ts.map

package/dist/sync/sleep-correction/staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/sync/sleep-correction/staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AASD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,GAAE,cAAkC,GAAG,MAAM,EAAE,CAsBpG"}

package/dist/sync/sleep-correction/staging.js

@@ -0,0 +1,51 @@
+/**
+ * Staging views: the warehouse, re-shaped into v3.1's raw firmware relations.
+ *
+ * The pipeline's SQL reads sleep(date, quality, start, "unitLength"),
+ * heartrate(date, "singleHR") and activity(date, step) with epoch-second
+ * dates — the shapes v3.1 was validated on. Rather than rewrite the SQL for
+ * the warehouse columns, these TEMP views rename back at the boundary, so the
+ * ported queries stay as close to v3.1 as the parity suite proved them.
+ *
+ * - sleep comes from the LOCAL `sleep_raw` (not viewed: collected-only, and
+ *   the nights a batch touches are local). Catalog-qualified, because after
+ *   an R2 attach an unqualified name resolves to the remote catalog.
+ * - HR and steps come from `v_heart_rate` / `v_activity`, so a 30-day
+ *   baseline lookback sees remote history too.
+ * - One user and one device: the correction is per ring.
+ *
+ * `sleep_raw.quality` must hold the firmware's own codes (1 deep / 2 light /
+ * 3 rem / 5 awake). That is true only once the producer sends raw rows
+ * (sleep-correction tasks §3); until then these views are exercised by tests.
+ */
+import { DEFAULT_RELATIONS } from './sql';
+const CATALOG_RE = /^[a-z_]\w*$/i;
+const QUOTE_RE = /'/g;
+function lit(s) {
+    return `'${s.replace(QUOTE_RE, '\'\'')}'`;
+}
+/** `CREATE OR REPLACE TEMP VIEW` statements for the three staging relations. */
+export function stagingViewsSql(scope, r = DEFAULT_RELATIONS) {
+    const catalog = scope.localCatalog ?? 'memory';
+    if (!CATALOG_RE.test(catalog))
+        throw new Error(`sleep-correction: invalid catalog ${JSON.stringify(catalog)}`);
+    const tenant = `user_id = ${lit(scope.userId)} AND device_id = ${lit(scope.deviceId)}`;
+    return [
+        `CREATE OR REPLACE TEMP VIEW ${r.sleep} AS
+SELECT CAST(epoch(ts) AS BIGINT) AS date,
+       quality,
+       CAST(epoch(ts_session_start) AS BIGINT) AS start,
+       unit_length AS "unitLength"
+FROM ${catalog}.main.sleep_raw
+WHERE brand = ${lit(scope.brand)} AND family_id = ${lit(scope.familyId)} AND ${tenant}`,
+        `CREATE OR REPLACE TEMP VIEW ${r.heartrate} AS
+SELECT CAST(epoch(ts) AS BIGINT) AS date, bpm AS "singleHR"
+FROM v_heart_rate
+WHERE ${tenant}`,
+        `CREATE OR REPLACE TEMP VIEW ${r.activity} AS
+SELECT CAST(epoch(ts) AS BIGINT) AS date, steps AS step
+FROM v_activity
+WHERE ${tenant}`,
+    ];
+}
+//# sourceMappingURL=staging.js.map

package/dist/sync/sleep-correction/staging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.js","sourceRoot":"","sources":["../../../src/sync/sleep-correction/staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAWzC,MAAM,UAAU,GAAG,cAAc,CAAA;AACjC,MAAM,QAAQ,GAAG,IAAI,CAAA;AAErB,SAAS,GAAG,CAAC,CAAS;IACpB,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAA;AAC3C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,IAAoB,iBAAiB;IACxF,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,IAAI,QAAQ,CAAA;IAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACjF,MAAM,MAAM,GAAG,aAAa,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,oBAAoB,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAA;IACtF,OAAO;QACL,+BAA+B,CAAC,CAAC,KAAK;;;;;OAKnC,OAAO;gBACE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,oBAAoB,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,MAAM,EAAE;QACnF,+BAA+B,CAAC,CAAC,SAAS;;;QAGtC,MAAM,EAAE;QACZ,+BAA+B,CAAC,CAAC,QAAQ;;;QAGrC,MAAM,EAAE;KACb,CAAA;AACH,CAAC"}

package/dist/sync/sleep-derive.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Derived sleep — the correction step every batch cycle runs before
+ * `batch:complete` (sleep-correction §3).
+ *
+ * `sleep_raw` is written like any sensor table. Sessions and stages are not:
+ * they are derived from it by the validated correction pipeline, night by
+ * night, and written back into the SAME batch, so a `context: 'asleep'` rule
+ * woken by `batch:complete` sees corrected sleep, never raw minutes.
+ *
+ * Raw rows can arrive by three flush paths (scheduled cycle, manual flush,
+ * size/age triggers), so the deriver does not hang off any one flush: it
+ * notes every enqueued `sleep_raw` range, and the next batch cycle corrects
+ * all pending nights after its flushes land.
+ *
+ * Night replace (principle 66 as amended): a corrected night's END moves as
+ * later data arrives, and the principle-25 id moves with it, so a night is
+ * DELETEd locally before its new rows are written. Nights that come back with
+ * no primary block are left alone — replacing a night with nothing on a
+ * partial sync would erase sleep the next sync restores.
+ *
+ * Local only. Rows already pushed to a remote catalog are not rewritten; that
+ * needs a server-side answer before cloud sync is switched on.
+ */
+import type { HybridDuckDB } from '../core/engine';
+import type { SensorBuffer } from './buffer';
+import type { BatchFlusher, FlushReason } from './flusher';
+import type { SchedulerLogger } from './scheduler';
+export interface SleepDeriverDeps {
+    engine: HybridDuckDB;
+    buffer: SensorBuffer;
+    flusher: BatchFlusher;
+    /** The user's IANA zone (the factory's `resolveTimezone`). */
+    resolveTimezone: (userId: string) => Promise<string>;
+    /** Baseline lookback. v3.1 production: 30 days. */
+    lookbackDays?: number;
+    now?: () => number;
+    logger?: SchedulerLogger;
+    localCatalog?: string;
+}
+export interface SleepDeriver {
+    /** Record an enqueued `sleep_raw` batch so the next cycle corrects its nights. */
+    noteRaw: (batch: {
+        brand: string;
+        familyId: string;
+        userId: string;
+        deviceId: string;
+        rows: ReadonlyArray<Record<string, unknown>>;
+    }) => void;
+    /** (user, device) ranges still waiting for a cycle. */
+    pendingCount: () => number;
+    /** Correct every pending range and write its nights into `batchId`. Never throws. */
+    derive: (batchId: string, reason: FlushReason) => Promise<void>;
+}
+export declare function createSleepDeriver(deps: SleepDeriverDeps): SleepDeriver;
+//# sourceMappingURL=sleep-derive.d.ts.map

package/dist/sync/sleep-derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-derive.d.ts","sourceRoot":"","sources":["../../src/sync/sleep-derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAiBlD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,YAAY,CAAA;IACrB,8DAA8D;IAC9D,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,OAAO,EAAE,CAAC,KAAK,EAAE;QACf,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAC7C,KAAK,IAAI,CAAA;IACV,uDAAuD;IACvD,YAAY,EAAE,MAAM,MAAM,CAAA;IAC1B,qFAAqF;IACrF,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAChE;AA8CD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAuHvE"}

package/dist/sync/sleep-derive.js

@@ -0,0 +1,180 @@
+/**
+ * Derived sleep — the correction step every batch cycle runs before
+ * `batch:complete` (sleep-correction §3).
+ *
+ * `sleep_raw` is written like any sensor table. Sessions and stages are not:
+ * they are derived from it by the validated correction pipeline, night by
+ * night, and written back into the SAME batch, so a `context: 'asleep'` rule
+ * woken by `batch:complete` sees corrected sleep, never raw minutes.
+ *
+ * Raw rows can arrive by three flush paths (scheduled cycle, manual flush,
+ * size/age triggers), so the deriver does not hang off any one flush: it
+ * notes every enqueued `sleep_raw` range, and the next batch cycle corrects
+ * all pending nights after its flushes land.
+ *
+ * Night replace (principle 66 as amended): a corrected night's END moves as
+ * later data arrives, and the principle-25 id moves with it, so a night is
+ * DELETEd locally before its new rows are written. Nights that come back with
+ * no primary block are left alone — replacing a night with nothing on a
+ * partial sync would erase sleep the next sync restores.
+ *
+ * Local only. Rows already pushed to a remote catalog are not rewritten; that
+ * needs a server-side answer before cloud sync is switched on.
+ */
+import { sessionsFromCorrected } from './mapper/sleep';
+import { computeNightOf } from './mapper/time';
+import { correctSleepNights, nightsForEpochs } from './sleep-correction/orchestrate';
+import { stagingViewsSql } from './sleep-correction/staging';
+const SIX_HOURS = 6 * 3600;
+function epochOf(ts) {
+    if (ts instanceof Date)
+        return Math.floor(ts.getTime() / 1000);
+    if (typeof ts === 'number')
+        return Math.floor(ts > 1e12 ? ts / 1000 : ts);
+    if (typeof ts === 'string') {
+        const ms = Date.parse(ts.includes('T') ? ts : `${ts.replace(' ', 'T')}Z`);
+        return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+    }
+    return null;
+}
+/** The `night_of` value a session starting inside this window is stored with. */
+function storedNightOf(windowStart, timeZone) {
+    return computeNightOf(new Date((windowStart + 60) * 1000), timeZone).toISOString().slice(0, 10);
+}
+/** Every 6pm→6pm night between two instants, inclusive. */
+function nightsBetween(minEpoch, maxEpoch, timeZone) {
+    const probes = [];
+    for (let e = minEpoch; e < maxEpoch; e += SIX_HOURS)
+        probes.push(e);
+    probes.push(maxEpoch);
+    return nightsForEpochs(probes, timeZone);
+}
+function DELETE_STAGES_SQL(catalog) {
+    return `
+DELETE FROM ${catalog}.main.sleep_stage
+WHERE session_id IN (
+  SELECT session_id FROM ${catalog}.main.sleep_session
+  WHERE brand = $brand AND family_id = $family_id AND user_id = $user_id
+    AND device_id = $device_id AND night_of = CAST($night AS DATE)
+)`;
+}
+function DELETE_SESSIONS_SQL(catalog) {
+    return `
+DELETE FROM ${catalog}.main.sleep_session
+WHERE brand = $brand AND family_id = $family_id AND user_id = $user_id
+  AND device_id = $device_id AND night_of = CAST($night AS DATE)`;
+}
+export function createSleepDeriver(deps) {
+    const pending = new Map();
+    const catalog = deps.localCatalog ?? 'memory';
+    const now = deps.now ?? (() => Date.now());
+    const lookbackDays = deps.lookbackDays ?? 30;
+    async function replaceNight(ctx, night) {
+        const params = {
+            brand: ctx.brand,
+            family_id: ctx.familyId,
+            user_id: ctx.userId,
+            device_id: ctx.deviceId,
+            night,
+        };
+        await deps.engine.execute(DELETE_STAGES_SQL(catalog), params);
+        await deps.engine.execute(DELETE_SESSIONS_SQL(catalog), params);
+    }
+    async function deriveRange(p) {
+        const timeZone = await deps.resolveTimezone(p.userId);
+        const ctx = {
+            brand: p.brand,
+            familyId: p.familyId,
+            userId: p.userId,
+            deviceId: p.deviceId,
+            userTimezone: timeZone,
+        };
+        for (const sql of stagingViewsSql({ ...ctx, localCatalog: catalog }))
+            await deps.engine.execute(sql);
+        const result = await correctSleepNights(deps.engine, {
+            nights: nightsBetween(p.minEpoch, p.maxEpoch, timeZone),
+            timeZone,
+            cutoffEpoch: Math.floor(now() / 1000) - lookbackDays * 86400,
+        });
+        const sessions = [];
+        const stages = [];
+        for (const n of result.nights) {
+            if (n.status === 'failed')
+                deps.logger?.warn('sync.sleep-derive: night failed; previous rows kept', { night: n.night, err: n.error });
+            if (n.status !== 'ok' || !n.rows)
+                continue;
+            const out = sessionsFromCorrected(n.rows, ctx, { settleMin: n.settleMin });
+            if (out.sleep_session.length === 0)
+                continue;
+            // Two conventions meet here. v3.1 names a night by its MORNING date
+            // (window Jun 17 18:00 → Jun 18 18:00 is "2026-06-18"); `night_of` is
+            // the mapper's evening date, stored as the UTC date of `computeNightOf`.
+            // Deleting by `n.night` would wipe the FOLLOWING night — so the key is
+            // derived exactly as the writer derives it, from inside the window.
+            const nights = new Set([
+                storedNightOf(n.windowStart, timeZone),
+                ...out.sleep_session.map(s => s.night_of.toISOString().slice(0, 10)),
+            ]);
+            for (const night of nights)
+                await replaceNight(ctx, night);
+            sessions.push(...out.sleep_session);
+            stages.push(...out.sleep_stage);
+        }
+        return { sessions, stages };
+    }
+    return {
+        noteRaw(batch) {
+            let min = Number.POSITIVE_INFINITY;
+            let max = Number.NEGATIVE_INFINITY;
+            for (const row of batch.rows) {
+                const e = epochOf(row.ts);
+                if (e == null)
+                    continue;
+                if (e < min)
+                    min = e;
+                if (e > max)
+                    max = e;
+            }
+            if (!Number.isFinite(min))
+                return;
+            const key = `${batch.brand}|${batch.familyId}|${batch.userId}|${batch.deviceId}`;
+            const prev = pending.get(key);
+            pending.set(key, {
+                brand: batch.brand,
+                familyId: batch.familyId,
+                userId: batch.userId,
+                deviceId: batch.deviceId,
+                minEpoch: prev ? Math.min(prev.minEpoch, min) : min,
+                maxEpoch: prev ? Math.max(prev.maxEpoch, max) : max,
+            });
+        },
+        pendingCount: () => pending.size,
+        async derive(batchId, reason) {
+            if (pending.size === 0)
+                return;
+            const ranges = [...pending.values()];
+            pending.clear();
+            for (const p of ranges) {
+                try {
+                    const { sessions, stages } = await deriveRange(p);
+                    const tenant = { brand: p.brand, familyId: p.familyId, userId: p.userId, deviceId: p.deviceId };
+                    if (sessions.length > 0)
+                        await deps.buffer.push({ table: 'sleep_session', ...tenant, rows: sessions });
+                    if (stages.length > 0)
+                        await deps.buffer.push({ table: 'sleep_stage', ...tenant, rows: stages });
+                }
+                catch (err) {
+                    deps.logger?.warn('sync.sleep-derive: correction failed; raw sleep kept, nights unchanged', {
+                        userId: p.userId,
+                        deviceId: p.deviceId,
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // Land the derived rows inside this batch, so batch:complete follows them.
+            await deps.flusher.flush('sleep_session', reason, batchId);
+            await deps.flusher.flush('sleep_stage', reason, batchId);
+        },
+    };
+}
+//# sourceMappingURL=sleep-derive.js.map