plurimath 0.11.12 → 0.11.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4113e509a9cfc9298026571f3c9231f5ffba3ddf9f7307a66fd6335383c4a940
-  data.tar.gz: a51115633f6392f2940cb266823a77d660d701867f4c507f6a9e787b84da82b4
+  metadata.gz: e4112028ba3d71553b4695b371e34b8ba481739085e6d330fcba281970482f35
+  data.tar.gz: 1bf3a115ef3dc443d1c02d7e15d288f336177830dbcccbc00b68309c8cf05352
 SHA512:
-  metadata.gz: 0450ed469724fc5117b04f24ee0fba4ba91810978943c3c3d08fe6db0ae98bcaa4e5a874a3c41ce05e9671f489941529c34ae6c35f1f5575dd033ddd99987ea2
-  data.tar.gz: 9f9a4dc4287cfda6c8f4128ab0e795c6772b1d12bfb3fa9ec56a0a88c4e9c45a7a8fd1941305fdf2cbf7b2a46cbcda879bf500196caa71bddae4ea837d668942
+  metadata.gz: 28c135b5a874a229183a29adb31d1ef34ad2b700927800c6e557e83a2fa681afb959e3c95f7eb696c0fdaa7f5a2daeb7d7784e11f5db6f1f75e26a3de8ea1e11
+  data.tar.gz: 04fb461b9990cc43cb3ef39b5948eb76248e175d3d5bb8bf34a5d83958ed4fe29b843d06aa5c02c3f85684dce26b93c88ad16f8ba6ddcbb7168642c59fb1875c

data/.github/workflows/dependent-tests.yml

@@ -14,4 +14,11 @@ jobs:
     uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
     with:
       command: bundle exec rspec
+      # Remove the source bootstrap once the amath runtime dependency in #512 is available.
+      after-setup-ruby: |
+        set -euo pipefail
+        git init ../amath
+        git -C ../amath fetch --depth 1 https://github.com/plurimath/amath.git b67f924477ce129e85926eda5973d771c007dfec
+        git -C ../amath checkout --detach FETCH_HEAD
+        printf '\ngem "amath", path: "../amath"\ngem "parsanol", "~> 1.3", ">= 1.3.112"\n' >> Gemfile
       repos-json-file: .github/workflows/dependent-repos-ruby.json

data/.github/workflows/shared-testsuite.yml

@@ -0,0 +1,24 @@
+name: Shared conformance suite
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  conformance:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0.1"
+          bundler-cache: true
+      - name: Run shared YAML conformance cases
+        run: bundle exec rspec spec/conformance --format progress

data/.gitmodules

@@ -1,3 +1,6 @@
 [submodule "submodules/unicodemath-tests"]
 	path = submodules/unicodemath-tests
 	url = git@github.com:plurimath/unicodemath-tests.git
+[submodule "submodules/plurimath-testsuite"]
+	path = submodules/plurimath-testsuite
+	url = https://github.com/plurimath/plurimath-testsuite.git

data/.rspec-opal

@@ -9,3 +9,6 @@
 --format documentation
 --color
 --require spec_helper
+
+# The shared corpus adapter uses native filesystem/YAML validation.
+--exclude-pattern=spec/conformance/**/*_spec.rb

data/Gemfile

@@ -4,11 +4,29 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
+# Optional native image-rendering backend for `Formula#render` / `plurimath
+# render`. Git-pinned until `lasem` ships to RubyGems; intentionally NOT a
+# gemspec runtime dependency so Opal/plurimath-js and lasem-less installs keep
+# working. For local dev against an in-progress checkout:
+#   bundle config set --local local.lasem /path/to/lasem-ruby
+gem "lasem", github: "plurimath/lasem-ruby", branch: "main", submodules: true
 # gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
 gem "oga"
+# spec_helper selects the Nokogiri adapter directly.
+gem "nokogiri"
+# AsciiMath parser; tracks amath main until a release is published.
+# AMATH_PATH points at a local amath checkout instead.
+if ENV["AMATH_PATH"]
+  gem "amath", path: ENV["AMATH_PATH"]
+else
+  gem "amath", github: "plurimath/amath", ref: "b67f924477ce129e85926eda5973d771c007dfec"
+end
 # gem "omml", github: "plurimath/omml", branch: "main"
 gem "opal-rspec", "~> 1.1.0a"
 gem "ox"
+# Parsanol::Slice for the amath SliceAdapter specs.
+# 1.3.112 restores the v1 edition default (1.3.110 and 1.3.111 are yanked).
+gem "parsanol", "~> 1.3", ">= 1.3.112"
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
 gem "rubocop-performance"

data/README.adoc

@@ -13,7 +13,8 @@ remains consistent and accurate regardless of the format it is presented in.
 Supported math representational languages:
 
 * https://www.w3.org/TR/MathML3/[MathML 3] (and https://www.w3.org/TR/mathml4/[MathML 4])
-* https://www.asciimath.org[AsciiMath]
+* https://www.asciimath.org[AsciiMath] (parsed by the
+https://github.com/plurimath/amath[amath] gem)
 * http://unicodemath.org[UnicodeMath] (https://www.unicode.org/notes/tn28/UTN28-PlainTextMath-v3.2.pdf[UnicodeMath v3.2])
 * LaTeX math
 * Microsoft Office Math Markup Language (OMML) https://devblogs.microsoft.com/math-in-office/officemath/["OfficeMath"]
@@ -38,6 +39,13 @@ Accessibility:: Convert mathematical content into formats that are more
 accessible for screen readers and other assistive technologies.
 
 
+== Reference catalog
+
+`Plurimath::Catalog.entries` generates reference data for documented functions,
+including each serializer's output and separate availability notes. See
+link:docs/catalog.adoc[the Ruby catalog contract] for the entry schema and export rules.
+
+
 == Installation
 
 Add this line to your application's Gemfile:
@@ -142,6 +150,68 @@ plurimath help convert
 ----
 
 
+=== Rendering images
+
+The `render` command rasterizes or vectorizes a formula to an image
+(`svg`, `png`, `pdf`, or `ps`) using the optional
+https://github.com/plurimath/lasem-ruby[`lasem`] gem (a native extension
+wrapping the Lasem C library). Image rendering is OPTIONAL: Plurimath works
+fully without it, and it is unavailable under Opal/plurimath-js. See
+<<image-rendering,Rendering to images>> for installing the backend.
+
+[source,bash]
+----
+plurimath render [options]
+----
+
+Options mirror `convert` for the input side (`-i`, `-f`, `-p`, `-e`), plus:
+
+`-o`, `--output <FILE>`::
+Output file path. The image format is taken from its extension
+(`.svg`/`.png`/`.pdf`/`.ps`); an extension outside that set is an error. When
+omitted, the rendered bytes are written to standard output.
+
+`-r`, `--format <FORMAT>`::
+Image format (`svg`, `png`, `pdf`, `ps`). Used when `--output` has no usable
+extension or when writing to standard output (a file's extension takes
+precedence). Defaults to `svg`.
+
+`-d`, `--display-style`::
+DisplayStyle, boolean. Defaults to the parsed formula's display style.
+
+`-s`, `--split-on-linebreak`::
+Boolean. Note that lasem renders a single MathML document, so this mainly
+affects the serialized MathML rather than producing multiple images.
+
+`-e`, `--xml-engine <ENGINE>`::
+XML engine used to parse the input (`ox` or `oga`). Defaults to `ox`.
+
+`--ppi`, `--zoom`, `--width`, `--height`, `--offset-x`, `--offset-y`::
+Numeric geometry options passed through to lasem; omit them to use lasem's
+defaults.
+
+[example]
+.Render an AsciiMath equation to a PNG file
+====
+[source,bash]
+----
+plurimath render -i "sqrt(x^2 + y^2)" -f asciimath -o formula.png --ppi 144
+----
+====
+
+[example]
+.Render a LaTeX file to SVG on standard output
+====
+[source,bash]
+----
+plurimath render -p formula.tex -f latex -r svg > formula.svg
+----
+====
+
+If the `lasem` backend is unavailable, the format is unsupported, or rendering
+fails, the command prints a message and exits with a non-zero status.
+
+
 == Ruby API
 
 
@@ -457,6 +527,69 @@ omml = formula.to_omml
 ----
 
 
+[#image-rendering]
+=== Rendering to images
+
+`Formula#render` produces a binary image (`:svg`, `:png`, `:pdf`, or `:ps`) by
+serializing the formula to MathML and handing it to the optional
+https://github.com/plurimath/lasem-ruby[`lasem`] gem, a native extension
+wrapping the Lasem C library. `lasem` is an OPTIONAL, soft dependency: it is not
+a runtime dependency of Plurimath, is unavailable under Opal/plurimath-js, and
+must be added explicitly.
+
+Until `lasem` is published to RubyGems, pin it via Git in your `Gemfile`:
+
+[source,ruby]
+----
+gem "lasem", github: "plurimath/lasem-ruby", branch: "main", submodules: true
+----
+
+Then verify the native toolchain (cairo, pango, and the Lasem C library):
+
+[source,sh]
+----
+bundle exec lasem-doctor
+----
+
+Render with `Formula#render`:
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("sum_(i=1)^n i", "asciimath")
+
+svg = formula.render(format: :svg)
+png = formula.render(format: :png, ppi: 144, zoom: 2)
+File.binwrite("sum.png", png)
+----
+
+Or render directly from source in one step with `Plurimath::Math.render`, which
+parses and then renders (parse options such as `:locale` are routed to parsing):
+
+[source,ruby]
+----
+png = Plurimath::Math.render("sum_(i=1)^n i", "asciimath", format: :png, ppi: 144)
+File.binwrite("sum.png", png)
+
+# Check availability before rendering to avoid a raise:
+Plurimath::Math.render_available? # => true / false (always false under Opal)
+----
+
+Supported `format:` values are `:svg`, `:png`, `:pdf`, `:ps`. Remaining keyword
+options are split between the MathML serialization (`:display_style`,
+`:intent`, `:formatter`, `:unitsml`, `:unary_function_spacing`,
+`:split_on_linebreak`) and the lasem renderer (`:ppi`, `:zoom`, `:width`,
+`:height`, `:offset_x`, `:offset_y`); omit the geometry options to use lasem's
+defaults. When `:display_style` is omitted the formula's own display style is
+used.
+
+If `lasem` or its native extension is unavailable, the format is unsupported, or
+rendering fails, a `Plurimath::Errors` rendering error is raised
+(`RenderingUnavailable`, `UnsupportedRenderFormat`, or `RenderingFailed` — all
+subclasses of `Plurimath::Error`); the unavailable message points you to
+`lasem-doctor`. A malformed formula surfaces as `Plurimath::Math::ParseError`
+from the MathML step, not as a rendering error.
+
+
 == Number formatting
 
 === Introduction
@@ -2099,8 +2232,29 @@ of the parsed mathematical expression.
 ----
 formula = Plurimath::Math.parse("sin(1)", :asciimath)
 formula.to_display(:formula)
-# ...
-----
+# Plurimath::Math::Formula
+#   value[0]: Plurimath::Math::Function::Sin
+#     parameter_one: Plurimath::Math::Function::Fenced
+#       parameter_one: Plurimath::Math::Symbols::Paren::Lround
+#         value: nil
+#       parameter_two[0]: Plurimath::Math::Number
+#         value: "1"
+#       parameter_three: Plurimath::Math::Symbols::Paren::Rround
+#         value: nil
+----
+
+This tree shows the stored Ruby objects, with their full class names and ordered
+content fields. Array entries have indexes; empty arrays are shown as `[]` and
+absent values as `nil`. Some symbol classes, such as `Lround`, represent their
+symbol through the class itself and store no literal value. String literals are
+escaped, so quotes, backslashes and newlines stay on one tree line.
+
+The tree preserves `Formula` and `Fenced` wrappers and does not group operators:
+the stored siblings in `a+b` remain siblings. It includes `value`, function
+parameters, table delimiters, UnitsML text and the declared uncertainty fields.
+Formatting flags and options, original input text, XML internals and rendering
+caches are omitted. Repeated references appear at each position; a reference to
+an ancestor is marked `<cycle: ClassName>`.
 
 === Displaying in the math language of expression
 
@@ -2131,6 +2285,107 @@ formula.to_display(:mathml)
 #            |_ "<mtext>1</mtext>" text
 ----
 
+=== Displaying a semantic operator tree
+
+Use `tree: :semantic` to see which operands each operator owns. The default
+`tree: :display` keeps the display tree shown above. Both views support
+`:asciimath`, `:latex`, `:mathml`, `:omml`, and `:unicodemath`; semantic expression,
+operand-role and leaf labels use the existing writer for the selected language.
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("a+b*c", :asciimath)
+puts formula.to_display(:unicodemath, tree: :semantic)
+# |_ Semantic tree
+#    |_ expression "a + b × c"
+#       |_ add "+"
+#          |_ symbol "a"
+#          |_ multiply
+#             |_ symbol "b"
+#             |_ symbol "c"
+----
+
+The semantic view shares numeric evaluation's precedence parser, but does not
+evaluate numbers or require variable bindings. It distinguishes explicit and
+implicit multiplication, retains explicit round groups, and preserves the
+parser's left nesting for chained subtraction, powers, and relations. Fractions,
+radicals, scripts, function arguments, and integral limits remain attached to
+their owning nodes. Fractions expose numerator and denominator roles; functions
+expose their name and argument; powers expose base and script. A square root
+exposes the implicit-degree placeholder `⬚` and its radicand. Unbounded and
+partly bounded integrals, sums and products also retain their body, and a powered
+function such as `sin^2 x` binds `x` as the function argument inside the power.
+
+For example, the original integral expression produces this UnicodeMath view:
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse(
+  '1/(2pi) int_0^(2pi) (bbb"d" theta) / (a + b sin⁡ theta) = 1/sqrt(a^2−b^2)',
+  :asciimath,
+)
+puts formula.to_display(:unicodemath, tree: :semantic)
+# |_ Semantic tree
+#    |_ expression "(1)/(2 π) ∫_(0)^(2 π)▒〖(\\Bbb\"d\" θ)/(a + b sin⁡θ)〗 = (1)/(√(a^(2) − b^(2)))"
+#       |_ relation "="
+#          |_ implicit multiply
+#             |_ fraction "(1)/(2 π)"
+#                |_ numerator "1"
+#                   |_ number "1"
+#                |_ denominator "2 π"
+#                   |_ implicit multiply
+#                      |_ number "2"
+#                      |_ symbol "π"
+#             |_ integral "∫_(0)^(2 π)▒〖(\\Bbb\"d\" θ)/(a + b sin⁡θ)〗"
+#                |_ lower limit "0"
+#                   |_ number "0"
+#                |_ upper limit "2 π"
+#                   |_ implicit multiply
+#                      |_ number "2"
+#                      |_ symbol "π"
+#                |_ integrand "(\\Bbb\"d\" θ)/(a + b sin⁡θ)"
+#                   |_ fraction "(\\Bbb\"d\" θ)/(a + b sin⁡θ)"
+#                      |_ numerator "\\Bbb\"d\" θ"
+#                         |_ implicit multiply
+#                            |_ symbol "\\Bbb\"d\""
+#                            |_ symbol "θ"
+#                      |_ denominator "a + b sin⁡θ"
+#                         |_ add "+"
+#                            |_ symbol "a"
+#                            |_ implicit multiply
+#                               |_ symbol "b"
+#                               |_ apply "sin⁡θ"
+#                                  |_ function name "sin"
+#                                  |_ argument "θ"
+#                                     |_ symbol "θ"
+#          |_ fraction "(1)/(√(a^(2) − b^(2)))"
+#             |_ numerator "1"
+#                |_ number "1"
+#             |_ denominator "√(a^(2) − b^(2))"
+#                |_ square root "√(a^(2) − b^(2))"
+#                   |_ degree "⬚"
+#                   |_ radicand "a^(2) − b^(2)"
+#                      |_ subtract "−"
+#                         |_ power "a^(2)"
+#                            |_ base "a"
+#                               |_ symbol "a"
+#                            |_ script "2"
+#                               |_ number "2"
+#                         |_ power "b^(2)"
+#                            |_ base "b"
+#                               |_ symbol "b"
+#                            |_ script "2"
+#                               |_ number "2"
+----
+
+The double-struck `d` remains a styled symbol multiplied by `theta`; the view
+does not infer a differential. It builds a temporary rendering view and leaves
+the stored Formula model unchanged. This is not a general symbolic algebra
+engine: unsupported or ambiguous constructs, including tables, text runs,
+non-round fences, missing operands, and adjacent number literals, raise
+`Plurimath::Errors::UnsupportedSemanticTreeError` naming the construct. Unknown
+`tree:` values raise `ArgumentError`.
+
 // == Integration
 
 // Integrate Plurimath into your project by requiring the gem and using its
@@ -2375,6 +2630,45 @@ NOTE: To regenerate these files, delete them and run:
 * link:OMML-Supported-Data.adoc[OMML Supported Data]
 * link:UnitsML-Supported-Data.adoc[UnitsML Supported Data]
 
+== Shared conformance fixtures
+
+The language-independent YAML expectations used by the TypeScript port are
+pinned at `submodules/plurimath-testsuite`. Initialize the test data before
+running specs:
+
+[source,sh]
+----
+git submodule update --init --recursive
+bundle exec rspec spec/conformance
+----
+
+The conformance specs validate the dataset and compare preprocessing, parser
+trees, formula models, rendering outcomes, rejection positions and recorded
+formatter/UnitsML calls. Cases are read directly from the pinned repository;
+the test run never regenerates expectations. Missing, empty or unsupported
+corpora fail the run. The golden bytes were recorded with Ox, so these specs
+run once with Ox. Existing native specs still run with Ox and Oga. The native
+filesystem/YAML adapter is excluded from Opal test discovery.
+
+Portable parser and renderer expectations also live in the pinned repository's
+`fixtures/` directory. Native specs select shared case IDs instead of embedding
+expected trees, constructor graphs or output strings. The authored datasets
+retain each assertion's source revision and location. They are extracted from
+the original expectations, independently of production parser or renderer output.
+
+The adapters preserve the original entry points, argument types, configuration,
+operation order and comparisons. Typed constructor recipes distinguish symbols,
+string keys, positional arguments and keyword arguments. Memo references preserve
+sharing within one example, while each example receives fresh mutable values.
+Raw grammar fixtures preserve their preprocessing and tree projection steps.
+External UnicodeMath fixtures retain the original inputs, expected raw trees,
+models and refusal patterns.
+
+These examples continue to run through the native Ox/Oga hooks. Node/Opal uses
+the same YAML files from the checkout. Ruby API, configuration, identity and
+extension-hook tests remain native. Missing cases, unsupported schemas and
+unknown recipe operations fail rather than silently skipping coverage.
+
 == Copyright and license
 
 Copyright Ribose. BSD 2-clause license.

data/docs/catalog.adoc

@@ -0,0 +1,73 @@
+= Ruby reference catalog
+
+`Plurimath::Catalog.entries` returns plain Ruby hashes suitable for YAML or JSON
+export. The catalog describes the Ruby implementation. TypeScript conformance
+is separate work and does not gate the Ruby catalog.
+
+== Entry identity and compatibility
+
+Each entry has a safe lowercase `name` and a `kind`: `function` or `symbol`.
+Use the pair `[kind, name]` as its identity. A function and symbol may share a
+name, such as `bar`; write them to separate directories.
+The catalog rejects duplicate identities instead of allowing exports to overwrite
+one another.
+
+`arity` is the reference-page category (`unary`, `binary`, or `ternary`) for a
+function, and `nil` for a symbol. It describes the reference classification,
+not the number of arguments accepted by a Ruby constructor.
+
+The legacy `type` field remains unchanged: it holds the function's reference
+category, or `symbol`. Function entries retain `description` and `reference`;
+symbol entries omit them. Existing `asciimath`, `latexmath`, `mathml`, and `omml`
+fields retain the serializers' exact output, including empty strings and
+placeholders. The additional metadata does not repair or rewrite serializer output.
+
+== Format availability
+
+`formats` contains an entry for each of the four serialization formats:
+
+[source,ruby]
+----
+entry = Plurimath::Math::Function::Sum.catalog_entry
+entry["kind"]                         # => "function"
+entry["arity"]                        # => "ternary"
+entry["formats"]["mathml"]["status"]   # => "available"
+entry["formats"]["mathml"]["notes"]    # => []
+----
+
+* `available`: the serializer returns nonempty output and no limitation is
+  declared. This is not proof of semantic parity or round-trip correctness.
+* `limited`: a known loss or limitation is described in `notes`.
+* `unavailable`: output is empty or the declaration identifies an unsupported
+  representation, including nonempty placeholders. `notes` explains why.
+
+Consumers should read this metadata before presenting an example as supported.
+Unexpected serializer exceptions still propagate; the catalog does not convert
+programming failures into a successful availability record.
+
+A class can declare its own limitations without affecting sibling classes:
+
+[source,ruby]
+----
+CATALOG_FORMAT_LIMITATIONS = {
+  mathml: { status: :limited, notes: ["The current serializer omits a modifier."] },
+}.freeze
+----
+
+Declarations use canonical keys `asciimath`, `latexmath`, `mathml`, and `omml`.
+Keys and statuses accept strings or symbols. A declaration must use `limited`
+or `unavailable` and include a nonempty array of explanatory strings.
+Empty serializer output always becomes `unavailable`, with a reason.
+
+== Validation and extension classes
+
+The shared entry builder validates required fields, safe slugs, type/kind/arity
+agreement, format records, and limitation declarations. Invalid data raises
+`Plurimath::Catalog::InvalidEntryError`, a subclass of `ArgumentError`.
+`Plurimath::Catalog::Validation.validate_all!(entries)` also checks identity
+uniqueness when validating an exported array.
+
+Function classes need their own description, reference, and deferred example
+to be documentable. Anonymous classes are excluded because they have no stable
+Ruby name. Examples and format notes are built afresh; modifying returned notes
+does not modify the class's declarations.

data/docs/uncertainty-asciimath-tree.md

@@ -0,0 +1,92 @@
+# AsciiMath uncertainty: parse tree contract (plurimath#493, B4)
+
+The amath grammar turns `ustd(...)`, `uexp(...)` and `ucov(...)` into the tree
+below. `Plurimath::Asciimath::Transform` (rule `uncertainty:`) turns it into
+`Math::Function::Uncertainty`. Design: `docs/uncertainty.adoc`; cases:
+`spec/plurimath/fixtures/uncertainty/contract.yml`; spec that checks this
+tree against amath, the transform and `Math.parse`, and round-trips every case
+through `to_asciimath`: `spec/plurimath/asciimath/uncertainty_spec.rb`.
+
+## Shape
+
+The node sits where any other operand sits, for example as the whole formula:
+
+```ruby
+{ expr: { sequence: { uncertainty: { uncertainty_class: "uexp", value: "10.0",
+                                     magnitude: "0.3", coverage_factor: "2" } } } }
+```
+
+Every leaf under `uncertainty:` is a `Parslet::Slice` holding the text exactly
+as written (no `{number: ...}` wrapper, no sign or whitespace). Keys absent from
+the input are left out, never given as nil.
+
+| Input | Keys under `uncertainty:` |
+|---|---|
+| `ustd(y, u)` | `uncertainty_class: "ustd"`, `value`, `magnitude` |
+| `ustd(y(d))` | `uncertainty_class: "ustd"`, `value`, `concise_digits` |
+| `uexp(y, U, k[, p])` | `uncertainty_class: "uexp"`, `value`, `magnitude`, `coverage_factor`[, `coverage_probability`] |
+| `ucov(y, lo, hi, p[, kind])` | `uncertainty_class: "ucov"`, `value`, `lower`, `upper`, `coverage_probability`[, `interval_kind`] |
+| `..., "unitsml(g)")` (last argument, any form) | adds `unit: "g"` (the text inside `unitsml(...)`) |
+
+- `value` may carry a leading `-`; every other number is unsigned. The decimal
+  marker is always a full stop, whatever the locale.
+- `concise_digits` is the digit run inside the inner brackets: `ustd(1.230(4))`
+  gives `value: "1.230"`, `concise_digits: "4"`. The transform turns it into
+  `magnitude: 0.004`, `notation: :concise`.
+- `unit` must not use the existing `{unitsml: ...}` key: that rule turns the unit
+  into a rendered `Formula`, but the node keeps a `Math::Function::Unitsml`.
+
+## Shared decimal exponents
+
+The following call forms add an optional `shared_exponent` slice containing
+signed exponent digits without `e`. No space is allowed before `e`:
+
+```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)
+```
+
+The transform shifts the decimal point using strings, never floating-point
+arithmetic. It scales value and magnitude, or value and both interval
+endpoints; coverage factors and probabilities remain unchanged. Concise
+magnitude is derived before applying the scale. The first two examples yield
+`38500` with magnitude `2300`, and `0.680` with magnitude `0.041`.
+Trailing decimal zeros remain significant stored text. Writers emit the
+normalized existing uncertainty form, which can be read back into the same
+model.
+
+Existing calls omit this key and retain their behavior. Bare inline uncertainty
+is part of the separate expression-language work in #513. To bound allocation,
+the reader rejects a shared exponent that would expand a number beyond
+1,000,000 decimal characters with `Errors::InvalidUncertainty`; no partial
+number or rounded approximation is returned.
+
+The shipped amath corpus `corpora/uncertainty-shared-exponent.yml` contains the
+input trees and exact normalized model expectations checked by the reader specs.
+
+## Interval kind spelling
+
+`interval_kind` is a bare word: `shortest` or `symmetric`.
+`probabilistically-symmetric` cannot be used, because AsciiMath reads the `-` as
+minus. `symmetric` means the probabilistically symmetric coverage interval of
+JCGM 101 §5.3.4 and maps to `:probabilistically_symmetric`. The output side
+(`Uncertainty#to_asciimath`, which today writes `probabilistically-symmetric`)
+must write `symmetric` so that output reads back.
+
+## Errors
+
+- Wrong argument count (for example `uexp(10.0, 0.3)`, no `k`): the call is
+  not an uncertainty, and amath falls back to the letter reading it had before
+  the uncertainty words (plurimath/amath#9). `uexp(10.0, 0.3)` reads as the
+  symbol `u` followed by `exp(10.0, 0.3)`, as the contract cell
+  `invalid.asciimath_missing_k` records; no error is raised. Should a tree with
+  too few fields reach the transform anyway, the node raises
+  `Errors::InvalidUncertainty`, which `Math.parse` reports as
+  `Math::ParseError`.
+- An unknown `uncertainty_class`, an unexpected key, a non-text leaf, both
+  `magnitude` and `concise_digits`, non-digit `concise_digits` or an unknown
+  `interval_kind` raise `Errors::InvalidUncertainty`.
+- `+-`, `pm`, `±` and `1.230(4)` outside these three words never produce this
+  tree.