velocious 1.0.503 → 1.0.504

package/src/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/src/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/src/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
+}

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

@@ -0,0 +1,146 @@
+// @ts-check
+
+import VelociousWebsocketChannel from "../http-server/websocket-channel.js"
+import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
+
+/** Configurations whose framework sync channel has already been registered. */
+const registeredConfigurations = new WeakSet()
+
+/**
+ * Framework-owned websocket channel for synced resources
+ * ({@link VELOCIOUS_SYNC_CHANNEL}).
+ *
+ * Subscribe params mirror a declared pull scope — `{resourceType, conditions}`
+ * plus the client-injected `authenticationToken` — and subscribe-time
+ * authorization delegates to the app sync resource's existing
+ * `authorizeChanges({params, scope})` (the `sync.api.resourceClass`), so apps
+ * hook in through the authorization they already declared instead of writing
+ * their own channel classes. Broadcast routing matches the publisher's
+ * scoping params against the subscription's scope conditions.
+ */
+export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
+  /**
+   * Scope the subscription was authorized for, set by {@link SyncWebsocketChannel#canSubscribe}.
+   * @type {import("./sync-resource-base.js").SerializedChangesScope | null}
+   */
+  _scope = null
+
+  /**
+   * Registers the framework sync channel on a configuration declaring a
+   * `sync.api` block (guarded so repeated server boots with the same
+   * configuration register it only once). No-op without `sync.api` — the
+   * channel authorizes through the app's sync resource class.
+   * @param {import("../configuration.js").default} configuration - Configuration instance.
+   * @returns {void}
+   */
+  static registerFromConfiguration(configuration) {
+    if (!configuration.getSyncConfiguration().api || registeredConfigurations.has(configuration)) return
+
+    registeredConfigurations.add(configuration)
+    configuration.registerWebsocketChannel(VELOCIOUS_SYNC_CHANNEL, this)
+  }
+
+  /**
+   * Authorizes the subscription through the app sync resource: the subscribe
+   * params are parsed into the same serialized scope the changes endpoint
+   * consumes and passed to the resource's `authorizeChanges({params, scope})`.
+   * Denials and malformed scopes throw, rejecting the subscription.
+   * @returns {Promise<boolean>} Whether the subscription is allowed.
+   */
+  async canSubscribe() {
+    const resource = await this.buildSyncResource()
+    const scope = resource.changesScope({scope: {conditions: this.params.conditions, resourceType: this.params.resourceType}})
+
+    await resource.authorizeChanges({params: this.params, scope})
+
+    this._scope = scope
+
+    return true
+  }
+
+  /**
+   * Builds the app sync resource authorizing this subscription, mirroring the
+   * sync transport controller's resource construction with the ability
+   * resolved from the subscribe params (which carry the client-injected
+   * authenticationToken).
+   * @returns {Promise<import("./sync-resource-base.js").default>} App sync resource instance.
+   */
+  async buildSyncResource() {
+    const configuration = this.session.configuration
+    const api = configuration.getSyncConfiguration().api
+
+    if (!api) {
+      throw new Error(`The ${VELOCIOUS_SYNC_CHANNEL} channel requires a sync.api configuration block with the app's sync resource class`)
+    }
+
+    // Narrows the configured resource class to the sync resource contract
+    // (changesScope/authorizeChanges) the sync.api validation requires.
+    const ResourceClass = /** @type {typeof import("./sync-resource-base.js").default} */ (api.resourceClass)
+    // Narrows the websocket subscribe params to the resource params contract.
+    const params = /** @type {import("../configuration-types.js").VelociousParams} */ (/** @type {unknown} */ (this.params))
+    const request = this.session.upgradeRequest
+    const ability = await configuration.resolveAbility({params, request})
+
+    return new ResourceClass({
+      ability,
+      context: {
+        ...(ability?.getContext() || {}),
+        params,
+        request
+      },
+      locals: ability?.getLocals() || {},
+      modelClass: ResourceClass.ModelClass,
+      modelName: ResourceClass.ModelClass?.name,
+      params,
+      resourceConfiguration: /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */ ({
+        attributes: ResourceClass.attributes || {},
+        sync: {enabled: true}
+      })
+    })
+  }
+
+  /**
+   * Routes a publisher broadcast to this subscription when the published
+   * resource type equals the type the subscription was authorized for and the
+   * scoping params satisfy every scope condition: each condition key must be
+   * present in the broadcast params and match by string comparison (array
+   * conditions match by membership). Broadcasts without a resource type and
+   * conditions the publisher's scoping params do not carry never match, so a
+   * subscription cannot receive changes outside its authorized scope.
+   * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} broadcastParams - Publisher scoping params (the published resourceType plus the change's scope-partition values).
+   * @returns {boolean} Whether the broadcast belongs to this subscription's scope.
+   */
+  matches(broadcastParams) {
+    const scope = this._scope
+
+    if (!scope) return false
+
+    const scopingParams = broadcastParams && typeof broadcastParams === "object" && !Array.isArray(broadcastParams)
+      ? /** @type {Record<string, ?>} */ (broadcastParams)
+      : {}
+
+    if (!Object.hasOwn(scopingParams, "resourceType") || String(scopingParams.resourceType) !== String(scope.resourceType)) return false
+
+    for (const [conditionName, conditionValue] of Object.entries(scope.conditions)) {
+      if (!Object.hasOwn(scopingParams, conditionName)) return false
+
+      const scopingValue = scopingParams[conditionName]
+
+      if (Array.isArray(conditionValue)) {
+        if (!conditionValue.some((value) => String(value) === String(scopingValue))) return false
+      } else if (String(conditionValue) !== String(scopingValue)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Returns the authorized scope for debug snapshots.
+   * @returns {Record<string, ?>} Debug-safe subscription details.
+   */
+  debugSnapshot() {
+    return {scope: this._scope}
+  }
+}