@vibesdotdev/storage 0.0.1

package/dist/record/base.js

@@ -0,0 +1,1437 @@
+/**
+ * StorageRecord Base Implementation
+ *
+ * Provides CRUD operations on a single table with relations.
+ * This is what gets resolved when you query for a storage/record descriptor.
+ *
+ * @example
+ * ```typescript
+ * const todos = new StorageRecord(todoDescriptor, adapter);
+ * await todos.initialize();
+ *
+ * const todo = await todos.create({
+ *   sessionId: 'session-123',
+ *   title: 'Implement storage',
+ *   status: 'in_progress'
+ * });
+ * ```
+ */
+import { getLogger } from '@vibesdotdev/logging';
+import { toErrorContext } from '../utils/error-context';
+const logger = getLogger('storage:record');
+import { resolveHomePath, resolveScopePathTemplate, resolveWorkspacePath } from '../paths';
+import { getVibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import { createTracer } from '@vibesdotdev/runtime/debug';
+function resolveTimestampField(timestamps, field) {
+    return typeof timestamps === 'object' && typeof timestamps?.[field] === 'string'
+        ? timestamps[field]
+        : field;
+}
+export function applyCreateTimestamps(record, timestamps, now) {
+    if (!timestamps) {
+        return;
+    }
+    const createdAtField = resolveTimestampField(timestamps, 'createdAt');
+    const updatedAtField = resolveTimestampField(timestamps, 'updatedAt');
+    if (!record[createdAtField]) {
+        record[createdAtField] = now;
+    }
+    if (!record[updatedAtField]) {
+        record[updatedAtField] = now;
+    }
+}
+export function applyUpdateTimestamp(record, update, timestamps, now) {
+    if (!timestamps) {
+        return;
+    }
+    const updatedAtField = resolveTimestampField(timestamps, 'updatedAt');
+    if (!(updatedAtField in update)) {
+        record[updatedAtField] = now;
+    }
+}
+/**
+ * StorageRecord Implementation
+ *
+ * Implements StorageRecordInterface for single-table CRUD operations.
+ * Works with SQLite via the localdb adapter.
+ *
+ * Uses runtime query API to resolve the appropriate adapter based on
+ * the descriptor's allowedAdapters and defaultAdapter settings.
+ */
+export class StorageRecord {
+    tableName;
+    primaryKey;
+    schema;
+    relations;
+    descriptor;
+    context;
+    adapterCache = null;
+    db = null;
+    initialized = false;
+    asMutableRecord(record) {
+        return record;
+    }
+    readStringField(record, field) {
+        const value = this.asMutableRecord(record)[field];
+        return typeof value === 'string' ? value : null;
+    }
+    readPrimaryKey(record) {
+        const id = this.readStringField(record, this.primaryKey);
+        if (!id) {
+            throw new Error(`Record in ${this.tableName} is missing primary key '${this.primaryKey}'`);
+        }
+        return id;
+    }
+    /**
+     * Emit a lifecycle event via the runtime HookBus.
+     * Fire-and-forget: never blocks CRUD, silently catches errors.
+     */
+    emitLifecycle(phase, record) {
+        try {
+            const runtime = getVibesRuntime();
+            const id = record[this.primaryKey];
+            runtime.hooks('storage/record').emit(phase, {
+                recordId: id,
+                recordKind: this.descriptor.id,
+                tableName: this.tableName,
+                data: record
+            });
+        }
+        catch {
+            // Runtime may not be bootstrapped in tests — never block CRUD
+        }
+    }
+    constructor(descriptor, context) {
+        this.descriptor = descriptor;
+        this.context = context;
+        this.tableName = descriptor.tableName;
+        this.primaryKey = descriptor.primaryKey || 'id';
+        this.schema = descriptor.schema;
+        this.relations = descriptor.relations || {};
+    }
+    /**
+     * Resolve the adapter for this record using runtime query API.
+     *
+     * Uses the record's allowed adapters list and current scope to
+     * select the best available adapter.
+     */
+    async getAdapter() {
+        if (this.adapterCache) {
+            return this.adapterCache;
+        }
+        const adapterTracer = createTracer(`adapter:${this.descriptor.id}`);
+        adapterTracer.start();
+        const runtime = getVibesRuntime();
+        let adapter = null;
+        let adapterId = '';
+        if (this.descriptor.defaultAdapter &&
+            this.descriptor.allowedAdapters.includes(this.descriptor.defaultAdapter)) {
+            adapterId = this.descriptor.defaultAdapter;
+            adapter = await runtime
+                .query('storage/adapter')
+                .withId(adapterId)
+                .enabled()
+                .resolve()
+                .catch(() => null);
+        }
+        if (!adapter) {
+            for (const allowedId of this.descriptor.allowedAdapters) {
+                adapter = await runtime
+                    .query('storage/adapter')
+                    .withId(allowedId)
+                    .enabled()
+                    .resolve()
+                    .catch(() => null);
+                if (adapter) {
+                    adapterId = allowedId;
+                    break;
+                }
+            }
+        }
+        if (!adapter || !adapterId) {
+            throw new Error(`No available adapter for record '${this.descriptor.id}'. Checked: ${this.descriptor.allowedAdapters.join(', ')}`);
+        }
+        if (!adapter.isConfigured()) {
+            const config = this.getAdapterConfig(adapterId);
+            adapter.configure(config);
+        }
+        this.adapterCache = adapter;
+        adapterTracer.end('resolved');
+        return adapter;
+    }
+    /**
+     * Get adapter configuration based on record scope.
+     */
+    getAdapterConfig(adapterId) {
+        const workspacePath = resolveWorkspacePath(this.context);
+        const config = {
+            basePath: this.getBasePath(workspacePath),
+            workspacePath
+        };
+        if (this.descriptor.adapterConfig) {
+            const selectedAdapterId = adapterId || this.descriptor.defaultAdapter || this.descriptor.allowedAdapters[0];
+            const adapterSpecificConfig = this.descriptor.adapterConfig[selectedAdapterId];
+            if (adapterSpecificConfig && typeof adapterSpecificConfig === 'object') {
+                Object.assign(config, adapterSpecificConfig);
+            }
+        }
+        return config;
+    }
+    /**
+     * Get base path for storage based on scope.
+     *
+     * Scope mapping:
+     * - global:  ~/.vibes/          (user-level, shared across projects)
+     * - project: ./.vibes/          (project-level, within .vibes dir)
+     * - local:   ./.vibes/          (alias for project)
+     * - auto:    ./.vibes/          (defaults to project scope)
+     */
+    getBasePath(workspacePath = resolveWorkspacePath(this.context)) {
+        const scope = this.descriptor.scope || 'project';
+        const homePath = resolveHomePath();
+        const descriptorWithScopePaths = this.descriptor;
+        if (descriptorWithScopePaths.scopePaths) {
+            const customPath = descriptorWithScopePaths.scopePaths[scope];
+            if (customPath) {
+                return resolveScopePathTemplate(customPath, workspacePath);
+            }
+        }
+        switch (scope) {
+            case 'global':
+                return `${homePath}/.vibes`;
+            case 'local':
+            case 'project':
+            case 'auto':
+            default:
+                return `${workspacePath}/.vibes`;
+        }
+    }
+    /**
+     * Initialize the storage record
+     * - Creates table if it doesn't exist
+     * - Runs migrations
+     * - Creates indexes
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Get database connection from adapter
+        this.db = await this.getDatabase();
+        // Create table if using inline migrations
+        if (this.descriptor.migrations && this.descriptor.migrations.length > 0) {
+            await this.runMigrations();
+            // Inline migrations may create normalized column schemas.
+            // StorageRecord CRUD operations expect a `data` TEXT column for JSON storage.
+            // If the migrated table lacks a `data` column and is empty, recreate it
+            // with the minimal (primaryKey, data) schema that StorageRecord requires.
+            await this.ensureDataColumn();
+        }
+        else if (this.descriptor.migrationKey) {
+            // Migrations should be pre-registered by the module
+            // The adapter will handle them
+        }
+        else {
+            // Auto-create table based on schema
+            await this.createTableFromSchema();
+        }
+        // Create indexes
+        if (this.descriptor.indexes && this.descriptor.indexes.length > 0) {
+            await this.createIndexes();
+        }
+        this.initialized = true;
+    }
+    /**
+     * Ensure the table has a `data` TEXT column required by StorageRecord CRUD operations.
+     *
+     * Inline migrations may create normalized column schemas that don't include a `data`
+     * column. StorageRecord's create/get/list/update/delete all use json_extract(data, ...)
+     * and INSERT INTO ... (primaryKey, data). If the table is empty and lacks `data`,
+     * it is safe to drop and recreate with the minimal (primaryKey, data) schema.
+     */
+    async ensureDataColumn() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const cols = this.db.query(`PRAGMA table_info(${this.tableName})`).all();
+        if (cols.some((c) => c.name === 'data'))
+            return;
+        // Table lacks a data column. Only recreate if it is empty (no data to lose).
+        const row = this.db
+            .query(`SELECT COUNT(*) as n FROM ${this.tableName}`)
+            .get();
+        if (!row || row.n > 0) {
+            logger.warn(`[StorageRecord] Table '${this.tableName}' has no 'data' column and contains rows. ` +
+                `CRUD operations may fail. Consider adding a migration to add a 'data TEXT' column.`);
+            return;
+        }
+        // Safe to recreate: drop and replace with minimal schema
+        this.db.exec(`DROP TABLE IF EXISTS ${this.tableName}`);
+        this.db.exec(`CREATE TABLE ${this.tableName} (${this.primaryKey} TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+    }
+    /**
+     * Get database connection from adapter.
+     * Uses the typed ensureReady() / getDatabaseConnection() interface.
+     */
+    async getDatabase() {
+        const adapter = await this.getAdapter();
+        await adapter.ensureReady();
+        const db = adapter.getDatabaseConnection();
+        if (!db) {
+            throw new Error(`Adapter '${adapter.id}' returned null from getDatabaseConnection() for record '${this.descriptor.id}'`);
+        }
+        return db;
+    }
+    /**
+     * Create table from schema definition
+     */
+    async createTableFromSchema() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        // Build column definitions from schema
+        const columns = this.buildColumnDefinitions();
+        const columnDefs = Object.entries(columns)
+            .map(([name, def]) => `${name} ${def}`)
+            .join(',\n  ');
+        const sql = `
+			CREATE TABLE IF NOT EXISTS ${this.tableName} (
+				${columnDefs}
+			)
+		`;
+        this.db.exec(sql);
+    }
+    /**
+     * Build column definitions from schema and descriptor
+     */
+    buildColumnDefinitions() {
+        const columns = {};
+        // Primary key
+        const pkType = this.descriptor.fieldConfig?.[this.primaryKey]?.type || 'TEXT';
+        columns[this.primaryKey] = `${pkType} PRIMARY KEY`;
+        // Auto-managed fields
+        if (this.descriptor.timestamps) {
+            const createdAt = typeof this.descriptor.timestamps === 'object'
+                ? this.descriptor.timestamps.createdAt
+                : 'createdAt';
+            const updatedAt = typeof this.descriptor.timestamps === 'object'
+                ? this.descriptor.timestamps.updatedAt
+                : 'updatedAt';
+            if (createdAt) {
+                const createdAtField = typeof createdAt === 'string' ? createdAt : 'createdAt';
+                columns[createdAtField] = 'TEXT DEFAULT CURRENT_TIMESTAMP';
+            }
+            if (updatedAt) {
+                const updatedAtField = typeof updatedAt === 'string' ? updatedAt : 'updatedAt';
+                columns[updatedAtField] = 'TEXT DEFAULT CURRENT_TIMESTAMP';
+            }
+        }
+        if (this.descriptor.softDelete) {
+            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+            columns[deletedAtField] = 'TEXT';
+        }
+        // Schema introspection is not yet wired; all non-meta fields live in a JSON `data` blob.
+        columns['data'] = 'TEXT';
+        return columns;
+    }
+    /**
+     * Create indexes from descriptor
+     */
+    async createIndexes() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        // Detect whether the table uses JSON blob storage (has a 'data' column).
+        // ensureDataColumn() may have recreated the table as (primaryKey, data TEXT),
+        // so direct column references from the descriptor won't exist. Use json_extract
+        // expressions instead so indexes still function and unique constraints are enforced.
+        const tableInfo = this.db
+            .query(`PRAGMA table_info(${this.tableName})`)
+            .all();
+        const hasDataColumn = tableInfo.some((c) => c.name === 'data');
+        const toSnakeCase = (value) => value
+            .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+            .replace(/-/g, '_')
+            .toLowerCase();
+        const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        for (const index of this.descriptor.indexes || []) {
+            const indexName = index.name || `idx_${this.tableName}_${index.fields.join('_')}`;
+            const unique = index.unique ? 'UNIQUE' : '';
+            let fieldExpr;
+            let whereExpr = '';
+            if (hasDataColumn) {
+                // JSON blob mode: reference fields via json_extract so indexes work
+                fieldExpr = index.fields.map((f) => `json_extract(data, '$.${f}')`).join(', ');
+                if (index.where) {
+                    // Replace field name references in the WHERE clause with json_extract.
+                    // Some descriptors still use snake_case predicates (legacy migration SQL style).
+                    let w = index.where;
+                    for (const f of index.fields) {
+                        // Dedupe aliases so identical camel/snake names don't double-replace,
+                        // which would corrupt an already-substituted json_extract expression.
+                        const aliases = [...new Set([f, toSnakeCase(f)])];
+                        for (const alias of aliases) {
+                            w = w.replace(new RegExp(`\\b${escapeRegExp(alias)}\\b`, 'g'), `json_extract(data, '$.${f}')`);
+                        }
+                    }
+                    whereExpr = `WHERE ${w}`;
+                }
+            }
+            else {
+                // Normalized column mode: use direct column references
+                fieldExpr = index.fields.join(', ');
+                whereExpr = index.where ? `WHERE ${index.where}` : '';
+            }
+            const sql = `CREATE ${unique} INDEX IF NOT EXISTS ${indexName} ON ${this.tableName} (${fieldExpr}) ${whereExpr}`;
+            try {
+                this.db.query(sql).run();
+            }
+            catch (error) {
+                if (index.unique) {
+                    // Unique index failures must be fatal — they protect data integrity
+                    throw error;
+                }
+                // Non-unique index creation can fail if descriptor field names don't match
+                // actual column names (e.g. camelCase vs snake_case mismatch). Log and continue.
+                logger.warn(`[StorageRecord] Skipping index '${indexName}' on '${this.tableName}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    /**
+     * Execute one or more SQL statements, splitting on `;` and running each
+     * via the prepared-statement path so bun:sqlite does not misinterpret `$`
+     * tokens inside string literals (e.g. json_extract paths).
+     */
+    execStatements(sql) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        for (const stmt of sql.split(';').map((s) => s.trim()).filter(Boolean)) {
+            this.db.query(stmt).run();
+        }
+    }
+    /**
+     * Run migrations from descriptor
+     */
+    async runMigrations() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const migrations = this.descriptor.migrations || [];
+        // Create migrations tracking table if not exists
+        this.db.exec(`
+			CREATE TABLE IF NOT EXISTS _migrations_${this.tableName} (
+				version INTEGER PRIMARY KEY,
+				name TEXT,
+				applied_at TEXT DEFAULT CURRENT_TIMESTAMP
+			)
+		`);
+        // Get applied migrations
+        const applied = this.db
+            .query(`SELECT version FROM _migrations_${this.tableName}`)
+            .all()
+            .map((r) => r.version);
+        // Run pending migrations
+        for (const migration of migrations) {
+            if (applied.includes(migration.version))
+                continue;
+            try {
+                if (typeof migration.up === 'string') {
+                    this.execStatements(migration.up);
+                }
+                else if (typeof migration.up === 'function') {
+                    await migration.up(this.db);
+                }
+                // Record migration
+                this.db
+                    .query(`INSERT INTO _migrations_${this.tableName} (version, name) VALUES (?, ?)`)
+                    .run(migration.version, migration.name || '');
+                logger.debug(`[StorageRecord] Applied migration ${migration.version} for ${this.tableName}`);
+            }
+            catch (error) {
+                // A "no such table" failure typically means the consumer is
+                // querying before its initial seed has run (e.g. `knowledge
+                // status` before any knowledge base exists). The application
+                // layer catches the throw and renders empty state; demote the
+                // log so the spurious noise doesn't reach the user. Real
+                // migration failures still surface at warn level + the throw.
+                const message = error instanceof Error ? error.message : String(error);
+                const isTableMissing = /no such table/i.test(message);
+                if (isTableMissing) {
+                    logger.debug(`[StorageRecord] Migration ${migration.version} skipped for ${this.tableName} (table not yet initialized)`);
+                }
+                else {
+                    logger.error(`[StorageRecord] Migration ${migration.version} failed for ${this.tableName}:`, toErrorContext(error));
+                }
+                throw error;
+            }
+        }
+    }
+    // CREATE
+    async create(data) {
+        await this.ensureInitialized();
+        // Prepare record
+        const record = { ...data };
+        // Auto-generate ID (must happen before validation so the schema check passes)
+        if (this.descriptor.autoId) {
+            const idField = typeof this.descriptor.autoId === 'object' && this.descriptor.autoId.field
+                ? this.descriptor.autoId.field
+                : this.primaryKey;
+            if (!record[idField]) {
+                record[idField] = this.generateId();
+            }
+        }
+        // Auto-manage timestamps (before validation so timestamps are present)
+        if (this.descriptor.timestamps) {
+            const now = new Date().toISOString();
+            applyCreateTimestamps(record, this.descriptor.timestamps, now);
+        }
+        // Execute beforeCreate hook (may set additional required fields)
+        if (this.descriptor.beforeCreate) {
+            await this.descriptor.beforeCreate(record);
+        }
+        // Validate after all auto-fields are populated
+        if (this.descriptor.validateOnWrite !== false) {
+            const validation = await this.validate(record);
+            if (!validation.success) {
+                throw new Error(`Validation failed: ${validation.errors?.message}`);
+            }
+        }
+        // Insert into database
+        const id = record[this.primaryKey];
+        const dataJson = JSON.stringify(record);
+        this.db.query(`INSERT INTO ${this.tableName} (${this.primaryKey}, data) VALUES (?, ?)`).run(id, dataJson);
+        // Execute afterCreate hook
+        if (this.descriptor.afterCreate) {
+            await this.descriptor.afterCreate(record);
+        }
+        this.emitLifecycle('afterCreate', record);
+        return record;
+    }
+    async createMany(data, options) {
+        const results = [];
+        const batchSize = options?.batchSize || 100;
+        for (let i = 0; i < data.length; i += batchSize) {
+            const batch = data.slice(i, i + batchSize);
+            const created = await Promise.all(batch.map((item) => this.create(item)));
+            results.push(...created);
+        }
+        return results;
+    }
+    // READ
+    async get(id, options) {
+        await this.ensureInitialized();
+        const row = this.db.query(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+        if (!row)
+            return null;
+        const record = JSON.parse(row.data);
+        // Load relations if requested
+        if (options?.include) {
+            await this.loadRelations(record, options.include);
+        }
+        // Validate on read if configured
+        if (this.descriptor.validateOnRead) {
+            const validation = await this.validate(record);
+            if (!validation.success) {
+                logger.warn(`[StorageRecord] Validation failed on read:`, toErrorContext(validation.errors));
+            }
+        }
+        return record;
+    }
+    async getOrThrow(id, options) {
+        const record = await this.get(id, options);
+        if (!record) {
+            throw new Error(`Record with ${this.primaryKey}=${id} not found in ${this.tableName}`);
+        }
+        return record;
+    }
+    async getMany(ids, options) {
+        await this.ensureInitialized();
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db.query(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} IN (${placeholders})`).all(...ids);
+        let records = rows.map((row) => JSON.parse(row.data));
+        // Load relations if requested
+        if (options?.include) {
+            records = await Promise.all(records.map((record) => this.loadRelations(record, options.include)));
+        }
+        return records;
+    }
+    async list(options) {
+        await this.ensureInitialized();
+        // Build query
+        let sql = `SELECT data FROM ${this.tableName}`;
+        const params = [];
+        // WHERE clause
+        let hasWhereConditions = false;
+        if (options?.where) {
+            const { clause, values } = this.buildWhereClause(options.where);
+            if (clause) {
+                sql += ` WHERE ${clause}`;
+                params.push(...values);
+                hasWhereConditions = true;
+            }
+        }
+        // Soft delete filter
+        if (this.descriptor.softDelete && !options?.includeDeleted) {
+            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+            sql += hasWhereConditions ? ` AND ` : ` WHERE `;
+            sql += `json_extract(data, '$.${deletedAtField}') IS NULL`;
+        }
+        // ORDER BY
+        if (options?.orderBy) {
+            sql += ` ORDER BY ${this.buildOrderBy(options.orderBy)}`;
+        }
+        // COUNT query for total
+        const countSql = sql.replace('SELECT data', 'SELECT COUNT(*) as count');
+        const countRow = this.db.query(countSql).get(...params);
+        const total = countRow?.count || 0;
+        // LIMIT and OFFSET
+        if (options?.limit) {
+            sql += ` LIMIT ?`;
+            params.push(options.limit);
+        }
+        if (options?.offset) {
+            sql += ` OFFSET ?`;
+            params.push(options.offset);
+        }
+        // Execute query
+        const rows = this.db.query(sql).all(...params);
+        let items = rows.map((row) => JSON.parse(row.data));
+        // Load relations if requested
+        if (options?.include) {
+            items = await Promise.all(items.map((item) => this.loadRelations(item, options.include)));
+        }
+        return {
+            items,
+            total,
+            hasMore: options?.limit ? items.length === options.limit : false
+        };
+    }
+    async findFirst(options) {
+        const result = await this.list({ ...options, limit: 1 });
+        return result.items[0] || null;
+    }
+    async findFirstOrThrow(options) {
+        const record = await this.findFirst(options);
+        if (!record) {
+            throw new Error(`No record found in ${this.tableName} matching criteria`);
+        }
+        return record;
+    }
+    async exists(id) {
+        await this.ensureInitialized();
+        const row = this.db.query(`SELECT COUNT(*) as count FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+        return (row?.count || 0) > 0;
+    }
+    async count(where) {
+        await this.ensureInitialized();
+        let sql = `SELECT COUNT(*) as count FROM ${this.tableName}`;
+        const params = [];
+        let hasWhereConditions = false;
+        if (where) {
+            const { clause, values } = this.buildWhereClause(where);
+            if (clause) {
+                sql += ` WHERE ${clause}`;
+                params.push(...values);
+                hasWhereConditions = true;
+            }
+        }
+        // Soft delete filter
+        if (this.descriptor.softDelete) {
+            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+            sql += hasWhereConditions ? ` AND ` : ` WHERE `;
+            sql += `json_extract(data, '$.${deletedAtField}') IS NULL`;
+        }
+        const row = this.db.query(sql).get(...params);
+        return row?.count || 0;
+    }
+    // UPDATE
+    async update(id, data, _options) {
+        await this.ensureInitialized();
+        // Get existing record
+        const existing = await this.get(id);
+        if (!existing) {
+            throw new Error(`Record with ${this.primaryKey}=${id} not found in ${this.tableName}`);
+        }
+        // Merge updates
+        const updated = { ...existing, ...data };
+        // Auto-manage timestamps
+        if (this.descriptor.timestamps) {
+            applyUpdateTimestamp(updated, data, this.descriptor.timestamps, new Date().toISOString());
+        }
+        // Validate
+        if (this.descriptor.validateOnWrite !== false) {
+            const validation = await this.validate(updated);
+            if (!validation.success) {
+                throw new Error(`Validation failed: ${validation.errors?.message}`);
+            }
+        }
+        // Execute beforeUpdate hook
+        if (this.descriptor.beforeUpdate) {
+            await this.descriptor.beforeUpdate(updated);
+        }
+        // Update in database
+        const dataJson = JSON.stringify(updated);
+        this.db.query(`UPDATE ${this.tableName} SET data = ? WHERE ${this.primaryKey} = ?`).run(dataJson, id);
+        // Execute afterUpdate hook
+        if (this.descriptor.afterUpdate) {
+            await this.descriptor.afterUpdate(updated);
+        }
+        this.emitLifecycle('afterUpdate', updated);
+        return updated;
+    }
+    async updateMany(where, data, options) {
+        await this.ensureInitialized();
+        // Find matching records
+        const result = await this.list({ where, select: [this.primaryKey] });
+        const ids = result.items.map((item) => this.readPrimaryKey(item));
+        // Update each record
+        let count = 0;
+        for (const id of ids) {
+            try {
+                await this.update(id, data, options);
+                count++;
+            }
+            catch (error) {
+                logger.error(`[StorageRecord] Failed to update record ${id}:`, toErrorContext(error));
+            }
+        }
+        return { count, success: count > 0 };
+    }
+    async upsert(id, create, update) {
+        const existing = await this.get(id);
+        if (existing) {
+            return this.update(id, update);
+        }
+        else {
+            return this.create({ ...create, [this.primaryKey]: id });
+        }
+    }
+    // DELETE
+    async delete(id, options) {
+        await this.ensureInitialized();
+        // Check if exists
+        let existing = await this.get(id, { include: undefined });
+        if (!existing && this.descriptor.softDelete && options?.force) {
+            const row = this.db.query(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+            existing = row ? JSON.parse(row.data) : null;
+        }
+        if (!existing) {
+            return { count: 0, success: false };
+        }
+        // Execute beforeDelete hook
+        if (this.descriptor.beforeDelete) {
+            await this.descriptor.beforeDelete(existing);
+        }
+        // Soft delete or hard delete
+        if (this.descriptor.softDelete && !options?.force) {
+            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+            const deleted = {
+                ...existing,
+                [deletedAtField]: new Date().toISOString()
+            };
+            const dataJson = JSON.stringify(deleted);
+            this.db.query(`UPDATE ${this.tableName} SET data = ? WHERE ${this.primaryKey} = ?`).run(dataJson, id);
+        }
+        else {
+            this.db.query(`DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).run(id);
+        }
+        // Execute afterDelete hook
+        if (this.descriptor.afterDelete) {
+            await this.descriptor.afterDelete(existing);
+        }
+        this.emitLifecycle('afterDelete', existing);
+        return { count: 1, success: true };
+    }
+    async deleteMany(where, options) {
+        await this.ensureInitialized();
+        // Find matching records
+        const result = await this.list({ where, select: [this.primaryKey] });
+        const ids = result.items.map((item) => this.readPrimaryKey(item));
+        // Delete each record
+        let count = 0;
+        for (const id of ids) {
+            try {
+                const deleteResult = await this.delete(id, options);
+                count += deleteResult.count;
+            }
+            catch (error) {
+                logger.error(`[StorageRecord] Failed to delete record ${id}:`, toErrorContext(error));
+            }
+        }
+        return { count, success: count > 0 };
+    }
+    async restore(id) {
+        await this.ensureInitialized();
+        if (!this.descriptor.softDelete) {
+            throw new Error(`Soft delete is not enabled for ${this.tableName}`);
+        }
+        const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+        // Get record (including soft-deleted)
+        const row = this.db.query(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+        if (!row) {
+            throw new Error(`Record with ${this.primaryKey}=${id} not found in ${this.tableName}`);
+        }
+        const record = JSON.parse(row.data);
+        if (!record[deletedAtField]) {
+            throw new Error(`Record ${id} is not soft-deleted`);
+        }
+        // Restore by clearing deletedAt
+        delete record[deletedAtField];
+        // Update timestamp
+        if (this.descriptor.timestamps) {
+            const updatedAtField = typeof this.descriptor.timestamps === 'object' &&
+                typeof this.descriptor.timestamps.updatedAt === 'string'
+                ? this.descriptor.timestamps.updatedAt
+                : 'updatedAt';
+            record[updatedAtField] = new Date().toISOString();
+        }
+        const dataJson = JSON.stringify(record);
+        this.db.query(`UPDATE ${this.tableName} SET data = ? WHERE ${this.primaryKey} = ?`).run(dataJson, id);
+        return record;
+    }
+    // AGGREGATION
+    async aggregate(options) {
+        await this.ensureInitialized();
+        const func = options.function;
+        const field = options.field;
+        let sql = `SELECT `;
+        // Aggregation function
+        if (func === 'count' && !field) {
+            sql += `COUNT(*) as value`;
+        }
+        else if (field) {
+            const fieldName = String(field);
+            switch (func) {
+                case 'count':
+                    sql += `COUNT(${fieldName}) as value`;
+                    break;
+                case 'sum':
+                    sql += `SUM(CAST(json_extract(data, '$.${fieldName}') AS REAL)) as value`;
+                    break;
+                case 'avg':
+                    sql += `AVG(CAST(json_extract(data, '$.${fieldName}') AS REAL)) as value`;
+                    break;
+                case 'min':
+                    sql += `MIN(json_extract(data, '$.${fieldName}')) as value`;
+                    break;
+                case 'max':
+                    sql += `MAX(json_extract(data, '$.${fieldName}')) as value`;
+                    break;
+            }
+        }
+        sql += ` FROM ${this.tableName}`;
+        // WHERE clause
+        const params = [];
+        if (options.where) {
+            const { clause, values } = this.buildWhereClause(options.where);
+            if (clause) {
+                sql += ` WHERE ${clause}`;
+                params.push(...values);
+            }
+        }
+        // GROUP BY
+        if (options.groupBy) {
+            const groupByFields = Array.isArray(options.groupBy) ? options.groupBy : [options.groupBy];
+            const groupByExpr = groupByFields
+                .map((f) => `json_extract(data, '$.${String(f)}')`)
+                .join(', ');
+            sql += ` GROUP BY ${groupByExpr}`;
+        }
+        const rows = this.db.query(sql).all(...params);
+        return rows.map((row) => ({
+            value: row.value || 0
+        }));
+    }
+    // TRANSACTIONS
+    async transaction(fn) {
+        await this.ensureInitialized();
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        // Begin transaction
+        this.db.exec('BEGIN TRANSACTION');
+        const tx = {
+            id: `tx-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+            startTime: Date.now(),
+            isActive: true
+        };
+        try {
+            const result = await fn(tx);
+            // Commit transaction
+            this.db.exec('COMMIT');
+            tx.isActive = false;
+            return result;
+        }
+        catch (error) {
+            // Rollback transaction
+            this.db.exec('ROLLBACK');
+            tx.isActive = false;
+            throw error;
+        }
+    }
+    // STREAMING
+    async *stream(options) {
+        await this.ensureInitialized();
+        const batchSize = options?.batchSize || 100;
+        let offset = options?.offset || 0;
+        while (true) {
+            // StreamOptions extends QueryOptions but adds batchSize/offset; both belong on QueryOptions
+            // for the list() call below, but `batchSize` is stream-only — strip it before passing along.
+            const { batchSize: _strip, ...listOptions } = (options ?? {});
+            const result = await this.list({
+                ...listOptions,
+                limit: batchSize,
+                offset
+            });
+            if (result.items.length === 0) {
+                break;
+            }
+            for (const item of result.items) {
+                yield item;
+            }
+            offset += batchSize;
+            if (!result.hasMore) {
+                break;
+            }
+        }
+    }
+    // BATCH OPERATIONS
+    batch(operations) {
+        return this.transaction(async () => {
+            const results = [];
+            for (const op of operations) {
+                let result;
+                switch (op.type) {
+                    case 'create':
+                        result = await this.create(op.data);
+                        break;
+                    case 'update':
+                        if (!op.id)
+                            throw new Error('ID required for update');
+                        result = await this.update(op.id, op.data);
+                        break;
+                    case 'delete':
+                        if (!op.id)
+                            throw new Error('ID required for delete');
+                        result = await this.delete(op.id);
+                        break;
+                }
+                results.push(result);
+            }
+            return results;
+        });
+    }
+    // UTILITIES
+    async validate(data) {
+        try {
+            const result = this.schema.parse(data);
+            return { success: true, data: result };
+        }
+        catch (error) {
+            if (error instanceof Error && 'issues' in error) {
+                return { success: false, errors: error };
+            }
+            return { success: false, errors: undefined };
+        }
+    }
+    getAdapterId() {
+        if (this.adapterCache) {
+            return this.adapterCache.id;
+        }
+        return this.descriptor.defaultAdapter || this.descriptor.allowedAdapters[0] || '';
+    }
+    async close() {
+        // Database connection is managed by the adapter
+        this.initialized = false;
+    }
+    // PRIVATE HELPERS
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+    }
+    generateId() {
+        const strategy = typeof this.descriptor.autoId === 'object' ? this.descriptor.autoId.strategy : 'uuid';
+        if (strategy === 'uuid') {
+            return crypto.randomUUID();
+        }
+        else if (strategy === 'nanoid') {
+            // Simple nanoid implementation
+            const alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+            let id = '';
+            for (let i = 0; i < 21; i++) {
+                id += alphabet[Math.floor(Math.random() * alphabet.length)];
+            }
+            return id;
+        }
+        else if (strategy === 'custom' && typeof this.descriptor.autoId === 'object') {
+            if (this.descriptor.autoId.generator) {
+                return this.descriptor.autoId.generator();
+            }
+        }
+        return crypto.randomUUID();
+    }
+    buildWhereClause(where) {
+        const conditions = [];
+        const values = [];
+        for (const [field, condition] of Object.entries(where)) {
+            if (typeof condition === 'object' && condition !== null) {
+                // Complex condition
+                const cond = condition;
+                if ('eq' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') = ?`);
+                    values.push(cond.eq);
+                }
+                if ('ne' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') != ?`);
+                    values.push(cond.ne);
+                }
+                if ('gt' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') > ?`);
+                    values.push(cond.gt);
+                }
+                if ('gte' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') >= ?`);
+                    values.push(cond.gte);
+                }
+                if ('lt' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') < ?`);
+                    values.push(cond.lt);
+                }
+                if ('lte' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') <= ?`);
+                    values.push(cond.lte);
+                }
+                if ('in' in cond && Array.isArray(cond.in)) {
+                    const placeholders = cond.in.map(() => '?').join(', ');
+                    conditions.push(`json_extract(data, '$.${field}') IN (${placeholders})`);
+                    values.push(...cond.in);
+                }
+                if ('like' in cond) {
+                    conditions.push(`json_extract(data, '$.${field}') LIKE ?`);
+                    values.push(cond.like);
+                }
+                if ('isNull' in cond) {
+                    if (cond.isNull) {
+                        conditions.push(`json_extract(data, '$.${field}') IS NULL`);
+                    }
+                    else {
+                        conditions.push(`json_extract(data, '$.${field}') IS NOT NULL`);
+                    }
+                }
+            }
+            else {
+                // Simple equality
+                conditions.push(`json_extract(data, '$.${field}') = ?`);
+                values.push(condition);
+            }
+        }
+        return {
+            clause: conditions.join(' AND '),
+            values
+        };
+    }
+    buildOrderBy(orderBy) {
+        if (Array.isArray(orderBy)) {
+            return orderBy
+                .map((o) => `json_extract(data, '$.${String(o.field)}') ${o.direction}`)
+                .join(', ');
+        }
+        else {
+            const fields = Object.entries(orderBy).map(([field, direction]) => {
+                return `json_extract(data, '$.${field}') ${direction}`;
+            });
+            return fields.join(', ');
+        }
+    }
+    async loadRelations(record, include) {
+        if (!include || Object.keys(this.relations).length === 0) {
+            return record;
+        }
+        const relationNames = Array.isArray(include) ? include : Object.keys(include);
+        for (const relationName of relationNames) {
+            const relation = this.relations[relationName];
+            if (!relation)
+                continue;
+            const related = await this.loadRelation(record, relation);
+            this.asMutableRecord(record)[relationName] = related;
+        }
+        return record;
+    }
+    async loadRelation(record, relation) {
+        // For now, we'll implement basic relation loading
+        // This would be enhanced with proper relation resolution
+        switch (relation.type) {
+            case 'belongs_to': {
+                const foreignKey = relation.foreignKey;
+                if (!foreignKey)
+                    return null;
+                const foreignId = this.readStringField(record, foreignKey);
+                if (!foreignId)
+                    return null;
+                // Resolving belongs_to requires runtime access to the target storage; unimplemented.
+                return null;
+            }
+            case 'has_many': {
+                // Resolving has_many requires runtime access to the target storage; unimplemented.
+                return [];
+            }
+            case 'has_one': {
+                // Resolving has_one requires runtime access to the target storage; unimplemented.
+                return null;
+            }
+            case 'many_to_many': {
+                // Implement many-to-many through junction table
+                return await this.loadManyToManyRelation(record, relation);
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Load many-to-many relation through junction table
+     */
+    async loadManyToManyRelation(record, relation) {
+        if (!relation.through) {
+            logger.warn(`Many-to-many relation '${relation.as || 'unknown'}' has no 'through' property`);
+            return [];
+        }
+        try {
+            const runtime = getVibesRuntime();
+            if (!runtime) {
+                logger.warn('Runtime not available for relation loading');
+                return [];
+            }
+            // Resolve the junction table storage interface
+            const junctionStorage = await runtime
+                .query('storage/record')
+                .withId(relation.through)
+                .enabled()
+                .resolve()
+                .catch((error) => {
+                logger.warn(`Failed to resolve junction table '${relation.through}':`, toErrorContext(error));
+                return null;
+            });
+            if (!junctionStorage) {
+                return [];
+            }
+            // Resolve the target table storage interface
+            const targetStorage = await runtime
+                .query('storage/record')
+                .withId(relation.target)
+                .enabled()
+                .resolve()
+                .catch((error) => {
+                logger.warn(`Failed to resolve target table '${relation.target}':`, toErrorContext(error));
+                return null;
+            });
+            if (!targetStorage) {
+                return [];
+            }
+            // Get the primary key for this record
+            const thisPrimaryKey = this.readStringField(record, this.primaryKey);
+            if (!thisPrimaryKey) {
+                return [];
+            }
+            const junctionTable = this.quoteIdentifier(junctionStorage.tableName);
+            const thisFkColumn = await this.findJunctionForeignKeyColumn(junctionStorage, thisPrimaryKey, junctionTable);
+            if (!thisFkColumn) {
+                return [];
+            }
+            // Query junction rows by this record id
+            const junctionResults = await junctionStorage.raw(`SELECT * FROM ${junctionTable} WHERE ${this.quoteIdentifier(thisFkColumn)} = ?`, thisPrimaryKey);
+            if (junctionResults.length === 0) {
+                return [];
+            }
+            // Extract target foreign keys from junction results
+            const targetIds = this.extractJunctionTargetIds(junctionResults, thisFkColumn, targetStorage.primaryKey);
+            if (targetIds.length === 0) {
+                return [];
+            }
+            return await targetStorage.getMany(targetIds);
+        }
+        catch (error) {
+            logger.error(`Error loading many-to-many relation: ${error}`);
+            return [];
+        }
+    }
+    /**
+     * Find a junction table column that stores this record's primary key.
+     */
+    async findJunctionForeignKeyColumn(junctionStorage, recordId, quotedJunctionTable) {
+        let tableInfo;
+        try {
+            tableInfo = await junctionStorage.raw(`PRAGMA table_info(${quotedJunctionTable})`);
+        }
+        catch {
+            return null;
+        }
+        const candidateColumns = tableInfo
+            .map((column) => column.name)
+            .filter((name) => this.isLikelyIdColumn(name))
+            .filter((name) => name !== 'id' && name !== junctionStorage.primaryKey)
+            .filter((name) => name !== 'data');
+        for (const column of candidateColumns) {
+            const rows = await junctionStorage.raw(`SELECT COUNT(*) as count FROM ${quotedJunctionTable} WHERE ${this.quoteIdentifier(column)} = ?`, recordId);
+            if ((rows[0]?.count ?? 0) > 0) {
+                return column;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract target IDs from junction rows.
+     */
+    extractJunctionTargetIds(junctionRows, thisFkColumn, targetPrimaryKey) {
+        const targetIds = new Set();
+        for (const row of junctionRows) {
+            for (const [field, value] of Object.entries(row)) {
+                if (field === thisFkColumn || field === targetPrimaryKey) {
+                    continue;
+                }
+                if (!this.isLikelyIdColumn(field) || typeof value !== 'string') {
+                    continue;
+                }
+                if (value.length > 0) {
+                    targetIds.add(value);
+                }
+            }
+        }
+        return [...targetIds];
+    }
+    /**
+     * True when a field name is likely an identifier / foreign key field.
+     */
+    isLikelyIdColumn(name) {
+        const lower = name.toLowerCase();
+        return (lower === 'id' ||
+            lower === 'data' ||
+            /(^|[._])id$/i.test(name) ||
+            /_id$/.test(lower) ||
+            /Id$/.test(name));
+    }
+    /**
+     * Escape SQL identifier safely for query fragments.
+     */
+    quoteIdentifier(name) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new Error(`Invalid SQL identifier: ${name}`);
+        }
+        return `"${name}"`;
+    }
+    // FULL-TEXT SEARCH
+    async search(query, options) {
+        await this.ensureInitialized();
+        if (!this.descriptor.fts) {
+            throw new Error(`FTS is not configured for ${this.tableName}`);
+        }
+        const ftsTable = this.descriptor.fts.tableName || `${this.tableName}_fts`;
+        const ftsFields = this.descriptor.fts.fields;
+        // Split into words and AND them for multi-word queries.
+        // Each word is quoted to escape FTS5 special characters.
+        const words = query.split(/\s+/).filter((w) => w.length > 0);
+        const ftsQuery = words.length <= 1
+            ? `"${query.replace(/"/g, '""')}"`
+            : words.map((w) => `"${w.replace(/"/g, '""')}"`).join(' AND ');
+        const params = [ftsQuery];
+        let sql = `
+			SELECT
+				${this.tableName}.${this.primaryKey},
+				${this.tableName}.data,
+				${ftsTable}.rank as _rank
+			FROM ${this.tableName}
+			JOIN ${ftsTable} ON ${ftsTable}.rowid = ${this.tableName}.rowid
+			WHERE ${ftsTable} MATCH ?
+		`;
+        if (options?.where) {
+            const { clause, values } = this.buildWhereClause(options.where);
+            if (clause) {
+                sql += ` AND ${clause}`;
+                params.push(...values);
+            }
+        }
+        if (options?.orderBy) {
+            sql += ` ORDER BY ${this.buildOrderBy(options.orderBy)}`;
+        }
+        else if (options?.rankByRelevance !== false) {
+            sql += ` ORDER BY _rank`;
+        }
+        if (options?.limit) {
+            sql += ` LIMIT ?`;
+            params.push(options.limit);
+        }
+        if (options?.offset) {
+            sql += ` OFFSET ?`;
+            params.push(options.offset);
+        }
+        const rows = this.db.query(sql).all(...params);
+        const items = [];
+        const scores = [];
+        const highlights = new Map();
+        for (const row of rows) {
+            const record = JSON.parse(row.data);
+            items.push(record);
+            scores.push(row._rank);
+            if (options?.highlight) {
+                const prefix = options.highlightPrefix || '<mark>';
+                const suffix = options.highlightSuffix || '</mark>';
+                const id = this.readPrimaryKey(record);
+                const fieldHighlights = [];
+                for (const field of ftsFields) {
+                    const highlightSql = `
+						SELECT highlight(${ftsTable}, ?, ?, ?) as highlighted
+						WHERE ${ftsTable} MATCH ? AND rowid = ?
+					`;
+                    const fieldIndex = ftsFields.indexOf(field);
+                    const highlightRow = this.db.query(highlightSql).get(fieldIndex, prefix, suffix, ftsQuery, rows.indexOf(row) + 1);
+                    if (highlightRow?.highlighted) {
+                        fieldHighlights.push(highlightRow.highlighted);
+                    }
+                }
+                highlights.set(id, fieldHighlights);
+            }
+            if (options?.minScore !== undefined && row._rank < options.minScore) {
+                items.pop();
+                scores.pop();
+            }
+        }
+        return {
+            items,
+            total: items.length,
+            scores,
+            highlights: highlights.size > 0 ? highlights : undefined,
+            hasMore: options?.limit ? items.length === options.limit : false
+        };
+    }
+    // HIERARCHY
+    async getDescendants(id, options) {
+        await this.ensureInitialized();
+        if (!this.descriptor.hierarchy) {
+            throw new Error(`Hierarchy is not configured for ${this.tableName}`);
+        }
+        const parentField = this.descriptor.hierarchy.parentField;
+        const maxDepth = options?.maxDepth || 1000;
+        const includePath = options?.includePath !== false;
+        const sql = `
+			WITH RECURSIVE hierarchy AS (
+				SELECT
+					*,
+					0 as depth
+					${includePath ? `, json_array(id) as path` : ''}
+				FROM ${this.tableName}
+				WHERE ${this.primaryKey} = ?
+
+				UNION ALL
+
+				SELECT
+					t.*,
+					h.depth + 1 as depth
+					${includePath ? `, CASE WHEN h.depth = 0 THEN json_array(t.id) ELSE json_insert(h.path, '$[#]', t.id) END as path` : ''}
+				FROM ${this.tableName} t
+				INNER JOIN hierarchy h ON json_extract(t.data, '$.${parentField}') = h.${this.primaryKey}
+				WHERE h.depth < ?
+			)
+			SELECT * FROM hierarchy ORDER BY depth, ${this.primaryKey}
+		`;
+        const rows = this.db.query(sql).all(id, maxDepth);
+        const items = rows.map((row) => {
+            const record = JSON.parse(row.data);
+            record.depth = row.depth;
+            if (includePath && row.path) {
+                record.path = JSON.parse(row.path);
+            }
+            return record;
+        });
+        return {
+            items,
+            total: items.length,
+            hasMore: false
+        };
+    }
+    async getAncestors(id, _options) {
+        await this.ensureInitialized();
+        if (!this.descriptor.hierarchy) {
+            throw new Error(`Hierarchy is not configured for ${this.tableName}`);
+        }
+        const parentField = this.descriptor.hierarchy.parentField;
+        const sql = `
+			WITH RECURSIVE ancestors AS (
+				SELECT *, 0 as depth FROM ${this.tableName} WHERE ${this.primaryKey} = ?
+
+				UNION ALL
+
+				SELECT t.*, a.depth + 1 as depth
+				FROM ${this.tableName} t
+				INNER JOIN ancestors a ON json_extract(a.data, '$.${parentField}') = t.${this.primaryKey}
+			)
+			SELECT * FROM ancestors ORDER BY depth DESC
+		`;
+        const rows = this.db.query(sql).all(id);
+        return rows.map((row) => JSON.parse(row.data));
+    }
+    async getTree(options) {
+        await this.ensureInitialized();
+        if (!this.descriptor.hierarchy) {
+            throw new Error(`Hierarchy is not configured for ${this.tableName}`);
+        }
+        const parentField = this.descriptor.hierarchy.parentField;
+        const maxDepth = options?.maxDepth || 1000;
+        const whereClause = options?.where
+            ? this.buildWhereClause(options.where)
+            : { clause: `json_extract(data, '$.${parentField}') IS NULL`, values: [] };
+        const sql = `
+			WITH RECURSIVE tree AS (
+				SELECT
+					*,
+					0 as depth,
+					json_array(id) as path
+				FROM ${this.tableName}
+				WHERE ${whereClause.clause}
+
+				UNION ALL
+
+				SELECT
+					t.*,
+					tree.depth + 1 as depth,
+					json_insert(tree.path, '$[#]', t.id) as path
+				FROM ${this.tableName} t
+				INNER JOIN tree ON json_extract(t.data, '$.${parentField}') = tree.${this.primaryKey}
+				WHERE tree.depth < ?
+			)
+			SELECT * FROM tree ORDER BY depth, ${this.primaryKey}
+		`;
+        const rows = this.db.query(sql).all(...whereClause.values, maxDepth);
+        const nodeMap = new Map();
+        const rootNodes = [];
+        for (const row of rows) {
+            const record = JSON.parse(row.data);
+            const recordId = this.readPrimaryKey(record);
+            const parentId = this.readStringField(record, parentField);
+            const node = {
+                record,
+                children: [],
+                depth: row.depth,
+                path: JSON.parse(row.path)
+            };
+            nodeMap.set(recordId, node);
+            if (parentId && nodeMap.has(parentId)) {
+                nodeMap.get(parentId).children.push(node);
+            }
+            else {
+                rootNodes.push(node);
+            }
+        }
+        return rootNodes;
+    }
+    // RAW QUERIES
+    async raw(sql, ...params) {
+        await this.ensureInitialized();
+        return this.db.query(sql).all(...params);
+    }
+    async queryRaw(options) {
+        await this.ensureInitialized();
+        const rows = this.db.query(options.sql).all(...(options.params || []));
+        if (options.schema) {
+            return rows.map((row) => options.schema.parse(row));
+        }
+        return rows;
+    }
+}
+//# sourceMappingURL=base.js.map