familia 2.0.0.pre17 → 2.0.0.pre18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e760a3ff094446126c56a0c2b76fd5bed0f6ff64d8eed89580e19d98a5a9ba66
-  data.tar.gz: 74545b0bbb8c89b06ffd385c1448a95a7808b168686a955155a004b91160dafa
+  metadata.gz: e5bbf0ac2fc6a1243d74f679c7027040be00783af625dd90d376637e32417394
+  data.tar.gz: 4b354347a0c2403490dc20fdc12f93b3e71b826cf0b2b08638f6fd884a883630
 SHA512:
-  metadata.gz: cd9cd6c374f24859279125ef05199b0dfdac51f7cccdf2bcdf0489c7cca5126ac03d7cab1d54aa8021ce38b286203212514b2b412322ea151b8957fa16c9b445
-  data.tar.gz: 3e44e06249e6daf715ce09b02643b8faf153c85fc2d8451d4cf56d77c5115e5e5fdb1b752acef3f1fdd46f7b7eb7f019213f22850ffe728ec51a05d98ecc5528
+  metadata.gz: 221116e1aa14bc7114cb51164727587dcb0e8435dd8b85bb7d14618393ef446446376fd7febf6dbc9993098e2c819b3b0aa6f3c8bedce1c965b99ec4c8832a7b
+  data.tar.gz: 457b0e5bfef1f203c8f2edf934d1ee37915df04c49b0cb8b097ab9732738186ba9e8e92496851699f0952426971d2d3d244e61e594719439672996a0ccde2050

data/CHANGELOG.rst

@@ -12,6 +12,66 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre18:
+
+2.0.0.pre18 — 2025-10-05
+========================
+
+Added
+-----
+
+- Added ``Familia.reconnect!`` method to refresh connection pools with current middleware configuration. This solves issues in test suites where middleware (like DatabaseLogger) is enabled after connection pools are created. The method clears the connection chain, increments the middleware version, and clears fiber-local connections, ensuring new connections include the latest middleware. See ``lib/familia/connection/middleware.rb:81-117``.
+
+Changed
+-------
+
+- **BREAKING**: Implemented type-preserving JSON serialization for Horreum field values. Non-string values (Integer, Boolean, Float, nil, Hash, Array) are JSON-encoded for storage and JSON-decoded on retrieval. **Strings are stored as-is without JSON encoding** to avoid double-quoting and maintain Redis baseline simplicity. Type preservation is achieved through smart deserialization: values that parse as JSON restore to their original types, otherwise remain as strings.
+
+- **BREAKING**: Changed default Hash key format from symbols to strings throughout the codebase (``symbolize: false`` default). This eliminates ambiguity with HTTP request parameters and IndifferentHash-style implementations, providing strict adherence to JSON parsing rules and avoiding key duplication issues.
+
+- **BREAKING**: Fixed ``initialize_with_keyword_args`` to properly handle ``false`` and ``0`` values during object initialization. Previously, falsy values were incorrectly skipped due to truthiness checks. Now uses explicit nil checking with ``fetch`` to preserve all non-nil values including ``false`` and ``0``.
+
+- **String serialization now uses JSON encoding**: All string values are JSON-encoded during storage (wrapped in quotes) for consistent type preservation. The lenient deserializer handles both new JSON-encoded strings and legacy plain strings automatically. PR #152
+
+Removed
+-------
+
+- **BREAKING**: Removed ``dump_method`` and ``load_method`` configuration options from ``Familia::Base`` and ``Familia::Horreum::Definition``. JSON serialization is now hard-coded for consistency and type safety. Custom serialization methods are no longer supported.
+
+Fixed
+-----
+
+- Fixed type coercion bugs where Integer fields (e.g., ``age: 35``) became Strings (``"35"``) and Boolean fields (e.g., ``active: true``) became Strings (``"true"``) after database round-trips. All primitive types now maintain their original types through ``find_by_dbkey``, ``refresh!``, and ``batch_update`` operations.
+
+- Fixed ``deserialize_value`` to return all JSON-parsed types instead of filtering to Hash/Array only. This enables proper deserialization of primitive types (Integer, Boolean, Float, String) from Redis storage.
+
+- Added JSON deserialization in ``find_by_dbkey`` using existing ``initialize_with_keyword_args_deserialize_value`` helper method to maintain DRY principles and ensure loaded objects receive properly typed field values rather than raw Redis strings.
+
+- Optimized serialization to avoid double-encoding strings - strings stored directly in Redis as-is, only non-string types use JSON encoding. This reduces storage overhead and maintains Redis's string baseline semantics.
+
+- Fixed encrypted fields with ``category: :encrypted`` appearing in ``to_h()`` output. These fields now correctly set ``loggable: false`` to prevent accidental exposure in logs, APIs, or external interfaces. PR #152
+
+- Fixed middleware registration to only set ``@middleware_registered`` flag when middleware is actually enabled and registered. Previously, calling ``create_dbclient`` before enabling middleware would set the flag to ``true`` without registering anything, preventing later middleware enablement from working. The fix ensures ``register_middleware_once`` only sets the flag after successful registration. See ``lib/familia/connection/middleware.rb:124-146``.
+
+Security
+--------
+
+- Encrypted fields defined via ``field :name, category: :encrypted`` now properly excluded from ``to_h()`` serialization, matching the security behavior of ``encrypted_field``. PR #152
+
+Documentation
+-------------
+
+- Added comprehensive type preservation test suite (``try/unit/horreum/json_type_preservation_try.rb``) with 30 test cases covering Integer, Boolean, String, Float, Hash, Array, nested structures, nil handling, empty strings, zero values, round-trip consistency, ``batch_update``, and ``refresh!`` operations.
+
+AI Assistance
+-------------
+
+- Claude Code (claude-sonnet-4-5) provided implementation guidance, identified the ``initialize_with_keyword_args`` falsy value bug, wrote comprehensive test suite, and coordinated multi-file changes across serialization, management, and base modules.
+
+- Issue analysis, implementation guidance, test verification, and documentation for JSON serialization changes and encrypted field security fix.
+
+- Claude Code (Sonnet 4.5) provided architecture analysis, implementation design, and identified critical issues through the second-opinion agent. Key contributions included recommending the simplified approach without pool shutdown lifecycle management, identifying the race condition risk in clearing ``@middleware_registered``, and suggesting the use of natural pool aging instead of explicit shutdown.
+
 .. _changelog-2.0.0.pre17:
 
 2.0.0.pre17 — 2025-10-03

data/CLAUDE.md

@@ -154,8 +154,15 @@ end
 
 ### Important Implementation Notes
 
-**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended.
-**Serialization**: Uses JSON by default but supports custom `serialize_value`/`deserialize_value` methods.
+**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended. All non-nil values including `false` and `0` are preserved during initialization.
+
+**Serialization**: All field values are JSON-encoded for storage and JSON-decoded on retrieval to preserve Ruby types (Integer, Boolean, String, Float, Hash, Array, nil). This ensures type preservation across the Redis storage boundary. For example:
+- `age: 35` (Integer) stores as `"35"` in Redis and loads back as Integer `35`
+- `active: true` (Boolean) stores as `"true"` in Redis and loads back as Boolean `true`
+- `metadata: {key: "value"}` (Hash) stores as JSON and loads back as Hash with proper types
+
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
+
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
+
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre17)
+    familia (2.0.0.pre18)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)

data/README.md

@@ -438,6 +438,19 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### PR Compliance Checks
+
+Pull requests are automatically reviewed by [Qodo Merge](https://qodo.ai) with compliance checks for:
+- **Error Handling** - External API calls and database operations must have proper error handling
+- **Test Coverage** - New features must include tests using the Tryouts framework
+- **Changelog Fragments** - User-facing changes should include a changelog entry
+- **Documentation** - API changes must update documentation
+- **Backward Compatibility** - Breaking changes must be documented
+- **Thread Safety** - Shared state must be properly synchronized
+- **Database Key Naming** - Keys must follow Familia conventions
+
+See [docs/qodo-merge-compliance.md](docs/qodo-merge-compliance.md) for details.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/bin/irb

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-irb -Ilib -r familia -Itry -r helpers/test_helpers
+irb -Ilib -r familia -Itry -r support/helpers/test_helpers

data/docs/guides/core-field-system.md

@@ -50,17 +50,20 @@ customer.email = "admin@acme.com"     # Custom method name
 customer.name!("Updated Corp")        # Fast writer (immediate DB persistence)
 ```
 
-### Field Categories
+### Special Field Types
 
-Fields can be categorized for special processing by features:
+Use dedicated field methods provided by features for special field behaviors:
 
 ```ruby
 class Document < Familia::Horreum
-  field :title                           # Regular field
-  field :content, category: :encrypted   # Will be processed by encrypted_fields feature
-  field :api_key, category: :transient   # Non-persistent field
-  field :tags, category: :indexed        # Custom category for indexing
-  field :metadata, category: :json       # Custom JSON serialization
+  feature :encrypted_fields
+  feature :transient_fields
+
+  field :title                    # Regular persistent field
+  encrypted_field :content        # Encrypted storage
+  transient_field :api_key        # Non-persistent (memory only)
+  field :tags                     # Regular field
+  field :metadata                 # Regular field
 end
 ```
 
@@ -285,27 +288,28 @@ order.priority_urgent?   # => false
 
 ```ruby
 class Product < Familia::Horreum
-  field :name, category: :searchable
-  field :price, category: :numeric
-  field :description, category: :text
-  field :secret_key, category: :encrypted
+  feature :transient_fields
+
+  field :name
+  field :price
+  field :description
   transient_field :temp_data
 end
 
 # Get all field names
 Product.fields
-# => [:name, :price, :description, :secret_key, :temp_data]
+# => [:name, :price, :description, :temp_data]
 
 # Get field types registry
 Product.field_types
 # => { name: #<FieldType...>, price: #<FieldType...>, ... }
 
-# Get fields by category
-Product.fields.select { |f| Product.field_types[f].category == :searchable }
-# => [:name]
+# Get fields by category (read-only introspection)
+Product.fields.select { |f| Product.field_types[f].category == :transient }
+# => [:temp_data]
 
 # Get persistent vs transient fields
-Product.persistent_fields  # => [:name, :price, :description, :secret_key]
+Product.persistent_fields  # => [:name, :price, :description]
 Product.transient_fields   # => [:temp_data]
 
 # Field method mapping (for backward compatibility)
@@ -313,15 +317,24 @@ Product.field_method_map
 # => { name: :name, price: :price, secret_key: :secret_key, temp_data: :temp_data }
 ```
 
-### Field Categories for Feature Processing
+### Using Field Type Category for Introspection
+
+The `category` method on FieldType provides read-only metadata for introspection:
 
 ```ruby
-# Features can process fields by category
+# Custom field type with category metadata
+class SearchableFieldType < Familia::FieldType
+  def category
+    :searchable
+  end
+end
+
+# Features can process fields by inspecting their category
 module SearchableFieldsFeature
   def self.included(base)
     base.extend ClassMethods
 
-    # Process all searchable fields
+    # Find all searchable fields by inspecting field type category
     searchable_fields = base.fields.select do |field|
       base.field_types[field].category == :searchable
     end
@@ -348,11 +361,17 @@ module SearchableFieldsFeature
 end
 
 class Product < Familia::Horreum
-  feature :searchable_fields  # Processes all :searchable category fields
+  feature :searchable_fields
 
-  field :name, category: :searchable
-  field :description, category: :searchable
-  field :internal_id, category: :system
+  # Use custom field type with searchable category
+  def self.searchable_field(name, **options)
+    field_type = SearchableFieldType.new(name, **options)
+    register_field_type(field_type)
+  end
+
+  searchable_field :name
+  searchable_field :description
+  field :internal_id
 end
 
 # Auto-generated search methods available
@@ -733,10 +752,13 @@ end
 ### 1. Choose Appropriate Field Types
 
 ```ruby
-# Use built-in field types when possible
+# Use dedicated field methods provided by features
 class User < Familia::Horreum
-  field :name                    # Simple string field
-  field :metadata, category: :json  # For complex data
+  feature :transient_fields
+  feature :encrypted_fields
+
+  field :name                    # Simple persistent field
+  field :metadata                # For complex data
   transient_field :temp_token    # For runtime-only data
   encrypted_field :api_key       # For sensitive data
 end

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

@@ -0,0 +1,58 @@
+# 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/qodo-merge-compliance.md

@@ -0,0 +1,96 @@
+# Qodo Merge Compliance Configuration
+
+This document describes the Qodo Merge (formerly PR-Agent) configuration for the Familia project.
+
+## Overview
+
+Qodo Merge provides automated PR analysis, code reviews, and compliance checks. Our configuration enables two key compliance features:
+
+1. **Codebase Duplication Compliance** - Uses RAG (Retrieval-Augmented Generation) to check for duplicate code across related repositories
+2. **Custom Compliance** - Project-specific rules tailored to Familia's development practices
+
+## Configuration Files
+
+### pr_agent.toml
+
+The main Qodo Merge configuration file located in the repository root. It includes:
+
+- **Response Language**: Set to English for consistency
+- **RAG Context Enrichment**: Enabled with related repositories (`delano/familia`, `delano/tryouts`, `delano/otto`)
+- **Custom Compliance Path**: References our custom compliance checklist
+- **Ignore Rules**: Excludes generated files and build artifacts from analysis
+
+### pr_compliance_checklist.yaml
+
+Custom compliance rules specific to Familia development:
+
+#### ErrorHandling
+All external API calls and database operations must have proper error handling with try-catch blocks or appropriate error handling mechanisms.
+
+#### TestCoverage
+New features must include tests using the Tryouts framework. Test files should be in the `try/` directory following the `*_try.rb` or `*.try.rb` naming convention.
+
+#### ChangelogFragment
+User-facing changes must include a changelog fragment in the `changelog.d/` directory following RST format, or provide explicit justification for omission.
+
+#### DocumentationUpdates
+API changes must be reflected in documentation, including YARD comments for new public methods or updates to the `docs/` directory.
+
+#### BackwardCompatibility
+Changes must maintain backward compatibility or document breaking changes in migration guides with deprecation warnings.
+
+#### ThreadSafety
+Code handling shared state must be thread-safe with proper synchronization or clear documentation of thread-safety assumptions.
+
+#### DatabaseKeyNaming
+Database key generation must follow Familia conventions:
+- Use the configured `delim` separator (default `:`)
+- Avoid reserved keywords: `ttl`, `db`, `valkey`, `redis`
+- Handle empty identifiers to prevent stack overflow
+
+## Interactive Commands
+
+Team members can trigger on-demand Qodo Merge analysis in PR comments:
+
+- `/analyze --review` - Run code review
+- `/analyze --test` - Generate test suggestions
+- `/improve` - Get improvement suggestions
+- `/ask` - Ask questions about the PR
+
+## Compliance Status
+
+In PR comments from `@qodo-merge-pro`, you'll see:
+
+- 🟢 Green circle - Compliance check passed
+- 🔴 Red circle - Compliance check failed with details
+- ⚪ White circle - Compliance check not configured (should not appear with proper configuration)
+
+## References
+
+- [Qodo Merge Configuration Options](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/)
+- [RAG Context Enrichment Guide](https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/)
+- [Compliance Guide](https://qodo-merge-docs.qodo.ai/tools/compliance/)
+- [Best Practices](https://docs.qodo.ai/qodo-documentation/qodo-merge/features/best-practices)
+
+## Maintenance
+
+### Updating Compliance Rules
+
+To add or modify compliance rules:
+
+1. Edit `pr_compliance_checklist.yaml`
+2. Ensure YAML syntax is valid: `ruby -r yaml -e "YAML.load_file('pr_compliance_checklist.yaml')"`
+3. Commit changes - they take effect immediately on new PRs
+
+### Updating Ignore Rules
+
+To exclude additional files from analysis:
+
+1. Edit the `[ignore]` section in `pr_agent.toml`
+2. Use glob patterns to match file paths
+3. Test with new PRs to verify exclusions work as expected
+
+## Future Improvements (Optional)
+
+- **Centralized Configuration**: Create a `pr-agent-settings` repository with `metadata.yaml` to share configuration across all repos
+- **Wiki Configuration**: Enable repo wiki and create `.pr_agent.toml` page (wiki config takes precedence over local files)

data/lib/familia/base.rb

@@ -17,8 +17,6 @@ module Familia
 
     @features_available = nil
     @feature_definitions = nil
-    @dump_method = :to_json
-    @load_method = :from_json
 
     def self.included(base)
       # Ensure the including class gets its own feature registry

data/lib/familia/connection/middleware.rb

@@ -1,6 +1,6 @@
 # lib/familia/connection/middleware.rb
 
-require_relative '../../middleware/database_middleware'
+require_relative '../../middleware/database_logger'
 
 module Familia
   module Connection
@@ -19,13 +19,13 @@ module Familia
       # Increments the middleware version, invalidating all cached connections
       def increment_middleware_version!
         @middleware_version += 1
-        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}" if Familia.debug?
+        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}"
       end
 
       # Sets a versioned fiber-local connection
-      def set_fiber_connection(connection)
+      def fiber_connection=(connection)
         Fiber[:familia_connection] = [connection, middleware_version]
-        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}" if Familia.debug?
+        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}"
       end
 
       # Clears the fiber-local connection
@@ -50,24 +50,78 @@ module Familia
         increment_middleware_version! if value
       end
 
+      # Reconnects with fresh middleware registration
+      #
+      # This method is useful when middleware needs to be applied to connection pools
+      # that were created before middleware was enabled. It:
+      #
+      # 1. Clears the middleware registration flag to allow re-registration
+      # 2. Re-runs the middleware registration logic
+      # 3. Clears connection chain to force rebuild
+      # 4. Increments middleware version to invalidate cached connections
+      # 5. Clears fiber-local connections
+      #
+      # The next connection request will use the updated middleware configuration.
+      # Existing connection pools will naturally create new connections with middleware
+      # as old connections are cycled out.
+      #
+      # @note If no middleware is enabled, this method safely clears connection state
+      #       but won't register any middleware until it's enabled.
+      #
+      # @example Enable middleware and reconnect
+      #   Familia.enable_database_logging = true
+      #   Familia.reconnect!
+      #
+      # @example In test suites
+      #   # Test file A creates pools
+      #   Familia.connection_provider = ->(uri) { pool.with { |c| c } }
+      #
+      #   # Test file B enables middleware
+      #   Familia.enable_database_logging = true
+      #   Familia.reconnect!  # Force new connections with middleware
+      #
+      def reconnect!
+        # Allow middleware to be re-registered
+        @middleware_registered = false
+        register_middleware_once
+
+        # Clear connection chain to force rebuild
+        @connection_chain = nil
+
+        # Increment version to invalidate all cached connections
+        increment_middleware_version!
+
+        # Clear fiber-local connections
+        clear_fiber_connection!
+
+        Familia.trace :RECONNECT, nil, 'Connection chain cleared, will rebuild with current middleware on next use'
+      end
+
       private
 
       # Registers middleware once globally, regardless of when clients are created.
       # This prevents duplicate middleware registration and ensures all clients get middleware.
       def register_middleware_once
+        # Skip if already registered
         return if @middleware_registered
 
+        # Check if any middleware is enabled
+        return unless Familia.enable_database_logging || Familia.enable_database_counter
+
         if Familia.enable_database_logging
           DatabaseLogger.logger = Familia.logger
           RedisClient.register(DatabaseLogger)
+          Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseLogger'
         end
 
         if Familia.enable_database_counter
           # NOTE: This middleware uses AtomicFixnum from concurrent-ruby which is
           # less contentious than Mutex-based counters. Safe for production.
           RedisClient.register(DatabaseCommandCounter)
+          Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseCommandCounter'
         end
 
+        # Set flag after successful registration
         @middleware_registered = true
       end
     end

data/lib/familia/connection.rb

@@ -42,7 +42,7 @@ module Familia
       @connection_chain = nil # Force rebuild of chain
     end
 
-    # Sets the default URI for Database connections.
+# Sets the default URI for Database connections.
     #
     # NOTE: uri is not a property of the Settings module b/c it's not
     # configured in class defintions like default_expiration or logical DB index.

data/lib/familia/data_type/{commands.rb → database_commands.rb}

@@ -1,10 +1,10 @@
-# lib/familia/data_type/commands.rb
+# lib/familia/data_type/database_commands.rb
 
 module Familia
   class DataType
     # Must be included in all DataType classes to provide Valkey/Redis
     # commands. The class must have a dbkey method.
-    module Commands
+    module DatabaseCommands
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end

data/lib/familia/data_type/serialization.rb

@@ -11,9 +11,9 @@ module Familia
       # @return [String, nil] The serialized representation of the value, or nil
       #   if serialization fails.
       #
-      # @note When a class option is specified, it uses that class's
-      #   serialization method. Otherwise, it relies on Familia.distinguisher for
-      #   serialization.
+      # @note When a class option is specified, it uses Familia.identifier_extractor
+      #   to extract the identifier from objects. Otherwise, it extracts identifiers
+      #   from Familia::Base instances or class names.
       #
       # @example With a class option
       #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
@@ -31,13 +31,13 @@ module Familia
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
         if opts[:class]
-          prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
+          prepared = Familia.identifier_extractor(opts[:class])
           Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
         end
 
         if prepared.nil?
           # Enforce strict values when no class option is specified
-          prepared = Familia.distinguisher(val, strict_values: true)
+          prepared = Familia.identifier_extractor(val)
           Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
         end
 

data/lib/familia/data_type.rb

@@ -3,7 +3,7 @@
 require_relative 'data_type/class_methods'
 require_relative 'data_type/settings'
 require_relative 'data_type/connection'
-require_relative 'data_type/commands'
+require_relative 'data_type/database_commands'
 require_relative 'data_type/serialization'
 
 # Familia
@@ -77,7 +77,7 @@ module Familia
 
     include Settings
     include Connection
-    include Commands
+    include DatabaseCommands
     include Serialization
   end
 

data/lib/familia/encryption/encrypted_data.rb

@@ -44,8 +44,18 @@ module Familia
         new(**parsed)
       end
 
-      def self.from_json(json_string)
-        validate!(json_string)
+      def self.from_json(json_string_or_hash)
+        # Support both JSON strings (legacy) and already-parsed Hashes (v2.0 deserialization)
+        if json_string_or_hash.is_a?(Hash)
+          # Already parsed - use directly
+          parsed = json_string_or_hash
+          # Symbolize keys if they're strings
+          parsed = parsed.transform_keys(&:to_sym) if parsed.keys.first.is_a?(String)
+          new(**parsed)
+        else
+          # JSON string - validate and parse
+          validate!(json_string_or_hash)
+        end
       end
 
       # Instance methods for decryptability validation

data/lib/familia/encryption/manager.rb

@@ -32,15 +32,22 @@ module Familia
         Familia::Encryption.secure_wipe(key) if key
       end
 
-      def decrypt(encrypted_json, context:, additional_data: nil)
-        return nil if encrypted_json.nil? || encrypted_json.empty?
+      def decrypt(encrypted_json_or_hash, context:, additional_data: nil)
+        return nil if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
 
         # Increment counter immediately to track all decryption attempts, even failed ones
         Familia::Encryption.derivation_count.increment
 
         begin
-          data = Familia::Encryption::EncryptedData.new(**Familia::JsonSerializer.parse(encrypted_json,
-                                                                                        symbolize_names: true))
+          # Delegate parsing and instantiation to EncryptedData.from_json
+          # Wrap validation errors for security (don't expose internal structure details)
+          begin
+            data = Familia::Encryption::EncryptedData.from_json(encrypted_json_or_hash)
+            raise EncryptionError, 'Failed to parse encrypted data' unless data
+          rescue EncryptionError => e
+            # Re-wrap validation errors with generic message for security
+            raise EncryptionError, "Decryption failed: #{e.message}"
+          end
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)