familia 2.0.0.pre19 → 2.0.0.pre22

data/CHANGELOG.rst

@@ -7,61 +7,222 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
-.. _changelog-2.0.0.pre19:
+.. _changelog-2.0.0.pre22:
+
+2.0.0.pre22 — 2025-12-03
+========================
+
+- **ExternalIdentifier Format Flexibility**: The `external_identifier` feature now supports customizable format templates via the `format` option (e.g., `format: 'cust_%{id}'` or `format: 'api-%{id}'`). Default format remains `'ext_%{id}'`. Provides complete flexibility for various ID formatting needs including different prefixes, separators, URL paths, or no prefix at all.
 
-2.0.0.pre19 — 2025-10-11
-=========================
+- **Participation Relationships with Symbol/String Target Classes**: Fixed four bugs that occurred when calling `participates_in` with Symbol/String target class instead of Class object. Issues included NoMethodError during relationship definition (private method call), failures in `current_participations` (undefined `familia_name`), errors in `target_class_config_name` (undefined `config_name`), and confusing error messages for load order issues. All now properly resolve using `Familia.resolve_class` API with clear error messages for common issues.
+
+- **Pipelined Bulk Loading Methods**: New `load_multi` and `load_multi_by_keys` methods enable efficient bulk object loading using Redis pipelining, reducing network round trips from N×2 commands to a single batch (up to 2× performance improvement). Methods maintain nil-return contract for missing objects and preserve input order.
+
+- **Optional EXISTS Check Optimization**: The `find_by_dbkey` and `find_by_identifier` methods now accept `check_exists:` parameter (default: `true`) to optionally skip EXISTS check, reducing Redis commands from 2 to 1 per object. Maintains backwards compatibility and same nil-return behavior.
+
+- **Parameter Consistency**: The `suffix` parameter in `find_by_identifier` is now a keyword parameter (was optional positional) for consistency with `check_exists`, following Ruby conventions.
 
 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:
+- Bidirectional reverse collection methods for ``participates_in`` with ``_instances`` suffix (e.g., ``user.project_team_instances``, ``user.project_team_ids``). Supports union behavior for multiple collections and custom naming via ``as:`` parameter. Closes #179.
+
+Changed
+-------
+
+- All Ruby files now include consistent headers with ``frozen_string_literal: true`` pragma for improved performance and memory efficiency. Headers follow the format: filename comment, blank comment line, frozen string literal pragma. Executable scripts properly place shebang first.
+
+- Standardized DataType serialization to use JSON encoding for type preservation, matching Horreum field behavior. All primitive values (Integer, Boolean, String, Float, Hash, Array, nil) are now consistently serialized through JSON, ensuring types are preserved across the Redis storage boundary. Familia object references continue to use identifier extraction. Issue #190.
+
+Fixed
+-----
+
+- Fixed critical race condition in mutex initialization for connection chain lazy loading. The mutex itself was being lazily initialized with ``||=``, which is not atomic and could result in multiple threads creating different mutex instances, defeating synchronization. Changed to eager initialization via ``Connection.included`` hook. (`lib/familia/horreum/connection.rb`)
+
+- Fixed critical race condition in mutex initialization for logger lazy loading. Similar to connection chain issue, the logger mutex was lazily initialized with ``||=``. Changed to eager initialization at module definition time. (`lib/familia/logging.rb`)
+
+- Fixed logger assignment atomicity issue where ``Familia.logger=`` set ``DatabaseLogger.logger`` outside the mutex synchronization block, potentially causing ``Familia.logger`` and ``DatabaseLogger.logger`` to be temporarily out of sync during concurrent access. Moved ``DatabaseLogger.logger`` assignment inside the synchronization block. (`lib/familia/logging.rb`)
+
+- Added explicit return statement to ``Familia.logger`` method for robustness against future refactoring. (`lib/familia/logging.rb`)
 
-   * ``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
+AI Assistance
+-------------
 
--  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
+- Claude Code (Opus 4, Sonnet 4.5): Implementation of bidirectional participation relationships, external identifier format flexibility, bulk loading optimization with pipelining, race condition fixes in mutex initialization, frozen string literal pragma automation (308 files), and DataType serialization standardization. Comprehensive test coverage and documentation throughout.
+
+.. _changelog-2.0.0.pre21:
+
+2.0.0.pre21 — 2025-10-21
+========================
+
+Added
+-----
+
+- Pipeline Routing Investigation: Created 7 diagnostic testcases in ``try/investigation/pipeline_routing/`` to investigate suspected middleware routing issue. Investigation revealed single-command pipelines don't have ' | ' separator (expected Array#join behavior), confirming no routing bug exists. Full analysis documented in ``CONCLUSION.md``.
 
 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**: Duration measurements now use integer microseconds instead of milliseconds. Instrumentation hooks and logging output have changed format:
+
+  - ``Familia.on_command`` receives ``duration`` in microseconds (was ``duration_ms`` in milliseconds)
+  - ``Familia.on_pipeline`` receives ``duration`` in microseconds (was ``duration_ms`` in milliseconds)
+  - ``Familia.on_lifecycle`` uses ``duration`` key in microseconds (was ``duration_ms`` in milliseconds)
+  - Log messages show ``duration=1234`` (microseconds) instead of ``duration_ms=1.23`` (milliseconds)
+
+- Migration: Convert to milliseconds when needed: ``duration / 1000.0``
+
+Fixed
+-----
+
+- Connection Chain Race Condition: Fixed race condition in connection chain initialization where concurrent calls could create multiple instances. Added thread-safe protection to ensure proper singleton behavior.
+
+- Thread Safety Test Suite: Corrected test assertions to properly verify thread safety invariants.
+
+
+AI Assistance
+-------------
+
+- Claude Code assisted with analyzing test failures, identifying and fixing the connection chain race condition with Mutex protection, correcting test assertions to verify proper thread safety invariants, and creating diagnostic testcases to investigate pipeline routing behavior.
+
+
+
+.. _changelog-2.0.0.pre20:
+
+2.0.0.pre20 — 2025-10-20
+========================
+
+Added
+-----
+
+- **Instrumentation Hooks**: New ``Familia::Instrumentation`` module provides hooks for Redis commands, pipeline operations, lifecycle events, and errors. Applications can now register callbacks for audit trails and performance monitoring.
+
+- **DatabaseLogger Structured Mode**: Added ``DatabaseLogger.structured_logging`` mode that outputs Redis commands with structured key=value context instead of formatted string output.
+
+- **DatabaseLogger Sampling**: Added ``DatabaseLogger.sample_rate`` for controlling log volume in high-traffic scenarios. Set to 0.1 for 10% sampling, 0.01 for 1% sampling, or nil to disable. Command capture for testing remains unaffected.
+
+- **Lifecycle Logging**: Horreum initialize, save, and destroy operations now log with timing and structured context when ``FAMILIA_DEBUG`` is enabled.
+
+- **Operational Logging**: TTL operations and serialization errors now include structured context for better debugging.
+
+Changed
+-------
+
+- Refactored ``save`` and ``save_if_not_exists!`` to use shared helper methods (``prepare_for_save`` and ``persist_to_storage``) to eliminate code duplication and ensure consistency. Both methods now follow the same preparation and persistence logic, differing only in their concurrency control patterns (simple transaction vs. optimistic locking with WATCH).
+
+- **Structured Logging**: Replaced internal logging methods (``Familia.ld``, ``Familia.le``) with structured logging methods (``Familia.debug``, ``Familia.info``, ``Familia.error``) that support keyword context for operational observability.
+
+Removed
+-------
 
--  **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)
+- **Internal Methods**: Removed ``Familia.ld`` and ``Familia.le`` internal logging methods. These were never part of the public API.
 
 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
+- Fixed ``save_if_not_exists!`` to perform the same operations as ``save`` when creating new objects. Previously, ``save_if_not_exists!`` omitted timestamp updates (``created``/``updated``), unique index validation (``guard_unique_indexes!``), and adding to the instances collection. Now both methods produce identical results when saving a new object, with ``save_if_not_exists`` only differing in its conditional existence check.
+
+- Fixed ``save_if_not_exists!`` return value to correctly return ``true`` when successfully saving new objects. Previously returned ``false`` despite successful persistence due to incorrect handling of transaction result.
 
 Documentation
 -------------
 
--  Added comprehensive parameter documentation for database command methods including return value specifications and usage examples
+- Streamlined inline documentation for ``save``, ``save_if_not_exists!``, and ``save_if_not_exists`` methods to be more concise, internally consistent, and non-redundant. Each method's documentation now stands on its own with clear, focused descriptions.
 
 AI Assistance
 -------------
 
-This feature was implemented with AI assistance from Claude Sonnet 4.5, Opus 4.1 (Anthropic).
+- Claude Code identified the inconsistencies between ``save`` and ``save_if_not_exists!`` methods, implemented the fixes, refactored both methods to extract shared logic into private helper methods (``prepare_for_save`` and ``persist_to_storage``), and updated the documentation to be more concise and internally consistent.
+
+
+
+This implementation was completed with significant AI assistance from Claude (Anthropic), including:
+
+- Architecture design for the instrumentation hook system
+- Implementation of structured logging methods with backward-compatible signatures
+- Integration of hooks into DatabaseLogger middleware
+- Bulk replacement of 51 logging method calls across 21 files
+- Comprehensive code review and bug fixes (RedisClient::Config object vs hash handling)
+- Documentation and changelog creation
+
+The AI provided discussion, rubber ducking, code generation, testing strategy, and documentation throughout the implementation process.
+
+Developer Notes
+---------------
+
+This is a clean break for v2.0 with no deprecation warnings, as the removed methods were internal-only. Applications using the public API are unaffected.
+
+**Migration**: No action required for external users. Internal development references to ``Familia.ld`` should use ``Familia.debug``, and ``Familia.le`` should use ``Familia.error``.
+
+**New Capabilities**: Applications can now register instrumentation hooks for operational observability:
+
+.. code-block:: ruby
+
+   # Enable structured logging with 10% sampling for production
+   Familia.logger = Rails.logger
+   DatabaseLogger.structured_logging = true
+   DatabaseLogger.sample_rate = 0.1  # Log 10% of commands
+
+   # Register hooks for audit trails
+   Familia.on_command do |cmd, duration_ms, context|
+     AuditLog.create!(
+       event: 'redis_command',
+       command: cmd,
+       duration_ms: duration_ms,
+       user_id: RequestContext.current_user_id
+     )
+   end
 
-* 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
+   Familia.on_lifecycle do |event, instance, context|
+     case event
+     when :save
+       AuditLog.create!(event: 'object_saved', object_id: instance.identifier)
+     when :destroy
+       AuditLog.create!(event: 'object_destroyed', object_id: instance.identifier)
+     end
+   end
+
+.. _changelog-2.0.0.pre19:
+
+2.0.0.pre19 — 2025-10-13
+========================
+
+Added
+-----
+
+-  **DataType Transaction and Pipeline Support** - DataType objects can now initiate transactions and pipelines independently, enabling atomic operations and batch command execution. `PR #159 <https://github.com/familia/familia/pull/159>`_
+
+   * ``transaction`` and ``pipelined`` methods for all DataType classes
+   * Connection chain pattern with ``ParentDelegationHandler`` and ``StandaloneConnectionHandler``
+   * Enhanced ``direct_access`` method with automatic context detection
+   * Shared ``Familia::Connection::Behavior`` module for common functionality
+
+-  **Automatic Unique Index Validation** - Instance-scoped unique indexes now validate automatically in ``add_to_*`` methods, with transaction detection to prevent ``save()`` calls within MULTI/EXEC blocks
+
+Changed
+-------
+
+-  **Connection Architecture** - Refactored to share ``Familia::Connection::Behavior`` between Horreum and DataType, with cleaner URI construction for logical databases
+
+-  **Indexing Terminology** - Renamed internal ``target_class`` to ``scope_class`` throughout to clarify semantic role. Added explicit ``:within`` field to IndexingRelationship for clearer instance-scoped index handling
+
+Fixed
+-----
+
+-  URI formatting for DataType objects with logical database settings
+-  Transaction detection and validation flow for unique index operations
+
+Documentation
+-------------
+
+-  Enhanced ``save()`` method documentation with transaction restrictions
+-  Updated indexing and relationship cheatsheets with improved terminology
+-  Added comprehensive test coverage (48 new tests) for transactions, pipelines, and validation
+
+AI Assistance
+-------------
+
+This release was implemented with assistance from Claude (Anthropic) for architectural design, test coverage, and systematic refactoring of terminology across the codebase.
 
 
 .. _changelog-2.0.0.pre18:
@@ -118,7 +279,7 @@ Documentation
 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.
+- Claude Code (claude-sonnet-4-5) provided implementation guidance, identified the ``initialize_with_keyword_args`` falsy value bug, wrote test coverage, 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.
 
@@ -132,19 +293,17 @@ AI Assistance
 Added
 -----
 
-- **SortedSet#add**: Full ZADD option support (NX, XX, GT, LT, CH) for atomic conditional operations and accurate change tracking. This enables proper index management with timestamp preservation, update-only operations, conditional score updates, and analytics tracking. Closes issue #135.
+- **SortedSet#add** - Full ZADD option support (NX, XX, GT, LT, CH) for atomic conditional operations and accurate change tracking. Closes #135
 
 Fixed
 -----
 
-- Restored objid provenance tracking when loading objects from Redis. The ``ObjectIdentifier`` feature now infers the generator type (:uuid_v7, :uuid_v4, :hex) from the objid format, enabling dependent features like ``ExternalIdentifier`` to derive external identifiers from loaded objects. PR #131
+- Restored objid provenance tracking when loading objects from Redis, enabling dependent features to derive external identifiers. PR #131
 
 AI Assistance
 -------------
 
-- Claude Code assisted with implementing the ``infer_objid_generator`` method and updating the setter logic in ``lib/familia/features/object_identifier.rb``.
-
-- Claude Code assisted with Redis ZADD option semantics research, mutual exclusivity validation design, comprehensive test case matrix creation (50+ test cases), and YAML documentation examples.
+- Claude (Anthropic) assisted with objid generator inference implementation and ZADD option validation design.
 
 .. _changelog-2.0.0.pre16:
 
@@ -154,57 +313,29 @@ AI Assistance
 Added
 -----
 
-- Added support for instance-scoped unique indexes via ``unique_index`` with ``within:`` parameter. Issue #128
-
-  Example: ``unique_index :badge_number, :badge_index, within: Company`` creates per-company unique badge lookups using HashKey DataType.
+- **Instance-scoped unique indexes** via ``unique_index`` with ``within:`` parameter for per-scope unique lookups. Issue #128
 
 Changed
 -------
 
-- **BREAKING**: Consolidated relationships API by replacing ``tracked_in`` and ``member_of`` with unified ``participates_in`` method. PR #110
-- **BREAKING**: Renamed ``context_class`` terminology to ``target_class`` throughout relationships module for clarity
-- **BREAKING**: Removed ``tracking.rb`` and ``membership.rb`` modules, merged functionality into ``participation.rb``
-- **BREAKING**: Updated method names and configuration keys to use ``target`` instead of ``context`` terminology
-- Added ``bidirectional`` parameter to ``participates_in`` to control generation of convenience methods (default: true)
-- Added support for different collection types (sorted_set, set, list) in unified ``participates_in`` API
-- Renamed ``class_tracked_in`` to ``class_participates_in`` for consistency
-
-- Renamed DataType classes to avoid Ruby namespace confusion: ``Familia::String`` → ``Familia::StringKey``, ``Familia::List`` → ``Familia::ListKey``
-- Added dual registration for both traditional and explicit method names (``string``/``stringkey``, ``list``/``listkey``)
-- Updated ``Counter`` and ``Lock`` to inherit from ``StringKey`` instead of ``String``
+- **BREAKING**: Consolidated relationships API - replaced ``tracked_in`` and ``member_of`` with unified ``participates_in`` method. PR #110
 
-- **BREAKING:** Renamed indexing API methods for clarity. Issue #128
+- **BREAKING**: Renamed indexing API methods for clarity. Issue #128
+  - ``class_indexed_by`` → ``unique_index``
+  - ``indexed_by`` → ``multi_index``
+  - Changed ``multi_index`` to use ``UnsortedSet`` instead of ``SortedSet``
 
-  - ``class_indexed_by`` → ``unique_index`` (1:1 field-to-object mapping via HashKey)
-  - ``indexed_by`` → ``multi_index`` (1:many field-to-objects mapping via UnsortedSet)
-  - Parameter ``target:`` → ``within:`` for consistency across both index types
-
-- **BREAKING:** Changed ``multi_index`` to use ``UnsortedSet`` instead of ``SortedSet``. Issue #128
-
-  Multi-value indexes no longer include temporal scoring. This aligns with the design philosophy that indexing is for finding objects by attribute, not ordering them. Sort results in Ruby when needed: ``employees.sort_by(&:hire_date)``
+- **DataType class renaming** to avoid Ruby namespace conflicts: ``Familia::String`` → ``Familia::StringKey``, ``Familia::List`` → ``Familia::ListKey``, etc., with dual registration for compatibility
 
 Documentation
 -------------
 
-- Updated overview documentation to explain dual naming system and namespace safety benefits
-- Enhanced examples to demonstrate both traditional and explicit DataType method naming
-
-- Updated inline module documentation
-    - ``Familia::Features::Relationships::Indexing`` with comprehensive examples, terminology guide, and design philosophy.
-    - ``Familia::Features::Relationships::Participation`` to clarify differences from indexing module.
+- Updated indexing and participation module documentation with comprehensive examples and design philosophy
 
 AI Assistance
 -------------
 
-- Comprehensive analysis of existing ``tracked_in`` and ``member_of`` implementations
-- Design and implementation of unified ``participates_in`` API integrating both functionalities
-- Systematic refactoring of codebase terminology from context to target
-- Complete test suite updates to verify API consolidation and new functionality
-
-- DataType class renaming and dual registration system implementation designed and developed with Claude Code assistance
-- All test updates and documentation enhancements created with AI support
-
-- Architecture design, implementation, test updates, and documentation for indexing API refactoring completed with Claude Code assistance. Issue #128
+- Claude (Anthropic) assisted with relationship API consolidation, DataType renaming, and indexing API refactoring.
 
 .. _changelog-2.0.0.pre14:
 
@@ -214,19 +345,18 @@ AI Assistance
 Changed
 -------
 
-- **BREAKING CHANGE**: Renamed ``Familia::Refinements::TimeUtils`` to ``Familia::Refinements::TimeLiterals`` to better reflect the module's primary purpose of enabling numeric and string values to be treated as time unit literals (e.g., ``5.minutes``, ``"30m".in_seconds``). Functionality remains the same - only the module name has changed. Users must update their refinement usage from ``using Familia::Refinements::TimeUtils`` to ``using Familia::Refinements::TimeLiterals``.
+- **BREAKING**: Renamed ``TimeUtils`` to ``TimeLiterals`` to better reflect module purpose. PR #100
 
 Fixed
 -----
 
-- Fixed ExternalIdentifier HashKey method calls by replacing incorrect ``.del()`` calls with ``.remove_field()`` in three critical locations: extid setter (cleanup old mapping when changing value), find_by_extid (cleanup orphaned mapping when object not found), and destroy! (cleanup mapping when object is destroyed). Added comprehensive test coverage for all scenarios to prevent regression. PR #100
+- **CRITICAL**: Fixed Redis connection persistence for standalone DataType objects. PR #107
+- Fixed ExternalIdentifier HashKey cleanup using correct ``remove_field()`` method. PR #100
 
 AI Assistance
 -------------
 
-- Claude Code helped rename TimeUtils to TimeLiterals throughout the codebase, including module name, file path, all usage references, and updating existing documentation.
-- Gemini 2.5 Flash wrote the inline docs for TimeLiterals based on a discussion re: naming rationale.
-- Claude Code fixed the ExternalIdentifier HashKey method bug, replacing incorrect ``.del()`` calls with proper ``.remove_field()`` calls, and implemented test coverage for the affected scenarios.
+- Claude (Anthropic) and Gemini assisted with TimeLiterals refactoring and ExternalIdentifier fixes.
 
 .. _changelog-2.0.0.pre13:
 
@@ -236,61 +366,39 @@ AI Assistance
 Added
 -----
 
-- **Feature Autoloading System**: Features can now automatically discover and load extension files from your project directories. When you include a feature like ``safe_dump``, Familia searches for configuration files using conventional patterns like ``{model_name}/{feature_name}_*.rb``, enabling clean separation between core model definitions and feature-specific configurations. See ``docs/migrating/v2.0.0-pre13.md`` for migration details.
-
-- **Consolidated autoloader architecture**: Introduced ``Familia::Features::Autoloader`` as a shared utility for consistent file loading patterns across the framework, supporting both general-purpose and feature-specific autoloading scenarios.
-
-- Added ``PER_MONTH`` constant (2,629,746 seconds = 30.437 days) derived from Gregorian year for consistent month calculations.
-- Added ``months``, ``month``, and ``in_months`` conversion methods to Numeric refinement.
-- Added month unit mappings (``'mo'``, ``'month'``, ``'months'``) to TimeLiterals ``UNIT_METHODS`` hash.
+- **Feature Autoloading System** - Features automatically discover and load extension files from project directories using conventional patterns. PR #97
 
-- **Error Handling**: Added ``NotSupportedError`` for invalid serialization mode combinations in encryption subsystem. PR #97
+- **Month calculations** - Added ``PER_MONTH`` constant and month conversion methods to TimeLiterals refinement. Issue #94
 
 Changed
 -------
 
-- Refactored time and numeric extensions from global monkey patches to proper Ruby refinements for better encapsulation and reduced global namespace pollution
-- Updated all internal classes to use refinements via ``using Familia::Refinements::TimeLiterals`` statements
-- Added centralized ``RefinedContext`` module in test helpers to support refinement testing in tryouts files
-
-- Updated ``PER_YEAR`` constant to use Gregorian year (31,556,952 seconds = 365.2425 days) for calendar consistency.
-
-- **Performance**: Replaced stdlib JSON with OJ gem for 2-5x faster JSON operations and reduced memory allocation. All existing code remains compatible through mimic_JSON mode. PR #97
-
-- **Encryption**: Enhanced serialization safety for encrypted fields with improved ConcealedString handling across different JSON processing modes. Strengthened protection against accidental data exposure during serialization. PR #97
+- **Performance** - Replaced stdlib JSON with OJ gem for 2-5x faster operations. PR #97
+- Refactored time/numeric extensions from global monkey patches to Ruby refinements
+- Enhanced encryption serialization safety with improved ConcealedString handling
 
 Fixed
 -----
 
-- Fixed byte conversion logic in ``to_bytes`` method to correctly handle exact 1024-byte boundaries (``size >= 1024`` instead of ``size > 1024``)
-- Resolved refinement testing issues in tryouts by implementing ``eval``-based code execution within refined contexts
-
-- Fixed TimeLiterals refinement ``months_old`` and ``years_old`` methods returning incorrect values (raw seconds instead of months/years). The underlying ``age_in`` method now properly handles ``:months`` and ``:years`` units. Issue #94.
-- Fixed calendar consistency issue where ``12.months != 1.year`` by updating ``PER_YEAR`` to use Gregorian year (365.2425 days) and defining ``PER_MONTH`` as ``PER_YEAR / 12``.
+- Fixed ``months_old`` and ``years_old`` methods returning raw seconds instead of proper units. Issue #94
+- Fixed byte conversion boundary logic (``size >= 1024`` instead of ``size > 1024``)
+- Fixed calendar consistency where ``12.months != 1.year`` by using Gregorian year
 
 Security
 --------
 
-- **Encryption**: Improved concealed value protection during JSON serialization, ensuring encrypted data remains properly protected across all OJ serialization modes. PR #97
+- Improved concealed value protection during JSON serialization across all OJ modes. PR #97
 
 Documentation
 -------------
 
-- **Feature System Autoloading Guide**: Added comprehensive guide at ``docs/guides/Feature-System-Autoloading.md`` explaining the new autoloading system, including file naming conventions, directory patterns, and usage examples.
-- **Enhanced API documentation**: Added detailed YARD documentation for autoloading modules and methods.
+- Added Feature System Autoloading guide with conventions and usage examples
+- Enhanced YARD documentation for autoloading modules
 
 AI Assistance
 -------------
 
-- Provided comprehensive analysis of Ruby refinement scoping issues and designed the eval-based testing solution
-- Assisted with refactoring global extensions to proper refinements while maintaining backward compatibility
-- Helped debug and fix the byte conversion boundary condition bug
-
-- Significant AI assistance in architectural design and implementation of the feature-specific autoloading system, including pattern matching logic, Ruby introspection methods, and comprehensive debugging of edge cases and thread safety considerations.
-
-- Claude Code assisted with implementing the fix for broken ``months_old`` and ``years_old`` methods in the TimeLiterals refinement, including analysis, implementation, testing, and documentation.
-
-- Performance optimization research and OJ gem integration strategy, including compatibility analysis and testing approach for seamless stdlib JSON replacement. PR #97
+- Claude (Anthropic) assisted with refinement refactoring, autoloading system design, and OJ integration.
 
 2.0.0.pre12 — 2025-09-04
 ========================

data/CLAUDE.md

@@ -53,7 +53,7 @@ Add changelog fragment with each user-facing or documented change (optional but
 ### Known Issues & Quirks
 - **Reserved Keywords**: Cannot use `ttl`, `db`, `valkey`, `redis` as field names - use prefixed alternatives
 - **Empty Identifiers**: Cause stack overflow in key generation - validate before operations
-- **Connection Pool Race Conditions**: Thread safety issues under high concurrency
+- **Lazy Initialization Races**: Connection chains and field collections use lazy initialization without synchronization (generally safe due to Ruby GIL, but not guaranteed)
 
 ### Debugging
 - **Database command logging**: You can request real-time Database command monitoring from the user
@@ -191,3 +191,30 @@ end
 **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.
+
+## Thread Safety Considerations
+
+### Current Thread Safety Status (as of 2025-10-21)
+
+Familia has **good thread safety** for standard multi-threaded environments:
+
+### Testing Thread Safety
+
+Thread safety tests are available in `try/thread_safety/`:
+- **100% passing** (56/56 tests)
+- **CyclicBarrier pattern** for maximum contention testing
+- **Test execution**: ~300ms for full suite with 1,000+ concurrent operations
+- **Production monitoring**: 10/10 monitoring tests passing
+
+Run thread safety tests:
+```bash
+bundle exec try --agent try/thread_safety/
+bundle exec try --agent try/unit/thread_safety_monitor_try.rb
+```
+
+### Best Practices for Thread-Safe Usage
+
+1. **Configure Once at Startup**: Module-level configuration should be set before threads spawn
+2. **Use Immutable DataTypes**: Leverage the fact that DataType instances are frozen
+3. **Test Under Concurrency**: Use the patterns in `try/thread_safety/` to verify thread safety
+4. **Enable Production Monitoring**: Use `Familia.start_monitoring!` to track contention in production

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
   gem 'ruby-prof'
   gem 'stackprof'
   gem 'timecop', require: false
-  gem 'tryouts', '~> 3.6.0', require: false
+  gem 'tryouts', '~> 3.7.1', require: false
 end
 
 group :development, :test do

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre19)
+    familia (2.0.0.pre22)
       benchmark (~> 0.4)
+      concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)
       csv (~> 3.3)
       logger (~> 1.7)
@@ -21,7 +22,7 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
     csv (3.3.5)
-    date (3.4.1)
+    date (3.5.0)
     debug (1.11.0)
       irb (~> 1.10)
       reline (>= 0.3.8)
@@ -55,11 +56,11 @@ GEM
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
-    erb (5.0.2)
+    erb (5.1.3)
     ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
     io-console (0.8.1)
-    irb (1.15.2)
+    irb (1.15.3)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
@@ -67,7 +68,7 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
+    minitest (5.26.0)
     oj (3.16.11)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
@@ -78,10 +79,10 @@ GEM
       racc
     pastel (0.8.0)
       tty-color (~> 0.5)
-    pp (0.6.2)
+    pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.5.2)
+    prism (1.6.0)
     psych (5.2.6)
       date
       stringio
@@ -91,9 +92,10 @@ GEM
       ffi (~> 1)
     rbs (3.9.5)
       logger
-    rdoc (6.14.2)
+    rdoc (6.15.1)
       erb
       psych (>= 4.0.0)
+      tsort
     redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
@@ -109,19 +111,19 @@ GEM
     reline (0.6.2)
       io-console (~> 0.5)
     rexml (3.4.1)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
+    rspec-support (3.13.6)
     rubocop (1.81.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -154,15 +156,16 @@ GEM
     stackprof (0.2.27)
     stringio (3.1.7)
     timecop (0.9.10)
-    tryouts (3.6.0)
-      concurrent-ruby (~> 1.0)
+    tryouts (3.7.1)
+      concurrent-ruby (~> 1.0, < 2)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
       prism (~> 1.0)
-      rspec (~> 3.0)
+      rspec (>= 3.0, < 5.0)
       tty-cursor (~> 0.7)
       tty-screen (~> 0.8)
+    tsort (0.2.0)
     tty-color (0.6.0)
     tty-cursor (0.7.1)
     tty-screen (0.8.2)
@@ -192,8 +195,8 @@ DEPENDENCIES
   ruby-prof
   stackprof
   timecop
-  tryouts (~> 3.6.0)
+  tryouts (~> 3.7.1)
   yard (~> 0.9)
 
 BUNDLED WITH
-   2.6.2
+   2.7.2

data/bin/try

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'try' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tryouts", "try")