familia 2.0.0.pre10 → 2.0.0.pre13

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/time_utils_try.rb

@@ -0,0 +1,130 @@
+require_relative '../helpers/test_helpers'
+
+module RefinedContext
+  using Familia::Refinements::TimeUtils
+
+  def self.eval_in_refined_context(code)
+    eval(code)
+  end
+
+  def self.instance_eval_in_refined_context(code)
+    instance_eval(code)
+  end
+end
+
+# Test TimeUtils refinement
+
+## Numeric#months - convert number to months in seconds
+result = RefinedContext.eval_in_refined_context("1.month")
+result.round(0)
+#=> 2629746.0
+
+## Numeric#months - plural form
+result = RefinedContext.instance_eval_in_refined_context("2.months")
+result.round(0)
+#=> 5259492.0
+
+## Numeric#years - convert number to years in seconds
+result = RefinedContext.eval_in_refined_context("1.year")
+result.round(0)
+#=> 31556952.0
+
+## Numeric#in_months - convert seconds to months
+RefinedContext.instance_eval_in_refined_context("2629746.in_months")
+#=> 1.0
+
+## Numeric#in_years - convert seconds to years
+result = RefinedContext.eval_in_refined_context("#{Familia::Refinements::TimeUtils::PER_YEAR}.in_years")
+result.round(1)
+#=> 1.0
+
+## String#in_seconds - parse month string
+RefinedContext.instance_eval_in_refined_context("'1mo'.in_seconds")
+#=> 2629746.0
+
+## String#in_seconds - parse month string (long form)
+RefinedContext.eval_in_refined_context("'2months'.in_seconds")
+#=> 5259492.0
+
+## String#in_seconds - parse year string
+result = RefinedContext.instance_eval_in_refined_context("'1y'.in_seconds")
+result.round(0)
+#=> 31556952.0
+
+## Numeric#age_in - calculate age in months from timestamp (approximately 1 month ago)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+result = RefinedContext.eval_in_refined_context("#{timestamp}.age_in(:months)")
+(result - 1.0).abs < 0.01
+#=> true
+
+## Numeric#age_in - calculate age in years from timestamp (approximately 1 year ago)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.age_in(:years)")
+(result - 1.0).abs < 0.01
+#=> true
+
+## Numeric#months_old - convenience method for age_in(:months)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+result = RefinedContext.eval_in_refined_context("#{timestamp}.months_old")
+(result - 1.0).abs < 0.01
+#=> true
+
+## Numeric#years_old - convenience method for age_in(:years)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.years_old")
+(result - 1.0).abs < 0.01
+#=> true
+
+## Numeric#months_old - should NOT return seconds (the original bug)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+result = RefinedContext.eval_in_refined_context("#{timestamp}.months_old")
+result.between?(0.9, 1.1)  # Should be ~1 month, not millions of seconds
+#=> true
+
+## Numeric#years_old - should NOT return seconds (the original bug)
+timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.years_old")
+result.between?(0.9, 1.1)  # Should be ~1 year, not millions of seconds
+#=> true
+
+## age_in with from_time parameter - months
+past_time = Time.now - (2 * Familia::Refinements::TimeUtils::PER_MONTH)  # 2 months ago
+from_time = Time.now - Familia::Refinements::TimeUtils::PER_MONTH  # 1 month ago
+result = RefinedContext.eval_in_refined_context("#{past_time.to_f}.age_in(:months, #{from_time.to_f})")
+(result - 1.0).abs < 0.01
+#=> true
+
+## age_in with from_time parameter - years
+past_time = Time.now - (2 * Familia::Refinements::TimeUtils::PER_YEAR)  # 2 years ago
+from_time = Time.now - Familia::Refinements::TimeUtils::PER_YEAR  # 1 year ago
+result = RefinedContext.instance_eval_in_refined_context("#{past_time.to_f}.age_in(:years, #{from_time.to_f})")
+(result - 1.0).abs < 0.01
+#=> true
+
+## Verify month constant is approximately correct (30.437 days)
+expected_seconds_per_month = 30.437 * 24 * 60 * 60
+Familia::Refinements::TimeUtils::PER_MONTH.round(0)
+#=> 2629746.0
+
+## Verify year constant (365.2425 days - Gregorian year)
+expected_seconds_per_year = 365.2425 * 24 * 60 * 60
+Familia::Refinements::TimeUtils::PER_YEAR.round(0)
+#=> 31556952.0
+
+## UNIT_METHODS contains months mapping
+Familia::Refinements::TimeUtils::UNIT_METHODS['months']
+#=> :months
+
+## UNIT_METHODS contains mo mapping
+Familia::Refinements::TimeUtils::UNIT_METHODS['mo']
+#=> :months
+
+## UNIT_METHODS contains month mapping
+Familia::Refinements::TimeUtils::UNIT_METHODS['month']
+#=> :months
+
+## Calendar consistency - 12 months equals 1 year (fix for inconsistency issue)
+result1 = RefinedContext.eval_in_refined_context("12.months")
+result2 = RefinedContext.instance_eval_in_refined_context("1.year")
+result1 == result2
+#=> 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/data_types/datatype_base_try.rb

@@ -21,7 +21,7 @@ p [@a.name, @b.name]
 #=> true
 
 ## Limiter#qstamp
-@limiter1.counter.qstamp(10.minutes, '%H:%M', 1_302_468_980)
+RefinedContext.eval_in_refined_context("@limiter1.counter.qstamp(10.minutes, '%H:%M', 1_302_468_980)")
 ##=> '20:50'
 
 ## Database Types can be stored to quantized stamp suffix
@@ -32,7 +32,8 @@ p [@a.name, @b.name]
 @limiter2 = Limiter.new :requests
 p [@limiter1.default_expiration, @limiter2.default_expiration]
 p [@limiter1.counter.parent.default_expiration, @limiter2.counter.parent.default_expiration]
-@limiter2.counter.qstamp(10.minutes, pattern: nil, time: 1_302_468_980)
+RefinedContext.instance_variable_set(:@limiter2, @limiter2)
+RefinedContext.eval_in_refined_context("@limiter2.counter.qstamp(10.minutes, pattern: nil, time: 1_302_468_980)")
 #=> 1302468600
 
 ## Database Types can be stored to quantized numeric suffix. This

data/try/features/autoloadable/autoloadable_try.rb

@@ -0,0 +1,61 @@
+# try/features/autoloadable/autoloadable_try.rb
+
+require_relative '../../../lib/familia'
+
+# Create test feature module that includes Autoloadable
+module TestAutoloadableFeature
+  include Familia::Features::Autoloadable
+
+  def self.included(base)
+    super
+    base.define_method(:test_feature_method) { "feature_loaded" }
+  end
+end
+
+# Create test class to include the feature
+class TestModelForAutoloadable < Familia::Horreum
+  field :name
+end
+
+## Test that Autoloadable can be included in feature modules
+TestAutoloadableFeature.ancestors.include?(Familia::Features::Autoloadable)
+#=> true
+
+## Test that Autoloadable extends feature modules with ClassMethods
+TestAutoloadableFeature.respond_to?(:post_inclusion_autoload)
+#=> true
+
+## Test that including autoloadable feature in Horreum class works
+TestModelForAutoloadable.include(TestAutoloadableFeature)
+TestModelForAutoloadable.ancestors.include?(TestAutoloadableFeature)
+#=> true
+
+## Test that post_inclusion_autoload can be called with test class
+TestAutoloadableFeature.post_inclusion_autoload(TestModelForAutoloadable, :test_autoloadable_feature, {})
+"success"
+#=> "success"
+
+## Test that feature methods are available on the model
+@test_instance = TestModelForAutoloadable.new(name: 'test')
+@test_instance.respond_to?(:test_feature_method)
+#=> true
+
+## Test that feature method works
+@test_instance.test_feature_method
+#=> "feature_loaded"
+
+## Test that Autoloadable works with DataType classes (should not crash)
+class TestDataTypeAutoloadable < Familia::DataType
+  include Familia::Features::Autoloadable
+end
+
+TestDataTypeAutoloadable.ancestors.include?(Familia::Features::Autoloadable)
+#=> true
+
+## Test that SafeDump includes Autoloadable (real-world usage)
+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

data/try/features/encrypted_fields/concealed_string_core_try.rb

@@ -77,9 +77,14 @@ end
 @doc.content.to_str
 #=!> NoMethodError
 
-## JSON serialization - to_json
-@doc.content.to_json
-#=> "\"[CONCEALED]\""
+## JSON serialization - to_json (fails for security)
+begin
+  @doc.content.to_json
+  raise "Should have raised SerializerError"
+rescue Familia::SerializerError => e
+  e.class
+end
+#=> Familia::SerializerError
 
 ## JSON serialization - as_json
 @doc.content.as_json

data/try/features/encrypted_fields/secure_by_default_behavior_try.rb

@@ -188,18 +188,30 @@ rescue TypeError => e
 end
 #=> true
 
-## JSON serialization is safe
-@user_json = {
-  id: @user.id,
-  username: @user.username,
-  password: @user.password_hash
-}.to_json
-
-@user_json.include?("bcrypt")
-#=> false
+## JSON serialization prevents leakage by raising error
+begin
+  user_json = {
+    id: @user.id,
+    username: @user.username,
+    password: @user.password_hash
+  }.to_json
+  false
+rescue Familia::SerializerError
+  true
+end
+#=> true
 
-## JSON contains concealed marker
-@user_json.include?("[CONCEALED]")
+## JSON serialization with ConcealedString raises error
+begin
+  user_json = {
+    id: @user.id,
+    username: @user.username,
+    password: @user.password_hash
+  }.to_json
+  false
+rescue Familia::SerializerError => e
+  e.message.include?("ConcealedString")
+end
 #=> true
 
 ## Bulk field operations are secure
@@ -281,16 +293,46 @@ api_response = {
   }
 }
 
-@response_json = api_response.to_json
-@response_json.include?("bcrypt")
-#=> false
+begin
+  @response_json = api_response.to_json
+  false
+rescue Familia::SerializerError
+  true
+end
+#=> true
 
 ## API response doesn't leak secrets
-@response_json.include?("sk-1234567890abcdef")
-#=> false
+api_response = {
+  user_id: @user.id,
+  credentials: {
+    password: @user.password_hash,
+    api_key: @user.api_secret
+  }
+}
+
+begin
+  @response_json = api_response.to_json
+  false
+rescue Familia::SerializerError
+  true
+end
+#=> true
 
 ## API response contains concealed markers
-@response_json.include?("[CONCEALED]")
+api_response = {
+  user_id: @user.id,
+  credentials: {
+    password: @user.password_hash,
+    api_key: @user.api_secret
+  }
+}
+
+begin
+  @response_json = api_response.to_json
+  false
+rescue Familia::SerializerError => e
+  e.message.include?("ConcealedString")
+end
 #=> true
 
 ## Debug logging safety

data/try/features/encrypted_fields/universal_serialization_safety_try.rb

@@ -67,9 +67,14 @@ hash_result.keys.include?("api_token")
 @record.api_token.inspect
 #=> "[CONCEALED]"
 
-## JSON serialization - to_json
-@record.api_token.to_json
-#=> "\"[CONCEALED]\""
+## JSON serialization - to_json (fails for security)
+begin
+  @record.api_token.to_json
+  raise "Should have raised SerializerError"
+rescue Familia::SerializerError => e
+  e.class
+end
+#=> Familia::SerializerError
 
 ## JSON serialization - as_json
 @record.api_token.as_json
@@ -100,12 +105,21 @@ hash_result.keys.include?("api_token")
   }
 }
 
-@serialized = @nested_data.to_json
-@serialized.include?("token-abc123456789")
-#=> false
+begin
+  @serialized = @nested_data.to_json
+  false
+rescue Familia::SerializerError
+  true
+end
+#=> true
 
-## Nested JSON contains concealed markers
-@nested_data.to_json.include?("[CONCEALED]")
+## Nested JSON with ConcealedString raises error
+begin
+  @nested_data.to_json
+  false
+rescue Familia::SerializerError => e
+  e.message.include?("ConcealedString cannot be serialized")
+end
 #=> true
 
 ## Array of mixed field types safety
@@ -116,11 +130,21 @@ hash_result.keys.include?("api_token")
   @record.secret_notes
 ]
 
-@mixed_array.to_json.include?("token-abc123456789")
-#=> false
+begin
+  @mixed_array.to_json
+  false
+rescue Familia::SerializerError
+  true
+end
+#=> true
 
-## Mixed array preserves public data
-@mixed_array.to_json.include?("Public Record")
+## Mixed array with ConcealedString raises error
+begin
+  @mixed_array.to_json
+  false
+rescue Familia::SerializerError => e
+  e.message.include?("ConcealedString")
+end
 #=> true
 
 ## String interpolation safety