leptris 1.9.12-aarch64-linux → 1.9.14-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf80f624ccd37fd9495e26c150943bc07923b82fd3e96eacb0d115d2a2651f5d
-  data.tar.gz: f7974a661b342dacb962a6e92bc7c9634d3a606b0ab1c2300262c469420b4bd2
+  metadata.gz: c96f59841d0606a790ec372576cdb05f50bbc39c43cdf1188e7a4535068a7a8f
+  data.tar.gz: e3396a5ec39b5638f20a2254da0796f6330ca689f62e2fcad939850a42662f64
 SHA512:
-  metadata.gz: b4524b049a05c7dffe328ccb16742dede857b442b8dc5443ceddb9aad27c9b71ea7ab02bcf7d0d6b6fc724828587b3557d11042b939c15c97727d7ed048384e2
-  data.tar.gz: 74811080bd538e8b9023de303cbca5ade92c6005cb76aebd72e548c44b9504fae44dfa44055b7d34d2e157c5b779a330cc5da2c875fc485574728fcaaf237e26
+  metadata.gz: a6cc9bb4c0ba7b0c39ced816d8435370947d6e051df16d1d03a899c5fbbdd1a7ba1e0c7e0a05f7879874a4b20c5db7b2f7b639138eb0137bbb1276e1288b7b59
+  data.tar.gz: 12846d96eec9f9a3d681bdb1bd9a2e29807a21575adc209851bdb4b3067f8c5999732faa9a4bdfad0af1ac6e55cdac6f52c832d886623f137c8b0aa867bc5ba2

data/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.14] - 2026-08-27
+
+### Changed
+
+- **Writable documents memoize** — the versioned read cache. A
+  per-document mutation version advances at every mutation gate
+  (ensure_writable!, root=, add_pi); each memoized field carries
+  its own version stamp and recomputes after any bump. Readonly
+  semantics unchanged (their version never advances — memos
+  forever valid). Measured on writable documents: namespace
+  inspection 0.392 s -> 0.013 s (**31x**, readonly parity),
+  children 0.154 s -> 0.014 s (**11x**). The read-heavy
+  DOM-editing workload (parse, query repeatedly, mutate
+  occasionally) now performs like the readonly one between
+  mutations. Staleness is test-pinned: a mutation-invalidation
+  matrix covers content, attribute, structural, namespace, root=,
+  and PI mutations against every memoized read. The shared
+  node-level stamp variant was tried and rejected in favor of
+  per-field stamps (one field's recompute must not resurrect
+  another's stale memo). ADR 0003 extended.
+- NodeSet#[] drops the Ruby-side bounds FFI (the C accessor
+  already returns NULL out of range).
+
+## [1.9.13] - 2026-08-27
+
+### Changed
+
+- **Cached-true readonly guard**: readonly is one-way, so a node
+  caches TRUE once observed (FALSE stays uncached — the document
+  may still flip). Per-read guards drop from a three-call document
+  round-trip to one ivar check. Harness attr loop 0.061 -> 0.048 s.
+- **Lazy wrapper-cache allocation**: Documents no longer allocate
+  the wrapper-identity Hash up front; parse-heavy loops that free
+  before re-reading stop paying it (~9% on the tiny-doc
+  parse-query-serialize loop). Identity semantics unchanged.
+
+### Measured dead
+
+- Further readonly-[] trimming: the isolated read is at the Ruby
+  call-chain floor (~227 ns across ~7 calls); inlining the
+  attributes build would duplicate memo logic for ~10%.
+
 ## [1.9.12] - 2026-08-27
 
 ### Changed

data/docs/adr/0003-readonly-memoization-pattern.md

@@ -1,4 +1,20 @@
-# ADR 0003: readonly memoization stays hand-rolled
+# ADR 0003: memoization stays hand-rolled; writable docs memoize via version stamps
+
+## 2026-08-27 extension (leptris-ruby 1.9.14)
+
+Writable documents now memoize too: Document carries a mutation
+version advanced at every mutation gate (Node#ensure_writable!,
+root=, add_pi), and each memoized field stores its OWN version
+stamp (`return @x if memo_hit?(@x_version)`). A shared node-level
+stamp was tried and rejected — one field's recompute resurrects
+another field's stale memo. Readonly semantics are unchanged
+(their version never advances). Round X's "version-stamp rejected:
+the compare costs the read" was corrected: the compare is cheap
+against multi-FFI reads.
+
+The hand-rolled per-site pattern (below) still stands; only the
+guard gained a version argument.
+
 
 ## Context
 Every readonly-mode read repeats the same three lines:

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.12"
+  VERSION = "1.9.14"
 end

data/lib/leptris/xml/cdata.rb

@@ -4,11 +4,14 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   def name; "#cdata-section"; end
 
   def content
-    return @content if readonly_cached?(:@content)
+    return @content if memo_hit?(@content_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr).tap do |text|
-      @content = text if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr)
+    if @document
+      @content = result
+      @content_version = @document.version
     end
+    result
   end
 
   def content=(new_content)

data/lib/leptris/xml/comment.rb

@@ -4,11 +4,14 @@ class Leptris::XML::Comment < Leptris::XML::Node
   def name; "comment"; end
 
   def content
-    return @content if readonly_cached?(:@content)
+    return @content if memo_hit?(@content_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr).tap do |text|
-      @content = text if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr)
+    if @document
+      @content = result
+      @content_version = @document.version
     end
+    result
   end
 
   def content=(new_content)

data/lib/leptris/xml/document.rb

@@ -3,7 +3,7 @@
 require "ffi"
 
 class Leptris::XML::Document
-  attr_reader :c_ptr, :wrapper_cache
+  attr_reader :c_ptr
 
   # @api private
   # Internal flag container shared between the Document instance and its
@@ -14,10 +14,27 @@ class Leptris::XML::Document
   # `Document#free` was called explicitly and then GC ran.
   Freed = Struct.new(:state)  # state: :alive | :freed
 
+  # Mutation version: advanced by every data mutation (via
+  # Node#ensure_writable!, root=, add_pi). Node memos stamp the
+  # version they were computed under and recompute after any bump —
+  # the invalidation that makes WRITABLE-document memoization sound.
+  # Readonly documents never advance it, so their memos are forever
+  # valid (ADR 0003 semantics, unchanged).
+  def version
+    @version
+  end
+
+  # Called by the mutation gates (Node#ensure_writable!, root=,
+  # add_pi) — every memo stamped with an older version discards.
+  def advance_version
+    @version += 1
+  end
+
   def initialize(c_ptr = nil, freed = Freed.new(:alive))
     @c_ptr = c_ptr
     @freed = freed
     @readonly = false
+    @version = 0
     # Per-document STRONG cache for Node wrappers, keyed on c_ptr
     # address. Every wrapper is created through Node.wrap, which is the
     # single construction path, so the same C node always yields the
@@ -31,7 +48,13 @@ class Leptris::XML::Document
     # the weak map — any GC sweep evicted it and the second call built
     # a fresh object. A strong cache costs at most one wrapper per node
     # actually visited, held until the document dies.
-    @wrapper_cache = {}
+    #
+    # Allocated lazily: parse-heavy loops stop paying one Hash per
+    # document for trees that are freed before any wrap.
+  end
+
+  def wrapper_cache
+    @wrapper_cache ||= {}
   end
 
   def self.parse(xml_or_io, options: nil, readonly: false, recover: false)
@@ -136,6 +159,7 @@ class Leptris::XML::Document
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_document_set_root(@c_ptr, element.c_ptr))
+    @version += 1
     element
   end
 
@@ -230,7 +254,7 @@ class Leptris::XML::Document
     @freed.state = :freed
     Leptris::XML::FFI.leptris_document_free(@c_ptr) unless @c_ptr.nil?
     @c_ptr = nil
-    @wrapper_cache.clear
+    @wrapper_cache&.clear
   end
 
   # Enable the first-party EXSLT-style extension pack on this
@@ -247,15 +271,14 @@ class Leptris::XML::Document
   # Document-level processing instructions (not tree nodes):
   # an array of [target, data] pairs in document order.
   def processing_instructions
-    if readonly? && instance_variable_defined?(:@processing_instructions)
-      return @processing_instructions
-    end
+    return @processing_instructions if @pi_version == @version
     count = Leptris::XML::FFI.leptris_document_pi_count(@c_ptr)
     result = count.times.map do |i|
       [Leptris::XML::FFI.leptris_document_pi_target(@c_ptr, i),
        Leptris::XML::FFI.leptris_document_pi_data(@c_ptr, i)]
     end
-    @processing_instructions = result if readonly?
+    @processing_instructions = result
+    @pi_version = @version
     result
   end
 
@@ -264,6 +287,7 @@ class Leptris::XML::Document
     witness = Leptris::XML::FFI.leptris_document_add_pi(
       @c_ptr, target.to_s, data.to_s)
     raise Leptris::XML::Error, "leptris_document_add_pi failed" if witness.null?
+    @version += 1
     self
   end
 

data/lib/leptris/xml/element.rb

@@ -17,11 +17,14 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :node_name=, :name=
 
   def content
-    return @content if readonly_cached?(:@content)
+    return @content if memo_hit?(@content_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_element_text(@c_ptr).tap do |text|
-      @content = text if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_element_text(@c_ptr)
+    if @document
+      @content = result
+      @content_version = @document.version
     end
+    result
   end
 
   def content=(new_content)
@@ -36,7 +39,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     # materializes on demand — repeated reads become hash lookups,
     # with no dispatch and no lifetime guard (a hash read cannot
     # use-after-free).
-    if @document&.readonly?
+    if readonly_document?
       cached = attributes[key.to_s]
       return cached.nil? ? nil : cached.value
     end
@@ -104,31 +107,43 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def keys
-    return @keys if readonly_cached?(:@keys)
+    return @keys if memo_hit?(@keys_version)
     result = each_attribute.to_a.map(&:name)
-    @keys = result if @document&.readonly?
+    if @document
+      @keys = result
+      @keys_version = @document.version
+    end
     result
   end
 
   def values
-    return @values if readonly_cached?(:@values)
+    return @values if memo_hit?(@values_version)
     result = each_attribute.to_a.map(&:value)
-    @values = result if @document&.readonly?
+    if @document
+      @values = result
+      @values_version = @document.version
+    end
     result
   end
 
   def attributes
-    return @attributes if readonly_cached?(:@attributes)
+    return @attributes if memo_hit?(@attributes_version)
     result = {}
     each_attribute { |attr| result[attr.name] = attr }
-    @attributes = result if @document&.readonly?
+    if @document
+      @attributes = result
+      @attributes_version = @document.version
+    end
     result
   end
 
   def attribute_nodes
-    return @attribute_nodes if readonly_cached?(:@attribute_nodes)
+    return @attribute_nodes if memo_hit?(@attribute_nodes_version)
     result = each_attribute.to_a
-    @attribute_nodes = result if @document&.readonly?
+    if @document
+      @attribute_nodes = result
+      @attribute_nodes_version = @document.version
+    end
     result
   end
 
@@ -247,7 +262,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :<<, :add_child
 
   def namespace
-    return @namespace if readonly_cached?(:@namespace)
+    return @namespace if memo_hit?(@namespace_version)
     ensure_alive!
     uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
     result =
@@ -261,12 +276,15 @@ class Leptris::XML::Element < Leptris::XML::Node
         prefix = nil if prefix.nil? || prefix.empty?
         Leptris::XML::Namespace.new(self, uri, prefix: prefix)
       end
-    @namespace = result if @document&.readonly?
+    if @document
+      @namespace = result
+      @namespace_version = @document.version
+    end
     result
   end
 
   def namespace_definitions
-    return @namespace_definitions if readonly_cached?(:@namespace_definitions)
+    return @namespace_definitions if memo_hit?(@namespace_definitions_version)
     ensure_alive!
     count = Leptris::XML::FFI.leptris_element_namespace_count(@c_ptr)
     result = count.times.map do |i|
@@ -274,12 +292,15 @@ class Leptris::XML::Element < Leptris::XML::Node
       uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@c_ptr, i)
       Leptris::XML::Namespace.new(self, uri, prefix: prefix)
     end
-    @namespace_definitions = result if @document&.readonly?
+    if @document
+      @namespace_definitions = result
+      @namespace_definitions_version = @document.version
+    end
     result
   end
 
   def namespaces
-    return @namespaces if readonly_cached?(:@namespaces)
+    return @namespaces if memo_hit?(@namespaces_version)
     scopes = {}
     node = self
     while node.is_a?(Leptris::XML::Element)
@@ -289,7 +310,10 @@ class Leptris::XML::Element < Leptris::XML::Node
       end
       node = node.parent
     end
-    @namespaces = scopes if @document&.readonly?
+    if @document
+      @namespaces = scopes
+      @namespaces_version = @document.version
+    end
     scopes
   end
 

data/lib/leptris/xml/node.rb

@@ -101,13 +101,29 @@ class Leptris::XML::Node
   end
 
   # Raises ReadOnlyError when the owning document was marked readonly,
-  # UseAfterFreeError when it was freed.
+  # UseAfterFreeError when it was freed. Every node-level mutation
+  # passes through this gate, so it is where the document's mutation
+  # version advances — the invalidation behind writable-document
+  # memoization. Bumping before the C call is conservative: a failed
+  # mutation merely discards memos.
   def ensure_writable!
     ensure_alive!
-    if @document&.readonly?
+    if readonly_document?
       raise Leptris::XML::ReadOnlyError,
         "document is readonly — mutation attempted on #{inspect}"
     end
+    @document.advance_version
+    nil
+  end
+
+  # Readonly is one-way, so caching TRUE is sound: once observed,
+  # the document is readonly forever. FALSE stays uncached (the
+  # document may still flip). Saves the document round-trip on
+  # per-read guards.
+  def readonly_document?
+    return true if instance_variable_defined?(:@readonly_document)
+    return false unless @document&.readonly?
+    @readonly_document = true
   end
 
   def line
@@ -132,14 +148,17 @@ class Leptris::XML::Node
   def children
     # Immutable in readonly mode: the batch fetch plus wrapper
     # construction is paid once.
-    return @children if readonly_cached?(:@children)
+    return @children if memo_hit?(@children_version)
     ensure_alive!
     parent = as_element_or_self
     nodes = Leptris::XML::FFI.fetch_children(@c_ptr).map do |ptr|
       Leptris::XML::Node.wrap(ptr, @document, parent: parent)
     end
     result = Leptris::XML::NodeSet.new(@document, nodes)
-    @children = result if @document&.readonly?
+    if @document
+      @children = result
+      @children_version = @document.version
+    end
     result
   end
 
@@ -175,9 +194,12 @@ class Leptris::XML::Node
   end
 
   def element_children
-    return @element_children if readonly_cached?(:@element_children)
+    return @element_children if memo_hit?(@element_children_version)
     result = children.select(&:element?)
-    @element_children = result if @document&.readonly?
+    if @document
+      @element_children = result
+      @element_children_version = @document.version
+    end
     result
   end
   alias_method :elements, :element_children
@@ -220,16 +242,19 @@ class Leptris::XML::Node
   end
 
   def path
-    return @path if readonly_cached?(:@path)
+    return @path if memo_hit?(@path_version)
     ensure_alive!
     str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(@c_ptr)
     result = str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
-    @path = result if @document&.readonly?
+    if @document
+      @path = result
+      @path_version = @document.version
+    end
     result
   end
 
   def css_path
-    return @css_path if readonly_cached?(:@css_path)
+    return @css_path if memo_hit?(@css_path_version)
     result =
       if path.nil?
         nil
@@ -239,7 +264,10 @@ class Leptris::XML::Node
           part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
         end.join(" > ")
       end
-    @css_path = result if @document&.readonly?
+    if @document
+      @css_path = result
+      @css_path_version = @document.version
+    end
     result
   end
 
@@ -264,11 +292,15 @@ class Leptris::XML::Node
 
   protected
 
-  # Memo presence alone proves readonly: every memo site assigns
-  # only under readonly, and readonly is one-way — so the guard
-  # saves the document round-trip on every memoized read.
-  def readonly_cached?(ivar)
-    instance_variable_defined?(ivar)
+  # A memo is valid while the document's mutation version has not
+  # advanced since that memo was stored. Each memoized field carries
+  # its OWN stamp — a shared node-level stamp would let one field's
+  # recompute resurrect another field's stale memo. Readonly
+  # documents never advance the version, so their memos are forever
+  # valid (ADR 0003 semantics); writable documents gain memos
+  # between mutations.
+  def memo_hit?(stamp)
+    @document && stamp == @document.version
   end
 
   def as_element_or_self

data/lib/leptris/xml/node_set.rb

@@ -60,7 +60,6 @@ class Leptris::XML::NodeSet
     # inconsistently with an eager set.
     return to_a[idx] if idx.negative?
     if @result_ptr
-      return nil if idx < 0 || idx >= length
       ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, idx)
       return nil if ptr.null?
       Leptris::XML::Node.wrap(ptr, @document)

data/lib/leptris/xml/processing_instruction.rb

@@ -2,20 +2,26 @@
 
 class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def name
-    return @name if readonly_cached?(:@name)
+    return @name if memo_hit?(@name_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr).tap do |target|
-      @name = target if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr)
+    if @document
+      @name = result
+      @name_version = @document.version
     end
+    result
   end
   alias_method :target, :name
 
   def content
-    return @content if readonly_cached?(:@content)
+    return @content if memo_hit?(@content_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s.tap do |data|
-      @content = data if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s
+    if @document
+      @content = result
+      @content_version = @document.version
     end
+    result
   end
 
   def target=(new_target)

data/lib/leptris/xml/text.rb

@@ -4,11 +4,14 @@ class Leptris::XML::Text < Leptris::XML::Node
   def name; "text"; end
 
   def content
-    return @content if readonly_cached?(:@content)
+    return @content if memo_hit?(@content_version)
     ensure_alive!
-    Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr).tap do |text|
-      @content = text if @document&.readonly?
+    result = Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr)
+    if @document
+      @content = result
+      @content_version = @document.version
     end
+    result
   end
 
   def content=(new_content)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.12
+  version: 1.9.14
 platform: aarch64-linux
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi