@mongrov/analytics 0.6.0 → 0.8.0

package/dist/core/sampling.js

@@ -0,0 +1,107 @@
+/**
+ * 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 { METRIC_METADATA, } from './metric_metadata';
+/** Default memo lifetime. Ring schedules change on the order of never. */
+export const SAMPLING_CACHE_TTL_MS = 10 * 60 * 1000;
+/** The fallback, with no I/O. */
+export function fallbackSampling(metric) {
+    return {
+        minutes: METRIC_METADATA[metric].sampling_minutes,
+        source: 'metric_metadata',
+    };
+}
+export function createSamplingResolver(config) {
+    const ttlMs = config.ttlMs ?? SAMPLING_CACHE_TTL_MS;
+    const now = config.now ?? (() => Date.now());
+    const cache = new Map();
+    const keyOf = (deviceId, metric) => `${deviceId} ${metric}`;
+    return {
+        async resolve(metric, deviceId) {
+            // Register-time validation has no device. Returning the fallback here
+            // is deliberately permissive: a denser real device only ever makes a
+            // rule MORE satisfiable, never less, so validating against the
+            // nominal cadence cannot produce a false pass.
+            if (!deviceId)
+                return fallbackSampling(metric);
+            const key = keyOf(deviceId, metric);
+            const hit = cache.get(key);
+            if (hit && hit.expiresAt > now())
+                return hit.value;
+            let value = fallbackSampling(metric);
+            try {
+                const rows = await config.analytics.execute(`SELECT interval_minutes FROM device_config
+            WHERE device_id = $deviceId AND metric = $metric
+              AND valid_to IS NULL
+            ORDER BY valid_from DESC LIMIT 1`, { deviceId, metric });
+                const interval = rows[0]?.interval_minutes;
+                if (typeof interval === 'number' && interval > 0) {
+                    value = { minutes: interval, source: 'device_config' };
+                }
+            }
+            catch (err) {
+                // A missing config row is normal (pre-first-sync). A failed read is
+                // not, but falling back beats failing a chart render or an
+                // evaluation pass over a cadence lookup.
+                config.logger?.warn('sampling: device_config read failed, using fallback', {
+                    metric,
+                    deviceId,
+                    err: err.message,
+                });
+            }
+            cache.set(key, { value, expiresAt: now() + ttlMs });
+            return value;
+        },
+        invalidate(deviceId) {
+            if (deviceId === undefined) {
+                cache.clear();
+                return;
+            }
+            const prefix = `${deviceId} `;
+            for (const key of cache.keys()) {
+                if (key.startsWith(prefix))
+                    cache.delete(key);
+            }
+        },
+    };
+}
+/**
+ * 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 function minimumWindowMinutes(sampling, consecutive) {
+    if (sampling === 'per_session')
+        return null;
+    return sampling * Math.max(1, consecutive);
+}
+//# sourceMappingURL=sampling.js.map

package/dist/core/sampling.js.map

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

package/dist/core/schemas.js

@@ -39,7 +39,26 @@ export const TABLE_NAMES = [
     'insight',
     'sync_watermark',
     'tool_call_audit',
+    'user_baseline',
 ];
+/**
+ * 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 const LOCAL_ONLY_TABLES = new Set([
+    'user_baseline',
+]);
 /**
  * Frozen DDL for every warehouse table. Copied verbatim from spec §Table
  * schema; rewrite happens in `ensureSchemas` at issue time.
@@ -151,32 +170,39 @@ export const SCHEMAS = Object.freeze({
   device_id VARCHAR NOT NULL,
   battery_pct DOUBLE NOT NULL
 ) PARTITIONED BY (day(ts), device_id);`,
+    // Sprint 5 §2 — `metric VARCHAR`, not the firmware's `data_type` integer.
+    // Principle 21: firmware enums never leak into the schema. The mapper
+    // translates `dataType` (1=heartRate, 2=spo2, 3=temperature, 4=HRV per
+    // the JStyle J2301A SDK) at the ingestion boundary.
     device_config: `CREATE TABLE device_config (
   device_id VARCHAR NOT NULL,
   brand VARCHAR NOT NULL,
   family_id VARCHAR NOT NULL,
   user_id VARCHAR NOT NULL,
-  data_type INTEGER NOT NULL,
+  metric VARCHAR NOT NULL,
   interval_minutes INTEGER NOT NULL,
   start_time VARCHAR,
   end_time VARCHAR,
   weeks INTEGER,
   valid_from TIMESTAMP NOT NULL,
   valid_to TIMESTAMP,
-  PRIMARY KEY (device_id, data_type, valid_from)
+  PRIMARY KEY (device_id, metric, valid_from)
 );`,
     insight: `CREATE TABLE insight (
-  id VARCHAR PRIMARY KEY,
+  insight_id VARCHAR PRIMARY KEY,
   ts TIMESTAMP NOT NULL,
   brand VARCHAR NOT NULL,
   family_id VARCHAR NOT NULL,
   user_id VARCHAR NOT NULL,
   rule_id VARCHAR,
+  metric VARCHAR NOT NULL,
+  kind VARCHAR NOT NULL,
   severity VARCHAR NOT NULL,
   title VARCHAR NOT NULL,
   body TEXT,
   evidence VARCHAR,
-  acknowledged_at TIMESTAMP
+  acknowledged_at TIMESTAMP,
+  dismissed_at TIMESTAMP
 ) PARTITIONED BY (day(ts));`,
     sync_watermark: `CREATE TABLE sync_watermark (
   brand VARCHAR NOT NULL,
@@ -200,7 +226,131 @@ export const SCHEMAS = Object.freeze({
   outcome VARCHAR NOT NULL,
   error_message VARCHAR
 ) PARTITIONED BY (day(ts));`,
+    // Sprint 5 §7 — shared baseline source of truth for rules, tools, and
+    // screens. Quantiles are computed DAY-FIRST (principle 27): readings
+    // collapse to one value per local day, then quantiles run across days.
+    // `sample_count` therefore counts DAYS, not readings — a row is only
+    // written at >= 20 days (BASELINE_MIN_DAYS).
+    //
+    // Not partitioned: the table holds at most
+    // (metrics x windows) = 21 rows per user, and the composite PK is the
+    // only access path any consumer uses.
+    user_baseline: `CREATE TABLE user_baseline (
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  metric VARCHAR NOT NULL,
+  window_days SMALLINT NOT NULL,
+  p05 DOUBLE,
+  p10 DOUBLE,
+  p50 DOUBLE,
+  p90 DOUBLE,
+  p95 DOUBLE,
+  mean DOUBLE,
+  stddev DOUBLE,
+  sample_count INTEGER,
+  computed_at TIMESTAMP NOT NULL,
+  PRIMARY KEY (brand, family_id, user_id, metric, window_days)
+);`,
 });
+/**
+ * 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 function insightIndexDdl(catalog) {
+    return `CREATE INDEX IF NOT EXISTS idx_insight_lookup ON ${catalog}.insight (user_id, metric, dismissed_at, ts);`;
+}
+/**
+ * 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 const VIEWED_TABLES = [
+    'hrv',
+    'heart_rate',
+    'spo2',
+    'temperature',
+    'activity',
+    'activity_bucket',
+    'sleep_session',
+    'sleep_stage',
+    'device_event',
+    'device_battery',
+];
+/** Timestamp column the watermark partitions on, per table. */
+export function watermarkColumnFor(table) {
+    return table === 'sleep_session' ? 'ts_start' : 'ts';
+}
+/**
+ * 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 function generateViewDdl(table, ctx) {
+    const tsCol = watermarkColumnFor(table);
+    const brand = sqlLiteral(ctx.brand);
+    const familyId = sqlLiteral(ctx.familyId);
+    const local = `${ctx.localCatalog}.${table}`;
+    const watermark = `COALESCE((SELECT cursor_ts FROM ${ctx.localCatalog}.sync_watermark `
+        + `WHERE table_name = '${table}' AND kind = 'push' `
+        + `AND brand = ${brand} AND family_id = ${familyId}), `
+        + `'1970-01-01'::TIMESTAMP)`;
+    if (!ctx.remoteCatalog) {
+        // Local mode: nothing is ever pushed, so every local row is visible and
+        // the watermark filter would be a no-op that only costs a scan.
+        return `CREATE OR REPLACE VIEW v_${table} AS SELECT * FROM ${local};`;
+    }
+    const remote = `${ctx.remoteCatalog}.${REMOTE_NAMESPACE_VIEW}.${table}`;
+    return (`CREATE OR REPLACE VIEW v_${table} AS\n`
+        + `  SELECT * FROM ${local}\n`
+        + `  WHERE ${tsCol} > ${watermark}\n`
+        + `  UNION ALL\n`
+        + `  SELECT * FROM ${remote};`);
+}
+/**
+ * Iceberg namespace remote tables live under. Duplicated from
+ * `migrations.ts` rather than imported to keep `schemas.ts` free of a
+ * migrations dependency (migrations already imports schemas).
+ */
+const REMOTE_NAMESPACE_VIEW = 'default';
+/**
+ * Single-quote a SQL string literal. View bodies cannot take bound
+ * parameters, so brand/familyId are inlined — escaping is mandatory, not
+ * optional, even though both values are server-issued.
+ */
+function sqlLiteral(value) {
+    return `'${value.replace(/'/g, `''`)}'`;
+}
+/** `DROP VIEW IF EXISTS v_{table}` for detach + brand switch. */
+export function dropViewDdl(table) {
+    return `DROP VIEW IF EXISTS v_${table};`;
+}
 /**
  * Rewrite one base DDL to `CREATE TABLE IF NOT EXISTS <catalog>.<table>`.
  *
@@ -240,8 +390,13 @@ export const LOCAL_SCHEMAS = Object.freeze(Object.fromEntries(TABLE_NAMES.map(ta
  * catalog (without). Default is `SCHEMAS` for back-compat with 0.4.x
  * callers that only wrote to the attached remote.
  */
-export async function ensureSchemas(db, catalog, schemas = SCHEMAS) {
+export async function ensureSchemas(db, catalog, schemas = SCHEMAS, opts = {}) {
     for (const table of TABLE_NAMES) {
+        // Remote passes `skipLocalOnly` so derived/bookkeeping tables never get
+        // created in the user's R2 zone.
+        if (opts.skipLocalOnly && LOCAL_ONLY_TABLES.has(table)) {
+            continue;
+        }
         const sql = qualifyDdl(schemas[table], table, catalog);
         try {
             await db.execute(sql);

package/dist/core/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAGzC,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,KAAK;IACL,YAAY;IACZ,MAAM;IACN,aAAa;IACb,UAAU;IACV,iBAAiB;IACjB,eAAe;IACf,aAAa;IACb,WAAW;IACX,cAAc;IACd,gBAAgB;IAChB,eAAe;IACf,SAAS;IACT,gBAAgB;IAChB,iBAAiB;CACT,CAAA;AAIV;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAwC,MAAM,CAAC,MAAM,CAAC;IACxE,GAAG,EAAE;;;;;;;;;;;qCAW8B;IAEnC,UAAU,EAAE;;;;;;;qCAOuB;IAEnC,IAAI,EAAE;;;;;;;qCAO6B;IAEnC,WAAW,EAAE;;;;;;;qCAOsB;IAEnC,QAAQ,EAAE;;;;;;;qCAOyB;IAEnC,eAAe,EAAE;;;;;;;;qCAQkB;IAEnC,aAAa,EAAE;;;;;;;;;;;;;;;2CAe0B;IAEzC,WAAW,EAAE;;;;;;;;;qCASsB;IAEnC,SAAS,EAAE;;;;;;;;;mDASsC;IAEjD,YAAY,EAAE;;;;;;;;4BAQY;IAE1B,cAAc,EAAE;;;;;;;uCAOqB;IAErC,aAAa,EAAE;;;;;;;;;;;;;GAad;IAED,OAAO,EAAE;;;;;;;;;;;;4BAYiB;IAE1B,cAAc,EAAE;;;;;;;;GAQf;IAED,eAAe,EAAE;;;;;;;;;;;;4BAYS;CAC3B,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,KAAgB,EAAE,OAAe;IAC3E,OAAO,OAAO,CAAC,OAAO,CACpB,gBAAgB,KAAK,EAAE,EACvB,8BAA8B,OAAO,IAAI,KAAK,EAAE,CACjD,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,qEAAqE;IACrE,sEAAsE;IACtE,6DAA6D;IAC7D,OAAO,OAAO,CAAC,OAAO,CAAC,6BAA6B,EAAE,IAAI,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAwC,MAAM,CAAC,MAAM,CAC7E,MAAM,CAAC,WAAW,CAChB,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACjC,CAC/B,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAgB,EAChB,OAAe,EACf,UAA+C,OAAO;IAEtD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;QACtD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACvB,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,kBAAkB,EAClB,iCAAiC,KAAK,EAAE,EACxC,KAAK,CACN,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"table_metadata.d.ts","sourceRoot":"","sources":["../../src/core/table_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAgBxE,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"table_metadata.d.ts","sourceRoot":"","sources":["../../src/core/table_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAmBxE,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAE7D"}

package/dist/core/table_metadata.js

@@ -30,6 +30,9 @@ export const TABLE_METADATA = Object.freeze({
     device_config: { timeColumn: 'valid_from', syncable: true },
     insight: { timeColumn: 'ts', syncable: true },
     sync_watermark: { timeColumn: 'updated_at', syncable: false },
+    // Derived, local-only, and UPSERTed in place — never pushed, and its
+    // `computed_at` is a recompute stamp rather than a sync cursor.
+    user_baseline: { timeColumn: 'computed_at', syncable: false },
     tool_call_audit: { timeColumn: 'ts', syncable: false },
 });
 /**

package/dist/core/table_metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"table_metadata.js","sourceRoot":"","sources":["../../src/core/table_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,CAAC,MAAM,cAAc,GAAmD,MAAM,CAAC,MAAM,CAAC;IAC1F,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACzC,UAAU,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAChD,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC1C,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjD,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC9C,eAAe,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACrD,aAAa,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE;IACzD,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjD,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC/C,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAClD,cAAc,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACpD,aAAa,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC3D,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC7C,cAAc,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE;IAC7D,eAAe,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE;CACvD,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,OAAQ,cAAoD,CAAC,KAAK,CAAC,EAAE,UAAU,IAAI,IAAI,CAAA;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,OAAQ,cAAoD,CAAC,KAAK,CAAC,EAAE,QAAQ,IAAI,KAAK,CAAA;AACxF,CAAC"}
+{"version":3,"file":"table_metadata.js","sourceRoot":"","sources":["../../src/core/table_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,CAAC,MAAM,cAAc,GAAmD,MAAM,CAAC,MAAM,CAAC;IAC1F,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACzC,UAAU,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAChD,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC1C,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjD,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC9C,eAAe,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACrD,aAAa,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE;IACzD,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjD,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC/C,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAClD,cAAc,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IACpD,aAAa,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC3D,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC7C,cAAc,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE;IAC7D,qEAAqE;IACrE,gEAAgE;IAChE,aAAa,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE;IAC7D,eAAe,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE;CACvD,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,OAAQ,cAAoD,CAAC,KAAK,CAAC,EAAE,UAAU,IAAI,IAAI,CAAA;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,OAAQ,cAAoD,CAAC,KAAK,CAAC,EAAE,QAAQ,IAAI,KAAK,CAAA;AACxF,CAAC"}

package/dist/core/types.d.ts

@@ -139,6 +139,31 @@ export interface AnalyticsEngine {
      */
     readonly mode: AnalyticsMode;
     subscribe(listener: (s: AnalyticsState) => void): Unsubscribe;
+    /**
+     * Family member userIds for the current attach context (principle 39 —
+     * "Rules engine and AI tools share the same source of truth").
+     *
+     * Delegates to the `familyMembersProvider` configured at
+     * `createAnalytics`, so rules + tools never reach for RxDB or auth state
+     * themselves. Result is cached in-engine for 60s and invalidated on
+     * `family:update` (analytics-core/spec.md §Family membership resolution).
+     *
+     * Returns `[]` when not attached, when `tenantScope === 'org'`, or in
+     * local mode (no family fanout) — callers treat empty as "no fanout",
+     * never as "denied".
+     */
+    getFamilyMembers(): Promise<string[]>;
+    /**
+     * Stamp `dismissed_at` on one insight (Sprint 5 §7b). Backs the app
+     * registry's `insight.dismiss` mutation — `@mongrov/data-access` types
+     * this exact shape on `MutationContext.analytics`.
+     *
+     * Authorized by ownership: `userId` must match the insight's owner.
+     */
+    dismissInsight(args: {
+        insightId: string;
+        userId: string;
+    }): Promise<void>;
     setRetention(days: number): Promise<void>;
     /**
      * Return the last successfully-attached ctx (persisted via KVStore) if it
@@ -148,22 +173,32 @@ export interface AnalyticsEngine {
     getLastAttach(brand: string): Promise<AttachContext | null>;
     close(): Promise<void>;
 }
+/** Insight categories per spec §Table schema (`insight.kind`). */
+export type InsightKind = 'threshold' | 'pattern' | 'baseline_shift' | 'factor';
+/** Insight severity per spec §Table schema (`insight.severity`). */
+export type InsightSeverity = 'info' | 'warn' | 'urgent';
 /**
- * Insight row shape as read from the `insight` DuckDB table.
- * The full schema is frozen in T-06 (schemas.ts); this stub matches the
- * columns needed by `useInsight()` in v0.1.0.
+ * Insight row shape as read from the `insight` DuckDB table — mirrors the
+ * DDL in schemas.ts (camelCase field names, snake_case columns).
  */
 export interface Insight {
-    id: string;
+    insightId: string;
+    /** fired_at semantic; adapters may surface TIMESTAMP as ISO string. */
+    ts: Date | string;
     brand: string;
     familyId: string;
     userId: string;
-    ruleId?: string;
-    severity: 'info' | 'warn' | 'critical';
-    observedAt: Date;
-    observedValue?: number;
-    thresholdValue?: number;
-    payload?: Record<string, unknown>;
+    /** Nullable — non-rule insights (patterns, factors) carry no rule_id. */
+    ruleId?: string | null;
+    metric: string;
+    kind: InsightKind;
+    severity: InsightSeverity;
+    title: string;
+    body?: string | null;
+    /** JSON payload (readings, thresholds, …) serialized as VARCHAR. */
+    evidence?: string | null;
+    acknowledgedAt?: Date | string | null;
+    dismissedAt?: Date | string | null;
 }
 export {};
 //# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/warehouse.d.ts

@@ -105,4 +105,32 @@ export declare function probeLocalCatalog(db: HybridDuckDB): Promise<string>;
  * the state machine's `detachEngine` actor can dispatch symmetrically.
  */
 export declare function detachLocal(_db: HybridDuckDB, _tenantId: string): Promise<void>;
+/**
+ * Create every `v_{table}` union view for the current attach.
+ *
+ * Called after migrations, so the underlying tables are guaranteed to
+ * exist — a view over a missing table fails at creation in DuckDB, not
+ * lazily at scan.
+ *
+ * The view bodies bake in `brand` + `family_id` (see `generateViewDdl` for
+ * why they cannot be bound parameters), which makes recreation on every
+ * attach a correctness requirement rather than housekeeping: a brand
+ * switch that reused the previous attach's views would serve the previous
+ * tenant's rows. `CREATE OR REPLACE` handles the overwrite; `dropViews` on
+ * detach closes the window where a stale view exists with no attach behind
+ * it.
+ */
+export declare function createViews(db: HybridDuckDB, ctx: {
+    brand: string;
+    familyId: string;
+    localCatalog: string;
+    remoteCatalog?: string;
+}): Promise<void>;
+/**
+ * Drop every union view. Idempotent (`DROP VIEW IF EXISTS`), and tolerant
+ * of individual failures: detach must not be blockable by a view that is
+ * already gone or whose catalog vanished first, or the engine would strand
+ * in `detaching`.
+ */
+export declare function dropViews(db: HybridDuckDB): Promise<void>;
 //# sourceMappingURL=warehouse.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"warehouse.d.ts","sourceRoot":"","sources":["../../src/core/warehouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,WAAW,EAEX,WAAW,EACZ,MAAM,SAAS,CAAA;AAchB,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,mBAAmB,EAAE,CACnB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAA;IACX,WAAW,EAAE,WAAW,CAAA;IACxB,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAA;IACvB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,cAAc,EAAE,IAAI,CAAA;IACpB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,YAAY,CAAC,CA0FvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAaf;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,YAAY,CAAC,CA8BvB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAczE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,YAAY,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"warehouse.d.ts","sourceRoot":"","sources":["../../src/core/warehouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,WAAW,EAEX,WAAW,EACZ,MAAM,SAAS,CAAA;AAchB,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,mBAAmB,EAAE,CACnB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAA;IACX,WAAW,EAAE,WAAW,CAAA;IACxB,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAA;IACvB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,cAAc,EAAE,IAAI,CAAA;IACpB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,YAAY,CAAC,CA0FvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAaf;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,YAAY,CAAC,CA8BvB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAczE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,YAAY,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE;IACH,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,GACA,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/D"}