@haverstack/record-adapter-sqlite 0.20.0 → 0.22.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,7 @@ 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 SORT_FIELDS = NATIVE_SORT_FIELDS;
 var toBase64 = (text) => {
   const bytes = new TextEncoder().encode(text);
   let binary = "";
@@ -367,17 +367,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 +399,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 +445,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,46 +644,6 @@ 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");
@@ -723,6 +671,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 +719,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: patchContent/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 +745,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 +843,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]);
@@ -848,55 +856,70 @@ var SharedSqlRecordLogic = class {
     const associations = this.getAssociationsForRecord(id);
     return rowToRecord(row, associations);
   }
-  async patchContent(id, patch, opts = {}) {
+  /**
+   * Apply a change set in one transaction: one UPDATE over the record row
+   * with only the columns the change set names, the association set
+   * replaced when it carries one, and the snapshot written alongside — so
+   * one call is one version whatever it moved.
+   *
+   * The expectedVersion check is standalone rather than folded into the
+   * UPDATE alone, because a content change needs fts.remove() to run
+   * *before* the records-table content changes. The guard is still in the
+   * UPDATE's WHERE, so a writer that slipped in between the read and the
+   * write is caught there rather than overwriting.
+   */
+  async mutateRecord(id, changes, opts = {}) {
     const existing = await this.getRecord(id);
     if (!existing)
-      throw new Error(`Record not found: "${id}"`);
+      throw new StackNotFoundError(`Record not found: "${id}"`);
     this.checkExpectedVersion(existing, opts.expectedVersion);
-    const merged = applyMergePatch(existing.content, patch);
+    const merged = changes.contentPatch ? applyMergePatch(existing.content, changes.contentPatch) : void 0;
+    const sets = [];
+    const values = [];
+    if (merged !== void 0) {
+      sets.push("content = ?");
+      values.push(JSON.stringify(merged));
+    }
+    if (changes.parentId !== void 0) {
+      sets.push("parent_id = ?");
+      values.push(changes.parentId);
+    }
+    if (changes.permissions !== void 0) {
+      sets.push("permissions = ?");
+      values.push(changes.permissions.length ? JSON.stringify(changes.permissions) : null);
+    }
+    const now = toMs(/* @__PURE__ */ new Date());
+    if (changes.unlisted !== void 0) {
+      sets.push("unlisted_at = ?");
+      values.push(changes.unlisted ? now : null);
+    }
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
-      fts5Strategy.remove(this.exec, id);
-      this.exec.run(`UPDATE records SET content = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?`, [
-        JSON.stringify(merged),
-        toMs(/* @__PURE__ */ new Date()),
-        opts.updatedBy ?? null,
-        opts.updatedVia ?? null,
-        id
-      ]);
-      fts5Strategy.insert(this.exec, id, JSON.stringify(merged));
-      this.syncContentIndex(id, existing.typeId, merged);
+      if (merged !== void 0)
+        fts5Strategy.remove(this.exec, id);
+      this.versionedUpdate(id, sets, values, opts, now);
+      if (changes.associations !== void 0) {
+        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 patchContent: "${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
@@ -909,15 +932,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]);
@@ -929,79 +949,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);
-    });
-    const updated = await this.getRecord(id);
-    if (!updated)
-      throw new Error(`Record not found after undelete: "${id}"`);
-    return updated;
-  }
-  async setPermissions(id, permissions, opts = {}) {
-    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 permissions = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [
-        permissions.length ? JSON.stringify(permissions) : null,
-        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 setPermissions: "${id}"`);
-    return updated;
-  }
-  async setUnlisted(id, unlisted, opts = {}) {
-    this.exec.transaction(() => {
-      if (opts.snapshot)
-        this.snapshotBeforeMutation(id, opts.snapshot);
-      const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
-      const now = toMs(/* @__PURE__ */ new Date());
-      const changed = this.exec.run(`UPDATE records SET unlisted_at = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [
-        unlisted ? now : null,
-        now,
-        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 setUnlisted: "${id}"`);
-    return updated;
-  }
-  async setParent(id, parentId, opts = {}) {
-    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 parent_id = ?, version = version + 1, updated_at = ?, updated_by = ?, updated_via = ? WHERE id = ?${clause}`, [
-        parentId,
-        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 setParent: "${id}"`);
-    return updated;
+    return this.reread(id, "undelete");
   }
   async restoreVersion(id, version, opts = {}) {
     const existing = await this.getRecord(id);
@@ -1014,28 +964,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
-      ]);
-      if (target.associations !== void 0) {
-        this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
-        if (target.associations.length)
-          this.insertAssociations(id, target.associations);
-      }
-      fts5Strategy.insert(this.exec, id, JSON.stringify(target.content));
-      this.syncContentIndex(id, target.typeId, target.content);
+      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.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);
@@ -1045,22 +979,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;
@@ -1121,8 +1060,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
@@ -1133,21 +1072,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.`);
@@ -1156,28 +1082,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
@@ -1228,8 +1141,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");
@@ -1242,19 +1155,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 = ?
@@ -1265,16 +1175,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
@@ -1346,6 +1258,43 @@ var SharedSqlRecordLogic = class {
     return this.getIndexedFields(record.typeId).get(field);
   }
 };
+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) {
@@ -1357,7 +1306,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,
@@ -1372,7 +1321,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;
@@ -1549,8 +1498,8 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
   getRecord(id) {
     return this.record.getRecord(id);
   }
-  patchContent(id, patch, opts) {
-    return this.record.patchContent(id, patch, opts);
+  mutateRecord(id, changes, opts) {
+    return this.record.mutateRecord(id, changes, opts);
   }
   deleteRecord(id, opts) {
     return this.record.deleteRecord(id, opts);
@@ -1558,15 +1507,6 @@ var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
   undeleteRecord(id, opts) {
     return this.record.undeleteRecord(id, opts);
   }
-  setPermissions(id, permissions, opts) {
-    return this.record.setPermissions(id, permissions, opts);
-  }
-  setUnlisted(id, unlisted, opts) {
-    return this.record.setUnlisted(id, unlisted, opts);
-  }
-  setParent(id, parentId, opts) {
-    return this.record.setParent(id, parentId, opts);
-  }
   restoreVersion(id, version, opts) {
     return this.record.restoreVersion(id, version, opts);
   }