velocious 1.0.562 → 1.0.564

package/src/http-server/worker-handler/in-process.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import Client from "../client/index.js"
+import ClientDeliveryQueue from "../client-delivery-queue.js"
 import dispatchChannelSubscribers from "./channel-subscriber-dispatch.js"
 import Logger from "../../logger.js"
 import websocketEventsHost from "../websocket-events-host.js"
@@ -23,7 +24,7 @@ export default class VelociousHttpServerInProcessHandler {
 
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Record<number, {httpClient: Client, serverClient: import("../server-client.js").default}>} */
+     * @type {Record<number, {deliveryQueue: ClientDeliveryQueue, httpClient: Client, serverClient: import("../server-client.js").default}>} */
     this.clients = {}
 
     /** @type {Set<Promise<void>>} */
@@ -56,25 +57,36 @@ export default class VelociousHttpServerInProcessHandler {
       remoteAddress: serverClient.remoteAddress
     })
 
-    let deliveryQueue = Promise.resolve()
-    const enqueueDelivery = (/** @type {() => Promise<void>} */ delivery) => {
-      deliveryQueue = deliveryQueue
-        .catch(() => {})
-        .then(delivery)
-
-      return deliveryQueue
-    }
+    const {maxBytes, maxFrames} = this.configuration.getWebsocketOutboundQueueLimits()
+    const deliveryQueue = new ClientDeliveryQueue({
+      clientCount,
+      maxBytes,
+      maxFrames,
+      onOverflow: (error) => {
+        deliveryQueue.destroy()
+        serverClient.destroy(error)
+        this._reportOutboundQueueOverflow({clientCount, error})
+      }
+    })
 
-    httpClient.events.on("output", (output) => {
+    httpClient.events.on("output", (output, {websocketFrame = false} = {}) => {
       if (output !== null && output !== undefined) {
-        void enqueueDelivery(() => serverClient.send(output)).catch((error) => {
+        const delivery = () => serverClient.send(output)
+        const queued = websocketFrame
+          ? deliveryQueue.enqueueFrame({
+            byteLength: typeof output === "string" ? Buffer.byteLength(output) : output.byteLength,
+            delivery
+          })
+          : deliveryQueue.enqueueControl(delivery)
+
+        void queued.catch((error) => {
           this.logger.error(() => ["Failed to deliver client output", {clientCount}, error])
         })
       }
     })
 
     httpClient.events.on("file", ({filePath, sendBody, settle}) => {
-      void enqueueDelivery(async () => {
+      void deliveryQueue.enqueueControl(async () => {
         await settle(await serverClient.sendFile(filePath, sendBody))
       }).catch((error) => {
         this.logger.error(() => ["Failed to deliver file response", {clientCount, filePath}, error])
@@ -83,11 +95,12 @@ export default class VelociousHttpServerInProcessHandler {
     })
 
     httpClient.events.on("close", () => {
-      void enqueueDelivery(() => serverClient.end())
+      void deliveryQueue.enqueueControl(() => serverClient.end())
         .finally(() => delete this.clients[clientCount])
     })
 
     serverClient.events.on("close", () => {
+      deliveryQueue.destroy()
       const cleanup = httpClient.abortPendingFileResponses()
         .catch((error) => {
           this.logger.warn("Failed to abort file responses after client close", error)
@@ -100,7 +113,7 @@ export default class VelociousHttpServerInProcessHandler {
       this.pendingClientCloseCleanups.add(cleanup)
     })
 
-    this.clients[clientCount] = {httpClient, serverClient}
+    this.clients[clientCount] = {deliveryQueue, httpClient, serverClient}
 
     // Create a message-port shim so ServerClient.onSocketData can route data
     // to the in-process HTTP Client without needing a real worker thread.
@@ -118,6 +131,24 @@ export default class VelociousHttpServerInProcessHandler {
     serverClient.listen()
   }
 
+  /**
+   * Reports a per-client outbound queue overflow.
+   * @param {object} args - Overflow details.
+   * @param {number} args.clientCount - Affected client.
+   * @param {Error} args.error - Overflow error.
+   * @returns {void}
+   */
+  _reportOutboundQueueOverflow({clientCount, error}) {
+    const errorPayload = {
+      context: {clientCount, websocketOutboundQueueOverflow: true, workerCount: this.workerCount},
+      error
+    }
+    const errorEvents = this.configuration.getErrorEvents()
+
+    errorEvents.emit("framework-error", errorPayload)
+    errorEvents.emit("all-error", {...errorPayload, errorType: "framework-error"})
+  }
+
   /**
    * Runs stop.
    * @returns {Promise<void>} */
@@ -158,6 +189,14 @@ export default class VelociousHttpServerInProcessHandler {
     return this.configuration._broadcastToChannelLocal(channel, broadcastParams, body, {eventId})
   }
 
+  /**
+   * Gets the configuration-wide V2 broadcast target shared by in-process handlers.
+   * @returns {import("../../configuration.js").default} - Shared configuration target.
+   */
+  websocketV2BroadcastDispatchKey() {
+    return this.configuration
+  }
+
   /**
    * Runs dispatch websocket event.
    * @param {object} args - Options object.

package/src/http-server/worker-handler/index.js

@@ -2,6 +2,7 @@
 
 import {ensureError} from "typanic"
 import Logger from "../../logger.js"
+import ClientDeliveryQueue from "../client-delivery-queue.js"
 import {Worker} from "worker_threads"
 import websocketEventsHost from "../websocket-events-host.js"
 
@@ -59,7 +60,7 @@ export default class VelociousHttpServerWorker {
      * @type {Map<number, {resolve: (snapshot: Record<string, ?>) => void}>} */
     this._debugSnapshotRequests = new Map()
 
-    /** @type {Map<number, Promise<void>>} */
+    /** @type {Map<number, ClientDeliveryQueue>} */
     this._clientDeliveryQueues = new Map()
   }
 
@@ -117,6 +118,7 @@ export default class VelociousHttpServerWorker {
     if (!this.clients[clientCount] && !this._clientDeliveryQueues.has(clientCount)) return
 
     delete this.clients[clientCount]
+    this._clientDeliveryQueues.get(clientCount)?.destroy()
     this._clientDeliveryQueues.delete(clientCount)
     this.worker?.postMessage({command: "clientAbort", clientCount})
   }
@@ -163,6 +165,10 @@ export default class VelociousHttpServerWorker {
   _closeAllClients() {
     const clients = Object.values(this.clients)
     this.clients = {}
+    const deliveryQueues = this._clientDeliveryQueues
+    this._clientDeliveryQueues = new Map()
+
+    for (const queue of deliveryQueues.values()) queue.destroy()
 
     for (const client of clients) {
       try {
@@ -182,6 +188,7 @@ export default class VelociousHttpServerWorker {
    * @param {string} [data.filePath] - File path.
    * @param {boolean} [data.sendBody] - Whether to send the file body.
    * @param {number} [data.transferId] - File transfer id.
+   * @param {boolean} [data.websocketFrame] - Whether output is a completed WebSocket frame.
    * @param {string} [data.channel] - Channel name.
    * @param {number} [data.requestId] - Debug request id.
    * @param {Record<string, ?>} [data.snapshot] - Worker debug snapshot.
@@ -219,7 +226,11 @@ export default class VelociousHttpServerWorker {
       if (output !== null && output !== undefined) {
         const outputLength = typeof output === "string" ? output.length : output.byteLength
 
-        void this.enqueueClientDelivery(client.clientCount, () => client.send(output)).then(() => {
+        const delivery = data.websocketFrame === true
+          ? this.enqueueClientFrame(client, output)
+          : this.enqueueClientControl(client, () => client.send(output))
+
+        void delivery.then(() => {
           this.logger.debug(() => ["Client output delivered", {
             clientCount,
             outputLength,
@@ -243,7 +254,7 @@ export default class VelociousHttpServerWorker {
         return
       }
 
-      void this.enqueueClientDelivery(client.clientCount, async () => {
+      void this.enqueueClientControl(client, async () => {
         const result = await client.sendFile(filePath, sendBody !== false)
 
         this.worker?.postMessage({command: "clientFileResult", result, transferId})
@@ -260,7 +271,7 @@ export default class VelociousHttpServerWorker {
         return
       }
 
-      void this.enqueueClientDelivery(client.clientCount, () => client.end())
+      void this.enqueueClientControl(client, () => client.end())
         .finally(() => delete this.clients[client.clientCount])
     } else if (command == "debugSnapshot") {
       const {requestId, snapshot} = data
@@ -289,7 +300,12 @@ export default class VelociousHttpServerWorker {
         throw new Error("Worker websocket v2-broadcast channel must be a string")
       }
 
-      websocketEventsHost.broadcastV2({body, broadcastParams: broadcastParams || {}, channel})
+      websocketEventsHost.broadcastV2({
+        body,
+        broadcastParams: broadcastParams || {},
+        channel,
+        configuration: this.configuration
+      })
     } else {
       throw new Error(`Unknown command: ${command}`)
     }
@@ -297,24 +313,70 @@ export default class VelociousHttpServerWorker {
 
   /**
    * Preserves socket output ordering for one client.
-   * @param {number} clientCount - Client count.
+   * @param {import("../server-client.js").default} client - Client instance.
+   * @param {string | Uint8Array} output - Complete output buffer.
+   * @returns {Promise<void>} - Queued delivery.
+   */
+  enqueueClientFrame(client, output) {
+    const byteLength = typeof output === "string" ? Buffer.byteLength(output) : output.byteLength
+
+    return this._deliveryQueueFor(client).enqueueFrame({
+      byteLength,
+      delivery: () => client.send(output)
+    })
+  }
+
+  /**
+   * Preserves ordering for a delivery that retains no complete output frame.
+   * @param {import("../server-client.js").default} client - Client instance.
    * @param {() => Promise<void>} delivery - Delivery operation.
    * @returns {Promise<void>} - Queued delivery.
    */
-  enqueueClientDelivery(clientCount, delivery) {
-    const previous = this._clientDeliveryQueues.get(clientCount) || Promise.resolve()
-    const queued = previous
-      .catch(() => {})
-      .then(delivery)
-
-    this._clientDeliveryQueues.set(clientCount, queued)
-    const clearQueue = () => {
-      if (this._clientDeliveryQueues.get(clientCount) === queued) this._clientDeliveryQueues.delete(clientCount)
-    }
+  enqueueClientControl(client, delivery) {
+    return this._deliveryQueueFor(client).enqueueControl(delivery)
+  }
 
-    void queued.then(clearQueue, clearQueue)
+  /**
+   * Gets or creates one client's delivery queue.
+   * @param {import("../server-client.js").default} client - Client instance.
+   * @returns {ClientDeliveryQueue} - Client-owned delivery queue.
+   */
+  _deliveryQueueFor(client) {
+    const existing = this._clientDeliveryQueues.get(client.clientCount)
+    if (existing) return existing
+
+    const {maxBytes, maxFrames} = this.configuration.getWebsocketOutboundQueueLimits()
+    const queue = new ClientDeliveryQueue({
+      clientCount: client.clientCount,
+      maxBytes,
+      maxFrames,
+      onOverflow: (error) => {
+        queue.destroy()
+        client.destroy(error)
+        this._reportOutboundQueueOverflow({clientCount: client.clientCount, error})
+      }
+    })
+
+    this._clientDeliveryQueues.set(client.clientCount, queue)
+    return queue
+  }
+
+  /**
+   * Reports a per-client outbound queue overflow.
+   * @param {object} args - Overflow details.
+   * @param {number} args.clientCount - Affected client.
+   * @param {Error} args.error - Overflow error.
+   * @returns {void}
+   */
+  _reportOutboundQueueOverflow({clientCount, error}) {
+    const errorPayload = {
+      context: {clientCount, websocketOutboundQueueOverflow: true, workerCount: this.workerCount},
+      error
+    }
+    const errorEvents = this.configuration.getErrorEvents()
 
-    return queued
+    errorEvents.emit("framework-error", errorPayload)
+    errorEvents.emit("all-error", {...errorPayload, errorType: "framework-error"})
   }
 
   /**
@@ -410,6 +472,14 @@ export default class VelociousHttpServerWorker {
     this.worker.postMessage({body, broadcastParams, channel, command: "websocketV2Broadcast", eventId, createdAt})
   }
 
+  /**
+   * Gets this worker's isolated V2 broadcast target.
+   * @returns {VelociousHttpServerWorker} - This worker handler.
+   */
+  websocketV2BroadcastDispatchKey() {
+    return this
+  }
+
   /**
    * Runs register with events host.
    * @returns {void} */

package/src/http-server/worker-handler/worker-thread.js

@@ -154,8 +154,8 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
       remoteAddress
     })
 
-    client.events.on("output", (output) => {
-      this.parentPort.postMessage({command: "clientOutput", clientCount, output})
+    client.events.on("output", (output, {websocketFrame = false} = {}) => {
+      this.parentPort.postMessage({command: "clientOutput", clientCount, output, websocketFrame})
     })
 
     client.events.on("file", ({filePath, sendBody, settle}) => {

package/src/plugins/sqljs-wasm-route.js

@@ -2,23 +2,21 @@ import {createRequire} from "node:module"
 import path from "node:path"
 import SqlJsWasmRouteController from "./sqljs-wasm-route-controller.js"
 
-const require = createRequire(import.meta.url)
-const sqlJsEntryPath = require.resolve("sql.js")
-const sqlJsDistDirectory = path.dirname(sqlJsEntryPath)
-
 /**
  * InstallSqlJsWasmRouteArgs type.
  * @typedef {object} InstallSqlJsWasmRouteArgs
  * @property {import("../configuration.js").default} configuration - Velocious configuration instance.
  * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
  */
-
 /**
  * SqlJsLocateFileFromBackendArgs type.
  * @typedef {object} SqlJsLocateFileFromBackendArgs
  * @property {string} backendBaseUrl - Backend base URL (for example `https://api.example.com`).
  * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
  */
+const require = createRequire(import.meta.url)
+const sqlJsEntryPath = require.resolve("sql.js")
+const sqlJsDistDirectory = path.dirname(sqlJsEntryPath)
 
 /**
  * Runs normalize route prefix.

package/src/sync/conflict-strategy.js

@@ -1,17 +1,11 @@
-// @ts-check
-
-const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"])
-
 /**
  * @typedef {null | string | number | boolean | unknown[] | Record<string, unknown>} SyncJsonValue
  */
-
 /**
  * @typedef {object} SyncConflictRecord
  * @property {Record<string, SyncJsonValue>} attributes - Record attributes.
  * @property {string | number | boolean | null} [version] - Record version value.
  */
-
 /**
  * @typedef {object} SyncConflictResult
  * @property {Record<string, SyncJsonValue>} [attributes] - Attributes to apply when replay may continue.
@@ -19,6 +13,9 @@ const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWri
  * @property {"applied" | "conflict" | "rejected"} status - Conflict decision.
  * @property {string} strategy - Strategy that produced the decision.
  */
+// @ts-check
+
+const CONFLICT_STRATEGIES = new Set(["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"])
 
 /**
  * Evaluates a replay mutation against server/base state using a sync conflict strategy.

package/src/sync/device-identity.js

@@ -1,13 +1,7 @@
-// @ts-check
-
-const ECDSA_P256_SHA256_ALGORITHM = "ECDSA-P256-SHA256"
-const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
-
 /**
  * JSON Web Key used by the sync signing helpers.
  * @typedef {import("node:crypto").webcrypto.JsonWebKey} SyncJsonWebKey
  */
-
 /**
  * Backend-signed device certificate payload.
  * @typedef {object} DeviceCertificatePayload
@@ -18,7 +12,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {string} expiresAt - ISO timestamp after which the certificate is invalid.
  * @property {string} issuedAt - ISO timestamp when the backend issued the certificate.
  */
-
 /**
  * Backend-signed device certificate envelope.
  * @typedef {object} DeviceCertificate
@@ -26,7 +19,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {DeviceCertificatePayload} certificate - Certificate payload.
  * @property {string} signature - Backend signature over the certificate payload.
  */
-
 /**
  * Sync mutation payload signed by a device.
  * @typedef {object} SyncMutation
@@ -43,7 +35,6 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [payload] - Domain command payload.
  * @property {string} policyHash - Sync policy hash the mutation was checked against.
  */
-
 /**
  * Device-signed mutation envelope.
  * @typedef {object} SignedSyncMutation
@@ -52,6 +43,10 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
  * @property {SyncMutation} mutation - Mutation payload.
  * @property {string} signature - Device signature over the mutation envelope.
  */
+// @ts-check
+
+const ECDSA_P256_SHA256_ALGORITHM = "ECDSA-P256-SHA256"
+const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
 
 /**
  * Generates an ECDSA P-256 keypair exported as JWKs.

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

@@ -1,19 +1,8 @@
-// @ts-check
-
-const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
-const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
-const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
-const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
-const TERMINAL_STATUSES = new Set(["rejected", "synced"])
-/** @type {Map<string, Promise<unknown>>} */
-const STORAGE_KEY_LOCKS = new Map()
-
 /**
  * Local mutation log record query options.
  * @typedef {object} LocalMutationLogRecordsOptions
  * @property {LocalMutationStatus[]} [statuses] - Optional status filter.
  */
-
 /**
  * Local mutation log row-oriented storage adapter.
  *
@@ -28,19 +17,16 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {(storageKey: string, options?: LocalMutationLogRecordsOptions) => Promise<LocalMutationLogRecord[]> | LocalMutationLogRecord[]} records - Reads log records.
  * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} updateRecord - Replaces one log record.
  */
-
 /**
  * Local sync mutation dependency metadata.
  * @typedef {object} LocalMutationDependency
  * @property {string} clientMutationId - Client mutation id this mutation depends on.
  * @property {string} model - Dependent model/resource name.
  */
-
 /**
  * Local mutation log status.
  * @typedef {"pending" | "applied-locally" | "peer-applied" | "conflict" | "rejected" | "synced"} LocalMutationStatus
  * */
-
 /**
  * Local mutation log record.
  * @typedef {object} LocalMutationLogRecord
@@ -53,6 +39,15 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [syncResult] - Backend replay/result metadata.
  * @property {string} updatedAt - ISO timestamp when the record was last changed.
  */
+// @ts-check
+
+const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
+const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
+const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
+const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
+const TERMINAL_STATUSES = new Set(["rejected", "synced"])
+/** @type {Map<string, Promise<unknown>>} */
+const STORAGE_KEY_LOCKS = new Map()
 
 /** Client-side append-only sync mutation log with pluggable persistent storage. */
 export default class LocalMutationLog {

package/src/sync/offline-grant.js

@@ -1,8 +1,3 @@
-// @ts-check
-
-const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
-const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
-
 /**
  * Signed offline grant envelope.
  * @typedef {object} SignedOfflineGrant
@@ -11,7 +6,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} keyId - Signing key id.
  * @property {string} signature - Hex HMAC signature with a hmac-sha256 prefix.
  */
-
 /**
  * Backend-issued offline grant payload.
  * @typedef {object} OfflineGrant
@@ -23,7 +17,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} scopes - Materialized grant scopes.
  * @property {string} userId - Actor user id allowed to use the grant.
  */
-
 /**
  * Offline grant signing key.
  * @typedef {object} OfflineGrantSigningKey
@@ -31,6 +24,10 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} id - Public key id included in signed grant envelopes.
  * @property {string} secret - Private HMAC secret. Never expose this to clients.
  */
+// @ts-check
+
+const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
+const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
 
 /**
  * Creates a signed offline grant envelope.

package/src/sync/peer-mutation-bundle.js

@@ -2,9 +2,6 @@
 
 import {createSignedMutation, mutationIdempotencyKey, verifySignedMutation} from "./device-identity.js"
 
-const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
-const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
-
 /**
  * Peer mutation bundle exported by a device for offline/P2P transfer.
  * @typedef {object} PeerMutationBundle
@@ -12,7 +9,6 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {"velocious.sync.peer-mutation-bundle.v1"} format - Bundle format identifier.
  * @property {PeerMutationBundleEntry[]} mutations - Signed mutations in local sequence order.
  */
-
 /**
  * One peer mutation bundle entry.
  * @typedef {object} PeerMutationBundleEntry
@@ -20,6 +16,8 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {number} [localSequence] - Exporting device's local mutation sequence.
  * @property {import("./device-identity.js").SignedSyncMutation} signedMutation - Device-signed mutation envelope.
  */
+const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
+const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
 
 /**
  * Exports local non-terminal mutations as a signed peer-transfer bundle.

package/src/sync/server-change-feed.js

@@ -4,6 +4,38 @@ import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
 import stableJsonStringify from "./stable-json.js"
 
+/**
+ * @typedef {object} ServerChangeFeedEntry
+ * @property {string | null} actorDeviceId - Signed mutation actor device id when available.
+ * @property {string | null} actorUserId - Signed mutation actor user id when available.
+ * @property {Record<string, ?> | null} attributes - Serialized mutation attributes.
+ * @property {string} createdAt - Server change creation timestamp.
+ * @property {string} id - Server change id.
+ * @property {string | null} idempotencyKey - Mutation idempotency key when available.
+ * @property {string} model - Frontend model name.
+ * @property {string} operation - Mutation operation.
+ * @property {Record<string, ?> | null} payload - Serialized mutation payload.
+ * @property {string | null} recordId - Changed record id when known.
+ * @property {Record<string, ?> | null} response - Command response payload.
+ * @property {Record<string, ?> | null} scope - Offline grant scope.
+ * @property {number} serverSequence - Monotonic server sequence.
+ */
+/**
+ * @typedef {object} ServerChangeFeedRow
+ * @property {string | null} actor_device_id - Actor device id.
+ * @property {string | null} actor_user_id - Actor user id.
+ * @property {string | null} attributes_json - Attributes JSON.
+ * @property {Date | string} created_at - Creation time.
+ * @property {string} id - Entry id.
+ * @property {string | null} idempotency_key - Mutation idempotency key.
+ * @property {string} model - Frontend model name.
+ * @property {string} operation - Mutation operation.
+ * @property {string | null} payload_json - Mutation payload JSON.
+ * @property {string | null} record_id - Record id.
+ * @property {string | null} response_json - Response JSON.
+ * @property {string | null} scope_json - Scope JSON.
+ * @property {number | string} server_sequence - Server sequence.
+ */
 const DEFAULT_RETENTION_SIZE = 10000
 const DEFAULT_PAGE_SIZE = 100
 const MAX_PAGE_SIZE = 1000
@@ -464,37 +496,3 @@ function scopesEqual(changeScope, requestedScope) {
 
   return stableJsonStringify(changeScope || null) === stableJsonStringify(requestedScope)
 }
-
-/**
- * @typedef {object} ServerChangeFeedEntry
- * @property {string | null} actorDeviceId - Signed mutation actor device id when available.
- * @property {string | null} actorUserId - Signed mutation actor user id when available.
- * @property {Record<string, ?> | null} attributes - Serialized mutation attributes.
- * @property {string} createdAt - Server change creation timestamp.
- * @property {string} id - Server change id.
- * @property {string | null} idempotencyKey - Mutation idempotency key when available.
- * @property {string} model - Frontend model name.
- * @property {string} operation - Mutation operation.
- * @property {Record<string, ?> | null} payload - Serialized mutation payload.
- * @property {string | null} recordId - Changed record id when known.
- * @property {Record<string, ?> | null} response - Command response payload.
- * @property {Record<string, ?> | null} scope - Offline grant scope.
- * @property {number} serverSequence - Monotonic server sequence.
- */
-
-/**
- * @typedef {object} ServerChangeFeedRow
- * @property {string | null} actor_device_id - Actor device id.
- * @property {string | null} actor_user_id - Actor user id.
- * @property {string | null} attributes_json - Attributes JSON.
- * @property {Date | string} created_at - Creation time.
- * @property {string} id - Entry id.
- * @property {string | null} idempotency_key - Mutation idempotency key.
- * @property {string} model - Frontend model name.
- * @property {string} operation - Mutation operation.
- * @property {string | null} payload_json - Mutation payload JSON.
- * @property {string | null} record_id - Record id.
- * @property {string | null} response_json - Response JSON.
- * @property {string | null} scope_json - Scope JSON.
- * @property {number | string} server_sequence - Server sequence.
- */

package/src/sync/sync-api-client.js

@@ -4,8 +4,6 @@ import {optionalBoolean, optionalInteger} from "typanic"
 
 import recordChanges from "../database/record-changes.js"
 
-const syncTaskPromises = new Map()
-
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
 /** @typedef {import("./sync-api-client-types.js").SyncChangeEnvelope} SyncChangeEnvelope */
 /** @typedef {import("./sync-api-client-types.js").SyncChangesRequest} SyncChangesRequest */
@@ -15,6 +13,7 @@ const syncTaskPromises = new Map()
 /** @typedef {import("./sync-api-client-types.js").SyncReplayItem} SyncReplayItem */
 /** @typedef {import("./sync-api-client-types.js").SyncReplayResponse} SyncReplayResponse */
 /** @typedef {import("./sync-api-client-types.js").SyncResourceConfig} SyncResourceConfig */
+const syncTaskPromises = new Map()
 
 /**
  * Generic client-side helper for replaying pending sync envelopes through the