velocious 1.0.492 → 1.0.494

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

@@ -0,0 +1,246 @@
+// @ts-check
+
+import Configuration from "../configuration.js"
+import TableData from "../database/table-data/index.js"
+
+/**
+ * Allocation queues per database+table, serializing insert/last-insert-id
+ * pairs across all allocator instances in this process.
+ * @type {Map<string, Promise<void>>}
+ */
+const allocationQueues = new Map()
+
+/**
+ * Allocates monotonically increasing server sync sequences from an
+ * AUTO_INCREMENT id table: every allocation inserts a row and returns the
+ * driver's last-insert id, so sequences stay unique and increasing across
+ * processes sharing the same database.
+ *
+ * Backed by an auto-created `velocious_server_sequences` table on the
+ * configured database, with a process-local memory counter fallback when no
+ * database is configured (mirroring the sync scope store). Apps with an
+ * existing sequence table (for example a bare `id`-only AUTO_INCREMENT table)
+ * point `tableName` at it and pass `insertData: {}` to insert empty rows.
+ */
+export default class ServerSequenceAllocator {
+  /**
+   * Creates a server sequence allocator.
+   * @param {object} [args] - Options.
+   * @param {import("../configuration.js").default} [args.configuration] - Configuration owning the database. Defaults to the current configuration, resolved lazily per allocation.
+   * @param {string} [args.databaseIdentifier] - Database identifier.
+   * @param {Record<string, ?>} [args.insertData] - Row payload inserted per allocation. Defaults to `{created_at: new Date()}` matching the auto-created table; pass `{}` for bare id-only tables.
+   * @param {string} [args.tableName] - Sequence table name.
+   */
+  constructor({configuration, databaseIdentifier = "default", insertData, tableName = "velocious_server_sequences"} = {}) {
+    this.configuration = configuration
+    this.databaseIdentifier = databaseIdentifier
+    this.insertData = insertData
+    this.tableName = tableName
+    this._memorySequence = 0
+    this._isReady = false
+    /** @type {Promise<void> | null} */
+    this._readyPromise = null
+  }
+
+  /**
+   * Allocates the next monotonically increasing sequence.
+   *
+   * Allocations serialize through a module-level queue per database+table so
+   * parallel `next()` calls - including calls from other allocator instances
+   * sharing the same table and connection - cannot interleave their insert
+   * and last-insert-id reads and hand out duplicate sequences.
+   * @returns {Promise<number>} Next sequence value.
+   */
+  async next() {
+    const queueKey = `${this.databaseIdentifier}::${this.tableName}`
+    const previousAllocation = allocationQueues.get(queueKey) ?? Promise.resolve()
+    const allocation = previousAllocation.then(() => this._allocateNext())
+
+    allocationQueues.set(queueKey, allocation.then(() => undefined, () => undefined))
+
+    return await allocation
+  }
+
+  /**
+   * Ensures the backing table exists.
+   * @returns {Promise<void>} Resolves when ready.
+   */
+  async ensureReady() {
+    if (this._isReady) return
+
+    if (this._usesMemoryStorage()) {
+      this._isReady = true
+      return
+    }
+
+    if (this._readyPromise) return await this._readyPromise
+
+    this._readyPromise = this._withDb(async (db) => {
+      const created = await this._ensureSequencesTable(db)
+
+      // 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
+    })
+
+    try {
+      await this._readyPromise
+    } finally {
+      if (!this._isReady) this._readyPromise = null
+    }
+  }
+
+  /**
+   * Allocates one sequence value after queueing.
+   * @returns {Promise<number>} Allocated sequence value.
+   */
+  async _allocateNext() {
+    await this.ensureReady()
+
+    if (this._usesMemoryStorage()) {
+      return ++this._memorySequence
+    }
+
+    return await this._withDb(async (db) => {
+      // The allocated id must be returned by the insert statement itself (OUTPUT
+      // INSERTED/RETURNING), like the record create path does: MSSQL's
+      // SCOPE_IDENTITY() only sees inserts from the same batch/scope, so reading
+      // the last-insert id as a separate query always returns NULL there. Drivers
+      // without insert-returning support (older SQLite) keep the reliable
+      // connection-scoped last-insert-id fallback.
+      const insertSql = db.insertSql({
+        data: this._insertPayload(),
+        returnLastInsertedColumnNames: ["id"],
+        tableName: this.tableName
+      })
+      const insertResult = await db.query(insertSql)
+      const insertedId = Array.isArray(insertResult) ? insertResult[0]?.id : undefined
+
+      if (insertedId !== undefined && insertedId !== null) return Number(insertedId)
+
+      return Number(await db.lastInsertID())
+    })
+  }
+
+  /**
+   * Builds the row payload inserted per allocation.
+   * @returns {Record<string, ?>} Insert payload.
+   */
+  _insertPayload() {
+    return this.insertData ?? {created_at: new Date()}
+  }
+
+  /**
+   * Resolves the configuration owning the sequence table.
+   * @returns {import("../configuration.js").default} Resolved configuration.
+   */
+  _getConfiguration() {
+    return this.configuration ?? Configuration.current()
+  }
+
+  /**
+   * Whether the allocator runs without a configured database.
+   * @returns {boolean} Whether memory storage is used.
+   */
+  _usesMemoryStorage() {
+    try {
+      return !this._getConfiguration().getDatabaseConfiguration()[this.databaseIdentifier]
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * Runs a callback with a database connection.
+   * @template Result
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
+   * @returns {Promise<Result>} Callback result.
+   */
+  async _withDb(callback) {
+    return await this._getConfiguration().ensureConnections({name: "Server sequence allocator"}, async (dbs) => {
+      const db = dbs[this.databaseIdentifier]
+
+      if (!db) throw new Error(`No database connection available for identifier: ${this.databaseIdentifier}`)
+
+      return await callback(db)
+    })
+  }
+
+  /**
+   * Ensures the sequences table exists.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<boolean>} Whether the table had to be created.
+   */
+  async _ensureSequencesTable(db) {
+    if (await db.tableExists(this.tableName)) return false
+
+    const table = new TableData(this.tableName, {ifNotExists: true})
+
+    table.bigint("id", {autoIncrement: true, null: false, primaryKey: true})
+    table.datetime("created_at", {null: false})
+
+    await db.createTable(table)
+
+    return true
+  }
+}
+
+/**
+ * Wires server sequencing onto a sync model class: registers a beforeCreate
+ * lifecycle callback assigning the next sequence when the record has none, and
+ * defines an `advance<Column>()` instance method (when the model does not
+ * already define one) that re-sequences the record through the allocator.
+ *
+ * The sequence is always written through the model's generated typed setter
+ * (for example `setServerSequence`), so the model must expose the generated
+ * `set<Column>`/`has<Column>` accessors for the column.
+ * @template {typeof import("../database/record/index.js").default} TModelClass
+ * @param {TModelClass} ModelClass - Sync model class to sequence.
+ * @param {object} args - Options.
+ * @param {ServerSequenceAllocator} args.allocator - Allocator providing sequence values.
+ * @param {string} [args.column] - Sequence attribute name.
+ * @returns {TModelClass} The given model class.
+ */
+export function withServerSequence(ModelClass, {allocator, column = "serverSequence"}) {
+  if (!(allocator instanceof ServerSequenceAllocator)) {
+    throw new Error(`withServerSequence requires a ServerSequenceAllocator, got: ${String(allocator)}`)
+  }
+
+  const upperColumn = `${column.charAt(0).toUpperCase()}${column.slice(1)}`
+  const advanceMethodName = `advance${upperColumn}`
+  const hasMethodName = `has${upperColumn}`
+  const setterMethodName = `set${upperColumn}`
+
+  // Narrows the prototype to dynamic method access for the configured column name.
+  const prototype = /** @type {Record<string, ?>} */ (ModelClass.prototype)
+
+  if (typeof prototype[setterMethodName] != "function" || typeof prototype[hasMethodName] != "function") {
+    throw new Error(`withServerSequence requires generated ${setterMethodName} and ${hasMethodName} accessors on ${ModelClass.name}`)
+  }
+
+  if (typeof prototype[advanceMethodName] != "function") {
+    /**
+     * Assigns the next server-side sequence.
+     * @this {Record<string, ?>}
+     * @returns {Promise<void>}
+     */
+    prototype[advanceMethodName] = async function advanceServerSequenceThroughAllocator() {
+      this[setterMethodName](await allocator.next())
+    }
+  }
+
+  ModelClass.beforeCreate(async (record) => {
+    // Narrows the record to dynamic method access for the configured column name.
+    const dynamicRecord = /** @type {Record<string, ?>} */ (/** @type {?} */ (record))
+
+    if (dynamicRecord[hasMethodName]()) return
+
+    await dynamicRecord[advanceMethodName]()
+  })
+
+  return ModelClass
+}

package/build/sync/sync-attribute-normalizer.js

@@ -0,0 +1,186 @@
+// @ts-check
+
+import {snakeCaseKey} from "typanic"
+
+/**
+ * Builds the error thrown for a failed sync attribute validation.
+ * @callback SyncAttributeErrorFactory
+ * @param {string} message - Human-readable validation message.
+ * @param {{cause?: Error, code: string}} details - Stable machine-readable code and optional cause.
+ * @returns {Error} Error to throw.
+ */
+
+/**
+ * Declarative validation schema for one writable sync attribute.
+ *
+ * Keys are camelCase attribute names; each attribute also accepts its
+ * snake_case column key on input (the camelCase key wins when both are given)
+ * and is written under the snake_case column key on output. Error messages
+ * default to `<label> ...` phrasings with `sync-<label>-...` codes, where the
+ * label defaults to the camelCase attribute name; apps pin exact messages per
+ * attribute through the `*Message` overrides.
+ * @typedef {object} SyncAttributeSchemaEntry
+ * @property {"date" | "json" | "raw" | "string"} type - Attribute value type.
+ * @property {boolean} [required] - Whether present blank/absent values are rejected (strings reject blank-after-trim, dates reject null).
+ * @property {number} [maxLength] - Maximum string length, checked after trimming.
+ * @property {string} [label] - Label used in derived messages and codes.
+ * @property {string} [column] - Output column key. Defaults to the snake_cased attribute name.
+ * @property {string} [requiredMessage] - Pinned message for required rejections.
+ * @property {string} [tooLongMessage] - Pinned message for too-long rejections.
+ * @property {string} [invalidMessage] - Pinned message for invalid dates and non-object/non-string json values.
+ * @property {string} [invalidJsonMessage] - Pinned message for unparseable json strings.
+ */
+
+/**
+ * Normalizes writable sync attributes against a declarative schema.
+ *
+ * Only present keys are validated, so required attributes may be absent —
+ * create defaults own that concern. Input keys not declared in the schema are
+ * rejected by default so misspelled or read-only attributes fail loudly
+ * instead of being silently discarded (`unknownAttributes: "ignore"` opts
+ * out). Validation failures throw through the given error factory so apps
+ * control the raised error class.
+ * @param {object} args - Options.
+ * @param {Record<string, ?>} args.attributes - Raw incoming attributes (camelCase and/or snake_case keys).
+ * @param {SyncAttributeErrorFactory} args.errorFactory - Maps validation failures to thrown errors.
+ * @param {Record<string, SyncAttributeSchemaEntry>} args.schema - Attribute schema keyed by camelCase attribute name.
+ * @param {"error" | "ignore"} [args.unknownAttributes] - Unknown input-key handling. Defaults to "error".
+ * @returns {Record<string, ?>} Normalized values keyed by snake_case column names.
+ */
+export default function normalizeAttributesWithSchema({attributes, errorFactory, schema, unknownAttributes = "error"}) {
+  if (!attributes || typeof attributes != "object") throw new Error(`normalizeAttributesWithSchema requires an attributes object, got: ${String(attributes)}`)
+  if (typeof errorFactory != "function") throw new Error("normalizeAttributesWithSchema requires an errorFactory function")
+  if (!schema || typeof schema != "object") throw new Error(`normalizeAttributesWithSchema requires a schema object, got: ${String(schema)}`)
+  if (unknownAttributes != "error" && unknownAttributes != "ignore") {
+    throw new Error(`normalizeAttributesWithSchema unknownAttributes must be "error" or "ignore", got: ${String(unknownAttributes)}`)
+  }
+
+  /** @type {Record<string, ?>} */
+  const normalized = {}
+  /** @type {Set<string>} */
+  const knownInputKeys = new Set()
+
+  for (const [attributeName, entry] of Object.entries(schema)) {
+    const column = entry.column ?? snakeCaseKey(attributeName)
+    const inputKeys = column == attributeName ? [attributeName] : [column, attributeName]
+
+    for (const inputKey of inputKeys) {
+      knownInputKeys.add(inputKey)
+
+      if (!Object.prototype.hasOwnProperty.call(attributes, inputKey)) continue
+
+      normalized[column] = normalizeAttributeValue({attributeName, entry, errorFactory, value: attributes[inputKey]})
+    }
+  }
+
+  if (unknownAttributes == "error") {
+    for (const inputKey of Object.keys(attributes)) {
+      if (!knownInputKeys.has(inputKey)) {
+        throw errorFactory(`Unknown attribute: ${inputKey}.`, {code: "sync-unknown-attribute"})
+      }
+    }
+  }
+
+  return normalized
+}
+
+/**
+ * Normalizes one present attribute value per its schema entry.
+ * @param {object} args - Options.
+ * @param {string} args.attributeName - camelCase attribute name.
+ * @param {SyncAttributeSchemaEntry} args.entry - Schema entry.
+ * @param {SyncAttributeErrorFactory} args.errorFactory - Error factory.
+ * @param {?} args.value - Raw value.
+ * @returns {?} Normalized value.
+ */
+function normalizeAttributeValue({attributeName, entry, errorFactory, value}) {
+  const label = entry.label ?? attributeName
+
+  if (entry.type == "string") return normalizeString({entry, errorFactory, label, value})
+  if (entry.type == "date") return normalizeDate({entry, errorFactory, label, value})
+  if (entry.type == "json") return normalizeJson({entry, errorFactory, label, value})
+  if (entry.type == "raw") return value
+
+  throw new Error(`Unknown sync attribute schema type for ${attributeName}: ${String(entry.type)}`)
+}
+
+/**
+ * Normalizes a string attribute: trims, rejects blank required values after trimming, maps empty optional values to null and bounds the trimmed length.
+ * @param {object} args - Options.
+ * @param {SyncAttributeSchemaEntry} args.entry - Schema entry.
+ * @param {SyncAttributeErrorFactory} args.errorFactory - Error factory.
+ * @param {string} args.label - Message/code label.
+ * @param {?} args.value - Raw value.
+ * @returns {string | null} Normalized string.
+ */
+function normalizeString({entry, errorFactory, label, value}) {
+  const requiredError = () => errorFactory(entry.requiredMessage ?? `${label} is required.`, {code: `sync-${label}-required`})
+
+  if (value === null || value === undefined || value === "") {
+    if (entry.required) throw requiredError()
+
+    return null
+  }
+
+  const stringValue = String(value).trim()
+
+  if (stringValue === "") {
+    if (entry.required) throw requiredError()
+
+    return null
+  }
+
+  if (entry.maxLength !== undefined && stringValue.length > entry.maxLength) {
+    throw errorFactory(entry.tooLongMessage ?? `${label} is too long (maximum is ${entry.maxLength} characters).`, {code: `sync-${label}-too-long`})
+  }
+
+  return stringValue
+}
+
+/**
+ * Normalizes a date attribute: Date instances pass through, strings/numbers are parsed and invalid or missing-required values are rejected.
+ * @param {object} args - Options.
+ * @param {SyncAttributeSchemaEntry} args.entry - Schema entry.
+ * @param {SyncAttributeErrorFactory} args.errorFactory - Error factory.
+ * @param {string} args.label - Message/code label.
+ * @param {?} args.value - Raw value.
+ * @returns {Date | null} Normalized date.
+ */
+function normalizeDate({entry, errorFactory, label, value}) {
+  if (!entry.required && (value === null || value === undefined || value === "")) return null
+
+  const dateValue = value instanceof Date ? value : typeof value == "string" || typeof value == "number" ? new Date(value) : null
+
+  if (!dateValue || Number.isNaN(dateValue.getTime())) {
+    throw errorFactory(entry.invalidMessage ?? `${label} must be a valid datetime.`, {code: `sync-${label}-invalid-datetime`})
+  }
+
+  return dateValue
+}
+
+/**
+ * Normalizes a json attribute: empty values become null, objects pass through, strings must parse as JSON and other types are rejected.
+ * @param {object} args - Options.
+ * @param {SyncAttributeSchemaEntry} args.entry - Schema entry.
+ * @param {SyncAttributeErrorFactory} args.errorFactory - Error factory.
+ * @param {string} args.label - Message/code label.
+ * @param {?} args.value - Raw value.
+ * @returns {?} Normalized json value.
+ */
+function normalizeJson({entry, errorFactory, label, value}) {
+  if (value === null || value === undefined || value === "") return null
+  if (typeof value == "object") return value
+
+  if (typeof value == "string") {
+    try {
+      return JSON.parse(value)
+    } catch (error) {
+      throw errorFactory(entry.invalidJsonMessage ?? `${label} must be valid JSON.`, {
+        cause: /** @type {Error} */ (error),
+        code: `sync-${label}-invalid-json`
+      })
+    }
+  }
+
+  throw errorFactory(entry.invalidMessage ?? `${label} must be an object or JSON string.`, {code: `sync-${label}-invalid`})
+}

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

@@ -1,5 +1,16 @@
 // @ts-check
 
+import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
+
+/**
+ * One declarative broadcast fanned out after a mutation applies.
+ * @typedef {object} SyncReplayBroadcast
+ * @property {string | ((args: Record<string, ?>) => string)} channel - Channel name or resolver.
+ * @property {(args: Record<string, ?>) => Record<string, ?>} broadcastParams - Channel routing params.
+ * @property {(args: Record<string, ?>) => ?} body - Broadcast body.
+ * @property {(args: Record<string, ?>) => boolean} [when] - Optional gate; skipped when it returns false.
+ */
+
 /**
  * Replays client sync envelopes through project supplied authentication,
  * authorization, application, and persistence hooks.
@@ -23,15 +34,49 @@ export default class SyncEnvelopeReplayService {
    * @param {{debug?: (...args: Array<unknown>) => void, warn?: (...args: Array<unknown>) => void}} [args.logger] - Logger used for normalization warnings.
    * @param {?} [args.syncModel] - Sync/change model enabling model-backed default hooks.
    * @param {string} [args.actorForeignKeyColumn] - Sync model column linking rows to the replay actor.
+   * @param {?} [args.authenticationTokenModel] - Token model enabling the default token-lookup authenticateReplay.
+   * @param {string} [args.authenticationTokenColumn] - Token model column holding the token. Defaults to "token".
+   * @param {string} [args.authenticationTokenParam] - Request param carrying the token. Defaults to "authenticationToken".
+   * @param {Record<string, ((args: Record<string, ?>) => Promise<?>) | ConstructorParameters<typeof SyncReplayUpsertApplier>[0]>} [args.applyHandlers] - Per-resourceType apply handlers (functions or declarative upsert-applier specs) enabling the default applyReplayMutation dispatch.
+   * @param {(args: Record<string, ?>) => Record<string, ?>} [args.persistExtraAttributes] - Extra attributes merged into the model-backed persisted row (e.g. an event scope column).
+   * @param {(args: {mutation: ?, applyResult: ?}) => ?} [args.persistSerializedData] - Overrides the persisted data payload (object results are JSON stringified).
+   * @param {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [args.broadcaster] - Delivers declarative broadcasts. Required when broadcasts are configured.
+   * @param {SyncReplayBroadcast[]} [args.broadcasts] - Broadcasts fanned out by the default afterReplayMutation.
    */
   constructor(args = {}) {
     this.logger = args.logger || console
     this.syncModel = args.syncModel || null
     this.actorForeignKeyColumn = args.actorForeignKeyColumn || "authentication_token_id"
+    this.authenticationTokenModel = args.authenticationTokenModel || null
+    this.authenticationTokenColumn = args.authenticationTokenColumn || "token"
+    this.authenticationTokenParam = args.authenticationTokenParam || "authenticationToken"
+    this.persistExtraAttributes = args.persistExtraAttributes || null
+    this.persistSerializedData = args.persistSerializedData || null
+    this.broadcaster = args.broadcaster || null
+    this.broadcasts = args.broadcasts || null
+    this.applyHandlers = args.applyHandlers ? this.builtApplyHandlers(args.applyHandlers) : null
 
     if (args.actorForeignKeyColumn !== undefined && (typeof args.actorForeignKeyColumn !== "string" || args.actorForeignKeyColumn.length < 1)) {
       throw new Error(`actorForeignKeyColumn must be a non-blank string, got: ${String(args.actorForeignKeyColumn)}`)
     }
+    if (this.broadcasts && !this.broadcaster) {
+      throw new Error("SyncEnvelopeReplayService broadcasts require a broadcaster option delivering them")
+    }
+  }
+
+  /**
+   * Wraps declarative apply-handler specs in upsert appliers.
+   * @param {Record<string, ?>} applyHandlers - Raw apply handlers.
+   * @returns {Record<string, (args: Record<string, ?>) => Promise<?>>} Callable handlers by resource type.
+   */
+  builtApplyHandlers(applyHandlers) {
+    return Object.fromEntries(Object.entries(applyHandlers).map(([resourceType, handler]) => {
+      if (typeof handler === "function") return [resourceType, handler]
+
+      const applier = new SyncReplayUpsertApplier(handler)
+
+      return [resourceType, (/** @type {Record<string, ?>} */ applyArgs) => applier.apply(/** @type {?} */ (applyArgs))]
+    }))
   }
 
   /**
@@ -91,11 +136,30 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Authenticates the sync batch actor.
-   * @param {Record<string, ?>} _params - Request params.
+   *
+   * Defaults to a token-model lookup when `authenticationTokenModel` is
+   * configured; otherwise apps override this hook.
+   * @param {Record<string, ?>} params - Request params.
    * @returns {Promise<{authenticated: true, actor: ?} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
    */
-  async authenticateReplay(_params) {
-    throw new Error("SyncEnvelopeReplayService.authenticateReplay must be implemented")
+  async authenticateReplay(params) {
+    if (!this.authenticationTokenModel) {
+      throw new Error("SyncEnvelopeReplayService.authenticateReplay must be implemented (or configure authenticationTokenModel)")
+    }
+
+    const token = params[this.authenticationTokenParam]
+
+    if (!token) {
+      return {authenticated: false, errorCode: "missing-authentication-token", errorMessage: "Missing authentication token"}
+    }
+
+    const actor = await this.authenticationTokenModel.findBy({[this.authenticationTokenColumn]: token})
+
+    if (!actor) {
+      return {authenticated: false, errorCode: "invalid-authentication-token", errorMessage: "Invalid authentication token"}
+    }
+
+    return {actor, authenticated: true}
   }
 
   /**
@@ -257,11 +321,20 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Applies one normalized mutation to domain models.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} _args - Actor, batch context, existing sync row, and mutation.
+   *
+   * Defaults to dispatching through the configured apply-handler registry;
+   * mutations without a registered handler fail loudly.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, existing sync row, and mutation.
    * @returns {Promise<?>} Project-specific apply result.
    */
-  async applyReplayMutation(_args) {
-    return null
+  async applyReplayMutation(args) {
+    if (!this.applyHandlers) return null
+
+    const applyHandler = this.applyHandlers[args.mutation.resourceType]
+
+    if (!applyHandler) throw new Error(`No sync apply handler registered for: ${args.mutation.resourceType}`)
+
+    return await applyHandler(args)
   }
 
   /**
@@ -281,11 +354,25 @@ export default class SyncEnvelopeReplayService {
    * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} args - Replay persistence arguments.
    * @returns {Promise<void>}
    */
-  async persistReplayMutation({actor, existingSync, mutation}) {
+  async persistReplayMutation({actor, applyResult, context, existingSync, mutation, shouldApply}) {
     if (!this.syncModel) return
 
     const attributes = this.replayPersistAttributes({actor, mutation})
 
+    // Stale replays never applied anything, so the applyResult-driven extension
+    // hooks must not run against the default null skipped result.
+    if (this.persistExtraAttributes && shouldApply) {
+      Object.assign(attributes, this.persistExtraAttributes({actor, applyResult, context, existingSync, mutation, shouldApply}))
+    }
+
+    if (this.persistSerializedData && shouldApply) {
+      const serializedData = this.persistSerializedData({applyResult, mutation})
+
+      if (serializedData !== undefined && serializedData !== null) {
+        attributes.data = typeof serializedData === "string" ? serializedData : JSON.stringify(serializedData)
+      }
+    }
+
     if (existingSync) {
       const existingClientUpdatedAt = this.existingReplaySyncClientUpdatedAt(existingSync)
 
@@ -317,10 +404,28 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Runs side effects after a successful mutation replay and persistence.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} _args - Replay side-effect arguments.
+   *
+   * Defaults to fanning the applied result out through the configured
+   * declarative broadcasts.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} args - Replay side-effect arguments.
    * @returns {Promise<void>}
    */
-  async afterReplayMutation(_args) {}
+  async afterReplayMutation(args) {
+    if (!this.broadcasts || !this.broadcaster) return
+    // Stale replays never applied anything - broadcasting their skipped results
+    // would fan out stale side effects (or crash on the default null applyResult).
+    if (!args.shouldApply) return
+
+    for (const broadcast of this.broadcasts) {
+      if (broadcast.when && !broadcast.when(args)) continue
+
+      await this.broadcaster({
+        body: broadcast.body(args),
+        channel: typeof broadcast.channel === "function" ? broadcast.channel(args) : broadcast.channel,
+        params: broadcast.broadcastParams(args)
+      })
+    }
+  }
 }
 
 /**