akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_VALUE, dayjs, FIELD_META } from "akanjs/base";
-import { type ConstantModel, getDefault } from "akanjs/constant";
+import { Logger } from "akanjs/common";
+import { type ConstantModel, freshPrimitiveValue, getDefault } from "akanjs/constant";
 import {
   createDocumentId,
   type DatabaseModel,
@@ -16,10 +17,10 @@ import {
   resolveDocumentUpdate,
   sanitizeJson,
 } from "akanjs/document";
-import { descriptorHash, quoteIdent, stableJson } from "../sqlDescriptor";
 import { SqliteDialect } from "./dialect/sqlite";
 import { QueryCompiler } from "./QueryCompiler";
 import {
+  type AkanSqlClient,
   type AkanSqlStatement,
   BASE_COLUMNS,
   type DocumentDatabaseOwner,
@@ -38,11 +39,30 @@ import {
   type SortOption,
   type SqlDialect,
   type SqliteDocumentRow,
+  type TransferRow,
   toSafeRefName,
   type WriteHookOptions,
 } from "./types";
 import { UpdateCompiler } from "./UpdateCompiler";
-import { decodeDateValue, encodeSqlValue, jsonStr } from "./values";
+import {
+  assertStorableJson,
+  decodeDateValue,
+  descriptorHash,
+  encodeSqlValue,
+  jsonStr,
+  quoteIdent,
+  stableJson,
+} from "./values";
+
+interface DeclaredIndex {
+  name: string;
+  next: string;
+  metaKey: string;
+  hash: string;
+  create: (name: string, concurrently: boolean) => string;
+}
+
+type StoredRow = Omit<SqliteDocumentRow, "id">;
 
 const freshDefault = (value: unknown) => (Array.isArray(value) ? [...(value as unknown[])] : value);
 
@@ -51,10 +71,14 @@ export class SqlDocumentStore {
   readonly table: string;
   readonly compiler: QueryCompiler;
   readonly updateCompiler: UpdateCompiler;
-  #insertStmt: AkanSqlStatement | null = null;
-  #readStmtCache = new Map<string, AkanSqlStatement>();
+  
+  #statements = new WeakMap<AkanSqlClient, Map<string, AkanSqlStatement>>();
   #docPrototype: object | null = null;
   #immutableKeys: string[] | null = null;
+  #ensured: Promise<void> | null = null;
+  static readonly #logger = new Logger("SqlDocumentStore");
+  /** The row a document was read or last written as. */
+  static readonly #storedRow = Symbol("akan.storedRow");
 
   constructor(
     private readonly owner: DocumentDatabaseOwner,
@@ -66,45 +90,106 @@ export class SqlDocumentStore {
     this.schema = schema;
     this.table = database.refName;
     const fields = database.doc[FIELD_META] as unknown as FieldMap;
-
-    this.compiler = new QueryCompiler(fields, dialect, this.table, () => !!this.owner.getSearchIndex()?.enabled);
+    
+    this.compiler = new QueryCompiler(fields, dialect, this.table, () => this.owner.getSearchIndex());
     this.updateCompiler = new UpdateCompiler(fields, dialect);
   }
 
-  async ensure() {
+  ensure() {
+    this.#ensured ??= this.#ensure();
+    return this.#ensured;
+  }
+
+  async #ensure() {
     this.assertValidRefName(this.table);
-    const db = this.owner.getConnection();
-    const ts = this.dialect.timestampType();
-    await db.execute(
-      `CREATE TABLE IF NOT EXISTS ${quoteIdent(this.table)} (
+    const indexes = await this.#declaredIndexes();
+    const createSchema = async () => {
+      const db = this.owner.getConnection();
+      const existed = !!this.owner.buildIndexConcurrently && !!(await this.owner.hasTable?.(this.table));
+      const ts = this.dialect.timestampType();
+      await db.execute(
+        `CREATE TABLE IF NOT EXISTS ${quoteIdent(this.table)} (
         "id" TEXT PRIMARY KEY NOT NULL,
         "createdAt" ${ts} NOT NULL,
         "updatedAt" ${ts} NOT NULL,
         "removedAt" ${ts},
         "_doc" ${this.dialect.docColumnType()} NOT NULL
       )`,
-    );
-    await this.owner.setMeta(
-      `table:${this.table}`,
-      await descriptorHash({ table: this.table, columns: ["id", "createdAt", "updatedAt", "removedAt", "_doc"] }),
-    );
-    for (const [idx, index] of this.schema.indexes.entries()) {
-      const name = index.name ?? `${this.table}_${Object.keys(index.fields).map(toSafeRefName).join("_")}_${idx}`;
-      this.assertValidRefName(name);
-      const hash = await descriptorHash(index);
-      const metaKey = `index:${this.table}:${name}`;
-      const existing = await this.owner.getMeta(metaKey);
-      if (existing && existing !== hash) throw new Error(`Index descriptor mismatch: ${name}`);
-      const expressions = Object.keys(index.fields).map((field) => this.compiler.fieldExpr(field));
-      const unique = index.unique ? "UNIQUE " : "";
-      await db.execute(
-        `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(name)} ON ${quoteIdent(this.table)} (${expressions.join(", ")})`,
       );
+      await this.owner.grantInsight?.(this.table);
+      await this.owner.setMeta(
+        `table:${this.table}`,
+        await descriptorHash({ table: this.table, columns: ["id", "createdAt", "updatedAt", "removedAt", "_doc"] }),
+      );
+      const concurrent: (DeclaredIndex & { replace: boolean })[] = [];
+      for (const index of indexes) {
+        const stored = await this.owner.getMeta(index.metaKey);
+        const replace = !!stored && stored !== index.hash;
+        if (replace)
+          SqlDocumentStore.#logger.warn(
+            `Index ${index.name} on ${this.table} changed its descriptor and is rebuilt; on a large table that is a full index build`,
+          );
+        if (existed && !replace && (await this.owner.hasValidIndex?.(index.name))) {
+          await this.owner.setMeta(index.metaKey, index.hash);
+          continue;
+        }
+        if (existed) {
+          concurrent.push({ ...index, replace });
+          continue;
+        }
+        if (replace) await this.#replaceIndex(index);
+        else await db.execute(index.create(index.name, false));
+        await this.owner.setMeta(index.metaKey, index.hash);
+      }
+      return concurrent;
+    };
+    const concurrent = this.owner.lockSchema ? await this.owner.lockSchema(createSchema) : await createSchema();
+    for (const { name, next, create, replace, metaKey, hash } of concurrent) {
+      await this.owner.buildIndexConcurrently?.({ name, next, create: (target) => create(target, true), replace });
       await this.owner.setMeta(metaKey, hash);
     }
     await this.owner.getSearchIndex()?.ensureRef(this.constant, this.database);
   }
 
+  async #declaredIndexes(): Promise<DeclaredIndex[]> {
+    return await Promise.all(
+      this.schema.indexes.map(async (index, idx) => {
+        const declared = index.name ?? `${this.table}_${Object.keys(index.fields).map(toSafeRefName).join("_")}_${idx}`;
+        this.assertValidRefName(declared);
+        const name = this.dialect.indexName(declared);
+        const columns = Object.keys(index.fields).map((path) => ({
+          path,
+          expr: this.compiler.fieldExpr(path),
+          isArray: this.compiler.isArrayPath(path),
+        }));
+        return {
+          name,
+          next: this.dialect.indexName(`${declared}_next`),
+          metaKey: `index:${this.table}:${name}`,
+          hash: await descriptorHash(index),
+          create: (target: string, concurrently: boolean) =>
+            this.dialect.createIndex({
+              name: target,
+              table: this.table,
+              unique: !!index.unique,
+              columns,
+              concurrently,
+            }),
+        };
+      }),
+    );
+  }
+
+  async #replaceIndex(index: DeclaredIndex) {
+    const rebuild = async () => {
+      const db = this.owner.getConnection();
+      await db.execute(`DROP INDEX IF EXISTS ${quoteIdent(index.name)}`);
+      await db.execute(index.create(index.name, false));
+    };
+    if (this.owner.transaction) await this.owner.transaction(rebuild);
+    else await rebuild();
+  }
+
   async create(data: DocumentRecord, { runSaveHooks = true }: WriteHookOptions = {}) {
     const now = Date.now();
     const id = data.id ?? createDocumentId(now);
@@ -123,7 +208,7 @@ export class SqlDocumentStore {
     await this.insertStmt().run(row.id, row.createdAt, row.updatedAt, row.removedAt, row._doc);
     await this.runHooks("create", "create", doc, "post");
     if (runSaveHooks) await this.runHooks("save", "create", doc, "post");
-    return doc;
+    return this.#withStoredRow(doc, row);
   }
 
   async clone(data: DocumentRecord & { id: string }) {
@@ -136,10 +221,47 @@ export class SqlDocumentStore {
   }
 
   async remove(id: string) {
-    
     return this.update(id, { removedAt: dayjs() }, { runSaveHooks: false, crudType: "remove" });
   }
 
+  /** Up to `limit` stored rows after the id `after`, in id order and removed ones included. */
+  async exportRows(after: string, limit: number): Promise<TransferRow[]> {
+    const rows = await this.owner
+      .getConnection()
+      .prepare(
+        `SELECT "id", "createdAt", "updatedAt", "removedAt", "_doc" FROM ${quoteIdent(this.table)} WHERE "id" > ? ORDER BY "id" LIMIT ${Math.trunc(limit)}`,
+      )
+      .all<SqliteDocumentRow>(after);
+    const epoch = (value: unknown) => decodeDateValue(value)?.valueOf() ?? null;
+    return rows.map((row) => ({
+      id: row.id,
+      createdAt: epoch(row.createdAt) ?? 0,
+      updatedAt: epoch(row.updatedAt) ?? 0,
+      removedAt: epoch(row.removedAt),
+      _doc: JSON.parse(row._doc) as Record<string, unknown>,
+    }));
+  }
+
+  /** Rows as another database stored them: a taken id is replaced, and no hook runs or field is derived. */
+  async importRows(rows: TransferRow[]) {
+    const write = async () => {
+      const statement = this.owner.getConnection().prepare(
+        `INSERT INTO ${quoteIdent(this.table)} ("id", "createdAt", "updatedAt", "removedAt", "_doc") VALUES (?, ?, ?, ?, ${this.dialect.docValuePlaceholder()})
+           ON CONFLICT("id") DO UPDATE SET "createdAt" = excluded."createdAt", "updatedAt" = excluded."updatedAt", "removedAt" = excluded."removedAt", "_doc" = excluded."_doc"`,
+      );
+      for (const row of rows)
+        await statement.run(
+          row.id,
+          row.createdAt,
+          row.updatedAt,
+          row.removedAt,
+          assertStorableJson(JSON.stringify(row._doc), this.table),
+        );
+    };
+    if (this.owner.transaction) await this.owner.transaction(write);
+    else await write();
+  }
+
   async updateOneByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentUpdateOptions = {}) {
     const resolved = resolveDocumentUpdate(update);
     const { assignments, params } = this.compiledUpdate(resolved);
@@ -174,16 +296,18 @@ export class SqlDocumentStore {
   }
 
   async removeManyByQuery(query: DocumentQuery) {
-
+    
     return this.updateManyByQuery(query, { removedAt: dayjs() });
   }
 
   async removeOneByQuery(query: DocumentQuery) {
-
+    
     return this.updateOneByQuery(query, { removedAt: dayjs() });
   }
 
   private compiledUpdate(update: DocumentUpdate) {
+    for (const raw of Object.values(update))
+      assertStorableJson(jsonStr(isDocumentUpdateNode(raw) ? raw.value : raw), this.table);
     const compiled = this.updateCompiler.compile(update);
     return {
       assignments: [`${quoteIdent("updatedAt")} = ?`, ...compiled.assignments],
@@ -209,44 +333,36 @@ export class SqlDocumentStore {
   }
 
   async find(query?: DocumentQuery, options: FindManyOptions = {}) {
-    const { where, params, joins } = this.safeQuery(query);
-    const limitValue = Number(options.limit ?? 0);
-    const skipValue = Number(options.skip ?? 0);
-    const limit = limitValue ? ` LIMIT ${limitValue}` : "";
-    const offset = skipValue ? ` OFFSET ${skipValue}` : "";
-    const join = this.joinSql(joins);
-    const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.orderBy(options.sort, joins)}`;
-    const args = [...this.joinParams(joins), ...params];
+    const { star, tail, args } = this.listQuery(query, options);
     const projection = this.resolveProjection(options.select);
     if (projection) {
-      const rows = await this.prepareReadStmt(
-        `SELECT ${this.projectionSql(projection)} FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
+      const rows = await this.prepareStmt(
+        `SELECT ${this.projectionSql(projection)} ${tail}`,
       ).all<ProjectedSqliteDocumentRow>(...args);
       return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }));
     }
+    const rows = await this.prepareStmt(`SELECT ${star} ${tail}`).all<SqliteDocumentRow>(...args);
+    return rows.map((row) => this.#withStoredRow(this.hydrate(this.fromRow(row), undefined, { track: false }), row));
+  }
 
-    const star = joins.length ? `${quoteIdent(this.table)}.*` : "*";
-    const rows = await this.prepareReadStmt(
-      `SELECT ${star} FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
-    ).all<SqliteDocumentRow>(...args);
-    return rows.map((row) => this.hydrate(this.fromRow(row), undefined, { track: false }));
+  async findIds(query?: DocumentQuery, options: Omit<FindManyOptions, "select"> = {}) {
+    const { tail, args } = this.listQuery(query, options);
+    const rows = await this.prepareStmt(`SELECT ${quoteIdent(this.table)}."id" ${tail}`).all<{ id: string }>(...args);
+    return rows.map((row) => row.id);
   }
 
-  async findIds(
-    query?: DocumentQuery,
-    options: { sort?: SortOption; skip?: number | null; limit?: number | null; sample?: number } = {},
-  ) {
+  private listQuery(query: DocumentQuery | undefined, options: FindManyOptions) {
     const { where, params, joins } = this.safeQuery(query);
     const limitValue = Number(options.limit ?? 0);
     const skipValue = Number(options.skip ?? 0);
-    const limit = limitValue ? ` LIMIT ${limitValue}` : "";
-    const offset = skipValue ? ` OFFSET ${skipValue}` : "";
-    const join = this.joinSql(joins);
     const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.orderBy(options.sort, joins)}`;
-    const rows = await this.prepareReadStmt(
-      `SELECT ${quoteIdent(this.table)}."id" FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
-    ).all<{ id: string }>(...this.joinParams(joins), ...params);
-    return rows.map((row) => row.id);
+    const page = `${limitValue ? ` LIMIT ${limitValue}` : ""}${skipValue ? ` OFFSET ${skipValue}` : ""}`;
+    return {
+      
+      star: joins.length ? `${quoteIdent(this.table)}.*` : "*",
+      tail: `FROM ${quoteIdent(this.table)}${this.joinSql(joins)} WHERE ${where} ${order}${page}`,
+      args: [...this.joinParams(joins), ...params],
+    };
   }
 
   async findOne(query?: DocumentQuery, options: FindOneOptions = {}) {
@@ -275,7 +391,7 @@ export class SqlDocumentStore {
 
   async count(query?: DocumentQuery) {
     const { where, params, joins } = this.safeQuery(query);
-    const row = await this.prepareReadStmt(
+    const row = await this.prepareStmt(
       `SELECT count(*) as count FROM ${quoteIdent(this.table)}${this.joinSql(joins)} WHERE ${where}`,
     ).get<{ count: number }>(...this.joinParams(joins), ...params);
     return row?.count ?? 0;
@@ -335,7 +451,7 @@ export class SqlDocumentStore {
         if (props.default !== undefined && props.default !== null) {
           doc[key] = freshDefault(typeof props.default === "function" ? props.default(data) : props.default);
         } else if (props.isClass && props.isScalar && !props.nullable) {
-
+          
           doc[key] = getDefault((props.modelRef as { [FIELD_META]: FieldMap })[FIELD_META] as never);
         } else if (!props.nullable && !["removedAt"].includes(key)) {
           if (["id", "createdAt", "updatedAt"].includes(key)) continue;
@@ -438,23 +554,17 @@ export class SqlDocumentStore {
     return doc;
   }
 
-  private toRow(doc: DocumentRecord) {
-    const payload = { ...doc };
-    delete payload.id;
-    delete payload.createdAt;
-    delete payload.updatedAt;
-    delete payload.removedAt;
+  private toRow({ id, createdAt, updatedAt, removedAt, ...payload }: DocumentRecord) {
     return {
-      id: doc.id,
-      createdAt: Number(encodeSqlValue(doc.createdAt ?? dayjs())),
-      updatedAt: Number(encodeSqlValue(doc.updatedAt ?? dayjs())),
-      removedAt: doc.removedAt ? Number(encodeSqlValue(doc.removedAt)) : null,
-      _doc: JSON.stringify(sanitizeJson(payload)),
+      id,
+      createdAt: Number(encodeSqlValue(createdAt ?? dayjs())),
+      updatedAt: Number(encodeSqlValue(updatedAt ?? dayjs())),
+      removedAt: removedAt ? Number(encodeSqlValue(removedAt)) : null,
+      _doc: assertStorableJson(JSON.stringify(sanitizeJson(payload)), this.table),
     };
   }
 
   private fromRow(row: SqliteDocumentRow) {
-    
     const rawDoc: unknown = row._doc;
     const raw = typeof rawDoc === "string" ? JSON.parse(rawDoc) : (rawDoc as Record<string, unknown>);
     const payload = this.decodeDocumentPayload(raw);
@@ -514,11 +624,13 @@ export class SqlDocumentStore {
       const props = (this.database.doc[FIELD_META] as unknown as FieldMap)[field]?.getProps?.();
       if (value === null && !props?.nullable) {
         if (props?.default != null) {
-          doc[field] =
-            typeof props.default === "function" ? (props.default as (data: unknown) => unknown)(doc) : props.default;
+          doc[field] = freshDefault(
+            typeof props.default === "function" ? (props.default as (data: unknown) => unknown)(doc) : props.default,
+          );
+        } else if (props?.isClass && props.isScalar) {
+          doc[field] = getDefault((props.modelRef as { [FIELD_META]: FieldMap })[FIELD_META] as never);
         } else {
-          doc[field] =
-            ((props as Record<string, unknown>).modelRef as { [DEFAULT_VALUE]?: unknown })?.[DEFAULT_VALUE] ?? null;
+          doc[field] = SqlDocumentStore.#primitiveDefault(props as Record<string, unknown>);
         }
       } else {
         doc[field] = props ? this.decodeFieldValue(value, props) : value;
@@ -528,18 +640,9 @@ export class SqlDocumentStore {
   }
 
   private async findForWrite(query?: DocumentQuery, options: FindManyOptions = {}) {
-    const { where, params, joins } = this.safeQuery(query);
-    const limitValue = Number(options.limit ?? 0);
-    const skipValue = Number(options.skip ?? 0);
-    const limit = limitValue ? ` LIMIT ${limitValue}` : "";
-    const offset = skipValue ? ` OFFSET ${skipValue}` : "";
-    const join = this.joinSql(joins);
-    const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.orderBy(options.sort, joins)}`;
-    const star = joins.length ? `${quoteIdent(this.table)}.*` : "*";
-    const rows = await this.prepareReadStmt(
-      `SELECT ${star} FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
-    ).all<SqliteDocumentRow>(...this.joinParams(joins), ...params);
-    return rows.map((row) => this.hydrate(this.fromRow(row)));
+    const { star, tail, args } = this.listQuery(query, options);
+    const rows = await this.prepareStmt(`SELECT ${star} ${tail}`).all<SqliteDocumentRow>(...args);
+    return rows.map((row) => this.#withStoredRow(this.hydrate(this.fromRow(row)), row));
   }
 
   private async findOneForWrite(query?: DocumentQuery, options: FindOneOptions = {}) {
@@ -563,19 +666,75 @@ export class SqlDocumentStore {
     const prepared = this.prepareDocument({ ...data, id, updatedAt: dayjs() });
     this.#assertImmutableUnchanged(prepared, originalData);
     const doc = this.hydrate(prepared, originalData);
-
+    
     const previous = originalData;
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "pre", previous);
     await this.runHooks(crudType, crudType, doc, "pre", previous);
     const row = this.toRow(doc);
-    await this.owner
-      .getConnection()
-      .prepare(
-        `UPDATE ${quoteIdent(this.table)} SET "createdAt" = ?, "updatedAt" = ?, "removedAt" = ?, "_doc" = ${this.dialect.docValuePlaceholder()} WHERE "id" = ?`,
-      )
-      .run(row.createdAt, row.updatedAt, row.removedAt, row._doc, id);
+    const stored = (originalData as Record<symbol, StoredRow | undefined>)[SqlDocumentStore.#storedRow];
+    await this.#writeChanges(id, stored ?? this.toRow(originalData), row);
     await this.runHooks(crudType, crudType, doc, "post", previous);
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "post", previous);
+    return this.#withStoredRow(doc, row);
+  }
+
+  /**
+   * Merges only the fields that changed into the stored `_doc`, so a concurrent write to another field survives. A key
+   * the stored row lacks is written out, which is what `q.missing` tells rows from before a field existed apart by.
+   */
+  async #writeChanges(id: string, read: StoredRow, written: StoredRow) {
+    const before = SqlDocumentStore.#encodedFields(read);
+    const after = SqlDocumentStore.#encodedFields(written);
+    const assignments = [`"updatedAt" = ?`];
+    const params: unknown[] = [written.updatedAt];
+    for (const column of ["createdAt", "removedAt"] as const) {
+      if (before.get(column) === after.get(column)) continue;
+      assignments.push(`${quoteIdent(column)} = ?`);
+      params.push(written[column]);
+    }
+    const payload = JSON.parse(written._doc) as Record<string, unknown>;
+    const set: [string, string][] = [];
+    const removed: string[] = [];
+    for (const field of new Set([...before.keys(), ...after.keys()])) {
+      if (BASE_COLUMNS.has(field) || before.get(field) === after.get(field)) continue;
+      if (after.has(field)) set.push([field, JSON.stringify(payload[field])]);
+      else removed.push(field);
+    }
+    if (set.length || removed.length) {
+      const merged = this.dialect.mergeDocument(set, removed);
+      assignments.push(`"_doc" = ${merged.sql}`);
+      params.push(...merged.params);
+    }
+    await this.owner
+      .getConnection()
+      .prepare(`UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE "id" = ?`)
+      .run(...params, id);
+  }
+
+  #changesOf(doc: DocumentRecord): DocumentRecord {
+    const row = (doc as Record<symbol, StoredRow | undefined>)[SqlDocumentStore.#storedRow];
+    if (!row) return doc;
+    
+    const reread = this.hydrate(this.fromRow({ ...row, id: String(doc.id) }), undefined, { track: false });
+    const read = SqlDocumentStore.#encodedFields(this.toRow(reread));
+    const held = SqlDocumentStore.#encodedFields(this.toRow(doc));
+    const changes: DocumentRecord = {};
+    for (const field of new Set([...read.keys(), ...held.keys()]))
+      if (read.get(field) !== held.get(field)) changes[field] = doc[field];
+    return changes;
+  }
+
+  static #encodedFields({ createdAt, removedAt, _doc }: StoredRow) {
+    const fields = new Map(
+      Object.entries(JSON.parse(_doc) as Record<string, unknown>).map(([field, value]) => [field, stableJson(value)]),
+    );
+    fields.set("createdAt", String(createdAt));
+    fields.set("removedAt", String(removedAt ?? null));
+    return fields;
+  }
+
+  #withStoredRow<Doc extends object>(doc: Doc, row: StoredRow): Doc {
+    Object.defineProperty(doc, SqlDocumentStore.#storedRow, { value: row, configurable: true });
     return doc;
   }
 
@@ -606,11 +765,10 @@ export class SqlDocumentStore {
         } else if (props.nullable) {
           result[key] = null;
         } else if (props.isClass && props.isScalar) {
-
+          
           result[key] = getDefault((props.modelRef as { [FIELD_META]: FieldMap })[FIELD_META] as never);
         } else {
-          result[key] =
-            ((props as Record<string, unknown>).modelRef as { [DEFAULT_VALUE]?: unknown })?.[DEFAULT_VALUE] ?? null;
+          result[key] = SqlDocumentStore.#primitiveDefault(props);
         }
       } else {
         result[key] = this.decodeFieldValue(value, props);
@@ -624,6 +782,10 @@ export class SqlDocumentStore {
     return result;
   }
 
+  static #primitiveDefault(props: Record<string, unknown>) {
+    return freshPrimitiveValue((props.modelRef as { [DEFAULT_VALUE]?: unknown } | undefined)?.[DEFAULT_VALUE]) ?? null;
+  }
+
   private decodeFieldValue(value: unknown, props: Record<string, unknown>): unknown {
     if (value === undefined || value === null) return value;
     if (props.isMap) {
@@ -689,12 +851,7 @@ export class SqlDocumentStore {
     return result;
   }
 
-  /**
-   * `track` buys `isModified()` and costs a deep clone of the row, so it is decided per call site rather than
-   * paid everywhere. Only the read paths (`find`, and the projected read behind it) opt out — that clone was 42%
-   * of a list query, and a listed document is never the one a save hook runs on. Everything else keeps it, so an
-   * external caller of `hydrate` sees no change.
-   */
+  /** `track` buys `isModified()` with a deep clone of the row; only the read paths opt out. */
   hydrate(data: DocumentRecord, originalData: DocumentRecord = data, { track = true }: { track?: boolean } = {}) {
     const isNew = !originalData.id;
     const hydratedData = isNew ? this.prepareDocument(data) : data;
@@ -703,18 +860,21 @@ export class SqlDocumentStore {
     Object.defineProperty(doc, MODIFICATION_STATE, {
       value: {
         isNew,
-
+        
         original: JSON.parse(JSON.stringify(sanitizeJson(originalData) ?? {})) as Record<string, unknown>,
       } satisfies ModificationState,
     });
     return doc;
   }
 
-  /**
-   * One prototype per store instead of six closures per document. It extends the model's own document prototype,
-   * so declared chain methods and `instanceof` are unaffected, and every method here is non-enumerable exactly as
-   * the previous per-document `defineProperties` made them.
-   */
+  serialize(doc: DocumentRecord) {
+    return JSON.stringify(this.toRow(doc));
+  }
+
+  deserialize(text: string) {
+    return this.hydrate(this.fromRow(JSON.parse(text) as SqliteDocumentRow), undefined, { track: false });
+  }
+
   #documentPrototype() {
     if (this.#docPrototype) return this.#docPrototype;
     const store = this;
@@ -727,13 +887,14 @@ export class SqlDocumentStore {
       },
       save: {
         async value(this: DocumentRecord) {
-          return this.id ? store.update(this.id as string, this) : store.create(this);
+          return this.id ? store.update(this.id as string, store.#changesOf(this)) : store.create(this);
         },
       },
       refresh: {
         async value(this: DocumentRecord) {
-          Object.assign(this, await store.pickById(this.id as string));
-          return this;
+          const fresh = (await store.pickById(this.id as string)) as DocumentRecord & Record<symbol, StoredRow>;
+          Object.assign(this, fresh);
+          return store.#withStoredRow(this, fresh[SqlDocumentStore.#storedRow]);
         },
       },
       isModified: {
@@ -783,24 +944,27 @@ export class SqlDocumentStore {
   }
 
   private insertStmt() {
-    this.#insertStmt ??= this.owner
-      .getConnection()
-      .prepare(
-        `INSERT INTO ${quoteIdent(this.table)} ("id", "createdAt", "updatedAt", "removedAt", "_doc") VALUES (?, ?, ?, ?, ${this.dialect.docValuePlaceholder()})`,
-      );
-    return this.#insertStmt;
+    return this.prepareStmt(
+      `INSERT INTO ${quoteIdent(this.table)} ("id", "createdAt", "updatedAt", "removedAt", "_doc") VALUES (?, ?, ?, ?, ${this.dialect.docValuePlaceholder()})`,
+    );
   }
 
-  private prepareReadStmt(sql: string) {
-    const cached = this.#readStmtCache.get(sql);
+  private prepareStmt(sql: string) {
+    const connection = this.owner.getConnection();
+    let cache = this.#statements.get(connection);
+    if (!cache) {
+      cache = new Map();
+      this.#statements.set(connection, cache);
+    }
+    const cached = cache.get(sql);
     if (cached) return cached;
     
-    if (this.#readStmtCache.size >= 128) {
-      const oldest = this.#readStmtCache.keys().next().value;
-      if (oldest) this.#readStmtCache.delete(oldest);
+    if (cache.size >= 128) {
+      const oldest = cache.keys().next().value;
+      if (oldest) cache.delete(oldest);
     }
-    const stmt = this.owner.getConnection().prepare(sql);
-    this.#readStmtCache.set(sql, stmt);
+    const stmt = connection.prepare(sql);
+    cache.set(sql, stmt);
     return stmt;
   }
 
@@ -809,15 +973,3 @@ export class SqlDocumentStore {
       throw new Error(`Invalid database identifier: ${refName}`);
   }
 }
-
-/**
- * The schema setups `getStore` starts but nobody awaits.
- *
- * `getStore` returns a store synchronously while `ensure()` goes on creating tables and indexes, so
- * the connection could be closed out from under one — a server shutting down, or a test tearing its
- * fixture down. That surfaced as an unhandled `Cannot use a closed database` blamed on whatever ran
- * next, which made it look like a flaky test rather than a race at shutdown.
- *
- * Every statement `ensure()` runs is `IF NOT EXISTS`, so one cut short is simply redone on the next
- * boot; a failure *before* the close is still a real problem and still surfaces.
- */