@haverstack/record-adapter-do-sqlite 0.14.0 → 0.15.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { StackVersionConflictError, StackNotFoundError, StackConflictError, applyMergePatch, StackQueryError } from '@haverstack/core';
+import { StackNotFoundError, StackConflictError, applyMergePatch, StackVersionConflictError, StackQueryError, NATIVE_SORT_FIELDS } from '@haverstack/core';
 import { contentSortEntry, parseContentFilterKey, contentSortKey } from '@haverstack/core/adapter';
 
 // ../sqlite-shared/dist/schema.js
@@ -132,7 +132,7 @@ var FTS5_SCHEMA_SQL = `
   );
 `;
 var PRAGMA_FOREIGN_KEYS_ON = `PRAGMA foreign_keys = ON;`;
-var SORT_FIELDS = ["createdAt", "updatedAt", "version"];
+var SORT_FIELDS = NATIVE_SORT_FIELDS;
 var toBase64 = (text) => {
   const bytes = new TextEncoder().encode(text);
   let binary = "";
@@ -348,17 +348,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");
@@ -367,49 +380,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);
   }
@@ -438,7 +426,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;
@@ -664,6 +652,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)) {
@@ -689,26 +700,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).
@@ -719,7 +726,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
@@ -776,11 +824,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]);
@@ -831,49 +879,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
@@ -886,15 +913,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]);
@@ -906,15 +930,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);
@@ -927,29 +945,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);
@@ -959,22 +960,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;
@@ -1035,8 +1041,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
@@ -1047,21 +1053,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.`);
@@ -1070,28 +1063,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
@@ -1142,8 +1122,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");
@@ -1156,19 +1136,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 = ?
@@ -1179,16 +1156,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