familia 2.0.0.pre10 → 2.0.0.pre12

data/try/features/{object_identifiers/object_identifiers_integration_try.rb → object_identifier/object_identifier_integration_try.rb}

@@ -1,15 +1,15 @@
-# try/features/object_identifiers_integration_try.rb
+# try/features/object_identifier/object_identifier_integration_try.rb
 
 require_relative '../../helpers/test_helpers'
 
 Familia.debug = false
 
-# Integration test for ObjectIdentifiers and ExternalIdentifiers features together
+# Integration test for ObjectIdentifier and ExternalIdentifiers features together
 
 # Class using both features with defaults
 class IntegrationTest < Familia::Horreum
-  feature :object_identifiers
-  feature :external_identifiers  # This depends on :object_identifiers
+  feature :object_identifier
+  feature :external_identifier  # This depends on :object_identifier
   identifier_field :id
   field :id
   field :name
@@ -18,8 +18,8 @@ end
 
 # Class with custom configurations for both features
 class CustomIntegrationTest < Familia::Horreum
-  feature :object_identifiers, generator: :hex
-  feature :external_identifiers, prefix: 'custom'
+  feature :object_identifier, generator: :hex
+  feature :external_identifier, prefix: 'custom'
   identifier_field :id
   field :id
   field :name
@@ -27,8 +27,8 @@ end
 
 # Class testing full lifecycle with Redis persistence
 class PersistenceTest < Familia::Horreum
-  feature :object_identifiers
-  feature :external_identifiers
+  feature :object_identifier
+  feature :external_identifier
   identifier_field :id
   field :id
   field :name
@@ -39,12 +39,12 @@ end
 @integration_obj = IntegrationTest.new(id: 'integration_1', name: 'Integration Test', email: 'test@example.com')
 @custom_obj = CustomIntegrationTest.new(id: 'custom_1', name: 'Custom Test')
 
-## Object identifiers feature is automatically included
-IntegrationTest.features_enabled.include?(:object_identifiers)
+## Object identifier feature is automatically included
+IntegrationTest.features_enabled.include?(:object_identifier)
 #==> true
 
-## External identifiers feature is included
-IntegrationTest.features_enabled.include?(:external_identifiers)
+## External identifier feature is included
+IntegrationTest.features_enabled.include?(:external_identifier)
 #==> true
 
 ## Object responds to objid accessor
@@ -70,14 +70,12 @@ obj = IntegrationTest.new
 obj.objid != obj.extid
 #==> true
 
-## extid is deterministically generated from objid
+## extid is deterministically generated from objid for same object
 obj = IntegrationTest.new
 original_objid = obj.objid
 original_extid = obj.extid
-# Create new object with same objid
-obj2 = IntegrationTest.new
-obj2.instance_variable_set(:@objid, original_objid)
-obj2.extid == original_extid
+# Multiple calls on same object should return same extid
+obj.extid == original_extid
 #==> true
 
 ## Custom objid uses hex format (64 chars for 256-bit)
@@ -145,41 +143,41 @@ lazy_obj2.instance_variable_get(:@objid)
 #=*> nil
 
 ## Check field types objid
-IntegrationTest.field_types[:objid].is_a?(Familia::Features::ObjectIdentifiers::ObjectIdentifierFieldType)
+IntegrationTest.field_types[:objid].is_a?(Familia::Features::ObjectIdentifier::ObjectIdentifierFieldType)
 #==> true
 
 ## ObjectIdentifier fields have correct types in field registry
-IntegrationTest.field_types[:objid].class.ancestors.include?(Familia::Features::ObjectIdentifiers::ObjectIdentifierFieldType)
+IntegrationTest.field_types[:objid].class.ancestors.include?(Familia::Features::ObjectIdentifier::ObjectIdentifierFieldType)
 #==> true
 
 ## ExternalIdentifier fields have correct types in field registry
-IntegrationTest.field_types[:extid].class.ancestors.include?(Familia::Features::ExternalIdentifiers::ExternalIdentifierFieldType)
+IntegrationTest.field_types[:extid].class.ancestors.include?(Familia::Features::ExternalIdentifier::ExternalIdentifierFieldType)
 #==> true
 
-## Object identifiers options are preserved
+## Object identifier options are preserved
 opts = IntegrationTest.feature_options
-opts.key?(:object_identifiers)
+opts.key?(:object_identifier)
 #==> true
 
-## External identifiers options are preserved
+## External identifiersoptions are preserved
 opts = IntegrationTest.feature_options
-opts.key?(:external_identifiers)
+opts.key?(:external_identifier)
 #==> true
 
 ## Generator default configuration is applied correctly
-IntegrationTest.feature_options(:object_identifiers)[:generator]
+IntegrationTest.feature_options(:object_identifier)[:generator]
 #=> :uuid_v7
 
 ## Prefix default configuration is applied correctly
-IntegrationTest.feature_options(:external_identifiers)[:prefix]
+IntegrationTest.feature_options(:external_identifier)[:prefix]
 #=> "ext"
 
 ## Custom generator configuration is applied correctly
-CustomIntegrationTest.feature_options(:object_identifiers)[:generator]
+CustomIntegrationTest.feature_options(:object_identifier)[:generator]
 #=> :hex
 
 ## Custom prefix configuration is applied correctly
-CustomIntegrationTest.feature_options(:external_identifiers)[:prefix]
+CustomIntegrationTest.feature_options(:external_identifier)[:prefix]
 #=> "custom"
 
 ## objid is URL-safe (UUID format)
@@ -265,9 +263,9 @@ second_extid = stability_obj.extid
 first_extid == second_extid
 #==> true
 
-## Feature dependency is enforced (external_identifiers requires object_identifiers)
+## Feature dependency is enforced (external_identifier requires object_identifier)
 # This is automatically handled by the feature system
-IntegrationTest.features_enabled.include?(:object_identifiers)
+IntegrationTest.features_enabled.include?(:object_identifier)
 #==> true
 
 ## Objects work with existing Horreum save pattern

data/try/features/{object_identifiers/object_identifiers_try.rb → object_identifier/object_identifier_try.rb}

@@ -1,14 +1,14 @@
-# try/features/object_identifiers_try.rb
+# try/features/object_identifier/object_identifier_try.rb
 
 require_relative '../../helpers/test_helpers'
 
 Familia.debug = false
 
-# Test ObjectIdentifiers feature functionality
+# Test ObjectIdentifier feature functionality
 
 # Basic class using default UUID v7 generator
 class BasicObjectTest < Familia::Horreum
-  feature :object_identifiers
+  feature :object_identifier
   identifier_field :id
   field :id
   field :name
@@ -16,7 +16,7 @@ end
 
 # Class using UUID v4 generator
 class UuidV4Test < Familia::Horreum
-  feature :object_identifiers, generator: :uuid_v4
+  feature :object_identifier, generator: :uuid_v4
   identifier_field :id
   field :id
   field :name
@@ -24,7 +24,7 @@ end
 
 # Class using hex generator
 class HexTest < Familia::Horreum
-  feature :object_identifiers, generator: :hex
+  feature :object_identifier, generator: :hex
   identifier_field :id
   field :id
   field :name
@@ -32,7 +32,7 @@ end
 
 # Class using custom proc generator
 class CustomProcTest < Familia::Horreum
-  feature :object_identifiers, generator: -> { "custom_#{SecureRandom.hex(4)}" }
+  feature :object_identifier, generator: -> { "custom_#{SecureRandom.hex(4)}" }
   identifier_field :id
   field :id
   field :name
@@ -40,7 +40,7 @@ end
 
 # Class testing data integrity preservation
 class DataIntegrityTest < Familia::Horreum
-  feature :object_identifiers
+  feature :object_identifier
   identifier_field :id
   field :id
   field :name
@@ -50,7 +50,7 @@ end
 @existing_obj = DataIntegrityTest.new(id: 'test_id', objid: 'preset_id_123', name: 'Preset Object')
 
 ## Feature is available on class
-BasicObjectTest.features_enabled.include?(:object_identifiers)
+BasicObjectTest.features_enabled.include?(:object_identifier)
 #==> true
 
 ## Class has objid field defined
@@ -162,22 +162,22 @@ basic_obj.objid.include?('-') && !hex_obj.objid.include?('-')
 
 ## objid field type is ObjectIdentifierFieldType
 BasicObjectTest.field_types[:objid]
-#=:> Familia::Features::ObjectIdentifiers::ObjectIdentifierFieldType
+#=:> Familia::Features::ObjectIdentifier::ObjectIdentifierFieldType
 
 ## Generator configuration is accessible through feature options
-BasicObjectTest.feature_options(:object_identifiers)[:generator]
+BasicObjectTest.feature_options(:object_identifier)[:generator]
 #=> :uuid_v7
 
 ## UUID v4 class has correct generator configured
-UuidV4Test.feature_options(:object_identifiers)[:generator]
+UuidV4Test.feature_options(:object_identifier)[:generator]
 #=> :uuid_v4
 
 ## Hex class has correct generator configured
-HexTest.feature_options(:object_identifiers)[:generator]
+HexTest.feature_options(:object_identifier)[:generator]
 #=> :hex
 
 ## Custom proc class has proc generator
-CustomProcTest.feature_options(:object_identifiers)[:generator]
+CustomProcTest.feature_options(:object_identifier)[:generator]
 #=:> Proc
 
 ## Empty initialization preserves nil objid for lazy generation

data/try/features/real_feature_integration_try.rb

@@ -22,11 +22,10 @@ class SafeDumpCategoryTest < Familia::Horreum
 
   feature :safe_dump
 
-  @safe_dump_fields = [
-    :id,
-    :public_name,
-    :email
-  ]
+  # Use new SafeDump DSL
+  safe_dump_field :id
+  safe_dump_field :public_name
+  safe_dump_field :email
 end
 
 # Combined features work together
@@ -39,7 +38,9 @@ class CombinedFeaturesTest < Familia::Horreum
   feature :expiration
   feature :safe_dump
 
-  @safe_dump_fields = [:id, :name]
+  # Use new SafeDump DSL
+  safe_dump_field :id
+  safe_dump_field :name
 end
 
 # Test that individual features can be queried

data/try/features/safe_dump/safe_dump_try.rb

@@ -15,12 +15,11 @@ class SafeDumpTest < Familia::Horreum
   field :email
   field :secret_data
 
-  @safe_dump_fields = [
-    :id,
-    :name,
-    { display_name: ->(obj) { "#{obj.name} (#{obj.id})" } },
-    { has_email: ->(obj) { !obj.email.nil? && !obj.email.empty? } }
-  ]
+  # Use new DSL instead of @safe_dump_fields
+  safe_dump_field :id
+  safe_dump_field :name
+  safe_dump_field :display_name, ->(obj) { "#{obj.name} (#{obj.id})" }
+  safe_dump_field :has_email, ->(obj) { !obj.email.nil? && !obj.email.empty? }
 
   def active?
     true
@@ -47,9 +46,9 @@ SafeDumpTest.respond_to?(:safe_dump_field_map)
 #=> true
 
 ## safe_dump_fields returns field names only
-fields = SafeDumpTest.safe_dump_fields
-fields
-#=> [:id, :name, :display_name, :has_email]
+fields = SafeDumpTest.safe_dump_field_names
+fields.sort
+#=> [:display_name, :has_email, :id, :name]
 
 ## safe_dump_field_map returns callable map
 field_map = SafeDumpTest.safe_dump_field_map

data/try/helpers/test_helpers.rb

@@ -33,6 +33,11 @@ class Blone < Familia::Horreum
   string    :value, default: 'GREAT!'
 end
 
+class Bourne < Familia::Horreum
+  feature :object_identifier
+  feature :external_identifier
+end
+
 class Customer < Familia::Horreum
   logical_database 15 # Use something other than the default DB
   default_expiration 5.years
@@ -41,24 +46,19 @@ class Customer < Familia::Horreum
   # feature :expiration
   # feature :api_version
 
-  # NOTE: The SafeDump mixin caches the safe_dump_field_map so updating this list
-  # with hot reloading in dev mode will not work. You will need to restart the
-  # server to see the changes.
-  @safe_dump_fields = [
-    :custid,
-    :role,
-    :verified,
-    :updated,
-    :created,
-
-    # NOTE: The secrets_created incrementer is null until the first secret
-    # is created. See CreateSecret for where the incrementer is called.
-    #
-    { secrets_created: ->(cust) { cust.secrets_created.value || 0 } },
+  # Use new SafeDump DSL instead of @safe_dump_fields
+  safe_dump_field :custid
+  safe_dump_field :role
+  safe_dump_field :verified
+  safe_dump_field :updated
+  safe_dump_field :created
+
+  # NOTE: The secrets_created incrementer is null until the first secret
+  # is created. See CreateSecret for where the incrementer is called.
+  safe_dump_field :secrets_created, ->(cust) { cust.secrets_created.value || 0 }
 
-    # We use the hash syntax here since `:active?` is not a valid symbol.
-    { active: ->(cust) { cust.active? } }
-  ]
+  # We use a callable here since `:active?` is not a valid method symbol.
+  safe_dump_field :active, ->(cust) { cust.active? }
 
   class_sorted_set :values, key: 'onetime:customer'
   class_hashkey :domains

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre10
+  version: 2.0.0.pre12
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -15,56 +15,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -137,8 +137,6 @@ files:
 - README.md
 - bin/irb
 - changelog.d/README.md
-- changelog.d/fragments/.keep
-- changelog.d/template.md.j2
 - docs/archive/.gitignore
 - docs/archive/FAMILIA_RELATIONSHIPS.md
 - docs/archive/FAMILIA_TECHNICAL.md
@@ -160,10 +158,18 @@ files:
 - docs/guides/Security-Model.md
 - docs/guides/Transient-Fields-Guide.md
 - docs/guides/relationships-methods.md
+- docs/migrating/.gitignore
+- docs/migrating/v2.0.0-pre.md
+- docs/migrating/v2.0.0-pre11.md
+- docs/migrating/v2.0.0-pre12.md
+- docs/migrating/v2.0.0-pre5.md
+- docs/migrating/v2.0.0-pre6.md
+- docs/migrating/v2.0.0-pre7.md
 - docs/overview.md
-- examples/bit_encoding_integration.rb
-- examples/redis_command_validation_example.rb
-- examples/relationships_basic.rb
+- docs/reference/auditing_database_commands.rb
+- examples/permissions.rb
+- examples/relationships.rb
+- examples/safe_dump.rb
 - familia.gemspec
 - lib/familia.rb
 - lib/familia/base.rb
@@ -187,17 +193,16 @@ files:
 - lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb
 - lib/familia/encryption/providers/xchacha20_poly1305_provider.rb
 - lib/familia/encryption/registry.rb
-- lib/familia/encryption_request_cache.rb
+- lib/familia/encryption/request_cache.rb
 - lib/familia/errors.rb
 - lib/familia/features.rb
+- lib/familia/features/autoloader.rb
 - lib/familia/features/encrypted_fields.rb
 - lib/familia/features/encrypted_fields/concealed_string.rb
 - lib/familia/features/encrypted_fields/encrypted_field_type.rb
 - lib/familia/features/expiration.rb
-- lib/familia/features/external_identifiers.rb
-- lib/familia/features/external_identifiers/external_identifier_field_type.rb
-- lib/familia/features/object_identifiers.rb
-- lib/familia/features/object_identifiers/object_identifier_field_type.rb
+- lib/familia/features/external_identifier.rb
+- lib/familia/features/object_identifier.rb
 - lib/familia/features/quantization.rb
 - lib/familia/features/relationships.rb
 - lib/familia/features/relationships/cascading.rb
@@ -235,6 +240,7 @@ files:
 - lib/familia/validation/expectations.rb
 - lib/familia/validation/test_helpers.rb
 - lib/familia/validation/validator.rb
+- lib/familia/verifiable_identifier.rb
 - lib/familia/version.rb
 - lib/middleware/database_middleware.rb
 - setup.cfg
@@ -254,6 +260,7 @@ files:
 - try/core/settings_try.rb
 - try/core/tools_try.rb
 - try/core/utils_try.rb
+- try/core/verifiable_identifier_try.rb
 - try/data_types/boolean_try.rb
 - try/data_types/counter_try.rb
 - try/data_types/datatype_base_try.rb
@@ -321,10 +328,11 @@ files:
 - try/features/encrypted_fields/thread_safety_try.rb
 - try/features/encrypted_fields/universal_serialization_safety_try.rb
 - try/features/expiration/expiration_try.rb
-- try/features/external_identifiers/external_identifiers_try.rb
+- try/features/external_identifier/external_identifier_try.rb
 - try/features/feature_dependencies_try.rb
-- try/features/object_identifiers/object_identifiers_integration_try.rb
-- try/features/object_identifiers/object_identifiers_try.rb
+- try/features/feature_improvements_try.rb
+- try/features/object_identifier/object_identifier_integration_try.rb
+- try/features/object_identifier/object_identifier_try.rb
 - try/features/quantization/quantization_try.rb
 - try/features/real_feature_integration_try.rb
 - try/features/relationships/categorical_permissions_try.rb

data/changelog.d/template.md.j2

@@ -1,29 +0,0 @@
-<!--
-A new scriv fragment. Uncomment sections as needed.
-Reference issues or pull requests in parentheses at the end of the entry.
-Example: - Fixed a bug in the connection pool. (Closes #123)
--->
-
-### Added
-<!-- - New features or capabilities -->
-
-### Changed
-<!-- - Changes to existing functionality -->
-
-### Deprecated
-<!-- - Soon-to-be removed features -->
-
-### Removed
-<!-- - Now removed features -->
-
-### Fixed
-<!-- - Bug fixes -->
-
-### Security
-<!-- - Security-related improvements -->
-
-### Documentation
-<!-- - Documentation improvements -->
-
-### AI Assistance
-<!-- - Briefly describe how AI was used for this change (e.g., "Refactoring and documentation by Gemini"). -->

data/lib/familia/features/external_identifiers/external_identifier_field_type.rb

@@ -1,120 +0,0 @@
-# lib/familia/features/external_identifiers/external_identifier_field_type.rb
-
-require 'familia/field_type'
-
-module Familia
-  module Features
-    module ExternalIdentifiers
-      # ExternalIdentifierFieldType - Fields that generate deterministic external identifiers
-      #
-      # External identifier fields generate shorter, public-facing identifiers that are
-      # deterministically derived from object identifiers. These IDs are safe for use
-      # in URLs, APIs, and other external contexts where shorter IDs are preferred.
-      #
-      # Key characteristics:
-      # - Deterministic generation from objid ensures consistency
-      # - Shorter than objid (128-bit vs 256-bit) for external use
-      # - Base-36 encoding for URL-safe identifiers
-      # - 'ext_' prefix for clear identification as external IDs
-      # - Lazy generation preserves values from initialization
-      #
-      # @example Using external identifier fields
-      #   class User < Familia::Horreum
-      #     feature :object_identifiers
-      #     feature :external_identifiers
-      #     field :email
-      #   end
-      #
-      #   user = User.new(email: 'user@example.com')
-      #   user.objid  # => "01234567-89ab-7def-8000-123456789abc"
-      #   user.extid  # => "ext_abc123def456ghi789" (deterministic from objid)
-      #
-      #   # Same objid always produces same extid
-      #   user2 = User.new(objid: user.objid, email: 'user@example.com')
-      #   user2.extid  # => "ext_abc123def456ghi789" (identical to user.extid)
-      #
-      class ExternalIdentifierFieldType < FieldType
-        # Override getter to provide lazy generation from objid
-        #
-        # Generates the external identifier deterministically from the object's
-        # objid. This ensures consistency - the same objid will always produce
-        # the same extid. Only generates when objid is available.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_getter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, method_name) do
-            klass.define_method method_name do
-              # Check if we already have a value (from initialization or previous generation)
-              existing_value = instance_variable_get(:"@#{field_name}")
-              return existing_value unless existing_value.nil?
-
-              # Generate external identifier from objid if available
-              generated_extid = generate_external_identifier
-              return unless generated_extid
-
-              instance_variable_set(:"@#{field_name}", generated_extid)
-
-              # Update mapping if we have an identifier
-              if respond_to?(:identifier) && identifier
-                self.class.extid_lookup[generated_extid] = identifier
-              end
-
-              generated_extid
-            end
-          end
-        end
-
-        # Override setter to preserve values during initialization
-        #
-        # This ensures that values passed during object initialization
-        # (e.g., when loading from Redis) are preserved and not overwritten
-        # by the lazy generation logic.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_setter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, :"#{method_name}=") do
-            klass.define_method :"#{method_name}=" do |value|
-              # Remove old mapping if extid is changing
-              old_value = instance_variable_get(:"@#{field_name}")
-              if old_value && old_value != value && respond_to?(:identifier)
-                self.class.extid_lookup.del(old_value)
-              end
-
-              # Set the new value
-              instance_variable_set(:"@#{field_name}", value)
-
-              # Update mapping if we have both extid and identifier
-              if value && respond_to?(:identifier) && identifier
-                self.class.extid_lookup[value] = identifier
-              end
-            end
-          end
-        end
-
-        # External identifier fields are persisted to database
-        #
-        # @return [Boolean] true - external identifiers are always persisted
-        #
-        def persistent?
-          true
-        end
-
-        # Category for external identifier fields
-        #
-        # @return [Symbol] :external_identifier
-        #
-        def category
-          :external_identifier
-        end
-      end
-    end
-  end
-end