velocious 1.0.503 → 1.0.504

package/build/sync/sync-publisher-types.js

@@ -1,8 +1,8 @@
 // @ts-check
 
 /**
- * Args resolved against a publish declaration's broadcasts after a published
- * server-side mutation commits.
+ * Args resolved against a publish declaration's deprecated broadcasts after a
+ * published server-side mutation commits.
  * @typedef {object} SyncPublishBroadcastArgs
  * @property {Record<string, ?>} data - Payload snapshotted through the declaration's `serialize(record)` at mutation time.
  * @property {"create" | "update" | "destroy"} operation - Mutation operation that published.
@@ -16,6 +16,7 @@
 /**
  * One declarative broadcast fanned out after a published server-side mutation
  * commits — same shape the replay service's injected broadcaster consumes.
+ * @deprecated Publishing broadcasts the standard sync envelope on the framework sync channel automatically; declare app-channel broadcasts only for legacy channels old app versions still subscribe.
  * @typedef {object} SyncPublishBroadcast
  * @property {string | ((args: SyncPublishBroadcastArgs) => string)} channel - Channel name or resolver.
  * @property {(args: SyncPublishBroadcastArgs) => Record<string, ?>} broadcastParams - Channel routing params.
@@ -27,38 +28,57 @@
  * Server-side publish declaration on a model's `static sync`, consumed by
  * `SyncPublisher.fromConfiguration(...)`. Publishing is on for models
  * declaring it (server-side creates and updates write to the sync change
- * feed and broadcast automatically once their transaction commits);
- * `publish: false` opts a model out explicitly.
+ * feed and broadcast the standard sync envelope on the framework sync
+ * channel automatically once their transaction commits); `publish: true`
+ * opts in with all defaults and `publish: false` opts a model out explicitly.
+ * @template [TModel=any]
  * @typedef {object} SyncPublishDeclarationConfig
- * @property {(record: ?) => Record<string, ?> | Promise<Record<string, ?>>} serialize - Builds the published payload snapshot from the mutated record (snapshotted at mutation time).
- * @property {(record: ?) => string | number | null | Promise<string | number | null>} [eventId] - Resolves the event scope persisted to the sync row's event_id column.
- * @property {SyncPublishBroadcast[]} [broadcasts] - Declarative broadcasts fanned out after the sync row is upserted.
+ * @property {(record: TModel) => Record<string, ?> | Promise<Record<string, ?>>} [serialize] - Builds the published payload snapshot from the mutated record (snapshotted at mutation time). Defaults to the record's attributes with Date values serialized to ISO strings.
+ * @property {Record<string, string>} [scopeAttributes] - Record-attribute name overrides per scope attribute declared on the sync model's `static syncScopeAttributes`. By default each declared scope attribute reads the record's attribute of the same name when the model has one, else the record's own id (scope-root models).
+ * @property {string | ((record: TModel) => string | number | null | Promise<string | number | null>)} [eventId] - Deprecated 1.0.503 form: attribute-name string (or resolver function) persisted to a fixed event_id sync-row column and broadcast as a fixed `eventId` scoping param. Declare `static syncScopeAttributes` on the sync model plus `scopeAttributes` overrides instead.
+ * @property {SyncPublishBroadcast[]} [broadcasts] - Deprecated: declarative app-channel broadcasts fanned out after the framework sync channel broadcast. The framework broadcast happens automatically; keep this only for legacy channels old app versions still subscribe.
  * @property {Array<"create" | "update" | "destroy">} [operations] - Published operations. Defaults to creates and updates; destroys are opt-in because a server destroy is often cleanup rather than a synced delete.
  * @property {string} [resourceType] - Published resource type. Defaults to the model name.
  */
 
-/** @typedef {false | SyncPublishDeclarationConfig} SyncPublishDeclaration */
+/**
+ * Model-level publish declaration value: `true` publishes with all defaults,
+ * `false` opts out explicitly, an object customizes the published payload and scoping.
+ * @template [TModel=any]
+ * @typedef {boolean | SyncPublishDeclarationConfig<TModel>} SyncPublishDeclaration
+ */
 
 /**
  * Options for building a sync publisher. Published resources are derived from
  * the configuration's registered models (`static sync` publish declarations).
  * @typedef {object} SyncPublisherOptions
  * @property {string} [actorForeignKeyColumn] - Sync model column linking rows to a device actor. Published server-origin rows set it to null (no device to echo). Defaults to "authentication_token_id".
- * @property {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [broadcaster] - Delivers declared broadcasts. Defaults to the configuration's channel broadcast.
+ * @property {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [broadcaster] - Delivers the framework sync channel broadcast and any deprecated declared broadcasts. Defaults to the configuration's channel broadcast.
  * @property {import("../configuration.js").default} [configuration] - Configuration owning the registered models. Defaults to the current configuration.
  * @property {(error: Error) => void} [onError] - Reports post-commit publish failures. Defaults to loud logging.
  * @property {?} [syncModel] - Sync/change model override. Defaults to the registered "Sync" model.
  */
 
+/**
+ * One derived scope-partition source for a published resource — not an
+ * app-facing API. The value is persisted to the sync row's `columnName` and
+ * broadcast under `scopeAttribute` on the framework sync channel.
+ * @typedef {object} SyncPublisherScopePlanEntry
+ * @property {string} columnName - Sync-row column persisting the scope value.
+ * @property {string | null} recordAttribute - Record attribute read for the scope value, or null when the record's own id is the scope (scope-root models).
+ * @property {((record: ?) => string | number | null | Promise<string | number | null>) | undefined} resolver - Deprecated eventId resolver function.
+ * @property {string} scopeAttribute - Scope attribute name broadcast as the framework channel scoping param.
+ */
+
 /**
  * Internal derived publish policy for one resource — not an app-facing API.
  * @typedef {object} SyncPublisherResourceConfig
- * @property {SyncPublishBroadcast[] | undefined} broadcasts - Declared broadcasts.
- * @property {SyncPublishDeclarationConfig["eventId"] | undefined} eventId - Event scope resolver.
+ * @property {SyncPublishBroadcast[] | undefined} broadcasts - Deprecated declared app-channel broadcasts.
  * @property {?} modelClass - Server model class for this resource.
  * @property {Array<"create" | "update" | "destroy">} operations - Published operations.
+ * @property {Array<SyncPublisherScopePlanEntry>} scopePlan - Derived scope-partition plan.
+ * @property {(record: ?) => Record<string, ?> | Promise<Record<string, ?>>} serialize - Payload snapshot builder (the declaration's serialize or the default attribute serializer).
  * @property {string} resourceType - Published resource type.
- * @property {SyncPublishDeclarationConfig["serialize"]} serialize - Payload snapshot builder.
  */
 
 export {}

package/build/sync/sync-publisher.js

@@ -4,8 +4,10 @@ import Configuration from "../configuration.js"
 import Logger from "../logger.js"
 import restArgsError from "../utils/rest-args-error.js"
 
+import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
 import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
 import {isPublishingSuppressed} from "./sync-publish-suppression.js"
+import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
 
 /** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
 const PUBLISHED_CALLBACK_NAMES = {create: "afterCreate", destroy: "afterDestroy", update: "afterUpdate"}
@@ -29,16 +31,23 @@ const startedPublishersByConfiguration = new WeakMap()
  * Server models declare what to publish through `static sync`'s `publish`
  * key, and Velocious writes every committed server-side change to the sync
  * change feed (model-backed Sync-row upsert with server re-sequencing) and
- * fans out the declared broadcasts, so devices receive server-origin changes
- * without app code calling manual upsert/broadcast helpers:
+ * broadcasts the standard sync envelope (`{echoOrigin, syncs: [...]}`) on the
+ * framework sync channel ({@link VELOCIOUS_SYNC_CHANNEL}) scoped by the
+ * change's derived scope-partition values, so devices receive server-origin
+ * changes without app code declaring channels or calling manual
+ * upsert/broadcast helpers:
  *
- *     static sync = {
- *       publish: {
- *         serialize: (event) => ({id: event.id(), eventPin: event.eventPin()}),
- *         eventId: (event) => event.id(),
- *         broadcasts: [{channel: "ticket-scans", broadcastParams: ..., body: ...}]
- *       }
- *     }
+ *     static sync = {publish: true} // default payload (attributes) + default scope partition
+ *     static sync = {publish: {serialize: (record) => ({id: record.id(), pin: record.pin()})}}
+ *
+ * The scope partition comes from the sync model's `static
+ * syncScopeAttributes` declaration (for example `["eventId"]` or
+ * `["accountId"]` — Velocious has no built-in partition name): each declared
+ * scope attribute reads the record's attribute of the same name when the
+ * model has one, else the record's own id (scope-root models), overridable
+ * per model through `publish: {scopeAttributes: {accountId: "ownerId"}}`.
+ * The pre-framework-channel `broadcasts` list and the `eventId`
+ * string/resolver-function declaration forms keep working but are deprecated.
  *
  * Replayed device mutations never double-publish: the framework's routed
  * replay apply marks its written records through `markServerApply(record)`
@@ -61,20 +70,9 @@ export default class SyncPublisher {
     restArgsError(restOptions)
 
     const modelClasses = configuration.getModelClasses()
-    /** @type {Record<string, import("./sync-publisher-types.js").SyncPublisherResourceConfig>} */
-    const resources = {}
-
-    for (const modelClass of Object.values(modelClasses)) {
-      const publish = publishDeclarationFor(modelClass)
-
-      if (!publish) continue
-
-      const resourceConfig = resourceConfigFromPublishDeclaration({modelClass, publish})
-
-      resources[resourceConfig.resourceType] = resourceConfig
-    }
+    const publishingModelClasses = Object.values(modelClasses).filter((modelClass) => publishDeclarationFor(modelClass))
 
-    if (Object.keys(resources).length === 0) {
+    if (publishingModelClasses.length === 0) {
       throw new Error("SyncPublisher found no registered models declaring static sync publish - declare `static sync = {publish: {serialize}}` on the models whose server-side changes should publish to the sync feed")
     }
 
@@ -84,6 +82,17 @@ export default class SyncPublisher {
       throw new Error("SyncPublisher requires a registered \"Sync\" model for published sync change rows (or pass options.syncModel)")
     }
 
+    const scopeAttributes = declaredSyncScopeAttributes(resolvedSyncModel)
+    /** @type {Record<string, import("./sync-publisher-types.js").SyncPublisherResourceConfig>} */
+    const resources = {}
+
+    for (const modelClass of publishingModelClasses) {
+      const publish = publishDeclarationFor(modelClass)
+      const resourceConfig = resourceConfigFromPublishDeclaration({modelClass, publish, scopeAttributes, syncModel: resolvedSyncModel})
+
+      resources[resourceConfig.resourceType] = resourceConfig
+    }
+
     /** @type {{actorForeignKeyColumn: string, broadcaster: import("./sync-publisher-types.js").SyncPublisherOptions["broadcaster"], configuration: Configuration, onError: import("./sync-publisher-types.js").SyncPublisherOptions["onError"], resources: Record<string, import("./sync-publisher-types.js").SyncPublisherResourceConfig>, syncModel: ?}} */
     this.config = {actorForeignKeyColumn, broadcaster, configuration, onError, resources, syncModel: resolvedSyncModel}
     /** @type {Array<{callback: (record: ?) => Promise<void>, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy", modelClass: ?}>} */
@@ -183,6 +192,7 @@ export default class SyncPublisher {
       const data = await resourceConfig.serialize(record)
       const resourceId = String(record.id())
       const syncType = operation === "destroy" ? "delete" : "update"
+      const scopeValues = await this.publishedScopeValues({record, resourceConfig})
       /** @type {Record<string, ?>} */
       const attributes = {
         [this.config.actorForeignKeyColumn]: null,
@@ -190,19 +200,23 @@ export default class SyncPublisher {
         data: JSON.stringify(data),
         resource_id: resourceId,
         resource_type: resourceConfig.resourceType,
-        sync_type: syncType
-      }
-
-      if (resourceConfig.eventId) {
-        const eventId = await resourceConfig.eventId(record)
-
-        attributes.event_id = eventId === undefined || eventId === null ? null : String(eventId)
+        sync_type: syncType,
+        ...scopeValues.columns
       }
 
       await resourceConfig.modelClass.connection().afterCommit(async () => {
         try {
           const syncRow = await this.upsertPublishedSyncRow(attributes)
 
+          await this.broadcaster()({
+            body: {
+              echoOrigin: null,
+              syncs: [{data, resourceId, resourceType: resourceConfig.resourceType, syncType}]
+            },
+            channel: VELOCIOUS_SYNC_CHANNEL,
+            params: {...scopeValues.params, resourceType: resourceConfig.resourceType}
+          })
+
           if (resourceConfig.broadcasts) {
             await deliverDeclaredBroadcasts({
               args: {data, operation, record, resourceId, resourceType: resourceConfig.resourceType, syncRow, syncType},
@@ -217,6 +231,42 @@ export default class SyncPublisher {
     }
   }
 
+  /**
+   * Resolves the scope-partition values for one published mutation from the
+   * resource's derived scope plan: each entry reads its record attribute (or
+   * the record's own id for scope-root models, or the deprecated resolver
+   * function). The values are persisted onto the sync row's partition columns
+   * and broadcast as the framework sync channel's scoping params.
+   * @param {{record: ?, resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig}} args - Mutated record and resource config.
+   * @returns {Promise<{columns: Record<string, string | null>, params: Record<string, string | null>}>} Scope values keyed by sync-row column and by scope attribute.
+   */
+  async publishedScopeValues({record, resourceConfig}) {
+    /** @type {Record<string, string | null>} */
+    const columns = {}
+    /** @type {Record<string, string | null>} */
+    const params = {}
+
+    for (const scopePlanEntry of resourceConfig.scopePlan) {
+      /** @type {?} */
+      let rawValue
+
+      if (scopePlanEntry.resolver) {
+        rawValue = await scopePlanEntry.resolver(record)
+      } else if (scopePlanEntry.recordAttribute) {
+        rawValue = record.readAttribute(scopePlanEntry.recordAttribute)
+      } else {
+        rawValue = record.id()
+      }
+
+      const value = rawValue === undefined || rawValue === null ? null : String(rawValue)
+
+      columns[scopePlanEntry.columnName] = value
+      params[scopePlanEntry.scopeAttribute] = value
+    }
+
+    return {columns, params}
+  }
+
   /**
    * Upserts the published server-origin sync row for a resource identity:
    * server-origin rows carry a null actor column (no device to echo the
@@ -296,7 +346,7 @@ export default class SyncPublisher {
  * Opted-out (`publish: false`) and undeclared models resolve to null; every
  * other declared value flows into loud declaration validation.
  * @param {?} modelClass - Registered model class.
- * @returns {import("./sync-publisher-types.js").SyncPublishDeclarationConfig | null} Active publish declaration, or null.
+ * @returns {import("./sync-publisher-types.js").SyncPublishDeclaration | null} Active publish declaration, or null.
  */
 function publishDeclarationFor(modelClass) {
   const declaration = modelClass.sync
@@ -308,25 +358,27 @@ function publishDeclarationFor(modelClass) {
 
 /**
  * Builds one published resource config from a model's `static sync` publish
- * declaration.
- * @param {{modelClass: ?, publish: import("./sync-publisher-types.js").SyncPublishDeclarationConfig}} args - Declaration args.
+ * declaration. `publish: true` opts in with all defaults (attribute payload,
+ * derived scope partition, created/updated operations).
+ * @param {{modelClass: ?, publish: import("./sync-publisher-types.js").SyncPublishDeclaration | null, scopeAttributes: string[] | null, syncModel: ?}} args - Declaration args plus the sync model's declared scope attributes.
  * @returns {import("./sync-publisher-types.js").SyncPublisherResourceConfig} Derived resource config.
  */
-function resourceConfigFromPublishDeclaration({modelClass, publish}) {
+function resourceConfigFromPublishDeclaration({modelClass, publish, scopeAttributes: syncScopeAttributes, syncModel}) {
   const modelName = modelClass.getModelName()
+  const normalizedPublish = publish === true ? {} : publish
 
-  if (!publish || typeof publish !== "object" || Array.isArray(publish)) {
-    throw new Error(`${modelName} static sync publish must be false or a publish declaration object, got: ${String(publish)}`)
+  if (!normalizedPublish || typeof normalizedPublish !== "object" || Array.isArray(normalizedPublish)) {
+    throw new Error(`${modelName} static sync publish must be true, false or a publish declaration object, got: ${String(publish)}`)
   }
 
-  const {broadcasts, eventId, operations, resourceType, serialize, ...restDeclaration} = publish
+  const {broadcasts, eventId, operations, resourceType, scopeAttributes, serialize, ...restDeclaration} = normalizedPublish
   const unknownKeys = Object.keys(restDeclaration)
 
   if (unknownKeys.length > 0) {
-    throw new Error(`${modelName} static sync publish received unknown keys: ${unknownKeys.join(", ")} (supported: broadcasts, eventId, operations, resourceType, serialize)`)
+    throw new Error(`${modelName} static sync publish received unknown keys: ${unknownKeys.join(", ")} (supported: broadcasts, eventId (deprecated), operations, resourceType, scopeAttributes, serialize)`)
   }
-  if (typeof serialize !== "function") {
-    throw new Error(`${modelName} static sync publish requires a serialize(record) function building the published payload`)
+  if (serialize !== undefined && typeof serialize !== "function") {
+    throw new Error(`${modelName} static sync publish serialize must be a function building the published payload, got: ${String(serialize)}`)
   }
   if (operations !== undefined) {
     if (!Array.isArray(operations) || operations.length === 0) {
@@ -342,10 +394,109 @@ function resourceConfigFromPublishDeclaration({modelClass, publish}) {
 
   return {
     broadcasts,
-    eventId,
     modelClass,
     operations: operations === undefined ? DEFAULT_PUBLISHED_OPERATIONS : operations,
     resourceType: resourceType === undefined ? modelName : resourceType,
-    serialize
+    scopePlan: scopePlanFor({eventId, modelClass, modelName, scopeAttributes, syncModel, syncScopeAttributes}),
+    serialize: serialize === undefined ? defaultSerializedAttributes : serialize
   }
 }
+
+/**
+ * Derives the scope plan partitioning a published model's changes: one entry
+ * per scope attribute declared on the sync model (`static
+ * syncScopeAttributes`), each reading the record attribute named like the
+ * scope attribute (overridable through the declaration's `scopeAttributes`
+ * name map), or the record's own id when the model has no such attribute
+ * (scope-root models). The deprecated `eventId` declaration forms map to a
+ * fixed `eventId`/`event_id` plan for 1.0.503 compatibility.
+ * @param {{eventId: import("./sync-publisher-types.js").SyncPublishDeclarationConfig["eventId"], modelClass: ?, modelName: string, scopeAttributes: Record<string, string> | undefined, syncModel: ?, syncScopeAttributes: string[] | null}} args - Declaration and sync-model scope args.
+ * @returns {Array<import("./sync-publisher-types.js").SyncPublisherScopePlanEntry>} Derived scope plan.
+ */
+function scopePlanFor({eventId, modelClass, modelName, scopeAttributes, syncModel, syncScopeAttributes}) {
+  const attributeNames = Object.values(modelClass.getColumnNameToAttributeNameMap())
+
+  if (eventId !== undefined) {
+    if (scopeAttributes !== undefined) {
+      throw new Error(`${modelName} static sync publish can't declare both scopeAttributes and the deprecated eventId form`)
+    }
+    if (typeof eventId === "function") {
+      return [{columnName: "event_id", recordAttribute: null, resolver: eventId, scopeAttribute: "eventId"}]
+    }
+    if (typeof eventId !== "string") {
+      throw new Error(`${modelName} static sync publish eventId must be an attribute-name string (or a deprecated resolver function), got: ${String(eventId)}`)
+    }
+    if (!attributeNames.includes(eventId)) {
+      throw new Error(`${modelName} static sync publish eventId attribute doesn't exist on the model: ${eventId}`)
+    }
+
+    return [{columnName: "event_id", recordAttribute: eventId, resolver: undefined, scopeAttribute: "eventId"}]
+  }
+
+  if (scopeAttributes !== undefined && !syncScopeAttributes) {
+    throw new Error(`${modelName} static sync publish declares scopeAttributes but the sync model declares no static syncScopeAttributes`)
+  }
+
+  if (!syncScopeAttributes) return []
+
+  if (scopeAttributes !== undefined && (typeof scopeAttributes !== "object" || Array.isArray(scopeAttributes))) {
+    throw new Error(`${modelName} static sync publish scopeAttributes must be an object mapping scope attributes to record attribute names, got: ${String(scopeAttributes)}`)
+  }
+
+  for (const scopeAttribute of Object.keys(scopeAttributes || {})) {
+    if (!syncScopeAttributes.includes(scopeAttribute)) {
+      throw new Error(`${modelName} static sync publish scopeAttributes received unknown scope attribute: ${scopeAttribute} (the sync model declares: ${syncScopeAttributes.join(", ")})`)
+    }
+  }
+
+  return syncScopeAttributes.map((scopeAttribute) => {
+    const declaredRecordAttribute = scopeAttributes?.[scopeAttribute]
+
+    if (declaredRecordAttribute !== undefined) {
+      if (typeof declaredRecordAttribute !== "string" || !attributeNames.includes(declaredRecordAttribute)) {
+        throw new Error(`${modelName} static sync publish scopeAttributes.${scopeAttribute} must name an existing record attribute, got: ${String(declaredRecordAttribute)}`)
+      }
+
+      return {columnName: syncScopeColumnName({scopeAttribute, syncModel}), recordAttribute: declaredRecordAttribute, resolver: undefined, scopeAttribute}
+    }
+
+    return {
+      columnName: syncScopeColumnName({scopeAttribute, syncModel}),
+      recordAttribute: attributeNames.includes(scopeAttribute) ? scopeAttribute : null,
+      resolver: undefined,
+      scopeAttribute
+    }
+  })
+}
+
+/**
+ * Resolves the sync-row column persisting a declared scope attribute.
+ * @param {{scopeAttribute: string, syncModel: ?}} args - Scope attribute and sync model.
+ * @returns {string} Sync-row column name.
+ */
+function syncScopeColumnName({scopeAttribute, syncModel}) {
+  const columnName = syncModel.getAttributeNameToColumnNameMap()[scopeAttribute]
+
+  if (!columnName) {
+    throw new Error(`${syncModel.name} declares the sync scope attribute ${scopeAttribute} but has no matching column for it`)
+  }
+
+  return columnName
+}
+
+/**
+ * Default publish serializer: the record's attributes with Date values
+ * serialized to ISO strings.
+ * @param {?} record - Mutated server model record.
+ * @returns {Record<string, ?>} Serialized attributes payload.
+ */
+function defaultSerializedAttributes(record) {
+  /** @type {Record<string, ?>} */
+  const attributes = {...record.attributes()}
+
+  for (const [attributeName, value] of Object.entries(attributes)) {
+    if (value instanceof Date) attributes[attributeName] = value.toISOString()
+  }
+
+  return attributes
+}

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

@@ -1,17 +1,22 @@
 // @ts-check
 
 import SyncApiClient from "./sync-api-client.js"
+import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
 
 /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeChannelDescriptor} VelociousSyncRealtimeChannelDescriptor */
 /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} VelociousSyncRealtimeWebsocketClient */
 
 /**
- * Derived realtime push bridge for the sync client. Subscribes the declared
- * websocket channels (config `sync.client.realtime.channels` callback plus
- * model-level `static sync = {realtime: {channel}}` declarations), applies
- * pushed changes through the same derived resource applier as pulls (with echo
- * suppression against tracked re-queueing), drops own-device messages by echo
- * origin, and fires a coalesced `pull()` when subscriptions become ready or
+ * Derived realtime push bridge for the sync client. Subscribes every declared
+ * pull scope to the framework sync channel ({@link VELOCIOUS_SYNC_CHANNEL})
+ * automatically — the subscribe params mirror the scope's
+ * `{resourceType, conditions}` so the server authorizes them through the same
+ * sync resource authorization as pulls — plus any deprecated legacy channels
+ * (config `sync.client.realtime.channels` callback and model-level
+ * `static sync = {realtime: {channel}}` declarations). Pushed changes apply
+ * through the same derived resource applier as pulls (with echo suppression
+ * against tracked re-queueing), own-device messages are dropped by echo
+ * origin, and a coalesced `pull()` fires when subscriptions become ready or
  * resume so offline gaps close.
  */
 export default class SyncRealtimeBridge {
@@ -41,7 +46,7 @@ export default class SyncRealtimeBridge {
    * Subscribes the derived realtime channels (idempotent and single-flighted):
    * an active subscription is kept as-is and a concurrent subscribe awaits the
    * in-flight attempt. Call `unsubscribe()` first to change the context.
-   * @param {?} [context] - App context passed to the `sync.client.realtime.channels` callback (runtime values like eventId).
+   * @param {?} [context] - App context passed to the deprecated `sync.client.realtime.channels` callback (runtime scope values).
    * @returns {Promise<void>}
    */
   async subscribe(context) {
@@ -204,9 +209,12 @@ export default class SyncRealtimeBridge {
   }
 
   /**
-   * Derives the channel descriptors to subscribe: model-level static realtime
-   * declarations plus the config channels callback, failing loudly when none exist.
-   * @param {?} context - App context passed to the channels callback.
+   * Derives the channel descriptors to subscribe: one framework sync channel
+   * subscription per declared pull scope (the params mirror the scope's
+   * `{resourceType, conditions}`), plus the deprecated legacy paths —
+   * model-level static realtime declarations and the config channels callback.
+   * Fails loudly when nothing is subscribable.
+   * @param {?} context - App context passed to the deprecated channels callback.
    * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
    */
   async channelDescriptors(context) {
@@ -214,6 +222,13 @@ export default class SyncRealtimeBridge {
     /** @type {Array<VelociousSyncRealtimeChannelDescriptor>} */
     const channelDescriptors = []
 
+    for (const scopeRow of await this.syncClient.scopeStore().activeScopes()) {
+      channelDescriptors.push({
+        channel: VELOCIOUS_SYNC_CHANNEL,
+        params: {conditions: this.attributeNamedConditions(scopeRow), resourceType: scopeRow.resourceType}
+      })
+    }
+
     for (const [resourceType, resourceConfig] of Object.entries(this.syncClient.config.resources)) {
       if (!resourceConfig.realtime) continue
 
@@ -225,12 +240,42 @@ export default class SyncRealtimeBridge {
     }
 
     if (channelDescriptors.length === 0) {
-      throw new Error("subscribeRealtime found no realtime channels - declare sync.client.realtime.channels or static sync = {realtime: {channel}} on a model")
+      throw new Error("subscribeRealtime found no channels to subscribe - declare a sync scope (syncClient().sync(query)) so its framework sync channel subscription can be derived, or the deprecated sync.client.realtime.channels callback")
     }
 
     return channelDescriptors
   }
 
+  /**
+   * Translates a persisted scope's condition keys to the model's attribute
+   * names so the framework channel subscription matches the publisher's
+   * attribute-named scoping params: `serializedScopeFromQuery` persists the
+   * query's model-normalized column names (for example `project_id`), while
+   * scope-partition broadcasts carry attribute names (`projectId`). Keys
+   * without a column mapping are already attribute names and pass through;
+   * scopes on models without a declared sync resource fail loudly because no
+   * attribute mapping exists for them.
+   * @param {{conditions: Record<string, ?>, resourceType: string}} scopeRow - Active scope row.
+   * @returns {Record<string, ?>} Attribute-named scope conditions.
+   */
+  attributeNamedConditions(scopeRow) {
+    const resourceConfig = this.syncClient.config.resources[scopeRow.resourceType]
+
+    if (!resourceConfig) {
+      throw new Error(`subscribeRealtime can't derive attribute names for the sync scope declared on ${scopeRow.resourceType} - declare static sync on that model so its resource is registered`)
+    }
+
+    const columnNameToAttributeName = resourceConfig.modelClass.getColumnNameToAttributeNameMap()
+    /** @type {Record<string, ?>} */
+    const conditions = {}
+
+    for (const [conditionName, conditionValue] of Object.entries(scopeRow.conditions)) {
+      conditions[columnNameToAttributeName[conditionName] || conditionName] = conditionValue
+    }
+
+    return conditions
+  }
+
   /**
    * Chains one pushed message onto the serialized apply queue so changes apply
    * in arrival order; failures go to the sync client's error reporting.

package/build/sync/sync-scope-attributes.js

@@ -0,0 +1,26 @@
+// @ts-check
+
+/**
+ * Reads and validates a sync/change model's declared scope-partition
+ * attributes (`static syncScopeAttributes`).
+ *
+ * The declaration names the attribute(s) partitioning the app's sync feed —
+ * the same attribute names client pull scopes use as conditions (for example
+ * `["eventId"]` or `["accountId"]`). The publisher persists them onto every
+ * published sync row and broadcasts them as the framework sync channel's
+ * scoping params, and the change feed serializes them onto every changes row
+ * under their own names. Velocious itself has no built-in partition name.
+ * @param {?} syncModel - Sync/change model class.
+ * @returns {string[] | null} Declared scope attributes, or null when the model declares none.
+ */
+export function declaredSyncScopeAttributes(syncModel) {
+  const declared = syncModel.syncScopeAttributes
+
+  if (declared === undefined || declared === null) return null
+
+  if (!Array.isArray(declared) || declared.length === 0 || declared.some((attributeName) => typeof attributeName !== "string" || !attributeName)) {
+    throw new Error(`${syncModel.name} static syncScopeAttributes must be a non-empty array of attribute-name strings, got: ${String(declared)}`)
+  }
+
+  return declared
+}