@mongrov/analytics 0.1.0-alpha.1 → 0.1.0-alpha.7

package/dist/core/persistence.js

@@ -0,0 +1,80 @@
+/**
+ * KVStore-backed persistence for analytics state.
+ *
+ * Two concerns:
+ *
+ *   1. **Last-attach ctx** — persisted on every successful attach and cleared
+ *      on detach. `loadLastAttach` returns the ctx only if it was written
+ *      within `LAST_ATTACH_TTL_MS` (24h per spec §Testing) so apps can safely
+ *      auto-reattach after a crash / cold start without silently reviving a
+ *      stale multi-day-old context.
+ *
+ *   2. **Retention override** — `setRetention(days)` persists the user
+ *      override layer per spec §Retention precedence at
+ *      `analytics:retention:override:{brand}:{tenantId}:{userId}`. v0.1.0
+ *      resolves via `resolveEffectiveRetention` (retention.ts) but does not
+ *      surface UX to write it (`analytics.setRetention` is the escape hatch).
+ *
+ * All keys use the `analytics:` prefix so consumers can namespace-clear.
+ */
+// -------------------- keys --------------------
+/** 24h in ms — freshness bound for the persisted attach ctx. */
+export const LAST_ATTACH_TTL_MS = 24 * 60 * 60 * 1000;
+function lastAttachKey(brand) {
+    return `analytics:last-attach:${brand}`;
+}
+function retentionOverrideKey(brand, tenantId, userId) {
+    return `analytics:retention:override:${brand}:${tenantId}:${userId}`;
+}
+/**
+ * Persist the ctx that just successfully attached. Overwrites any prior
+ * entry for the same brand.
+ */
+export async function saveLastAttach(kv, ctx, now = Date.now()) {
+    const record = { ctx, attachedAt: now };
+    await kv.set(lastAttachKey(ctx.brand), record);
+}
+/**
+ * Load the last attach ctx for `brand` if it was written within the TTL.
+ * Returns `null` for missing entries or entries older than
+ * `LAST_ATTACH_TTL_MS`. Stale entries are also deleted as a side effect so
+ * repeated reads don't keep resurfacing them.
+ */
+export async function loadLastAttach(kv, brand, now = Date.now()) {
+    const record = await kv.get(lastAttachKey(brand));
+    if (!record)
+        return null;
+    if (now - record.attachedAt > LAST_ATTACH_TTL_MS) {
+        // Best-effort cleanup — swallow errors so a flaky KV can't wedge callers.
+        try {
+            await kv.delete(lastAttachKey(brand));
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    return record.ctx;
+}
+/**
+ * Clear the persisted attach ctx for `brand`. Invoked on `detach()` so a
+ * subsequent open doesn't auto-restore a context the app deliberately left.
+ */
+export async function clearLastAttach(kv, brand) {
+    await kv.delete(lastAttachKey(brand));
+}
+/**
+ * Persist the user-override retention for the current attach context.
+ * Overwrites any prior override for the same `(brand, tenantId, userId)`.
+ */
+export async function saveRetentionOverride(kv, ctx, days, now = Date.now()) {
+    const record = { days, updatedAt: now };
+    await kv.set(retentionOverrideKey(ctx.brand, ctx.tenantId, ctx.userId), record);
+}
+/**
+ * Load the user-override retention (days) for `(brand, tenantId, userId)`,
+ * or `null` when none is stored.
+ */
+export async function loadRetentionOverride(kv, ctx) {
+    const record = await kv.get(retentionOverrideKey(ctx.brand, ctx.tenantId, ctx.userId));
+    return record ? record.days : null;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/core/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/core/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,iDAAiD;AAEjD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAErD,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,yBAAyB,KAAK,EAAE,CAAA;AACzC,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,QAAgB,EAAE,MAAc;IAC3E,OAAO,gCAAgC,KAAK,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAA;AACtE,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAW,EACX,GAAkB,EAClB,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,MAAM,GAAqB,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAA;IACzD,MAAM,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAA;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAW,EACX,KAAa,EACb,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAmB,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;IACnE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACxB,IAAI,GAAG,GAAG,MAAM,CAAC,UAAU,GAAG,kBAAkB,EAAE,CAAC;QACjD,0EAA0E;QAC1E,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;QACvC,CAAC;QACD,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAA;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAW,EAAE,KAAa;IAC9D,MAAM,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;AACvC,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAW,EACX,GAAkB,EAClB,IAAY,EACZ,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,MAAM,GAA4B,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;IAChE,MAAM,EAAE,CAAC,GAAG,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAW,EACX,GAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CACzB,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAC1D,CAAA;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACpC,CAAC"}

package/dist/core/retention.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Retention scheduler for the analytics warehouse.
+ *
+ * Two responsibilities:
+ *
+ *   1. **Resolve** effective retention days for `(brand, tenantId, userId)`
+ *      via `resolveEffectiveRetention` — precedence per spec §Retention
+ *      is `max(userOverride, familySetting, brandDefault)` so *any* layer
+ *      that would preserve data wins.
+ *
+ *   2. **Sweep** the warehouse via `runRetentionSweep` — issues one DELETE
+ *      per retention-managed table, guarded by the per-table push watermark
+ *      from `sync_watermark` so rows still awaiting server sync are never
+ *      dropped (spec Fix 9).
+ *
+ * Internal tables have fixed defaults independent of brand/user config:
+ *   - `insight`          → 90 days
+ *   - `tool_call_audit`  → 30 days
+ *
+ * Tables without a retention semantic (`device_config`, `sync_watermark`)
+ * are skipped.
+ */
+import type { HybridDuckDB } from './engine';
+import type { TableName } from './schemas';
+export interface EffectiveRetentionInput {
+    /** Brand-level default (v0.1.0 active layer) — from `AnalyticsConfig.retention[brand].days`. */
+    brandDefault: number;
+    /** Family-level setting (v2 candidate — plumbed but unused by v0.1.0). */
+    familySetting?: number;
+    /** User override (v2 candidate — plumbed via `setRetention`, unused in v0.1.0 UX). */
+    userOverride?: number;
+}
+/**
+ * Resolve effective retention days per spec §Retention precedence — returns
+ * `max(userOverride ?? 0, familySetting ?? 0, brandDefault)`.
+ *
+ * Rationale: retention is *protective* — if any layer would preserve data
+ * longer, we honour that layer (max wins, not first-match).
+ */
+export declare function resolveEffectiveRetention(input: EffectiveRetentionInput): number;
+/** Fixed retention for the `insight` table — spec §Retention. */
+export declare const INSIGHT_RETENTION_DAYS = 90;
+/** Fixed retention for the `tool_call_audit` table — spec §Retention. */
+export declare const AUDIT_RETENTION_DAYS = 30;
+export interface RetentionSweepInput {
+    /** Effective retention days for sensor tables (see `resolveEffectiveRetention`). */
+    effectiveDays: number;
+}
+export interface RetentionSweepEntry {
+    table: TableName;
+    days: number;
+}
+export interface RetentionSweepResult {
+    swept: RetentionSweepEntry[];
+}
+/**
+ * Delete expired rows across every retention-managed table under `catalog`,
+ * bounded by each table's push watermark (`sync_watermark.cursor_ts`).
+ *
+ * SQL shape per table:
+ *
+ * ```sql
+ * DELETE FROM {catalog}.{table}
+ *  WHERE {tsCol} < LEAST(
+ *    now() - INTERVAL '{days} days',
+ *    (SELECT MAX(cursor_ts) FROM {catalog}.sync_watermark
+ *      WHERE table_name = '{table}')
+ *  );
+ * ```
+ *
+ * When no watermark exists, `MAX` returns NULL, `LEAST` becomes NULL and the
+ * comparison drops to false — safest default (no deletion on unsynced data).
+ *
+ * Failure at any table surfaces as `AnalyticsError('retention_failed', …)`;
+ * the caller decides whether to swallow-and-log or bubble.
+ */
+export declare function runRetentionSweep(db: HybridDuckDB, catalog: string, input: RetentionSweepInput): Promise<RetentionSweepResult>;
+interface DeleteSqlInput {
+    catalog: string;
+    table: TableName;
+    tsCol: string;
+    days: number;
+}
+/**
+ * Compose the retention DELETE for one table. Extracted so tests can snapshot
+ * the exact SQL issued without a live engine.
+ */
+export declare function buildDeleteSql(input: DeleteSqlInput): string;
+export {};
+//# sourceMappingURL=retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAI1C,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAMhF;AA4CD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAItC,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,EAAE,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;AAaD,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAS5D"}

package/dist/core/retention.js

@@ -0,0 +1,119 @@
+/**
+ * Retention scheduler for the analytics warehouse.
+ *
+ * Two responsibilities:
+ *
+ *   1. **Resolve** effective retention days for `(brand, tenantId, userId)`
+ *      via `resolveEffectiveRetention` — precedence per spec §Retention
+ *      is `max(userOverride, familySetting, brandDefault)` so *any* layer
+ *      that would preserve data wins.
+ *
+ *   2. **Sweep** the warehouse via `runRetentionSweep` — issues one DELETE
+ *      per retention-managed table, guarded by the per-table push watermark
+ *      from `sync_watermark` so rows still awaiting server sync are never
+ *      dropped (spec Fix 9).
+ *
+ * Internal tables have fixed defaults independent of brand/user config:
+ *   - `insight`          → 90 days
+ *   - `tool_call_audit`  → 30 days
+ *
+ * Tables without a retention semantic (`device_config`, `sync_watermark`)
+ * are skipped.
+ */
+import { AnalyticsError } from './errors';
+/**
+ * Resolve effective retention days per spec §Retention precedence — returns
+ * `max(userOverride ?? 0, familySetting ?? 0, brandDefault)`.
+ *
+ * Rationale: retention is *protective* — if any layer would preserve data
+ * longer, we honour that layer (max wins, not first-match).
+ */
+export function resolveEffectiveRetention(input) {
+    return Math.max(input.userOverride ?? 0, input.familySetting ?? 0, input.brandDefault);
+}
+const TABLE_RETENTION = Object.freeze({
+    hrv: { tsColumn: 'ts', kind: 'sensor' },
+    heart_rate: { tsColumn: 'ts', kind: 'sensor' },
+    spo2: { tsColumn: 'ts', kind: 'sensor' },
+    temperature: { tsColumn: 'ts', kind: 'sensor' },
+    activity: { tsColumn: 'ts', kind: 'sensor' },
+    activity_bucket: { tsColumn: 'ts', kind: 'sensor' },
+    // `sleep_session` retains by session close, not start — a session that ends
+    // outside the retention window has fully aged out.
+    sleep_session: { tsColumn: 'ts_end', kind: 'sensor' },
+    sleep_stage: { tsColumn: 'ts', kind: 'sensor' },
+    sleep_raw: { tsColumn: 'ts', kind: 'sensor' },
+    device_event: { tsColumn: 'ts', kind: 'sensor' },
+    device_config: null,
+    insight: { tsColumn: 'ts', kind: 'insight' },
+    sync_watermark: null,
+    tool_call_audit: { tsColumn: 'ts', kind: 'audit' },
+});
+// -------------------- constants --------------------
+/** Fixed retention for the `insight` table — spec §Retention. */
+export const INSIGHT_RETENTION_DAYS = 90;
+/** Fixed retention for the `tool_call_audit` table — spec §Retention. */
+export const AUDIT_RETENTION_DAYS = 30;
+/**
+ * Delete expired rows across every retention-managed table under `catalog`,
+ * bounded by each table's push watermark (`sync_watermark.cursor_ts`).
+ *
+ * SQL shape per table:
+ *
+ * ```sql
+ * DELETE FROM {catalog}.{table}
+ *  WHERE {tsCol} < LEAST(
+ *    now() - INTERVAL '{days} days',
+ *    (SELECT MAX(cursor_ts) FROM {catalog}.sync_watermark
+ *      WHERE table_name = '{table}')
+ *  );
+ * ```
+ *
+ * When no watermark exists, `MAX` returns NULL, `LEAST` becomes NULL and the
+ * comparison drops to false — safest default (no deletion on unsynced data).
+ *
+ * Failure at any table surfaces as `AnalyticsError('retention_failed', …)`;
+ * the caller decides whether to swallow-and-log or bubble.
+ */
+export async function runRetentionSweep(db, catalog, input) {
+    const swept = [];
+    const tableNames = Object.keys(TABLE_RETENTION);
+    for (const table of tableNames) {
+        const cfg = TABLE_RETENTION[table];
+        if (!cfg)
+            continue;
+        const days = daysForKind(cfg.kind, input.effectiveDays);
+        const sql = buildDeleteSql({ catalog, table, tsCol: cfg.tsColumn, days });
+        try {
+            await db.execute(sql);
+            swept.push({ table, days });
+        }
+        catch (cause) {
+            throw new AnalyticsError('retention_failed', `runRetentionSweep failed on table ${table}`, cause);
+        }
+    }
+    return { swept };
+}
+function daysForKind(kind, effective) {
+    switch (kind) {
+        case 'sensor':
+            return effective;
+        case 'insight':
+            return INSIGHT_RETENTION_DAYS;
+        case 'audit':
+            return AUDIT_RETENTION_DAYS;
+    }
+}
+/**
+ * Compose the retention DELETE for one table. Extracted so tests can snapshot
+ * the exact SQL issued without a live engine.
+ */
+export function buildDeleteSql(input) {
+    const { catalog, table, tsCol, days } = input;
+    return (`DELETE FROM ${catalog}.${table} `
+        + `WHERE ${tsCol} < LEAST(`
+        + `now() - INTERVAL '${days} days', `
+        + `(SELECT MAX(cursor_ts) FROM ${catalog}.sync_watermark WHERE table_name = '${table}')`
+        + `);`);
+}
+//# sourceMappingURL=retention.js.map

package/dist/core/retention.js.map

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

package/dist/core/schemas.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Table DDL for the analytics warehouse (spec §Table schema).
+ *
+ * Fourteen tables, verbatim from `.specifica/features/analytics-core/spec.md`.
+ * DDL strings are frozen — apps must not mutate them; migrations (T-08) own
+ * schema evolution.
+ *
+ * `ensureSchemas(db, catalog)` idempotently creates every table inside the
+ * attached catalog (i.e. `zone_<tenantId>`), rewriting `CREATE TABLE <name>`
+ * to `CREATE TABLE IF NOT EXISTS <catalog>.<name>` at issue time so the base
+ * DDL stays faithful to the spec text.
+ */
+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_config", "insight", "sync_watermark", "tool_call_audit"];
+export type TableName = (typeof TABLE_NAMES)[number];
+/**
+ * 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>>;
+/**
+ * Rewrite one base DDL to `CREATE TABLE IF NOT EXISTS <catalog>.<table>`.
+ *
+ * Exported for tests; call sites should prefer `ensureSchemas`.
+ */
+export declare function qualifyDdl(baseDdl: string, table: TableName, catalog: string): string;
+/**
+ * Create every warehouse table under `<catalog>.<table>`, in `TABLE_NAMES` order.
+ *
+ * Idempotent — every issued statement uses `IF NOT EXISTS`. Failure at any
+ * table surfaces as `AnalyticsError('migration_failed', <table>, cause)`.
+ */
+export declare function ensureSchemas(db: HybridDuckDB, catalog: string): Promise<void>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,qEAAqE;AACrE,eAAO,MAAM,WAAW,oNAed,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,CAiKtD,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAcpF"}

package/dist/core/schemas.js

@@ -0,0 +1,209 @@
+/**
+ * Table DDL for the analytics warehouse (spec §Table schema).
+ *
+ * Fourteen tables, verbatim from `.specifica/features/analytics-core/spec.md`.
+ * DDL strings are frozen — apps must not mutate them; migrations (T-08) own
+ * schema evolution.
+ *
+ * `ensureSchemas(db, catalog)` idempotently creates every table inside the
+ * attached catalog (i.e. `zone_<tenantId>`), rewriting `CREATE TABLE <name>`
+ * to `CREATE TABLE IF NOT EXISTS <catalog>.<name>` at issue time so the base
+ * DDL stays faithful to the spec text.
+ */
+import { AnalyticsError } from './errors';
+/** Ordered list of every warehouse table. Order = creation order. */
+export const TABLE_NAMES = [
+    'hrv',
+    'heart_rate',
+    'spo2',
+    'temperature',
+    'activity',
+    'activity_bucket',
+    'sleep_session',
+    'sleep_stage',
+    'sleep_raw',
+    'device_event',
+    'device_config',
+    'insight',
+    'sync_watermark',
+    'tool_call_audit',
+];
+/**
+ * Frozen DDL for every warehouse table. Copied verbatim from spec §Table
+ * schema; rewrite happens in `ensureSchemas` at issue time.
+ */
+export const SCHEMAS = Object.freeze({
+    hrv: `CREATE TABLE hrv (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  hrv_ms SMALLINT,
+  stress SMALLINT,
+  systolic_bp SMALLINT,
+  diastolic_bp SMALLINT,
+  vascular_aging SMALLINT
+) PARTITIONED BY (day(ts), user_id);`,
+    heart_rate: `CREATE TABLE heart_rate (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  bpm SMALLINT NOT NULL
+) PARTITIONED BY (day(ts), user_id);`,
+    spo2: `CREATE TABLE spo2 (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  spo2 SMALLINT NOT NULL
+) PARTITIONED BY (day(ts), user_id);`,
+    temperature: `CREATE TABLE temperature (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  temp_c SMALLINT NOT NULL
+) PARTITIONED BY (day(ts), user_id);`,
+    activity: `CREATE TABLE activity (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  steps INTEGER NOT NULL
+) PARTITIONED BY (day(ts), user_id);`,
+    activity_bucket: `CREATE TABLE activity_bucket (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  calories DOUBLE,
+  distance_km DOUBLE
+) PARTITIONED BY (day(ts), user_id);`,
+    sleep_session: `CREATE TABLE sleep_session (
+  session_id VARCHAR PRIMARY KEY,
+  ts_start TIMESTAMP NOT NULL,
+  ts_end TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  total_minutes INTEGER NOT NULL,
+  deep_minutes INTEGER,
+  rem_minutes INTEGER,
+  light_minutes INTEGER,
+  awake_minutes INTEGER,
+  avg_confidence DOUBLE,
+  night_of DATE
+) PARTITIONED BY (day(ts_start), user_id);`,
+    sleep_stage: `CREATE TABLE sleep_stage (
+  ts TIMESTAMP NOT NULL,
+  session_id VARCHAR NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  stage SMALLINT NOT NULL,
+  confidence DOUBLE
+) PARTITIONED BY (day(ts), user_id);`,
+    sleep_raw: `CREATE TABLE sleep_raw (
+  ts TIMESTAMP NOT NULL,
+  ts_session_start TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  quality SMALLINT NOT NULL,
+  unit_length SMALLINT
+) PARTITIONED BY (day(ts_session_start), user_id);`,
+    device_event: `CREATE TABLE device_event (
+  ts TIMESTAMP NOT NULL,
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  user_id VARCHAR NOT NULL,
+  device_id VARCHAR NOT NULL,
+  event_type VARCHAR NOT NULL,
+  payload JSON
+) PARTITIONED BY (day(ts));`,
+    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 SMALLINT NOT NULL,
+  interval_minutes SMALLINT NOT NULL,
+  start_time VARCHAR,
+  end_time VARCHAR,
+  weeks SMALLINT,
+  valid_from TIMESTAMP NOT NULL,
+  valid_to TIMESTAMP,
+  PRIMARY KEY (device_id, data_type, valid_from)
+);`,
+    insight: `CREATE TABLE 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,
+  severity VARCHAR NOT NULL,
+  title VARCHAR NOT NULL,
+  body TEXT,
+  evidence JSON,
+  acknowledged_at TIMESTAMP
+) PARTITIONED BY (day(ts));`,
+    sync_watermark: `CREATE TABLE sync_watermark (
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  table_name VARCHAR NOT NULL,
+  kind VARCHAR NOT NULL,
+  cursor_ts TIMESTAMP NOT NULL,
+  updated_at TIMESTAMP NOT NULL,
+  PRIMARY KEY (brand, family_id, table_name, kind)
+);`,
+    tool_call_audit: `CREATE TABLE tool_call_audit (
+  ts TIMESTAMP NOT NULL DEFAULT now(),
+  brand VARCHAR NOT NULL,
+  family_id VARCHAR NOT NULL,
+  requester_user_id VARCHAR NOT NULL,
+  tool_name VARCHAR NOT NULL,
+  args JSON NOT NULL,
+  result_bytes INTEGER,
+  result_row_count INTEGER,
+  latency_ms INTEGER,
+  outcome VARCHAR NOT NULL,
+  error_message VARCHAR
+) PARTITIONED BY (day(ts));`,
+});
+/**
+ * Rewrite one base DDL to `CREATE TABLE IF NOT EXISTS <catalog>.<table>`.
+ *
+ * Exported for tests; call sites should prefer `ensureSchemas`.
+ */
+export function qualifyDdl(baseDdl, table, catalog) {
+    return baseDdl.replace(`CREATE TABLE ${table}`, `CREATE TABLE IF NOT EXISTS ${catalog}.${table}`);
+}
+/**
+ * Create every warehouse table under `<catalog>.<table>`, in `TABLE_NAMES` order.
+ *
+ * Idempotent — every issued statement uses `IF NOT EXISTS`. Failure at any
+ * table surfaces as `AnalyticsError('migration_failed', <table>, cause)`.
+ */
+export async function ensureSchemas(db, catalog) {
+    for (const table of TABLE_NAMES) {
+        const sql = qualifyDdl(SCHEMAS[table], table, catalog);
+        try {
+            await db.execute(sql);
+        }
+        catch (cause) {
+            throw new AnalyticsError('migration_failed', `ensureSchemas failed at table ${table}`, cause);
+        }
+    }
+}
+//# sourceMappingURL=schemas.js.map

package/dist/core/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/core/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;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,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,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;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAgB,EAAE,OAAe;IACnE,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"}

package/dist/core/types.d.ts

@@ -97,8 +97,18 @@ export interface AnalyticsEngine {
     stream<T = unknown>(sql: string, params?: Record<string, unknown>): AsyncIterable<T[]>;
     createAppender(table: string): AnalyticsAppender;
     readonly state: AnalyticsState;
+    /** Last machine error surfaced; cleared on successful recovery. */
+    readonly lastError: Error | null;
+    /** Catalog / warehouse secret name for the current attach; undefined when not attached. */
+    readonly catalog: string | undefined;
     subscribe(listener: (s: AnalyticsState) => void): Unsubscribe;
     setRetention(days: number): Promise<void>;
+    /**
+     * Return the last successfully-attached ctx (persisted via KVStore) if it
+     * was written within the freshness window (24h). Apps may pass the result
+     * to `attach()` to auto-restore after a cold start.
+     */
+    getLastAttach(brand: string): Promise<AttachContext | null>;
     close(): Promise<void>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,mCAAmC;AACnC,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAA;AAEpC,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE1C,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,OAAO,GACP,WAAW,GACX,UAAU,GACV,WAAW,GACX,OAAO,CAAA;AAIX,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,WAAW,CAAA;QACxB,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAA;KAClC,CAAA;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CACrD;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAIvB,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC7D;AAID;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAA;IACvC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW,CAAA;IACtE,gBAAgB,CAAC,CAAC,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,GAC1C,WAAW,CAAA;CACf;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,mBAAmB,EAAE,CACnB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAA;IACX,eAAe,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;IACxB,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAID,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAClC,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;IACjF,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,CAAA;IACtF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,WAAW,CAAA;IAC7D,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAID;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;IACtC,UAAU,EAAE,IAAI,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,mCAAmC;AACnC,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAA;AAEpC,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE1C,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,OAAO,GACP,WAAW,GACX,UAAU,GACV,WAAW,GACX,OAAO,CAAA;AAIX,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,WAAW,CAAA;QACxB,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAA;KAClC,CAAA;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CACrD;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAIvB,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC7D;AAID;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAA;IACvC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW,CAAA;IACtE,gBAAgB,CAAC,CAAC,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,GAC1C,WAAW,CAAA;CACf;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,mBAAmB,EAAE,CACnB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,KACb,MAAM,CAAA;IACX,eAAe,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;IACxB,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAID,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAClC,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;IACjF,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,CAAA;IACtF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,CAAA;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,WAAW,CAAA;IAC7D,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAID;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;IACtC,UAAU,EAAE,IAAI,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC"}

package/dist/core/warehouse.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Warehouse attach / detach for a single tenant zone.
+ *
+ * Attaches R2 Iceberg data as a named DuckDB catalog, so downstream code can
+ * `SELECT ... FROM zone_<tenantId>.<table>`. The full sequence lives here so
+ * the state machine (T-09) can invoke it as a single actor step.
+ *
+ * Sequence per spec §Attach Protocol:
+ *   1. Build warehouse URI via `warehouseUriBuilder(brand, scope, tenantId)`.
+ *   2. Fetch bearer token via `tokenVendor.fetch({ brand, scope, tenantId })`.
+ *   3. `CREATE OR REPLACE SECRET` bound to the catalog endpoint + bearer token.
+ *   4. `ATTACH '<warehouseUri>' AS zone_<tenantId> (TYPE ICEBERG)`.
+ *   5. If `tenantScope === 'family'`, prime member ids via
+ *      `familyMembersProvider({ brand, familyId })` (for retention math).
+ *
+ * All failures map to `AnalyticsError('attach_failed' | 'token_vendor_failed',
+ * <phase>, cause)`.
+ */
+import type { HybridDuckDB } from './engine';
+import type { AttachContext, FamilyMembersProvider, TenantScope, TokenVendor } from './types';
+/** Dependencies required to attach a warehouse — a subset of `AnalyticsConfig`. */
+export interface AttachDeps {
+    warehouseUriBuilder: (brand: string, tenantScope: TenantScope, tenantId: string) => string;
+    tokenVendor: TokenVendor;
+    familyMembersProvider: FamilyMembersProvider;
+    catalogEndpoint: string;
+}
+/** Result of a successful attach — surfaced to the machine + config store. */
+export interface AttachResult {
+    /** DuckDB secret + catalog alias, e.g. `zone_fam123`. */
+    warehouseSecret: string;
+    /** S3/Iceberg URI the warehouse points at. */
+    warehouseUri: string;
+    /** When the bearer token expires (drives 75% TTL refresh in T-09). */
+    tokenExpiresAt: Date;
+    /** Populated only when `tenantScope === 'family'`. */
+    familyMemberIds?: string[];
+}
+/**
+ * Derive the DuckDB catalog alias for a tenant. Also used as the SECRET name.
+ *
+ * Sanitised to `[A-Za-z0-9_]` so it's always a valid DuckDB identifier.
+ */
+export declare function warehouseSecretName(tenantId: string): string;
+/**
+ * Attach a warehouse for a single tenant zone.
+ *
+ * Steps are surfaced explicitly in the error message so callers (machine,
+ * logger) can see which phase failed.
+ */
+export declare function attachWarehouse(db: HybridDuckDB, ctx: AttachContext, deps: AttachDeps): Promise<AttachResult>;
+/**
+ * Reverse of `attachWarehouse`: `DETACH` the catalog then drop its secret.
+ * Idempotent from the caller's perspective — a `DETACH` of an unknown alias
+ * throws in DuckDB, but the machine only calls this from `attached`.
+ */
+export declare function detachWarehouse(db: HybridDuckDB, tenantId: string): Promise<void>;
+//# sourceMappingURL=warehouse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"warehouse.d.ts","sourceRoot":"","sources":["../../src/core/warehouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;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,CAsFvB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAaf"}