familia 2.0.0.pre10 → 2.0.0.pre12

data/lib/familia/verifiable_identifier.rb

@@ -0,0 +1,162 @@
+# lib/familia/verifiable_identifier.rb
+
+require 'openssl'
+require_relative 'secure_identifier'
+
+module Familia
+  # Creates and verifies identifiers that contain an embedded HMAC signature,
+  # allowing for stateless verification of an identifier's authenticity.
+  module VerifiableIdentifier
+    # By extending SecureIdentifier, we gain access to its instance methods
+    # (like generate_hex_id) as class methods on this module.
+    extend Familia::SecureIdentifier
+
+    # The secret key for HMAC generation, loaded from an environment variable.
+    #
+    # This key is the root of trust for verifying identifier authenticity. It must be
+    # a long, random, and cryptographically strong string.
+    #
+    # @!attribute [r] SECRET_KEY
+    #   @return [String] The secret key.
+    #
+    # @note Security Considerations:
+    #   - **Secrecy:** This key MUST be kept secret and secure, just like a database
+    #     password or API key. Do not commit it to version control.
+    #   - **Consistency:** All running instances of your application must use the
+    #     exact same key, otherwise verification will fail across different servers.
+    #   - **Rotation:** If this key is ever compromised, it must be rotated. Be
+    #     aware that rotating the key will invalidate all previously generated
+    #     verifiable identifiers.
+    #
+    # @example Generating and Setting the Key
+    #     1. Generate a new secure key in your terminal:
+    #        $ openssl rand -hex 32
+    #        > cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d
+    #
+    #     2. Set it as an environment variable in your production environment:
+    #        export VERIFIABLE_ID_HMAC_SECRET="cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
+    #
+    SECRET_KEY = ENV.fetch('VERIFIABLE_ID_HMAC_SECRET', 'cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d')
+
+    # The length of the random part of the ID in hex characters (256 bits).
+    RANDOM_HEX_LENGTH = 64
+    # The length of the HMAC tag in hex characters (64 bits).
+    # 64 bits is strong enough to prevent forgery (1 in 18 quintillion chance).
+    TAG_HEX_LENGTH = 16
+
+    # Generates a verifiable, base-36 encoded identifier.
+    #
+    # The final identifier contains a 256-bit random component and a 64-bit
+    # authentication tag.
+    #
+    # @param base [Integer] The base for encoding the output string.
+    # @return [String] A verifiable, signed identifier.
+    def self.generate_verifiable_id(base_or_scope = nil, scope: nil, base: 36)
+      # Handle backward compatibility with positional base argument
+      if base_or_scope.is_a?(Integer)
+        base = base_or_scope
+        # scope remains as passed in keyword argument
+      elsif base_or_scope.is_a?(String) || base_or_scope.nil?
+        scope = base_or_scope if scope.nil?
+        # base remains as passed in keyword argument or default
+      end
+
+      # Re-use generate_hex_id from the SecureIdentifier module.
+      random_hex = generate_hex_id
+      tag_hex = generate_tag(random_hex, scope: scope)
+
+      combined_hex = random_hex + tag_hex
+
+      # Re-use the min_length_for_bits helper from the SecureIdentifier module.
+      total_bits = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH) * 4
+      target_length = Familia::SecureIdentifier.min_length_for_bits(total_bits, base)
+
+      combined_hex.to_i(16).to_s(base).rjust(target_length, '0')
+    end
+
+    # Verifies the authenticity of a given identifier using a timing-safe comparison.
+    #
+    # @param verifiable_id [String] The identifier string to check.
+    # @param base [Integer] The base of the input string.
+    # @return [Boolean] True if the identifier is authentic, false otherwise.
+    def self.verified_identifier?(verifiable_id, base_or_scope = nil, scope: nil, base: 36)
+      # Handle backward compatibility with positional base argument
+      if base_or_scope.is_a?(Integer)
+        base = base_or_scope
+        # scope remains as passed in keyword argument
+      elsif base_or_scope.is_a?(String) || base_or_scope.nil?
+        scope = base_or_scope if scope.nil?
+        # base remains as passed in keyword argument or default
+      end
+
+      return false unless plausible_identifier?(verifiable_id, base)
+
+      expected_hex_length = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH)
+      combined_hex = verifiable_id.to_i(base).to_s(16).rjust(expected_hex_length, '0')
+
+      random_part = combined_hex[0...RANDOM_HEX_LENGTH]
+      tag_part = combined_hex[RANDOM_HEX_LENGTH..]
+
+      expected_tag = generate_tag(random_part, scope: scope)
+      OpenSSL.secure_compare(expected_tag, tag_part)
+    end
+
+    # Checks if an identifier is plausible (correct format and length) without
+    # performing cryptographic verification.
+    #
+    # This can be used as a fast pre-flight check to reject obviously
+    # malformed identifiers.
+    #
+    # @param identifier_str [String] The identifier string to check.
+    # @param base [Integer] The base of the input string.
+    # @return [Boolean] True if the identifier has a valid format, false otherwise.
+    def self.plausible_identifier?(identifier_str, base = 36)
+      return false unless identifier_str.is_a?(::String)
+
+      # 1. Check length
+      total_bits = (RANDOM_HEX_LENGTH + TAG_HEX_LENGTH) * 4
+      expected_length = Familia::SecureIdentifier.min_length_for_bits(total_bits, base)
+      return false unless identifier_str.length == expected_length
+
+      # 2. Check character set
+      # The most efficient way to check for invalid characters is to attempt
+      # conversion and rescue the error.
+      Integer(identifier_str, base)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    class << self
+      private
+
+      # Generates the HMAC tag for a given message.
+      # @private
+      def generate_tag(message, scope: nil)
+        # Include scope in HMAC calculation for domain separation if provided.
+        # The scope parameter enables creating cryptographically isolated identifier
+        # namespaces (e.g., per-domain, per-tenant, per-application) while maintaining
+        # all security properties of the base system.
+        #
+        # Security considerations for scope values:
+        # - Any string content is cryptographically safe (HMAC handles arbitrary input)
+        # - No length restrictions (short scopes like "a" or long scopes work equally well)
+        # - UTF-8 encoding is handled consistently
+        # - Empty string "" vs nil produce different identifiers (intentional for security)
+        # - Different scope values guarantee different identifier spaces
+        #
+        # Examples of scope usage:
+        # - Customer isolation: scope: "tenant:#{tenant_id}"
+        # - Environment separation: scope: "production" vs scope: "staging"
+        # - Domain scoping: scope: "example.com"
+        # - Application scoping: scope: "#{app_name}:#{version}"
+        hmac_input = scope ? "#{message}:scope:#{scope}" : message
+
+        digest = OpenSSL::Digest.new('sha256')
+        hmac = OpenSSL::HMAC.hexdigest(digest, SECRET_KEY, hmac_input)
+        # Truncate to the desired length for the tag.
+        hmac[0...TAG_HEX_LENGTH]
+      end
+    end
+  end
+end

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre10'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre12'.freeze unless defined?(Familia::VERSION)
 end

data/lib/familia.rb

@@ -81,6 +81,7 @@ end
 
 require_relative 'familia/base'
 require_relative 'familia/features'
+require_relative 'familia/features/autoloader'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'
 require_relative 'familia/encryption'

data/setup.cfg

@@ -1,12 +1,5 @@
 [scriv]
-format = md
 categories = Added, Changed, Deprecated, Removed, Fixed, Security, Documentation, AI Assistance
-version_scheme = semver
-entry_title_template = [{{ version }}] - {{ date }}
-fragment_directory = changelog.d/fragments
-template_file = changelog.d/template.md.j2
-output_file = CHANGELOG.md
+version = command: ruby -r ./lib/familia/version.rb -e "puts Familia::VERSION"
 main_branches = main, develop
 md_header_level = 2
-end_marker = scriv-end-here
-start_marker = scriv-insert-here

data/try/core/secure_identifier_try.rb

@@ -56,22 +56,6 @@ hex_trace_id = Familia.generate_hex_trace_id
 [hex_trace_id.class, hex_trace_id.length == 16, hex_trace_id.match?(/^[a-f0-9]+$/)]
 #=> [String, true, true]
 
-## Familia.shorten_to_external_id
-Familia.respond_to?(:shorten_to_external_id)
-#=> true
-
-## Can shorten hex ID to external ID (128 bits)
-hex_id = Familia.generate_hex_id
-external_id = Familia.shorten_to_external_id(hex_id)
-[external_id.class, external_id.length < hex_id.length]
-#=> [String, true]
-
-## Can shorten hex ID to external ID with custom base (hex)
-hex_id = Familia.generate_hex_id
-hex_external_id = Familia.shorten_to_external_id(hex_id, base: 16)
-[hex_external_id.class, hex_external_id.length == 32]
-#=> [String, true]
-
 ## Familia.shorten_to_trace_id
 Familia.respond_to?(:shorten_to_trace_id)
 #=> true
@@ -88,10 +72,55 @@ hex_trace_id = Familia.shorten_to_trace_id(hex_id, base: 16)
 [hex_trace_id.class, hex_trace_id.length == 16]
 #=> [String, true]
 
+## Familia.truncate_hex
+Familia.respond_to?(:truncate_hex)
+#=> true
+
+## Can truncate hex ID to 128 bits by default
+hex_id = Familia.generate_hex_id
+truncated_id = Familia.truncate_hex(hex_id)
+[truncated_id.class, truncated_id.length < hex_id.length]
+#=> [String, true]
+
+## Can truncate hex ID to a custom bit length (64 bits)
+hex_id = Familia.generate_hex_id
+truncated_64 = Familia.truncate_hex(hex_id, bits: 64)
+[truncated_64.class, truncated_64.length < hex_id.length]
+#=> [String, true]
+
+## Can truncate with a custom base (hex)
+hex_id = Familia.generate_hex_id
+hex_truncated = Familia.truncate_hex(hex_id, bits: 128, base: 16)
+[hex_truncated.class, hex_truncated.length == 32]
+#=> [String, true]
+
+## Truncated IDs are deterministic
+hex_id = Familia.generate_hex_id
+id1 = Familia.truncate_hex(hex_id)
+id2 = Familia.truncate_hex(hex_id)
+id1 == id2
+#=> true
+
+## Raises error for invalid hex
+begin
+  Familia.truncate_hex("not-a-hex-string")
+rescue ArgumentError => e
+  e.message
+end
+#=> "Invalid hexadecimal string: not-a-hex-string"
+
+## Raises error if input bits are less than output bits
+begin
+  Familia.truncate_hex("abc", bits: 64)
+rescue ArgumentError => e
+  e.message
+end
+#=> "Input bits (12) cannot be less than desired output bits (64)."
+
 ## Shortened IDs are deterministic
 hex_id = Familia.generate_hex_id
-id1 = Familia.shorten_to_external_id(hex_id)
-id2 = Familia.shorten_to_external_id(hex_id)
+id1 = Familia.shorten_to_trace_id(hex_id)
+id2 = Familia.shorten_to_trace_id(hex_id)
 id1 == id2
 #=> true
 

data/try/core/verifiable_identifier_try.rb

@@ -0,0 +1,171 @@
+# try/core/verifiable_identifier_try.rb
+
+require_relative '../helpers/test_helpers'
+require 'familia/verifiable_identifier'
+
+## Module is available
+defined?(Familia::VerifiableIdentifier)
+#=> "constant"
+
+## Uses the development secret key by default when ENV is not set
+Familia::VerifiableIdentifier::SECRET_KEY
+#=> "cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
+
+# --- Verifiable ID Generation and Verification ---
+
+## Generates a non-empty string ID
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+id.is_a?(String) && !id.empty?
+#=> true
+
+## Generated ID is URL-safe (base36)
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+id.match?(/[a-z0-9]+/ix)
+#=> true
+
+## Generates unique identifiers on subsequent calls
+Familia::VerifiableIdentifier.generate_verifiable_id
+#=/> Familia::VerifiableIdentifier.generate_verifiable_id
+
+## A genuinely generated ID successfully verifies
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.verified_identifier?(id)
+#=> true
+
+## Fails verification for a completely random garbage string
+Familia::VerifiableIdentifier.verified_identifier?('this-is-not-a-valid-id-at-all')
+#=> false
+
+## Fails verification for a string with invalid characters for the base
+# A plus sign is not a valid base-36 character.
+Familia::VerifiableIdentifier.verified_identifier?('this+is+invalid', 36)
+#=> false
+
+## Fails verification if the random part of the ID is tampered with
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+tampered_id = id.dup
+tampered_id[0] = (tampered_id[0] == 'a' ? 'b' : 'a') # Flip the first character
+Familia::VerifiableIdentifier.verified_identifier?(tampered_id)
+#=> false
+
+## Fails verification if the tag part of the ID is tampered with
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+tampered_id = id.dup
+idx = tampered_id.length - 1
+tampered_id[idx] = (tampered_id[idx] == 'a' ? 'b' : 'a') # Flip the last character
+Familia::VerifiableIdentifier.verified_identifier?(tampered_id)
+#=> false
+
+## Works correctly with a different base (hexadecimal)
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(16)
+Familia::VerifiableIdentifier.verified_identifier?(id_hex, 16)
+#=> true
+
+## Base 16 ID has the correct hex length (64 random + 16 tag = 80 chars)
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(16)
+id_hex.length
+#=> 80
+
+# --- Plausibility Checks ---
+
+## A genuinely generated ID is plausible
+id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.plausible_identifier?(id)
+#=> true
+
+## A well-formed but fake ID is still plausible
+# A string of the correct length (62 for base 36) and charset is plausible
+total_bits = (Familia::VerifiableIdentifier::RANDOM_HEX_LENGTH + Familia::VerifiableIdentifier::TAG_HEX_LENGTH) * 4
+fake_id = 'a' * Familia::SecureIdentifier.min_length_for_bits(total_bits, 36)
+Familia::VerifiableIdentifier.plausible_identifier?(fake_id)
+#=> true
+
+## Fails plausibility check if too short
+short_id = 'a' * 60
+Familia::VerifiableIdentifier.plausible_identifier?(short_id)
+#=> false
+
+## Fails plausibility check if too long
+long_id = 'a' * 66
+Familia::VerifiableIdentifier.plausible_identifier?(long_id)
+#=> false
+
+## Fails plausibility check for invalid characters
+invalid_char_id = 'a' * 61 + '+'
+Familia::VerifiableIdentifier.plausible_identifier?(invalid_char_id)
+#=> false
+
+## Fails plausibility check for nil input
+Familia::VerifiableIdentifier.plausible_identifier?(nil)
+#=> false
+
+# --- Scoped Identifier Generation and Verification ---
+
+## Scoped identifier generation produces different results than unscoped
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+unscoped_id = Familia::VerifiableIdentifier.generate_verifiable_id
+scoped_id != unscoped_id
+#=> true
+
+## Scoped identifiers verify successfully with correct scope
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id, scope: "example.com")
+#=> true
+
+## Scoped identifiers fail verification with wrong scope
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id, scope: "different.com")
+#=> false
+
+## Scoped identifiers fail verification without scope parameter
+scoped_id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "example.com")
+Familia::VerifiableIdentifier.verified_identifier?(scoped_id)
+#=> false
+
+## Unscoped identifiers fail verification with scope parameter
+unscoped_id = Familia::VerifiableIdentifier.generate_verifiable_id
+Familia::VerifiableIdentifier.verified_identifier?(unscoped_id, scope: "example.com")
+#=> false
+
+## Empty string scope produces different identifier than nil scope
+id_nil = Familia::VerifiableIdentifier.generate_verifiable_id(scope: nil)
+id_empty = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "")
+id_nil != id_empty
+#=> true
+
+## Empty string scope verifies correctly
+id_empty = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "")
+Familia::VerifiableIdentifier.verified_identifier?(id_empty, scope: "")
+#=> true
+
+## Short scope values work correctly
+id_short = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "a")
+Familia::VerifiableIdentifier.verified_identifier?(id_short, scope: "a")
+#=> true
+
+## Long scope values work correctly
+long_scope = "x" * 1000
+id_long = Familia::VerifiableIdentifier.generate_verifiable_id(scope: long_scope)
+Familia::VerifiableIdentifier.verified_identifier?(id_long, scope: long_scope)
+#=> true
+
+## Unicode scope values work correctly
+unicode_scope = "测试🔒🔑"
+id_unicode = Familia::VerifiableIdentifier.generate_verifiable_id(scope: unicode_scope)
+Familia::VerifiableIdentifier.verified_identifier?(id_unicode, scope: unicode_scope)
+#=> true
+
+## Scoped identifiers work with different bases
+id_hex = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "test", base: 16)
+Familia::VerifiableIdentifier.verified_identifier?(id_hex, scope: "test", base: 16)
+#=> true
+
+## Backward compatibility: existing method signatures still work
+id = Familia::VerifiableIdentifier.generate_verifiable_id(36)
+Familia::VerifiableIdentifier.verified_identifier?(id, 36)
+#=> true
+
+## Mixed parameter styles work correctly
+id = Familia::VerifiableIdentifier.generate_verifiable_id(scope: "test", base: 16)
+Familia::VerifiableIdentifier.verified_identifier?(id, scope: "test", base: 16)
+#=> true

data/try/features/{external_identifiers/external_identifiers_try.rb → external_identifier/external_identifier_try.rb}

@@ -1,15 +1,15 @@
-# try/features/external_identifiers_try.rb
+# try/features/external_identifier/external_identifier_try.rb
 
 require_relative '../../helpers/test_helpers'
 
 Familia.debug = false
 
-# Test ExternalIdentifiers feature functionality
+# Test ExternalIdentifier feature functionality
 
-# Basic class using external identifiers
+# Basic class using external_identifier
 class ExternalIdTest < Familia::Horreum
-  feature :object_identifiers
-  feature :external_identifiers
+  feature :object_identifier
+  feature :external_identifier
   identifier_field :id
   field :id
   field :name
@@ -17,8 +17,8 @@ end
 
 # Class with custom prefix
 class CustomPrefixTest < Familia::Horreum
-  feature :object_identifiers
-  feature :external_identifiers, prefix: 'cust'
+  feature :object_identifier
+  feature :external_identifier, prefix: 'cust'
   identifier_field :id
   field :id
   field :name
@@ -26,8 +26,8 @@ end
 
 # Class testing data integrity preservation
 class ExternalDataIntegrityTest < Familia::Horreum
-  feature :object_identifiers
-  feature :external_identifiers
+  feature :object_identifier
+  feature :external_identifier
   identifier_field :id
   field :id
   field :name
@@ -40,12 +40,12 @@ end
 @lazy_obj = ExternalIdTest.new
 @complex_obj = ExternalIdTest.new(id: 'complex_ext', name: 'Complex External')
 
-## Feature depends on object_identifiers
-ExternalIdTest.features_enabled.include?(:object_identifiers)
+## Feature depends on object_identifier
+ExternalIdTest.features_enabled.include?(:object_identifier)
 #==> true
 
-## External identifiers feature is included
-ExternalIdTest.features_enabled.include?(:external_identifiers)
+## External identifier feature is included
+ExternalIdTest.features_enabled.include?(:external_identifier)
 #==> true
 
 ## Class has extid field defined
@@ -57,16 +57,14 @@ obj = ExternalIdTest.new
 obj.respond_to?(:extid)
 #==> true
 
-## External ID is generated from objid deterministically
+## External ID is generated from objid deterministically for same object
 obj = ExternalIdTest.new
 obj.id = 'test_obj'
 obj.name = 'Test Object'
 objid = obj.objid
 extid = obj.extid
-# Same objid should always produce same extid
-obj2 = ExternalIdTest.new
-obj2.instance_variable_set(:@objid, objid)
-obj2.extid == extid
+# Multiple calls to extid on same object should return same value
+obj.extid == extid
 #==> true
 
 ## External ID uses default 'ext' prefix
@@ -123,13 +121,12 @@ result = ExternalIdTest.find_by_extid('nonexistent')
 result.is_a?(ExternalIdTest) || result.nil?
 #==> true
 
-## External ID is deterministic from objid
-test_objid = "01234567-89ab-7def-8fed-cba987654321"
-obj1 = ExternalIdTest.new
-obj1.instance_variable_set(:@objid, test_objid)
-obj2 = ExternalIdTest.new
-obj2.instance_variable_set(:@objid, test_objid)
-obj1.extid == obj2.extid
+## External ID is deterministic within same object
+obj = ExternalIdTest.new
+obj.id = 'deterministic_test'
+first_extid = obj.extid
+second_extid = obj.extid
+first_extid == second_extid
 #==> true
 
 ## External ID is different from objid
@@ -155,14 +152,14 @@ obj1.extid != obj2.extid
 
 ## extid field type is ExternalIdentifierFieldType
 ExternalIdTest.field_types[:extid]
-#=:> Familia::Features::ExternalIdentifiers::ExternalIdentifierFieldType
+#=:> Familia::Features::ExternalIdentifier::ExternalIdentifierFieldType
 
 ## Feature options contain correct prefix
-ExternalIdTest.feature_options(:external_identifiers)[:prefix]
+ExternalIdTest.feature_options(:external_identifier)[:prefix]
 #=> "ext"
 
 ## Custom prefix feature options
-CustomPrefixTest.feature_options(:external_identifiers)[:prefix]
+CustomPrefixTest.feature_options(:external_identifier)[:prefix]
 #=> "cust"
 
 ## External ID is shorter than UUID objid

data/try/features/feature_improvements_try.rb

@@ -0,0 +1,126 @@
+# try/features/feature_improvements_try.rb
+
+require_relative '../helpers/test_helpers'
+
+# Test hierarchical feature registration
+class ::TestClass
+  include Familia::Base
+end
+
+class TestSubClass < TestClass
+end
+
+# Create a simple test feature
+module ::TestFeature
+  def test_method
+    "test feature working"
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def class_test_method
+      "class method from feature"
+    end
+  end
+end
+
+# Test SafeDump DSL improvements
+class ::TestModelWithSafeDump
+  include Familia::Base
+  include Familia::Features::SafeDump
+
+  attr_accessor :id, :name, :email, :active
+
+  def initialize(attrs = {})
+    attrs.each { |k, v| send("#{k}=", v) }
+  end
+
+  def active?
+    @active == true
+  end
+
+  # Define safe dump fields using new DSL
+  safe_dump_field :id
+  safe_dump_field :name
+  safe_dump_field :status, ->(obj) { obj.active? ? 'active' : 'inactive' }
+  safe_dump_fields :email, { computed_field: ->(obj) { "#{obj.name}-computed" } }
+end
+
+# Test field definitions in feature modules
+module ::TestFieldFeature
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # This should work - field calls in ClassMethods should execute in the extending class context
+    def define_test_fields
+      # Assuming we have a field method available (this would come from Horreum)
+      # For this test, we'll just verify the method gets called in the right context
+      self.name + "_with_fields"
+    end
+  end
+end
+
+class ::TestFieldClass
+  include Familia::Base
+  include TestFieldFeature
+end
+
+## Test model-specific feature registration
+# Register feature on TestClass
+TestClass.add_feature TestFeature, :test_feature
+#=> TestFeature
+
+## TestClass should have the feature available
+TestClass.features_available[:test_feature]
+#=> TestFeature
+
+## TestSubClass should inherit the feature from TestClass via ancestry chain
+TestSubClass.find_feature(:test_feature)
+#=> TestFeature
+
+## Familia::Base should also be able to find features in the chain
+Familia::Base.find_feature(:test_feature, TestSubClass)
+#=> TestFeature
+
+## Check that fields were registered correctly
+TestModelWithSafeDump.safe_dump_field_names.sort
+#=> [:computed_field, :email, :id, :name, :status]
+
+## Test the safe_dump functionality
+@test_model = TestModelWithSafeDump.new
+@test_model.id = 123
+@test_model.name = "Test User"
+@test_model.email = "test@example.com"
+@test_model.active = true
+
+@result = @test_model.safe_dump
+#=:> Hash
+
+## Test safe_dump returns correct values
+@result[:id]
+#=> 123
+
+## Test safe_dump name field
+@result[:name]
+#=> "Test User"
+
+## Test safe_dump email field
+@result[:email]
+#=> "test@example.com"
+
+## Test safe_dump status field with callable
+@result[:status]
+#=> "active"
+
+## Test safe_dump computed field
+@result[:computed_field]
+#=> "Test User-computed"
+
+## Test that ClassMethods execute in the right context
+TestFieldClass.define_test_fields
+#=> "TestFieldClass_with_fields"