local-lite 0.0.22 → 0.0.25

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 local-lite contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 local-lite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -63,9 +63,10 @@ remain configurable; the existing default conflict strategy is last-write-wins.
   `inMemoryRemote: true`; it must never silently acknowledge production writes.
 - `autoSchema` now defaults to `false` in the configuration factory as well as the
   core constructor. Set `autoSchema: true` to retain inferred schema behavior.
-- Migrations run transactionally before sync starts, including when initialization
-  is deferred with `autoInitialize: false`. Use idempotent SQL; this is not a
-  versioned migration framework.
+- Versioned `schemaMigrations` run transactionally before sync starts, including
+  when initialization is deferred with `autoInitialize: false`. The existing
+  `migrations` option remains available for legacy idempotent SQL that runs on
+  every initialization.
 - `initialize()` is safe to call repeatedly or concurrently. After `stop()`, call
   `client.syncWorker.start()` to resume. Mutations after stop remain queued.
 - `autoStart: false` prepares storage without automatic sync. Explicit push/pull
@@ -91,11 +92,11 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
 * **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
-* **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
-* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
-* **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
-* **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
-* **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
+* **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
+* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
+* **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
+* **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
+* **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
 * **⏰ Offline Job Scheduler & Background Cron (`client.scheduler`):** Persistent background task runner supporting human schedules and 5-field cron.
 
 
@@ -299,46 +300,46 @@ export function UserProfileHeader() {
 ---
 
 
-### 4. Offline Actions & Inbuilt Email Queue
-
-`local-lite` includes a durable **Generic Action Outbox** (`client.actions`) for side-effects that should not be lost when offline:
-
-```typescript
-import { client } from './sync.config';
-
-// ⚡ 1. Enqueue transactional email offline (0ms latency, safe if app closes)
-const emailAction = await client.actions.sendEmail({
-  to: 'customer@example.com',
-  subject: 'Order #1042 Confirmed',
-  html: '<h1>Thank you for your purchase!</h1>',
-  template: 'order_receipt',
-  templateData: { orderId: 1042, total: '$49.99' },
-  idempotencyKey: 'order_receipt_1042', // Prevents sending twice
-  ttlMs: 24 * 60 * 60 * 1000,           // Expire if offline for >24 hours
-});
-
-// ⚡ 2. Register local dispatcher (or let rows replicate to Supabase/Convex/Firebase)
-client.actions.registerEmailHandler(async (email) => {
-  // Dispatch via your transactional provider or backend API
-  const response = await fetch('https://api.resend.com/emails', {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${process.env.RESEND_API_KEY}` },
-    body: JSON.stringify(email),
-  });
-  const data = await response.json();
-  return { messageId: data.id };
-});
-
-// ⚡ 3. Enqueue arbitrary asynchronous actions (e.g., push notifications, analytics)
-await client.actions.enqueue({
-  action: 'push_notification',
-  payload: { title: 'New chat message', token: 'fcm-xxx' },
-  idempotencyKey: 'chat_msg_99',
-});
-```
-
----
-
+### 4. Offline Actions & Inbuilt Email Queue
+
+`local-lite` includes a durable **Generic Action Outbox** (`client.actions`) for side-effects that should not be lost when offline:
+
+```typescript
+import { client } from './sync.config';
+
+// ⚡ 1. Enqueue transactional email offline (0ms latency, safe if app closes)
+const emailAction = await client.actions.sendEmail({
+  to: 'customer@example.com',
+  subject: 'Order #1042 Confirmed',
+  html: '<h1>Thank you for your purchase!</h1>',
+  template: 'order_receipt',
+  templateData: { orderId: 1042, total: '$49.99' },
+  idempotencyKey: 'order_receipt_1042', // Prevents sending twice
+  ttlMs: 24 * 60 * 60 * 1000,           // Expire if offline for >24 hours
+});
+
+// ⚡ 2. Register local dispatcher (or let rows replicate to Supabase/Convex/Firebase)
+client.actions.registerEmailHandler(async (email) => {
+  // Dispatch via your transactional provider or backend API
+  const response = await fetch('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.RESEND_API_KEY}` },
+    body: JSON.stringify(email),
+  });
+  const data = await response.json();
+  return { messageId: data.id };
+});
+
+// ⚡ 3. Enqueue arbitrary asynchronous actions (e.g., push notifications, analytics)
+await client.actions.enqueue({
+  action: 'push_notification',
+  payload: { title: 'New chat message', token: 'fcm-xxx' },
+  idempotencyKey: 'chat_msg_99',
+});
+```
+
+---
+
 ## Supabase Backend Setup & Schema
 
 To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):

package/dist/actions/store.js

@@ -27,19 +27,19 @@ class ActionStore {
      * Initializes the action outbox schema and indexes if they do not exist.
      */
     static async ensureSchema(db, tableName = exports.DEFAULT_ACTIONS_TABLE) {
-        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
-        id TEXT PRIMARY KEY,
-        action TEXT NOT NULL,
-        payload TEXT NOT NULL,
-        idempotency_key TEXT UNIQUE,
-        status TEXT NOT NULL DEFAULT 'PENDING',
-        created_at INTEGER NOT NULL,
-        expires_at INTEGER,
-        executed_at INTEGER,
-        retry_count INTEGER NOT NULL DEFAULT 0,
-        max_retries INTEGER NOT NULL DEFAULT 3,
-        last_error TEXT,
-        result TEXT
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+        id TEXT PRIMARY KEY,
+        action TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        idempotency_key TEXT UNIQUE,
+        status TEXT NOT NULL DEFAULT 'PENDING',
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        executed_at INTEGER,
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 3,
+        last_error TEXT,
+        result TEXT
       );`);
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_status ON ${tableName} (status, created_at);`);
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_idempotency ON ${tableName} (idempotency_key);`);
@@ -55,8 +55,8 @@ class ActionStore {
      * Inserts an action record into storage.
      */
     static async insertRecord(db, tableName = exports.DEFAULT_ACTIONS_TABLE, record) {
-        await db.execute(`INSERT INTO ${tableName} (
-        id, action, payload, idempotency_key, status, created_at, expires_at, executed_at, retry_count, max_retries, last_error, result
+        await db.execute(`INSERT INTO ${tableName} (
+        id, action, payload, idempotency_key, status, created_at, expires_at, executed_at, retry_count, max_retries, last_error, result
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);`, [
             record.id,
             record.action,

package/dist/auth/session.js

@@ -54,19 +54,19 @@ class SessionManager {
      * Ensures the _local_sessions schema exists.
      */
     async initialize() {
-        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
-        id TEXT PRIMARY KEY,
-        user_id TEXT NOT NULL,
-        user_data TEXT NOT NULL,
-        token TEXT,
-        refresh_token TEXT,
-        provider TEXT,
-        created_at INTEGER NOT NULL,
-        last_active_at INTEGER NOT NULL,
-        expires_at INTEGER,
-        offline_access_until INTEGER,
-        metadata TEXT,
-        is_active INTEGER NOT NULL DEFAULT 1
+        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        user_data TEXT NOT NULL,
+        token TEXT,
+        refresh_token TEXT,
+        provider TEXT,
+        created_at INTEGER NOT NULL,
+        last_active_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        offline_access_until INTEGER,
+        metadata TEXT,
+        is_active INTEGER NOT NULL DEFAULT 1
       );`);
         await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_user ON ${this.tableName} (user_id);`);
         await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_active ON ${this.tableName} (is_active);`);
@@ -90,20 +90,20 @@ class SessionManager {
             // Deactivate other sessions
             await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
         }
-        const sql = `
-      INSERT INTO ${this.tableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        user_id = excluded.user_id,
-        user_data = excluded.user_data,
-        token = excluded.token,
-        refresh_token = excluded.refresh_token,
-        provider = excluded.provider,
-        last_active_at = excluded.last_active_at,
-        expires_at = excluded.expires_at,
-        offline_access_until = excluded.offline_access_until,
-        metadata = excluded.metadata,
-        is_active = excluded.is_active;
+        const sql = `
+      INSERT INTO ${this.tableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        user_id = excluded.user_id,
+        user_data = excluded.user_data,
+        token = excluded.token,
+        refresh_token = excluded.refresh_token,
+        provider = excluded.provider,
+        last_active_at = excluded.last_active_at,
+        expires_at = excluded.expires_at,
+        offline_access_until = excluded.offline_access_until,
+        metadata = excluded.metadata,
+        is_active = excluded.is_active;
     `;
         await this.db.execute(sql, [
             id,

package/dist/config/index.js

@@ -85,6 +85,7 @@ async function createSyncClient(config) {
         autoSchema,
         tables: config.tables ?? [],
         migrations: config.migrations,
+        schemaMigrations: config.schemaMigrations,
         autoStart: config.autoStart,
         jsonColumns: config.jsonColumns,
         autoHydrateJSON: config.autoHydrateJSON,

package/dist/config/types.d.ts

@@ -1,6 +1,6 @@
 import { LocalDBAdapter } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
-import { ConflictResolver, ConflictStrategy, NetworkStatusProvider, RetryConfig } from '../core/types.js';
+import { ConflictResolver, ConflictStrategy, NetworkStatusProvider, RetryConfig, SchemaMigration } from '../core/types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 export interface SupabaseConfigOptions {
     url?: string;
@@ -84,10 +84,15 @@ export interface LocalLiteConfig {
      */
     tables?: string[];
     /**
-     * Initial SQL table schema migration queries to execute on startup.
+     * Legacy idempotent SQL statements executed transactionally on every initialization.
      * e.g. ["CREATE TABLE IF NOT EXISTS todos (id TEXT PRIMARY KEY, title TEXT);"]
      */
     migrations?: string[];
+    /**
+     * Versioned application schema migrations. Versions must be consecutive integers
+     * starting at 1; each migration is applied once and recorded in schema_migrations.
+     */
+    schemaMigrations?: SchemaMigration[];
     /**
      * Automatically create tables and columns dynamically on the fly without manual SQL migrations.
      * Opt-in (default: false). When true, tables in `tables` are created automatically,

package/dist/core/client.d.ts

@@ -4,7 +4,7 @@ import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
 import { DatabaseMaintenance } from './maintenance.js';
 import { SchemaManager } from './schema-manager.js';
-import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
+import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SchemaMigration, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
 import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
@@ -31,6 +31,7 @@ export interface LocalFirstClientConfig {
     autoSchema?: boolean;
     tables?: string[];
     migrations?: string[];
+    schemaMigrations?: SchemaMigration[];
     autoStart?: boolean;
     coalesceOutbox?: boolean;
     jsonColumns?: Record<string, string[]>;
@@ -108,6 +109,7 @@ export declare class LocalFirstClient {
     readonly session: SessionManager;
     private primaryKey;
     private migrations;
+    private schemaMigrations;
     private autoStart;
     private initialization?;
     constructor(config: LocalFirstClientConfig);
@@ -139,6 +141,7 @@ export declare class LocalFirstClient {
      */
     initialize(): Promise<void>;
     private initializeStorage;
+    private applySchemaMigrations;
     /**
      * Performs an atomic dual-write: mutates the local data table AND writes
      * to sync_outbox within the same database transaction.
@@ -347,7 +350,21 @@ export declare class LocalFirstClient {
         dropTables?: boolean;
         includeInternal?: boolean;
     }): Promise<void>;
-    private getAllTableNames;
+    /**
+   * Checks if a table name belongs to internal system, FTS, or engine tables.
+   */
+    isInternalTable(tableName: string): boolean;
+    /**
+     * Returns list of database tables.
+     * By default, internal tables (FTS shadow tables, local-lite engine tables) are excluded.
+     * Pass `{ includeInternal: true }` to include internal tables.
+     */
+    getTables(options?: {
+        includeInternal?: boolean;
+    }): Promise<string[]>;
+    getAllTableNames(options?: {
+        includeInternal?: boolean;
+    }): Promise<string[]>;
     /**
      * Exports the entire local database state as a portable binary snapshot.
      * If the local adapter has a native export mechanism (e.g. serialize or export),

package/dist/core/client.js

@@ -21,6 +21,30 @@ const index_js_5 = require("../search/index.js");
 const index_js_6 = require("../storage/index.js");
 const index_js_7 = require("../scheduler/index.js");
 const session_js_1 = require("../auth/session.js");
+function normalizeSchemaMigrations(migrations) {
+    if (!Array.isArray(migrations)) {
+        throw new TypeError('schemaMigrations must be an array.');
+    }
+    if (migrations.some((migration) => !migration ||
+        typeof migration !== 'object' ||
+        !Number.isSafeInteger(migration.version) ||
+        migration.version < 1)) {
+        throw new TypeError('Each schema migration must have a positive integer version.');
+    }
+    const ordered = [...migrations].sort((a, b) => a.version - b.version);
+    return ordered.map((migration, index) => {
+        const expectedVersion = index + 1;
+        if (!migration || !Number.isSafeInteger(migration.version) || migration.version !== expectedVersion) {
+            throw new TypeError(`schemaMigrations must use consecutive integer versions starting at 1; expected version ${expectedVersion}.`);
+        }
+        const statements = Array.isArray(migration.up) ? migration.up : [migration.up];
+        if (statements.length === 0 ||
+            statements.some((statement) => typeof statement !== 'string' || statement.trim().length === 0)) {
+            throw new TypeError(`schemaMigrations version ${migration.version} must contain non-empty SQL.`);
+        }
+        return { version: migration.version, up: statements.map((statement) => statement.trim()) };
+    });
+}
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -182,6 +206,7 @@ class LocalFirstClient {
     session;
     primaryKey;
     migrations;
+    schemaMigrations;
     autoStart;
     initialization;
     constructor(config) {
@@ -193,6 +218,7 @@ class LocalFirstClient {
         this.coalesceOutbox = config.coalesceOutbox ?? true;
         this.tables = config.tables ?? [];
         this.migrations = config.migrations ?? [];
+        this.schemaMigrations = normalizeSchemaMigrations(config.schemaMigrations ?? []);
         this.autoStart = config.autoStart ?? true;
         this.jsonColumns = config.jsonColumns ?? {};
         this.autoHydrateJSON = config.autoHydrateJSON ?? false;
@@ -416,6 +442,7 @@ class LocalFirstClient {
                 }
             });
         }
+        await this.applySchemaMigrations();
         if (this.autoSchema && this.tables.length > 0) {
             for (const table of this.tables) {
                 await this.schemaManager.ensureTable(this.db, table, this.primaryKey);
@@ -424,6 +451,36 @@ class LocalFirstClient {
         if (this.autoStart)
             this.syncWorker.start();
     }
+    async applySchemaMigrations() {
+        if (this.schemaMigrations.length === 0)
+            return;
+        await this.db.transaction(async (tx) => {
+            await tx.execute(`CREATE TABLE IF NOT EXISTS schema_migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at INTEGER NOT NULL
+        );`);
+            const rows = await tx.execute('SELECT version FROM schema_migrations ORDER BY version ASC');
+            const appliedVersions = rows.map((row) => Number(row.version));
+            for (let index = 0; index < appliedVersions.length; index += 1) {
+                if (appliedVersions[index] !== index + 1) {
+                    throw new Error('The schema_migrations table contains a missing or invalid version.');
+                }
+            }
+            let currentVersion = appliedVersions.at(-1) ?? 0;
+            if (currentVersion > this.schemaMigrations.length) {
+                throw new Error(`Database schema version ${currentVersion} is newer than the latest available migration (${this.schemaMigrations.length}).`);
+            }
+            for (const migration of this.schemaMigrations) {
+                if (migration.version <= currentVersion)
+                    continue;
+                for (const statement of migration.up) {
+                    await tx.execute(statement);
+                }
+                await tx.execute('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)', [migration.version, Date.now()]);
+                currentVersion = migration.version;
+            }
+        });
+    }
     /**
      * Performs an atomic dual-write: mutates the local data table AND writes
      * to sync_outbox within the same database transaction.
@@ -978,22 +1035,50 @@ class LocalFirstClient {
         await this.resetSyncCursor();
         this.events.emit('reset', { dropTables: options.dropTables ?? false });
     }
-    async getAllTableNames() {
+    /**
+   * Checks if a table name belongs to internal system, FTS, or engine tables.
+   */
+    isInternalTable(tableName) {
+        return (0, sql_js_1.isInternalTable)(tableName);
+    }
+    /**
+     * Returns list of database tables.
+     * By default, internal tables (FTS shadow tables, local-lite engine tables) are excluded.
+     * Pass `{ includeInternal: true }` to include internal tables.
+     */
+    async getTables(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
+        const allTables = await this.getAllTableNames(options);
+        if (includeInternal) {
+            return allTables;
+        }
+        return allTables.filter(name => !(0, sql_js_1.isInternalTable)(name));
+    }
+    async getAllTableNames(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
         const list = new Set(this.tables);
-        list.add('sync_outbox');
-        list.add('sync_meta');
+        if (includeInternal) {
+            list.add('sync_outbox');
+            list.add('sync_meta');
+        }
         try {
-            const rows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            const rows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'android_%'`);
             if (Array.isArray(rows)) {
                 for (const r of rows) {
-                    if (r.name)
-                        list.add(r.name);
+                    if (r.name) {
+                        if (includeInternal || !(0, sql_js_1.isInternalTable)(r.name)) {
+                            list.add(r.name);
+                        }
+                    }
                 }
             }
         }
         catch {
             // Non-SQLite database adapter, fallback to configured tables
         }
+        if (!includeInternal) {
+            return Array.from(list).filter(name => !(0, sql_js_1.isInternalTable)(name));
+        }
         return Array.from(list);
     }
     /**

package/dist/core/maintenance.d.ts

@@ -62,5 +62,7 @@ export declare class DatabaseMaintenance {
     /**
      * Gathers storage metrics: table row counts, outbox status distribution, and database size.
      */
-    getStorageStats(): Promise<StorageStats>;
+    getStorageStats(options?: {
+        includeInternal?: boolean;
+    }): Promise<StorageStats>;
 }

package/dist/core/maintenance.js

@@ -76,17 +76,21 @@ class DatabaseMaintenance {
     /**
      * Gathers storage metrics: table row counts, outbox status distribution, and database size.
      */
-    async getStorageStats() {
+    async getStorageStats(options = {}) {
+        const includeInternal = options.includeInternal ?? false;
         // 1. Table row counts
         const tableCounts = {};
         let tableNames = [];
         try {
-            const masterRows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+            const masterRows = await this.db.execute(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'android_%'`);
             tableNames = masterRows.map((r) => r.name);
         }
         catch {
             tableNames = this.getKnownTables();
         }
+        if (!includeInternal) {
+            tableNames = tableNames.filter(name => !(0, sql_js_1.isInternalTable)(name));
+        }
         for (const tableName of tableNames) {
             try {
                 const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);

package/dist/core/meta-store.js

@@ -7,9 +7,9 @@ class MetaStore {
      * This table is strictly local to the device and is never synced to the remote server.
      */
     static async ensureSchema(db) {
-        await db.execute(`CREATE TABLE IF NOT EXISTS sync_meta (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
+        await db.execute(`CREATE TABLE IF NOT EXISTS sync_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
       );`);
     }
     /**

package/dist/core/outbox-store.js

@@ -22,16 +22,16 @@ class OutboxStore {
      * Initializes the sync_outbox schema if it does not already exist.
      */
     static async ensureSchema(db) {
-        await db.execute(`CREATE TABLE IF NOT EXISTS sync_outbox (
-        id TEXT PRIMARY KEY,
-        table_name TEXT NOT NULL,
-        row_id TEXT NOT NULL,
-        operation TEXT NOT NULL,
-        payload TEXT,
-        timestamp INTEGER NOT NULL,
-        status TEXT NOT NULL DEFAULT 'PENDING',
-        retry_count INTEGER NOT NULL DEFAULT 0,
-        last_error TEXT
+        await db.execute(`CREATE TABLE IF NOT EXISTS sync_outbox (
+        id TEXT PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        row_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        payload TEXT,
+        timestamp INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'PENDING',
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT
       );`);
         // Indexes for the hot paths: pending scans (push), per-row conflict lookups (pull),
         // and status counts (telemetry). Executed separately: many drivers prepare one statement.
@@ -43,7 +43,7 @@ class OutboxStore {
      * Inserts a new outbox entry within an existing database transaction.
      */
     static async insertRecord(tx, op) {
-        await tx.execute(`INSERT INTO sync_outbox (id, table_name, row_id, operation, payload, timestamp, status, retry_count)
+        await tx.execute(`INSERT INTO sync_outbox (id, table_name, row_id, operation, payload, timestamp, status, retry_count)
        VALUES (?, ?, ?, ?, ?, ?, 'PENDING', 0)`, [
             op.id,
             op.tableName,
@@ -85,11 +85,11 @@ class OutboxStore {
     static async getPending(db, maxRetries = 5, limit = 50) {
         const isInfinite = !Number.isFinite(maxRetries) || maxRetries === -1;
         const query = isInfinite
-            ? `SELECT * FROM sync_outbox 
-         WHERE status = 'PENDING' OR status = 'FAILED' 
+            ? `SELECT * FROM sync_outbox 
+         WHERE status = 'PENDING' OR status = 'FAILED' 
          ORDER BY timestamp ASC LIMIT ?`
-            : `SELECT * FROM sync_outbox 
-         WHERE status = 'PENDING' OR (status = 'FAILED' AND retry_count < ?) 
+            : `SELECT * FROM sync_outbox 
+         WHERE status = 'PENDING' OR (status = 'FAILED' AND retry_count < ?) 
          ORDER BY timestamp ASC LIMIT ?`;
         const params = isInfinite ? [limit] : [maxRetries, limit];
         const rows = await db.execute(query, params);
@@ -101,8 +101,8 @@ class OutboxStore {
      * Finds the latest pending outbox record for a given table and row.
      */
     static async findPendingByRow(tx, tableName, rowId) {
-        const rows = await tx.execute(`SELECT * FROM sync_outbox 
-       WHERE table_name = ? AND row_id = ? AND status != 'FAILED' 
+        const rows = await tx.execute(`SELECT * FROM sync_outbox 
+       WHERE table_name = ? AND row_id = ? AND status != 'FAILED' 
        ORDER BY timestamp DESC LIMIT 1`, [tableName, rowId]);
         if (!rows || rows.length === 0)
             return undefined;
@@ -193,10 +193,10 @@ class OutboxStore {
         if (ids.length === 0)
             return;
         const placeholders = ids.map(() => '?').join(',');
-        await db.execute(`UPDATE sync_outbox 
-       SET status = 'FAILED', 
-           retry_count = retry_count + 1, 
-           last_error = ? 
+        await db.execute(`UPDATE sync_outbox 
+       SET status = 'FAILED', 
+           retry_count = retry_count + 1, 
+           last_error = ? 
        WHERE id IN (${placeholders})`, [errorMessage, ...ids]);
     }
     /**
@@ -235,8 +235,8 @@ class OutboxStore {
         try {
             if (ids && ids.length > 0) {
                 const placeholders = ids.map(() => '?').join(',');
-                await db.execute(`UPDATE sync_outbox 
-           SET status = 'PENDING', retry_count = 0, last_error = NULL 
+                await db.execute(`UPDATE sync_outbox 
+           SET status = 'PENDING', retry_count = 0, last_error = NULL 
            WHERE status = 'FAILED' AND id IN (${placeholders})`, ids);
                 return ids.length;
             }