familia 2.0.0.pre18 → 2.0.0.pre19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5bbf0ac2fc6a1243d74f679c7027040be00783af625dd90d376637e32417394
-  data.tar.gz: 4b354347a0c2403490dc20fdc12f93b3e71b826cf0b2b08638f6fd884a883630
+  metadata.gz: 4250fd7b94da275c6cfe9ebc7515e14fc6bead4bb25597aa5e433bf6c9368727
+  data.tar.gz: 50818f7fce2464d3a4349d4de6a1fd7992900e45d8774f6d6d40d047d71a1842
 SHA512:
-  metadata.gz: 221116e1aa14bc7114cb51164727587dcb0e8435dd8b85bb7d14618393ef446446376fd7febf6dbc9993098e2c819b3b0aa6f3c8bedce1c965b99ec4c8832a7b
-  data.tar.gz: 457b0e5bfef1f203c8f2edf934d1ee37915df04c49b0cb8b097ab9732738186ba9e8e92496851699f0952426971d2d3d244e61e594719439672996a0ccde2050
+  metadata.gz: bf19202fe2ae0176698fa3ed5b5bd5cb4c1536de2e091a0978d75d8d9964c05cf2285cbcbbdf2d8deb20500a00b83f4fc4d7091e80f08fcaa29840053788da4f
+  data.tar.gz: c7a5810d3c84cca3c8f51e7449d0049c13eae86300f4703b5af9a492329a1a1c6ff01142529351e705f527c4b4f1ad8d07b15e5280b956a3c5a4fa2971ff2b08

data/CHANGELOG.rst

@@ -1,17 +1,69 @@
 CHANGELOG.rst
 =============
 
-All notable changes to Familia are documented here.
-
-The format is based on `Keep a
-Changelog <https://keepachangelog.com/en/1.1.0/>`__, and this project
-adheres to `Semantic
-Versioning <https://semver.org/spec/v2.0.0.html>`__.
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`__, and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
 .. raw:: html
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre19:
+
+2.0.0.pre19 — 2025-10-11
+=========================
+
+Added
+-----
+
+-  **DataType Transaction and Pipeline Support** - DataType objects can now initiate transactions and pipelines independently, enabling atomic operations and batch command execution for both parent-owned and standalone DataType objects. `PR #160 <https://github.com/familia/familia/pull/160>`__. Key capabilities added:
+
+   * ``transaction`` and ``pipelined`` methods for atomic MULTI/EXEC operations and batched command execution on all DataType classes
+   * Connection chain pattern with Chain of Responsibility for DataType objects
+   * Two new connection handlers: ``ParentDelegationHandler`` for owned DataTypes and ``StandaloneConnectionHandler`` for independent DataTypes
+   * Enhanced ``direct_access`` method with automatic transaction/pipeline context detection
+   * Shared ``Familia::Connection::Behavior`` module extracting common connection functionality
+
+-  New error hierarchy with ``PersistenceError``, ``HorreumError``, ``CreationError``, and ``OptimisticLockError`` classes for better error categorization and handling
+-  ``watch``, ``unwatch``, and ``discard`` Redis commands for optimistic locking support
+-  Enhanced database command logging with structured format for pipelined and transaction operations
+-  ``save_fields`` method in Persistence module for selective field updates
+
+Changed
+-------
+
+-  **Connection Architecture Refactored** - The ``Horreum::Connection`` module now includes ``Familia::Connection::Behavior``, eliminating code duplication by sharing URI normalization and connection creation methods between Horreum and DataType. DataType objects with ``logical_database`` settings now return clean URIs without custom port information (e.g., ``redis://127.0.0.1/3`` instead of ``redis://127.0.0.1:2525/3``), ensuring consistent URI representation across the library.
+
+-  **BREAKING**: Renamed ``Management.create`` to ``create!`` to follow Rails conventions and indicate potential exceptions
+-  **BREAKING**: Updated ``save_if_not_exists`` to ``save_if_not_exists!`` with optimistic locking and automatic retry logic (up to 3 attempts)
+-  Improved ``save`` method to use single atomic transaction encompassing field updates, expiration setting, index updates, and instance collection management
+-  Enhanced ``delete!`` methods to work correctly within Redis transactions
+-  Updated timestamp fields (``created``, ``updated``) to use float values instead of integers for higher precision
+-  Refined log message formatting for better readability and debugging
+-  Removed deprecated Connection instance methods for Horreum models in favor of class-level database operations
+-  Clarified "pipelined" terminology throughout codebase (renamed from "pipeline" for consistency with Redis documentation)
+
+Fixed
+-----
+
+-  Resolved atomicity issues and race conditions in save operations by consolidating all related operations into single Redis transaction with proper watch/multi/exec pattern and optimistic locking
+-  Corrected transaction handling to ensure proper cleanup and error propagation
+
+Documentation
+-------------
+
+-  Added comprehensive parameter documentation for database command methods including return value specifications and usage examples
+
+AI Assistance
+-------------
+
+This feature was implemented with AI assistance from Claude Sonnet 4.5, Opus 4.1 (Anthropic).
+
+* Architectural design of the connection chain pattern and shared Behavior module
+* Implementation of DataType-specific connection handlers  (ParentDelegationHandler, StandaloneConnectionHandler) and comprehensive test coverage
+* Error hierarchy design and transaction atomicity optimization
+* Documentation enhancement and URI formatting debugging
+
+
 .. _changelog-2.0.0.pre18:
 
 2.0.0.pre18 — 2025-10-05

data/CLAUDE.md

@@ -105,30 +105,55 @@ class User < Familia::Horreum
 end
 ```
 
-**Good - use the `init` hook instead:**
+**Good - use the `init` hook to apply defaults (use `||=` not `=`):**
 ```ruby
 class User < Familia::Horreum
-  def init(email = nil)
-    @email = email  # Called after super, related fields work
+  field :objid
+  field :email
+
+  # Called after Horreum sets fields from kwargs
+  # IMPORTANT: Use ||= to apply defaults, not = to override
+  def init
+    @objid ||= SecureRandom.uuid  # Apply default only if not already set
+    _run_post_init_hooks          # Additional setup logic
   end
 end
+
+# This works correctly:
+user = User.new(email: 'test@example.com')
+user.objid      # → generated UUID (applied by init)
+user.email      # → 'test@example.com' (set by Horreum from kwargs)
 ```
 
-**Good - call super explicitly:**
+**Okay - if absolutely necessary, override and call super explicitly:**
 ```ruby
 class User < Familia::Horreum
   def initialize(email = nil, **kwargs)
-    super(**kwargs)  # ✓ Related fields initialized
-    @email = email
+    super # Initializes related fields here and also calls init
+    @email ||= generate_email if email.nil?
   end
 end
 ```
 
-**Why this matters**: Familia's `initialize` method calls `initialize_relatives` to set up DataType objects (lists, sets, etc.). Without calling `super`, these objects remain nil and you'll get helpful errors pointing to the missing super call.
+**Why this matters**: Familia's `initialize` method processes kwargs FIRST (setting fields), then calls `initialize_relatives` (setting up DataType objects), then calls your `init` hook. By the time `init` runs, kwargs have already been consumed and fields are set.
+
+**The ||= Pattern Explained**:
+```ruby
+# WRONG - overwrites what Horreum already set
+def init
+  @email = generate_email  # Overwrites the correct value
+end
+
+# RIGHT - applies default only if not already set
+def init
+  @email ||= email               # Preserves value Horreum set from kwargs
+  @email ||= 'default@example.com'  # Apply fallback default if still nil
+end
+```
 
 **When to use each approach:**
-- **Use `init` hook** (preferred): For simple initialization logic that doesn't need to intercept constructor arguments. The `init` method is called automatically after `super` with the same arguments passed to `new`.
-- **Use explicit `super`**: When you need full control over initialization order or need to transform arguments before passing to parent. Remember to pass `**kwargs` to preserve keyword argument handling.
+- **Use `init` hook with `||=`** (preferred): Apply defaults, run validations, setup callbacks - any logic that should run after field initialization. Follows standard ORM lifecycle hook patterns.
+- **Use explicit `super`**: Only when you need to intercept or transform arguments before Horreum processes them (rare).
 
 **DataType Definition**: Use class methods to define keystore database-backed attributes:
 ```ruby

data/Gemfile

@@ -17,10 +17,10 @@ group :development, :test do
   gem 'irb', '~> 1.15.2', require: false
   gem 'redcarpet', require: false
   gem 'reek', require: false
-  gem 'rubocop', require: false
+  gem 'rubocop', '~> 1.81.1', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
-  gem 'solargraph', require: false
+  gem 'ruby-lsp', require: false
   gem 'yard', '~> 0.9', require: false
 end
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre18)
+    familia (2.0.0.pre19)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)
@@ -15,7 +15,6 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    backport (1.2.0)
     base64 (0.3.0)
     benchmark (0.4.1)
     bigdecimal (3.2.3)
@@ -64,23 +63,11 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    jaro_winkler (1.6.1)
-    json (2.15.0)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
+    json (2.15.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    mini_portile2 (2.8.9)
     minitest (5.25.5)
-    nokogiri (1.18.10)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
-    nokogiri (1.18.10-arm64-darwin)
-      racc (~> 1.4)
-    observer (0.1.2)
     oj (3.16.11)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
@@ -94,7 +81,7 @@ GEM
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.5.1)
+    prism (1.5.2)
     psych (5.2.6)
       date
       stringio
@@ -121,8 +108,6 @@ GEM
     regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
-    reverse_markdown (3.0.0)
-      nokogiri
     rexml (3.4.1)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
@@ -159,34 +144,15 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
+    ruby-lsp (0.26.1)
+      language_server-protocol (~> 3.17.0)
+      prism (>= 1.2, < 2.0)
+      rbs (>= 3, < 5)
     ruby-prof (1.7.2)
       base64
     ruby-progressbar (1.13.0)
-    solargraph (0.57.0)
-      backport (~> 1.2)
-      benchmark (~> 0.4)
-      bundler (~> 2.0)
-      diff-lcs (~> 1.4)
-      jaro_winkler (~> 1.6, >= 1.6.1)
-      kramdown (~> 2.3)
-      kramdown-parser-gfm (~> 1.1)
-      logger (~> 1.6)
-      observer (~> 0.1)
-      ostruct (~> 0.6)
-      parser (~> 3.0)
-      prism (~> 1.4)
-      rbs (>= 3.6.1, <= 4.0.0.dev.4)
-      reverse_markdown (~> 3.0)
-      rubocop (~> 1.76)
-      thor (~> 1.0)
-      tilt (~> 2.0)
-      yard (~> 0.9, >= 0.9.24)
-      yard-activesupport-concern (~> 0.0)
-      yard-solargraph (~> 0.1)
     stackprof (0.2.27)
     stringio (3.1.7)
-    thor (1.4.0)
-    tilt (2.6.1)
     timecop (0.9.10)
     tryouts (3.6.0)
       concurrent-ruby (~> 1.0)
@@ -205,10 +171,6 @@ GEM
     unicode-emoji (4.1.0)
     uri-valkey (1.4.0)
     yard (0.9.37)
-    yard-activesupport-concern (0.0.1)
-      yard (>= 0.8)
-    yard-solargraph (0.1.0)
-      yard (~> 0.9)
     zeitwerk (2.7.3)
 
 PLATFORMS
@@ -223,11 +185,11 @@ DEPENDENCIES
   rbnacl (~> 7.1, >= 7.1.1)
   redcarpet
   reek
-  rubocop
+  rubocop (~> 1.81.1)
   rubocop-performance
   rubocop-thread_safety
+  ruby-lsp
   ruby-prof
-  solargraph
   stackprof
   timecop
   tryouts (~> 3.6.0)

data/README.md

@@ -280,6 +280,7 @@ Flower.multiget("prose", "tulip", "daisy")
 
 ### Transactional Operations
 
+**Horreum Model Transactions:**
 ```ruby
 user.transaction do |conn|
   conn.set("user:#{user.id}:status", "active")
@@ -287,6 +288,44 @@ user.transaction do |conn|
 end
 ```
 
+**DataType Transactions** (standalone or parent-owned):
+```ruby
+# Recommended: Use DataType methods for clean, automatic key handling
+user.scores.transaction do
+  user.scores.add('level1', 100)
+  user.scores.add('level2', 200)
+end
+
+# Standalone DataType transaction (e.g., session storage)
+session_key = Familia::StringKey.new('session:abc123')
+session_key.transaction do
+  session_key.set(session_data)
+  session_key.expire(3600)  # Atomic: both succeed or both fail
+end
+
+# Advanced: Connection available for low-level Redis commands
+user.scores.transaction do |conn|
+  conn.zadd(user.scores.dbkey, 100, 'level1')
+  conn.hset(user.profile.dbkey, 'status', 'active')
+end
+```
+
+**Pipeline Operations** (batch commands for performance):
+```ruby
+# Recommended: Use DataType methods
+leaderboard.pipelined do
+  leaderboard.add('player1', 500)
+  leaderboard.add('player2', 600)
+  leaderboard.size
+end
+
+# Advanced: Raw Redis commands for fine-grained control
+leaderboard.pipelined do |conn|
+  conn.zadd(leaderboard.dbkey, 500, 'player1')
+  conn.zadd(leaderboard.dbkey, 600, 'player2')
+end
+```
+
 ### Advanced Patterns
 
 **Time-based Expiration:**

data/changelog.d/20251011_012003_delano_159_datatype_transaction_pipeline_support.rst

@@ -0,0 +1,91 @@
+.. Added
+.. -----
+.. New features and capabilities that have been added.
+
+.. Changed
+.. -------
+.. Changes to existing functionality.
+
+.. Deprecated
+.. ----------
+.. Soon-to-be removed features.
+
+.. Removed
+.. -------
+.. Now removed features.
+
+.. Fixed
+.. -----
+.. Bug fixes.
+
+.. Security
+.. --------
+.. Security-related improvements.
+
+Added
+-----
+
+-  **DataType Transaction and Pipeline Support** - DataType objects can now initiate transactions and pipelines independently, enabling atomic operations and batch command execution for both parent-owned and standalone DataType objects. `PR #159 <https://github.com/familia/familia/pull/159>`_
+
+   Key capabilities added:
+
+   * ``transaction`` method for atomic MULTI/EXEC operations on all DataType classes
+   * ``pipelined`` method for batched command execution on all DataType classes
+   * Connection chain pattern with Chain of Responsibility for DataType objects
+   * Two new connection handlers: ``ParentDelegationHandler`` for owned DataTypes and ``StandaloneConnectionHandler`` for independent DataTypes
+   * Enhanced ``direct_access`` method with automatic transaction/pipeline context detection
+   * Shared ``Familia::Connection::Behavior`` module extracting common connection functionality
+
+   This enhancement addresses a critical gap where standalone DataType objects could not guarantee atomicity across multiple operations. A prime example is session storage implementations (similar to Rack::Session stores) where setting session data and expiration must be atomic to prevent memory leaks or security issues. Both parent-owned DataTypes (delegating to parent Horreum objects) and standalone DataTypes now support the full transaction and pipeline API.
+
+   Example usage:
+
+   .. code-block:: ruby
+
+      # Recommended: Use DataType methods for clean, key-free syntax
+      # Parent-owned DataType transaction
+      user.scores.transaction do
+        user.scores.add('level1', 100)
+        user.scores.add('level2', 200)
+      end
+
+      # Standalone DataType transaction (e.g., session storage)
+      session_store = Familia::StringKey.new('session:abc123')
+      session_store.transaction do
+        session_store.set(session_data)
+        session_store.update_expiration(expiration: 3600)
+      end
+
+      # Pipeline for performance optimization
+      leaderboard.pipelined do
+        leaderboard.add('player1', 500)
+        leaderboard.add('player2', 600)
+        leaderboard.size
+      end
+
+      # Advanced: Connection available for low-level Redis commands when needed
+      user.scores.transaction do |conn|
+        conn.zadd(user.scores.dbkey, 100, 'level1')
+        conn.hset(user.profile.dbkey, 'status', 'active')
+      end
+
+Changed
+-------
+
+-  **DataType URI Construction** - DataType objects with ``logical_database`` settings now return clean URIs without custom port information (e.g., ``redis://127.0.0.1/3`` instead of ``redis://127.0.0.1:2525/3``), ensuring consistent URI representation across the library.
+
+-  **Horreum::Connection Refactored** - The ``Horreum::Connection`` module now includes ``Familia::Connection::Behavior``, eliminating code duplication by sharing URI normalization and connection creation methods between Horreum and DataType. This refactoring improves maintainability while preserving all existing functionality.
+
+AI Assistance
+-------------
+
+This feature was implemented with significant AI assistance from Claude (Anthropic). The AI helped with:
+
+* Architectural design of the connection chain pattern for DataType objects
+* Implementation of the shared Behavior module to extract common functionality
+* Creation of DataType-specific connection handlers (ParentDelegationHandler, StandaloneConnectionHandler)
+* Comprehensive test coverage including transaction and pipeline integration tests
+* Documentation and changelog preparation
+* Debugging and fixing URI formatting edge cases
+
+The implementation preserves backward compatibility (all 2,216 existing tests pass) while adding 27 new tests specifically for DataType transaction and pipeline support.

data/changelog.d/20251011_203905_delano_next.rst

@@ -0,0 +1,30 @@
+.. A new scriv changelog fragment.
+..
+.. Uncomment the section that is right (remove the leading dots).
+.. For top level release notes, leave all the headers commented out.
+..
+Added
+-----
+
+- Automatic validation in ``add_to_*`` methods for instance-scoped unique indexes. Previously required manual ``guard_unique_*!`` call before adding to index; now validation happens automatically with clear error messages on duplicate detection.
+
+- Transaction detection in ``save()`` method. Raises ``Familia::OperationModeError`` when ``save()`` is called within an existing transaction, since unique index guards need to read current values which is not possible inside MULTI/EXEC blocks.
+
+Changed
+-------
+
+- Instance-scoped unique index ``add_to_*`` methods now automatically validate uniqueness before adding to parent's index. This matches modern ORM expectations where constraint validation happens implicitly during mutation operations.
+
+Documentation
+-------------
+
+- Enhanced ``save()`` method documentation to explain transaction restrictions and unique index validation flow.
+
+- Updated ``UniqueIndexGenerators`` documentation to clarify that ``add_to_*`` methods perform automatic validation.
+
+- Added comprehensive test suite (21 test cases) demonstrating automatic validation behavior, transaction detection, and error handling patterns.
+
+AI Assistance
+-------------
+
+- Claude Sonnet 4.5 assisted with implementation design, test coverage, and documentation for automatic unique index validation and transaction detection features.

data/changelog.d/20251011_212633_delano_next.rst

@@ -0,0 +1,13 @@
+
+Changed
+-------
+
+- **IndexingRelationship**: Added explicit ``:within`` field to preserve the original DSL parameter, replacing brittle ``target_class`` equality checks with clearer ``within.nil?`` checks. This makes the distinction between class-level and instance-scoped indexes more explicit and prevents potential issues with inheritance scenarios.
+
+AI Assistance
+-------------
+
+- Design review and architectural analysis by Claude Code (Sonnet 4.5) via second-opinion agent, identifying brittleness in class comparison logic and recommending explicit storage of the ``within`` parameter.
+- Implementation of the ``within`` field addition across IndexingRelationship, generators, and usage sites by Claude Code.
+- All tests verified passing with no behavioral changes.
+..

data/changelog.d/20251011_221253_delano_next.rst

@@ -0,0 +1,26 @@
+.. Internal terminology refactoring for indexing relationships
+
+Changed
+-------
+
+- **Indexing terminology refactoring**: Renamed internal field ``target_class`` to ``scope_class`` throughout the indexing system to better reflect the semantic role. The ``within:`` parameter in index declarations refers to a "scope" that provides a uniqueness boundary, not a "target" or "parent" relationship. This change affects internal code, comments, and documentation but has no user-facing API impact.
+
+  - Renamed ``IndexingRelationship.target_class`` to ``scope_class``
+  - Updated method parameter names from ``target_instance`` to ``scope_instance``
+  - Replaced "parent" terminology with "scope" in comments and documentation
+  - Updated cheatsheets to reflect correct terminology
+
+  **Rationale**: The term "target" created semantic confusion because it has different meanings in participation relationships (where objects target a collection owner) versus indexing relationships (where objects use a scope for uniqueness). The term "parent" was misleading because it implied an ownership relationship that doesn't exist. "Scope" accurately describes the role: Company provides the scope within which badge_number must be unique.
+
+Documentation
+-------------
+
+- Updated indexing and relationships cheatsheets with improved terminology explanations
+- Added explicit clarification of scope vs target vs parent semantics
+
+AI Assistance
+-------------
+
+- Claude Code (Sonnet 4.5) provided second-opinion analysis on terminology confusion
+- Assisted with systematic refactoring of variable names, comments, and documentation
+- Helped identify all occurrences requiring updates across codebase and tests

data/docs/guides/feature-expiration.md

@@ -66,7 +66,7 @@ session.default_expiration  # => 900.0
 session.update_expiration  # Uses instance expiration (15 minutes)
 
 # Or specify expiration inline
-session.update_expiration(default_expiration: 5.minutes)
+session.update_expiration(expiration: 5.minutes)
 ```
 
 ## Advanced Usage
@@ -112,7 +112,7 @@ customer = Customer.new(customer_id: 'cust_123')
 customer.save
 
 # This will set TTL on the main object AND all related fields
-customer.update_expiration(default_expiration: 12.hours)
+customer.update_expiration(expiration: 12.hours)
 # Sets expiration on:
 # - customer:cust_123 (main hash)
 # - customer:cust_123:recent_orders (list)
@@ -137,9 +137,9 @@ class AnalyticsEvent < Familia::Horreum
     save
 
     if should_expire?
-      update_expiration(default_expiration: 1.hour)
+      update_expiration(expiration: 1.hour)
     else
-      update_expiration(default_expiration: 30.days)
+      update_expiration(expiration: 30.days)
     end
   end
 end
@@ -200,7 +200,7 @@ class SessionCleanupJob
     # Extend expiration for active sessions
     UserSession.all.each do |session|
       if session.recently_active?
-        session.update_expiration(default_expiration: 30.minutes)
+        session.update_expiration(expiration: 30.minutes)
       end
     end
   end
@@ -225,7 +225,7 @@ class SessionExpirationMiddleware
       session = UserSession.find(session_token)
 
       # Extend session TTL on each request
-      session&.update_expiration(default_expiration: 30.minutes)
+      session&.update_expiration(expiration: 30.minutes)
     end
 
     @app.call(env)
@@ -268,14 +268,14 @@ end
 class SessionManager
   def self.extend_all_sessions(new_ttl)
     UserSession.all.each do |session|
-      session.update_expiration(default_expiration: new_ttl)
+      session.update_expiration(expiration: new_ttl)
     end
   end
 
   def self.expire_inactive_sessions
     UserSession.all.select(&:inactive?).each do |session|
       # Set very short TTL for inactive sessions
-      session.update_expiration(default_expiration: 5.minutes)
+      session.update_expiration(expiration: 5.minutes)
     end
   end
 
@@ -306,7 +306,7 @@ class DataRetentionService
       model_class = data_type.to_s.pascalize.constantize
 
       model_class.all.each do |record|
-        record.update_expiration(default_expiration: ttl)
+        record.update_expiration(expiration: ttl)
       end
     end
   end
@@ -323,7 +323,7 @@ DataRetentionService.apply_retention_policies
 ```ruby
 # ❌ Inefficient: Multiple round trips
 sessions.each do |session|
-  session.update_expiration(default_expiration: 1.hour)
+  session.update_expiration(expiration: 1.hour)
 end
 
 # ✅ Efficient: Batch operations
@@ -357,7 +357,7 @@ class ResilientSession < Familia::Horreum
     return unless exists?
 
     begin
-      update_expiration(default_expiration: new_ttl)
+      update_expiration(expiration: new_ttl)
     rescue => e
       # Log error but don't crash the application
       Familia.logger.warn "Failed to update expiration for #{dbkey}: #{e.message}"
@@ -377,7 +377,7 @@ Familia.debug = true
 
 session = UserSession.new(session_token: 'debug_session')
 session.save
-session.update_expiration(default_expiration: 5.minutes)
+session.update_expiration(expiration: 5.minutes)
 # Logs will show:
 # [update_expiration] Expires session:debug_session in 300.0 seconds
 ```
@@ -388,11 +388,11 @@ session.update_expiration(default_expiration: 5.minutes)
 ```ruby
 session = UserSession.new
 # ❌ Won't work - object must be saved first
-session.update_expiration(default_expiration: 1.hour)
+session.update_expiration(expiration: 1.hour)
 
 # ✅ Correct - save first, then expire
 session.save
-session.update_expiration(default_expiration: 1.hour)
+session.update_expiration(expiration: 1.hour)
 ```
 
 **2. Related Fields Not Expiring**
@@ -459,7 +459,7 @@ RSpec.describe UserSession do
 
     it "applies TTL to database key" do
       session.save
-      session.update_expiration(default_expiration: 10.minutes)
+      session.update_expiration(expiration: 10.minutes)
 
       ttl = session.ttl
       expect(ttl).to be > 500  # Should be close to 600 seconds
@@ -470,7 +470,7 @@ RSpec.describe UserSession do
       session.save
       session.activity_log.push('login')  # Assume activity_log is a list
 
-      session.update_expiration(default_expiration: 5.minutes)
+      session.update_expiration(expiration: 5.minutes)
 
       # Both main object and related fields should have TTL
       expect(session.ttl).to be > 250
@@ -542,7 +542,7 @@ class TTLHealthCheck
         expired_count += 1
       elsif ttl < 300  # Less than 5 minutes remaining
         # Extend TTL for active sessions
-        session.update_expiration(default_expiration: 30.minutes) if session.active?
+        session.update_expiration(expiration: 30.minutes) if session.active?
       end
     end
 
@@ -565,7 +565,7 @@ class RobustSessionManager
     # Check if session exists and hasn't expired
     if session&.ttl&.positive?
       # Extend TTL on access
-      session.update_expiration(default_expiration: 30.minutes)
+      session.update_expiration(expiration: 30.minutes)
       session
     else
       # Create new session if old one expired