leptris 1.9.13 → 1.9.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 590285b33ed6aac05def5ff85268822fc6d5abf87cfd5b262d51b72868f70ac3
-  data.tar.gz: 8dc09c12f495c12177a5dd15ff8892340dc090d678eb342738571bfb0e142228
+  metadata.gz: c1b73d7abca12056f163aed086825140416384075955e593f11191156db475fc
+  data.tar.gz: ead9075339cfd0736ca79cbede18612702f4632c95d9d90a512f67b3e4c32ec7
 SHA512:
-  metadata.gz: 2781b4465ff07a85ea7ecc91824070da8412aa933bc96273a4b9159860c95a0e227e06630967685e66db9fd696a6e5648ec9474217ecae769b8163096adf18ed
-  data.tar.gz: 9d7173b435723be6f068700e27e05f796246143dcf22dd1319079c5770a71f3f933fdd7d517a71ee47cba58f1305ed2d2e270ffaee43c422c43d693dbb77f4f7
+  metadata.gz: 22ec81a95a094913096d9c0749c42a64274f7af9225c4128b51529c8160f6480d3f23476b548f7c766202be9744dee9a830eaa715dbeea77a42e4d374f61b6e5
+  data.tar.gz: 5e5408837f3ca2b4b54e4069a36798000b67d87fee9ed7021927b4e6c8b95d6a04a9f9d770fcd786763569d700182f87fc5b7df54c14462391c0420f69d108ed

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.15] - 2026-08-27
+
+### Changed
+
+- **`Element#[]` serves bare names from the versioned attributes
+  hash on every document kind** (writable included): materializes
+  on demand, invalidates through the mutation gate. Qualified names
+  (with a colon) still route to the engine — they resolve through
+  in-scope declarations where the written prefix never matters,
+  which a written-name-keyed hash cannot answer. Writable
+  attribute loops reach readonly parity: 0.196 s -> 0.101 s (2x);
+  the readonly special-case branch is deleted. The qualified/bare
+  split is spec-pinned (cross-prefix match, undeclared-prefix nil).
+- **`first_element_child` memoizes** with version invalidation
+  (structural mutations bump): 0.058 s -> 0.015 s (4x) on the
+  repeat loop.
+
+## [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

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.13"
+  VERSION = "1.9.15"
 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

@@ -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
@@ -142,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
 
@@ -253,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
 
@@ -270,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)
@@ -32,16 +35,20 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def [](key)
-    # Readonly: the attributes hash cannot go stale (ADR 0003) and
-    # materializes on demand — repeated reads become hash lookups,
-    # with no dispatch and no lifetime guard (a hash read cannot
-    # use-after-free).
-    if readonly_document?
-      cached = attributes[key.to_s]
+    # BARE names serve from the versioned attributes hash (written
+    # name == the only legal key for a no-namespace attribute);
+    # materializes on demand, invalidates through the mutation gate
+    # (ADR 0003's 1.9.14 extension); a hash read cannot
+    # use-after-free. QUALIFIED names (with a colon) go to the
+    # engine: they resolve through in-scope declarations, where the
+    # written prefix never matters — the hash cannot answer them.
+    name = key.to_s
+    if @document && !name.include?(":")
+      cached = attributes[name]
       return cached.nil? ? nil : cached.value
     end
     ensure_alive!
-    Leptris::XML::FFI.leptris_element_attribute(@c_ptr, key.to_s)
+    Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
   end
   alias_method :attr, :[]
   alias_method :get_attribute, :[]
@@ -104,31 +111,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 +266,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 +280,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 +296,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 +314,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,19 @@ 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 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,
@@ -142,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
 
@@ -170,14 +179,23 @@ class Leptris::XML::Node
   alias_method :previous, :previous_sibling
 
   def first_element_child
+    return @first_element_child if memo_hit?(@first_element_child_version)
     ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    result = nil
     until ptr.nil? || ptr.null?
       node = Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
-      return node if node.element?
+      if node.element?
+        result = node
+        break
+      end
       ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
     end
-    nil
+    if @document
+      @first_element_child = result
+      @first_element_child_version = @document.version
+    end
+    result
   end
 
   def last_element_child
@@ -185,9 +203,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
@@ -230,16 +251,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
@@ -249,7 +273,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
 
@@ -274,11 +301,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.13
+  version: 1.9.15
 platform: ruby
 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