amath 0.1.0

data/corpora/uncertainty-shared-exponent.yml

@@ -0,0 +1,119 @@
+schema_version: 1
+issue: https://github.com/plurimath/amath/issues/13
+contract: Original source leaves and optional shared_exponent; normalized_model_text
+  is the exact-decimal consuming-reader expectation, not a transformed Amath slice.
+cases:
+- id: standard.positive
+  input: ustd((3.85, 0.23)e4)
+  tree:
+    uncertainty_class: ustd
+    value: '3.85'
+    magnitude: '0.23'
+    shared_exponent: '4'
+  normalized_model_text:
+    value: '38500'
+    magnitude: '2300'
+- id: standard.negative
+  input: ustd((-3.850, 0.230)e+4)
+  tree:
+    uncertainty_class: ustd
+    value: '-3.850'
+    magnitude: '0.230'
+    shared_exponent: '+4'
+  normalized_model_text:
+    value: '-38500'
+    magnitude: '2300'
+- id: standard.leading_zeroes
+  input: ustd((001.2300, 000.0040)e-2)
+  tree:
+    uncertainty_class: ustd
+    value: '001.2300'
+    magnitude: '000.0040'
+    shared_exponent: '-2'
+  normalized_model_text:
+    value: '0.012300'
+    magnitude: '0.000040'
+- id: standard.zero_exponent
+  input: ustd((1.230, 0.004)e0)
+  tree:
+    uncertainty_class: ustd
+    value: '1.230'
+    magnitude: '0.004'
+    shared_exponent: '0'
+  normalized_model_text:
+    value: '1.230'
+    magnitude: '0.004'
+- id: concise.negative_exponent
+  input: ustd(680(41)e-3)
+  tree:
+    uncertainty_class: ustd
+    value: '680'
+    concise_digits: '41'
+    shared_exponent: '-3'
+  normalized_model_text:
+    value: '0.680'
+    magnitude: '0.041'
+- id: concise.zero_exponent
+  input: ustd(1.230(4)e0)
+  tree:
+    uncertainty_class: ustd
+    value: '1.230'
+    concise_digits: '4'
+    shared_exponent: '0'
+  normalized_model_text:
+    value: '1.230'
+    magnitude: '0.004'
+- id: concise.unit
+  input: ustd(680(41)e-3, "unitsml(kg)")
+  tree:
+    uncertainty_class: ustd
+    value: '680'
+    concise_digits: '41'
+    shared_exponent: '-3'
+    unit: kg
+  normalized_model_text:
+    value: '0.680'
+    magnitude: '0.041'
+- id: expanded.dimensionless_fields
+  input: uexp((3.85, 0.23)e4, 2.00, 0.950, "unitsml(m)")
+  tree:
+    uncertainty_class: uexp
+    value: '3.85'
+    magnitude: '0.23'
+    shared_exponent: '4'
+    coverage_factor: '2.00'
+    coverage_probability: '0.950'
+    unit: m
+  normalized_model_text:
+    value: '38500'
+    magnitude: '2300'
+    coverage_factor: '2.00'
+    coverage_probability: '0.950'
+- id: expanded.negative_exponent
+  input: uexp((100.02147, 0.00079)e-2, 2)
+  tree:
+    uncertainty_class: uexp
+    value: '100.02147'
+    magnitude: '0.00079'
+    shared_exponent: '-2'
+    coverage_factor: '2'
+  normalized_model_text:
+    value: '1.0002147'
+    magnitude: '0.0000079'
+    coverage_factor: '2'
+- id: interval.shared_exponent
+  input: ucov((1.024, 0.983, 1.088)e-3, 0.95, shortest, "unitsml(V)")
+  tree:
+    uncertainty_class: ucov
+    value: '1.024'
+    lower: '0.983'
+    upper: '1.088'
+    shared_exponent: '-3'
+    coverage_probability: '0.95'
+    interval_kind: shortest
+    unit: V
+  normalized_model_text:
+    value: '0.001024'
+    lower: '0.000983'
+    upper: '0.001088'
+    coverage_probability: '0.95'

data/docs/parser-contract.adoc

@@ -0,0 +1,257 @@
+= Amath parser contract
+:toc:
+
+This document is the contract between amath and its callers (first of all
+Plurimath's AsciiMath transform). It covers the public API, decimal markers,
+engine policy, errors and positions. Anything not written here is not part of
+the contract.
+
+Runtime dependency: `parsanol ~> 1.3, >= 1.3.107`. amath never requires
+Plurimath or reads Plurimath constants.
+
+== API
+
+[source,ruby]
+----
+Amath.parse(input, decimal: ".", engine: :auto) # => tree
+Amath.last_engine                                # => :native, :ruby or nil
+Amath.native_available?                          # => true / false
+Amath.artifact_path                              # => String
+Amath.artifact_path = path                       # tests and tooling only
+Amath::VERSION
+----
+
+`input`:: a `String`. Non-UTF-8 strings are transcoded to UTF-8; a string that
+is not valid UTF-8 (or cannot be transcoded) raises `ArgumentError`. amath does
+no preprocessing: the caller passes the exact string to parse, and every
+position refers to that string.
+
+`decimal`:: the decimal marker for numbers. See <<decimal>>.
+
+`engine`:: `:auto`, `:native` or `:ruby`. See <<engine>>.
+
+=== Successful result
+
+The return value is the Parsanol tree of the selected entry:
+
+* `Hash` with Symbol keys, `Array` (order preserved), and `Parsanol::Slice`
+  leaves;
+* empty input returns a plain `""` (a `String`, not a `Slice`). This is the
+  grammar's end-of-input alternative and callers must handle it the same way
+  they handled Parslet's empty match.
+
+The tree's key names and nesting are defined by the grammar artifact
+(`artifacts/asciimath.json`) and are pinned by the conformance corpus, not by
+this document.
+
+`Parsanol::Slice` is not `Parslet::Slice`. Callers that check the leaf class
+exactly (Plurimath's transform does) need an adapter; that is the caller's
+concern.
+
+=== Shared exponents in uncertainty calls
+
+An uncertainty call can put its measured fields in a group followed immediately
+by `e` and a signed or unsigned integer exponent:
+
+[source,asciimath]
+----
+ustd((3.85, 0.23)e4)
+ustd(680(41)e-3)
+uexp((3.85, 0.23)e+4, 2, 0.95)
+ucov((1.024, 0.983, 1.088)e-3, 0.95, shortest)
+----
+
+These forms add `shared_exponent` to the existing `uncertainty` hash. Its
+value is the original `Parsanol::Slice` for the exponent digits and optional
+sign, without the `e`. All mantissas, concise digits, units and dimensionless
+coverage fields remain unchanged source slices with their original byte offsets.
+Calls without an exponent keep their existing trees.
+
+The consuming reader shifts the decimal point exactly in the value and
+magnitude, or in the value and both interval endpoints. For concise notation,
+it first derives the magnitude from the mantissa's decimal places. Thus
+`ustd(680(41)e-3)` means value `0.680` and magnitude `0.041`.
+Coverage factors and probabilities are not scaled. No float conversion is
+needed, and amath does not replace source slices with calculated text.
+
+Whitespace before `e`, incomplete exponents and a minus sign on a magnitude
+remain outside the uncertainty syntax and follow the ordinary grammar fallback.
+The separate expression-language forms `(3.85 +/- 0.23)e4` and `680(41)e-3`
+remain ordinary AsciiMath here; this extension uses explicit uncertainty calls.
+The input/tree and consuming-reader decimal expectations are recorded in
+`corpora/uncertainty-shared-exponent.yml`.
+
+[[decimal]]
+== Decimal markers
+
+The artifact carries one entry per supported marker. `decimal:` selects the
+entry; there is no locale lookup inside amath.
+
+[cols="1,1,2"]
+|===
+| `decimal:` | Artifact entry | Marker
+
+| `"."` (default) | `dot` | FULL STOP, U+002E
+| `","` | `comma` | COMMA, U+002C
+| `"٫"` | `arabic` | ARABIC DECIMAL SEPARATOR, U+066B
+|===
+
+Any other value raises `ArgumentError` before the artifact is touched. An
+artifact that lacks any of the three entries is rejected with
+`Amath::ArtifactError`.
+
+[[engine]]
+== Engine policy
+
+Parsanol has a native (Rust) engine and a pure-Ruby engine. Its own
+`mode: :native` silently runs the Ruby engine when the extension is missing,
+so amath decides the engine itself before calling Parsanol:
+
+[cols="1,3"]
+|===
+| `engine:` | Behaviour
+
+| `:auto` (default)
+| Native if `Parsanol::Native.available?`, otherwise Ruby. Input nested too
+  deeply for the native engine (see <<deep-nesting>>) is parsed again with the
+  Ruby engine.
+
+| `:native`
+| Native. If the extension is not available, raises
+  `Amath::EngineUnavailable`; never runs Ruby instead. Input nested too
+  deeply for the native engine raises `Amath::NestingTooDeep`; never runs
+  Ruby instead.
+
+| `:ruby`
+| Ruby engine only; the native extension is not called.
+|===
+
+After every call that reaches the parser (success or `ParseError`),
+`Amath.last_engine` returns the engine that produced the result, `:native` or
+`:ruby`: under `:auto` it is `:ruby` when deep input was parsed again with the
+Ruby engine. The value is thread-local; it is `nil` on a thread that has not
+parsed yet.
+
+Limits of what `last_engine` proves:
+
+* It records the engine amath ran. Inside `Parsanol::Native.parse`,
+  Parsanol may still run its interpreter for grammar constructs native cannot
+  express (custom atoms). The amath grammar is expected to contain none; the
+  differential check in `scripts/check.rb` is where internal fallback is
+  detected, not this flag.
+* Parsanol 1.3.107 ships precompiled native extensions for x86_64 Linux on
+  Ruby 3.2 to 4.0. CI runs Ruby 3.2, 3.3 and 3.4 on ubuntu-latest with the
+  native examples required. Other platforms are not yet verified.
+
+[[deep-nesting]]
+=== Deep nesting
+
+Parsanol's native engine stops at a fixed recursion depth ("Maximum recursion
+depth (500) exceeded" or "Recursion limit exceeded: depth 1000"). With the
+AsciiMath artifact that is about 110 levels of `(` and about 80 of `{`; other
+constructs (`sqrt`, `/`, unary `-`) reach it at other depths. On a thread
+other than the main one, the native call can also exhaust the thread's Ruby
+stack (1 MiB by default) much earlier (at about 40 levels of `(` on x86_64 Linux); Ruby reports
+that as `SystemStackError`.
+
+Length is not depth. A run of terms (a sum such as `x + x + ... + x`, a
+sequence of symbols, a comma list) is parsed as a repetition, not by one
+nested rule call per term, so neither engine gets deeper as the run gets
+longer. The tree is still the nested one, `{expr: term + {expr: ...}}`, one
+level per term: amath rebuilds it after the engine returns, without
+recursion (`Amath::Renester`), with the same keys, order, slices and
+offsets as the recursive grammar produced. Code that walks the returned
+tree recursively must still be ready for one level per term. When the
+input after a run fails to parse, the grammar falls back to its recursive
+rule to find the same tree or rejection as before; such input can still
+hit the limits below.
+
+For such a recursion-limit failure Parsanol's own error path would reparse
+the input through its Ruby interpreter with a diagnostic reporter, which on
+deep input takes minutes or exhausts the stack. amath therefore hooks
+`Parsanol::Native.raise_native_parse_error` (a prepended module, active only
+on the current thread while amath's own native call runs) and stops at the
+native failure. Then:
+
+* `engine: :auto` parses the input with the Ruby engine (`last_engine` is
+  `:ruby`), as it also does when the native call raises `SystemStackError`;
+* `engine: :native` raises `Amath::NestingTooDeep` (`last_engine` is
+  `:native`).
+
+The Ruby engine has no fixed limit but is bounded by the Ruby stack. On the
+main thread it parses 1,000 levels of `(`; rejecting deep invalid input needs
+more stack, because Parsanol reparses it with its recursive interpreter to
+find the position, so a rejection of input a few hundred levels deep can
+raise `Amath::NestingTooDeep` instead of a positioned `ParseError`. amath
+never lets `SystemStackError` escape from `Amath.parse`.
+
+== Errors
+
+All deliberate errors inherit from `Amath::Error < StandardError`.
+
+`Amath::ParseError`::
+The input is not valid AsciiMath for the selected decimal marker. Full
+consumption is required: a valid prefix followed by invalid text is a
+rejection, never a partial tree. Attributes:
++
+* `byte_offset` — zero-based UTF-8 byte offset of the deepest failure;
+* `char_offset` — the same position in characters;
+* `input` — the (UTF-8) string that was parsed.
++
+The message text is for humans and is not part of the contract. The original
+`Parsanol::ParseFailed` is available as `cause`.
+
+`Amath::NestingTooDeep < Amath::ParseError`::
+The input nests deeper than the engine that ran can handle: the native
+engine's recursion limit under `engine: :native`, or an exhausted Ruby stack
+under any engine. See <<deep-nesting>>. `byte_offset` and `char_offset` are
+`nil`, since no rejection position was found; `input` is set. Whether such
+input is valid AsciiMath is not known.
+
+`Amath::ArtifactError`::
+The artifact is missing, is not valid JSON, is not a JSON object, fails its
+checksum, declares an unsupported shape, lacks a required entry, or cannot be
+compiled or registered by the installed Parsanol. Raised under every engine
+setting. amath never falls back to another artifact or grammar and never
+recompiles anything except the artifact's own embedded source (Parsanol's
+documented pure-Ruby path).
+
+`Amath::EngineUnavailable`::
+`engine: :native` was requested and the native extension is not available.
+
+`ArgumentError`::
+Unknown `decimal:` or `engine:`, non-String input, or input that is not valid
+UTF-8.
+
+== Positions: bytes versus characters
+
+Parsanol reports positions in *bytes*; Parslet reported them in *characters*.
+They differ as soon as the input contains non-ASCII text.
+
+* `Parsanol::Slice#offset` is a zero-based byte offset. Note that
+  `Parsanol::Slice#charpos` is an alias of `offset` and is *also* a byte
+  offset.
+* `Amath::ParseError#byte_offset` is a byte offset and `#char_offset` is the
+  character offset computed by amath.
+
+Example: in `text(é) x`, the leaf `x` has `offset == 9`, while it is
+character 8. To convert a byte offset to Parslet's character offset:
+
+[source,ruby]
+----
+char = input.byteslice(0, byte_offset).length
+----
+
+where `input` is the UTF-8 string passed to `Amath.parse`.
+
+Known difference from Parslet: the deepest rejection position can differ by
+one. For `x 1.` the A0 spike measured Parslet's deepest failure at 3 and
+Parsanol's at 4. The conformance corpus records the agreed position per case.
+
+== Artifact loading
+
+The artifact path defaults to `artifacts/asciimath.json` inside the installed
+gem (`Amath::DEFAULT_ARTIFACT_PATH`). It is loaded and checksum-verified once,
+on first use, and cached for the process. Assigning `Amath.artifact_path=`
+clears the cache; it exists for tests and tooling, not for selecting
+alternative grammars in production.

data/lib/amath/artifact.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Amath
+  # The compiled grammar artifact Amath parses with: loaded and verified
+  # once per path, and reloaded after the path changes.
+  class Artifact
+    # Loads the Parsanol::PARG::Artifact at +path+ and checks it has an
+    # entry for every decimal marker. Every load failure is an ArtifactError.
+    def self.load(path)
+      raise ArtifactError, "artifact not found: #{path}" unless File.file?(path)
+
+      artifact = Parsanol::PARG::Artifact.load(path)
+      missing = Configuration::DECIMAL_ENTRIES.values - artifact.entries
+      unless missing.empty?
+        raise ArtifactError,
+              "artifact #{path} lacks required entries: #{missing.join(', ')}"
+      end
+
+      artifact
+    rescue JSON::ParserError => e
+      raise ArtifactError,
+            "artifact #{path} is not valid JSON: #{e.message.lines.first&.strip}"
+    rescue Parsanol::PARG::Error, SystemCallError, KeyError, TypeError,
+           NoMethodError => e
+      raise ArtifactError,
+            "artifact #{path} is invalid: #{e.class}: #{e.message}"
+    end
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      @loaded = nil
+      @lock = Mutex.new
+    end
+
+    # Clears the loaded artifact so the next #fetch loads +path+.
+    def path=(path)
+      @lock.synchronize do
+        @path = path.to_s
+        @loaded = nil
+      end
+    end
+
+    # The Parsanol::PARG::Artifact at #path, loaded on first use.
+    def fetch
+      @lock.synchronize { @loaded ||= self.class.load(@path) }
+    end
+  end
+end

data/lib/amath/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Amath
+  # Fixed settings: the artifact entries, the engine names and where the
+  # bundled artifact lives. Amath re-exports each constant.
+  module Configuration
+    # Decimal marker => artifact entry name.
+    DECIMAL_ENTRIES = {
+      "." => "dot",
+      "," => "comma",
+      "٫" => "arabic", # ARABIC DECIMAL SEPARATOR
+    }.freeze
+
+    ENGINES = %i[auto native ruby].freeze
+
+    # Deepest bracket nesting sent to the native engine off the main thread.
+    THREAD_NATIVE_DEPTH = 25
+    OPENING = "([{\u2112\u1455".chars.freeze
+    CLOSING = ")]}\u211b\u1450".chars.freeze
+
+    DEFAULT_ARTIFACT_PATH = File.expand_path("../../artifacts/asciimath.json",
+                                             __dir__)
+  end
+end

data/lib/amath/engine.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Amath
+  # Runs a parse on the native or Ruby Parsanol engine: resolves the
+  # requested engine, reruns input too deep for native on Ruby under
+  # engine: :auto, maps Parsanol failures to Amath errors, and records the
+  # engine that produced the result per thread.
+  module Engine
+    LAST_ENGINE_KEY = :amath_last_engine
+
+    module_function
+
+    # See Amath.last_engine.
+    def last_engine
+      Thread.current[LAST_ENGINE_KEY]
+    end
+
+    def native_available?
+      Parsanol::Native.available?
+    rescue LoadError, StandardError
+      false
+    end
+
+    # The engine (:native or :ruby) that +engine+ (one of ENGINES) runs.
+    def resolve(engine)
+      case engine
+      when :auto then native_available? ? :native : :ruby
+      when :ruby then :ruby
+      when :native
+        return :native if native_available?
+
+        raise EngineUnavailable,
+              "engine: :native requested but the Parsanol native extension " \
+              "is not available on this platform (#{RUBY_PLATFORM}, Ruby #{RUBY_VERSION})"
+      else
+        raise ArgumentError,
+              "unknown engine #{engine.inspect} (use #{Configuration::ENGINES.map(&:inspect).join(', ')})"
+      end
+    end
+
+    # Parses +text+ from +entry+ on +mode+ and returns the tree.
+    def run(artifact, entry, text, mode, fallback:)
+      tree, ran = run_with_fallback(artifact, entry, text, mode,
+                                    fallback: fallback)
+      record(ran)
+      tree
+    end
+
+    # Runs +mode+ and returns [tree, engine that produced it]. Under :auto
+    # (+fallback+), input nested too deeply for the native engine is rerun
+    # on the Ruby engine: either native's own recursion limit, or the Ruby
+    # stack running out inside the native call (threads other than the
+    # main one have a 1 MiB machine stack by default).
+    def run_with_fallback(artifact, entry, text, mode, fallback:)
+      if mode == :native && too_deep_for_native_thread?(text)
+        record(:native)
+        unless fallback
+          raise native_too_deep(
+            text,
+            "nesting depth over #{Configuration::THREAD_NATIVE_DEPTH} " \
+            "off the main thread",
+          )
+        end
+
+        return [run_mode(artifact, entry, text, :ruby), :ruby]
+      end
+
+      [run_mode(artifact, entry, text, mode), mode]
+    rescue NativeRecursionLimit => e
+      record(:native)
+      raise native_too_deep(text, e.message) unless fallback
+
+      [run_mode(artifact, entry, text, :ruby), :ruby]
+    rescue NestingTooDeep
+      raise unless fallback && mode == :native
+
+      [run_mode(artifact, entry, text, :ruby), :ruby]
+    end
+
+    # Off the main thread the machine stack is small (1 MiB by default) and
+    # the native engine overflows it at about 40 levels of brackets. A Ruby
+    # stack overflow inside the native call crashes the process instead of
+    # raising, so deep input never reaches native there.
+    def too_deep_for_native_thread?(text)
+      return false if Thread.current.equal?(Thread.main)
+
+      depth = 0
+      max = 0
+      text.each_char do |char|
+        if Configuration::OPENING.include?(char)
+          depth += 1
+          max = depth if depth > max
+        elsif Configuration::CLOSING.include?(char)
+          depth -= 1 if depth.positive?
+        end
+      end
+      max > Configuration::THREAD_NATIVE_DEPTH
+    end
+
+    def native_too_deep(text, detail)
+      NestingTooDeep.new(
+        "AsciiMath input nests deeper than the native engine's recursion limit " \
+        "(#{detail}); use engine: :ruby or engine: :auto",
+        input: text, byte_offset: nil, char_offset: nil,
+      )
+    end
+
+    def run_mode(artifact, entry, text, mode)
+      # Parsanol's mode: :native silently runs Ruby when the extension is
+      # missing; resolve has already checked availability.
+      if mode == :native
+        NativeRecursionGuard.watch do
+          artifact.parse(entry, text, mode: :native)
+        end
+      else
+        artifact.parse(entry, text, mode: mode)
+      end
+    rescue Parsanol::ParseFailed => e
+      record(mode)
+      raise parse_error(e, artifact, entry, text)
+    rescue SystemStackError
+      record(mode)
+      raise NestingTooDeep.new(
+        "AsciiMath input nests too deeply for the #{mode} engine (Ruby stack exhausted)",
+        input: text, byte_offset: nil, char_offset: nil,
+      )
+    rescue Parsanol::PARG::Error, Parsanol::GrammarError,
+           Parsanol::Native::UnsupportedGrammar => e
+      raise ArtifactError,
+            "artifact #{Amath.artifact_path} cannot be used: #{e.class}: #{e.message}"
+    end
+
+    def parse_error(error, artifact, entry, text)
+      byte = ErrorPosition.byte_offset(error, artifact, entry, text)
+      char = byte && ErrorPosition.char_offset(text, byte)
+      where = byte ? " at character #{char} (byte #{byte})" : ""
+      ParseError.new("AsciiMath input rejected#{where}: #{error.message.lines.first&.strip}",
+                     input: text, byte_offset: byte, char_offset: char)
+    end
+
+    def record(mode)
+      Thread.current[LAST_ENGINE_KEY] = mode
+    end
+
+    private_class_method :run_with_fallback, :native_too_deep, :run_mode,
+                         :parse_error, :record, :too_deep_for_native_thread?
+  end
+end

data/lib/amath/error_position.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Amath
+  # Where a rejected input failed, reported the way Plurimath's Parslet
+  # parser did.
+  module ErrorPosition
+    module_function
+
+    # The zero-based byte offset of the rejection +failure+ (a
+    # Parsanol::ParseFailed for +text+ from +entry+), or nil if none is known.
+    def byte_offset(failure, artifact, entry, text)
+      parslet_position(artifact, entry,
+                       text) || deepest_position(failure.parse_failure_cause)
+    end
+
+    # The character offset of byte offset +byte+ in +text+.
+    def char_offset(text, byte)
+      text.byteslice(0, byte).force_encoding(Encoding::UTF_8).scrub.length
+    end
+
+    # The rejection position Plurimath's Parslet parser reported: the
+    # deepest *leaf* of the cause tree built by a Parslet-style Tree
+    # reporter, which holds only the failures that caused the final
+    # rejection. Neither engine's own cause gives this: the native engine
+    # returns one childless cause at its farthest failure, and the Ruby
+    # engine's Deepest reporter grafts in failures from branches that
+    # later succeeded, so both can point past Parslet's position. The
+    # interpreter reparse runs only on rejection. Returns nil if that
+    # reparse unexpectedly accepts, so the caller falls back.
+    #
+    # The interpreter and deepest_leaf recurse once per nesting level; if
+    # that exhausts the stack on very deep input, this returns nil too.
+    def parslet_position(artifact, entry, text)
+      cause = begin
+        artifact.root_atom(entry).parse(text, reporter: Parsanol::ErrorReporter::Tree.new)
+        nil
+      rescue Parsanol::ParseFailed => e
+        e.parse_failure_cause
+      end
+      cause && deepest_leaf(cause)
+    rescue SystemStackError
+      nil
+    end
+
+    # Parslet's rule: a node with children reports no position of its own.
+    def deepest_leaf(cause)
+      children = cause.children.compact
+      return cause.position if children.empty?
+
+      children.filter_map { |c| deepest_leaf(c) }.max
+    end
+
+    # Iterative: the cause tree of a deeply nested input is as deep as the
+    # input, so recursion here could exhaust the stack.
+    def deepest_position(cause)
+      deepest = nil
+      stack = [cause].compact
+      until stack.empty?
+        node = stack.pop
+        deepest = node.position if node.position && (deepest.nil? || node.position > deepest)
+        stack.concat(node.children.compact)
+      end
+      deepest
+    end
+
+    private_class_method :parslet_position, :deepest_leaf, :deepest_position
+  end
+end