canon 0.3.112 → 0.3.114

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afbb918c5dd097f911cfb587efa51b493ceed18976086f141f54373a8ab2c277
-  data.tar.gz: d6ef44bf2617820a71df1ec06b69e50a8436ee4879714f3fe3c9bf070fad8782
+  metadata.gz: e1fba0743a7127443ef7837004ae95b97be4760617237be10a63de01147e6812
+  data.tar.gz: 7853cf8424906ab05947560615db5d3c3ff5620564a86ee38b8fe19f306e8dac
 SHA512:
-  metadata.gz: 1f5a7911c15b91176afd697b75e01836f7aec79363df4f79bc504d79d5ae307ec0432151c6cde2ada42071ad95c97bcde03b6e265d23b6ff512e8cf663c5a95a
-  data.tar.gz: 4b35e4166db83dfc545a55c3f89093e09dc1f7d7e1d5b591f1306fac6b49bb7ce0346810fa4484fde9bcbd264dd34f0b5dec0d4d5a66869a2061d54e90afaac1
+  metadata.gz: 4b222586fe5831e76e443fa61bb4ee0601c31e5c048f3a9e39a37649437c738f03b9be5f89e7b97a823f311245a1ce1275cf215649a07758307715c86242aecb
+  data.tar.gz: 32d38e3eaaa8703697f2e14ff7610f44b76a69ba8d7ff18a4951d57f0d36ba83d9e02525526643103c2d62f37bd37cc0f7174d707a1fb96d87de262430251bad

data/docs/_references/comparison-theory.adoc

@@ -0,0 +1,289 @@
+= Canon comparison theory: dimensions, profiles, and the two algorithms
+:toc:
+
+This document is the specification of canon's comparison semantics.
+It is REVIEWED AGAINST THE IMPLEMENTATION by
+`spec/canon/docs/comparison_theory_spec.rb`: every dimension,
+behavior, and profile row cited here must exist in the dimension
+registry and the profile resolvers, and everything the registry
+defines must appear here (docs match shipped behavior — the W6.3
+standing rule).
+
+== 1. The four-layer pipeline
+
+Comparison flows through four independent layers. Each layer's
+output is the next layer's input; no layer sees another layer's
+options.
+
+[cols="1,3,2"]
+|===
+|Layer |Decides |Resolved from
+
+|1. Preprocessing
+|What byte form enters the parse (`:none`, `:c14n`, `:normalize`,
+`:format`, `:rendered`)
+|The profile's `preprocessing` key
+
+|2. Algorithm
+|The comparison engine: `:dom` (position-based recursive descent) or
+`:semantic` (signature matching producing insert/update/delete/move)
+|`diff_algorithm:` (default `:dom`); the two are distinct by design
+and are never merged
+
+|3. Matching
+|How nodes are deemed equal: one behavior per dimension
+|The profile (or explicit per-dimension options) resolved through
+the format's resolver
+
+|4. Presentation
+|How results are spelled (`by_line`, `by_object`, normative-only
+filtering)
+|`show_diffs:` and the formatter choice
+|===
+
+== 2. Dimensions
+
+A *dimension* is one axis along which two nodes may differ. The
+dimension registry (`Canon::Comparison::Dimensions::Registry`)
+defines, per format, each dimension's name and its *valid
+behaviors* — closed sets; an option outside the set raises at
+resolution. HTML aliases (`html`, `html4`, `html5`) resolve to the
+XML dimension set.
+
+=== 2.1 XML and HTML (the `:xml` set)
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`text_content`
+|`strict`, `normalize`, `ignore`
+|`strict`: character-exact text comparison. `normalize`:
+whitespace runs collapse to a single space and leading/trailing
+whitespace strips before comparison. `ignore`: text content never
+differs.
+
+|`structural_whitespace`
+|`strict`, `normalize`, `ignore`
+|Whitespace-only text nodes between elements. `strict`: they are
+content (normative: a `strict`-only dimension — a non-strict
+behavior can never make documents inequivalent on its own).
+`normalize`: whitespace-only nodes are equivalent regardless of
+shape. `ignore`: whitespace-only nodes are dropped before the walk.
+
+|`attribute_presence`
+|`strict`, `ignore`
+|Whether an attribute exists. `ignore` drops all attributes before
+comparison.
+
+|`attribute_order`
+|`strict`, `ignore`
+|`strict`: attribute order is significant. `ignore`: attributes
+compare as a set.
+
+|`attribute_values`
+|`strict`, `strip`, `compact`, `normalize`, `ignore`
+|`strict`: character-exact values. `strip`: leading/trailing
+whitespace strips. `compact`: internal whitespace runs collapse
+(verify: the value is compared after whitespace compaction).
+`normalize`: both strip and collapse. `ignore`: values compare
+equal regardless.
+
+|`element_position`
+|`strict`, `ignore`
+|`strict`: child order is significant. `ignore`: children match by
+identity (the ElementMatcher's id-attribute matching), not position.
+
+|`comments`
+|`strict`, `ignore`
+|Comment nodes: content-compared or dropped.
+
+|`namespace_prefix`
+|`significant`, `ignore`
+|`significant`: the written prefix is part of the node's identity.
+`ignore`: only the namespace URI matters; the prefix is spelling.
+|===
+
+=== 2.2 JSON (the `:json` set)
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`text_content`
+|`strict`, `normalize`, `ignore`
+|String values, `strict` character-exact.
+
+|`structural_whitespace`
+|`strict`, `normalize`, `ignore`
+|Whitespace between tokens outside strings. `strict`-only
+normative.
+
+|`key_order`
+|`strict`, `ignore`
+|`ignore`: objects compare as unordered maps (the canonical lane
+sorts keys).
+|===
+
+=== 2.3 YAML (the `:yaml` set)
+
+The `:json` set plus:
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`comments`
+|`strict`, `ignore`
+|YAML comments: compared or dropped before parse.
+|===
+
+== 3. Profiles and the profile algebra
+
+A *profile* is a named total assignment: one behavior per dimension
+of the format, plus a preprocessing layer. Profiles resolve through
+the format's resolver; explicit per-dimension options override a
+profile's entry for that dimension alone. XML/HTML ship FOUR
+profiles; JSON and YAML ship THREE (`:rendered` does not exist for
+them — the resolvers reject it). The resolved assignments below are
+asserted by the review spec:
+
+[cols="1,1,1"]
+|===
+|Profile |Intent |Resolved assignment
+
+|`:strict`
+|Default. Everything significant.
+|`text_content=strict`, `structural_whitespace=strict`,
+`attribute_presence=strict`, `attribute_order=strict`,
+`attribute_values=strict`, `element_position=strict`,
+`comments=strict`, `namespace_prefix=significant`,
+`whitespace_type=strict`, `preprocessing=none`.
+
+|`:spec_friendly`
+|Normative-document comparison (the spec-familiar shape).
+|`text_content=normalize`, `structural_whitespace=ignore`,
+`attribute_presence=strict`, `attribute_values=normalize`,
+`attribute_order=ignore`, `element_position=ignore`,
+`comments=ignore`, `namespace_prefix=ignore`,
+`whitespace_type=strict`, `preprocessing=rendered`.
+
+|`:rendered` (XML/HTML only)
+|The same document as rendered sources.
+|`text_content=normalize`, `structural_whitespace=normalize`,
+`attribute_presence=strict`, `attribute_order=ignore`,
+`comments=ignore`, `attribute_values=strict`,
+`element_position=strict`, `namespace_prefix=significant`,
+`whitespace_type=strict`, `preprocessing=none`.
+
+|`:content_only`
+|Ignore all spelling; compare information content.
+|`text_content=normalize`, `structural_whitespace=ignore`,
+`attribute_presence=strict`, `attribute_order=ignore`,
+`attribute_values=normalize`, `element_position=ignore`,
+`comments=ignore`, `namespace_prefix=ignore`,
+`whitespace_type=strict`, `preprocessing=c14n`.
+|===
+
+=== 3.1 JSON and YAML profile assignments
+
+JSON ships `:strict`, `:spec_friendly`, and `:content_only` (no
+`:rendered`); YAML the same plus its `comments` dimension.
+
+[cols="1,1,1"]
+|===
+|Profile |JSON |YAML
+
+|`:strict`
+|`key_order=strict`, `text_content=strict`,
+`structural_whitespace=strict`, `preprocessing=none`
+|`key_order=strict`, `text_content=strict`,
+`structural_whitespace=strict`, `comments=strict`,
+`preprocessing=none`
+
+|`:spec_friendly`
+|`key_order=ignore`, `text_content=strict`,
+`structural_whitespace=ignore`, `preprocessing=normalize`
+|`key_order=ignore`, `text_content=strict`,
+`structural_whitespace=ignore`, `comments=ignore`,
+`preprocessing=normalize`
+
+|`:content_only`
+|`key_order=ignore`, `text_content=normalize`,
+`structural_whitespace=ignore`, `preprocessing=normalize`
+|`key_order=ignore`, `text_content=normalize`,
+`structural_whitespace=ignore`, `comments=ignore`,
+`preprocessing=normalize`
+|===
+
+*Registry note (the W6.2 audit finding)*: the resolvers resolve
+one key beyond the registry's dimension sets — `whitespace_type`
+(`strict` in every shipped profile) — governing whether whitespace
+TYPE differences (space vs tab) are significant. It awaits registry
+promotion; until then it is documented here as a resolver-level
+option.
+
+Profile algebra properties:
+
+* *Totality*: a resolved profile assigns every format dimension
+exactly one behavior (the resolver raises on a gap).
+* *Monotone relaxation*: `:strict` is the identity of the algebra —
+every other profile differs from `:strict` only by relaxing
+dimensions toward `ignore`/`normalize`, never by strengthening.
+* *Non-normativity of relaxed dimensions*: with the exception of
+`text_content`, a dimension at `ignore` contributes no
+equivalence-affecting differences (the normative/informative split
+below).
+
+== 4. Normative, informative, and formatting-only differences
+
+A difference is classified when emitted:
+
+* *Normative* — affects equivalence: the documents are not
+equivalent. Produced by a dimension at a strict/significant
+behavior.
+* *Informative* — recorded but not equivalence-affecting: produced
+by a dimension at a relaxed behavior where the difference is still
+observable.
+* *Formatting-only* — the canonical forms match; the difference is
+pure spelling.
+
+`show_diffs: :normative` filters the presentation to normative
+findings. The classification is a property of the dimension's
+resolved behavior, not of the documents.
+
+== 5. The two algorithms
+
+=== 5.1 DOM (`diff_algorithm: :dom`, default)
+
+Position-based recursive descent. For each element pair: compare
+names, dimensions resolve per-dimension (attributes as sets or
+sequences per `attribute_order`, children positionally per
+`element_position` with the ElementMatcher's identity matching when
+relaxed). Complexity is linear in the sum of tree sizes. The
+intermediate representation is comparison-result codes
+(`EQUIVALENT`, `MISSING_NODE`, `UNEQUAL_TEXT_CONTENTS`, ...) which
+convert to DiffNodes.
+
+=== 5.2 Semantic (`diff_algorithm: :semantic`)
+
+Signature-based tree matching in three phases: (1) hash matching —
+identical subtrees match exactly; (2) similarity matching —
+remaining nodes pair by content similarity above
+`similarity_threshold`; (3) structural propagation — parent/child
+correspondences derive from matched ancestors. The intermediate
+representation is an operation stream (INSERT, DELETE, UPDATE,
+MOVE) converted to DiffNodes. The algorithms share preprocessing,
+configuration, match options, and output formatting; the comparison
+cores never share code (distinct by design — see CLAUDE.md, "Two
+Comparison Algorithms — Distinct by Design").
+
+== 6. Registry citation
+
+The review spec (`spec/canon/docs/comparison_theory_spec.rb`)
+asserts, at every run: for each format, every registry dimension
+name and every valid behavior token appears in this document; every
+profile row's resolved assignment equals the resolver's output for
+that profile. A dimension added to the registry without a §2 entry,
+a behavior added without its semantics row, or a profile change
+without a §3 row update, fails the battery.

data/docs/_references/html-canonical-form.adoc

@@ -0,0 +1,67 @@
+= The HTML canonical form (W1.3)
+
+This document specifies canon's HTML canonical form as shipped by
+`Canon::Formatters::HtmlFormatter` (and the html4/html5 variants).
+It is reviewed against the implementation by
+`spec/canon/docs/canonical_form_spec.rb` (the W6.3 review-gate
+pattern: law tokens asserted against the formatter's constants and
+methods).
+
+== 1. Pipeline
+
+format(input):
+
+1. *Parse* through the engine HTML adapter (WHATWG fragment
+parsing; the fixture materialization keeps whitespace text nodes —
+whitespace significance is the comparison profile's decision, not
+the parser's).
+2. *Canonicalize the tree* (attribute order, whitespace law below).
+3. *Serialize* through the engine's HTML serializer.
+4. *Post-serialize spacing* (the two regex laws below).
+
+== 2. Whitespace law
+
+*Whitespace-sensitive elements* — `pre`, `code`, `textarea`,
+`script`, `style` — are never normalized: their text content rides
+verbatim.
+
+Every other text node normalizes:
+
+* *Whitespace-only text* between/inside block elements collapses to
+  one space (the information-preserving canonical form);
+  whitespace-only text elsewhere is removed.
+* *Text with content*: whitespace runs collapse to single spaces;
+  leading/trailing strips only at `body` boundaries (first/last
+  real child).
+
+*Block elements* (the formatter's BLOCK_ELEMENTS registry):
+address, article, aside, blockquote, dd, details, dialog, div, dl,
+dt, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5,
+h6, header, hgroup, hr, li, main, nav, ol, p, pre, section, table,
+tbody, td, tfoot, th, thead, tr, ul.
+
+== 3. Attribute order
+
+Attributes sort by name (the shared `Canon::Xml::AttributeSorter`
+walk — the canonical order matches the XML lane's sorter; the
+formatter's `sort_attributes` delegates to it).
+
+== 4. Post-serialize spacing
+
+Two serialization laws, applied in order (the formatter's compiled
+constants carry the same names):
+
+* *Block spacing* (`BLOCK_SPACING_PATTERN`): a block close tag
+  followed by newlines and a block open tag re-spells exactly one
+  newline between them.
+* *After-block fold* (`AFTER_BLOCK_NEWLINE_PATTERN`): a block close
+  tag followed by a newline run and any open tag folds the run to a
+  single space when the follower is not a close tag (the
+  engine-inserted newlines after block closes fold to the canonical
+  single space).
+
+== 5. Idempotence
+
+The form is a fixed point: format(format(x)) == format(x). The
+property suite (canonical-form invariants) and the corpus gates pin
+this per release.

data/docs/_references/yaml-canonical-form.adoc

@@ -0,0 +1,45 @@
+= The YAML canonical form (W1.4)
+
+This document specifies canon's YAML canonical form as shipped by
+`Canon::Formatters::YamlFormatter`. Reviewed against the
+implementation by `spec/canon/docs/canonical_form_spec.rb` (the
+W6.3 review-gate pattern).
+
+== 1. Pipeline
+
+format(input):
+
+1. *Validate* through the YAML validator (engine-resolved: yeptris
+when loadable, Psych otherwise; a validator rejection is a
+Canon::ValidationError with position information).
+2. *Parse* to the Ruby object graph (`safe_load`, aliases enabled).
+3. *Sort* every mapping's keys (the law below).
+4. *Dump* through the engine's emitter (the engine-dump byte-parity
+is pinned by the YAML engine-parity spec).
+
+== 2. The key-order law
+
+Every mapping's keys sort under the TOTAL order over
+`[key.class.name, key.to_s]`:
+
+* Homogeneous String keys sort exactly as a plain string sort.
+* Heterogeneous keys (strings, symbols, integers, nil, complex
+  collections — YAML mappings allow any key type) order by class
+  name first, then string form: the order is deterministic and
+  total, and the sort cannot raise on mixed types (the pre-0.3.113
+  `keys.sort` crashed on the yaml-test-suite's mixed-key shapes).
+
+The sort is applied recursively: nested mappings, and mappings
+inside arrays, sort by the same law.
+
+== 3. Equivalence contract
+
+The canonical form respects key order: two documents differing only
+in mapping key order produce identical canonical bytes (pinned by
+the property suite's shuffled-YAML leg).
+
+== 4. Fixed point
+
+format(format(x)) == format(x) for every accepted document (the
+property suite pins this across the generated corpus and the
+yaml-test-suite gate across the vendored suite).

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.112"
+  VERSION = "0.3.114"
 end

data/lib/canon/xml/attribute_handler.rb

@@ -5,8 +5,12 @@ module Canon
     # Attribute handler for C14N 1.1
     # Handles attribute processing per spec
     class AttributeHandler
-      def initialize(encoder)
+      def initialize(encoder, inherit_xml_attributes: true)
         @encoder = encoder
+        # C14N 1.1 inherits xml:lang/xml:base from omitted ancestors in
+        # subsets; Exclusive C14N drops all xml:* inheritance (the
+        # spec's own point) and disables it here.
+        @inherit_xml_attributes = inherit_xml_attributes
       end
 
       # Process attribute axis of an element
@@ -35,7 +39,7 @@ module Canon
         attributes = element.sorted_attribute_nodes.select(&:in_node_set?)
 
         # Add inherited simple inheritable attributes if needed
-        if omitted_ancestors.any?
+        if @inherit_xml_attributes && omitted_ancestors.any?
           inherited = collect_inherited_attributes(element, omitted_ancestors)
           attributes = merge_attributes(attributes, inherited)
         end

data/lib/canon/xml/c14n.rb

@@ -108,54 +108,15 @@ module Canon
       def self.canonicalize_subset(xml, xpath, with_comments: false)
         root_node = DataModel.from_xml(xml)
 
-        # Mark all nodes as NOT in the node-set initially
-        mark_all_nodes(root_node, false)
-
-        # Evaluate XPath and mark matched nodes
+        # Evaluate XPath and mark the node-set (the C14N marking law:
+        # matched nodes and their descendants; the root always rides)
         matched = XPathEngine.evaluate(root_node, xpath)
-
-        # If XPath matches root or is empty, fall back to full canonicalization
-        if matched.empty?
-          mark_all_nodes(root_node, true)
-        else
-          # Mark matched nodes and their ancestors/descendants
-          mark_subset(root_node, matched)
-        end
+        NodeSetMarker.mark(root_node, matched)
 
         # Process to canonical form
         processor = Processor.new(with_comments: with_comments)
         processor.process(root_node)
       end
-
-      class << self
-        private
-
-        # Recursively set in_node_set on all nodes
-        def mark_all_nodes(node, value)
-          node.in_node_set = value
-          node.children.each { |child| mark_all_nodes(child, value) }
-        end
-
-        # Mark matched nodes and all required supporting nodes.
-        #
-        # Per W3C C14N 1.1, only nodes in the node-set are rendered.
-        # Ancestors not in the node-set become "omitted ancestors" —
-        # the Processor handles namespace/attribute inheritance from them.
-        def mark_subset(root_node, matched)
-          # Mark matched nodes and their descendants
-          matched.each do |node|
-            mark_node_and_descendants(node)
-          end
-
-          # Root node is always in the set so processing starts
-          root_node.in_node_set = true
-        end
-
-        def mark_node_and_descendants(node)
-          node.in_node_set = true
-          node.children.each { |child| mark_node_and_descendants(child) }
-        end
-      end
     end
   end
 end

data/lib/canon/xml/exclusive_c14n.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Exclusive XML Canonicalization (W3C REC xml-exc-c14n-20080702),
+    # the Ruby reference processor. Differs from C14N 1.1 only in the
+    # namespace axis: namespaces render when VISIBLY UTILIZED (the
+    # element's own prefix or an attribute's prefix) or named in the
+    # InclusiveNamespaces PrefixList — see ExclusiveNamespaceHandler.
+    #
+    #     ExclusiveC14n.canonicalize(xml)
+    #     ExclusiveC14n.canonicalize(xml, inclusive_ns_prefixes:
+    #                                       ["#default", "ds"])
+    #     ExclusiveC14n.canonicalize(xml, xpath: "(//. | //@*)
+    #                                            [ancestor-or-self::x]")
+    #
+    # The leptris native exclusive lane rides this face once the
+    # engine ships it (the canon acceptance protocol: byte-identity
+    # through this reference first).
+    class ExclusiveC14n
+      # Canonicalize a document (or an XPath-selected subset)
+      # @param xml [String] XML document as string
+      # @param with_comments [Boolean] Include comments in canonical form
+      # @param inclusive_ns_prefixes [Array<String>] InclusiveNamespaces
+      #        PrefixList tokens (`#default`, bare prefixes)
+      # @param xpath [String, nil] subset selection (C14N node-set
+      #        semantics); nil canonicalizes the whole document
+      # @return [String] Canonical form in UTF-8
+      def self.canonicalize(xml, with_comments: false,
+                            inclusive_ns_prefixes: [], xpath: nil)
+        root_node = DataModel.from_xml(xml)
+
+        if xpath
+          if (idiom = c14n_selection_idiom(xpath))
+            matched = select_ancestor_or_self(root_node, *idiom)
+            NodeSetMarker.mark(root_node, matched, keep_root: false)
+          else
+            matched = XPathEngine.evaluate(root_node, xpath)
+            NodeSetMarker.mark(root_node, matched)
+          end
+        end
+
+        processor = Processor.new(
+          with_comments: with_comments,
+          namespace_handler: ExclusiveNamespaceHandler.new(
+            CharacterEncoder.new, inclusive_ns_prefixes
+          ),
+          inherit_xml_attributes: false,
+        )
+        processor.process(root_node)
+      end
+
+      # The C14N selection idiom the suite drives:
+      #   (//. | //@* | //namespace::*)[ancestor-or-self::pfx:name]
+      # — every node in the subtrees rooted at pfx:name. Returns
+      # [prefix, local_name], or nil for anything else.
+      def self.c14n_selection_idiom(xpath)
+        # the suite's .xpath files are XML documents wrapping the
+        # expression (with prefix declarations and inline comments)
+        text = xpath.sub(/\A<\?xml[^?]*\?>/, "")
+          .gsub(/<!--[\s\S]*?-->/, "")
+          .gsub(/<[^>]*>/, " ")
+          .squeeze(" ")
+        m = text.match(%r{\(//\.\s*\|\s*//@\*\s*\|\s*//namespace::\*\)\s*\[\s*ancestor-or-self::([A-Za-z_][\w.-]*)(?::([\w.-]+))?\s*\]\s*\z})
+        return nil unless m
+
+        m[2] ? [m[1], m[2]] : [nil, m[1]]
+      end
+
+      # The subtree roots whose ancestor-or-self chain touches
+      # prefix:name (resolved through the document's bindings), with
+      # deeper matches subsumed by their topmost ancestor.
+      def self.select_ancestor_or_self(root_node, prefix, local_name)
+        target_uri = nil
+        walk = lambda do |el|
+          if el.respond_to?(:namespace_nodes)
+            el.namespace_nodes.each do |ns|
+              next if ns.default_namespace?
+
+              if ns.prefix == prefix || (prefix.nil? && ns.prefix.nil?)
+                target_uri = ns.uri
+                break
+              end
+            end
+          end
+          break if target_uri
+
+          el.children.each { |c| walk.call(c) if c.node_type == :element }
+        end
+        root_node.children.each { |c| walk.call(c) if c.node_type == :element }
+
+        tops = []
+        collect = lambda do |el|
+          hit = target_uri.nil? ? false : (el.namespace_uri == target_uri)
+          hit ||= prefix.nil? && el.name == local_name
+          if hit
+            tops << el
+          else
+            el.children.each { |c| collect.call(c) if c.node_type == :element }
+          end
+        end
+        root_node.children.each { |c| collect.call(c) if c.node_type == :element }
+        tops
+      end
+    end
+  end
+end

data/lib/canon/xml/exclusive_namespace_handler.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Exclusive XML Canonicalization namespace law (W3C REC
+    # xml-exc-c14n-20080702). Unlike C14N 1.1's render-all-in-scope
+    # namespace axis, the exclusive law renders only namespaces that
+    # are:
+    #
+    #   1. VISIBLY UTILIZED — the element's own prefix, or the prefix
+    #      of an in-node-set attribute of the element; or
+    #   2. IN THE InclusiveNamespaces PrefixList — the transform
+    #      parameter that re-imports ancestor context.
+    #
+    # and then only when no rendered ancestor already carries the
+    # same prefix=uri binding (the ancestor-dedup law C14N shares).
+    # `#default` in the prefix list imports the default namespace.
+    class ExclusiveNamespaceHandler < NamespaceHandler
+      # @param encoder [CharacterEncoder]
+      # @param inclusive_ns_prefixes [Array<String>] the
+      #        InclusiveNamespaces PrefixList tokens (`#default`,
+      #        bare prefixes; a trailing ':' on a token is spelling)
+      def initialize(encoder, inclusive_ns_prefixes = [])
+        super(encoder)
+        @inclusive = inclusive_ns_prefixes.map { |p| p.to_s.chomp(":") }
+        @inclusive_default = @inclusive.delete("#default")
+      end
+
+      private
+
+      # The exclusive rendering set: visibly utilized ∪ inclusive
+      # list, intersected with the element's in-scope namespace nodes.
+      def renderable_namespaces(element)
+        utilized = visibly_utilized_prefixes(element)
+        element.namespace_nodes.sort_by(&:local_name).select do |ns|
+          next false unless ns.in_node_set?
+
+          if ns.default_namespace?
+            @inclusive_default
+          else
+            utilized.include?(ns.prefix) || @inclusive.include?(ns.prefix)
+          end
+        end
+      end
+
+      # The element's own prefix plus the prefixes of its in-node-set
+      # attributes (xml:* excluded — the XML namespace never renders).
+      def visibly_utilized_prefixes(element)
+        prefixes = []
+        prefixes << element.prefix if element.prefix && !element.prefix.empty?
+        element.attribute_nodes.each do |attr|
+          next unless attr.in_node_set?
+          next if attr.xml_base?
+          next if attr.name == "xml:base"
+
+          p = attr.prefix.to_s
+          prefixes << p unless p.empty? || p == "xmlns"
+        end
+        prefixes.uniq
+      end
+
+      # The exclusive law replaces C14N's render-all selection.
+      # (the `ns` param name is the file's shared vocabulary)
+      def should_skip_namespace?(ns, elem, parent_element) # rubocop:disable Naming/MethodParameterName
+        return true if ns.xml_namespace?
+
+        namespace_declared_by_ancestor?(ns, elem, parent_element)
+      end
+
+      # The empty-default emission follows the inclusive list: only
+      # when #default is imported and the in-scope default is
+      # non-empty does xmlns="" re-appear.
+      def should_emit_empty_default_namespace?(_element, namespaces,
+                                               parent_element)
+        return false unless @inclusive_default
+        return false if namespaces.first&.default_namespace?
+        return false unless parent_element
+
+        parent_default_ns = parent_element.namespace_nodes.find do |ns|
+          ns.default_namespace? && ns.in_node_set?
+        end
+
+        parent_default_ns && !parent_default_ns.uri.empty?
+      end
+    end
+  end
+end

data/lib/canon/xml/node_set_marker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Marks the XPath node-set on a data-model tree for both C14N
+    # lanes (C14n and ExclusiveC14n): all nodes cleared, the matched
+    # nodes and their descendants marked, the root always kept so
+    # processing starts.
+    module NodeSetMarker
+      module_function
+
+      # keep_root: the C14N subset lane pins the root into the set so
+      # processing starts there (its selectors include it); the
+      # exclusive corpus's selectors exclude the document element and
+      # the output renders the included subtrees as fragments.
+      def mark(root_node, matched, keep_root: true)
+        mark_all(root_node, false)
+        if matched.nil? || matched.empty?
+          mark_all(root_node, true)
+        else
+          matched.each { |node| mark_node_and_descendants(node) }
+          root_node.in_node_set = true if keep_root
+        end
+      end
+
+      def mark_all(node, value)
+        node.in_node_set = value
+        node.children.each { |child| mark_all(child, value) }
+      end
+
+      def mark_node_and_descendants(node)
+        node.in_node_set = true
+        node.children.each { |child| mark_node_and_descendants(child) }
+      end
+    end
+  end
+end

data/lib/canon/xml/processor.rb

@@ -5,11 +5,14 @@ module Canon
     # C14N 1.1 processor
     # Processes XPath data model and generates canonical form
     class Processor
-      def initialize(with_comments: false)
+      def initialize(with_comments: false, namespace_handler: nil,
+                     inherit_xml_attributes: true)
         @with_comments = with_comments
         @encoder = CharacterEncoder.new
-        @namespace_handler = NamespaceHandler.new(@encoder)
-        @attribute_handler = AttributeHandler.new(@encoder)
+        @namespace_handler = namespace_handler || NamespaceHandler.new(@encoder)
+        @attribute_handler = AttributeHandler.new(
+          @encoder, inherit_xml_attributes: inherit_xml_attributes
+        )
         @xml_base_handler = XmlBaseHandler.new
       end
 

data/lib/canon/xml/xpath_engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "strscan"
+
 module Canon
   module Xml
     # XPath evaluation engine for C14N subset selection.

data/lib/canon/xml.rb

@@ -21,10 +21,13 @@ module Canon
     autoload :CharacterEncoder, "canon/xml/character_encoder"
     autoload :DataModel, "canon/xml/data_model"
     autoload :ElementMatcher, "canon/xml/element_matcher"
+    autoload :ExclusiveC14n, "canon/xml/exclusive_c14n"
+    autoload :ExclusiveNamespaceHandler, "canon/xml/exclusive_namespace_handler"
     autoload :LineRangeMapper, "canon/xml/line_range_mapper"
     autoload :NamespaceHandler, "canon/xml/namespace_handler"
     autoload :NamespaceHelper, "canon/xml/namespace_helper"
     autoload :Node, "canon/xml/node"
+    autoload :NodeSetMarker, "canon/xml/node_set_marker"
     autoload :Nodes, "canon/xml/nodes"
     autoload :Processor, "canon/xml/processor"
     autoload :Sax, "canon/xml/sax"

data/scripts/exc_c14n_differential.rb

@@ -0,0 +1,61 @@
+require_relative "../lib/canon"
+require "nokogiri"
+
+# Diagnostic: the ExclusiveC14n differential against nokogiri/libxml2
+# over the vendored merlin-c14n-two corpus. NOT a battery gate — see
+# TODO.sota/05 for the residual map (the extended-predicate subset
+# semantics and the default-ns law disposition).
+CORPUS = File.join(__dir__, "../spec/fixtures/corpora/exc-c14n")
+results = Hash.new { |h, k| h[k] = [] }
+
+Dir.glob("#{CORPUS}/*.xml").each do |input|
+  base = File.basename(input, ".xml")
+  xpath_file = "#{CORPUS}/#{base}.xpath"
+  ns_file = "#{CORPUS}/#{base}.ns"
+  ns_list = File.exist?(ns_file) ? File.read(ns_file).split : []
+
+  doc = Nokogiri::XML(File.read(input))
+  # compact product: strip whitespace-only text nodes (canon's C14N
+  # lane parses noblanks; the compact bytes are the product)
+  doc.xpath("//text()").select { |t| t.content.strip.empty? }.each(&:remove)
+
+  if File.exist?(xpath_file)
+    # subset case: canon evaluates its own XPath marking
+    mine = Canon::Xml::ExclusiveC14n.canonicalize(
+      File.read(input), xpath: File.read(xpath_file).strip,
+                        inclusive_ns_prefixes: ns_list
+    )
+    # oracle: subtree selection — evaluate the same selector, take
+    # the topmost matched element(s), canonicalize exclusive with
+    # the same prefix list
+    xp = Nokogiri::XML(File.read(xpath_file))
+    prefix_map = xp.root.namespaces.transform_values { |v| v.to_s.sub(%r{^xmlns(?::)?}, "") }
+    expr = xp.root.text.strip
+    matched = doc.xpath(expr, prefix_map).grep(Nokogiri::XML::Element)
+    tops = matched.reject { |n| n.ancestors.any? { |a| a.element? && matched.include?(a) } }
+    ref = tops.map do |t|
+      t.canonicalize(Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0, ns_list, false)
+    end.join
+  else
+    mine = Canon::Xml::ExclusiveC14n.canonicalize(
+      File.read(input), inclusive_ns_prefixes: ns_list
+    )
+    ref = doc.root.canonicalize(Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0, ns_list, false)
+  end
+
+  if mine == ref
+    results[:match] << base
+  elsif base == "merlin-c14n-two-10"
+    File.write("/tmp/exc_ref.txt", ref)
+    File.write("/tmp/exc_mine.txt", mine)
+  elsif mine.include?("xmlns=") == ref.include?("xmlns=") &&
+      mine.gsub(/ xmlns(:\w+)?="[^"]*"/, "") == ref.gsub(/ xmlns(:\w+)?="[^"]*"/, "")
+    results[:default_ns_only] << base
+  else
+    results[:differ] << base
+  end
+rescue StandardError => e
+  results[:error] << "#{base} (#{e.class.name.split('::').last}: #{e.message[0, 60]})"
+end
+
+results.each { |k, v| puts "#{k}: #{v.count} #{v.first(6).inspect}" }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.112
+  version: 0.3.114
 platform: ruby
 authors:
 - Ribose Inc.
@@ -173,6 +173,9 @@ files:
 - docs/Gemfile
 - docs/INDEX.adoc
 - docs/_config.yml
+- docs/_references/comparison-theory.adoc
+- docs/_references/html-canonical-form.adoc
+- docs/_references/yaml-canonical-form.adoc
 - docs/advanced/diff-classification.adoc
 - docs/advanced/diff-pipeline.adoc
 - docs/advanced/extending-canon.adoc
@@ -411,10 +414,13 @@ files:
 - lib/canon/xml/data_model.rb
 - lib/canon/xml/digest_gate.rb
 - lib/canon/xml/element_matcher.rb
+- lib/canon/xml/exclusive_c14n.rb
+- lib/canon/xml/exclusive_namespace_handler.rb
 - lib/canon/xml/line_range_mapper.rb
 - lib/canon/xml/namespace_handler.rb
 - lib/canon/xml/namespace_helper.rb
 - lib/canon/xml/node.rb
+- lib/canon/xml/node_set_marker.rb
 - lib/canon/xml/nodes.rb
 - lib/canon/xml/nodes/attribute_node.rb
 - lib/canon/xml/nodes/comment_node.rb
@@ -444,6 +450,7 @@ files:
 - lib/tasks/performance_helpers.rb
 - lib/tasks/performance_report.rb
 - lib/xml-c14n.rb
+- scripts/exc_c14n_differential.rb
 - sig/xml/c14n.rbs
 homepage: https://github.com/lutaml/canon
 licenses: