familia 2.0.0.pre12 → 2.0.0.pre14

data/try/features/safe_dump/safe_dump_autoloading_try.rb

@@ -0,0 +1,111 @@
+# try/features/safe_dump/safe_dump_autoloading_try.rb
+
+require_relative '../../../lib/familia'
+require 'fileutils'
+require 'tmpdir'
+
+# Create test directory structure for SafeDump autoloading testing
+@test_dir = Dir.mktmpdir('familia_safe_dump_autoload_test')
+@model_file = File.join(@test_dir, 'test_safe_dump_model.rb')
+@extension_file = File.join(@test_dir, 'test_safe_dump_model', 'safe_dump_extensions.rb')
+@extension_dir = File.join(@test_dir, 'test_safe_dump_model')
+
+# Create directory structure
+FileUtils.mkdir_p(@extension_dir)
+
+# Write test model file that uses SafeDump
+File.write(@model_file, <<~RUBY)
+  class TestSafeDumpModel < Familia::Horreum
+    field :name
+    field :email
+    field :secret
+
+    feature :safe_dump
+  end
+RUBY
+
+# Write extension file (pattern: model_name/safe_dump_*.rb)
+File.write(@extension_file, <<~RUBY)
+  class TestSafeDumpModel
+    # Define safe dump fields
+    safe_dump_fields :name, :email
+
+    # Add method to verify autoloading worked
+    def extension_loaded?
+      true
+    end
+  end
+RUBY
+
+## Test that SafeDump includes Autoloadable
+Familia::Features::SafeDump.ancestors.include?(Familia::Features::Autoloadable)
+#=> true
+
+## Test that SafeDump has post_inclusion_autoload capability
+Familia::Features::SafeDump.respond_to?(:post_inclusion_autoload)
+#=> true
+
+## Test SafeDump autoloading by loading model file
+@model_instance = nil
+
+begin
+  require @model_file
+  @model_instance = TestSafeDumpModel.new(
+    name: 'John Doe',
+    email: 'john@example.com',
+    secret: 'hidden data'
+  )
+  true
+rescue => e
+  false
+end
+#=> true
+
+## Test that autoloaded extension method is available
+@model_instance.respond_to?(:extension_loaded?)
+#=> true
+
+## Test autoloaded extension method works
+@model_instance.extension_loaded?
+#=> true
+
+## Test that model was created successfully
+@model_instance.class.name
+#=> "TestSafeDumpModel"
+
+## Test that feature_options were set up correctly
+TestSafeDumpModel.respond_to?(:feature_options)
+#=> true
+
+## Test that safe_dump fields were loaded from extension file
+TestSafeDumpModel.safe_dump_field_names.sort
+#=> [:email, :name]
+
+## Test that safe_dump functionality works with autoloaded fields
+@dump_result = @model_instance.safe_dump
+@dump_result.keys.sort
+#=> [:email, :name]
+
+## Test that only safe fields are dumped
+@dump_result[:name]
+#=> "John Doe"
+
+## Test that email field is included
+@dump_result[:email]
+#=> "john@example.com"
+
+## Test that secret field is excluded (not in safe_dump_fields)
+@dump_result.key?(:secret)
+#=> false
+
+## Test that feature_options can be retrieved
+@options = TestSafeDumpModel.feature_options(:safe_dump)
+@options.is_a?(Hash)
+#=> true
+
+## Test safe_dump feature is recognized
+TestSafeDumpModel.features_enabled.include?(:safe_dump)
+#=> true
+
+# Cleanup test files and directories
+FileUtils.rm_rf(@test_dir)

data/try/helpers/test_helpers.rb

@@ -12,6 +12,8 @@ Familia.enable_database_logging = true
 Familia.enable_database_counter = true
 
 class Bone < Familia::Horreum
+  using Familia::Refinements::TimeLiterals
+
   identifier_field :token
   field     :token
   field     :name
@@ -39,6 +41,9 @@ class Bourne < Familia::Horreum
 end
 
 class Customer < Familia::Horreum
+
+  using Familia::Refinements::TimeLiterals
+
   logical_database 15 # Use something other than the default DB
   default_expiration 5.years
 
@@ -101,6 +106,8 @@ end
 @c.custid = 'd@example.com'
 
 class Session < Familia::Horreum
+  using Familia::Refinements::TimeLiterals
+
   logical_database 14 # don't use Onetime's default DB
   default_expiration 180.minutes
 
@@ -123,6 +130,8 @@ end
 @s = Session.new
 
 class CustomDomain < Familia::Horreum
+  using Familia::Refinements::TimeLiterals
+
   feature :expiration
 
   class_sorted_set :values
@@ -152,6 +161,8 @@ end
 @d.custid = @c.custid
 
 class Limiter < Familia::Horreum
+  using Familia::Refinements::TimeLiterals
+
   feature :expiration
   feature :quantization
 
@@ -229,3 +240,16 @@ module ConcealedStringTestHelper
     end
   end
 end
+
+# Helper module for testing refinements in tryouts
+module RefinedContext
+  using Familia::Refinements::TimeLiterals
+
+  def self.eval_in_refined_context(code)
+    eval(code)
+  end
+
+  def self.instance_eval_in_refined_context(code)
+    instance_eval(code)
+  end
+end

data/try/integration/cross_component_try.rb

@@ -2,7 +2,9 @@
 
 require_relative '../helpers/test_helpers'
 
-TestUser = Class.new(Familia::Horreum) do
+class TestUser < Familia::Horreum
+  using Familia::Refinements::SnakeCase
+
   identifier_field :email
   field :email
   field :name

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre12
+  version: 2.0.0.pre14
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -129,7 +143,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".yardopts"
-- CHANGELOG.md
+- CHANGELOG.rst
 - CLAUDE.md
 - Gemfile
 - Gemfile.lock
@@ -137,6 +151,7 @@ files:
 - README.md
 - bin/irb
 - changelog.d/README.md
+- changelog.d/scriv.ini
 - docs/archive/.gitignore
 - docs/archive/FAMILIA_RELATIONSHIPS.md
 - docs/archive/FAMILIA_TECHNICAL.md
@@ -148,6 +163,7 @@ files:
 - docs/guides/Connection-Pooling-Guide.md
 - docs/guides/Encrypted-Fields-Overview.md
 - docs/guides/Expiration-Feature-Guide.md
+- docs/guides/Feature-System-Autoloading.md
 - docs/guides/Feature-System-Guide.md
 - docs/guides/Features-System-Developer-Guide.md
 - docs/guides/Field-System-Guide.md
@@ -158,23 +174,28 @@ files:
 - docs/guides/Security-Model.md
 - docs/guides/Transient-Fields-Guide.md
 - docs/guides/relationships-methods.md
+- docs/guides/time-utilities.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-pre13.md
+- docs/migrating/v2.0.0-pre14.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
 - docs/reference/auditing_database_commands.rb
+- examples/autoloader/mega_customer.rb
+- examples/autoloader/mega_customer/safe_dump_fields.rb
 - examples/permissions.rb
 - examples/relationships.rb
 - examples/safe_dump.rb
 - familia.gemspec
 - lib/familia.rb
+- lib/familia/autoloader.rb
 - lib/familia/base.rb
 - lib/familia/connection.rb
-- lib/familia/core_ext.rb
 - lib/familia/data_type.rb
 - lib/familia/data_type/commands.rb
 - lib/familia/data_type/serialization.rb
@@ -196,7 +217,7 @@ files:
 - lib/familia/encryption/request_cache.rb
 - lib/familia/errors.rb
 - lib/familia/features.rb
-- lib/familia/features/autoloader.rb
+- lib/familia/features/autoloadable.rb
 - lib/familia/features/encrypted_fields.rb
 - lib/familia/features/encrypted_fields/concealed_string.rb
 - lib/familia/features/encrypted_fields/encrypted_field_type.rb
@@ -229,22 +250,26 @@ files:
 - lib/familia/horreum/subclass/definition.rb
 - lib/familia/horreum/subclass/management.rb
 - lib/familia/horreum/subclass/related_fields_management.rb
+- lib/familia/json_serializer.rb
 - lib/familia/logging.rb
 - lib/familia/multi_result.rb
 - lib/familia/refinements.rb
+- lib/familia/refinements/logger_trace.rb
+- lib/familia/refinements/snake_case.rb
+- lib/familia/refinements/time_literals.rb
 - lib/familia/secure_identifier.rb
 - lib/familia/settings.rb
 - lib/familia/utils.rb
 - lib/familia/validation.rb
 - lib/familia/validation/command_recorder.rb
 - lib/familia/validation/expectations.rb
-- lib/familia/validation/test_helpers.rb
+- lib/familia/validation/validation_helpers.rb
 - lib/familia/validation/validator.rb
 - lib/familia/verifiable_identifier.rb
 - lib/familia/version.rb
 - lib/middleware/database_middleware.rb
-- setup.cfg
 - try/configuration/scenarios_try.rb
+- try/core/autoloader_try.rb
 - try/core/base_enhancements_try.rb
 - try/core/connection_try.rb
 - try/core/create_method_try.rb
@@ -258,6 +283,7 @@ files:
 - try/core/pools_try.rb
 - try/core/secure_identifier_try.rb
 - try/core/settings_try.rb
+- try/core/time_utils_try.rb
 - try/core/tools_try.rb
 - try/core/utils_try.rb
 - try/core/verifiable_identifier_try.rb
@@ -310,6 +336,7 @@ files:
 - try/encryption/providers/xchacha20_poly1305_provider_try.rb
 - try/encryption/roundtrip_validation_try.rb
 - try/encryption/secure_memory_handling_try.rb
+- try/features/autoloadable/autoloadable_try.rb
 - try/features/encrypted_fields/aad_protection_try.rb
 - try/features/encrypted_fields/concealed_string_core_try.rb
 - try/features/encrypted_fields/context_isolation_try.rb
@@ -344,6 +371,7 @@ files:
 - try/features/relationships/relationships_performance_working_try.rb
 - try/features/relationships/relationships_try.rb
 - try/features/safe_dump/safe_dump_advanced_try.rb
+- try/features/safe_dump/safe_dump_autoloading_try.rb
 - try/features/safe_dump/safe_dump_try.rb
 - try/features/transient_fields/redacted_string_try.rb
 - try/features/transient_fields/refresh_reset_try.rb

data/CHANGELOG.md

@@ -1,247 +0,0 @@
-# CHANGELOG.md
-
-All notable changes to Familia are documented here.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-<!--scriv-insert-here-->
-
-<a id='changelog-2.0.0.pre12'></a>
-## 2.0.0.pre12 — 2025-09-04
-
-### Added
-
-- Added the `Familia::VerifiableIdentifier` module to create and verify identifiers with an embedded HMAC signature. This allows an application to stateless-ly confirm that an identifier was generated by itself, preventing forged IDs from malicious sources.
-
-- **Scoped VerifiableIdentifier**: Added `scope` parameter to `generate_verifiable_id()` and `verified_identifier?()` methods, enabling cryptographically isolated identifier namespaces for multi-tenant, multi-domain, or multi-environment applications while maintaining full backward compatibility with existing code.
-
-### Changed
-
-- ObjectIdentifier feature now tracks which generator (uuid_v7, uuid_v4, hex, or custom) was used for each objid to provide provenance information for security-sensitive operations.
-- Updated external identifier derivation to normalize objid format based on the known generator type, eliminating format ambiguity between UUID and hex formats.
-
-- Refactored identifier generation methods for clarity and consistency. Method `generate_objid` is now `generate_object_identifier`, and `generate_external_identifier` is now `derive_external_identifier` to reflect its deterministic nature.
-
-### Removed
-
-- Removed the `generate_extid` class method, which was less secure than the instance-level derivation logic.
-
-### Security
-
-- Hardened external identifier derivation with provenance validation. ExternalIdentifier now validates that objid values come from the ObjectIdentifier feature before deriving external identifiers, preventing derivation from potentially malicious or unvalidated objid values while maintaining deterministic behavior for legitimate use cases.
-
-- Improved the security of external identifiers (`extid`) by using the internal object identifier (`objid`) as a seed for a new random value, rather than deriving the `extid` directly. This prevents potential information leakage from the internal `objid`.
-
-### Documentation
-
-- Added detailed YARD documentation for `VerifiableIdentifier`, explaining how to securely generate and manage the required `VERIFIABLE_ID_HMAC_SECRET` key.
-
-### AI Assistance
-
-- Security analysis of external identifier derivation and hardened design approach was discussed and developed with AI assistance, including provenance tracking, validation logic, format normalization, and comprehensive test updates.
-
-- Implementation of scoped verifiable identifiers was developed with AI assistance to ensure cryptographic security properties and comprehensive test coverage.
-
-<a id='changelog-2.0.0.pre11'></a>
-## 2.0.0.pre11 - 2025-09-03
-
-### Added
-
-- **Enhanced Feature System**: Introduced a hierarchical feature system with ancestry chain traversal for model-specific feature registration. This enables better organization, standardized naming, and automatic loading of project-specific features via the new `Familia::Features::Autoloader` module.
-- **Improved SafeDump DSL**: Replaced the internal `@safe_dump_fields` implementation with a cleaner, more robust DSL using `safe_dump_field` and `safe_dump_fields` methods.
-- Added `generate_short_id` and `shorten_securely` utility methods for creating short, secure identifiers, adapted from `OT::Utils::SecureNumbers`.
-- For a detailed guide on migrating to the new feature system, see `docs/migration/v2.0.0-pre11.md`.
-
-### Changed
-
-- External identifier now raises an `ExternalIdentifierError` if the model does not have an objid field. Previously: returned nil. In practice this should never happen, since the external_identifier feature declares its dependency on object_identifier.
-- Moved lib/familia/encryption_request_cache.rb to lib/familia/encryption/request_cache.rb for consistency.
-- **Simplified ObjectIdentifier Feature Implementation**: Consolidated the ObjectIdentifier feature from two files (~190 lines) to a single file (~140 lines) by moving the ObjectIdentifierFieldType class inline. This reduces complexity while maintaining all existing functionality including lazy generation, data integrity preservation, and multiple generator strategies.
-- **Renamed Identifier Features to Singular Form**: Renamed `object_identifier` → `object_identifier` and `external_identifier` → `external_identifier` for more accurate naming. Added full-length aliases (`object_identifier`/`external_identifier`) alongside the short forms (`objid`/`extid`) for clarity when needed.
-- **Simplified ExternalIdentifier Feature Implementation**: Consolidated the ExternalIdentifier feature from two files (~240 lines) to a single file (~120 lines) by moving the ExternalIdentifierFieldType class inline, following the same pattern as ObjectIdentifier.
-
-### Fixed
-
-- Fixed external identifier generation returning all zeros for UUID-based objids. The `shorten_to_external_id` method now correctly handles both 256-bit secure identifiers and 128-bit UUIDs by detecting input length and applying appropriate bit truncation only when needed.
-
-### Security
-
-- Improved input validation in `shorten_to_external_id` method by replacing insecure character count checking with proper bit length calculation and explicit validation. Invalid inputs now raise clear error messages instead of being silently processed incorrectly.
-
-<a id='changelog-2.0.0-pre10'></a>
-## 2.0.0-pre10 - 2025-09-02
-
-### Added
-
-- The `Familia::Horreum` initializer now supports creating an object directly from its identifier by passing a single argument (e.g., `Customer.new(customer_id)`). This provides a more convenient and intuitive way to instantiate objects from lookups.
-
-- Automatic indexing and class-level tracking on `save()` operations, eliminating the need for manual index updates.
-- Enhanced collection syntax supports the Ruby-idiomatic `<<` operator for more natural relationship management.
-
-### Changed
-
-- The `member_of` relationship is now bidirectional. A single call to `member.add_to_owner_collection(owner)` is sufficient to establish the relationship, removing the need for a second, redundant call on the owner object. This fixes bugs where members could be added to collections twice.
-
-- **BREAKING**: Refactored Familia Relationships API to remove "global" terminology and simplify method generation. (Closes #86)
-- Split `generate_indexing_instance_methods` into focused `generate_direct_index_methods` and `generate_relationship_index_methods` for better separation between direct class-level and relationship-based indexing.
-- Simplified method generation by removing complex global vs parent conditionals.
-- All indexes are now stored at the class level for consistency.
-
-### Fixed
-
-- Fixed a bug in the `class_indexed_by` feature where finder methods (e.g., `find_by_email`) would fail to correctly instantiate objects from the index, returning partially-formed objects.
-
-- Refactored connection handling to properly cache and reuse Redis connections. This eliminates repetitive "Overriding existing connection" warnings and improves performance.
-
-- Method generation now works consistently for both `class_indexed_by` and `indexed_by` with a `parent:`.
-- Resolved metadata storage issues for dynamically created classes.
-- Improved error handling for nil class names in tracking relationships.
-
-### Documentation
-
-- Updated the `examples/relationships_basic.rb` script to reflect the improved, bidirectional `member_of` API and to ensure a clean database state for each run.
-
-### AI Assistance
-
-- This refactoring was implemented with Claude Code assistance, including comprehensive test updates and API modernization.
-
-<a id='changelog-2.0.0-pre9'></a>
-## 2.0.0-pre9 - 2025-09-02
-
-### Added
-
-- Added `class_tracked_in` method for global tracking relationships following Horreum's established `class_` prefix convention
-- Added `class_indexed_by` method for global index relationships with consistent API design
-
-### Changed
-
-- **BREAKING**: `tracked_in :global, collection` syntax now raises ArgumentError - use `class_tracked_in collection` instead
-- **BREAKING**: `indexed_by field, index, context: :global` syntax replaced with `class_indexed_by field, index`
-- **BREAKING**: `indexed_by field, index, context: SomeClass` syntax replaced with `indexed_by field, index, parent: SomeClass`
-- Relationships API now provides consistent parameter naming across all relationship types
-
-### Documentation
-
-- Updated Relationships Guide with new API syntax and migration examples
-- Updated relationships method documentation with new method signatures
-- Updated basic relationships example to demonstrate new API patterns
-- Added tryouts test coverage in try/features/relationships/relationships_api_changes_try.rb
-
-
-<a id='changelog-2.0.0-pre8'></a>
-## 2.0.0-pre8 - 2025-09-01
-
-### Added
-
-- Implemented Scriv-based changelog system for sustainable documentation
-- Added fragment-based workflow for tracking changes
-- Created structured changelog templates and configuration
-
-### Documentation
-
-- Set up Scriv configuration and directory structure
-- Created README for changelog fragment workflow
-
-<!-- scriv-end-here -->
-
-<a id='changelog-2.0.0-pre7'></a>
-## 2.0.0-pre7 - 2025-08-31
-
-### Added
-
-- Comprehensive relationships system with three relationship types:
-  - `tracked_in` - Multi-presence tracking with score encoding
-  - `indexed_by` - O(1) hash-based lookups
-  - `member_of` - Bidirectional membership with collision-free naming
-- Categorical permission system with bit-encoded permissions
-- Time-based permission scoring for temporal access control
-- Permission tier hierarchies with inheritance patterns
-- Scalable permission management for large object collections
-- Score-based sorting with custom scoring functions
-- Permission-aware queries filtering by access levels
-- Relationship validation framework ensuring data integrity
-
-### Changed
-
-- Performance optimizations for large-scale relationship operations
-
-### Security
-
-- GitHub Actions security hardening with matrix optimization
-
-
-<a id='changelog-2.0.0-pre6'></a>
-## 2.0.0-pre6 - 2025-08-15
-
-### Added
-
-- New `save_if_not_exists` method for conditional persistence
-- Atomic persistence operations with transaction support
-- Enhanced error handling for persistence failures
-- Improved data consistency guarantees
-
-### Changed
-
-- Connection provider pattern for flexible pooling strategies
-- Multi-database support with intelligent pool management
-- Thread-safe connection handling for concurrent applications
-- Configurable pool sizing and timeout management
-- Modular class structure with cleaner separation of concerns
-- Enhanced feature system with dependency management
-- Improved inheritance patterns for better code organization
-- Streamlined base class functionality
-
-### Fixed
-
-- Critical security fixes in Ruby workflow vulnerabilities
-- Systematic dependency resolution via multi-constraint optimization
-
-
-<a id='changelog-2.0.0-pre5'></a>
-## 2.0.0-pre5 - 2025-08-05
-
-### Added
-
-- Field-level encryption with transparent access patterns
-- Multiple encryption providers:
-  - XChaCha20-Poly1305 (preferred, requires rbnacl)
-  - AES-256-GCM (fallback, OpenSSL-based)
-- Field-specific key derivation for cryptographic domain separation
-- Configurable key versioning supporting key rotation
-- Non-persistent field storage for sensitive runtime data
-- RedactedString wrapper preventing accidental logging/serialization
-- Memory-safe handling of sensitive data in Ruby objects
-- API-safe serialization excluding transient fields
-
-### Security
-
-- Encryption field security hardening with additional validation
-- Enhanced memory protection for sensitive data handling
-- Improved key management patterns and best practices
-- Security test suite expansion with comprehensive coverage
-
-
-<a id='changelog-2.0.0-pre'></a>
-## 2.0.0-pre - 2025-07-25
-
-### Added
-
-- Complete API redesign for clarity and modern Ruby conventions
-- Valkey compatibility alongside traditional Redis support
-- Ruby 3.4+ modernization with fiber and thread safety improvements
-- Connection pooling foundation with provider pattern architecture
-
-### Changed
-
-- `Familia::Base` replaced by `Familia::Horreum` as the primary base class
-- Connection configuration moved from simple string to block-based setup
-- Feature activation changed from `include` to `feature` declarations
-- Method naming updated for consistency (`delete` → `destroy`, `exists` → `exists?`, `dump` → `serialize`)
-
-### Documentation
-
-- YARD documentation workflow with automated GitHub Pages deployment
-- Comprehensive migrating guide for v1.x to v2.0.0-pre transition
-
-<!-- scriv-end-here -->