familia 2.0.0.pre12 → 2.0.0.pre14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 003a28f3135f0e89f6813e61cf08482350dbff865d2d97971998c714aafcc898
-  data.tar.gz: 6c713c9861043c71d7b2cfc99a37c4522e404ed7461d8dafed5462022735440b
+  metadata.gz: 21e0d1d581a958fbf3492579039d9190764a83fb4add2a47fe3eb23d2d27ef2b
+  data.tar.gz: 9cda237209e910633ddcb9a7605cecb291eb66825de05aacd3bc6522168d220b
 SHA512:
-  metadata.gz: b0e4cb9f390ee0a3e1d83cc94a2248690fe757ce343665ef6e4ea6dbd2c74f8f7d07e352661380f0aac23e91f437315300a409847d28896b58b4ddf567d5e953
-  data.tar.gz: 2ec7616c6b2d64d522d441447ac93e58fe89f35eccd357bfdfc65305fc4324122148e5a3722c4bfd613d1f194fac1e5c0228d72b3774aa0e86e09bcdfe8b90fb
+  metadata.gz: 65cda30c3f3f96c0315c03f200dff37b507474d9a6367c6ce03b899450fd041403263ce6a5bfdb318bc90120c59234190e07548e576a522f92bcb4718dba6a55
+  data.tar.gz: 7a14a093a0fd83bce0e1fd08be41b98c4c418352d1d4210937cc3473f29264e1bf3dae2b671dee18c89b75faeb3a8e38b93ebf55632bba696da8653eb91b4eb3

data/.rubocop_todo.yml

@@ -64,14 +64,13 @@ Naming/BlockForwarding:
     - "lib/familia/data_type/types/list.rb"
     - "lib/familia/data_type/types/sorted_set.rb"
     - "lib/familia/data_type/types/unsorted_set.rb"
-    - "lib/familia/refinements.rb"
+    - "lib/familia/refinements/logger_trace.rb"
 
 # Offense count: 8
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
   Exclude:
-    - "lib/familia/core_ext.rb"
     - "lib/familia/horreum/class_methods.rb"
     - "lib/familia/data_type/types/sorted_set.rb"
     - "lib/familia/data_type/types/unsorted_set.rb"
@@ -107,7 +106,7 @@ Style/ArgumentsForwarding:
     - "lib/familia/data_type/types/list.rb"
     - "lib/familia/data_type/types/sorted_set.rb"
     - "lib/familia/data_type/types/unsorted_set.rb"
-    - "lib/familia/refinements.rb"
+    - "lib/familia/refinements/logger_trace.rb"
 
 # Offense count: 11
 # Configuration parameters: AllowedConstants.

data/CHANGELOG.rst

@@ -0,0 +1,529 @@
+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>`__.
+
+.. raw:: html
+
+   <!--scriv-insert-here-->
+
+.. _changelog-2.0.0.pre14:
+
+2.0.0.pre14 — 2025-09-08
+========================
+
+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``.
+
+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
+
+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.
+
+.. _changelog-2.0.0.pre13:
+
+2.0.0.pre13 — 2025-09-07
+========================
+
+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::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.
+
+- **Error Handling**: Added ``NotSupportedError`` for invalid serialization mode combinations in encryption subsystem. PR #97
+
+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
+
+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``.
+
+Security
+--------
+
+- **Encryption**: Improved concealed value protection during JSON serialization, ensuring encrypted data remains properly protected across all OJ serialization 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.
+
+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
+
+2.0.0.pre12 — 2025-09-04
+========================
+
+Added
+~~~~~
+
+-  Added the ``Familia::VerifiableIdentifier`` module to create and
+   verify identifiers with an embedded HMAC signature. This allows an
+   application to stateless-ly confirm that an identifier was generated
+   by itself, preventing forged IDs from malicious sources.
+
+-  **Scoped VerifiableIdentifier**: Added ``scope`` parameter to
+   ``generate_verifiable_id()`` and ``verified_identifier?()`` methods,
+   enabling cryptographically isolated identifier namespaces for
+   multi-tenant, multi-domain, or multi-environment applications while
+   maintaining full backward compatibility with existing code.
+
+Changed
+~~~~~~~
+
+-  ObjectIdentifier feature now tracks which generator (uuid_v7,
+   uuid_v4, hex, or custom) was used for each objid to provide
+   provenance information for security-sensitive operations.
+
+-  Updated external identifier derivation to normalize objid format
+   based on the known generator type, eliminating format ambiguity
+   between UUID and hex formats.
+
+-  Refactored identifier generation methods for clarity and consistency.
+   Method ``generate_objid`` is now ``generate_object_identifier``, and
+   ``generate_external_identifier`` is now
+   ``derive_external_identifier`` to reflect its deterministic nature.
+
+Removed
+~~~~~~~
+
+-  Removed the ``generate_extid`` class method, which was less secure
+   than the instance-level derivation logic.
+
+Security
+~~~~~~~~
+
+-  Hardened external identifier derivation with provenance validation.
+   ExternalIdentifier now validates that objid values come from the
+   ObjectIdentifier feature before deriving external identifiers,
+   preventing derivation from potentially malicious or unvalidated objid
+   values while maintaining deterministic behavior for legitimate use
+   cases.
+
+-  Improved the security of external identifiers (``extid``) by using
+   the internal object identifier (``objid``) as a seed for a new random
+   value, rather than deriving the ``extid`` directly. This prevents
+   potential information leakage from the internal ``objid``.
+
+Documentation
+~~~~~~~~~~~~~
+
+-  Added detailed YARD documentation for ``VerifiableIdentifier``,
+   explaining how to securely generate and manage the required
+   ``VERIFIABLE_ID_HMAC_SECRET`` key.
+
+AI Assistance
+~~~~~~~~~~~~~
+
+-  Security analysis of external identifier derivation and hardened
+   design approach was discussed and developed with AI assistance,
+   including provenance tracking, validation logic, format
+   normalization, and comprehensive test updates.
+
+-  Implementation of scoped verifiable identifiers was developed with AI
+   assistance to ensure cryptographic security properties and
+   comprehensive test coverage.
+
+2.0.0.pre11 - 2025-09-03
+======================
+
+.. _added-1:
+
+Added
+~~~~~
+
+-  **Enhanced Feature System**: Introduced a hierarchical feature system
+   with ancestry chain traversal for model-specific feature
+   registration. This enables better organization, standardized naming,
+   and automatic loading of project-specific features via the new
+   ``Familia::Autoloader`` module.
+-  **Improved SafeDump DSL**: Replaced the internal
+   ``@safe_dump_fields`` implementation with a cleaner, more robust DSL
+   using ``safe_dump_field`` and ``safe_dump_fields`` methods.
+-  Added ``generate_short_id`` and ``shorten_securely`` utility methods
+   for creating short, secure identifiers, adapted from
+   ``OT::Utils::SecureNumbers``.
+-  For a detailed guide on migrating to the new feature system, see
+   ``docs/migration/v2.0.0-pre11.md``.
+
+.. _changed-1:
+
+Changed
+~~~~~~~
+
+-  External identifier now raises an ``ExternalIdentifierError`` if the
+   model does not have an objid field. Previously: returned nil. In
+   practice this should never happen, since the external_identifier
+   feature declares its dependency on object_identifier.
+-  Moved lib/familia/encryption_request_cache.rb to
+   lib/familia/encryption/request_cache.rb for consistency.
+-  **Simplified ObjectIdentifier Feature Implementation**: Consolidated
+   the ObjectIdentifier feature from two files (~190 lines) to a single
+   file (~140 lines) by moving the ObjectIdentifierFieldType class
+   inline. This reduces complexity while maintaining all existing
+   functionality including lazy generation, data integrity preservation,
+   and multiple generator strategies.
+-  **Renamed Identifier Features to Singular Form**: Renamed
+   ``object_identifier`` → ``object_identifier`` and
+   ``external_identifier`` → ``external_identifier`` for more accurate
+   naming. Added full-length aliases
+   (``object_identifier``/``external_identifier``) alongside the short
+   forms (``objid``/``extid``) for clarity when needed.
+-  **Simplified ExternalIdentifier Feature Implementation**:
+   Consolidated the ExternalIdentifier feature from two files (~240
+   lines) to a single file (~120 lines) by moving the
+   ExternalIdentifierFieldType class inline, following the same pattern
+   as ObjectIdentifier.
+
+Fixed
+~~~~~
+
+-  Fixed external identifier generation returning all zeros for
+   UUID-based objids. The ``shorten_to_external_id`` method now
+   correctly handles both 256-bit secure identifiers and 128-bit UUIDs
+   by detecting input length and applying appropriate bit truncation
+   only when needed.
+
+.. _security-1:
+
+Security
+~~~~~~~~
+
+-  Improved input validation in ``shorten_to_external_id`` method by
+   replacing insecure character count checking with proper bit length
+   calculation and explicit validation. Invalid inputs now raise clear
+   error messages instead of being silently processed incorrectly.
+
+2.0.0-pre10 - 2025-09-02
+======================
+
+.. _added-2:
+
+Added
+~~~~~
+
+-  The ``Familia::Horreum`` initializer now supports creating an object
+   directly from its identifier by passing a single argument (e.g.,
+   ``Customer.new(customer_id)``). This provides a more convenient and
+   intuitive way to instantiate objects from lookups.
+
+-  Automatic indexing and class-level tracking on ``save()`` operations,
+   eliminating the need for manual index updates.
+
+-  Enhanced collection syntax supports the Ruby-idiomatic ``<<``
+   operator for more natural relationship management.
+
+.. _changed-2:
+
+Changed
+~~~~~~~
+
+-  The ``member_of`` relationship is now bidirectional. A single call to
+   ``member.add_to_owner_collection(owner)`` is sufficient to establish
+   the relationship, removing the need for a second, redundant call on
+   the owner object. This fixes bugs where members could be added to
+   collections twice.
+
+-  **BREAKING**: Refactored Familia Relationships API to remove “global”
+   terminology and simplify method generation. (Closes #86)
+
+-  Split ``generate_indexing_instance_methods`` into focused
+   ``generate_direct_index_methods`` and
+   ``generate_relationship_index_methods`` for better separation between
+   direct class-level and relationship-based indexing.
+
+-  Simplified method generation by removing complex global vs parent
+   conditionals.
+
+-  All indexes are now stored at the class level for consistency.
+
+.. _fixed-1:
+
+Fixed
+~~~~~
+
+-  Fixed a bug in the ``class_indexed_by`` feature where finder methods
+   (e.g., ``find_by_email``) would fail to correctly instantiate objects
+   from the index, returning partially-formed objects.
+
+-  Refactored connection handling to properly cache and reuse Redis
+   connections. This eliminates repetitive “Overriding existing
+   connection” warnings and improves performance.
+
+-  Method generation now works consistently for both
+   ``class_indexed_by`` and ``indexed_by`` with a ``parent:``.
+
+-  Resolved metadata storage issues for dynamically created classes.
+
+-  Improved error handling for nil class names in tracking
+   relationships.
+
+.. _documentation-1:
+
+Documentation
+~~~~~~~~~~~~~
+
+-  Updated the ``examples/relationships_basic.rb`` script to reflect the
+   improved, bidirectional ``member_of`` API and to ensure a clean
+   database state for each run.
+
+.. _ai-assistance-1:
+
+AI Assistance
+~~~~~~~~~~~~~
+
+-  This refactoring was implemented with Claude Code assistance,
+   including comprehensive test updates and API modernization.
+
+2.0.0-pre9 - 2025-09-02
+======================
+
+.. _added-3:
+
+Added
+~~~~~
+
+-  Added ``class_tracked_in`` method for global tracking relationships
+   following Horreum’s established ``class_`` prefix convention
+-  Added ``class_indexed_by`` method for global index relationships with
+   consistent API design
+
+.. _changed-3:
+
+Changed
+~~~~~~~
+
+-  **BREAKING**: ``tracked_in :global, collection`` syntax now raises
+   ArgumentError - use ``class_tracked_in collection`` instead
+-  **BREAKING**: ``indexed_by field, index, context: :global`` syntax
+   replaced with ``class_indexed_by field, index``
+-  **BREAKING**: ``indexed_by field, index, context: SomeClass`` syntax
+   replaced with ``indexed_by field, index, parent: SomeClass``
+-  Relationships API now provides consistent parameter naming across all
+   relationship types
+
+.. _documentation-2:
+
+Documentation
+~~~~~~~~~~~~~
+
+-  Updated Relationships Guide with new API syntax and migration
+   examples
+-  Updated relationships method documentation with new method signatures
+-  Updated basic relationships example to demonstrate new API patterns
+-  Added tryouts test coverage in
+   try/features/relationships/relationships_api_changes_try.rb
+
+2.0.0-pre8 - 2025-09-01
+======================
+
+.. _added-4:
+
+Added
+~~~~~
+
+-  Implemented Scriv-based changelog system for sustainable
+   documentation
+-  Added fragment-based workflow for tracking changes
+-  Created structured changelog templates and configuration
+
+.. _documentation-3:
+
+Documentation
+~~~~~~~~~~~~~
+
+-  Set up Scriv configuration and directory structure
+-  Created README for changelog fragment workflow
+
+.. raw:: html
+
+   <!-- scriv-end-here -->
+
+2.0.0-pre7 - 2025-08-31
+======================
+
+.. _added-5:
+
+Added
+~~~~~
+
+-  Comprehensive relationships system with three relationship types:
+
+   -  ``tracked_in`` - Multi-presence tracking with score encoding
+   -  ``indexed_by`` - O(1) hash-based lookups
+   -  ``member_of`` - Bidirectional membership with collision-free
+      naming
+
+-  Categorical permission system with bit-encoded permissions
+-  Time-based permission scoring for temporal access control
+-  Permission tier hierarchies with inheritance patterns
+-  Scalable permission management for large object collections
+-  Score-based sorting with custom scoring functions
+-  Permission-aware queries filtering by access levels
+-  Relationship validation framework ensuring data integrity
+
+.. _changed-4:
+
+Changed
+~~~~~~~
+
+-  Performance optimizations for large-scale relationship operations
+
+.. _security-2:
+
+Security
+~~~~~~~~
+
+-  GitHub Actions security hardening with matrix optimization
+
+2.0.0-pre6 - 2025-08-15
+======================
+
+.. _added-6:
+
+Added
+~~~~~
+
+-  New ``save_if_not_exists`` method for conditional persistence
+-  Atomic persistence operations with transaction support
+-  Enhanced error handling for persistence failures
+-  Improved data consistency guarantees
+
+.. _changed-5:
+
+Changed
+~~~~~~~
+
+-  Connection provider pattern for flexible pooling strategies
+-  Multi-database support with intelligent pool management
+-  Thread-safe connection handling for concurrent applications
+-  Configurable pool sizing and timeout management
+-  Modular class structure with cleaner separation of concerns
+-  Enhanced feature system with dependency management
+-  Improved inheritance patterns for better code organization
+-  Streamlined base class functionality
+
+.. _fixed-2:
+
+Fixed
+~~~~~
+
+-  Critical security fixes in Ruby workflow vulnerabilities
+-  Systematic dependency resolution via multi-constraint optimization
+
+2.0.0-pre5 - 2025-08-05
+======================
+
+.. _added-7:
+
+Added
+~~~~~
+
+-  Field-level encryption with transparent access patterns
+-  Multiple encryption providers:
+
+   -  XChaCha20-Poly1305 (preferred, requires rbnacl)
+   -  AES-256-GCM (fallback, OpenSSL-based)
+
+-  Field-specific key derivation for cryptographic domain separation
+-  Configurable key versioning supporting key rotation
+-  Non-persistent field storage for sensitive runtime data
+-  RedactedString wrapper preventing accidental logging/serialization
+-  Memory-safe handling of sensitive data in Ruby objects
+-  API-safe serialization excluding transient fields
+
+.. _security-3:
+
+Security
+~~~~~~~~
+
+-  Encryption field security hardening with additional validation
+-  Enhanced memory protection for sensitive data handling
+-  Improved key management patterns and best practices
+-  Security test suite expansion with comprehensive coverage
+
+2.0.0-pre - 2025-07-25
+======================
+
+.. _added-8:
+
+Added
+~~~~~
+
+-  Complete API redesign for clarity and modern Ruby conventions
+-  Valkey compatibility alongside traditional Redis support
+-  Ruby 3.4+ modernization with fiber and thread safety improvements
+-  Connection pooling foundation with provider pattern architecture
+
+.. _changed-6:
+
+Changed
+~~~~~~~
+
+-  ``Familia::Base`` replaced by ``Familia::Horreum`` as the primary
+   base class
+-  Connection configuration moved from simple string to block-based
+   setup
+-  Feature activation changed from ``include`` to ``feature``
+   declarations
+-  Method naming updated for consistency (``delete`` → ``destroy``,
+   ``exists`` → ``exists?``, ``dump`` → ``serialize``)
+
+.. _documentation-4:
+
+Documentation
+~~~~~~~~~~~~~
+
+-  YARD documentation workflow with automated GitHub Pages deployment
+-  Comprehensive migrating guide for v1.x to v2.0.0-pre transition
+
+.. raw:: html
+
+   <!-- scriv-end-here -->

data/CLAUDE.md

@@ -47,7 +47,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Changelog Management
 
-Add changelog fragment with each user-facing or documented change (optional but encouraged). See:
+Add changelog fragment with each user-facing or documented change (optional but encouraged). Fragments use RST format. See:
 @changelog.d/README.md
 
 ### Known Issues & Quirks

data/Gemfile

@@ -5,12 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  if ENV['LOCAL_DEV']
-    gem 'tryouts', path: '../tryouts'
-    gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
-  else
-    gem 'tryouts', '~> 3.5.2', require: false
-  end
+  gem 'tryouts', '~> 3.6.0', require: false
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'
   gem 'stackprof'

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre12)
-      benchmark
-      connection_pool
-      csv
-      logger
+    familia (2.0.0.pre14)
+      benchmark (~> 0.4)
+      connection_pool (~> 2.5)
+      csv (~> 3.3)
+      logger (~> 1.7)
+      oj (~> 3.16)
       redis (>= 4.8.1, < 6.0)
       stringio (~> 3.1.1)
       uri-valkey (~> 1.4)
@@ -16,6 +17,7 @@ GEM
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.4.1)
+    bigdecimal (3.2.3)
     byebug (11.1.3)
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
@@ -39,6 +41,10 @@ GEM
     logger (1.7.0)
     method_source (1.1.0)
     minitest (5.25.5)
+    oj (3.16.11)
+      bigdecimal (>= 3.0)
+      ostruct (>= 0.2)
+    ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -113,7 +119,7 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.5.2)
+    tryouts (3.6.0)
       concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
@@ -148,7 +154,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.5.2)
+  tryouts (~> 3.6.0)
   yard (~> 0.9)
 
 BUNDLED WITH

data/README.md

@@ -170,7 +170,26 @@ All relationships support automatic indexing and tracking - objects are automati
 
 ## Organizing Complex Models
 
-For large applications, you can organize model complexity using custom features:
+For large applications, you can organize model complexity using custom features and the Feature Autoloading System:
+
+### Feature Autoloading System
+
+Familia automatically discovers and loads feature-specific configuration files, enabling clean separation between core model definitions and feature configurations:
+
+```ruby
+# app/models/user.rb - Clean model definition
+class User < Familia::Horreum
+  field :name, :email, :password
+  feature :safe_dump  # Configuration auto-loaded
+end
+
+# app/models/user/safe_dump_extensions.rb - Automatically discovered
+class User
+  safe_dump_fields :name, :email  # password excluded for security
+end
+```
+
+Extension files follow the pattern: `{model_name}/{feature_name}_*.rb`
 
 ### Self-Registering Features
 
@@ -201,7 +220,7 @@ class Customer < Familia::Horreum
 end
 ```
 
-This keeps complex models organized while maintaining Familia's clean, declarative style.
+These approaches keep complex models organized while maintaining Familia's clean, declarative style. For detailed migration information, see the [migration guides](docs/migrating/).
 
 ## AI Development Assistance