moxml 0.5.148 → 0.5.150

data/spec/consistency/divergence_register_spec.rb

@@ -9,7 +9,7 @@ require "spec_helper"
 # no spec cites an unregistered ID.
 RSpec.describe "divergence register linkage" do
   REGISTER_PATH = "docs/_pages/divergences.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
-  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb spec/support/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
   NEXT_GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
     /same engine as/, # engine dedup, not a divergence
     /source_adapter == target_adapter/, # self round-trip
@@ -18,7 +18,15 @@ RSpec.describe "divergence register linkage" do
     /skip_shapes/,              # shape routing (IDs cited above)
     /leptris_fixed\?/,          # version gate
     /source_elements/,          # data-presence guard
+    /next unless doc/,          # adapter-availability guard (not a
+    # divergence: the adapter is not installed in this environment)
+    /next unless cell\[:pin\]/, # matrix data-presence guard
     /next unless match/,        # scanner-internal guard
+    /well_formed|voids\.empty\?|default_ns|per\.size/, # property-scope
+    # and availability guards (input scoping, not adapter exemptions)
+    /exempt/i, # value-routed exemption table: the
+    # table's VALUES are D-IDs, enforced by
+    # the coverage audit's exempt rule
   ].freeze
 
   # Version/availability gates are not divergences: a binding too old

data/spec/consistency/eol_normalization_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Processing model §Parsing (normative): pinned here.
+
 require "spec_helper"
 
 # XML 1.0 §2.11 End-of-Line Handling: literal CRLF and lone CR

data/spec/consistency/loud_degradation_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Processing model §Errors and loud degradation (normative): pinned here.
+
 require "spec_helper"
 
 # Loud degradation (processing model, "Errors and loud degradation"):

data/spec/consistency/metamorphic_properties_spec.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/input_taxonomy"
+require "support/input_generator"
+
+# Metamorphic property suite (TODO.sota/02): generated evidence over
+# the 01 taxonomy's vocabulary, seeded per run — SOTA_FUZZ_SEEDS
+# (default fixed, identical cases every CI run; the nightly fuzz leg
+# passes a random comma-separated list) and SOTA_FUZZ_CASES per seed
+# (bounded per leg).
+#
+# M1 round trip, M2 c14n idempotence, M3 document-order/union order,
+# M4 serialization shape, M5 cross-adapter answer equality modulo the
+# register; the malformed class raises the named ParseError
+# everywhere. Failures name the case id ("gen <seed>/<i>") —
+# reproducible at that seed and index — and the cell.
+RSpec.describe "metamorphic properties (generated, seeded)" do
+  let(:fuzz_seeds) do
+    if ENV.key?("SOTA_FUZZ_SEEDS")
+      ENV.fetch("SOTA_FUZZ_SEEDS").split(",").map(&:to_i)
+    else
+      [20261020]
+    end
+  end
+
+  let(:fuzz_count) { Integer(ENV.fetch("SOTA_FUZZ_CASES", "200")) }
+
+  let(:cases) do
+    fuzz_seeds.flat_map do |seed|
+      InputGenerator.cases(seed: seed, count: fuzz_count)
+    end
+  end
+
+  def snapshot(doc)
+    {
+      nodes: doc.traverse.to_a.grep_v(Moxml::Document).count,
+      root: doc.root&.name,
+      text: doc.text,
+      xpath: doc.xpath("//*").to_a.count,
+    }
+  end
+
+  def compact(snap)
+    snap.except(:nodes).merge(text: snap[:text].gsub(/\s+/, ""))
+  end
+
+  def exempt?(input, face, name)
+    input.features.any? do |feature|
+      InputGenerator::FEATURE_EXEMPT.dig(feature, face, name)
+    end
+  end
+
+  it "M1: keeps the round trip stable per adapter over generated inputs" do
+    cases.each do |input|
+      next unless input.well_formed
+
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        begin
+          ctx = Moxml.new(name)
+          first = snapshot(ctx.parse(input.xml))
+          second = snapshot(ctx.parse(ctx.parse(input.xml).to_xml(indent: 0)))
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next # adapter unavailable or a named guard excuses the leg
+        end
+        expect(compact(second)).to eq(compact(first)),
+                                   "#{input.id} round-trip drifted on " \
+                                   "#{name}: #{first.inspect} vs " \
+                                   "#{second.inspect}"
+      end
+    end
+  end
+
+  it "M2: canonicalization is idempotent (c14n∘c14n == c14n)" do
+    c14n = Moxml::C14n::Inclusive10.new
+    cases.each do |input|
+      next unless input.well_formed
+
+      once = c14n.canonicalize(input.xml)
+      expect(c14n.canonicalize(once)).to eq(once),
+                                         "#{input.id}: c14n is not " \
+                                         "idempotent"
+    end
+  end
+
+  it "M3: XPath unions answer in first-encounter (document) order" do
+    # XPath 1.0 unprefixed name tests match no-namespace elements
+    # only (processing model, "Names and namespaces") — the union
+    # property is scoped to cases an unprefixed query can address.
+    addressed = cases.select do |input|
+      input.well_formed && !input.features.include?(:default_ns)
+    end
+    addressed.each do |input|
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        begin
+          doc = Moxml.new(name).parse(input.xml)
+          union = doc.xpath("//a | //b").to_a.map(&:name)
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next # adapter unavailable in this environment
+        end
+        wanted = %w[a b]
+        doc_order = doc.traverse.to_a
+          .grep(Moxml::Element)
+          .map(&:name)
+          .select { |n| wanted.include?(n) }
+        expect(union).to eq(doc_order),
+                         "#{input.id}: union order diverges from document " \
+                         "order on #{name}: #{union.inspect} vs " \
+                         "#{doc_order.inspect}"
+      end
+    end
+  end
+
+  it "M4: to_html and to_xhtml hold their serialization shape" do
+    cases.each do |input|
+      next if !input.well_formed || input.voids.empty?
+
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        begin
+          doc = Moxml.new(name).parse(input.xml)
+          html = doc.to_html
+          xhtml = doc.to_xhtml
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next # the HTML face is adapter-optional (loud raise where absent)
+        end
+        expect(html).not_to include("<?xml"),
+                            "#{input.id}: to_html declared XML on #{name}"
+        input.voids.each do |v|
+          expect(html).not_to match(%r{<#{v}\b[^>]*/>}),
+                              "#{input.id}: to_html self-closed void <#{v}> " \
+                              "on #{name}"
+        end
+        # "none of the HTML short forms": a bare <br> is not XML,
+        # so the strict re-parse is the rigorous check (self-closed
+        # and paired forms are both legal XHTML).
+        expect { Moxml.new(:leptris).parse(xhtml, strict: true) }
+          .not_to raise_error,
+                  "#{input.id}: to_xhtml left an HTML short form on " \
+                  "#{name}: #{xhtml[0, 120].inspect}"
+      end
+    end
+  end
+
+  it "M5: every adapter answers generated inputs identically, modulo the register" do
+    cases.each do |input|
+      next unless input.well_formed
+
+      per = Moxml::Adapter::AVAILABLE_ADAPTERS.filter_map do |name|
+        [name, snapshot(Moxml.new(name).parse(input.xml))]
+      rescue Moxml::Error, NotImplementedError, LoadError
+        nil # adapter unavailable in this environment
+      end.to_h
+      expect(per.keys.count).to be >= 2
+
+      base_name = per.keys.first
+      base = per[base_name]
+      per.each do |name, got|
+        base.except(:text).each_key do |face|
+          next if exempt?(input, face, name)
+
+          expect(got[face]).to eq(base[face]),
+                               "#{input.id}/#{face} differs on #{name} vs " \
+                               "#{base_name}: #{got[face].inspect} vs " \
+                               "#{base[face].inspect} — fix it or register " \
+                               "a divergence and exempt the cell"
+        end
+        next if exempt?(input, :text, name)
+
+        expect(got[:text]).to eq(base[:text]),
+                              "#{input.id}/text differs on #{name} vs " \
+                              "#{base_name}: #{got[:text].inspect} vs " \
+                              "#{base[:text].inspect} — fix it or register " \
+                              "a divergence and exempt the cell"
+      end
+    end
+  end
+
+  it "raises the named parse error on generated malformed input, everywhere" do
+    cases.each do |input|
+      next if input.well_formed
+
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        # oga's strict lane is lexer-strict, not
+        # well-formedness-strict (D-17) — structural malformations
+        # parse there; every other adapter must raise the named error.
+        next if name == :oga # D-17
+
+        expect { Moxml.new(name).parse(input.xml, strict: true) }
+          .to raise_error(Moxml::ParseError),
+              "#{input.id}: #{name} accepted malformed input or raised " \
+              "outside the named ParseError contract"
+      end
+    end
+  end
+end

data/spec/consistency/metamorphic_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/xml_generator"
+
+# Metamorphic conformance (TODO.sota/02): properties over GENERATED
+# documents — no expected outputs needed, only relations that must
+# hold for every input. Seeded: a failing seed reproduces locally.
+# Nightly legs sweep larger seeds (SOTA_FUZZ_SEEDS).
+RSpec.describe "metamorphic relations over generated documents" do
+  SEEDS = (ENV.key?("SOTA_FUZZ_SEEDS") ? ENV.fetch("SOTA_FUZZ_SEEDS").split(",").map(&:to_i) : [1, 2, 3]) # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  DOCS_PER_SEED = 10 # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  def adapters
+    Moxml::Adapter::AVAILABLE_ADAPTERS - [:headed_ox]
+  end
+
+  def docs
+    @docs ||= SEEDS.flat_map do |seed|
+      (0...DOCS_PER_SEED).map do |i|
+        [:"#{seed}_#{i}", XmlGenerator.generate((seed * 1000) + i)]
+      end
+    end
+  end
+
+  def snapshot_structure(doc)
+    doc.xpath("//*").to_a.map(&:name)
+  end
+
+  def element_attr_set(doc)
+    doc.xpath("//*").to_a.map do |n|
+      n.attribute_pairs.map { |k, v| [k, v] }.sort
+    end
+  end
+
+  # M1: parse∘serialize identity on the information set
+  it "M1 round-trips every generated document on every adapter" do
+    docs.each do |seed_tag, xml|
+      adapters.each do |name|
+        begin
+          ctx = Moxml.new(name)
+          doc = ctx.parse(xml)
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next
+        end
+        first = snapshot_structure(doc)
+        again = ctx.parse(doc.to_xml(indent: 0))
+        expect(snapshot_structure(again)).to eq(first),
+                                             "M1 drift #{seed_tag}/#{name}"
+      end
+    end
+  end
+
+  # M2: canonicalization idempotence (the Ruby reference + native
+  # delegations answer one canonical form; re-canonicalizing it is
+  # the identity).
+  it "M2 canonicalization is idempotent on every adapter" do
+    docs.each do |seed_tag, xml|
+      adapters.each do |name|
+        begin
+          doc = Moxml.new(name).parse(xml)
+          once = Moxml::C14n.canonicalize(doc)
+          twice = Moxml::C14n.canonicalize(Moxml.new(name).parse(once))
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next
+        end
+        expect(twice).to eq(once), "M2 drift #{seed_tag}/#{name}"
+      end
+    end
+  end
+
+  # M3: document order — XPath element results equal the pre-order
+  # walk's element sequence.
+  it "M3 XPath results preserve document order on every adapter" do
+    docs.each do |seed_tag, xml|
+      adapters.each do |name|
+        begin
+          doc = Moxml.new(name).parse(xml)
+          via_xpath = doc.xpath("//*").to_a.map(&:name)
+          via_walk = []
+          doc.traverse { |n| via_walk << n.name if n.node_type == :element }
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next
+        end
+        expect(via_xpath).to eq(via_walk), "M3 drift #{seed_tag}/#{name}"
+      end
+    end
+  end
+
+  # M4: serialization shape invariants (per shape).
+  it "M4 keeps the shape contracts on every adapter" do
+    docs.each do |seed_tag, xml|
+      adapters.each do |name|
+        begin
+          ctx = Moxml.new(name)
+          doc = ctx.parse(xml)
+          xhtml = doc.to_xhtml
+        rescue Moxml::Error, NotImplementedError, LoadError
+          next # loud contracts (no HTML engine) are pinned elsewhere
+        end
+        expect(xhtml).not_to include("<!DOCTYPE"),
+                             "M4 #{seed_tag}/#{name}: xhtml grew a doctype"
+        expect(xhtml).not_to include("<?xml"),
+                             "M4 #{seed_tag}/#{name}: xhtml grew a declaration"
+        # The XHTML shape re-parses with the same element set (the
+        # slash forms are well-formed XML).
+        expect(snapshot_structure(ctx.parse(xhtml)))
+          .to eq(snapshot_structure(doc)),
+              "M4 #{seed_tag}/#{name}: xhtml round-trip drifted"
+      end
+    end
+  end
+
+  # M5: adapter-adapter equivalence on the structural information set
+  # (element sequence + attribute sets). Text-level equivalence over
+  # generated docs rides the taxonomy differential's registered
+  # exemptions (D-13/D-14 whitespace/PI families).
+  it "M5 structural equivalence across adapters" do
+    docs.each do |seed_tag, xml|
+      per = adapters.filter_map do |name|
+        doc = Moxml.new(name).parse(xml)
+        [name, snapshot_structure(doc), element_attr_set(doc)]
+      rescue Moxml::Error, NotImplementedError, LoadError
+        nil
+      end
+      next if per.size < 2
+
+      base_name, base_struct, base_attrs = per.first
+      per.each do |name, struct, attrs|
+        expect(struct).to eq(base_struct),
+                          "M5 structure drift #{seed_tag}/#{name} vs " \
+                          "#{base_name}"
+        expect(attrs).to eq(base_attrs),
+                         "M5 attribute drift #{seed_tag}/#{name} vs " \
+                         "#{base_name}"
+      end
+    end
+  end
+end

data/spec/consistency/model_coverage_audit_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "spec_helper"
+require "support/model_coverage"
 
 # Model coverage matrix (TODO.model/03): every face family of the
 # processing model is governed for every adapter — covered by a pin
@@ -8,68 +9,13 @@ require "spec_helper"
 # a registered divergence (adapter => D-ID), or loud (adapter =>
 # the named error class). An unpinned family is an ungoverned cell:
 # this audit fails until it has one of the three.
-# See docs/_references/processing-model.adoc for the model itself.
+#
+# The matrix itself lives in spec/support/model_coverage.rb: the same
+# data drives this audit, the model document's pin lists, and the
+# published coverage page. See docs/_references/processing-model.adoc
+# for the model itself.
 RSpec.describe "model coverage matrix" do
-  MODEL_MATRIX = { # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
-    "document order and children listing" => {
-      pin: "spec/consistency/adapter_parity_spec.rb",
-    },
-    "name resolution" => {
-      pin: "spec/consistency/xpath_idioms_spec.rb",
-    },
-    "namespace resolution and bindings normalization" => {
-      pin: "spec/consistency/xpath_idioms_spec.rb",
-    },
-    "attribute access" => {
-      pin: "spec/moxml/attribute_resolver_spec.rb",
-    },
-    "text/content/raw_content" => {
-      pin: "spec/moxml/text_spec.rb",
-    },
-    "parsing modes and diagnostics" => {
-      pin: "spec/moxml/document_parse_diagnostics_spec.rb",
-    },
-    "EOL normalization" => {
-      pin: "spec/consistency/eol_normalization_spec.rb",
-      exempt: { oga: "D-02", ox: "D-03" },
-    },
-    "entity modes" => {
-      pin: "spec/moxml/entity_spec.rb",
-    },
-    "XPath evaluation and declared idioms" => {
-      pin: "spec/consistency/xpath_idioms_spec.rb",
-      exempt: { oga: "D-01" },
-    },
-    "serialization shapes (xml/html/xhtml)" => {
-      pin: "spec/moxml/xhtml_output_spec.rb",
-    },
-    "indentation knobs" => {
-      pin: "spec/moxml/to_html_spec.rb",
-      exempt: { oga: "D-09", ox: "D-09", headed_ox: "D-09",
-                libxml: "D-09", leptris: "D-09" },
-    },
-    "canonicalization" => {
-      pin: "spec/moxml/c14n/adapter_delegation_spec.rb",
-      exempt: { oga: "D-04", ox: "D-05", headed_ox: "D-05" },
-    },
-    "XSLT" => {
-      pin: "spec/consistency/xslt_spec.rb",
-      loud: { oga: "Moxml::NotImplementedError",
-              ox: "Moxml::NotImplementedError",
-              headed_ox: "Moxml::NotImplementedError",
-              rexml: "Moxml::NotImplementedError",
-              libxml: "Moxml::NotImplementedError" },
-    },
-    "SAX" => {
-      pin: "spec/moxml/sax_spec.rb",
-    },
-    "materialization" => {
-      pin: "spec/moxml/plan_conformance_spec.rb",
-    },
-    "loud capability contracts" => {
-      pin: "spec/consistency/loud_degradation_spec.rb",
-    },
-  }.freeze
+  MODEL_MATRIX = ModelCoverage::MODEL_COVERAGE_MATRIX # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
 
   def register_ids
     File.readlines("docs/_pages/divergences.adoc")
@@ -110,4 +56,141 @@ RSpec.describe "model coverage matrix" do
     expect(bad).to be_empty,
                    "loud cells must name Moxml errors: #{bad.join('; ')}"
   end
+
+  # Model-derived governance: the matrix is generated FROM the model
+  # doc's section headings, in both directions. A new section in
+  # processing-model.adoc without a matrix citation (or an explicit
+  # non-face declaration) fails this audit; a matrix citation whose
+  # section vanished fails too.
+  MODEL_DOC = "docs/_references/processing-model.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  NON_FACE = ModelCoverage::MODEL_COVERAGE_NON_FACE # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  def model_sections
+    File.readlines(MODEL_DOC).filter_map do |line|
+      line[/\A=== (\S.*)$/, 1]&.strip
+    end.uniq
+  end
+
+  # Document-side pin lists (TODO.sota/07): every section carries a
+  # `Pins::` line naming the specs that enforce it (`Pins:: none` for
+  # non-face sections). Parsed as section => [paths] or nil when the
+  # line is missing.
+  def model_pin_lists
+    lists = {}
+    current = nil
+    File.readlines(MODEL_DOC).each do |line|
+      if (heading = line[/\A=== (\S.*)$/, 1])
+        current = heading.strip
+        lists[current] = nil
+      elsif current && (entry = line[/\APins:: (.*)$/, 1])
+        lists[current] = entry.scan(/`([^`]+)`/).flatten
+      end
+    end
+    lists
+  end
+
+  it "cites an existing model section for every face family" do
+    sections = model_sections
+    unknown = MODEL_MATRIX.filter_map do |family, cell|
+      section = cell[:section]
+      next "#{family}: nil" if section.nil?
+
+      "#{family}: #{section.inspect}" unless sections.include?(section)
+    end
+    expect(unknown).to be_empty,
+                       "matrix families citing missing model sections: #{unknown.join('; ')}"
+  end
+
+  it "covers or declares every model section" do
+    cited = MODEL_MATRIX.values.filter_map { |cell| cell[:section] }
+    uncovered = model_sections.reject do |section|
+      cited.include?(section) || NON_FACE.include?(section)
+    end
+    expect(uncovered).to be_empty,
+                         "model sections with no coverage matrix family " \
+                         "(add a family or declare non-face): #{uncovered.join('; ')}"
+  end
+
+  it "declares non-face sections that actually exist in the model doc" do
+    stale = NON_FACE.reject { |s| model_sections.include?(s) }
+    expect(stale).to be_empty,
+                     "non-face declarations citing missing sections: #{stale.join('; ')}"
+  end
+
+  it "gives every model section a Pins line" do
+    missing = model_pin_lists.select { |_, pins| pins.nil? }.keys
+    expect(missing).to be_empty,
+                       "model sections without a Pins line: #{missing.join('; ')}"
+  end
+
+  it "matches the model doc's face-section pin lists to the matrix" do
+    lists = model_pin_lists
+    drift = ModelCoverage.sections.filter_map do |section|
+      expected = ModelCoverage.pins_for(section)
+      got = lists[section]
+      "#{section}: doc #{got.inspect} vs matrix #{expected.inspect}" if got != expected
+    end
+    expect(drift).to be_empty,
+                     "model-doc pin lists drift from the matrix: #{drift.join('; ')}"
+  end
+
+  it "leaves non-face sections without pins" do
+    lists = model_pin_lists
+    pinned = NON_FACE.select { |section| lists[section]&.any? }
+    expect(pinned).to be_empty,
+                      "non-face sections must declare Pins:: none: #{pinned.join('; ')}"
+  end
+
+  it "points every model-doc pin at an existing spec" do
+    missing = model_pin_lists.values.compact.flatten.uniq.reject do |path|
+      File.exist?(path)
+    end
+    expect(missing).to be_empty,
+                       "model-doc pins missing on disk: #{missing.join(', ')}"
+  end
+
+  # Bidirectional linkage (TODO.sota/03): the model doc, the pins, and
+  # the reference form one checkable triangle. Every pin cites the
+  # section it enforces; every citation names a section that exists.
+  PIN_CITATION = /Processing model §(.+?) \(normative\)/ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  def pin_citations(path)
+    File.readlines(path).filter_map { |line| line[PIN_CITATION, 1]&.strip }
+  end
+
+  it "has every pin cite the model section it enforces" do
+    missing = MODEL_MATRIX.filter_map do |family, cell|
+      next unless cell[:pin] && File.exist?(cell[:pin])
+
+      "#{family}: #{cell[:pin]}" unless pin_citations(cell[:pin])
+        .include?(cell[:section])
+    end
+    expect(missing).to be_empty,
+                       "pins must cite their model section " \
+                       "(# Processing model §<section>): #{missing.join('; ')}"
+  end
+
+  it "never cites a model section that does not exist" do
+    sections = model_sections
+    orphans = MODEL_MATRIX.filter_map { |_, cell| cell[:pin] }.uniq.flat_map do |path|
+      next [] unless File.exist?(path)
+
+      pin_citations(path).reject { |section| sections.include?(section) }
+        .map { |section| "#{path}: #{section}" }
+    end
+    expect(orphans).to be_empty,
+                       "pin citations naming missing sections: #{orphans.join('; ')}"
+  end
+
+  it "cites every face section from at least one pin" do
+    cited = MODEL_MATRIX.filter_map { |_, cell| cell[:pin] }.uniq.flat_map do |path|
+      File.exist?(path) ? pin_citations(path) : []
+    end
+    uncovered = model_sections.reject do |section|
+      cited.include?(section) || NON_FACE.include?(section)
+    end
+    expect(uncovered).to be_empty,
+                         "model sections no pin cites: #{uncovered.join('; ')}"
+  end
 end

data/spec/consistency/published_docs_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/model_coverage"
+require "json"
+
+# Published documentation is part of the specification apparatus
+# (TODO.sota/07): generated blocks must be views of committed data. A
+# data change without regeneration fails here, so the published
+# coverage proof and scoreboard can never claim more than the tests do.
+RSpec.describe "published documentation" do
+  it "keeps the model-coverage page in sync with the matrix" do
+    page = File.read("docs/_pages/model-coverage.adoc")
+    block = page[/MODEL-COVERAGE:BEGIN\n(.*?)\n?\/\/ MODEL-COVERAGE:END/m, 1]
+    expect(block).not_to be_nil, "coverage page is missing its markers"
+
+    expect(block).to eq(ModelCoverage.render_page_block),
+                     "model-coverage page is stale: run rake docs:coverage"
+  end
+
+  it "keeps every published scoreboard row in sync with the JSON data" do
+    data = JSON.parse(File.read("benchmark/scoreboard.json"))
+    page = File.read("docs/_pages/performance.adoc")
+    block = page[/SCOREBOARD:BEGIN(.*?)SCOREBOARD:END/m, 1]
+    expect(block).not_to be_nil, "performance page is missing its markers"
+
+    data["rows"].each do |row|
+      expect(block).to include(
+        "| `#{row['row']}` | #{format('%.2f', row['ratio'])}x | " \
+        "#{row['kind']} |",
+      ), "scoreboard row #{row['row']} is stale against scoreboard.json"
+    end
+
+    expect(block.scan(/\| `[^`]+` \| \d+\.\d\dx \|/).size)
+      .to eq(data["rows"].size), "scoreboard row count differs"
+  end
+
+  it "names the measured engine version in the scoreboard metadata" do
+    data = JSON.parse(File.read("benchmark/scoreboard.json"))
+    protocol = data["protocol"]
+    page = File.read("docs/_pages/performance.adoc")
+    block = page[/SCOREBOARD:BEGIN(.*?)SCOREBOARD:END/m, 1]
+
+    expect(block).to include("#{protocol['adapter']} " \
+                             "#{protocol['adapter_version']}"),
+                     "scoreboard metadata does not name the measured engine"
+    expect(block).to include("nokogiri #{protocol['nokogiri']}")
+  end
+end