familia 2.0.0.pre17 → 2.0.0.pre19

data/lib/familia/horreum/persistence.rb

@@ -35,17 +35,23 @@ module Familia
     # Handles conversion between Ruby objects and Valkey hash storage
     #
     module Persistence
-      # Persists the object to Valkey storage with automatic timestamping.
+      # Persists the object to Valkey storage with automatic timestamping and validation.
       #
       # Saves the current object state to Valkey storage, automatically setting
       # created and updated timestamps if the object supports them. The method
-      # commits all persistent fields and optionally updates the key's expiration.
+      # validates unique indexes before the transaction, commits all persistent
+      # fields, and optionally updates the key's expiration.
       #
       # @param update_expiration [Boolean] Whether to update the key's expiration
       #   time after saving. Defaults to true.
       #
       # @return [Boolean] true if the save operation was successful, false otherwise.
       #
+      # @raise [Familia::OperationModeError] If called within an existing transaction.
+      #   Guards need to read current values, which is not possible inside MULTI/EXEC.
+      # @raise [Familia::RecordExistsError] If a unique index constraint is violated
+      #   for any class-level unique_index relationships.
+      #
       # @example Save an object to Valkey
       #   user = User.new(name: "John", email: "john@example.com")
       #   user.save
@@ -55,36 +61,60 @@ module Familia
       #   user.save(update_expiration: false)
       #   # => true
       #
+      # @example Handle duplicate unique index
+      #   user2 = User.new(name: "Jane", email: "john@example.com")
+      #   user2.save
+      #   # => raises Familia::RecordExistsError
+      #
+      # @note Cannot be called within a transaction. Call save first to start
+      #   the transaction, or use commit_fields/hmset for manual field updates
+      #   within transactions.
+      #
       # @note When Familia.debug? is enabled, this method will trace the save
       #   operation for debugging purposes.
       #
       # @see #commit_fields The underlying method that performs the field persistence
+      # @see #guard_unique_indexes! Automatic validation of class-level unique indexes
       #
       def save(update_expiration: true)
-        Familia.trace :SAVE, nil, uri if Familia.debug?
-
-        # No longer need to sync computed identifier with a cache field
-        self.created ||= Familia.now.to_i if respond_to?(:created)
-        self.updated = Familia.now.to_i if respond_to?(:updated)
-
-        # Commit our tale to the Database chronicles
-        # Wrap in transaction for atomicity between save and indexing
-        ret = commit_fields(update_expiration: update_expiration)
-
-        # Auto-index for class-level indexes after successful save
-        # Use transaction to ensure atomicity with the save operation
-        if ret
-          transaction do |conn|
-            auto_update_class_indexes
-            # Add to class-level instances collection after successful save
-            self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
-          end
+        # Prevent save within transaction - unique index guards require read operations
+        # which are not available in Redis MULTI/EXEC blocks
+        if Fiber[:familia_transaction]
+          raise Familia::OperationModeError,
+            "Cannot call save within a transaction. Save operations must be called outside transactions to ensure unique constraints can be validated."
         end
 
-        Familia.ld "[save] #{self.class} #{dbkey} #{ret} (update_expiration: #{update_expiration})"
+        Familia.trace :SAVE, nil, self.class.uri if Familia.debug?
+
+        # Update timestamp fields before saving
+        self.created ||= Familia.now if respond_to?(:created)
+        self.updated = Familia.now if respond_to?(:updated)
+
+        # Validate unique indexes BEFORE the transaction
+        guard_unique_indexes!
+
+        # Everything in ONE transaction for complete atomicity
+        result = transaction do |_conn|
+          # 1. Save all fields
+          prepared_h = to_h_for_storage
+          hmset_result = hmset(prepared_h)
 
-        # Did Database accept our offering?
-        !ret.nil?
+          # 2. Set expiration in same transaction
+          self.update_expiration if update_expiration
+
+          # 3. Update class-level indexes
+          auto_update_class_indexes
+
+          # 4. Add to instances collection if available
+          self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
+
+          hmset_result
+        end
+
+        Familia.ld "[save] #{self.class} #{dbkey} #{result} (update_expiration: #{update_expiration})"
+
+        # Return boolean indicating success
+        !result.nil?
       end
 
       # Saves the object to Valkey storage only if it doesn't already exist.
@@ -129,34 +159,51 @@ module Familia
       # Check if record exists
       # If exists, raise Familia::RecordExistsError
       # If not exists, save
-      def save_if_not_exists(update_expiration: true)
+      def save_if_not_exists!(update_expiration: true)
+        # Prevent save_if_not_exists! within transaction - needs to read existence state
+        if Fiber[:familia_transaction]
+          raise Familia::OperationModeError,
+            "Cannot call save_if_not_exists! within a transaction. This method must be called outside transactions to properly check existence."
+        end
+
         identifier_field = self.class.identifier_field
 
         Familia.ld "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
-        Familia.trace :SAVE_IF_NOT_EXISTS, nil, uri if Familia.debug?
+        Familia.trace :SAVE_IF_NOT_EXISTS, nil, self.class.uri if Familia.debug?
 
-        success = dbclient.watch(dbkey) do
-          if dbclient.exists(dbkey).positive?
-            dbclient.unwatch
-            raise Familia::RecordExistsError, dbkey
-          end
+        attempts = 0
+        begin
+          attempts += 1
 
-          result = dbclient.multi do |multi|
-            multi.hmset(dbkey, to_h_for_storage)
-          end
+          watch do
+            raise Familia::RecordExistsError, dbkey if exists?
 
-          result.is_a?(Array) # transaction succeeded
-        end
+            txn_result = transaction do |_multi|
+              hmset(to_h_for_storage)
+
+              self.update_expiration if update_expiration
+
+              # Auto-index for class-level indexes after successful save
+              auto_update_class_indexes
+            end
 
-        # Auto-index for class-level indexes after successful save
-        # Use transaction to ensure atomicity with the save operation
-        if success
-          transaction do |conn|
-            auto_update_class_indexes
+            Familia.ld "[save_if_not_exists]: txn_result=#{txn_result.inspect}"
+
+            txn_result.successful?
           end
+        rescue OptimisticLockError => e
+          Familia.ld "[save_if_not_exists]: OptimisticLockError (#{attempts}): #{e.message}"
+          raise if attempts >= 3
+
+          sleep(0.001 * (2**attempts))
+          retry
         end
+      end
 
-        success
+      def save_if_not_exists(...)
+        save_if_not_exists!(...)
+      rescue RecordExistsError, OptimisticLockError
+        false
       end
 
       # Commits object fields to the DB storage.
@@ -188,14 +235,15 @@ module Familia
         prepared_value = to_h_for_storage
         Familia.ld "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
 
-        result = hmset(prepared_value)
+        transaction do |_conn|
+          # Set all fields atomically
+          result = hmset(prepared_value)
 
-        # Only classes that have the expiration ferature enabled will
-        # actually set an expiration time on their keys. Otherwise
-        # this will be a no-op that simply logs the attempt.
-        update_expiration(default_expiration: nil) if update_expiration
+          # Update expiration in same transaction to ensure atomicity
+          self.update_expiration if result && update_expiration
 
-        result
+          result
+        end
       end
 
       # Updates multiple fields atomically in a Database transaction.
@@ -216,20 +264,57 @@ module Familia
 
         Familia.trace :BATCH_UPDATE, nil, fields.keys if Familia.debug?
 
-        transaction_result = transaction do |conn|
+        transaction do |_conn|
+          # 1. Update all fields atomically
           fields.each do |field, value|
             prepared_value = serialize_value(value)
-            conn.hset dbkey, field, prepared_value
+            hset field, prepared_value
             # Update instance variable to keep object in sync
             send("#{field}=", value) if respond_to?("#{field}=")
           end
+
+          # 2. Update expiration in same transaction
+          self.update_expiration if update_expiration
         end
+      end
+
+      # Persists only the specified fields to Redis.
+      #
+      # Saves the current in-memory values of specified fields to Redis without
+      # modifying them first. Fields must already be set on the instance.
+      #
+      # @param field_names [Array<Symbol, String>] Names of fields to persist
+      # @param update_expiration [Boolean] Whether to refresh key expiration
+      # @return [self] Returns self for method chaining
+      #
+      # @example Persist only passphrase fields after updating them
+      #   customer.update_passphrase('secret').save_fields(:passphrase, :passphrase_encryption)
+      #
+      def save_fields(*field_names, update_expiration: true)
+        raise ArgumentError, 'No fields specified' if field_names.empty?
 
-        # Update expiration if requested and supported
-        self.update_expiration(default_expiration: nil) if update_expiration && respond_to?(:update_expiration)
+        Familia.trace :SAVE_FIELDS, nil, field_names if Familia.debug?
+
+        transaction do |_conn|
+          # Build hash of field names to serialized values
+          fields_hash = {}
+          field_names.each do |field|
+            field_sym = field.to_sym
+            raise ArgumentError, "Unknown field: #{field}" unless respond_to?(field_sym)
+
+            value = send(field_sym)
+            prepared_value = serialize_value(value)
+            fields_hash[field] = prepared_value
+          end
 
-        # Return the MultiResult directly (transaction already returns MultiResult)
-        transaction_result
+          # Set all fields at once using hmset
+          hmset(fields_hash)
+
+          # Update expiration in same transaction
+          self.update_expiration if update_expiration
+        end
+
+        self
       end
 
       # Updates the object by applying multiple field values.
@@ -279,22 +364,22 @@ module Familia
       # @see #delete! The underlying method that performs the key deletion
       #
       def destroy!
-        Familia.trace :DESTROY, dbkey, uri
+        Familia.trace :DESTROY!, dbkey, self.class.uri
 
         # Execute all deletion operations within a transaction
-        transaction do |conn|
+        transaction do |_conn|
           # Delete the main object key
-          conn.del(dbkey)
+          delete!
 
           # Delete all related fields if present
           if self.class.relations?
             Familia.trace :DELETE_RELATED_FIELDS!, nil,
                           "#{self.class} has relations: #{self.class.related_fields.keys}"
 
-            self.class.related_fields.each do |name, _definition|
+            self.class.related_fields.each_key do |name|
               obj = send(name)
               Familia.trace :DELETE_RELATED_FIELD, name, "Deleting related field #{name} (#{obj.dbkey})"
-              conn.del(obj.dbkey)
+              obj.delete!
             end
           end
         end
@@ -318,6 +403,7 @@ module Familia
       #   after clear_fields! if you want to persist the cleared state.
       #
       def clear_fields!
+        Familia.trace :CLEAR_FIELDS!, dbkey, self.class.uri
         self.class.field_method_map.each_value { |method_name| send("#{method_name}=", nil) }
       end
 
@@ -343,7 +429,7 @@ module Familia
       #   no authoritative source in Valkey storage.
       #
       def refresh!
-        Familia.trace :REFRESH, nil, uri if Familia.debug?
+        Familia.trace :REFRESH, nil, self.class.uri if Familia.debug?
         raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
         fields = hgetall
@@ -354,7 +440,7 @@ module Familia
         # their uninitialized state during refresh operations
         reset_transient_fields!
 
-        optimistic_refresh(**fields)
+        naive_refresh(**fields)
       end
 
       # Refreshes object state from the DB and returns self for method chaining.
@@ -378,6 +464,11 @@ module Familia
         self
       end
 
+      # Convenience methods that forward to the class method of the same name
+      def transaction(...) = self.class.transaction(...)
+      def pipelined(...) = self.class.pipelined(...)
+      def dbclient(...) = self.class.dbclient(...)
+
       private
 
       # Reset all transient fields to nil
@@ -402,12 +493,46 @@ module Familia
         end
       end
 
+      # Validates that unique index constraints are satisfied before saving
+      # This must be called OUTSIDE of transactions to allow reading current values
+      #
+      # @raise [Familia::RecordExistsError] If a unique index constraint is violated
+      #   for any class-level unique_index relationships
+      #
+      # @note Only validates class-level unique indexes (without within: parameter).
+      #   Instance-scoped indexes (with within:) are validated automatically when
+      #   calling add_to_*_index methods:
+      #
+      # @example Instance-scoped indexes need to be called explicitly but when
+      # called they will perform the validation automatically:
+      #   employee.add_to_company_badge_index(company) # raises on duplicate
+      #
+      # @return [void]
+      #
+      def guard_unique_indexes!
+        return unless self.class.respond_to?(:indexing_relationships)
+
+        self.class.indexing_relationships.each do |rel|
+          # Only validate unique indexes (not multi_index)
+          next unless rel.cardinality == :unique
+
+          # Only validate class-level indexes (skip instance-scoped)
+          next if rel.within
+
+          # Call the validation method if it exists
+          validate_method = :"guard_unique_#{rel.index_name}!"
+          send(validate_method) if respond_to?(validate_method)
+        end
+
+        nil # Explicit nil return as documented
+      end
+
       # Automatically update class-level indexes after save
       #
       # Iterates through class-level indexing relationships and calls their
       # corresponding add_to_class_* methods to populate indexes. Only processes
-      # class-level indexes (where target_class == self.class), skipping
-      # instance-scoped indexes which require parent context.
+      # class-level indexes (where within is nil), skipping instance-scoped
+      # indexes which require scope context.
       #
       # Uses idempotent Redis commands (HSET for unique_index) so repeated calls
       # are safe and have negligible performance overhead. Note that multi_index
@@ -434,12 +559,12 @@ module Familia
         return unless self.class.respond_to?(:indexing_relationships)
 
         self.class.indexing_relationships.each do |rel|
-          # Skip instance-scoped indexes (require parent context)
+          # Skip instance-scoped indexes (require scope context)
           # Instance-scoped indexes must be manually populated because they need
-          # the parent object reference (e.g., employee.add_to_company_badge_index(company))
-          unless rel.target_class == self.class
+          # the scope instance reference (e.g., employee.add_to_company_badge_index(company))
+          if rel.within
             Familia.ld <<~LOG_MESSAGE
-              [auto_update_class_indexes] Skipping #{rel.index_name} (requires parent context)
+              [auto_update_class_indexes] Skipping #{rel.index_name} (requires scope context)
             LOG_MESSAGE
             next
           end
@@ -449,7 +574,6 @@ module Familia
           send(add_method) if respond_to?(add_method)
         end
       end
-
     end
   end
 end

data/lib/familia/horreum/serialization.rb

@@ -7,21 +7,20 @@ module Familia
     module Serialization
       # Converts the object's persistent fields to a hash for external use.
       #
-      # Serializes persistent field values for external consumption (APIs, logs),
-      # excluding non-loggable fields like encrypted fields for security.
-      # Only non-nil values are included in the resulting hash.
+      # Returns actual Ruby values (String, Integer, Hash, etc.) for API consumption,
+      # NOT JSON-encoded strings. Excludes non-loggable fields like encrypted fields
+      # for security.
       #
-      # @return [Hash] Hash with field names as keys and serialized values
-      #   safe for external exposure
+      # @return [Hash] Hash with field names as string keys and Ruby values
       #
       # @example Converting an object to hash format for API response
       #   user = User.new(name: "John", email: "john@example.com", age: 30)
       #   user.to_h
-      #   # => {"name"=>"John", "email"=>"john@example.com", "age"=>"30"}
-      #   # encrypted fields are excluded for security
+      #   # => {"name"=>"John", "email"=>"john@example.com", "age"=>30}
+      #   # Note: Returns actual Ruby types, not JSON strings
       #
-      # @note Only loggable fields are included for security
-      # @note Only fields with non-nil values are included
+      # @note Only loggable fields are included. Encrypted fields are excluded.
+      # @note Nil values are excluded from the returned hash (storage optimization)
       #
       def to_h
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
@@ -30,40 +29,45 @@ module Familia
           # Security: Skip non-loggable fields (e.g., encrypted fields)
           next unless field_type.loggable
 
-          method_name = field_type.method_name
-          val = send(method_name)
-          prepared = serialize_value(val)
-          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+          val = send(field_type.method_name)
+          Familia.ld " [to_h] field: #{field} val: #{val.class}"
 
-          # Only include non-nil values in the hash for Valkey
-          # Use string key for database compatibility
-          hsh[field.to_s] = prepared unless prepared.nil?
+          # Use string key for external API compatibility
+          # Return Ruby values, not JSON-encoded strings
+          hsh[field.to_s] = val
         end
       end
 
       # Converts the object's persistent fields to a hash for database storage.
       #
-      # Serializes ALL persistent field values for database storage, including
-      # encrypted fields. This is used internally by commit_fields and other
-      # persistence operations.
+      # Returns JSON-encoded strings for ALL persistent field values, ready for
+      # Redis storage. Unlike to_h, this includes encrypted fields and serializes
+      # values using serialize_value (JSON encoding).
       #
-      # @return [Hash] Hash with field names as keys and serialized values
-      #   ready for database storage
+      # @return [Hash] Hash with field names as string keys and JSON-encoded values
       #
-      # @note Includes ALL persistent fields, including encrypted fields
-      # @note Only fields with non-nil values are included for storage efficiency
+      # @example Internal storage preparation
+      #   user = User.new(name: "John", age: 30)
+      #   user.to_h_for_storage
+      #   # => {"name"=>"\"John\"", "age"=>"30"}
+      #   # Note: Strings are JSON-encoded with quotes
+      #
+      # @note This is an internal method used by commit_fields and hmset
+      # @note Nil values are excluded to optimize Redis storage
       #
       def to_h_for_storage
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
           field_type = self.class.field_types[field]
-          method_name = field_type.method_name
-          val = send(method_name)
+
+          val = send(field_type.method_name)
           prepared = serialize_value(val)
-          Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
 
-          # Only include non-nil values in the hash for Valkey
+          if Familia.debug?
+            Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+          end
+
           # Use string key for database compatibility
-          hsh[field.to_s] = prepared unless prepared.nil?
+          hsh[field.to_s] = prepared
         end
       end
 
@@ -84,7 +88,7 @@ module Familia
       #   methods to maintain data consistency across operations.
       #
       def to_a
-        self.class.persistent_fields.filter_map do |field|
+        self.class.persistent_fields.map do |field|
           field_type = self.class.field_types[field]
 
           # Security: Skip non-loggable fields (e.g., encrypted fields)
@@ -92,80 +96,97 @@ module Familia
 
           method_name = field_type.method_name
           val = send(method_name)
-          prepared = serialize_value(val)
-          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class} prepared: #{prepared.class}"
-          prepared
+          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
+
+          # Return actual Ruby values, including nil to maintain array positions
+          val
         end
       end
 
       # Serializes a Ruby object for Valkey storage.
       #
-      # Converts Ruby objects into the DB-compatible string representations using
-      # the Familia distinguisher for type coercion. Falls back to JSON serialization
-      # for complex types (Hash, Array) when the primary distinguisher returns nil.
+      # Converts ALL Ruby values (including strings) to JSON-encoded strings for
+      # type-safe storage. This ensures round-trip type preservation: the type you
+      # save is the type you get back.
       #
       # The serialization process:
-      # 1. Attempts conversion using Familia.distinguisher with relaxed type checking
-      # 2. For Hash/Array types that return nil, tries custom dump_method or Familia::JsonSerializer.dump
-      # 3. Logs warnings when serialization fails completely
+      # 1. ConcealedStrings (encrypted values) → extract encrypted_value
+      # 2. ALL other types → JSON serialization (String, Integer, Boolean, Float, nil, Hash, Array)
       #
       # @param val [Object] The Ruby object to serialize for Valkey storage
       #
-      # @return [String, nil] The serialized value ready for Valkey storage, or nil
-      #   if serialization failed
+      # @return [String] JSON-encoded string representation
+      #
+      # @example Type preservation through JSON encoding
+      #   serialize_value("007")           # => "\"007\"" (JSON string)
+      #   serialize_value(123)             # => "123" (JSON number)
+      #   serialize_value(true)            # => "true" (JSON boolean)
+      #   serialize_value({a: 1})          # => "{\"a\":1}" (JSON object)
       #
-      # @example Serializing different data types
-      #   serialize_value("hello")        # => "hello"
-      #   serialize_value(42)             # => "42"
-      #   serialize_value({name: "John"}) # => '{"name":"John"}'
-      #   serialize_value([1, 2, 3])      # => "[1,2,3]"
+      # @note Strings are JSON-encoded to prevent type coercion bugs where
+      #   string "123" would be indistinguishable from integer 123 in storage
       #
       # @note This method integrates with Familia's type system and supports
       #   custom serialization methods when available on the object
       #
-      # @see Familia.distinguisher The primary serialization mechanism
+      # @see Familia.identifier_extractor For extracting identifiers from Familia objects
       #
       def serialize_value(val)
         # Security: Handle ConcealedString safely - extract encrypted data for storage
         return val.encrypted_value if val.respond_to?(:encrypted_value)
 
-        prepared = Familia.distinguisher(val, strict_values: false)
-
-        # If the distinguisher returns nil, try using the dump_method but only
-        # use JSON serialization for complex types that need it.
-        if prepared.nil? && (val.is_a?(Hash) || val.is_a?(Array))
-          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : Familia::JsonSerializer.dump(val)
-        end
-
-        # If both the distinguisher and dump_method return nil, log an error
-        Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}" if prepared.nil?
-
-        prepared
+        # ALWAYS write valid JSON for type preservation
+        # This includes strings, which get JSON-encoded with wrapping quotes
+        Familia::JsonSerializer.dump(val)
       end
 
-      # Converts a Database string value back to its original Ruby type
+      # Converts a Redis string value back to its original Ruby type
       #
-      # This method attempts to deserialize JSON strings back to their original
-      # Hash or Array types. Simple string values are returned as-is.
+      # This method deserializes JSON strings back to their original Ruby types
+      # (Integer, Boolean, Float, nil, Hash, Array). Plain strings that cannot
+      # be parsed as JSON are returned as-is.
       #
-      # @param val [String] The string value from Database to deserialize
-      # @param symbolize [Boolean] Whether to symbolize hash keys (default: true for compatibility)
-      # @return [Object] The deserialized value (Hash, Array, or original string)
+      # This pairs with serialize_value which JSON-encodes all non-string values.
+      # The contract ensures type preservation across Redis storage:
+      # - Strings stored as-is → returned as-is
+      # - All other types JSON-encoded → JSON-decoded back to original type
       #
-      def deserialize_value(val, symbolize: true)
-        return val if val.nil? || val == ''
+      # @param val [String] The string value from Redis to deserialize
+      # @param symbolize [Boolean] Whether to symbolize hash keys (default: false)
+      # @param field_name [Symbol, nil] Optional field name for better error context
+      # @return [Object] The deserialized value with original Ruby type, or the original string if not JSON
+      #
+      def deserialize_value(val, symbolize: false, field_name: nil)
+        return nil if val.nil? || val == ''
+
+        # Handle Redis::Future objects during transactions
+        return val if val.is_a?(Redis::Future)
 
-        # Try to parse as JSON first for complex types
         begin
-          parsed = Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
-          # Only return parsed value if it's a complex type (Hash/Array)
-          # Simple values should remain as strings
-          return parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
+          Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
         rescue Familia::SerializerError
-          # Not valid JSON, return as-is
+          log_deserialization_issue(val, field_name)
+          val
+        end
+      end
+
+      private
+
+      def log_deserialization_issue(val, field_name)
+        context = field_name ? "#{self.class}##{field_name}" : self.class.to_s
+        dbkey_info = respond_to?(:dbkey) ? dbkey : 'no dbkey'
+
+        msg = if looks_like_json?(val)
+          "Corrupted JSON in #{context}: #{val.inspect} (#{dbkey_info})"
+        else
+          "Legacy plain string in #{context}: #{val.inspect} (#{dbkey_info})"
         end
 
-        val
+        Familia.le(msg)
+      end
+
+      def looks_like_json?(val)
+        val.start_with?('{', '[', '"') || %w[true false null].include?(val)
       end
     end
   end

data/lib/familia/horreum/utils.rb

@@ -11,14 +11,6 @@ module Familia
     # Provides identifier handling, dbkey generation, and object inspection
     #
     module Utils
-      # def uri
-      #   base_uri = self.class.uri || Familia.uri
-      #   u = base_uri.dup # make a copy to modify safely
-      #   u.logical_database = logical_database if logical_database
-      #   u.key = dbkey
-      #   u
-      # end
-
       # +suffix+ is the value to be used at the end of the db key
       # (e.g. `customer:customer_id:scores` would have `scores` as the suffix
       # and `customer_id` would have been the identifier in that case).