familia 2.0.0.pre25 → 2.0.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre25
+  version: 2.0.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -9,20 +9,6 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: benchmark
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -194,17 +180,6 @@ files:
 - docs/guides/thread-safety-monitoring.md
 - docs/guides/time-literals.md
 - docs/migrating/.gitignore
-- docs/migrating/v2.0.0-pre.md
-- docs/migrating/v2.0.0-pre11.md
-- docs/migrating/v2.0.0-pre12.md
-- docs/migrating/v2.0.0-pre13.md
-- docs/migrating/v2.0.0-pre14.md
-- docs/migrating/v2.0.0-pre18.md
-- docs/migrating/v2.0.0-pre19.md
-- docs/migrating/v2.0.0-pre22.md
-- docs/migrating/v2.0.0-pre5.md
-- docs/migrating/v2.0.0-pre6.md
-- docs/migrating/v2.0.0-pre7.md
 - docs/overview.md
 - docs/qodo-merge-compliance.md
 - docs/reference/api-technical.md
@@ -377,6 +352,7 @@ files:
 - try/features/relationships/participation_target_class_resolution_try.rb
 - try/features/relationships/participation_through_try.rb
 - try/features/relationships/participation_unresolved_target_try.rb
+- try/features/relationships/prefix_vs_config_name_try.rb
 - try/features/relationships/relationships_api_changes_try.rb
 - try/features/relationships/relationships_edge_cases_try.rb
 - try/features/relationships/relationships_performance_minimal_try.rb
@@ -556,7 +532,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.6
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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

@@ -1,84 +0,0 @@
-# Migrating Guide: v1.x to v2.0.0-pre
-
-This guide covers migrating from Familia v1.x to the v2.0.0-pre foundation release.
-
-## Overview
-
-The v2.0.0-pre series represents a major modernization of Familia with:
-- Complete API redesign for clarity and consistency
-- Valkey compatibility alongside Valkey/Redis support
-- Ruby 3.4+ modernization with improved thread safety
-- New connection pooling architecture
-
-## Step-by-Step Migration
-
-### 1. Update Connection Configuration
-
-**Before (v1.x):**
-```ruby
-Familia.connect('redis://localhost:6379/0')
-```
-
-**After (v2.0.0-pre):**
-```ruby
-Familia.configure do |config|
-  config.redis_uri = 'redis://localhost:6379/0'
-  config.connection_pool = true
-end
-```
-
-### 2. Migrate Identifier Declarations
-
-**Before (v1.x):**
-```ruby
-class User < Familia::Base
-  identifier :user_id
-end
-```
-
-**After (v2.0.0-pre):**
-```ruby
-class User < Familia::Horreum
-  identifier_field :user_id
-end
-```
-
-### 3. Update Feature Activations
-
-**Before (v1.x):**
-```ruby
-class User < Familia::Base
-  include Familia::Features::Expiration
-end
-```
-
-**After (v2.0.0-pre):**
-```ruby
-class User < Familia::Horreum
-  feature :expiration
-end
-```
-
-### 4. Review Method Calls
-
-Several methods were renamed for consistency:
-
-| v1.x Method | v2.0.0-pre Method | Notes |
-|-------------|------------------|-------|
-| `delete` | `destroy` | More semantic naming |
-| `exists` | `exists?` | Ruby predicate convention |
-| `dump` | `serialize` | Clearer intent |
-
-## Breaking Changes
-
-- `Familia::Base` replaced by `Familia::Horreum`
-- Connection configuration moved to block-based setup
-- Feature inclusion changed from `include` to `feature` declarations
-- Several method names updated for consistency
-
-## Next Steps
-
-After completing the foundation migration:
-1. Review [Security Feature Adoption](v2.0.0-pre5.md) for encrypted fields
-2. See [Architecture Migration](v2.0.0-pre6.md) for persistence improvements
-3. Explore [Relationships Migration](v2.0.0-pre7.md) for the new relationship system

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

@@ -1,253 +0,0 @@
-# Migrating Guide: v2.0.0-pre11
-
-This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.
-
-## Enhanced Feature System
-
-### Model-Specific Feature Registration
-
-Previously, all features were registered globally. Now you can register features specific to individual model classes, allowing for better organization and namespace management.
-
-#### Before
-```ruby
-# Global feature registration only
-module MyProjectFeature
-  # Feature implementation
-end
-Familia::Base.add_feature MyProjectFeature, :my_project_feature
-
-class Customer < Familia::Horreum
-  feature :my_project_feature
-end
-
-class Session < Familia::Horreum
-  feature :my_project_feature  # Same global feature
-end
-```
-
-#### After
-```ruby
-# Model-specific feature registration
-module CustomerSpecificFeature
-  # Feature implementation
-end
-
-# Register feature only for Customer and its subclasses
-Customer.add_feature CustomerSpecificFeature, :customer_specific
-
-class Customer < Familia::Horreum
-  feature :customer_specific  # Available via Customer's registry
-end
-
-class PremiumCustomer < Customer
-  feature :customer_specific  # Inherited via ancestry chain
-end
-
-class Session < Familia::Horreum
-  # feature :customer_specific  # Not available - would raise error
-end
-```
-
-**Benefits:**
-- Features can have the same name across different model hierarchies
-- Standardized naming: `deprecated_fields.rb` instead of `customer_deprecated_fields.rb`
-- Natural inheritance through Ruby's class hierarchy
-
-## SafeDump DSL Improvements
-
-The new DSL replaces the brittle `@safe_dump_fields` class instance variable pattern with clean, explicit methods.
-
-### Before
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-
-  # Brittle - hard to move to feature modules, confusing syntax
-  @safe_dump_fields = [
-    :custid,
-    :email,
-    { active: ->(obj) { obj.active? } },
-    { display_name: ->(obj) { "#{obj.name} (#{obj.custid})" } }
-  ]
-end
-```
-
-### After
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-
-  # Clean DSL - easy to understand and organize
-  safe_dump_field :custid
-  safe_dump_field :email
-  safe_dump_field :active, ->(obj) { obj.active? }
-  safe_dump_field :display_name, ->(obj) { "#{obj.name} (#{obj.custid})" }
-
-  # Or define multiple fields at once
-  safe_dump_fields :created, :updated, { status: ->(obj) { obj.role } }
-end
-```
-
-**New methods available:**
-- `safe_dump_field(name, callable = nil)` - Define a single field
-- `safe_dump_fields(*fields)` - Define multiple fields or get field names
-- `safe_dump_field_names` - Get array of field names
-- `safe_dump_field_map` - Get the internal callable map
-
-**Backward Compatibility:**
-- `set_safe_dump_fields(*fields)` - Legacy setter method (still works)
-- The old `@safe_dump_fields` pattern is no longer supported
-
-## Auto-loading Features
-
-### Before: Manual Loading
-```ruby
-# customer/features.rb
-
-# Manual feature loading (copied from Familia)
-features_dir = File.join(__dir__, 'features')
-if Dir.exist?(features_dir)
-  Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
-    require_relative feature_file
-  end
-end
-
-class Customer < Familia::Horreum
-  # Features now available for use
-  feature :deprecated_fields
-end
-```
-
-### After: Automatic Loading
-```ruby
-# customer/features.rb
-
-class Customer < Familia::Horreum
-  module Features
-    include Familia::Features::Autoloader
-    # Automatically discovers and loads all *.rb files from customer/features/
-  end
-end
-
-class Customer < Familia::Horreum
-  # Features automatically loaded and available
-  feature :deprecated_fields
-end
-```
-
-**Directory structure this enables:**
-```
-models/
-├── customer/
-│   ├── features/
-│   │   ├── deprecated_fields.rb      # Standardized names!
-│   │   ├── legacy_support.rb
-│   │   └── stripe_integration.rb
-│   └── features.rb                   # Include Autoloader here
-├── session/
-│   ├── features/
-│   │   ├── deprecated_fields.rb      # Same name, different implementation
-│   │   └── expiration_hooks.rb
-│   └── features.rb
-└── customer.rb
-```
-
-## Field Definitions in Feature Modules
-
-Feature modules can now define fields directly in their `ClassMethods` modules. When a class extends the module, the field definitions execute in the extending class's context.
-
-### Example
-```ruby
-# features/common_fields.rb
-
-module CommonFields
-  def self.included(base)
-    base.extend ClassMethods
-  end
-
-  module ClassMethods
-    # These field calls execute in the extending class's context
-    field :created
-    field :updated
-    field :version
-
-    def touch_updated
-      self.updated = Familia.now.to_i
-    end
-  end
-
-  Familia::Base.add_feature self, :common_fields
-end
-
-# Usage
-class Customer < Familia::Horreum
-  feature :common_fields
-  # Now has :created, :updated, :version fields and touch_updated class method
-end
-```
-
-## Migration Steps
-
-### 1. Update SafeDump Usage
-Replace all `@safe_dump_fields` definitions with the new DSL:
-
-```ruby
-# Find and replace pattern:
-# Old: @safe_dump_fields = [:field1, :field2, { field3: ->(obj) { ... } }]
-# New: safe_dump_fields :field1, :field2, { field3: ->(obj) { ... } }
-
-# Or use individual field definitions for better readability:
-safe_dump_field :field1
-safe_dump_field :field2
-safe_dump_field :field3, ->(obj) { ... }
-```
-
-### 2. UnsortedSet Up Auto-loading (Optional)
-If you have project-specific features, set up auto-loading:
-
-```ruby
-# Create: models/[model_name]/features.rb
-module YourProject
-  class ModelName < Familia::Horreum
-    module Features
-      include Familia::Features::Autoloader
-    end
-  end
-end
-
-# Require this file before your model definitions
-require_relative 'model_name/features'
-```
-
-### 3. Organize Features by Model (Optional)
-Consider reorganizing shared feature names by model:
-
-```ruby
-# Before: features/customer_deprecated_fields.rb
-# After: models/customer/features/deprecated_fields.rb
-
-# This allows multiple models to have their own deprecated_fields.rb
-```
-
-### 4. Test Your Changes
-Run your test suite to ensure all SafeDump functionality works correctly:
-
-```ruby
-# Verify SafeDump DSL works
-model = YourModel.new(field1: 'value')
-result = model.safe_dump
-puts result.keys  # Should include your defined fields
-```
-
-## Breaking Changes
-
-1. **`@safe_dump_fields` no longer supported** - Must migrate to DSL methods
-2. **SafeDump field order** - Fields are now returned in definition order via Hash keys (Ruby 1.9+ behavior)
-
-## New Capabilities Unlocked
-
-1. **Standardized feature names** across different models
-2. **Cleaner SafeDump definitions** that can be easily moved to feature modules
-3. **Automatic feature discovery** for better project organization
-4. **Model-specific feature registries** for better namespace management
-5. **Field definitions in feature modules** for shared functionality

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')}"
-```