@mongrov/analytics 0.5.0 → 0.7.0

package/dist/core/watermark-cache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Push-watermark cache (Sprint 5 T-07 / item (b)).
+ *
+ * **Disabled by default, and deliberately so.** Every `v_{table}` scan
+ * resolves the push watermark through a correlated subquery against
+ * `sync_watermark`. That is presumed cheap — a primary-key lookup against a
+ * table with one row per (tenant, table, kind) — but "presumed" is the
+ * operative word, and caching a value that gates data visibility is exactly
+ * the kind of optimisation that trades a measurable millisecond for an
+ * unmeasurable correctness bug.
+ *
+ * So this ships behind a measurement gate (principles §Open Items,
+ * "Watermark cache activation — pilot measurement gate"): the instrument
+ * runs always, the cache runs only when p95 query latency for hot registry
+ * queries exceeds 20ms in the Ziva pilot and an operator opts in via
+ * `AnalyticsConfig.watermarkCache: true`.
+ *
+ * Staleness is bounded on two axes:
+ *   - a 5-second TTL, so the worst case is bounded even if invalidation is
+ *     missed entirely;
+ *   - explicit invalidation on `{table}:sync_complete`, which is the only
+ *     event that advances a push watermark.
+ *
+ * A stale-high watermark would hide freshly-flushed local rows; a
+ * stale-low one would double-count rows present in both catalogs. The TTL
+ * caps both windows at 5s, which is below the shortest sync cycle.
+ */
+import type { EventBus } from './types';
+/** Cache lifetime. Below the shortest sync cycle, so drift cannot compound. */
+export declare const WATERMARK_CACHE_TTL_MS = 5000;
+export interface WatermarkCacheStats {
+    hits: number;
+    misses: number;
+    invalidations: number;
+    expirations: number;
+    /** Rolling p50/p95/p99 over observed loader latencies, in ms. */
+    latency: {
+        p50: number;
+        p95: number;
+        p99: number;
+        samples: number;
+    };
+}
+export interface WatermarkCacheOptions {
+    /** Master switch. `false` (default) makes every read a pass-through. */
+    enabled?: boolean;
+    /** Override the 5s TTL. Tests inject shorter values. */
+    ttlMs?: number;
+    /** Injectable clock so tests need no timers. */
+    now?: () => number;
+    /**
+     * Bus to subscribe for `{table}:sync_complete`. Omitted → the cache
+     * relies on TTL expiry alone.
+     */
+    eventBus?: EventBus;
+}
+export interface WatermarkCache {
+    /**
+     * Resolve a watermark, consulting the cache when enabled.
+     *
+     * `load` is always the source of truth; the cache only ever elides a
+     * call to it. When disabled, this is `load()` plus instrumentation.
+     */
+    get(brand: string, familyId: string, table: string, load: () => Promise<Date | null>): Promise<Date | null>;
+    /** Drop one table's entry across all tenants. */
+    invalidate(table: string): void;
+    /** Drop everything — used on attach/detach and brand switch. */
+    clear(): void;
+    stats(): WatermarkCacheStats;
+    /** Detach the event-bus subscription. */
+    dispose(): void;
+    readonly enabled: boolean;
+}
+export declare function createWatermarkCache(options?: WatermarkCacheOptions): WatermarkCache;
+//# sourceMappingURL=watermark-cache.d.ts.map

package/dist/core/watermark-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark-cache.d.ts","sourceRoot":"","sources":["../../src/core/watermark-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,OAAQ,CAAA;AAE3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAsBD,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,GAAG,CACD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,GAC/B,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;IACvB,iDAAiD;IACjD,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,gEAAgE;IAChE,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,mBAAmB,CAAA;IAC5B,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAA;IACf,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,cAAc,CA6FhB"}

package/dist/core/watermark-cache.js.map

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

package/dist/rules/__fakes__/fakeEngine.d.ts

@@ -9,6 +9,8 @@ export interface FakeEngine extends AnalyticsEngine {
     __setError(err: Error | null): void;
     /** Mutate the reported `state` for tests that exercise the attached-state guard. */
     __setState(state: AnalyticsState): void;
+    /** Seed the roster returned by `getFamilyMembers()`. */
+    __setFamilyMembers(ids: string[]): void;
 }
 export declare function createFakeEngine(): FakeEngine;
 //# sourceMappingURL=fakeEngine.d.ts.map

package/dist/rules/__fakes__/fakeEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fakeEngine.d.ts","sourceRoot":"","sources":["../../../src/rules/__fakes__/fakeEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEvE,wDAAwD;AACxD,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;IAC3D,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAClC,UAAU,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,CAAA;IACnC,oFAAoF;IACpF,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;CACxC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAkC7C"}
+{"version":3,"file":"fakeEngine.d.ts","sourceRoot":"","sources":["../../../src/rules/__fakes__/fakeEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEvE,wDAAwD;AACxD,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;IAC3D,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAClC,UAAU,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,CAAA;IACnC,oFAAoF;IACpF,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;IACvC,wDAAwD;IACxD,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACxC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAsC7C"}

package/dist/rules/__fakes__/fakeEngine.js

@@ -2,10 +2,13 @@ export function createFakeEngine() {
     let queued = [];
     let queuedErr = null;
     let state = 'attached';
+    let familyMembers = [];
     const calls = [];
     const engine = {
         async attach() { },
         async detach() { },
+        async getFamilyMembers() { return familyMembers; },
+        async dismissInsight() { },
         async execute(sql, params) {
             calls.push({ sql, params: params ?? {} });
             if (queuedErr)
@@ -30,6 +33,7 @@ export function createFakeEngine() {
         __setResult(rows) { queued = rows; queuedErr = null; },
         __setError(err) { queuedErr = err; },
         __setState(s) { state = s; },
+        __setFamilyMembers(ids) { familyMembers = ids; },
     };
     return engine;
 }

package/dist/rules/__fakes__/fakeEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"fakeEngine.js","sourceRoot":"","sources":["../../../src/rules/__fakes__/fakeEngine.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,gBAAgB;IAC9B,IAAI,MAAM,GAAc,EAAE,CAAA;IAC1B,IAAI,SAAS,GAAiB,IAAI,CAAA;IAClC,IAAI,KAAK,GAAmB,UAAU,CAAA;IACtC,MAAM,KAAK,GAAuD,EAAE,CAAA;IAEpE,MAAM,MAAM,GAAe;QACzB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,OAAO,CAAI,GAAW,EAAE,MAAgC;YAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC,CAAA;YACzC,IAAI,SAAS;gBAAE,MAAM,SAAS,CAAA;YAC9B,OAAO,MAAa,CAAA;QACtB,CAAC;QACD,MAAM;YACJ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;QACnD,CAAC;QACD,cAAc;YACZ,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC3D,CAAC;QACD,IAAI,KAAK,KAAK,OAAO,KAAK,CAAA,CAAC,CAAC;QAC5B,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,IAAI;QACV,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACzB,KAAK,CAAC,YAAY,KAAI,CAAC;QACvB,KAAK,CAAC,aAAa,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QACrC,KAAK,CAAC,KAAK,KAAI,CAAC;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,CAAC,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,CAAA,CAAC,CAAC;QACrD,UAAU,CAAC,GAAG,IAAI,SAAS,GAAG,GAAG,CAAA,CAAC,CAAC;QACnC,UAAU,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAA,CAAC,CAAC;KAC5B,CAAA;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"fakeEngine.js","sourceRoot":"","sources":["../../../src/rules/__fakes__/fakeEngine.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,gBAAgB;IAC9B,IAAI,MAAM,GAAc,EAAE,CAAA;IAC1B,IAAI,SAAS,GAAiB,IAAI,CAAA;IAClC,IAAI,KAAK,GAAmB,UAAU,CAAA;IACtC,IAAI,aAAa,GAAa,EAAE,CAAA;IAChC,MAAM,KAAK,GAAuD,EAAE,CAAA;IAEpE,MAAM,MAAM,GAAe;QACzB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,gBAAgB,KAAK,OAAO,aAAa,CAAA,CAAC,CAAC;QACjD,KAAK,CAAC,cAAc,KAAI,CAAC;QACzB,KAAK,CAAC,OAAO,CAAI,GAAW,EAAE,MAAgC;YAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC,CAAA;YACzC,IAAI,SAAS;gBAAE,MAAM,SAAS,CAAA;YAC9B,OAAO,MAAa,CAAA;QACtB,CAAC;QACD,MAAM;YACJ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;QACnD,CAAC;QACD,cAAc;YACZ,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC3D,CAAC;QACD,IAAI,KAAK,KAAK,OAAO,KAAK,CAAA,CAAC,CAAC;QAC5B,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,IAAI;QACV,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACzB,KAAK,CAAC,YAAY,KAAI,CAAC;QACvB,KAAK,CAAC,aAAa,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QACrC,KAAK,CAAC,KAAK,KAAI,CAAC;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,CAAC,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,CAAA,CAAC,CAAC;QACrD,UAAU,CAAC,GAAG,IAAI,SAAS,GAAG,GAAG,CAAA,CAAC,CAAC;QACnC,UAAU,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAA,CAAC,CAAC;QAC3B,kBAAkB,CAAC,GAAG,IAAI,aAAa,GAAG,GAAG,CAAA,CAAC,CAAC;KAChD,CAAA;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/rules/baseline-reader.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Baseline reader (Sprint 5 T-24).
+ *
+ * Rules with `baseline_percent` / `baseline_stddev` targets need the user's
+ * usual range. The scheduled job in `analytics-sync/baseline-compute.ts`
+ * writes it to `user_baseline` after each sync cycle — but a rule can fire
+ * before the first compute has run, so this reader falls back to computing
+ * on read.
+ *
+ * The fallback uses the **same day-first pattern** as the scheduled job.
+ * That consistency is the whole point of the module: if the on-read path
+ * quantiled raw readings while the scheduled path quantiled daily values,
+ * the same rule would fire or not depending purely on whether a sync cycle
+ * had happened yet — a heisenbug in a health alert.
+ *
+ * Results are cached for the duration of one evaluation batch. Within a
+ * batch, every rule x user combination reads a consistent baseline;
+ * across batches, fresh reads pick up the latest compute.
+ */
+import { type BaselineWindowDays, type MetricId } from '../core/metric_metadata';
+import type { AnalyticsEngine } from '../core/types';
+import type { RulesLogger } from './types';
+export interface Baseline {
+    p05: number | null;
+    p10: number | null;
+    p50: number | null;
+    p90: number | null;
+    p95: number | null;
+    mean: number | null;
+    stddev: number | null;
+    /** Number of DAYS the baseline is built from, never readings. */
+    sampleCount: number;
+    /** True when this came from an on-read compute, not the stored table. */
+    computedOnRead: boolean;
+}
+export interface BaselineReaderConfig {
+    analytics: AnalyticsEngine;
+    logger?: RulesLogger;
+    /**
+     * IANA zone for the on-read fallback's day bucketing. Only the fallback
+     * needs it — stored rows were already bucketed at compute time.
+     */
+    timezone?: string;
+}
+export interface BaselineReader {
+    /** Null when the user has fewer than `BASELINE_MIN_DAYS` days of data. */
+    getBaseline(userId: string, metric: MetricId, windowDays: BaselineWindowDays, ctx: {
+        brand: string;
+        familyId: string;
+    }): Promise<Baseline | null>;
+    /** Drop the per-batch cache. Called at the start of each evaluation pass. */
+    resetCache(): void;
+}
+export declare function createBaselineReader(config: BaselineReaderConfig): BaselineReader;
+//# sourceMappingURL=baseline-reader.d.ts.map

package/dist/rules/baseline-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-reader.d.ts","sourceRoot":"","sources":["../../src/rules/baseline-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,eAAe,CAAA;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,WAAW,CACT,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,EAChB,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACvC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IAC3B,6EAA6E;IAC7E,UAAU,IAAI,IAAI,CAAA;CACnB;AAaD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,cAAc,CAwGhB"}

package/dist/rules/baseline-reader.js

@@ -0,0 +1,111 @@
+/**
+ * Baseline reader (Sprint 5 T-24).
+ *
+ * Rules with `baseline_percent` / `baseline_stddev` targets need the user's
+ * usual range. The scheduled job in `analytics-sync/baseline-compute.ts`
+ * writes it to `user_baseline` after each sync cycle — but a rule can fire
+ * before the first compute has run, so this reader falls back to computing
+ * on read.
+ *
+ * The fallback uses the **same day-first pattern** as the scheduled job.
+ * That consistency is the whole point of the module: if the on-read path
+ * quantiled raw readings while the scheduled path quantiled daily values,
+ * the same rule would fire or not depending purely on whether a sync cycle
+ * had happened yet — a heisenbug in a health alert.
+ *
+ * Results are cached for the duration of one evaluation batch. Within a
+ * batch, every rule x user combination reads a consistent baseline;
+ * across batches, fresh reads pick up the latest compute.
+ */
+import { buildBaselineSql } from '../sync/baseline-compute';
+import { BASELINE_MIN_DAYS, } from '../core/metric_metadata';
+export function createBaselineReader(config) {
+    const { analytics, logger } = config;
+    const cache = new Map();
+    function key(userId, metric, windowDays, brand, familyId) {
+        return `${brand} ${familyId} ${userId} ${metric} ${windowDays}`;
+    }
+    async function readStored(userId, metric, windowDays, ctx) {
+        const rows = await analytics.execute(`SELECT p05, p10, p50, p90, p95, mean, stddev, sample_count
+       FROM user_baseline
+       WHERE brand = $brand AND family_id = $familyId AND user_id = $userId
+         AND metric = $metric AND window_days = $windowDays
+       LIMIT 1`, {
+            brand: ctx.brand,
+            familyId: ctx.familyId,
+            userId,
+            metric,
+            windowDays,
+        });
+        const row = rows[0];
+        if (!row || row.sample_count === null || row.sample_count < BASELINE_MIN_DAYS) {
+            return null;
+        }
+        return { ...toBaseline(row), computedOnRead: false };
+    }
+    async function computeOnRead(userId, metric, windowDays, ctx) {
+        // Identical SQL to the scheduled job — imported, not reimplemented, so
+        // the two paths cannot drift.
+        const rows = await analytics.execute(buildBaselineSql(metric, windowDays), {
+            userId,
+            brand: ctx.brand,
+            familyId: ctx.familyId,
+            tz: config.timezone ?? 'UTC',
+            windowDays,
+        });
+        const row = rows[0];
+        if (!row || row.sample_count === null || row.sample_count < BASELINE_MIN_DAYS) {
+            return null;
+        }
+        return { ...toBaseline(row), computedOnRead: true };
+    }
+    return {
+        resetCache() {
+            cache.clear();
+        },
+        async getBaseline(userId, metric, windowDays, ctx) {
+            const k = key(userId, metric, windowDays, ctx.brand, ctx.familyId);
+            if (cache.has(k))
+                return cache.get(k) ?? null;
+            let result = null;
+            try {
+                result = await readStored(userId, metric, windowDays, ctx);
+                if (result === null) {
+                    result = await computeOnRead(userId, metric, windowDays, ctx);
+                    if (result !== null) {
+                        logger?.debug('rules.baseline: stored row absent, computed on read', {
+                            userId, metric, windowDays,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                // A missing baseline is a normal state (new user). A failed read is
+                // not, but it must not take down the evaluation pass — the rule
+                // simply doesn't fire this cycle.
+                logger?.warn('rules.baseline: read failed', {
+                    userId,
+                    metric,
+                    windowDays,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+                result = null;
+            }
+            cache.set(k, result);
+            return result;
+        },
+    };
+}
+function toBaseline(row) {
+    return {
+        p05: row.p05,
+        p10: row.p10,
+        p50: row.p50,
+        p90: row.p90,
+        p95: row.p95,
+        mean: row.mean,
+        stddev: row.stddev,
+        sampleCount: row.sample_count,
+    };
+}
+//# sourceMappingURL=baseline-reader.js.map

package/dist/rules/baseline-reader.js.map

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

package/dist/rules/compiler.d.ts

@@ -17,11 +17,46 @@
  *   observed_value NUMERIC, threshold_value NUMERIC
  * so the evaluator can build `RuleViolation` without dispatching per
  * target type.
+ *
+ * ## v0.2.0 additions (Sprint 5 §4)
+ *
+ * - **`context`** (T-17) — an INNER JOIN, not a post-filter. "SpO₂ during
+ *   sleep" must aggregate over sleep samples only; computing over
+ *   everything and labelling the result would report a number nobody asked
+ *   for.
+ * - **`consecutive: n`** (T-18) — run-length detection via gaps-and-islands.
+ *   `n <= 1` stays on the aggregate path, because "any single breach" is
+ *   already expressible as `aggregation: 'min'` + `less_than`.
+ * - **`target.type: 'user_setting'`** (T-19) — emits a `$userSettingValue`
+ *   placeholder the evaluator binds from KVStore at eval time. The compiled
+ *   SQL is threshold-agnostic and therefore cacheable across users.
+ * - **Views** (T-20) — all generated SQL reads `v_{table}`, never
+ *   `local.{table}` or `r2.default.{table}` (principle 19).
  */
 import type { CompiledRule } from './types';
-import { type Rule } from './schema';
+import { type Rule, type RuleContext } from './schema';
 /** Sanitize an identifier for direct interpolation. */
 export declare function sanitizeIdent(raw: string): string;
+/**
+ * Union-view name for a table (T-20, principle 19). Reading the view is
+ * what makes a rule see rows flushed locally but not yet pushed to R2 —
+ * i.e. this morning's sync, which is exactly the data a rule fires on.
+ */
+export declare function viewFor(table: string): string;
+/**
+ * T-17 — INNER JOIN restricting samples to a physiological context.
+ *
+ * Aliased `m` for the metric relation throughout. Both joins carry the
+ * full tenant triple, not just `user_id`: a join on user alone would match
+ * another brand's sleep sessions for the same person on a multi-brand
+ * install.
+ */
+export declare function emitContextJoin(context: RuleContext): string;
+/**
+ * Placeholder the evaluator binds from KVStore for `user_setting` targets
+ * (T-19/T-23). Exported so the evaluator and its tests agree on the name.
+ */
+export declare const USER_SETTING_PARAM = "userSettingValue";
 /** Compile a validated rule to a `CompiledRule`. */
 export declare function compileRule(rule: Rule): CompiledRule;
 //# sourceMappingURL=compiler.d.ts.map

package/dist/rules/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/rules/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAGL,KAAK,IAAI,EAIV,MAAM,UAAU,CAAA;AAEjB,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AA4DD,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CA0CpD"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/rules/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAGL,KAAK,IAAI,EACT,KAAK,WAAW,EAIjB,MAAM,UAAU,CAAA;AAEjB,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AA6CD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAsB5D;AAiBD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,qBAAqB,CAAA;AAEpD,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CA8CpD"}