familia 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7903e14486c85385ad0b682c009b1f7d182e0cff24b107aa0264692529bb8dfd
-  data.tar.gz: 445219dfcd2df1cf2054b07d90e33902fc21532279730bc274629a2082a02f7f
+  metadata.gz: c322fb98599ca1596829b047f78d414a3216a4e94a61ded4c6d3a4355dd7780a
+  data.tar.gz: a0af405d479ba7547b2fe65fe17e7a9b0fc5fb04cfe8b5563ce10726187d0396
 SHA512:
-  metadata.gz: 635d35b86d7c6a85332517e3b238b8b932d4823b0cfad2f58b7c349a530de44ae02b91930c9ddac7ed538c619cea3a6f8355eeaba20ebf52358ebd45f4547067
-  data.tar.gz: d96538d6fbb486fcd92bc329acd52cba07008e40db5df059f338e060cb6dbb4789c8fe0e8e52ee69891662b1b2353eec3832032aa3ccda50848a986d06ea6a4d
+  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,97 @@ 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

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.1)
+    familia (2.11.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -29,8 +29,8 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    dry-configurable (1.4.0)
-      dry-core (~> 1.0)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
       zeitwerk (~> 2.6)
     dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
@@ -204,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

data/docs/guides/feature-encrypted-fields.md

@@ -892,7 +892,10 @@ end
 Familia.configure do |config|
   config.encryption_keys = { v1: key, v2: new_key }
   config.current_key_version = :v2
-  config.encryption_personalization = 'MyApp-2024'  # XChaCha20 only
+  config.encryption_personalization = 'MyApp-2024'  # XChaCha20 BLAKE2b domain separation (<= 16 bytes)
+  config.encryption_hkdf_salt = 'MyApp-2024'        # AES-GCM HKDF salt domain separation (any length)
+  # When rotating the AES-GCM salt, keep prior values for backward-compatible decryption:
+  # config.encryption_hkdf_salt_history = ['MyApp-2023']
 end
 
 # Validate configuration

data/docs/reference/api-technical.md

@@ -160,7 +160,8 @@ Familia.configure do |config|
     v3: ENV['NEW_KEY']       # New key for rotation
   }
   config.current_key_version = :v2
-  config.encryption_personalization = 'MyApp-2024'  # Optional (XChaCha20 only)
+  config.encryption_personalization = 'MyApp-2024'  # XChaCha20 BLAKE2b domain separation (<= 16 bytes)
+  config.encryption_hkdf_salt = 'MyApp-2024'        # AES-GCM HKDF salt domain separation (any length)
 end
 
 # Operations with encrypted fields

data/lib/familia/connection.rb

@@ -83,7 +83,7 @@ module Familia
       # Register middleware only once, globally
       register_middleware_once
 
-      Redis.new(parsed_uri.conf)
+      Redis.new(parsed_uri.conf.merge(timeout: 5))
     end
     alias connect create_dbclient # backwards compatibility
     alias isolated_dbclient create_dbclient # matches with_isolated_dbclient api

data/lib/familia/core_ext/securerandom.rb

@@ -0,0 +1,57 @@
+# lib/familia/core_ext/securerandom.rb
+#
+# frozen_string_literal: true
+
+require 'securerandom'
+
+# Polyfills for SecureRandom.uuid_v7 and SecureRandom.uuid_v4 -- Ruby 3.2 only.
+#
+# Both named methods entered Ruby's standard library in Ruby 3.3. Ruby 3.2 is
+# the oldest version familia supports (the gemspec's required_ruby_version
+# floor), and there only SecureRandom.uuid exists (it produces a v4 UUID).
+# Familia's :object_identifier feature offers both :uuid_v7 (the default, for
+# its embedded sortable millisecond timestamp) and :uuid_v4 generators, so on
+# Ruby 3.2 we supply faithful fallbacks.
+#
+# The RUBY_VERSION guard below ensures these definitions exist ONLY on Ruby
+# 3.2: on Ruby 3.3+ the block is skipped entirely and the native stdlib
+# implementations are left untouched. The caller (lib/familia/secure_identifier.rb)
+# also gates the require on RUBY_VERSION, so on 3.3+ this file is normally never
+# loaded -- the guard here is a second line of defence in case it is required
+# directly.
+if RUBY_VERSION < '3.3'
+  # UUIDv4 is exactly what the long-standing SecureRandom.uuid returns, so the
+  # fallback simply delegates to it.
+  def SecureRandom.uuid_v4
+    uuid
+  end
+
+  # UUIDv7 layout (RFC 9562, millisecond precision):
+  #
+  #   field       bits  description
+  #   unix_ts_ms   48    Unix timestamp in milliseconds, big-endian
+  #   ver           4    version, always 0b0111 (7)
+  #   rand_a       12    random
+  #   var           2    variant, always 0b10
+  #   rand_b       62    random
+  def SecureRandom.uuid_v7
+    unix_ts_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+
+    # 48-bit timestamp split across the first two groups (32 + 16 bits).
+    time_hi = (unix_ts_ms >> 16) & 0xffff_ffff
+    time_lo = unix_ts_ms & 0xffff
+
+    # Third group: version 7 in the top nibble, then 12 random bits.
+    ver_rand_a = 0x7000 | random_number(0x1000)
+
+    # Fourth group: variant 0b10 in the top two bits, then 14 random bits.
+    var_rand_b_hi = 0x8000 | random_number(0x4000)
+
+    # Fifth group: the remaining 48 random bits.
+    rand_b_lo = random_number(0x1_0000_0000_0000)
+
+    format('%<time_hi>08x-%<time_lo>04x-%<ver_rand_a>04x-%<var_rand_b_hi>04x-%<rand_b_lo>012x',
+           time_hi: time_hi, time_lo: time_lo, ver_rand_a: ver_rand_a,
+           var_rand_b_hi: var_rand_b_hi, rand_b_lo: rand_b_lo)
+  end
+end

data/lib/familia/data_type/types/sorted_set.rb

@@ -205,7 +205,8 @@ module Familia
     end
 
     def members(count = -1, opts = {})
-      count -= 1 if count.positive?
+      # NOTE: count math (positive count -> end index) is handled once by
+      # membersraw. Do not decrement here too, or members(n) returns n-1.
       elements = membersraw count, opts
       deserialize_values(*elements)
     end
@@ -218,7 +219,8 @@ module Familia
     end
 
     def revmembers(count = -1, opts = {})
-      count -= 1 if count.positive?
+      # See #members: revmembersraw already converts a positive count to the
+      # correct end index; decrementing here as well would drop one element.
       elements = revmembersraw count, opts
       deserialize_values(*elements)
     end

data/lib/familia/encryption/manager.rb

@@ -57,14 +57,35 @@ module Familia
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)
-          key = derive_key_without_increment(context, version: data.key_version, provider: provider)
 
           # Safely decode and validate sizes
           nonce = decode_and_validate(data.nonce, provider.nonce_size, 'nonce')
           ciphertext = decode_and_validate_ciphertext(data.ciphertext)
           auth_tag = decode_and_validate(data.auth_tag, provider.auth_tag_size, 'auth_tag')
 
-          plaintext = provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+          # Try each candidate HKDF salt, current first, so ciphertext written
+          # before a salt change still decrypts. Providers without salt rotation
+          # expose a single nil "salt" and are attempted exactly once. A wrong
+          # salt derives a different key and fails the authenticated decrypt
+          # cleanly, so iterating never yields a false positive. See #310 (S2).
+          salts = provider.respond_to?(:hkdf_salts) ? provider.hkdf_salts : [nil]
+          key = nil
+          plaintext = nil
+          last_error = nil
+          salts.each do |salt|
+            key = derive_key_without_increment(context, version: data.key_version, provider: provider, salt: salt)
+            begin
+              plaintext = provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+              break
+            rescue EncryptionError => e
+              last_error = e
+              plaintext = nil
+            ensure
+              Familia::Encryption.secure_wipe(key)
+            end
+          end
+          raise(last_error || EncryptionError.new('Decryption failed - invalid key or corrupted data')) if plaintext.nil?
+
           plaintext.force_encoding(data.encoding || 'UTF-8')
         rescue EncryptionError
           raise
@@ -74,6 +95,11 @@ module Familia
           raise EncryptionError, "Decryption failed: #{e.message}"
         end
       ensure
+        # Defensive backstop only. The salt-rotation loop's per-iteration `ensure`
+        # (around provider.decrypt) is the primary wipe and clears `key` on every
+        # path -- success, failure, and break -- so by here `key` is already wiped
+        # and this re-clear is a harmless no-op. It is kept so any future change to
+        # the loop structure still cannot leave a derived key unwiped (#311).
         Familia::Encryption.secure_wipe(key) if key
       end
 
@@ -101,7 +127,7 @@ module Familia
         derive_key_without_increment(context, version: version, provider: provider)
       end
 
-      def derive_key_without_increment(context, version: nil, provider: nil)
+      def derive_key_without_increment(context, version: nil, provider: nil, salt: nil)
         # Use provided provider or fall back to instance provider
         provider ||= @provider
 
@@ -113,18 +139,31 @@ module Familia
         # Request-scoped key cache (opt-in via Familia::Encryption.with_request_cache).
         # Disabled by default for maximum security (keys are not held in memory
         # longer than a single derivation). The cache key includes the algorithm
-        # so different providers never share a derived key, and the version so
-        # key rotation stays correct. On a hit we return a copy and never fetch
-        # the master key, minimising master-key exposure.
+        # so different providers never share a derived key, the version so key
+        # rotation stays correct, and the resolved salt so rotated-salt derivations
+        # never collide. On a hit we return a copy and never fetch the master key,
+        # minimising master-key exposure.
         cache = Fiber[:familia_request_cache] if Fiber[:familia_request_cache_enabled]
         if cache
-          cache_key = "#{provider.algorithm}:#{version}:#{context}"
+          # Key on the *resolved* salt, not the raw argument. When salt is nil
+          # (the encrypt path) the provider derives with hkdf_salts.first; the
+          # decrypt loop later passes that same value explicitly. Keying on the
+          # raw argument would file those two identical derivations under
+          # different keys (nil vs the resolved salt), so an encrypt followed by a
+          # decrypt of the same value in one request would derive twice instead of
+          # hitting the cache. Providers without salt rotation have no effective
+          # salt (nil), so their cache key is unchanged.
+          effective_salt = salt || (provider.respond_to?(:hkdf_salts) ? provider.hkdf_salts.first : nil)
+          cache_key = "#{provider.algorithm}:#{version}:#{effective_salt}:#{context}"
           cached = cache[cache_key]
           return cached.dup if cached
         end
 
         master_key = get_master_key(version)
-        derived = provider.derive_key(master_key, context)
+        # Only forward an explicit salt to providers that accept one (the AES-GCM
+        # salt-rotation path). The default derivation keeps the original arity so
+        # providers without a salt parameter are unaffected.
+        derived = salt.nil? ? provider.derive_key(master_key, context) : provider.derive_key(master_key, context, salt: salt)
         cache[cache_key] = derived.dup if cache
         derived
       ensure