@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/dist/record/base.js

@@ -16,16 +16,248 @@
  * });
  * ```
  */
+import * as z from 'zod/v4';
+import { isRecordTableMissing } from "./failure-condition.js";
 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;
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { JsonObjectSchema, JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { toErrorContext } from "../utils/error-context.js";
+import { failureOfSync, outcomeOf } from "../utils/failure-of.js";
+import { RecordFilterOperatorSchema } from "../schemas/record/query-values.js";
+import { StorageAdapterConfigSchema } from "../schemas/adapter-config.js";
+import { ZodSchemaValueSchema } from "../schemas/zod-schema-value.js";
+import { resolveScopePathTemplate, resolveVibesBaseDir, resolveWorkspacePathWithPolicy } from "../path-policy.js";
+import { createTracer } from '@vibesdotdev/kernel/debug';
+import { getPathRoots } from '@vibesdotdev/paths';
+import { selectStorageAdapter } from "../adapters/select-adapter.js";
+import { parseAdapterInput } from "../adapters/parse-adapter-input.js";
+import { extractCloudEndpoint, registerCloudEndpointIfSupported } from "../schemas/cloud-endpoints.js";
+import { enqueueRecordDelivery } from "./delivery.js";
+import { applySetAdditions, assertArrayField, assertArrayMembers, updatePatch } from "./array-fields.js";
+import { resolveSchemaCoordination } from "./schema-coordination.client.js";
+import { loadRecordRelations } from "./relations.js";
+import { assertRecordRevisionSchema, recordIndexName, resolveTimestampField, softDeleteColumn, timestampColumn } from "./columns.js";
+import { RECORD_REVISION_COLUMN, RecordRevisionMetadataSchema, RecordRevisionQuerySchema } from "../schemas/record/revision.js";
+import { RecordAtomicMutationsSchema } from "../schemas/record/atomic.js";
+/** Whether a value is a field map: an object that is not an array (every stored row's JSON is one). */
+function isFieldMap(value) {
+    return value instanceof Object && !Array.isArray(value);
+}
+/** A record value seen as its field map: the same object, never a copy, so a hook's or loader's change lands on it. */
+const RecordFieldsViewSchema = z.custom((value) => isFieldMap(value));
+const RecordLifecycleHookSchema = z.custom((value) => value instanceof Function);
+/** An inline migration's `up` step: SQL text, or a function run against the record's database. */
+const MigrationSqlSchema = z.string();
+const MigrationFunctionSchema = z.custom((value) => value instanceof Function);
+/** A descriptor's custom id generator (`autoId.strategy: 'custom'`) and the id it produces. */
+const IdGeneratorSchema = z.custom((value) => value instanceof Function);
+const GeneratedIdSchema = z.string();
+/** A descriptor's per-scope storage path templates (`scopePaths`), when it declares them. */
+const ScopePathTemplatesSchema = z.object({ scopePaths: z.record(z.string(), z.string().optional()).optional() });
+/** What a SQL database connection must offer this record: prepared statements and statement execution. */
+const SqlHandleMethodsSchema = z.object({ prepare: z.function(), exec: z.function() });
+const SqlDatabaseHandleSchema = z.custom((value) => SqlHandleMethodsSchema.safeParse(value).success);
+const SyncTransactionMethodsSchema = z.object({ transaction: z.function(), inTransaction: z.boolean() });
+const SyncTransactionDatabaseSchema = z.custom(value => SyncTransactionMethodsSchema.safeParse(value).success);
+/** Where a record-scoped database opens: the record's resolved base path and its adapter's database file name. */
+const RecordDatabaseTargetSchema = z.object({ basePath: z.string(), dbName: z.string().optional() });
+/** The workspace a record's kind context names (`runtime/workspace-path`), when it names one. */
+const ContextWorkspacePathSchema = z.string();
+/** A hierarchy query's id path (`json_array` of the primary keys from the root). */
+const HierarchyPathSchema = z.array(z.union([z.string(), z.number()]).transform(String));
+/**
+ * A filter's fields, seen as the caller's own object (never a copy, so no own
+ * key is dropped): each field's condition, an operator object or an equality value.
+ */
+const FilterFieldsViewSchema = z.custom((value) => isFieldMap(value));
+const JsonFilterOperandSchema = z.union([JsonObjectSchema, z.array(JsonValueSchema)]);
+/**
+ * Whether a field condition is an operator object (`{ eq, in, isNull, … }`):
+ * any object, null-prototype ones included, except a Date (a Date, a function
+ * or a primitive is an equality value). The condition is read in place.
+ */
+function isOperatorObject(value) {
+    if (value === null || value === undefined || Array.isArray(value))
+        return false;
+    if (value instanceof Object)
+        return !(value instanceof Date) && !(value instanceof Function);
+    return Object.getPrototypeOf(value) === null;
+}
+const FilterOperatorsSchema = z.custom((value) => isOperatorObject(value));
+/**
+ * Whether a descriptor's schema is a zod schema. The record's row type `T` is
+ * the one its registered descriptor declares: the schema it carries produces it.
+ */
+function isRecordSchema(schema) {
+    return ZodSchemaValueSchema.safeParse(schema).success;
+}
+const connectionTransactions = new WeakMap();
+const signalConnectionStates = new WeakMap();
+function getConnectionTransactionState(db) {
+    let state = connectionTransactions.get(db);
+    if (!state) {
+        state = {
+            leased: false,
+            waiters: [],
+            framesBySignal: new Map(),
+            fallbackFrame: null,
+            savepointSeq: 0
+        };
+        connectionTransactions.set(db, state);
+    }
+    return state;
+}
+function currentInvocationSignal(runtime) {
+    let signal;
+    const failure = failureOfSync(() => {
+        signal = runtime.invocationSignal;
+    });
+    return failure ? undefined : signal;
+}
+function getActiveTransactionFrame(db, runtime) {
+    const state = connectionTransactions.get(db);
+    if (!state || !state.leased)
+        return null;
+    const signal = currentInvocationSignal(runtime);
+    if (signal !== undefined) {
+        return state.framesBySignal.get(signal) ?? null;
+    }
+    return state.fallbackFrame;
+}
+function isConnectionTransactionActive(db) {
+    const state = connectionTransactions.get(db);
+    return Boolean(state?.leased);
+}
+async function waitForConnectionLease(db, runtime) {
+    const state = connectionTransactions.get(db);
+    if (!state)
+        return;
+    while (state.leased && getActiveTransactionFrame(db, runtime) === null) {
+        await new Promise((resolve) => {
+            state.waiters.push(resolve);
+        });
+    }
+}
+async function withTransactionFrame(runtime, state, parentFrame, operation) {
+    const parentSignal = currentInvocationSignal(runtime);
+    const controller = new AbortController();
+    const runWithFrame = async (ownedSignal) => {
+        const frame = {
+            state,
+            parent: parentFrame,
+            signal: ownedSignal,
+            childLeased: false,
+            childWaiters: [],
+            onRollback: []
+        };
+        const inheritedStates = [];
+        if (ownedSignal !== undefined) {
+            state.framesBySignal.set(ownedSignal, frame);
+            const ownedSet = new Set([state]);
+            if (parentSignal !== undefined) {
+                const parentSet = signalConnectionStates.get(parentSignal);
+                if (parentSet) {
+                    for (const otherState of parentSet) {
+                        ownedSet.add(otherState);
+                        if (otherState !== state) {
+                            const otherFrame = otherState.framesBySignal.get(parentSignal);
+                            if (otherFrame) {
+                                otherState.framesBySignal.set(ownedSignal, otherFrame);
+                                inheritedStates.push(otherState);
+                            }
+                        }
+                    }
+                }
+            }
+            signalConnectionStates.set(ownedSignal, ownedSet);
+        }
+        else {
+            state.fallbackFrame = frame;
+        }
+        try {
+            return await operation(frame);
+        }
+        finally {
+            if (ownedSignal !== undefined) {
+                state.framesBySignal.delete(ownedSignal);
+                for (const otherState of inheritedStates) {
+                    otherState.framesBySignal.delete(ownedSignal);
+                }
+                signalConnectionStates.delete(ownedSignal);
+            }
+            else {
+                state.fallbackFrame = parentFrame;
+            }
+        }
+    };
+    return runtime.runInvocation(() => runWithFrame(currentInvocationSignal(runtime)), { signal: controller.signal });
+}
+function flushRollbackCallbacks(frame) {
+    for (let i = frame.onRollback.length - 1; i >= 0; i--) {
+        frame.onRollback[i]();
+    }
+}
+async function runInSavepoint(runtime, parentFrame, db, operation) {
+    while (parentFrame.childLeased) {
+        await new Promise((resolve) => {
+            parentFrame.childWaiters.push(resolve);
+        });
+    }
+    parentFrame.childLeased = true;
+    const savepoint = `vibes_tx_sp_${++parentFrame.state.savepointSeq}`;
+    try {
+        return await withTransactionFrame(runtime, parentFrame.state, parentFrame, async (childFrame) => {
+            db.exec(`SAVEPOINT ${savepoint}`);
+            try {
+                const result = await operation(childFrame);
+                db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+                parentFrame.onRollback.push(...childFrame.onRollback);
+                return result;
+            }
+            catch (error) {
+                db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+                flushRollbackCallbacks(childFrame);
+                throw error;
+            }
+        });
+    }
+    finally {
+        parentFrame.childLeased = false;
+        const waiters = parentFrame.childWaiters.splice(0);
+        for (const wake of waiters) {
+            wake();
+        }
+    }
+}
+async function withImmediateSchemaTransaction(runtime, db, operation) {
+    const state = getConnectionTransactionState(db);
+    while (state.leased) {
+        await new Promise((resolve) => {
+            state.waiters.push(resolve);
+        });
+    }
+    state.leased = true;
+    try {
+        await withTransactionFrame(runtime, state, null, async () => {
+            db.exec('BEGIN IMMEDIATE');
+            try {
+                await operation();
+                db.exec('COMMIT');
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    finally {
+        state.leased = false;
+        const waiters = state.waiters.splice(0);
+        for (const wake of waiters) {
+            wake();
+        }
+    }
 }
 export function applyCreateTimestamps(record, timestamps, now) {
     if (!timestamps) {
@@ -49,6 +281,93 @@ export function applyUpdateTimestamp(record, update, timestamps, now) {
         record[updatedAtField] = now;
     }
 }
+/**
+ * Split a multi-statement SQL string into individual statements.
+ *
+ * Unlike a naive `split(';')`, this respects:
+ *  - single/double-quoted string literals (including `''` escapes),
+ *  - line comments (--) and block comments,
+ *  - `CREATE TRIGGER ... BEGIN ... END` bodies, whose internal `;`s must not
+ *    terminate the statement (a `CASE ... END` inside the body is balanced too).
+ */
+export function splitSqlStatements(sql) {
+    const statements = [];
+    let current = '';
+    let triggerDepth = 0;
+    let i = 0;
+    const isWordChar = (c) => /[A-Za-z0-9_]/.test(c);
+    while (i < sql.length) {
+        const c = sql[i];
+        const next = sql[i + 1];
+        if (c === '-' && next === '-') {
+            const end = sql.indexOf('\n', i);
+            const stop = end === -1 ? sql.length : end + 1;
+            current += sql.slice(i, stop);
+            i = stop;
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            const stop = end === -1 ? sql.length : end + 2;
+            current += sql.slice(i, stop);
+            i = stop;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            let j = i + 1;
+            while (j < sql.length) {
+                if (sql[j] === c) {
+                    // '' inside a single-quoted literal is an escaped quote
+                    if (c === "'" && sql[j + 1] === "'") {
+                        j += 2;
+                        continue;
+                    }
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            current += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === ';') {
+            if (triggerDepth > 0) {
+                current += c;
+                i++;
+                continue;
+            }
+            if (current.trim())
+                statements.push(current.trim());
+            current = '';
+            i++;
+            continue;
+        }
+        if (isWordChar(c)) {
+            let j = i;
+            while (j < sql.length && isWordChar(sql[j]))
+                j++;
+            const word = sql.slice(i, j).toUpperCase();
+            if (triggerDepth > 0) {
+                if (word === 'CASE')
+                    triggerDepth++;
+                else if (word === 'END')
+                    triggerDepth--;
+            }
+            else if (word === 'BEGIN' && /\bCREATE\s+(TEMP(ORARY)?\s+)?TRIGGER\b/i.test(current)) {
+                triggerDepth = 1;
+            }
+            current += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        current += c;
+        i++;
+    }
+    if (current.trim())
+        statements.push(current.trim());
+    return statements;
+}
 /**
  * StorageRecord Implementation
  *
@@ -58,22 +377,188 @@ export function applyUpdateTimestamp(record, update, timestamps, now) {
  * Uses runtime query API to resolve the appropriate adapter based on
  * the descriptor's allowedAdapters and defaultAdapter settings.
  */
+/**
+ * Thrown by `update()` when an `UpdateOptions.where` precondition does not
+ * match the record's current state at write time — an optimistic-lock
+ * conflict. The precondition is enforced ATOMICALLY inside the UPDATE
+ * statement's WHERE (single SQL statement, evaluated against the live row), so
+ * this is a genuine compare-and-set with no read-check-write TOCTOU window:
+ * of two concurrent writers passing `{ where: { updatedAt: <read> } }`, the
+ * second sees 0 rows matched and gets this error instead of clobbering the
+ * first. Callers catch it to detect a concurrent write and retry.
+ *
+ * It is a `CapabilityError` (`CONFLICT`, reason `record-precondition-conflict`)
+ * named `OptimisticLockError`. Its message and details are value-free (the
+ * table only); the record id and the precondition travel on its own fields.
+ */
+export class OptimisticLockError extends CapabilityError {
+    recordId;
+    tableName;
+    where;
+    constructor(tableName, recordId, where, cause) {
+        super(`Optimistic-lock conflict updating a ${tableName} record: it no longer matches its update precondition (concurrent write).`, 'CONFLICT', { reason: 'record-precondition-conflict', retryable: true, details: { tableName }, cause });
+        this.name = 'OptimisticLockError';
+        this.tableName = tableName;
+        this.recordId = recordId;
+        this.where = where;
+    }
+}
 export class StorageRecord {
     tableName;
     primaryKey;
-    schema;
     relations;
+    supportsConditionalWrites = true;
+    get revisions() {
+        if (!this.descriptor.versioning)
+            return undefined;
+        return {
+            metadata: id => this.revisionMetadata(id),
+            list: options => this.revisionList(options),
+            readAtRevision: (id, revision) => this.readAtRevision(id, revision)
+        };
+    }
+    revisionLivePredicate() {
+        const deletedAt = this.softDeleteField();
+        if (!deletedAt)
+            return '';
+        const path = `$.${JSON.stringify(deletedAt)}`.replaceAll("'", "''");
+        return ` AND json_extract(data, '${path}') IS NULL`;
+    }
+    async revisionMetadata(id) {
+        await this.ensureInitialized();
+        const row = this.db.prepare(`SELECT CAST(${this.primaryKey} AS TEXT) AS id, ${RECORD_REVISION_COLUMN} AS revision FROM ${this.tableName} WHERE ${this.primaryKey} = ?${this.revisionLivePredicate()}`).get(id);
+        return row ? RecordRevisionMetadataSchema.parse(row) : null;
+    }
+    async readAtRevision(id, revision) {
+        await this.ensureInitialized();
+        const row = this.db.prepare(`SELECT data, ${RECORD_REVISION_COLUMN} AS revision FROM ${this.tableName} WHERE ${this.primaryKey} = ? AND ${RECORD_REVISION_COLUMN} = ?${this.revisionLivePredicate()}`).get(id, revision);
+        if (row)
+            return { status: 'read', revision: row.revision, value: this.decodeRecord(row.data) };
+        const current = await this.revisionMetadata(id);
+        return current ? { status: 'changed', revision: current.revision } : { status: 'not-found' };
+    }
+    async revisionList(options) {
+        await this.ensureInitialized();
+        const query = RecordRevisionQuerySchema.parse(options ?? {});
+        const filter = this.buildWhereClause(query.where ?? {});
+        const predicate = `${filter.clause || '1 = 1'}${this.revisionLivePredicate()}`;
+        const params = [...filter.values];
+        const projection = `CAST(${this.primaryKey} AS TEXT) AS id, ${RECORD_REVISION_COLUMN} AS revision`;
+        let sql = `SELECT ${projection} FROM ${this.tableName} WHERE ${predicate}`;
+        const order = Array.isArray(query.orderBy) ? query.orderBy : Object.entries(query.orderBy ?? {}).map(([field, direction]) => ({ field, direction }));
+        const ordering = order.map(item => `${this.filterColumn(item.field)} ${item.direction}`);
+        if (!order.some(item => item.field === this.primaryKey))
+            ordering.push(this.primaryKey);
+        sql += ` ORDER BY ${ordering.join(', ')}`;
+        if (query.limit !== undefined) {
+            sql += ' LIMIT ?';
+            params.push(query.limit + 1);
+        }
+        else if (query.offset !== undefined)
+            sql += ' LIMIT -1';
+        if (query.offset !== undefined) {
+            sql += ' OFFSET ?';
+            params.push(query.offset);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        const hasMore = query.limit !== undefined && rows.length > query.limit;
+        const items = (hasMore ? rows.slice(0, query.limit) : rows).map(row => RecordRevisionMetadataSchema.parse(row));
+        const page = { items, hasMore };
+        if (query.limit === undefined || query.includeTotal) {
+            page.total = this.db.prepare(`SELECT COUNT(*) AS count FROM ${this.tableName} WHERE ${predicate}`).get(...filter.values)?.count ?? 0;
+        }
+        return page;
+    }
     descriptor;
     context;
     adapterCache = null;
+    adapterCacheId = null;
+    adapterBasePathSemantics = 'unused';
     db = null;
     initialized = false;
-    asMutableRecord(record) {
-        return record;
+    initialization = null;
+    nativeRecords = new WeakMap();
+    /** This record's row type: a stored field map, the same object (rows are written after this record's schema accepted them). */
+    recordValueSchema = z.custom((value) => isFieldMap(value));
+    /** The runtime this record was handed; there is no ambient default. */
+    getRuntime() {
+        const runtime = this.context.runtime;
+        if (!runtime) {
+            throw new CapabilityError(`Storage record '${this.descriptor.id}' was built without a runtime.`, 'INVALID_INPUT', { reason: 'storage-runtime-missing', retryable: false });
+        }
+        return runtime;
+    }
+    /** This record's Logging: the handed runtime's, never an ambient default. */
+    get logger() {
+        return getLogger('storage:record', this.getRuntime());
+    }
+    /**
+     * This record's zod schema, as its descriptor declares it. The record's
+     * row type `T` is the one its owner declares: the schema it carries produces it.
+     */
+    get schema() {
+        const schema = this.descriptor.schema;
+        if (!isRecordSchema(schema)) {
+            throw new CapabilityError(`Storage record '${this.descriptor.id}' declares no zod schema.`, 'INVALID_INPUT', {
+                reason: 'storage-record-schema-missing',
+                retryable: false,
+                details: { recordKind: this.descriptor.id }
+            });
+        }
+        return schema;
+    }
+    /** A record value's field map: the same object, refused typed when it is not one. */
+    fieldsOf(value) {
+        const fields = parseAdapterInput(RecordFieldsViewSchema, value, {
+            message: 'A storage record value must be a field map.',
+            code: 'INVALID_INPUT',
+            reason: 'record-value-invalid',
+            details: { recordKind: this.descriptor.id }
+        });
+        if (this.descriptor.versioning && Object.hasOwn(fields, RECORD_REVISION_COLUMN))
+            throw new CapabilityError('Storage revision metadata cannot be written as record data.', 'INVALID_INPUT', {
+                reason: 'record-revision-field-reserved', retryable: false
+            });
+        return fields;
+    }
+    /** A field map as this record's row type: the same object. */
+    recordOf(fields) {
+        this.fieldsOf(fields);
+        return parseAdapterInput(this.recordValueSchema, fields, {
+            message: 'A storage record value must be a field map.',
+            code: 'INVALID_INPUT',
+            reason: 'record-value-invalid',
+            details: { recordKind: this.descriptor.id }
+        });
+    }
+    /** One stored row's JSON `data` column as its field map; a row that is not a JSON object is refused typed. */
+    decodeFields(data) {
+        return parseAdapterInput(RecordFieldsViewSchema, JSON.parse(data), {
+            message: `A stored ${this.tableName} row is not a JSON object.`,
+            code: 'INTERNAL',
+            reason: 'record-row-invalid',
+            details: { recordKind: this.descriptor.id }
+        });
+    }
+    /** One stored row's JSON `data` column as this record's row type. */
+    decodeRecord(data) {
+        return this.recordOf(this.decodeFields(data));
+    }
+    /** A hierarchy query's id path, each id as text. */
+    decodePath(path) {
+        return parseAdapterInput(HierarchyPathSchema, JSON.parse(path), {
+            message: `A ${this.tableName} hierarchy path is not a list of ids.`,
+            code: 'INTERNAL',
+            reason: 'record-hierarchy-path-invalid',
+            details: { recordKind: this.descriptor.id }
+        });
     }
     readStringField(record, field) {
-        const value = this.asMutableRecord(record)[field];
-        return typeof value === 'string' ? value : null;
+        const fields = RecordFieldsViewSchema.safeParse(record);
+        if (!fields.success)
+            return null;
+        const value = z.string().safeParse(fields.data[field]);
+        return value.success ? value.data : null;
     }
     readPrimaryKey(record) {
         const id = this.readStringField(record, this.primaryKey);
@@ -82,33 +567,196 @@ export class StorageRecord {
         }
         return id;
     }
+    /** Run one descriptor lifecycle hook, when the descriptor declares it, with the row's fields; it must be a function. */
+    async runHook(name, fields) {
+        const declared = this.descriptor[name];
+        if (!declared)
+            return;
+        const hook = parseAdapterInput(RecordLifecycleHookSchema, declared, {
+            message: `Storage record '${this.descriptor.id}' declares a ${name} hook that is not a function.`,
+            code: 'INVALID_INPUT',
+            reason: 'record-hook-invalid',
+            details: { recordKind: this.descriptor.id, hook: name }
+        });
+        await hook(fields);
+    }
     /**
-     * Emit a lifecycle event via the runtime HookBus.
-     * Fire-and-forget: never blocks CRUD, silently catches errors.
+     * Emit a lifecycle event via the handed runtime's HookBus. A failing
+     * subscriber never blocks the CRUD that already happened; it is reported.
      */
-    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
+    emitLifecycle(phase, fields) {
+        const runtime = this.getRuntime();
+        const payload = {
+            recordId: fields[this.primaryKey],
+            recordKind: this.descriptor.id,
+            tableName: this.tableName,
+            data: fields
+        };
+        void outcomeOf(() => runtime.hooks('storage/record').emit(phase, payload)).then(outcome => {
+            if (!outcome.ok)
+                this.logger.warn('storage/record lifecycle hook failed', {
+                    phase, recordKind: this.descriptor.id, error: outcome.failure
+                });
+        });
+    }
+    atomic = { commit: mutations => this.commitAtomic(mutations) };
+    /** Prepare complete row mutations, then commit without yielding to another record or reader. */
+    async commitAtomic(input) {
+        const runtime = this.getRuntime();
+        const lifecycle = runtime.lifecycle;
+        const assertLive = () => {
+            if (lifecycle.phase === 'live' && !lifecycle.signal.aborted && runtime.lifecycle === lifecycle)
+                return;
+            throw new CapabilityError('A prepared commit cannot outlive its admitted runtime.', 'CANCELLED', {
+                reason: 'runtime-disposed', retryable: false, cause: lifecycle.signal.reason
             });
-        }
-        catch {
-            // Runtime may not be bootstrapped in tests — never block CRUD
+        };
+        assertLive();
+        if (this.constructor !== StorageRecord)
+            throw new CapabilityError('A custom record cannot initiate a native prepared commit.', 'UNAVAILABLE', {
+                reason: 'record-atomic-target-unsupported', retryable: false
+            });
+        if (!this.initialized || !this.db)
+            throw new CapabilityError('Prepared commits require explicitly initialized native records.', 'UNAVAILABLE', {
+                reason: 'record-atomic-not-initialized', retryable: false
+            });
+        const db = this.db;
+        const transactionDb = parseAdapterInput(SyncTransactionDatabaseSchema, db, {
+            message: 'The selected connection has no synchronous transaction capability.', code: 'UNAVAILABLE',
+            reason: 'record-atomic-transaction-unsupported'
+        });
+        const assertNoTransaction = () => {
+            if (transactionDb.inTransaction || isConnectionTransactionActive(db)) {
+                throw new CapabilityError('A prepared commit cannot join an existing transaction.', 'CONFLICT', {
+                    reason: 'record-atomic-transaction-active', retryable: true
+                });
+            }
+        };
+        assertNoTransaction();
+        const mutations = parseAdapterInput(RecordAtomicMutationsSchema, input, {
+            message: 'Prepared record mutations are invalid.', code: 'INVALID_INPUT',
+            reason: 'record-atomic-input-invalid'
+        });
+        // Snapshot only row data, never selected record handles. The bytes and their
+        // validation/event drafts belong to this admission before preparation yields.
+        const snapshots = mutations.map(mutation => mutation.type === 'delete'
+            ? undefined : JSON.stringify(mutation.data));
+        const targets = mutations.map(mutation => {
+            const record = mutation.record;
+            if (!(record instanceof StorageRecord) || record.constructor !== StorageRecord || record.getRuntime() !== runtime) {
+                throw new CapabilityError('Prepared commits require native records from the same runtime.', 'UNAVAILABLE', {
+                    reason: 'record-atomic-target-unsupported', retryable: false
+                });
+            }
+            if (!record.initialized || !record.db)
+                throw new CapabilityError('Prepared commits require explicitly initialized native records.', 'UNAVAILABLE', {
+                    reason: 'record-atomic-not-initialized', retryable: false,
+                    details: { recordKind: record.descriptor.id }
+                });
+            if (record.db !== db)
+                throw new CapabilityError('Prepared records must share one physical connection.', 'UNAVAILABLE', {
+                    reason: 'record-atomic-connection-mismatch', retryable: false
+                });
+            const descriptor = record.descriptor;
+            const hooks = ['beforeCreate', 'afterCreate', 'beforeUpdate', 'afterUpdate', 'beforeDelete', 'afterDelete'];
+            if (descriptor.autoId || descriptor.timestamps || descriptor.versioning || descriptor.softDelete ||
+                descriptor.audit || descriptor.changeTracking || descriptor.delivery || descriptor.sideEffects || descriptor.validate !== undefined ||
+                hooks.some(hook => descriptor[hook] !== undefined)) {
+                throw new CapabilityError('This record requires behavior outside the prepared commit contract.', 'UNAVAILABLE', {
+                    reason: 'record-atomic-descriptor-unsupported', retryable: false,
+                    details: { recordKind: descriptor.id }
+                });
+            }
+            const condition = mutation.type === 'create' || !mutation.where
+                ? { clause: '', values: [] } : record.buildWhereClause(mutation.where);
+            return { record, descriptor, condition };
+        });
+        const prepared = [];
+        for (const [index, mutation] of mutations.entries()) {
+            const { record, descriptor, condition } = targets[index];
+            const serialized = snapshots[index];
+            const fields = serialized === undefined ? undefined : record.decodeFields(serialized);
+            if (fields && String(fields[record.primaryKey]) !== mutation.id) {
+                throw new CapabilityError('A prepared row must carry its exact primary key.', 'INVALID_INPUT', {
+                    reason: 'record-primary-key-immutable', retryable: false
+                });
+            }
+            if (fields && descriptor.validateOnWrite !== false) {
+                const validation = await record.validate(fields);
+                if (!validation.success)
+                    throw new CapabilityError('Prepared record validation failed.', 'INVALID_INPUT', {
+                        reason: 'record-atomic-validation-failed', retryable: false, details: { recordKind: descriptor.id }
+                    });
+            }
+            const predicate = `${record.primaryKey} = ?${condition.clause ? ` AND (${condition.clause})` : ''}`;
+            const parameters = [mutation.id, ...condition.values];
+            const sql = mutation.type === 'create'
+                ? `INSERT INTO ${record.tableName} (${record.primaryKey}, data) VALUES (?, ?)`
+                : mutation.type === 'replace'
+                    ? `UPDATE ${record.tableName} SET data = ? WHERE ${predicate}`
+                    : `DELETE FROM ${record.tableName} WHERE ${predicate} RETURNING data`;
+            const statement = db.prepare(sql);
+            prepared.push({ record, type: mutation.type, run: () => {
+                    if (mutation.type === 'delete') {
+                        const deleted = statement.get(...parameters);
+                        if (deleted)
+                            return record.decodeFields(deleted.data);
+                    }
+                    else {
+                        const result = mutation.type === 'create'
+                            ? statement.run(mutation.id, serialized) : statement.run(serialized, ...parameters);
+                        if (result.changes === 1 && serialized !== undefined)
+                            return record.decodeFields(serialized);
+                    }
+                    throw new CapabilityError('A prepared record precondition no longer holds.', 'CONFLICT', {
+                        reason: 'record-atomic-precondition-failed', retryable: false, details: { index }
+                    });
+                } });
+        }
+        assertLive();
+        assertNoTransaction();
+        const committed = transactionDb.transaction(() => prepared.map(operation => ({ ...operation, fields: operation.run() })));
+        for (const operation of committed) {
+            const phase = operation.type === 'create' ? 'afterCreate' : operation.type === 'replace' ? 'afterUpdate' : 'afterDelete';
+            operation.record.emitLifecycle(phase, operation.fields);
         }
     }
     constructor(descriptor, context) {
+        assertRecordRevisionSchema(descriptor);
         this.descriptor = descriptor;
         this.context = context;
         this.tableName = descriptor.tableName;
         this.primaryKey = descriptor.primaryKey || 'id';
-        this.schema = descriptor.schema;
         this.relations = descriptor.relations || {};
     }
+    /** Default records use the selected adapter's native record implementation. */
+    static async resolveValue(implementation) {
+        if (!(implementation instanceof StorageRecord) || implementation.constructor !== StorageRecord) {
+            return implementation;
+        }
+        return implementation.resolveNativeRecord();
+    }
+    async resolveNativeRecord() {
+        const adapter = await this.getAdapter();
+        const config = await this.getAdapterConfig(this.adapterCacheId ?? adapter.id, this.adapterBasePathSemantics);
+        // Non-filesystem adapters require no workspace; their selected owner remains
+        // the identity. Filesystem records retain the Kernel-resolved target at selection.
+        const key = this.adapterBasePathSemantics === 'filesystem'
+            ? JSON.stringify([config.basePath, config.dbName]) : '';
+        let records = this.nativeRecords.get(adapter);
+        if (!records) {
+            records = new Map();
+            this.nativeRecords.set(adapter, records);
+        }
+        const existing = records.get(key);
+        if (existing)
+            return existing;
+        const context = this.adapterBasePathSemantics === 'filesystem'
+            ? { ...this.context, 'runtime/workspace-path': config.workspacePath } : this.context;
+        const record = adapter.record(this.descriptor, context);
+        records.set(key, record);
+        return record;
+    }
     /**
      * Resolve the adapter for this record using runtime query API.
      *
@@ -117,62 +765,73 @@ export class StorageRecord {
      */
     async getAdapter() {
         if (this.adapterCache) {
+            const adapterId = this.adapterCacheId ?? this.adapterCache.id;
+            const config = await this.getAdapterConfig(adapterId, this.adapterBasePathSemantics);
+            this.adapterCache.configure(config);
             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;
-                }
+        const runtime = this.getRuntime();
+        // A default adapter that is offered but fails is an error — never a
+        // silent reroute to another allowed adapter (RC06 U6).
+        const request = {
+            ownerKind: 'record',
+            ownerId: this.descriptor.id,
+            allowedAdapters: this.descriptor.allowedAdapters
+        };
+        if (this.descriptor.defaultAdapter) {
+            request.preferred = { adapterId: this.descriptor.defaultAdapter, source: 'descriptor' };
+        }
+        const { adapter, adapterId, descriptor: adapterDescriptor } = await selectStorageAdapter(runtime, request);
+        // Storage adapters are runtime singletons, while records can target different
+        // files/scopes through descriptor adapterConfig. Re-apply this record's config
+        // before opening the connection so one record cannot inherit another's DB.
+        const basePathSemantics = adapterDescriptor.basePathSemantics ?? 'unused';
+        const config = await this.getAdapterConfig(adapterId, basePathSemantics);
+        adapter.configure(config);
+        // Register per-record cloud endpoint overrides so cloud-api uses
+        // descriptor endpoints instead of the namespace fallback.
+        if (adapterId === 'storage.cloud-api') {
+            const cloudEndpoint = extractCloudEndpoint(this.descriptor.adapterConfig);
+            if (cloudEndpoint) {
+                registerCloudEndpointIfSupported(adapter, this.descriptor.namespace ?? this.descriptor.id, cloudEndpoint);
             }
         }
-        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;
+        this.adapterCacheId = adapterId;
+        this.adapterBasePathSemantics = basePathSemantics;
         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
-        };
+    async getAdapterConfig(adapterId, basePathSemantics = this.adapterBasePathSemantics) {
+        const runtime = this.getRuntime();
+        // Every adapter call runs on this record's runtime: an adapter that
+        // resolves origins or credentials (cloud-api) uses it, never an ambient one.
+        const config = { runtime };
+        if (basePathSemantics === 'filesystem') {
+            // The storage workspace policy the manifest uses (SPEC): the record's own
+            // kind context (`runtime/workspace-path`) first, else the host's bound
+            // workspace. Only a record whose context names none asks the runtime,
+            // whose reader refuses `workspace-unbound` for an unbound host — before
+            // any path is resolved or file opened, and with no home-directory fallback.
+            const hostWorkspace = ContextWorkspacePathSchema.safeParse(this.context['runtime/workspace-path']).success
+                ? undefined
+                : await runtime.context('runtime/workspace-path');
+            const roots = getPathRoots(runtime);
+            const workspacePath = resolveWorkspacePathWithPolicy(this.context, undefined, roots, undefined, undefined, hostWorkspace);
+            config.basePath = this.getBasePath(workspacePath, roots);
+            config.workspacePath = workspacePath;
+            config.roots = roots;
+        }
         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);
+            const adapterSpecificConfig = StorageAdapterConfigSchema.safeParse(this.descriptor.adapterConfig[selectedAdapterId]);
+            if (adapterSpecificConfig.success) {
+                Object.assign(config, adapterSpecificConfig.data);
             }
         }
         return config;
@@ -181,24 +840,21 @@ export class StorageRecord {
      * Get base path for storage based on scope.
      *
      * Scope mapping:
-     * - global:  ~/.vibes/          (user-level, shared across projects)
+     * - global:  canonical Vibes home selected by runtime/environment
      * - project: ./.vibes/          (project-level, within .vibes dir)
      * - local:   ./.vibes/          (alias for project)
      * - auto:    ./.vibes/          (defaults to project scope)
      */
-    getBasePath(workspacePath = resolveWorkspacePath(this.context)) {
+    getBasePath(workspacePath, roots) {
         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);
-            }
+        const declared = ScopePathTemplatesSchema.safeParse(this.descriptor);
+        const customPath = declared.success ? declared.data.scopePaths?.[scope] : undefined;
+        if (customPath) {
+            return resolveScopePathTemplate(customPath, workspacePath, roots);
         }
         switch (scope) {
             case 'global':
-                return `${homePath}/.vibes`;
+                return resolveVibesBaseDir(roots);
             case 'local':
             case 'project':
             case 'auto':
@@ -206,6 +862,15 @@ export class StorageRecord {
                 return `${workspacePath}/.vibes`;
         }
     }
+    /** The field soft deletion stamps, or null when the record does not soft-delete. */
+    softDeleteField() {
+        return softDeleteColumn(this.descriptor.softDelete);
+    }
+    /** The descriptor's `autoId` options, when it declares them as an object. */
+    autoIdOptions() {
+        const autoId = this.descriptor.autoId;
+        return autoId === true || autoId === false ? undefined : autoId;
+    }
     /**
      * Initialize the storage record
      * - Creates table if it doesn't exist
@@ -213,30 +878,80 @@ export class StorageRecord {
      * - Creates indexes
      */
     async initialize() {
+        if (this.initialized)
+            return;
+        const runtime = this.getRuntime();
+        const db = this.db ?? (await this.getDatabase());
+        this.db = db;
+        await waitForConnectionLease(db, runtime);
+        if (this.initialized)
+            return;
+        if (this.initialization)
+            return this.initialization;
+        const initialization = this.initializeOnce();
+        this.initialization = initialization;
+        try {
+            await initialization;
+        }
+        finally {
+            if (this.initialization === initialization) {
+                this.initialization = null;
+            }
+        }
+    }
+    async initializeOnce() {
         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
+        const runtime = this.getRuntime();
+        const db = this.db ?? (await this.getDatabase());
+        this.db = db;
+        const initializeSchema = async () => {
+            // 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();
+            }
+            if (this.descriptor.versioning) {
+                const columns = this.db.prepare(`PRAGMA table_info(${this.tableName})`).all();
+                if (!columns.some(column => column.name === RECORD_REVISION_COLUMN)) {
+                    this.db.exec(`ALTER TABLE ${this.tableName} ADD COLUMN ${RECORD_REVISION_COLUMN} TEXT`);
+                }
+                this.db.exec(`UPDATE ${this.tableName} SET ${RECORD_REVISION_COLUMN} = lower(hex(randomblob(16))) WHERE ${RECORD_REVISION_COLUMN} IS NULL`);
+            }
+            // Create indexes
+            if (this.descriptor.indexes && this.descriptor.indexes.length > 0) {
+                await this.createIndexes();
+            }
+            await this.createFtsArtifacts();
+        };
+        const activeFrame = getActiveTransactionFrame(db, runtime);
+        if (activeFrame) {
+            await runInSavepoint(runtime, activeFrame, db, async (savepointFrame) => {
+                await initializeSchema();
+                savepointFrame.onRollback.push(() => {
+                    this.initialized = false;
+                });
+            });
         }
-        else {
-            // Auto-create table based on schema
-            await this.createTableFromSchema();
+        else if (this.adapterCacheId === 'storage.localdb') {
+            const coordination = await resolveSchemaCoordination(runtime);
+            await coordination.initializeSchema(db, () => withImmediateSchemaTransaction(runtime, db, initializeSchema));
         }
-        // Create indexes
-        if (this.descriptor.indexes && this.descriptor.indexes.length > 0) {
-            await this.createIndexes();
+        else {
+            await initializeSchema();
         }
         this.initialized = true;
     }
@@ -251,15 +966,15 @@ export class StorageRecord {
     async ensureDataColumn() {
         if (!this.db)
             throw new Error('Database not initialized');
-        const cols = this.db.query(`PRAGMA table_info(${this.tableName})`).all();
+        const cols = this.db.prepare(`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}`)
+            .prepare(`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. ` +
+            this.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;
         }
@@ -269,16 +984,69 @@ export class StorageRecord {
     }
     /**
      * Get database connection from adapter.
-     * Uses the typed ensureReady() / getDatabaseConnection() interface.
+     *
+     * Prefers the record-scoped connection when the adapter supports one
+     * (`getRecordDatabaseConnection`). The adapter instance is a runtime
+     * singleton shared by every record that resolves it, while `configure()`
+     * mutates that shared instance's `this.database`/`this.config` in place —
+     * two records with different descriptors (different `scope`/`dbName`)
+     * resolving concurrently can otherwise race each other's `configure()` +
+     * `ensureReady()` + `getDatabaseConnection()` sequence and hand back a
+     * connection open on the WRONG descriptor's physical database (live
+     * forensics: stray `brain_state`/`session_state` tables inside
+     * `awareness.db`, frozen partial `awareness_*` tables inside
+     * `sessions.db`).
+     *
+     * `getRecordDatabaseConnection({ basePath, dbName })` resolves from a
+     * dbPath-keyed pool instead, keyed off THIS call's own `getAdapterConfig()`
+     * output — computed purely from `this.descriptor`/`this.context` (never
+     * from the adapter's shared mutable fields) — so it never depends on that
+     * shared state surviving to the end of this call. This is the record
+     * analogue of the fix already applied to the document-store path (see the
+     * localdb adapter's `getScopedDb` for that incident writeup); it is a
+     * DIFFERENT method (not the same `getScopedDb` pool) because a record's
+     * scope→path mapping (`getBasePath()` below) is its own and does not match
+     * a manifest's scope→path mapping — reusing `getScopedDb` here would
+     * silently retarget every existing local record store (e.g.
+     * `~/.vibes/awareness.db`) to a different, empty file (verified live: for
+     * a global-scope record, `getScopedDb`'s manifest resolution lands on
+     * `resolveGlobalStorageBasePath()` — a different absolute path than this
+     * record's own configured basePath). Adapters that don't implement
+     * `getRecordDatabaseConnection` (memory, a single remote connection, etc.)
+     * fall back to the plain 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}'`);
+        if (adapter.getRecordDatabaseConnection) {
+            // Computed purely from this record's own (immutable per-instance)
+            // descriptor/context — not from the adapter's shared mutable
+            // `this.config` — so it can't be clobbered by a sibling record's
+            // concurrent configure() call.
+            const config = await this.getAdapterConfig(this.adapterCacheId ?? adapter.id, this.adapterBasePathSemantics);
+            const target = parseAdapterInput(RecordDatabaseTargetSchema, config, {
+                message: `Storage record '${this.descriptor.id}' has no database location for its adapter.`,
+                code: 'INVALID_INPUT',
+                reason: 'storage-record-database-location-invalid',
+                details: { recordKind: this.descriptor.id, adapterId: adapter.id }
+            });
+            const db = await adapter.getRecordDatabaseConnection({
+                basePath: target.basePath,
+                dbName: target.dbName,
+                runtime: this.getRuntime()
+            });
+            return this.sqlHandleOf(db, adapter.id);
         }
-        return db;
+        await adapter.ensureReady();
+        return this.sqlHandleOf(adapter.getDatabaseConnection(), adapter.id);
+    }
+    /** An adapter's database connection as a SQL handle; anything else (no connection) is refused typed. */
+    sqlHandleOf(connection, adapterId) {
+        return parseAdapterInput(SqlDatabaseHandleSchema, connection, {
+            message: `Adapter '${adapterId}' returned no SQL database connection for record '${this.descriptor.id}'.`,
+            code: 'INTERNAL',
+            reason: 'storage-record-database-unavailable',
+            details: { recordKind: this.descriptor.id, adapterId }
+        });
     }
     /**
      * Create table from schema definition
@@ -288,8 +1056,8 @@ export class StorageRecord {
             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}`)
+        const columnDefs = [...columns]
+            .map(([name, def]) => `"${name.replaceAll('"', '""')}" ${def}`)
             .join(',\n  ');
         const sql = `
 			CREATE TABLE IF NOT EXISTS ${this.tableName} (
@@ -299,36 +1067,33 @@ export class StorageRecord {
         this.db.exec(sql);
     }
     /**
-     * Build column definitions from schema and descriptor
+     * Build column definitions (name to SQL definition, in declaration order)
+     * from schema and descriptor
      */
     buildColumnDefinitions() {
-        const columns = {};
+        const columns = new Map();
         // Primary key
         const pkType = this.descriptor.fieldConfig?.[this.primaryKey]?.type || 'TEXT';
-        columns[this.primaryKey] = `${pkType} PRIMARY KEY`;
+        columns.set(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';
+            const createdAtField = timestampColumn(this.descriptor.timestamps, 'createdAt');
+            const updatedAtField = timestampColumn(this.descriptor.timestamps, 'updatedAt');
+            if (createdAtField) {
+                columns.set(createdAtField, 'TEXT DEFAULT CURRENT_TIMESTAMP');
             }
-            if (updatedAt) {
-                const updatedAtField = typeof updatedAt === 'string' ? updatedAt : 'updatedAt';
-                columns[updatedAtField] = 'TEXT DEFAULT CURRENT_TIMESTAMP';
+            if (updatedAtField) {
+                columns.set(updatedAtField, 'TEXT DEFAULT CURRENT_TIMESTAMP');
             }
         }
-        if (this.descriptor.softDelete) {
-            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
-            columns[deletedAtField] = 'TEXT';
+        const deletedAtField = this.softDeleteField();
+        if (deletedAtField) {
+            columns.set(deletedAtField, 'TEXT');
         }
         // Schema introspection is not yet wired; all non-meta fields live in a JSON `data` blob.
-        columns['data'] = 'TEXT';
+        columns.set('data', 'TEXT');
+        if (this.descriptor.versioning)
+            columns.set(RECORD_REVISION_COLUMN, 'TEXT');
         return columns;
     }
     /**
@@ -337,12 +1102,13 @@ export class StorageRecord {
     async createIndexes() {
         if (!this.db)
             throw new Error('Database not initialized');
+        const db = this.db;
         // 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})`)
+        const tableInfo = db
+            .prepare(`PRAGMA table_info(${this.tableName})`)
             .all();
         const hasDataColumn = tableInfo.some((c) => c.name === 'data');
         const toSnakeCase = (value) => value
@@ -351,13 +1117,14 @@ export class StorageRecord {
             .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 indexName = recordIndexName(this.tableName, index);
             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(', ');
+                // JSON blob mode: reference fields as queries compile them (`filterColumn`:
+                // the primary-key column, else json_extract) so an index serves its query.
+                fieldExpr = index.fields.map((f) => this.filterColumn(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).
@@ -367,7 +1134,7 @@ export class StorageRecord {
                         // 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}')`);
+                            w = w.replace(new RegExp(`\\b${escapeRegExp(alias)}\\b`, 'g'), this.filterColumn(f));
                         }
                     }
                     whereExpr = `WHERE ${w}`;
@@ -378,31 +1145,155 @@ export class StorageRecord {
                 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;
+            const indexIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/.test(indexName) ? indexName : `"${indexName.replace(/"/g, '""')}"`;
+            const sql = `CREATE ${unique} INDEX IF NOT EXISTS ${indexIdentifier} ON ${this.tableName} (${fieldExpr}) ${whereExpr}`;
+            const existing = db.prepare("SELECT sql, tbl_name FROM sqlite_master WHERE type = 'index' AND name = ?").all(indexName)[0];
+            if (existing) {
+                if (existing.tbl_name !== this.tableName || !existing.sql) {
+                    throw new CapabilityError('The declared record index belongs to another schema.', 'CONFLICT', {
+                        reason: 'record-index-owner-conflict'
+                    });
                 }
-                // 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)}`);
+                // SQLite omits IF NOT EXISTS from stored DDL. Preserve quoted values
+                // while ignoring statement whitespace, so unchanged indexes stay intact.
+                const definition = (statement) => statement
+                    .replace(/^(\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+)IF\s+NOT\s+EXISTS\s+/i, '$1')
+                    .replace(/'(?:[^']|'')*'|"(?:[^"]|"")*"|\s+/g, (token) => /^\s+$/.test(token) ? ' ' : token)
+                    .trim().replace(/;$/, '');
+                if (definition(existing.sql) === definition(sql))
+                    continue;
+                // Initialization holds BEGIN IMMEDIATE: a failed replacement rolls
+                // back the drop, preserving the previous index and unique constraint.
+                db.exec(`DROP INDEX "${indexName.replace(/"/g, '""')}"`);
+                db.prepare(sql).run();
+                continue;
+            }
+            if (index.unique) {
+                // Unique index failures must be fatal — they protect data integrity.
+                db.prepare(sql).run();
+                continue;
+            }
+            // 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.
+            const failure = failureOfSync(() => {
+                db.prepare(sql).run();
+            });
+            if (failure) {
+                this.logger.warn('[StorageRecord] Skipping a non-unique index that could not be created', {
+                    index: indexName,
+                    table: this.tableName,
+                    error: failure
+                });
             }
         }
     }
+    sqlString(value) {
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    jsonPathForField(field) {
+        return `$."${field.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    }
+    validateTokenizer(tokenizer) {
+        if (!/^[A-Za-z0-9_\s]+$/.test(tokenizer)) {
+            throw new Error(`Invalid FTS tokenizer for ${this.tableName}: ${tokenizer}`);
+        }
+        return tokenizer.trim() || 'unicode61';
+    }
+    async createFtsArtifacts() {
+        if (!this.db || !this.descriptor.fts)
+            return;
+        const fields = this.descriptor.fts.fields.map((field) => String(field));
+        if (fields.length === 0)
+            return;
+        const tableInfo = this.db
+            .prepare(`PRAGMA table_info(${this.tableName})`)
+            .all();
+        const hasDataColumn = tableInfo.some((column) => column.name === 'data');
+        const ftsRawTableName = this.descriptor.fts.tableName || `${this.tableName}_fts`;
+        const tableName = this.quoteIdentifier(this.tableName);
+        const ftsTableName = this.quoteIdentifier(ftsRawTableName);
+        const insertTriggerName = this.quoteIdentifier(`${ftsRawTableName}_ai`);
+        const deleteTriggerName = this.quoteIdentifier(`${ftsRawTableName}_ad`);
+        const updateTriggerName = this.quoteIdentifier(`${ftsRawTableName}_au`);
+        const quotedFields = fields.map((field) => this.quoteIdentifier(field));
+        const fieldList = quotedFields.join(', ');
+        const tokenizer = this.validateTokenizer(this.descriptor.fts.tokenizer || 'unicode61');
+        const valueExpression = (source, field) => {
+            if (hasDataColumn) {
+                const dataRef = source ? `${source}.data` : 'data';
+                return `json_extract(${dataRef}, ${this.sqlString(this.jsonPathForField(field))})`;
+            }
+            const tableRef = source ? `${source}.` : '';
+            return `${tableRef}${this.quoteIdentifier(field)}`;
+        };
+        const newValues = fields.map((field) => valueExpression('NEW', field)).join(', ');
+        const selectValues = fields.map((field) => valueExpression(null, field)).join(', ');
+        const triggerNames = new Set([
+            `${ftsRawTableName}_ai`,
+            `${ftsRawTableName}_ad`,
+            `${ftsRawTableName}_au`,
+            `${this.tableName}_fts_insert`,
+            `${this.tableName}_fts_delete`,
+            `${this.tableName}_fts_update`
+        ]);
+        for (const row of this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = ? AND instr(sql, ?) > 0`)
+            .all(this.tableName, ftsRawTableName)) {
+            triggerNames.add(row.name);
+        }
+        for (const triggerName of triggerNames) {
+            this.db.exec(`DROP TRIGGER IF EXISTS ${this.quoteIdentifier(triggerName)}`);
+        }
+        this.db.exec(`DROP TABLE IF EXISTS ${ftsTableName}`);
+        this.db.exec(`
+			CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTableName} USING fts5(
+				${fieldList},
+				tokenize=${this.sqlString(tokenizer)}
+			)
+		`);
+        this.execStatements(`
+			CREATE TRIGGER IF NOT EXISTS ${insertTriggerName} AFTER INSERT ON ${tableName}
+			BEGIN
+				INSERT INTO ${ftsTableName}(rowid, ${fieldList})
+				VALUES (NEW.rowid, ${newValues});
+			END
+		`);
+        this.execStatements(`
+			CREATE TRIGGER IF NOT EXISTS ${deleteTriggerName} AFTER DELETE ON ${tableName}
+			BEGIN
+				DELETE FROM ${ftsTableName} WHERE rowid = OLD.rowid;
+			END
+		`);
+        this.execStatements(`
+			CREATE TRIGGER IF NOT EXISTS ${updateTriggerName} AFTER UPDATE ON ${tableName}
+			BEGIN
+				DELETE FROM ${ftsTableName} WHERE rowid = OLD.rowid;
+				INSERT INTO ${ftsTableName}(rowid, ${fieldList})
+				VALUES (NEW.rowid, ${newValues});
+			END
+		`);
+        this.db
+            .prepare(`
+			INSERT INTO ${ftsTableName}(rowid, ${fieldList})
+			SELECT rowid, ${selectValues}
+			FROM ${tableName}
+		`)
+            .run();
+    }
     /**
      * 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).
+     *
+     * Splitting is statement-aware: `;` inside string literals, comments, or a
+     * `CREATE TRIGGER ... BEGIN ... END` body does NOT terminate a statement —
+     * a naive split truncates trigger bodies and SQLite throws "incomplete input".
      */
     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();
+        for (const stmt of splitSqlStatements(sql)) {
+            this.db.prepare(stmt).run();
         }
     }
     /**
@@ -411,9 +1302,10 @@ export class StorageRecord {
     async runMigrations() {
         if (!this.db)
             throw new Error('Database not initialized');
+        const db = this.db;
         const migrations = this.descriptor.migrations || [];
         // Create migrations tracking table if not exists
-        this.db.exec(`
+        db.exec(`
 			CREATE TABLE IF NOT EXISTS _migrations_${this.tableName} (
 				version INTEGER PRIMARY KEY,
 				name TEXT,
@@ -421,8 +1313,8 @@ export class StorageRecord {
 			)
 		`);
         // Get applied migrations
-        const applied = this.db
-            .query(`SELECT version FROM _migrations_${this.tableName}`)
+        const applied = db
+            .prepare(`SELECT version FROM _migrations_${this.tableName}`)
             .all()
             .map((r) => r.version);
         // Run pending migrations
@@ -430,17 +1322,21 @@ export class StorageRecord {
             if (applied.includes(migration.version))
                 continue;
             try {
-                if (typeof migration.up === 'string') {
-                    this.execStatements(migration.up);
+                // The `up` step: SQL text runs statement by statement; a function runs against this database.
+                const upSql = MigrationSqlSchema.safeParse(migration.up);
+                if (upSql.success) {
+                    this.execStatements(upSql.data);
                 }
-                else if (typeof migration.up === 'function') {
-                    await migration.up(this.db);
+                else {
+                    const upFunction = MigrationFunctionSchema.safeParse(migration.up);
+                    if (upFunction.success)
+                        await upFunction.data(db);
                 }
                 // Record migration
-                this.db
-                    .query(`INSERT INTO _migrations_${this.tableName} (version, name) VALUES (?, ?)`)
+                db
+                    .prepare(`INSERT INTO _migrations_${this.tableName} (version, name) VALUES (?, ?)`)
                     .run(migration.version, migration.name || '');
-                logger.debug(`[StorageRecord] Applied migration ${migration.version} for ${this.tableName}`);
+                this.logger.debug(`[StorageRecord] Applied migration ${migration.version} for ${this.tableName}`);
             }
             catch (error) {
                 // A "no such table" failure typically means the consumer is
@@ -449,13 +1345,12 @@ export class StorageRecord {
                 // 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);
+                const isTableMissing = error instanceof Error && isRecordTableMissing(error);
                 if (isTableMissing) {
-                    logger.debug(`[StorageRecord] Migration ${migration.version} skipped for ${this.tableName} (table not yet initialized)`);
+                    this.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));
+                    this.logger.error(`[StorageRecord] Migration ${migration.version} failed for ${this.tableName}:`, toErrorContext(error));
                 }
                 throw error;
             }
@@ -463,14 +1358,14 @@ export class StorageRecord {
     }
     // CREATE
     async create(data) {
+        return this.createFields(this.fieldsOf({ ...data }));
+    }
+    /** Create one row from its own (already copied) field map. */
+    async createFields(record) {
         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;
+            const idField = this.autoIdOptions()?.field || this.primaryKey;
             if (!record[idField]) {
                 record[idField] = this.generateId();
             }
@@ -481,9 +1376,8 @@ export class StorageRecord {
             applyCreateTimestamps(record, this.descriptor.timestamps, now);
         }
         // Execute beforeCreate hook (may set additional required fields)
-        if (this.descriptor.beforeCreate) {
-            await this.descriptor.beforeCreate(record);
-        }
+        await this.runHook('beforeCreate', record);
+        this.fieldsOf(record);
         // Validate after all auto-fields are populated
         if (this.descriptor.validateOnWrite !== false) {
             const validation = await this.validate(record);
@@ -494,13 +1388,52 @@ export class StorageRecord {
         // 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);
+        const db = await this.acquireConnection();
+        const inserted = this.descriptor.versioning
+            ? db.prepare(`INSERT INTO ${this.tableName} (${this.primaryKey}, data, ${RECORD_REVISION_COLUMN}) VALUES (?, ?, ?) ON CONFLICT (${this.primaryKey}) DO NOTHING`).run(id, dataJson, crypto.randomUUID())
+            : db.prepare(`INSERT INTO ${this.tableName} (${this.primaryKey}, data) VALUES (?, ?) ON CONFLICT (${this.primaryKey}) DO NOTHING`).run(id, dataJson);
+        if (inserted.changes === 0) {
+            throw new CapabilityError(`Record with duplicate ${this.primaryKey} already exists in ${this.tableName}.`, 'CONFLICT', {
+                reason: 'record-identity-conflict',
+                retryable: true,
+                details: { tableName: this.tableName, primaryKey: this.primaryKey }
+            });
         }
+        // Execute afterCreate hook
+        await this.runHook('afterCreate', record);
+        // In-process notification only (D-RC11): the hook bus dies with this
+        // runtime and never delivers across processes.
         this.emitLifecycle('afterCreate', record);
-        return record;
+        // Durable delivery the record kind declares: a Workers job keyed by this
+        // record's id, enqueued before create() returns. A gated kind is claimed
+        // by the reconcile once its gate admits the pass (one eligibility decision
+        // per pass, not per row); the row itself is the durable intent.
+        if (this.descriptor.delivery && !this.descriptor.delivery.gate) {
+            await this.enqueueDelivery(String(id));
+        }
+        return this.recordOf(record);
+    }
+    /**
+     * Enqueue this record kind's declared delivery job for one created row. The
+     * row is already persisted, so a failed enqueue does not fail the write: it
+     * is logged at error with its value-free facts, the row stays pending, and
+     * the Workers consumer enqueues it again when it starts
+     * (`requeuePendingDeliveries`).
+     */
+    async enqueueDelivery(recordId) {
+        const delivery = this.descriptor.delivery;
+        if (!delivery)
+            return;
+        const enqueued = await outcomeOf(() => enqueueRecordDelivery(this.getRuntime(), this.descriptor.id, delivery, recordId));
+        if (enqueued.ok)
+            return;
+        this.logger.error('Record delivery could not be enqueued; the record stays pending until the Workers consumer re-enqueues it', {
+            reason: 'storage-record-delivery-enqueue-failed',
+            recordKind: this.descriptor.id,
+            recordId,
+            job: delivery.job,
+            error: enqueued.failure
+        });
     }
     async createMany(data, options) {
         const results = [];
@@ -515,19 +1448,22 @@ export class StorageRecord {
     // READ
     async get(id, options) {
         await this.ensureInitialized();
-        const row = this.db.query(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+        const row = this.db.prepare(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
         if (!row)
             return null;
-        const record = JSON.parse(row.data);
+        const record = this.decodeRecord(row.data);
         // Load relations if requested
         if (options?.include) {
-            await this.loadRelations(record, options.include);
+            await loadRecordRelations(this.relationOwner, 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));
+                this.logger.warn('[StorageRecord] Validation failed on read', {
+                    recordKind: this.descriptor.id,
+                    issues: validation.errors?.issues.length ?? 0
+                });
             }
         }
         return record;
@@ -544,15 +1480,20 @@ export class StorageRecord {
         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));
+        const rows = this.db.prepare(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} IN (${placeholders})`).all(...ids);
+        let records = rows.map((row) => this.decodeRecord(row.data));
         // Load relations if requested
-        if (options?.include) {
-            records = await Promise.all(records.map((record) => this.loadRelations(record, options.include)));
+        const include = options?.include;
+        if (include) {
+            records = await Promise.all(records.map((record) => loadRecordRelations(this.relationOwner, record, include)));
         }
         return records;
     }
     async list(options) {
+        return this.listRecords(options);
+    }
+    /** `list()` over any relation names: the bulk paths (stream, updateMany, deleteMany) list through it. */
+    async listRecords(options) {
         await this.ensureInitialized();
         // Build query
         let sql = `SELECT data FROM ${this.tableName}`;
@@ -568,19 +1509,23 @@ export class StorageRecord {
             }
         }
         // Soft delete filter
-        if (this.descriptor.softDelete && !options?.includeDeleted) {
-            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+        const deletedAtField = this.softDeleteField();
+        if (deletedAtField && !options?.includeDeleted) {
             sql += hasWhereConditions ? ` AND ` : ` WHERE `;
             sql += `json_extract(data, '$.${deletedAtField}') IS NULL`;
         }
+        // A bounded page does not scan the entire match set merely to report
+        // metadata. Callers that need it explicitly request the independent count.
+        let total;
+        if (options?.limit === undefined || options.includeTotal === true) {
+            const countSql = sql.replace('SELECT data', 'SELECT COUNT(*) as count');
+            const countRow = this.db.prepare(countSql).get(...params);
+            total = countRow?.count ?? 0;
+        }
         // 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 ?`;
@@ -591,17 +1536,20 @@ export class StorageRecord {
             params.push(options.offset);
         }
         // Execute query
-        const rows = this.db.query(sql).all(...params);
-        let items = rows.map((row) => JSON.parse(row.data));
+        const rows = this.db.prepare(sql).all(...params);
+        let items = rows.map((row) => this.decodeRecord(row.data));
         // Load relations if requested
-        if (options?.include) {
-            items = await Promise.all(items.map((item) => this.loadRelations(item, options.include)));
+        const include = options?.include;
+        if (include) {
+            items = await Promise.all(items.map((item) => loadRecordRelations(this.relationOwner, item, include)));
         }
-        return {
+        const result = {
             items,
-            total,
             hasMore: options?.limit ? items.length === options.limit : false
         };
+        if (total !== undefined)
+            result.total = total;
+        return result;
     }
     async findFirst(options) {
         const result = await this.list({ ...options, limit: 1 });
@@ -616,7 +1564,7 @@ export class StorageRecord {
     }
     async exists(id) {
         await this.ensureInitialized();
-        const row = this.db.query(`SELECT COUNT(*) as count FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+        const row = this.db.prepare(`SELECT COUNT(*) as count FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
         return (row?.count || 0) > 0;
     }
     async count(where) {
@@ -633,24 +1581,46 @@ export class StorageRecord {
             }
         }
         // Soft delete filter
-        if (this.descriptor.softDelete) {
-            const deletedAtField = typeof this.descriptor.softDelete === 'string' ? this.descriptor.softDelete : 'deletedAt';
+        const deletedAtField = this.softDeleteField();
+        if (deletedAtField) {
             sql += hasWhereConditions ? ` AND ` : ` WHERE `;
             sql += `json_extract(data, '$.${deletedAtField}') IS NULL`;
         }
-        const row = this.db.query(sql).get(...params);
+        const row = this.db.prepare(sql).get(...params);
         return row?.count || 0;
     }
     // UPDATE
-    async update(id, data, _options) {
+    async update(id, data, options) {
+        return this.updateFields(id, data, options);
+    }
+    /** One update of a row's fields; a `where` precondition that no longer holds throws its OptimisticLockError. */
+    async updateFields(id, data, options) {
+        const updated = await this.updateWithConditions(id, data, options);
+        if (updated instanceof OptimisticLockError)
+            throw updated;
+        return updated;
+    }
+    /**
+     * One conditional update: the updated record, or the optimistic-lock
+     * conflict when its precondition no longer holds (the drizzle record's
+     * same contract), so a guarded bulk write skips a conflicting row without
+     * catching anything.
+     */
+    async updateWithConditions(id, data, options, bulkWhere) {
         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}`);
+            throw new CapabilityError(`Record with ${this.primaryKey}=${id} not found in ${this.tableName}`, 'NOT_FOUND', {
+                reason: 'record-absent',
+                retryable: false,
+                details: { tableName: this.tableName, id }
+            });
         }
         // Merge updates
-        const updated = { ...existing, ...data };
+        const snapshot = this.fieldsOf(structuredClone(existing));
+        const updated = this.fieldsOf({ ...existing, ...data });
+        const additions = applySetAdditions(updated, data, options);
         // Auto-manage timestamps
         if (this.descriptor.timestamps) {
             applyUpdateTimestamp(updated, data, this.descriptor.timestamps, new Date().toISOString());
@@ -663,34 +1633,105 @@ export class StorageRecord {
             }
         }
         // Execute beforeUpdate hook
-        if (this.descriptor.beforeUpdate) {
-            await this.descriptor.beforeUpdate(updated);
+        await this.runHook('beforeUpdate', updated);
+        this.fieldsOf(updated);
+        // A record's identity is its key column, and the stored JSON carries the same id; a filter
+        // on the primary key reads the column. An update (or a beforeUpdate hook) naming another
+        // primary key is refused, so the two never diverge.
+        const nextKey = updated[this.primaryKey];
+        if (nextKey !== undefined && nextKey !== null && String(nextKey) !== id) {
+            throw new CapabilityError('A record update cannot change its primary key.', 'INVALID_INPUT', {
+                reason: 'record-primary-key-immutable',
+                retryable: false,
+                details: { recordKind: this.descriptor.id, field: this.primaryKey }
+            });
         }
-        // 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);
+        // Update in database. Honor the declared `where` precondition
+        // (UpdateOptions.where — "update only if conditions match") ATOMICALLY:
+        // the precondition rides in the UPDATE's WHERE, so SQLite evaluates it
+        // against the current row at write time in a single statement. If a
+        // concurrent writer moved the row between our get() and here, 0 rows
+        // match → changes === 0 → conflict. This is a real compare-and-set, not
+        // a read-check-write (which would leave a TOCTOU window — two writers
+        // both passing an in-memory check before either writes). Single-record
+        // update() previously ignored this param entirely (silent unconditional
+        // write); the lost-update hazard it exists to prevent (TF-05) is now
+        // actually closed for every record type.
+        const patch = updatePatch(snapshot, updated, data, additions);
+        const argumentsSql = [];
+        const params = [];
+        const removals = [];
+        for (const [field, value] of Object.entries(patch)) {
+            const path = `$.${JSON.stringify(field)}`;
+            if (value === undefined) {
+                removals.push(path);
+                continue;
+            }
+            argumentsSql.push('?, json(?)');
+            params.push(path, JSON.stringify(value));
+        }
+        for (const [field, value] of Object.entries(additions)) {
+            const path = `$.${field}`;
+            argumentsSql.push(`?, json(CASE WHEN EXISTS (
+				SELECT 1 FROM json_each(COALESCE(json_extract(data, ?), '[]'))
+				WHERE type = 'text' AND value = ?
+			) THEN COALESCE(json_extract(data, ?), '[]')
+			ELSE json_insert(COALESCE(json_extract(data, ?), '[]'), '$[#]', ?) END)`);
+            params.push(path, path, value, path, path, value);
+        }
+        let expression = argumentsSql.length ? `json_set(data, ${argumentsSql.join(', ')})` : 'data';
+        if (removals.length) {
+            expression = `json_remove(${expression}, ${removals.map(() => '?').join(', ')})`;
+            params.push(...removals);
+        }
+        let revisionAssignment = '';
+        if (this.descriptor.versioning) {
+            revisionAssignment = `, ${RECORD_REVISION_COLUMN} = ?`;
+            params.push(crypto.randomUUID());
+        }
+        let sql = `UPDATE ${this.tableName} SET data = ${expression}${revisionAssignment} WHERE ${this.primaryKey} = ?`;
+        params.push(id);
+        // Build the bulk and additional preconditions independently: overlapping
+        // fields must both match the live row, never overwrite each other.
+        for (const where of [bulkWhere, options?.where]) {
+            if (!where)
+                continue;
+            const { clause, values } = this.buildWhereClause(where);
+            if (clause) {
+                sql += ` AND (${clause})`;
+                params.push(...values);
+            }
         }
-        this.emitLifecycle('afterUpdate', updated);
-        return updated;
+        const db = await this.acquireConnection();
+        const result = db.prepare(`${sql} RETURNING data`).get(...params);
+        const precondition = options?.where ?? bulkWhere;
+        if (precondition && !result) {
+            // The row exists (get() above) but the precondition no longer holds.
+            return new OptimisticLockError(this.tableName, String(id), precondition);
+        }
+        if (!result)
+            throw new Error(`Record with ${this.primaryKey}=${id} not found in ${this.tableName}`);
+        // RETURNING reads the same JSON record just patched by SQLite.
+        const persisted = this.decodeFields(result.data);
+        // Execute afterUpdate hook
+        await this.runHook('afterUpdate', persisted);
+        this.emitLifecycle('afterUpdate', persisted);
+        return this.recordOf(persisted);
     }
     async updateMany(where, data, options) {
         await this.ensureInitialized();
         // Find matching records
-        const result = await this.list({ where, select: [this.primaryKey] });
+        const result = await this.listRecords({ where });
         const ids = result.items.map((item) => this.readPrimaryKey(item));
-        // Update each record
+        // Update each record under the same filter, so a row that stopped
+        // matching between the list and its update (another writer claimed it)
+        // is skipped instead of overwritten: updateMany is a guarded write.
         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));
-            }
+            const updated = await this.updateWithConditions(id, data, options, where);
+            if (updated instanceof OptimisticLockError)
+                continue;
+            count++;
         }
         return { count, success: count > 0 };
     }
@@ -700,75 +1741,131 @@ export class StorageRecord {
             return this.update(id, update);
         }
         else {
-            return this.create({ ...create, [this.primaryKey]: id });
+            return this.createFields(this.fieldsOf({ ...create, [this.primaryKey]: id }));
         }
     }
     // DELETE
     async delete(id, options) {
+        return this.deleteWithConditions(id, options);
+    }
+    async deleteWithConditions(id, options, bulkWhere) {
         await this.ensureInitialized();
+        const predicates = [`${this.primaryKey} = ?`];
+        const values = [id];
+        for (const where of [bulkWhere, options?.where]) {
+            if (where === undefined)
+                continue;
+            const condition = this.buildDeleteWhereClause(where);
+            if (condition.clause) {
+                predicates.push(`(${condition.clause})`);
+                values.push(...condition.values);
+            }
+        }
         // Check if exists
-        let existing = await this.get(id, { include: undefined });
+        let existing = null;
+        const live = await this.get(id, { include: undefined });
+        if (live)
+            existing = this.fieldsOf(live);
         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;
+            const forceDb = await this.acquireConnection();
+            const row = forceDb.prepare(`SELECT data FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).get(id);
+            existing = row ? this.decodeFields(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);
+        await this.runHook('beforeDelete', existing);
+        // Patch only deletion fields against live JSON; a before hook may yield to a peer.
+        let sql;
+        let parameters;
+        const deletedAtField = this.softDeleteField();
+        if (deletedAtField && !options?.force) {
+            const now = new Date().toISOString();
+            const deleted = { [deletedAtField]: now };
+            applyUpdateTimestamp(deleted, {}, this.descriptor.timestamps, now);
+            const assignments = Object.entries(deleted);
+            sql = `UPDATE ${this.tableName} SET data = json_set(data, ${assignments.map(() => '?, json(?)').join(', ')})`;
+            parameters = assignments.flatMap(([field, value]) => [`$.${JSON.stringify(field)}`, JSON.stringify(value)]);
+            if (this.descriptor.versioning) {
+                sql += `, ${RECORD_REVISION_COLUMN} = ?`;
+                parameters.push(crypto.randomUUID());
+            }
         }
         else {
-            this.db.query(`DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`).run(id);
+            sql = `DELETE FROM ${this.tableName}`;
+            parameters = [];
         }
+        const db = await this.acquireConnection();
+        const result = db.prepare(`${sql} WHERE ${predicates.join(' AND ')} RETURNING data`).get(...parameters, ...values);
+        if (!result)
+            return { count: 0, success: false };
+        // RETURNING carries the same JSON row actually mutated.
+        const persisted = this.decodeFields(result.data);
         // Execute afterDelete hook
-        if (this.descriptor.afterDelete) {
-            await this.descriptor.afterDelete(existing);
-        }
-        this.emitLifecycle('afterDelete', existing);
+        await this.runHook('afterDelete', persisted);
+        this.emitLifecycle('afterDelete', persisted);
         return { count: 1, success: true };
     }
     async deleteMany(where, options) {
         await this.ensureInitialized();
+        const predicates = [];
+        const values = [];
+        for (const filter of [where, options?.where]) {
+            if (filter === undefined)
+                continue;
+            const condition = this.buildDeleteWhereClause(filter);
+            if (condition.clause) {
+                predicates.push(`(${condition.clause})`);
+                values.push(...condition.values);
+            }
+        }
+        const physicalDelete = !this.descriptor.softDelete || Boolean(options?.force);
+        // A forced delete must be able to see rows that are already soft-deleted.
+        // `list()` appends `deletedAt IS NULL` unless told otherwise, so without
+        // this a soft-deleted row can never be physically removed in bulk — soft
+        // delete becomes a one-way trip and the table grows forever. Retention
+        // that stamps at one window and reaps at a longer one depends on this.
+        const includeDeleted = Boolean(options?.force);
+        // Set-based fast path. The per-row loop below exists to run
+        // beforeDelete/afterDelete hooks and emit per-record lifecycle events; a
+        // descriptor with neither needs none of that, and paying one SELECT plus
+        // one statement per row is ruinous at scale (a real retention sweep hit
+        // ~500k rows, i.e. ~1M statements and 500k hook emissions, one
+        // transaction each). Hook-bearing descriptors keep the old semantics.
+        const hasDeleteHooks = Boolean(this.descriptor.beforeDelete || this.descriptor.afterDelete);
+        if (physicalDelete && !hasDeleteHooks) {
+            const clause = predicates.join(' AND ');
+            const sql = clause
+                ? `DELETE FROM ${this.tableName} WHERE ${clause}`
+                : `DELETE FROM ${this.tableName}`;
+            const result = this.db.prepare(sql).run(...values);
+            const count = Number(result?.changes ?? 0);
+            return { count, success: count > 0 };
+        }
         // Find matching records
-        const result = await this.list({ where, select: [this.primaryKey] });
+        const result = await this.listRecords({ where, includeDeleted });
         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));
-            }
+            const deleteResult = await this.deleteWithConditions(id, options, where);
+            count += deleteResult.count;
         }
         return { count, success: count > 0 };
     }
     async restore(id) {
         await this.ensureInitialized();
-        if (!this.descriptor.softDelete) {
+        const deletedAtField = this.softDeleteField();
+        if (!deletedAtField) {
             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);
+        const row = this.db.prepare(`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);
+        const record = this.decodeFields(row.data);
         if (!record[deletedAtField]) {
             throw new Error(`Record ${id} is not soft-deleted`);
         }
@@ -776,15 +1873,16 @@ export class StorageRecord {
         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();
+            record[resolveTimestampField(this.descriptor.timestamps, 'updatedAt')] = new Date().toISOString();
         }
         const dataJson = JSON.stringify(record);
-        this.db.query(`UPDATE ${this.tableName} SET data = ? WHERE ${this.primaryKey} = ?`).run(dataJson, id);
-        return record;
+        if (this.descriptor.versioning) {
+            this.db.prepare(`UPDATE ${this.tableName} SET data = ?, ${RECORD_REVISION_COLUMN} = ? WHERE ${this.primaryKey} = ?`).run(dataJson, crypto.randomUUID(), id);
+        }
+        else {
+            this.db.prepare(`UPDATE ${this.tableName} SET data = ? WHERE ${this.primaryKey} = ?`).run(dataJson, id);
+        }
+        return this.recordOf(record);
     }
     // AGGREGATION
     async aggregate(options) {
@@ -834,36 +1932,72 @@ export class StorageRecord {
                 .join(', ');
             sql += ` GROUP BY ${groupByExpr}`;
         }
-        const rows = this.db.query(sql).all(...params);
+        const rows = this.db.prepare(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');
+        const runtime = this.getRuntime();
+        const db = this.db ?? (await this.getDatabase());
+        this.db = db;
+        const existingFrame = getActiveTransactionFrame(db, runtime);
+        if (existingFrame) {
+            await this.ensureInitialized();
+            return runInSavepoint(runtime, existingFrame, db, async () => {
+                const tx = {
+                    id: `tx-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                    startTime: Date.now(),
+                    isActive: true
+                };
+                try {
+                    return await fn(tx);
+                }
+                finally {
+                    tx.isActive = false;
+                }
+            });
         }
-        // Begin transaction
-        this.db.exec('BEGIN TRANSACTION');
-        const tx = {
-            id: `tx-${Date.now()}-${Math.random().toString(36).slice(2)}`,
-            startTime: Date.now(),
-            isActive: true
-        };
+        const state = getConnectionTransactionState(db);
+        while (state.leased || !this.initialized) {
+            if (state.leased) {
+                await new Promise((resolve) => {
+                    state.waiters.push(resolve);
+                });
+                continue;
+            }
+            await this.initialize();
+        }
+        state.leased = true;
         try {
-            const result = await fn(tx);
-            // Commit transaction
-            this.db.exec('COMMIT');
-            tx.isActive = false;
-            return result;
+            return await withTransactionFrame(runtime, state, null, async (frame) => {
+                const tx = {
+                    id: `tx-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                    startTime: Date.now(),
+                    isActive: true
+                };
+                db.exec('BEGIN TRANSACTION');
+                try {
+                    const result = await fn(tx);
+                    db.exec('COMMIT');
+                    tx.isActive = false;
+                    return result;
+                }
+                catch (error) {
+                    db.exec('ROLLBACK');
+                    tx.isActive = false;
+                    flushRollbackCallbacks(frame);
+                    throw error;
+                }
+            });
         }
-        catch (error) {
-            // Rollback transaction
-            this.db.exec('ROLLBACK');
-            tx.isActive = false;
-            throw error;
+        finally {
+            state.leased = false;
+            const waiters = state.waiters.splice(0);
+            for (const wake of waiters) {
+                wake();
+            }
         }
     }
     // STREAMING
@@ -871,11 +2005,12 @@ export class StorageRecord {
         await this.ensureInitialized();
         const batchSize = options?.batchSize || 100;
         let offset = options?.offset || 0;
+        // StreamOptions extends QueryOptions but adds batchSize; `batchSize` is
+        // stream-only — strip it before passing the rest to list().
+        const streamOptions = options ?? {};
+        const { batchSize: _strip, ...listOptions } = streamOptions;
         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({
+            const result = await this.listRecords({
                 ...listOptions,
                 limit: batchSize,
                 offset
@@ -900,12 +2035,12 @@ export class StorageRecord {
                 let result;
                 switch (op.type) {
                     case 'create':
-                        result = await this.create(op.data);
+                        result = await this.createFields({ ...this.fieldsOf(op.data) });
                         break;
                     case 'update':
                         if (!op.id)
                             throw new Error('ID required for update');
-                        result = await this.update(op.id, op.data);
+                        result = await this.updateFields(op.id, this.fieldsOf(op.data));
                         break;
                     case 'delete':
                         if (!op.id)
@@ -920,16 +2055,12 @@ export class StorageRecord {
     }
     // 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 };
-        }
+        // A schema refusal is the validation result; any other failure while
+        // validating (a refinement that throws) is not a result and propagates.
+        const result = this.schema.safeParse(data);
+        if (result.success)
+            return { success: true, data: result.data };
+        return { success: false, errors: result.error };
     }
     getAdapterId() {
         if (this.adapterCache) {
@@ -943,12 +2074,30 @@ export class StorageRecord {
     }
     // PRIVATE HELPERS
     async ensureInitialized() {
-        if (!this.initialized) {
+        const runtime = this.getRuntime();
+        const db = this.db ?? (await this.getDatabase());
+        this.db = db;
+        const state = connectionTransactions.get(db);
+        while ((state?.leased && getActiveTransactionFrame(db, runtime) === null) || !this.initialized) {
+            if (state?.leased && getActiveTransactionFrame(db, runtime) === null) {
+                await new Promise((resolve) => {
+                    state.waiters.push(resolve);
+                });
+                continue;
+            }
             await this.initialize();
         }
     }
+    async acquireConnection() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        await waitForConnectionLease(this.db, this.getRuntime());
+        return this.db;
+    }
     generateId() {
-        const strategy = typeof this.descriptor.autoId === 'object' ? this.descriptor.autoId.strategy : 'uuid';
+        const autoId = this.autoIdOptions();
+        const strategy = autoId ? autoId.strategy : 'uuid';
         if (strategy === 'uuid') {
             return crypto.randomUUID();
         }
@@ -961,66 +2110,241 @@ export class StorageRecord {
             }
             return id;
         }
-        else if (strategy === 'custom' && typeof this.descriptor.autoId === 'object') {
-            if (this.descriptor.autoId.generator) {
-                return this.descriptor.autoId.generator();
-            }
+        else if (strategy === 'custom' && autoId?.generator) {
+            const refusal = {
+                message: `Storage record '${this.descriptor.id}' declares a custom id generator that does not produce a string id.`,
+                code: 'INVALID_INPUT',
+                reason: 'record-id-generator-invalid',
+                details: { recordKind: this.descriptor.id }
+            };
+            const generator = parseAdapterInput(IdGeneratorSchema, autoId.generator, refusal);
+            return parseAdapterInput(GeneratedIdSchema, generator(), refusal);
         }
         return crypto.randomUUID();
     }
+    buildDeleteWhereClause(where) {
+        const scalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null(), z.date()]);
+        const filter = z.record(z.string(), z.unknown()).safeParse(where);
+        if (!filter.success) {
+            throw new CapabilityError('Deletion filters must be field objects.', 'INVALID_INPUT', { reason: 'record-delete-filter-invalid', retryable: false });
+        }
+        for (const [field, condition] of Object.entries(filter.data)) {
+            const invalid = () => { throw new CapabilityError(`Invalid deletion filter for '${field}'.`, 'INVALID_INPUT', { reason: 'record-delete-filter-invalid', retryable: false }); };
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field) || field === '__proto__')
+                invalid();
+            if (scalarSchema.safeParse(condition).success)
+                continue;
+            const comparison = z.record(z.string(), z.unknown()).safeParse(condition);
+            if (!comparison.success)
+                return invalid();
+            const operators = Object.entries(comparison.data);
+            if (!operators.length)
+                invalid();
+            for (const [operator, value] of operators) {
+                if (!RecordFilterOperatorSchema.safeParse(operator).success)
+                    invalid();
+                if (operator === 'hasAll' && !z.array(z.string()).min(1).safeParse(value).success)
+                    invalid();
+                if (['eq', 'ne', 'gt', 'gte', 'lt', 'lte'].includes(operator) && !scalarSchema.safeParse(value).success)
+                    invalid();
+                if (['like', 'ilike', 'contains', 'startsWith', 'endsWith'].includes(operator) && !z.string().safeParse(value).success)
+                    invalid();
+                if ((operator === 'in' || operator === 'notIn') && !z.array(scalarSchema).safeParse(value).success)
+                    invalid();
+                if (operator === 'between' && !z.tuple([scalarSchema, scalarSchema]).safeParse(value).success)
+                    invalid();
+                if ((operator === 'isNull' || operator === 'isNotNull') && !z.boolean().safeParse(value).success)
+                    invalid();
+            }
+        }
+        return this.buildWhereClause(where);
+    }
+    encodeDateFilterOperand(value) {
+        if (!(value instanceof Date))
+            return value;
+        const date = z.date().safeParse(value);
+        if (!date.success) {
+            throw new CapabilityError('Date filter operands must be valid dates.', 'INVALID_INPUT', {
+                reason: 'record-filter-date-invalid', retryable: false
+            });
+        }
+        return date.data.toISOString();
+    }
+    /** json_extract returns object/array fields as their persisted JSON text. */
+    encodeEqualityFilterOperand(value) {
+        const structured = JsonFilterOperandSchema.safeParse(value);
+        if (structured.success)
+            return JSON.stringify(structured.data);
+        return this.encodeDateFilterOperand(value);
+    }
+    /**
+     * The SQL a filter on `field` reads. The primary key is the table's own key
+     * column, which always equals the stored record's id, so filtering on it is an
+     * index lookup; every other field is read from the stored JSON. Before this,
+     * an id filter scanned the whole table through json_extract, which made a
+     * per-row guarded update quadratic in the table size.
+     */
+    filterColumn(field) {
+        const path = `$.${field}`.replaceAll("'", "''");
+        return field === this.primaryKey ? this.primaryKey : `json_extract(data, '${path}')`;
+    }
+    /** The SQL type of `field` in the stored JSON (`NULL` when the key is absent, `'null'` when JSON `null`). */
+    filterFieldType(field) {
+        const path = `$.${field}`.replaceAll("'", "''");
+        return field === this.primaryKey ? `typeof(${this.primaryKey})` : `json_type(data, '${path}')`;
+    }
     buildWhereClause(where) {
         const conditions = [];
         const values = [];
-        for (const [field, condition] of Object.entries(where)) {
-            if (typeof condition === 'object' && condition !== null) {
+        const filter = parseAdapterInput(FilterFieldsViewSchema, where, {
+            message: 'Record filters must be field objects.',
+            code: 'INVALID_INPUT',
+            reason: 'record-filter-invalid',
+            details: { recordKind: this.descriptor.id }
+        });
+        for (const [field, condition] of Object.entries(filter)) {
+            // An operator object (`{ eq, in, … }`) is a complex condition; a Date or any other value is equality.
+            const operators = FilterOperatorsSchema.safeParse(condition);
+            if (operators.success) {
                 // Complex condition
-                const cond = condition;
+                const cond = operators.data;
+                const refuse = (check) => {
+                    throw new CapabilityError('Record filter clause cannot be enforced.', 'INVALID_INPUT', {
+                        reason: 'record-filter-invalid',
+                        retryable: false,
+                        details: { recordKind: this.descriptor.id, field, check }
+                    });
+                };
+                const operatorKeys = Object.keys(cond);
+                // An operator object with no operator constrains nothing: refused, never read as "every row".
+                if (!operatorKeys.length)
+                    refuse('empty-comparison');
+                for (const operator of operatorKeys) {
+                    if (!RecordFilterOperatorSchema.safeParse(operator).success)
+                        refuse('unknown-operator');
+                }
+                if ('in' in cond && !Array.isArray(cond.in))
+                    refuse('array-operand-required');
+                if ('notIn' in cond && !Array.isArray(cond.notIn))
+                    refuse('array-operand-required');
+                if ('between' in cond && !(Array.isArray(cond.between) && cond.between.length === 2))
+                    refuse('two-bounds-required');
+                if ('hasAll' in cond) {
+                    for (const member of assertArrayMembers(field, cond.hasAll)) {
+                        conditions.push(`EXISTS (SELECT 1 FROM json_each(COALESCE(json_extract(data, ?), '[]')) WHERE type = 'text' AND value = ?)`);
+                        values.push(`$.${field}`, member);
+                    }
+                }
+                if ('hasNot' in cond) {
+                    assertArrayField(field, cond.hasNot);
+                    conditions.push(`NOT EXISTS (SELECT 1 FROM json_each(COALESCE(json_extract(data, ?), '[]')) WHERE type = 'text' AND value = ?)`);
+                    values.push(`$.${field}`, cond.hasNot);
+                }
                 if ('eq' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') = ?`);
-                    values.push(cond.eq);
+                    if (cond.eq === undefined) {
+                        conditions.push(`${this.filterFieldType(field)} IS NULL`);
+                    }
+                    else {
+                        conditions.push(`${this.filterColumn(field)} ${cond.eq === null ? 'IS NULL' : '= ?'}`);
+                        if (cond.eq !== null)
+                            values.push(this.encodeEqualityFilterOperand(cond.eq));
+                    }
                 }
                 if ('ne' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') != ?`);
-                    values.push(cond.ne);
+                    if (cond.ne === undefined) {
+                        conditions.push(`${this.filterFieldType(field)} IS NOT NULL`);
+                    }
+                    else {
+                        conditions.push(`${this.filterColumn(field)} ${cond.ne === null ? 'IS NOT NULL' : '!= ?'}`);
+                        if (cond.ne !== null)
+                            values.push(this.encodeEqualityFilterOperand(cond.ne));
+                    }
                 }
                 if ('gt' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') > ?`);
-                    values.push(cond.gt);
+                    conditions.push(`${this.filterColumn(field)} > ?`);
+                    values.push(this.encodeDateFilterOperand(cond.gt));
                 }
                 if ('gte' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') >= ?`);
-                    values.push(cond.gte);
+                    conditions.push(`${this.filterColumn(field)} >= ?`);
+                    values.push(this.encodeDateFilterOperand(cond.gte));
                 }
                 if ('lt' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') < ?`);
-                    values.push(cond.lt);
+                    conditions.push(`${this.filterColumn(field)} < ?`);
+                    values.push(this.encodeDateFilterOperand(cond.lt));
                 }
                 if ('lte' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') <= ?`);
-                    values.push(cond.lte);
+                    conditions.push(`${this.filterColumn(field)} <= ?`);
+                    values.push(this.encodeDateFilterOperand(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);
+                    conditions.push(`${this.filterColumn(field)} IN (${placeholders})`);
+                    values.push(...cond.in.map(value => this.encodeEqualityFilterOperand(value)));
                 }
                 if ('like' in cond) {
-                    conditions.push(`json_extract(data, '$.${field}') LIKE ?`);
+                    conditions.push(`${this.filterColumn(field)} LIKE ?`);
                     values.push(cond.like);
                 }
                 if ('isNull' in cond) {
                     if (cond.isNull) {
-                        conditions.push(`json_extract(data, '$.${field}') IS NULL`);
+                        conditions.push(`${this.filterColumn(field)} IS NULL`);
+                    }
+                    else {
+                        conditions.push(`${this.filterColumn(field)} IS NOT NULL`);
+                    }
+                }
+                // Operators below were declared by WhereFilter but never built, so a
+                // query using them was silently UNFILTERED — no error, just wrong
+                // rows. Found when a retention sweep's `{ processedAt: { isNotNull:
+                // true } }` guard was dropped and the delete matched 328,232 rows
+                // instead of the ~148k processed ones, i.e. it would have removed
+                // 178,639 unprocessed rows the caller had explicitly excluded.
+                // A typed operator that no builder honours is worse than a missing
+                // one: it reads as a guarantee.
+                if ('isNotNull' in cond) {
+                    if (cond.isNotNull) {
+                        conditions.push(`${this.filterColumn(field)} IS NOT NULL`);
                     }
                     else {
-                        conditions.push(`json_extract(data, '$.${field}') IS NOT NULL`);
+                        conditions.push(`${this.filterColumn(field)} IS NULL`);
                     }
                 }
+                if ('notIn' in cond && Array.isArray(cond.notIn)) {
+                    const placeholders = cond.notIn.map(() => '?').join(', ');
+                    conditions.push(`${this.filterColumn(field)} NOT IN (${placeholders})`);
+                    values.push(...cond.notIn.map(value => this.encodeEqualityFilterOperand(value)));
+                }
+                if ('ilike' in cond) {
+                    // SQLite LIKE is case-insensitive for ASCII by default; lower()
+                    // both sides so the intent holds regardless of collation.
+                    conditions.push(`lower(${this.filterColumn(field)}) LIKE lower(?)`);
+                    values.push(cond.ilike);
+                }
+                if ('contains' in cond) {
+                    conditions.push(`${this.filterColumn(field)} LIKE ?`);
+                    values.push(`%${String(cond.contains)}%`);
+                }
+                if ('startsWith' in cond) {
+                    conditions.push(`${this.filterColumn(field)} LIKE ?`);
+                    values.push(`${String(cond.startsWith)}%`);
+                }
+                if ('endsWith' in cond) {
+                    conditions.push(`${this.filterColumn(field)} LIKE ?`);
+                    values.push(`%${String(cond.endsWith)}`);
+                }
+                if ('between' in cond && Array.isArray(cond.between) && cond.between.length === 2) {
+                    conditions.push(`${this.filterColumn(field)} BETWEEN ? AND ?`);
+                    values.push(this.encodeDateFilterOperand(cond.between[0]), this.encodeDateFilterOperand(cond.between[1]));
+                }
+            }
+            else if (condition === undefined) {
+                conditions.push(`${this.filterFieldType(field)} IS NULL`);
             }
             else {
-                // Simple equality
-                conditions.push(`json_extract(data, '$.${field}') = ?`);
-                values.push(condition);
+                // SQL equality with NULL never matches; nullable fields use the null predicate.
+                conditions.push(`${this.filterColumn(field)} ${condition === null ? 'IS NULL' : '= ?'}`);
+                if (condition !== null)
+                    values.push(this.encodeEqualityFilterOperand(condition));
             }
         }
         return {
@@ -1031,181 +2355,19 @@ export class StorageRecord {
     buildOrderBy(orderBy) {
         if (Array.isArray(orderBy)) {
             return orderBy
-                .map((o) => `json_extract(data, '$.${String(o.field)}') ${o.direction}`)
+                .map((o) => `${this.filterColumn(String(o.field))} ${o.direction}`)
                 .join(', ');
         }
         else {
             const fields = Object.entries(orderBy).map(([field, direction]) => {
-                return `json_extract(data, '$.${field}') ${direction}`;
+                return `${this.filterColumn(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));
+    /** What relation loading reads of this record: its kind, primary key, declared relations and runtime. */
+    get relationOwner() {
+        return { recordKind: this.descriptor.id, primaryKey: this.primaryKey, relations: this.relations, runtime: this.context.runtime };
     }
     /**
      * Escape SQL identifier safely for query fragments.
@@ -1223,6 +2385,9 @@ export class StorageRecord {
             throw new Error(`FTS is not configured for ${this.tableName}`);
         }
         const ftsTable = this.descriptor.fts.tableName || `${this.tableName}_fts`;
+        const baseTableName = this.quoteIdentifier(this.tableName);
+        const primaryKeyName = this.quoteIdentifier(this.primaryKey);
+        const ftsTableName = this.quoteIdentifier(ftsTable);
         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.
@@ -1230,23 +2395,42 @@ export class StorageRecord {
         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 ?
+        // MATCH + where fragment shared by the page query and the COUNT query so
+        // the two can never drift.
+        let fromWhere = `
+			FROM ${baseTableName}
+			JOIN ${ftsTableName} ON ${ftsTableName}.rowid = ${baseTableName}.rowid
+			WHERE ${ftsTableName} MATCH ?
 		`;
+        const filterParams = [ftsQuery];
         if (options?.where) {
             const { clause, values } = this.buildWhereClause(options.where);
             if (clause) {
-                sql += ` AND ${clause}`;
-                params.push(...values);
+                fromWhere += ` AND ${clause}`;
+                filterParams.push(...values);
             }
         }
+        // Soft delete filter — search honors softDelete exactly like list()/count()
+        // (includeDeleted opts out). Callers must never re-implement this per-lane.
+        const deletedAtField = this.softDeleteField();
+        if (deletedAtField && !options?.includeDeleted) {
+            fromWhere += ` AND json_extract(data, '$.${deletedAtField}') IS NULL`;
+        }
+        // True total: COUNT over the same MATCH + where BEFORE limit/offset.
+        // Returning the page length as `total` hid every match past the cap.
+        // (minScore is applied per-row after fetch, so the total counts matches
+        // before that post-filter.)
+        const countRow = this.db.prepare(`SELECT COUNT(*) as count ${fromWhere}`).get(...filterParams);
+        const total = countRow?.count || 0;
+        const params = [...filterParams];
+        let sql = `
+			SELECT
+				${baseTableName}.${primaryKeyName},
+				${baseTableName}.data,
+				${ftsTableName}.rowid as _fts_rowid,
+				${ftsTableName}.rank as _rank
+			${fromWhere}
+		`;
         if (options?.orderBy) {
             sql += ` ORDER BY ${this.buildOrderBy(options.orderBy)}`;
         }
@@ -1261,12 +2445,12 @@ export class StorageRecord {
             sql += ` OFFSET ?`;
             params.push(options.offset);
         }
-        const rows = this.db.query(sql).all(...params);
+        const rows = this.db.prepare(sql).all(...params);
         const items = [];
         const scores = [];
         const highlights = new Map();
         for (const row of rows) {
-            const record = JSON.parse(row.data);
+            const record = this.decodeRecord(row.data);
             items.push(record);
             scores.push(row._rank);
             if (options?.highlight) {
@@ -1274,13 +2458,13 @@ export class StorageRecord {
                 const suffix = options.highlightSuffix || '</mark>';
                 const id = this.readPrimaryKey(record);
                 const fieldHighlights = [];
-                for (const field of ftsFields) {
+                for (const fieldIndex of ftsFields.keys()) {
                     const highlightSql = `
-						SELECT highlight(${ftsTable}, ?, ?, ?) as highlighted
-						WHERE ${ftsTable} MATCH ? AND rowid = ?
+						SELECT highlight(${ftsTableName}, ?, ?, ?) as highlighted
+						FROM ${ftsTableName}
+						WHERE ${ftsTableName} MATCH ? AND rowid = ?
 					`;
-                    const fieldIndex = ftsFields.indexOf(field);
-                    const highlightRow = this.db.query(highlightSql).get(fieldIndex, prefix, suffix, ftsQuery, rows.indexOf(row) + 1);
+                    const highlightRow = this.db.prepare(highlightSql).get(fieldIndex, prefix, suffix, ftsQuery, row._fts_rowid);
                     if (highlightRow?.highlighted) {
                         fieldHighlights.push(highlightRow.highlighted);
                     }
@@ -1294,10 +2478,10 @@ export class StorageRecord {
         }
         return {
             items,
-            total: items.length,
+            total,
             scores,
             highlights: highlights.size > 0 ? highlights : undefined,
-            hasMore: options?.limit ? items.length === options.limit : false
+            hasMore: (options?.offset ?? 0) + items.length < total
         };
     }
     // HIERARCHY
@@ -1330,12 +2514,11 @@ export class StorageRecord {
 			)
 			SELECT * FROM hierarchy ORDER BY depth, ${this.primaryKey}
 		`;
-        const rows = this.db.query(sql).all(id, maxDepth);
+        const rows = this.db.prepare(sql).all(id, maxDepth);
         const items = rows.map((row) => {
-            const record = JSON.parse(row.data);
-            record.depth = row.depth;
+            const record = Object.assign(this.decodeRecord(row.data), { depth: row.depth });
             if (includePath && row.path) {
-                record.path = JSON.parse(row.path);
+                return Object.assign(record, { path: this.decodePath(row.path) });
             }
             return record;
         });
@@ -1363,8 +2546,8 @@ export class StorageRecord {
 			)
 			SELECT * FROM ancestors ORDER BY depth DESC
 		`;
-        const rows = this.db.query(sql).all(id);
-        return rows.map((row) => JSON.parse(row.data));
+        const rows = this.db.prepare(sql).all(id);
+        return rows.map((row) => this.decodeRecord(row.data));
     }
     async getTree(options) {
         await this.ensureInitialized();
@@ -1397,18 +2580,18 @@ export class StorageRecord {
 			)
 			SELECT * FROM tree ORDER BY depth, ${this.primaryKey}
 		`;
-        const rows = this.db.query(sql).all(...whereClause.values, maxDepth);
+        const rows = this.db.prepare(sql).all(...whereClause.values, maxDepth);
         const nodeMap = new Map();
         const rootNodes = [];
         for (const row of rows) {
-            const record = JSON.parse(row.data);
+            const record = this.decodeRecord(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)
+                path: this.decodePath(row.path)
             };
             nodeMap.set(recordId, node);
             if (parentId && nodeMap.has(parentId)) {
@@ -1423,11 +2606,11 @@ export class StorageRecord {
     // RAW QUERIES
     async raw(sql, ...params) {
         await this.ensureInitialized();
-        return this.db.query(sql).all(...params);
+        return this.db.prepare(sql).all(...params);
     }
     async queryRaw(options) {
         await this.ensureInitialized();
-        const rows = this.db.query(options.sql).all(...(options.params || []));
+        const rows = this.db.prepare(options.sql).all(...(options.params || []));
         if (options.schema) {
             return rows.map((row) => options.schema.parse(row));
         }