yrby 0.2.1-x86_64-linux → 0.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff22dc8ae310daac142d0fe476d8659cfedff1b1f5cb88ccc9c46688e03fbe27
-  data.tar.gz: e3ff8171d93f3785b1d349173b7b7ebf12e1f762ea172bf48c4f9c7c40a0255f
+  metadata.gz: 1c679e136a706fb345dedc22c7b3e9da97919a16c827dc67fe0a5e06ab0ed414
+  data.tar.gz: df08be53339b8a833474f3ecd8234838e1aad5dd178fd1ae419d44adaf29637c
 SHA512:
-  metadata.gz: 4f3c2c3291521f47218ed70e4f2d9205efe7143312588d755079e87bbee32ac60e4c0fc45f7156453cc54c695d702ae53e91be8904cd6d1436551b8d10cddd31
-  data.tar.gz: 6796d3d50aceac6f5924be12d9cb9b1beb9ef8b3c80a75745d88f0b04dd930e1af9abb3119bd495b358af08a5703e58a45a368af9cea3c460b36bd45c9cc0054
+  metadata.gz: '0903a87fcf089ec17d8aafbe0feb39fdd05b1068ae85540167434c818b2542a8b4f252115fd79f3f3d01a1ac63ee1a0a54eabd28172600538154f195e330cb04'
+  data.tar.gz: 4f349abd4f2f62f662d8c988489a9a5b9b79892e5f78ce5790a4e0638217e4262b3c69d39d390c2f4d34bcf1b5a9ee981520ad178cd7b81c820ff08e7771fdc6

data/CHANGELOG.md

@@ -6,6 +6,72 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-01
+
+### Fixed
+
+- **Sync no longer serves un-integrable pending structs.** When a doc holds a
+  *pending* struct (a gappy update whose causally-prior update is missing — e.g.
+  legacy data recorded before the `update_ready?` gate existed), its integrated
+  state vector is empty but `encode_state_as_update` merges the pending bytes back
+  in. Answering a peer's `SyncStep1` with that state handed the peer content it
+  couldn't integrate, so it parked the same pending forever and the empty-SV /
+  non-empty-content mismatch drove endless resync traffic (observed as a browser
+  re-sending frames several times a second). `handle_sync_message` now answers
+  `SyncStep1` with **integrated-only** state, so a server never serves a struct it
+  can't integrate itself. Neutralizes existing poisoned server state on deploy —
+  no migration needed. The server's own pending is untouched and still heals if
+  the missing dependency later arrives (only then does the content become
+  visible in sync). Live delta relay (`Update` frames) is unchanged.
+
+### Added
+
+- `Doc#pending?` — true if the doc holds un-integrable pending structs or a
+  pending delete set (content waiting on a missing causally-prior update).
+- `Doc#compacted_state_update` — like `encode_state_as_update` (full state) but
+  **gap-free**: excludes pending structs/delete set. Use it when persisting or
+  serving state other peers will apply. Non-destructive — the doc keeps its
+  pending (so it can still heal), and `encode_state_as_update` stays lossless for
+  raw-update recovery.
+
+## [0.2.3] - 2026-07-01
+
+### Fixed
+
+- `Doc#update_advances?` is now exact for **delete-bearing** updates, so an
+  already-applied pure-delete retry no longer reports as advancing. Previously any
+  update carrying a delete set returned `true` (record it) because deletes don't
+  move the state vector, so the cheap state-vector probe couldn't prove a
+  duplicate. A lost-ack retry of a deletion the server had already integrated was
+  therefore re-recorded and re-broadcast every time. For delete-bearing updates we
+  now compare the full encoded document state (which includes the delete set)
+  before vs. after a trial apply on an isolated probe: a genuinely new deletion
+  changes it (`true`); an already-applied retry re-encodes identically (`false`).
+  Insert/format-only updates keep the cheaper state-vector path, so only
+  delete-bearing frames — a minority — pay for the exact comparison. The exactly-
+  once guarantee is unchanged in the safe direction: a real deletion is never
+  dropped.
+
+  This lets `yrby-actioncable` (and any caller gating `on_change` on
+  `update_advances?`) settle a duplicate pure-delete frame as `:applied` — acked,
+  but not stored or relayed — so apps no longer need an app-level
+  encode-and-compare guard around their durable writes.
+
+## [0.2.2] - 2026-06-30
+
+### Fixed
+
+- `Doc#read_xml` now recovers text from **nested** Lexical/Lexxy blocks. Lexical
+  embeds child blocks (list items, table cells, nested lists) as `Y.XmlText`
+  embeds that `get_string` silently drops, so lists and tables previously came
+  back empty. `read_xml` now walks the embeds: text runs build a line, inline
+  children (links) join it, and nested block children flush and recurse — so a
+  document with headings, formatted text, links, bullet/numbered/check/nested
+  lists, blockquotes, code blocks and tables extracts every piece of text.
+  Lexical decorator elements (horizontal rule, image) are skipped instead of
+  emitting their `<UNDEFINED …>` serialization. ProseMirror handling is
+  unchanged.
+
 ## [0.2.1] - 2026-06-29
 
 ### Changed
@@ -15,15 +81,9 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.2.0] - 2026-06-28
 
-First release under the **`yrby`** name (the project was previously developed
-as `yrb-lite`). The public Ruby interface is the top-level module **`Y`** —
-mirroring the `y-rb` gem's `Y::Doc` interface.
-
-### Changed
-- **Renamed `yrb-lite` → `yrby`.** Module `YrbLite` → top-level `Y`
-  (`Y::Doc`, `Y::Error`, `Y::VERSION`). Require path `require "yrb_lite"` →
-  `require "y"`. (The native extension crate shipped as `y_ruby` in 0.2.0; see
-  0.2.1 for its rename to `yrby`.)
+First release. The public Ruby interface is the top-level module **`Y`**
+(`Y::Doc`, `Y::Error`, `Y::VERSION`), loaded with `require "y"` — mirroring the
+`y-rb` gem's `Y::Doc` interface.
 
 ### Added
 - Native `Doc#read_text` and `Doc#read_map` readers — reconstruct plain text and

data/README.md

@@ -41,23 +41,25 @@ npm install yrby-client
   one-include ActionCable concern.
 - Authoritative record-before-distribute semantics: each document change can be
   recorded durably before it goes out to anyone.
-- 
+- Optional server-side reads: `Doc#read_text` and `Doc#read_map` reconstruct a
+  document's contents in Ruby - no Node process - for search, exports, validation,
+  or server-side rendering.
 
-## Why "lite"
+## Scope
 
-The "lite" is the size of the surface. `yrby` binds just the part of `y-crdt` you
-need to *sync and persist* collaborative documents - a `Doc`, awareness, and the
-y-websocket protocol primitives. The Ruby side treats a document as opaque CRDT
-state: it applies updates, answers sync handshakes, and records deltas, but never
-reaches in to read or edit the contents. The browser editor owns the document's
-shape.
+`yrby` binds just the part of `y-crdt` you need to *sync and persist* collaborative
+documents - a `Doc`, awareness, and the y-websocket protocol primitives. By default
+the Ruby side treats a document as opaque CRDT state: it applies updates, answers
+sync handshakes, and records deltas without reaching into the contents - the browser
+editor owns the document's shape. When you do need to look inside, `Doc#read_text`
+and `Doc#read_map` reconstruct it server-side, in Ruby.
 
-## What isn't "lite"
+## Durability and delivery
 
-The surface area may be "lite", but a core focus is on durability, resiliency, delivery
+The surface is intentionally small, but the focus is durability, resiliency, delivery
 guarantees, correctness, and thread safety.
 
-Towards that goal, `yrby` adds capabilities that may even stand out in the Yjs ecosystem:
+Towards that goal, `yrby` adds capabilities that stand out even in the Yjs ecosystem:
 
 - Built-in update acknowledgement: the `ActionCableProvider` in `yrby-client` will continue to
   send updates until an ack is received from the server. [`yrby-actioncable`](https://rubygems.org/gems/yrby-actioncable)
@@ -140,18 +142,39 @@ doc = Y::Doc.new(12345) # specific client ID (used for CRDT identity)
 
 # Encoding
 doc.encode_state_vector           # => current state vector
-doc.encode_state_as_update        # => full update
+doc.encode_state_as_update        # => full update (lossless: keeps pending)
 doc.encode_state_as_update(sv)    # => update diff against state vector
+doc.compacted_state_update        # => full update, gap-free (excludes pending)
 
 # Applying updates
 doc.apply_update(update_bytes)    # apply raw V1 update
+doc.pending?                      # => true if holding un-integrable pending structs
 
 # 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
+                                  #    peer's SyncStep1 with an integrated-only
+                                  #    SyncStep2 (never serves pending structs)
 ```
 
+### Pending structs and gap-free state
+
+If a doc applies an update whose causally-prior update is missing (a "gappy"
+update), yrs parks it as a **pending** struct: the integrated state vector stays
+empty, but the pending block is held as a recovery buffer and heals if the
+missing dependency later arrives. `Doc#pending?` reports this.
+
+Pending structs are *not* document state, so they must not cross the sync
+boundary — a peer that receives one can't integrate it and gets stuck. Two
+guarantees keep serving safe:
+
+- `handle_sync_message` answers `SyncStep1` with **integrated-only** state, so a
+  server never serves a struct it can't integrate itself (this is automatic).
+- `Doc#compacted_state_update` gives you the same gap-free full-state update for
+  when you persist or hand off state yourself. It's non-destructive (the doc
+  keeps its pending), while `encode_state_as_update` stays lossless so you can
+  still preserve the raw pending bytes for recovery.
+
 ### Protocol codec (module functions)
 
 Classifying and unwrapping wire frames is stateless, so it's exposed as

data/lib/y/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Y
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: x86_64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest