familia 2.0.0.pre15 → 2.0.0.pre17

data/docs/archive/FAMILIA_TECHNICAL.md

@@ -1,6 +1,6 @@
 # Familia v2.0.0-pre Series Technical Reference
 
-**Familia** is a Ruby ORM for Redis/Valkey providing object mapping, relationships, and advanced features like encryption, connection pooling, and permission systems. This technical reference covers the major classes, methods, and usage patterns introduced in the v2.0.0-pre series.
+**Familia** is a Ruby ORM for Valkey/Redis providing object mapping, relationships, and advanced features like encryption, connection pooling, and permission systems. This technical reference covers the major classes, methods, and usage patterns introduced in the v2.0.0-pre series.
 
 ---
 
@@ -9,37 +9,37 @@
 ### Base Classes
 
 #### `Familia::Horreum` - Primary ORM Base Class
-The main base class for Redis-backed objects, similar to ActiveRecord models.
+The main base class for Valkey/Redis-backed objects, similar to ActiveRecord models.
 
 ```ruby
 class User < Familia::Horreum
   # Basic field definitions
   field :name, :email, :created_at
 
-  # Redis data types as instance variables
-  list :sessions      # Redis list
-  set :tags          # Redis set
-  sorted_set :scores # Redis sorted set
-  hash :settings     # Redis hash
+  # Valkey/Redis data types as instance variables
+  list :sessions      # Valkey/Redis list
+  set :tags          # Valkey/Redis set
+  sorted_set :scores # Valkey/Redis sorted set
+  hash :settings     # Valkey/Redis hash
 end
 ```
 
 **Key Methods:**
-- `save` - Persist object to Redis
+- `save` - Persist object to Valkey/Redis
 - `save_if_not_exists` - Conditional persistence (v2.0.0-pre6)
-- `load` - Load object from Redis
-- `exists?` - Check if object exists in Redis
-- `destroy` - Remove object from Redis
+- `load` - Load object from Valkey/Redis
+- `exists?` - Check if object exists in Valkey/Redis
+- `destroy` - Remove object from Valkey/Redis
 
-#### `Familia::DataType` - Redis Data Type Wrapper
-Base class for Redis data type implementations.
+#### `Familia::DataType` - Valkey/Redis Data Type Wrapper
+Base class for Valkey/Redis data type implementations.
 
 **Registered Types:**
-- `String` - Redis strings
-- `List` - Redis lists
-- `Set` - Redis sets
-- `SortedSet` - Redis sorted sets
-- `HashKey` - Redis hashes
+- `String` - Valkey/Redis strings
+- `List` - Valkey/Redis lists
+- `UnsortedSet` - Valkey/Redis sets
+- `SortedSet` - Valkey/Redis sorted sets
+- `HashKey` - Valkey/Redis hashes
 - `Counter` - Atomic counters
 - `Lock` - Distributed locks
 
@@ -82,7 +82,7 @@ end
 
 session = Session.new(user_id: 123, token: "abc123")
 session.save
-session.expire_in(1.hour)  # Set custom expiration
+session.expire_in(1.hour)  # UnsortedSet custom expiration
 session.ttl                # Check remaining time
 ```
 
@@ -152,7 +152,7 @@ class LoginForm < Familia::Horreum
   feature :transient_fields
 
   field :username              # Persistent
-  transient_field :password    # Never stored in Redis
+  transient_field :password    # Never stored in Valkey/Redis
   transient_field :csrf_token  # Runtime only
 end
 
@@ -188,7 +188,7 @@ class Customer < Familia::Horreum
   indexed_by :email_lookup, field: :email
 
   # Global tracking with scoring
-  tracked_in :all_customers, type: :sorted_set, score: :created_at
+  participates_in :all_customers, type: :sorted_set, score: :created_at
 end
 
 class Domain < Familia::Horreum
@@ -201,8 +201,8 @@ class Domain < Familia::Horreum
   member_of Customer, :domains, type: :set
 
   # Conditional tracking with lambda scoring
-  tracked_in :active_domains, type: :sorted_set,
-    score: ->(domain) { domain.status == 'active' ? Time.now.to_i : 0 }
+  participates_in :active_domains, type: :sorted_set,
+    score: ->(domain) { domain.status == 'active' ? Familia.now.to_i : 0 }
 end
 ```
 
@@ -228,7 +228,7 @@ found_id = Customer.email_lookup.get(customer.email)  # O(1) lookup
 # Global tracking
 Customer.add_to_all_customers(customer)
 recent = Customer.all_customers.range_by_score(
-  (Time.now - 24.hours).to_i, '+inf'
+  (Familia.now - 24.hours).to_i, '+inf'
 )
 ```
 
@@ -240,7 +240,7 @@ recent = Customer.all_customers.range_by_score(
 Flexible connection pooling with provider-based architecture.
 
 ```ruby
-# Basic Redis connection
+# Basic Valkey/Redis connection
 Familia.configure do |config|
   config.redis_uri = "redis://localhost:6379/0"
 end
@@ -331,7 +331,7 @@ end
 # Usage example
 user_id = "user123"
 doc_id = "doc456"
-timestamp = Time.now.to_i
+timestamp = Familia.now.to_i
 
 # Grant read + write permissions
 permissions = Document::READ | Document::WRITE  # 3
@@ -356,25 +356,25 @@ class ActivityTracker < Familia::Horreum
   feature :relationships
 
   # Track user activities with timestamps
-  tracked_in :user_activities, type: :sorted_set,
+  participates_in :user_activities, type: :sorted_set,
     score: ->(activity) { activity.created_at }
 
   # Track by activity type
-  tracked_in :activity_by_type, type: :sorted_set,
+  participates_in :activity_by_type, type: :sorted_set,
     score: ->(activity) { "#{activity.activity_type}:#{activity.created_at}".hash }
 
   field :user_id, :activity_type, :data, :created_at
 end
 
 # Query recent activities (last hour)
-hour_ago = (Time.now - 1.hour).to_i
+hour_ago = (Familia.now - 1.hour).to_i
 recent_activities = ActivityTracker.user_activities.range_by_score(
   hour_ago, '+inf', limit: [0, 50]
 )
 
 # Get activities by type in time range
 login_activities = ActivityTracker.activity_by_type.range_by_score(
-  "login:#{hour_ago}".hash, "login:#{Time.now.to_i}".hash
+  "login:#{hour_ago}".hash, "login:#{Familia.now.to_i}".hash
 )
 ```
 
@@ -382,8 +382,8 @@ login_activities = ActivityTracker.activity_by_type.range_by_score(
 
 ## Data Type Usage Patterns
 
-### Advanced Sorted Set Operations
-Leverage Redis sorted sets for rankings, time series, and scored data.
+### Advanced Sorted UnsortedSet Operations
+Leverage Valkey/Redis sorted sets for rankings, time series, and scored data.
 
 ```ruby
 class Leaderboard < Familia::Horreum
@@ -414,7 +414,7 @@ leaderboard.scores.increment("player1", 100)  # Add 100 to existing score
 ```
 
 ### List-Based Queues and Feeds
-Use Redis lists for queues, feeds, and ordered data.
+Use Valkey/Redis lists for queues, feeds, and ordered data.
 
 ```ruby
 class TaskQueue < Familia::Horreum
@@ -447,7 +447,7 @@ task_data = JSON.parse(next_task) if next_task
 feed = ActivityFeed.new(user_id: "user123")
 
 # Add activity (keep last 100)
-feed.activities.unshift("User logged in at #{Time.now}")
+feed.activities.unshift("User logged in at #{Familia.now}")
 feed.activities.trim(0, 99)  # Keep only last 100 items
 
 # Get recent activities
@@ -492,7 +492,7 @@ beta_enabled = prefs.feature_flags.get("beta_ui") == "true"
 ## Error Handling and Validation
 
 ### Connection Error Handling
-Robust error handling for Redis connection issues.
+Robust error handling for Valkey/Redis connection issues.
 
 ```ruby
 class ResilientService < Familia::Horreum
@@ -508,7 +508,7 @@ class ResilientService < Familia::Horreum
         sleep(0.1 * (4 - retries))  # Exponential backoff
         retry
       else
-        Familia.warn "Redis operation failed after retries: #{e.message}"
+        Familia.warn "Valkey/Redis operation failed after retries: #{e.message}"
         nil  # Return nil or handle gracefully
       end
     end
@@ -574,7 +574,7 @@ end
 ## Performance Optimization
 
 ### Batch Operations
-Minimize Redis round trips with batch operations.
+Minimize Valkey/Redis round trips with batch operations.
 
 ```ruby
 # Instead of multiple individual operations
@@ -584,7 +584,7 @@ users = []
   users << user
 end
 
-# Use Redis pipelining for batch saves
+# Use Valkey/Redis pipelining for batch saves
 User.transaction do |redis|
   users.each do |user|
     # All operations batched in transaction
@@ -720,9 +720,9 @@ Common patterns for testing Familia applications.
 # test_helper.rb
 require 'familia'
 
-# Use separate Redis database for tests
+# Use separate Valkey/Redis database for tests
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:6379/15')
+  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:2525/3')
 end
 
 module TestHelpers
@@ -739,7 +739,7 @@ module TestHelpers
     User.new({
       email: "test@example.com",
       name: "Test User",
-      created_at: Time.now.to_i
+      created_at: Familia.now.to_i
     }.merge(attrs))
   end
 end
@@ -787,7 +787,7 @@ Essential configuration options for Familia v2.0.0-pre.
 
 ```ruby
 Familia.configure do |config|
-  # Basic Redis connection
+  # Basic Valkey/Redis connection
   config.redis_uri = ENV['REDIS_URL'] || 'redis://localhost:6379/0'
 
   # Connection provider for pooling (optional)

data/docs/archive/FAMILIA_UPDATE.md

@@ -17,7 +17,7 @@
 
 ### Major API Modernization
 - **Complete API redesign** for clarity and modern Ruby conventions
-- **Valkey compatibility** alongside traditional Redis support
+- **Valkey compatibility** alongside traditional Valkey/Redis support
 - **Ruby 3.4+ modernization** with fiber and thread safety improvements
 - **Connection pooling foundation** with provider pattern architecture
 
@@ -103,7 +103,7 @@ end
 
 ### Comprehensive Relationships System
 - **Three relationship types** optimized for different use cases:
-  - `tracked_in` - Multi-presence tracking with score encoding
+  - `participates_in` - Multi-presence tracking with score encoding
   - `indexed_by` - O(1) hash-based lookups
   - `member_of` - Bidirectional membership with collision-free naming
 
@@ -116,7 +116,7 @@ class Customer < Familia::Horreum
 
   # Define collections
   set :domains
-  tracked_in :active_users, type: :sorted_set
+  participates_in :active_users, type: :sorted_set
 end
 
 class Domain < Familia::Horreum

data/docs/archive/README.md

@@ -1,9 +1,10 @@
 # Archived Documentation
 
-This directory contains original documentation files that have been migrated to the new Scriv-based changelog system and reorganized documentation structure.
+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
-**September 1, 2025** - As part of implementing [Issue #84: Scriv-based changelog system](https://github.com/delano/familia/issues/84)
+**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
 

data/docs/{guides/API-Reference.md → archive/api-reference.md}

@@ -1,5 +1,8 @@
 # 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
@@ -7,22 +10,22 @@
 Defines an encrypted field on a Familia::Horreum class.
 
 ```ruby
-encrypted_field(name, **options)
+encrypted_field(name, aad_fields: [], **options)
 ```
 
 **Parameters:**
 - `name` (Symbol) - Field name
-- `**options` (Hash) - Standard field options plus encryption-specific options
-
-**Options:**
-- `:as` - Custom accessor method name
-- `:on_conflict` - Conflict resolution (always `:raise` for encrypted fields)
+- `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, as: :secret_key
+  encrypted_field :api_key
+  encrypted_field :notes, aad_fields: [:user_id, :email]  # With tamper protection
 end
 ```
 
@@ -38,63 +41,60 @@ User.encrypted_fields  # => [:favorite_snack, :api_key]
 
 ### Field Accessors
 
-Encrypted fields provide standard accessors:
+Encrypted fields provide standard accessors that return ConcealedString objects:
 
 ```ruby
-user.favorite_snack           # Get decrypted value
+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)
 ```
 
-### Passphrase-Protected Access
-
+**ConcealedString Methods:**
 ```ruby
-# For passphrase-protected fields
-vault.secret_data(passphrase_value: "user_passphrase")
+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
 
-### manager
+### with_request_cache
 
-Creates a manager instance with optional algorithm selection.
+Enables key derivation caching for performance optimization:
 
 ```ruby
-# Use best available provider
-mgr = Familia::Encryption.manager
-
-# Use specific algorithm
-mgr = Familia::Encryption.manager(algorithm: 'xchacha20poly1305')
+Familia::Encryption.with_request_cache do
+  # Multiple encryption operations reuse derived keys
+  user.secret_one = "value1"
+  user.secret_two = "value2"
+  user.save
+end
 ```
 
-### encrypt
+### clear_request_cache!
 
-Encrypts plaintext using the default provider.
+Manually clears the request-level key cache:
 
 ```ruby
-Familia::Encryption.encrypt(plaintext,
-  context: "User:favorite_snack:user123",
-  additional_data: nil
-)
+Familia::Encryption.clear_request_cache!
 ```
 
-### encrypt_with
+### encrypt / decrypt
 
-Encrypts plaintext with a specific algorithm.
+Low-level encryption methods (typically used internally):
 
 ```ruby
-Familia::Encryption.encrypt_with('aes-256-gcm', plaintext,
+# Encrypt with context for key derivation
+encrypted = Familia::Encryption.encrypt(plaintext,
   context: "User:favorite_snack:user123",
   additional_data: nil
 )
-```
 
-### decrypt
-
-Decrypts ciphertext (auto-detects algorithm from JSON).
-
-```ruby
-Familia::Encryption.decrypt(encrypted_json,
+# Decrypt (auto-detects algorithm from JSON)
+decrypted = Familia::Encryption.decrypt(encrypted_json,
   context: "User:favorite_snack:user123",
   additional_data: nil
 )
@@ -200,16 +200,19 @@ Familia.configure do |config|
   }
   config.current_key_version = :v1
 
-  # Multi-version configuration
+  # 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
 
-  # Key cache TTL (seconds)
-  config.key_cache_ttl = 300  # Default: 5 minutes
+  # Optional personalization (XChaCha20-Poly1305 only)
+  config.encryption_personalization = 'MyApp-2024'
 end
+
+# Always validate configuration
+Familia::Encryption.validate_configuration!
 ```
 
 ## Data Types
@@ -228,18 +231,30 @@ EncryptedData = Data.define(
 )
 ```
 
-### RedactedString
+### ConcealedString
 
-String subclass that redacts sensitive data in output.
+String-like object that conceals sensitive data in output and provides memory safety.
 
 ```ruby
-class RedactedString < String
+class ConcealedString
+  def reveal
+    # Returns actual decrypted string value
+  end
+
   def to_s
-    '[REDACTED]'
+    '[CONCEALED]'
   end
 
   def inspect
-    '[REDACTED]'
+    '[CONCEALED]'
+  end
+
+  def clear!
+    # Best-effort memory wiping
+  end
+
+  def cleared?
+    # Returns true if cleared from memory
   end
 end
 ```
@@ -265,83 +280,54 @@ rescue Familia::EncryptionError => e
 end
 ```
 
-## CLI Commands
-
-### Generate Key
+## Instance Methods
 
-```bash
-$ familia encryption:generate_key [--bits 256]
-# Outputs Base64-encoded key
-```
+### encrypted_data?
 
-### Verify Encryption
+Check if any encrypted fields have values:
 
-```bash
-$ familia encryption:verify [--model User] [--field favorite_snack]
-# Verifies field encryption is working
+```ruby
+user.encrypted_data?  # => true if any encrypted fields have values
 ```
 
-### Rotate Keys
+### clear_encrypted_fields!
+
+Clear all encrypted field values from memory:
 
-```bash
-$ familia encryption:rotate [--from v1] [--to v2]
-# Migrates encrypted fields to new key
+```ruby
+user.clear_encrypted_fields!  # Clear all ConcealedString values
 ```
 
-## Testing Helpers
+### encrypted_fields_cleared?
 
-### EncryptionTestHelpers
+Check if all encrypted fields have been cleared:
 
 ```ruby
-module Familia::EncryptionTestHelpers
-  # Set up test encryption keys
-  def with_test_encryption_keys(&block)
-
-  # Verify field is encrypted in storage
-  def assert_field_encrypted(model, field)
-
-  # Verify decryption works
-  def assert_decryption_works(model, field, expected)
-end
+user.encrypted_fields_cleared?  # => true if all cleared
 ```
 
-### RSpec Example
-
-```ruby
-RSpec.describe User do
-  include Familia::EncryptionTestHelpers
+### re_encrypt_fields!
 
-  it "encrypts favorite snack field" do
-    with_test_encryption_keys do
-      user = User.create(favorite_snack: "chocolate chip cookies")
+Re-encrypt all encrypted fields with current key version:
 
-      assert_field_encrypted(user, :favorite_snack)
-      assert_decryption_works(user, :favorite_snack, "chocolate chip cookies")
-    end
-  end
-end
+```ruby
+user.re_encrypt_fields!  # Uses current_key_version
+user.save
 ```
 
-## Performance Considerations
+### encrypted_fields_status
 
-### Key Derivation Caching
+Get encryption status for debugging:
 
 ```ruby
-# Automatic in web requests
-class ApplicationController
-  around_action :with_encryption_cache
-
-  def with_encryption_cache
-    Familia::Encryption.with_key_cache { yield }
-  end
-end
+user.encrypted_fields_status
+# => {
+#   ssn: { encrypted: true, cleared: false },
+#   credit_card: { encrypted: true, cleared: true }
+# }
 ```
 
-### Batch Operations
+---
 
-```ruby
-# Efficient for bulk operations
-User.batch_decrypt(:favorite_snack) do |users|
-  users.each { |u| process(u.favorite_snack) }
-end
-```
+> [!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).

data/docs/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Familia"
+copyright = "2010-ongoing delano, contributors"
+author = "Delano Mandelbaum"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

data/docs/guides/{Field-System-Guide.md → core-field-system.md}

@@ -376,10 +376,10 @@ profile = UserProfile.new(user_id: 'user_123')
 profile.save
 
 # Regular setter: updates instance variable only
-profile.last_login_at = Time.now  # Not yet in database
+profile.last_login_at = Familia.now  # Not yet in database
 
 # Fast method: immediate database write
-profile.last_login_at!(Time.now)  # Written to database immediately
+profile.last_login_at!(Familia.now)  # Written to database immediately
 
 # Reading from database
 profile.last_login_at   # => reads from instance variable
@@ -417,8 +417,8 @@ class AuditedFieldType < Familia::FieldType
             field: field_name,
             old_value: old_value,
             new_value: value,
-            changed_at: Time.now.to_f,
-            changed_by: Thread.current[:current_user]&.id
+            changed_at: Familia.now,
+            changed_by: Fiber[:current_user]&.id
           }
 
           # Store audit trail
@@ -449,7 +449,7 @@ end
 doc = AuditedDocument.new(doc_id: 'doc_123')
 doc.save
 
-Thread.current[:current_user] = OpenStruct.new(id: 'user_456')
+Fiber[:current_user] = OpenStruct.new(id: 'user_456')
 doc.content!("Initial content")    # Audited change
 doc.status!("draft")               # Audited change
 
@@ -705,22 +705,22 @@ RSpec.describe TimestampFieldType do
     instance.created_at = "2023-06-15 14:30:00"
     expect(instance.created_at).to be_a(Time)
 
-    instance.created_at = Time.now
+    instance.created_at = Familia.now
     expect(instance.created_at).to be_a(Time)
 
-    instance.created_at = Time.now.to_i
+    instance.created_at = Familia.now.to_i
     expect(instance.created_at).to be_a(Time)
   end
 
   it "serializes to integer" do
-    time_value = Time.now
+    time_value = Familia.now
     serialized = field_type.serialize(time_value)
     expect(serialized).to be_a(Integer)
     expect(serialized).to eq(time_value.to_i)
   end
 
   it "deserializes from integer" do
-    timestamp = Time.now.to_i
+    timestamp = Familia.now.to_i
     deserialized = field_type.deserialize(timestamp)
     expect(deserialized).to be_a(Time)
     expect(deserialized.to_i).to eq(timestamp)