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

package/dist/core/engine.js

@@ -0,0 +1,119 @@
+/**
+ * Thin wrapper around a native DuckDB instance.
+ *
+ * Owns lifecycle (`open`/`close`), maps native errors into the analytics
+ * error taxonomy, and normalises `execute`/`stream`/`createAppender` so the
+ * rest of the package doesn't touch `react-native-duckdb` directly.
+ *
+ * We depend on `react-native-duckdb` only structurally (via the
+ * `DuckDBInstance` interface below) so the package builds and tests without
+ * the native module installed. The public factory (T-10) supplies a real
+ * instance via a `DuckDBFactory`; test suites supply fakes.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _HybridDuckDB_instances, _HybridDuckDB_factory, _HybridDuckDB_instance, _HybridDuckDB_closed, _HybridDuckDB_ready;
+import { AnalyticsError } from './errors';
+/**
+ * Owns the DuckDB connection lifecycle.
+ *
+ * - `open()` is idempotent: repeated calls after a successful open are no-ops.
+ * - `close()` is idempotent and terminal — subsequent `execute`/`stream`/
+ *   `createAppender` throw `not_ready`.
+ * - `execute()` returns a full row set; `stream()` yields pages of rows
+ *   (recommended page size `HybridDuckDB.PAGE_SIZE`, applied by the native
+ *   driver; the wrapper just forwards).
+ * - Any native throw is wrapped in `AnalyticsError`.
+ */
+export class HybridDuckDB {
+    constructor(factory) {
+        _HybridDuckDB_instances.add(this);
+        _HybridDuckDB_factory.set(this, void 0);
+        _HybridDuckDB_instance.set(this, void 0);
+        _HybridDuckDB_closed.set(this, false);
+        __classPrivateFieldSet(this, _HybridDuckDB_factory, factory, "f");
+    }
+    /** Whether `open()` has completed successfully and `close()` has not been called. */
+    get isOpen() {
+        return __classPrivateFieldGet(this, _HybridDuckDB_instance, "f") !== undefined && !__classPrivateFieldGet(this, _HybridDuckDB_closed, "f");
+    }
+    async open() {
+        if (__classPrivateFieldGet(this, _HybridDuckDB_closed, "f")) {
+            throw new AnalyticsError('not_ready', 'HybridDuckDB has been closed');
+        }
+        if (__classPrivateFieldGet(this, _HybridDuckDB_instance, "f")) {
+            return;
+        }
+        try {
+            __classPrivateFieldSet(this, _HybridDuckDB_instance, await __classPrivateFieldGet(this, _HybridDuckDB_factory, "f").call(this), "f");
+        }
+        catch (cause) {
+            throw new AnalyticsError('engine_open_failed', 'Failed to open DuckDB instance', cause);
+        }
+    }
+    async execute(sql, params) {
+        const inst = __classPrivateFieldGet(this, _HybridDuckDB_instances, "m", _HybridDuckDB_ready).call(this);
+        try {
+            const rows = await inst.execute(sql, params);
+            return rows;
+        }
+        catch (cause) {
+            throw new AnalyticsError('query_failed', `execute failed: ${previewSql(sql)}`, cause);
+        }
+    }
+    async *stream(sql, params) {
+        const inst = __classPrivateFieldGet(this, _HybridDuckDB_instances, "m", _HybridDuckDB_ready).call(this);
+        try {
+            for await (const page of inst.stream(sql, params)) {
+                yield page;
+            }
+        }
+        catch (cause) {
+            throw new AnalyticsError('query_failed', `stream failed: ${previewSql(sql)}`, cause);
+        }
+    }
+    createAppender(table) {
+        const inst = __classPrivateFieldGet(this, _HybridDuckDB_instances, "m", _HybridDuckDB_ready).call(this);
+        try {
+            return inst.createAppender(table);
+        }
+        catch (cause) {
+            throw new AnalyticsError('query_failed', `createAppender failed for table ${table}`, cause);
+        }
+    }
+    async close() {
+        if (__classPrivateFieldGet(this, _HybridDuckDB_closed, "f")) {
+            return;
+        }
+        __classPrivateFieldSet(this, _HybridDuckDB_closed, true, "f");
+        const inst = __classPrivateFieldGet(this, _HybridDuckDB_instance, "f");
+        __classPrivateFieldSet(this, _HybridDuckDB_instance, undefined, "f");
+        if (inst) {
+            await inst.close();
+        }
+    }
+}
+_HybridDuckDB_factory = new WeakMap(), _HybridDuckDB_instance = new WeakMap(), _HybridDuckDB_closed = new WeakMap(), _HybridDuckDB_instances = new WeakSet(), _HybridDuckDB_ready = function _HybridDuckDB_ready() {
+    if (__classPrivateFieldGet(this, _HybridDuckDB_closed, "f")) {
+        throw new AnalyticsError('not_ready', 'HybridDuckDB is closed');
+    }
+    if (!__classPrivateFieldGet(this, _HybridDuckDB_instance, "f")) {
+        throw new AnalyticsError('not_ready', 'HybridDuckDB.open() has not been called');
+    }
+    return __classPrivateFieldGet(this, _HybridDuckDB_instance, "f");
+};
+/** Recommended page size for streamed queries (spec §Engine). */
+HybridDuckDB.PAGE_SIZE = 500;
+function previewSql(sql) {
+    return sql.length > 120 ? `${sql.slice(0, 120)}…` : sql;
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/engine.js.map

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

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' | 'token_vendor_failed' | 'migration_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' | '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,qBAAqB,GACrB,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,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;AAaH,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,yDAAyD,CAAC,CAAA;QAC5F,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}
+{"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,yDAAyD,CAAC,CAAA;QAC5F,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/core/extensions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DuckDB extension bootstrap.
+ *
+ * Analytics needs `httpfs` + `iceberg` + `parquet` loaded before any
+ * `ATTACH 'iceberg://…'` can succeed. This module is the single place we
+ * issue `INSTALL/LOAD`, so failures map cleanly to
+ * `AnalyticsError('extension_load_failed', <name>)`.
+ *
+ * Bootstrapping is idempotent — a `#booted: Set<string>` guards repeated
+ * calls, and DuckDB itself no-ops re-loads, so calling twice is safe.
+ */
+import type { HybridDuckDB } from './engine';
+/** Extensions required for R2 Iceberg attach, in load order. */
+export declare const REQUIRED_EXTENSIONS: readonly ["httpfs", "iceberg", "parquet"];
+export type RequiredExtension = (typeof REQUIRED_EXTENSIONS)[number];
+/**
+ * Issue `INSTALL <ext>; LOAD <ext>;` for each required extension in order.
+ *
+ * Idempotent per-engine: extensions already loaded on the same
+ * `HybridDuckDB` instance are skipped.
+ *
+ * @throws `AnalyticsError('extension_load_failed', <ext>)` if any extension
+ *   fails; the extension name appears in the message + cause is preserved.
+ */
+export declare function bootstrapExtensions(db: HybridDuckDB): Promise<void>;
+/**
+ * Test-only: introspect which extensions have been booted for a given engine.
+ *
+ * Exposed for coverage of the idempotency path in
+ * `__tests__/extensions.test.ts`; not re-exported from `core/index.ts`.
+ */
+export declare function getBootedExtensions(db: HybridDuckDB): ReadonlySet<string>;
+//# sourceMappingURL=extensions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,2CAA4C,CAAA;AAE5E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAQpE;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBzE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAEzE"}

package/dist/core/extensions.js

@@ -0,0 +1,58 @@
+/**
+ * DuckDB extension bootstrap.
+ *
+ * Analytics needs `httpfs` + `iceberg` + `parquet` loaded before any
+ * `ATTACH 'iceberg://…'` can succeed. This module is the single place we
+ * issue `INSTALL/LOAD`, so failures map cleanly to
+ * `AnalyticsError('extension_load_failed', <name>)`.
+ *
+ * Bootstrapping is idempotent — a `#booted: Set<string>` guards repeated
+ * 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'];
+/**
+ * Tracks which extensions this process has already booted. Keyed by
+ * `HybridDuckDB` instance to keep isolation across engines in tests.
+ */
+const bootedByDb = new WeakMap();
+/**
+ * Issue `INSTALL <ext>; LOAD <ext>;` for each required extension in order.
+ *
+ * Idempotent per-engine: extensions already loaded on the same
+ * `HybridDuckDB` instance are skipped.
+ *
+ * @throws `AnalyticsError('extension_load_failed', <ext>)` if any extension
+ *   fails; the extension name appears in the message + cause is preserved.
+ */
+export async function bootstrapExtensions(db) {
+    let booted = bootedByDb.get(db);
+    if (!booted) {
+        booted = new Set();
+        bootedByDb.set(db, booted);
+    }
+    for (const ext of REQUIRED_EXTENSIONS) {
+        if (booted.has(ext)) {
+            continue;
+        }
+        try {
+            await db.execute(`INSTALL ${ext};`);
+            await db.execute(`LOAD ${ext};`);
+        }
+        catch (cause) {
+            throw new AnalyticsError('extension_load_failed', `Failed to load DuckDB extension: ${ext}`, cause);
+        }
+        booted.add(ext);
+    }
+}
+/**
+ * Test-only: introspect which extensions have been booted for a given engine.
+ *
+ * Exposed for coverage of the idempotency path in
+ * `__tests__/extensions.test.ts`; not re-exported from `core/index.ts`.
+ */
+export function getBootedExtensions(db) {
+    return bootedByDb.get(db) ?? new Set();
+}
+//# sourceMappingURL=extensions.js.map

package/dist/core/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/core/extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAGzC,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAU,CAAA;AAI5E;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,OAAO,EAA6B,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAgB;IACxD,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,KAAK,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;QACtC,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

@@ -1,9 +1,26 @@
-import type { AnalyticsConfig, AnalyticsEngine } from './types';
 /**
- * Wires config into engine + warehouse + machine.
+ * Wires config + engine + machine into an `AnalyticsEngine`.
+ *
+ * Public entry:  `createAnalytics(config)` — used by apps. Uses the injected
+ * duckdb factory from `config.duckdb?.factory` (see below) or a lazy
+ * `react-native-duckdb` resolver.
  *
- * Stub in T-02. Full wiring lands in T-10 (Phase 4 — factory) once the
- * engine (T-03/04), warehouse (T-05/06/07/08), and machine (T-09) exist.
+ * The 2nd (optional) `internal` argument is an escape hatch for tests +
+ * embed contexts that need to substitute a `DuckDBFactory` without shipping
+ * `react-native-duckdb`. Not part of the spec surface; consumers should
+ * stick to the 1-arg form.
+ */
+import type { DuckDBFactory } from './engine';
+import type { AnalyticsConfig, AnalyticsEngine } from './types';
+/**
+ * Internal-only extra input for `createAnalytics`. Not exported from the
+ * package barrel; ships in the `factory.ts` module surface so the test suite
+ * and embedders can substitute a `DuckDBFactory` without shipping
+ * `react-native-duckdb`.
  */
-export declare function createAnalytics(_config: AnalyticsConfig): AnalyticsEngine;
+export interface CreateAnalyticsInternal {
+    /** Substitute the DuckDB factory (fakes in tests; native adapter in app). */
+    duckdbFactory?: DuckDBFactory;
+}
+export declare function createAnalytics(config: AnalyticsConfig, internal?: CreateAnalyticsInternal): AnalyticsEngine;
 //# sourceMappingURL=factory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/core/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE/D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAEzE"}
+{"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,EAIhB,MAAM,SAAS,CAAA;AA6BhB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAoCD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,QAAQ,GAAE,uBAA4B,GACrC,eAAe,CA2LjB"}

package/dist/core/factory.js

@@ -1,11 +1,236 @@
-import { NotImplementedError } from './errors';
 /**
- * Wires config into engine + warehouse + machine.
+ * Wires config + engine + machine into an `AnalyticsEngine`.
  *
- * Stub in T-02. Full wiring lands in T-10 (Phase 4 — factory) once the
- * engine (T-03/04), warehouse (T-05/06/07/08), and machine (T-09) exist.
+ * Public entry:  `createAnalytics(config)` — used by apps. Uses the injected
+ * duckdb factory from `config.duckdb?.factory` (see below) or a lazy
+ * `react-native-duckdb` resolver.
+ *
+ * The 2nd (optional) `internal` argument is an escape hatch for tests +
+ * embed contexts that need to substitute a `DuckDBFactory` without shipping
+ * `react-native-duckdb`. Not part of the spec surface; consumers should
+ * stick to the 1-arg form.
+ */
+import { createActor } from 'xstate';
+import { AnalyticsError, NotImplementedError } from './errors';
+import { HybridDuckDB } from './engine';
+import { bootstrapExtensions } from './extensions';
+import { resolveLogger } from './logger';
+import { analyticsMachine } from './machine';
+import { ensureMigrations } from './migrations';
+import { clearLastAttach, loadLastAttach, loadRetentionOverride, saveLastAttach, saveRetentionOverride, } from './persistence';
+import { resolveEffectiveRetention, runRetentionSweep } from './retention';
+import { attachWarehouse, detachWarehouse, warehouseSecretName, } from './warehouse';
+// -------------------- default DuckDB factory --------------------
+/**
+ * Lazy resolver for `react-native-duckdb`. Only fires on `open()` — importing
+ * `createAnalytics` on a Node/CI host without the native module must not
+ * throw. Failure is deferred to the machine's `openEngine` actor, which
+ * surfaces as `AnalyticsError('engine_open_failed')` per spec.
+ */
+function defaultDuckdbFactory() {
+    return async () => {
+        throw new NotImplementedError('defaultDuckdbFactory — supply internal.duckdbFactory or wait for react-native-duckdb adapter');
+        // T-10 acceptance: apps must supply a factory via the internal arg while
+        // the react-native-duckdb adapter lands (tracked separately). Returning
+        // an unreachable satisfies the `DuckDBInstance` return contract.
+        return undefined;
+    };
+}
+// -------------------- state promise helper --------------------
+/**
+ * Resolve when the actor next enters one of `targets` (excluding its
+ * *current* state at the time of subscription).
  */
-export function createAnalytics(_config) {
-    throw new NotImplementedError('createAnalytics');
+function waitForNextState(actor, targets) {
+    return new Promise((resolve) => {
+        let seenFirst = false;
+        const targetSet = new Set(targets);
+        const sub = actor.subscribe((snapshot) => {
+            if (!seenFirst) {
+                seenFirst = true;
+                return;
+            }
+            const value = typeof snapshot.value === 'string' ? snapshot.value : '';
+            if (targetSet.has(value)) {
+                sub.unsubscribe();
+                resolve(value);
+            }
+        });
+    });
+}
+function currentState(actor) {
+    const raw = actor.getSnapshot().value;
+    return typeof raw === 'string' ? raw : 'idle';
+}
+// -------------------- factory --------------------
+export function createAnalytics(config, internal = {}) {
+    const log = resolveLogger(config.logger);
+    const duckdbFactory = internal.duckdbFactory ?? defaultDuckdbFactory();
+    const db = new HybridDuckDB(duckdbFactory);
+    const machineActors = {
+        async openEngine() {
+            await db.open();
+            await bootstrapExtensions(db);
+        },
+        async attachEngine({ ctx }) {
+            const attach = await attachWarehouse(db, ctx, {
+                warehouseUriBuilder: config.warehouseUriBuilder,
+                tokenVendor: config.tokenVendor,
+                familyMembersProvider: config.familyMembersProvider,
+                catalogEndpoint: config.catalogEndpoint,
+            });
+            await ensureMigrations(db, config.storage, { brand: ctx.brand, tenantId: ctx.tenantId }, attach.warehouseSecret);
+            return {
+                warehouseSecret: attach.warehouseSecret,
+                tokenExpiresAt: attach.tokenExpiresAt.getTime(),
+            };
+        },
+        async detachEngine({ ctx }) {
+            await detachWarehouse(db, ctx.tenantId);
+        },
+        async refreshToken({ ctx }) {
+            const token = await config.tokenVendor.fetch({
+                brand: ctx.brand,
+                tenantScope: ctx.tenantScope,
+                tenantId: ctx.tenantId,
+            });
+            const secretName = warehouseSecretName(ctx.tenantId);
+            try {
+                await db.execute(`CREATE OR REPLACE SECRET ${secretName} (TYPE ICEBERG, TOKEN $token, ENDPOINT $endpoint);`, { token: token.token, endpoint: config.catalogEndpoint });
+            }
+            catch (cause) {
+                throw new AnalyticsError('token_vendor_failed', `refreshToken: CREATE OR REPLACE SECRET failed for ${secretName}`, cause);
+            }
+            return { tokenExpiresAt: token.expiresAt.getTime() };
+        },
+    };
+    const actor = createActor(analyticsMachine, { input: { deps: machineActors } });
+    const publicSubscribers = new Set();
+    let lastLoggedState;
+    const internalSub = actor.subscribe(() => {
+        const s = currentState(actor);
+        if (s !== lastLoggedState) {
+            lastLoggedState = s;
+            log.debug('analytics.state', { value: s });
+        }
+        for (const fn of publicSubscribers)
+            fn(s);
+    });
+    actor.start();
+    actor.send({ type: 'OPEN' });
+    /**
+     * Ctx of the last successful attach; cleared on detach. Used by
+     * `setRetention` (needs `brand/tenantId/userId` for the override key) and
+     * by the attach-time persistence + sweep hook.
+     */
+    let currentCtx;
+    /**
+     * Load user override (if any), resolve effective retention against the
+     * brand default from `AnalyticsConfig.retention`, run one sweep. Errors
+     * are re-thrown; callers may choose to swallow (attach-time sweep does).
+     */
+    async function sweep(ctx, catalog) {
+        const brandCfg = config.retention[ctx.brand];
+        const brandDefault = brandCfg?.days ?? 0;
+        const userOverride = (await loadRetentionOverride(config.storage, ctx)) ?? undefined;
+        const effectiveDays = resolveEffectiveRetention({ brandDefault, userOverride });
+        if (effectiveDays <= 0)
+            return;
+        await runRetentionSweep(db, catalog, { effectiveDays });
+    }
+    const engine = {
+        async attach(ctx) {
+            const pending = waitForNextState(actor, ['attached', 'error']);
+            actor.send({ type: 'ATTACH', ctx });
+            const final = await pending;
+            if (final === 'error') {
+                throw actor.getSnapshot().context.lastError ?? new AnalyticsError('attach_failed', 'attach failed');
+            }
+            currentCtx = ctx;
+            log.info('analytics.attached', {
+                brand: ctx.brand,
+                tenantId: ctx.tenantId,
+                tenantScope: ctx.tenantScope,
+            });
+            // Persistence + retention sweep are best-effort so a KV / DELETE
+            // failure never rejects a successful attach.
+            try {
+                await saveLastAttach(config.storage, ctx);
+            }
+            catch (cause) {
+                log.warn('analytics.persist.last_attach_failed', { cause });
+            }
+            const catalog = actor.getSnapshot().context.warehouseSecret;
+            if (catalog) {
+                try {
+                    await sweep(ctx, catalog);
+                }
+                catch (cause) {
+                    log.warn('analytics.retention.sweep_failed', { cause });
+                }
+            }
+        },
+        async detach() {
+            const ctxAtDetach = currentCtx;
+            const pending = waitForNextState(actor, ['ready', 'error']);
+            actor.send({ type: 'DETACH' });
+            const final = await pending;
+            if (final === 'error') {
+                throw actor.getSnapshot().context.lastError ?? new AnalyticsError('detach_failed', 'detach failed');
+            }
+            currentCtx = undefined;
+            if (ctxAtDetach) {
+                log.info('analytics.detached', {
+                    brand: ctxAtDetach.brand,
+                    tenantId: ctxAtDetach.tenantId,
+                });
+                try {
+                    await clearLastAttach(config.storage, ctxAtDetach.brand);
+                }
+                catch (cause) {
+                    log.warn('analytics.persist.clear_last_attach_failed', { cause });
+                }
+            }
+        },
+        execute: (sql, params) => db.execute(sql, params),
+        stream: (sql, params) => db.stream(sql, params),
+        createAppender: (table) => db.createAppender(table),
+        get state() {
+            return currentState(actor);
+        },
+        get lastError() {
+            return actor.getSnapshot().context.lastError ?? null;
+        },
+        get catalog() {
+            return actor.getSnapshot().context.warehouseSecret;
+        },
+        subscribe(listener) {
+            publicSubscribers.add(listener);
+            return () => publicSubscribers.delete(listener);
+        },
+        async setRetention(days) {
+            if (!currentCtx) {
+                throw new AnalyticsError('not_attached', 'setRetention requires an attached engine');
+            }
+            const catalog = actor.getSnapshot().context.warehouseSecret;
+            if (!catalog) {
+                throw new AnalyticsError('not_attached', 'setRetention: no warehouse catalog');
+            }
+            await saveRetentionOverride(config.storage, currentCtx, days);
+            await sweep(currentCtx, catalog);
+        },
+        async getLastAttach(brand) {
+            return loadLastAttach(config.storage, brand);
+        },
+        async close() {
+            log.info('analytics.closed');
+            actor.send({ type: 'CLOSE' });
+            internalSub.unsubscribe();
+            publicSubscribers.clear();
+            await db.close();
+            actor.stop();
+        },
+    };
+    return engine;
 }
 //# sourceMappingURL=factory.js.map

package/dist/core/factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/core/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,MAAM,IAAI,mBAAmB,CAAC,iBAAiB,CAAC,CAAA;AAClD,CAAC"}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/core/factory.ts"],"names":[],"mappings":"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"}

package/dist/core/hooks.d.ts

@@ -1,27 +1,46 @@
-import type { AnalyticsState, Insight } from './types';
 /**
- * React hooks over the analytics engine. Stubs in T-02; real wiring via
- * `useSyncExternalStore` on `engine.subscribe()` lands in Phase 5 (T-11/12/13).
+ * React hooks over the analytics engine.
  *
- * React is an optional peer, so these stubs deliberately do not import
- * React — they simply throw NotImplementedError. This keeps @mongrov/analytics
- * consumable from non-React runtimes (Node CLI, background workers) until
- * the hooks are actually implemented.
+ * All three hooks resolve the engine via `useAnalyticsEngine()` (context) and
+ * subscribe to state transitions with `useSyncExternalStore`. Query hooks
+ * (`useTimeseries`, `useInsight`) block until the engine is attached; a
+ * detach + re-attach (family switch) refires them via the state subscription.
  */
-export declare function useAnalytics(): {
+import type { AnalyticsState, Insight } from './types';
+export interface UseAnalyticsResult {
     state: AnalyticsState;
     isReady: boolean;
     isAttached: boolean;
     error: Error | null;
-};
-export declare function useTimeseries<T = unknown>(_key: string | undefined, _sql: string, _params?: Record<string, unknown>): {
+}
+/**
+ * Subscribe to the engine's state machine. Re-renders on every transition.
+ * `isReady` is true from `ready` onward (engine opened); `isAttached` is true
+ * only in the `attached` state.
+ */
+export declare function useAnalytics(): UseAnalyticsResult;
+export interface UseTimeseriesResult<T> {
     data: T[] | undefined;
     loading: boolean;
     error: Error | null;
     refetch: () => Promise<void>;
-};
-export declare function useInsight(_id: string): {
+}
+/**
+ * Runs `sql` (with `params`) against the engine whenever `key`, `sql`,
+ * `params`, or the engine's attached state changes. `key === undefined`
+ * disables the query (data stays `undefined`).
+ *
+ * `refetch()` re-runs the current query; stale results from prior effects are
+ * discarded via a per-effect abort flag so out-of-order responses never win.
+ */
+export declare function useTimeseries<T = unknown>(key: string | undefined, sql: string, params?: Record<string, unknown>): UseTimeseriesResult<T>;
+export interface UseInsightResult {
     insight: Insight | undefined;
     loading: boolean;
-};
+}
+/**
+ * Reads a single insight row by id. Returns `undefined` if the engine is not
+ * attached or the row does not exist.
+ */
+export declare function useInsight(id: string): UseInsightResult;
 //# sourceMappingURL=hooks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;;;;;GAQG;AAGH,wBAAgB,YAAY,IAAI;IAC9B,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB,CAEA;AAGD,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;IACD,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B,CAEA;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG;IACvC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;CACjB,CAEA"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAmB,cAAc,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAIvE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CASjD;AAID,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AA8BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,CAAC,CAAC,CAAC,CA8ExB;AAID,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,CAgBvD"}