@mongrov/analytics 0.5.0 → 0.7.0

package/README.md

@@ -6,16 +6,29 @@ Per-family (or per-tenant) warehouses attached as DuckDB catalogs. Zero-copy
 reads against R2 Iceberg tables. Headless core with optional React hooks and
 UI subpaths.
 
-Status: **0.3.0** — Phases 1 → 7 landed on the core engine plus the full
-`@mongrov/analytics/sync` subpath (mapper → buffer → flusher → watermark →
-pusher → fetcher → scheduler → factory + hooks). T-18 / T-28 integration
-suites green against the MinIO + Iceberg REST docker stack (10 cases + 3
-round trips). 0.3.0 additionally lands SCD-2 `device_config` support:
-`RingConfigTranslator`, `PendingClosesStore`, `R2Pusher.pushCloses`, and
-a rewritten sink that closes prior configs both locally and against the
-remote Iceberg zone. **Breaking**: `DeviceConfigRow` shape changed
-(`metric` → `data_type`, `start_hour`/`end_hour` → `start_time`/`end_time`,
-added `weeks`) — see the `ringConfigTranslator` section below.
+Status: **0.7.0** — Sprint 5 hardening. Core engine, `/sync`, `/rules`,
+`/tools` and `/tools/mcp` subpaths all landed; 727 tests green, plus the
+T-18 / T-28 integration suites against the MinIO + Iceberg REST docker
+stack.
+
+0.7.0 lands: `icu` extension, `v_{table}` union views (local-unpushed +
+remote), `user_baseline` with day-first quantiles, `batch:complete` batch
+lifecycle, rules `context` / `consecutive` / `user_setting` targets, the
+`getSpO2` tool, and copy guardrails on every formatter.
+
+**Breaking** — see [UPGRADING.md](./UPGRADING.md) for rewrites. Headlines:
+mapped sleep row shapes now match the DDL (they did not before, and sleep
+flushes were writing NULLs into NOT NULL columns); `AnalyticsEngine` gained
+`getFamilyMembers()` and `dismissInsight()`; rule and tool SQL now reads
+`v_{table}` views, so an attach is required; rules evaluate once per batch
+rather than per table.
+
+> Historical note (0.3.0): SCD-2 `device_config` support inverted the
+> ring-config mapping direction — `DeviceConfigRow` moved from `metric` to
+> `data_type`, with a consumer-supplied `RingConfigTranslator` producing the
+> firmware enum from our metric names. Sprint 5 §2 intended to reverse this
+> (`metric VARCHAR`), but the change is **blocked**: the spec's firmware
+> codes do not match the real JStyle codes. See UPGRADING §12.
 
 ## Features
 

package/UPGRADING.md

@@ -0,0 +1,370 @@
+# Upgrading
+
+## 0.6.0 → 0.7.0 (Sprint 5 coordinated release)
+
+This is a **coordinated release**. Upgrade all four together — the packages
+share contracts that changed in lockstep:
+
+| Package | From | To |
+|---|---|---|
+| `@mongrov/analytics` | 0.6.0 | **0.7.0** |
+| `@mongrov/data-access` | 0.1.0 | **0.2.0** |
+| `@mongrov/types` | 0.4.0 | **0.5.0** |
+| `@mongrov/device` | 0.1.1 | **0.2.0** |
+
+> The Sprint 5 spec named these 0.2.0 / 0.2.0 / 0.4.0 / 0.2.0. Those targets
+> were unreachable: analytics had already shipped 0.2.0→0.6.0 across five
+> post-Sprint-4 releases, and types had reached 0.4.0 without ever landing
+> the Sprint 3 §18 content. Versions are next-minor-from-actual.
+
+---
+
+## 1. Breaking: mapped sleep row shapes
+
+**Who is affected:** anyone who consumes `MappedBatch` directly, supplies
+`columnOrder` for sleep tables, or has snapshot tests over mapper output.
+
+The sleep mapper had drifted from the DDL it writes to and was emitting rows
+the `sleep_session` table could not accept. If you were flushing sleep data,
+it was failing (or writing NULLs into NOT NULL columns) — this release fixes
+that, and the row types changed as a result.
+
+```diff
+ interface SleepSessionRow {
+   session_id: string
+-  ts: Date              // no such column; DDL partitions on day(ts_start)
+-  start_ts: Date
+-  end_ts: Date
++  ts_start: Date
++  ts_end: Date
++  total_minutes: number        // NOT NULL — was never produced
++  deep_minutes: number | null
++  rem_minutes: number | null
++  light_minutes: number | null
++  awake_minutes: number | null
++  avg_confidence: number | null
+   night_of: Date
+ }
+
+ interface SleepStageRow {
+-  stage: string         // firmware block_type leaked into an INTEGER column
++  stage: number         // 1=awake, 2=light, 3=deep, 5=rem
+-  confidence: number
++  confidence: number | null
+ }
+
+ interface SleepRawRow {
+-  payload: FirmwareSleepRow    // no such column
++  ts_session_start: Date
++  quality: number              // NOT NULL; derived from confidence when
++  unit_length: number | null   // firmware omits it
+ }
+```
+
+Two smaller removals in the same pass — both were keys with no column:
+
+```diff
+-interface ActivityBucketRow { steps: number; … }   // steps live on `activity`
+-interface DeviceConfigRow   { ts: Date; … }        // axis is valid_from/valid_to
+```
+
+**Migrating `columnOrder`:** if you hand-wrote sleep entries, regenerate them
+from the DDL. Column names now match exactly, so
+`columnOrder[table].map(c => row[c])` works without translation.
+
+**Behaviour changes worth knowing:**
+
+- Session boundaries come from the firmware's own `start`/`end` fields, not
+  min/max of block instants. Deriving from blocks under-reported any session
+  whose first or last minutes went unclassified.
+- `primary` blocks produce **no** `sleep_stage` row. The DDL enum has no code
+  for them and they read as the session envelope rather than a stage. All
+  blocks are still preserved in `sleep_raw`. *Open question with the firmware
+  team — see `analytics-sync/tasks.md` T-06.*
+
+A new contract test (`mapper/__tests__/ddl-contract.test.ts`) parses
+`core/schemas.ts` and asserts every mapped row's keys are real columns and
+every NOT NULL column is populated. If you extend the mapper, it will tell
+you when you drift.
+
+---
+
+## 2. Breaking: `AnalyticsEngine` gained two methods
+
+**Who is affected:** anyone implementing `AnalyticsEngine` — test fakes,
+custom adapters.
+
+```diff
+ interface AnalyticsEngine {
+   …
++  getFamilyMembers(): Promise<string[]>
++  dismissInsight(args: { insightId: string; userId: string }): Promise<void>
+ }
+```
+
+`getFamilyMembers()` closes a principle-39 gap: the rules evaluator and the
+AI-tools authorize hook each held their own wire to family membership. Now
+both go through the engine, which delegates to the `familyMembersProvider`
+you configured at `createAnalytics` and caches for 60s.
+
+Minimal fake:
+
+```ts
+const engine: AnalyticsEngine = {
+  …,
+  async getFamilyMembers() { return ['alice', 'bob'] },
+  async dismissInsight() {},
+}
+```
+
+---
+
+## 3. Breaking: authorize hooks no longer fall back to SQL
+
+`familyScopeAuthorize` / `orgScopeAuthorize` previously fell back to
+`SELECT 1 FROM family_member …` when no provider was passed. **No DDL in this
+package ever created that table**, so the fallback could only throw and fail
+closed — silently denying every cross-member query on any install that did
+not pass a provider explicitly.
+
+```diff
+-familyScopeAuthorize(analytics)                       // used a phantom table
++familyScopeAuthorize(analytics)                       // uses engine roster
+ familyScopeAuthorize(analytics, { familyMembersProvider })  // still wins
+```
+
+If you relied on the SQL path, wire `familyMembersProvider` at
+`createAnalytics` instead. Membership lives in the RxDB Family doc, not
+DuckDB.
+
+---
+
+## 4. Breaking: generated SQL reads `v_{table}` views
+
+Rule SQL and tool SQL now target the union views instead of raw catalogs.
+This is what lets a rule fire on data flushed locally but not yet pushed to
+R2 — i.e. this morning's sync.
+
+**Consequence:** the views must exist. They are created on `attach()` and
+dropped on `detach()`, so anything executing rule or tool SQL against a
+non-attached engine now fails where it previously read stale remote rows.
+
+View bodies inline `brand` and `family_id`, because DuckDB views cannot bind
+parameters. That makes per-attach recreation a **correctness** requirement,
+not housekeeping — a brand switch reusing old views would serve the previous
+tenant's rows. Handled automatically; do not cache view DDL yourself.
+
+`insight` is deliberately *not* viewed — it is local-authoritative.
+
+---
+
+## 5. Behaviour change: rules evaluate on `batch:complete`
+
+Rules previously evaluated once per table, on each `{table}:insert`. They now
+evaluate once per batch. **Default is the new behaviour.**
+
+This fixes a real race: a `context: 'asleep'` rule JOINs `v_sleep_session`,
+and firing it the moment `spo2` flushed let it evaluate against a night whose
+sleep rows were still buffered.
+
+```ts
+createSyncManager({
+  …,
+  strictBatchOrdering: false,  // opt out — restores per-table triggering
+})
+```
+
+Only opt out if you need lower evaluation latency **and** ship no
+context-JOIN or `consecutive` rules.
+
+Per-table `{table}:insert` events still fire — they drive cache
+invalidation, which wants to refresh as early as possible. `batch:complete`
+is additional, not a replacement.
+
+---
+
+## 6. New config: `userTimezoneProvider`
+
+Day-first baselines bucket by **local** day, so they need each user's IANA
+zone. `User.timezone` lives in auth/RxDB where this package cannot reach it.
+
+```ts
+createSyncManager({
+  …,
+  userTimezoneProvider: async (userId) => (await getUser(userId))?.timezone,
+})
+```
+
+Unwired, it falls back to the device zone — wrong for a travelling user or
+one whose profile zone differs from their device. Baselines still compute;
+they just bucket by the wrong midnight.
+
+---
+
+## 7. Rules schema additions
+
+Additive — existing rules keep parsing. New fields:
+
+```toml
+context = "asleep"      # 'any' (default) | 'asleep' | 'resting'
+consecutive = 3         # require N adjacent breaching samples
+
+[rule.target]
+type = "user_setting"   # threshold read from KVStore at eval time
+key = "user:spo2SafeLevel"
+defaultValue = 90
+```
+
+`user_setting` is what makes a user-configurable threshold work without
+per-user rule rows: the compiled SQL is threshold-agnostic, and the evaluator
+binds `analytics:{userId}:{key}` at eval time, falling back to `defaultValue`.
+
+Two constraints the validator now enforces:
+
+- `consecutive` is **rejected with baseline targets**. Baselines resolve
+  per-window, not per-sample; there is no correct query shape, so it throws
+  rather than emitting something subtly wrong.
+- `consecutive × sampling_minutes` must fit the window, or the rule could
+  never fire.
+
+**Ziva catalog rule ids changed.** Throttle state is keyed by rule id, so
+existing throttle counters for the renamed rules are orphaned (they expire
+naturally):
+
+| Was | Now |
+|---|---|
+| `ziva.sleep-deprivation-3d` | `ziva.sleep-deprivation-3` |
+| `ziva.stress-elevated` | `ziva.stress-elevated-day` |
+| `ziva.activity-low-24h` | `ziva.low-activity-week` |
+
+`ziva.hrv-drop-30` and `ziva.stress-elevated-day` also switched from
+`absolute` to `baseline_percent` / `baseline_stddev` targets — a fixed HRV
+threshold is meaningless across users.
+
+Also note `registry.register()` is **async**. An un-awaited call silently
+no-ops:
+
+```diff
+-rules.register(zivaDefaults)
++await rules.register(zivaDefaults)
+```
+
+---
+
+## 8. Copy guardrails — contract for tool authors
+
+Every tool formatter must call `assertNoBanTerms(text, formatterName)` on its
+return path. Tool output lands in an LLM's context, and the model repeats
+whatever register it finds there.
+
+```ts
+import { assertNoBanTerms } from '@mongrov/analytics/tools'
+
+function finalize(text: string, rowCount: number): ToolResult {
+  assertNoBanTerms(text, 'myTool')
+  return { text, rowCount, bytes: formatBytes(text) }
+}
+```
+
+It throws `FormatterCopyError` on any banned medical term. Matching is
+leading-boundary, so `desaturation` also catches `desaturations` — over-
+blocking is the right bias here. `applyPreferredLanguage(text)` rewrites the
+common phrasings, but it is a convenience, not a substitute: the guard still
+runs afterwards.
+
+This applies to text you did not author. An insight row titled *"Nocturnal
+desaturation detected"* interpolated into `getInsights` output fails the tool
+call — which is the point.
+
+---
+
+## 9. `@mongrov/data-access` 0.2.0
+
+`RequestContext` shape:
+
+```diff
+ interface RequestContext {
+-  requesterUserId: string
++  userId: string       // canonical — queries bind it as $userId
+   brand: string
+   familyId: string
++  timezone: string     // bound as $tz by every day-grouped query
+   now: () => Date
+ }
+```
+
+Both are required. Update your `DataAccessProvider` context factory.
+
+The remaining 0.2.0 items (`asyncFetch`, `fetching` hook state,
+JOIN-invalidation validator, `transform` field, `MutationContext.analytics`)
+were already implemented before this release; 0.2.0 records the version.
+
+---
+
+## 10. `@mongrov/types` 0.5.0
+
+Additive. Lands the Sprint 3 §18 layer every Sprint 4 feature was written
+against but which never shipped: `Brand`, `Family`, `User`,
+`AnalyticsDevice`, `SensorSink`, `FirmwareExport`, `MapperContext`,
+`EventBus`, and the seven missing `AnalyticsQuerySchemas`.
+
+**`AnalyticsDevice`, not `Device`.** `types/device.ts` already exports a
+`Device` describing the BLE transport's view (adapterId, connection state,
+RSSI). Both are legitimate and neither is a superset — one is the durable
+tenancy record sensor rows key against, the other is the live connection
+handle. The existing `Device` is unchanged.
+
+`DEVICE_EVENT_TYPES` and its payload schemas now live here canonically
+(`@mongrov/types/device-events`); `@mongrov/analytics` re-exports them. This
+is what lets `@mongrov/device` emit events the analytics engine will store
+without depending on the engine.
+
+**Packaging change: dual CJS/ESM emit.** `dist/` is now `dist/esm` +
+`dist/cjs`, each with its own `type` marker, and every export declares
+`import` / `require` / `types` conditions. Previously the package emitted
+ESM only and declared no `require` condition — which nothing noticed,
+because every cross-package import was type-only and therefore erased at
+compile. The first *value* import from a subpath (`device-events`,
+`analytics-queries`) failed to resolve under CommonJS.
+
+If you deep-imported `@mongrov/types/dist/...` — don't; use the subpath
+exports. `main` / `module` / `types` now point into the split trees.
+
+---
+
+## 11. Migrations
+
+One new migration runs automatically on attach:
+
+| Version | What |
+|---|---|
+| v4 | `user_baseline` table (local catalog only) |
+
+**Numbering note.** The Sprint 5 spec called this "migration v3" and
+specified a "v4" adding `insight.dismissed_at`. Versions 2 and 3 were already
+spent (`device_battery`, `insight` v2 rebuild), and `dismissed_at` already
+ships in the baseline DDL with migration v3 backfilling it — so the ALTER
+would have been a no-op against an existing column.
+
+`user_baseline` and `sync_watermark` are **local-only** — never created in
+the attached R2 zone. Baselines are derived data, cheap to recompute, and
+pushing them would invite two devices in one family to race on the same
+composite PK.
+
+---
+
+## 12. Known gaps in this release
+
+Documented so you do not go looking:
+
+- **`device_config` still uses `data_type SMALLINT`.** Sprint 5 §2's change
+  to `metric VARCHAR` is blocked: the spec's firmware codes (1/2/4) do not
+  match the real JStyle codes (`HR:0, SLEEP:1, SPO2:3, HRV:8, ACTIVITY:9,
+  TEMPERATURE:14`), and SpO₂/temperature are separate schedules — so the
+  "fan-out `data_type=2` into two rows" the task describes may not correspond
+  to real hardware behaviour. Unresolved with the firmware team.
+- **`@mongrov/device` sync events are emitter-only.** `createSyncEventEmitter`
+  and the `DeviceEventSink` port ship and are usable stand-alone, but the sync
+  machine that would call them is D5 work and does not exist yet.
+- **`transform` is declared but not resolved** by the data-access dispatcher.
+  Queries declaring it will not produce derived output fields yet.

package/dist/core/device-events.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `device_event.event_type` enum + per-type payload schemas (Sprint 5 §6).
+ *
+ * **Re-export only.** The canonical definition lives in
+ * `@mongrov/types/device-events` so that `@mongrov/device` — which must
+ * never depend on the analytics engine — can emit events this engine will
+ * store, against the same contract.
+ *
+ * Kept as a module here so analytics consumers get one import surface, and
+ * so the `core/index.ts` export list stays stable.
+ */
+export { decodeDeviceEventPayload, DEVICE_EVENT_PAYLOAD_SCHEMAS, DEVICE_EVENT_TYPES, encodeDeviceEventPayload, isDeviceEventType, SyncTrigger, } from '@mongrov/types/device-events';
+export type { DeviceEventPayload, DeviceEventType, SyncTriggerValue, } from '@mongrov/types/device-events';
+//# sourceMappingURL=device-events.d.ts.map

package/dist/core/device-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-events.d.ts","sourceRoot":"","sources":["../../src/core/device-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,GACZ,MAAM,8BAA8B,CAAA;AAErC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAA"}

package/dist/core/device-events.js

@@ -0,0 +1,13 @@
+/**
+ * `device_event.event_type` enum + per-type payload schemas (Sprint 5 §6).
+ *
+ * **Re-export only.** The canonical definition lives in
+ * `@mongrov/types/device-events` so that `@mongrov/device` — which must
+ * never depend on the analytics engine — can emit events this engine will
+ * store, against the same contract.
+ *
+ * Kept as a module here so analytics consumers get one import surface, and
+ * so the `core/index.ts` export list stays stable.
+ */
+export { decodeDeviceEventPayload, DEVICE_EVENT_PAYLOAD_SCHEMAS, DEVICE_EVENT_TYPES, encodeDeviceEventPayload, isDeviceEventType, SyncTrigger, } from '@mongrov/types/device-events';
+//# sourceMappingURL=device-events.js.map

package/dist/core/device-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-events.js","sourceRoot":"","sources":["../../src/core/device-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,GACZ,MAAM,8BAA8B,CAAA"}

package/dist/core/errors.d.ts

@@ -5,7 +5,7 @@
  * ships the class and code union so stubs can throw typed errors from
  * day one; downstream phases add more codes without breaking imports.
  */
-export type AnalyticsErrorCode = 'engine_open_failed' | 'extension_load_failed' | 'attach_failed' | 'detach_failed' | 'token_vendor_failed' | 'migration_failed' | 'retention_failed' | 'query_failed' | 'not_attached' | 'not_ready' | 'not_implemented';
+export type AnalyticsErrorCode = 'engine_open_failed' | 'extension_load_failed' | 'attach_failed' | 'detach_failed' | 'token_vendor_failed' | 'migration_failed' | 'retention_failed' | 'family_members_failed' | 'query_failed' | 'not_attached' | 'not_ready' | 'not_implemented';
 export declare class AnalyticsError extends Error {
     readonly code: AnalyticsErrorCode;
     readonly cause?: unknown;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,uBAAuB,GACvB,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,WAAW,GACX,iBAAiB,CAAA;AAErB,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAA;IACxC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEnB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMvE;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,MAAM,EAAE,MAAM;CAI3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,uBAAuB,GACvB,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,uBAAuB,GACvB,cAAc,GACd,cAAc,GACd,WAAW,GACX,iBAAiB,CAAA;AAErB,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAA;IACxC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEnB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMvE;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,MAAM,EAAE,MAAM;CAI3B"}

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAIvC,YAAY,IAAwB,EAAE,OAAe,EAAE,KAAe;QACpE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD,YAAY,MAAc;QACxB,KAAK,CAAC,iBAAiB,EAAE,GAAG,MAAM,qBAAqB,CAAC,CAAA;QACxD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAIvC,YAAY,IAAwB,EAAE,OAAe,EAAE,KAAe;QACpE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD,YAAY,MAAc;QACxB,KAAK,CAAC,iBAAiB,EAAE,GAAG,MAAM,qBAAqB,CAAC,CAAA;QACxD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/core/extensions.d.ts

@@ -18,10 +18,27 @@
  */
 import type { HybridDuckDB } from './engine';
 import type { AnalyticsMode } from './types';
-/** Extensions required for R2 Iceberg attach, in load order. */
-export declare const REQUIRED_EXTENSIONS: readonly ["httpfs", "iceberg", "parquet"];
-/** Extensions required for local-only mode (no remote sync, no iceberg). */
-export declare const LOCAL_EXTENSIONS: readonly ["parquet"];
+/**
+ * Extensions required for R2 Iceberg attach, in load order.
+ *
+ * `icu` sits between `httpfs` and `iceberg` per Sprint 5 T-01. It is not
+ * optional: every registry query and every baseline computation groups by
+ * local day via `timezone($tz, ts)` / `date_trunc('day', timezone(...))`,
+ * and DuckDB's `timezone()` with a named IANA zone resolves only when
+ * `icu` is loaded. Without it those queries fail at parse time rather than
+ * silently returning UTC-grouped rows.
+ */
+export declare const REQUIRED_EXTENSIONS: readonly ["httpfs", "icu", "iceberg", "parquet"];
+/**
+ * Extensions required for local-only mode (no remote sync, no iceberg).
+ *
+ * `icu` is here too, and deliberately so: local mode skips `httpfs` +
+ * `iceberg` to avoid the AWSSDK/vcpkg build burden, but it does NOT skip
+ * timezone-aware queries — a local-only install still renders day charts
+ * and computes day-first baselines. Omitting `icu` here would make those
+ * paths work on R2 installs and fail on local ones.
+ */
+export declare const LOCAL_EXTENSIONS: readonly ["icu", "parquet"];
 export type RequiredExtension = (typeof REQUIRED_EXTENSIONS)[number];
 /**
  * Issue `INSTALL <ext>; LOAD <ext>;` for each mode-appropriate extension

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

@@ -1 +1 @@
-{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,2CAA4C,CAAA;AAE5E,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,sBAAuB,CAAA;AAEpD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAQpE;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,YAAY,EAChB,IAAI,GAAE,aAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAEzE"}
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,kDAAmD,CAAA;AAEnF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,6BAA8B,CAAA;AAE3D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAQpE;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,YAAY,EAChB,IAAI,GAAE,aAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAEzE"}

package/dist/core/extensions.js

@@ -17,10 +17,27 @@
  * calls, and DuckDB itself no-ops re-loads, so calling twice is safe.
  */
 import { AnalyticsError } from './errors';
-/** Extensions required for R2 Iceberg attach, in load order. */
-export const REQUIRED_EXTENSIONS = ['httpfs', 'iceberg', 'parquet'];
-/** Extensions required for local-only mode (no remote sync, no iceberg). */
-export const LOCAL_EXTENSIONS = ['parquet'];
+/**
+ * Extensions required for R2 Iceberg attach, in load order.
+ *
+ * `icu` sits between `httpfs` and `iceberg` per Sprint 5 T-01. It is not
+ * optional: every registry query and every baseline computation groups by
+ * local day via `timezone($tz, ts)` / `date_trunc('day', timezone(...))`,
+ * and DuckDB's `timezone()` with a named IANA zone resolves only when
+ * `icu` is loaded. Without it those queries fail at parse time rather than
+ * silently returning UTC-grouped rows.
+ */
+export const REQUIRED_EXTENSIONS = ['httpfs', 'icu', 'iceberg', 'parquet'];
+/**
+ * Extensions required for local-only mode (no remote sync, no iceberg).
+ *
+ * `icu` is here too, and deliberately so: local mode skips `httpfs` +
+ * `iceberg` to avoid the AWSSDK/vcpkg build burden, but it does NOT skip
+ * timezone-aware queries — a local-only install still renders day charts
+ * and computes day-first baselines. Omitting `icu` here would make those
+ * paths work on R2 installs and fail on local ones.
+ */
+export const LOCAL_EXTENSIONS = ['icu', 'parquet'];
 /**
  * Tracks which extensions this process has already booted. Keyed by
  * `HybridDuckDB` instance to keep isolation across engines in tests.

package/dist/core/extensions.js.map

@@ -1 +1 @@
-{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAIzC,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAU,CAAA;AAE5E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,SAAS,CAAU,CAAA;AAIpD;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,OAAO,EAA6B,CAAA;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,EAAgB,EAChB,OAAsB,IAAI;IAE1B,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAA;QAClB,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;IAC5B,CAAC;IAED,MAAM,UAAU,GACZ,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CAAA;IAE7D,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,SAAQ;QACV,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC,CAAA;YACnC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,uBAAuB,EACvB,oCAAoC,GAAG,EAAE,EACzC,KAAK,CACN,CAAA;QACH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAgB;IAClD,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG,EAAE,CAAA;AACxC,CAAC"}
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAIzC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAU,CAAA;AAEnF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,CAAU,CAAA;AAI3D;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,OAAO,EAA6B,CAAA;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,EAAgB,EAChB,OAAsB,IAAI;IAE1B,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAA;QAClB,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;IAC5B,CAAC;IAED,MAAM,UAAU,GACZ,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CAAA;IAE7D,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,SAAQ;QACV,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC,CAAA;YACnC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,uBAAuB,EACvB,oCAAoC,GAAG,EAAE,EACzC,KAAK,CACN,CAAA;QACH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAgB;IAClD,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG,EAAE,CAAA;AACxC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/core/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,UAAU,CAAA;AAe7D,OAAO,KAAK,EAEV,eAAe,EACf,eAAe,EAKhB,MAAM,SAAS,CAAA;AAgChB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAwED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,QAAQ,GAAE,uBAA4B,GACrC,eAAe,CA8QjB"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/core/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,UAAU,CAAA;AAgB7D,OAAO,KAAK,EAEV,eAAe,EACf,eAAe,EAKhB,MAAM,SAAS,CAAA;AAkChB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAwED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,QAAQ,GAAE,uBAA4B,GACrC,eAAe,CAoYjB"}