familia 2.11.2 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b0eed1c3632c68c8c4c91617830f0b15a10907da5c7af0bbc14b9cf67a5336
-  data.tar.gz: 4a123b805e826b8ede218675c16781f428fab6c3194968c5a3840323b949b28e
+  metadata.gz: d860c29966392e82cf54d842d457353d6a7268c3bf5378e25af9cb850f59d37c
+  data.tar.gz: 87fc36560a6cd68ffb614ef6b3ab11625300ebed8433508739f1ab4633f5b9ff
 SHA512:
-  metadata.gz: 6c245370d354eaa0d8af0b0994cd44ea10f8dec3b260c9750d3cceb66563c51ee8f4390062429c8aced6cd578d919c7a806a0eef2e5be0f9d90bbc00dcf87b06
-  data.tar.gz: a824edcd1af5d3535168600d90a3e189b0203c884fe17c7382cafb22ebc6c19a36c68011a468e9dd8b16fed386b902eac16709625004f73b7f4085b0ae0a601e
+  metadata.gz: 15b5c9028503566db28d179052982d3a38617463753ea360f22ea49eeb86d3fc896352f18c73a703fe62d3fd5a6cdcf65f254dab284a7671f3b9a0b9db413acb
+  data.tar.gz: 633e8ae2bab11aaf362791f23f68ea7f0287e1388c38850200809c5b43ed79ae59039492258927023ea91821d39243a18c9eaa5a63d8c068fb011edc99120468

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@be7b93b1907a4abad570368f3c74b6fe3807510b # v1.0.183
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
@@ -56,13 +56,23 @@ 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 comment:*),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
           use_sticky_comment: true
 
-          direct_prompt: |
+          # v1 renamed direct_prompt -> prompt. The REPO/PR NUMBER header is the
+          # format the migration guide calls for so Claude reviews the right PR.
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
             Please review this pull request and provide feedback on:
             - Code quality and best practices
             - Potential bugs or issues
@@ -73,7 +83,3 @@ jobs:
             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@be7b93b1907a4abad570368f3c74b6fe3807510b # v1.0.183
         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/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

@@ -24,8 +24,14 @@ 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

@@ -21,6 +21,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

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.12.0:
+
+2.12.0 — 2026-08-03
+===================
+
+Added
+-----
+
+- Added ``Familia::HashKey#claim_field`` and ``#release_field`` for server-side compare-and-set/compare-and-delete on single hash fields. Raises ``Familia::OperationModeError`` in pipelines/transactions.
+- Added generated ``claim_unique_<index>!`` and ``release_unique_<index>!`` instance methods with automatic partial claim rollback on unique index save collisions. #353
+- Added tryout test helpers (``set_test_encryption_keys``, ``clear_test_encryption_keys``, ``with_test_encryption_keys``) to safely manage encryption key configurations during test runs. #363
+- Added ``Familia::MultiResult#aborted?`` to distinguish WATCH aborts from individual command errors.
+- Added ``Familia::MultiResult#inspect`` for log-safe, compact transaction outcome summaries.
+- Added ``max_length:`` option to ``SortedSet`` and ``ListKey`` to automatically cap collection sizes at write time (retaining newest N elements). #351
+- Added ``DataType#max_length`` to query configured collection caps, with definition-time validation of the parameter. #351
+- Added ``SortedSet#enforce_max_length!`` and ``ListKey#enforce_max_length!`` to trim existing collections. #351
+- Added ``max_length:`` option to ``participates_in`` and ``class_participates_in``. #351
+- Added ``Familia::Features::Housekeeping::EnforceCollectionCaps`` chore class to support bulk cap enforcement. #351
+- Added ``encryption_personalization_history`` setting to support key personalization rotation for XChaCha20-Poly1305 providers. #333
+- Added ``limit:``, ``offset:``, and ``each_<collection>_with_permission`` to stream permission-filtered collection members via ``ZSCAN`` with O(1) memory. #309
+
+Changed
+-------
+
+- Unique index updates (``add_to_class_<index>``, ``update_in_class_<index>``) now raise ``Familia::OperationModeError`` inside transactions unless the written value was previously claimed. #353
+- Retained ``guard_unique_indexes!`` for fast-fail read checks before acquiring index claims. #353
+- Calls to ``remove_from_class_*`` and class-level ``destroy!`` no longer evict index entries that point to different identifiers. #353
+- ``Familia::MultiResult#results`` now always returns an ``Array`` (empty instead of ``nil`` on transaction abort) to prevent upstream crashes.
+- ``Familia::MultiResult#to_h`` now includes an ``:aborted`` boolean key.
+- ``Familia::MultiResult`` instances are now read-only, freezing both ``#results`` and ``#errors``.
+- ``SortedSet#increment`` now runs the ``warn_if_dirty!`` guard, warning or raising when called on an unsaved parent. #351
+- ``Manager#decrypt`` now handles XChaCha20 provider personalization candidates correctly during decryption walks, matching AES-GCM salt history behavior. #333
+- The request-scoped key cache key now includes a personalization segment to prevent collisions across different rotation candidates. #333
+- ``multi_field_fast_write`` now raises ``Familia::IndexedFieldFastWriteError`` if any written field backs a class-level index. #308
+- Fast writer ``field!`` on a class-indexed field now raises ``Familia::IndexedFieldFastWriteError`` inside transactions/pipelines, and raises ``Familia::PersistenceError`` on unsaved records. #308
+- With a blank ``encryption_hkdf_salt``, ``Manager#encrypt`` now raises ``EncryptionError`` when the request-cache key is built rather than at key derivation. The raise happens earlier and now also fires on what would previously have been a warm-cache hit; correctly configured deployments see no change. #380
+
+Removed
+-------
+
+- Removed the unused ``ScoreEncoding.category_score_range`` method.
+- Removed unused ``csv`` and ``stringio`` runtime dependencies from the gemspec. #354
+- Removed dead private helper methods ``Horreum::define_attr_accessor_methods``, ``remove_stale_collection_member``, and ``define_fast_writer_method``. #347, #308
+
+Fixed
+-----
+
+- Fixed ``decrby`` and ``decr`` (and aliases) to correctly use ``HINCRBY`` with a negated amount and added client-side integer validation.
+- Fixed ``encryption_info`` to reference the correct provider APIs and accurately expose ``key_size``.
+- Fixed a TOCTOU race in ``unique_index`` by enforcing server-side CAS claims using Lua before opening transactions, raising ``Familia::RecordExistsError`` on collision. #353
+- Fixed ``remove_from_class_*`` and ``update_in_class_*`` to use ownership-checked deletes, preventing accidental deletion of other records' valid entries. #353
+- Fixed process-global encryption configuration leaks across tryouts by using scoped helpers and restoring baselines. #363
+- Fixed test isolation in ``real_feature_integration_try.rb`` and ``module_loading_try.rb`` by explicitly managing encryption key rings. #363
+- Fixed fiber-local key cache teardowns to clear the correct request cache key. #363
+- Fixed claim leaks on unpersisted records in ``update_in_<scope>_<index_name>`` by running the persisted-record guard before checking claims. #370
+- Fixed ``ConcealedString`` by removing a redundant and non-functional GC finalizer. #359
+- Fixed ``Familia::MultiResult`` to prevent ``NoMethodError`` crashes on WATCH-aborted transactions. #355
+- Fixed ``SecureXChaCha20Poly1305Provider#derive_key`` to avoid mutating the receiver context string and handle non-String contexts correctly. #356
+- Fixed ``SortedSet#increment`` inside transactions/pipelines to safely return the future instead of calling ``to_f`` prematurely. #351
+- Fixed long-ignored ``:maxlength`` spelling to explicitly warn at definition time, prompting rename to ``max_length:``. #351
+- Fixed ``Lock#acquire`` with a positive TTL to run as a single atomic ``SET NX EX`` command. #347
+- Fixed ``DatabaseLogger.sample_rate`` assignment to validate and clamp input values, preventing crashes on the hot path. #347
+- Fixed ``SingleUseRedactedString`` to be loaded automatically by ``require 'familia'``. #347
+- Fixed memory overhead in ``<collection>_with_permission`` queries by batching and paging internally via ``ZRANGEBYSCORE ... LIMIT``. #309
+- Fixed performance by removing redundant post-save ``update_all_indexes`` calls inside relationships save. #307
+- Fixed partial write paths (``commit_fields``, ``save_fields``, ``multi_field_update``) to safely guard and claim unique indexes before executing writes. #308
+- Fixed fast writers (``field!``) on indexed fields to claim and update the index atomically before execution. #308
+
+Security
+--------
+
+- Enforced field-type semantics in ``multi_field_update`` and ``multi_field_fast_write`` to prevent writing plaintext to encrypted fields or persisting transient fields.
+- Enforced loud failures for invalid permission symbol lookups in ``Relationships::ScoreEncoding`` to prevent silent misconfigurations.
+- Pinned GitHub Workflows holding ``CLAUDE_CODE_OAUTH_TOKEN`` to immutable release commit SHAs.
+- The encrypt-path request-cache key now resolves the HKDF salt through the fail-closed ``current_hkdf_salt`` accessor instead of the permissive candidate list's head (``hkdf_salts.first``). Previously, with a blank ``encryption_hkdf_salt``, a decrypt inside ``with_request_cache`` could warm an entry keyed on a historical salt that a subsequent encrypt would silently reuse -- because the cache lookup precedes derivation, the blank-salt refusal in the provider never fired. Encrypts now refuse a blank salt even against a warm cache. #380
+
+Documentation
+-------------
+
+- Replaced fabricated/incorrect examples in ``docs/overview.md`` and RDoc comments with accurate, tested examples for permission management and relationships.
+- Documented that ``<collection>_with_permission`` requires atomic flags and rejects role symbols.
+- Corrected the error message for ``guard_allowed_fields!``.
+- Documented ``PERMISSION_CATEGORIES`` and exclusive permission tiers.
+- Fixed incorrect connection provider examples in docs.
+- Updated encryption guides to cover personalization history and 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

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.88.2', 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.12.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,17 +63,17 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.9)
+    json (2.20.0)
     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.4)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
@@ -98,7 +95,7 @@ GEM
     rake (13.4.2)
     rbnacl (7.1.2)
       ffi (~> 1)
-    rbs (4.0.2)
+    rbs (4.0.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -134,7 +131,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.0)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -145,7 +142,7 @@ 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)
@@ -156,7 +153,7 @@ GEM
       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.10)
       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.88.2)
   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

data/changelog.d/README.md

@@ -4,64 +4,56 @@ This directory contains changelog fragments managed by [Scriv](https://scriv.rea
 
 ## Our Approach
 
-Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) and semvar to ensure our release notes are clear, consistent, and useful.
-
-To achieve this, we use a fragment-based workflow with `scriv`. Instead of a single, large `CHANGELOG.md` file that can cause merge conflicts, each developer includes a small changelog fragment with their pull request. At release time, these fragments are collected and aggregated into the main changelog.
-
-This approach provides several benefits:
-- **Reduces Merge Conflicts:** Developers can work in parallel without conflicting over a central changelog file.
-- **Improves Developer Experience:** Creating a small, focused fragment is a simple and repeatable task during development.
-- **Ensures Consistency:** Automation helps maintain a consistent structure for all changelog entries.
-- **AI Transparency:** An opportunity to be specific and detailed about the assistance provided.
-- **Builds Trust:** A clear and well-maintained changelog communicates respect for our users and collaborators.
-
-## Relevant paths
-
-* `changelog.d/` - (e.g. changelog.d/YYYYMMDD_HHmmss_username_branch.rst)
-* `docs/migrating/` - (e.g. docs/migrating/v2.0.0-pre.md)
-* `CHANGELOG.rst` - The full changelog for all releases, in reverse chronological order. Careful: LARGE DOCUMENT. Limit reading to the first 50 lines.
-
-* `changelog.d/scriv.ini` - Scriv tool settings
-
-## How to Add a Changelog Entry
-
-1.  **Create a New Fragment:**
-
-```bash
-# This will create a new file in the `changelog.d/` directory.
-scriv create
-```
-
-2.  **Edit the Fragment File:**
-Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good CHANGELOG entries.
-
-3. **Add or Update Migrating Guide:** (optional)
-Include technical details to help developers update to the new version. Start with a specific introduction, e.g. "This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.". Including code snippets and multi-line content that is too detailed for the CHANGELOG.
-
-Use the content of an existing `docs/migrating/vMajor.Minor.Patch*.md file as a reference.
-
-Compare the headers of your draft content with the headers of the previous migration guide to make sure it does not repeat or overlap.
-
-4.  **Commit with Your Code:**
-```bash
-git add changelog.d/YYYYMMDD_HHmmss_username_branch.rst [docs/migrating/v2.0.0-pre.md]
-git commit
-```
+Changelogs are for humans and agents, not just machines. We follow [Keep a Changelog](https://keepachangelog.com) and semver to ensure clear, consistent, and useful release notes.
+
+We use a fragment-based workflow with `scriv`. Each developer includes a small, focused changelog fragment with their pull request. At release time, these are compiled into the main changelog.
+
+Benefits:
+- **No Merge Conflicts:** Developers work in parallel without conflicting over a single file.
+- **Improved DX:** Creating a small fragment is simple and repeatable.
+- **AI Transparency:** Briefly notes AI involvement without cluttering technical sections.
+- **Consistency:** Automation maintains a unified structure.
+
+### Relevant Paths
+
+* `changelog.d/` - Fragment directory (e.g. `changelog.d/YYYYMMDD_HHmmss_username_branch.rst`)
+* `docs/migrating/` - Migration guides (e.g. `docs/migrating/v2.0.0-pre.md`)
+* `CHANGELOG.rst` - The full changelog (reverse chronological, large file; read only the top 100 lines default)
+* `changelog.d/scriv.ini` - Scriv configuration
+
+## Add a Changelog Entry
+
+1. **Create a New Fragment:**
+   ```bash
+   scriv create
+   ```
+2. **Edit the Fragment:**
+   Open the new `.rst` file and write your entry under the relevant category using the guidelines below.
+3. **Add or Update Migrating Guide (Optional):**
+   If the change requires developer action to upgrade, add or update a guide in `docs/migrating/`. Use existing guides as a reference and ensure headers do not repeat.
+4. **Commit with Your Code:**
+   ```bash
+   git add changelog.d/YYYYMMDD_HHmmss_username_branch.rst [docs/migrating/v2.0.0-pre.md]
+   git commit
+   ```
 
 ## Fragment Guidelines
 
 - **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
-- **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
-- **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
-    - **Good:** "Improved the performance and stability of Database connections under high load."
-    - **Bad:** "Refactored the `DatabaseManager`."
-- **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
-- **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
-    - **Example:** `- Fixed a bug where users could not reset their passwords. PR #123`
+- **Reference Context:** Include issue or PR numbers. Scriv will automatically link them. (e.g., `PR #123`).
+
+## Content Guidelines
+
+- **Target the Consumer:** Focus exclusively on external, breaking, or actionable behavior. Omit internal implementation steps, development metadata, and agent logs.
+- **Impact-Driven Filtering:** Focus strictly on technical facts (method/class signatures, parameters, exceptions, issues resolved) and eliminate explanatory "how" or "why" narratives.
+  - **Good:** "Added ``Familia::HashKey#claim_field`` and ``#release_field`` for single-hash server-side CAS/CAD operations. Raises ``Familia::OperationModeError`` in pipelines/transactions."
+  - **Bad:** "We found a race condition during an audit, so we added a nice compare-and-set wrapper called `#claim_field` to allow callers to safely claim a field in single hash fields."
+- **Process Log Exclusion:** Remove all development metadata (such as tool-specific implementation notes, agent logs, and audit timelines) that do not change library APIs or behavior.
+- **Maintain Consistency:** Match the terse style, semantic classification, and spacing of previous changelog versions.
 
-### Categories
+## Categories
 
-Use these categories:
+Use these standard headers in your fragment:
 
 - **Added**: New features or capabilities.
 - **Changed**: Changes to existing functionality.
@@ -70,8 +62,8 @@ Use these categories:
 - **Fixed**: Bug fixes.
 - **Security**: Security-related improvements.
 - **Documentation**: Documentation improvements.
-- **AI Assistance**: Significant AI assistance in the change, including discussion, rubber ducking, formatting, writing documentation, writing tests.
+- **AI Assistance**: Terse, single-sentence acknowledgment of AI assistance for the change. Do not duplicate technical details already listed in other categories.
 
 ## Release Process
 
-At release time, scriv will collect all fragments into the main `CHANGELOG.rst` file with th command `scriv collect`. The version is taken automatically from `lib/familia/version.rb`.
+At release, run `scriv collect` to aggregate all fragments into `CHANGELOG.rst`. The version is parsed automatically from `lib/familia/version.rb`.

data/changelog.d/fragments/20260725_202500_delano_282_unsaved_index_guard.md

@@ -0,0 +1,7 @@
+### Changed
+
+- **Index mutations now require a persisted record**: the `add_to_*`/`update_in_*` methods generated by `unique_index`/`multi_index` — both instance-scoped (`within:`) and class-level (`add_to_class_*`/`update_in_class_*`) — raise `Familia::PersistenceError` when called directly on an object that has never been saved. Previously the entry landed in the index pointing at a record that did not exist yet — and if the process never saved, nothing (including `destroy!` cleanup) could find it. The check runs before any write, so a rejected call leaves no partial state, and is skipped inside transactions/pipelines — which is why the save path (auto-indexing runs inside the save MULTI) and index rebuilds are unaffected. Call `save` before indexing. (#282; surfaced by the #278 unsaved-parent write guard)
+
+### AI Assistance
+
+- Root-cause analysis of the #278/#282 guard interaction, the fail-fast persisted-record guard, and test updates were developed with AI assistance.

data/changelog.d/fragments/20260725_213000_delano_282_index_scope_tracker.md

@@ -0,0 +1,18 @@
+### Added
+
+- **Instance-scoped indexes now refresh on save**: once a membership has been registered with `add_to_*`, saving the record keeps its index entry current. Unique indexes route through `update_in_*` with the previous value from dirty tracking, so a changed indexed field retracts its stale entry and the freed value becomes reusable; multi indexes are add-only, matching the existing class-level decision that a value change does not retract prior buckets (`destroy!` still cleans every bucket — see the tracker cardinality note below — so add-only costs no cleanup coverage; call `update_in_*` to retract at change time instead). The refresh runs inside save's MULTI (alongside class-level index maintenance) using a tracker snapshot read just before the transaction opens, so index mutations commit atomically with the object hash. The *initial* `add_to_*` remains manual — save has no scope instance to infer. Note that `atomic_write` does **not** refresh instance-scoped indexes: it calls the shared persistence path from inside a MULTI it already opened, leaving no pre-transaction point at which the tracker snapshot could be read, so index entries silently keep their previous values on that path. Use `save`, or call `update_in_*` explicitly afterwards. (#282)
+- **Instance-scoped unique indexes are validated on save**: changing an indexed field to a value another record already holds in that scope now raises `Familia::RecordExistsError` and leaves the index untouched, matching how class-level `unique_index` has always behaved on save. Previously the uniqueness guard existed only in `add_to_*`, never `update_in_*`, so the save-refresh path could silently evict the other record's entry — and because the evicted record's tracker still claimed the slot, its later `destroy!` would unindex the live record that had taken it. The check runs before the transaction opens, alongside the existing class-level `guard_unique_indexes!`, and only inspects fields that actually changed. (#282)
+- **`dirty_write_warnings:` option on DataType**: overrides the parent class's dirty-write diagnostic mode for a single collection. Added for ORM-internal structures that the persistence path writes deliberately while the parent is dirty — the index scope tracker sets `:off`, since the warning is false there (the scalar write is queued in the same transaction) and `Familia.strict_write_order` would otherwise abort every save that refreshes an index.
+
+### Fixed
+
+- **Instance-scoped index cleanup now survives a changed field value**: the reverse index tracker (`_idx_scopes`) is a hash mapping each membership to the field value that was written into the index, instead of a set of memberships alone. Tracker cardinality mirrors index cardinality: unique entries are keyed by `scope_config`/`index_name`/`scope_id` (1:1 within a scope, so HSET-overwrite is exact), while multi entries append the value, giving one entry per bucket the object occupies — a single triple-keyed entry could only name one of several simultaneous buckets, and `destroy!` would orphan the rest. `destroy!` removes the recorded buckets rather than re-reading the current field value, so cleanup still lands correctly when the indexed field changed after `add_to_*` — and when the object being destroyed was constructed identifier-only (`Model.new(id: x).destroy!`), where the current value is nil and cleanup previously short-circuited and orphaned the entry. `update_in_*` now updates the tracker too, so a value change needs no old-value bookkeeping. The generated `remove_from_{scope}_{index}` methods accept an optional field value (defaulting to the current one, so the single-argument call is unchanged) which is how cleanup passes the recorded value. (#282)
+- **Instance-scoped index cleanup with a shared index name**: a tracker entry is now matched on scope class *and* index name. When two scope classes declared the same `index_name`, the first-declared relationship always won, so cleanup built a stub of the wrong class and mutated the wrong key. (#282)
+
+### Changed
+
+- **Instance-scoped index writes reject untrackable scopes**: `add_to_*`/`update_in_*` raise `Familia::NoIdentifier` when the scope instance has no identifier, and `ArgumentError` when the scope class's `identifier_field` is not a Symbol or String. Both are checked before the index write, so a rejected call leaves no partial state. The identifier-field restriction exists because `destroy!` must rebuild the scope from its identifier alone inside a MULTI, where reads return futures — a scope that cannot be rebuilt that way would leave an index entry nothing could clean up. (#282)
+
+### AI Assistance
+
+- The stored-value tracker design, the scope-config-aware entry lookup, the save-path refresh wiring, and the accompanying tests were developed with AI assistance.

data/changelog.d/fragments/20260728_120000_delano_365_stale_tracker_prune.rst

@@ -0,0 +1,30 @@
+Fixed
+-----
+
+- A record saved under a reused identifier no longer inherits the previous
+  record's index tracker. ``delete!`` removes only the main object hash, so the
+  instance-scoped index tracker (``_idx_scopes``) survived it — and the next
+  ``save`` under the same identifier replayed the stale entries, silently
+  joining the new record to every scope the *previous* record had been added to
+  (or raising ``Familia::RecordExistsError`` when the new value collided with
+  another record's entry). Save now detects the staleness — tracker entries can
+  only outlive the object hash when a previous incarnation was ``delete!``'d or
+  expired, since ``add_to_*`` refuses never-saved records — and prunes them
+  inside the save transaction: ``remove_from_*`` is replayed with the recorded
+  values, clearing the dead incarnation's index entries (previously orphaned
+  forever) along with the tracker itself. The new record starts with no
+  instance-scoped memberships; ``add_to_*`` remains the explicit opt-in.
+  ``save_if_not_exists!`` applies the same reconciliation (replacing its
+  previous behavior of re-syncing stale entries onto the resurrected record),
+  and the detection costs an EXISTS probe only when the tracker actually has
+  entries. Note that ``atomic_write`` performs no staleness detection (it has
+  no pre-transaction point to probe from), and once it has recreated the hash a
+  later ``save`` can no longer tell the inherited entries are stale — the first
+  write to a reused identifier should be a ``save``. (#365)
+
+AI Assistance
+-------------
+
+- The staleness-detection design (prune-on-stale rather than a ``delete!``
+  override or an epoch marker), the save-path wiring, and the accompanying
+  tests were developed with AI assistance.