familia 2.12.0 → 2.14.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d860c29966392e82cf54d842d457353d6a7268c3bf5378e25af9cb850f59d37c
-  data.tar.gz: 87fc36560a6cd68ffb614ef6b3ab11625300ebed8433508739f1ab4633f5b9ff
+  metadata.gz: 78abdfef8c91211092845604967187b510a3b01f8b00772340cfb1c6ff081819
+  data.tar.gz: 8e982398843fb0c227be798af2c3b6de60b2daf40a6d9e8791ac4c122e586f55
 SHA512:
-  metadata.gz: 15b5c9028503566db28d179052982d3a38617463753ea360f22ea49eeb86d3fc896352f18c73a703fe62d3fd5a6cdcf65f254dab284a7671f3b9a0b9db413acb
-  data.tar.gz: 633e8ae2bab11aaf362791f23f68ea7f0287e1388c38850200809c5b43ed79ae59039492258927023ea91821d39243a18c9eaa5a63d8c068fb011edc99120468
+  metadata.gz: 0d612da7f16d268eb3b214a43cfa8f53c26e7766e70294ce3dabd134e2ca1c065726811f87c0e4dccb2aaacb463aba05a3e13148c7d8b6578933361c1c62c9e8
+  data.tar.gz: 39a032c23215875127fb97cdcbb7501ee28a9e624df60e81ab5feab700feeb1fdeae98df28bfbf660271d622aa77a74a3004ea9a4b8061345e0972e40ecb4094

data/.github/dependabot.yml

@@ -13,3 +13,8 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
+    ignore:
+      # dry-configurable 1.4.0 requires Ruby >= 3.3. Remove with Ruby 3.2
+      # support (see the Gemfile).
+      - dependency-name: "dry-configurable"
+        versions: [">= 1.4"]

data/.github/workflows/ci.yml

@@ -13,6 +13,92 @@ permissions:
   contents: read
 
 jobs:
+  # The repo's own bundle includes development and test gems, which can supply
+  # a library that familia requires but does not declare (base64 arrived this
+  # way, through ruby-prof). This job bundles familia alone, as an application
+  # does, and fails if it cannot be required or if Ruby warns that a required
+  # library is leaving the default gems.
+  consumer-load:
+    timeout-minutes: 10
+
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+
+      - name: Require familia from a bundle that contains only familia
+        run: |
+          consumer="$RUNNER_TEMP/consumer"
+          mkdir -p "$consumer"
+          cd "$consumer"
+          printf "source 'https://rubygems.org'\ngem 'familia', path: '%s'\n" "$GITHUB_WORKSPACE" > Gemfile
+          bundle install
+          if ! out=$(bundle exec ruby -e 'require "familia"; puts "familia #{Familia::VERSION} loaded"' 2>&1); then
+            echo "$out"
+            echo "::error::require 'familia' failed in a bundle that contains only familia"
+            exit 1
+          fi
+          echo "$out"
+          if grep -q "loaded from the standard library" <<<"$out"; then
+            echo "::error::familia requires a library that is leaving Ruby's default gems without declaring it in familia.gemspec"
+            exit 1
+          fi
+
+  # An application can resolve any release familia.gemspec allows, not only
+  # the newest one consumer-load gets. This job pins each runtime dependency
+  # to the lowest release the gemspec allows and fails if familia, or
+  # json_schemer (which familia requires on first schema validation), cannot
+  # be required. Ruby 3.4 is the first release that raises LoadError under
+  # Bundler for libraries that left the default gems (base64, bigdecimal).
+  # Warnings are not checked here: oj 3.16.2 to 3.16.4 warn about ostruct
+  # but load, and consumer-load checks warnings with the newest releases.
+  consumer-load-lowest:
+    timeout-minutes: 10
+
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+
+      - name: Require familia with the lowest dependency releases it allows
+        run: |
+          consumer="$RUNNER_TEMP/consumer-lowest"
+          mkdir -p "$consumer"
+          cd "$consumer"
+          ruby - "$GITHUB_WORKSPACE" > Gemfile <<'RUBY'
+            workspace = ARGV.fetch(0)
+            spec = Dir.chdir(workspace) { Gem::Specification.load('familia.gemspec') }
+            puts "source 'https://rubygems.org'"
+            puts "gem 'familia', path: #{workspace.dump}"
+            spec.runtime_dependencies.each do |dep|
+              found, = Gem::SpecFetcher.fetcher.spec_for_dependency(dep)
+              lowest = found.map { |s, _source| s.version }.min or abort "no release satisfies #{dep}"
+              puts "gem #{dep.name.dump}, #{lowest.to_s.dump}"
+            end
+          RUBY
+          cat Gemfile
+          bundle install
+          probe='require "familia"; require "json_schemer"; puts "familia #{Familia::VERSION} and json_schemer #{JSONSchemer::VERSION} loaded"'
+          if ! out=$(bundle exec ruby -e "$probe" 2>&1); then
+            echo "$out"
+            echo "::error::familia or json_schemer failed to load with the lowest dependency releases familia.gemspec allows"
+            exit 1
+          fi
+          echo "$out"
+
   build:
     timeout-minutes: 10
 

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@be7b93b1907a4abad570368f3c74b6fe3807510b # v1.0.183
+        uses: anthropics/claude-code-action@d70510b174a1244958df0b03166a54912811f3e6 # v1.0.264
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
@@ -62,17 +62,18 @@ jobs:
           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:*)"
+            --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
 
-          # 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
@@ -81,5 +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.

data/.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@be7b93b1907a4abad570368f3c74b6fe3807510b # v1.0.183
+        uses: anthropics/claude-code-action@d70510b174a1244958df0b03166a54912811f3e6 # v1.0.264
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

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/.gitignore

@@ -18,6 +18,7 @@
 dump.rdb
 appendonlydir
 data
+doc
 log
 tmp
 vendor

data/.rubocop.yml

@@ -30,6 +30,9 @@ AllCops:
     - "rspec/**/*.rb"
     - "tmp/**/*.rb"
     - "try/**/*.rb"
+    # Setting Exclude here replaces RuboCop's default list, which excludes
+    # vendor/. CI installs gems into vendor/bundle inside the checkout.
+    - "vendor/**/*"
 
 #
 # Trailing commas

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.
@@ -171,8 +173,9 @@ in one MULTI/EXEC; collection mutations auto-route into the open transaction via
 `Fiber[:familia_transaction]`. Constraints:
 
 - All related DataTypes must share the parent's `logical_database`, else `Familia::CrossDatabaseError` (fall back to `save_with_collections`). MULTI/EXEC is single-database only.
-- Cannot nest inside another `transaction`/`atomic_write` (`Familia::OperationModeError`).
+- Cannot nest inside another `transaction`/`atomic_write` or run inside a `pipelined` block (`Familia::OperationModeError`).
 - Collection return values inside the block are `Redis::Future` — do not inspect before EXEC.
+- Methods that need a reply to continue (iterators, finders and loaders, `fetch`, `refresh!`, the partial writers) raise `Familia::OperationModeError` inside the block. The policy and method lists are in docs/reference/transaction_safety.md, rule 4.
 
 **Factory — `build` for create-and-populate:**
 
@@ -203,3 +206,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.