denebola 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddb3a396701e9479f38cc53d23f86e568e7d2e31b4a38576d6670dc8f5026c56
-  data.tar.gz: 718554282d9670f3c656e06b67f9219679be4ec626cad2c390f49d8ff720cd27
+  metadata.gz: 605dec1949038f3bf81ca5b49d875231c515fdc656933467f2d34d1b1411da7e
+  data.tar.gz: 856f7ba61ad06df9f280850a4912259d1a76556cf32e0e5e8b8c78e6cec264e5
 SHA512:
-  metadata.gz: c4af8ed526cacc5ed81c91614349b79d985ee8851d7c5ee47e58cc7bea011aa6ce1f461c390a1ec5fdc5d731ae16a9ce5ad24e4291d8fe34c4e3926341e8f3a9
-  data.tar.gz: 4728022bcf1941df19c6cbb808ad8ece063582402d41d44f7a24be21924701e8b081edaef15999538c02c95de990327a297511b11a7aa184b81b0bfda3e3c609
+  metadata.gz: 02af176392f474c79428f0837f7ea44ed7198a25a56a250d6119b80ddc9a9bf6f5e5eba7e020417c3c3b922ec65912b075050e6224993b73e78f4da1c8cf1d79
+  data.tar.gz: 2d69fa29d55fb1970b30da016df0cc4730985ec286aaaa2048c08f17472f38e3904d37cefaa75961b6f3e476e1e86e3bd45fa1223dbe7101a2802dd480a2e8ed

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0 — 2026-09-15
+
+- Add `LazyRope` for bounded-memory access to very large UTF-8 files.
+- Build line, character, and UTF-16 indexes incrementally.
+- Keep edits as in-memory overlays while untouched bytes remain file-backed.
+- Detect files changed or replaced after opening.
+
 ## 0.1.0 — 2026-09-10
 
 - Initial release.

data/README.md

@@ -1,12 +1,66 @@
-# Denebola
+<h1 align="center">Denebola</h1>
 
-Persistent summary B+ trees and Unicode text ropes, in pure Ruby. Ruby 3.1 or later; no runtime dependencies.
+<p align="center">
+  <strong>Persistent summary B+ trees and Unicode text ropes in pure Ruby</strong>
+</p>
 
-Nodes, text chunks, and summaries are frozen. An edit shares untouched subtrees with the previous value. Keeping a snapshot is an ordinary assignment, so readers can keep analyzing old text while an editor creates a new version.
+<p align="center">
+  <a href="https://rubygems.org/gems/denebola"><img src="https://img.shields.io/gem/v/denebola.svg?colorB=319e8c" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/denebola"><img src="https://img.shields.io/gem/dt/denebola.svg" alt="Downloads"></a>
+  <a href="https://github.com/noxdea/denebola/actions/workflows/main.yml"><img src="https://github.com/noxdea/denebola/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby version">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
 
-This source is version 0.1.0, not yet published. Build it with `gem build denebola.gemspec`, or use `gem "denebola", path: "/path/to/denebola"` in a Gemfile.
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#text-rope">Text Rope</a> ·
+  <a href="#generic-summary-tree">Summary Tree</a> ·
+  <a href="#benchmarks">Benchmarks</a>
+</p>
 
-## Text editing
+---
+
+Denebola is a library for immutable, structurally shared sequences. It provides a generic summary B+ tree and a Unicode-aware text rope built on it. Every edit returns a new value while reusing untouched subtrees, so retaining a snapshot is an ordinary assignment.
+
+## Features
+
+- Persistent text editing with structural sharing
+- Bounded-memory, file-backed editing for multi-gigabyte text
+- UTF-8 byte, Unicode codepoint, UTF-16, and line-based indexing
+- Batched edits and explicit anchor transformation
+- LF, CRLF, CR, U+2028, and U+2029 line break support
+- Generic summary B+ tree with dimension-based cursors
+- Pure Ruby 3.1+ with no runtime dependencies
+- RBS signatures for the public API
+
+## Installation
+
+Add Denebola to your Gemfile:
+
+```ruby
+gem "denebola"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install denebola
+```
+
+### Requirements
+
+- Ruby 3.1 or later
+
+## Quick Start
 
 ```ruby
 require "denebola"
@@ -14,32 +68,56 @@ require "denebola"
 rope = Denebola::Rope.new("hello\nworld")
 snapshot = rope
 rope = rope.insert(5, ", there")
-rope.line(0)                # => "hello, there"
-snapshot.to_s               # => "hello\nworld"
-rope.bytesize               # => 18
-rope.length                 # => 18 Unicode codepoints
-rope.line_count             # => 2
-rope.byteslice(0, 5).to_s    # => "hello"
-rope = rope.delete(0...5)
-rope = rope.replace(0...7, "goodbye")
-rope.each_chunk { |text| puts text }  # Frozen strings, without flattening
+
+rope.line(0)  # => "hello, there"
+rope.to_s     # => "hello, there\nworld"
+snapshot.to_s # => "hello\nworld"
 ```
 
-All `replace`, `apply_edits`, and `byteslice` ranges address **bytes in UTF-8**, and are checked for bounds and codepoint boundaries. Inclusive and exclusive Ruby ranges work; beginless/endless ranges are accepted. Invalid encodings, split codepoints, and overlapping batch edits raise exceptions. Input strings are copied or shared safely with Ruby's copy-on-write strings; later mutation of the source cannot alter a rope.
+For files that should not be copied into memory, open a `LazyRope`:
+
+```ruby
+text = Denebola::LazyRope.open("server.log")
+text.line(1_000_000)                 # indexes only as far as needed
+text.line_count                      # estimate until the index reaches EOF
+text.line_count(exact: true)         # force an exact count
+text.edit(0...5, "INFO:")           # untouched bytes remain file-backed
+text.materialize(0...1024)           # an ordinary editable Rope
+text.close
+```
 
-`apply_edits([[range, text], ...])` applies nonoverlapping edits against one original snapshot, sorting them into source order. Adjacent ranges are allowed. Chunks preserve extended grapheme clusters when building or joining text; a single unusually long grapheme may exceed the configured chunk size. Explicit byte slices and edits may operate between codepoints inside a grapheme.
+`LazyRope` reads 1 MiB chunks by default and keeps eight chunks in an LRU cache. `byteslice`, line access, byte/codepoint positions, UTF-16 positions, and anchors follow `Rope` semantics. `edit`, `insert`, `delete`, and `replace` mutate the open view and store only replacement text in memory; call `materialize` when an immutable `Rope` snapshot is needed. A file changed, removed, or replaced after opening raises `Denebola::Error`. `to_s` and `materialize` without a range intentionally load the complete logical file.
+
+## Text Rope
+
+### Editing
 
 ```ruby
 rope = Denebola::Rope.new("hello\nworld")
-rope.apply_edits([[0...5, "Hi"], [6...11, "Ruby"]]).to_s # => "Hi\nRuby"
+
+rope.bytesize                         # => 11
+rope.length                           # => 11 Unicode codepoints
+rope.line_count                       # => 2
+rope.byteslice(0, 5).to_s             # => "hello"
+rope.delete(0...5).to_s               # => "\nworld"
+rope.replace(0...5, "Hi").to_s       # => "Hi\nworld"
+rope.each_chunk { |text| puts text }  # Frozen strings, without flattening
+
+rope.apply_edits([[0...5, "Hi"], [6...11, "Ruby"]]).to_s
+# => "Hi\nRuby"
 ```
 
-## Lines and positions
+Ranges passed to `replace`, `apply_edits`, and `byteslice` address bytes in UTF-8. Bounds and codepoint boundaries are checked. Inclusive, exclusive, beginless, and endless Ruby ranges are accepted; invalid encodings, split codepoints, and overlapping batch edits raise exceptions.
+
+`apply_edits` applies nonoverlapping edits against one original snapshot and sorts them into source order. Adjacent ranges are allowed. Input strings are copied or shared safely with Ruby's copy-on-write strings, so later mutation of the source cannot alter a rope.
 
-LF, CRLF, CR, U+2028, and U+2029 are line breaks. `line(row)` omits its terminator. Rows are zero based; empty text and a final empty row after a terminator each count as a line.
+Chunks preserve extended grapheme clusters when building or joining text. A single unusually long grapheme may exceed the configured chunk size; explicit byte slices and edits may operate between codepoints inside a grapheme.
+
+### Lines and Positions
 
 ```ruby
 rope = Denebola::Rope.new("😀\n日本")
+
 rope.point_at(8)                              # => Point(row: 1, column: 1)
 rope.offset_at(Denebola::Point.new(1, 1))     # => 8
 rope.line_start(1)                            # => 5
@@ -49,28 +127,32 @@ rope.utf16_point_at(4)                        # => Point(row: 0, column: 2)
 rope.offset_at_utf16_point(Denebola::Point.new(0, 2)) # => 4
 ```
 
-`Point` accepts positional or keyword `row` and `column`. Unqualified offsets are UTF-8 byte offsets. Normal columns count Unicode codepoints, not screen cells or graphemes. The UTF-16 methods count code units and reject offsets inside a surrogate pair. `offset_at` and `offset_at_utf16_point` require a column within the line's content. A byte position between CR and LF normalizes to the following row, column zero; converting that point back returns the position after LF.
+`Point` accepts positional or keyword `row` and `column`. Unqualified offsets are UTF-8 byte offsets. Normal columns count Unicode codepoints, not screen cells or graphemes. UTF-16 methods count code units and reject offsets inside a surrogate pair. `offset_at` and `offset_at_utf16_point` require a column within the line's content.
+
+`line(row)` omits the terminator. Rows are zero-based; empty text and a final empty row after a terminator each count as a line. A byte position between CR and LF normalizes to the following row, column zero; converting that point back returns the position after LF.
 
-`rope.summary` exposes `bytesize`, `length`, `utf16_length`, `break_count`, `longest_row` (earliest row with maximum width), `longest_row_length`, `first_line_length`, and `last_line_length`. `TextSummary.zero` is the identity and `summary + other_summary` combines concatenated text, including CRLF across a boundary.
+`rope.summary` exposes `bytesize`, `length`, `utf16_length`, `break_count`, `longest_row` (the earliest row with maximum width), `longest_row_length`, `first_line_length`, and `last_line_length`. `TextSummary.zero` is the identity, and `summary + other_summary` combines concatenated text, including CRLF across a boundary.
 
-## Anchors
+### Anchors
 
-Anchors transform explicitly using the same finite byte ranges as an edit, without retaining the entire edit history:
+Anchors transform explicitly using the same finite byte ranges as an edit, without retaining the edit history:
 
 ```ruby
 rope = Denebola::Rope.new("hello")
 anchor = rope.anchor(2, bias: :right)
 edits = [[2...2, "XYZ"]]
+
 anchor = anchor.transform(edits)
 rope = rope.apply_edits(edits)
+
 anchor.offset # => 5
 ```
 
-`:left` keeps an anchor before text inserted at its position; `:right` keeps it after. Anchors covered by a replacement collapse to the corresponding side of the replacement. Offsets after an edit move by its byte-length delta. Anchor transformation returns a new anchor; it does not mutate the original or automatically observe a rope.
+`:left` keeps an anchor before text inserted at its position; `:right` keeps it after. Anchors covered by a replacement collapse to the corresponding side of the replacement. Offsets after an edit move by its byte-length delta. Transformation returns a new anchor; it does not mutate the original or automatically observe a rope.
 
-## Generic summary tree
+## Generic Summary Tree
 
-Items expose `summary`. The summary class supplies `.zero` and `#+`, with an associative addition and identity. Items and their summaries must be immutable. A dimension is a summary attribute name, a callable, or an object with `from_summary(summary)`; its projection must be monotone along the sequence.
+Items expose `summary`. The summary class supplies `.zero` and `#+`, with associative addition and an identity. Items and their summaries must be immutable. A dimension is a summary attribute name, a callable, or an object with `from_summary(summary)`; its projection must be monotone along the sequence.
 
 ```ruby
 Weight = Struct.new(:weight) do
@@ -79,27 +161,35 @@ Weight = Struct.new(:weight) do
   def summary = self
 end
 
-tree = Denebola::Tree.new([Weight.new(2).freeze, Weight.new(3).freeze], summary: Weight)
+tree = Denebola::Tree.new(
+  [Weight.new(2).freeze, Weight.new(3).freeze],
+  summary: Weight
+)
 tree = tree.push(Weight.new(5).freeze)
 cursor = tree.cursor(:weight).seek(2)
+
 cursor.item.weight          # => 3
-cursor.summary.weight       # => 2: summary before the current item
+cursor.summary.weight       # => 2, the summary before the current item
 cursor.next.weight          # => 5
 cursor.prev.weight          # => 3
 cursor.seek(2, bias: :left).item.weight # => 2
 ```
 
-`Tree.from(items, summary: ...)` and `Tree.new(items, summary: ...)` bulk-build an already ordered sequence. `append` joins another compatible tree or enumerable. `tree[index]`, `slice(index, count)`, and `split_at(index)` use item indexes; `replace_at(index, items)` replaces one item, or appends when `index == size`. Every update returns a new tree.
+`Tree.from(items, summary: ...)` and `Tree.new(items, summary: ...)` bulk-build an ordered sequence. `append` joins another compatible tree or enumerable. `tree[index]`, `slice(index, count)`, and `split_at(index)` use item indexes. `replace_at(index, items)` replaces one item, or appends when `index == size`. Every update returns a new tree.
 
 `cursor.seek(value)` chooses the item whose ending dimension exceeds the target; `bias: :left` also includes equality. At the end, `item` is `nil`, `index == tree.size`, and `summary` is the whole summary. `cursor.read_until(value)` returns complete items up to the target boundary and advances the cursor; it does not split an item. `next` and `prev` return the newly selected item or `nil`.
 
-Text dimensions are also available as `Denebola::Dimensions::BYTES`, `CHARACTERS`, `UTF16`, and `LINE_BREAKS`. B+ nodes hold cumulative summaries and item counts; navigation uses binary search. Editing copies touched chunks and ancestor paths, and splitting/joining preserves occupancy and equal leaf depth. Returning a string or a long line necessarily costs at least its output size. `check_invariants!` checks occupancy, frozen nodes, depth, prefix counts, and summaries and is intended for tests.
+Text dimensions are available as `Denebola::Dimensions::BYTES`, `CHARACTERS`, `UTF16`, and `LINE_BREAKS`. B+ nodes hold cumulative summaries and item counts; navigation uses binary search. Editing copies touched chunks and ancestor paths, while splitting and joining preserve occupancy and equal leaf depth. Returning a string or a long line necessarily costs at least its output size.
+
+`check_invariants!` checks occupancy, frozen nodes, depth, prefix counts, and summaries. It is intended for tests.
 
-## Benchmarks and validation
+## Benchmarks
 
-Run `bundle install`, then `bundle exec rake test`. The default suite includes 100,000 deterministic random Unicode edits compared with Ruby `String`, 5,000 summary monoid cases, immutable snapshots, split/join occupancy checks, all supported newline types, surrogate boundaries, and retained node counts after 10,000 edits. `bundle exec rake test:oracle` runs the property tests alone. `ruby tools/check_isolation.rb` checks runtime independence; `sig/denebola.rbs` describes the public API.
+```bash
+bundle exec rake bench
+```
 
-`bundle exec rake bench` compares fanouts 8/16/32/64 and chunk sizes 256/512/1024/2048 before exercising a 1,000,000-line ASCII document (11,000,000 bytes). Timings are five-batch medians after warmup. Defaults are fanout **16**, chunk size **1024 bytes**: smaller chunks improve some edits but allocate more nodes; these defaults meet the edit and retained-memory budgets together. Override them with `Rope.new(text, branching: 8, chunk_size: 512)`.
+The benchmark compares fanouts 8/16/32/64 and chunk sizes 256/512/1024/2048 before exercising a 1,000,000-line ASCII document (11,000,000 bytes). Timings are five-batch medians after warmup. The defaults are fanout **16** and chunk size **1024 bytes**: smaller chunks improve some edits but allocate more nodes, while these defaults meet the edit and retained-memory budgets together. Override them with `Rope.new(text, branching: 8, chunk_size: 512)`.
 
 Measured 2026-09-09 on arm64 macOS, Ruby 4.0.2 with YJIT:
 
@@ -113,8 +203,23 @@ Measured 2026-09-09 on arm64 macOS, Ruby 4.0.2 with YJIT:
 | Slice 1 KB | 6.79 µs | 20 µs |
 | Retained Ruby object memory | 33.84 MiB | 40 MiB |
 
-Performance depends on document content, Ruby version, and hardware. Memory is measured with `ObjectSpace` after releasing the input and collecting garbage; it is not process RSS. `rake bench:assert` uses explicitly wider timing ceilings for shared CI hardware, while retaining the 40 MiB memory ceiling. CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux, macOS, and Windows.
+Performance depends on document content, Ruby version, and hardware. Memory is measured with `ObjectSpace` after releasing the input and collecting garbage; it is not process RSS. `rake bench:assert` uses wider timing ceilings for shared CI hardware while retaining the 40 MiB memory ceiling.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+The default suite includes 100,000 deterministic random Unicode edits compared with Ruby `String`, 5,000 summary monoid cases, immutable snapshots, split/join occupancy checks, all supported newline types, surrogate boundaries, and retained node counts after 10,000 edits. `bundle exec rake test:oracle` runs the property tests alone, and `ruby tools/check_isolation.rb` checks runtime independence.
+
+CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux, macOS, and Windows. See the [RBS signatures](sig/denebola.rbs) for the public API and the [changelog](CHANGELOG.md) for release history.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/noxdea/denebola.
 
 ## License
 
-[MIT](LICENSE.txt).
+Released under the [MIT License](LICENSE.txt).

data/lib/denebola/lazy_rope.rb

@@ -0,0 +1,572 @@
+# frozen_string_literal: true
+
+module Denebola
+  # A file-backed text rope. File pages and indexes are populated on demand;
+  # edits replace only the affected byte ranges with ordinary Rope values.
+  class LazyRope
+    DEFAULT_CHUNK_SIZE = 1_048_576
+    DEFAULT_CACHE_CHUNKS = 8
+    FilePiece = Struct.new(:offset, :bytesize, keyword_init: true)
+    TextPiece = Struct.new(:rope, keyword_init: true) do
+      def bytesize = rope.bytesize
+    end
+
+    attr_reader :chunk_size, :cached_bytes
+
+    def self.open(path, chunk_size: DEFAULT_CHUNK_SIZE, encoding: Encoding::UTF_8, cache_chunks: DEFAULT_CACHE_CHUNKS)
+      new(path, chunk_size: chunk_size, encoding: encoding, cache_chunks: cache_chunks)
+    end
+
+    def initialize(path, chunk_size: DEFAULT_CHUNK_SIZE, encoding: Encoding::UTF_8, cache_chunks: DEFAULT_CACHE_CHUNKS)
+      raise ArgumentError, "chunk_size must be an integer >= 4" unless chunk_size.is_a?(Integer) && chunk_size >= 4
+      raise ArgumentError, "cache_chunks must be a positive integer" unless cache_chunks.is_a?(Integer) && cache_chunks.positive?
+      raise ArgumentError, "only UTF-8 files are supported" unless encoding == Encoding::UTF_8
+
+      flags = File::RDONLY | File::BINARY
+      flags |= File::SHARE_DELETE if defined?(File::SHARE_DELETE)
+      @file = File.open(path, flags)
+      @path = File.expand_path(path)
+      @chunk_size = chunk_size
+      @cache_chunks = cache_chunks
+      @cache = {}
+      @cached_bytes = 0
+      @positioned_reads = true
+      @read_lock = Mutex.new
+      @stamp = file_stamp(@file.stat)
+      @path_stamp = file_stamp(File.stat(@path))
+      @origin = @file.size >= 3 && raw_read(0, 3) == "\xEF\xBB\xBF".b ? 3 : 0
+      @source_bytesize = @file.size - @origin
+      @pieces = @source_bytesize.zero? ? [] : [FilePiece.new(offset: 0, bytesize: @source_bytesize).freeze]
+      rebuild_piece_ends
+      reset_index
+    rescue StandardError
+      @file&.close
+      raise
+    end
+
+    def lazy? = true
+    def closed? = @file.closed?
+
+    def bytesize
+      ensure_unchanged!
+      @piece_ends.last || 0
+    end
+    def empty? = bytesize.zero?
+
+    def length
+      index_to_eof
+      @indexed_characters
+    end
+
+    def size = length
+
+    def utf16_length
+      index_to_eof
+      @indexed_utf16
+    end
+
+    # Until exact indexing is requested, return an estimate based on the
+    # already scanned prefix. The estimate never reports fewer known lines.
+    def line_count(exact: false)
+      index_to_eof if exact
+      return packed_line_count if @index_complete
+      scan_index if @indexed_offset.zero? && bytesize.positive?
+
+      known_lines = packed_line_count + (@pending_cr ? 1 : 0)
+      breaks = known_lines - 1
+      return 1 if breaks.zero? || @indexed_offset.zero?
+
+      [known_lines, (breaks * bytesize.fdiv(@indexed_offset)).round + 1].max
+    end
+
+    def line_start(row)
+      raise RangeError, "line out of bounds" unless row.is_a?(Integer) && row >= 0
+      index_until_line(row)
+      raise RangeError, "line out of bounds" if row >= packed_line_count
+
+      unpack_line_start(row)
+    end
+
+    def line(row)
+      start = line_start(row)
+      index_until_line(row + 1)
+      ending = row + 1 < packed_line_count ? unpack_line_start(row + 1) : bytesize
+      read_bytes(start, ending - start).force_encoding(Encoding::UTF_8).sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "")
+    end
+
+    def byteslice(offset, length = nil)
+      start, finish = slice_bounds(offset, length)
+      Rope.new(read_bytes(start, finish - start).force_encoding(Encoding::UTF_8))
+    end
+
+    def each_chunk
+      return enum_for(__method__) unless block_given?
+
+      offset = 0
+      total = bytesize
+      while offset < total
+        raw = read_bytes(offset, [chunk_size, total - offset].min)
+        complete = complete_utf8_length(raw)
+        if complete.zero?
+          raw = read_bytes(offset, [chunk_size + 3, total - offset].min)
+          complete = complete_utf8_length(raw)
+        end
+        text = raw.byteslice(0, complete).force_encoding(Encoding::UTF_8)
+        raise Error, "file contains invalid UTF-8" if complete.zero? || !text.valid_encoding?
+        yield text
+        offset += complete
+      end
+      self
+    end
+
+    def materialize(range = nil)
+      range ? byteslice(range) : Rope.new(to_s)
+    end
+
+    def to_s
+      text = String.new(capacity: bytesize, encoding: Encoding::UTF_8)
+      each_chunk { |chunk| text << chunk }
+      text
+    end
+
+    # Mutates this file-backed view and keeps untouched ranges file-backed.
+    def edit(range, text)
+      replacement = normalize_text(text)
+      start, finish = byte_bounds(range)
+      validate_offset(start)
+      validate_offset(finish)
+
+      updated = pieces_for(0, start)
+      updated << TextPiece.new(rope: Rope.new(replacement)).freeze unless replacement.empty?
+      updated.concat(pieces_for(finish, bytesize))
+      @pieces = coalesce(updated)
+      rebuild_piece_ends
+      invalidate_index_from(start)
+      self
+    end
+
+    def insert(offset, text) = edit(offset...offset, text)
+    def delete(range) = edit(range, "")
+    def replace(range, text) = edit(range, text)
+
+    def point_at(byte_offset)
+      validate_offset(byte_offset)
+      index_to([byte_offset + 1, bytesize].min)
+      if byte_offset.positive? && byte_offset < bytesize && read_bytes(byte_offset - 1, 2) == "\r\n"
+        row = line_index_at(byte_offset + 1)
+        return Point.new(row, 0)
+      end
+
+      row = line_index_at(byte_offset)
+      start = unpack_line_start(row)
+      Point.new(row, read_bytes(start, byte_offset - start).force_encoding(Encoding::UTF_8).length)
+    end
+
+    def offset_at(point)
+      start = line_start(point.row)
+      content = line(point.row)
+      raise RangeError, "column out of bounds" unless point.column.is_a?(Integer) && point.column.between?(0, content.length)
+
+      start + content.each_char.take(point.column).join.bytesize
+    end
+
+    def utf16_offset_at(byte_offset)
+      validate_offset(byte_offset)
+      prefix_dimensions(byte_offset).last
+    end
+
+    def offset_at_utf16(utf16_offset)
+      raise RangeError, "UTF-16 offset out of bounds" unless utf16_offset.is_a?(Integer) && utf16_offset >= 0
+      index_to_eof
+      raise RangeError, "UTF-16 offset out of bounds" if utf16_offset > @indexed_utf16
+
+      checkpoint = @checkpoints.bsearch { |entry| entry[2] > utf16_offset }
+      checkpoint = checkpoint ? @checkpoints[@checkpoints.index(checkpoint) - 1] : @checkpoints.last
+      offset, _characters, units = checkpoint
+      return offset if units == utf16_offset
+
+      each_codepoint_from(offset) do |codepoint, byte_start, _byte_finish|
+        width = codepoint > 0xFFFF ? 2 : 1
+        raise RangeError, "UTF-16 offset splits a surrogate pair" if units + width > utf16_offset
+        units += width
+        return _byte_finish if units == utf16_offset
+        break if units > utf16_offset
+      end
+      raise RangeError, "UTF-16 offset out of bounds"
+    end
+
+    def utf16_point_at(byte_offset)
+      point = point_at(byte_offset)
+      start = line_start(point.row)
+      Point.new(point.row, [utf16_offset_at(byte_offset) - utf16_offset_at(start), 0].max)
+    end
+
+    def offset_at_utf16_point(point)
+      start = line_start(point.row)
+      content = line(point.row)
+      units = 0
+      bytes = 0
+      content.each_codepoint do |codepoint|
+        return start + bytes if units == point.column
+        width = codepoint > 0xFFFF ? 2 : 1
+        raise RangeError, "UTF-16 column splits a surrogate pair" if units + width > point.column
+        units += width
+        bytes += codepoint.chr(Encoding::UTF_8).bytesize
+      end
+      return start + bytes if units == point.column
+
+      raise RangeError, "column out of bounds"
+    end
+
+    def anchor(byte_offset, bias: :right)
+      validate_offset(byte_offset)
+      Anchor.new(byte_offset, bias: bias)
+    end
+
+    def check_invariants!
+      ensure_unchanged!
+      raise Error, "invalid piece index" unless @piece_ends.each_cons(2).all? { |left, right| left < right }
+      raise Error, "invalid piece size" unless @pieces.all? { |piece| piece.bytesize.positive? }
+      @pieces.grep(TextPiece).each { |piece| piece.rope.check_invariants! }
+      index_to_eof
+      starts = @line_starts.unpack("Q<*")
+      raise Error, "invalid line index" unless starts.first == 0 && starts.each_cons(2).all? { |left, right| left < right } && starts.last <= bytesize
+      raise Error, "invalid dimension index" unless @checkpoints.each_cons(2).all? { |left, right| left[0] < right[0] }
+      true
+    end
+
+    def close
+      @file.close unless @file.closed?
+      nil
+    end
+
+    private
+
+    def normalize_text(text)
+      raise TypeError, "text must be a String" unless text.is_a?(String)
+      value = text.encoding == Encoding::UTF_8 ? text.dup : text.encode(Encoding::UTF_8)
+      raise ArgumentError, "text must be valid UTF-8" unless value.valid_encoding?
+      value
+    end
+
+    def byte_bounds(range)
+      raise TypeError, "range must be a Range" unless range.is_a?(Range)
+      start = range.begin || 0
+      finish = range.end || bytesize
+      finish += 1 unless range.exclude_end? || range.end.nil?
+      raise RangeError, "range out of bounds" unless start.is_a?(Integer) && finish.is_a?(Integer) && start.between?(0, bytesize) && finish.between?(start, bytesize)
+      [start, finish]
+    end
+
+    def slice_bounds(offset, length)
+      return byte_bounds(offset) if offset.is_a?(Range)
+      raise TypeError, "offset must be an Integer" unless offset.is_a?(Integer)
+      length ||= bytesize - offset
+      raise RangeError, "slice out of bounds" unless length.is_a?(Integer) && length >= 0 && offset.between?(0, bytesize) && offset + length <= bytesize
+      validate_offset(offset)
+      validate_offset(offset + length)
+      [offset, offset + length]
+    end
+
+    def validate_offset(offset)
+      raise RangeError, "offset out of bounds" unless offset.is_a?(Integer) && offset.between?(0, bytesize)
+      return if offset == bytesize || (read_bytes(offset, 1).getbyte(0) & 0xC0) != 0x80
+      raise RangeError, "offset inside UTF-8 character"
+    end
+
+    def pieces_for(start, finish)
+      return [] if start == finish
+      result = []
+      piece_start = 0
+      @pieces.each do |piece|
+        piece_finish = piece_start + piece.bytesize
+        overlap_start = [start, piece_start].max
+        overlap_finish = [finish, piece_finish].min
+        result << slice_piece(piece, overlap_start - piece_start, overlap_finish - overlap_start) if overlap_start < overlap_finish
+        piece_start = piece_finish
+      end
+      result
+    end
+
+    def slice_piece(piece, local_start, length)
+      if piece.is_a?(FilePiece)
+        FilePiece.new(offset: piece.offset + local_start, bytesize: length).freeze
+      else
+        TextPiece.new(rope: piece.rope.byteslice(local_start, length)).freeze
+      end
+    end
+
+    def coalesce(pieces)
+      pieces.each_with_object([]) do |piece, result|
+        previous = result.last
+        if previous.is_a?(FilePiece) && piece.is_a?(FilePiece) && previous.offset + previous.bytesize == piece.offset
+          result[-1] = FilePiece.new(offset: previous.offset, bytesize: previous.bytesize + piece.bytesize).freeze
+        elsif previous.is_a?(TextPiece) && piece.is_a?(TextPiece) && previous.bytesize + piece.bytesize <= Rope::DEFAULT_CHUNK_SIZE
+          result[-1] = TextPiece.new(rope: Rope.new(previous.rope.to_s + piece.rope.to_s)).freeze
+        else
+          result << piece
+        end
+      end
+    end
+
+    def rebuild_piece_ends
+      total = 0
+      @piece_ends = @pieces.map { |piece| total += piece.bytesize }
+    end
+
+    def read_bytes(offset, count)
+      ensure_unchanged!
+      return "".b if count.zero?
+      raise RangeError, "read out of bounds" unless offset >= 0 && count >= 0 && offset + count <= (@piece_ends.last || 0)
+
+      output = String.new(capacity: count, encoding: Encoding::BINARY)
+      piece_index = @piece_ends.bsearch_index { |piece_end| piece_end > offset } || @pieces.length
+      piece_start = piece_index.zero? ? 0 : @piece_ends[piece_index - 1]
+      while piece_index < @pieces.length
+        piece = @pieces[piece_index]
+        piece_finish = piece_start + piece.bytesize
+        if offset < piece_finish && offset + count > piece_start
+          local_start = [offset - piece_start, 0].max
+          length = [[offset + count, piece_finish].min - (piece_start + local_start), 0].max
+          if piece.is_a?(FilePiece)
+            output << read_file(piece.offset + local_start, length)
+          else
+            append_rope_bytes(output, piece.rope, local_start, length)
+          end
+        end
+        break if output.bytesize == count
+        piece_start = piece_finish
+        piece_index += 1
+      end
+      raise Error, "short read" unless output.bytesize == count
+      output
+    end
+
+    def append_rope_bytes(output, rope, offset, count)
+      tree = rope.__send__(:tree)
+      index, chunk, prefix = tree.locate(offset, :bytesize)
+      local = offset - prefix.bytesize
+      while chunk && count.positive?
+        length = [count, chunk.text.bytesize - local].min
+        output << chunk.text.b.byteslice(local, length)
+        count -= length
+        local = 0
+        index += 1
+        chunk = tree[index]
+      end
+    end
+
+    def read_file(offset, count)
+      output = String.new(capacity: count, encoding: Encoding::BINARY)
+      while count.positive?
+        page, local = offset.divmod(chunk_size)
+        data = @cache.delete(page)
+        unless data
+          data = raw_read(@origin + page * chunk_size, [chunk_size, @source_bytesize - page * chunk_size].min)
+          @cached_bytes += data.bytesize
+          while @cache.length >= @cache_chunks
+            _old_page, old_data = @cache.shift
+            @cached_bytes -= old_data.bytesize
+          end
+        end
+        @cache[page] = data
+        length = [count, data.bytesize - local].min
+        raise Error, "file was truncated" unless length.positive?
+        output << data.byteslice(local, length)
+        offset += length
+        count -= length
+      end
+      output
+    end
+
+    def raw_read(offset, count)
+      return "".b if count.zero?
+      if @positioned_reads
+        @file.pread(count, offset)
+      else
+        @read_lock.synchronize do
+          @file.seek(offset)
+          @file.read(count)
+        end
+      end
+    rescue NotImplementedError
+      @positioned_reads = false
+      retry
+    end
+
+    def reset_index
+      @line_starts = [0].pack("Q<")
+      @indexed_offset = 0
+      @indexed_characters = 0
+      @indexed_utf16 = 0
+      @pending_cr = nil
+      @checkpoints = [[0, 0, 0, nil]]
+      @index_complete = false
+    end
+
+    def invalidate_index_from(offset)
+      # Re-scan the byte before an edit as well: inserting or removing an LF
+      # can change whether a preceding CR is one terminator or half of CRLF.
+      rewind_to = [offset - 1, 0].max
+      checkpoint_index = @checkpoints.rindex { |entry| entry[0] <= rewind_to } || 0
+      checkpoint = @checkpoints[checkpoint_index]
+      @checkpoints = @checkpoints.take(checkpoint_index + 1)
+      @indexed_offset, @indexed_characters, @indexed_utf16, @pending_cr = checkpoint
+      starts = @line_starts.unpack("Q<*").take_while { |line_start| line_start <= @indexed_offset }
+      @line_starts = starts.pack("Q<*")
+      @index_complete = false
+    end
+
+    def index_until_line(row)
+      scan_index while packed_line_count <= row && !@index_complete
+    end
+
+    def index_to(offset)
+      scan_index while @indexed_offset < offset && !@index_complete
+    end
+
+    def index_to_eof
+      scan_index until @index_complete
+    end
+
+    def scan_index
+      total = bytesize
+      if @indexed_offset == total
+        append_line_start(@pending_cr) if @pending_cr
+        @pending_cr = nil
+        @index_complete = true
+        @checkpoints[-1] = [@indexed_offset, @indexed_characters, @indexed_utf16, nil]
+        return
+      end
+
+      raw = read_bytes(@indexed_offset, [chunk_size, total - @indexed_offset].min)
+      complete = complete_utf8_length(raw)
+      text = raw.byteslice(0, complete).force_encoding(Encoding::UTF_8)
+      raise Error, "file contains invalid UTF-8" if complete.zero? || !text.valid_encoding?
+
+      if text.ascii_only?
+        scan_ascii_index(text)
+      else
+        scan_unicode_index(text)
+      end
+      @indexed_offset += complete
+      @checkpoints << [@indexed_offset, @indexed_characters, @indexed_utf16, @pending_cr]
+      scan_index if @indexed_offset == total
+    end
+
+    def append_line_start(offset)
+      return if unpack_line_start(packed_line_count - 1) == offset
+      @line_starts << [offset].pack("Q<")
+    end
+
+    def packed_line_count = @line_starts.bytesize / 8
+    def unpack_line_start(row) = @line_starts.unpack1("Q<", offset: row * 8)
+
+    def line_index_at(offset)
+      low = 0
+      high = packed_line_count
+      while low < high
+        middle = (low + high) / 2
+        unpack_line_start(middle) <= offset ? low = middle + 1 : high = middle
+      end
+      [low - 1, 0].max
+    end
+
+    def prefix_dimensions(offset)
+      index_to(offset)
+      checkpoint_index = @checkpoints.bsearch_index { |entry| entry[0] > offset }
+      checkpoint = checkpoint_index ? @checkpoints[checkpoint_index - 1] : @checkpoints.last
+      base, characters, units = checkpoint
+      text = read_bytes(base, offset - base).force_encoding(Encoding::UTF_8)
+      raise RangeError, "offset inside UTF-8 character" unless text.valid_encoding?
+      [characters + text.length, units + (text.ascii_only? ? text.bytesize : text.encode(Encoding::UTF_16LE).bytesize / 2)]
+    end
+
+    def each_codepoint_from(offset)
+      while offset < bytesize
+        raw = read_bytes(offset, [chunk_size, bytesize - offset].min)
+        complete = complete_utf8_length(raw)
+        text = raw.byteslice(0, complete).force_encoding(Encoding::UTF_8)
+        raise Error, "file contains invalid UTF-8" if complete.zero? || !text.valid_encoding?
+        cursor = offset
+        text.each_codepoint do |codepoint|
+          finish = cursor + codepoint.chr(Encoding::UTF_8).bytesize
+          yield codepoint, cursor, finish
+          cursor = finish
+        end
+        offset += complete
+      end
+    end
+
+    def scan_ascii_index(text)
+      base = @indexed_offset
+      @indexed_characters += text.bytesize
+      @indexed_utf16 += text.bytesize
+      scan_from = 0
+      if @pending_cr
+        if text.start_with?("\n")
+          append_line_start(base + 1)
+          scan_from = 1
+        else
+          append_line_start(@pending_cr)
+        end
+        @pending_cr = nil
+      end
+      text.b.byteslice(scan_from, text.bytesize - scan_from).scan(/\r\n|[\r\n]/n) do |ending|
+        finish = base + scan_from + Regexp.last_match.end(0)
+        if ending == "\r" && finish == base + text.bytesize
+          @pending_cr = finish
+        else
+          append_line_start(finish)
+        end
+      end
+    end
+
+    def scan_unicode_index(text)
+      cursor = @indexed_offset
+      text.each_codepoint do |codepoint|
+        width = codepoint.chr(Encoding::UTF_8).bytesize
+        finish = cursor + width
+        @indexed_characters += 1
+        @indexed_utf16 += codepoint > 0xFFFF ? 2 : 1
+        if @pending_cr
+          if codepoint == 10
+            append_line_start(finish)
+            @pending_cr = nil
+            cursor = finish
+            next
+          end
+          append_line_start(@pending_cr)
+          @pending_cr = nil
+        end
+        if codepoint == 13
+          @pending_cr = finish
+        elsif codepoint == 10 || codepoint == 0x2028 || codepoint == 0x2029
+          append_line_start(finish)
+        end
+        cursor = finish
+      end
+    end
+
+    def complete_utf8_length(value)
+      return 0 if value.empty?
+      index = value.bytesize - 1
+      index -= 1 while index.positive? && (value.getbyte(index) & 0xC0) == 0x80
+      leading = value.getbyte(index)
+      expected = leading < 0x80 ? 1 : leading < 0xE0 ? 2 : leading < 0xF0 ? 3 : 4
+      value.bytesize - index < expected ? index : value.bytesize
+    end
+
+    def file_stamp(stat)
+      [stat.dev, stat.ino, stat.size, stat.mtime, stat.ctime]
+    end
+
+    def ensure_unchanged!
+      raise IOError, "closed file" if @file.closed?
+      unchanged = file_stamp(@file.stat) == @stamp && file_stamp(File.stat(@path)) == @path_stamp
+      raise Error, "file changed on disk; reopen it" unless unchanged
+    rescue Errno::ENOENT
+      raise Error, "file changed on disk; reopen it"
+    end
+  end
+end

data/lib/denebola/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Denebola
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/denebola.rb

@@ -9,3 +9,4 @@ require_relative "denebola/point"
 require_relative "denebola/dimensions"
 require_relative "denebola/rope"
 require_relative "denebola/anchor"
+require_relative "denebola/lazy_rope"

data/sig/denebola.rbs

@@ -146,6 +146,43 @@ module Denebola
     end
   end
 
+  class LazyRope
+    DEFAULT_CHUNK_SIZE: Integer
+    DEFAULT_CACHE_CHUNKS: Integer
+    attr_reader chunk_size: Integer
+    attr_reader cached_bytes: Integer
+    def self.open: (String | _ToPath path, ?chunk_size: Integer, ?encoding: Encoding, ?cache_chunks: Integer) -> LazyRope
+    def initialize: (String | _ToPath path, ?chunk_size: Integer, ?encoding: Encoding, ?cache_chunks: Integer) -> void
+    def lazy?: () -> true
+    def closed?: () -> bool
+    def bytesize: () -> Integer
+    def size: () -> Integer
+    def empty?: () -> bool
+    def length: () -> Integer
+    def utf16_length: () -> Integer
+    def line_count: (?exact: bool) -> Integer
+    def line_start: (Integer) -> Integer
+    def line: (Integer) -> String
+    def byteslice: (Integer | Range[Integer?], ?Integer?) -> Rope
+    def each_chunk: () { (String) -> void } -> self
+                  | () -> Enumerator[String, self]
+    def materialize: (?Range[Integer?]?) -> Rope
+    def to_s: () -> String
+    def edit: (Range[Integer?], String) -> self
+    def insert: (Integer, String) -> self
+    def delete: (Range[Integer?]) -> self
+    def replace: (Range[Integer?], String) -> self
+    def point_at: (Integer) -> Point
+    def offset_at: (Point) -> Integer
+    def utf16_offset_at: (Integer) -> Integer
+    def offset_at_utf16: (Integer) -> Integer
+    def utf16_point_at: (Integer) -> Point
+    def offset_at_utf16_point: (Point) -> Integer
+    def anchor: (Integer, ?bias: :left | :right) -> Anchor
+    def check_invariants!: () -> true
+    def close: () -> nil
+  end
+
   class Anchor
     attr_reader offset: Integer
     attr_reader bias: :left | :right

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: denebola
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies: []
-description: Immutable, structurally shared trees with summary dimensions, UTF-8 text
-  editing, line and UTF-16 indexing, and anchors.
+description: Immutable text ropes plus bounded-memory, file-backed editing with line
+  and UTF-16 indexing.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -25,6 +26,7 @@ files:
 - lib/denebola/cursor.rb
 - lib/denebola/dimensions.rb
 - lib/denebola/error.rb
+- lib/denebola/lazy_rope.rb
 - lib/denebola/point.rb
 - lib/denebola/rope.rb
 - lib/denebola/text_summary.rb
@@ -38,6 +40,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/noxdea/denebola
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -52,7 +55,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Persistent summary B+ trees and Unicode text ropes in pure Ruby
 test_files: []