familia 2.0.0.pre10 → 2.0.0.pre12

data/examples/{bit_encoding_integration.rb → permissions.rb}

@@ -17,11 +17,11 @@ class User < Familia::Horreum
   field :user_id
   field :email
   field :name
-  field :role  # admin, editor, viewer, guest
+  field :role # admin, editor, viewer, guest
   field :created_at
 
-  sorted_set :documents  # Documents this user can access
-  sorted_set :recent_activity  # Recent document access
+  sorted_set :documents # Documents this user can access
+  sorted_set :recent_activity # Recent document access
 end
 
 class Document < Familia::Horreum
@@ -39,10 +39,10 @@ class Document < Familia::Horreum
   field :content
   field :created_at
   field :updated_at
-  field :document_type  # public, private, confidential
+  field :document_type # public, private, confidential
 
-  sorted_set :collaborators  # Users with access to this document
-  list :audit_log  # Track permission changes and access
+  sorted_set :collaborators # Users with access to this document
+  list :audit_log # Track permission changes and access
 
   # Add document to user's collection with specific permissions
   def share_with_user(user, *permissions)
@@ -78,7 +78,7 @@ class Document < Familia::Horreum
 
   # Get users with specific permission level or higher
   def users_with_permission(*required_permissions)
-    all_permissions.select do |user_id, user_perms|
+    all_permissions.select do |_user_id, user_perms|
       required_permissions.all? { |perm| user_perms.include?(perm) }
     end.keys
   end
@@ -102,7 +102,7 @@ class Document < Familia::Horreum
       active_users: active_users,
       total_collaborators: collaborators.size,
       permission_breakdown: all_permissions,
-      audit_entries: audit_log.range(0, 50)
+      audit_entries: audit_log.range(0, 50),
     }
   end
 end
@@ -113,10 +113,10 @@ class DocumentService
   ROLE_PERMISSIONS = {
     guest: [:read],
     viewer: [:read],
-    commenter: [:read, :append],
-    editor: [:read, :write, :edit],
-    reviewer: [:read, :write, :edit, :delete],
-    admin: [:read, :write, :edit, :delete, :configure, :transfer, :admin]
+    commenter: %i[read append],
+    editor: %i[read write edit],
+    reviewer: %i[read write edit delete],
+    admin: %i[read write edit delete configure transfer admin],
   }.freeze
 
   def self.create_document(owner, title, content, doc_type = 'private')
@@ -164,7 +164,7 @@ class DocumentService
 
     documents.each do |doc|
       users.each do |user|
-        doc.revoke_access(user)  # Clear existing
+        doc.revoke_access(user) # Clear existing
         doc.share_with_user(user, *permissions) if permissions
       end
     end
@@ -173,8 +173,8 @@ end
 
 # Example Usage and Demonstration
 if __FILE__ == $0
-  puts "🚀 Familia Bit Encoding Integration Example"
-  puts "=" * 50
+  puts '🚀 Familia Bit Encoding Integration Example'
+  puts '=' * 50
 
   # Create users
   alice = User.new(user_id: 'alice', email: 'alice@company.com', name: 'Alice Smith', role: 'admin')
@@ -182,9 +182,9 @@ if __FILE__ == $0
   charlie = User.new(user_id: 'charlie', email: 'charlie@company.com', name: 'Charlie Brown', role: 'viewer')
 
   # Create documents
-  doc1 = DocumentService.create_document(alice, "Q4 Financial Report", "Confidential financial data...", 'confidential')
-  doc2 = DocumentService.create_document(alice, "Team Meeting Notes", "Weekly standup notes...", 'private')
-  doc3 = DocumentService.create_document(bob, "Project Proposal", "New feature proposal...", 'public')
+  doc1 = DocumentService.create_document(alice, 'Q4 Financial Report', 'Confidential financial data...', 'confidential')
+  doc2 = DocumentService.create_document(alice, 'Team Meeting Notes', 'Weekly standup notes...', 'private')
+  doc3 = DocumentService.create_document(bob, 'Project Proposal', 'New feature proposal...', 'public')
 
   # Share documents with different permission levels
   puts "\n📄 Document Sharing:"
@@ -209,14 +209,14 @@ if __FILE__ == $0
   analytics = doc1.access_analytics
   puts "Financial Report - Active Users: #{analytics[:active_users].size}"
   puts "Total Collaborators: #{analytics[:total_collaborators]}"
-  puts "Permission Breakdown:"
+  puts 'Permission Breakdown:'
   analytics[:permission_breakdown].each do |user_id, perms|
     puts "  #{user_id}: #{perms.join(', ')}"
   end
 
   # Demonstrate bit encoding efficiency
   puts "\n⚡ Bit Encoding Efficiency:"
-  score = Familia::Features::Relationships::ScoreEncoding.encode_score(Time.now, [:read, :write, :edit, :delete])
+  score = Familia::Features::Relationships::ScoreEncoding.encode_score(Time.now, %i[read write edit delete])
   decoded = Familia::Features::Relationships::ScoreEncoding.decode_score(score)
   puts "Encoded score: #{score}"
   puts "Decoded permissions: #{decoded[:permission_list].join(', ')}"
@@ -225,13 +225,16 @@ if __FILE__ == $0
   # Cleanup
   puts "\n🧹 Cleanup:"
   [alice, bob, charlie].each { |user| user.documents.clear }
-  [doc1, doc2, doc3].each { |doc| doc.clear_all_permissions; doc.collaborators.clear }
+  [doc1, doc2, doc3].each do |doc|
+    doc.clear_all_permissions
+    doc.collaborators.clear
+  end
 
-  puts "✅ Integration example completed successfully!"
+  puts '✅ Integration example completed successfully!'
   puts "\nThis demonstrates:"
-  puts "• Fine-grained permission management with 8-bit encoding"
-  puts "• Role-based access control with business logic"
-  puts "• Time-based analytics and audit trails"
-  puts "• Efficient Redis storage with sorted sets"
-  puts "• Production-ready error handling and validation"
+  puts '• Fine-grained permission management with 8-bit encoding'
+  puts '• Role-based access control with business logic'
+  puts '• Time-based analytics and audit trails'
+  puts '• Efficient Redis storage with sorted sets'
+  puts '• Production-ready error handling and validation'
 end

data/examples/{relationships_basic.rb → relationships.rb}

@@ -49,7 +49,7 @@ class Domain < Familia::Horreum
   field :status
 
   # Declare membership in customer collections
-  member_of Customer, :domains #, type: :set
+  member_of Customer, :domains # , type: :set
 
   # Track domains by status (using class_ prefix for class-level)
   class_tracked_in :active_domains,
@@ -107,7 +107,7 @@ puts
 puts '=== 2. Establishing Relationships ==='
 
 # Save objects to automatically update indexes and class-level tracking
-customer.save  # Automatically adds to email_lookup, plan_lookup, and all_customers
+customer.save # Automatically adds to email_lookup, plan_lookup, and all_customers
 puts '✓ Customer automatically added to indexes and tracking on save'
 
 # Establish member_of relationships using clean << operator syntax
@@ -173,7 +173,6 @@ active_domain_scores.each_slice(2) do |domain_id, timestamp|
 end
 puts
 
-
 puts '=== 6. Relationship Cleanup ==='
 
 # Remove relationships

data/examples/safe_dump.rb

@@ -0,0 +1,281 @@
+#!/usr/bin/env ruby
+
+# examples/safe_dump.rb
+#
+# Demonstrates the SafeDump feature with the new DSL methods.
+# SafeDump allows you to control which fields are exposed when
+# serializing objects, preventing accidental exposure of sensitive data.
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'familia'
+
+# Configure connection
+Familia.uri = 'redis://localhost:6379/15'
+
+puts '=== SafeDump Feature Examples ==='
+puts
+
+# Example 1: Basic SafeDump with simple fields
+class User < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :email
+  field :email
+  field :first_name
+  field :last_name
+  field :password_hash # Sensitive - not included in safe dump
+  field :ssn # Sensitive - not included in safe dump
+  field :created_at
+
+  # Define safe dump fields using the new DSL
+  safe_dump_field :email
+  safe_dump_field :first_name
+  safe_dump_field :last_name
+  safe_dump_field :created_at
+end
+
+puts 'Example 1: Basic SafeDump'
+user = User.new(
+  email: 'alice@example.com',
+  first_name: 'Alice',
+  last_name: 'Smith',
+  password_hash: 'secret123',
+  ssn: '123-45-6789',
+  created_at: Time.now.to_i
+)
+
+puts "Full object data: #{user.to_h}"
+puts "Safe dump: #{user.safe_dump}"
+puts 'Notice: password_hash and ssn are excluded'
+puts
+
+# Example 2: SafeDump with computed fields using callables
+class Product < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :sku
+  field :sku
+  field :name
+  field :price_cents      # Store price in cents internally
+  field :cost_cents       # Sensitive - don't expose
+  field :inventory_count
+  field :category
+  field :created_at
+
+  # Mix simple fields with computed fields
+  safe_dump_field :sku
+  safe_dump_field :name
+  safe_dump_field :category
+  safe_dump_field :created_at
+
+  # Computed fields using callables
+  safe_dump_field :price, ->(product) { "$#{format('%.2f', product.price_cents.to_i / 100.0)}" }
+  safe_dump_field :in_stock, ->(product) { product.inventory_count.to_i > 0 }
+  safe_dump_field :display_name, ->(product) { "#{product.name} (#{product.sku})" }
+end
+
+puts 'Example 2: SafeDump with computed fields'
+product = Product.new(
+  sku: 'WIDGET-001',
+  name: 'Super Widget',
+  price_cents: 1599,     # $15.99
+  cost_cents: 800,       # $8.00 - sensitive, not exposed
+  inventory_count: 25,
+  category: 'widgets',
+  created_at: Time.now.to_i
+)
+
+puts "Full object data: #{product.to_h}"
+puts "Safe dump: #{product.safe_dump}"
+puts 'Notice: price converted to dollars, in_stock computed, cost_cents hidden'
+puts
+
+# Example 3: SafeDump with multiple field definition styles
+class Order < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :order_id
+  field :order_id
+  field :customer_email
+  field :status
+  field :total_cents
+  field :payment_method
+  field :credit_card_number  # Very sensitive!
+  field :processing_notes    # Internal only
+  field :created_at
+  field :shipped_at
+
+  # Mix of individual fields and batch definitions
+  safe_dump_field :order_id
+  safe_dump_field :customer_email
+  safe_dump_field :status
+
+  # Define multiple fields at once
+  safe_dump_fields :created_at, :shipped_at
+
+  # Computed fields using hash syntax
+  safe_dump_fields(
+    { total: ->(order) { "$#{format('%.2f', order.total_cents.to_i / 100.0)}" } },
+    { payment_type: ->(order) { order.payment_method&.split('_')&.first&.capitalize } }
+  )
+
+  def customer_obscured_email
+    email = customer_email.to_s
+    return email if email.length < 3
+
+    local, domain = email.split('@', 2)
+    return email unless domain
+
+    obscured_local = local[0] + ('*' * [local.length - 2, 0].max) + local[-1]
+    "#{obscured_local}@#{domain}"
+  end
+end
+
+puts 'Example 3: Multiple definition styles'
+order = Order.new(
+  order_id: 'ORD-2024-001',
+  customer_email: 'customer@example.com',
+  status: 'shipped',
+  total_cents: 2499, # $24.99
+  payment_method: 'credit_card',
+  credit_card_number: '4111-1111-1111-1111', # Never expose this!
+  processing_notes: 'Rush order - expedite shipping',
+  created_at: Time.now.to_i - 86_400, # Yesterday
+  shipped_at: Time.now.to_i - 3600 # 1 hour ago
+)
+
+puts "Full object data: #{order.to_h}"
+puts "Safe dump: #{order.safe_dump}"
+puts 'Notice: credit card and internal notes excluded, computed fields included'
+puts
+
+# Example 4: SafeDump with nested objects
+class Address < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :id
+  field :id
+  field :street
+  field :city
+  field :state
+  field :zip_code
+  field :country
+
+  # Simple address fields
+  safe_dump_fields :street, :city, :state, :zip_code, :country
+end
+
+class Customer < Familia::Horreum
+  feature :safe_dump
+
+  identifier_field :id
+  field :id
+  field :name
+  field :email
+  field :phone
+  field :billing_address_id
+  field :shipping_address_id
+  field :account_balance_cents
+  field :credit_limit_cents   # Sensitive
+  field :internal_notes       # Internal only
+
+  safe_dump_field :id
+  safe_dump_field :name
+  safe_dump_field :email
+  safe_dump_field :phone
+
+  # Nested object handling - load and safe_dump related addresses
+  safe_dump_field :billing_address, lambda { |customer|
+    addr_id = customer.billing_address_id
+    addr_id ? Address.load(addr_id)&.safe_dump : nil
+  }
+
+  safe_dump_field :shipping_address, lambda { |customer|
+    addr_id = customer.shipping_address_id
+    addr_id ? Address.load(addr_id)&.safe_dump : nil
+  }
+
+  safe_dump_field :account_balance, lambda { |customer|
+    "$#{format('%.2f', customer.account_balance_cents.to_i / 100.0)}"
+  }
+end
+
+puts 'Example 4: SafeDump with nested objects'
+
+# Create addresses first
+billing = Address.new(
+  id: 'addr_1',
+  street: '123 Main St',
+  city: 'Anytown',
+  state: 'CA',
+  zip_code: '90210',
+  country: 'USA'
+)
+billing.save
+
+shipping = Address.new(
+  id: 'addr_2',
+  street: '456 Oak Ave',
+  city: 'Somewhere',
+  state: 'NY',
+  zip_code: '10001',
+  country: 'USA'
+)
+shipping.save
+
+customer = Customer.new(
+  id: 'cust_123',
+  name: 'Bob Johnson',
+  email: 'bob@example.com',
+  phone: '555-1234',
+  billing_address_id: 'addr_1',
+  shipping_address_id: 'addr_2',
+  account_balance_cents: 15_000,  # $150.00
+  credit_limit_cents: 100_000,    # $1000.00 - sensitive!
+  internal_notes: 'VIP customer - handle with care'
+)
+
+puts 'Customer safe dump:'
+puts JSON.pretty_generate(customer.safe_dump)
+puts 'Notice: Nested addresses included, sensitive credit limit excluded'
+puts
+
+# Example 5: Introspection methods
+puts 'Example 5: SafeDump introspection'
+puts "User safe dump field names: #{User.safe_dump_field_names}"
+puts "Product safe dump field names: #{Product.safe_dump_field_names}"
+puts "Order safe dump field names: #{Order.safe_dump_field_names}"
+puts
+
+puts "User safe dump field map keys: #{User.safe_dump_field_map.keys}"
+puts "All Product safe dump fields are callable: #{Product.safe_dump_field_map.values.all? do |v|
+  v.respond_to?(:call)
+end}"
+puts
+
+# Example 6: Legacy compatibility methods
+puts 'Example 6: Legacy compatibility'
+puts "Using legacy safe_dump_fields getter: #{User.safe_dump_fields}"
+puts 'Setting fields with set_safe_dump_fields:'
+
+class LegacyModel < Familia::Horreum
+  feature :safe_dump
+  identifier_field :id
+  field :id
+  field :name
+  field :value
+end
+
+LegacyModel.set_safe_dump_fields(:id, :name)
+puts "LegacyModel fields after set_safe_dump_fields: #{LegacyModel.safe_dump_fields}"
+
+# Clean up
+puts
+puts '=== Cleaning up test data ==='
+[User, Product, Order, Address, Customer, LegacyModel].each do |klass|
+  klass.redis.del(klass.redis.keys("#{klass.name.downcase}:*"))
+rescue StandardError => e
+  puts "Error cleaning #{klass}: #{e.message}"
+end
+
+puts 'SafeDump examples completed!'

data/familia.gemspec

@@ -19,10 +19,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
 
-  spec.add_dependency 'benchmark', '~> 0.1'
-  spec.add_dependency 'connection_pool', '~> 2.4'
-  spec.add_dependency 'csv', '~> 3.1'
-  spec.add_dependency 'logger', '~> 1.6'
+  spec.add_dependency 'benchmark', '~> 0.4'
+  spec.add_dependency 'connection_pool', '~> 2.5'
+  spec.add_dependency 'csv', '~> 3.3'
+  spec.add_dependency 'logger', '~> 1.7'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'

data/lib/familia/base.rb

@@ -19,6 +19,38 @@ module Familia
     @dump_method = :to_json
     @load_method = :from_json
 
+    def self.included(base)
+      # Ensure the including class gets its own feature registry
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      attr_reader :features_available, :feature_definitions
+      attr_accessor :dump_method, :load_method
+
+      def add_feature(klass, feature_name, depends_on: [])
+        @features_available ||= {}
+        Familia.trace :ADD_FEATURE, klass, feature_name, caller(1..1) if Familia.debug?
+
+        # Create field definition object
+        feature_def = FeatureDefinition.new(
+          name: feature_name,
+          depends_on: depends_on,
+        )
+
+        # Track field definitions after defining field methods
+        @feature_definitions ||= {}
+        @feature_definitions[feature_name] = feature_def
+
+        features_available[feature_name] = klass
+      end
+
+      # Find a feature by name, traversing this class's ancestry chain
+      def find_feature(feature_name)
+        Familia::Base.find_feature(feature_name, self)
+      end
+    end
+
     # Returns a string representation of the object. Implementing classes
     # are welcome to override this method to provide a more meaningful
     # representation. Using this as a default via super is recommended.
@@ -29,6 +61,7 @@ module Familia
       "#<#{self.class}:0x#{object_id.to_s(16)}>"
     end
 
+    # Module-level methods for Familia::Base itself
     class << self
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
@@ -49,6 +82,25 @@ module Familia
 
         features_available[feature_name] = klass
       end
+
+      # Find a feature by name, traversing the ancestry chain of classes
+      # that include Familia::Base
+      def find_feature(feature_name, starting_class = self)
+        # Convert to symbol for consistent lookup
+        feature_name = feature_name.to_sym
+
+        # Walk up the ancestry chain, checking each class that includes Familia::Base
+        starting_class.ancestors.each do |ancestor|
+          next unless ancestor.respond_to?(:features_available)
+          next unless ancestor.features_available
+
+          if ancestor.features_available.key?(feature_name)
+            return ancestor.features_available[feature_name]
+          end
+        end
+
+        nil
+      end
     end
 
     def generate_id

data/lib/familia/{encryption_request_cache.rb → encryption/request_cache.rb}

@@ -1,4 +1,4 @@
-# lib/familia/encryption_request_cache.rb
+# lib/familia/encryption/request_cache.rb
 #
 # Request-scoped caching for encryption keys (if needed for performance)
 # This should ONLY be enabled if performance testing shows it's necessary

data/lib/familia/errors.rb

@@ -5,6 +5,8 @@ module Familia
   class NoIdentifier < Problem; end
   class NonUniqueKey < Problem; end
 
+  class FieldTypeError < Problem; end
+
   class HighRiskFactor < Problem
     attr_reader :value
 

data/lib/familia/features/autoloader.rb

@@ -0,0 +1,57 @@
+# lib/familia/features/autoloader.rb
+
+module Familia
+  module Features
+    # Autoloader is a mixin that automatically loads feature files from a 'features'
+    # subdirectory when included. This provides a standardized way to organize and
+    # auto-load project-specific features.
+    #
+    # When included in a module, it automatically:
+    # 1. Determines the directory containing the module file
+    # 2. Looks for a 'features' subdirectory in that location
+    # 3. Loads all *.rb files from that features directory
+    #
+    # Example usage:
+    #
+    #   # apps/api/v2/models/customer/features.rb
+    #   module V2
+    #     class Customer < Familia::Horreum
+    #       module Features
+    #         include Familia::Features::Autoloader
+    #         # Automatically loads all files from customer/features/
+    #       end
+    #     end
+    #   end
+    #
+    # This would automatically load:
+    #   - apps/api/v2/models/customer/features/deprecated_fields.rb
+    #   - apps/api/v2/models/customer/features/legacy_support.rb
+    #   - etc.
+    #
+    module Autoloader
+      def self.included(_base)
+        # Get the file path of the module that's including us.
+        # `caller_locations(1, 1).first` gives us the location where `include` was called.
+        # This is a robust way to find the file path, especially for anonymous modules.
+        calling_location = caller_locations(1, 1)&.first
+        return unless calling_location
+
+        including_file = calling_location.path
+
+        # Find the features directory relative to the including file
+        features_dir = File.join(File.dirname(including_file), 'features')
+
+        Familia.ld "[DEBUG] Autoloader: Looking for features in #{features_dir}"
+
+        if Dir.exist?(features_dir)
+          Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
+            Familia.ld "[DEBUG] Autoloader: Loading feature #{feature_file}"
+            require feature_file
+          end
+        else
+          Familia.ld "[DEBUG] Autoloader: No features directory found at #{features_dir}"
+        end
+      end
+    end
+  end
+end