familia 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab706939f766966f0471ff1285db5def4d14bfc9b0d428c5b0caf481595d57c2
-  data.tar.gz: 6d08805e52f5acd4a90fc117bb8a6b2e352c036daa9916c0a19079af827ddfec
+  metadata.gz: c322fb98599ca1596829b047f78d414a3216a4e94a61ded4c6d3a4355dd7780a
+  data.tar.gz: a0af405d479ba7547b2fe65fe17e7a9b0fc5fb04cfe8b5563ce10726187d0396
 SHA512:
-  metadata.gz: b328108ed4793a4c94ddd1ef1447e759bd369647fc81aca87bafe92eb1f23a71a53ca1d763726da5a631af19e520966075bb65ab40ff29d4a4563ac1a4b1e34a
-  data.tar.gz: 652d0a36301b9321eba9225ec658f3d72b0aa449bc0133b038055900475fe546fca36e2df2133680f69a938409afd6b637d0541be44dd956f51cf2cb50b205b2
+  metadata.gz: ac3aac1967a9730670b6f43f464c001d6c0acad7e599e528d94edb5b60b7939fb59dc5ef320962bfaacd1c204603e36d09647670f2511320a98c9b4fc9f0d715
+  data.tar.gz: f5f7e14e48be039962af4bcda0ac6c61248143353f773239c5b4ac0a9e9af498f64618d2f18dc48f903c7349d47e375f6e87c6ed686d7e0bbc6ebb444a4456b7

data/.github/workflows/ci.yml

@@ -23,11 +23,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.4", "3.5"]
+        ruby: ["3.2", "3.3", "3.4", "3.5", "4.0"]
         continue-on-error: [false]
-        include:
-          - ruby: "4.0"
-            continue-on-error: true
 
     services:
       redis:

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

@@ -0,0 +1,161 @@
+# Release Gem Workflow
+#
+# Automatically builds and publishes the familia gem to RubyGems.org when a
+# GitHub release is published with a semantic version tag (vMAJOR.MINOR.PATCH,
+# e.g. v2.10.1, v3.0.0).
+#
+# Follows the canonical RubyGems Trusted Publishing workflow:
+#   https://guides.rubygems.org/trusted-publishing/
+#
+# ============================================================================
+# SETUP INSTRUCTIONS (one-time)
+# ============================================================================
+#
+# This workflow uses RubyGems Trusted Publishing (OIDC). No long-lived API
+# key needs to be stored in GitHub.
+#
+# ----------------------------------------------------------------------------
+# 1. Configure the trusted publisher on RubyGems.org
+# ----------------------------------------------------------------------------
+#
+#   a. Sign in to https://rubygems.org and enable MFA on your account
+#      (required for trusted publishing).
+#
+#   b. Open the gem's trusted publisher page (works for both existing gems
+#      and the first-ever publish):
+#        Existing gem: https://rubygems.org/gems/familia/trusted_publishers
+#        First publish: https://rubygems.org/profile/oidc/pending_trusted_publishers/new
+#
+#   c. Click "Create" and fill in:
+#        Publisher type:    GitHub Actions
+#        Repository owner:  delano
+#        Repository name:   familia
+#        Workflow filename: release-gem.yml
+#        Environment:       rubygems.org   (must match `environment.name` below)
+#
+#   d. Save. RubyGems will now accept short-lived OIDC tokens issued by this
+#      workflow running in this repository.
+#
+# ----------------------------------------------------------------------------
+# 2. Configure the GitHub environment
+# ----------------------------------------------------------------------------
+#
+#   a. In GitHub: Settings -> Environments -> New environment
+#      Name: `rubygems.org`   (must match `environment.name` below)
+#
+#   b. Under "Deployment branches and tags", restrict to tags matching:
+#        v*.*.*
+#      This prevents the environment (and its OIDC token) from being used
+#      from any branch or non-release tag.
+#
+#   c. Optional but recommended: add required reviewers to gate publishes
+#      behind manual approval.
+#
+#   No GitHub secrets are required - OIDC handles authentication.
+#
+# ----------------------------------------------------------------------------
+# 3. Cutting a release
+# ----------------------------------------------------------------------------
+#
+#   a. Bump Familia::VERSION in lib/familia/version.rb (semver: MAJOR.MINOR.PATCH).
+#   b. Update CHANGELOG.rst and commit on main.
+#   c. On GitHub, draft a Release with tag `vX.Y.Z` (matching the constant)
+#      and publish it. This workflow runs automatically: it verifies the tag
+#      matches the gemspec version, builds the gem, and pushes it.
+#
+# ----------------------------------------------------------------------------
+# Fallback: API key (only if Trusted Publishing isn't an option)
+# ----------------------------------------------------------------------------
+#
+#   1. Create an API key at https://rubygems.org/profile/api_keys with scope
+#      "Push rubygem" restricted to the `familia` gem.
+#   2. Store it as a repo secret named `RUBYGEMS_API_KEY`.
+#   3. Drop the `id-token: write` permission and `environment:` block, and
+#      replace the `rubygems/release-gem` step with:
+#
+#        - name: Publish to RubyGems
+#          env:
+#            GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+#          run: gem push familia-*.gem
+#
+# ----------------------------------------------------------------------------
+# Action provenance (SHA pins)
+# ----------------------------------------------------------------------------
+#
+# All third-party actions below are pinned to a full commit SHA, per GitHub's
+# secure-use guidance for release-critical workflows. The accompanying
+# comment records the tag the SHA was resolved from so renovate/dependabot
+# can keep them current.
+#
+#   actions/checkout      - official GitHub action
+#   ruby/setup-ruby       - official Ruby org action (GitHub-verified creator)
+#   rubygems/release-gem  - official RubyGems action for trusted publishing
+#
+# ============================================================================
+
+name: Release Gem
+
+on:
+  release:
+    types: [published]
+
+# Coarse default. Each job re-declares the narrowest permissions it needs.
+permissions:
+  contents: read
+
+# Don't allow two release runs to race - one published tag, one publish.
+concurrency:
+  group: release-gem-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build and push gem
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    environment:
+      name: rubygems.org
+      url: https://rubygems.org/gems/familia
+
+    permissions:
+      contents: write   # rubygems/release-gem attaches built .gem to the GitHub release
+      id-token: write   # OIDC token for RubyGems Trusted Publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        with:
+          bundler-cache: true
+          # Pinned to 3.2, the oldest non-experimental Ruby in ci.yml's matrix
+          # and the gemspec's required_ruby_version floor, so the release build
+          # matches the minimum supported configuration that CI exercises.
+          ruby-version: "3.2"
+
+      - name: Verify release tag matches Familia::VERSION
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          case "${RELEASE_TAG}" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *)
+              echo "Release tag '${RELEASE_TAG}' is not a vMAJOR.MINOR.PATCH semver tag." >&2
+              exit 1
+              ;;
+          esac
+          tag_version="${RELEASE_TAG#v}"
+          gem_version="$(ruby -r ./lib/familia/version.rb -e 'print Familia::VERSION')"
+          if [ "${tag_version}" != "${gem_version}" ]; then
+            echo "Release tag ${RELEASE_TAG} (${tag_version}) != Familia::VERSION (${gem_version})." >&2
+            exit 1
+          fi
+          echo "Releasing familia ${gem_version} from tag ${RELEASE_TAG}"
+
+      - name: Build and push gem to RubyGems
+        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/.rubocop.yml

@@ -135,9 +135,11 @@ Style/StringLiterals:
   Enabled: true
   EnforcedStyle: single_quotes
 
+# Every lib/ file carries `# frozen_string_literal: true`; require it rather
+# than flag it (the previous `never` contradicted the entire codebase).
 Style/FrozenStringLiteralComment:
   Enabled: true
-  EnforcedStyle: never
+  EnforcedStyle: always_true
 
 Naming/MemoizedInstanceVariableName:
   Enabled: false

data/CHANGELOG.rst

@@ -7,6 +7,166 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.11.0:
+
+2.11.0 — 2026-06-22
+===================
+
+Added
+-----
+
+- Project-wide relationship introspection: ``Familia.index_descriptors``,
+  ``Familia.unique_indexes``, ``Familia.multi_indexes``, and
+  ``Familia.participation_descriptors`` aggregate index/participation metadata
+  across all loaded ``Horreum`` subclasses, returning ``Familia::IndexDescriptor``
+  objects (``coordinate``, ``each_record``, ``rebuild!``, ``stale_format?``).
+
+- ``Familia.stale_indexes`` and ``Familia.assert_indexes_current!`` detect
+  class-level unique indexes still holding pre-2.10.0 JSON-encoded identifiers and
+  fail fast (or warn) at boot. Rebuild with ``Familia.stale_indexes.each(&:rebuild!)``.
+
+- ``Familia.legacy_json_encoded?`` predicate for detecting legacy-format
+  identifiers.
+
+Changed
+-------
+
+- New ``encryption_hkdf_salt`` and ``encryption_hkdf_salt_history`` settings
+  configure the AES-GCM HKDF salt, decoupled from ``encryption_personalization``
+  (now used only by the XChaCha20/BLAKE2b providers, still capped at 16 bytes). The
+  salt has no length limit and supports rotation; no data migration is required
+  (issue #311).
+
+- ``feature :external_identifier`` accepts a callable ``secret:``, resolved lazily
+  at first use (issue #311).
+
+- The opt-in request-scoped key cache keys on the resolved salt, so an encrypt and a
+  later decrypt of the same value within one request share a single derived key
+  (issue #311).
+
+Fixed
+-----
+
+- ``SortedSet#members(n)`` / ``#revmembers(n)`` returned one fewer element than
+  requested.
+
+- Participation permission queries (``<collection>_with_permission``) now return
+  matching members instead of raising on a non-existent ``zrangebyscore`` call.
+
+- Class-level ``Model.destroy!(id)`` now removes the record's unique-index entries
+  instead of leaving them orphaned, so a stale ``find_by_<field>`` can no longer
+  resolve a deleted record.
+
+- Changing a ``unique_index`` field value and saving now removes the old value's
+  index entry in the same transaction (``multi_index`` keeps add-only semantics).
+
+Security
+--------
+
+- ``Familia::VerifiableIdentifier`` now requires ``VERIFIABLE_ID_HMAC_SECRET``
+  (issue #310, S1). The committed fallback secret, which allowed identifier
+  forgery, is removed; the secret is read lazily, so requiring the file without it
+  set does not raise.
+
+- AES-GCM keys derive from a per-deployment ``encryption_hkdf_salt`` instead of a
+  static library salt (issue #310, S2). A blank salt or personalization now raises
+  rather than silently using a weak/global value; existing ciphertext still
+  decrypts (issue #311).
+
+- External identifiers derive via SHA-256, or keyed HMAC-SHA256 with a ``secret:``,
+  instead of a Mersenne-Twister PRNG seeded from a truncated digest (issue #310, S3).
+
+- ``ParticipationMembership#target_instance`` resolves class names through the
+  ``Familia.resolve_class`` allowlist instead of ``Object.const_get`` (issue #310, S4).
+
+- The request-scoped key cache is wiped on entry to ``with_request_cache`` as well
+  as on exit, so a reused fiber cannot inherit another request's keys (issue #310, S6).
+
+Documentation
+-------------
+
+- Documented the relationship introspection API and stale-index boot guard across
+  the relationships guide and methods reference. Renamed
+  ``docs/migrating/v2.10.0.md`` to ``docs/migrating/v2.10.md``.
+
+- Clarified that the migration ``Script`` SHA-1 is the Redis ``EVALSHA`` identity,
+  not a security checksum (issue #310, S5).
+
+AI Assistance
+-------------
+
+- The 2.11.0 changes, their tryouts, and this changelog were drafted with AI
+  assistance.
+
+.. _changelog-2.10.1:
+
+2.10.1 — 2026-06-06
+===================
+
+Added
+-----
+
+- ``record_class:`` option for collection DataTypes (``list``/``set``/
+  ``sorted_set``/``hashkey``). This loading-only hint tells ``each_record`` which
+  class to hydrate via ``load_multi`` without changing how the collection
+  serializes or deserializes reads. Use this when you want ``each_record`` lookup
+  behavior but no changes to read behavior. Issue #297
+
+- ``Familia.atomic_write(*instances)`` persists multiple Horreum instances in a
+  single ``MULTI/EXEC``. Includes an optional ``watch_keys:``/``pre_check:``
+  variant for race-safe, write-once semantics. All participating instances must
+  resolve to the same logical database (raising ``Familia::CrossDatabaseError``
+  otherwise) and must share a hash slot on Redis Cluster. #296
+
+Changed
+-------
+
+- ``participates_in`` / ``class_participates_in`` collections now default to
+  using ``record_class:``. This change requires **no data migration and causes no
+  behavior changes**: existing collections already stored raw identifiers, and
+  read operations (``members``, ``to_a``, ``member?``, ``score``) behave exactly
+  as before. The only difference is that ``each_record`` is now supported. Pre-
+  declared collections are left untouched. Issue #297
+
+Fixed
+-----
+
+- Enabled ``each_record`` on ``participates_in`` and ``class_participates_in``
+  collections by automatically declaring them with ``record_class: <participant
+  class>``. This resolves ``Familia::Problem`` exceptions and loads participant
+  records via ``load_multi`` across all collection types. Issue #297
+
+- Suppressed per-member ``[deserialize] Raw fallback`` warning storm when
+  iterating ``record_class`` collections with non-JSON identifiers (such as UUIDs
+  or prefixed IDs). These expected raw values are now logged at the debug level
+  instead of warnings. Issue #297
+
+- Resolved a connection-pooling bug where the ``WATCH``-based optimistic lock
+  in ``atomic_write(watch_keys:)``, ``save_if_not_exists!``, and ``create!`` was
+  silent/inert. The ``WATCH`` and ``MULTI/EXEC`` commands are now driven through
+  the same connection, ensuring concurrent modifications correctly abort and raise
+  as
+  documented. #296
+
+AI Assistance
+-------------
+
+- AI diagnosed the participation iteration bug and identified that ``reference: true``
+  introduced unintended read-behavior changes. Designed and implemented the
+  ``record_class:`` option to decouple ``each_record`` lookup from read deserialization,
+  suppressed a resulting per-member deserialize warning storm, kept intentional
+  raw-string semantics on ``instances`` and ``unique_index``, updated stale
+  flowcharts in ``datatype-collections.md``, and added regression coverage. Issue #297
+
+- Root-caused and fixed a split-connection defect with Claude Code: implemented a
+  single-connection ``execute_watched_transaction`` primitive (avoiding fiber-pinning
+  that degrades atomic commands) and added real concurrent-modification tests to
+  replace simulated aborts. #296
+
+- Designed and built multi-model atomic writes on top of the new ``WATCH`` primitive:
+  implemented the same-database guard, orchestration logic, and a test suite covering
+  two-model commits, rollback on error, cross-database rejection, and race conditions. #296
+
 .. _changelog-2.10.0:
 
 2.10.0 — 2026-06-04

data/Gemfile

@@ -15,6 +15,12 @@ end
 group :development, :test do
   gem 'benchmark', '~> 0.4', require: false
   gem 'debug', require: false
+  # reek pulls in dry-configurable transitively (via dry-schema). Its 1.4.0
+  # release bumped the minimum Ruby to 3.3, which breaks `bundle install` on
+  # Ruby 3.2 (our gemspec's required_ruby_version floor). 1.4.0 only adds
+  # Config#to_data, which we don't use (we don't use Dry::Configurable at all),
+  # so cap below 1.4 to keep the dev bundle installable on Ruby 3.2.
+  gem 'dry-configurable', '>= 1.3', '< 1.5', require: false
   gem 'irb', '~> 1.15.2', require: false
   gem 'json_schemer', '~> 2.0', require: false
   gem 'rake', '~> 13.0', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.10.0)
+    familia (2.11.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -15,59 +15,59 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.9)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
-    bigdecimal (3.3.1)
+    bigdecimal (4.1.2)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     csv (3.3.5)
-    date (3.5.0)
-    debug (1.11.0)
+    date (3.5.1)
+    debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
     dry-configurable (1.3.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-core (1.1.0)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.2.0)
+    dry-inflector (1.3.1)
     dry-initializer (3.2.0)
     dry-logic (1.6.0)
       bigdecimal
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-schema (1.14.1)
+    dry-schema (1.16.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
       dry-core (~> 1.1)
       dry-initializer (~> 3.2)
-      dry-logic (~> 1.5)
-      dry-types (~> 1.8)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-types (1.8.3)
-      bigdecimal (~> 3.0)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
-    erb (5.1.3)
-    ffi (1.17.2)
-    ffi (1.17.2-arm64-darwin)
+    erb (6.0.4)
+    ffi (1.17.4)
+    ffi (1.17.4-arm64-darwin)
     hana (1.3.7)
-    io-console (0.8.1)
+    io-console (0.8.2)
     irb (1.15.3)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.2.1)
+    json (2.19.8)
     json-schema (6.2.0)
       addressable (~> 2.8)
       bigdecimal (>= 3.1, < 5)
@@ -79,15 +79,15 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    mcp (0.8.0)
+    mcp (0.18.0)
       json-schema (>= 4.1)
     minitest (5.27.0)
-    oj (3.16.13)
+    oj (3.17.3)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    parallel (1.28.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -96,25 +96,27 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    psych (5.2.6)
+    psych (5.4.0)
       date
       stringio
     public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     rbnacl (7.1.2)
       ffi (~> 1)
-    rbs (3.9.5)
+    rbs (4.0.2)
       logger
-    rdoc (6.15.1)
+      prism (>= 1.6.0)
+      tsort
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
     redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.26.2)
+    redis-client (0.29.0)
       connection_pool
     reek (6.5.0)
       dry-schema (~> 1.13)
@@ -122,10 +124,10 @@ GEM
       parser (~> 3.3.0)
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
-    regexp_parser (2.11.3)
-    reline (0.6.2)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rexml (3.4.1)
+    rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -135,10 +137,10 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
+    rspec-support (3.13.7)
     rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -151,28 +153,29 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-performance (1.25.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-thread_safety (0.7.3)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.1)
+    ruby-lsp (0.26.9)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
-    ruby-prof (1.7.2)
+    ruby-prof (2.0.4)
       base64
+      ostruct
     ruby-progressbar (1.13.0)
     simpleidn (0.2.3)
-    stackprof (0.2.27)
+    stackprof (0.2.28)
     stringio (3.1.9)
-    timecop (0.9.10)
+    timecop (0.9.11)
     tryouts (3.7.1)
       concurrent-ruby (~> 1.0, < 2)
       irb
@@ -190,8 +193,8 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri-valkey (1.4.0)
-    yard (0.9.37)
-    zeitwerk (2.7.3)
+    yard (0.9.44)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-24
@@ -201,6 +204,7 @@ DEPENDENCIES
   benchmark (~> 0.4)
   concurrent-ruby (~> 1.3.6)
   debug
+  dry-configurable (>= 1.3, < 1.5)
   familia!
   irb (~> 1.15.2)
   json_schemer (~> 2.0)

data/README.md

@@ -475,6 +475,32 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### Running the Tests
+
+Familia's test suite uses the [Tryouts](https://github.com/delano/tryouts)
+framework. The simplest way to run it:
+
+```bash
+bundle install
+bundle exec rake test   # full suite, with a guaranteed UTF-8 locale
+```
+
+`rake test` runs the suite in a child process with a UTF-8 locale, which the
+suite needs: some tryouts contain UTF-8 source (e.g. Unicode cases) and assert on
+string encodings, so when no locale is set Ruby falls back to
+`Encoding.default_external = US-ASCII`, the runner aborts with `invalid byte
+sequence in US-ASCII`, and encoding specs fail spuriously. (A locale you already
+have is kept; most shells and CI provide a UTF-8 one.)
+
+To invoke the runner directly — e.g. for a single file — ensure your shell has a
+UTF-8 locale first:
+
+```bash
+export LANG=C.UTF-8                        # or en_US.UTF-8; only needed if unset
+bundle exec try -vf                        # full suite
+bundle exec try try/path/to/foo_try.rb     # a single file
+```
+
 ### PR Compliance Checks
 
 Pull requests are automatically reviewed by [Qodo Merge](https://qodo.ai) with compliance checks for:

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Run the Tryouts test suite with a guaranteed UTF-8 locale.
+#
+# The suite's source and specs are UTF-8. The tryouts runner reads each test file
+# with File.read, which honours Encoding.default_external; when the caller's
+# locale is unset that defaults to US-ASCII and the run aborts on non-ASCII source
+# ("invalid byte sequence in US-ASCII"), with encoding-sensitive specs failing
+# spuriously. Running the suite in a child process with a UTF-8 locale makes it
+# work regardless of the caller's environment. A caller that already has a UTF-8
+# locale (CI, most shells) keeps it -- the defaults below only fill in when unset.
+desc 'Run the Tryouts test suite (ensures a UTF-8 locale)'
+task :test do
+  ENV['LANG'] ||= 'C.UTF-8'
+  ENV['LC_ALL'] ||= 'C.UTF-8'
+  sh 'bundle exec try -vf'
+end
+
+task default: :test