familia 2.0.0.pre12 → 2.0.0.pre13

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 -->

data/lib/familia/core_ext.rb

@@ -1,135 +0,0 @@
-# lib/familia/core_ext.rb
-
-# Extends the String class with time-related functionality
-#
-# This implementaton assumes Time::Units and Numeric mixins are available.
-#
-class String
-  # Converts a string representation of time to seconds
-  #
-  # @example
-  #   "60m".in_seconds #=> 3600.0
-  #
-  # @return [Float, nil] The time in seconds, or nil if the string is invalid
-  def in_seconds
-    q, u = scan(/([\d.]+)([smhyd])?/).flatten
-    q &&= q.to_f and u ||= 's'
-    q&.in_seconds(u)
-  end
-end
-
-# Extends the Time class with additional time unit functionality
-class Time
-  # Provides methods for working with various time units
-  module Units
-    # rubocop:disable Style/SingleLineMethods, Layout/ExtraSpacing
-
-    PER_MICROSECOND = 0.000001
-    PER_MILLISECOND = 0.001
-    PER_MINUTE = 60.0
-    PER_HOUR = 3600.0
-    PER_DAY = 86_400.0
-
-    # Conversion methods
-    #
-    # From other time units -> seconds
-    #
-    def microseconds()    seconds * PER_MICROSECOND     end
-    def milliseconds()    seconds * PER_MILLISECOND    end
-    def seconds()         self                         end
-    def minutes()         seconds * PER_MINUTE          end
-    def hours()           seconds * PER_HOUR             end
-    def days()            seconds * PER_DAY               end
-    def weeks()           seconds * PER_DAY * 7           end
-    def years()           seconds * PER_DAY * 365        end
-
-    # From seconds -> other time units
-    #
-    def in_years()        seconds / PER_DAY / 365      end
-    def in_weeks()        seconds / PER_DAY / 7       end
-    def in_days()         seconds / PER_DAY          end
-    def in_hours()        seconds / PER_HOUR          end
-    def in_minutes()      seconds / PER_MINUTE         end
-    def in_milliseconds() seconds / PER_MILLISECOND    end
-    def in_microseconds() seconds / PER_MICROSECOND   end
-
-    #
-    # Converts seconds to a Time object
-    #
-    # @return [Time] A Time object representing the seconds
-    def in_time
-      Time.at(self).utc
-    end
-
-    # Converts seconds to the specified time unit
-    #
-    # @param u [String, Symbol] The unit to convert to (e.g., 'y', 'w', 'd', 'h', 'm', 'ms', 'us')
-    # @return [Float] The converted time value
-    def in_seconds(u = nil)
-      case u.to_s
-      when /\A(y)|(years?)\z/
-        years
-      when /\A(w)|(weeks?)\z/
-        weeks
-      when /\A(d)|(days?)\z/
-        days
-      when /\A(h)|(hours?)\z/
-        hours
-      when /\A(m)|(minutes?)\z/
-        minutes
-      when /\A(ms)|(milliseconds?)\z/
-        milliseconds
-      when /\A(us)|(microseconds?)|(μs)\z/
-        microseconds
-      else
-        self
-      end
-    end
-
-    # Starring Jennifer Garner, Victor Garber, and Carl Lumbly
-    alias ms milliseconds
-    alias μs microseconds
-    alias second seconds
-    alias minute minutes
-    alias hour hours
-    alias day days
-    alias week weeks
-    alias year years
-
-    # rubocop:enable Style/SingleLineMethods, Layout/ExtraSpacing
-  end
-end
-
-# Extends the Numeric class with time unit and byte conversion functionality
-class Numeric
-  include Time::Units
-
-  # Converts the number to milliseconds
-  #
-  # @return [Float] The number in milliseconds
-  def to_ms
-    (self * 1000.to_f)
-  end
-
-  # Converts the number to a human-readable byte representation using binary units
-  #
-  # @return [String] A string representing the number in bytes, KiB, MiB, GiB, or TiB
-  #
-  # @example
-  #   1024.to_bytes      #=> "1.00 KiB"
-  #   2_097_152.to_bytes #=> "2.00 MiB"
-  #   3_221_225_472.to_bytes #=> "3.00 GiB"
-  #
-  def to_bytes
-    units = %w[B KiB MiB GiB TiB]
-    size = abs.to_f
-    unit = 0
-
-    while size >= 1024 && unit < units.length - 1
-      size /= 1024
-      unit += 1
-    end
-
-    format('%3.2f %s', size, units[unit])
-  end
-end

data/lib/familia/features/autoloader.rb

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