@prabhask5/stellar-engine 1.2.0 → 1.2.2

package/dist/config.d.ts

@@ -2,20 +2,19 @@
  * @fileoverview Engine Configuration and Initialization
  *
  * Central configuration hub for the sync engine. {@link initEngine} is the
- * first function consumers call — it accepts a {@link SyncEngineConfig} object
- * that describes:
+ * first function consumers call — it accepts a configuration object that
+ * describes:
  *   - Which Supabase tables to sync and their IndexedDB schemas
  *   - Authentication configuration (single-user gate, offline auth, etc.)
  *   - Sync timing parameters (debounce, polling interval, tombstone TTL)
  *   - Optional callbacks for auth state changes
  *
  * The config is stored as a module-level singleton and accessed by every other
- * module via {@link getEngineConfig}. The database creation flow supports two
- * modes:
- *   1. **Managed** — Engine creates and owns the Dexie instance from a
- *      {@link DatabaseConfig} (recommended).
- *   2. **Provided** — Consumer passes a pre-created `Dexie` instance for
- *      backward compatibility.
+ * module via {@link getEngineConfig}. Supports two configuration modes:
+ *   1. **Schema-driven** (recommended) — Provide a `schema` object. The engine
+ *      auto-generates tables, Dexie stores, versioning, and database naming.
+ *   2. **Manual** — Provide explicit `tables` and `database` for full control
+ *      over IndexedDB versioning and migration history.
  *
  * @see {@link database.ts} for Dexie instance creation
  * @see {@link engine.ts} for the sync lifecycle that consumes this config
@@ -23,38 +22,62 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { Session } from '@supabase/supabase-js';
 import type Dexie from 'dexie';
-import type { SingleUserGateType } from './types';
+import type { SingleUserGateType, SchemaDefinition, AuthConfig } from './types';
 import type { CRDTConfig } from './crdt/types';
 import type { DemoConfig } from './demo';
 import { type DatabaseConfig } from './database';
 /**
  * Top-level configuration for the sync engine.
  *
- * Passed to {@link initEngine} at app startup. All fields except `tables`
- * and `prefix` have sensible defaults.
+ * Passed to {@link initEngine} at app startup. Supports two configuration modes:
+ *
+ * 1. **Schema-driven** (recommended) — Provide a `schema` object. The engine
+ *    auto-generates `tables`, Dexie stores, versioning, and database naming.
+ * 2. **Manual** — Provide explicit `tables` and `database` for full control
+ *    over IndexedDB versioning and migration history.
+ *
+ * The two modes are mutually exclusive (`schema` vs `tables` + `database`).
  *
  * @example
+ * // Schema-driven (recommended):
  * initEngine({
  *   prefix: 'myapp',
- *   tables: [
- *     { supabaseName: 'goals', columns: 'id,title,target,current_value,...' },
- *   ],
- *   database: { name: 'myapp-db', versions: [{ version: 1, stores: { goals: 'id,user_id' } }] },
- *   syncDebounceMs: 1000,
+ *   schema: {
+ *     goals: 'goal_list_id, order',
+ *     focus_settings: { singleton: true },
+ *   },
+ *   auth: { gateType: 'code', codeLength: 6 },
  * });
  */
 export interface SyncEngineConfig {
-    /** Per-table sync configuration (required). */
+    /** Per-table sync configuration. Auto-populated when using `schema`. */
     tables: TableConfig[];
     /** Application prefix — used for localStorage keys, debug logging, etc. */
     prefix: string;
-    /** Provide a pre-created Dexie instance (backward compat). Mutually exclusive with `database`. */
+    /**
+     * Declarative schema definition — replaces both `tables` and `database`.
+     *
+     * Each key is a Supabase table name (snake_case). Values are either a string
+     * of Dexie indexes or a {@link SchemaTableConfig} object for full control.
+     * Mutually exclusive with `tables` + `database`.
+     *
+     * @see {@link SchemaDefinition} for the full type definition
+     */
+    schema?: SchemaDefinition;
+    /**
+     * Override the auto-generated database name when using `schema`.
+     *
+     * By default, the database is named `${prefix}DB` (e.g., `stellarDB`).
+     * Use this to keep an existing database name for data continuity.
+     */
+    databaseName?: string;
+    /** Dexie instance — set internally by `createDatabase()`. Do not set manually. */
     db?: Dexie;
-    /** Provide a pre-created Supabase client (backward compat). Engine creates one internally if not provided. */
+    /** Supabase client — pass to use a custom client instead of the engine's internal proxy. */
     supabase?: SupabaseClient;
-    /** Engine creates and owns the Dexie instance when this is provided. */
+    /** Database creation config — auto-generated when using `schema`, or provided manually. */
     database?: DatabaseConfig;
-    /** Authentication configuration. */
+    /** Authentication configuration (nested/internal form). */
     auth?: {
         /** Single-user mode gate configuration. */
         singleUser?: {
@@ -112,9 +135,11 @@ export interface SyncEngineConfig {
      * CRDT document storage and allows use of the `@prabhask5/stellar-engine/crdt` API.
      * When omitted, no CRDT tables are created and CRDT imports will throw.
      *
+     * Pass `true` as shorthand for `{}` (all defaults).
+     *
      * @see {@link CRDTConfig} for available configuration options
      */
-    crdt?: CRDTConfig;
+    crdt?: CRDTConfig | true;
 }
 /**
  * Per-table sync configuration.
@@ -152,20 +177,29 @@ export interface TableConfig {
  *
  * Must be called once at app startup, before any other engine function.
  * Propagates the `prefix` to all internal modules (debug, deviceId,
- * Supabase client, runtime config) and creates or registers the Dexie
- * database instance.
+ * Supabase client, runtime config) and creates the Dexie database instance.
  *
- * @param config - The full engine configuration object.
+ * @param config - The engine configuration object.
  *
  * @example
- * // In your app's root layout or entry point:
  * initEngine({
  *   prefix: 'myapp',
- *   tables: [...],
- *   database: { name: 'myapp-db', versions: [...] },
+ *   schema: { goals: 'goal_list_id, order' },
+ *   auth: { gateType: 'code', codeLength: 6 },
  * });
  */
-export declare function initEngine(config: SyncEngineConfig): void;
+/**
+ * Input type for {@link initEngine}.
+ *
+ * Differs from {@link SyncEngineConfig} in two ways:
+ * - `tables` is optional (auto-generated when `schema` is provided)
+ * - `auth` accepts either the flat {@link AuthConfig} or the nested internal form
+ */
+export type InitEngineInput = Omit<SyncEngineConfig, 'tables' | 'auth'> & {
+    tables?: TableConfig[];
+    auth?: AuthConfig | SyncEngineConfig['auth'];
+};
+export declare function initEngine(config: InitEngineInput): void;
 /**
  * Wait for the database to be fully opened and upgraded.
  *

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -2,20 +2,19 @@
  * @fileoverview Engine Configuration and Initialization
  *
  * Central configuration hub for the sync engine. {@link initEngine} is the
- * first function consumers call — it accepts a {@link SyncEngineConfig} object
- * that describes:
+ * first function consumers call — it accepts a configuration object that
+ * describes:
  *   - Which Supabase tables to sync and their IndexedDB schemas
  *   - Authentication configuration (single-user gate, offline auth, etc.)
  *   - Sync timing parameters (debounce, polling interval, tombstone TTL)
  *   - Optional callbacks for auth state changes
  *
  * The config is stored as a module-level singleton and accessed by every other
- * module via {@link getEngineConfig}. The database creation flow supports two
- * modes:
- *   1. **Managed** — Engine creates and owns the Dexie instance from a
- *      {@link DatabaseConfig} (recommended).
- *   2. **Provided** — Consumer passes a pre-created `Dexie` instance for
- *      backward compatibility.
+ * module via {@link getEngineConfig}. Supports two configuration modes:
+ *   1. **Schema-driven** (recommended) — Provide a `schema` object. The engine
+ *      auto-generates tables, Dexie stores, versioning, and database naming.
+ *   2. **Manual** — Provide explicit `tables` and `database` for full control
+ *      over IndexedDB versioning and migration history.
  *
  * @see {@link database.ts} for Dexie instance creation
  * @see {@link engine.ts} for the sync lifecycle that consumes this config
@@ -25,7 +24,7 @@ import { _setDeviceIdPrefix } from './deviceId';
 import { _setClientPrefix } from './supabase/client';
 import { _setConfigPrefix } from './runtime/runtimeConfig';
 import { registerDemoConfig, _setDemoPrefix, isDemoMode } from './demo';
-import { createDatabase, _setManagedDb } from './database';
+import { createDatabase, SYSTEM_INDEXES, computeSchemaVersion } from './database';
 import { _initCRDT } from './crdt/config';
 import { snakeToCamel } from './utils';
 // =============================================================================
@@ -35,28 +34,32 @@ import { snakeToCamel } from './utils';
 let engineConfig = null;
 /** Promise that resolves when the database is fully opened and upgraded. */
 let _dbReady = null;
-// =============================================================================
-// Initialization
-// =============================================================================
-/**
- * Initialize the sync engine with the provided configuration.
- *
- * Must be called once at app startup, before any other engine function.
- * Propagates the `prefix` to all internal modules (debug, deviceId,
- * Supabase client, runtime config) and creates or registers the Dexie
- * database instance.
- *
- * @param config - The full engine configuration object.
- *
- * @example
- * // In your app's root layout or entry point:
- * initEngine({
- *   prefix: 'myapp',
- *   tables: [...],
- *   database: { name: 'myapp-db', versions: [...] },
- * });
- */
 export function initEngine(config) {
+    /* Normalize `crdt: true` shorthand to `crdt: {}`. */
+    if (config.crdt === true) {
+        config.crdt = {};
+    }
+    /* Normalize flat auth config to the nested structure used internally. */
+    if (config.auth) {
+        config.auth = normalizeAuthConfig(config.auth);
+    }
+    /*
+     * Schema-driven mode: auto-generate `tables` and `database` from the
+     * declarative schema definition.
+     */
+    if (config.schema) {
+        if (config.tables || config.database) {
+            throw new Error('initEngine: `schema` is mutually exclusive with `tables` and `database`. ' +
+                'Use either the schema-driven API or the manual API, not both.');
+        }
+        config.tables = generateTablesFromSchema(config.schema);
+        config.database = generateDatabaseFromSchema(config.schema, config.prefix, config.databaseName, !!config.crdt);
+    }
+    /* Validate that tables are configured (either manually or via schema). */
+    if (!config.tables || config.tables.length === 0) {
+        throw new Error('initEngine: No tables configured. Provide `schema` or `tables` + `database`.');
+    }
+    /* At this point tables is guaranteed to be populated — safe to cast. */
     engineConfig = config;
     /* Propagate prefix to all internal modules that use localStorage keys. */
     if (config.prefix) {
@@ -78,19 +81,13 @@ export function initEngine(config) {
     if (isDemoMode() && config.database) {
         config.database = { ...config.database, name: config.database.name + '_demo' };
     }
-    /* Handle database creation — either managed or provided.
+    /* Create the Dexie database and store the instance on config for engine.ts access.
      * Pass crdtEnabled flag so CRDT IndexedDB tables are conditionally included. */
     if (config.database) {
         _dbReady = createDatabase(config.database, !!config.crdt).then((db) => {
-            /* Store on config for backward compat (engine.ts reads config.db). */
             config.db = db;
         });
     }
-    else if (config.db) {
-        /* Backward compat: use the consumer-provided Dexie instance. */
-        _setManagedDb(config.db);
-        _dbReady = Promise.resolve();
-    }
 }
 // =============================================================================
 // Accessors
@@ -164,4 +161,235 @@ export function getTableColumns(supabaseName) {
     }
     return table.columns;
 }
+// =============================================================================
+// Schema → Config Generation
+// =============================================================================
+/**
+ * Generate `TableConfig[]` from a declarative {@link SchemaDefinition}.
+ *
+ * Each schema key becomes a `TableConfig` with:
+ * - `supabaseName` = the schema key (snake_case)
+ * - `columns` = `'*'` (SELECT all by default — no egress micro-optimization)
+ * - `ownershipFilter` = `'user_id'` (default, since RLS always filters by user)
+ * - `isSingleton`, `excludeFromConflict`, `numericMergeFields`, `onRemoteChange`
+ *   from the object form (if provided)
+ *
+ * @param schema - The declarative schema definition.
+ * @returns An array of `TableConfig` objects ready for engine consumption.
+ *
+ * @example
+ * generateTablesFromSchema({
+ *   goals: 'goal_list_id, order',
+ *   focus_settings: { singleton: true },
+ * });
+ * // → [
+ * //   { supabaseName: 'goals', columns: '*', ownershipFilter: 'user_id' },
+ * //   { supabaseName: 'focus_settings', columns: '*', ownershipFilter: 'user_id', isSingleton: true },
+ * // ]
+ */
+function generateTablesFromSchema(schema) {
+    const tables = [];
+    for (const [tableName, definition] of Object.entries(schema)) {
+        /* String form is sugar for { indexes: theString }. */
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        const tableConfig = {
+            supabaseName: tableName,
+            columns: config.columns || '*',
+            ownershipFilter: config.ownership || 'user_id'
+        };
+        if (config.singleton)
+            tableConfig.isSingleton = true;
+        if (config.excludeFromConflict)
+            tableConfig.excludeFromConflict = config.excludeFromConflict;
+        if (config.numericMergeFields)
+            tableConfig.numericMergeFields = config.numericMergeFields;
+        if (config.onRemoteChange)
+            tableConfig.onRemoteChange = config.onRemoteChange;
+        tables.push(tableConfig);
+    }
+    return tables;
+}
+/**
+ * Generate a `DatabaseConfig` from a declarative {@link SchemaDefinition}.
+ *
+ * Builds the Dexie store schema for each table by combining the app-specific
+ * indexes from the schema with the {@link SYSTEM_INDEXES} constant. Uses
+ * {@link computeSchemaVersion} for automatic version management.
+ *
+ * @param schema - The declarative schema definition.
+ * @param prefix - Application prefix for database naming and versioning.
+ * @param databaseName - Optional override for the database name.
+ * @param crdtEnabled - Whether the CRDT subsystem is enabled.
+ * @returns A `DatabaseConfig` ready for `createDatabase()`.
+ *
+ * @example
+ * generateDatabaseFromSchema(
+ *   { goals: 'goal_list_id, order' },
+ *   'stellar',
+ *   undefined,
+ *   false
+ * );
+ * // → {
+ * //   name: 'stellarDB',
+ * //   versions: [{ version: 1, stores: { goals: 'id, user_id, ..., goal_list_id, order' } }]
+ * // }
+ */
+function generateDatabaseFromSchema(schema, prefix, databaseName, crdtEnabled = false) {
+    const stores = {};
+    for (const [tableName, definition] of Object.entries(schema)) {
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        /* Determine the Dexie table name (camelCase by default, or explicit override). */
+        const dexieName = config.dexieName || snakeToCamel(tableName);
+        /* Merge system indexes with app-specific indexes. */
+        const appIndexes = (config.indexes || '').trim();
+        stores[dexieName] = appIndexes ? `${SYSTEM_INDEXES}, ${appIndexes}` : SYSTEM_INDEXES;
+    }
+    /* Compute auto-version based on the merged store schema.
+     * The CRDT flag affects the schema hash because CRDT system tables are merged
+     * by buildDexie() — if CRDT is toggled, the version should bump. */
+    const hashInput = crdtEnabled ? { ...stores, __crdt: 'enabled' } : stores;
+    const result = computeSchemaVersion(prefix, hashInput);
+    /*
+     * Build the versions array. When an upgrade is detected, declare BOTH
+     * the previous version and the current version so Dexie has a proper
+     * upgrade path (v(N-1) → vN). This avoids the UpgradeError that occurs
+     * when only the new version is declared and the browser already has the
+     * old version's IndexedDB schema.
+     *
+     * Dexie handles additive changes (new tables, new indexes) natively.
+     * For the previous version we use its original stores so Dexie can diff
+     * and apply the structural changes.
+     */
+    const versions = [];
+    if (result.previousStores && result.previousVersion) {
+        versions.push({ version: result.previousVersion, stores: result.previousStores });
+    }
+    /*
+     * Generate an upgrade callback when any table declares `renamedFrom`.
+     * The callback copies data from the old Dexie table to the new one,
+     * applying any `renamedColumns` transformations along the way.
+     */
+    const upgradeCallback = buildRenameUpgradeCallback(schema);
+    if (upgradeCallback) {
+        versions.push({ version: result.version, stores, upgrade: upgradeCallback });
+    }
+    else {
+        versions.push({ version: result.version, stores });
+    }
+    return {
+        name: databaseName || `${prefix}DB`,
+        versions
+    };
+}
+/**
+ * Build a Dexie upgrade callback that handles table renames.
+ *
+ * When a table declares `renamedFrom`, the callback copies all rows from
+ * the old table name to the new one, applying any `renamedColumns` field
+ * name transformations. Dexie's schema diff handles creating the new table
+ * and removing the old one — this callback only handles data migration.
+ *
+ * @param schema - The declarative schema definition.
+ * @returns An upgrade function, or `null` if no renames are declared.
+ * @internal
+ */
+function buildRenameUpgradeCallback(schema) {
+    /* Collect all rename operations. */
+    const renames = [];
+    for (const [tableName, definition] of Object.entries(schema)) {
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        if (!config.renamedFrom)
+            continue;
+        const oldDexie = config.dexieName ? config.dexieName : snakeToCamel(config.renamedFrom);
+        const newDexie = config.dexieName || snakeToCamel(tableName);
+        /* Only generate a callback if the Dexie name actually changed. */
+        if (oldDexie !== newDexie) {
+            renames.push({
+                oldDexie,
+                newDexie,
+                columnMap: config.renamedColumns
+            });
+        }
+    }
+    if (renames.length === 0)
+        return null;
+    return async (tx) => {
+        for (const { oldDexie, newDexie, columnMap } of renames) {
+            try {
+                const oldTable = tx.table(oldDexie);
+                const newTable = tx.table(newDexie);
+                const rows = await oldTable.toArray();
+                for (const row of rows) {
+                    /* Apply column renames if specified. */
+                    if (columnMap) {
+                        for (const [newCol, oldCol] of Object.entries(columnMap)) {
+                            if (oldCol in row) {
+                                row[newCol] = row[oldCol];
+                                delete row[oldCol];
+                            }
+                        }
+                    }
+                    await newTable.put(row);
+                }
+                /* Clear the old table — Dexie's schema diff will remove it. */
+                await oldTable.clear();
+            }
+            catch {
+                /* Old table may not exist (e.g., fresh install) — skip silently. */
+            }
+        }
+    };
+}
+/**
+ * Normalize an auth config to the internal nested structure.
+ *
+ * Detects whether the config is in the flat form ({@link AuthConfig}) or
+ * the nested form (has a `singleUser` key). Flat form is converted to
+ * nested; nested form is passed through unchanged.
+ *
+ * @param auth - The auth config (flat or nested).
+ * @returns The normalized nested auth config.
+ * @internal
+ */
+function normalizeAuthConfig(auth) {
+    if (!auth)
+        return auth;
+    /* Detect nested form by the presence of `singleUser` key. */
+    if ('singleUser' in auth) {
+        return auth;
+    }
+    /* Flat form (AuthConfig) → convert to nested structure. */
+    const flat = auth;
+    const nested = {};
+    /* Map flat singleUser fields to nested singleUser object. */
+    const gateType = flat.gateType || 'code';
+    const codeLength = flat.codeLength || 6;
+    nested.singleUser = {
+        gateType,
+        ...(gateType === 'code' ? { codeLength } : {})
+    };
+    /* Map flat boolean flags to nested object structures. */
+    const emailConfirmation = flat.emailConfirmation !== undefined ? flat.emailConfirmation : true;
+    nested.emailConfirmation = { enabled: emailConfirmation };
+    const deviceVerification = flat.deviceVerification !== undefined ? flat.deviceVerification : true;
+    nested.deviceVerification = {
+        enabled: deviceVerification,
+        trustDurationDays: flat.trustDurationDays || 90
+    };
+    /* Pass through remaining fields with defaults. */
+    nested.confirmRedirectPath = flat.confirmRedirectPath || '/confirm';
+    nested.enableOfflineAuth =
+        flat.enableOfflineAuth !== undefined ? flat.enableOfflineAuth : true;
+    if (flat.sessionValidationIntervalMs !== undefined) {
+        nested.sessionValidationIntervalMs =
+            flat.sessionValidationIntervalMs;
+    }
+    if (flat.profileExtractor) {
+        nested.profileExtractor = flat.profileExtractor;
+    }
+    if (flat.profileToMetadata) {
+        nested.profileToMetadata = flat.profileToMetadata;
+    }
+    return nested;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/database.d.ts

@@ -2,14 +2,9 @@
  * @fileoverview IndexedDB Database Management via Dexie
  *
  * Manages the lifecycle of the Dexie (IndexedDB) database instance used
- * by the sync engine. The engine can operate in two modes:
- *
- *   1. **Managed mode** — The engine creates and owns the Dexie instance
- *      via {@link createDatabase}. System tables (syncQueue, conflictHistory,
- *      etc.) are automatically merged into every schema version declaration.
- *
- *   2. **Provided mode** — The consumer passes a pre-created Dexie instance
- *      via {@link _setManagedDb} (backward compatibility).
+ * by the sync engine. The engine creates and owns the Dexie instance
+ * via {@link createDatabase}. System tables (syncQueue, conflictHistory,
+ * etc.) are automatically merged into every schema version declaration.
  *
  * Recovery strategy:
  *   If the database fails to open (e.g., blocked by another tab, corrupted
@@ -44,6 +39,21 @@ export interface DatabaseConfig {
     /** Ordered list of version declarations (each adds or modifies tables). */
     versions: DatabaseVersionConfig[];
 }
+/**
+ * Dexie indexes automatically appended to every app table when using the
+ * schema-driven API (`initEngine({ schema: {...} })`).
+ *
+ * These correspond to the system columns that every synced table has:
+ * - `id`         — UUID primary key
+ * - `user_id`    — ownership filter for RLS
+ * - `created_at` — creation timestamp
+ * - `updated_at` — last modification timestamp (sync cursor)
+ * - `deleted`    — soft-delete flag
+ * - `_version`   — optimistic concurrency version counter
+ *
+ * @see {@link config.ts#generateDatabaseFromSchema} for usage
+ */
+export declare const SYSTEM_INDEXES = "id, user_id, created_at, updated_at, deleted, _version";
 /**
  * Create a Dexie database with system tables auto-merged into every version.
  *
@@ -71,15 +81,55 @@ export declare function createDatabase(config: DatabaseConfig, crdtEnabled?: boo
  */
 export declare function getDb(): Dexie;
 /**
- * Register a consumer-provided Dexie instance as the managed database.
+ * Result of schema version computation.
  *
- * Used in backward-compatibility mode when the consumer creates their own
- * Dexie instance and passes it via `initEngine({ db: myDexie })`.
+ * Contains the resolved version number plus the previous stores schema
+ * (if any) so that the caller can declare both versions and give Dexie
+ * a proper upgrade path.
+ */
+export interface SchemaVersionResult {
+    /** The resolved Dexie version number (positive integer, starts at 1). */
+    version: number;
+    /**
+     * The previous version's store schema, or `null` if this is the first
+     * run or no change was detected. When non-null, the caller should declare
+     * **both** `previousStores` at `version - 1` and the current stores at
+     * `version` so Dexie can perform a non-destructive upgrade.
+     */
+    previousStores: Record<string, string> | null;
+    /** The previous version number, or `null` if no upgrade is needed. */
+    previousVersion: number | null;
+}
+/**
+ * Compute a stable Dexie version number from a merged store schema.
+ *
+ * Uses a localStorage-backed hash comparison to detect schema changes:
+ *   1. Compute a deterministic hash of the stringified stores object.
+ *   2. Compare to the previously stored hash in localStorage.
+ *   3. If changed → increment the stored version, persist both hash and
+ *      previous stores schema, and return the upgrade info.
+ *   4. If unchanged → return the stored version.
+ *   5. If first run → return version 1.
+ *
+ * When a schema change is detected, the previous stores schema is returned
+ * so that the caller can declare both versions. This gives Dexie a proper
+ * upgrade path (version N → version N+1) instead of requiring a full
+ * database rebuild.
+ *
+ * @param prefix - Application prefix for namespacing localStorage keys.
+ * @param mergedStores - The complete Dexie store schema (app + system tables).
+ * @returns Version info including previous stores for upgrade path.
+ *
+ * @example
+ * const result = computeSchemaVersion('stellar', {
+ *   goals: 'id, user_id, goal_list_id, order',
+ * });
+ * // First run:  { version: 1, previousStores: null, previousVersion: null }
+ * // On change:  { version: 2, previousStores: { goals: '...' }, previousVersion: 1 }
  *
- * @param db - The consumer-created Dexie instance.
- * @internal
+ * @see {@link config.ts#generateDatabaseFromSchema} for the caller
  */
-export declare function _setManagedDb(db: Dexie): void;
+export declare function computeSchemaVersion(prefix: string, mergedStores: Record<string, string>): SchemaVersionResult;
 /**
  * Delete the IndexedDB database entirely and clear associated state.
  *

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAoDD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAsDhG;AAoCD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAK7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE7C;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyB5D"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,2DAA2D,CAAC;AAoDvF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAsDhG;AAoCD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAO7B;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,sEAAsE;IACtE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,mBAAmB,CA+CrB;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyB5D"}