parsanol 1.3.108 → 1.3.112

data/lib/parsanol/parg/compiler.rb

@@ -66,6 +66,19 @@ module Parsanol
 
       # QoL shorthands (ABNF core rules): materialized on reference when
       # the grammar does not define its own rule of that name.
+      # Character-class core rules (TODO.sota/9 T1, ruby#303): the RFC
+      # 5234 prelude that is expressible as a class. A grammar's own
+      # rule of the same name shadows these — fetch_rule checks the
+      # document first. ALNUM/WORD/ANY predate the RFC set.
+      # Unicode general categories (U3): one-letter groups plus the
+      # two-letter codes grammars actually reach for. Both regex
+      # engines carry the tables; this gate rejects misspellings at
+      # compile time instead of silently matching nothing.
+      GENERAL_CATEGORIES = %w[
+        L Lu Ll Lt Lm Lo M Mn Mc Me N Nd Nl No P Pc Pd Ps Pe Pi Pf Po
+        S Sm Sc Sk So Z Zs Zl Zp C Cc Cf Co Cn
+      ].freeze
+
       BUILTIN_CLASSES = {
         "DIGIT" => [[0x30, 0x39]],
         "ALPHA" => [[0x41, 0x5A], [0x61, 0x7A]],
@@ -73,15 +86,30 @@ module Parsanol
         "WORD" => [[0x30, 0x39], [0x41, 0x5A], [0x5F, 0x5F], [0x61, 0x7A]],
         "HEXDIG" => [[0x30, 0x39], [0x41, 0x46], [0x61, 0x66]],
         "ANY" => [[0x00, 0x10FFFF]],
+        "BIT" => [[0x30, 0x31]],
+        "CHAR" => [[0x01, 0x7F]],
+        "CR" => [[0x0D, 0x0D]],
+        "CTL" => [[0x00, 0x1F], [0x7F, 0x7F]],
+        "DQUOTE" => [[0x22, 0x22]],
+        "HTAB" => [[0x09, 0x09]],
+        "LF" => [[0x0A, 0x0A]],
+        "OCTET" => [[0x00, 0xFF]],
+        "SP" => [[0x20, 0x20]],
+        "VCHAR" => [[0x21, 0x7E]],
+        "WSP" => [[0x20, 0x20], [0x09, 0x09]],
       }.freeze
 
       def compile
+        inject_core_rules!
         expand_left_recursion!
         @document.rules.each_key { |name| atom_for(name) }
         errors = Lints.errors(@document, self)
         raise CompileError, errors.join("\n") unless errors.empty?
 
-        @warnings = Lints.warnings(@document, self)
+        # The author sees every finding; the envelope carries only the
+        # semantic subset (see Lints::Advisory).
+        @warnings = Lints.warnings(@document, self).map(&:to_s)
+        @envelope_warnings = Lints.envelope_warnings(@document, self)
         failures = run_tests
         raise CompileError, failures.join("\n") unless failures.empty?
 
@@ -120,6 +148,65 @@ module Parsanol
         end.flatten
       end
 
+      # The structured core rules (TODO.sota/9 T1, ruby#303): CRLF and
+      # LWSP are not character classes, so BUILTIN_CLASSES cannot serve
+      # them — they inject as real rules when referenced and missing,
+      # transitively (LWSP needs CRLF). Class-expressible members of
+      # the RFC 5234 set ride BUILTIN_CLASSES above; a grammar's own
+      # rule of the same name shadows either mechanism. Injected at the
+      # front so definitions precede references for the order lint.
+      STRUCTURED_CORE_RULES_SOURCE = <<~PARG
+        grammar CoreRules version "1.0.0" {
+          CRLF = %x0D.0A
+          LWSP = *( WSP / CRLF WSP )
+        }
+      PARG
+
+      STRUCTURED_CORE_RULE_NAMES = %w[CRLF LWSP].freeze
+
+      def inject_core_rules!
+        return if @core_rules_injected
+
+        @core_rules_injected = true
+        missing = STRUCTURED_CORE_RULE_NAMES.select do |name|
+          !@document.rules.key?(name) &&
+            @document.rules.each_value.any? { |node| references_atom?(node, name) }
+        end
+        return if missing.empty?
+
+        # Snapshot before the prelude merges: lints distinguish an
+        # authored shadow from an injected prelude rule.
+        @document.authored_rules ||= @document.rules.keys
+        prelude = Parser.new(STRUCTURED_CORE_RULES_SOURCE).parse
+        injected = {}
+        until missing.empty?
+          name = missing.pop
+          next if injected.key?(name) || @document.rules.key?(name)
+
+          node = prelude.rules.fetch(name)
+          injected[name] = node
+          STRUCTURED_CORE_RULE_NAMES.each do |dep|
+            missing << dep if !injected.key?(dep) && !@document.rules.key?(dep) &&
+              references_atom?(node, dep)
+          end
+        end
+        # rules is deliberately read-only on the document: prepend in place.
+        @document.rules.replace(injected.merge(@document.rules))
+      end
+
+      def references_atom?(node, name)
+        walk = lambda do |n|
+          case n.kind
+          when :ref then return true if n.a == name
+          when :alt, :seq then n.a.each { |b| return true if references_atom?(b, name) }
+          when :cap, :pred then return true if references_atom?(n.b, name)
+          when :rep, :opt then return true if references_atom?(n.a, name)
+          end
+          false
+        end
+        walk.call(node) == true
+      end
+
       def resolve_custom(name)
         class_name = @document.customs.fetch(name)
         klass = Object.const_get(class_name)
@@ -141,7 +228,146 @@ 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
         @atom_cache[name] ||= begin
           atom = build_atom(fetch_rule(name))
@@ -159,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
@@ -600,6 +835,14 @@ module Parsanol
             Atoms::Str.new(node.a)
           end
         when :class then Atoms::Re.new(class_pattern(node.a))
+        when :category
+          code = node.a
+          unless GENERAL_CATEGORIES.include?(code)
+            raise CompileError,
+                  "unknown general category %p{#{code}} -- use one of " \
+                  "#{GENERAL_CATEGORIES.join(' ')}"
+          end
+          Atoms::Re.new("[\\p{#{code}}]")
         when :until
           # QoL: (*( !terminal any_char )) — consume everything up to
           # (and excluding) the delimiter.
@@ -858,9 +1101,10 @@ module Parsanol
       def compute_first(node)
         case node.kind
         when :lit
-          # The zero-width marker ("" as name) consumes nothing: its
-          # first set is empty, which also marks the node nullable.
-          return Set.new if node.a.empty?
+          # The zero-width marker ("" as name) consumes nothing: EPS in
+          # its first set marks the node nullable (the convention every
+          # nullable? check uses).
+          return Set.new([EPS]) if node.a.empty?
 
           set = Set.new(node.a[0].bytes)
           set += node.a[0].upcase.bytes + node.a[0].downcase.bytes if node.b
@@ -954,7 +1198,7 @@ module Parsanol
           "entries" => entries,
           "preprocess" => @document.preprocess,
           "tables" => table_manifest,
-          "lint" => { "order_warnings" => @warnings.uniq },
+          "lint" => { "order_warnings" => @envelope_warnings.uniq },
           "default_entry" => begin
             resolve_default_entry
           rescue StandardError
@@ -980,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/diff.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module PARG
+    # ruby#306: `parg diff OLD NEW` — semantic classification of grammar
+    # changes against the artifact contract. Atoms are compared by
+    # canonical rendering, never by JSON bytes, so compiler-version churn
+    # and key order never read as a grammar change.
+    #
+    # Levels: :major breaks consumers (capture/entry/branch removals,
+    # binding changes, mode change), :minor extends them (new entries,
+    # captures, branches), :patch is behavior-preserving detail (literal
+    # fixes, doc changes, added tests). Ambiguous cases land at the
+    # higher level with the evidence attached — never guessed down.
+    module Diff
+      Finding = Struct.new(:level, :kind, :detail)
+
+      SEVERITY = { none: 0, patch: 1, minor: 2, major: 3 }.freeze
+
+      module_function
+
+      def diff(old_envelope, new_envelope)
+        findings = []
+        findings.concat(diff_mode(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))
+        findings
+      end
+
+      def level(findings)
+        findings.reduce(:none) { |acc, finding| higher(acc, finding.level) }
+      end
+
+      def higher(left, right)
+        SEVERITY[left] >= SEVERITY[right] ? left : right
+      end
+
+      def suggest_bump(findings)
+        level = level(findings)
+        level == :none ? "no bump needed" : "bump #{level}"
+      end
+
+      # -- entries ------------------------------------------------------
+
+      def diff_entries(old_env, new_env)
+        old_entries = old_env["entries"] || {}
+        new_entries = new_env["entries"] || {}
+        findings = (old_entries.keys - new_entries.keys).map do |name|
+          Finding.new(:major, :entry_removed, "entry #{name.inspect} removed")
+        end
+        (new_entries.keys - old_entries.keys).each do |name|
+          findings << Finding.new(:minor, :entry_added, "entry #{name.inspect} added")
+        end
+        old_entries.each do |name, old_entry|
+          new_entry = new_entries[name]
+          next unless new_entry
+
+          findings.concat(diff_entry(name, old_entry, new_entry))
+        end
+        findings
+      end
+
+      def diff_entry(name, old_entry, new_entry)
+        old_atoms = old_entry.dig("grammar", "atoms") || []
+        new_atoms = new_entry.dig("grammar", "atoms") || []
+        old_root = old_entry.dig("grammar", "root")
+        new_root = new_entry.dig("grammar", "root")
+        return [Finding.new(:major, :entry_changed, "entry #{name.inspect} lost its root")] if old_root.nil? || new_root.nil?
+
+        old_render = render_atom(old_atoms, old_root)
+        new_render = render_atom(new_atoms, new_root)
+        return [] if old_render == new_render
+
+        findings = []
+        findings.concat(diff_captures(name, old_render, new_render))
+        findings.concat(diff_branches(name, mask(old_render), mask(new_render)))
+        if findings.empty?
+          findings << if mask(old_render) == mask(new_render)
+                        # Same captures, same branches, same structure: the
+                        # difference is inside literals, bounds, or trivia markers —
+                        # behavior-preserving.
+                        Finding.new(:patch, :literal_or_bound_change,
+                                    "entry #{name.inspect}: literal/bound/doc-level change")
+                      else
+                        # Structure reshuffled without a detectable capture or
+                        # branch delta — evidence over a guess.
+                        Finding.new(:minor, :structure_changed,
+                                    "entry #{name.inspect}: structure changed " \
+                                    "(no capture or branch removed): " \
+                                    "#{mask(old_render)[0, 60]} -> #{mask(new_render)[0, 60]}")
+                      end
+        end
+        findings
+      end
+
+      # -- captures -----------------------------------------------------
+
+      def diff_captures(entry_name, old_render, new_render)
+        old_names = capture_names(old_render)
+        new_names = capture_names(new_render)
+        removed = old_names - new_names
+        added = new_names - old_names
+        removed.map { |n| Finding.new(:major, :capture_removed, "entry #{entry_name.inspect}: capture #{n.inspect} removed") } +
+          added.map { |n| Finding.new(:minor, :capture_added, "entry #{entry_name.inspect}: capture #{n.inspect} added") }
+      end
+
+      def capture_names(render)
+        render.scan(/\(name "([^"]+)"/).flatten.uniq
+      end
+
+      # -- alternative branches ----------------------------------------
+
+      # A branch that stops matching is the ambiguous-breaking case:
+      # inputs it used to accept now reject. Removed branches are major;
+      # added-only is the documented minor.
+      def diff_branches(entry_name, old_render, new_render)
+        old_branches = alt_branches(old_render)
+        new_branches = alt_branches(new_render)
+        removed = old_branches - new_branches
+        added = new_branches - old_branches
+        removed.map { |b| Finding.new(:major, :branch_removed, "entry #{entry_name.inspect}: alternative branch #{b} no longer matches") } +
+          added.map { |b| Finding.new(:minor, :branch_added, "entry #{entry_name.inspect}: alternative branch #{b} added") }
+      end
+
+      # Literals masked: branch identity is structural, not spelling —
+      # a literal fix inside a branch is not that branch's removal.
+      def mask(render)
+        render.gsub(/str:"[^"]*"/, "str:#").gsub(/const:[^\s)]+/, "const:#")
+      end
+
+      # Every alternative branch's canonical rendering, anywhere in the
+      # tree (alternatives inside repetitions, groups, captures…).
+      # Balanced-paren walk: branches nest.
+      def alt_branches(render)
+        branches = []
+        index = render.index("(alt ")
+        while index
+          start = index + 5
+          depth = 1
+          cursor = start
+          while depth.positive? && cursor < render.length
+            case render[cursor]
+            when "(" then depth += 1
+            when ")" then depth -= 1
+            end
+            cursor += 1
+          end
+          body = render[start...(cursor - 1)]
+          child_depth = 0
+          current = +""
+          body.each_char do |ch|
+            case ch
+            when "(" then child_depth += 1
+            when ")" then child_depth -= 1
+            when " "
+              if child_depth.zero?
+                branches << current unless current.empty?
+                current = +""
+                next
+              end
+            end
+            current << ch
+          end
+          branches << current unless current.empty?
+          index = render.index("(alt ", cursor)
+        end
+        branches.uniq.sort
+      end
+
+      # -- mode ---------------------------------------------------------
+
+      def diff_mode(old_env, new_env)
+        old_mode = old_env["mode"]
+        new_mode = new_env["mode"]
+        return [] if old_mode == new_mode
+
+        [Finding.new(:major, :mode_changed,
+                     "mode changed #{old_mode.inspect} -> #{new_mode.inspect} " \
+                     "(every uncaptured node's tree shape changes)")]
+      end
+
+      # -- bindings -----------------------------------------------------
+
+      def diff_bindings(old_env, new_env)
+        old_bindings = old_env["bindings"]
+        new_bindings = new_env["bindings"]
+        return [] if old_bindings == new_bindings
+        return [Finding.new(:minor, :bindings_added, "bindings section added")] if old_bindings.nil?
+        return [Finding.new(:major, :bindings_removed, "bindings section removed")] if new_bindings.nil?
+
+        [Finding.new(:major, :bindings_changed,
+                     "bindings changed — binding paths/types re-validate " \
+                     "against the tree")]
+      end
+
+      # -- tests --------------------------------------------------------
+
+      def diff_tests(old_env, new_env)
+        old_tests = old_env["tests"].to_a
+        new_tests = new_env["tests"].to_a
+        return [] if old_tests == new_tests
+
+        # Pins per kind: a pin whose INPUT changed alongside a literal
+        # fix is the pin following the grammar (patch), not a removal.
+        old_counts = old_tests.each_with_object(Hash.new(0)) { |t, counts| counts[t["kind"]] += 1 }
+        new_counts = new_tests.each_with_object(Hash.new(0)) { |t, counts| counts[t["kind"]] += 1 }
+        dropped = old_counts.keys.select { |kind| new_counts[kind] < old_counts[kind] }
+        unless dropped.empty?
+          return [Finding.new(:major, :tests_removed,
+                              "#{dropped.join(', ')} pin(s) removed — the contract weakened")]
+        end
+
+        [Finding.new(:patch, :tests_added,
+                     "test pins changed/added (#{old_tests.size} -> #{new_tests.size})")]
+      end
+
+      # -- canonical rendering ------------------------------------------
+
+      # Canonical s-expression of one atom index. Entities resolve; keyed
+      # hashes render in fixed field order; nothing escapes — this is a
+      # diff key, not output text.
+      def render_atom(atoms, idx, depth = 0)
+        return "…" if depth > 64
+
+        a = atoms[idx]
+        return "missing:#{idx}" if a.nil?
+
+        if (str = a["Str"])
+          "str:#{str['pattern'].inspect}"
+        elsif (re = a["Re"])
+          "re:#{re['pattern']}"
+        elsif (sequence = a["Sequence"])
+          "(seq #{sequence['atoms'].map { |i| render_atom(atoms, i, depth + 1) }.join(' ')})"
+        elsif (alt = a["Alternative"])
+          "(alt #{alt['atoms'].map { |i| render_atom(atoms, i, depth + 1) }.join(' ')})"
+        elsif (rep = a["Repetition"])
+          "(rep #{rep['min']} #{rep['max'].nil? ? '*' : rep['max']} #{rep['tag']} #{render_atom(atoms, rep['atom'], depth + 1)})"
+        elsif (named = a["Named"])
+          "(name \"#{named['name']}\" #{render_atom(atoms, named['atom'], depth + 1)})"
+        elsif (entity = a["Entity"])
+          render_atom(atoms, entity["atom"], depth + 1)
+        elsif (look = a["Lookahead"])
+          "(look #{look['positive'] ? '&' : '!'} #{render_atom(atoms, look['atom'], depth + 1)})"
+        elsif (behind = a["Lookbehind"])
+          "(behind #{behind['positive'] ? '&' : '!'} #{behind['look'].inspect})"
+        elsif a["Cut"]
+          "cut"
+        elsif (ignore = a["Ignore"])
+          "(ignore #{render_atom(atoms, ignore['atom'], depth + 1)})"
+        elsif (trivia = a["Trivia"])
+          "(trivia #{render_atom(atoms, trivia['atom'], depth + 1)})"
+        elsif (capture_trivia = a["TriviaCapture"])
+          "(trivia-cap #{capture_trivia['rules'].map { |m, k| "#{m}=#{k}" }.join(',')} " \
+            "#{render_atom(atoms, capture_trivia['atom'], depth + 1)})"
+        elsif (constant = a["Constant"])
+          "const:#{constant['value'].inspect}"
+        else
+          "unknown:#{a.keys.first}"
+        end
+      end
+    end
+  end
+end

data/lib/parsanol/parg/document.rb

@@ -17,19 +17,29 @@ module Parsanol
 
       Test = Struct.new(:entry, :kind, :input, :expect)
 
-      attr_accessor :grammar_name, :version, :source, :uses, :skip_declaration, :skip_source,
-                    :atomic_rules, :skip_capture_key
+      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).
       attr_reader :resyncs
       attr_reader :rules, :bindings, :preprocess, :entries, :docs, :tests, :render, :derive,
+                  :declaration_order,
                   :customs, :states
       # Entries authored in this file (pre-import); nil-entry tests resolve
       # against these first.
       attr_accessor :own_entries
+      # Rule names the grammar itself wrote, snapshotted before the
+      # compiler injects core rules — lints must not mistake an injected
+      # prelude rule for an authored shadow.
+      attr_accessor :authored_rules
 
       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 = {}
@@ -38,6 +48,7 @@ module Parsanol
         @bindings = {}
         @preprocess = {}
         @entries = {}
+        @declaration_order = []
         @docs = {}
         @tests = []
         @uses = []
@@ -48,6 +59,8 @@ module Parsanol
         # suppressed inside their bodies (token-shaped rules match
         # contiguously).
         @atomic_rules = []
+        @brace_rules = []
+        @authored_rules = nil
         # R2 declared resync: rule -> skip pattern. Recovery consumes
         # each pattern match at a failure point as annotated error text
         # and resumes the iteration after it.