familia 2.0.0.pre17 → 2.0.0.pre19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e760a3ff094446126c56a0c2b76fd5bed0f6ff64d8eed89580e19d98a5a9ba66
-  data.tar.gz: 74545b0bbb8c89b06ffd385c1448a95a7808b168686a955155a004b91160dafa
+  metadata.gz: 4250fd7b94da275c6cfe9ebc7515e14fc6bead4bb25597aa5e433bf6c9368727
+  data.tar.gz: 50818f7fce2464d3a4349d4de6a1fd7992900e45d8774f6d6d40d047d71a1842
 SHA512:
-  metadata.gz: cd9cd6c374f24859279125ef05199b0dfdac51f7cccdf2bcdf0489c7cca5126ac03d7cab1d54aa8021ce38b286203212514b2b412322ea151b8957fa16c9b445
-  data.tar.gz: 3e44e06249e6daf715ce09b02643b8faf153c85fc2d8451d4cf56d77c5115e5e5fdb1b752acef3f1fdd46f7b7eb7f019213f22850ffe728ec51a05d98ecc5528
+  metadata.gz: bf19202fe2ae0176698fa3ed5b5bd5cb4c1536de2e091a0978d75d8d9964c05cf2285cbcbbdf2d8deb20500a00b83f4fc4d7091e80f08fcaa29840053788da4f
+  data.tar.gz: c7a5810d3c84cca3c8f51e7449d0049c13eae86300f4703b5af9a492329a1a1c6ff01142529351e705f527c4b4f1ad8d07b15e5280b956a3c5a4fa2971ff2b08

data/CHANGELOG.rst

@@ -1,17 +1,129 @@
 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
+========================
+
+Added
+-----
+
+- Added ``Familia.reconnect!`` method to refresh connection pools with current middleware configuration. This solves issues in test suites where middleware (like DatabaseLogger) is enabled after connection pools are created. The method clears the connection chain, increments the middleware version, and clears fiber-local connections, ensuring new connections include the latest middleware. See ``lib/familia/connection/middleware.rb:81-117``.
+
+Changed
+-------
+
+- **BREAKING**: Implemented type-preserving JSON serialization for Horreum field values. Non-string values (Integer, Boolean, Float, nil, Hash, Array) are JSON-encoded for storage and JSON-decoded on retrieval. **Strings are stored as-is without JSON encoding** to avoid double-quoting and maintain Redis baseline simplicity. Type preservation is achieved through smart deserialization: values that parse as JSON restore to their original types, otherwise remain as strings.
+
+- **BREAKING**: Changed default Hash key format from symbols to strings throughout the codebase (``symbolize: false`` default). This eliminates ambiguity with HTTP request parameters and IndifferentHash-style implementations, providing strict adherence to JSON parsing rules and avoiding key duplication issues.
+
+- **BREAKING**: Fixed ``initialize_with_keyword_args`` to properly handle ``false`` and ``0`` values during object initialization. Previously, falsy values were incorrectly skipped due to truthiness checks. Now uses explicit nil checking with ``fetch`` to preserve all non-nil values including ``false`` and ``0``.
+
+- **String serialization now uses JSON encoding**: All string values are JSON-encoded during storage (wrapped in quotes) for consistent type preservation. The lenient deserializer handles both new JSON-encoded strings and legacy plain strings automatically. PR #152
+
+Removed
+-------
+
+- **BREAKING**: Removed ``dump_method`` and ``load_method`` configuration options from ``Familia::Base`` and ``Familia::Horreum::Definition``. JSON serialization is now hard-coded for consistency and type safety. Custom serialization methods are no longer supported.
+
+Fixed
+-----
+
+- Fixed type coercion bugs where Integer fields (e.g., ``age: 35``) became Strings (``"35"``) and Boolean fields (e.g., ``active: true``) became Strings (``"true"``) after database round-trips. All primitive types now maintain their original types through ``find_by_dbkey``, ``refresh!``, and ``batch_update`` operations.
+
+- Fixed ``deserialize_value`` to return all JSON-parsed types instead of filtering to Hash/Array only. This enables proper deserialization of primitive types (Integer, Boolean, Float, String) from Redis storage.
+
+- Added JSON deserialization in ``find_by_dbkey`` using existing ``initialize_with_keyword_args_deserialize_value`` helper method to maintain DRY principles and ensure loaded objects receive properly typed field values rather than raw Redis strings.
+
+- Optimized serialization to avoid double-encoding strings - strings stored directly in Redis as-is, only non-string types use JSON encoding. This reduces storage overhead and maintains Redis's string baseline semantics.
+
+- Fixed encrypted fields with ``category: :encrypted`` appearing in ``to_h()`` output. These fields now correctly set ``loggable: false`` to prevent accidental exposure in logs, APIs, or external interfaces. PR #152
+
+- Fixed middleware registration to only set ``@middleware_registered`` flag when middleware is actually enabled and registered. Previously, calling ``create_dbclient`` before enabling middleware would set the flag to ``true`` without registering anything, preventing later middleware enablement from working. The fix ensures ``register_middleware_once`` only sets the flag after successful registration. See ``lib/familia/connection/middleware.rb:124-146``.
+
+Security
+--------
+
+- Encrypted fields defined via ``field :name, category: :encrypted`` now properly excluded from ``to_h()`` serialization, matching the security behavior of ``encrypted_field``. PR #152
+
+Documentation
+-------------
+
+- Added comprehensive type preservation test suite (``try/unit/horreum/json_type_preservation_try.rb``) with 30 test cases covering Integer, Boolean, String, Float, Hash, Array, nested structures, nil handling, empty strings, zero values, round-trip consistency, ``batch_update``, and ``refresh!`` operations.
+
+AI Assistance
+-------------
+
+- Claude Code (claude-sonnet-4-5) provided implementation guidance, identified the ``initialize_with_keyword_args`` falsy value bug, wrote comprehensive test suite, and coordinated multi-file changes across serialization, management, and base modules.
+
+- Issue analysis, implementation guidance, test verification, and documentation for JSON serialization changes and encrypted field security fix.
+
+- Claude Code (Sonnet 4.5) provided architecture analysis, implementation design, and identified critical issues through the second-opinion agent. Key contributions included recommending the simplified approach without pool shutdown lifecycle management, identifying the race condition risk in clearing ``@middleware_registered``, and suggesting the use of natural pool aging instead of explicit shutdown.
+
 .. _changelog-2.0.0.pre17:
 
 2.0.0.pre17 — 2025-10-03

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
@@ -154,8 +179,15 @@ end
 
 ### Important Implementation Notes
 
-**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended.
-**Serialization**: Uses JSON by default but supports custom `serialize_value`/`deserialize_value` methods.
+**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended. All non-nil values including `false` and `0` are preserved during initialization.
+
+**Serialization**: All field values are JSON-encoded for storage and JSON-decoded on retrieval to preserve Ruby types (Integer, Boolean, String, Float, Hash, Array, nil). This ensures type preservation across the Redis storage boundary. For example:
+- `age: 35` (Integer) stores as `"35"` in Redis and loads back as Integer `35`
+- `active: true` (Boolean) stores as `"true"` in Redis and loads back as Boolean `true`
+- `metadata: {key: "value"}` (Hash) stores as JSON and loads back as Hash with proper types
+
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
+
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
+
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.

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.pre17)
+    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:**
@@ -438,6 +477,19 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### PR Compliance Checks
+
+Pull requests are automatically reviewed by [Qodo Merge](https://qodo.ai) with compliance checks for:
+- **Error Handling** - External API calls and database operations must have proper error handling
+- **Test Coverage** - New features must include tests using the Tryouts framework
+- **Changelog Fragments** - User-facing changes should include a changelog entry
+- **Documentation** - API changes must update documentation
+- **Backward Compatibility** - Breaking changes must be documented
+- **Thread Safety** - Shared state must be properly synchronized
+- **Database Key Naming** - Keys must follow Familia conventions
+
+See [docs/qodo-merge-compliance.md](docs/qodo-merge-compliance.md) for details.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/bin/irb

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-irb -Ilib -r familia -Itry -r helpers/test_helpers
+irb -Ilib -r familia -Itry -r support/helpers/test_helpers

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