moxml 0.5.149 → 0.5.150

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3af023098a8dde5521f0297f240a1c6fa71625cc2b3cd6924eba638724e12517
-  data.tar.gz: 9fb194d059475ed0c4aea3471b9048195ce7ea0bef349c25bdc52f991944ca5f
+  metadata.gz: 73b67b633933c60095bdeafd744a8f7a827066edf478245e9c2f49aadf1d75e6
+  data.tar.gz: 92320b13e8bb745cd5b650e85d4fa7b8397e082871a7c255cb61f637595c6048
 SHA512:
-  metadata.gz: 860ac49f2684d504273e22dcbc9c6ed43106ebf67d9ca093af74543ab284e89c7be5c02d3991421973674837ece981127ede74329bfce9a352236bf9b3c094ff
-  data.tar.gz: 24b50dee831eb6856dc3f24b7759e32aead60c98896427ed7776277cd69aca0db01f3521841cbc556ccfaaee8fca56a071f2f219276f0553fe919b712c87ef2b
+  metadata.gz: c34b4df4cf09797b5a28ec909e0df41c970897676154fa1b66dc9ebbd18cdccb13408b83f5647c44d41cfda7ebcbf09571314d0bfe71b572a58dde972e78994b
+  data.tar.gz: d926c442a8b0dc0f9d159f27f42772a3af48358fbbd67d62d7cec1cdd51c609110def03466fa93c5b95b2eccfdaa7ab34e26c818b30b2651a996b9879c63d699

data/.github/workflows/dependent-repos.json

@@ -1,5 +1,10 @@
 {
   "repo": [
-    "lutaml/lutaml-model"
+    "lutaml/lutaml-model",
+    "lutaml/canon",
+    "metanorma/metanorma-standoc",
+    "metanorma/metanorma-ietf",
+    "lutaml/expressir",
+    "metanorma/svg_conform"
   ]
-}
+}

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

@@ -24,4 +24,7 @@ jobs:
   rake:
     uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
     with:
-      command: bundle exec rspec
+      command: bundle exec rspec
+      # metanorma-ietf needs xml2rfc; metanorma-standoc needs
+      # ghostscript. Both are harmless for the other consumers.
+      setup-tools: xml2rfc,ghostscript

data/.github/workflows/performance-release.yml

@@ -0,0 +1,79 @@
+name: performance-release
+
+# Every release re-measures the scoreboard and appends the table to
+# the release notes (TODO.sota/04). Triggered by the release
+# workflow's completion; idempotent — a re-run replaces the marked
+# section instead of stacking it.
+on:
+  workflow_run:
+    workflows: ["release"]
+    types: [completed]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  report:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
+      - name: Measure the scoreboard
+        run: |
+          SCORE_MARKDOWN=/tmp/section.md \
+            bundle exec ruby benchmark/scoreboard.rb
+
+      - name: Append the scoreboard to the latest release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG=$(gh release view --json tagName --jq .tagName)
+          gh release view "$TAG" --json body --jq .body > /tmp/body.md
+          ruby -e '
+            body = File.read("/tmp/body.md")
+            section = File.read("/tmp/section.md")
+            block = "<!-- PERFORMANCE:BEGIN -->\n#{section}" \
+                    "<!-- PERFORMANCE:END -->"
+            if body.include?("<!-- PERFORMANCE:BEGIN -->")
+              body = body.sub(
+                /<!-- PERFORMANCE:BEGIN -->.*<!-- PERFORMANCE:END -->/m,
+                block,
+              )
+            else
+              body = body.chomp + "\n\n" + block
+            end
+            File.write("/tmp/new_body.md", body)
+          '
+          gh release edit "$TAG" --notes-file /tmp/new_body.md

data/.github/workflows/performance.yml

@@ -0,0 +1,59 @@
+name: performance
+
+# The published scoreboard lock (TODO.sota/04). Runs on a quiet
+# weekly schedule (and on demand); PRs do not run it — measurement
+# noise is a release concern, not a change-gating one.
+on:
+  schedule:
+    - cron: "0 4 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          # bundler-cache is disabled because the path-source oga and
+          # ruby-ll forks need generated outputs before their C
+          # extensions can compile.
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
+      - name: Scoreboard lock (parity rows + 10% regression tolerance)
+        run: bundle exec rake benchmark:lock
+
+      - name: Upload the measured scoreboard
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: scoreboard
+          path: benchmark/scoreboard.json
+          if-no-files-found: ignore

data/Rakefile

@@ -284,6 +284,22 @@ namespace :benchmark do
   task :report do
     ruby "benchmarks/generate_report.rb"
   end
+
+  # Published scoreboard (TODO.sota/04): CPU medians, interleaved A/B,
+  # load-gated; see benchmark/README.md for the protocol and rows.
+  desc "Published performance scoreboard (CPU medians, interleaved A/B)"
+  task :scoreboard do
+    sh "bundle exec ruby benchmark/scoreboard.rb"
+  end
+
+  # CI lock: parity rows must be >= 1.0x and no row may fall more than
+  # 10% below the committed baseline.
+  desc "Scoreboard regression lock (parity + 10% baseline tolerance)"
+  task :lock do
+    sh({ "SCORE_LOCK" => "1",
+         "SCORE_BASELINE" => "benchmark/scoreboard.json" },
+       "bundle exec ruby benchmark/scoreboard.rb")
+  end
 end
 
 namespace :opal do
@@ -324,4 +340,11 @@ namespace :opal do
   end
 end
 
+namespace :docs do
+  desc "Regenerate the published model-coverage page from the matrix"
+  task :coverage do
+    sh "bundle exec ruby -I spec bin/generate-model-coverage"
+  end
+end
+
 task default: :spec

data/benchmark/README.md

@@ -0,0 +1,106 @@
+# Performance scoreboard
+
+`benchmark/scoreboard.rb` is the published performance surface
+(TODO.sota/04). It answers one question for every operation a
+consumer runs: **how does moxml on its fastest engine lane compare
+with raw nokogiri on the same operation?**
+
+## Protocol
+
+- **CPU time medians** (`CLOCK_PROCESS_CPUTIME_ID`), not wall time —
+  scheduler noise never becomes a performance claim.
+- **Interleaved A/B**: baseline and candidate alternate every
+  repetition in the same thermal window; warmups are discarded and
+  GC runs between samples. The ratio is `median(baseline) /
+  median(candidate)`; `> 1.0x` means moxml is faster.
+- **Load gate**: the harness refuses to report when the 1-minute
+  load exceeds half the CPU count. `SCORE_FORCE=1` overrides for
+  smoke runs only — such numbers are not publishable.
+- Rows name the exact operation measured; lazy and materialized
+  XPath results are separate rows because they cost different things.
+- The pair is **moxml + leptris latest**; the baseline is raw
+  nokogiri on the same document.
+
+## Rows
+
+| Row | Operation | Kind |
+| --- | --------- | ---- |
+| `parse` | `Nokogiri::XML` vs `ctx.parse` on the catalog document | parity |
+| `serialize` | `doc.to_xml` | parity |
+| `xpath //field (count)` | node-set cardinality, nothing materialized | parity |
+| `xpath //field (each)` | iterate every result (wrapper materialization) | structural |
+| `attr pairs listing` | collect `[name, value]` for every record | parity |
+| `build add_element` | create + attach 300 records x 4 fields with attrs and text | structural |
+| `walk+read (warm)` | traverse a pre-parsed document, read name + text | structural |
+| `walk+read (cold)` | parse + the same traversal | structural |
+| `children recursion (cold)` | parse + recurse via `children` filtering elements | structural |
+| `plan records (typed)` | compiled `Moxml::Plan` vs the hand-written typed walk | data API |
+
+**Parity rows** are the commitment: the lock fails below a 0.95
+measurement floor. **Structural rows** are measured and trend-locked
+(no row may regress >10% against the committed baseline), but they
+are known to be below parity — the gaps are listed below. **Data
+API** rows are informational: they show what consumers gain by using
+the record APIs instead of node-by-node access.
+
+## Commands
+
+```bash
+# Every row, human-readable
+bundle exec rake benchmark:scoreboard
+
+# One or more rows
+SCORE_ROWS="parse,serialize" bundle exec ruby benchmark/scoreboard.rb
+
+# Another engine lane
+SCORE_ADAPTER=oga bundle exec ruby benchmark/scoreboard.rb
+
+# Machine-readable results (protocol metadata + rows)
+SCORE_JSON=benchmark/scoreboard.json bundle exec ruby benchmark/scoreboard.rb
+
+# CI lock: parity rows >= 1.0x, and no row > 10% below the baseline
+SCORE_LOCK=1 SCORE_BASELINE=benchmark/scoreboard.json \
+  bundle exec ruby benchmark/scoreboard.rb
+```
+
+A smoke run on a loaded machine:
+
+```bash
+SCORE_FORCE=1 SCORE_REPS=5 bundle exec ruby benchmark/scoreboard.rb
+```
+
+## Honest status
+
+Reference run (generated; do not edit by hand — `SCORE_PUBLISH=1`
+rewrites this block and `docs/_pages/performance.adoc`):
+
+<!-- SCOREBOARD:BEGIN -->
+| Row | Ratio | Kind | Status |
+| --- | ----- | ---- | ------ |
+| `parse` | 2.59x | parity | met |
+| `serialize` | 1.35x | parity | met |
+| `xpath //field (count)` | 1.20x | parity | met |
+| `xpath //field (each)` | 0.34x | structural | tracked (below parity) |
+| `attr pairs listing` | 8.16x | parity | met |
+| `build add_element` | 0.60x | structural | tracked (below parity) |
+| `walk+read (warm)` | 0.77x | structural | tracked (below parity) |
+| `walk+read (cold)` | 0.22x | structural | tracked (below parity) |
+| `children recursion (cold)` | 0.27x | structural | tracked (below parity) |
+| `plan records (typed)` | 0.79x | data | informational |
+<!-- SCOREBOARD:END -->
+
+The open rows are the known structural gap: every node the facade
+hands a consumer is a contract-carrying wrapper with its own
+identity/invalidation state, while nokogiri hands out thin handles.
+Closing them needs engine-side construction/walk faces (leptris
+C contract work), not more facade tuning. Facade-side wins already
+landed here: single-crossing `add_element` construction, native
+`set_binding_text` without a binding-twin mint per write, and the
+generation memo no longer writing on every `children` read.
+
+Numbers move by a few percent between runs; the lock's 10% tolerance
+is the regression tripwire, not a claim of precision. The committed
+baseline is a reference measured on a shared machine — regenerate it
+on a quiet machine (the `performance` workflow uploads its measured
+`scoreboard.json` as an artifact) before treating a lock failure as
+a regression.

data/benchmark/scoreboard.json

@@ -0,0 +1,115 @@
+{
+  "protocol": {
+    "measured": "2026-10-20T14:53:54Z",
+    "ruby": "3.4.8",
+    "adapter": "leptris",
+    "adapter_version": "1.9.374.0",
+    "nokogiri": "1.19.4",
+    "reps": 9,
+    "warmup": 2,
+    "clock": "CLOCK_PROCESS_CPUTIME_ID",
+    "load": 34.01
+  },
+  "rows": [
+    {
+      "row": "parse",
+      "kind": "parity",
+      "parity": true,
+      "baseline_us": 677.0,
+      "candidate_us": 261.0,
+      "ratio": 2.594,
+      "baseline_allocs": 6,
+      "candidate_allocs": 18
+    },
+    {
+      "row": "serialize",
+      "kind": "parity",
+      "parity": true,
+      "baseline_us": 474.0,
+      "candidate_us": 351.0,
+      "ratio": 1.35,
+      "baseline_allocs": 30,
+      "candidate_allocs": 13
+    },
+    {
+      "row": "xpath //field (count)",
+      "kind": "parity",
+      "parity": true,
+      "baseline_us": 132.0,
+      "candidate_us": 110.0,
+      "ratio": 1.2,
+      "baseline_allocs": 12,
+      "candidate_allocs": 9
+    },
+    {
+      "row": "xpath //field (each)",
+      "kind": "structural",
+      "parity": false,
+      "baseline_us": 276.0,
+      "candidate_us": 800.0,
+      "ratio": 0.345,
+      "baseline_allocs": 1212,
+      "candidate_allocs": 12
+    },
+    {
+      "row": "attr pairs listing",
+      "kind": "parity",
+      "parity": true,
+      "baseline_us": 310.0,
+      "candidate_us": 38.0,
+      "ratio": 8.158,
+      "baseline_allocs": 3300,
+      "candidate_allocs": 0
+    },
+    {
+      "row": "build add_element",
+      "kind": "structural",
+      "parity": false,
+      "baseline_us": 3434.0,
+      "candidate_us": 5744.0,
+      "ratio": 0.598,
+      "baseline_allocs": 20358,
+      "candidate_allocs": 11062
+    },
+    {
+      "row": "walk+read (warm)",
+      "kind": "structural",
+      "parity": false,
+      "baseline_us": 1101.0,
+      "candidate_us": 1431.0,
+      "ratio": 0.769,
+      "baseline_allocs": 4503,
+      "candidate_allocs": 2
+    },
+    {
+      "row": "walk+read (cold)",
+      "kind": "structural",
+      "parity": false,
+      "baseline_us": 1915.0,
+      "candidate_us": 8590.0,
+      "ratio": 0.223,
+      "baseline_allocs": 6010,
+      "candidate_allocs": 8730
+    },
+    {
+      "row": "children recursion (cold)",
+      "kind": "structural",
+      "parity": false,
+      "baseline_us": 2293.0,
+      "candidate_us": 8595.0,
+      "ratio": 0.267,
+      "baseline_allocs": 5710,
+      "candidate_allocs": 7230
+    },
+    {
+      "row": "plan records (typed)",
+      "kind": "data",
+      "parity": false,
+      "baseline_us": 2401.0,
+      "candidate_us": 3038.0,
+      "ratio": 0.79,
+      "baseline_allocs": 8111,
+      "candidate_allocs": 13231
+    }
+  ]
+}