stride-align 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88ccdf6bd96ab5ff0dadc902ecdcfc3c00126230f1ecadeb3e848e2353c75920
+  data.tar.gz: a76d32796250ec94130ad285b7adc293387edcd8ae6bb3067b109ec9aedf664b
+SHA512:
+  metadata.gz: c02fc4191b38e0fe898d33dc5f249bf7f6d8ce60b1003c213a793c434f8e8d2b1d2e862c9308395e52ec717ae4ef30f85987f4a2bc7af9f7711d450772ade69a
+  data.tar.gz: 856dc17733bf48743ce985438a6aadbab76a3d5c95aeb6050da51326d8e3f74ba8dbfd00b31bc3ef547c8c4760986121ecff926683f67c1593654eb65b33cfd5

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,255 @@
+stride-align
+Copyright 2025-2026 Adam DePrince
+
+This product includes software developed by The Apache Software Foundation
+(http://www.apache.org/).
+
+----------------------------------------------------------------------
+
+Phonetic encoder ports
+======================
+
+The following phonetic encoder implementations are derivative works of
+Apache Commons Codec (https://commons.apache.org/proper/commons-codec/),
+licensed under the Apache License, Version 2.0. The algorithmic
+structure of the ports follows the corresponding Apache Commons Codec
+classes; the C++ port is original code.
+
+  * include/stride_align/soundex.hpp
+    Reference: org.apache.commons.codec.language.Soundex
+
+  * include/stride_align/metaphone.hpp
+    Reference: org.apache.commons.codec.language.Metaphone
+
+  * include/stride_align/double_metaphone.hpp
+    Reference: org.apache.commons.codec.language.DoubleMetaphone
+
+  * include/stride_align/nysiis.hpp
+    Reference: org.apache.commons.codec.language.Nysiis
+
+  * include/stride_align/match_rating.hpp
+    Reference: org.apache.commons.codec.language.MatchRatingApproachEncoder
+
+  * include/stride_align/caverphone.hpp
+    Reference: org.apache.commons.codec.language.Caverphone2
+
+  * include/stride_align/cologne_phonetic.hpp
+    Reference: org.apache.commons.codec.language.ColognePhonetic
+
+  * include/stride_align/daitch_mokotoff.hpp
+    Reference: org.apache.commons.codec.language.DaitchMokotoffSoundex
+    The rule table is derived directly from the Apache Commons Codec
+    resource file ``dmrules.txt`` (see
+    ``docs/upstream/apache-commons-codec-dmrules.txt``).
+
+  * include/stride_align/beider_morse.hpp
+    src/cpp/beider_morse_impl.cpp
+    Reference: org.apache.commons.codec.language.bm.*
+    Stride-align ships the GENERIC name-type rules only. The vendored
+    rule files live in ``src/stride_align/bmpm_data/`` (loaded at
+    runtime via ``importlib.resources``); each file preserves its
+    original ASF Apache 2.0 header. The first-codepoint-bucket rule
+    lookup, predicate classifier, arena allocator, and parser in
+    ``beider_morse_impl.cpp`` are original C++.
+
+Algorithmic structure and named test vectors of each encoder were
+cross-checked against the canonical Apache Commons Codec test cases
+during development. The third-party Python libraries listed in
+``[project.optional-dependencies].phonetic-compat`` — jellyfish
+(MIT), the ``metaphone`` PyPI package (BSD), and pyphonetics (MIT) —
+are available to downstream users who want their own cross-checks;
+stride-align's own tests (``tests/test_phonetic.py``,
+``tests/test_beider_morse.py``) import only ``pytest`` and
+``stride_align`` and use hand-pinned expected values.
+
+The separate ``tests/test_jellyfish_shim.py`` differential battery
+imports Jellyfish when available because that module explicitly
+targets Jellyfish API compatibility.
+
+----------------------------------------------------------------------
+
+Algorithmic inspiration
+=======================
+
+The multi-word bit-parallel Indel / LCSseq kernel in
+``include/stride_align/indel.hpp`` (the ``indel_distance_k2_u8`` and
+related K-specialised paths, plus the fused per-block recurrence in
+``indel_distance_multi_word_u8``) is informed by the architecture of
+rapidfuzz-cpp (https://github.com/rapidfuzz/rapidfuzz-cpp,
+licensed MIT, Max Bachmann and contributors). Specifically:
+
+  * The fused single-step Hyyrö per-block update
+    ``U = S & PEQ[c]; sum = addc64(S, U, carry);
+    S = sum | (S - U)`` — one fused expression per K block
+    rather than four separate K-sized passes — was adopted from
+    the rapidfuzz-cpp Indel / LCSseq design.
+  * The observation that the per-block ``S - U`` term needs no
+    borrow chain across blocks (the Hyyrö invariant ``U <= S``
+    bitwise) was likewise inherited from their implementation.
+  * Compile-time template specialisation of K = 1 through 8 paths
+    with a runtime ``switch`` dispatch on block count, so the
+    compiler sees N as a constant and pins state in registers
+    across the entire text loop.
+  * Stack-resident ``S[N]`` state for K <= 8 (no heap traffic per
+    call).
+  * The Ukkonen-style diagonal-band early-exit shape for the
+    ``score_cutoff`` path.
+
+No source code, header comments, identifier names, file layouts,
+struct field orderings, or close-paraphrased structural elements
+were copied from rapidfuzz-cpp. The architectural ideas above were
+extracted by a delegated investigation that reported back algorithm
+structure in its own prose, while the code-authoring agent did not
+read the rapidfuzz-cpp source. See
+``docs/phase-D-external-sources.md`` §3a and §4c for the full
+provenance trail.
+
+Striped SIMD alignment kernels
+==============================
+
+The striped-profile layout and the lazy-F (Farrar-style) horizontal-gap
+correction in stride-align's SIMD Smith-Waterman / Needleman-Wunsch kernels
+(``src/cpp/backends/*.hpp``) are informed by the architecture of parasail
+(https://github.com/jeffdaily/parasail), a BSD-3-Clause SIMD pairwise
+alignment library by Jeff Daily. The striped inner-loop structure and the
+lazy-F correction pass were studied from parasail's source for algorithmic
+ideas; the kernels here are original C++ and no parasail source was copied.
+The academic citation lives in the README "References" section:
+
+  Daily, Jeff. (2016). Parasail: SIMD C library for global, semi-global, and
+  local pairwise sequence alignments. BMC Bioinformatics, 17(1), 1-11.
+  doi:10.1186/s12859-016-0930-z
+
+A consolidated source audit covering every phonetic encoder lives at
+``docs/phonetic-encoder-external-sources.md``. The BMPM-specific
+audit (Apache Commons Codec rule data, vendored resources, explicit
+GPL-port exclusions) lives at ``docs/bmpm-external-sources.md``.
+
+----------------------------------------------------------------------
+
+Test oracles and compatibility references
+=========================================
+
+The third-party phonetic libraries listed under
+``[project.optional-dependencies].phonetic-compat`` are optional
+cross-check oracles. ``metaphone`` and ``pyphonetics`` remain
+test-time references only. Jellyfish is also the API and behavioural
+reference for ``src/stride_align/jellyfish.py``; its compatibility
+rule variants are adapted under the following MIT licence. TheFuzz
+and RapidFuzz are the behavioural references for
+``src/stride_align/thefuzz/`` and its optional differential tests;
+their compatibility conventions are adapted under the MIT licences
+retained below.
+
+Jellyfish compatibility facade
+==============================
+
+The Jellyfish 1.2.1 compatibility rule variants in
+``src/stride_align/jellyfish.py`` are adapted from Jellyfish:
+https://codeberg.org/jpt/jellyfish
+
+MIT License
+
+Copyright (c) 2015 James Turk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TheFuzz compatibility facade
+============================
+
+The public adapter structure and legacy compatibility conventions in
+``src/stride_align/thefuzz/`` are adapted from TheFuzz 0.22.1:
+https://github.com/seatgeek/thefuzz
+
+MIT License
+
+Copyright (c) 2014 SeatGeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+RapidFuzz sequence compatibility
+================================
+
+The generic-sequence normalization, token-set arithmetic order, and
+unrounded-score ranking conventions retained by the TheFuzz facade were
+cross-checked against RapidFuzz 3.14.5's MIT-licensed Python implementation:
+https://github.com/rapidfuzz/RapidFuzz
+
+Copyright © 2020-present Max Bachmann
+Copyright © 2011 Adam Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+----------------------------------------------------------------------
+
+Keyboard typo / confusion matrices (data)
+=========================================
+
+The optional keyboard substitution matrices — built by
+``tools/build_keyboard_matrices.py`` and loaded through the
+``stride_align.matrices.keyboard`` namespace — are derived, with the
+authors' permission, from the Aalto University "136 Million Keystrokes"
+dataset:
+
+    Vivek Dhakal, Anna Maria Feit, Per Ola Kristensson, Antti Oulasvirta.
+    "Observations on Typing from 136 Million Keystrokes." Proceedings of
+    the 2018 CHI Conference on Human Factors in Computing Systems
+    (CHI '18), 2018. https://doi.org/10.1145/3173574.3174220
+    Dataset: https://userinterfaces.aalto.fi/136Mkeystrokes/
+
+stride-align bundles a small number of example keyboard substitution
+matrices derived from this dataset. The dataset authors granted explicit
+permission to build and publish these derived matrices under stride-align's
+Apache-2.0 licence; only the derived matrices are distributed — the raw
+keystroke data is not. Retain the citation above as attribution. See
+docs/keyboard-matrix-external-sources.md for the provenance and the scope of
+the permission.

data/README.md

@@ -0,0 +1,107 @@
+# stride-align for Ruby
+
+`stride-align` brings the complete public R binding surface to Ruby: Unicode
+string distances and similarities, local and global alignment, batch search,
+substitution matrices, keyboard-confusion matrices, phonetics, and Dynamic
+Time Warping. The implementation is backed by the same header-only C++20 core.
+
+## Install
+
+Build and install the gem from the repository root:
+
+```sh
+bindings/ruby/build-package.sh
+gem install dist/ruby/stride-align-0.6.0.gem
+```
+
+Building requires Ruby development headers and a C++20 compiler. The resulting
+gem contains its C++ headers, BMPM rules, BLOSUM/PAM catalog, and keyboard data;
+it does not depend on Python, R, NumPy, or a binding-framework gem at runtime.
+
+## Import dispatch
+
+Requiring the gem first imports the portable `_generic` extension, asks it for
+the CPU-compatible backends packaged by the build, and then imports the best
+one. Each backend is a separate Ruby extension, matching Python's import-based
+dispatch model—unsupported instructions are never linked into the module that
+performs CPU detection.
+
+Source gems can build generic plus SSE4.1, AVX2, AVX-512 BW/VL, NEON, SVE,
+SVE2, LSX, LASX, VSX, or RVV extensions when the host compiler supports them.
+Pin a backend before `require` when benchmarking:
+
+```sh
+STRIDE_ALIGN_RUBY_BACKEND=generic ruby benchmark.rb
+STRIDE_ALIGN_RUBY_BACKEND=avx2 ruby benchmark.rb
+```
+
+An unavailable or CPU-incompatible override raises `LoadError`. Inspect the
+active dispatch with `StrideAlign.stride_backend` and
+`StrideAlign.stride_available_backends`.
+
+## Use
+
+```ruby
+require "stride_align"
+
+StrideAlign.levenshtein_score("kitten", "sitting")
+# => 3
+
+StrideAlign.jaro_winkler_similarities(
+  "Martha", ["Martha", "Marhta", "Arthur", nil]
+)
+
+StrideAlign.cdist(
+  ["Martha", "Arthur"],
+  ["Martha", "Marhta", "Arthur"],
+  scorer: StrideAlign::Scorer::JARO_WINKLER
+)
+
+path = StrideAlign.smith_waterman_path("ACCGT", "CCG")
+path.cigar          # => "3="
+path.aligned_query  # => "CCG"
+
+StrideAlign.smith_waterman_scores(
+  "HE", ["HE", "HH"], matrix: StrideAlign.blosum62
+)
+# => [13, 8]
+```
+
+Pair functions accept either scalar strings or arrays. Equal-length arrays are
+processed elementwise; a length-one side is broadcast. `nil` represents a
+missing string and produces a missing score. Batch selection returns arrays of
+hashes, `cdist` returns an array of rows, and source indices are zero-based.
+
+The Ruby API covers every export in the R package:
+
+- Levenshtein, OSA/Damerau, true Damerau-Levenshtein, Indel, Hamming, Jaro,
+  and Jaro-Winkler pair and batch forms
+- Smith-Waterman and Needleman-Wunsch scores, normalized scores, linear and
+  affine gaps, traceback objects, CIGAR output, and prepared score facades
+- top-k, best, `extract`, dense `cdist`, threshold filtering, global top-k,
+  and per-query top-k across all sixteen scorer IDs
+- LCS, n-gram similarities, Ratcliff-Obershelp, token/partial ratios, WRatio,
+  and Monge-Elkan
+- custom and NCBI-text substitution matrices, the complete BLOSUM/PAM
+  catalog, nucleotide/ASCII matrices, and keyboard-confusion helpers
+- Soundex, Metaphone, NYSIIS, Match Rating, Caverphone, Cologne,
+  Daitch-Mokotoff, Double Metaphone, and Beider-Morse
+- scalar and one-to-many Dynamic Time Warping
+
+Ruby classes and hashes replace R's S3 objects and data frames. The Python
+compatibility packages (`rapidfuzz`, `parasail`, `jellyfish`, and `thefuzz`)
+remain Python-only.
+
+## Test
+
+The test suite includes a live audit against the R `NAMESPACE`, so a newly
+exported R API cannot silently be omitted from Ruby:
+
+```sh
+bindings/ruby/build-package.sh /tmp/stride-align-ruby-dist
+GEM_HOME=/tmp/stride-align-ruby-gems \
+  gem install --local --no-document \
+  /tmp/stride-align-ruby-dist/stride-align-0.6.0.gem
+GEM_HOME=/tmp/stride-align-ruby-gems \
+  ruby bindings/ruby/test/test_stride_align.rb
+```