yrb-lite 0.1.0.beta4-aarch64-linux → 0.1.0.beta6-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 811a029459e6baa58dd666044e5109b00f9492b3cbca4e9ea19009e4460398ba
-  data.tar.gz: 38f3b38b56f1da1fc5b03c33e771ee14c89a92d45156b00c342d30ba60800663
+  metadata.gz: 2730b0d6a2bc31a36de1f842d7345659788d4c45968a895dfbbf7855ee6be21d
+  data.tar.gz: 9731717390fc3e45c983f20dd51429c214a6aaca85cb75b0e375a34390a785e0
 SHA512:
-  metadata.gz: 000b629de89198de2cf68d674acb297208d82b6e55760dc7a7252750b6c0868f7e18fda227793168b0904a80dd36b8d597d8ae335e53143b527e992b4cadaec9
-  data.tar.gz: 974cb16418ca4454daf682fbd0b45b5dad6d413a3db7e978d28d4481b7984473485ce29cc04070c458f62a4756d7a1da3c6525170a6128b922093aae876ab206
+  metadata.gz: '0913343e81dd6564a2ce23f058ec63cadb23917a105a86e430d859df77856054a8c0e4c02051a28a0dc8903c916f8c7ea60dd051ae8cbc022064d28539610680'
+  data.tar.gz: fb98a8a3e81ec173f812618dce6075a84f6516e4c7991c650c35835958465312b5b0380176a1e5628fdf302de8faa0ec05d3df64b1f78533c96820825ec4d2bc

data/CHANGELOG.md

@@ -6,6 +6,53 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.0.beta6] - 2026-06-22
+
+(yrb-lite core gem. The `yrb-lite-client` npm package ships these client changes as 0.1.2.)
+
+### Added
+
+- `yrb-lite-client`, the TypeScript client package for the yrb-lite
+  ActionCable/AnyCable protocol. It provides `ActionCableProvider`,
+  `YProtocolSession`, and the standalone `ReliableSync` delivery core.
+
+### Changed
+
+- Document delivery is ack-tracked by default in `yrb-lite-client`: document
+  frames use `{ update, id }`, acknowledgements use `{ ack }`, and pending
+  document updates stay queued until acked.
+- The ActionCable protocol surface uses a single canonical document envelope:
+  `{ "update" => "<base64 frame>" }`.
+- AnyCable awareness/presence uses an awareness-only whisper envelope,
+  `{ awareness: "<base64 awareness frame>" }`, while document frames stay on
+  the server persistence/ack path.
+
+### Fixed
+
+- Incoming protocol frames are validated before mutating documents or awareness
+  state, including trailing-byte rejection on the TypeScript client.
+- Native/Rust protocol entry points reject wire client IDs that are unsafe for
+  JavaScript clients.
+- `lib0` is declared as a direct runtime dependency of `yrb-lite-client`.
+
+## [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
@@ -15,9 +62,7 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `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
+  context. 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.
 
@@ -49,15 +94,13 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Reliable delivery (opt-in, client-driven). A client may tag a document update
   with an `"id"`; the server replies `{ "ack": <id> }` once the update has been
-  accepted (recorded in audit mode, applied in fast mode). This lets an
+  durably recorded. This lets an
   ack-aware client retain and retransmit an update until delivery is confirmed,
-  so an edit can't be silently lost on a flaky connection. Stock clients send no
-  `"id"`, never get acks, and behave exactly as before.
-- A vendored, ack-aware `@y-rb/actioncable` provider in the demo
-  (`reliable_actioncable_provider.mjs`) that adds reliable delivery with
-  "sync-since-last-ack" framing (the unacknowledged tail is sent as one merged,
-  causally-complete delta), plus a minimal reference client and an intensive
-  message-loss stress test.
+  so an edit can't be silently lost on a flaky connection. Clients that omit
+  `"id"` are still accepted, but their delivery is not ack-tracked.
+- Demo coverage for reliable delivery with "sync-since-last-ack" framing (the
+  unacknowledged tail is sent as one merged, causally-complete delta), plus a
+  minimal reference client and an intensive message-loss stress test.
 
 ### Fixed
 
@@ -77,21 +120,19 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   native extension). The GVL is released during CRDT work so docs can run in
   parallel on MRI.
 - `YrbLite::Sync` ActionCable channel concern implementing the y-websocket
-  protocol (document sync plus awareness/presence). It's wire-compatible with
-  the [`@y-rb/actioncable`](https://www.npmjs.com/package/@y-rb/actioncable)
-  browser provider, and accepts its `{ update: ... }` envelope and `{ m: ... }`.
+  protocol (document sync plus awareness/presence).
 - A "record-before-distribute" mode via an `on_change` hook, so every change is
   recorded durably before it's applied or relayed.
 - Presence cleanup on disconnect, and idle-document eviction.
-- Two backends: `sync_backend :memory` (default, classic ActionCable) and
-  `sync_backend :store` (stateless, AnyCable-ready, multi-process).
+- Store-backed ActionCable delivery for AnyCable and multi-process use.
 - Hardening against bad input: malformed or multi-message frames are dropped
   before processing or relay, and native panics are contained at the FFI
   boundary.
 - 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.beta4...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

data/README.md

@@ -9,26 +9,27 @@ documents.
 
 ```ruby
 class DocumentChannel < ApplicationCable::Channel
-  include YrbLite::Sync
+  include YrbLite::ActionCable::Sync
 
   def subscribed   = sync_for(params[:id])
   def receive(data) = sync_receive(data)
-  def unsubscribed = sync_clear_presence
+  def unsubscribed = sync_unsubscribed(params[:id])
 end
 ```
 
-On the browser, use the [`@y-rb/actioncable`](https://www.npmjs.com/package/@y-rb/actioncable)
-provider as-is. Tiptap, ProseMirror, and BlockNote all sync through it.
+On the browser, use the `yrb-lite-client` `ActionCableProvider`. Tiptap,
+ProseMirror, and BlockNote all sync through the `Y.Doc` you pass in and the
+provider's Awareness instance, unless you supply your own.
 
 ## What you get
 
-- Thread-safe `Doc` and `Awareness`. You can share them across Puma threads,
-  and the GVL is released while yrs does the actual work.
+- Thread-safe Ruby wrappers for `Doc` and `Awareness`. You can share them
+  across Puma threads; native CRDT work runs with the GVL released.
 - The y-websocket protocol (document sync plus awareness/presence) as a
   one-include ActionCable concern.
-- A store-backed mode for AnyCable and multi-process deployments.
-- An optional authoritative mode that records each change durably before it
-  goes out to anyone.
+- Store-backed ActionCable/AnyCable delivery for multi-process deployments.
+- Authoritative record-before-distribute semantics: each document change is
+  recorded durably before it goes out to anyone.
 
 What it doesn't do: auth, read-only connections, rate limiting, webhooks,
 metrics. Hocuspocus ships extensions for those; here you'd build them with
@@ -36,21 +37,26 @@ Rails.
 
 ## Testing
 
-Ruby and Rust unit tests cover the core, and an end-to-end suite runs the real
-stack: it fuzzes the protocol, throws garbage and chaos at the server, kills the
-server mid-write to check crash recovery, and drives real browsers under load.
-The benchmark numbers below are from a single laptop. Issues and PRs are
-welcome.
+Ruby and Rust unit tests cover the core. CI also runs the npm client tests and a
+Rails demo smoke slice against the real ActionCable stack. The demo includes
+heavier local suites for hostile input, crash recovery, multi-browser editing,
+AnyCable, and load testing. The benchmark note below is from a single laptop.
+Issues and PRs are welcome.
 
 ## Install
 
 ```ruby
+# Core CRDT + protocol primitives:
 gem "yrb-lite"
+
+# For the Rails/ActionCable server concern (YrbLite::ActionCable::Sync):
+gem "yrb-lite-actioncable"
 ```
 
-Requires Ruby 3.4 or newer. Precompiled gems ship for Linux and macOS on Ruby
-3.4 and 4.0, so installing there needs no Rust. Other platforms (and any other
-Ruby version) build from source, which needs [Rust](https://rustup.rs).
+Requires Ruby 3.4 or newer. The release workflow builds precompiled gems for
+Ruby 3.4 and 4.0 across the supported Ruby platforms, with native smoke tests
+on Linux x86_64 and macOS arm64. Installing from a matching platform gem needs
+no Rust; a source build needs [Rust](https://rustup.rs).
 
 To work on the gem itself:
 
@@ -128,44 +134,43 @@ send_to_peer(response) unless response.empty?
 
 ### ActionCable Integration
 
-`YrbLite::Sync` is a channel concern that implements the full y-websocket
-protocol (document sync + awareness/presence) over ActionCable:
+`YrbLite::ActionCable::Sync` (from the `yrb-lite-actioncable` gem) is a channel
+concern that implements the full y-websocket protocol (document sync +
+awareness/presence) over ActionCable:
 
 ```ruby
 # app/channels/document_channel.rb
 class DocumentChannel < ApplicationCable::Channel
-  include YrbLite::Sync
+  include YrbLite::ActionCable::Sync
 
-  # Optional persistence:
-  # on_load { |key| Document.find_by(key: key)&.content }
-  # on_save { |key, update| Document.find_by(key: key)&.update!(content: update) }
+  on_load { |key| MyStore.load(key) }                 # source of truth
+  on_change { |key, update| MyStore.append(key, update) } # durable record
 
   def subscribed
     sync_for params[:id]
   end
 
   def receive(data)
-    sync_receive(data)
+    sync_receive(data, params[:id])
   end
 
   def unsubscribed
-    sync_clear_presence
+    sync_unsubscribed(params[:id])
   end
 end
 ```
 
-One `YrbLite::Awareness` is shared per document key. Creating it is
-mutex-serialized; after that everything runs lock-free on the thread-safe
-native types. The concern answers SyncStep1 directly, relays document and
-awareness changes to the other subscribers (not back to the sender), and calls
-`on_save` after any message that changed the document.
+The concern is store-backed. A handshake is answered from `on_load`; document
+changes are checked against that durable state, recorded through `on_change`,
+then broadcast. Nothing authoritative is kept in ActionCable process memory, so
+AnyCable RPC workers, Puma workers, and separate dynos can all handle messages
+for the same document as long as they share the same store and cable adapter.
 
-`sync_unsubscribed` clears the connection's presence, so a closed tab doesn't
-leave a stale cursor hanging until the client-side timeout. It also unloads the
-document from memory once the last subscriber disconnects, which keeps the
-process from holding onto every document it ever served. That unload only
-happens when `on_load` is set and the document can be reloaded later; without
-it, the in-memory copy is the only one and stays put.
+`on_load` and `on_change` are required. If either is missing, the channel fails
+closed before it can acknowledge or broadcast edits. Presence is ephemeral:
+awareness frames are relayed, and `yrb-lite-client` sends a best-effort
+presence-removal frame on disconnect/pagehide, with the client-side awareness
+timeout as the fallback for abrupt disconnects.
 
 Incoming frames are validated as a single well-formed protocol message before
 anything processes or relays them. Malformed, truncated, multi-message,
@@ -182,37 +187,19 @@ Broadcasts cross processes through the Action Cable adapter, so it needs to be a
 real one (`redis` or `solid_cable`, not `async`). With that in place, a change
 on one process reaches clients on all of them.
 
-Each process also keeps its own copy of the document and applies broadcasts from
-the others. The merge is an ordinary CRDT apply, idempotent and
-order-independent, which keeps server reads and new-client handshakes current on
-every process. Each broadcast carries a per-process id (`Sync.process_id`) that
-tells a process to skip its own.
-
-A cold process (no copy yet) rebuilds from the durable store through `on_load`.
-In authoritative mode the store is always current, since changes are recorded
-before they go out. Record-before-distribute therefore holds across processes:
-whichever process receives a change records it to the shared store before
-anyone, anywhere, sees it.
+Every process rebuilds document state from the durable store through `on_load`.
+Because changes are recorded before broadcast, record-before-distribute holds
+across processes: whichever process receives a change records it to the shared
+store before anyone, anywhere, sees it.
 
 `bun multiprocess.mjs` in the demo runs clients across two processes and checks
-the lot: convergence, fresh copies on both, presence across processes, and one
-shared log.
-
-##### AnyCable (`sync_backend :store`)
+convergence, fresh reads on both, presence across processes, and one shared log.
 
-The default backend keeps that warm in-memory copy and relies on a `stream_from`
-block running in Ruby for each broadcast. AnyCable breaks both assumptions.
-anycable-go delivers broadcasts outside Ruby, so the block never runs. Each RPC
-gets a fresh channel instance, which means ivars set in `subscribed` are gone by
-`receive`. And there's no fixed worker-to-document mapping to lean on.
-
-`sync_backend :store` is the path for that: stateless per message, no warm
-copy.
+##### AnyCable
 
 ```ruby
 class DocumentChannel < ApplicationCable::Channel
-  include YrbLite::Sync
-  sync_backend :store
+  include YrbLite::ActionCable::Sync
 
   on_load  { |key| MyStore.load(key) }          # required: source of truth
   on_change { |key, update| MyStore.append(key, update) }  # required: record
@@ -227,6 +214,10 @@ end
 - A handshake (SyncStep1) is answered from the store. Changes are recorded, then
   broadcast. Nothing is held in Ruby between calls, so any worker can handle any
   message.
+- Document frames use the normal server path. Awareness/presence uses a
+  separate awareness stream with AnyCable `whisper: true`, so cursor traffic can
+  take the low-latency client-to-client path without bypassing document
+  durability.
 - Pass `params[:id]` into `sync_receive`/`sync_unsubscribed` so the document key
   survives AnyCable's per-command instances.
 - The sender gets its own updates echoed back (no Ruby callback to filter them).
@@ -234,34 +225,31 @@ end
 
 The demo checks this against a real anycable-go + RPC server
 (`frontend/anycable_probe.mjs`, `anycable_concurrent.mjs`): liveness, the
-`@y-rb/actioncable` provider, cross-process reads, and concurrent convergence.
+yrb-lite client provider, cross-process reads, and concurrent convergence.
 
 The wire format is the standard y-protocols binary messages, base64-encoded in
-the ActionCable envelope. The server accepts the `@y-rb/actioncable` provider's
-`{ "update" => ... }` envelope (and its own `{ "m" => ... }`) and sends one
-message per frame, so the off-the-shelf provider works with no custom client
-code:
+the ActionCable envelope. yrb-lite uses one canonical document envelope,
+`{ "update" => ... }`, and sends one message per frame.
 
 ```js
-import { createConsumer } from "@rails/actioncable"
-import { WebsocketProvider } from "@y-rb/actioncable"
+import { createConsumer } from "@anycable/web"
+import { ActionCableProvider } from "yrb-lite-client"
 
-const provider = new WebsocketProvider(ydoc, createConsumer(), "DocumentChannel", { id: docId })
+const provider = new ActionCableProvider(ydoc, createConsumer(), "DocumentChannel", { id: docId })
+provider.connect()
 ```
 
 [`examples/actioncable-demo`](examples/actioncable-demo) is a full Rails + Tiptap
-app using that provider, with end-to-end tests.
+app using the yrb-lite provider, with end-to-end tests.
 
-#### Authoritative audit mode (record before distribute)
+#### Record Before Distribute
 
-By default a change is applied and broadcast immediately (the fast path). If you
-need to durably record every change before anyone else sees it, whether for
-auditing or to guarantee nothing is distributed until it's stored, register an
-`on_change` recorder:
+Every document change is durably recorded before anyone else sees it. Register
+an `on_change` recorder:
 
 ```ruby
 class DocumentChannel < ApplicationCable::Channel
-  include YrbLite::Sync
+  include YrbLite::ActionCable::Sync
 
   on_change do |key, update|
     # Synchronous, durable write. `update` is the exact CRDT delta.
@@ -269,78 +257,43 @@ class DocumentChannel < ApplicationCable::Channel
   end
 
   def subscribed = sync_for(params[:id])
-  def receive(data) = sync_receive(data)
-  def unsubscribed = sync_clear_presence
+  def receive(data) = sync_receive(data, params[:id])
+  def unsubscribed = sync_unsubscribed(params[:id])
 end
 ```
 
 With `on_change` registered, a change is recorded before it goes anywhere. The
 recorder writes the raw CRDT delta synchronously; only then is the change
-applied to the shared document and broadcast. The whole sequence runs under a
-per-document lock, so every change to a document is recorded in the same order
-it's applied. That's what makes the log authoritative. Replay the deltas onto a
-fresh `Y.Doc` and you get the document back exactly.
+broadcast. Replay the deltas onto a fresh `Y.Doc` and you get the document back
+exactly.
 
 If the recorder raises (say the store is down), the change is rejected: not
 applied, not sent to anyone. The cost is a synchronous durable write per change,
 which serializes that document's writes. Other documents use other locks and run
 in parallel.
 
-`on_change` and `on_save` are separate. `on_save` snapshots the whole document
-when it gets a chance; `on_change` is the per-change log. The demo's `AUDIT=1`
-mode (in [`examples/actioncable-demo`](examples/actioncable-demo)) wires
-`on_change` to an fsync'd append-only log and checks, end to end, that the log
-alone rebuilds the document.
+The demo wires `on_change` to a durable Postgres-backed log by default, with an
+fsync'd file log available via `STORE_KIND=file`, and checks end to end that the
+log alone rebuilds the document.
 
 #### Reliable delivery (acks)
 
-The y-websocket protocol is fire-and-forget. If a client's update is lost in
-transit (a flaky socket, a send that never lands) and the client makes no
-further edits, the server stays idle and never asks anyone to resync, so that
-edit is gone -- even though the client believes it was saved. CRDTs converge the
-state everyone *has*; they don't recover an update that never arrived.
-
-yrb-lite closes that gap with an opt-in, client-driven acknowledgement. If an
-incoming 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 the client
-knows it hasn't landed yet.
+yrb-lite document delivery is ack-tracked. Browser 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; the server sends a
+resync request, and the client keeps the update queued until it lands.
 
 ```
-client -> server   { "m": "<base64 update>", "id": 42 }
+client -> server   { "update": "<base64 update>", "id": 42 }
 server -> client    { "ack": 42 }     # update accepted; safe to forget
 ```
 
-That's the whole server side. A reliable client tags each outgoing update with
-an incrementing id, keeps it in a pending buffer, and retransmits on a timer (and
-on reconnect) until the matching ack returns. Because CRDT apply is idempotent, a
-resend that already landed is a harmless no-op that just re-acks. An update lost
-in transit is recovered by the client's own retransmit -- no reconnect required,
-and no dependence on a later edit happening to trigger a resync.
-
-This is entirely **self-gating**: stock clients send no `"id"`, so they never get
-acks and behave exactly as before. Only a client that opts in by tagging its
-frames participates.
-
-Two client examples ship in the demo:
-
-- [`frontend/reliable.mjs`](examples/actioncable-demo/frontend/reliable.mjs) — a
-  minimal reference client showing the raw mechanism (tag with an id, retain,
-  retransmit on a timer, drain on ack), with an end-to-end test that loses an
-  update mid-flight and recovers it purely by retransmit.
-- [`frontend/provider/reliable_actioncable_provider.mjs`](examples/actioncable-demo/frontend/provider/reliable_actioncable_provider.mjs)
-  — the standard `@y-rb/actioncable` `WebsocketProvider`, vendored and augmented
-  for production use. It's a drop-in replacement that speaks the same protocol
-  and envelope, and adds reliability with **sync-since-last-ack** framing: rather
-  than retransmitting updates one by one, it keeps the unacknowledged local
-  updates in a queue and sends their *merge* as a single causally-complete delta,
-  with the id being the highest sequence in the batch (so one `{ ack: id }`
-  cumulatively confirms everything up to it). Because the whole unacked tail goes
-  as one self-contained delta, the server never sees an internal gap and never
-  has to round-trip a resync for a lost middle update — the next edit, or the
-  next timer tick, carries it. Awareness stays fire-and-forget; against a server
-  that doesn't implement acks it warns once and falls back to plain delivery; and
-  `reliable: false` opts out entirely. The demo's editor uses this provider.
+`yrb-lite-client`'s `ActionCableProvider` handles this automatically. It keeps
+the unacknowledged local document tail in a queue and sends the merged tail as a
+single causally-complete delta. The id is the highest sequence in the batch, so
+one `{ ack: id }` cumulatively confirms everything up to it. Because CRDT apply
+is idempotent, a resend that already landed is a harmless no-op that just
+re-acks. Awareness stays ephemeral and is not acked.
 
 ### User Awareness/Presence
 
@@ -376,24 +329,24 @@ message = awareness.encode_update(update_bytes)
 
 ## Thread Safety
 
-Unlike the official `y-rb` gem, yrb-lite is safe to share across Ruby threads. A
-`Doc` or `Awareness` can be used concurrently from Puma workers, ActionCable
-connection threads, or background jobs without external locking.
+`Doc` and `Awareness` are safe to share across Ruby threads. A `Doc` or
+`Awareness` can be used concurrently from Puma workers, ActionCable connection
+threads, or background jobs without external locking.
 
 That comes from how the underlying types work, not from locking on top:
 
 - `yrs::Doc` is `Send + Sync`. Every operation takes the document's internal
   RwLock with blocking semantics (`read_blocking`/`write_blocking`), so
   concurrent access serializes instead of erroring or corrupting state.
-- `yrs::sync::Awareness` is built for multi-threaded servers: client states
-  live in a `DashMap` and the whole API is `&self`.
-- The extension adds no interior-mutability tricks. There's no `RefCell`, where
-  a re-entrant borrow would panic and take the Ruby process down with it.
-  Each native method opens and closes its transaction in one call, so no lock
-  or borrow outlives a call and there's nothing to deadlock on.
-- A `Send + Sync` static assertion for both wrapped types lives in `lib.rs`. If
-  a yrs upgrade regressed this, the gem would fail to compile instead of quietly
-  turning thread-unsafe.
+- `yrs::sync::Awareness` is `Send` but not `Sync` in the current yrs version,
+  so the Ruby wrapper stores it in a `Mutex`. The mutex is always acquired
+  inside the no-GVL native section and released before Ruby runs again.
+- The extension uses no `RefCell`-style runtime borrows that could panic under
+  re-entrancy. Each native method opens and closes its transaction or mutex
+  guard inside one call.
+- Static assertions in `lib.rs` prove `Doc` and `Mutex<Awareness>` are
+  `Send + Sync`. If a yrs upgrade regressed either wrapper's thread-safety, the
+  gem would fail to compile instead of quietly turning thread-unsafe.
 
 `test/thread_safety_test.rb` runs shared docs, the full sync handshake, fan-in
 sync, and awareness state across 8 threads at once, and checks the interleaving
@@ -414,11 +367,12 @@ A slow operation also can't stall the VM. A thread applying a large update holds
 the doc's write lock without holding the GVL, so other Ruby threads keep running
 instead of queuing behind it.
 
-Each method has the same shape: copy the Ruby byte string, drop the GVL, do the
-yrs work (taking and releasing the doc lock entirely inside the closure), take
-the GVL back, then build Ruby objects. No Ruby API is touched without the GVL,
-and the doc lock is never held across a GVL boundary, so the lock order can't
-deadlock. Panics in native code are caught and re-raised as Ruby exceptions.
+Each method has the same shape: copy Ruby byte strings first, drop the GVL, do
+the yrs work while taking and releasing native locks entirely inside the
+closure, take the GVL back, then build Ruby objects. No Ruby API is touched
+without the GVL, and no native lock is held while reacquiring it, so the lock
+order can't deadlock. Panics in native code are caught and re-raised as Ruby
+exceptions.
 
 ## Message Type Constants
 

data/lib/yrb_lite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YrbLite
-  VERSION = "0.1.0.beta4"
+  VERSION = "0.1.0.beta6"
 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,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta4
+  version: 0.1.0.beta6
 platform: aarch64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-06-22 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: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -66,10 +52,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: []
@@ -83,7 +69,6 @@ files:
 - lib/yrb_lite.rb
 - lib/yrb_lite/3.4/yrb_lite.so
 - lib/yrb_lite/4.0/yrb_lite.so
-- lib/yrb_lite/sync.rb
 - lib/yrb_lite/version.rb
 homepage: https://github.com/jpcamara/yrb-lite
 licenses:
@@ -114,6 +99,6 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key: 
 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,580 +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) }
-  #
-  #     # on_change blocks run in the channel instance's context, so instance
-  #     # methods (current_user, params, ...) are available without plumbing:
-  #     on_change { |key, update| Document.record!(key, update, by: current_user) }
-  #
-  #     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.
-      #
-      # A block recorder runs in the *channel instance's* context, so it can
-      # call the channel's own methods (current_user, params, a per-connection
-      # Current.* accessor) directly, with no thread-local plumbing. (A non-Proc
-      # callable is invoked with #call instead, since it carries its own
-      # context.) on_change always fires from within sync_receive, unlike
-      # on_load/on_save, which can run context-free in the shared registry.
-      #
-      # 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)
-
-        sync_record_change(recorder, 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
-
-        if (recorder = self.class.on_change)
-          sync_record_change(recorder, update) # record before relay
-        end
-        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
-
-    # Invoke the on_change recorder. A block/proc runs in this channel instance's
-    # context (instance_exec) so it can reach the channel's own methods; a
-    # non-Proc callable is invoked with #call, since it carries its own context.
-    def sync_record_change(recorder, update)
-      args = [@sync_key, update]
-      recorder.is_a?(Proc) ? instance_exec(*args, &recorder) : recorder.call(*args)
-    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