velocious 1.0.504 → 1.0.506

package/src/configuration-types.js

@@ -419,6 +419,8 @@
  * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
  * @property {VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {VelociousSyncClientTransport} transport - Transport posting to the framework sync endpoints (e.g. the frontend-model websocket client).
+ * @property {VelociousSyncRealtimeWebsocketClient} [websocketClient] - Shared app-lifetime websocket client (the low-level form) that all sync traffic rides. Provide the same instance the frontend-model transport uses so one connection carries everything. When set, the realtime bridge subscribes channels on it and never owns its lifecycle: unsubscribing closes only channel subscriptions, leaving the socket connected.
+ * @property {string | (() => string | null | undefined)} [websocketUrl] - Shared app-lifetime websocket URL. When set (and no `websocketClient` is given), the framework builds and owns one reconnecting `VelociousWebsocketClient` for all sync traffic, connected on first use.
  */
 
 /**

package/src/configuration.js

@@ -463,11 +463,11 @@ export default class VelociousConfiguration {
       throw new Error("sync.client must be an object with transport and authenticationToken")
     }
 
-    const {authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport, ...restClient} = client
+    const {authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport, websocketClient, websocketUrl, ...restClient} = client
     const restClientKeys = Object.keys(restClient)
 
     if (restClientKeys.length > 0) {
-      throw new Error(`sync.client received unknown keys: ${restClientKeys.join(", ")} (supported: authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport)`)
+      throw new Error(`sync.client received unknown keys: ${restClientKeys.join(", ")} (supported: authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport, websocketClient, websocketUrl)`)
     }
     if (!transport || typeof transport !== "object" || typeof transport.post !== "function") {
       throw new Error("sync.client.transport must be an object with a post(path, body) method (like the frontend-model websocket client)")
@@ -487,6 +487,12 @@ export default class VelociousConfiguration {
     if (mountPath !== undefined && (typeof mountPath !== "string" || !mountPath.startsWith("/"))) {
       throw new Error(`sync.client.mountPath must start with '/', got: ${String(mountPath)}`)
     }
+    if (websocketClient !== undefined && (typeof websocketClient !== "object" || websocketClient === null || typeof websocketClient.subscribeChannel !== "function")) {
+      throw new Error("sync.client.websocketClient must be a websocket client with a subscribeChannel method (like VelociousWebsocketClient)")
+    }
+    if (websocketUrl !== undefined && typeof websocketUrl !== "string" && typeof websocketUrl !== "function") {
+      throw new Error(`sync.client.websocketUrl must be a URL string or a function resolving one, got: ${String(websocketUrl)}`)
+    }
 
     return {
       authenticationToken,
@@ -495,7 +501,9 @@ export default class VelociousConfiguration {
       mountPath: (mountPath || "/velocious/sync").replace(/\/+$/u, "") || "/",
       onError,
       realtime,
-      transport
+      transport,
+      websocketClient,
+      websocketUrl
     }
   }
 

package/src/database/drivers/sqlite/table-rebuilder.js

@@ -52,6 +52,23 @@ export default class VelociousDatabaseDriversSqliteTableRebuilder {
     const targetTableData = this.targetTableData
     const previousTargetName = targetTableData.getName()
 
+    // Column-level `index: true` indexes are named after the table they are created with, and
+    // ALTER TABLE ... RENAME does not rename indexes - creating them inside the temp table's
+    // CREATE would leak the temp rebuild name permanently. Strip the flags for the temp CREATE
+    // and create those indexes explicitly on the temp table with their FINAL names BEFORE the
+    // copy: index names are database-global and survive the rename, and a violation (e.g. a new
+    // unique index over rows that all receive the same default) fails during INSERT...SELECT,
+    // while the original table still exists - never after the swap.
+    /** @type {Array<{column: import("../../table-data/table-column.js").default, index: ?, indexArgs: ?}>} */
+    const strippedColumnIndexes = []
+
+    for (const column of targetTableData.getColumns()) {
+      if (!column.getIndex()) continue
+
+      strippedColumnIndexes.push({column, index: column.getIndex(), indexArgs: column.getIndexArgs()})
+      column.setIndex(false)
+    }
+
     targetTableData.setName(tempTableName)
 
     let createTableSQLs
@@ -60,6 +77,8 @@ export default class VelociousDatabaseDriversSqliteTableRebuilder {
       createTableSQLs = await driver.createTableSql(targetTableData)
     } finally {
       targetTableData.setName(previousTargetName)
+
+      for (const {column, index} of strippedColumnIndexes) column.setIndex(index)
     }
 
     const newColumnsSQL = this.columnPairs.map(([, newName]) => options.quoteColumnName(newName)).join(", ")
@@ -69,6 +88,22 @@ export default class VelociousDatabaseDriversSqliteTableRebuilder {
 
     for (const sql of createTableSQLs) sqls.push(sql)
 
+    for (const {column, indexArgs} of strippedColumnIndexes) {
+      const {unique, ...restIndexArgs} = indexArgs || {}
+
+      restArgsError(restIndexArgs)
+
+      const createIndexSQLs = await new CreateIndexBase({
+        columns: [column.getName()],
+        driver,
+        name: `index_on_${originalTableName}_${column.getName()}`,
+        tableName: tempTableName,
+        unique
+      }).toSQLs()
+
+      for (const sql of createIndexSQLs) sqls.push(sql)
+    }
+
     if (this.columnPairs.length > 0) {
       sqls.push(
         `INSERT INTO ${options.quoteTableName(tempTableName)} (${newColumnsSQL}) ` +

package/src/sync/query-scope.js

@@ -44,12 +44,19 @@ export function serializedScopeFromQuery(query) {
 }
 
 /**
- * Returns a stable canonical key identifying a sync scope.
+ * Returns a stable canonical key identifying a sync scope. When an `owner` is
+ * present (the authenticated identity that declared the scope locally), it
+ * participates in the key so the same wire scope owned by a different user gets
+ * its own local identity and cursor — a user scope's empty-conditions cursor
+ * never leaks across accounts on a shared device, while the same user
+ * reconnecting keeps continuity. Owner-less scopes keep their pre-owner key.
  * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
  * @returns {string} Stable scope key.
  */
 export function scopeKey(scope) {
-  return `${scope.resourceType}:${stableJsonStringify(scope.conditions)}`
+  const ownerPrefix = scope.owner === undefined || scope.owner === null ? "" : `owner=${stableJsonStringify(scope.owner)}|`
+
+  return `${ownerPrefix}${scope.resourceType}:${stableJsonStringify(scope.conditions)}`
 }
 
 /**

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

@@ -5,6 +5,7 @@
  * @typedef {object} SerializedSyncScope
  * @property {Record<string, ?>} conditions - Plain attribute conditions from the query.
  * @property {string} resourceType - Resource/model name the scope was declared for.
+ * @property {string} [owner] - Local partition key: the authenticated identity that declared the scope. Used only to partition the local scope/cursor store (never sent to the server as scope conditions), so a user scope's empty-conditions cursor does not leak across accounts on a shared device.
  */
 
 /**
@@ -58,6 +59,13 @@
  * @typedef {boolean | ModelSyncDeclarationConfig<TModel>} ModelSyncDeclaration
  */
 
+/**
+ * Shared app-lifetime websocket connection all sync traffic rides. Matches the
+ * realtime websocket client contract; the sync client rides it without owning
+ * its connect/disconnect lifecycle.
+ * @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} SyncClientSharedConnection
+ */
+
 /**
  * Options for building a sync client. Everything else — resources, transport
  * POSTers, auth, connectivity, batch size — is derived from the configuration's
@@ -84,6 +92,8 @@
  * @property {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {Record<string, SyncClientResourceConfig>} resources - Derived resource policies keyed by resource/model name.
  * @property {?} syncModel - Local pending-sync model class.
+ * @property {SyncClientSharedConnection} [websocketClient] - Shared app-lifetime websocket client instance (the low-level shared-connection form).
+ * @property {string | (() => string | null | undefined)} [websocketUrl] - Shared app-lifetime websocket URL the framework builds a client from.
  */
 
 export {}

package/src/sync/sync-client.js

@@ -4,6 +4,7 @@ import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
 import Logger from "../logger.js"
 import restArgsError from "../utils/rest-args-error.js"
+import VelociousWebsocketClient from "../http-client/websocket-client.js"
 
 import {serializedScopeFromQuery} from "./query-scope.js"
 import SyncApiClient from "./sync-api-client.js"
@@ -99,11 +100,19 @@ export default class SyncClient {
       postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, transport: clientConfiguration.transport}),
       realtime: clientConfiguration.realtime,
       resources,
-      syncModel: resolvedSyncModel
+      syncModel: resolvedSyncModel,
+      websocketClient: clientConfiguration.websocketClient,
+      websocketUrl: clientConfiguration.websocketUrl
     }
     this._clientNumber = ++clientCounter
     /** @type {SyncRealtimeBridge | null} */
     this._realtimeBridge = null
+    /** @type {import("./sync-client-types.js").SyncClientSharedConnection | null | undefined} Shared app-lifetime websocket connection (undefined until first resolved, null when none is configured). */
+    this._syncConnection = undefined
+    /** @type {Promise<void> | null} */
+    this._subscribeUserScopePromise = null
+    /** @type {"subscribed" | "subscribing" | "unsubscribed"} */
+    this._userScopeState = "unsubscribed"
     /** @type {import("./sync-scope-store.js").default | null} */
     this._scopeStore = scopeStore || null
     /** @type {Promise<void> | null} */
@@ -449,6 +458,33 @@ export default class SyncClient {
     }
   }
 
+  /**
+   * Resolves the shared app-lifetime websocket connection all sync traffic
+   * rides, or null when none is configured. Built once and memoized (per
+   * client): an app-provided `sync.client.websocketClient` instance wins (the
+   * frontend-model transport can pass its own client so one socket carries
+   * everything), else a framework-owned reconnecting {@link VelociousWebsocketClient}
+   * built from `sync.client.websocketUrl`. The realtime bridge rides this
+   * connection without owning its lifecycle; when neither is configured the
+   * bridge falls back to the deprecated per-cycle `realtime.createClient`.
+   * @returns {import("./sync-client-types.js").SyncClientSharedConnection | null} Shared websocket connection, or null.
+   */
+  syncConnection() {
+    if (this._syncConnection !== undefined) return this._syncConnection
+
+    if (this.config.websocketClient) {
+      this._syncConnection = this.config.websocketClient
+    } else if (this.config.websocketUrl) {
+      const url = typeof this.config.websocketUrl === "function" ? this.config.websocketUrl() : this.config.websocketUrl
+
+      this._syncConnection = url ? new VelociousWebsocketClient({url}) : null
+    } else {
+      this._syncConnection = null
+    }
+
+    return this._syncConnection
+  }
+
   /**
    * Subscribes the derived realtime channels so pushed websocket changes apply
    * through the same derived applier as pulls (idempotent, single-flighted).
@@ -459,6 +495,94 @@ export default class SyncClient {
     await this.realtimeBridge().subscribe(context)
   }
 
+  /**
+   * Subscribes the server-enumerated user scope: "everything my ability can
+   * see". Declares a user scope (empty conditions) for every pullable synced
+   * resource type, subscribes realtime so their framework sync channel
+   * subscriptions go live, and pulls so the device catches up. The server
+   * authorizes each empty-conditions scope through the app sync resource's
+   * `authorizeChanges` and re-checks record access per delivery, so the client
+   * subscribes with just its token and the server decides membership.
+   * Idempotent and single-flighted like {@link SyncClient#subscribeRealtime}.
+   * @returns {Promise<void>}
+   */
+  async subscribeUserScope() {
+    if (this._userScopeState === "subscribed") return
+
+    if (!this._subscribeUserScopePromise) {
+      this._subscribeUserScopePromise = this._subscribeUserScope().finally(() => {
+        this._subscribeUserScopePromise = null
+      })
+    }
+
+    await this._subscribeUserScopePromise
+  }
+
+  /**
+   * Declares and activates the user scope for every pullable resource, then
+   * subscribes realtime and pulls.
+   * @returns {Promise<void>}
+   */
+  async _subscribeUserScope() {
+    this._userScopeState = "subscribing"
+
+    const scopeStore = this.scopeStore()
+    const owner = await this.userScopeOwner()
+
+    for (const resourceType of this.userScopeResourceTypes()) {
+      await scopeStore.findOrCreateScope({conditions: {}, owner, resourceType})
+    }
+
+    await this.subscribeRealtime()
+    await this.pull()
+
+    this._userScopeState = "subscribed"
+  }
+
+  /**
+   * Unsubscribes the user scope: deactivates the per-resource user scopes and
+   * closes the realtime channel subscriptions. The shared websocket connection
+   * stays open when one is configured (sign-out drops subscriptions without
+   * disconnecting), so a subsequent sign-in resubscribes over the same socket.
+   * @returns {Promise<void>}
+   */
+  async unsubscribeUserScope() {
+    const scopeStore = this.scopeStore()
+    const owner = await this.userScopeOwner()
+
+    for (const resourceType of this.userScopeResourceTypes()) {
+      await scopeStore.deactivate({conditions: {}, owner, resourceType})
+    }
+
+    await this.unsubscribeRealtime()
+
+    this._userScopeState = "unsubscribed"
+    this._subscribeUserScopePromise = null
+  }
+
+  /**
+   * The resource types a user scope covers: every declared resource that
+   * receives pulled changes (has pull `attributes`).
+   * @returns {string[]} Pullable resource type names.
+   */
+  userScopeResourceTypes() {
+    return Object.keys(this.pullResourceConfigs())
+  }
+
+  /**
+   * Resolves the local partition key for the user scope: the currently
+   * configured authenticated identity (the sync auth token). Partitioning the
+   * user scope's local scope/cursor rows by this owner keeps the
+   * empty-conditions cursor from leaking across accounts on a shared device
+   * (account B signing in after account A gets a fresh cursor) while the same
+   * account reconnecting keeps its cursor continuity. The owner is a local
+   * partition key only — pulls still post empty conditions to the server.
+   * @returns {Promise<string>} User-scope owner partition key.
+   */
+  async userScopeOwner() {
+    return String(await this.config.authenticationToken())
+  }
+
   /**
    * Unsubscribes the realtime channels and disconnects the websocket client (idempotent).
    * @returns {Promise<void>}

package/src/sync/sync-realtime-bridge.js

@@ -30,6 +30,8 @@ export default class SyncRealtimeBridge {
     this._channels = []
     /** @type {VelociousSyncRealtimeWebsocketClient | null} */
     this._client = null
+    /** @type {boolean} Whether the bridge created its own client (deprecated per-cycle path) and must disconnect it on unsubscribe. A shared connection is never owned. */
+    this._ownsClient = false
     /** @type {Promise<void>} */
     this._applyPromise = Promise.resolve()
     /** @type {number} Subscription generation - bumped by unsubscribe so in-flight subscribes detect they became stale. */
@@ -80,8 +82,13 @@ export default class SyncRealtimeBridge {
     const channels = []
     /** @type {VelociousSyncRealtimeWebsocketClient | null} */
     let client = null
+    /** @type {boolean} Whether this attempt created its own client and must disconnect it on teardown. */
+    let ownsClient = false
     /**
-     * Tears down everything this stale/failed subscribe attempt created itself.
+     * Tears down everything this stale/failed subscribe attempt created itself:
+     * always closes its channel subscriptions, and disconnects the websocket
+     * only when the bridge owns it (deprecated per-cycle path); a shared
+     * connection stays open.
      * @returns {Promise<void>}
      */
     const teardown = async () => {
@@ -89,18 +96,28 @@ export default class SyncRealtimeBridge {
         subscription.close()
       }
 
-      if (client) await client.disconnectAndStopReconnect()
+      if (client && ownsClient) await client.disconnectAndStopReconnect()
     }
 
     try {
-      const realtime = this.realtimeConfiguration()
+      const sharedClient = this.syncClient.syncConnection()
+      const realtime = this.requireClientSource(sharedClient)
       const channelDescriptors = await this.channelDescriptors(context)
 
       if (generation !== this._generation) return
 
-      client = await realtime.createClient()
+      if (sharedClient) {
+        client = sharedClient
+      } else {
+        // requireClientSource guaranteed realtime.createClient when there is no shared connection.
+        client = await /** @type {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} */ (realtime).createClient()
+        ownsClient = true
+      }
 
-      if (generation !== this._generation) return
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
 
       await client.connect()
 
@@ -140,6 +157,7 @@ export default class SyncRealtimeBridge {
 
       this._channels = channels
       this._client = client
+      this._ownsClient = ownsClient
       this._state = "subscribed"
       this.schedulePull()
     } catch (error) {
@@ -152,9 +170,12 @@ export default class SyncRealtimeBridge {
   }
 
   /**
-   * Closes every channel subscription and disconnects the websocket client
-   * (idempotent). Also marks any in-flight subscribe attempt stale so it tears
-   * itself down instead of finishing the subscription afterwards.
+   * Closes every channel subscription (idempotent). The websocket is
+   * disconnected only when the bridge owns it (deprecated per-cycle
+   * `realtime.createClient` path); a shared app-lifetime connection stays open
+   * so unsubscribing drops subscriptions without tearing down the socket. Also
+   * marks any in-flight subscribe attempt stale so it tears itself down instead
+   * of finishing the subscription afterwards.
    * @returns {Promise<void>}
    */
   async unsubscribe() {
@@ -162,16 +183,18 @@ export default class SyncRealtimeBridge {
 
     const channels = this._channels
     const client = this._client
+    const ownsClient = this._ownsClient
 
     this._channels = []
     this._client = null
+    this._ownsClient = false
     this._state = "unsubscribed"
 
     for (const {subscription} of channels) {
       subscription.close()
     }
 
-    if (client) await client.disconnectAndStopReconnect()
+    if (client && ownsClient) await client.disconnectAndStopReconnect()
   }
 
   /**
@@ -195,14 +218,26 @@ export default class SyncRealtimeBridge {
   }
 
   /**
-   * Resolves the realtime configuration, failing loudly when it is missing.
-   * @returns {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} Realtime configuration.
+   * Resolves the realtime configuration block, or null when the app declared
+   * none (valid when a shared connection is configured).
+   * @returns {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration | null} Realtime configuration, or null.
    */
   realtimeConfiguration() {
-    const realtime = this.syncClient.config.realtime
+    return this.syncClient.config.realtime || null
+  }
+
+  /**
+   * Resolves the realtime configuration and asserts a websocket client source
+   * exists: a shared connection rides its own lifecycle, otherwise the
+   * deprecated per-cycle `realtime.createClient` must be configured.
+   * @param {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient | null} sharedClient - Shared connection, or null.
+   * @returns {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration | null} Realtime configuration, or null.
+   */
+  requireClientSource(sharedClient) {
+    const realtime = this.realtimeConfiguration()
 
-    if (!realtime) {
-      throw new Error("subscribeRealtime requires a sync.client.realtime configuration block with a createClient callback")
+    if (!sharedClient && typeof realtime?.createClient !== "function") {
+      throw new Error("subscribeRealtime requires a shared connection (sync.client.websocketUrl or sync.client.websocketClient) or the deprecated sync.client.realtime.createClient callback")
     }
 
     return realtime
@@ -235,7 +270,7 @@ export default class SyncRealtimeBridge {
       channelDescriptors.push({channel: resourceConfig.realtime.channel, params: resourceConfig.realtime.params, resourceType})
     }
 
-    if (realtime.channels) {
+    if (realtime?.channels) {
       channelDescriptors.push(...await realtime.channels(context))
     }
 
@@ -306,7 +341,7 @@ export default class SyncRealtimeBridge {
 
     const realtime = this.realtimeConfiguration()
 
-    if (realtime.localOrigin && body.echoOrigin !== undefined && body.echoOrigin !== null) {
+    if (realtime?.localOrigin && body.echoOrigin !== undefined && body.echoOrigin !== null) {
       const localOrigin = String(await realtime.localOrigin())
 
       if (String(body.echoOrigin) === localOrigin) return
@@ -329,7 +364,7 @@ export default class SyncRealtimeBridge {
    * @returns {void}
    */
   schedulePull() {
-    if (this.realtimeConfiguration().pullOnReconnect === false) return
+    if (this.realtimeConfiguration()?.pullOnReconnect === false) return
 
     this._scheduledPull ||= (async () => {
       try {

package/src/sync/sync-resource-base.js

@@ -215,6 +215,27 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
     throw new Error("SyncResourceBase#scopeChangesQuery must be implemented")
   }
 
+  /**
+   * Decides whether one published change is deliverable to a user-scope
+   * subscription (the framework sync channel's per-delivery access re-check).
+   * The default reuses the app's ability scoping: it applies
+   * {@link SyncResourceBase#scopeChangesQuery} to the change-feed model — which
+   * for an empty-conditions user scope falls back to ability scoping — and
+   * checks whether the published change's feed row is visible within that
+   * scope. Apps get this for free from the scoping they already declared;
+   * override only for custom per-delivery rules.
+   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null, sync: {resourceId: string, resourceType: string}}} args - Request params, subscription scope, and the published change's identity.
+   * @returns {Promise<boolean>} Whether the change may be delivered to this subscription.
+   */
+  async changeDeliverable({params, scope, sync}) {
+    const query = this.syncModelClass().where({})
+
+    this.scopeChangesQuery({params, query, scope})
+    query.where({resource_id: String(sync.resourceId), resource_type: String(sync.resourceType)})
+
+    return Boolean(await query.first())
+  }
+
   /**
    * Resolves the replay service class handling replay mutations: the
    * declarative {@link SyncResourceBase.ReplayServiceClass} static (shared

package/src/sync/sync-websocket-channel.js

@@ -136,11 +136,90 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
     return true
   }
 
+  /**
+   * Delivers a matched broadcast. Scoped subscriptions (with explicit
+   * conditions) already routed through {@link SyncWebsocketChannel#matches}, so
+   * the change is in scope and delivers unchanged. User-scope subscriptions
+   * (empty conditions, "everything my ability can see") match every broadcast
+   * of the resource type, so each published change is re-checked against the
+   * subscriber's ability at fan-out through the app sync resource's
+   * `changeDeliverable`; only accessible changes are delivered, and a broadcast
+   * with no accessible change is dropped.
+   * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} body - Broadcast body (sync envelope).
+   * @param {{eventId?: string}} [meta] - Optional event metadata.
+   * @returns {Promise<void>}
+   */
+  async deliverBroadcast(body, meta) {
+    if (!this._isUserScope()) {
+      this.sendMessage(body, meta)
+
+      return
+    }
+
+    const deliverableBody = await this._userScopeDeliverableBody(body)
+
+    if (deliverableBody !== null) this.sendMessage(deliverableBody, meta)
+  }
+
+  /**
+   * Whether this subscription is a user scope: authorized with empty conditions
+   * ("everything my ability can see").
+   * @returns {boolean} Whether the subscription is a user scope.
+   */
+  _isUserScope() {
+    return Boolean(this._scope) && Object.keys(/** @type {import("./sync-resource-base.js").SerializedChangesScope} */ (this._scope).conditions).length === 0
+  }
+
+  /**
+   * Filters a user-scope broadcast to the sync entries the subscriber's ability
+   * can access, re-checking each through the app sync resource's
+   * `changeDeliverable`. Returns the broadcast narrowed to accessible entries,
+   * or null when none are accessible. Non-envelope bodies and entries without a
+   * resource id are dropped (fail closed).
+   * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} body - Broadcast body.
+   * @returns {Promise<import("../http-server/websocket-channel.js").WebsocketJsonValue | null>} Deliverable body, or null.
+   */
+  async _userScopeDeliverableBody(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) return null
+
+    const envelope = /** @type {Record<string, ?>} */ (body)
+    const scope = /** @type {import("./sync-resource-base.js").SerializedChangesScope} */ (this._scope)
+    const syncs = Array.isArray(envelope.syncs) ? envelope.syncs : [envelope]
+    const configuration = this.session.configuration
+    /** @type {Array<Record<string, ?>>} */
+    const deliverableSyncs = []
+
+    // Broadcast fan-out runs through `withoutCurrentConnectionContexts` (see
+    // Configuration#_broadcastToChannelLocal), so there is no ambient database
+    // connection here. Resolve the resource's ability and run the per-delivery
+    // access query inside a checked-out connection context, mirroring how other
+    // broadcast-time DB work (the frontend-model channel) obtains connections.
+    await configuration.ensureConnections({name: `${VELOCIOUS_SYNC_CHANNEL} user-scope delivery access check`}, async () => {
+      const resource = await this.buildSyncResource()
+
+      for (const sync of syncs) {
+        const resourceId = sync?.resourceId
+        const resourceType = sync?.resourceType ?? scope.resourceType
+
+        if (resourceId === undefined || resourceId === null) continue
+
+        if (await resource.changeDeliverable({params: this.params, scope, sync: {resourceId: String(resourceId), resourceType: String(resourceType)}})) {
+          deliverableSyncs.push(sync)
+        }
+      }
+    })
+
+    if (deliverableSyncs.length === 0) return null
+    if (Array.isArray(envelope.syncs)) return {...envelope, syncs: deliverableSyncs}
+
+    return deliverableSyncs[0]
+  }
+
   /**
    * Returns the authorized scope for debug snapshots.
    * @returns {Record<string, ?>} Debug-safe subscription details.
    */
   debugSnapshot() {
-    return {scope: this._scope}
+    return {scope: this._scope, userScope: this._isUserScope()}
   }
 }