velocious 1.0.596 → 1.0.598

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/testing/factory/node/definition-reload-policy.js

@@ -0,0 +1,149 @@
+// @ts-check
+
+/**
+ * Default maximum number of cache-busted factory definition import attempts a
+ * single Node process may perform. Chosen conservatively from the
+ * `factory-esm-reload-retention` benchmark evidence: each cache-busted import
+ * retains roughly 6 KB of heap in Node's ESM module map, so the default bounds
+ * retained definition modules to a few tens of MB before the owning process
+ * must be recycled. This module is intentionally Node-only; browser-safe factory
+ * code must never import it.
+ */
+export const DEFAULT_DEFINITION_RELOAD_BUDGET = 4096
+
+/**
+ * Rejected when code tries to configure the process-global reload budget more
+ * than once or after any valid cache-busted import reservation was attempted.
+ * Retained ESM modules and their accounting live for the process lifetime, so
+ * changing the budget can never begin a new in-process policy epoch.
+ */
+export class DefinitionReloadConfigurationError extends Error {
+  /**
+   * Creates the error.
+   * @param {object} args - Details.
+   * @param {number} args.current - Cache-busted imports already reserved.
+   * @param {number} args.budget - Active process-global import budget.
+   * @param {number} args.requestedBudget - Rejected replacement budget.
+   * @param {boolean} args.configured - Whether an explicit budget was already configured.
+   */
+  constructor({budget, configured, current, requestedBudget}) {
+    const reason = configured
+      ? "the process-global definition reload budget was already configured"
+      : "a definition reload reservation was already attempted"
+
+    super(`Cannot configure definition reload budget to ${requestedBudget}: ${reason} (current=${current}, budget=${budget}). Configuration is allowed exactly once before the first reservation; only process exit resets retained-module accounting.`)
+    this.name = "DefinitionReloadConfigurationError"
+    this.budget = budget
+    this.configured = configured
+    this.current = current
+    this.requestedBudget = requestedBudget
+  }
+}
+
+/**
+ * Rejected when a reload would push the process over its cache-busted import
+ * budget. The rejection happens synchronously before any registry reset or
+ * import, so the currently loaded registry stays usable. Node never evicts
+ * retained ESM module instances, so only recycling/restarting the owning Node
+ * process reclaims the memory and refreshes edited dependency modules.
+ */
+export class DefinitionRecycleRequiredError extends Error {
+  /**
+   * Creates the error.
+   * @param {object} args - Details.
+   * @param {number} args.current - Cache-busted import attempts already reserved in this process.
+   * @param {number} args.budget - Process-global import budget.
+   * @param {number} args.requested - Import attempts the rejected reload needed.
+   */
+  constructor({current, budget, requested}) {
+    super(`Factory definition reload import budget exhausted (current=${current}, budget=${budget}, requested=${requested}). Recycle or restart the owning Node process: every reload imports a fresh cache-busted module instance and Node never evicts them, so process recycling is the only reclamation boundary.`)
+    this.name = "DefinitionRecycleRequiredError"
+    this.current = current
+    this.budget = budget
+    this.requested = requested
+  }
+}
+
+/** @type {number} - The single process-global import budget. */
+let importBudget = DEFAULT_DEFINITION_RELOAD_BUDGET
+
+/** @type {number} - Cache-busted import attempts reserved so far across every registry and target. */
+let reservedImports = 0
+
+/** @type {boolean} - Whether the process-global budget was explicitly configured. */
+let budgetConfigured = false
+
+/** @type {boolean} - Whether any valid complete reload batch reservation was attempted. */
+let reservationStarted = false
+
+/**
+ * Returns the process-global cache-busted import budget.
+ * @returns {number} - The budget.
+ */
+export function getDefinitionReloadBudget() {
+  return importBudget
+}
+
+/**
+ * Reads the cache-busted import attempts reserved so far in this process,
+ * across every registry and target. Combined with {@link getDefinitionReloadBudget}
+ * this is the deterministic process-global census for the recycle policy.
+ * @returns {number} - Reserved count.
+ */
+export function peekDefinitionReloadBudget() {
+  return reservedImports
+}
+
+/**
+ * Configures the one process-global import budget exactly once and only before
+ * the first valid reservation attempt. There is exactly one budget for the whole
+ * process, so no combination of registries or targets can create independent
+ * budgets that defeat the global limit. Retained-import accounting is never
+ * reset in-process.
+ * @param {number} budget - New budget.
+ * @returns {void}
+ */
+export function setDefinitionReloadBudget(budget) {
+  if (!Number.isInteger(budget) || budget < 1) {
+    throw new TypeError(`Definition reload budget must be a positive integer, got ${JSON.stringify(budget)}`)
+  }
+
+  if (budgetConfigured || reservationStarted) {
+    throw new DefinitionReloadConfigurationError({
+      budget: importBudget,
+      configured: budgetConfigured,
+      current: reservedImports,
+      requestedBudget: budget
+    })
+  }
+
+  importBudget = budget
+  budgetConfigured = true
+}
+
+/**
+ * Preflights and reserves a whole reload batch synchronously. Malformed counts
+ * are rejected before configuration is sealed or accounting changes. Every valid
+ * request, including zero and a rejected over-budget request, seals configuration
+ * before capacity is evaluated. Throws {@link DefinitionRecycleRequiredError}
+ * when the requested batch would push the process over its budget. The check and
+ * reservation run in one synchronous step, so concurrent reloads cannot race past
+ * the budget. The reservation is deliberately conservative: it covers every
+ * import attempt in the batch, so a mid-batch import failure still counts its
+ * attempts as retained modules.
+ * @param {number} requested - Cache-busted import attempts the reload will perform.
+ * @returns {void}
+ */
+export function reserveDefinitionReloadBudget(requested) {
+  if (!Number.isInteger(requested) || requested < 0) {
+    throw new TypeError(`Definition reload reservation must be a non-negative integer, got ${typeof requested} ${String(requested)}`)
+  }
+
+  reservationStarted = true
+
+  if (reservedImports + requested > importBudget) {
+    throw new DefinitionRecycleRequiredError({current: reservedImports, budget: importBudget, requested})
+  }
+
+  reservedImports += requested
+}

package/src/testing/factory/node/load-definitions.js

@@ -1,8 +1,9 @@
 // @ts-check
 
-import {pathToFileURL} from "node:url"
-import {readdir, stat} from "node:fs/promises"
+import { pathToFileURL } from "node:url"
+import { readdir, stat } from "node:fs/promises"
 import path from "node:path"
+import { reserveDefinitionReloadBudget } from "./definition-reload-policy.js"
 
 /**
  * Monotonic cache-busting counter shared by reloads. Kept module-local so a reload
@@ -68,6 +69,26 @@ async function resolveFiles(target) {
 export async function loadDefinitions(registry, target, {reload = false} = {}) {
   const files = await resolveFiles(target)
 
+  return await loadResolvedDefinitionFiles({files, registry, reload})
+}
+
+/**
+ * Loads definition files that have already been resolved into a deterministic
+ * sorted list. When `reload` is set, the whole batch is preflighted and reserved
+ * against the process-global import budget before any registry reset or import
+ * attempt, so a rejected reload never mutates the registry.
+ * @param {object} args - Options object.
+ * @param {string[]} args.files - Resolved, sorted definition file paths.
+ * @param {import("../factory-registry.js").default} args.registry - Registry to define into.
+ * @param {boolean} args.reload - Whether to cache-bust the imports.
+ * @param {boolean} [args.reset] - Whether to reset the registry first.
+ * @returns {Promise<string[]>} - The loaded file paths, in load order.
+ */
+async function loadResolvedDefinitionFiles({files, registry, reload, reset = false}) {
+  if (reload) reserveDefinitionReloadBudget(files.length)
+
+  if (reset) registry.reset()
+
   for (const file of files) {
     let href = pathToFileURL(file).href
 
@@ -91,13 +112,16 @@ export async function loadDefinitions(registry, target, {reload = false} = {}) {
 /**
  * Fully reloads definitions: resets the registry (dropping every factory, trait,
  * sequence, callback and default) and re-imports the target files with cache
- * busting so edited definitions take effect.
+ * busting so edited definitions take effect. The resolved batch is preflighted
+ * against the process-global import budget before the reset, and a
+ * `DefinitionRecycleRequiredError` is raised before any mutation when the batch
+ * would exceed the budget.
  * @param {import("../factory-registry.js").default} registry - Registry to reload.
  * @param {string | string[]} target - File path, directory, or list of paths.
  * @returns {Promise<string[]>} - The reloaded file paths, in load order.
  */
 export async function reloadDefinitions(registry, target) {
-  registry.reset()
+  const files = await resolveFiles(target)
 
-  return await loadDefinitions(registry, target, {reload: true})
+  return await loadResolvedDefinitionFiles({files, registry, reload: true, reset: true})
 }

package/src/testing/test-runner.js

@@ -1058,12 +1058,12 @@ export default class TestRunner {
               // back). Releasing the lease after each lifecycle also runs the pool's
               // session cleanup before another test can reuse the connection.
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
-                // Register dynamic candidates before application hooks so transaction
-                // state changes made during a hook are visible to a request dispatched
-                // by that same callback.
-                if (testArgs.type == "request") {
-                  testSharedConnectionRegistrations = this.activateTestSharedConnections()
-                }
+                // Register dynamic candidates before hooks so transaction state changes
+                // made during a hook are immediately visible to any in-process work.
+                // Long-lived services such as a background-jobs main can dispatch DB
+                // work between a transaction-starting hook and broker activation just
+                // as an HTTP request can dispatch work from inside the hook itself.
+                testSharedConnectionRegistrations = this.activateTestSharedConnections()
 
                 try {
                   try {

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>>} */ ({}))
+}