velocious 1.0.595 → 1.0.597

package/src/mailer/delivery-operation-store.js

@@ -0,0 +1,152 @@
+// @ts-check
+
+import BackgroundJobsStore from "../background-jobs/store.js"
+import VelociousError from "../velocious-error.js"
+import {
+  MAIL_DELIVERY_OPERATIONS_TABLE,
+  mailDeliveryOperationKey,
+  validateAttemptPayload
+} from "./delivery-operation.js"
+
+/**
+ * Durable first-attempt and retention guard for required mail operations.
+ */
+export default class MailerDeliveryOperationStore {
+  /**
+   * Creates a durable mail-operation state guard.
+   * @param {object} args - Store input.
+   * @param {import("../configuration.js").default} args.configuration - Active configuration.
+   * @param {() => number} [args.clock] - Explicit clock dependency.
+   */
+  constructor({configuration, clock = () => Date.now()}) {
+    this.backgroundJobsStore = new BackgroundJobsStore({configuration})
+    this.clock = clock
+    this.configuration = configuration
+  }
+
+  /**
+   * Atomically starts the provider retention clock once and rejects expired attempts.
+   * @param {object} args - Attempt input.
+   * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Current backend capability.
+   * @param {import("./index.js").MailerDeliveryPayload} args.payload - Persisted payload.
+   * @returns {Promise<{expiresAtMs: number, firstAttemptStartedAtMs: number}>} - Attempt window.
+   */
+  async beginAttempt({capability, payload}) {
+    const operation = validateAttemptPayload({capability, payload})
+    const nowMs = this.clock()
+
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0) throw new Error("Mailer delivery operation clock must return a non-negative safe integer")
+
+    const databaseIdentifier = this.backgroundJobsStore.getDatabaseIdentifier()
+
+    return await this.configuration.ensureConnections({
+      databaseIdentifiers: [databaseIdentifier],
+      name: "Mailer delivery operation attempt"
+    }, async (dbs) => {
+      const db = dbs[databaseIdentifier]
+
+      if (db.insideTransaction()) {
+        throw VelociousError.safe("Required mail delivery cannot start inside an existing database transaction.", {
+          code: "mail-delivery-idempotency-transaction-active"
+        })
+      }
+
+      await this.backgroundJobsStore.ensureSchema(db)
+
+      return await db.transaction(async () => {
+        const operationKey = mailDeliveryOperationKey(operation.id)
+
+        // A value-preserving structured update obtains the row's write lock on
+        // every driver before we inspect or initialize the one-shot timestamp.
+        await db.update({
+          tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+          data: {operation_key: operationKey},
+          conditions: {operation_key: operationKey}
+        })
+        let row = await this._operationRow(db, operation.id)
+
+        if (!row) throw new Error("Required mail delivery operation is not durably registered")
+        this._validateRow({operation, row})
+
+        let firstAttemptStartedAtMs = numberOrNull(row.first_attempt_started_at_ms)
+
+        if (firstAttemptStartedAtMs === null) {
+          await db.update({
+            tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+            data: {first_attempt_started_at_ms: nowMs},
+            conditions: {operation_key: operationKey}
+          })
+          row = await this._operationRow(db, operation.id)
+          firstAttemptStartedAtMs = row ? numberOrNull(row.first_attempt_started_at_ms) : null
+
+          if (firstAttemptStartedAtMs === null) throw new Error("Failed to durably start mail delivery provider retention")
+        }
+
+        const expiresAtMs = firstAttemptStartedAtMs + operation.providerRetentionMs
+
+        if (nowMs >= expiresAtMs) {
+          throw VelociousError.safe("The required mail delivery idempotency window expired before another attempt.", {
+            code: "mail-delivery-idempotency-expired",
+            details: {
+              expiresAtMs,
+              firstAttemptStartedAtMs,
+              operationId: operation.id,
+              providerKind: operation.providerKind
+            }
+          })
+        }
+
+        return {expiresAtMs, firstAttemptStartedAtMs}
+      })
+    })
+  }
+
+  /**
+   * Loads one operation by its fixed-size digest key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} operationId - Operation id.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Row or null.
+   */
+  async _operationRow(db, operationId) {
+    const rows = await db
+      .newQuery()
+      .from(MAIL_DELIVERY_OPERATIONS_TABLE)
+      .where({operation_key: mailDeliveryOperationKey(operationId)})
+      .limit(1)
+      .results()
+
+    return rows[0] ? /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0]) : null
+  }
+
+  /**
+   * Validates immutable durable fields without including mail content in failures.
+   * @param {object} args - Validation input.
+   * @param {import("./index.js").MailerDeliveryOperation} args.operation - Persisted payload operation.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.row - Durable operation row.
+   * @returns {void}
+   */
+  _validateRow({operation, row}) {
+    const matches = String(row.operation_id) === operation.id
+      && String(row.payload_digest) === operation.payloadDigest
+      && String(row.provider_kind) === operation.providerKind
+      && numberOrNull(row.provider_retention_ms) === operation.providerRetentionMs
+
+    if (!matches) {
+      throw VelociousError.safe("The durable mail delivery operation does not match the persisted payload or provider.", {
+        code: "mail-delivery-idempotency-conflict"
+      })
+    }
+  }
+}
+
+/**
+ * Normalizes a database integer.
+ * @param {ReturnType<typeof JSON.parse>} value - Database value.
+ * @returns {number | null} - Number or null.
+ */
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === "") return null
+  const number = Number(value)
+
+  return Number.isNaN(number) ? null : number
+}

package/src/mailer/delivery-operation.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+import {createHash} from "crypto"
+import VelociousError from "../velocious-error.js"
+import stableJsonStringify from "../utils/stable-json.js"
+
+export const MAIL_DELIVERY_JOB_NAME = "MailDeliveryJob"
+export const MAIL_DELIVERY_OPERATIONS_TABLE = "mailer_delivery_operations"
+const PAYLOAD_DIGEST_FORMAT = "velocious-mail-delivery-payload-v1"
+
+/**
+ * Reads and validates a backend's provider idempotency capability.
+ * @param {object} args - Capability input.
+ * @param {import("../configuration-types.js").MailerBackend | undefined} args.backend - Configured backend.
+ * @param {import("./index.js").MailerDeliveryOperationRequest | import("./index.js").MailerDeliveryOperation} args.deliveryOperation - Required operation.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered or persisted payload.
+ * @returns {import("./index.js").MailerDeliveryIdempotencyCapability} - Capability.
+ */
+export function requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload}) {
+  if (!backend || typeof backend.deliveryIdempotencyCapability !== "function") {
+    throw VelociousError.safe("The configured mailer backend does not support required provider idempotency.", {
+      code: "mail-delivery-idempotency-unsupported"
+    })
+  }
+
+  const capability = backend.deliveryIdempotencyCapability()
+
+  if (!capability || typeof capability.providerKind !== "string" || capability.providerKind.length === 0) {
+    throw new Error("Mailer backend delivery idempotency capability requires a non-empty providerKind")
+  }
+  if (!Number.isSafeInteger(capability.retentionMs) || capability.retentionMs <= 0) {
+    throw new Error("Mailer backend delivery idempotency capability requires a positive safe-integer retentionMs")
+  }
+
+  if (typeof backend.validateDeliveryOperation === "function") {
+    backend.validateDeliveryOperation({deliveryOperation, payload})
+  }
+
+  return capability
+}
+
+/**
+ * Normalizes one public required operation into immutable payload metadata.
+ * @param {object} args - Preparation input.
+ * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Backend capability.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} args.deliveryOperation - Public operation request.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+ * @returns {import("./index.js").MailerDeliveryPayload} - Payload with immutable operation metadata.
+ */
+export function prepareRequiredDeliveryPayload({capability, deliveryOperation, payload}) {
+  validateDeliveryOperationRequest(deliveryOperation)
+  const payloadDigest = mailDeliveryPayloadDigest({operationId: deliveryOperation.id, payload})
+
+  return {
+    ...payload,
+    deliveryOperation: {
+      id: deliveryOperation.id,
+      idempotency: "required",
+      payloadDigest,
+      providerKind: capability.providerKind,
+      providerRetentionMs: capability.retentionMs
+    }
+  }
+}
+
+/**
+ * Builds the versioned digest for every recipient-visible/provider-relevant payload field.
+ * @param {object} args - Digest input.
+ * @param {string} args.operationId - Stable operation id.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+ * @returns {string} - Versioned SHA-256 digest.
+ */
+export function mailDeliveryPayloadDigest({operationId, payload}) {
+  const canonicalPayload = {
+    action: payload.action,
+    bcc: payload.bcc ?? null,
+    cc: payload.cc ?? null,
+    format: PAYLOAD_DIGEST_FORMAT,
+    from: payload.from ?? null,
+    headers: canonicalHeaders(payload.headers),
+    html: payload.html,
+    mailer: payload.mailer,
+    operationId,
+    replyTo: payload.replyTo ?? null,
+    subject: payload.subject,
+    to: payload.to
+  }
+  const digest = createHash("sha256").update(stableJsonStringify(canonicalPayload)).digest("hex")
+
+  return `sha256:v1:${digest}`
+}
+
+/**
+ * Extracts validated persisted operation metadata from a payload.
+ * @param {import("./index.js").MailerDeliveryPayload} payload - Mail payload.
+ * @returns {import("./index.js").MailerDeliveryOperation | null} - Operation or null.
+ */
+export function deliveryOperationFromPayload(payload) {
+  const operation = payload.deliveryOperation
+
+  if (!operation) return null
+  if (operation.idempotency !== "required") throw new Error("Persisted mail delivery operation idempotency must be required")
+  if (typeof operation.id !== "string" || operation.id.length === 0) throw new Error("Persisted mail delivery operation requires an id")
+  if (typeof operation.payloadDigest !== "string" || !operation.payloadDigest.startsWith("sha256:v1:")) throw new Error("Persisted mail delivery operation requires a versioned payload digest")
+  if (typeof operation.providerKind !== "string" || operation.providerKind.length === 0) throw new Error("Persisted mail delivery operation requires a provider kind")
+  if (!Number.isSafeInteger(operation.providerRetentionMs) || operation.providerRetentionMs <= 0) throw new Error("Persisted mail delivery operation requires a positive retention")
+
+  return operation
+}
+
+/**
+ * Extracts a built-in mail operation from generic job arguments.
+ * @param {string} jobName - Job class name.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args - Job arguments.
+ * @returns {{operation: import("./index.js").MailerDeliveryOperation, payload: import("./index.js").MailerDeliveryPayload} | null} - Mail operation input.
+ */
+export function mailDeliveryOperationForJob(jobName, args) {
+  if (jobName !== MAIL_DELIVERY_JOB_NAME || !args[0] || typeof args[0] !== "object" || Array.isArray(args[0])) return null
+
+  const payload = /** @type {import("./index.js").MailerDeliveryPayload} */ (args[0])
+  const operation = deliveryOperationFromPayload(payload)
+
+  return operation ? {operation, payload} : null
+}
+
+/**
+ * Fixed-size primary key for a potentially long operation id.
+ * @param {string} operationId - Operation id.
+ * @returns {string} - SHA-256 operation key.
+ */
+export function mailDeliveryOperationKey(operationId) {
+  return createHash("sha256").update(`velocious-mail-delivery-operation:${operationId}`).digest("hex")
+}
+
+/**
+ * Validates provider compatibility and payload integrity before an attempt.
+ * @param {object} args - Validation input.
+ * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Current backend capability.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Persisted payload.
+ * @returns {import("./index.js").MailerDeliveryOperation} - Persisted operation.
+ */
+export function validateAttemptPayload({capability, payload}) {
+  const operation = deliveryOperationFromPayload(payload)
+
+  if (!operation) throw new Error("Expected a persisted mail delivery operation")
+  if (operation.providerKind !== capability.providerKind || operation.providerRetentionMs !== capability.retentionMs) {
+    throw VelociousError.safe("The configured mailer backend no longer matches the required delivery operation provider.", {
+      code: "mail-delivery-idempotency-provider-mismatch"
+    })
+  }
+
+  const currentDigest = mailDeliveryPayloadDigest({operationId: operation.id, payload})
+
+  if (currentDigest !== operation.payloadDigest) {
+    throw VelociousError.safe("The persisted mail delivery payload digest does not match its required operation.", {
+      code: "mail-delivery-idempotency-payload-mismatch"
+    })
+  }
+
+  return operation
+}
+
+/**
+ * Validates the public operation shape without accepting future semantics silently.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} deliveryOperation - Public operation.
+ * @returns {void}
+ */
+function validateDeliveryOperationRequest(deliveryOperation) {
+  if (!deliveryOperation || typeof deliveryOperation !== "object" || Array.isArray(deliveryOperation)) {
+    throw VelociousError.safe("deliveryOperation must be an object.", {code: "mail-delivery-operation-invalid"})
+  }
+  if (typeof deliveryOperation.id !== "string" || deliveryOperation.id.length === 0) {
+    throw VelociousError.safe("deliveryOperation.id must be a non-empty string.", {code: "mail-delivery-operation-invalid"})
+  }
+  if (deliveryOperation.idempotency !== "required") {
+    throw VelociousError.safe('deliveryOperation.idempotency must be "required".', {code: "mail-delivery-operation-invalid"})
+  }
+
+  const keys = Object.keys(deliveryOperation)
+
+  if (keys.some((key) => key !== "id" && key !== "idempotency")) {
+    throw VelociousError.safe("deliveryOperation contains unsupported fields.", {code: "mail-delivery-operation-invalid"})
+  }
+}
+
+/**
+ * Canonicalizes case-insensitive custom headers without exposing values.
+ * @param {Record<string, string> | undefined} headers - Custom headers.
+ * @returns {Array<[string, string]>} - Sorted header pairs.
+ */
+function canonicalHeaders(headers) {
+  if (!headers) return []
+
+  const pairs = Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value])
+  const names = new Set()
+
+  for (const [name] of pairs) {
+    if (names.has(name)) {
+      throw VelociousError.safe("Mail headers contain duplicate case-insensitive names.", {code: "mail-delivery-headers-invalid"})
+    }
+    names.add(name)
+  }
+
+  return /** @type {Array<[string, string]>} */ (pairs.sort(([left], [right]) => left.localeCompare(right)))
+}

package/src/mailer/delivery.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import restArgsError from "../utils/rest-args-error.js"
+
 /**
  * Represents a prepared mail delivery.
  */
@@ -52,19 +54,22 @@ export default class MailerDelivery {
 
   /**
    * Runs deliver later.
+   * @param {import("./index.js").MailerDeliveryLaterOptions} [options] - Delivery execution options.
    * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
    */
-  async deliverLater() {
+  async deliverLater({deliveryOperation, ...restArgs} = {}) {
+    restArgsError(restArgs)
     const payload = await this.buildPayload()
 
-    return await this.mailer._enqueuePayload(payload)
+    return await this.mailer._enqueuePayload(payload, {deliveryOperation})
   }
 
   /**
    * Runs deliver laver.
+   * @param {import("./index.js").MailerDeliveryLaterOptions} [options] - Delivery execution options.
    * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
    */
-  async deliverLaver() {
-    return await this.deliverLater()
+  async deliverLaver(options) {
+    return await this.deliverLater(options)
   }
 }

package/src/mailer/index.js

@@ -1,6 +1,10 @@
 // @ts-check
 
-/** @typedef {{to: ReturnType<typeof JSON.parse>, subject: string, from?: ReturnType<typeof JSON.parse>, cc?: ReturnType<typeof JSON.parse>, bcc?: ReturnType<typeof JSON.parse>, replyTo?: ReturnType<typeof JSON.parse>, headers?: Record<string, string>, html: string, mailer: string, action: string}} MailerDeliveryPayload */
+/** @typedef {{id: string, idempotency: "required"}} MailerDeliveryOperationRequest */
+/** @typedef {{id: string, idempotency: "required", payloadDigest: string, providerKind: string, providerRetentionMs: number}} MailerDeliveryOperation */
+/** @typedef {{providerKind: string, retentionMs: number}} MailerDeliveryIdempotencyCapability */
+/** @typedef {{deliveryOperation?: MailerDeliveryOperationRequest}} MailerDeliveryLaterOptions */
+/** @typedef {{to: ReturnType<typeof JSON.parse>, subject: string, from?: ReturnType<typeof JSON.parse>, cc?: ReturnType<typeof JSON.parse>, bcc?: ReturnType<typeof JSON.parse>, replyTo?: ReturnType<typeof JSON.parse>, headers?: Record<string, string>, html: string, mailer: string, action: string, deliveryOperation?: MailerDeliveryOperation}} MailerDeliveryPayload */
 
 import {
   clearDeliveries,

package/src/mailer.js

@@ -1,6 +1,10 @@
 // @ts-check
 
-/** @typedef {{to: ReturnType<typeof JSON.parse>, subject: string, from?: ReturnType<typeof JSON.parse>, cc?: ReturnType<typeof JSON.parse>, bcc?: ReturnType<typeof JSON.parse>, replyTo?: ReturnType<typeof JSON.parse>, headers?: Record<string, string>, html: string, mailer: string, action: string}} MailerDeliveryPayload */
+/** @typedef {import("./mailer/index.js").MailerDeliveryOperationRequest} MailerDeliveryOperationRequest */
+/** @typedef {import("./mailer/index.js").MailerDeliveryOperation} MailerDeliveryOperation */
+/** @typedef {import("./mailer/index.js").MailerDeliveryIdempotencyCapability} MailerDeliveryIdempotencyCapability */
+/** @typedef {import("./mailer/index.js").MailerDeliveryLaterOptions} MailerDeliveryLaterOptions */
+/** @typedef {import("./mailer/index.js").MailerDeliveryPayload} MailerDeliveryPayload */
 
 export {
   VelociousMailerBase,
@@ -12,4 +16,5 @@ export {
   setDeliveryHandler
 } from "./mailer/index.js"
 export {default as SmtpMailerBackend} from "./mailer/backends/smtp.js"
+export {default as ResendSmtpMailerBackend} from "./mailer/backends/resend-smtp.js"
 export {default} from "./mailer/index.js"

package/src/sync/local-mutation-log.js

@@ -37,11 +37,12 @@
  * @property {import("./device-identity.js").SignedSyncMutation} [signedMutation] - Original signed mutation envelope, retained for peer-forwarded mutations.
  * @property {number} sequence - Monotonic local sequence.
  * @property {LocalMutationStatus} status - Local replay/apply status.
- * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [syncResult] - Backend replay/result metadata.
+ * @property {Record<string, import("../frontend-models/base.js").FrontendModelTransportValue>} [syncResult] - Backend replay/result metadata. Stored as transport markers so Date (and other typed) values survive the durable JSON round trip and are restored on readback.
  * @property {string} updatedAt - ISO timestamp when the record was last changed.
  */
 // @ts-check
 
+import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportValue} from "../frontend-models/transport-serialization.js"
 import stableJsonStringify from "./stable-json.js"
 
 const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
@@ -126,7 +127,7 @@ export default class LocalMutationLog {
    * @param {object} args - Arguments.
    * @param {string} args.id - Record id.
    * @param {LocalMutationStatus} args.status - New status.
-   * @param {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [args.syncResult] - Result metadata.
+   * @param {Record<string, import("../frontend-models/base.js").FrontendModelTransportValue>} [args.syncResult] - Result metadata (may carry transport-restored typed values).
    * @returns {Promise<LocalMutationLogRecord>} - Updated record.
    */
   async updateStatus({id, status, syncResult}) {
@@ -140,11 +141,16 @@ export default class LocalMutationLog {
       const record = normalizeRecord(rawRecord)
 
       record.status = /** @type {LocalMutationStatus} */ (status)
-      if (syncResult !== undefined) record.syncResult = cloneJsonObject(syncResult, "syncResult")
+      if (syncResult !== undefined) {
+        // Encode transport-restored typed values (e.g. Date attributes in a
+        // conflict serverModel) as markers before the JSON clone so the
+        // durable persistence round trip cannot stringify them.
+        record.syncResult = cloneJsonObject(serializeFrontendModelTransportValue(syncResult), "syncResult")
+      }
       record.updatedAt = this.currentTimestamp()
       await this.storage.updateRecord(this.storageKey, cloneRecord(record))
 
-      return cloneRecord(record)
+      return restoreSyncResultTypes(cloneRecord(record))
     })
   }
 
@@ -168,7 +174,7 @@ export default class LocalMutationLog {
       record.updatedAt = this.currentTimestamp()
       await this.storage.updateRecord(this.storageKey, cloneRecord(record))
 
-      return cloneRecord(record)
+      return restoreSyncResultTypes(cloneRecord(record))
     })
   }
 
@@ -270,6 +276,25 @@ function normalizeRecordList(records) {
     .map(normalizeRecord)
     .sort((left, right) => left.sequence - right.sequence)
     .map((record) => cloneRecord(record))
+    .map(restoreSyncResultTypes)
+}
+
+/**
+ * Restores transport-restored typed values in a record's syncResult after the
+ * final JSON clone, so callers see Date (and other typed) values on durable
+ * readback instead of marker-encoded ISO strings.
+ * @param {LocalMutationLogRecord} record - Cloned record.
+ * @returns {LocalMutationLogRecord} - Record with restored syncResult types.
+ */
+function restoreSyncResultTypes(record) {
+  if (record.syncResult === undefined) return record
+
+  return {
+    ...record,
+    syncResult: /** @type {Record<string, import("../frontend-models/base.js").FrontendModelTransportValue>} */ (
+      deserializeFrontendModelTransportValue(record.syncResult)
+    )
+  }
 }
 
 /**
@@ -328,7 +353,13 @@ function normalizeRecord(value) {
   if (record.signedMutation !== undefined) {
     normalizedRecord.signedMutation = /** @type {import("./device-identity.js").SignedSyncMutation} */ (cloneJsonObject(record.signedMutation, "signedMutation"))
   }
-  if (record.syncResult !== undefined) normalizedRecord.syncResult = cloneJsonObject(record.syncResult, "syncResult")
+  if (record.syncResult !== undefined) {
+    // Persisted syncResult is marker-encoded so it survives the JSON clone;
+    // typed values are restored by restoreSyncResultTypes at the read boundary.
+    normalizedRecord.syncResult = /** @type {Record<string, import("../frontend-models/base.js").FrontendModelTransportValue>} */ (
+      cloneJsonObject(record.syncResult, "syncResult")
+    )
+  }
 
   return normalizedRecord
 }

package/src/sync/stable-json.js

@@ -1,28 +1 @@
-// @ts-check
-
-/**
- * Serializes a JSON-compatible value with recursively sorted object keys, so
- * equal values always produce byte-identical strings (used for sync scope and
- * change-feed identity comparisons).
- * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
- * @returns {string} - Stable JSON string.
- */
-export default function stableJsonStringify(value) {
-  return JSON.stringify(stableJsonValue(value))
-}
-
-/**
- * Produces a recursively key-sorted JSON value.
- * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
- * @returns {ReturnType<typeof JSON.parse>} - Stable JSON-compatible value.
- */
-function stableJsonValue(value) {
-  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
-  if (!value || typeof value !== "object") return value
-
-  return Object.keys(value).sort().reduce((memo, key) => {
-    memo[key] = stableJsonValue(value[key])
-
-    return memo
-  }, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({}))
-}
+export {default} from "../utils/stable-json.js"

package/src/sync/sync-envelope-replay-service.js

@@ -841,8 +841,9 @@ export default class SyncEnvelopeReplayService {
    * Projects affected mutation fields through the resource's readable
    * attribute contract. Writable-but-hidden fields are omitted, while custom
    * `<attribute>Attribute(model)` serializers and model accessors remain the
-   * source of frontend-visible values. The full model attribute hash is never
-   * exposed.
+   * source of frontend-visible values (Date values are kept raw so the normal
+   * frontend-model transport serializer can emit its date marker). The full
+   * model attribute hash is never exposed.
    * @param {object} args - Projection args.
    * @param {Record<string, ReturnType<typeof JSON.parse>>} args.attributes - Permitted affected mutation attributes.
    * @param {import("../database/record/index.js").default} args.existingRecord - Authorized server record.
@@ -885,7 +886,7 @@ export default class SyncEnvelopeReplayService {
       const resourceAttribute = resource.resourceMethod(`${attributeName}Attribute`)
 
       if (resourceAttribute) {
-        serializedAttributes[affectedField] = normalizeConflictValue(await resourceAttribute.method.call(resourceAttribute.resource, existingRecord))
+        serializedAttributes[affectedField] = await resourceAttribute.method.call(resourceAttribute.resource, existingRecord)
         continue
       }
 
@@ -893,9 +894,9 @@ export default class SyncEnvelopeReplayService {
       const attributeMethod = recordMethods[attributeName]
 
       if (typeof attributeMethod === "function") {
-        serializedAttributes[affectedField] = normalizeConflictValue(await attributeMethod.call(existingRecord))
+        serializedAttributes[affectedField] = await attributeMethod.call(existingRecord)
       } else {
-        serializedAttributes[affectedField] = normalizeConflictValue(existingRecord.readAttribute(attributeName))
+        serializedAttributes[affectedField] = existingRecord.readAttribute(attributeName)
       }
     }
 
@@ -1166,8 +1167,11 @@ export function syncReplayConflictLockName({resourceId, resourceType}) {
 }
 
 /**
- * Normalizes an authoritative conflict value for JSON transport and deterministic comparison.
- * @param {ReturnType<typeof JSON.parse>} value - Raw value from a database record.
+ * Normalizes a version value for deterministic comparison and transport.
+ * Only version values participate in stable-JSON comparison against client
+ * `baseVersion` strings; resource serializer/accessor results must stay raw so
+ * the frontend-model transport serializer can retain Date markers.
+ * @param {ReturnType<typeof JSON.parse>} value - Raw version value from a database record.
  * @returns {ReturnType<typeof JSON.parse>} - Normalized value (Date values become ISO strings).
  */
 function normalizeConflictValue(value) {

package/src/utils/stable-json.js

@@ -0,0 +1,26 @@
+// @ts-check
+
+/**
+ * Serializes a JSON-compatible value with recursively sorted object keys.
+ * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
+ * @returns {string} - Stable JSON string.
+ */
+export default function stableJsonStringify(value) {
+  return JSON.stringify(stableJsonValue(value))
+}
+
+/**
+ * Produces a recursively key-sorted JSON value.
+ * @param {ReturnType<typeof JSON.parse>} value - JSON-compatible value.
+ * @returns {ReturnType<typeof JSON.parse>} - Stable JSON-compatible value.
+ */
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
+  if (!value || typeof value !== "object") return value
+
+  return Object.keys(value).sort().reduce((memo, key) => {
+    memo[key] = stableJsonValue(value[key])
+
+    return memo
+  }, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({}))
+}