parsanol 1.3.109-aarch64-linux → 1.3.112-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c17015cb92f4e965c312eb69e7bb14e212700d6660650061ccfb0bb59da35cde
-  data.tar.gz: d246068f5c2b4b6bfe56aac5da14e450b29a8b39f36836ea5da65ab2d15a56af
+  metadata.gz: e622ed0c55dbbcc4295a1b3740c36e0dc725a89251eb36c7799d6b60dbb026ff
+  data.tar.gz: d6d4c119f0e08a8b167faae5f1bb8203cf1f18d77d9cebd132a8bed6c2817882
 SHA512:
-  metadata.gz: fe6458c0af76600f87a58c24c00405e0148dfd50aa75b694761f1c2a88a480ed9a8113419f65eaf8407dcdcfe5ae2e4b920df995018ad8d6440d45962619d4fb
-  data.tar.gz: e14f4c3c3bc2ed0decdae5d6339b6d06c7978f7e75e767a4f8a2cc48ffb93ae461792660eae5d81e6b26d60ddb6c248cda296834cc63acb4de98a13462150a04
+  metadata.gz: 6db2994d50d7d9e77a5a9b6614d3b0b461a623d06372bace9d30e9c45e09f6f55aa4efffbaa411ff00462e93e1f8b4681edc9229a15b391034293875a319846b
+  data.tar.gz: 4a36caf756fb3e162bdbe24235f1005a1a56e322677e86e2606900441994dbe6107ca8ce4822d02314bdda6bc38fb246dbd9767f1e816566daea4482e0ea558f

data/lib/parsanol/3.2/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.2/parsanol_native.so
-size: 42420800 bytes
-sha256: 81dd5dcbde9d4188c86c316102dabdb522048fe218134d89180db1334f5d2e77
+size: 45892256 bytes
+sha256: baf93c649b2dc899fc6b6a9e42d2f83ba44c08738db11fbb3ce74c1788507e55

data/lib/parsanol/3.3/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.3/parsanol_native.so
-size: 42655808 bytes
-sha256: 3c87af92ff773b9d78c286d55c8c82c7fd11d1331e0a09ca9942c28fc184ac47
+size: 46127304 bytes
+sha256: 542480a12619696edd8e73bbb30d995b2ed2bae78f660050ea5f3cbcbc39f94c

data/lib/parsanol/3.4/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.4/parsanol_native.so
-size: 42651368 bytes
-sha256: 4bc273e8b1473a31c24ef9b882ee53b001a337c620467000fe4021954bb640eb
+size: 46122944 bytes
+sha256: d01871833b692c8d59f1d88b7c69792d1c44ed14fa9d62180534cabf508eb440

data/lib/parsanol/4.0/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/4.0/parsanol_native.so
-size: 42661424 bytes
-sha256: 6c9c533b9b53407c3ef7c2c789c610fe35e860a470d7406dad4629be3f94cbf5
+size: 46132984 bytes
+sha256: a3d424e1bdd7e31770de8e830d3531df4010f7cb1ef5d9e10a9da04d1ac935b2

data/lib/parsanol/atoms/repetition.rb

@@ -195,8 +195,19 @@ module Parsanol
 
           unless success
             last_failure = value
+            if ENV["PARSANOL_REP_TRACE"]
+              warn "REP body FAIL at iter=#{occurrence} start=#{iteration_start} pos_after=#{source.bytepos} restoring"
+            end
+            # A failed iteration may have consumed input before its own
+            # inner failure (an ordered choice's partial alternative);
+            # the repetition owns the rollback — the rep ends at the
+            # last SUCCESSFUL iteration's end (ruby#357).
+            source.bytepos = iteration_start
             break
           end
+          if ENV["PARSANOL_REP_TRACE"]
+            warn "REP body OK at iter=#{occurrence} start=#{iteration_start} end=#{source.bytepos}"
+          end
 
           occurrence += 1
           result[occurrence] = value
@@ -276,8 +287,19 @@ module Parsanol
 
           unless success
             last_failure = value
+            if ENV["PARSANOL_REP_TRACE"]
+              warn "REP body FAIL at iter=#{occurrence} start=#{iteration_start} pos_after=#{source.bytepos} restoring"
+            end
+            # A failed iteration may have consumed input before its own
+            # inner failure (an ordered choice's partial alternative);
+            # the repetition owns the rollback — the rep ends at the
+            # last SUCCESSFUL iteration's end (ruby#357).
+            source.bytepos = iteration_start
             break
           end
+          if ENV["PARSANOL_REP_TRACE"]
+            warn "REP body OK at iter=#{occurrence} start=#{iteration_start} end=#{source.bytepos}"
+          end
 
           occurrence += 1
           result[occurrence] = value

data/lib/parsanol/native/libparsanol.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/native/libparsanol.so
-size: 36759888 bytes
-sha256: 885d841e5628d9fae0b43e78bd28ef5f27195ca0f3b543d35aaba7e8167ef2f4
+size: 41651720 bytes
+sha256: cff3505da15196c090a20db6db228680d94b0467a1daa0d28ebc1e22f2066145

data/lib/parsanol/parg/artifact.rb

@@ -26,6 +26,10 @@ module Parsanol
 
       SUPPORTED_SHAPE = "parsanol-tree/v2"
 
+      # The editions this runtime parses (ruby#357's consolidation):
+      # v1 = the legacy shapes; v2 = named trees + explicit spans.
+      SUPPORTED_EDITIONS = %w[v1 v2].freeze
+
       def initialize(envelope, path, tables_dir, imports_dir: nil)
         unless envelope["shape"] == SUPPORTED_SHAPE
           raise ArtifactError,
@@ -38,6 +42,18 @@ module Parsanol
         bindings = envelope["bindings"]
         validate_bindings!(bindings) unless bindings.nil?
         @envelope = envelope
+        # ruby#353: absent field = the pre-1.3.109 semantics. A level
+        # above this runtime's is a hard error (the trees would carry
+        # nodes this engine never emits); a lower one warns — parsing
+        # works, but frozen tree comparisons will differ.
+        # The declared edition must be one this runtime understands
+        # (ruby#357's consolidation: one axis, `edition`, values v1/v2).
+        edition = envelope["edition"] || "v1"
+        unless SUPPORTED_EDITIONS.include?(edition)
+          raise ArtifactError,
+                "artifact declares edition #{edition.inspect}; this " \
+                "runtime supports #{SUPPORTED_EDITIONS.map(&:inspect).join(', ')}"
+        end
         @path = path
         @tables_dir = tables_dir
         # parsanol-ruby#208: `use`-importing grammars need the imported
@@ -233,13 +249,27 @@ module Parsanol
         # initial parse's (the native FFI's coarse failure position
         # loses the deepest offset).
         captures, reparse_error = recovery_journal(entry_name, input, mode)
-        partial = recovery_partial(entry_name)
+        # The spine boundary, not the failure offset, is where the
+        # resync scan starts (rs#304 convergence): junk frequently lies
+        # BEFORE the deepest failure (the failed iteration consumed its
+        # own prefix), and the scan from the failure offset can never
+        # match it. When no iteration matched, the boundary is 0 —
+        # recovery still runs (rs#304 Gap B: a declared pattern is
+        # usable from the start).
+        stash = Parsanol::Recovery.take_partial
+        partial = recovery_partial(entry_name, stash)
+        boundary = stash&.first || 0
         resyncs = []
-        if partial && reparse_error
-          items = partial.values.first
-          extended, resyncs = resync_extension(entry_name, input,
-                                               reparse_error["offset"])
-          items.concat(extended) if extended
+        if reparse_error
+          root_name = entry(entry_name)["root"].to_sym
+          items = partial&.values&.first
+          created_partial = items.nil?
+          items ||= []
+          extended, resyncs = resync_extension(entry_name, input, boundary)
+          items.concat(extended)
+          # Recovered iterations with no prior partial form the partial
+          # (the rs engine's stash exists from offset 0).
+          partial = { root_name => items } if created_partial && !items.empty?
         end
         { "ok" => false,
           "error" => reparse_error || recovery_error(e),
@@ -367,8 +397,7 @@ module Parsanol
       # R1.5 (TODO.sota/1): the deepest repetition prefix the failed
       # journaling pass matched, shaped like the root (the item array
       # under the root rule's name). Nil when nothing matched.
-      def recovery_partial(entry_name)
-        stash = Parsanol::Recovery.take_partial
+      def recovery_partial(entry_name, stash = Parsanol::Recovery.take_partial)
         return nil if stash.nil?
 
         _end_pos, items, _tag = stash

data/lib/parsanol/parg/authoring.rb

@@ -64,22 +64,213 @@ module Parsanol
         end
       end
 
+      # The bound model's shape: a nested type tree derived from the
+      # binding paths (ruby#308 v2). Dot segments nest objects, a
+      # `[]` segment is an array of objects (or of leaf values when
+      # the array is itself the leaf), and the leaf carries the
+      # binding's type and card (`0..1` = nullable, `*` cards arrive
+      # through the array node itself).
+      #
+      #   shape({ "items[].n" => { "type" => "integer", "card" => "1" } })
+      #   # => { "items" => { "kind" => "array",
+      #   #                    "of" => { "n" => { "kind" => "leaf", "type" => "integer", "card" => "1" } } } }
+      def shape(fields)
+        root = {}
+        fields.each do |path, requirements|
+          segments = path.split(".")
+          node = root
+          segments.each_with_index do |segment, index|
+            array = segment.end_with?("[]")
+            name = array ? segment.delete_suffix("[]") : segment
+            leaf = index == segments.length - 1
+            if array && leaf
+              node[name] = {
+                "kind" => "array",
+                "of" => { "kind" => "leaf", "type" => requirements["type"], "card" => requirements["card"] },
+              }
+              break
+            end
+            slot = (node[name] ||= array ? { "kind" => "array", "of" => {} } : {})
+            node = array ? slot["of"] : slot
+            next unless leaf
+
+            slot.update("kind" => "leaf", "type" => requirements["type"], "card" => requirements["card"])
+          end
+        end
+        root
+      end
+
       # TypeScript materialization types: one interface per entry, one
-      # property per bound field. Cards ending in * become arrays;
+      # interface per nested object node (v2: the interfaces mirror
+      # the bound model's shape). Cards ending in * become arrays;
       # 0..1 becomes nullable.
       def to_typescript(schema)
         lines = ["// Generated by parsanol parg schema --ts — binding-requirements types."]
         schema.each do |entry, data|
           lines << ""
-          lines << "export interface #{ts_name(entry)} {"
-          data["fields"].each do |path, requirements|
-            lines << "  #{ts_prop(path)}: #{ts_type(requirements)};"
+          emit_ts_interface(lines, ts_name(entry), shape(data["fields"]))
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      def emit_ts_interface(lines, name, node)
+        nested = []
+        lines << "export interface #{name} {"
+        node.each do |prop, child|
+          case child["kind"]
+          when "array"
+            element = child["of"]
+            inner = element["kind"] == "leaf" ? ts_leaf(element) : ts_ref_name(name, prop)
+            lines << "  #{ts_prop(prop)}: #{inner}[];"
+            nested << [ts_ref_name(name, prop), element] unless element["kind"] == "leaf"
+          when "leaf"
+            lines << "  #{ts_prop(prop)}: #{ts_leaf(child)};"
           end
-          lines << "}"
+        end
+        lines << "}"
+        lines << ""
+        nested.each { |inner, element| emit_ts_interface(lines, inner, element) }
+      end
+
+      def ts_leaf(leaf)
+        base = ts_base(leaf["type"])
+        if leaf["card"].to_s.end_with?("*")
+          "#{base}[]"
+        elsif leaf["card"] == "0..1"
+          "#{base} | null"
+        else
+          base
+        end
+      end
+
+      def ts_base(type)
+        case type
+        when "integer", "float" then "number"
+        when "boolean" then "boolean"
+        else "string"
+        end
+      end
+
+      def ts_ref_name(parent, prop)
+        "#{parent}#{ts_prop(prop).split('.').map(&:capitalize).join}"
+      end
+
+      # Ruby materialization models: lutaml-model classes (the
+      # established serialization framework — the generated file
+      # requires it; the consumer's bundle carries the gem).
+      def to_ruby(schema)
+        lines = [
+          "# frozen_string_literal: true",
+          "",
+          "# Generated by parsanol parg schema --ruby — lutaml-model binding types.",
+          "require \"lutaml/model\"",
+          "",
+        ]
+        schema.each do |entry, data|
+          emit_ruby_class(lines, ts_name(entry), shape(data["fields"]))
         end
         "#{lines.join("\n")}\n"
       end
 
+      def emit_ruby_class(lines, name, node)
+        nested = []
+        node.each do |prop, child|
+          next unless child["kind"] == "array" && child["of"]["kind"] != "leaf"
+
+          inner = lutaml_ref_name(name, prop)
+          nested << [inner, child["of"]]
+        end
+        # Ruby resolves the constant at class-body time: the nested
+        # models precede their parents.
+        nested.each { |inner, element| emit_ruby_class(lines, inner, element) }
+        lines << "class #{name} < Lutaml::Model::Serializable"
+        lines <<
+          node.each do |prop, child|
+            attr_name = ts_prop(prop)
+            case child["kind"]
+            when "array"
+              element = child["of"]
+              if element["kind"] == "leaf"
+                lines << "  attribute :#{attr_name}, #{lutaml_type(element)}, collection: true"
+              else
+                inner = lutaml_ref_name(name, prop)
+                lines << "  attribute :#{attr_name}, #{inner}, collection: true"
+                nested << [inner, element]
+              end
+            when "leaf"
+              # lutaml-model attributes are nilable unless validated:
+              # a 0..1 card is the plain attribute; presence-validated
+              # cards are the consumer's policy, not the schema's.
+              lines << "  attribute :#{attr_name}, #{lutaml_type(child)}"
+            end
+          end
+        lines << "end"
+        lines << ""
+      end
+
+      def lutaml_type(leaf)
+        case leaf["type"]
+        when "integer" then ":integer"
+        when "float" then ":float"
+        when "boolean" then ":boolean"
+        else ":string"
+        end
+      end
+
+      def lutaml_ref_name(parent, prop)
+        "#{parent}#{ts_prop(prop).split('.').map(&:capitalize).join}"
+      end
+
+      # Rust materialization structs (serde): one struct per nested
+      # object node, i64/f64/bool/String leaves, Vec for arrays,
+      # Option for 0..1.
+      def to_rust(schema)
+        lines = [
+          "// Generated by parsanol parg schema --rust — serde binding types.",
+          "",
+        ]
+        schema.each do |entry, data|
+          emit_rust_struct(lines, ts_name(entry), shape(data["fields"]))
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      def emit_rust_struct(lines, name, node)
+        nested = []
+        lines << "#[derive(Debug, serde::Serialize, serde::Deserialize)]"
+        lines << "pub struct #{name} {"
+        node.each do |prop, child|
+          field = ts_prop(prop)
+          snake = field.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }
+          case child["kind"]
+          when "array"
+            element = child["of"]
+            inner = element["kind"] == "leaf" ? rust_leaf(element) : rust_ref_name(name, prop)
+            lines << "    pub #{snake}: Vec<#{inner}>,"
+            nested << [rust_ref_name(name, prop), element] unless element["kind"] == "leaf"
+          when "leaf"
+            base = rust_leaf(child)
+            lines << "    pub #{snake}: #{child['card'] == '0..1' ? "Option<#{base}>" : base},"
+          end
+        end
+        lines << "}"
+        lines << ""
+        nested.each { |inner, element| emit_rust_struct(lines, inner, element) }
+      end
+
+      def rust_leaf(leaf)
+        case leaf["type"]
+        when "integer" then "i64"
+        when "float" then "f64"
+        when "boolean" then "bool"
+        else "String"
+        end
+      end
+
+      def rust_ref_name(parent, prop)
+        ts_ref_name(parent, prop)
+      end
+
       def ts_name(entry)
         entry.split(/[_.]/).map(&:capitalize).join
       end

data/lib/parsanol/parg/cli.rb

@@ -116,6 +116,7 @@ module Parsanol
       # upgrade suggestions on top.
       def lint
         source = @argv.shift
+        @captures_radar = @argv.delete("--captures") ? true : false
         tables = @tables_dir || default_tables_dir(source)
         document = Parsanol::PARG::Parser.new(PARG.read_utf8(source)).parse
         Parsanol::PARG::Imports.merge!(document, [File.dirname(source)])
@@ -131,6 +132,10 @@ module Parsanol
           Lints::CoreRuleDuplicates.new.warnings(document, compiler)
             .each { |upgrade| puts "upgrade: #{upgrade}" }
         end
+        if @captures_radar
+          # The migration radar (ruby#304): what modern mode would name.
+          compiler.modern_radar.each { |line| puts "captures: #{line}" }
+        end
         0
       rescue Parsanol::PARG::ParseError, Parsanol::PARG::Error => e
         warn "#{e.class}: #{e.message}"
@@ -205,10 +210,16 @@ module Parsanol
 
       def schema
         ts = @argv.delete("--ts")
+        ruby = @argv.delete("--ruby")
+        rust = @argv.delete("--rust")
         artifact = artifact_for(@argv.shift)
         schema = Parsanol::PARG::Schema.from_artifact(artifact)
         if ts
           puts Parsanol::PARG::Schema.to_typescript(schema)
+        elsif ruby
+          puts Parsanol::PARG::Schema.to_ruby(schema)
+        elsif rust
+          puts Parsanol::PARG::Schema.to_rust(schema)
         else
           puts JSON.pretty_generate(schema)
         end

data/lib/parsanol/parg/compiler.rb

@@ -228,6 +228,144 @@ module Parsanol
         @resync_cache[rule.to_sym] ||= build_atom(pattern)
       end
 
+      # Modern mode (ruby#304, the #315 spec): every rule reference
+      # that produces no capture is wrapped in Named(rule_name) at
+      # compile time — the tree shape consumers read, opt-in via
+      # `mode` in the grammar header. Engines see ordinary
+      # Named atoms; identity rides the differential corpus.
+      def apply_modern_captures(atom)
+        return atom if @document.edition == "v1"
+
+        wrap_uncaptured(atom)
+      end
+
+      def wrap_uncaptured(atom)
+        case atom
+        when Atoms::Named
+          atom
+        when Atoms::Entity
+          # A rule that can only match whitespace is glue, not a
+          # semantic capture (ruby#352): wrapping it named every gap
+          # in the tree and broke consumers that fold captures into
+          # parameters. Conservatively: the rule's body is literals
+          # (through sequence/alternation/repetition composition) and
+          # every literal strips to empty.
+          # rubocop:disable Lint/DuplicateBranch -- trivia-glue and
+          # capture-producing refs both stay unwrapped; the bodies
+          # agree by design.
+          if trivia_only?(atom.rule_name.to_s, { atom.rule_name.to_s => true }) ||
+              produces_capture?(atom.parslet)
+            atom
+          else
+            Atoms::Named.new(atom, atom.rule_name.to_s)
+          end
+          # rubocop:enable Lint/DuplicateBranch
+        when Atoms::Sequence, Atoms::Alternative
+          # rubocop:disable Lint/DuplicateBranch -- the two composites
+          # rebuild with their own constructors; identical bodies,
+          # different decisions
+          kids = atom.respond_to?(:alternatives) ? atom.alternatives : atom.parslets
+          atom.class.new(*kids.map { |child| wrap_uncaptured(child) })
+        when Atoms::Repetition
+          Atoms::Repetition.new(wrap_uncaptured(atom.parslet), atom.min, atom.max, atom.result_tag)
+        else
+          atom
+        end
+      end
+
+      # Whether the named rule's body is provably whitespace-only:
+      # literals strip to empty; sequence/alternation/repetition
+      # compose the verdict; references resolve through the atom cache
+      # with a cycle set; anything else (classes, customs, authored
+      # captures) disqualifies.
+      def trivia_only?(name, seen)
+        return false unless @document.rules.key?(name)
+
+        trivia_walk(atom_for(name), seen)
+      end
+
+      def trivia_walk(atom, seen)
+        case atom
+        when Atoms::Str
+          atom.str.to_s.strip.empty?
+        when Atoms::Sequence, Atoms::Alternative
+          kids = atom.respond_to?(:alternatives) ? atom.alternatives : atom.parslets
+          kids.all? { |child| trivia_walk(child, seen) }
+        when Atoms::Repetition
+          trivia_walk(atom.parslet, seen)
+        when Atoms::Entity
+          name = atom.rule_name.to_s
+          return false if seen[name]
+
+          seen[name] = true
+          trivia_only?(name, seen)
+        else
+          false
+        end
+      end
+
+      # Whether the atom's flattening surfaces any Named capture:
+      # rule references resolve through (their own wrap pass already
+      # ran — a wrapped ref produces a capture), trivia never
+      # surfaces, everything else recurses structurally.
+      def produces_capture?(atom, seen = [])
+        return false if seen.include?(atom.object_id)
+
+        seen << atom.object_id
+        case atom
+        when Atoms::Named then true
+        when Atoms::Entity
+          wrapped = atom.parslet.is_a?(Atoms::Named)
+          wrapped || produces_capture?(atom.parslet, seen)
+        when Atoms::Sequence, Atoms::Alternative
+          kids = atom.respond_to?(:alternatives) ? atom.alternatives : atom.parslets
+          kids.any? { |child| produces_capture?(child, seen) }
+        when Atoms::Repetition
+          produces_capture?(atom.parslet, seen)
+        else
+          false
+        end
+      end
+
+      # The migration radar (ruby#304 `parg lint --captures`): for a
+      # LEGACY grammar, every rule reference modern mode would wrap —
+      # reference site, target rule. The compiler's state is warm
+      # (all rules built) when the lint calls this.
+      def modern_radar
+        # The radar is the classic dialect's migration tool: on a v2
+        # grammar every reference is already named.
+        return [] if @document.edition != "v1"
+
+        lines = []
+        @document.rules.each_key do |name|
+          atom = @atom_cache[name]
+          next unless atom
+
+          radar_walk(atom, name, lines, [])
+        end
+        lines
+      end
+
+      def radar_walk(atom, site, lines, seen)
+        return if seen.include?(atom.object_id)
+
+        seen << atom.object_id
+        case atom
+        when Atoms::Named then nil
+        when Atoms::Entity
+          unless produces_capture?(atom.parslet)
+            lines << "rule #{site}: reference to #{atom.rule_name} produces no capture -- " \
+                     "modern mode would name it #{atom.rule_name}"
+          end
+          radar_walk(atom.parslet, site, lines, seen)
+        when Atoms::Sequence, Atoms::Alternative
+          kids = atom.respond_to?(:alternatives) ? atom.alternatives : atom.parslets
+          kids.each { |child| radar_walk(child, site, lines, seen) }
+        when Atoms::Repetition
+          radar_walk(atom.parslet, site, lines, seen)
+        end
+      end
+
       def atom_for(name)
         inject_core_rules!
         expand_left_recursion! unless @expanded
@@ -247,6 +385,15 @@ module Parsanol
               atom = Atoms::Sequence.new(skip_maybe_atom, atom, skip_maybe_atom)
             end
           end
+          # The modern wrap runs LAST — the guide's spec table: trivia
+          # atoms are in place first, so the pass sees the final tree.
+          # The unwrapped tree lands in the cache BEFORE the wrap (the
+          # wrap's capture probes resolve rule references through
+          # atom_for; a mutual-reference grammar must hit the cache,
+          # not rebuild), then the cache takes the wrapped tree.
+          @atom_cache[name] = atom
+          atom = apply_modern_captures(atom)
+          @atom_cache[name] = atom
           atom
         end
       end
@@ -1077,8 +1224,22 @@ module Parsanol
           # back to a reference implementation instead of failing obscurely
           # at parse time. Checksummed like the rest of the envelope.
           "source_hash" => Digest::SHA256.hexdigest(@document.source.to_s),
+          # The U3 provenance stamp (rs#297): which Unicode table source
+          # the compiling engine's categories compiled against. An
+          # engine-specific stamp (checksummed here, excluded from the
+          # cross-engine parity set like compiler_version); the
+          # observable behavior stays pinned by the unicode corpus
+          # fixtures.
+          "unicode_tables" => "onigmo (Ruby #{RUBY_VERSION})",
           "compiler_version" => Parsanol::VERSION,
         }
+        # ruby#304: the envelope always names the capture dialect —
+        # consumers read the tree-shape contract before parsing.
+        envelope["edition"] = @document.edition
+        # ruby#353: the language-semantics level the trees were frozen
+        # against (1.3.108's implicit-capture shapes = 1; the
+        # explicit end_guard/marker/hyphen nodes = 2). Consumers freeze
+        # tree shapes and mappers; the loader asserts the level at
         if @document.skip_declaration
           # parsanol-ruby#134: declared trivia rule. Injection is baked
           # into the compiled trees (plain atom kinds), so consumers

data/lib/parsanol/parg/document.rb

@@ -17,7 +17,7 @@ module Parsanol
 
       Test = Struct.new(:entry, :kind, :input, :expect)
 
-      attr_accessor :grammar_name, :version, :source, :uses, :skip_declaration, :skip_source,
+      attr_accessor :grammar_name, :version, :edition, :source, :uses, :skip_declaration, :skip_source,
                     :atomic_rules, :skip_capture_key, :brace_rules
       # R2 declared resync: rule name -> skip pattern (the span matched
       # at a recovery point is consumed as annotated error text).
@@ -35,6 +35,11 @@ module Parsanol
 
       def initialize
         @grammar_name = nil
+        # The default capture dialect is v1 (the owner's reversal,
+        # 2026-10-28): runtime compiles of unpinned sources keep the
+        # legacy shapes — the pubid fleet froze against them. mode "v2"
+        # stays the named-trees opt-in via the grammar header.
+        @edition = "v1"
         @version = "0.0.0"
         @source = nil
         @rules = {}

data/lib/parsanol/parg/export.rb

@@ -19,9 +19,15 @@ module Parsanol
       TARGETS = %i[xgrammar].freeze
 
       class << self
-        def call(artifact_json, target: :xgrammar)
+        # `recovery: true` lowers each declared `resync <rule> = <pattern>`
+        # as an escape alternative at the repetition spine: the target's
+        # matcher then accepts exactly the strings the engines' recovery
+        # path accepts — clean parses, and violate-then-resync parses
+        # where the junk is emitted deliberately and the grammar closes
+        # back over the continuation (ruby#321's partial-mask story).
+        def call(artifact_json, target: :xgrammar, recovery: false)
           case target
-          when :xgrammar then Xgrammar.new(artifact_json).call
+          when :xgrammar then Xgrammar.new(artifact_json, recovery: recovery).call
           else raise Error, "unknown export target #{target.inspect} (supported: #{TARGETS.join(', ')})"
           end
         end
@@ -34,20 +40,64 @@ module Parsanol
       # equality. The artifact wire has no rule boundaries (all atoms
       # inline), so each entry lowers as one expression.
       class Xgrammar
-        def initialize(artifact_json)
+        def initialize(artifact_json, recovery: false)
           @envelope = JSON.parse(artifact_json)
+          @recovery = recovery
         end
 
         def call
           rules = @envelope["entries"].map do |entry, meta|
             grammar = meta.fetch("grammar")
-            "#{entry}_entry ::= #{lower(grammar.fetch('atoms'), grammar.fetch('root'))}"
+            "#{entry}_entry ::= #{lower_entry(entry, grammar)}"
           end
           "#{rules.join("\n")}\n"
         end
 
         private
 
+        # The recovery wrap mirrors the engines' resync contract: the
+        # root must be a repetition spine (the same shape resync
+        # recovery itself requires), and each declared resync pattern
+        # becomes an alternative of the spine body — junk between
+        # complete iterations is exactly what the recovery path
+        # consumes and resumes. Inferred (undeclared) policies are the
+        # trial scan and have no closed form here: the plain grammar
+        # ships, and the differential reports the gap honestly.
+        def lower_entry(entry, grammar)
+          atoms = grammar.fetch("atoms")
+          body = lower(atoms, grammar.fetch("root"))
+          return body unless @recovery
+
+          pattern = @envelope.dig("entries", entry, "resync")
+          return body unless pattern
+
+          spine = repetition_spine(atoms, grammar.fetch("root"))
+          unless spine
+            unsupported("recovery export: the entry root is not a repetition spine")
+          end
+          junk = lower(pattern.fetch("atoms"), pattern.fetch("root"))
+          # A spine item is a body, optionally preceded by one junk
+          # span: the engines scan forward to the first pattern match,
+          # consume it as one annotated span, and resume with the next
+          # iteration — which may be absent (trailing junk ends the
+          # parse, recovered).
+          "( #{body} | ( #{junk} ) ( #{body} )? )*"
+        end
+
+        # The lowerable body of the spine's repetition: Named/Entity
+        # unwrapping down to the Repetition atom, unbounded (max nil).
+        # Nil when the root is not that shape.
+        def repetition_spine(atoms, index)
+          tag, fields = atoms.fetch(index).first
+          case tag
+          when "Named", "Entity" then repetition_spine(atoms, fields.fetch("atom"))
+          when "Repetition"
+            return nil unless fields["max"].nil?
+
+            fields.fetch("atom")
+          end
+        end
+
         def lower(atoms, index)
           tag, fields = atoms.fetch(index).first
           case tag
@@ -91,7 +141,15 @@ module Parsanol
         # which IS the simple-case-fold semantics for ASCII. A non-ASCII
         # fold group needs a fold table the target does not have.
         def re_class(pattern)
-          return pattern if pattern.start_with?("[") && pattern.end_with?("]")
+          # Categories have no EBNF-class spelling: they must be
+          # rejected naming the construct, never emitted raw (the
+          # target's lexer rejects them, which fails the round trip
+          # obscurely instead of at export time).
+          if pattern.include?("\\p{")
+            unsupported("unicode category #{pattern.inspect}")
+          end
+
+          return de_escape_class(pattern) if pattern.start_with?("[") && pattern.end_with?("]")
 
           if (folded = pattern[/\A\(\?i:(.*)\)\z/m, 1])
             return expand_fold(folded, pattern)
@@ -100,6 +158,16 @@ module Parsanol
           unsupported("regex pattern #{pattern.inspect}")
         end
 
+        # Class endpoints \u00ff / \u{10ffff} spell as the literal
+        # characters — XGrammar's EBNF classes are UTF-8 text and
+        # accept them; emitting the escapes raw fails the target's
+        # lexer instead.
+        def de_escape_class(pattern)
+          pattern
+            .gsub(/\\u\{([0-9a-fA-F]+)\}/) { [$1.to_i(16)].pack("U") }
+            .gsub(/\\u([0-9a-fA-F]{4})/) { [$1.to_i(16)].pack("U") }
+        end
+
         def expand_fold(text, pattern)
           unsupported("non-ASCII fold group #{pattern.inspect} -- the target has no fold table") unless text.ascii_only?
 

data/lib/parsanol/parg/parser.rb

@@ -231,6 +231,23 @@ module Parsanol
         document.grammar_name = ident.value
         ident("version")
         document.version = unquote(expect(:str).value)
+        # `edition` — the language edition (ruby#304, ruby#357's
+        # consolidation; Rust's Cargo.toml `edition` is the model):
+        # the author declares, per grammar, which tree semantics the
+        # grammar means. THE DEFAULT IS "v1" (the legacy shapes — the
+        # owner's 2026-10-28 reversal). "v2" = fully named trees +
+        # explicit spans. `mode` remains accepted as a deprecated
+        # alias for the keyword. The edition is canonicalized here —
+        # everything downstream only ever sees "v1"/"v2".
+        if peek&.type == :ident && %w[edition mode].include?(peek.value)
+          keyword = advance.value
+          edition = unquote(expect(:str).value)
+          unless %w[v2 v1 classic].include?(edition)
+            raise ParseError,
+                  "unknown edition #{edition.inspect} -- supported editions are \"v1\" (default) and \"v2\" (named trees)"
+          end
+          document.edition = edition == "v2" ? "v2" : "v1"
+        end
         punct("{")
         skip_newlines
         until peek&.type == :punct && peek.value == "}"

data/lib/parsanol/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parsanol
-  VERSION = "1.3.109"
+  VERSION = "1.3.112"
 end

data/lib/parsanol/vm.rb

@@ -971,6 +971,50 @@ module Parsanol
         @memoize = memoize
       end
 
+      # The RE match's [char width, byte advance]: single-class
+      # patterns match one character; multi-character patterns (%i
+      # literals reach RE with no byte table) consume their full
+      # length (ruby#357: advancing one character skipped the
+      # pattern's remainder and let the parse re-match inside it).
+      def re_match_width(scanner, input, pos, table, pattern)
+        if table
+          w = CHAR_WIDTH[input.byteslice(pos, 1).bytes[0]]
+          w = char_width_slow(input, pos) if w.zero?
+          [w, w]
+        else
+          len = scanner.skip(pattern)
+          [input.byteslice(pos, len).length, len]
+        end
+      end
+
+      # An RE instruction's match at pos: [matched?, char width, byte
+      # advance]. Single-class patterns match one character;
+      # multi-character patterns (%i literals reach RE with no byte
+      # table) consume their FULL length (ruby#357: advancing one
+      # character skipped the pattern's remainder and let the parse
+      # re-match inside it).
+      def re_scan(scanner, input, pos, table, pattern)
+        b = table && input.getbyte(pos)
+        matched =
+          if b && b < 128
+            table[b]
+          elsif pos < input.length
+            (scanner.pos = pos) && scanner.match?(pattern)
+          else
+            false
+          end
+        return [false, 0, 0] unless matched
+
+        if b && b < 128
+          w = CHAR_WIDTH[b]
+          w = char_width_slow(input, pos) if w.zero?
+          [true, w, w]
+        else
+          len = scanner.skip(pattern)
+          [true, input.byteslice(pos, len).length, len]
+        end
+      end
+
       def execute # rubocop:disable Metrics/MethodLength, Metrics/BlockLength, Metrics/BlockNesting -- single dispatch loop; hot path
         ops = @ops
         input = @input
@@ -1054,20 +1098,11 @@ module Parsanol
               pc = fail_pc
             end
           when RE
-            b = bytes[pos]
-            matched =
-              if (table = ops[pc + 2]) && b && b < 128
-                table[b]
-              elsif pos < n
-                (scanner.pos = pos) && scanner.match?(ops[pc + 1])
-              else
-                false
-              end
+            table = ops[pc + 2]
+            matched, w, advance = re_scan(scanner, input, pos, table, ops[pc + 1])
             if matched
-              w = CHAR_WIDTH[b]
-              w = char_width_slow(input, pos) if w.zero?
               rstack << ((pos << 20) | w)
-              pos += w
+              pos += advance
               pc += 4
             else
               pc = fail_pc
@@ -1257,19 +1292,10 @@ module Parsanol
               kc = kids[ki + 3]
               case kop
               when RE
-                b = bytes[pos]
-                m = if kb && b && b < 128
-                      kb[b]
-                    elsif pos < n
-                      (scanner.pos = pos) && scanner.match?(ka)
-                    else
-                      false
-                    end
-                if m
-                  w = CHAR_WIDTH[b]
-                  w = char_width_slow(input, pos) if w.zero?
+                matched, w, advance = re_scan(scanner, input, pos, kb, ka)
+                if matched
                   values << ((pos << 20) | w)
-                  pos += w
+                  pos += advance
                 else
                   failed = true
                 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.109
+  version: 1.3.112
 platform: aarch64-linux
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-28 00:00:00.000000000 Z
 dependencies: []
 description: A small Ruby library for constructing parsers in the PEG (Parsing Expression
   Grammar) fashion. Parsanol provides Parslet-compatible API with additional features