@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/chunk-VISRDVTK.js

@@ -0,0 +1,675 @@
+// src/db-package/db/local-first-sqlite-adapter.ts
+var LocalFirstSqliteAdapter = class {
+  /** Optional create-time tenant_id fallback captured from options; not a read or mutation authorization filter. */
+  tenantId;
+  sqlite;
+  upstream;
+  onSyncError;
+  autoSyncOnMutation;
+  essentialTables;
+  syncTimer = null;
+  isSyncing = false;
+  cleanupListeners;
+  /**
+   * Captures drivers and starts optional outbox polling and browser lifecycle listeners.
+   * @param options - Host drivers and synchronization settings; see {@link LocalFirstSqliteAdapterOptions}.
+   * @remarks The constructor performs no schema initialization. Timers/listeners start immediately unless disabled; call destroy when the instance is no longer needed.
+   */
+  constructor(options) {
+    this.tenantId = options.tenantId;
+    this.sqlite = options.sqlite;
+    this.upstream = options.upstream;
+    this.onSyncError = options.onSyncError;
+    this.autoSyncOnMutation = options.autoSyncOnMutation !== false;
+    this.essentialTables = new Set(options.essentialTables ?? []);
+    if (options.syncIntervalMs !== 0) {
+      const interval = options.syncIntervalMs || 5e3;
+      if (typeof setInterval !== "undefined") {
+        this.syncTimer = setInterval(() => this.processOutbox(), interval);
+      }
+    }
+    if (options.enableLifecycleSync !== false && typeof window !== "undefined") {
+      this.attachLifecycleListeners();
+    }
+  }
+  /**
+   * Initializes SQLite synchronization metadata tables and attempts WAL, NORMAL, and 5000 ms busy-timeout pragmas.
+   * @returns No value; resolves after metadata table creation. Pragma failures are deliberately ignored.
+   * @throws Rejects metadata table creation failures; earlier tables may already exist.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     await adapter.initSchema();
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async initSchema() {
+    try {
+      await this.sqlite.execute(`PRAGMA journal_mode = WAL;`);
+      await this.sqlite.execute(`PRAGMA synchronous = NORMAL;`);
+      await this.sqlite.execute(`PRAGMA busy_timeout = 5000;`);
+    } catch {
+    }
+    await this.sqlite.execute(`
+      CREATE TABLE IF NOT EXISTS _sync_meta (
+        table_name TEXT PRIMARY KEY,
+        last_sync_scn INTEGER NOT NULL DEFAULT 0,
+        last_sync_at TEXT NOT NULL
+      );
+    `);
+    await this.sqlite.execute(`
+      CREATE TABLE IF NOT EXISTS _outbox_queue (
+        id TEXT PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        previous_state TEXT,
+        status TEXT NOT NULL DEFAULT 'pending',
+        error_message TEXT,
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL
+      );
+    `);
+    await this.sqlite.execute(`
+      CREATE TABLE IF NOT EXISTS _access_frequency (
+        table_name TEXT PRIMARY KEY,
+        read_count INTEGER NOT NULL DEFAULT 0,
+        write_count INTEGER NOT NULL DEFAULT 0,
+        last_accessed_at TEXT NOT NULL
+      );
+    `);
+  }
+  /**
+   * Attaches window focus & network online hooks to trigger synchronization at user activity moments.
+   */
+  attachLifecycleListeners() {
+    const handleFocusOrOnline = () => {
+      this.processOutbox().catch(() => {
+      });
+      this.syncActiveTables().catch(() => {
+      });
+    };
+    window.addEventListener("focus", handleFocusOrOnline);
+    window.addEventListener("online", handleFocusOrOnline);
+    this.cleanupListeners = () => {
+      window.removeEventListener("focus", handleFocusOrOnline);
+      window.removeEventListener("online", handleFocusOrOnline);
+    };
+  }
+  /**
+   * Increments a table read or write counter and records the current ISO timestamp.
+   * @param collection - Table name recorded as a metadata value.
+   * @param type - Counter to increment; read contributes weight 2 and write weight 5 in adaptive ranking.
+   * @returns No value; resolves after the counter upsert.
+   * @throws Rejects SQLite failures.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     await adapter.recordAccess("records", "read");
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async recordAccess(collection, type) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const readIncrement = type === "read" ? 1 : 0;
+    const writeIncrement = type === "write" ? 1 : 0;
+    await this.sqlite.execute(
+      `INSERT INTO _access_frequency (table_name, read_count, write_count, last_accessed_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(table_name) DO UPDATE SET
+         read_count = _access_frequency.read_count + excluded.read_count,
+         write_count = _access_frequency.write_count + excluded.write_count,
+         last_accessed_at = excluded.last_accessed_at`,
+      [collection, readIncrement, writeIncrement, now]
+    );
+  }
+  /**
+   * Pulls every essential table plus the highest weighted access-frequency tables sequentially.
+   * @param limit - Maximum frequency-ranked tables selected in addition to essential tables; defaults to 8 and is passed to SQLite without additional validation.
+   * @returns Names whose pullChanges calls completed, including tables with no new rows; failed tables are warned and omitted.
+   * @throws Rejects the initial frequency query failure; individual pull failures are caught.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.syncActiveTables(8);
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async syncActiveTables(limit = 8) {
+    const frequent = await this.sqlite.select(
+      `SELECT table_name FROM _access_frequency ORDER BY (read_count * 2 + write_count * 5) DESC LIMIT ?`,
+      [limit]
+    );
+    const targetTables = new Set(this.essentialTables);
+    frequent.forEach((row) => targetTables.add(row.table_name));
+    const synced = [];
+    for (const table of targetTables) {
+      try {
+        await this.pullChanges(table);
+        synced.push(table);
+      } catch (err) {
+        console.warn(`[LocalFirst] Failed to sync active table '${table}':`, err);
+      }
+    }
+    return synced;
+  }
+  /**
+   * Queries local SQLite rows and schedules a best-effort read-frequency update.
+   * @typeParam T - Expected local row shape; no runtime schema validation is performed.
+   * @param collection - Local table identifier, quoted by the adapter.
+   * @param filter - AND-combined equality/null or $eq/$gt/$gte/$lt/$lte column conditions; other operator objects are rejected.
+   * @param options - Supports sort, limit, and skip; limit/skip must be nonnegative safe integers. Projection and other options are ignored.
+   * @returns Local rows, or an empty array; remote freshness is not implied.
+   * @throws Rejects unsupported filters, invalid pagination, or SQLite query failures. Access-stat failures are ignored.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.find("records", { active: true }, { limit: 10 });
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async find(collection, filter, options) {
+    this.recordAccess(collection, "read").catch(() => {
+    });
+    const { sql, params } = this.buildSelectQuery(collection, filter, options);
+    return await this.sqlite.select(sql, params);
+  }
+  /**
+   * Counts local rows matching a filter without pagination.
+   * @param collection - Local table identifier, quoted by the adapter.
+   * @param filter - Same supported AND-combined conditions as find.
+   * @param options - Sort is retained; limit and skip are discarded. Other options are ignored.
+   * @returns Numeric count, or zero if the driver returns no count row.
+   * @throws Rejects unsupported filters or SQLite failures; access-stat failures are ignored.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.count("records");
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async count(collection, filter, options) {
+    this.recordAccess(collection, "read").catch(() => {
+    });
+    const { sql, params } = this.buildSelectQuery(collection, filter, { ...options, limit: void 0, skip: void 0 });
+    const rows = await this.sqlite.select(`SELECT COUNT(*) AS total FROM (${sql})`, params);
+    return Number(rows[0]?.total ?? 0);
+  }
+  /**
+   * Queries a local row by its id column.
+   * @typeParam T - Expected local row shape; no runtime validation is performed.
+   * @param collection - Local table identifier.
+   * @param id - ID value bound to an equality filter.
+   * @param options - find options with limit overridden to 1; skip, if supplied, still applies.
+   * @returns First matching row, or null.
+   * @throws Rejects invalid pagination or SQLite query failures.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.findOne("records", "record-1");
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async findOne(collection, id, options) {
+    const rows = await this.find(collection, { id: { $eq: id } }, { ...options, limit: 1 });
+    return rows.length > 0 ? rows[0] : null;
+  }
+  /**
+   * Inserts a local record before separately enqueueing its upstream INSERT.
+   * @typeParam T - Expected returned record shape; no runtime validation is performed.
+   * @param collection - Provisioned local table identifier.
+   * @param data - Column values; a truthy id is retained, otherwise an ID is generated. Missing tenant columns may receive the configured tenantId. Object values are JSON-encoded for local SQL.
+   * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+   * @returns The input record with its chosen ID and optional tenant default, before upstream acknowledgement.
+   * @throws Rejects local SQL, serialization, or enqueue failure; a local insert may already have committed. Background outbox errors are ignored by this call.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.create("records", { title: "Example" });
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async create(collection, data, _options) {
+    this.recordAccess(collection, "write").catch(() => {
+    });
+    const recordId = data.id || (typeof crypto !== "undefined" ? crypto.randomUUID() : `rec_${Date.now()}`);
+    const recordWithId = { ...data, id: recordId };
+    if (this.tenantId && !recordWithId.tenant_id && !recordWithId.tenantId) {
+      recordWithId.tenant_id = this.tenantId;
+    }
+    await this.insertLocal(collection, recordWithId);
+    await this.enqueueOutbox({
+      id: typeof crypto !== "undefined" ? crypto.randomUUID() : `out_${Date.now()}`,
+      tableName: collection,
+      recordId,
+      operation: "INSERT",
+      payload: recordWithId,
+      previousState: null,
+      status: "pending",
+      retryCount: 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (this.autoSyncOnMutation) {
+      this.processOutbox().catch(() => {
+      });
+    }
+    return recordWithId;
+  }
+  /**
+   * Snapshots a local row, updates its columns, and separately enqueues an upstream UPDATE.
+   * @typeParam T - Expected returned merged record shape.
+   * @param collection - Provisioned local table identifier.
+   * @param id - Record ID bound in local SQL and used for upstream update.
+   * @param data - Updated columns; local SQL excludes id but the payload is forwarded unchanged upstream. An empty update can cause a SQLite syntax failure.
+   * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+   * @returns Snapshot merged with data and the supplied id, even if no local row existed.
+   * @throws Rejects snapshot, local SQL, serialization, or enqueue failures; local changes may already have committed.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.update("records", "record-1", { title: "Changed" });
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async update(collection, id, data, _options) {
+    this.recordAccess(collection, "write").catch(() => {
+    });
+    const existing = await this.findOne(collection, id);
+    await this.updateLocal(collection, id, data);
+    const updatedRecord = { ...existing || {}, ...data, id };
+    await this.enqueueOutbox({
+      id: typeof crypto !== "undefined" ? crypto.randomUUID() : `out_${Date.now()}`,
+      tableName: collection,
+      recordId: id,
+      operation: "UPDATE",
+      payload: data,
+      previousState: existing || null,
+      status: "pending",
+      retryCount: 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (this.autoSyncOnMutation) {
+      this.processOutbox().catch(() => {
+      });
+    }
+    return updatedRecord;
+  }
+  /**
+   * Deletes a local row and separately enqueues upstream deletion with a rollback snapshot.
+   * @typeParam T - Expected deleted record shape.
+   * @param collection - Provisioned local table identifier.
+   * @param id - Record ID used for local and upstream deletion.
+   * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+   * @returns The previous local record, or an object containing only id when absent.
+   * @throws Rejects snapshot, local delete, or enqueue failures; local deletion may already have committed.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.delete("records", "record-1");
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async delete(collection, id, _options) {
+    this.recordAccess(collection, "write").catch(() => {
+    });
+    const existing = await this.findOne(collection, id);
+    await this.sqlite.execute(`DELETE FROM ${this.escapeId(collection)} WHERE id = ?`, [id]);
+    await this.enqueueOutbox({
+      id: typeof crypto !== "undefined" ? crypto.randomUUID() : `out_${Date.now()}`,
+      tableName: collection,
+      recordId: id,
+      operation: "DELETE",
+      payload: { id },
+      previousState: existing || null,
+      status: "pending",
+      retryCount: 0,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (this.autoSyncOnMutation) {
+      this.processOutbox().catch(() => {
+      });
+    }
+    return existing || { id };
+  }
+  /**
+   * Pulls incremental remote changes from Oracle ADB using ORA_ROWSCN cursor within a batch transaction.
+   *
+   * @param collection - Provisioned local table whose upstream supports ORA_ROWSCN filtering, ordering, and projection.
+   * @returns Number of remote rows upserted, or zero when no changes were returned.
+   * @throws Rejects upstream or local SQL failures; an opened local transaction is rolled back best-effort on upsert/cursor failure.
+   * @remarks Remote deletes are not discovered by this pull. No per-table synchronization lock prevents overlapping pulls or concurrent host transactions.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     return await adapter.pullChanges("records");
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async pullChanges(collection) {
+    const meta = await this.sqlite.select(
+      `SELECT last_sync_scn FROM _sync_meta WHERE table_name = ?`,
+      [collection]
+    );
+    const lastScn = meta.length > 0 ? meta[0].last_sync_scn : 0;
+    const filter = lastScn > 0 ? { ORA_ROWSCN: { $gt: lastScn } } : {};
+    const remoteRecords = await this.upstream.find(collection, filter, {
+      sort: { ORA_ROWSCN: 1 },
+      projection: ["*", "ORA_ROWSCN"]
+    });
+    if (remoteRecords.length === 0) {
+      return 0;
+    }
+    let maxScn = lastScn;
+    await this.sqlite.execute(`BEGIN TRANSACTION;`);
+    try {
+      for (const record of remoteRecords) {
+        const recordScn = Number(record.ORA_ROWSCN) || 0;
+        if (recordScn > maxScn) {
+          maxScn = recordScn;
+        }
+        await this.upsertLocal(collection, record);
+      }
+      await this.sqlite.execute(
+        `INSERT INTO _sync_meta (table_name, last_sync_scn, last_sync_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(table_name) DO UPDATE SET
+           last_sync_scn = excluded.last_sync_scn,
+           last_sync_at = excluded.last_sync_at`,
+        [collection, maxScn, (/* @__PURE__ */ new Date()).toISOString()]
+      );
+      await this.sqlite.execute(`COMMIT;`);
+    } catch (txErr) {
+      await this.sqlite.execute(`ROLLBACK;`).catch(() => {
+      });
+      throw txErr;
+    }
+    return remoteRecords.length;
+  }
+  /**
+   * Background Outbox Worker:
+   * Processes at most 20 pending mutations in creation order, pushes upstream, and attempts rollback for non-network failures.
+   * @returns No value; resolves after one batch, or immediately if this instance already has a batch running.
+   * @throws Rejects metadata reads, malformed persisted JSON, or error-handling SQL failures. Ordinary upstream failures are recorded or rolled back rather than rejected.
+   * @remarks Recognized network failures return rows to pending and increment retry_count; no delay/backoff is applied here. Other failures attempt local snapshot rollback and mark failed; rollback/callback errors are logged. Remote success followed by local queue-delete failure may leave an uncertain delivery outcome. There is no cross-instance lease or deduplication.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     await adapter.processOutbox();
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  async processOutbox() {
+    if (this.isSyncing) return;
+    this.isSyncing = true;
+    try {
+      const pendingItems = await this.sqlite.select(
+        `SELECT * FROM _outbox_queue WHERE status = 'pending' ORDER BY created_at ASC LIMIT 20`
+      );
+      for (const rawItem of pendingItems) {
+        const item = {
+          id: rawItem.id,
+          tableName: rawItem.table_name || rawItem.tableName,
+          recordId: rawItem.record_id || rawItem.recordId,
+          operation: rawItem.operation,
+          payload: typeof rawItem.payload === "string" ? JSON.parse(rawItem.payload) : rawItem.payload,
+          previousState: rawItem.previous_state ? typeof rawItem.previous_state === "string" ? JSON.parse(rawItem.previous_state) : rawItem.previous_state : null,
+          status: rawItem.status,
+          retryCount: rawItem.retry_count ?? rawItem.retryCount ?? 0,
+          createdAt: rawItem.created_at || rawItem.createdAt
+        };
+        try {
+          await this.sqlite.execute(`UPDATE _outbox_queue SET status = 'syncing' WHERE id = ?`, [item.id]);
+          if (item.operation === "INSERT") {
+            await this.upstream.create(item.tableName, item.payload);
+          } else if (item.operation === "UPDATE") {
+            await this.upstream.update(item.tableName, item.recordId, item.payload);
+          } else if (item.operation === "DELETE") {
+            await this.upstream.delete(item.tableName, item.recordId);
+          }
+          await this.sqlite.execute(`DELETE FROM _outbox_queue WHERE id = ?`, [item.id]);
+        } catch (err) {
+          const isNetworkError = err.name === "AbortError" || err.code === "ECONNREFUSED" || err.message?.includes("fetch failed") || err.message?.includes("NetworkError");
+          if (isNetworkError) {
+            await this.sqlite.execute(
+              `UPDATE _outbox_queue SET status = 'pending', retry_count = retry_count + 1, error_message = ? WHERE id = ?`,
+              [err.message, item.id]
+            );
+          } else {
+            await this.rollbackItem(item, err);
+          }
+        }
+      }
+    } finally {
+      this.isSyncing = false;
+    }
+  }
+  /**
+   * Rolls back a failed mutation in local SQLite using its previousState snapshot.
+   */
+  async rollbackItem(item, error) {
+    console.error(`[LocalFirst] Rolling back ${item.tableName}:${item.recordId} due to error:`, error);
+    try {
+      if (item.operation === "INSERT") {
+        await this.sqlite.execute(`DELETE FROM ${this.escapeId(item.tableName)} WHERE id = ?`, [item.recordId]);
+      } else if (item.operation === "UPDATE" || item.operation === "DELETE") {
+        if (item.previousState) {
+          await this.upsertLocal(item.tableName, item.previousState);
+        }
+      }
+      await this.sqlite.execute(`UPDATE _outbox_queue SET status = 'failed', error_message = ? WHERE id = ?`, [
+        error.message,
+        item.id
+      ]);
+      if (this.onSyncError) {
+        this.onSyncError({
+          item,
+          error,
+          rolledBack: true
+        });
+      }
+    } catch (rbErr) {
+      console.error("[LocalFirst] Critical: Failed to rollback record:", rbErr);
+    }
+  }
+  async enqueueOutbox(item) {
+    await this.sqlite.execute(
+      `INSERT INTO _outbox_queue (id, table_name, record_id, operation, payload, previous_state, status, retry_count, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        item.id,
+        item.tableName,
+        item.recordId,
+        item.operation,
+        JSON.stringify(item.payload),
+        item.previousState ? JSON.stringify(item.previousState) : null,
+        item.status,
+        item.retryCount,
+        item.createdAt
+      ]
+    );
+  }
+  async insertLocal(table, record) {
+    const keys = Object.keys(record);
+    const placeholders = keys.map(() => "?").join(", ");
+    const values = keys.map((k) => typeof record[k] === "object" ? JSON.stringify(record[k]) : record[k]);
+    const escapedKeys = keys.map((k) => this.escapeId(k)).join(", ");
+    await this.sqlite.execute(
+      `INSERT INTO ${this.escapeId(table)} (${escapedKeys}) VALUES (${placeholders})`,
+      values
+    );
+  }
+  async updateLocal(table, id, data) {
+    const keys = Object.keys(data).filter((k) => k !== "id");
+    const setClause = keys.map((k) => `${this.escapeId(k)} = ?`).join(", ");
+    const values = keys.map((k) => typeof data[k] === "object" ? JSON.stringify(data[k]) : data[k]);
+    await this.sqlite.execute(
+      `UPDATE ${this.escapeId(table)} SET ${setClause} WHERE id = ?`,
+      [...values, id]
+    );
+  }
+  async upsertLocal(table, record) {
+    const keys = Object.keys(record);
+    const placeholders = keys.map(() => "?").join(", ");
+    const values = keys.map((k) => typeof record[k] === "object" ? JSON.stringify(record[k]) : record[k]);
+    const escapedKeys = keys.map((k) => this.escapeId(k)).join(", ");
+    const updateClauses = keys.filter((k) => k !== "id").map((k) => `${this.escapeId(k)} = excluded.${this.escapeId(k)}`).join(", ");
+    await this.sqlite.execute(
+      `INSERT INTO ${this.escapeId(table)} (${escapedKeys}) VALUES (${placeholders})
+       ON CONFLICT(id) DO UPDATE SET ${updateClauses}`,
+      values
+    );
+  }
+  buildSelectQuery(table, filter, options) {
+    let sql = `SELECT * FROM ${this.escapeId(table)}`;
+    const params = [];
+    const whereParts = [];
+    for (const value of [options?.limit, options?.skip]) if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) throw new Error("Invalid SQLite pagination");
+    if (filter) {
+      for (const [key, val] of Object.entries(filter)) {
+        if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+          const opObj = val;
+          if ("$eq" in opObj) {
+            whereParts.push(`${this.escapeId(key)} = ?`);
+            params.push(opObj.$eq);
+          } else if ("$gt" in opObj) {
+            whereParts.push(`${this.escapeId(key)} > ?`);
+            params.push(opObj.$gt);
+          } else if ("$gte" in opObj) {
+            whereParts.push(`${this.escapeId(key)} >= ?`);
+            params.push(opObj.$gte);
+          } else if ("$lt" in opObj) {
+            whereParts.push(`${this.escapeId(key)} < ?`);
+            params.push(opObj.$lt);
+          } else if ("$lte" in opObj) {
+            whereParts.push(`${this.escapeId(key)} <= ?`);
+            params.push(opObj.$lte);
+          } else {
+            throw new Error("Unsupported SQLite filter");
+          }
+        } else if (val === null) {
+          whereParts.push(`${this.escapeId(key)} IS NULL`);
+        } else {
+          whereParts.push(`${this.escapeId(key)} = ?`);
+          params.push(val);
+        }
+      }
+    }
+    if (whereParts.length > 0) {
+      sql += ` WHERE ${whereParts.join(" AND ")}`;
+    }
+    if (options?.sort) {
+      const orderParts = Object.entries(options.sort).map(
+        ([col, dir]) => `${this.escapeId(col)} ${dir === -1 ? "DESC" : "ASC"}`
+      );
+      sql += ` ORDER BY ${orderParts.join(", ")}`;
+    }
+    if (options?.limit !== void 0 || options?.skip !== void 0) {
+      sql += ` LIMIT ${options.limit ?? -1}`;
+      if (options?.skip) {
+        sql += ` OFFSET ${options.skip}`;
+      }
+    }
+    return { sql, params };
+  }
+  escapeId(id) {
+    return `"${id.replace(/"/g, '""')}"`;
+  }
+  /**
+   * Stops this instance's polling timer and removes its browser focus/online listeners.
+   * @returns No value; repeated calls are safe. In-flight synchronization continues and drivers remain open.
+   * @example
+   * ```typescript
+   * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+   * export async function example(options: LocalFirstSqliteAdapterOptions) {
+   *   // The host supplies an initialized domain schema and authorized upstream adapter.
+   *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+   *   try {
+   *     await adapter.initSchema();
+   *     adapter.destroy();
+   *   } finally { adapter.destroy(); }
+   * }
+   * ```
+   */
+  destroy() {
+    if (this.syncTimer) {
+      clearInterval(this.syncTimer);
+      this.syncTimer = null;
+    }
+    if (this.cleanupListeners) {
+      this.cleanupListeners();
+      this.cleanupListeners = void 0;
+    }
+  }
+};
+
+export {
+  LocalFirstSqliteAdapter
+};
+//# sourceMappingURL=chunk-VISRDVTK.js.map