@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/src/record/base.ts

@@ -1,1872 +0,0 @@
-/**
- * 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 type { z } from 'zod/v4';
-import type { SqlDatabaseHandle } from '../interfaces/adapter';
-import { getLogger } from '@vibesdotdev/logging';
-import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
-import { toErrorContext } from '../utils/error-context';
-
-const logger = getLogger('storage:record');
-import type { StorageRecordDescriptor, StorageRelation } from '../schemas/record';
-import type {
-	StorageRecordInterface,
-	WhereFilter,
-	OrderBy,
-	IncludeRelations,
-	QueryOptions,
-	QueryResult,
-	CreateInput,
-	CreateManyOptions,
-	UpdateInput,
-	UpdateOptions,
-	UpdateResult,
-	DeleteOptions,
-	DeleteResult,
-	TransactionContext,
-	TransactionFn,
-	AggregationFunction,
-	AggregationOptions,
-	AggregationResult,
-	StreamOptions
-} from '../interfaces/record';
-import type { StorageAdapterInterface } from '../interfaces/adapter';
-import type { StorageAdapterDescriptor } from '../schemas/adapter-descriptor';
-import { resolveHomePath, resolveScopePathTemplate, resolveWorkspacePath } from '../paths';
-import { getVibesRuntime } from '@vibesdotdev/runtime/api/runtime';
-import { createTracer } from '@vibesdotdev/runtime/debug';
-
-function resolveTimestampField(
-	timestamps: StorageRecordDescriptor['timestamps'],
-	field: 'createdAt' | 'updatedAt'
-): string {
-	return typeof timestamps === 'object' && typeof timestamps?.[field] === 'string'
-		? timestamps[field]
-		: field;
-}
-
-export function applyCreateTimestamps(
-	record: Record<string, unknown>,
-	timestamps: StorageRecordDescriptor['timestamps'],
-	now: string
-): void {
-	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: Record<string, unknown>,
-	update: Record<string, unknown>,
-	timestamps: StorageRecordDescriptor['timestamps'],
-	now: string
-): void {
-	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<T = unknown> implements StorageRecordInterface<
-	T,
-	Record<string, StorageRelation>
-> {
-	readonly tableName: string;
-	readonly primaryKey: string;
-	readonly schema: z.ZodType<T>;
-	readonly relations: Record<string, StorageRelation>;
-
-	private descriptor: StorageRecordDescriptor;
-	private context: KindContext | Record<string, unknown>;
-	private adapterCache: StorageAdapterInterface | null = null;
-	private db: SqlDatabaseHandle | null = null;
-	private initialized = false;
-
-	private asMutableRecord(record: T): Record<string, unknown> {
-		return record as Record<string, unknown>;
-	}
-
-	private readStringField(record: T, field: string): string | null {
-		const value = this.asMutableRecord(record)[field];
-		return typeof value === 'string' ? value : null;
-	}
-
-	private readPrimaryKey(record: T): string {
-		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.
-	 */
-	private emitLifecycle(phase: string, record: Record<string, unknown>): void {
-		try {
-			const runtime = getVibesRuntime();
-			const id = record[this.primaryKey] as string;
-			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: StorageRecordDescriptor, context: KindContext | Record<string, unknown>) {
-		this.descriptor = descriptor;
-		this.context = context;
-		this.tableName = descriptor.tableName;
-		this.primaryKey = descriptor.primaryKey || 'id';
-		this.schema = descriptor.schema as z.ZodType<T>;
-		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.
-	 */
-	private async getAdapter(): Promise<StorageAdapterInterface> {
-		if (this.adapterCache) {
-			return this.adapterCache;
-		}
-
-		const adapterTracer = createTracer(`adapter:${this.descriptor.id}`);
-		adapterTracer.start();
-
-		const runtime = getVibesRuntime();
-		let adapter: StorageAdapterInterface | null = null;
-		let adapterId: string = '';
-
-		if (
-			this.descriptor.defaultAdapter &&
-			this.descriptor.allowedAdapters.includes(this.descriptor.defaultAdapter)
-		) {
-			adapterId = this.descriptor.defaultAdapter;
-			adapter = await runtime
-				.query<StorageAdapterDescriptor, StorageAdapterInterface>('storage/adapter')
-				.withId(adapterId)
-				.enabled()
-				.resolve()
-				.catch(() => null);
-		}
-
-		if (!adapter) {
-			for (const allowedId of this.descriptor.allowedAdapters) {
-				adapter = await runtime
-					.query<StorageAdapterDescriptor, StorageAdapterInterface>('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.
-	 */
-	private getAdapterConfig(adapterId?: string): Record<string, unknown> {
-		const workspacePath = resolveWorkspacePath(this.context);
-		const config: Record<string, unknown> = {
-			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)
-	 */
-	private getBasePath(workspacePath = resolveWorkspacePath(this.context)): string {
-		const scope = this.descriptor.scope || 'project';
-		const homePath = resolveHomePath();
-
-		const descriptorWithScopePaths = this.descriptor as {
-			scopePaths?: Partial<Record<'global' | 'project' | 'local', string>>;
-		};
-		if (descriptorWithScopePaths.scopePaths) {
-			const customPath =
-				descriptorWithScopePaths.scopePaths[scope as 'global' | 'project' | 'local'];
-			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(): Promise<void> {
-		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.
-	 */
-	private async ensureDataColumn(): Promise<void> {
-		if (!this.db) throw new Error('Database not initialized');
-
-		const cols = this.db.query<{ name: string }, []>(`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<{ n: number }, []>(`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.
-	 */
-	private async getDatabase(): Promise<SqlDatabaseHandle> {
-		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 as SqlDatabaseHandle;
-	}
-
-	/**
-	 * Create table from schema definition
-	 */
-	private async createTableFromSchema(): Promise<void> {
-		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
-	 */
-	private buildColumnDefinitions(): Record<string, string> {
-		const columns: Record<string, string> = {};
-
-		// 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
-	 */
-	private async createIndexes(): Promise<void> {
-		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<{ name: string }, []>(`PRAGMA table_info(${this.tableName})`)
-			.all();
-		const hasDataColumn = tableInfo.some((c) => c.name === 'data');
-		const toSnakeCase = (value: string): string =>
-			value
-				.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-				.replace(/-/g, '_')
-				.toLowerCase();
-		const escapeRegExp = (value: string): string => 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: string;
-			let whereExpr = '';
-
-			if (hasDataColumn) {
-				// JSON blob mode: reference fields via json_extract so indexes work
-				fieldExpr = index.fields.map((f: string) => `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).
-	 */
-	private execStatements(sql: string): void {
-		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
-	 */
-	private async runMigrations(): Promise<void> {
-		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<{ version: number }, []>(`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: CreateInput<T>): Promise<T> {
-		await this.ensureInitialized();
-
-		// Prepare record
-		const record = { ...data } as Record<string, unknown>;
-
-		// 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 as Function)(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 as string,
-			dataJson
-		);
-
-		// Execute afterCreate hook
-		if (this.descriptor.afterCreate) {
-			await (this.descriptor.afterCreate as Function)(record);
-		}
-
-		this.emitLifecycle('afterCreate', record);
-
-		return record as T;
-	}
-
-	async createMany(data: CreateInput<T>[], options?: CreateManyOptions): Promise<T[]> {
-		const results: T[] = [];
-		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: string,
-		options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>
-	): Promise<T | null> {
-		await this.ensureInitialized();
-
-		const row = this.db!.query<{ data: string }, [string]>(
-			`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`
-		).get(id);
-
-		if (!row) return null;
-
-		const record = JSON.parse(row.data) as T;
-
-		// Load relations if requested
-		if (options?.include) {
-			await this.loadRelations(record, options.include as IncludeRelations);
-		}
-
-		// 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: string,
-		options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>
-	): Promise<T> {
-		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: string[],
-		options?: Pick<QueryOptions<T, string & keyof this['relations']>, 'include' | 'select'>
-	): Promise<T[]> {
-		await this.ensureInitialized();
-
-		if (ids.length === 0) return [];
-
-		const placeholders = ids.map(() => '?').join(', ');
-		const rows = this.db!.query<{ data: string }, string[]>(
-			`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} IN (${placeholders})`
-		).all(...ids);
-
-		let records = rows.map((row) => JSON.parse(row.data) as T);
-
-		// Load relations if requested
-		if (options?.include) {
-			records = await Promise.all(
-				records.map((record) => this.loadRelations(record, options.include as IncludeRelations))
-			);
-		}
-
-		return records;
-	}
-
-	async list(options?: QueryOptions<T, string & keyof this['relations']>): Promise<QueryResult<T>> {
-		await this.ensureInitialized();
-
-		// Build query
-		let sql = `SELECT data FROM ${this.tableName}`;
-		const params: unknown[] = [];
-
-		// 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<{ count: number }, any[]>(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<{ data: string }, any[]>(sql).all(...params);
-		let items = rows.map((row) => JSON.parse(row.data) as T);
-
-		// Load relations if requested
-		if (options?.include) {
-			items = await Promise.all(
-				items.map((item) => this.loadRelations(item, options.include as IncludeRelations))
-			);
-		}
-
-		return {
-			items,
-			total,
-			hasMore: options?.limit ? items.length === options.limit : false
-		};
-	}
-
-	async findFirst(options?: QueryOptions<T, string & keyof this['relations']>): Promise<T | null> {
-		const result = await this.list({ ...options, limit: 1 });
-		return result.items[0] || null;
-	}
-
-	async findFirstOrThrow(options?: QueryOptions<T, string & keyof this['relations']>): Promise<T> {
-		const record = await this.findFirst(options);
-		if (!record) {
-			throw new Error(`No record found in ${this.tableName} matching criteria`);
-		}
-		return record;
-	}
-
-	async exists(id: string): Promise<boolean> {
-		await this.ensureInitialized();
-
-		const row = this.db!.query<{ count: number }, [string]>(
-			`SELECT COUNT(*) as count FROM ${this.tableName} WHERE ${this.primaryKey} = ?`
-		).get(id);
-
-		return (row?.count || 0) > 0;
-	}
-
-	async count(where?: WhereFilter<T>): Promise<number> {
-		await this.ensureInitialized();
-
-		let sql = `SELECT COUNT(*) as count FROM ${this.tableName}`;
-		const params: unknown[] = [];
-		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<{ count: number }, any[]>(sql).get(...params);
-		return row?.count || 0;
-	}
-
-	// UPDATE
-
-	async update(id: string, data: UpdateInput<T>, _options?: UpdateOptions): Promise<T> {
-		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 } as Record<string, unknown>;
-
-		// Auto-manage timestamps
-		if (this.descriptor.timestamps) {
-			applyUpdateTimestamp(
-				updated,
-				data as Record<string, unknown>,
-				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 as Function)(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 as Function)(updated);
-		}
-
-		this.emitLifecycle('afterUpdate', updated);
-
-		return updated as T;
-	}
-
-	async updateMany(
-		where: WhereFilter<T>,
-		data: UpdateInput<T>,
-		options?: UpdateOptions
-	): Promise<UpdateResult> {
-		await this.ensureInitialized();
-
-		// Find matching records
-		const result = await this.list({ where, select: [this.primaryKey as keyof T] });
-		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: string, create: CreateInput<T>, update: UpdateInput<T>): Promise<T> {
-		const existing = await this.get(id);
-		if (existing) {
-			return this.update(id, update);
-		} else {
-			return this.create({ ...create, [this.primaryKey]: id } as CreateInput<T>);
-		}
-	}
-
-	// DELETE
-
-	async delete(id: string, options?: DeleteOptions): Promise<DeleteResult> {
-		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<{ data: string }, [string]>(
-				`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`
-			).get(id);
-			existing = row ? (JSON.parse(row.data) as Awaited<T>) : null;
-		}
-		if (!existing) {
-			return { count: 0, success: false };
-		}
-
-		// Execute beforeDelete hook
-		if (this.descriptor.beforeDelete) {
-			await (this.descriptor.beforeDelete as Function)(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()
-			} as Record<string, unknown>;
-
-			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 as Function)(existing);
-		}
-
-		this.emitLifecycle('afterDelete', existing as Record<string, unknown>);
-
-		return { count: 1, success: true };
-	}
-
-	async deleteMany(where: WhereFilter<T>, options?: DeleteOptions): Promise<DeleteResult> {
-		await this.ensureInitialized();
-
-		// Find matching records
-		const result = await this.list({ where, select: [this.primaryKey as keyof T] });
-		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: string): Promise<T> {
-		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<{ data: string }, [string]>(
-			`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) as Record<string, unknown>;
-
-		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 as T;
-	}
-
-	// AGGREGATION
-
-	async aggregate(
-		options: AggregationOptions<T> & { function: AggregationFunction }
-	): Promise<AggregationResult[]> {
-		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: unknown[] = [];
-		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<{ value: number }, any[]>(sql).all(...params);
-
-		return rows.map((row) => ({
-			value: row.value || 0
-		}));
-	}
-
-	// TRANSACTIONS
-
-	async transaction<U>(fn: TransactionFn<U>): Promise<U> {
-		await this.ensureInitialized();
-
-		if (!this.db) {
-			throw new Error('Database not initialized');
-		}
-
-		// Begin transaction
-		this.db.exec('BEGIN TRANSACTION');
-
-		const tx: TransactionContext = {
-			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?: StreamOptions<T>): AsyncIterable<T> {
-		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 ?? {}) as { batchSize?: number };
-			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: Array<{
-			type: 'create' | 'update' | 'delete';
-			data?: unknown;
-			id?: string;
-		}>
-	): Promise<unknown[]> {
-		return this.transaction(async () => {
-			const results: unknown[] = [];
-
-			for (const op of operations) {
-				let result: unknown;
-				switch (op.type) {
-					case 'create':
-						result = await this.create(op.data as CreateInput<T>);
-						break;
-					case 'update':
-						if (!op.id) throw new Error('ID required for update');
-						result = await this.update(op.id, op.data as UpdateInput<T>);
-						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: unknown): Promise<{ success: boolean; data?: T; errors?: z.ZodError }> {
-		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 as z.ZodError };
-			}
-			return { success: false, errors: undefined };
-		}
-	}
-
-	getAdapterId(): string {
-		if (this.adapterCache) {
-			return this.adapterCache.id;
-		}
-		return this.descriptor.defaultAdapter || this.descriptor.allowedAdapters[0] || '';
-	}
-
-	async close(): Promise<void> {
-		// Database connection is managed by the adapter
-		this.initialized = false;
-	}
-
-	// PRIVATE HELPERS
-
-	private async ensureInitialized(): Promise<void> {
-		if (!this.initialized) {
-			await this.initialize();
-		}
-	}
-
-	private generateId(): string {
-		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 as Function)();
-			}
-		}
-
-		return crypto.randomUUID();
-	}
-
-	private buildWhereClause(where: WhereFilter<T>): { clause: string; values: unknown[] } {
-		const conditions: string[] = [];
-		const values: unknown[] = [];
-
-		for (const [field, condition] of Object.entries(where)) {
-			if (typeof condition === 'object' && condition !== null) {
-				// Complex condition
-				const cond = condition as Record<string, unknown>;
-
-				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
-		};
-	}
-
-	private buildOrderBy(orderBy: OrderBy<T>): string {
-		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(', ');
-		}
-	}
-
-	private async loadRelations(record: T, include: IncludeRelations): Promise<T> {
-		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 as string];
-			if (!relation) continue;
-
-			const related = await this.loadRelation(record, relation);
-			this.asMutableRecord(record)[relationName] = related;
-		}
-
-		return record;
-	}
-
-	private async loadRelation(record: T, relation: StorageRelation): Promise<unknown> {
-		// 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
-	 */
-	private async loadManyToManyRelation(record: T, relation: StorageRelation): Promise<unknown[]> {
-		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<StorageRecordDescriptor, StorageRecordInterface<Record<string, unknown>>>(
-					'storage/record'
-				)
-				.withId(relation.through)
-				.enabled()
-				.resolve()
-				.catch((error: unknown) => {
-					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<StorageRecordDescriptor, StorageRecordInterface<Record<string, unknown>>>(
-					'storage/record'
-				)
-				.withId(relation.target)
-				.enabled()
-				.resolve()
-				.catch((error: unknown) => {
-					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<Record<string, unknown>>(
-				`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.
-	 */
-	private async findJunctionForeignKeyColumn(
-		junctionStorage: StorageRecordInterface<Record<string, unknown>>,
-		recordId: string,
-		quotedJunctionTable: string
-	): Promise<string | null> {
-		let tableInfo: Array<{ name: string }>;
-		try {
-			tableInfo = await junctionStorage.raw<{ name: string }>(
-				`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<{ count: number }>(
-				`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.
-	 */
-	private extractJunctionTargetIds(
-		junctionRows: Array<Record<string, unknown>>,
-		thisFkColumn: string,
-		targetPrimaryKey: string
-	): string[] {
-		const targetIds = new Set<string>();
-
-		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.
-	 */
-	private isLikelyIdColumn(name: string): boolean {
-		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.
-	 */
-	private quoteIdentifier(name: string): string {
-		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: string,
-		options?: import('../interfaces/record').SearchOptions<T, string & keyof this['relations']>
-	): Promise<import('../interfaces/record').SearchResult<T>> {
-		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: unknown[] = [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<{ data: string; _rank: number }, any[]>(sql).all(...params);
-
-		const items: T[] = [];
-		const scores: number[] = [];
-		const highlights = new Map<string, string[]>();
-
-		for (const row of rows) {
-			const record = JSON.parse(row.data) as T;
-			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: string[] = [];
-
-				for (const field of ftsFields) {
-					const highlightSql = `
-						SELECT highlight(${ftsTable}, ?, ?, ?) as highlighted
-						WHERE ${ftsTable} MATCH ? AND rowid = ?
-					`;
-					const fieldIndex = ftsFields.indexOf(field as string);
-					const highlightRow = this.db!.query<{ highlighted: string }, any[]>(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: string,
-		options?: import('../interfaces/record').HierarchyOptions<T, string & keyof this['relations']>
-	): Promise<import('../interfaces/record').QueryResult<T & { depth: number; path?: string[] }>> {
-		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<{ data: string; depth: number; path?: string }, [string, number]>(
-			sql
-		).all(id, maxDepth);
-
-		const items = rows.map((row) => {
-			const record = JSON.parse(row.data) as T & { depth: number; path?: string[] };
-			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: string,
-		_options?: import('../interfaces/record').QueryOptions<T, string & keyof this['relations']>
-	): Promise<T[]> {
-		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<{ data: string }, [string]>(sql).all(id);
-
-		return rows.map((row) => JSON.parse(row.data) as T);
-	}
-
-	async getTree(
-		options?: import('../interfaces/record').HierarchyOptions<T, string & keyof this['relations']>
-	): Promise<import('../interfaces/record').TreeNode<T>[]> {
-		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<{ data: string; depth: number; path: string }, any[]>(sql).all(
-			...whereClause.values,
-			maxDepth
-		);
-
-		const nodeMap = new Map<string, import('../interfaces/record').TreeNode<T>>();
-		const rootNodes: import('../interfaces/record').TreeNode<T>[] = [];
-
-		for (const row of rows) {
-			const record = JSON.parse(row.data) as T;
-			const recordId = this.readPrimaryKey(record);
-			const parentId = this.readStringField(record, parentField);
-
-			const node: import('../interfaces/record').TreeNode<T> = {
-				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<R = unknown>(sql: string, ...params: unknown[]): Promise<R[]> {
-		await this.ensureInitialized();
-		return this.db!.query<R, any[]>(sql).all(...params);
-	}
-
-	async queryRaw<R>(options: import('../interfaces/record').RawQueryOptions<R>): Promise<R[]> {
-		await this.ensureInitialized();
-
-		const rows = this.db!.query<R, any[]>(options.sql).all(...(options.params || []));
-
-		if (options.schema) {
-			return rows.map((row) => options.schema!.parse(row));
-		}
-
-		return rows;
-	}
-}