yrby-rails 0.4.0

data/app/models/y/document.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# One row per collaborative document, addressed two ways:
+#
+#   key             what a channel addresses: one opaque, unique string.
+#                   Apps can supply their own ("room-42"), so nothing
+#                   parses meaning out of a key.
+#   record + name   which model attribute the document backs, where name
+#                   is the attribute name ("body") — optional, one
+#                   document per attribute per record, the same scheme as
+#                   ActionText::RichText.
+#
+# When a binding exists and no key was supplied, the key derives as
+# post/1/body. Either side can arrive first — a channel can write under a
+# key before any binding exists — so `.for` adopts a key-only row whose
+# key matches the derived one, converging both on one row.
+#
+# `state` holds the merged snapshot; the update rows are the uncompacted
+# tail, so a load reads the snapshot plus whatever the tail currently
+# holds. The models store CRDT state only: derived data (rendered HTML,
+# search text) is the application's job, typically done in the channel's
+# on_change.
+class Y::Document < ActiveRecord::Base
+  self.table_name = "y_documents"
+
+  belongs_to :record, polymorphic: true, optional: true
+  has_many :updates, class_name: "Y::DocumentUpdate", dependent: :delete_all
+
+  validates :key, presence: true
+  # A bound row carries record + name. Checked on the columns, not the
+  # association: reading `record` constantizes record_type, which must not
+  # be a validity requirement.
+  validates :name, presence: true, if: :record_type
+  validates :record_type, presence: true, if: -> { name || record_id }
+  validates :record_id, presence: true, if: :record_type
+  before_validation :assign_default_key, on: :create
+
+  # How long the tail may grow before an append compacts it into state.
+  # Lower values compact more often; higher values leave more tail rows
+  # for each load to merge.
+  class_attribute :compact_every, instance_writer: false, default: 64
+
+  class << self
+    def locate(key) = find_by(key: key)
+
+    def locate!(key)
+      find_by(key: key) || create_or_find_by!(key: key)
+    end
+
+    # The document bound to a record's attribute, created on first use.
+    # Find first (after the first call, every call is a read), then adopt:
+    # if a channel already appended under the key this binding derives, a
+    # key-only row exists whose key is taken — claiming it converges the two
+    # identities where a plain insert would collide on the key index.
+    #
+    # The insert can still lose a race it can't see: a channel creates the
+    # key-only row after adopt looked and before the insert lands, so
+    # create_or_find_by! collides on the key index — and its internal
+    # retry, which looks up by record + name, misses the key-only row and
+    # raises RecordNotFound. One more pass adopts the row that won.
+    def for(record, name)
+      attempts = 0
+      begin
+        find_by(record: record, name: name.to_s) ||
+          adopt(record, name) ||
+          create_or_find_by!(record: record, name: name.to_s)
+      rescue ActiveRecord::RecordNotFound
+        raise if (attempts += 1) > 1
+
+        retry
+      end
+    end
+
+    # The store contract for a sync channel, keyed by the transport key.
+    # Both skip the state blob (select(:id)): append never reads it, and
+    # load_state re-reads it fresh after the tail (see below), so neither
+    # should drag a potentially large snapshot over the wire per call.
+    def load_state(key) = select(:id).find_by(key: key)&.load_state
+
+    def append(key, update)
+      (select(:id).find_by(key: key) || create_or_find_by!(key: key)).append(update)
+    end
+
+    private
+
+    def adopt(record, name)
+      document = find_by(key: derived_key(record, name), record_type: nil)
+      document&.update!(record: record, name: name.to_s)
+      document
+    rescue ActiveRecord::RecordNotUnique
+      find_by(record: record, name: name.to_s) # a racer adopted or created it first
+    end
+
+    def derived_key(record, name)
+      # polymorphic_name is what Rails writes to record_type, so adoption
+      # and assign_default_key derive the same string under any setting of
+      # store_full_class_name.
+      "#{record.class.polymorphic_name.underscore}/#{record.id}/#{name}"
+    end
+  end
+
+  # Record one delta. The trigger is at-or-over rather than an exact
+  # multiple (concurrent appends can jump past one) and counts only clean
+  # rows: pending rows never satisfy it, so a quarantined gap doesn't
+  # retrigger compaction on every append.
+  def append(bytes)
+    updates.create!(payload: bytes)
+    compact! if updates.where(pending: false).count >= compact_every
+  end
+
+  # The merged document: state plus the whole tail. The tail is read first
+  # and the snapshot re-read after it, both straight from the database: a
+  # compaction committing between the two reads then hands us rows already
+  # folded into the fresh snapshot — an idempotent double-apply — where
+  # the reverse order could pair a pre-compaction snapshot with an empty
+  # tail and omit committed changes. Quarantined rows are applied too —
+  # the output goes through compacted_state_update, which is gap-free by
+  # construction, so an unhealed gap contributes nothing while a gap
+  # healed by a newer tail row is served immediately instead of waiting
+  # for the next compaction.
+  def load_state
+    tail = Y::DocumentUpdate.where(document_id: id).pluck(:payload)
+    snapshot = self.class.where(id: id).pick(:state)
+    return snapshot if tail.empty?
+
+    doc = Y::Doc.new
+    doc.apply_update(snapshot) if snapshot
+    tail.each { |payload| doc.apply_update(payload) }
+    doc.compacted_state_update
+  end
+
+  # Compact the tail into state. The row lock serializes racing
+  # compactions; a delta landing mid-compaction isn't in `rows`, so it
+  # survives the delete and compacts next time.
+  #
+  # A causally-gapped batch is never compacted whole and never deleted:
+  # state would silently exclude the gap, destroying the only healable
+  # copy. If the clean rows alone merge gap-free, they compact and only
+  # the gap is quarantined (marked pending); rows that causally build on
+  # quarantined content quarantine with it.
+  def compact!
+    with_lock do
+      rows = updates.pluck(:id, :payload, :pending)
+      next if rows.empty?
+
+      unless compact_rows(rows)
+        clean = rows.reject { |_, _, pending| pending }
+        remainder = compact_rows(clean) ? rows - clean : rows
+        updates.where(id: remainder.map(&:first)).update_all(pending: true)
+      end
+    end
+  end
+
+  private
+
+  # Compact state + the given rows if the merge is gap-free: writes state,
+  # deletes the rows, returns true. Leaves everything untouched and returns
+  # false on a gap.
+  def compact_rows(rows) # rubocop:disable Naming/PredicateMethod -- compacts AND reports
+    return true if rows.empty?
+
+    doc = Y::Doc.new
+    doc.apply_update(state) if state
+    rows.each { |_, payload, _| doc.apply_update(payload) }
+    return false if doc.pending?
+
+    update!(state: doc.compacted_state_update)
+    updates.where(id: rows.map(&:first)).delete_all
+    true
+  end
+
+  # Derives post/1/body from the polymorphic record_type — Rails stores
+  # the polymorphic_name there, which is base_class-derived, so STI
+  # subclasses share a key. Namespaces keep their slash
+  # (admin/post/1/body); flattening would collide Admin::Post with
+  # AdminPost. record_id is nil for an unsaved record at validation time
+  # (autosave runs after), so it guards too. Key-only documents supply
+  # their own key.
+  def assign_default_key
+    self.key ||= record_type && record_id && "#{record_type.underscore}/#{record_id}/#{name}"
+  end
+end

data/app/models/y/document_update.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# One CRDT delta per row: the document's uncompacted tail, compacted into
+# Y::Document#state and deleted at the compaction threshold. pending marks a
+# causally-gapped row, quarantined until its dependency arrives.
+class Y::DocumentUpdate < ActiveRecord::Base
+  self.table_name = "y_document_updates"
+
+  belongs_to :document, class_name: "Y::Document"
+end

data/lib/generators/yrby/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Creates a DocumentChannel speaking the y-websocket protocol, backed by
+    the gem's document storage (Y::Document + Y::DocumentUpdate), and the
+    migration for its tables.
+
+Example:
+    bin/rails generate yrby:install
+
+    This will create:
+        app/channels/document_channel.rb
+        db/migrate/XXXXXXXX_create_y_tables.rb

data/lib/generators/yrby/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "generators/yrby/tables/tables_generator"
+
+module Yrby
+  module Generators
+    # `bin/rails generate yrby:install` — a DocumentChannel speaking the
+    # y-websocket protocol over the gem's document storage, plus the storage
+    # migration (via yrby:tables). The models ship in the gem; only the
+    # migration lands in the app.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_channel
+        template "document_channel.rb", "app/channels/document_channel.rb"
+      end
+
+      def create_tables
+        invoke "yrby:tables"
+      end
+
+      def show_next_steps
+        say <<~NEXT
+
+          Next steps:
+
+            1. Authorize document access: implement `authorized?` in
+               app/channels/document_channel.rb (it denies everyone until you do).
+            2. bin/rails db:migrate
+            3. Install the yrby-client npm package and connect an editor:
+
+                 import { ActionCableProvider } from "yrby-client"
+                 const provider = new ActionCableProvider(doc, consumer,
+                   "DocumentChannel", { id: documentId })
+                 provider.connect()
+
+          The README's Editors section links working integrations for
+          Tiptap, Lexxy, Rhino Editor, and CodeMirror.
+        NEXT
+      end
+    end
+  end
+end

data/lib/generators/yrby/install/templates/document_channel.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Collaborative documents over Action Cable: one channel speaking the
+# y-websocket protocol (sync plus presence). Storage is Y::Document +
+# Y::DocumentUpdate; a document is created on its first change and its
+# history goes with it when it is destroyed. Point on_load/on_change
+# elsewhere to swap storage.
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable
+
+  # Rebuild a document from durable storage (nil means a brand-new document).
+  on_load { |key| Y::Document.load_state(key) }
+
+  # Record each CRDT delta durably. Runs before the change is acknowledged
+  # or broadcast; if this raises, the change is neither acked nor relayed,
+  # and yrby-client retries it.
+  on_change { |key, update| Y::Document.append(key, update) }
+
+  def subscribed
+    return reject unless authorized?(params[:id])
+
+    sync_subscribed(params[:id])
+  end
+
+  def receive(data) = sync_receive(data, params[:id])
+
+  private
+
+  # Everyone is denied until you fill this in. Wire it to your app's auth:
+  # identify current_user on the cable connection, then check they may read
+  # and write this document. Don't lean on on_change raising for access
+  # control — that path exists for store failures.
+  def authorized?(_document_key)
+    false
+  end
+end

data/lib/generators/yrby/tables/tables_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Yrby
+  module Generators
+    # `bin/rails generate yrby:tables` — the migration for the gem-owned
+    # document models (Y::Document + Y::DocumentUpdate). Invoked by
+    # yrby:install, and by other gems building on the same storage.
+    #
+    # Template notes (kept here, not in the emitted migration): state is
+    # 4.gigabytes - 1 (longblob on MySQL — a compacted snapshot is the whole
+    # document; a 16 MB cap would break compaction) and payload is
+    # 16.megabytes - 1 (one update can carry a big paste or a client's
+    # accumulated offline edits — the 64 KB default blob is too small).
+    # The partial unique index's WHERE only keeps
+    # key-only rows out of the index: uniqueness holds without it, since
+    # unique indexes treat NULLs as distinct on every supported database,
+    # and MySQL drops the predicate harmlessly. y_document_updates indexes
+    # (document_id, pending) instead of bare document_id: the prefix
+    # serves the tail and foreign-key lookups, and the pair serves the
+    # clean-row count every append runs.
+    class TablesGenerator < ::Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "create_y_tables.rb",
+                           File.join(db_migrate_path, "create_y_tables.rb")
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/yrby/tables/templates/create_y_tables.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateYTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :y_documents do |t|
+      t.string :key, null: false, index: { unique: true }
+      t.references :record, polymorphic: true, null: true, index: false
+      t.string :name
+      t.binary :state, limit: 4.gigabytes - 1
+      t.timestamps
+      t.index %i[record_type record_id name], unique: true,
+              where: "record_type IS NOT NULL",
+              name: "index_y_documents_on_record_and_name"
+    end
+
+    create_table :y_document_updates do |t|
+      t.references :document, null: false, foreign_key: { to_table: :y_documents }, index: false
+      t.binary :payload, null: false, limit: 16.megabytes - 1
+      t.boolean :pending, null: false, default: false
+      t.datetime :created_at, null: false
+      t.index %i[document_id pending]
+    end
+  end
+end

data/lib/y/action_cable/sync.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "y"
+require "base64"
+
+module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
+  # y-websocket protocol over ActionCable.
+  #
+  # Include this module in an ActionCable channel to sync Y.js documents
+  # (and awareness/presence) with browser clients. Messages are the standard
+  # y-protocols binary messages, base64-encoded in a JSON envelope:
+  #
+  #   { "update" => "<base64 bytes>", "id" => 42 } # client -> server
+  #   { "update" => "<base64 bytes>" }             # server -> subscribers
+  #   { "ack" => 42 }                              # server -> sender
+  #
+  # Example:
+  #   class DocumentChannel < ApplicationCable::Channel
+  #     include Y::ActionCable::Sync
+  #
+  #     on_load { |key| Document.find_by(key: key)&.content }
+  #     # on_change runs in the channel instance's context, so instance methods
+  #     # (current_user, params, ...) are available:
+  #     on_change { |key, update| Document.record!(key, update, by: current_user) }
+  #
+  #     def subscribed
+  #       sync_subscribed params[:id]
+  #     end
+  #
+  #     def receive(data)
+  #       sync_receive(data)
+  #     end
+  #   end
+  #
+  # There is no unsubscribe hook: the server keeps no per-connection document or
+  # presence state, so a disconnect needs no server-side cleanup.
+  #
+  # The concern is store-backed: every document update is validated against
+  # `on_load`, recorded through `on_change`, and only then broadcast.
+  # No authoritative document state is kept in ActionCable process memory.
+  module Sync
+    # Frame kinds we act on, from Y.message_kind. Its other codes (0 for a
+    # drop: malformed/truncated/multi-message/unknown, and 4 for an awareness
+    # query) fall through to a no-op in the dispatch below.
+    MSG_KIND_SYNC_STEP1 = 1
+    MSG_KIND_UPDATE = 2
+    MSG_KIND_AWARENESS = 3
+
+    # Default incoming-frame size cap (decoded bytes). Generous enough for a
+    # large initial SyncStep2, small enough to bound a single message's
+    # allocation/parse cost. Override per channel with `max_frame_bytes`.
+    DEFAULT_MAX_FRAME_BYTES = 8 * 1024 * 1024
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Load persisted document state. Called once per key with (key); return a
+      # binary Y.js update (or nil for a fresh document). Runs in the channel
+      # instance's context (instance_exec).
+      def on_load(&block)
+        @on_load = block if block
+        return @on_load if defined?(@on_load) && @on_load
+
+        superclass.respond_to?(:on_load) ? superclass.on_load : nil
+      end
+
+      # Record every document change durably before it is applied or
+      # distributed. Called synchronously with (key, update), where update is
+      # the exact CRDT delta. If the block raises, the change is rejected:
+      # neither acknowledged nor broadcast to other subscribers.
+      #
+      # Runs in the channel instance's context (instance_exec). Fires from within
+      # sync_receive.
+      def on_change(&block)
+        @on_change = block if block
+        return @on_change if defined?(@on_change) && @on_change
+
+        superclass.respond_to?(:on_change) ? superclass.on_change : nil
+      end
+
+      # Maximum size, in decoded bytes, of an incoming document/awareness frame.
+      # Oversized frames are dropped before base64 decode and before native
+      # parsing, so a client can't force huge allocations/CPU (a DoS vector).
+      # Defaults to DEFAULT_MAX_FRAME_BYTES; set to nil to disable the cap.
+      def max_frame_bytes(bytes = :__unset__)
+        # Combined reader/writer; the sentinel keeps nil a real value (disables the cap).
+        @max_frame_bytes = bytes unless bytes == :__unset__
+        return @max_frame_bytes if defined?(@max_frame_bytes)
+
+        superclass.respond_to?(:max_frame_bytes) ? superclass.max_frame_bytes : DEFAULT_MAX_FRAME_BYTES
+      end
+    end
+
+    # Call from `subscribed`. Streams broadcasts for this document and
+    # transmits the server's opening handshake (SyncStep1 from the store).
+    def sync_subscribed(key)
+      @sync_key = key.to_s
+      sync_validate_required_hooks!
+
+      # The document stream is never whisper-enabled; under AnyCable we also
+      # subscribe an awareness stream with `whisper: true`, scoping the client-to-
+      # client path to ephemeral presence rather than the durable document stream.
+      stream_from sync_stream_name
+      stream_from sync_awareness_stream_name, whisper: true if respond_to?(:whispers_to)
+      sync_transmit(sync_load_doc.sync_step1)
+    end
+
+    # Call from `receive`. Applies the client's message, replies directly
+    # when the protocol calls for it, and relays document/awareness changes
+    # to the other subscribers.
+    #
+    # Reliable delivery: document updates carry an "id", and the server replies
+    # `{ "ack" => id }` once the update has been durably recorded. A
+    # causally-gapped update is not acked; it gets a resync instead, so the
+    # client retransmits until the update lands.
+    def sync_receive(data, key = nil)
+      # Pass `key` (params[:id]) when your transport doesn't keep the channel
+      # instance alive across actions. Under AnyCable each RPC command gets a
+      # fresh channel, so instance variables set in `subscribed` are gone here.
+      @sync_key = key.to_s if key
+
+      encoded = data.is_a?(Hash) ? data["update"] : nil
+      return unless encoded.is_a?(String)
+
+      # Optional client-supplied id for reliable delivery (see sync_send_ack).
+      # data is known to be a Hash here (encoded came from it above).
+      id = data["id"]
+
+      # Frame-size cap: drop oversized frames before decoding (the encoded form
+      # is ~4/3 the decoded size) and again after, so a client can't force large
+      # base64 decodes / native parses / merges. A dropped frame is never acked,
+      # and there is no protocol NACK, so a legitimate oversized update is
+      # retransmitted indefinitely. Log the drop so it is at least findable.
+      cap = self.class.max_frame_bytes
+      if cap && encoded.bytesize > (cap * 4 / 3) + 4
+        sync_log_drop(:warn, "encoded #{encoded.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
+
+      begin
+        bytes = Base64.strict_decode64(encoded)
+      rescue ArgumentError
+        sync_log_drop(:debug, "not valid base64", id) # garbage or a probe, rarely a real client
+        return # ignore the frame and keep the connection
+      end
+
+      if cap && bytes.bytesize > cap
+        sync_log_drop(:warn, "decoded #{bytes.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
+
+      sync_send_ack(id, sync_handle_frame(encoded, bytes))
+    end
+
+    private
+
+    # Ask this connection's client to resync: re-send SyncStep1 carrying the
+    # server's current (gap-free) state vector. The client replies SyncStep2
+    # with everything the server is missing, delivered as one causally-complete
+    # delta, which heals the gap that triggered the resync.
+    def sync_request_resync(doc)
+      sync_transmit(doc.sync_step1)
+    end
+
+    # Reliable delivery: acknowledge an accepted update back to the sending
+    # connection. An ack-aware client tags each outgoing update with an "id"
+    # and retains it until the matching `{ "ack" => id }` returns, retransmitting
+    # on a timer or reconnect; idempotent CRDT apply makes resends free. Acks
+    # are sent only after the update has been durably recorded, or when a retry
+    # is already present in the durable store.
+    def sync_send_ack(id, outcome)
+      return if id.nil?
+      return unless %i[recorded applied].include?(outcome)
+
+      # The braces are required: a bare hash would bind to transmit's `via:`
+      # keyword instead of its positional data argument.
+      transmit({ "ack" => id })
+    end
+
+    # Single broadcast point so relay semantics live in one place and tests can
+    # observe distribution. Store-backed streams intentionally echo to the
+    # sender; applying the same CRDT update twice is a no-op.
+    def sync_distribute(encoded)
+      ActionCable.server.broadcast(sync_stream_name, sync_envelope(encoded))
+    end
+
+    # Transmit raw protocol bytes to this connection.
+    def sync_transmit(bytes)
+      transmit(sync_envelope(Base64.strict_encode64(bytes)))
+    end
+
+    def sync_envelope(encoded)
+      { "update" => encoded }
+    end
+
+    # Override in the channel to add identifying context to dropped-frame logs --
+    # a user id, a connection id, a request id. Return a short string (or nil for
+    # none); it is appended to the log line. Default: no extra context.
+    def sync_log_context
+      nil
+    end
+
+    # Surface a dropped frame through the channel logger. Drops are otherwise
+    # invisible (no ack, no broadcast); an oversized legitimate update is never
+    # acked and the client retransmits it forever, so make it findable. Names the
+    # document key, the reliable-delivery id when present, and whatever
+    # sync_log_context returns, so a drop can be tied to a specific document,
+    # update, and connection.
+    def sync_log_drop(level, reason, id = nil)
+      logger.public_send(level) do
+        parts = ["key=#{@sync_key.inspect}"]
+        parts << "id=#{id}" unless id.nil?
+        # A broken context hook must surface, not take down frame handling.
+        context = begin
+          sync_log_context
+        rescue StandardError => e
+          "log-context-error=#{e.class}"
+        end
+        parts << context if context
+        "[yrby] dropped frame (#{parts.join(" ")}): #{reason}"
+      end
+    end
+
+    # This concern acks updates as durably recorded, so it must have both a
+    # loader (to rebuild the doc and detect causal gaps) and a recorder (to
+    # actually persist before acking). Fail closed rather than silently acking
+    # and broadcasting updates that were never stored, which a cold load or
+    # reconnect would then lose.
+    def sync_validate_required_hooks!
+      missing = []
+      missing << :on_load unless self.class.on_load
+      missing << :on_change unless self.class.on_change
+      return if missing.empty?
+
+      raise Y::Error,
+            "Y::ActionCable::Sync requires #{missing.join(" and ")}. Updates are acked as " \
+            "durably recorded; without a loader and recorder, an ack would claim a persistence " \
+            "that never happened, and a cold load would lose the edit."
+    end
+
+    # Fail closed when no document key is set (typically: AnyCable rebuilt the
+    # channel instance and the app forgot to pass `key` to sync_receive).
+    # Proceeding would record under nil, broadcast to a stream nobody
+    # subscribes to, and still ack — the client believes the edit was
+    # delivered when it reached no one.
+    def sync_validate_key!
+      return unless @sync_key.nil? || @sync_key.empty?
+
+      raise Y::Error,
+            "Y::ActionCable::Sync has no document key. Call sync_subscribed(key) in " \
+            "subscribed, and pass the key to sync_receive(data, key) when the transport " \
+            "doesn't keep the channel instance alive across actions (e.g. AnyCable)."
+    end
+
+    # Stateless per message: any process can handle any document. A client's
+    # SyncStep1 is answered from the store, document changes are recorded durably
+    # before relay and then broadcast, and awareness is relayed best-effort.
+    # Echoing back to the sender is harmless, since the CRDT apply is idempotent.
+    #
+    # Returns an outcome symbol for the reliable-delivery ack: :recorded when a
+    # document update was durably recorded and relayed, :gap when it was
+    # rejected for a resync, :noop for everything else.
+    def sync_handle_frame(encoded, bytes)
+      sync_validate_required_hooks!
+      sync_validate_key!
+
+      case Y.message_kind(bytes)
+      when MSG_KIND_SYNC_STEP1
+        result = sync_load_doc.handle_sync_message(bytes)
+        sync_transmit(result[2])
+        :noop
+      when MSG_KIND_UPDATE
+        update = Y.update_from_message(bytes)
+        return :noop unless update
+
+        # Rebuild from the store (O(history) per update; snapshot in on_load if
+        # that cost bites).
+        doc = sync_load_doc
+
+        # Don't record a causally-incomplete update; resync instead so the gap
+        # heals as one complete delta.
+        unless doc.update_ready?(update)
+          sync_request_resync(doc)
+          return :gap
+        end
+
+        # A lost-ack retry: already recorded, so skip on_change — but DO
+        # re-broadcast. If the first attempt died between record and broadcast,
+        # this retry is the only path left to the live subscribers. Duplicate
+        # broadcasts are free (CRDT apply is idempotent).
+        unless doc.update_advances?(update)
+          sync_distribute(encoded)
+          return :applied
+        end
+
+        sync_record_change(update) # record before relay
+        sync_distribute(encoded)
+        :recorded
+      when MSG_KIND_AWARENESS
+        sync_distribute(encoded)
+        :noop
+      else
+        :noop
+      end
+    end
+
+    # Build a fresh document from the durable store (on_load). Callers validate
+    # the hooks first, so on_load is present; a nil state means a fresh document.
+    def sync_load_doc
+      doc = Y::Doc.new
+      state = instance_exec(@sync_key, &self.class.on_load)
+      doc.apply_update(state) if state
+      doc
+    end
+
+    def sync_stream_name
+      "yrby:#{@sync_key}"
+    end
+
+    def sync_awareness_stream_name
+      "#{sync_stream_name}:awareness"
+    end
+
+    # Invoke the on_change recorder in this channel instance's context
+    # (instance_exec) so it can reach the channel's own methods. Mirrors how
+    # sync_load_doc fetches and runs on_load.
+    def sync_record_change(update)
+      instance_exec(@sync_key, update, &self.class.on_change)
+    end
+  end
+end