familia 2.11.0 → 2.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c322fb98599ca1596829b047f78d414a3216a4e94a61ded4c6d3a4355dd7780a
-  data.tar.gz: a0af405d479ba7547b2fe65fe17e7a9b0fc5fb04cfe8b5563ce10726187d0396
+  metadata.gz: d7b0eed1c3632c68c8c4c91617830f0b15a10907da5c7af0bbc14b9cf67a5336
+  data.tar.gz: 4a123b805e826b8ede218675c16781f428fab6c3194968c5a3840323b949b28e
 SHA512:
-  metadata.gz: ac3aac1967a9730670b6f43f464c001d6c0acad7e599e528d94edb5b60b7939fb59dc5ef320962bfaacd1c204603e36d09647670f2511320a98c9b4fc9f0d715
-  data.tar.gz: f5f7e14e48be039962af4bcda0ac6c61248143353f773239c5b4ac0a9e9af498f64618d2f18dc48f903c7349d47e375f6e87c6ed686d7e0bbc6ebb444a4456b7
+  metadata.gz: 6c245370d354eaa0d8af0b0994cd44ea10f8dec3b260c9750d3cceb66563c51ee8f4390062429c8aced6cd578d919c7a806a0eef2e5be0f9d90bbc00dcf87b06
+  data.tar.gz: a824edcd1af5d3535168600d90a3e189b0203c884fe17c7382cafb22ebc6c19a36c68011a468e9dd8b16fed386b902eac16709625004f73b7f4085b0ae0a601e

data/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "bundler"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
           - 2525:6379
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -53,7 +53,7 @@ jobs:
           bundler-cache: true
 
       - name: Setup tmate session
-        uses: mxschmitt/action-tmate@7b6a61a73bbb9793cb80ad69b8dd8ac19261834c # v3
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
         with:
           detached: true

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

@@ -4,14 +4,34 @@ on:
   pull_request:
     types: [opened, synchronize, labeled]
   workflow_dispatch:
+    inputs:
+      model:
+        description: "Claude model for this run (overrides the CLAUDE_MODEL repo variable)"
+        type: choice
+        required: false
+        default: claude-opus-4-6
+        options:
+          - claude-opus-4-6
+          - claude-sonnet-4-6
+          - claude-haiku-4-5-20251001
 
 jobs:
   claude-review:
-    # Run on opened/synchronize, but only on 'labeled' if label is 'claude-review'
-    if: |
-      github.event.action == 'opened' ||
-      github.event.action == 'synchronize' ||
-      (github.event.action == 'labeled' && github.event.label.name == 'claude-review')
+    # Run only when ALL of the following hold:
+    #   1. Author is not a bot (renovate, dependabot, etc. surface as 'name[bot]').
+    #   2. PR head is not from a fork. Fork PRs run without repository secrets, so
+    #      CLAUDE_CODE_OAUTH_TOKEN is empty and the action would fail.
+    #   3. The event is a freshly opened PR, a 'claude-review' label add, or a push
+    #      to a PR that already carries the 'claude-review' label.
+    if: ${{
+      !endsWith(github.actor, '[bot]') &&
+      !github.event.pull_request.head.repo.fork &&
+      (
+        (github.event.action == 'opened') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'claude-review') ||
+        (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'claude-review'))
+      )
+      }}
 
     runs-on: ubuntu-latest
     permissions:
@@ -22,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 1
 
@@ -32,6 +52,13 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
+          # Primary model precedence: the workflow_dispatch "model" input (manual
+          # 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' }}"
+
           # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
           use_sticky_comment: true
 
@@ -50,6 +77,3 @@ jobs:
           # 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:*)"
-
-          # Allow bot-initiated workflows (e.g., qodo, dependabot)
-          allowed_bots: "*"

data/.github/workflows/claude.yml

@@ -26,16 +26,23 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 1
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@beta
         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' }}"
+
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read

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

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -91,7 +91,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/codeql.yml

@@ -0,0 +1,101 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '30 0 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: ruby
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

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

@@ -124,7 +124,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
@@ -132,10 +132,10 @@ jobs:
         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"
+          # Pinned to 3.3 to match the otto/rhales release builds. The gem is
+          # pure Ruby, so the build Ruby is independent of the supported range
+          # declared in the gemspec (>= 3.2).
+          ruby-version: "3.3"
 
       - name: Verify release tag matches Familia::VERSION
         env:
@@ -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@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+        uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

data/.github/workflows/ruby-lint.yml

@@ -0,0 +1,66 @@
+# .github/workflows/ruby-lint.yml
+
+name: Ruby Lint
+
+# Runs RuboCop across the supported Ruby versions. Linting is informational:
+# every dependency/lint step is continue-on-error, so style findings surface as
+# annotations without blocking merges.
+
+on:
+  push:
+    branches:
+      - fix/*
+      - rel/*
+  pull_request:
+    branches:
+      - main
+      - develop
+      - feature/*
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    timeout-minutes: 10 # prevent hung jobs
+
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: true
+      matrix:
+        ruby: ['3.2', '3.3', '3.4', '3.5', '4.0']
+        continue-on-error: [true]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+        with:
+          detached: true
+
+      - name: Install dependencies
+        continue-on-error: ${{ matrix.continue-on-error }}
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+
+      - name: Run Rubocop
+        continue-on-error: ${{ matrix.continue-on-error }}
+        run: |
+          bundle exec rubocop --config .rubocop.yml --format json --fail-level warning

data/.github/workflows/yardoc.yml

@@ -0,0 +1,110 @@
+name: Generate and Deploy YARD Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'lib/**/*'
+      - 'docs/**/*'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'CHANGELOG.rst'
+      - 'LICENSE.txt'
+      - '.yardopts'
+      - '.github/workflows/yardoc.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. Do NOT cancel in-progress runs so production
+# deployments can complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    name: Generate YARD Documentation
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Ruby environment
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Generate documentation
+        # Uses the repository's committed .yardopts as the single source of
+        # truth for the output dir, includes/excludes, markup, and tags.
+        run: |
+          echo "::group::YARD Documentation Generation"
+          bundle exec yard stats --list-undoc || true
+          bundle exec yard doc
+          echo "::endgroup::"
+
+      - name: Disable Jekyll processing
+        # YARD emits files and directories that begin with underscores; the
+        # .nojekyll marker stops GitHub Pages from stripping them.
+        run: touch doc/.nojekyll
+
+      - name: Validate documentation output
+        run: |
+          echo "::group::Documentation Validation"
+          if [ ! -d "doc" ]; then
+            echo "Error: documentation directory 'doc' was not generated." >&2
+            echo "Ensure .yardopts sets '--output-dir doc'." >&2
+            exit 1
+          fi
+          if [ ! -f "doc/index.html" ]; then
+            echo "Warning: doc/index.html not found"
+          fi
+          echo "Generated HTML files: $(find doc -name '*.html' | wc -l)"
+          echo "Total documentation size: $(du -sh doc/ | cut -f1)"
+          echo "::endgroup::"
+
+      - name: Setup GitHub Pages configuration
+        uses: actions/configure-pages@v4
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: './doc'
+
+  deploy-pages:
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-docs
+    outputs:
+      page_url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  notify-completion:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    needs: [build-docs, deploy-pages]
+    if: success()
+
+    steps:
+      - name: Documentation deployment summary
+        run: |
+          echo "::notice title=Documentation Deployed::YARD documentation successfully deployed to GitHub Pages"
+          echo "::notice title=Access URL::Documentation available at: ${{ needs.deploy-pages.outputs.page_url }}"

data/.yardopts

@@ -6,7 +6,7 @@
 --charset utf-8
 --markup markdown
 --markup-provider redcarpet
---output-dir public
+--output-dir doc
 --embed-mixin ClassMethods
 --embed-mixin InstanceMethods
 --embed-mixin Features

data/CHANGELOG.rst

@@ -7,6 +7,156 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.11.2:
+
+2.11.2 — 2026-07-05
+===================
+
+
+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.
+
+- 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.
+
+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.
+
+AI Assistance
+-------------
+
+- Investigation, implementation, and tryouts coverage produced with Claude Code.
+
+.. _changelog-2.11.1:
+
+2.11.1 — 2026-07-04
+===================
+
+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
+
+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
+
+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
+
+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
+
+AI Assistance
+-------------
+
+- The encryption upgrade proof, its regression tryouts, and this changelog
+  entry were drafted with AI assistance. PR #330
+
+- The ``exists?`` fix and its regression tryouts were drafted with AI
+  assistance. Issue #331
+
+- The per-field algorithm implementation, the ``encrypted_fields_status`` fix,
+  their regression tryouts, the guide corrections, and the
+  ``Registry.get`` error-message refinement were drafted with AI assistance.
+  Issue #334
+
+- The memory-audit investigation and its executable proofs were drafted with AI
+  assistance. Issue #309
+
 .. _changelog-2.11.0:
 
 2.11.0 — 2026-06-22

data/Gemfile

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem 'concurrent-ruby', '~> 1.3.6', require: false
+  gem 'concurrent-ruby', '~> 1.3.7', require: false
   gem 'ruby-prof'
   gem 'stackprof'
   gem 'timecop', require: false
@@ -21,12 +21,12 @@ group :development, :test do
   # 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 'irb', '~> 1.18.0', require: false
   gem 'json_schemer', '~> 2.0', require: false
   gem 'rake', '~> 13.0', require: false
   gem 'redcarpet', require: false
   gem 'reek', require: false
-  gem 'rubocop', '~> 1.85.1', require: false
+  gem 'rubocop', '~> 1.88.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'ruby-lsp', require: false