moxml 0.1.25 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed30996109d8cfb8057f216677cba8ca3cd3856287c38b6a7edab3251ebb2064
-  data.tar.gz: f93d7c13863ef9d437e40403e4a48434ed1e1c5530ea2424cdeff710740243a0
+  metadata.gz: 1e82117ebd56032bed4f9edffbb2714dec306b7bec52999193ef69fe62835ab9
+  data.tar.gz: 824fb9a07952249c2c97e650d5610d90c53ee23f279980aa5987e2a53922d74a
 SHA512:
-  metadata.gz: 9b09c144a268507bb02a16a4c6ba7caf6d1a2fa003718a6fa0960a8b68ba03a09584a66fb9475b1c23cd2d79071f1cc8c313200749f997d317aa90e61fba3811
-  data.tar.gz: 6389858a232d82faad5f6bbfd22d4828801c7a6d45a55a2a0f08d28c44647a588b52d2106649d408777453b571815b40c191f48c374cc49b648c58ad2be1e835
+  metadata.gz: 845a7de92860b25e68353e14efee1cc0015abfdc5a32f526b0baf1c45870e2966c1db6560eb45267a2fd0beab62936063493ac559fcca4317feffdcd0e54042a
+  data.tar.gz: 8242097334c0d1287bcc5c61658042e095ca1a34e375ff034c1504b9607f272937d62bd3ded2c439f45e7d6ae71ea58d86f5af37992858ab9a5fbadbe31fe738

data/.github/workflows/release.yml

@@ -13,6 +13,14 @@ on:
           Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
         required: true
         default: 'skip'
+      gated:
+        description: |
+          Defer rubygems publish to a separate repository_dispatch (do-release) run.
+          - false (default): bump + tag + publish in one step.
+          - true: bump + tag only; publish when do-release is triggered.
+        required: false
+        default: false
+        type: boolean
   repository_dispatch:
     types: [ do-release ]
 
@@ -21,6 +29,7 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      gated: ${{ inputs.gated == true }}
     secrets:
       rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/windows.yml

@@ -0,0 +1,62 @@
+name: windows
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  adapters:
+    name: Adapter specs on Windows (libxml)
+    runs-on: windows-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: false
+
+      - name: Install libxml2 and build tools via MSYS2
+        shell: cmd
+        run: |
+          C:\msys64\usr\bin\pacman.exe -S --needed --noconfirm ^
+            mingw-w64-ucrt-x86_64-libxml2 ^
+            mingw-w64-ucrt-x86_64-libiconv ^
+            mingw-w64-ucrt-x86_64-zlib ^
+            mingw-w64-ucrt-x86_64-ragel ^
+            mingw-w64-ucrt-x86_64-make ^
+            mingw-w64-ucrt-x86_64-gcc
+
+      - name: Put MSYS2 UCRT64 toolchain on PATH
+        shell: pwsh
+        run: |
+          "PATH=C:\msys64\ucrt64\bin;C:\msys64\usr\bin;$env:PATH" >> $env:GITHUB_ENV
+
+      - name: Configure libxml-ruby build
+        shell: pwsh
+        run: |
+          bundle config build.libxml-ruby --with-xml2-include=C:/msys64/ucrt64/include/libxml2 --with-xml2-lib=C:/msys64/ucrt64/lib --with-iconv-include=C:/msys64/ucrt64/include --with-iconv-lib=C:/msys64/ucrt64/lib
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        shell: pwsh
+        run: |
+          gem install ruby-ll --no-document
+          rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install --jobs 4
+
+      - name: Compile vendored native extensions
+        run: bundle exec rake vendor:compile
+
+      - name: Run adapter specs
+        run: bundle exec rake spec:adapter

data/Gemfile

@@ -9,6 +9,7 @@ gemspec
 gem "benchmark"
 gem "benchmark-ips"
 gem "get_process_mem"
+gem "leptris", "~> 1.1"
 gem "libxml-ruby", "~> 5.0"
 gem "nokogiri", "~> 1.18"
 gem "openssl", "~> 3.0"
@@ -30,7 +31,8 @@ gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "simplecov", require: false
-gem "stackprof"
+# stackprof relies on POSIX signals (SIGPROF/sigaction) unavailable on Windows
+gem "stackprof" unless Gem.win_platform?
 gem "tempfile"
 
 # Needed by get_process_mem on Windows

data/README.adoc

@@ -47,12 +47,21 @@ LibXML:: https://github.com/xml4r/libxml-ruby[libxml-ruby], Ruby bindings
 for the performant https://github.com/GNOME/libxml2[libxml2] C library.
 Alternative to Nokogiri with similar performance characteristics.
 
+Leptris:: https://github.com/leptris/leptris[Leptris], a pure-C99 XML 1.0
+parser with a W3C-conformant XPath 1.0 engine, consumed through the
+https://github.com/leptris/leptris-ruby[leptris-ruby] FFI binding
+(precompiled platform gems — no compilation at install). Fastest on
+every measured operation; requires leptris >= 1.2 for programmatic
+document construction.
+
 ==== Default adapter selection
 
 When no adapter is explicitly specified, Moxml selects one automatically based on
 the runtime environment:
 
 . If running on Opal (`RUBY_ENGINE == "opal"`), Oga is used (pure Ruby, no C extensions)
+. Otherwise, if the installed leptris gem supports programmatic document
+  construction (`Leptris::XML::Document.create`, leptris >= 1.2), Leptris is used
 . Otherwise, Moxml detects already-loaded XML libraries in this order:
   .. Nokogiri
   .. Ox
@@ -63,7 +72,7 @@ the runtime environment:
 ----
 # Automatic detection — picks the best available adapter
 ctx = Moxml.new
-ctx.config.adapter_name  # => :nokogiri (or :oga on Opal)
+ctx.config.adapter_name  # => :leptris (leptris >= 1.2), :nokogiri otherwise, :oga on Opal
 
 # Explicit override — always takes precedence
 ctx = Moxml.new(:ox)
@@ -80,9 +89,9 @@ The following table summarizes the features supported by each library.
 NOTE: The checkmarks indicate support for the feature, while the footnotes
 provide additional context for specific features.
 
-[cols="1,1,1,1,1,3"]
+[cols="1,1,1,1,1,1,1,3"]
 |===
-|Feature |Nokogiri |Oga |REXML |LibXML |Ox |HeadedOx
+|Feature |Nokogiri |Oga |REXML |LibXML |Ox |HeadedOx |Leptris
 
 |Parsing, serializing
 | ✅
@@ -91,6 +100,7 @@ provide additional context for specific features.
 | ✅
 | ✅
 | ✅
+| ✅
 
 |SAX parsing
 | ✅ Full (10/10 events)
@@ -99,6 +109,7 @@ provide additional context for specific features.
 | ✅ Full (10/10 events)
 | ⚠️ Core (4/10 events) See NOTE 7.
 | ⚠️ Core (4/10 events) See NOTE 7.
+| ✅ Full See NOTE 8.
 
 |Node manipulation
 | ✅
@@ -107,6 +118,7 @@ provide additional context for specific features.
 | ✅
 | ✅ See NOTE 1.
 | ✅ See NOTE 1.
+| ✅
 
 |Basic XPath
 | ✅
@@ -115,6 +127,8 @@ provide additional context for specific features.
 | ✅
 | Uses Ox-specific API `locate`. See NOTE 2.
 | ✅ Full XPath 1.0. See NOTE 3.
+| ✅ Full XPath 1.0 via Moxml's Ruby engine. See NOTE 8.
+
 
 |XPath with namespaces
 | ✅
@@ -123,6 +137,7 @@ provide additional context for specific features.
 | ✅
 | Uses Ox-specific API `locate`. See NOTE 2.
 | ⚠️ Basic. See NOTE 3.
+| ✅ Full See NOTE 8.
 
 |===
 
@@ -139,15 +154,23 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element,
 characters, errors). No separate CDATA, comment, or processing instruction
 events.
 
+NOTE: Leptris: XPath is evaluated by Moxml's pure-Ruby XPath 1.0 engine
+(same as HeadedOx) rather than libleptris's native engine, because the
+native engine does not resolve expression prefixes against
+document-declared namespaces. XML declarations, programmatic DOCTYPEs,
+and entity references are value objects stored via NativeAttachment —
+libleptris has no first-class nodes for them.
+
 == Adapter comparison
 
 === Feature compatibility matrix
 
-[cols="3,1,1,1,1,1,1", options="header"]
+[cols="3,1,1,1,1,1,1,1", options="header"]
 |===
-| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox | HeadedOx
+| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox | HeadedOx | Leptris
 
 | *Core Operations*
+
 |
 |
 |
@@ -162,6 +185,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Parse XML file/IO
 | ✅ Full
@@ -170,6 +194,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Serialize to XML
 | ✅ Full
@@ -178,9 +203,12 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | *Element Operations*
+
 |
+ 
 |
 |
 |
@@ -194,6 +222,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Get/set attributes
 | ✅ Full
@@ -202,6 +231,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Add/remove children
 | ✅ Full
@@ -210,6 +240,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Replace nodes
 | ✅ Full
@@ -218,9 +249,12 @@ events.
 | ✅ Full
 | ⚠️ Limited^1^
 | ⚠️ Limited^1^
+| ✅ Full
 
 | *Namespace Operations*
+
 |
+ 
 |
 |
 |
@@ -234,6 +268,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Default namespaces
 | ✅ Full
@@ -242,6 +277,7 @@ events.
 | ✅ Full
 | ⚠️ Basic
 | ⚠️ Basic
+| ✅ Full
 
 | Namespace inheritance
 | ✅ Full
@@ -250,6 +286,7 @@ events.
 | ✅ Full
 | ❌ None
 | ❌ None^5^
+| ✅ Full
 
 | Namespaced attributes
 | ✅ Full
@@ -258,9 +295,12 @@ events.
 | ✅ Full
 | ⚠️ Limited
 | ⚠️ Limited^5^
+| ✅ Full
 
 | *XPath Queries*
+
 |
+ 
 |
 |
 |
@@ -274,6 +314,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Attribute predicates (`[@id]`)
 | ✅ Full
@@ -282,6 +323,7 @@ events.
 | ✅ Full
 | ⚠️ Existence only^2^
 | ✅ Full
+| ✅ Full
 
 | Attribute values (`[@id='123']`)
 | ✅ Full
@@ -290,6 +332,7 @@ events.
 | ✅ Full
 | ❌ None^3^
 | ✅ Full
+| ✅ Full
 
 | Logical operators (`[@a and @b]`)
 | ✅ Full
@@ -298,6 +341,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Position predicates (`[1]`, `[last()]`)
 | ✅ Full
@@ -306,6 +350,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Text predicates (`[text()='x']`)
 | ✅ Full
@@ -314,6 +359,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Namespace-aware queries
 | ✅ Full
@@ -322,6 +368,7 @@ events.
 | ✅ Full
 | ❌ None
 | ⚠️ Basic^5^
+| ✅ Full
 
 | Parent axis (`..`)
 | ✅ Full
@@ -330,6 +377,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Sibling axes
 | ✅ Full
@@ -338,6 +386,7 @@ events.
 | ✅ Full
 | ❌ None
 | ❌ None^5^
+| ✅ Full
 
 | XPath functions (`count()`, etc.)
 | ✅ Full
@@ -346,9 +395,12 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ All 27
+| ✅ All 27
 
 | *Special Content*
+
 |
+ 
 |
 |
 |
@@ -362,6 +414,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Comments
 | ✅ Full
@@ -370,6 +423,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Processing instructions
 | ✅ Full
@@ -378,6 +432,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | DOCTYPE declarations
 | ✅ Full
@@ -386,9 +441,12 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ⚠️ Value-object sidecar^8^
 
 | *Performance*
+
 |
+ 
 |
 |
 |
@@ -402,6 +460,7 @@ events.
 | Fast
 | Very Fast
 | Very Fast
+| Fastest
 
 | Serialize speed
 | Fast
@@ -410,6 +469,7 @@ events.
 | Medium
 | Very Fast
 | Very Fast
+| Very Fast
 
 | Memory usage
 | Good
@@ -418,6 +478,7 @@ events.
 | Good
 | Excellent
 | Excellent
+| Excellent
 
 | Thread safety
 | ✅ Yes
@@ -426,13 +487,15 @@ events.
 | ✅ Yes
 | ✅ Yes
 | ✅ Yes
+| ⚠️ One doc per thread^8^
 |===
 +
 ^1^ Ox/HeadedOx: Text node replacement may fail in some cases due to internal node structure +
 ^2^ Ox: `//book[@id]` works (returns all book elements), but doesn't filter by attribute existence +
 ^3^ HeadedOx: Full XPath 1.0 with all 27 functions and 6 axes. Pure Ruby XPath engine on Ox's C parser. 99.20% pass rate. See link:docs/headed-ox.adoc[] +
 ^4^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute value predicates +
-^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
+^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[] +
+^8^ Leptris: XPath runs through Moxml's pure-Ruby XPath 1.0 engine (the native C engine does not resolve expression prefixes against document namespaces); DOCTYPEs and XML declarations are value objects stored via NativeAttachment; libleptris documents are not thread-safe — one document per thread
 
 === Adapter selection guide
 
@@ -559,6 +622,70 @@ ruby examples/api_client/api_client.rb
 See the link:examples/README.md[examples README] for complete documentation and
 learning paths.
 
+== XML Signature (Moxml::Signature)
+
+Moxml includes an XML-implementation-agnostic implementation of W3C XML
+Signature (xmldsig-core-1.1). Sign and verify documents with any moxml
+adapter; the canonicalization engine produces byte-exact output that
+cross-verifies with libxmlsec1.
+
+=== Quick start
+
+[source,ruby]
+----
+require "moxml"
+require "moxml/signature"
+require "openssl"
+
+ctx = Moxml.new(:nokogiri)
+key = OpenSSL::PKey::RSA.generate(2048)
+doc = ctx.parse("<doc><greeting>Hello, World!</greeting></doc>")
+
+# Sign
+signature = Moxml::Signature.sign(
+  context: ctx, document: doc, key: key,
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+# Verify (auto-extracts key from KeyInfo if absent)
+result = Moxml::Signature.verify(context: ctx, document: doc, key: key)
+result.valid?  # => true
+----
+
+=== Supported algorithms
+
+Digests:: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
+Signature methods:: RSA-PKCS1v1.5, HMAC, ECDSA (P-256/P-384/P-521), DSA
+Canonicalization:: Exclusive C14N 1.0, Inclusive C14N 1.0, Inclusive C14N 1.1
+Transforms:: base64, Enveloped Signature
+
+Adding a custom algorithm means declaring `identifier "http://..."` on a
+subclass — no edits to existing code. See
+link:docs/signature/algorithms.md[the algorithms doc].
+
+=== Canonicalization (Moxml::C14n)
+
+C14N is a top-level moxml feature (sibling to XPath, Builder, SAX).
+Inclusive C14N is ported from the sibling `canon` gem; Exclusive C14N
+is moxml-native. See link:docs/signature/c14n.md[the C14N doc].
+
+=== Documentation
+
+* link:docs/signature/architecture.md[Architecture]
+* link:docs/signature/algorithms.md[Algorithm registry]
+* link:docs/signature/c14n.md[Canonicalization]
+* link:docs/signature/flows.md[Signer and Verifier flows]
+* link:docs/signature/key-extraction.md[Key extraction] (TODO)
+* link:docs/signature/security.md[Security considerations]
+* link:docs/signature/quick-reference.md[Quick reference]
+* link:examples/signature/[Runnable examples]
+
 == Working with documents
 
 === Using the builder pattern

data/docs/signature/algorithms.md

@@ -0,0 +1,108 @@
+# Algorithm registry
+
+The `Moxml::Signature::Algorithms` module is the open-closed hub for
+all W3C XML Signature algorithms. Algorithms are identified by URI;
+the registry maps URI → class for each of four categories:
+
+| Category             | W3C spec section | Base class                                    |
+| -------------------- | ---------------- | --------------------------------------------- |
+| `:digest`            | §6.2             | `Algorithms::DigestBase`                      |
+| `:signature_method`  | §6.3, §6.4       | `Algorithms::SignatureMethodBase`             |
+| `:canonicalization`  | §6.5             | `Algorithms::CanonicalizationBase`            |
+| `:transform`         | §6.6             | `Algorithms::TransformBase`                   |
+
+## Built-in algorithms
+
+### Digests (§6.2)
+
+| URI                                                        | Class            |
+| ---------------------------------------------------------- | ---------------- |
+| `http://www.w3.org/2000/09/xmldsig#sha1`                   | `SHA1`           |
+| `http://www.w3.org/2001/04/xmldsig-more#sha224`            | `SHA224`         |
+| `http://www.w3.org/2001/04/xmlenc#sha256` (REQUIRED)       | `SHA256`         |
+| `http://www.w3.org/2001/04/xmldsig-more#sha384`            | `SHA384`         |
+| `http://www.w3.org/2001/04/xmlenc#sha512`                  | `SHA512`         |
+
+### Signature methods (§6.3, §6.4)
+
+| URI                                                        | Class            | Notes |
+| ---------------------------------------------------------- | ---------------- | ----- |
+| `…xmldsig#rsa-sha1`                                        | `RsaPkcs1Sha`    | Verification only (BP: SHA-1 discouraged) |
+| `…xmldsig-more#rsa-sha224`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha256` (REQUIRED)                      | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha384`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha512`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig#hmac-sha1`                                       | `HmacSha`        | Truncation enforced per §4.4.2 |
+| `…xmldsig-more#hmac-sha224`                                | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha256` (REQUIRED)                     | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha384`                                | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha512`                                | `HmacSha`        | |
+| `…xmldsig-more#ecdsa-sha1`                                 | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha224`                               | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha256` (REQUIRED)                    | `EcdsaSha`       | P-256/P-384/P-521 |
+| `…xmldsig-more#ecdsa-sha384`                               | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha512`                               | `EcdsaSha`       | |
+| `…xmldsig#dsa-sha1`                                        | `DsaSha`         | |
+| `…xmldsig11#dsa-sha256`                                    | `DsaSha`         | |
+
+### Canonicalization (§6.5)
+
+| URI                                                        | Engine                       |
+| ---------------------------------------------------------- | ---------------------------- |
+| `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`          | `Moxml::C14n::Inclusive10` (canon-ported) |
+| `…REC-xml-c14n-20010315#WithComments`                      | same, `with_comments: true`  |
+| `http://www.w3.org/2006/12/xml-c14n11`                     | `Moxml::C14n::Inclusive11`   |
+| `…xml-c14n11#WithComments`                                 | same, `with_comments: true`  |
+| `http://www.w3.org/2001/10/xml-exc-c14n#`                  | `Moxml::C14n::Exclusive` (moxml-native) |
+| `…xml-exc-c14n#WithComments`                               | same, `with_comments: true`  |
+
+### Transforms (§6.6)
+
+| URI                                                        | Class                          |
+| ---------------------------------------------------------- | ------------------------------ |
+| `http://www.w3.org/2000/09/xmldsig#base64`                 | `Base64Transform`              |
+| `http://www.w3.org/2000/09/xmldsig#enveloped-signature`    | `EnvelopedSignatureTransform`  |
+
+Canonicalization algorithms can also be used as transforms per §6.6.1.
+The `TransformPipeline` looks them up in the canonicalization registry
+as a fallback.
+
+## Adding a custom algorithm
+
+```ruby
+require "moxml/signature"
+
+module MyAlgo
+  class SHA3_256 < Moxml::Signature::Algorithms::DigestBase
+    identifier "http://www.w3.org/2007/xmldsig-more#sha3-256"
+
+    def compute_digest(data)
+      OpenSSL::Digest.digest("SHA3-256", data)
+    end
+  end
+end
+
+# Now the URI resolves:
+Moxml::Signature::Algorithms.lookup(
+  :digest,
+  "http://www.w3.org/2007/xmldsig-more#sha3-256",
+)
+# => MyAlgo::SHA3_256
+```
+
+The `identifier` declaration registers the class on load. No edits to
+existing code are required — pure OCP.
+
+## API
+
+```ruby
+Algorithms.lookup(:digest, uri)       # → class, raises UnknownAlgorithm
+Algorithms.registered?(:digest, uri)  # → bool
+Algorithms[:digest]                   # → { uri => class, ... }
+```
+
+## Lazy loading
+
+The registry autoloads built-in algorithm classes on first lookup
+(`load_builtins!` references each constant, triggering autoload).
+Custom algorithms register themselves on `require` of their file.