@haverstack/record-adapter-sqlite 0.21.0 → 0.23.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { existsSync, writeFileSync, readFileSync, unlinkSync } from 'fs';
-import { StackVersionConflictError, StackNotFoundError, StackConflictError, applyMergePatch, StackQueryError } from '@haverstack/core';
+import { existsSync, writeFileSync, unlinkSync, readFileSync } from 'fs';
+import { StackNotFoundError, StackConflictError, applyMergePatch, StackVersionConflictError, StackQueryError, NATIVE_SORT_FIELDS } from '@haverstack/core';
 import { contentSortEntry, parseContentFilterKey, contentSortKey } from '@haverstack/core/adapter';
 import { randomBytes, createHash } from 'crypto';
 
@@ -151,7 +151,13 @@ var FTS5_SCHEMA_SQL = `
 `;
 var PRAGMA_FOREIGN_KEYS_ON = `PRAGMA foreign_keys = ON;`;
 var PRAGMA_JOURNAL_MODE_WAL = `PRAGMA journal_mode = WAL;`;
-var SORT_FIELDS = ["createdAt", "updatedAt", "version"];
+var applyRecordSchema = (exec, opts) => {
+  exec.exec(PRAGMA_FOREIGN_KEYS_ON);
+  exec.exec(PRAGMA_JOURNAL_MODE_WAL);
+  exec.exec(RECORD_SCHEMA_SQL);
+  exec.exec(FTS5_SCHEMA_SQL);
+};
+var SORT_FIELDS = NATIVE_SORT_FIELDS;
 var toBase64 = (text) => {
   const bytes = new TextEncoder().encode(text);
   let binary = "";
@@ -367,17 +373,30 @@ var recordConditions = (query) => {
   const conditions = ["r.id != '_config'"];
   const params = [];
   const f = query.filter ?? {};
+  const inFilter = (column, value) => {
+    if (value === void 0)
+      return;
+    const values = Array.isArray(value) ? value : [value];
+    conditions.push(`r.${column} IN (${values.map(() => "?").join(",")})`);
+    params.push(...values);
+  };
+  const rangeFilter = (column, range) => {
+    if (range?.after) {
+      conditions.push(`r.${column} > ?`);
+      params.push(range.after.getTime());
+    }
+    if (range?.before) {
+      conditions.push(`r.${column} < ?`);
+      params.push(range.before.getTime());
+    }
+  };
   if (!f.includeDeleted) {
     conditions.push("r.deleted_at IS NULL");
   }
   if (!f.includeUnlisted) {
     conditions.push("r.unlisted_at IS NULL");
   }
-  if (f.typeId !== void 0) {
-    const ids = Array.isArray(f.typeId) ? f.typeId : [f.typeId];
-    conditions.push(`r.type_id IN (${ids.map(() => "?").join(",")})`);
-    params.push(...ids);
-  }
+  inFilter("type_id", f.typeId);
   if (f.parentId !== void 0) {
     if (f.parentId === null) {
       conditions.push("r.parent_id IS NULL");
@@ -386,49 +405,24 @@ var recordConditions = (query) => {
       params.push(f.parentId);
     }
   }
-  if (f.appId !== void 0) {
-    const ids = Array.isArray(f.appId) ? f.appId : [f.appId];
-    conditions.push(`r.app_id IN (${ids.map(() => "?").join(",")})`);
-    params.push(...ids);
-  }
-  if (f.entityId !== void 0) {
-    const ids = Array.isArray(f.entityId) ? f.entityId : [f.entityId];
-    conditions.push(`r.entity_id IN (${ids.map(() => "?").join(",")})`);
-    params.push(...ids);
-  }
-  if (f.principalId !== void 0) {
-    const ids = Array.isArray(f.principalId) ? f.principalId : [f.principalId];
-    conditions.push(`r.principal_id IN (${ids.map(() => "?").join(",")})`);
-    params.push(...ids);
-  }
-  if (f.createdAt?.after) {
-    conditions.push("r.created_at > ?");
-    params.push(f.createdAt.after.getTime());
-  }
-  if (f.createdAt?.before) {
-    conditions.push("r.created_at < ?");
-    params.push(f.createdAt.before.getTime());
-  }
-  if (f.updatedAt?.after) {
-    conditions.push("r.updated_at > ?");
-    params.push(f.updatedAt.after.getTime());
-  }
-  if (f.updatedAt?.before) {
-    conditions.push("r.updated_at < ?");
-    params.push(f.updatedAt.before.getTime());
-  }
+  inFilter("app_id", f.appId);
+  inFilter("entity_id", f.entityId);
+  inFilter("principal_id", f.principalId);
+  rangeFilter("created_at", f.createdAt);
+  rangeFilter("updated_at", f.updatedAt);
+  const hasAssociation = (kind, clauses) => `r.id IN (SELECT a.record_id FROM associations a WHERE a.kind = '${kind}'` + clauses.map((c) => ` AND ${c}`).join("") + `)`;
   if (f.tags?.length) {
     for (const tag of f.tags) {
-      conditions.push(`r.id IN (SELECT a.record_id FROM associations a WHERE a.kind = 'tag' AND a.label = ?)`);
+      conditions.push(hasAssociation("tag", ["a.label = ?"]));
       params.push(tag);
     }
   }
   if (f.hasAttachment) {
-    conditions.push(`r.id IN (SELECT a.record_id FROM associations a WHERE a.kind = 'attachment' AND a.label = ?)`);
+    conditions.push(hasAssociation("attachment", ["a.label = ?"]));
     params.push(f.hasAttachment);
   }
   if (f.attachmentFileId) {
-    conditions.push(`(r.id IN (SELECT a.record_id FROM associations a WHERE a.kind = 'attachment' AND a.file_id = ?)
+    conditions.push(`(${hasAssociation("attachment", ["a.file_id = ?"])}
         OR r.id IN (SELECT ci.record_id FROM content_index ci WHERE ci.file_id = ?))`);
     params.push(f.attachmentFileId, f.attachmentFileId);
   }
@@ -457,7 +451,7 @@ var recordConditions = (query) => {
         }
       }
     }
-    conditions.push(`r.id IN (SELECT a.record_id FROM associations a WHERE a.kind = 'relationship'` + clauses.map((c) => ` AND ${c}`).join("") + `)`);
+    conditions.push(hasAssociation("relationship", clauses));
   }
   if (f.content) {
     let aliasSeq = 0;
@@ -656,64 +650,32 @@ var rowToVersion = (row) => {
     v.permissions = JSON.parse(row.permissions);
   return v;
 };
-var lockPathFor = (dbPath) => `${dbPath}.lock`;
-var isProcessAlive = (pid) => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code !== "ESRCH";
-  }
-};
-var acquireLock = (dbPath, force) => {
-  const lockPath = lockPathFor(dbPath);
-  const info = existsSync(lockPath) ? readLock(lockPath) : null;
-  if (info) {
-    const ownedBySelf = info.pid === process.pid;
-    if (!ownedBySelf && !force && isProcessAlive(info.pid)) {
-      throw new Error(`Stack database at "${dbPath}" is in use by another process (pid ${info.pid}). Connect via its server instead, or pass { force: true } to override. If no such process is running, remove "${lockPath}".`);
-    }
-  }
-  writeFileSync(lockPath, JSON.stringify({ pid: process.pid }));
-};
-var readLock = (lockPath) => {
-  try {
-    const info = JSON.parse(readFileSync(lockPath, "utf-8"));
-    return typeof info?.pid === "number" ? info : null;
-  } catch {
-    return null;
-  }
-};
-var releaseLock = (dbPath) => {
-  const lockPath = lockPathFor(dbPath);
-  if (!existsSync(lockPath))
-    return;
-  try {
-    const info = JSON.parse(readFileSync(lockPath, "utf-8"));
-    if (info.pid === process.pid)
-      unlinkSync(lockPath);
-  } catch {
-    unlinkSync(lockPath);
-  }
-};
 
 // ../sqlite-shared/dist/executor.js
 var isForeignKeyViolation = (err) => err instanceof Error && err.message.includes("FOREIGN KEY constraint failed");
 var isUniqueConstraintViolation = (err) => err instanceof Error && err.message.includes("UNIQUE constraint failed");
 
 // ../sqlite-shared/dist/config.js
+var CONFIG_ROW_SQL = `SELECT content FROM records WHERE id = '_config'`;
 var insertConfigRecord = (exec, entityId, timezone) => {
   const now = Date.now();
   exec.run(`INSERT INTO records (id, type_id, created_at, updated_at, content, version)
      VALUES ('_config', '_config@1', ?, ?, ?, 1)`, [now, now, JSON.stringify({ entityId, timezone })]);
+  return { entityId, timezone };
 };
-var readStackConfig = (exec) => {
-  const row = exec.get(`SELECT content FROM records WHERE id = '_config'`);
+var tryReadStackConfig = (exec) => {
+  const row = exec.get(CONFIG_ROW_SQL);
   if (!row)
-    throw new Error("Stack database is missing its config record.");
+    return null;
   const content = JSON.parse(row.content);
   return { entityId: content.entityId, timezone: content.timezone };
 };
+var readStackConfig = (exec) => {
+  const config = tryReadStackConfig(exec);
+  if (!config)
+    throw new Error("Stack database is missing its config record.");
+  return config;
+};
 var asStackQueryError = (query, run) => {
   try {
     return run();
@@ -723,6 +685,29 @@ var asStackQueryError = (query, run) => {
     throw new StackQueryError(`Search text could not be parsed: ${err instanceof Error ? err.message : String(err)}`);
   }
 };
+var versionConflict = (id, expected, actual) => new StackVersionConflictError(`Record "${id}" is at version ${actual}, expected ${expected}`, id, expected, actual);
+var VERSION_COLUMNS = [
+  "type_id",
+  "content",
+  "updated_at",
+  "entity_id",
+  "updated_by",
+  "updated_via",
+  "parent_id",
+  "associations",
+  "permissions"
+];
+var versionRowValues = (version) => [
+  version.typeId,
+  JSON.stringify(version.content),
+  toMs(version.updatedAt),
+  version.entityId ?? null,
+  version.updatedBy ?? null,
+  version.updatedVia ?? null,
+  version.parentId ?? null,
+  version.associations ? JSON.stringify(version.associations) : null,
+  version.permissions ? JSON.stringify(version.permissions) : null
+];
 var indexedFieldKinds = (schema) => {
   const kinds = /* @__PURE__ */ new Map();
   for (const [field, def] of Object.entries(schema)) {
@@ -748,26 +733,22 @@ var SharedSqlRecordLogic = class {
     return this.deps.exec;
   }
   /**
-   * SQL fragment (plus its bind params) that gates a records-table
-   * UPDATE/DELETE on the opt-in `expectedVersion` precondition. Empty when
-   * expectedVersion is omitted, keeping today's unconditional behavior.
-   */
-  versionGuard(expectedVersion) {
-    return expectedVersion === void 0 ? { clause: "", params: [] } : { clause: " AND version = ?", params: [expectedVersion] };
-  }
-  /**
-   * Precondition check for mutations that can't fold expectedVersion into
-   * their primary UPDATE's WHERE clause: mutateRecord/restoreVersion need
-   * fts.remove() to run *before* the records-table content changes, so
-   * the check happens first, standalone.
+   * Precondition check for a mutation that has already read the record —
+   * either because it can't fold the check into its own statement
+   * (hardDeleteRecord: children reference the row, so the DELETE can't
+   * carry it), or because it has to settle the precondition *before*
+   * fts5Strategy.remove() runs, which needs the records row still holding
+   * the old content. In the latter case versionedUpdate() re-checks it
+   * inside the statement, and that is the enforcement; this is what lets
+   * the work before it be skipped.
    */
   checkExpectedVersion(record, expectedVersion) {
     if (expectedVersion === void 0 || record.version === expectedVersion)
       return;
-    throw new StackVersionConflictError(`Record "${record.id}" is at version ${record.version}, expected ${expectedVersion}`, record.id, expectedVersion, record.version);
+    throw versionConflict(record.id, expectedVersion, record.version);
   }
   /**
-   * Called after a versionGuard()-gated statement affected zero rows.
+   * Called after a version-gated statement affected zero rows.
    * Distinguishes "record doesn't exist" (StackNotFoundError) from "it
    * exists but isn't at expectedVersion" (StackVersionConflictError, with
    * the actual current version for the caller to act on).
@@ -778,7 +759,48 @@ var SharedSqlRecordLogic = class {
     ]);
     if (!row)
       throw new StackNotFoundError(`Record not found: "${id}"`);
-    throw new StackVersionConflictError(`Record "${id}" is at version ${row.version}, expected ${expectedVersion}`, id, expectedVersion, row.version);
+    throw versionConflict(id, expectedVersion, row.version);
+  }
+  /**
+   * The one shape every mutating UPDATE in this class has: whatever columns
+   * the caller is changing, then the version bump and the actor/timestamp
+   * stamp that every mutation owes, gated on the opt-in `expectedVersion`
+   * precondition and failing loudly when nothing matched.
+   *
+   * The guard rides in the WHERE clause even where the caller has already
+   * checked the version against a record it read: that read is outside this
+   * statement, so a writer slipping in between the two is caught here
+   * rather than silently overwritten.
+   */
+  versionedUpdate(id, sets, values, opts, now = toMs(/* @__PURE__ */ new Date())) {
+    const guarded = opts.expectedVersion !== void 0;
+    const changed = this.exec.run(`UPDATE records SET ${[...sets, "version = version + 1", "updated_at = ?", "updated_by = ?", "updated_via = ?"].join(", ")} WHERE id = ?${guarded ? " AND version = ?" : ""}`, [
+      ...values,
+      now,
+      opts.updatedBy ?? null,
+      opts.updatedVia ?? null,
+      id,
+      ...guarded ? [opts.expectedVersion] : []
+    ]);
+    if (changed === 0)
+      this.throwVersionConflict(id, opts.expectedVersion);
+  }
+  /**
+   * Read a record back after its own mutation committed, for the caller to
+   * return. Its absence is not a "not found" for the caller to handle — the
+   * mutation just succeeded against it — so it fails as the invariant
+   * breach it would be.
+   *
+   * Synchronous, via readRecord() rather than getRecord(), so the read
+   * cannot be separated from the commit by anything: an async caller
+   * returning this still hands back a record read in the same tick its
+   * transaction committed. See readRecord() for why that matters.
+   */
+  reread(id, verb) {
+    const updated = this.readRecord(id);
+    if (!updated)
+      throw new Error(`Record not found after ${verb}: "${id}"`);
+    return updated;
   }
   // -------------------------------------------------------
   // Records
@@ -835,11 +857,11 @@ var SharedSqlRecordLogic = class {
    * reason (see SqlExecutor.transaction).
    *
    * The same synchrony is what lets the post-commit reads below report the
-   * version their own mutation produced: `getRecord()` runs its body before
-   * the `await` yields, so nothing interleaves between the commit and the
-   * read. A backend that made these reads genuinely asynchronous would open
-   * that window, and a concurrent mutation could be reported under this
-   * one's verb.
+   * version their own mutation produced: reread() calls this directly, so
+   * nothing interleaves between the commit and the read even though the
+   * method returning it is async. A backend that made these reads genuinely
+   * asynchronous would open that window, and a concurrent mutation could be
+   * reported under this one's verb.
    */
   readRecord(id) {
     const row = this.exec.get("SELECT * FROM records WHERE id = ?", [id]);
@@ -890,49 +912,28 @@ var SharedSqlRecordLogic = class {
         this.snapshotBeforeMutation(id, opts.snapshot);
       if (merged !== void 0)
         fts5Strategy.remove(this.exec, id);
-      const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
-      const changed = this.exec.run(`UPDATE records SET ${sets.concat(["version = version + 1", "updated_at = ?", "updated_by = ?", "updated_via = ?"]).join(", ")} WHERE id = ?${clause}`, [...values, now, opts.updatedBy ?? null, opts.updatedVia ?? null, id, ...verParams]);
-      if (changed === 0)
-        this.throwVersionConflict(id, opts.expectedVersion);
+      this.versionedUpdate(id, sets, values, opts, now);
       if (changes.associations !== void 0) {
-        this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
-        if (changes.associations.length)
-          this.insertAssociations(id, changes.associations);
+        this.replaceAssociations(id, changes.associations);
       }
       if (merged !== void 0) {
         fts5Strategy.insert(this.exec, id, JSON.stringify(merged));
         this.syncContentIndex(id, existing.typeId, merged);
       }
     });
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after mutateRecord: "${id}"`);
-    return updated;
+    return this.reread(id, "mutateRecord");
   }
   async deleteRecord(id, opts = {}) {
     if (opts.hard) {
       return this.exec.transaction(() => this.hardDeleteRecord(id, opts.expectedVersion));
-    } else {
-      this.exec.transaction(() => {
-        if (opts.snapshot)
-          this.snapshotBeforeMutation(id, opts.snapshot);
-        const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
-        const changed = this.exec.run(`UPDATE records SET deleted_at = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [
-          toMs(/* @__PURE__ */ new Date()),
-          toMs(/* @__PURE__ */ new Date()),
-          opts.updatedBy ?? null,
-          opts.updatedVia ?? null,
-          id,
-          ...verParams
-        ]);
-        if (changed === 0)
-          this.throwVersionConflict(id, opts.expectedVersion);
-      });
     }
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after deleteRecord: "${id}"`);
-    return updated;
+    const now = toMs(/* @__PURE__ */ new Date());
+    this.exec.transaction(() => {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      this.versionedUpdate(id, ["deleted_at = ?"], [now], opts, now);
+    });
+    return this.reread(id, "deleteRecord");
   }
   /**
    * Deletes a record's FTS entry, associations, versions, file-refs, sort
@@ -945,15 +946,12 @@ var SharedSqlRecordLogic = class {
    */
   hardDeleteRecord(id, expectedVersion) {
     const purged = this.readRecord(id);
-    if (expectedVersion !== void 0) {
-      if (!purged)
+    if (!purged) {
+      if (expectedVersion !== void 0)
         throw new StackNotFoundError(`Record not found: "${id}"`);
-      if (purged.version !== expectedVersion) {
-        throw new StackVersionConflictError(`Record "${id}" is at version ${purged.version}, expected ${expectedVersion}`, id, expectedVersion, purged.version);
-      }
-    }
-    if (!purged)
       return null;
+    }
+    this.checkExpectedVersion(purged, expectedVersion);
     fts5Strategy.remove(this.exec, id);
     this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
     this.exec.run("DELETE FROM versions WHERE record_id = ?", [id]);
@@ -965,15 +963,9 @@ var SharedSqlRecordLogic = class {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
-      const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
-      const changed = this.exec.run(`UPDATE records SET deleted_at = NULL, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [toMs(/* @__PURE__ */ new Date()), opts.updatedBy ?? null, opts.updatedVia ?? null, id, ...verParams]);
-      if (changed === 0)
-        this.throwVersionConflict(id, opts.expectedVersion);
+      this.versionedUpdate(id, ["deleted_at = NULL"], [], opts);
     });
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after undelete: "${id}"`);
-    return updated;
+    return this.reread(id, "undelete");
   }
   async restoreVersion(id, version, opts = {}) {
     const existing = await this.getRecord(id);
@@ -986,29 +978,12 @@ var SharedSqlRecordLogic = class {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
-      fts5Strategy.remove(this.exec, id);
-      this.exec.run(`UPDATE records SET type_id = ?, content = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ?, parent_id = ? WHERE id = ?`, [
-        target.typeId,
-        JSON.stringify(target.content),
-        toMs(/* @__PURE__ */ new Date()),
-        opts.updatedBy ?? null,
-        opts.updatedVia ?? null,
-        target.parentId ?? null,
-        id
-      ]);
+      this.rewriteContent(id, target.typeId, target.content, opts, ["parent_id = ?"], [target.parentId ?? null]);
       const applied = opts.restoreAssociations === false ? void 0 : target.associations;
-      if (applied !== void 0) {
-        this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
-        if (applied.length)
-          this.insertAssociations(id, applied);
-      }
-      fts5Strategy.insert(this.exec, id, JSON.stringify(target.content));
-      this.syncContentIndex(id, target.typeId, target.content);
+      if (applied !== void 0)
+        this.replaceAssociations(id, applied);
     });
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after restoreVersion: "${id}"`);
-    return updated;
+    return this.reread(id, "restoreVersion");
   }
   async commitMigration(id, toTypeId, content, opts = {}) {
     const existing = await this.getRecord(id);
@@ -1018,22 +993,27 @@ var SharedSqlRecordLogic = class {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
-      fts5Strategy.remove(this.exec, id);
-      this.exec.run(`UPDATE records SET type_id = ?, content = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?`, [
-        toTypeId,
-        JSON.stringify(content),
-        toMs(/* @__PURE__ */ new Date()),
-        opts.updatedBy ?? null,
-        opts.updatedVia ?? null,
-        id
-      ]);
-      fts5Strategy.insert(this.exec, id, JSON.stringify(content));
-      this.syncContentIndex(id, toTypeId, content);
+      this.rewriteContent(id, toTypeId, content, opts);
     });
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after commitMigration: "${id}"`);
-    return updated;
+    return this.reread(id, "commitMigration");
+  }
+  /**
+   * Replace a record's type and content wholesale — what restoreVersion and
+   * commitMigration each do, differing only in where the content came from
+   * and whether the container moves with it.
+   *
+   * The order is the constraint: fts5Strategy.remove() has to read the old
+   * content off the records row, so it runs before the UPDATE, and the
+   * re-index runs after. Every caller must already sit inside
+   * exec.transaction() — a failure between the two halves would otherwise
+   * leave the record unindexed.
+   */
+  rewriteContent(id, typeId, content, opts, extraSets = [], extraValues = []) {
+    const json = JSON.stringify(content);
+    fts5Strategy.remove(this.exec, id);
+    this.versionedUpdate(id, ["type_id = ?", "content = ?", ...extraSets], [typeId, json, ...extraValues], opts);
+    fts5Strategy.insert(this.exec, id, json);
+    this.syncContentIndex(id, typeId, content);
   }
   async queryRecords(query) {
     const limit = query.limit ?? 50;
@@ -1094,8 +1074,8 @@ var SharedSqlRecordLogic = class {
     return rows.map(rowToVersion);
   }
   async getVersion(id, version) {
-    const rows = this.exec.all("SELECT * FROM versions WHERE record_id = ? AND version = ?", [id, version]);
-    return rows.length ? rowToVersion(rows[0]) : null;
+    const row = this.exec.get("SELECT * FROM versions WHERE record_id = ? AND version = ?", [id, version]);
+    return row ? rowToVersion(row) : null;
   }
   /**
    * A (record_id, version) collision is rejected loudly via the UNIQUE
@@ -1106,21 +1086,8 @@ var SharedSqlRecordLogic = class {
   insertVersionRow(id, version) {
     try {
       this.exec.run(`INSERT INTO versions
-          (record_id, version, type_id, content, updated_at, entity_id,
-           updated_by, updated_via, parent_id, associations, permissions)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-        id,
-        version.version,
-        version.typeId,
-        JSON.stringify(version.content),
-        toMs(version.updatedAt),
-        version.entityId ?? null,
-        version.updatedBy ?? null,
-        version.updatedVia ?? null,
-        version.parentId ?? null,
-        version.associations ? JSON.stringify(version.associations) : null,
-        version.permissions ? JSON.stringify(version.permissions) : null
-      ]);
+          (record_id, version, ${VERSION_COLUMNS.join(", ")})
+         VALUES (?, ?, ${VERSION_COLUMNS.map(() => "?").join(", ")})`, [id, version.version, ...versionRowValues(version)]);
     } catch (err) {
       if (isUniqueConstraintViolation(err)) {
         throw new StackConflictError(`Version ${version.version} already exists for record "${id}" \u2014 a concurrent writer raced past this version. Use ifVersion to detect this before it happens.`);
@@ -1129,28 +1096,15 @@ var SharedSqlRecordLogic = class {
     }
   }
   /**
-   * Replaces every column insertVersionRow writes, so an overwritten row is
-   * indistinguishable from a freshly inserted one — a column left out here
-   * would keep the replaced row's value and surface later as a restore
-   * putting back something the snapshot never said.
+   * Replaces every column insertVersionRow writes — structurally, off the
+   * same VERSION_COLUMNS list, because a column left out here would keep
+   * the replaced row's value and surface later as a restore putting back
+   * something the snapshot never said.
    */
   overwriteVersionRow(id, version) {
     this.exec.run(`UPDATE versions
-         SET type_id = ?, content = ?, updated_at = ?, entity_id = ?,
-             updated_by = ?, updated_via = ?, parent_id = ?, associations = ?, permissions = ?
-       WHERE record_id = ? AND version = ?`, [
-      version.typeId,
-      JSON.stringify(version.content),
-      toMs(version.updatedAt),
-      version.entityId ?? null,
-      version.updatedBy ?? null,
-      version.updatedVia ?? null,
-      version.parentId ?? null,
-      version.associations ? JSON.stringify(version.associations) : null,
-      version.permissions ? JSON.stringify(version.permissions) : null,
-      id,
-      version.version
-    ]);
+         SET ${VERSION_COLUMNS.map((c) => `${c} = ?`).join(", ")}
+       WHERE record_id = ? AND version = ?`, [...versionRowValues(version), id, version.version]);
   }
   /**
    * Standalone snapshot write for tooling and tests — loud on any
@@ -1201,8 +1155,8 @@ var SharedSqlRecordLogic = class {
     this.indexedFieldsByType.set(type.id, indexedFieldKinds(schema));
   }
   async getType(id) {
-    const rows = this.exec.all("SELECT * FROM types WHERE id = ?", [id]);
-    return rows.length ? rowToType(rows[0]) : null;
+    const row = this.exec.get("SELECT * FROM types WHERE id = ?", [id]);
+    return row ? rowToType(row) : null;
   }
   async listTypes() {
     const rows = this.exec.all("SELECT * FROM types ORDER BY base_id, version");
@@ -1215,19 +1169,16 @@ var SharedSqlRecordLogic = class {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(recordId, opts.snapshot);
-      this.bumpVersion(recordId, opts);
+      this.versionedUpdate(recordId, [], [], opts);
       this.insertAssociations(recordId, [association]);
     });
-    const updated = await this.getRecord(recordId);
-    if (!updated)
-      throw new Error(`Record not found after associate: "${recordId}"`);
-    return updated;
+    return this.reread(recordId, "associate");
   }
   async dissociate(recordId, association, opts = {}) {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(recordId, opts.snapshot);
-      this.bumpVersion(recordId, opts);
+      this.versionedUpdate(recordId, [], [], opts);
       this.exec.run(`DELETE FROM associations
        WHERE record_id = ?
          AND kind = ?
@@ -1238,16 +1189,18 @@ var SharedSqlRecordLogic = class {
          AND related_ns    = ?
          AND related_stack = ?`, [recordId, association.kind, association.label, ...associationKeyColumns(association)]);
     });
-    const updated = await this.getRecord(recordId);
-    if (!updated)
-      throw new Error(`Record not found after dissociate: "${recordId}"`);
-    return updated;
+    return this.reread(recordId, "dissociate");
   }
-  bumpVersion(id, opts = {}) {
-    const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
-    const changed = this.exec.run(`UPDATE records SET version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [toMs(/* @__PURE__ */ new Date()), opts.updatedBy ?? null, opts.updatedVia ?? null, id, ...verParams]);
-    if (changed === 0)
-      this.throwVersionConflict(id, opts.expectedVersion);
+  /**
+   * Swap a record's association set for `associations` wholesale — the
+   * "replace, don't merge" semantics a change set's association list and a
+   * version snapshot's both carry. Caller-transactional, like every write
+   * below.
+   */
+  replaceAssociations(recordId, associations) {
+    this.exec.run("DELETE FROM associations WHERE record_id = ?", [recordId]);
+    if (associations.length)
+      this.insertAssociations(recordId, associations);
   }
   /**
    * FK enforcement (PRAGMA_FOREIGN_KEYS_ON) means inserting an
@@ -1319,6 +1272,134 @@ var SharedSqlRecordLogic = class {
     return this.getIndexedFields(record.typeId).get(field);
   }
 };
+
+// ../sqlite-shared/dist/record-adapter.js
+var SQLITE_RECORD_CAPABILITIES = {
+  filter: {
+    content: "path",
+    contentPresent: true,
+    search: true
+  },
+  sort: {
+    fields: ["createdAt", "updatedAt", "version"],
+    contentField: true
+  },
+  limits: {
+    attachmentBytes: null,
+    contentBytes: null
+  }
+};
+var SharedSqlRecordAdapter = class {
+  capabilities = SQLITE_RECORD_CAPABILITIES;
+  ownerEntityId;
+  timezone;
+  record;
+  constructor(exec, config) {
+    this.record = new SharedSqlRecordLogic({ exec });
+    this.ownerEntityId = config.entityId;
+    this.timezone = config.timezone;
+  }
+  // -------------------------------------------------------
+  // Records
+  // -------------------------------------------------------
+  createRecord(record) {
+    return this.record.createRecord(record);
+  }
+  getRecord(id) {
+    return this.record.getRecord(id);
+  }
+  mutateRecord(id, changes, opts) {
+    return this.record.mutateRecord(id, changes, opts);
+  }
+  deleteRecord(id, opts) {
+    return this.record.deleteRecord(id, opts);
+  }
+  undeleteRecord(id, opts) {
+    return this.record.undeleteRecord(id, opts);
+  }
+  restoreVersion(id, version, opts) {
+    return this.record.restoreVersion(id, version, opts);
+  }
+  commitMigration(id, toTypeId, content, opts) {
+    return this.record.commitMigration(id, toTypeId, content, opts);
+  }
+  queryRecords(query) {
+    return this.record.queryRecords(query);
+  }
+  deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds) {
+    return this.record.deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds);
+  }
+  // -------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------
+  getVersions(id) {
+    return this.record.getVersions(id);
+  }
+  getVersion(id, version) {
+    return this.record.getVersion(id, version);
+  }
+  saveVersion(id, version) {
+    return this.record.saveVersion(id, version);
+  }
+  // -------------------------------------------------------
+  // Types
+  // -------------------------------------------------------
+  saveType(type) {
+    return this.record.saveType(type);
+  }
+  getType(id) {
+    return this.record.getType(id);
+  }
+  listTypes() {
+    return this.record.listTypes();
+  }
+  // -------------------------------------------------------
+  // Associations
+  // -------------------------------------------------------
+  associate(recordId, association, opts) {
+    return this.record.associate(recordId, association, opts);
+  }
+  dissociate(recordId, association, opts) {
+    return this.record.dissociate(recordId, association, opts);
+  }
+};
+var lockPathFor = (dbPath) => `${dbPath}.lock`;
+var isProcessAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== "ESRCH";
+  }
+};
+var acquireLock = (dbPath, force) => {
+  const lockPath = lockPathFor(dbPath);
+  const info = existsSync(lockPath) ? readLock(lockPath) : null;
+  if (info) {
+    const ownedBySelf = info.pid === process.pid;
+    if (!ownedBySelf && !force && isProcessAlive(info.pid)) {
+      throw new Error(`Stack database at "${dbPath}" is in use by another process (pid ${info.pid}). Connect via its server instead, or pass { force: true } to override. If no such process is running, remove "${lockPath}".`);
+    }
+  }
+  writeFileSync(lockPath, JSON.stringify({ pid: process.pid }));
+};
+var readLock = (lockPath) => {
+  try {
+    const info = JSON.parse(readFileSync(lockPath, "utf-8"));
+    return typeof info?.pid === "number" ? info : null;
+  } catch {
+    return null;
+  }
+};
+var releaseLock = (dbPath) => {
+  const lockPath = lockPathFor(dbPath);
+  if (!existsSync(lockPath))
+    return;
+  const info = readLock(lockPath);
+  if (!info || info.pid === process.pid)
+    unlinkSync(lockPath);
+};
+var hashToken = (token) => createHash("sha256").update(token).digest("hex");
 var SharedTokenLogic = class {
   deps;
   constructor(deps) {
@@ -1330,7 +1411,7 @@ var SharedTokenLogic = class {
   async createToken(principalId, opts = {}) {
     const id = randomBytes(8).toString("hex");
     const token = randomBytes(32).toString("hex");
-    const tokenHash = createHash("sha256").update(token).digest("hex");
+    const tokenHash = hashToken(token);
     this.exec.run("INSERT INTO tokens (id, token_hash, principal_id, subject_id, label, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)", [
       id,
       tokenHash,
@@ -1345,7 +1426,7 @@ var SharedTokenLogic = class {
     return { id, token };
   }
   async lookupToken(token) {
-    const hash = createHash("sha256").update(token).digest("hex");
+    const hash = hashToken(token);
     const row = this.exec.get("SELECT principal_id, subject_id, expires_at FROM tokens WHERE token_hash = ?", [hash]);
     if (!row)
       return null;
@@ -1439,33 +1520,26 @@ var NativeTokenStore = class _NativeTokenStore {
 };
 
 // src/index.ts
-var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
-  constructor(path) {
+var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter extends SharedSqlRecordAdapter {
+  constructor(path, db, exec, config) {
+    super(exec, config);
     this.path = path;
+    this.db = db;
   }
   path;
-  capabilities = {
-    filter: {
-      content: "path",
-      contentPresent: true,
-      search: true
-    },
-    sort: {
-      fields: ["createdAt", "updatedAt", "version"],
-      contentField: true
-    },
-    limits: {
-      attachmentBytes: null,
-      contentBytes: null
-    }
-  };
-  ownerEntityId;
-  timezone;
   db;
-  record;
-  wire() {
-    const exec = new NativeSqliteExecutor(this.db);
-    this.record = new SharedSqlRecordLogic({ exec });
+  /**
+   * Takes the storage-ownership lock, opens the file, and brings the
+   * schema up. Shared by initialize() and open(), which differ only in
+   * whether the file may already exist and in where the config record
+   * comes from.
+   */
+  static attach(path, force) {
+    acquireLock(path, force);
+    const db = new DatabaseSync(path);
+    const exec = new NativeSqliteExecutor(db);
+    applyRecordSchema(exec);
+    return [db, exec];
   }
   /**
    * Initialize a new stack database. Fails if the file already exists —
@@ -1477,18 +1551,9 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
         `Cannot initialize: database already exists at "${opts.path}". Use NativeSQLiteRecordAdapter.open() instead.`
       );
     }
-    acquireLock(opts.path, opts.force);
-    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
-    adapter.db = new DatabaseSync(opts.path);
-    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
-    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
-    adapter.db.exec(RECORD_SCHEMA_SQL);
-    adapter.db.exec(FTS5_SCHEMA_SQL);
-    adapter.wire();
-    insertConfigRecord(new NativeSqliteExecutor(adapter.db), opts.entityId, opts.timezone);
-    adapter.ownerEntityId = opts.entityId;
-    adapter.timezone = opts.timezone;
-    return adapter;
+    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
+    const config = insertConfigRecord(exec, opts.entityId, opts.timezone);
+    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, config);
   }
   /**
    * Open an existing stack database. Fails if the file does not exist —
@@ -1500,81 +1565,8 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
         `Cannot open: no database found at "${opts.path}". Use NativeSQLiteRecordAdapter.initialize() to create one.`
       );
     }
-    acquireLock(opts.path, opts.force);
-    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
-    adapter.db = new DatabaseSync(opts.path);
-    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
-    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
-    adapter.db.exec(RECORD_SCHEMA_SQL);
-    adapter.db.exec(FTS5_SCHEMA_SQL);
-    adapter.wire();
-    const config = readStackConfig(new NativeSqliteExecutor(adapter.db));
-    adapter.ownerEntityId = config.entityId;
-    adapter.timezone = config.timezone;
-    return adapter;
-  }
-  // -------------------------------------------------------
-  // Records
-  // -------------------------------------------------------
-  createRecord(record) {
-    return this.record.createRecord(record);
-  }
-  getRecord(id) {
-    return this.record.getRecord(id);
-  }
-  mutateRecord(id, changes, opts) {
-    return this.record.mutateRecord(id, changes, opts);
-  }
-  deleteRecord(id, opts) {
-    return this.record.deleteRecord(id, opts);
-  }
-  undeleteRecord(id, opts) {
-    return this.record.undeleteRecord(id, opts);
-  }
-  restoreVersion(id, version, opts) {
-    return this.record.restoreVersion(id, version, opts);
-  }
-  commitMigration(id, toTypeId, content, opts) {
-    return this.record.commitMigration(id, toTypeId, content, opts);
-  }
-  queryRecords(query) {
-    return this.record.queryRecords(query);
-  }
-  deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds) {
-    return this.record.deleteUnreferencedAttachmentRecords(fileId, metadataTypeIds);
-  }
-  // -------------------------------------------------------
-  // Versions
-  // -------------------------------------------------------
-  getVersions(id) {
-    return this.record.getVersions(id);
-  }
-  getVersion(id, version) {
-    return this.record.getVersion(id, version);
-  }
-  saveVersion(id, version) {
-    return this.record.saveVersion(id, version);
-  }
-  // -------------------------------------------------------
-  // Types
-  // -------------------------------------------------------
-  saveType(type) {
-    return this.record.saveType(type);
-  }
-  getType(id) {
-    return this.record.getType(id);
-  }
-  listTypes() {
-    return this.record.listTypes();
-  }
-  // -------------------------------------------------------
-  // Associations
-  // -------------------------------------------------------
-  associate(recordId, association, opts) {
-    return this.record.associate(recordId, association, opts);
-  }
-  dissociate(recordId, association, opts) {
-    return this.record.dissociate(recordId, association, opts);
+    const [db, exec] = _NativeSQLiteRecordAdapter.attach(opts.path, opts.force);
+    return new _NativeSQLiteRecordAdapter(opts.path, db, exec, readStackConfig(exec));
   }
   // -------------------------------------------------------
   // Lifecycle