velocious 1.0.670 → 1.0.671

package/build/sync/server-sequence-allocator.js

@@ -38,6 +38,7 @@ export default class ServerSequenceAllocator {
     this.tableName = tableName
     this._memorySequence = 0
     this._isReady = false
+    this._transactionalReadinessPending = false
     /** @type {Promise<void> | null} */
     this._readyPromise = null
   }
@@ -110,10 +111,28 @@ export default class ServerSequenceAllocator {
       // DDL joins any transaction already open on this connection (the mixin's
       // beforeCreate allocation always runs inside the record save transaction),
       // and on transactional-DDL databases (MSSQL, PostgreSQL, SQLite) a rollback
-      // of that outer transaction removes the just-created table again. Only
-      // cache readiness when the table was not created inside an active
-      // transaction; otherwise the next allocation re-verifies the table.
-      if (!created || !db.insideTransaction()) this._isReady = true
+      // of that outer transaction removes the just-created table again. Keep
+      // readiness pending for every later allocation in that same transaction;
+      // otherwise its table-exists check would incorrectly cache readiness before
+      // the outer transaction commits.
+      if (!created) {
+        if (!this._transactionalReadinessPending) this._isReady = true
+        return
+      }
+
+      if (db.insideTransaction()) {
+        this._transactionalReadinessPending = true
+
+        void db.transactionCompletion().then(() => {
+          // The transaction may have committed or rolled back. Re-check once
+          // on the next allocation, then cache the durable outcome normally.
+          this._isReady = false
+          this._transactionalReadinessPending = false
+        })
+      } else {
+        this._isReady = true
+        this._transactionalReadinessPending = false
+      }
     }, connection)
 
     try {

package/build/sync/sync-publisher.js

@@ -4,12 +4,11 @@ import Configuration from "../configuration.js"
 import Logger from "../logger.js"
 import {scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 import restArgsError from "../utils/rest-args-error.js"
-import sha256Hex from "../utils/sha256-hex.js"
-import stableJsonStringify from "../utils/stable-json.js"
 
 import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
-import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
+import {deliverDeclaredBroadcasts} from "./sync-change-fanout.js"
 import {isPublishingSuppressed} from "./sync-publish-suppression.js"
+import {upsertServerOriginSyncRow} from "./upsert-server-origin-sync-row.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
 
 /** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
@@ -213,8 +212,13 @@ export default class SyncPublisher {
 
       await record.connection().afterCommit(async () => {
         try {
-          const scopeColumnNames = resourceConfig.scopePlan.map(({columnName}) => columnName)
-          const syncRow = await this.upsertPublishedSyncRow(attributes, operationScope, scopeColumnNames)
+          const syncRow = await upsertServerOriginSyncRow({
+            actorForeignKeyColumn: this.config.actorForeignKeyColumn,
+            attributes,
+            persistenceModel: operationScope,
+            scopeColumnNames: resourceConfig.scopePlan.map(({columnName}) => columnName),
+            syncModel: this.config.syncModel
+          })
 
           await this.broadcaster()({
             body: {
@@ -362,55 +366,6 @@ export default class SyncPublisher {
     return entry
   }
 
-  /**
-   * Upserts the published server-origin sync row for a resource identity:
-   * server-origin rows carry a null actor column (no device to echo the
-   * change back to), so repeated server changes to one complete resource and
-   * scope identity reuse and re-sequence one feed row. A database advisory
-   * lock serializes reconciliation plus the shared upsert because unique
-   * constraints containing nullable actor/scope columns do not enforce this
-   * identity portably across supported databases. Reconciliation retains the
-   * row with the newest feed sequence (then lowest id for a deterministic tie)
-   * and removes older matching server-origin rows before applying the current
-   * mutation.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} attributes - Snapshotted sync row attributes.
-   * @param {ReturnType<typeof JSON.parse>} syncModel - Operation-bound or static Sync model interface.
-   * @param {string[]} scopeColumnNames - Persisted scope columns participating in the complete identity.
-   * @returns {Promise<ReturnType<typeof JSON.parse>>} Upserted sync row.
-   */
-  async upsertPublishedSyncRow(attributes, syncModel = this.config.syncModel, scopeColumnNames = []) {
-    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
-    const identity = {
-      [this.config.actorForeignKeyColumn]: null,
-      resource_id: attributes.resource_id,
-      resource_type: attributes.resource_type
-    }
-
-    for (const columnName of scopeColumnNames) {
-      if (!Object.hasOwn(attributes, columnName)) {
-        throw new Error(`Published sync row identity is missing the scope column ${columnName}`)
-      }
-
-      identity[columnName] = attributes[columnName]
-    }
-
-    return await this.config.syncModel.withAdvisoryLock(syncPublisherIdentityLockName(identity), async () => {
-      const matchingSyncs = await syncModel
-        .where(identity)
-        .toArray()
-
-      matchingSyncs.sort(comparePublishedSyncRowsByRecency)
-
-      const [existingSync, ...duplicateSyncs] = matchingSyncs
-
-      for (const duplicateSync of duplicateSyncs) {
-        await duplicateSync.destroy()
-      }
-
-      return await upsertSyncRow({attributes, existingSync, syncModel})
-    }, {dedicatedConnection: true})
-  }
-
   /**
    * Returns the broadcaster delivering declared broadcasts: the injected one,
    * or the configuration's channel broadcast awaited through the pending
@@ -465,40 +420,6 @@ export default class SyncPublisher {
   }
 }
 
-/**
- * Returns a deterministic, MySQL-safe advisory-lock name for one complete
- * server-origin publisher identity. Stable JSON preserves null actor/scope
- * components distinctly from strings, and the truncated SHA-256 digest keeps
- * the final name below MySQL/MariaDB's 64-character `GET_LOCK` limit.
- * @param {Record<string, ReturnType<typeof JSON.parse>>} identity - Complete sync-row identity in column form.
- * @returns {string} Advisory-lock name.
- */
-function syncPublisherIdentityLockName(identity) {
-  const hash = sha256Hex(stableJsonStringify(identity)).slice(0, 32)
-
-  return `vsp:${hash}`
-}
-
-/**
- * Orders matching published rows by the feed's public recency contract so
- * legacy duplicates have one deterministic survivor. Server sequences are
- * positive and monotonic; a legacy null sequence is older than any assigned
- * sequence, and the immutable row id breaks otherwise-equal ties.
- * @param {ReturnType<typeof JSON.parse>} left - First matching sync row.
- * @param {ReturnType<typeof JSON.parse>} right - Second matching sync row.
- * @returns {number} Sort comparison with the canonical survivor first.
- */
-function comparePublishedSyncRowsByRecency(left, right) {
-  const leftSequence = left.serverSequence()
-  const rightSequence = right.serverSequence()
-
-  if (leftSequence === null && rightSequence !== null) return 1
-  if (leftSequence !== null && rightSequence === null) return -1
-  if (leftSequence !== rightSequence) return rightSequence - leftSequence
-
-  return left.id().localeCompare(right.id())
-}
-
 /**
  * Resolves a model class's active publish declaration from `static sync`.
  * Opted-out (`publish: false`) and undeclared models resolve to null; every

package/build/sync/upsert-server-origin-sync-row.js

@@ -0,0 +1,158 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+import sha256Hex from "../utils/sha256-hex.js"
+import stableJsonStringify from "../utils/stable-json.js"
+
+import {upsertSyncRow} from "./sync-change-fanout.js"
+import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
+
+/**
+ * Atomically reconciles and upserts one server-origin sync row by its complete,
+ * null-safe logical identity. The identity contains the null actor, resource
+ * type/id, and either every scope column declared by the sync model or the
+ * caller's explicit effective scope columns for a supported legacy publisher.
+ * A stable portable advisory lock serializes runtime publication and maintenance/backfill calls;
+ * legacy duplicates converge to the newest server sequence, then the lowest
+ * immutable id, before the survivor is updated and re-sequenced.
+ *
+ * The lock is acquired through the static sync model on a dedicated connection.
+ * `persistenceModel` may be an operation-bound model facade so reads/writes keep
+ * their owning operation while sharing the same identity lock as ordinary
+ * publisher calls.
+ * @param {object} args - Persistence arguments.
+ * @param {string} [args.actorForeignKeyColumn] - Persisted actor foreign-key column.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} args.attributes - Complete sync-row mutation attributes.
+ * @param {ReturnType<typeof JSON.parse>} [args.persistenceModel] - Optional operation-bound model used for row reads/writes.
+ * @param {string[]} [args.scopeColumnNames] - Exact persisted scope columns overriding model declarations for a supported legacy publisher identity.
+ * @param {ReturnType<typeof JSON.parse>} args.syncModel - Static sync model owning scope metadata and the advisory lock.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} Created or reconciled sync row.
+ */
+export async function upsertServerOriginSyncRow({
+  actorForeignKeyColumn = "authentication_token_id",
+  attributes,
+  persistenceModel,
+  scopeColumnNames,
+  syncModel,
+  ...restArgs
+}) {
+  restArgsError(restArgs)
+
+  if (typeof actorForeignKeyColumn !== "string" || !actorForeignKeyColumn) {
+    throw new Error("Server-origin sync row actorForeignKeyColumn must be a non-empty string")
+  }
+  if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) {
+    throw new Error("Server-origin sync row attributes must be a plain object")
+  }
+  if (!Object.hasOwn(attributes, actorForeignKeyColumn) || attributes[actorForeignKeyColumn] === undefined) {
+    throw new Error(`Server-origin sync row identity must include the actor column ${actorForeignKeyColumn}`)
+  }
+  if (attributes[actorForeignKeyColumn] !== null) {
+    throw new Error(`Server-origin sync row actor column ${actorForeignKeyColumn} must be null`)
+  }
+
+  validateRequiredIdentityString({attributes, columnName: "resource_id"})
+  validateRequiredIdentityString({attributes, columnName: "resource_type"})
+
+  /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
+  const identity = {
+    [actorForeignKeyColumn]: null,
+    resource_id: attributes.resource_id,
+    resource_type: attributes.resource_type
+  }
+  const attributeToColumnName = syncModel.getAttributeNameToColumnNameMap()
+  const scopeColumns = new Set(scopeColumnNames || [])
+
+  if (scopeColumnNames === undefined) {
+    for (const scopeAttribute of declaredSyncScopeAttributes(syncModel) || []) {
+      const columnName = attributeToColumnName[scopeAttribute]
+
+      if (!columnName) {
+        throw new Error(`${syncModel.name} declares the sync scope attribute ${scopeAttribute} but has no matching column for it`)
+      }
+
+      scopeColumns.add(columnName)
+    }
+  }
+
+  for (const columnName of scopeColumns) {
+    if (typeof columnName !== "string" || !columnName || !Object.values(attributeToColumnName).includes(columnName)) {
+      throw new Error(`Server-origin sync row received an unknown scope column: ${String(columnName)}`)
+    }
+
+    if (!Object.hasOwn(attributes, columnName) || attributes[columnName] === undefined) {
+      throw new Error(`Server-origin sync row identity must include the declared scope column ${columnName}`)
+    }
+
+    const value = attributes[columnName]
+
+    if (value !== null && typeof value !== "string" && (typeof value !== "number" || !Number.isFinite(value))) {
+      throw new Error(`Server-origin sync row scope column ${columnName} must be a string, finite number, or null`)
+    }
+
+    identity[columnName] = value
+  }
+
+  const rowModel = persistenceModel || syncModel
+
+  return await syncModel.withAdvisoryLock(serverOriginSyncRowLockName(identity), async () => {
+    const matchingSyncs = await rowModel
+      .where(identity)
+      .toArray()
+
+    matchingSyncs.sort(compareServerOriginSyncRowsByRecency)
+
+    const [existingSync, ...duplicateSyncs] = matchingSyncs
+
+    for (const duplicateSync of duplicateSyncs) {
+      await duplicateSync.destroy()
+    }
+
+    return await upsertSyncRow({attributes, existingSync, syncModel: rowModel})
+  }, {dedicatedConnection: true})
+}
+
+/**
+ * Validates one required string component of the server-origin identity.
+ * @param {{attributes: Record<string, ReturnType<typeof JSON.parse>>, columnName: "resource_id" | "resource_type"}} args - Attributes and required column.
+ * @returns {void}
+ */
+function validateRequiredIdentityString({attributes, columnName}) {
+  const value = attributes[columnName]
+
+  if (typeof value !== "string" || !value) {
+    throw new Error(`Server-origin sync row ${columnName} must be a non-empty string`)
+  }
+}
+
+/**
+ * Returns the stable MySQL-safe advisory-lock name shared by every caller of a
+ * complete server-origin identity. Stable JSON preserves null identity values,
+ * while the truncated SHA-256 digest keeps the name under GET_LOCK's limit.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} identity - Complete sync-row identity in column form.
+ * @returns {string} Advisory-lock name.
+ */
+function serverOriginSyncRowLockName(identity) {
+  const hash = sha256Hex(stableJsonStringify(identity)).slice(0, 32)
+
+  return `vsp:${hash}`
+}
+
+/**
+ * Orders matching rows with the canonical deterministic survivor first:
+ * newest server sequence, then lowest immutable id. A null legacy sequence is
+ * older than every assigned sequence.
+ * @param {ReturnType<typeof JSON.parse>} left - First matching sync row.
+ * @param {ReturnType<typeof JSON.parse>} right - Second matching sync row.
+ * @returns {number} Sort comparison.
+ */
+function compareServerOriginSyncRowsByRecency(left, right) {
+  const leftSequence = left.serverSequence()
+  const rightSequence = right.serverSequence()
+
+  if (leftSequence === null && rightSequence !== null) return 1
+  if (leftSequence !== null && rightSequence === null) return -1
+  if (leftSequence !== rightSequence) return rightSequence - leftSequence
+
+  return left.id().localeCompare(right.id())
+}

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.670",
+  "version": "1.0.671",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/sync/server-sequence-allocator.js

@@ -38,6 +38,7 @@ export default class ServerSequenceAllocator {
     this.tableName = tableName
     this._memorySequence = 0
     this._isReady = false
+    this._transactionalReadinessPending = false
     /** @type {Promise<void> | null} */
     this._readyPromise = null
   }
@@ -110,10 +111,28 @@ export default class ServerSequenceAllocator {
       // DDL joins any transaction already open on this connection (the mixin's
       // beforeCreate allocation always runs inside the record save transaction),
       // and on transactional-DDL databases (MSSQL, PostgreSQL, SQLite) a rollback
-      // of that outer transaction removes the just-created table again. Only
-      // cache readiness when the table was not created inside an active
-      // transaction; otherwise the next allocation re-verifies the table.
-      if (!created || !db.insideTransaction()) this._isReady = true
+      // of that outer transaction removes the just-created table again. Keep
+      // readiness pending for every later allocation in that same transaction;
+      // otherwise its table-exists check would incorrectly cache readiness before
+      // the outer transaction commits.
+      if (!created) {
+        if (!this._transactionalReadinessPending) this._isReady = true
+        return
+      }
+
+      if (db.insideTransaction()) {
+        this._transactionalReadinessPending = true
+
+        void db.transactionCompletion().then(() => {
+          // The transaction may have committed or rolled back. Re-check once
+          // on the next allocation, then cache the durable outcome normally.
+          this._isReady = false
+          this._transactionalReadinessPending = false
+        })
+      } else {
+        this._isReady = true
+        this._transactionalReadinessPending = false
+      }
     }, connection)
 
     try {

package/src/sync/sync-publisher.js

@@ -4,12 +4,11 @@ import Configuration from "../configuration.js"
 import Logger from "../logger.js"
 import {scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 import restArgsError from "../utils/rest-args-error.js"
-import sha256Hex from "../utils/sha256-hex.js"
-import stableJsonStringify from "../utils/stable-json.js"
 
 import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
-import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
+import {deliverDeclaredBroadcasts} from "./sync-change-fanout.js"
 import {isPublishingSuppressed} from "./sync-publish-suppression.js"
+import {upsertServerOriginSyncRow} from "./upsert-server-origin-sync-row.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
 
 /** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
@@ -213,8 +212,13 @@ export default class SyncPublisher {
 
       await record.connection().afterCommit(async () => {
         try {
-          const scopeColumnNames = resourceConfig.scopePlan.map(({columnName}) => columnName)
-          const syncRow = await this.upsertPublishedSyncRow(attributes, operationScope, scopeColumnNames)
+          const syncRow = await upsertServerOriginSyncRow({
+            actorForeignKeyColumn: this.config.actorForeignKeyColumn,
+            attributes,
+            persistenceModel: operationScope,
+            scopeColumnNames: resourceConfig.scopePlan.map(({columnName}) => columnName),
+            syncModel: this.config.syncModel
+          })
 
           await this.broadcaster()({
             body: {
@@ -362,55 +366,6 @@ export default class SyncPublisher {
     return entry
   }
 
-  /**
-   * Upserts the published server-origin sync row for a resource identity:
-   * server-origin rows carry a null actor column (no device to echo the
-   * change back to), so repeated server changes to one complete resource and
-   * scope identity reuse and re-sequence one feed row. A database advisory
-   * lock serializes reconciliation plus the shared upsert because unique
-   * constraints containing nullable actor/scope columns do not enforce this
-   * identity portably across supported databases. Reconciliation retains the
-   * row with the newest feed sequence (then lowest id for a deterministic tie)
-   * and removes older matching server-origin rows before applying the current
-   * mutation.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} attributes - Snapshotted sync row attributes.
-   * @param {ReturnType<typeof JSON.parse>} syncModel - Operation-bound or static Sync model interface.
-   * @param {string[]} scopeColumnNames - Persisted scope columns participating in the complete identity.
-   * @returns {Promise<ReturnType<typeof JSON.parse>>} Upserted sync row.
-   */
-  async upsertPublishedSyncRow(attributes, syncModel = this.config.syncModel, scopeColumnNames = []) {
-    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
-    const identity = {
-      [this.config.actorForeignKeyColumn]: null,
-      resource_id: attributes.resource_id,
-      resource_type: attributes.resource_type
-    }
-
-    for (const columnName of scopeColumnNames) {
-      if (!Object.hasOwn(attributes, columnName)) {
-        throw new Error(`Published sync row identity is missing the scope column ${columnName}`)
-      }
-
-      identity[columnName] = attributes[columnName]
-    }
-
-    return await this.config.syncModel.withAdvisoryLock(syncPublisherIdentityLockName(identity), async () => {
-      const matchingSyncs = await syncModel
-        .where(identity)
-        .toArray()
-
-      matchingSyncs.sort(comparePublishedSyncRowsByRecency)
-
-      const [existingSync, ...duplicateSyncs] = matchingSyncs
-
-      for (const duplicateSync of duplicateSyncs) {
-        await duplicateSync.destroy()
-      }
-
-      return await upsertSyncRow({attributes, existingSync, syncModel})
-    }, {dedicatedConnection: true})
-  }
-
   /**
    * Returns the broadcaster delivering declared broadcasts: the injected one,
    * or the configuration's channel broadcast awaited through the pending
@@ -465,40 +420,6 @@ export default class SyncPublisher {
   }
 }
 
-/**
- * Returns a deterministic, MySQL-safe advisory-lock name for one complete
- * server-origin publisher identity. Stable JSON preserves null actor/scope
- * components distinctly from strings, and the truncated SHA-256 digest keeps
- * the final name below MySQL/MariaDB's 64-character `GET_LOCK` limit.
- * @param {Record<string, ReturnType<typeof JSON.parse>>} identity - Complete sync-row identity in column form.
- * @returns {string} Advisory-lock name.
- */
-function syncPublisherIdentityLockName(identity) {
-  const hash = sha256Hex(stableJsonStringify(identity)).slice(0, 32)
-
-  return `vsp:${hash}`
-}
-
-/**
- * Orders matching published rows by the feed's public recency contract so
- * legacy duplicates have one deterministic survivor. Server sequences are
- * positive and monotonic; a legacy null sequence is older than any assigned
- * sequence, and the immutable row id breaks otherwise-equal ties.
- * @param {ReturnType<typeof JSON.parse>} left - First matching sync row.
- * @param {ReturnType<typeof JSON.parse>} right - Second matching sync row.
- * @returns {number} Sort comparison with the canonical survivor first.
- */
-function comparePublishedSyncRowsByRecency(left, right) {
-  const leftSequence = left.serverSequence()
-  const rightSequence = right.serverSequence()
-
-  if (leftSequence === null && rightSequence !== null) return 1
-  if (leftSequence !== null && rightSequence === null) return -1
-  if (leftSequence !== rightSequence) return rightSequence - leftSequence
-
-  return left.id().localeCompare(right.id())
-}
-
 /**
  * Resolves a model class's active publish declaration from `static sync`.
  * Opted-out (`publish: false`) and undeclared models resolve to null; every

package/src/sync/upsert-server-origin-sync-row.js

@@ -0,0 +1,158 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+import sha256Hex from "../utils/sha256-hex.js"
+import stableJsonStringify from "../utils/stable-json.js"
+
+import {upsertSyncRow} from "./sync-change-fanout.js"
+import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
+
+/**
+ * Atomically reconciles and upserts one server-origin sync row by its complete,
+ * null-safe logical identity. The identity contains the null actor, resource
+ * type/id, and either every scope column declared by the sync model or the
+ * caller's explicit effective scope columns for a supported legacy publisher.
+ * A stable portable advisory lock serializes runtime publication and maintenance/backfill calls;
+ * legacy duplicates converge to the newest server sequence, then the lowest
+ * immutable id, before the survivor is updated and re-sequenced.
+ *
+ * The lock is acquired through the static sync model on a dedicated connection.
+ * `persistenceModel` may be an operation-bound model facade so reads/writes keep
+ * their owning operation while sharing the same identity lock as ordinary
+ * publisher calls.
+ * @param {object} args - Persistence arguments.
+ * @param {string} [args.actorForeignKeyColumn] - Persisted actor foreign-key column.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} args.attributes - Complete sync-row mutation attributes.
+ * @param {ReturnType<typeof JSON.parse>} [args.persistenceModel] - Optional operation-bound model used for row reads/writes.
+ * @param {string[]} [args.scopeColumnNames] - Exact persisted scope columns overriding model declarations for a supported legacy publisher identity.
+ * @param {ReturnType<typeof JSON.parse>} args.syncModel - Static sync model owning scope metadata and the advisory lock.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} Created or reconciled sync row.
+ */
+export async function upsertServerOriginSyncRow({
+  actorForeignKeyColumn = "authentication_token_id",
+  attributes,
+  persistenceModel,
+  scopeColumnNames,
+  syncModel,
+  ...restArgs
+}) {
+  restArgsError(restArgs)
+
+  if (typeof actorForeignKeyColumn !== "string" || !actorForeignKeyColumn) {
+    throw new Error("Server-origin sync row actorForeignKeyColumn must be a non-empty string")
+  }
+  if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) {
+    throw new Error("Server-origin sync row attributes must be a plain object")
+  }
+  if (!Object.hasOwn(attributes, actorForeignKeyColumn) || attributes[actorForeignKeyColumn] === undefined) {
+    throw new Error(`Server-origin sync row identity must include the actor column ${actorForeignKeyColumn}`)
+  }
+  if (attributes[actorForeignKeyColumn] !== null) {
+    throw new Error(`Server-origin sync row actor column ${actorForeignKeyColumn} must be null`)
+  }
+
+  validateRequiredIdentityString({attributes, columnName: "resource_id"})
+  validateRequiredIdentityString({attributes, columnName: "resource_type"})
+
+  /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
+  const identity = {
+    [actorForeignKeyColumn]: null,
+    resource_id: attributes.resource_id,
+    resource_type: attributes.resource_type
+  }
+  const attributeToColumnName = syncModel.getAttributeNameToColumnNameMap()
+  const scopeColumns = new Set(scopeColumnNames || [])
+
+  if (scopeColumnNames === undefined) {
+    for (const scopeAttribute of declaredSyncScopeAttributes(syncModel) || []) {
+      const columnName = attributeToColumnName[scopeAttribute]
+
+      if (!columnName) {
+        throw new Error(`${syncModel.name} declares the sync scope attribute ${scopeAttribute} but has no matching column for it`)
+      }
+
+      scopeColumns.add(columnName)
+    }
+  }
+
+  for (const columnName of scopeColumns) {
+    if (typeof columnName !== "string" || !columnName || !Object.values(attributeToColumnName).includes(columnName)) {
+      throw new Error(`Server-origin sync row received an unknown scope column: ${String(columnName)}`)
+    }
+
+    if (!Object.hasOwn(attributes, columnName) || attributes[columnName] === undefined) {
+      throw new Error(`Server-origin sync row identity must include the declared scope column ${columnName}`)
+    }
+
+    const value = attributes[columnName]
+
+    if (value !== null && typeof value !== "string" && (typeof value !== "number" || !Number.isFinite(value))) {
+      throw new Error(`Server-origin sync row scope column ${columnName} must be a string, finite number, or null`)
+    }
+
+    identity[columnName] = value
+  }
+
+  const rowModel = persistenceModel || syncModel
+
+  return await syncModel.withAdvisoryLock(serverOriginSyncRowLockName(identity), async () => {
+    const matchingSyncs = await rowModel
+      .where(identity)
+      .toArray()
+
+    matchingSyncs.sort(compareServerOriginSyncRowsByRecency)
+
+    const [existingSync, ...duplicateSyncs] = matchingSyncs
+
+    for (const duplicateSync of duplicateSyncs) {
+      await duplicateSync.destroy()
+    }
+
+    return await upsertSyncRow({attributes, existingSync, syncModel: rowModel})
+  }, {dedicatedConnection: true})
+}
+
+/**
+ * Validates one required string component of the server-origin identity.
+ * @param {{attributes: Record<string, ReturnType<typeof JSON.parse>>, columnName: "resource_id" | "resource_type"}} args - Attributes and required column.
+ * @returns {void}
+ */
+function validateRequiredIdentityString({attributes, columnName}) {
+  const value = attributes[columnName]
+
+  if (typeof value !== "string" || !value) {
+    throw new Error(`Server-origin sync row ${columnName} must be a non-empty string`)
+  }
+}
+
+/**
+ * Returns the stable MySQL-safe advisory-lock name shared by every caller of a
+ * complete server-origin identity. Stable JSON preserves null identity values,
+ * while the truncated SHA-256 digest keeps the name under GET_LOCK's limit.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} identity - Complete sync-row identity in column form.
+ * @returns {string} Advisory-lock name.
+ */
+function serverOriginSyncRowLockName(identity) {
+  const hash = sha256Hex(stableJsonStringify(identity)).slice(0, 32)
+
+  return `vsp:${hash}`
+}
+
+/**
+ * Orders matching rows with the canonical deterministic survivor first:
+ * newest server sequence, then lowest immutable id. A null legacy sequence is
+ * older than every assigned sequence.
+ * @param {ReturnType<typeof JSON.parse>} left - First matching sync row.
+ * @param {ReturnType<typeof JSON.parse>} right - Second matching sync row.
+ * @returns {number} Sort comparison.
+ */
+function compareServerOriginSyncRowsByRecency(left, right) {
+  const leftSequence = left.serverSequence()
+  const rightSequence = right.serverSequence()
+
+  if (leftSequence === null && rightSequence !== null) return 1
+  if (leftSequence !== null && rightSequence === null) return -1
+  if (leftSequence !== rightSequence) return rightSequence - leftSequence
+
+  return left.id().localeCompare(right.id())
+}