yrb-lite 0.1.0.beta3 → 0.1.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdc68c7b4936a2e6598441f2def20050e456a543f44de6ecd35aeb1a894cdcc7
-  data.tar.gz: 5a5ffbf2c1df1fc41d7eba424579459587d46e1e38db0606b79efefb5d5321c0
+  metadata.gz: 36bbe7531107d8654bf93ad29a1b3be40493b9f3a1172a3d478c39b75865f86d
+  data.tar.gz: 4175439a46c097b42c1316f44a6f43b4456db4977070072b7036a14e1bb5a64f
 SHA512:
-  metadata.gz: 00bff87ec9b51a46f7bee55e838ef629531c0f4faaa43400f2447055932fefc4d8ce597c15724b98e384bbd5f119c881ebf1f85f2b2bab614ff6d3e00d570eaa
-  data.tar.gz: 0dff053de27327d7517bdb83b850ee45c977d38f1556ee38210e8e3431da19937c1cc4e22201da2242ca249cee1a1647b8f0ec5dd1fe50ed75fb2d78743a4947
+  metadata.gz: da8fe865e590fd0c728f005c0a6bd040e8fca9424edf93d2f2bed4f0c88560c019451ade3c3bd9067ec1375a0c80fc02af55cd013901c8026510aab6c91d5bf1
+  data.tar.gz: 9cfca9a9430b4317041d748efc2d5a1116d97145f1d851a036bf466e159f0f87ef3c615ece560744bcfe78760efc8f08870be838341605c23792f406900acd44

data/CHANGELOG.md

@@ -6,6 +6,39 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.0.beta5] - 2026-06-18
+
+### Changed
+
+- **Breaking:** the ActionCable integration has been extracted into a separate
+  gem, [`yrb-lite-actioncable`](https://rubygems.org/gems/yrb-lite-actioncable).
+  `yrb-lite` is now a standalone y-crdt wrapper: CRDT documents, awareness, and
+  the y-websocket sync protocol primitives, with no Rails/ActionCable coupling
+  (mirrors the `y-rb` / `yrb-actioncable` split). The `base64` runtime
+  dependency moved with it.
+
+### Migration
+
+- Using `YrbLite::Sync`? Add `gem "yrb-lite-actioncable"` and change
+  `include YrbLite::Sync` to `include YrbLite::ActionCable::Sync`. The concern's
+  API is otherwise unchanged. If you only use `YrbLite::Doc`/`YrbLite::Awareness`,
+  nothing changes.
+
+## [0.1.0.beta4] - 2026-06-18
+
+### Changed
+
+- `on_change` block recorders now run in the **channel instance's context**
+  (via `instance_exec`), so a recorder can call the channel's own methods --
+  `current_user`, `params`, request/connection-scoped accessors -- directly,
+  instead of plumbing them in through a thread-local. A non-Proc callable (an
+  object responding to `#call`) is still invoked with `#call` and its own
+  context. `on_load`/`on_save` are unchanged: they can run in the shared
+  document registry during a cold load or eviction, where no connection
+  instance exists, so they remain key-only. Existing block recorders that use
+  only the `(key, update)` arguments and lexically-scoped constants are
+  unaffected; the only behavioral change is `self` inside the block.
+
 ## [0.1.0.beta3] - 2026-06-18
 
 ### Changed
@@ -76,7 +109,9 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Precompiled native gems for common platforms (no Rust toolchain needed to
   install) via the cross-gem workflow.
 
-[Unreleased]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta3...main
+[Unreleased]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta5...main
+[0.1.0.beta5]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta4...v0.1.0.beta5
+[0.1.0.beta4]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta3...v0.1.0.beta4
 [0.1.0.beta3]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta2...v0.1.0.beta3
 [0.1.0.beta2]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta1...v0.1.0.beta2
 [0.1.0.beta1]: https://github.com/jpcamara/yrb-lite/releases/tag/v0.1.0.beta1

data/ext/yrb_lite/src/lib.rs

@@ -1,10 +1,10 @@
 use magnus::{function, method, prelude::*, Error, RString, Ruby, TryConvert, Value};
+use std::sync::Mutex;
 use yrs::encoding::read::{Cursor, Read};
 use yrs::sync::protocol::MessageReader;
 use yrs::sync::{Awareness, DefaultProtocol, Message, Protocol, SyncMessage};
 use yrs::updates::decoder::{Decode, DecoderV1};
 use yrs::updates::encoder::{Encode, Encoder, EncoderV1};
-use std::sync::Mutex;
 use yrs::{ClientID, Doc, ReadTxn, Transact};
 
 /// Wrapper around yrs Doc.

data/lib/yrb_lite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YrbLite
-  VERSION = "0.1.0.beta3"
+  VERSION = "0.1.0.beta5"
 end

data/lib/yrb_lite.rb

@@ -13,8 +13,8 @@ rescue LoadError
 end
 
 module YrbLite
-  # Error class is defined in Rust extension
-
-  # Autoload Sync module - only loaded when ActionCable is available
-  autoload :Sync, "yrb_lite/sync"
+  # Error class is defined in the Rust extension.
+  #
+  # The ActionCable integration (YrbLite::ActionCable::Sync) lives in the
+  # separate `yrb-lite-actioncable` gem; require "yrb_lite/action_cable".
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta3
+  version: 0.1.0.beta5
 platform: ruby
 authors:
 - JP Camara
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: base64
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rb_sys
   requirement: !ruby/object:Gem::Requirement
@@ -79,10 +65,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-description: yrb-lite is a thread-safe Ruby binding over the Rust y-crdt (yrs) library
-  plus an ActionCable concern implementing the full y-websocket sync protocol and
-  awareness. It lets a Rails app be the collaboration server for Y.js editors (Tiptap,
-  ProseMirror, BlockNote) with no Node sidecar.
+description: 'yrb-lite is a thread-safe Ruby binding over the Rust y-crdt (yrs) library:
+  CRDT documents, awareness/presence, and the y-websocket sync protocol primitives,
+  with the GVL released during native work so documents sync in parallel. The ActionCable/Rails
+  integration lives in the companion yrb-lite-actioncable gem.'
 email:
 - johnpcamara@gmail.com
 executables: []
@@ -99,7 +85,6 @@ files:
 - ext/yrb_lite/src/lib.rs
 - lib/yrb-lite.rb
 - lib/yrb_lite.rb
-- lib/yrb_lite/sync.rb
 - lib/yrb_lite/version.rb
 homepage: https://github.com/jpcamara/yrb-lite
 licenses:
@@ -125,6 +110,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Thread-safe Ruby bindings for y-crdt (Y.js) with the y-websocket sync protocol
-  for ActionCable
+summary: 'Thread-safe Ruby bindings for y-crdt (Y.js): documents, awareness, and the
+  y-websocket sync protocol'
 test_files: []

data/lib/yrb_lite/sync.rb

@@ -1,559 +0,0 @@
-# frozen_string_literal: true
-
-require "base64"
-require "securerandom"
-
-module YrbLite
-  # 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:
-  #
-  #   { "m" => "<base64 bytes>" }              # client -> server
-  #   { "m" => "...", "origin" => "<id>" }     # server -> subscribers
-  #
-  # Example:
-  #   class DocumentChannel < ApplicationCable::Channel
-  #     include YrbLite::Sync
-  #
-  #     on_load { |key| Document.find_by(key: key)&.content }
-  #     on_save { |key, update| Document.find_by(key: key)&.update!(content: update) }
-  #
-  #     def subscribed
-  #       sync_for params[:id]
-  #     end
-  #
-  #     def receive(data)
-  #       sync_receive(data)
-  #     end
-  #
-  #     def unsubscribed
-  #       sync_clear_presence
-  #     end
-  #   end
-  #
-  # The shared YrbLite::Awareness instances are safe to use from ActionCable's
-  # worker thread pool: the native types are Send + Sync and every operation
-  # releases the GVL, so concurrent clients sync in parallel.
-  module Sync
-    # Validated frame kinds from Awareness#message_kind. A frame only gets a
-    # non-DROP kind if it is exactly one well-formed message; anything
-    # malformed, truncated, multi-message, or unknown is dropped before it can
-    # be processed or relayed.
-    MSG_KIND_DROP = 0
-    MSG_KIND_SYNC_STEP1 = 1
-    MSG_KIND_UPDATE = 2
-    MSG_KIND_AWARENESS = 3
-    MSG_KIND_AWARENESS_QUERY = 4
-
-    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).
-      def on_load(callable = nil, &block)
-        @on_load = callable || block if callable || block
-        @on_load
-      end
-
-      # Persist document state. Called with (key, update) after every
-      # message that modified the document.
-      def on_save(callable = nil, &block)
-        @on_save = callable || block if callable || block
-        @on_save
-      end
-
-      # Record every document change durably before it is applied or
-      # distributed (authoritative audit mode). Called synchronously with
-      # (key, update), where update is the exact CRDT delta, serialized per
-      # document so the recorded order is the apply order. If the block raises,
-      # the change is rejected: neither applied to the shared document nor
-      # broadcast to other subscribers.
-      #
-      # Registering an on_change switches that channel onto the strict path
-      # (record, apply, broadcast). Without it, the default fast path applies
-      # and broadcasts, with an optional on_save snapshot.
-      def on_change(callable = nil, &block)
-        @on_change = callable || block if callable || block
-        @on_change
-      end
-
-      # Select the document backend:
-      #   :memory (default): keep a warm in-memory replica per process and keep
-      #     it current via a custom stream_from callback. Fast, but it assumes
-      #     classic ActionCable (the callback runs in Ruby) and
-      #     process<->document affinity.
-      #   :store: stateless per message, with no warm replica and no custom
-      #     stream callback. Handshakes and reads are served from the durable
-      #     store (`on_load`); changes are recorded (`on_change`) and relayed.
-      #     Works under AnyCable (broadcasts handled outside Ruby, no worker
-      #     affinity) and across processes. Requires `on_load` and `on_change`.
-      def sync_backend(mode = nil)
-        @sync_backend = mode if mode
-        @sync_backend || :memory
-      end
-    end
-
-    # Call from `subscribed`. Streams broadcasts for this document and
-    # transmits the server's opening handshake (SyncStep1 + awareness).
-    def sync_for(key)
-      @sync_key = key.to_s
-      @sync_origin = SecureRandom.hex(8)
-      @sync_clients = [] # awareness client IDs seen on this connection
-
-      return sync_for_store_backed if self.class.sync_backend == :store
-
-      Sync.subscribe(@sync_key)
-      awareness = sync_awareness
-
-      stream_from sync_stream_name, coder: ActiveSupport::JSON do |payload|
-        sync_on_broadcast(payload)
-      end
-
-      # Opening handshake: SyncStep1 then the current awareness, each as its
-      # own single-message frame, so providers that parse one message per frame
-      # (e.g. @y-rb/actioncable) handle both. The client replies SyncStep2 to
-      # the SyncStep1, delivering its state to the server.
-      sync_transmit(awareness.sync_step1)
-      sync_transmit(awareness.encode_awareness_update)
-    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.
-    #
-    # If an `on_change` recorder is registered, document changes take the
-    # strict authoritative path (record -> apply -> broadcast, serialized per
-    # document); otherwise the fast path is used.
-    #
-    # Reliable delivery (opt-in, client-driven): if the frame carries an "id",
-    # the server replies `{ "ack" => id }` once the update has been accepted
-    # (recorded in audit mode, applied in fast mode). A causally-gapped update
-    # is not acked -- it gets a resync instead -- so an ack-aware client knows
-    # to retransmit until the update lands. Stock clients send no "id", never
-    # get acks, and are completely unaffected.
-    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
-
-      # Accept both envelope keys: "m" (yrb-lite's own clients) and "update"
-      # (the @y-rb/actioncable browser provider).
-      m = data.is_a?(Hash) ? (data["m"] || data["update"]) : nil
-      return unless m.is_a?(String)
-
-      # Optional client-supplied id for reliable delivery (see sync_send_ack).
-      id = data.is_a?(Hash) ? data["id"] : nil
-
-      begin
-        bytes = Base64.strict_decode64(m)
-      rescue ArgumentError
-        return # not valid base64; ignore the frame and keep the connection
-      end
-
-      sync_send_ack(id, sync_dispatch(m, bytes))
-    end
-
-    # Route a decoded frame to the backend/path that handles it and return the
-    # outcome symbol (:recorded/:applied/:gap/:noop) used by the reliable-
-    # delivery ack. A dropped frame returns nil (never acked).
-    def sync_dispatch(encoded, bytes)
-      return sync_receive_store_backed(encoded, bytes) if self.class.sync_backend == :store
-
-      awareness = sync_awareness
-      kind = awareness.message_kind(bytes)
-      # Malformed / truncated / multi-message / unknown frames are dropped
-      # before they can be processed or relayed to other clients.
-      return if kind == MSG_KIND_DROP
-
-      sync_track_clients(awareness, bytes) if kind == MSG_KIND_AWARENESS
-
-      if kind == MSG_KIND_UPDATE && self.class.on_change
-        sync_apply_authoritative(awareness, encoded, bytes)
-      else
-        sync_apply_fast(awareness, encoded, bytes, kind)
-      end
-    end
-
-    # Call from `unsubscribed`. Clears the presence states this connection
-    # introduced and tells the other subscribers to drop those cursors, so a
-    # closed tab or dropped socket doesn't leave a ghost cursor behind until
-    # the client-side timeout reaps it.
-    def sync_clear_presence
-      return if @sync_clients.nil? || @sync_clients.empty?
-
-      removal = sync_awareness.remove_clients(@sync_clients)
-      @sync_clients = []
-      return if removal.empty?
-
-      sync_distribute(Base64.strict_encode64(removal))
-    end
-
-    # Call from `unsubscribed`. Clears this connection's presence and, when the
-    # last subscriber for the document leaves, persists and unloads it from
-    # memory (only when an `on_load` is configured to bring it back; otherwise
-    # the in-memory document is the only copy and is kept). Prevents a
-    # long-running server from accumulating every document it has ever served.
-    def sync_unsubscribed(key = nil)
-      @sync_key = key.to_s if key
-      return if self.class.sync_backend == :store # nothing cached per process
-
-      sync_clear_presence
-      saver = self.class.on_save
-      Sync.release(@sync_key, evictable: !self.class.on_load.nil?) do |awareness|
-        saver&.call(@sync_key, awareness.encode_state_as_update)
-      end
-    end
-
-    # The shared Awareness (document + presence) for this channel's key.
-    # Also useful for server-side reads, e.g.:
-    #   sync_awareness.encode_state_as_update
-    def sync_awareness
-      Sync.awareness_for(@sync_key, self.class.on_load)
-    end
-
-    private
-
-    # Default path: apply the message, answer direct requests, relay
-    # state-changing messages to the other subscribers. Routing comes from the
-    # native `kind` (from Awareness#message_kind) rather than peeking at bytes.
-    # Document changes (SyncStep2, Update) and awareness get relayed; requests
-    # (SyncStep1, awareness-query) are answered above and not relayed. An
-    # optional on_save snapshot is taken after a document change.
-    #
-    # Returns an outcome symbol for the reliable-delivery ack: :applied when a
-    # document update was integrated and relayed, :gap when it was rejected for
-    # a resync, :noop for everything else (requests, awareness, empty updates).
-    def sync_apply_fast(awareness, encoded, bytes, kind)
-      # A document update that isn't causally ready (an earlier one was lost in
-      # transit) would relay an un-integrable change to peers and stall the
-      # replica. Drop it and ask the client to resync instead, which re-delivers
-      # the missing piece. See sync_apply_authoritative for the durable variant.
-      if kind == MSG_KIND_UPDATE
-        update = awareness.update_from_message(bytes)
-        # A no-op message (e.g. the empty SyncStep2 in an opening handshake)
-        # carries no change, so there's nothing to relay, persist, or ack.
-        return :noop unless update
-
-        unless awareness.update_ready?(update)
-          sync_request_resync(awareness)
-          return :gap
-        end
-      end
-
-      response = awareness.handle(bytes)
-      sync_transmit(response) unless response.empty?
-
-      return :noop unless [MSG_KIND_UPDATE, MSG_KIND_AWARENESS].include?(kind)
-
-      sync_distribute(encoded)
-      return :noop unless kind == MSG_KIND_UPDATE
-
-      sync_persist
-      :applied
-    end
-
-    # Authoritative path: record the change durably, then apply it to the
-    # shared document, then distribute it. The sequence runs under a
-    # per-document lock so changes are recorded in a single total order that
-    # matches the order they're applied, and nothing is distributed (or applied)
-    # before it has been recorded. If the recorder raises, the change is
-    # rejected (not applied, not broadcast) and the exception propagates, so the
-    # channel can surface it and the client can resync.
-    #
-    # Before recording, the update must be causally ready: every dependency it
-    # references must already be in the doc. If an earlier update was lost in
-    # transit, or its record failed, a later update arrives with a gap. Recording
-    # it would write a permanently-pending entry to the log -- one that can never
-    # be replayed until the missing update shows up. Such an update is rejected
-    # (not recorded, not applied, not relayed) and the client is asked to resync,
-    # which re-delivers the missing range as one causally-complete delta.
-    def sync_apply_authoritative(awareness, encoded, bytes)
-      recorder = self.class.on_change
-
-      outcome = Sync.lock_for(@sync_key).synchronize do
-        update = awareness.update_from_message(bytes)
-        # A no-op message (e.g. the empty SyncStep2 in a client's opening
-        # handshake) carries no change, so there's nothing to record or relay.
-        next :noop unless update
-        next :gap unless awareness.update_ready?(update)
-
-        recorder.call(@sync_key, update) # durable write; raise to reject
-        awareness.apply_update(update)   # only recorded changes reach the doc
-        sync_distribute(encoded)         # ...and only then the wire
-        :recorded
-      end
-
-      case outcome
-      when :recorded then sync_persist
-      when :gap      then sync_request_resync(awareness)
-      end
-
-      # Surface the outcome for the reliable-delivery ack: :recorded means the
-      # update is durably written (and will be acked); :gap triggered a resync
-      # (no ack); :noop carried no change.
-      outcome
-    end
-
-    # 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(awareness)
-      sync_transmit(awareness.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. We ack
-    # only when the client supplied an id (so stock clients are unaffected) and
-    # the update was actually accepted -- recorded in audit mode, applied in fast
-    # mode. A gapped update gets no ack (it got a resync), so the client keeps
-    # retransmitting until the missing range lands and the update can integrate.
-    def sync_send_ack(id, outcome)
-      return if id.nil?
-      return unless %i[recorded applied].include?(outcome)
-
-      # Braces are load-bearing: a bare hash would bind to transmit's `via:`
-      # keyword instead of its positional data argument.
-      transmit({ "ack" => id })
-    end
-
-    # Single broadcast point for both paths (and presence removal), so the
-    # relay semantics live in one place and tests can observe distribution.
-    # `origin` identifies the sending connection (don't echo to it); `pid`
-    # identifies the sending process (other processes apply it to their own
-    # replica; see sync_on_broadcast).
-    def sync_distribute(encoded)
-      ActionCable.server.broadcast(
-        sync_stream_name,
-        sync_envelope(encoded, "origin" => @sync_origin, "pid" => Sync.process_id)
-      )
-    end
-
-    # Transmit raw protocol bytes to this connection (base64, dual-key).
-    def sync_transmit(bytes)
-      transmit(sync_envelope(Base64.strict_encode64(bytes)))
-    end
-
-    # Build an outgoing envelope. We send the payload under both keys: "m"
-    # (yrb-lite's own clients) and "update" (the @y-rb/actioncable provider),
-    # so either client works against the same server.
-    def sync_envelope(encoded, extra = {})
-      { "m" => encoded, "update" => encoded }.merge(extra)
-    end
-
-    # Handle a broadcast delivered by the cable adapter. With a multi-process
-    # adapter (Redis, solid_cable), it may have come from another server
-    # process. Keep this process's in-memory replica current with changes that
-    # originated elsewhere, then relay to this connection's browser.
-    def sync_on_broadcast(payload)
-      sync_apply_remote(payload["m"]) if payload["pid"] != Sync.process_id
-      transmit(payload) unless payload["origin"] == @sync_origin
-    end
-
-    # Apply a change that originated on another process to this process's
-    # replica, without re-recording it (the origin process already recorded it
-    # before broadcasting). The CRDT merge is idempotent and commutative, so a
-    # cold replica converges regardless of ordering, and applying from several
-    # local connections is harmless.
-    def sync_apply_remote(encoded)
-      return unless encoded.is_a?(String)
-
-      begin
-        bytes = Base64.strict_decode64(encoded)
-      rescue ArgumentError
-        return
-      end
-
-      awareness = sync_awareness
-      case awareness.message_kind(bytes)
-      when MSG_KIND_UPDATE
-        update = awareness.update_from_message(bytes)
-        awareness.apply_update(update) if update
-      when MSG_KIND_AWARENESS
-        awareness.handle(bytes)
-      end
-    end
-
-    # -- Store-backed (AnyCable-native) path --------------------------------
-
-    # Subscribe without a custom block, so AnyCable (which delivers broadcasts
-    # outside Ruby) relays them directly. Send the opening SyncStep1 built from
-    # the durable store. No warm replica is kept.
-    def sync_for_store_backed
-      stream_from sync_stream_name
-      sync_transmit(sync_load_doc.sync_step1)
-    end
-
-    # Stateless per message: no warm replica, no assumptions about which process
-    # owns a 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_receive_store_backed(encoded, bytes)
-      case Sync.codec.message_kind(bytes)
-      when MSG_KIND_SYNC_STEP1
-        result = sync_load_doc.handle_sync_message(bytes)
-        sync_transmit(result[2]) if result
-        :noop
-      when MSG_KIND_UPDATE
-        update = Sync.codec.update_from_message(bytes)
-        return :noop unless update
-
-        # Store mode keeps no warm replica, so to tell whether this update is
-        # causally ready we rebuild the doc from the store and check against it.
-        # That's an O(history) load per update (mitigated by snapshotting the
-        # store on the load path). A gappy update -- an earlier one was lost or
-        # its record failed -- is rejected and the client asked to resync,
-        # rather than written to the log as a permanently-pending entry.
-        doc = sync_load_doc
-        unless doc.update_ready?(update)
-          sync_transmit(doc.sync_step1)
-          return :gap
-        end
-
-        self.class.on_change&.call(@sync_key, 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).
-    def sync_load_doc
-      doc = YrbLite::Doc.new
-      state = self.class.on_load&.call(@sync_key)
-      doc.apply_update(state) if state
-      doc
-    end
-
-    # Record the awareness client IDs carried by an incoming message (already
-    # known to be an awareness frame) so we can clear them when this connection
-    # closes.
-    def sync_track_clients(awareness, bytes)
-      awareness.awareness_client_ids(bytes).each do |id|
-        @sync_clients << id unless @sync_clients.include?(id)
-      end
-    end
-
-    def sync_stream_name
-      "yrb_lite:#{@sync_key}"
-    end
-
-    def sync_persist
-      return unless (saver = self.class.on_save)
-
-      saver.call(@sync_key, sync_awareness.encode_state_as_update)
-    end
-
-    # -- Shared document registry ------------------------------------------
-
-    @registry = {}
-    @locks = {}
-    @subscribers = Hash.new(0)
-    @registry_mutex = Mutex.new
-
-    class << self
-      # A stable id for this server process, stamped on every broadcast so
-      # other processes know to apply it to their replica and this process
-      # knows to skip its own. Survives for the life of the process.
-      def process_id
-        @process_id ||= SecureRandom.hex(8)
-      end
-
-      # A shared, stateless decoder for the store-backed path. message_kind and
-      # update_from_message only read their argument (they don't touch the
-      # instance's document), so one shared instance is safe across threads.
-      def codec
-        @codec ||= YrbLite::Awareness.new
-      end
-
-      # Get or create the shared Awareness for a key. Creation (including
-      # the on_load callback) is serialized under a mutex so concurrent
-      # subscribers can never observe two documents for one key; all
-      # subsequent operations run lock-free on the thread-safe native types.
-      def awareness_for(key, loader = nil)
-        @registry_mutex.synchronize do
-          @registry[key] ||= begin
-            awareness = YrbLite::Awareness.new
-            if loader && (state = loader.call(key))
-              awareness.apply_update(state)
-            end
-            awareness
-          end
-        end
-      end
-
-      # Per-document mutex serializing the authoritative record -> apply ->
-      # broadcast section, so a document's audit log is a single total order.
-      # Only briefly holds the registry mutex to fetch/create the lock; the
-      # durable write itself runs while holding only this per-key lock.
-      def lock_for(key)
-        @registry_mutex.synchronize { @locks[key] ||= Mutex.new }
-      end
-
-      # Count a new subscriber for a document.
-      def subscribe(key)
-        @registry_mutex.synchronize { @subscribers[key] += 1 }
-      end
-
-      # Drop a subscriber. When the last one leaves and the document is
-      # evictable (there's an on_load to bring it back, so unloading can't lose
-      # data), persist it via the given block and unload it from memory, so a
-      # long-running server doesn't accumulate every document and lock it has
-      # ever seen. Returns true if the document was evicted.
-      #
-      # The persist runs outside the registry lock (it may do I/O), and we
-      # re-check the subscriber count afterward: if someone reconnected while
-      # we were saving, eviction is aborted and the warm document is kept.
-      def release(key, evictable:)
-        awareness = @registry_mutex.synchronize do
-          @subscribers[key] -= 1 if @subscribers[key].positive?
-          next nil unless @subscribers[key].zero?
-
-          @subscribers.delete(key)
-          evictable ? @registry[key] : nil
-        end
-        return false unless awareness
-
-        yield awareness if block_given?
-
-        @registry_mutex.synchronize do
-          # A subscriber may have returned during the persist above.
-          next false unless @subscribers[key].zero?
-
-          @subscribers.delete(key)
-          @locks.delete(key)
-          !@registry.delete(key).nil?
-        end
-      end
-
-      def registry
-        @registry_mutex.synchronize { @registry.dup }
-      end
-
-      # Clear all documents (useful for testing).
-      def reset!
-        @registry_mutex.synchronize do
-          @registry = {}
-          @locks = {}
-          @subscribers = Hash.new(0)
-        end
-      end
-    end
-  end
-end