familia 2.0.0.pre18 → 2.0.0.pre21

data/docs/archive/FAMILIA_UPDATE.md

@@ -1,226 +0,0 @@
-# Familia v2.0.0-pre Series Update Overview
-
-**Familia** is a Ruby ORM for Redis/Valkey that provides object mapping and persistence capabilities. This document summarizes the major updates from v2.0.0-pre through v2.0.0-pre7, representing a significant evolution with new features, security enhancements, and architectural improvements.
-
-## Version Summary
-
-| Version | Focus | Key Features |
-|---------|-------|-------------|
-| v2.0.0-pre | Foundation | Modern API, Valkey support, connection pooling |
-| v2.0.0-pre5 | Security | Encrypted fields, transient fields, RedactedString |
-| v2.0.0-pre6 | Architecture | Horreum reorganization, enhanced persistence |
-| v2.0.0-pre7 | Relationships | Comprehensive relationship system, permissions |
-
----
-
-## v2.0.0-pre - Foundation Release
-
-### Major API Modernization
-- **Complete API redesign** for clarity and modern Ruby conventions
-- **Valkey compatibility** alongside traditional Valkey/Redis support
-- **Ruby 3.4+ modernization** with fiber and thread safety improvements
-- **Connection pooling foundation** with provider pattern architecture
-
-### Security & Dependency Management
-- **Critical security fixes** in Ruby workflow vulnerabilities
-- **Systematic dependency resolution** via multi-constraint optimization
-- **GitHub Actions security hardening** with matrix optimization
-
-### Documentation Infrastructure
-- **YARD documentation workflow** with automated GitHub Pages deployment
-- **Comprehensive wiki system** with structured documentation
-- **Developer-focused guides** for implementation and usage
-
----
-
-## v2.0.0-pre5 - Security Enhancement Release
-
-### Encrypted Fields System
-- **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
-
-```ruby
-class Vault < Familia::Horreum
-  feature :encrypted_fields
-
-  field :name                    # Plaintext
-  encrypted_field :secret_key    # Encrypted at rest
-  encrypted_field :api_token     # Transparent access
-end
-```
-
-### Transient Fields & RedactedString
-- **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
-
-```ruby
-class User < Familia::Horreum
-  feature :transient_fields
-
-  field :email
-  transient_field :password      # Never persisted
-  transient_field :session_token # Runtime only
-end
-```
-
-### Connection Pooling Enhancement
-- **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
-
----
-
-## v2.0.0-pre6 - Architecture Enhancement Release
-
-### Horreum Architecture Reorganization
-- **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**
-
-### Enhanced Persistence Operations
-- **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
-
-### Security Improvements
-- **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
-
----
-
-## v2.0.0-pre7 - Relationships & Permissions Release
-
-### Comprehensive Relationships System
-- **Three relationship types** optimized for different use cases:
-  - `participates_in` - Multi-presence tracking with score encoding
-  - `indexed_by` - O(1) hash-based lookups
-  - `member_of` - Bidirectional membership with collision-free naming
-
-```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-
-  identifier_field :custid
-  field :custid, :name, :email
-
-  # Define collections
-  set :domains
-  participates_in :active_users, type: :sorted_set
-end
-
-class Domain < Familia::Horreum
-  feature :relationships
-
-  identifier_field :domain_id
-  field :domain_id, :name
-
-  # Bidirectional relationship
-  member_of Customer, :domains, type: :set
-end
-```
-
-### Categorical Permission System
-- **Bit-encoded permissions** for efficient storage and querying
-- **Time-based permission scoring** for temporal access control
-- **Permission tier hierarchies** with inheritance patterns
-- **Scalable permission management** for large object collections
-
-### Advanced Relationship Features
-- **Score-based sorting** with custom scoring functions
-- **Permission-aware queries** filtering by access levels
-- **Relationship validation framework** ensuring data integrity
-- **Performance optimizations** for large-scale relationship operations
-
----
-
-## Breaking Changes & Migration
-
-### v2.0.0-pre Series
-- **API method renaming** for consistency and clarity
-- **Configuration changes** in connection management
-- **Feature activation syntax** updates for the new system
-- **Identifier field declaration** syntax modernization
-
-### Security Considerations
-- **Encryption key configuration** required for encrypted fields
-- **Memory handling changes** for sensitive data protection
-- **Permission system migration** for existing relationship data
-
----
-
-## Performance Improvements
-
-### Connection Management
-- **Pool-based connections** reducing connection overhead
-- **Intelligent connection reuse** across operations
-- **Concurrent operation support** with thread-safe pooling
-
-### Relationship Operations
-- **O(1) indexed lookups** for field-based queries
-- **Optimized sorted set operations** for scored relationships
-- **Batch relationship operations** for bulk updates
-- **Memory-efficient bit encoding** for permission storage
-
-### Feature System
-- **Lazy feature loading** reducing memory footprint
-- **Dependency-aware activation** preventing conflicts
-- **Optimized method dispatch** for feature methods
-
----
-
-## Migrating Guide Summary
-
-### From v1.x to v2.0.0-pre
-1. **Update connection configuration** to use new pooling system
-2. **Migrate identifier declarations** to new syntax
-3. **Update feature activations** to use `feature :name` syntax
-4. **Review method calls** for renamed API methods
-
-### Security Feature Adoption
-1. **Configure encryption keys** for encrypted fields
-2. **Identify sensitive fields** for encryption/transient marking
-3. **Update serialization code** to handle RedactedString
-4. **Implement key rotation procedures** for production systems
-
-### Relationship System Migration
-1. **Analyze existing relationships** for optimization opportunities
-2. **Choose appropriate relationship types** based on usage patterns
-3. **Implement permission systems** for access-controlled relationships
-4. **Update queries** to use new relationship methods
-
----
-
-## Next Steps & Roadmap
-
-### Immediate (v2.0.0 Final)
-- **Production stability** testing and bug fixes
-- **Performance benchmarking** and optimization
-- **Documentation completion** for all features
-- **Migration tooling** for existing applications
-
-### Future Releases
-- **Advanced encryption features** with hardware security modules
-- **Extended relationship types** for specialized use cases
-- **Performance analytics** and monitoring integration
-- **Cloud-native deployment** patterns and examples
-
----
-
-## Resources
-
-- [GitHub Repository](https://github.com/delano/familia)
-- [Wiki Documentation](https://github.com/delano/familia/wiki)
-- [API Reference](docs/wiki/API-Reference.md)
-- [Implementation Guide](docs/wiki/Implementation-Guide.md)
-- [Security Model](docs/wiki/Security-Model.md)

data/docs/archive/README.md

@@ -1,64 +0,0 @@
-# Archived Documentation
-
-This directory contains original documentation files that have either been migrated to the new Scriv-based changelog system or incorporated into other documents.
-
-## Migration Date
-**Sept 22, 1015** - Deprecated api-reference.md, to reduce surface area for stale documentation to hide.
-**Sept 1, 2025** - As part of implementing [Issue #84: Scriv-based changelog system](https://github.com/delano/familia/issues/84)
-
-## Archived Files
-
-### FAMILIA_UPDATE.md
-**Original Purpose:** Version summary table and detailed release notes for v2.0.0-pre series
-
-**Migrating Destinations:**
-- **Changelog entries** → Extracted to Scriv fragments, aggregated into `CHANGELOG.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
-**Original Purpose:** Auto-generated relationship methods reference
-
-**Migration Destination:**
-- **Complete content** → Moved to `docs/guides/relationships-methods.md`
-- **Cross-referenced** with existing `docs/guides/Relationships-Guide.md`
-
-### FAMILIA_TECHNICAL.md
-**Original Purpose:** Technical API reference for v2.0.0-pre series classes and methods
-
-**Migration Destination:**
-- **Core technical content** → Moved to `docs/reference/api-technical.md`
-- **Cross-referenced** with existing `docs/guides/API-Reference.md`
-
-## New Documentation Structure
-
-```
-docs/
-├── 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
-│
-└── archive/                # This directory
-```
-
-## Finding Migrated Content
-
-- **Version changes** → Check `CHANGELOG.md` (generated from fragments)
-- **How to upgrade** → See `docs/migration/` for version-specific guides
-- **Feature usage** → See `docs/guides/` for implementation examples
-- **API reference** → See `docs/reference/` for technical details
-
-## References
-
-- [Issue #84](https://github.com/delano/familia/issues/84) - Original migration plan
-- [Scriv Documentation](https://scriv.readthedocs.io/) - Changelog management tool
-- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard

data/docs/archive/api-reference.md

@@ -1,333 +0,0 @@
-# API Reference
-
-> [!NOTE]
-> This document is deprecated. For comprehensive encryption API documentation, see [`docs/reference/api-technical.md`](../reference/api-technical.md) which contains complete implementation details and examples.
-
-## Class Methods
-
-### encrypted_field
-
-Defines an encrypted field on a Familia::Horreum class.
-
-```ruby
-encrypted_field(name, aad_fields: [], **options)
-```
-
-**Parameters:**
-- `name` (Symbol) - Field name
-- `aad_fields` (Array<Symbol>) - Additional fields to include in authentication
-- `**options` (Hash) - Standard field options
-
-**Example:**
-```ruby
-class User < Familia::Horreum
-  feature :encrypted_fields
-
-  encrypted_field :favorite_snack
-  encrypted_field :api_key
-  encrypted_field :notes, aad_fields: [:user_id, :email]  # With tamper protection
-end
-```
-
-### encrypted_fields
-
-Returns list of encrypted field names.
-
-```ruby
-User.encrypted_fields  # => [:favorite_snack, :api_key]
-```
-
-## Instance Methods
-
-### Field Accessors
-
-Encrypted fields provide standard accessors that return ConcealedString objects:
-
-```ruby
-user.favorite_snack           # Returns ConcealedString (safe for logging)
-user.favorite_snack.reveal   # Get actual decrypted value
-user.favorite_snack = value   # Set and encrypt value
-user.favorite_snack!          # Fast write (still encrypted)
-```
-
-**ConcealedString Methods:**
-```ruby
-concealed = user.favorite_snack
-concealed.to_s                # => "[CONCEALED]" (safe for logging)
-concealed.reveal              # => "actual value"
-concealed.clear!              # Clear from memory
-concealed.cleared?            # Check if cleared
-```
-
-## Familia::Encryption Module
-
-### with_request_cache
-
-Enables key derivation caching for performance optimization:
-
-```ruby
-Familia::Encryption.with_request_cache do
-  # Multiple encryption operations reuse derived keys
-  user.secret_one = "value1"
-  user.secret_two = "value2"
-  user.save
-end
-```
-
-### clear_request_cache!
-
-Manually clears the request-level key cache:
-
-```ruby
-Familia::Encryption.clear_request_cache!
-```
-
-### encrypt / decrypt
-
-Low-level encryption methods (typically used internally):
-
-```ruby
-# Encrypt with context for key derivation
-encrypted = Familia::Encryption.encrypt(plaintext,
-  context: "User:favorite_snack:user123",
-  additional_data: nil
-)
-
-# Decrypt (auto-detects algorithm from JSON)
-decrypted = Familia::Encryption.decrypt(encrypted_json,
-  context: "User:favorite_snack:user123",
-  additional_data: nil
-)
-```
-
-### status
-
-Returns current encryption configuration and available providers.
-
-```ruby
-Familia::Encryption.status
-# => {
-#   default_algorithm: "xchacha20poly1305",
-#   available_algorithms: ["xchacha20poly1305", "aes-256-gcm"],
-#   preferred_available: "Familia::Encryption::Providers::XChaCha20Poly1305Provider",
-#   using_hardware: false,
-#   key_versions: [:v1],
-#   current_version: :v1
-# }
-```
-
-### benchmark
-
-Benchmarks available providers.
-
-```ruby
-Familia::Encryption.benchmark(iterations: 1000)
-# => {
-#   "xchacha20poly1305" => { time: 0.45, ops_per_sec: 4444, priority: 100 },
-#   "aes-256-gcm" => { time: 0.52, ops_per_sec: 3846, priority: 50 }
-# }
-```
-
-### validate_configuration!
-
-Validates encryption configuration at startup.
-
-```ruby
-Familia::Encryption.validate_configuration!
-# Raises Familia::EncryptionError if configuration invalid
-```
-
-### derivation_count / reset_derivation_count!
-
-Monitors key derivation operations (for testing and debugging).
-
-```ruby
-# Check how many key derivations have occurred
-count = Familia::Encryption.derivation_count.value
-# => 42
-
-# Reset counter
-Familia::Encryption.reset_derivation_count!
-```
-
-## Familia::Encryption::Manager
-
-Low-level manager class for direct provider control.
-
-### initialize
-
-```ruby
-# Use default provider
-manager = Familia::Encryption::Manager.new
-
-# Use specific algorithm
-manager = Familia::Encryption::Manager.new(algorithm: 'aes-256-gcm')
-```
-
-### encrypt / decrypt
-
-Same interface as module-level methods but tied to specific provider.
-
-## Familia::Encryption::Registry
-
-Provider management system.
-
-### setup!
-
-Registers all available providers.
-
-### get
-
-Returns provider instance by algorithm name.
-
-### default_provider
-
-Returns highest-priority available provider instance.
-
-### available_algorithms
-
-Returns array of available algorithm names.
-
-## Configuration
-
-### Familia.configure
-
-```ruby
-Familia.configure do |config|
-  # Single key configuration
-  config.encryption_keys = {
-    v1: ENV['FAMILIA_ENCRYPTION_KEY']
-  }
-  config.current_key_version = :v1
-
-  # Multi-version configuration for key rotation
-  config.encryption_keys = {
-    v1_2024: ENV['OLD_KEY'],
-    v2_2025: ENV['NEW_KEY']
-  }
-  config.current_key_version = :v2_2025
-
-  # Optional personalization (XChaCha20-Poly1305 only)
-  config.encryption_personalization = 'MyApp-2024'
-end
-
-# Always validate configuration
-Familia::Encryption.validate_configuration!
-```
-
-## Data Types
-
-### EncryptedData
-
-Internal data structure for encrypted values.
-
-```ruby
-EncryptedData = Data.define(
-  :library,      # "libsodium" or "openssl"
-  :algorithm,    # "xchacha20poly1305" or "aes-256-gcm"
-  :nonce,        # Base64-encoded nonce/IV
-  :ciphertext,   # Base64-encoded ciphertext
-  :key_version   # Key version identifier
-)
-```
-
-### ConcealedString
-
-String-like object that conceals sensitive data in output and provides memory safety.
-
-```ruby
-class ConcealedString
-  def reveal
-    # Returns actual decrypted string value
-  end
-
-  def to_s
-    '[CONCEALED]'
-  end
-
-  def inspect
-    '[CONCEALED]'
-  end
-
-  def clear!
-    # Best-effort memory wiping
-  end
-
-  def cleared?
-    # Returns true if cleared from memory
-  end
-end
-```
-
-## Exceptions
-
-### Familia::EncryptionError
-
-Raised for encryption/decryption failures.
-
-```ruby
-begin
-  user.decrypt_field(:favorite_snack)
-rescue Familia::EncryptionError => e
-  case e.message
-  when /key version/
-    # Handle key version mismatch
-  when /authentication/
-    # Handle tampering
-  else
-    # Handle other errors
-  end
-end
-```
-
-## Instance Methods
-
-### encrypted_data?
-
-Check if any encrypted fields have values:
-
-```ruby
-user.encrypted_data?  # => true if any encrypted fields have values
-```
-
-### clear_encrypted_fields!
-
-Clear all encrypted field values from memory:
-
-```ruby
-user.clear_encrypted_fields!  # Clear all ConcealedString values
-```
-
-### encrypted_fields_cleared?
-
-Check if all encrypted fields have been cleared:
-
-```ruby
-user.encrypted_fields_cleared?  # => true if all cleared
-```
-
-### re_encrypt_fields!
-
-Re-encrypt all encrypted fields with current key version:
-
-```ruby
-user.re_encrypt_fields!  # Uses current_key_version
-user.save
-```
-
-### encrypted_fields_status
-
-Get encryption status for debugging:
-
-```ruby
-user.encrypted_fields_status
-# => {
-#   ssn: { encrypted: true, cleared: false },
-#   credit_card: { encrypted: true, cleared: true }
-# }
-```
-
----
-
-> [!IMPORTANT]
-> For complete implementation details, configuration examples, and advanced usage patterns, see the comprehensive documentation in [`docs/reference/api-technical.md`](../reference/api-technical.md).