parsanol 1.3.109 → 1.3.113

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7abef89c341c194089d17849bb5e877e4f45a5b2f20a73e347b29905e49a377a
-  data.tar.gz: 4e3619755881576b2ea58c74b8d95ec70ee736cc0dfb258a511e44f83f73a2cf
+  metadata.gz: d9a04b4f0add7d25933bf9ddd041f28cf067e9b2750abb6595915d63cdd4cd3a
+  data.tar.gz: 69767361cdcb52ddeb7e0dbd4b05498e72fffe4d64639c4c5d00aad723f7c659
 SHA512:
-  metadata.gz: 3f128038206f01fe80038c2f5c02f44fd2202155e322386bd810b6e4f04cd1f08dc7c545cedc69270ec6f2d5eb539ef8a2561d6ff5837092bfa5cecffb2a81dc
-  data.tar.gz: bca7e6ef0d98b589d08973a0f20c198d0d864f394cf511b69fc5195f35c90bfd924455acd1a27a0558788723df864cc9b96c51a8d226e33854748d84f396d72a
+  metadata.gz: 8407c77dbca38833e2e2ddf189d601be84ed14f07bbe5e972feb76ce016df3f88c7725951ed20ba74b5403ad83dae25fef8d3f1259c6312e6e4158e709c037ba
+  data.tar.gz: 9fe4fd4df2ba548a686226ee50c80c60945dfad0e3719d7b1593fe9678a5a2f464df833940cb87201e86b98243c025d94ab42664b914f29ea3ca2649773c6aff

data/Cargo.lock

@@ -307,34 +307,16 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "parsanol"
-version = "0.18.21"
+version = "0.19.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b6762cda50ce912cb3b247e97559a4da27cec3843103a132568251952fbe9d0"
-dependencies = [
- "ahash",
- "getrandom 0.3.4",
- "getrandom 0.4.3",
- "hashbrown",
- "parsanol-derive 0.18.21",
- "regex",
- "regex-syntax",
- "serde",
- "serde_json",
- "sha2",
-]
-
-[[package]]
-name = "parsanol"
-version = "0.19.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "366ad171b2117387a355e5a09fb0dfaa0a2177ca7536d9b3a0b18ae63cca3594"
+checksum = "5233088cf0cde65b9a6e5e41d558b689becc722ccf156946c8f118049f2d3f5c"
 dependencies = [
  "ahash",
  "getrandom 0.3.4",
  "getrandom 0.4.3",
  "hashbrown",
  "magnus",
- "parsanol-derive 0.19.0",
+ "parsanol-derive",
  "regex",
  "regex-syntax",
  "serde",
@@ -344,20 +326,9 @@ dependencies = [
 
 [[package]]
 name = "parsanol-derive"
-version = "0.18.21"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77eed76fe86c54c683fbb8e2b462495506e9bc2f3007beec82bf6d90b8a82209"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 3.0.6",
-]
-
-[[package]]
-name = "parsanol-derive"
-version = "0.19.0"
+version = "0.19.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "271be27b8391e4c5731af22bd9294536592a2731e258566caa4b7045d09edf3d"
+checksum = "c84688541fbbd11509183b9c53debd924bcdbfae8cf8aca053414ea11a7aa7e9"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -368,7 +339,7 @@ dependencies = [
 name = "parsanol_cdylib"
 version = "1.3.52"
 dependencies = [
- "parsanol 0.18.21",
+ "parsanol",
 ]
 
 [[package]]
@@ -377,7 +348,7 @@ version = "1.0.2"
 dependencies = [
  "log",
  "magnus",
- "parsanol 0.19.0",
+ "parsanol",
  "rb-sys",
 ]
 

data/ext/parsanol_cdylib/Cargo.toml

@@ -13,4 +13,4 @@ doc = false
 
 [dependencies]
 # 0.17.0 carries LookSpec + the widened opaque writeback
-parsanol = { version = "0.18.0" }
+parsanol = { version = "0.19.1" }

data/ext/parsanol_native/Cargo.toml

@@ -32,7 +32,7 @@ magnus = { version = "0.9" }
 # parsanol parser library (crates.io; 0.17.0 carries the LookSpec regex
 # lookbehind (rs#163 gap 1) and the widened opaque writeback: the
 # lazy-continuation fix, parsanol-ruby#160)
-parsanol = { version = "0.19.0", features = ["ruby"] }
+parsanol = { version = "0.19.1", features = ["ruby"] }
 
 # Logging
 log = "0.4"

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/parg/artifact.rb

@@ -26,6 +26,18 @@ module Parsanol
 
       SUPPORTED_SHAPE = "parsanol-tree/v2"
 
+      # The editions this runtime parses (ruby#357's consolidation):
+      # 1 = the legacy shapes; 2 = named trees + explicit spans.
+      SUPPORTED_EDITIONS = [1, 2].freeze
+
+      # The header and envelope spellings that have shipped: the quoted
+      # v-forms stay loadable so artifacts baked before the numeric
+      # surface remain readable.
+      EDITION_ALIASES = {
+        1 => 1, "1" => 1, "v1" => 1, "classic" => 1,
+        2 => 2, "2" => 2, "v2" => 2
+      }.freeze
+
       def initialize(envelope, path, tables_dir, imports_dir: nil)
         unless envelope["shape"] == SUPPORTED_SHAPE
           raise ArtifactError,
@@ -38,6 +50,15 @@ module Parsanol
         bindings = envelope["bindings"]
         validate_bindings!(bindings) unless bindings.nil?
         @envelope = envelope
+        # The declared edition must be one this runtime understands
+        # (ruby#357's consolidation: one axis, `edition`). Absent field
+        # = the pre-1.3.109 artifacts, whose trees are edition 1.
+        edition = EDITION_ALIASES[envelope.fetch("edition", 1)]
+        unless SUPPORTED_EDITIONS.include?(edition)
+          raise ArtifactError,
+                "artifact declares edition #{envelope['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
@@ -50,6 +71,13 @@ module Parsanol
 
       def version = envelope["version"]
 
+      # The edition the artifact's trees carry: 1 = the legacy shapes,
+      # 2 = fully named trees. Legacy artifacts that spell the field
+      # "v2" (or omit it) normalize here.
+      def edition
+        EDITION_ALIASES.fetch(envelope.fetch("edition", 1))
+      end
+
       # Freshness (parsanol-ruby#209): what source revision and compiler
       # produced this artifact. `source_hash` is the SHA-256 of the .parg
       # text at compile time; nil on artifacts baked before the field
@@ -233,13 +261,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 +409,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,234 @@ 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, character classes are whitespace-only;
+      # sequence/alternation/repetition compose the verdict; references
+      # resolve through the atom cache with a cycle set; anything else
+      # (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::Re
+          whitespace_class?(atom.match)
+        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
+
+      # A class matches only whitespace when every codepoint it admits
+      # strips to empty — the same verdict Atoms::Str gets. Compiled
+      # classes are the dialect class_pattern emits: bracket bodies of
+      # literal chars, \t\n\v\f\r, \xHH, \uXXXX and \u{...}, plus ranges
+      # between them. Anything else disqualifies.
+      def whitespace_class?(pattern)
+        body = pattern.to_s[/\A\[(.*)\]\z/m, 1]
+        return false if body.nil? || body.empty? || body.start_with?("^")
+
+        ranges = class_ranges(body)
+        ranges&.all? { |lo, hi| whitespace_range?(lo, hi) }
+      end
+
+      WHITESPACE_CODEPOINTS = [0x00, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20].freeze
+
+      def whitespace_range?(low, high)
+        return false if low > high
+
+        union = WHITESPACE_CODEPOINTS.count { |code| code.between?(low, high) }
+        union == high - low + 1
+      end
+
+      def class_ranges(body)
+        slots = []
+        pending_range = false
+        index = 0
+        while index < body.length
+          if body[index] == "-" && !pending_range && !slots.empty?
+            pending_range = true
+            index += 1
+            next
+          end
+
+          code, index = class_token(body, index)
+          return nil unless code
+
+          if pending_range
+            previous = slots.pop
+            slots << [previous[0], code].minmax
+            pending_range = false
+          else
+            slots << [code, code]
+          end
+        end
+        return nil if pending_range
+
+        slots
+      end
+
+      def class_token(body, index)
+        char = body[index]
+        unless char == "\\"
+          return [char.ord, index + 1]
+        end
+
+        escaped = body[index + 1]
+        return nil if escaped.nil?
+
+        case escaped
+        when "x" then hex_token(body, index + 2, 2)
+        when "u"
+          if body[index + 2] == "{"
+            close = body.index("}", index + 3)
+            return nil unless close
+
+            [body[(index + 3)...close].to_i(16), close + 1]
+          else
+            hex_token(body, index + 2, 4)
+          end
+        when "t" then [0x09, index + 2]
+        when "n" then [0x0A, index + 2]
+        when "v" then [0x0B, index + 2]
+        when "f" then [0x0C, index + 2]
+        when "r" then [0x0D, index + 2]
+        else [escaped.ord, index + 2]
+        end
+      end
+
+      def hex_token(body, start, length)
+        hex = body[start, length]
+        return nil unless hex&.match?(/\A\h{#{length}}\z/)
+
+        [hex.to_i(16), start + length]
+      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
+          # Mirror wrap_uncaptured's verdicts: trivia glue and
+          # capture-producing refs both stay bare.
+          unless trivia_only?(atom.rule_name.to_s, { atom.rule_name.to_s => true }) ||
+              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 +475,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 +1314,20 @@ 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 edition —
+        # consumers read the tree-shape contract before parsing. The
+        # numeric form is canonical: 1 = the legacy shapes, 2 = fully
+        # named trees + explicit spans.
+        envelope["edition"] = @document.edition == "v2" ? 2 : 1
         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/diff.rb

@@ -21,7 +21,7 @@ module Parsanol
 
       def diff(old_envelope, new_envelope)
         findings = []
-        findings.concat(diff_mode(old_envelope, new_envelope))
+        findings.concat(diff_edition(old_envelope, new_envelope))
         findings.concat(diff_entries(old_envelope, new_envelope))
         findings.concat(diff_bindings(old_envelope, new_envelope))
         findings.concat(diff_tests(old_envelope, new_envelope))
@@ -168,18 +168,25 @@ module Parsanol
         branches.uniq.sort
       end
 
-      # -- mode ---------------------------------------------------------
+      # -- edition ------------------------------------------------------
 
-      def diff_mode(old_env, new_env)
-        old_mode = old_env["mode"]
-        new_mode = new_env["mode"]
-        return [] if old_mode == new_mode
+      def diff_edition(old_env, new_env)
+        old_edition = edition_level(old_env)
+        new_edition = edition_level(new_env)
+        return [] if old_edition == new_edition
 
-        [Finding.new(:major, :mode_changed,
-                     "mode changed #{old_mode.inspect} -> #{new_mode.inspect} " \
+        [Finding.new(:major, :edition_changed,
+                     "edition changed #{old_edition.inspect} -> #{new_edition.inspect} " \
                      "(every uncaptured node's tree shape changes)")]
       end
 
+      # Artifacts baked before the numeric surface spell the edition
+      # "v1"/"v2"; they mean the same levels, not a change.
+      def edition_level(envelope)
+        declared = envelope.fetch("edition", 1)
+        Artifact::EDITION_ALIASES.fetch(declared, declared)
+      end
+
       # -- bindings -----------------------------------------------------
 
       def diff_bindings(old_env, new_env)

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

@@ -18,6 +18,14 @@ module Parsanol
 
       IN_BLOCK_SECTIONS = %w[entry bindings preprocess test].freeze
 
+      # The header's edition spellings: the bare numbers are canonical
+      # (Rust's Cargo.toml model); the quoted forms stay accepted as
+      # aliases for grammars written before the numeric surface.
+      EDITIONS = {
+        "1" => "v1", "v1" => "v1", "classic" => "v1",
+        "2" => "v2", "v2" => "v2"
+      }.freeze
+
       STATE_KEYWORDS = %w[custom state].freeze
       KEYWORDS = %w[grammar as alt from_table column bindings render derive
                     preprocess entry table_lookup custom state set switch
@@ -227,10 +235,39 @@ module Parsanol
 
       def punct(char) = expect(:punct, char)
 
+      def edition_value
+        token = advance
+        raw = case token&.type
+              when :num then token.value
+              when :str then unquote(token.value)
+              else
+                raise ParseError,
+                      "edition must be a number (1 or 2) or a quoted alias " \
+                      "(\"v1\", \"v2\", \"classic\")"
+              end
+        EDITIONS.fetch(raw) do
+          raise ParseError,
+                "unknown edition #{raw.inspect} -- supported editions are " \
+                "1 (default) and 2 (named trees)"
+        end
+      end
+
       def parse_grammar(document)
         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 1 (the legacy shapes — the
+        # owner's 2026-10-28 reversal). 2 = 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)
+          advance
+          document.edition = edition_value
+        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.113"
 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.109
+  version: 1.3.113
 platform: ruby
 authors:
 - Ribose Inc.