familia 2.0.0.pre26 → 2.0.0

data/docs/migrating/v2.0.0-pre12.md

@@ -1,306 +0,0 @@
-# Migrating Guide: v2.0.0-pre12
-
-This version introduces significant security improvements to Familia's identifier system, including verifiable identifiers with HMAC signatures, scoped identifier namespaces, and hardened external identifier derivation to prevent potential security vulnerabilities.
-
-## VerifiableIdentifier Feature
-
-### Overview
-
-The new `Familia::VerifiableIdentifier` module allows applications to create and verify identifiers with embedded HMAC signatures. This enables stateless confirmation that an identifier was generated by your application, preventing forged IDs from malicious sources.
-
-### Basic Usage
-
-```ruby
-class Customer < Familia::Horreum
-  feature :verifiable_identifier
-
-  # Required: UnsortedSet the HMAC secret (do this once in your app initialization)
-  # Generate with: SecureRandom.hex(64)
-  ENV['VERIFIABLE_ID_HMAC_SECRET'] = 'your_64_character_hex_secret'
-end
-
-# Generate a verifiable identifier
-customer = Customer.new
-verifiable_id = customer.generate_verifiable_id
-# => "cust_1234567890abcdef_a1b2c3d4e5f6789..."
-
-# Verify the identifier later (stateless verification)
-if Customer.verified_identifier?(verifiable_id)
-  # Identifier is valid and was generated by this application
-  original_id = Customer.extract_identifier(verifiable_id)
-  customer = Customer.new(original_id)
-else
-  # Identifier is forged or corrupted
-  raise SecurityError, "Invalid identifier"
-end
-```
-
-### Scoped VerifiableIdentifier
-
-The new `scope` parameter enables cryptographically isolated identifier namespaces for multi-tenant, multi-domain, or multi-environment applications.
-
-#### Before (Global Scope)
-```ruby
-# All identifiers share the same cryptographic space
-admin_id = admin.generate_verifiable_id
-user_id = user.generate_verifiable_id
-
-# Risk: Cross-contamination between different contexts
-```
-
-#### After (Scoped Namespaces)
-```ruby
-# Production environment
-prod_customer_id = customer.generate_verifiable_id(scope: 'production')
-prod_admin_id = admin.generate_verifiable_id(scope: 'production:admin')
-
-# Development environment
-dev_customer_id = customer.generate_verifiable_id(scope: 'development')
-
-# Multi-tenant application
-tenant_a_id = user.generate_verifiable_id(scope: "tenant:#{tenant_a.id}")
-tenant_b_id = user.generate_verifiable_id(scope: "tenant:#{tenant_b.id}")
-
-# Verification requires matching scope
-Customer.verified_identifier?(prod_customer_id, scope: 'production')  # => true
-Customer.verified_identifier?(prod_customer_id, scope: 'development') # => false
-```
-
-**Scope Benefits:**
-- **Multi-tenant isolation**: Tenant A cannot forge identifiers for Tenant B
-- **Environment separation**: Production IDs cannot be used in development
-- **Role-based security**: Admin scopes separate from user scopes
-- **Full backward compatibility**: Existing code without scopes continues to work
-
-### Key Management
-
-#### Secure Secret Generation
-```ruby
-# Generate a cryptographically secure HMAC secret
-require 'securerandom'
-secret = SecureRandom.hex(64)  # 512-bit secret
-puts "VERIFIABLE_ID_HMAC_SECRET=#{secret}"
-```
-
-#### Environment Configuration
-```ruby
-# config/application.rb or equivalent
-# UnsortedSet this BEFORE any VerifiableIdentifier usage
-ENV['VERIFIABLE_ID_HMAC_SECRET'] = Rails.application.credentials.verifiable_id_secret
-
-# Or configure programmatically
-Familia::VerifiableIdentifier.hmac_secret = your_secret_string
-```
-
-## ObjectIdentifier Feature Improvements
-
-### Method Renaming
-
-Method names have been updated for clarity and consistency:
-
-#### Before
-```ruby
-customer = Customer.new
-objid = customer.generate_objid           # Unclear what this generates
-extid = Customer.generate_extid(objid)    # Less secure class method
-```
-
-#### After
-```ruby
-customer = Customer.new
-objid = customer.generate_object_identifier    # Clear: generates object ID
-extid = customer.derive_external_identifier    # Clear: derives from objid, instance method
-```
-
-**Migration:**
-- Replace `generate_objid` → `generate_object_identifier`
-- Replace `generate_external_identifier` → `derive_external_identifier`
-- Remove usage of `generate_extid` (deprecated for security reasons)
-
-### Provenance Tracking
-
-ObjectIdentifier now tracks which generator was used for each identifier:
-
-```ruby
-class Customer < Familia::Horreum
-  feature :object_identifier
-
-  # Configure generator type
-  object_identifier_generator :uuid_v7  # or :uuid_v4, :hex, custom proc
-end
-
-customer = Customer.new
-objid = customer.generate_object_identifier
-
-# Provenance information available
-puts customer.object_identifier_generator_type  # => :uuid_v7
-puts customer.objid_format                     # => :uuid (normalized format)
-```
-
-**Benefits:**
-- **Security auditing**: Know which generator created each identifier
-- **Format normalization**: Eliminates ambiguity between UUID and hex formats
-- **Migration support**: Track mixed generator usage during transitions
-
-## ExternalIdentifier Security Hardening
-
-### Provenance Validation
-
-ExternalIdentifier now validates that objid values come from the ObjectIdentifier feature before deriving external identifiers.
-
-#### Before (Potential Security Risk)
-```ruby
-# Could derive external IDs from any string, including malicious input
-extid = customer.derive_external_identifier("malicious_input")
-```
-
-#### After (Hardened)
-```ruby
-customer = Customer.new
-customer.generate_object_identifier  # Must generate objid first
-
-# Only works with validated objid from ObjectIdentifier feature
-extid = customer.derive_external_identifier  # Secure: uses validated objid
-```
-
-### Improved Security Model
-
-External identifiers are now derived using the internal objid as a seed for a new random value, rather than directly deriving from objid.
-
-#### Before
-```ruby
-# Direct derivation could leak information about objid
-extid = hash(objid)  # Information leakage risk
-```
-
-#### After
-```ruby
-# objid used as seed for new random value
-extid = secure_hash(objid + additional_entropy)  # No information leakage
-```
-
-### Error Handling Improvements
-
-External identifier now raises clear errors for invalid usage:
-
-```ruby
-class Customer < Familia::Horreum
-  feature :external_identifier  # Missing: object_identifier dependency
-end
-
-customer = Customer.new
-# Raises ExternalIdentifierError instead of returning nil
-customer.derive_external_identifier
-# => Familia::ExternalIdentifierError: Model does not have an objid field
-```
-
-## Migration Steps
-
-### 1. Update Method Names
-
-Replace deprecated method names in your codebase:
-
-```bash
-# Search and replace patterns:
-grep -r "generate_objid" --include="*.rb" .
-# Replace with: generate_object_identifier
-
-grep -r "generate_external_identifier" --include="*.rb" .
-# Replace with: derive_external_identifier
-
-grep -r "generate_extid" --include="*.rb" .
-# Remove usage - use derive_external_identifier instead
-```
-
-### 2. Add HMAC Secret for VerifiableIdentifier
-
-If you plan to use VerifiableIdentifier:
-
-```ruby
-# Generate secret
-require 'securerandom'
-secret = SecureRandom.hex(64)
-
-# Add to your environment configuration
-# .env, Rails credentials, or similar
-VERIFIABLE_ID_HMAC_SECRET=your_generated_secret
-
-# Verify configuration
-puts ENV['VERIFIABLE_ID_HMAC_SECRET']&.length  # Should be 128 characters
-```
-
-### 3. Update ExternalIdentifier Usage
-
-Ensure proper dependency chain:
-
-```ruby
-class YourModel < Familia::Horreum
-  # Required: ObjectIdentifier must come before ExternalIdentifier
-  feature :object_identifier
-  feature :external_identifier
-
-  # Configure generator if needed
-  object_identifier_generator :uuid_v7
-end
-
-# Usage pattern
-model = YourModel.new
-model.generate_object_identifier  # Generate objid first
-extid = model.derive_external_identifier  # Then derive external ID
-```
-
-### 4. Review Security-Sensitive Code
-
-Audit any code that processes identifiers from external sources:
-
-```ruby
-# Before: Potentially unsafe
-def process_identifier(external_id)
-  # Could process forged identifiers
-  model = Model.find_by_external_id(external_id)
-end
-
-# After: With verification
-def process_identifier(verifiable_id)
-  # Verify identifier authenticity first
-  unless Model.verified_identifier?(verifiable_id)
-    raise SecurityError, "Invalid identifier"
-  end
-
-  original_id = Model.extract_identifier(verifiable_id)
-  model = Model.new(original_id)
-end
-```
-
-## Breaking Changes
-
-1. **`generate_extid` removed** - Use instance-level `derive_external_identifier` instead
-2. **ExternalIdentifier validation** - Now raises `ExternalIdentifierError` instead of returning `nil` for models without objid
-3. **Method names changed** - `generate_objid` → `generate_object_identifier`, `generate_external_identifier` → `derive_external_identifier`
-
-## New Security Capabilities
-
-1. **Cryptographic identifier verification** - Prevent forged IDs with HMAC signatures
-2. **Scoped namespaces** - Isolate identifiers by tenant, environment, or role
-3. **Provenance tracking** - Know which generator created each identifier
-4. **Information leakage prevention** - External IDs no longer directly expose internal IDs
-5. **Input validation** - Clear error messages for invalid operations
-
-## Testing Your Migration
-
-```ruby
-# Test ObjectIdentifier changes
-model = YourModel.new
-objid = model.generate_object_identifier
-extid = model.derive_external_identifier
-puts "Generator: #{model.object_identifier_generator_type}"
-
-# Test VerifiableIdentifier (if using)
-vid = model.generate_verifiable_id
-puts "Verifiable: #{YourModel.verified_identifier?(vid)}"
-
-# Test scoped identifiers (if using)
-scoped_vid = model.generate_verifiable_id(scope: 'production')
-puts "Scoped valid: #{YourModel.verified_identifier?(scoped_vid, scope: 'production')}"
-puts "Wrong scope: #{YourModel.verified_identifier?(scoped_vid, scope: 'development')}"
-```

data/docs/migrating/v2.0.0-pre13.md

@@ -1,95 +0,0 @@
-# Migrating Guide: v2.0.0-pre13
-
-This version introduces the Feature Autoloading System for automatic discovery and loading of feature-specific configuration files, enabling cleaner separation between core model definitions and feature configurations.
-
-## Feature Autoloading System
-
-### What Changed
-
-Features now automatically discover and load extension files from your project directories using conventional file naming patterns. This eliminates the need to configure features in your main model files.
-
-### Basic Migration
-
-#### Before
-```ruby
-# app/models/user.rb
-class User < Familia::Horreum
-  field :name, :email, :password
-
-  feature :safe_dump
-  safe_dump_fields :name, :email  # Configuration mixed with model
-end
-```
-
-#### After
-```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
-end
-```
-
-### File Naming Convention
-
-Extension files follow the pattern: `{model_name}/{feature_name}_*.rb`
-
-```
-app/models/
-├── user.rb
-├── user/
-│   ├── safe_dump_extensions.rb    # SafeDump configuration
-│   └── expiration_config.rb       # Expiration settings
-```
-
-### Migration Steps
-
-1. **Create extension directories**: `mkdir -p app/models/user`
-2. **Extract feature configuration** from main model files to separate extension files
-3. **Verify autoloading**: Check that feature methods are available after migration
-
-### Debugging
-
-Enable debug output to troubleshoot autoloading:
-```ruby
-ENV['FAMILIA_DEBUG'] = '1'  # Shows discovered and loaded files
-```
-
-Common issues:
-- Files must follow `{feature_name}_*.rb` naming pattern
-- Extension files should reopen the same class as your model
-
-## Architecture
-
-The Feature Autoloading System consists of two key components:
-
-### Familia::Features::Autoloader
-A utility module providing shared file loading functionality:
-- Handles Dir.glob pattern matching and file loading
-- Provides consistent debug logging across all autoloading scenarios
-- Used by both feature-specific and general-purpose autoloading
-
-### Familia::Features::Autoloadable
-A mixin for feature modules that enables post-inclusion autoloading:
-- Uses `Module.const_source_location` to find where user classes are defined
-- Discovers extension files using conventional patterns relative to the user class location
-- Integrates with the feature system's inclusion lifecycle
-
-When you call `feature :safe_dump`, the SafeDump module (which includes Autoloadable) triggers post-inclusion autoloading that searches for `user/safe_dump_*.rb` files and loads them automatically.
-
-## New Capabilities
-
-1. **Automatic Extension Discovery**: No manual require statements needed
-2. **Conventional File Organization**: Standard patterns for consistent project structure
-3. **Feature Isolation**: Clean separation between core models and feature configurations
-4. **Shared Autoloader Infrastructure**: Consistent loading behavior across all features
-5. **Debug Support**: Built-in debugging for troubleshooting autoloading issues
-
-## Breaking Changes
-
-**None** - This release is fully backward compatible. Existing models and feature configurations continue to work without modification.

data/docs/migrating/v2.0.0-pre14.md

@@ -1,37 +0,0 @@
-# Migrating Guide: v2.0.0-pre14
-
-This version renames TimeUtils to TimeLiterals for semantic clarity and fixes an ExternalIdentifier bug.
-
-## Breaking Change: TimeUtils → TimeLiterals
-
-**Migration Required:**
-
-Find and replace in your codebase:
-```bash
-# Find files to update
-grep -r "using Familia::Refinements::TimeUtils" .
-
-# Replace the import
-sed -i 's/using Familia::Refinements::TimeUtils/using Familia::Refinements::TimeLiterals/g' *.rb
-```
-
-**Before:**
-```ruby
-using Familia::Refinements::TimeUtils
-```
-
-**After:**
-```ruby
-using Familia::Refinements::TimeLiterals
-```
-
-All functionality remains identical - only the module name changed.
-
-## Bug Fix: ExternalIdentifier
-
-Fixed `NoMethodError` when using ExternalIdentifier by replacing incorrect `.del()` calls with `.remove_field()` in HashKey operations. This affected:
-- Changing external identifier values
-- Looking up objects by external ID
-- Destroying objects with external identifiers
-
-No migration needed - the fix is automatic.

data/docs/migrating/v2.0.0-pre18.md

@@ -1,58 +0,0 @@
-# Migrating Guide: v2.0.0-pre18
-
-This version completes the JSON serialization implementation by removing the string-as-is optimization and fixes encrypted field visibility in serialization.
-
-## JSON Serialization for All Types
-
-**What Changed:**
-
-All field values (including strings) are now JSON-encoded during storage for consistent type preservation.
-
-**Storage Format:**
-
-```ruby
-# Before (v2.0.0-pre14):
-HGET user:123 name
-"John Doe"                    # Plain string
-
-# After (v2.0.0-pre18):
-HGET user:123 name
-"\"John Doe\""                # JSON-encoded string
-```
-
-**Migration:**
-
-No migration needed. The deserializer automatically handles:
-- **New format**: `"\"value\""` → `"value"`
-- **Legacy format**: `"value"` → `"value"`
-
-**Why This Matters:**
-
-Prevents data corruption for edge cases:
-- Badge `"007"` stays `"007"` (not converted to integer `7`)
-- String `"true"` stays `"true"` (not converted to boolean)
-- String `"null"` stays `"null"` (not converted to `nil`)
-
-## Encrypted Field Security Fix
-
-**What Changed:**
-
-Fields defined with `category: :encrypted` now correctly exclude encrypted data from `to_h()` output.
-
-**Before:**
-```ruby
-field :secret, category: :encrypted
-user.to_h  # => {"id" => "123", "secret" => {...}}  # ❌ Exposed!
-```
-
-**After:**
-```ruby
-field :secret, category: :encrypted
-user.to_h  # => {"id" => "123"}  # ✅ Secure
-```
-
-Both `encrypted_field` and `field :name, category: :encrypted` now behave identically for security.
-
-**Migration:**
-
-No code changes needed. Review any code relying on encrypted fields appearing in `to_h()` output.

data/docs/migrating/v2.0.0-pre19.md

@@ -1,197 +0,0 @@
-# Migrating Guide: v2.0.0-pre19
-
-This version introduces significant improvements to Familia's database operations, making them more atomic, reliable, and consistent with Rails conventions. The changes include enhanced error handling, optimistic locking support, and breaking API changes.
-
-## Breaking Changes
-
-### Management.create → create!
-
-**What Changed:**
-
-The `create` class method has been renamed to `create!` to follow Rails conventions and indicate that it raises exceptions on failure.
-
-**Before:**
-```ruby
-user = User.create(email: "test@example.com")
-```
-
-**After:**
-```ruby
-user = User.create!(email: "test@example.com")
-```
-
-**Why This Matters:**
-
-- Follows Rails naming conventions where `!` methods raise exceptions
-- Makes it clear that `CreationError` will be raised if object already exists
-- Prevents silent failures in object creation
-
-### save_if_not_exists → save_if_not_exists!
-
-**What Changed:**
-
-The `save_if_not_exists` method has been renamed to `save_if_not_exists!` and now includes optimistic locking with automatic retry logic.
-
-**Before:**
-```ruby
-success = user.save_if_not_exists
-```
-
-**After:**
-```ruby
-success = user.save_if_not_exists!
-```
-
-**Behavior Changes:**
-- Now uses Redis WATCH/MULTI/EXEC for optimistic locking
-- Automatically retries up to 3 times on `OptimisticLockError`
-- Raises `RecordExistsError` if object already exists
-- More atomic and thread-safe
-
-## Enhanced Error Handling
-
-### New Error Hierarchy
-
-**What's New:**
-
-A structured error hierarchy provides better error categorization:
-
-```ruby
-Familia::Problem                    # Base class
-├── Familia::PersistenceError       # Redis/database errors
-│   ├── Familia::NonUniqueKey
-│   ├── Familia::OptimisticLockError
-│   ├── Familia::OperationModeError
-│   ├── Familia::NoConnectionAvailable
-│   ├── Familia::NotFound
-│   └── Familia::NotConnected
-└── Familia::HorreumError           # Model-related errors
-    ├── Familia::CreationError
-    ├── Familia::NoIdentifier
-    ├── Familia::FieldTypeError
-    ├── Familia::AutoloadError
-    ├── Familia::SerializerError
-    ├── Familia::UnknownFieldError
-    └── Familia::NotDistinguishableError
-```
-
-**Migration:**
-
-Update exception handling to use specific error classes:
-
-```ruby
-# Before
-rescue Familia::Problem => e
-  # Handle all errors
-
-# After - More granular handling
-rescue Familia::CreationError => e
-  # Handle creation failures specifically
-rescue Familia::OptimisticLockError => e
-  # Handle concurrent modification
-rescue Familia::PersistenceError => e
-  # Handle database-related errors
-```
-
-### New Exception Types
-
-- **`CreationError`**: Raised when object creation fails (replaces generic errors)
-- **`OptimisticLockError`**: Raised when WATCH fails due to concurrent modification
-- **`UnknownFieldError`**: Raised when referencing non-existent fields
-
-## Database Operation Improvements
-
-### Atomic Save Operations
-
-**What Changed:**
-
-The `save` method now uses a single Redis transaction for complete atomicity:
-
-```ruby
-# All operations now happen atomically:
-# 1. Save all fields (HMSET)
-# 2. Set expiration (EXPIRE)
-# 3. Update indexes
-# 4. Add to instances collection
-```
-
-**Benefits:**
-- Eliminates race conditions during save operations
-- Ensures data consistency across related operations
-- Better performance with fewer round trips
-
-### Enhanced Timestamp Precision
-
-**What Changed:**
-
-Created/updated timestamps now use float values instead of integers for higher precision:
-
-**Before:**
-```ruby
-user.created  # => 1697234567 (integer seconds)
-```
-
-**After:**
-```ruby
-user.created  # => 1697234567.123 (float with milliseconds)
-```
-
-**Migration:**
-
-No code changes needed. Existing integer timestamps continue to work.
-
-## Redis Command Enhancements
-
-### New Commands Available
-
-Added support for optimistic locking commands:
-- `watch(key)` - Watch key for changes
-- `unwatch()` - Remove all watches
-- `discard()` - Discard queued commands
-
-### Improved Command Logging
-
-Database command logging now includes:
-- Structured format for better readability
-- Pipelined operation tracking
-- Transaction boundary markers
-- Command timing information
-
-## Terminology Updates
-
-**What Changed:**
-
-Standardized on "pipelined" terminology throughout (previously mixed "pipeline"/"pipelined").
-
-**Files Affected:**
-- Method names now consistently use "pipelined"
-- Documentation updated to match Redis terminology
-- Log messages standardized
-
-**Migration:**
-
-No code changes needed - this was an internal consistency improvement.
-
-## Recommended Actions
-
-1. **Update method calls:**
-   ```ruby
-   # Replace all instances
-   Model.create(...)      → Model.create!(...)
-   obj.save_if_not_exists → obj.save_if_not_exists!
-   ```
-
-2. **Review error handling:**
-   ```ruby
-   # Consider more specific error handling
-   rescue Familia::CreationError
-   rescue Familia::OptimisticLockError
-   ```
-
-3. **Test concurrent operations:**
-   - The new optimistic locking provides better concurrency handling
-   - Verify your application handles `OptimisticLockError` appropriately
-
-4. **Review logging:**
-   - Enhanced database command logging may affect log volume
-   - Adjust log levels if needed for production environments