familia 2.0.0.pre10 → 2.0.0.pre13

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre10)
-      benchmark
-      connection_pool
-      csv
-      logger
+    familia (2.0.0.pre13)
+      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/changelog.d/README.md

@@ -4,7 +4,7 @@ This directory contains changelog fragments managed by [Scriv](https://scriv.rea
 
 ## Our Approach
 
-Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) to ensure our release notes are clear, consistent, and trustworthy.
+Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) and semvar to ensure our release notes are clear, consistent, and useful.
 
 To achieve this, we use a fragment-based workflow with `scriv`. Instead of a single, large `CHANGELOG.md` file that can cause merge conflicts, each developer includes a small changelog fragment with their pull request. At release time, these fragments are collected and aggregated into the main changelog.
 
@@ -12,55 +12,66 @@ This approach provides several benefits:
 - **Reduces Merge Conflicts:** Developers can work in parallel without conflicting over a central changelog file.
 - **Improves Developer Experience:** Creating a small, focused fragment is a simple and repeatable task during development.
 - **Ensures Consistency:** Automation helps maintain a consistent structure for all changelog entries.
+- **AI Transparency:** An opportunity to be specific and detailed about the assistance provided.
 - **Builds Trust:** A clear and well-maintained changelog communicates respect for our users and collaborators.
 
+## Relevant paths
+
+* `changelog.d/` - (e.g. changelog.d/YYYYMMDD_HHmmss_username_branch.rst)
+* `docs/migrating/` - (e.g. docs/migrating/v2.0.0-pre.md)
+* `CHANGELOG.rst` - The full changelog for all releases, in reverse chronological order. Careful: LARGE DOCUMENT. Limit reading to the first 50 lines.
+
+* `changelog.d/scriv.ini` - Scriv tool settings
+
 ## How to Add a Changelog Entry
 
 1.  **Create a New Fragment:**
-    ```bash
-    scriv create
-    ```
-    This will create a new file in the `changelog.d/fragments/` directory.
 
-    **Alternative:** Use `scriv create --edit` to create and immediately open in your editor.
-    **Important:** You must add content and save before exiting, or scriv will abort with "Empty fragment, aborting..."
+```bash
+# This will create a new file in the `changelog.d/` directory.
+scriv create
+```
 
 2.  **Edit the Fragment File:**
-    Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good entries.
+Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good CHANGELOG entries.
+
+3. **Add or Update Migrating Guide:** (optional)
+Include technical details to help developers update to the new version. Start with a specific introduction, e.g. "This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.". Including code snippets and multi-line content that is too detailed for the CHANGELOG.
+
+Use the content of an existing `docs/migrating/vMajor.Minor.Patch*.md file as a reference.
 
-3.  **Commit with Your Code:**
-    ```bash
-    git add changelog.d/fragments/your_fragment_name.md
-    git commit
-    ```
+Compare the headers of your draft content with the headers of the previous migration guide to make sure it does not repeat or overlap.
+
+4.  **Commit with Your Code:**
+```bash
+git add changelog.d/YYYYMMDD_HHmmss_username_branch.rst [docs/migrating/v2.0.0-pre.md]
+git commit
+```
 
 ## Fragment Guidelines
 
--   **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
--   **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
--   **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
-    -   **Good:** "Improved the performance and stability of Redis connections under high load."
-    -   **Bad:** "Refactored the `RedisManager` to use a connection pool."
--   **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
--   **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
-    -   **Example:** `- Fixed a bug where users could not reset their passwords. (Closes #123)`
+- **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
+- **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
+- **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
+    - **Good:** "Improved the performance and stability of Redis connections under high load."
+    - **Bad:** "Refactored the `RedisManager`."
+- **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
+- **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
+    - **Example:** `- Fixed a bug where users could not reset their passwords. PR #123`
 
 ### Categories
 
-Use these categories from [Keep a Changelog](https://keepachangelog.com):
+Use these categories:
 
--   **Added**: New features or capabilities.
--   **Changed**: Changes to existing functionality.
--   **Deprecated**: Soon-to-be removed features.
--   **Removed**: Now removed features.
--   **Fixed**: Bug fixes.
--   **Security**: Security-related improvements.
--   **Documentation**: Documentation improvements.
+- **Added**: New features or capabilities.
+- **Changed**: Changes to existing functionality.
+- **Deprecated**: Soon-to-be removed features.
+- **Removed**: Now removed features.
+- **Fixed**: Bug fixes.
+- **Security**: Security-related improvements.
+- **Documentation**: Documentation improvements.
+- **AI Assistance**: Significant AI assistance in the change, including discussion, rubber ducking, formatting, writing documentation, writing tests.
 
 ## Release Process
 
-At release time, an authorized maintainer will collect all fragments into the main `CHANGELOG.md` file:
-
-```bash
-scriv collect --version 2.0.0
-```
+At release time, scriv will collect all fragments into the main `CHANGELOG.rst` file with th command `scriv collect`. The version is taken automatically from `lib/familia/version.rb`.

data/changelog.d/scriv.ini

@@ -0,0 +1,5 @@
+[scriv]
+format = rst
+categories = Added, Changed, Deprecated, Removed, Fixed, Security, Documentation, AI Assistance
+version = command: ruby -r ./lib/familia/version.rb -e "puts Familia::VERSION"
+main_branches = main, develop

data/docs/archive/FAMILIA_RELATIONSHIPS.md

@@ -189,7 +189,7 @@ customer.find_by_name("production-api-key")
 customer.find_all_by_scope(["read", "write"])
 ```
 
-### Migration Guide
+### Migrating Guide
 If you have existing code with incorrect syntax, here's how to fix it:
 
 ```ruby

data/docs/archive/FAMILIA_UPDATE.md

@@ -179,7 +179,7 @@ end
 
 ---
 
-## Migration Guide Summary
+## Migrating Guide Summary
 
 ### From v1.x to v2.0.0-pre
 1. **Update connection configuration** to use new pooling system

data/docs/archive/README.md

@@ -10,9 +10,9 @@ This directory contains original documentation files that have been migrated to
 ### FAMILIA_UPDATE.md
 **Original Purpose:** Version summary table and detailed release notes for v2.0.0-pre series
 
-**Migration Destinations:**
+**Migrating Destinations:**
 - **Changelog entries** → Extracted to Scriv fragments, aggregated into `CHANGELOG.md`
-- **Migration guides** → Reorganized into `docs/migration/v2.0.0-pre*.md`
+- **Migrating guides** → Reorganized into `docs/migrating/v2.0.0-pre*.md`
 - **Feature descriptions** → Cross-referenced with existing feature guides in `docs/guides/`
 
 ### FAMILIA_RELATIONSHIPS.md
@@ -33,26 +33,22 @@ This directory contains original documentation files that have been migrated to
 
 ```
 docs/
-├── migration/           # Version-specific migration guides
-│   ├── v2.0.0-pre.md   # Foundation migration
-│   ├── v2.0.0-pre5.md  # Security features
-│   ├── v2.0.0-pre6.md  # Architecture improvements
-│   └── v2.0.0-pre7.md  # Relationships system
-├── guides/              # Feature guides (moved from wiki/)
-│   ├── relationships-methods.md  # From FAMILIA_RELATIONSHIPS.md
+├── migrating/              # Version-specific migrating guides
+│   ├── v2.0.0-pre.md
+│   ├── v2.0.0-pre5.md      # Security features
+│   ├── v2.0.0-pre6.md      # Architecture improvements
+│   └── v2.0.0-pre7.md      # Relationships system
+│
+├── guides/                 # Feature-specific guides (moved from wiki/)
+│   ├── relationships.md    # From FAMILIA_RELATIONSHIPS.md
 │   └── [other guides...]
-├── reference/           # Technical reference
-│   └── api-technical.md # From FAMILIA_TECHNICAL.md
-└── archive/            # This directory
+│
+├── reference/              # Technical reference
+│   └── api-technical.md
+│
+└── archive/                # This directory
 ```
 
-## Why These Files Were Archived
-
-1. **Sustainability** - The original files accumulated overlapping content without clear organization
-2. **Maintainability** - Scriv fragment system prevents documentation bloat
-3. **Clarity** - Separation of changelog, guides, and reference improves findability
-4. **Workflow** - Fragment-based workflow scales better with development
-
 ## Finding Migrated Content
 
 - **Version changes** → Check `CHANGELOG.md` (generated from fragments)

data/docs/guides/Feature-System-Autoloading.md

@@ -0,0 +1,228 @@
+# Feature System Autoloading
+
+## Overview
+
+Familia's feature system includes an autoloading mechanism that automatically discovers and loads feature-specific extension files when features are included in your classes. This allows you to keep your main model files clean while organizing feature-specific configurations in separate files.
+
+## The Problem It Solves
+
+When you include a feature like `safe_dump` in a Familia class:
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump  # This line should trigger autoloading
+end
+```
+
+You want to be able to define the safe dump configuration in a separate file:
+
+```ruby
+# user/safe_dump_extensions.rb
+class User
+  safe_dump_fields :name, :email  # Don't dump :password
+end
+```
+
+But there's a **timing problem**: when should this extension file be loaded?
+
+## Why Standard `included` Hook Doesn't Work
+
+The original approach tried to use the standard `included` hook:
+
+```ruby
+module SafeDump
+  def self.included(base)
+    # Try to autoload here - BUT THIS IS TOO EARLY!
+    autoload_files_for(base)
+  end
+end
+```
+
+**Problem**: This happens **during** the feature inclusion process, before the feature is fully set up. The class isn't in a stable state yet.
+
+## The Solution: Post-Inclusion Hook
+
+The `post_inclusion_autoload` system works in **two phases**:
+
+### Phase 1: Feature System Hook
+
+In `lib/familia/features.rb`, after including the feature module:
+
+```ruby
+def feature(feature_name, **options)
+  # ... setup code ...
+
+  include feature_class  # Include the feature module
+
+  # NOW call the post-inclusion hook
+  if feature_class.respond_to?(:post_inclusion_autoload)
+    feature_class.post_inclusion_autoload(self, feature_name, options)
+  end
+end
+```
+
+### Phase 2: Autoloadable Implementation
+
+The `post_inclusion_autoload` method in `lib/familia/features/autoloadable.rb`:
+
+1. **Gets the source location** of the user's class file using Ruby's introspection:
+   ```ruby
+   location_info = Module.const_source_location(base.name)
+   source_location = location_info&.first  # e.g., "/path/to/models/user.rb"
+   ```
+
+2. **Calculates extension file paths** based on conventions:
+   ```ruby
+   base_dir = File.dirname(location_path)  # "/path/to/models"
+   model_name = base.name.snake_case       # "user"
+
+   # Look for files like:
+   patterns = [
+     "/path/to/models/user/safe_dump_*.rb",
+     "/path/to/models/user/features/safe_dump_*.rb",
+     "/path/to/models/features/safe_dump_*.rb"
+   ]
+   ```
+
+3. **Loads any matching files** found in those locations
+
+## Why This Timing Matters
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump  # ← Timing is critical here
+end
+```
+
+**What happens in order:**
+
+1. `feature :safe_dump` is called
+2. Feature system includes `Familia::Features::SafeDump` module
+3. **Feature is now fully included and stable**
+4. `post_inclusion_autoload` is called
+5. Extension files are discovered and loaded
+6. `safe_dump_fields :name, :email` executes in the extension file
+
+## File Naming Conventions
+
+The autoloading system looks for files matching these patterns (in order of precedence):
+
+1. `{model_directory}/{model_name}/{feature_name}_*.rb`
+2. `{model_directory}/{model_name}/features/{feature_name}_*.rb`
+3. `{model_directory}/features/{feature_name}_*.rb`
+
+### Examples
+
+For a `User` class defined in `app/models/user.rb` with `feature :safe_dump`:
+
+```
+app/models/user/safe_dump_extensions.rb     # ← Most specific
+app/models/user/safe_dump_config.rb         # ← Also matches pattern
+app/models/user/features/safe_dump_*.rb     # ← Feature subdirectory
+app/models/features/safe_dump_*.rb          # ← Shared feature configs
+```
+
+## Complete Example
+
+### Main Model File
+
+```ruby
+# app/models/user.rb
+class User < Familia::Horreum
+  field :name
+  field :email
+  field :password
+  field :created_at
+
+  feature :safe_dump  # ← Triggers autoloading
+  feature :expiration
+end
+```
+
+### Safe Dump Extensions
+
+```ruby
+# app/models/user/safe_dump_extensions.rb
+class User
+  # Configure which fields are safe to dump in API responses
+  safe_dump_fields :name, :email, :created_at
+  # Note: :password is intentionally excluded for security
+
+  def safe_dump_display_name
+    "#{name} (#{email})"
+  end
+end
+```
+
+### Expiration Extensions
+
+```ruby
+# app/models/user/expiration_config.rb
+class User
+  # Set default TTL for user objects
+  expires_in 30.days
+
+  # Custom expiration logic
+  def should_expire?
+    !active? && last_login_at < 90.days.ago
+  end
+end
+```
+
+### Result
+
+After loading, the `User` class has:
+- `User.safe_dump_field_names` returns `[:name, :email, :created_at]`
+- `User.ttl` returns the configured expiration
+- All extension methods are available on instances
+
+## Key Benefits
+
+1. **Separation of Concerns**: Main model file focuses on core definition, extension files handle feature-specific configuration
+
+2. **Convention Over Configuration**: No manual requires, just follow naming conventions
+
+3. **Safe Timing**: Extension files load after the feature is fully set up
+
+4. **Thread Safe**: No shared state between classes
+
+5. **Discoverable**: Clear file organization makes extensions easy to find
+
+## Why It's Better Than Alternatives
+
+- **Manual requires**: Error-prone, verbose, easy to forget
+- **Configuration blocks**: Clutters the main model file
+- **Included hook**: Wrong timing, class not stable yet
+- **Class_eval strings**: Complex, hard to debug and maintain
+
+The `post_inclusion_autoload` system provides a clean, automatic, and safe way to extend feature behavior without polluting the main class definitions.
+
+## Implementation Details
+
+### Autoloadable Module
+
+Features that support autoloading include the `Familia::Features::Autoloadable` module:
+
+```ruby
+module Familia::Features::SafeDump
+  include Familia::Features::Autoloadable  # ← Enables autoloading
+
+  # Feature implementation...
+end
+```
+
+### Anonymous Class Handling
+
+The system gracefully handles edge cases:
+
+- **Anonymous classes**: Classes without names (e.g., `Class.new`) are skipped
+- **Eval contexts**: Classes defined in `eval` or irb are skipped
+- **Missing files**: No errors if extension files don't exist
+
+### Error Handling
+
+- Missing extension files are silently ignored
+- Syntax errors in extension files propagate normally
+- `NameError` during constant resolution is caught and logged
+
+This robust error handling ensures the autoloading system never breaks your application, even with unusual class definitions or missing files.

data/docs/guides/Home.md

@@ -23,7 +23,7 @@ Welcome to the comprehensive documentation for Familia v2.0. This wiki covers al
 
 ### 🚀 Operations (As Needed)
 
-9. **[Migration Guide](Migration-Guide.md)** - Upgrading existing fields _(coming soon)_
+9. **[Migrating Guide](Migrating-Guide.md)** - Upgrading existing fields _(coming soon)_
 10. **[Key Management](Key-Management.md)** - Rotation and best practices _(coming soon)_
 
 ## 🚀 Quick Start Examples

data/docs/guides/Implementation-Guide.md

@@ -273,4 +273,4 @@ end
 
 - [Security Model](Security-Model) - Understand the cryptographic design
 - [Key Management](Key-Management) - Rotation and best practices
-- [Migration Guide](Migration-Guide) - Upgrade existing fields
+- [Migrating Guide](Migrating-Guide) - Upgrade existing fields

data/docs/guides/relationships-methods.md

@@ -234,7 +234,7 @@ customer.find_by_name("production-api-key")
 customer.find_all_by_scope(["read", "write"])
 ```
 
-### Migration Guide
+### Migrating Guide
 If you have existing code with old syntax, here's how to update it:
 
 ```ruby