familia 2.11.2 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b0eed1c3632c68c8c4c91617830f0b15a10907da5c7af0bbc14b9cf67a5336
-  data.tar.gz: 4a123b805e826b8ede218675c16781f428fab6c3194968c5a3840323b949b28e
+  metadata.gz: 889cca334ccb762d4a5cb4fa64a400c3df8727a8219bf19129b6699bf4056069
+  data.tar.gz: c2e315e109a866d8b1943be21fb7cf215c3db767e801138fa4097229e98c5dcb
 SHA512:
-  metadata.gz: 6c245370d354eaa0d8af0b0994cd44ea10f8dec3b260c9750d3cceb66563c51ee8f4390062429c8aced6cd578d919c7a806a0eef2e5be0f9d90bbc00dcf87b06
-  data.tar.gz: a824edcd1af5d3535168600d90a3e189b0203c884fe17c7382cafb22ebc6c19a36c68011a468e9dd8b16fed386b902eac16709625004f73b7f4085b0ae0a601e
+  metadata.gz: d7e65ba3aa75c03d7c0328a34f7c6ad13f9c840efc2aefbe0c06bba678a41ac27704928962b5d9a3be769bd7df186bf1bc56647ee80aa173a1000ff6404d599e
+  data.tar.gz: e34f5200cac7681ff999b31cf842d326e49882ffd823602d8d677bec95b6376edca29f967f9da494eb431f9a857bc81758519dd4fd5969714ed478bd085cdf54

data/.github/workflows/claude-code-review.yml

@@ -48,7 +48,7 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@833fb0f8c9f6686b33d963a8bae0a94f4936ab2a # v1.0.211
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
@@ -56,13 +56,24 @@ jobs:
           # runs) -> the CLAUDE_MODEL repo variable -> this built-in default.
           # Pinning a current id avoids the action's frozen default, which 404s
           # ("model: claude-sonnet-4-20250514"). Fall back to Sonnet on overload.
-          model: "${{ inputs.model || vars.CLAUDE_MODEL || 'claude-opus-4-6' }}"
-          fallback_model: "${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}"
+          # v1 of the action dropped the model/fallback_model/allowed_tools
+          # inputs; they are CLI flags passed via claude_args now (see
+          # docs/migration-guide.md and docs/usage.md in the action repo).
+          claude_args: |
+            --model ${{ inputs.model || vars.CLAUDE_MODEL || 'claude-opus-4-6' }}
+            --fallback-model ${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}
+            --allowedTools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"
 
-          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # A bare `prompt` puts the action in agent mode, which creates no tracking
+          # comment, so use_sticky_comment alone did nothing and every push got a
+          # fresh `gh pr comment`. track_progress forces tag mode: the action owns
+          # one tracking comment, use_sticky_comment finds and reuses it on later
+          # pushes, and Claude writes the review into it via the action's built-in
+          # comment tool. The prompt becomes <custom_instructions> in tag mode.
+          track_progress: true
           use_sticky_comment: true
 
-          direct_prompt: |
+          prompt: |
             Please review this pull request and provide feedback on:
             - Code quality and best practices
             - Potential bugs or issues
@@ -71,9 +82,3 @@ jobs:
             - Test coverage
 
             Use the repository's AGENTS.md for guidance on style and conventions. Be constructive and helpful in your feedback.
-
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
-          allowed_tools: "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"

data/.github/workflows/claude.yml

@@ -32,47 +32,31 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@833fb0f8c9f6686b33d963a8bae0a94f4936ab2a # v1.0.211
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
           # Primary model: set the CLAUDE_MODEL repo variable to override without
           # editing this file. Pinning a current id avoids the action's frozen
           # default, which 404s ("model: claude-sonnet-4-20250514"). Fall back to
-          # Sonnet if the primary is unavailable or overloaded.
-          model: "${{ vars.CLAUDE_MODEL || 'claude-opus-4-6' }}"
-          fallback_model: "${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}"
+          # Sonnet if the primary is unavailable or overloaded. v1 of the action
+          # dropped the model/fallback_model inputs; models are CLI flags passed
+          # via claude_args (see docs/migration-guide.md in the action repo).
+          # Other supported flags (--allowedTools, --max-turns, ...):
+          # https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          claude_args: |
+            --model ${{ vars.CLAUDE_MODEL || 'claude-opus-4-6' }}
+            --fallback-model ${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}
 
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
 
-          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
-          # model: "claude-opus-4-20250514"
-
           # Optional: Customize the trigger phrase (default: @claude)
           # trigger_phrase: "/claude"
 
           # Optional: Trigger when specific user is assigned to an issue
           # assignee_trigger: "claude-bot"
 
-          # Optional: Allow Claude to run specific commands
-          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
-
-          # Optional: Add custom instructions for Claude to customize its behavior for your project
-          # custom_instructions: |
-          #   Follow our coding standards
-          #   Ensure all new code has tests
-          #   Use TypeScript for new files
-
-          # Optional: Custom environment variables for Claude
-          # claude_env: |
-          #   NODE_ENV: test
-
           # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
           # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
-          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'

data/.github/workflows/code-smells.yml

@@ -74,7 +74,7 @@ jobs:
         continue-on-error: true
 
       - name: Upload Reek report as artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: reek-report

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

@@ -158,4 +158,4 @@ jobs:
           echo "Releasing familia ${gem_version} from tag ${RELEASE_TAG}"
 
       - name: Build and push gem to RubyGems
-        uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0
+        uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

data/.github/workflows/yardoc.yml

@@ -75,7 +75,7 @@ jobs:
           echo "::endgroup::"
 
       - name: Setup GitHub Pages configuration
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v6
 
       - name: Upload documentation artifact
         uses: actions/upload-pages-artifact@v5

data/.gitignore

@@ -18,14 +18,21 @@
 dump.rdb
 appendonlydir
 data
+doc
 log
 tmp
 vendor
 *.gem
 public/
 
-# Ignore WIP or temp dev files with uppercase names
-[A-Z]*.md
+# Ignore WIP or temp dev files with uppercase names, at the repo root only.
+# Anchored because core.ignoreCase is true on macOS/Windows checkouts: git
+# casefolds the [A-Z] class, so an unanchored pattern silently swallowed every
+# new lowercase .md anywhere in the tree (docs/*.md included).
+/[A-Z]*.md
+
+# Unredacted security notes stay local; publish redacted summaries only
+*.private.md
 
 # Exclusions
 !README.md

data/.talismanrc

@@ -12,4 +12,17 @@ fileignoreconfig:
     checksum: 10c94f802b2fa3a39fa33bf7dc34dac2ecaa2dd453ff97a19313f96a32fadeff
   - filename: examples/encrypted_fields.rb
     checksum: d1bd77f85d951d367e1c2bfd066a1d68d5f486346ee479121a3d5dcc2560bf52
+  # SHA-pinned actions read as "hex encoded text" to talisman; the pin is the point.
+  - filename: .github/workflows/claude.yml
+    checksum: 3a7acf45fb032644c40bad629ba6c0271689a1233ef6893aba3caf03f6327b50
+  - filename: .github/workflows/claude-code-review.yml
+    checksum: 698ebf39c1c49a72212cd8d9fd0117aaf15079dcb9f1e22c94dc7a871dd7952e
+  - filename: docs/adr/0002-watch-for-private-keys-lua-for-shared-keys.md
+    checksum: 0ace51636017e6d0a5b489dc14fc6b684cabd64c6bb706a710f869d31ea5f4f0
+  - filename: .github/workflows/ruby-lint.yml
+    checksum: b8009bc29189d214229c88f1cf7960c651404e659be74436a79efb130177ff58
+  - filename: .github/workflows/ci.yml
+    checksum: 0b356104ddf0b192d29b25669c61b17c863eca5de0e36822ea4d7b353d065016
+  - filename: .github/workflows/release-gem.yml
+    checksum: 1ad4786c939da966b79275105f60005c7a3214f424d5701d8118a7175b087112
 version: ""

data/AGENTS.md

@@ -11,6 +11,8 @@ Guidance for AI coding agents working in this repository.
 
 ### Testing (Tryouts v3)
 
+Use `valkey-server try/valkey.conf` to start the test redis.
+
 Each file has optional setup, testcases, and optional teardown. A testcase is a
 `##` description line, Ruby code, then one or more expectation comments
 (`#=>`, `#==>`, `#=:>`, `#=!>`, ...). The last expression is the result.
@@ -21,6 +23,13 @@ Run with `--agent` for token-efficient output (`--agent-focus summary|first-fail
 See `bundle exec try --help` for the full CLI, framework integration (`--rspec`,
 `--minitest`), and debugging flags.
 
+The whole suite runs in one process, so anything a file sets globally outlives
+it. For encryption keys use the scoped helpers rather than assigning
+`Familia.config.encryption_keys` directly: `set_test_encryption_keys(keys,
+current_version:)` in setup with `clear_test_encryption_keys` in teardown, or
+`with_test_encryption_keys(keys, current_version:) { ... }` for a single
+testcase. See @try/support/helpers/encryption_config.rb.
+
 ### Changelog
 
 Add a changelog fragment (RST) with each user-facing change. See @changelog.d/README.md
@@ -196,3 +205,22 @@ last-write timestamps (ZADD score), not a registry.
 DataType instances are frozen (immutable). Configure module-level settings once
 at startup, before threads spawn. `Familia.start_monitoring!` tracks contention.
 Tests and contention patterns live in `try/thread_safety/`.
+
+## Project claims and source authority
+
+### Attribution
+
+Do not infer project terminology or guarantees from repetition. Before attributing a claim to the project, locate an authoritative primary source and provide its exact wording. Treat delivery notes, commit messages, agent output, and documents created or modified during the current task as leads, not evidence. If the wording is absent, call it an interpretation or proposal. Never place paraphrases in quotation marks.
+
+### Authoritative sources
+
+Authoritative sources must be identified explicitly; repository presence alone does not confer authority. Accepted specifications and ADRs may establish project claims only within their stated scope. Delivery notes, commit messages, issue discussions, summaries, and agent-authored text are non-authoritative unless an authoritative source incorporates them explicitly.
+
+### Normative claims
+
+For normative claims concerning security, privacy, compatibility, persistence, or data loss:
+
+1. Cite the authoritative source and its exact wording.
+2. Distinguish quotations, paraphrases, interpretations, and proposals.
+3. Do not use material created or modified during the current task to validate that task’s claims.
+4. If no authoritative wording exists, report the claim as unsupported.

data/CHANGELOG.rst

@@ -7,6 +7,77 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.12.0:
+
+2.12.0 — 2026-08-03
+===================
+
+Added
+-----
+
+- Added ``Familia::HashKey#claim_field`` and ``#release_field`` for single-field compare-and-set and compare-and-delete. They raise ``Familia::OperationModeError`` in pipelines and transactions.
+- Added generated ``claim_unique_<index>!`` and ``release_unique_<index>!`` methods for class-level unique indexes. #353
+- Added ``Familia::MultiResult#aborted?`` and ``#inspect`` for transaction outcome handling and logging.
+- Added ``max_length:`` to ``ListKey``, ``SortedSet``, ``participates_in``, and ``class_participates_in``. ``ListKey`` retains the N elements nearest the end written to, while ``SortedSet`` retains its N highest-scoring members. Existing oversized collections are trimmed on the next capped write; call ``enforce_max_length!`` or run ``Familia::Features::Housekeeping::EnforceCollectionCaps`` to enforce a new cap immediately. ``DataType#max_length`` exposes the configured cap. #351
+- Added ``encryption_personalization_history`` to support XChaCha20-Poly1305 personalization rotation. See ``docs/guides/encryption.md``. #333
+- Added ``limit:``, ``offset:``, and ``each_<collection>_with_permission`` for memory-bounded permission-filtered collection queries. #309
+- Added the ``dirty_write_warnings:`` collection option to override a parent class's diagnostic mode. #282
+
+Changed
+-------
+
+- Class-level unique-index updates inside transactions now require a prior claim and raise ``Familia::OperationModeError`` otherwise. #353
+- Class-level index removal and destruction no longer delete entries owned by other records. #353
+- ``Familia::MultiResult#results`` now returns an empty ``Array`` on transaction aborts, ``#to_h`` includes ``:aborted``, and result objects are read-only.
+- ``SortedSet#increment`` now applies the dirty-write guard. #351
+- XChaCha20 decryption and request caching now support personalization rotation candidates. #333
+- ``multi_field_fast_write`` rejects class-indexed fields, and ``field!`` rejects class-indexed fields in transactions or pipelines and unsaved records. #308
+- Registered instance-scoped index memberships refresh on ``save``. ``atomic_write`` callers must update those indexes explicitly. #282
+- Saving a record with an instance-scoped unique-index collision now raises ``Familia::RecordExistsError`` without replacing the existing entry. #282
+- Direct instance- and class-scoped index mutations now require a persisted record. #282
+- Instance-scoped index mutations now reject scopes without an identifier or a Symbol/String ``identifier_field``. #282
+
+Removed
+-------
+
+- Removed unused ``csv`` and ``stringio`` runtime dependencies from the gemspec. #354
+
+Fixed
+-----
+
+- Fixed ``decrby`` and ``decr`` (and aliases) to decrement hash fields correctly and validate integer amounts.
+- Fixed ``encryption_info`` to report correct provider details and key sizes.
+- Fixed unique-index save races and ownership-checked removals, preventing collisions from replacing or deleting another record's entry. #353
+- Fixed claim leaks when unpersisted records call ``update_in_<scope>_<index_name>``. #370
+- Fixed ``Familia::MultiResult`` handling of WATCH-aborted transactions. #355
+- Fixed XChaCha20 key derivation to preserve caller-provided context values. #356
+- Fixed ``SortedSet#increment`` in transactions and pipelines to return the queued result. #351
+- ``:maxlength`` now warns at definition time; rename it to ``max_length:`` to opt in to collection capping. #351
+- Fixed ``Lock#acquire`` with a TTL to acquire and set the expiration atomically. #347
+- Fixed ``DatabaseLogger.sample_rate`` validation and ``SingleUseRedactedString`` loading through ``require 'familia'``. #347
+- Fixed memory use in ``<collection>_with_permission`` queries by processing results in bounded batches. #309
+- Fixed invalid permission-symbol lookups to fail rather than silently misconfigure permission queries.
+- Fixed partial and fast writes to maintain class-level unique indexes atomically. #308
+- Fixed instance-scoped index cleanup after indexed values change, scope classes share an index name, or identifiers are reused. #282, #365
+
+Security
+--------
+
+- ``multi_field_update`` and ``multi_field_fast_write`` now reject plaintext writes to encrypted fields and writes to transient fields.
+- Pinned GitHub Workflows holding ``CLAUDE_CODE_OAUTH_TOKEN`` to immutable release commit SHAs.
+- Encryption now fails closed when ``encryption_hkdf_salt`` is blank, including with a warm request cache. Configure a non-blank salt as described in ``docs/guides/encryption.md``. #380
+
+Documentation
+-------------
+
+- Corrected permission-management, relationship, and connection-provider examples.
+- Documented ``<collection>_with_permission`` flags, permission categories, exclusive tiers, and encryption personalization rotation.
+
+AI Assistance
+-------------
+
+- Core fixes, tryout coverage (120+ test cases), and documentation updates implemented with AI assistance.
+
 .. _changelog-2.11.2:
 
 2.11.2 — 2026-07-05
@@ -16,25 +87,14 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 Changed
 -------
 
-- ``to_h_for_storage`` omits nil fields; every write path removes a field that has
-  become nil. ``save``/``commit_fields`` do a full overwrite (the stored hash
-  matches the in-memory object, so a field nil in memory is deleted);
-  ``save_fields``/``multi_field_update``/``multi_field_fast_write`` delete a named
-  field passed as nil. ``to_h`` still returns every declared field, nils included.
+- Nil-valued fields are now omitted from storage. Setting a field to ``nil`` removes it on every write path, while ``to_h`` continues to include declared fields with nil values.
 
-- Claim caveat: a full ``save``/``commit_fields`` of a stale copy clears a field
-  another writer claimed via ``HSETNX``. To claim and update without disturbing
-  it, use the targeted writers or ``refresh!`` first.
+- Refresh stale instances before a full ``save`` or ``commit_fields`` when another writer may have claimed a field; use targeted writers to update only named fields.
 
 Fixed
 -----
 
-- Nil-valued fields are no longer stored as the JSON string ``"null"``. Because a
-  hash has no native NULL, this left declared fields perpetually present, breaking
-  ``HSETNX``/``HEXISTS`` atomic-claim patterns and wasting memory. Nil fields are
-  now omitted, and clearing a field to nil removes it from storage (``HDEL``), so
-  absence again means "no value". No migration required: stale ``"null"`` values
-  are cleaned up on the next save and already decode back to ``nil`` on read.
+- Fixed nil-valued fields being stored as the JSON string ``"null"``. No migration is required; existing values are cleaned up on the next save.
 
 AI Assistance
 -------------
@@ -49,96 +109,28 @@ AI Assistance
 Added
 -----
 
-- ``encrypted_field`` now honors a per-field ``algorithm:`` option, pinning that
-  field's write algorithm to a specific registered provider (``'aes-256-gcm'`` or
-  ``'xchacha20poly1305'``) independent of the registry's default-provider
-  priority. The option was previously documented but silently ignored, so writes
-  always used the default provider. Decryption stays envelope-driven, so a pin can
-  be added, changed, or removed without breaking ciphertext already at rest, and
-  ``re_encrypt_fields!`` re-encrypts under the pin rather than the default. This is
-  the supported lever for a reader-before-writer format migration: deploy
-  ``rbnacl`` fleet-wide so every node can *read* XChaCha20-Poly1305 while keeping
-  *writes* pinned to AES-256-GCM until all readers are confirmed capable, then drop
-  the pin. Issue #334
+- ``encrypted_field`` now honors its per-field ``algorithm:`` option for new writes, including ``re_encrypt_fields!``. Existing ciphertext remains decryptable when the pin changes or is removed. See ``docs/guides/feature-encrypted-fields.md`` for rollout guidance. #334
 
 Changed
 -------
 
-- ``Familia::Encryption::Registry.get`` now distinguishes an unknown algorithm
-  from a *known* algorithm whose provider is not available on the current node.
-  Because ``Registry.register`` only stores providers whose runtime dependency is
-  present, pinning ``encrypted_field ..., algorithm: 'xchacha20poly1305'`` on a
-  node without ``rbnacl``/libsodium previously raised the misleading
-  ``"Unsupported algorithm: xchacha20poly1305"`` -- pointing an operator at a typo
-  when the real fix is a missing dependency. It now names the provider, explains
-  the dependency is missing, and (because ``get`` runs on both the encrypt and
-  decrypt paths) states that installing the dependency is what enables reading
-  *and* writing the algorithm, framing an algorithm pin as a write-time
-  workaround that cannot decrypt existing ciphertext. Each provider declares its
-  own dependency via a new ``Provider.dependency_hint`` class method (nil for
-  always-available providers like OpenSSL AES-256-GCM), so the generic error path
-  names the correct library as providers are added rather than hardcoding any one
-  of them. The set of registerable providers is centralized in
-  ``Registry.known_providers``, the single source of truth shared by ``setup!``
-  and ``get``. Error-message and internal-refactor only; the resolution of every
-  available algorithm is unchanged. Issue #334
+- Encryption errors now distinguish unsupported algorithms from known algorithms whose provider dependency is unavailable. #334
 
 Fixed
 -----
 
-- ``Familia::DataType#exists?`` no longer returns ``true`` for a deleted or
-  never-created scalar key (``StringKey``, ``Counter``, ``Lock``,
-  ``JsonStringKey``). The check was ``dbclient.exists(dbkey) && !size.zero?``,
-  but ``EXISTS`` returns an Integer count and ``0`` is truthy in Ruby, so the
-  guard never short-circuited on a missing key -- existence was decided
-  entirely by the size check. ``exists?`` now uses a boolean-coerced ``EXISTS``
-  count directly. Issue #331
-
-- Relatedly, ``StringKey#size``/``#length``/``#empty?`` (and ``Lock``'s) no
-  longer reflect the never-nil ``#to_s`` fallback. ``#char_count`` derived from
-  ``#to_s.size``, and ``#to_s`` intentionally returns ``Familia::Base``'s
-  documented "never nil" inspect-string when the value is absent -- so
-  ``#size`` was non-zero (and ``#empty?`` false) for a missing key.
-  ``#char_count`` now reads ``#value`` directly; ``#to_s`` is left unchanged.
-  Issue #331
-
-- ``encrypted_fields_status`` now reports each field's real algorithm for a live
-  encrypted value (e.g. ``{ encrypted: true, algorithm: "aes-256-gcm", cleared:
-  false }``), honoring any per-field pin. Previously it returned ``{ encrypted:
-  false, value: "[CONCEALED]" }`` for every encrypted field, because
-  ``ConcealedString`` had no ``concealed?`` predicate for the status check to
-  match -- so the algorithm shown in the method's docstring and the guides was
-  never actually produced. ``ConcealedString`` gains ``#concealed?`` and
-  ``#algorithm`` readers (the latter reads the stored envelope). Issue #334
+- Fixed ``Familia::DataType#exists?`` and missing ``StringKey`` and ``Lock`` size and emptiness checks. #331
+
+- Fixed ``encrypted_fields_status`` to report the stored algorithm for encrypted fields, including per-field algorithm pins. #334
 
 Documentation
 -------------
 
-- Added an executable, multi-phase proof (``examples/encryption_upgrade_proof/``)
-  demonstrating that installing ``rbnacl`` safely flips new writes to
-  XChaCha20-Poly1305 while every existing AES-256-GCM envelope — including
-  ciphertext written by the released 2.10.1 gem, under the pre-#310 static HKDF
-  salt, and under a retired master key version — keeps decrypting. Also pins,
-  as deliberately-passing checks, two operational hazards: the XChaCha
-  ``encryption_personalization`` cannot be rotated (no history/fallback like
-  ``encryption_hkdf_salt_history``), and once any XChaCha envelope exists,
-  every node that may read it needs libsodium installed. PR #330
-
-- The encrypted-fields guide previously showed a ``provider: :aes_gcm`` field
-  option that was never implemented; those examples now use the real
-  ``algorithm: 'aes-256-gcm'`` form, and the ``Familia::Encryption`` facade
-  docstring documents the shipped behavior instead of a hypothetical
-  implementation sketch. The ``encrypted_fields_status`` output examples across
-  the guides and the overview were corrected to match what the method now
-  returns. Issue #334
-
-- Added a memory-audit investigation (``docs/investigation/memory-audit.md``)
-  diagnosing #309's ``<collection>_with_permission`` O(N) query as a transient,
-  GC-reclaimable spike rather than a per-process leak, and auditing the rest of
-  ``lib/`` for per-process growth (concluding Familia has no unconditional leak).
-  Ships two executable proofs in ``try/investigation/`` — a pure-Ruby
-  ``process_memory_leak_proof.rb`` and a live-Redis ``memory_leak_proof.rb``.
-  Diagnosis only; no runtime behaviour is changed by the investigation. Issue #309
+- Added ``examples/encryption_upgrade_proof/`` to demonstrate encrypted-field algorithm upgrades. PR #330
+
+- Corrected encrypted-field option and status examples to match supported behavior. #334
+
+- Documented memory characteristics of ``<collection>_with_permission`` queries in ``docs/investigation/memory-audit.md``. #309
 
 AI Assistance
 -------------

data/Gemfile

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem 'concurrent-ruby', '~> 1.3.7', require: false
+  gem 'concurrent-ruby', '~> 1.3.8', require: false
   gem 'ruby-prof'
   gem 'stackprof'
   gem 'timecop', require: false
@@ -26,7 +26,7 @@ group :development, :test do
   gem 'rake', '~> 13.0', require: false
   gem 'redcarpet', require: false
   gem 'reek', require: false
-  gem 'rubocop', '~> 1.88.0', require: false
+  gem 'rubocop', '~> 1.90.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'ruby-lsp', require: false

data/Gemfile.lock

@@ -1,15 +1,13 @@
 PATH
   remote: .
   specs:
-    familia (2.11.2)
+    familia (2.13.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
-      csv (~> 3.3)
       json_schemer (~> 2.0)
       logger (~> 1.7)
       oj (~> 3.16)
       redis (>= 5.0, < 6.0)
-      stringio (>= 3.1.1, < 3.3.0)
       uri-valkey (~> 1.4)
 
 GEM
@@ -19,9 +17,8 @@ GEM
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (4.1.2)
-    concurrent-ruby (1.3.7)
+    concurrent-ruby (1.3.8)
     connection_pool (3.0.2)
-    csv (3.3.5)
     date (3.5.1)
     debug (1.11.1)
       irb (~> 1.10)
@@ -66,22 +63,22 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.9)
+    json (2.21.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       simpleidn (~> 0.2)
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.27.0)
-    oj (3.17.3)
+    oj (3.17.6)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
     parallel (1.28.0)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -98,7 +95,7 @@ GEM
     rake (13.4.2)
     rbnacl (7.1.2)
       ffi (~> 1)
-    rbs (4.0.2)
+    rbs (4.1.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -134,8 +131,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.0)
-      json (~> 2.3)
+    rubocop (1.90.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -145,18 +142,18 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-performance (1.26.1)
+    rubocop-performance (1.27.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.75.0, < 2.0)
+      rubocop (>= 1.89.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.9)
+    ruby-lsp (0.26.11)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -185,7 +182,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri-valkey (1.4.0)
-    yard (0.9.44)
+    yard (0.9.45)
     zeitwerk (2.8.2)
 
 PLATFORMS
@@ -194,7 +191,7 @@ PLATFORMS
 
 DEPENDENCIES
   benchmark (~> 0.4)
-  concurrent-ruby (~> 1.3.7)
+  concurrent-ruby (~> 1.3.8)
   debug
   dry-configurable (>= 1.3, < 1.5)
   familia!
@@ -204,7 +201,7 @@ DEPENDENCIES
   rbnacl (~> 7.1, >= 7.1.1)
   redcarpet
   reek
-  rubocop (~> 1.88.0)
+  rubocop (~> 1.90.0)
   rubocop-performance
   rubocop-thread_safety
   ruby-lsp

data/README.md

@@ -377,13 +377,24 @@ end
 ```ruby
 require 'connection_pool'
 
+POOLS = {}
+POOLS_MUTEX = Mutex.new
+
 Familia.connection_provider = lambda do |uri|
-  ConnectionPool.new(size: 10, timeout: 5) do
-    Redis.new(url: uri)
-  end.with { |conn| yield conn if block_given?; conn }
+  POOLS_MUTEX.synchronize do
+    POOLS[uri] ||= ConnectionPool::Wrapper.new(size: 10, timeout: 5) do
+      Redis.new(url: uri)
+    end
+  end
 end
 ```
 
+Build each pool once, outside the lambda, and return a `ConnectionPool::Wrapper`
+— it checks a connection out for the duration of each command and checks it back
+in afterwards. Returning `pool.with { |conn| conn }` instead hands back a
+connection the pool already considers free, so concurrent callers share it. See
+[the provider contract](docs/reference/api-technical.md#provider-contract).
+
 ### Encryption Setup
 
 ```ruby