velocious 1.0.574 → 1.0.575

package/README.md

@@ -11,11 +11,11 @@
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
-* Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see [docs/offline-sync.md](docs/offline-sync.md))
+* Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
 * Declarative client sync scopes with per-scope cursors, automatic mutation tracking, realtime delivery whose per-recipient authorization hook receives the complete persisted sync envelope, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
 * Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
-* Server-side sync envelope replay orchestration for app-owned sync receivers (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
-* AwesomeTasks-shaped offline sync proof using routed resources, domain commands, signed offline grants, and peer-forwarded mutations (see [docs/awesome-tasks-offline-sync-proof.md](docs/awesome-tasks-offline-sync-proof.md))
+* Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative values for conflict resolution (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
+* AwesomeTasks-shaped offline sync proof using routed resources, domain commands, signed offline grants, and peer-forwarded mutations (see the [developer guide](docs/shared-resource-sync-guide.md) and [proof](docs/awesome-tasks-offline-sync-proof.md))
 * SQLite web persistence that automatically prefers OPFS, then IndexedDB, and migrates legacy persisted bytes when possible (see [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
@@ -2249,6 +2249,20 @@ await MyJob.performLaterWithOptions({
 
 Until `scheduledAtMs` is reached, the job remains queued but is not eligible for dispatch. The event-driven dispatcher arms its timer for the earliest future job and wakes at that timestamp. Omitting `scheduledAtMs` keeps the immediate-enqueue behavior.
 
+Use a durable stable key when the same logical one-off schedule must be moved or cancelled without retaining its transient job id:
+
+```js
+const result = await MyJob.replaceScheduled({
+  scheduleKey: `event:${eventId}:reminder:24h`,
+  args: [eventId, reminderRevision],
+  options: {scheduledAtMs: reminderAtMs}
+})
+
+await MyJob.cancelScheduled(`event:${eventId}:reminder:24h`)
+```
+
+A queued owner is atomically cancelled during replacement/cancellation. A `previousStatus` or cancellation `outcome` of `"handed_off"` means the worker may already be running; Velocious removes or replaces key ownership but does not claim that JavaScript stopped. Store a generation/revision in application state, pass it to the job, and re-check it immediately before irreversible effects. Stable keys and full result shapes are documented in [Scheduling One-Off Background Jobs](docs/scheduled-background-job-enqueue.md#replacing-or-cancelling-a-logical-schedule).
+
 Set `deduplicateWhileQueued: true` to coalesce an enqueue onto the earliest identical queued job with the same job name, arguments, and queue when that existing job is scheduled no later than the new request. A retry backed off into the future does not suppress a new immediate enqueue, while repeated immediate triggers and equal or later schedules still coalesce.
 
 Select a non-default runtime explicitly with `options: {executionMode: "inline" | "forked" | "spawned"}`.

package/build/background-jobs/client.js

@@ -13,6 +13,17 @@ export default class BackgroundJobsClient {
     this.configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
   }
 
+  /**
+   * Builds a one-shot client socket request from the resolved configuration.
+   * @returns {Promise<BackgroundJobsSocketRequest>} - Socket request.
+   */
+  async _request() {
+    const configuration = await this.configurationPromise
+    const {host, port} = configuration.getBackgroundJobsConfig()
+
+    return new BackgroundJobsSocketRequest({host, port, role: "client"})
+  }
+
   /**
    * Runs enqueue.
    * @param {object} args - Options.
@@ -22,9 +33,7 @@ export default class BackgroundJobsClient {
    * @returns {Promise<string>} - Job id.
    */
   async enqueue({jobName, args, options}) {
-    const configuration = await this.configurationPromise
-    const {host, port} = configuration.getBackgroundJobsConfig()
-    const request = new BackgroundJobsSocketRequest({host, port, role: "client"})
+    const request = await this._request()
 
     return await request.run({
       onConnect: (jsonSocket) => {
@@ -47,4 +56,63 @@ export default class BackgroundJobsClient {
       }
     })
   }
+
+  /**
+   * Atomically replaces the queued owner of a stable schedule key.
+   * @param {object} args - Options.
+   * @param {string} args.scheduleKey - Stable logical schedule key.
+   * @param {string} args.jobName - Job name.
+   * @param {Array<?>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  async replaceScheduled({scheduleKey, jobName, args, options}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "replace-scheduled", scheduleKey, jobName, args, options})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "schedule-replaced") {
+          resolve({
+            jobId: message.jobId,
+            previousJobId: message.previousJobId,
+            previousStatus: message.previousStatus
+          })
+          return
+        }
+
+        if (message?.type === "replace-scheduled-error") {
+          reject(new Error(message.error || "Failed to replace scheduled job"))
+        }
+      }
+    })
+  }
+
+  /**
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {object} args - Options.
+   * @param {string} args.scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  async cancelScheduled({scheduleKey}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "cancel-scheduled", scheduleKey})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "schedule-cancelled") {
+          resolve({jobId: message.jobId, outcome: message.outcome})
+          return
+        }
+
+        if (message?.type === "cancel-scheduled-error") {
+          reject(new Error(message.error || "Failed to cancel scheduled job"))
+        }
+      }
+    })
+  }
 }

package/build/background-jobs/job.js

@@ -100,6 +100,36 @@ export default class VelociousJob {
     })
   }
 
+  /**
+   * Atomically replaces this job class's queued owner for a stable schedule key.
+   * @param {object} args - Options.
+   * @param {string} args.scheduleKey - Stable logical schedule key.
+   * @param {Array<?>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  static async replaceScheduled({scheduleKey, args, options}) {
+    const client = new BackgroundJobsClient()
+
+    return await client.replaceScheduled({
+      scheduleKey,
+      jobName: this.jobName(),
+      args,
+      options: this._withQueue(options)
+    })
+  }
+
+  /**
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  static async cancelScheduled(scheduleKey) {
+    const client = new BackgroundJobsClient()
+
+    return await client.cancelScheduled({scheduleKey})
+  }
+
   /**
    * Runs split args and options.
    * @param {Array<?>} args - Job args.

package/build/background-jobs/main.js

@@ -538,6 +538,16 @@ export default class BackgroundJobsMain {
   _handleClientSocketMessage({jsonSocket, message}) {
     if (message?.type === "enqueue") {
       this._handleEnqueue({jsonSocket, message})
+      return
+    }
+
+    if (message?.type === "replace-scheduled") {
+      this._handleReplaceScheduled({jsonSocket, message})
+      return
+    }
+
+    if (message?.type === "cancel-scheduled") {
+      this._handleCancelScheduled({jsonSocket, message})
     }
   }
 
@@ -749,23 +759,99 @@ export default class BackgroundJobsMain {
       this._notifyEnqueued()
       await this._drain()
     } catch (error) {
-      if (error instanceof VelociousError && error.safeToExpose) {
-        jsonSocket.send({type: "enqueue-error", error: error.message})
-        return
-      }
-
-      const normalizedError = error instanceof Error ? error : new Error(String(error))
-      const payload = {
+      this._handleClientMutationError({
         context: {jobName: message.jobName, stage: "background-job-enqueue"},
-        error: normalizedError
-      }
-      const errorEvents = this.configuration.getErrorEvents()
+        error,
+        fallbackMessage: "Failed to enqueue job",
+        jsonSocket,
+        logMessage: "Failed to enqueue background job:",
+        responseType: "enqueue-error"
+      })
+    }
+  }
+
+  /**
+   * Handles a stable-key replacement request and re-arms dispatch afterward.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobReplaceScheduledMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleReplaceScheduled({jsonSocket, message}) {
+    try {
+      const result = await this.store.replaceScheduled({
+        scheduleKey: message.scheduleKey,
+        jobName: message.jobName,
+        args: message.args || [],
+        options: message.options || {}
+      })
+
+      jsonSocket.send({type: "schedule-replaced", ...result})
+      this._notifyEnqueued()
+      await this._drain()
+    } catch (error) {
+      this._handleClientMutationError({
+        context: {jobName: message.jobName, scheduleKey: message.scheduleKey, stage: "background-job-replace-scheduled"},
+        error,
+        fallbackMessage: "Failed to replace scheduled job",
+        jsonSocket,
+        logMessage: "Failed to replace scheduled background job:",
+        responseType: "replace-scheduled-error"
+      })
+    }
+  }
+
+  /**
+   * Handles a stable-key cancellation request and re-arms dispatch afterward.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobCancelScheduledMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleCancelScheduled({jsonSocket, message}) {
+    try {
+      const result = await this.store.cancelScheduled(message.scheduleKey)
+
+      jsonSocket.send({type: "schedule-cancelled", ...result})
+      this._notifyEnqueued()
+      await this._drain()
+    } catch (error) {
+      this._handleClientMutationError({
+        context: {scheduleKey: message.scheduleKey, stage: "background-job-cancel-scheduled"},
+        error,
+        fallbackMessage: "Failed to cancel scheduled job",
+        jsonSocket,
+        logMessage: "Failed to cancel scheduled background job:",
+        responseType: "cancel-scheduled-error"
+      })
+    }
+  }
 
-      this.logger.error(() => ["Failed to enqueue background job:", normalizedError])
-      errorEvents.emit("framework-error", payload)
-      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
-      jsonSocket.send({type: "enqueue-error", error: "Failed to enqueue job"})
+  /**
+   * Returns safe validation failures and reports unexpected client mutations.
+   * @param {object} args - Options.
+   * @param {Record<string, ?>} args.context - Framework-error context.
+   * @param {?} args.error - Mutation failure.
+   * @param {string} args.fallbackMessage - Client-safe fallback message.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {string} args.logMessage - Error log prefix.
+   * @param {"enqueue-error" | "replace-scheduled-error" | "cancel-scheduled-error"} args.responseType - Response type.
+   * @returns {void}
+   */
+  _handleClientMutationError({context, error, fallbackMessage, jsonSocket, logMessage, responseType}) {
+    if (error instanceof VelociousError && error.safeToExpose) {
+      jsonSocket.send({type: responseType, error: error.message})
+      return
     }
+
+    const normalizedError = error instanceof Error ? error : new Error(String(error))
+    const payload = {context, error: normalizedError}
+    const errorEvents = this.configuration.getErrorEvents()
+
+    this.logger.error(() => [logMessage, normalizedError])
+    errorEvents.emit("framework-error", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    jsonSocket.send({type: responseType, error: fallbackMessage})
   }
 
   /**