yrb-lite 0.1.0.beta7-aarch64-mingw-ucrt → 0.1.0.beta9-aarch64-mingw-ucrt

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf634b759425b1eac44a737a4eeee7de4b5339405ee1994f504882d33745003
-  data.tar.gz: c1d5756f78a505d2a2b12b5df4a32c7e2eaf3688859baa67feab3138236aa271
+  metadata.gz: 5c65659e7f4abd5578f7775314d9410ec41656c2226b6291d65302d56c0cccf6
+  data.tar.gz: f848f63fcf096be692b100fce8080609a1500c97a47f7d73e171cbf94c89a41f
 SHA512:
-  metadata.gz: a91dfeafd0dd74edb5cc8de4dcab10f39a92c7487140b10b8cd2900298a00c9c8de0e762be77546275be613ccb8db947d63776e486032b906c3cc44984ebfc1c
-  data.tar.gz: ba620b483797e49021b42447ae3cb53ba9b5f13e3bf3b5607219a7c7ad841e4e559859198224570f66e29f00100c6db71a0a718a3944879e49d69bf09599411c
+  metadata.gz: 7577c5170055d9a41d535ee694adfcab716432541d836fa3a7066eda6798191db9a5e41835c54a772545e394977de2cec4bbfc7831be1400e2cb62a4a58f53cd
+  data.tar.gz: a8b1b143dc96f97771bb817b1ce8687b338d7533fdf353b2cb373b54de07d5f3a4c9572e2a32e06b5a7a1f6d01d4e0e5e132521e2b68c7793963fde4c543141b

data/CHANGELOG.md

@@ -5,135 +5,3 @@ All notable changes to this project are documented here. The format is based on
 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
-
-- `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. 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
-
-- Upgraded the bundled `yrs` (y-crdt) from 0.21 to 0.27.2. No change to the
-  `YrbLite::Doc`, `YrbLite::Awareness`, or `YrbLite::Sync` public API; existing
-  code and the wire protocol are unaffected.
-- Thread-safety is preserved across the upgrade. yrs 0.27 dropped `Awareness`'s
-  internal locking (its mutating methods now take `&mut self`, and `Awareness`
-  is no longer `Sync`), so `YrbLite::Awareness` now serializes access through an
-  internal `Mutex`. The lock is taken only while the GVL is released and is
-  never held across the GVL boundary, so concurrent access from multiple Ruby
-  threads stays safe and deadlock-free, and document reads still run in parallel
-  (they operate on a cheaply-cloned, `Arc`-backed `Doc` handle, not under the
-  presence lock).
-
-### Build
-
-- Building the gem from source now requires **Rust 1.94 or newer** (yrs 0.27.2
-  uses `let`-chains). The precompiled platform gems are unaffected -- they need
-  no Rust toolchain to install.
-
-## [0.1.0.beta2] - 2026-06-16
-
-### Added
-
-- 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
-  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. 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
-
-- Causal-gap protection. The authoritative, fast, and store paths now reject a
-  document update that isn't causally ready -- one whose dependencies are
-  missing because an earlier update was lost in transit or its durable record
-  failed -- and ask the client to resync, instead of recording or relaying an
-  un-integrable update that would leave the log permanently pending. Adds native
-  `Doc#update_ready?`/`#pending?` (cheap, read-only checks) used to gate the
-  record-before-distribute path.
-
-## [0.1.0.beta1]
-
-### Added
-
-- Thread-safe `YrbLite::Doc` and `YrbLite::Awareness` over `yrs` (magnus/rb-sys
-  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).
-- 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.
-- 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.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/README.md

@@ -19,12 +19,12 @@ end
 
 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.
+provider's Awareness instance.
 
 ## What you get
 
-- Thread-safe Ruby wrappers for `Doc` and `Awareness`. You can share them
-  across Puma threads; native CRDT work runs with the GVL released.
+- A thread-safe Ruby `Doc` you can share 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.
 - Store-backed ActionCable/AnyCable delivery for multi-process deployments.
@@ -86,11 +86,7 @@ require "yrb_lite"
 
 # Create docs
 doc = YrbLite::Doc.new        # random client ID
-doc = YrbLite::Doc.new(12345) # specific client ID
-
-# Get document info
-doc.client_id  # => unique client identifier
-doc.guid       # => document GUID
+doc = YrbLite::Doc.new(12345) # specific client ID (used for CRDT identity)
 
 # Encoding
 doc.encode_state_vector           # => current state vector
@@ -100,36 +96,23 @@ doc.encode_state_as_update(sv)    # => update diff against state vector
 # Applying updates
 doc.apply_update(update_bytes)    # apply raw V1 update
 
-# Sync protocol messages
-doc.sync_step1                    # => SyncStep1 message (contains state vector)
-doc.sync_step2(state_vector)      # => SyncStep2 message (contains update)
-doc.handle_sync_message(data)     # => [msg_type, sync_type, response]
-doc.encode_update_message(update) # => wrap update as sync Update message
+# Sync protocol
+doc.sync_step1                    # => SyncStep1 message (this doc's state vector)
+doc.handle_sync_message(data)     # => [msg_type, sync_type, response]; answers a
+                                  #    peer's SyncStep1 with a SyncStep2
 ```
 
-### Awareness (Document + Presence)
-
-```ruby
-# Create awareness instances (each contains a Doc)
-awareness = YrbLite::Awareness.new        # random client ID
-awareness = YrbLite::Awareness.new(12345) # specific client ID
-
-# Get document info
-awareness.client_id  # => unique client identifier
-awareness.guid       # => document GUID
-```
+### Protocol codec (module functions)
 
-### Handling Sync Messages
+Classifying and unwrapping wire frames is stateless, so it's exposed as
+`YrbLite` module functions rather than a class. The server never holds presence
+or document state to route a frame — presence lives in the browser clients, and
+the server only relays awareness frames opaquely.
 
 ```ruby
-# When connection opens, send initial sync messages
-initial_message = awareness.start
-# Send initial_message to peer via WebSocket
-
-# When receiving messages from peer
-response = awareness.handle(incoming_data)
-# Send response back to peer if not empty
-send_to_peer(response) unless response.empty?
+YrbLite.message_kind(frame)         # => 0 drop / 1 step1 / 2 update / 3 awareness / 4 query
+YrbLite.update_from_message(frame)  # => the document delta carried by a frame, or nil
+YrbLite.wrap_update(update_bytes)   # => wrap a raw doc update as a sync Update frame
 ```
 
 ### ActionCable Integration
@@ -178,6 +161,34 @@ oversized, or unknown frames are dropped. A bad frame can't crash the process: a
 Rust panic is caught at the FFI boundary and re-raised as a Ruby exception. And
 no single client can relay garbage that breaks the others in a room.
 
+#### Delivery guarantees
+
+The contract is the same at every scale — one process, or hundreds across many
+servers:
+
+- **The document always converges.** CRDT updates are commutative and
+  idempotent, so out-of-order, duplicate, or concurrent delivery all converge to
+  the same correct document. This needs no coordination and holds everywhere.
+- **The durable log never goes gappy.** An update is recorded only once its
+  causal dependencies are already in the store (checked against `on_load`); a
+  causally-incomplete update triggers a resync instead, so the log always
+  rebuilds cleanly.
+- **`on_change` is at-least-once, and the durable guarantee is that replaying the
+  log reconstructs the document.** Every change is recorded before it's acked or
+  broadcast (record-before-distribute). Entry count is not 1:1 with edits: a
+  best-effort check skips most lost-ack retries but isn't cross-process exact (a
+  retry on another process can record the same update twice), and a resync can
+  coalesce a client's un-acked tail into a single record. So **make `on_change`
+  idempotent** if duplicate side effects would matter (a webhook, a counter) — a
+  raw append-only delta log is naturally fine, since it replays to the same
+  document either way.
+
+There is deliberately no in-gem cross-process lock. One that only spanned a
+single process would give exactly-once at small scale and silently degrade as
+you scale out, so the guarantee is uniform instead. If you need exactly-once
+*side effects*, enforce it in your store (a unique key on the update) or with
+your own distributed lock — the gem stays storage-agnostic and assumes neither.
+
 #### Multi-process deployments
 
 Most Rails apps run several processes (Puma workers, multiple dynos), and any of
@@ -295,43 +306,15 @@ 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
-
-```ruby
-# Set local user state (cursor position, name, etc.)
-awareness.set_local_state('{"user": {"name": "Alice", "color": "#ff0000"}}')
-
-# Get local state
-awareness.local_state  # => '{"user": {"name": "Alice", "color": "#ff0000"}}'
-
-# Clear local state (e.g., when disconnecting)
-awareness.clear_local_state
-
-# Encode awareness update for broadcasting
-update = awareness.encode_awareness_update
-```
-
-### Low-Level Access
-
-```ruby
-# Get state vector for manual sync
-sv = awareness.encode_state_vector
-
-# Get update diffed against a state vector
-update = awareness.encode_state_as_update(remote_state_vector)
-
-# Apply raw update to the document
-awareness.apply_update(update_bytes)
-
-# Wrap raw update data in a sync message
-message = awareness.encode_update(update_bytes)
-```
+Presence (cursors, selections) is owned by the browser clients — the server
+never sets or holds presence state, it only relays awareness frames opaquely.
+See `yrb-lite-client` for the client-side awareness API.
 
 ## Thread Safety
 
-`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.
+A `Doc` is safe to share across Ruby threads — 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:
 

data/lib/yrb_lite/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta7
+  version: 0.1.0.beta9
 platform: aarch64-mingw-ucrt
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest