familia 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 923e4c76b9ee95ca39160a66ec9534462b21b16e273fc27c6e67e707647da1a4
-  data.tar.gz: c8dd58304412dd4d9ad57727a4044d8680c16f701869e3f8dd7d0e2a57ed221a
+  metadata.gz: 217726d80e8424a761dfa3aa0f565e9cdadd3da409654f5077226e1a85ae29ac
+  data.tar.gz: b9ce4a30717b220b78689332da5fe40fe790535029399fa2b0f9978dabd89ff5
 SHA512:
-  metadata.gz: 0716f0b0e47a4758933547b884da5265ce186ce3eba55def7672e2540823b8f15671791ed7b2906f6862d863faa273436fb9e52434cec0e10a91a9bd7614ae9e
-  data.tar.gz: 6e018ee75bb16fa2e1be7a7e812dbcd8d8ca9e8a3c82fe078ef19958e3736f01f8c5f34b925a9fc6a0fd3d7ca709604571a5915ee2b828f2a67539e61ac401a2
+  metadata.gz: ba13b9a6832ffce17a17548a398ca25f5588b6b7bc24e349151ddb3289173418947f833959fa83497e65d953ce781c51007c8a8516c42a5deab589e2e013100b
+  data.tar.gz: a2165e1aa07cdd4f7ca90f6c233dace66f9aba8647f652fb26f8ae484ee142506c218a57c57f1c9d86dc5a551958cd95a01be28de789b817ebd529280ee6c8f3

data/CHANGELOG.rst

@@ -7,6 +7,149 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.0:
+
+2.3.0 — 2026-02-26
+==================
+
+Added
+-----
+
+- ``touch_instances!`` and ``remove_from_instances!`` instance methods for
+  explicit instances timeline management. ``touch_instances!`` is idempotent
+  (ZADD updates the timestamp without duplicating).
+
+- ``in_instances?(identifier)`` class method for O(log N) membership checks
+  against the ``instances`` sorted set without loading the object.
+
+- Dirty tracking for scalar fields: ``dirty?``, ``dirty_fields``,
+  ``changed_fields``, ``clear_dirty!``. Setters automatically mark fields
+  dirty; state is cleared after ``save``, ``commit_fields``, and ``refresh!``.
+
+- ``warn_if_dirty!`` guard on collection write methods (``add``, ``push``,
+  ``[]=``, ``value=``). Warns when the parent Horreum has unsaved scalar
+  changes. Enable ``Familia.strict_write_order = true`` to raise instead.
+
+- ``ttl_report`` instance method on Expiration-enabled models. Returns a hash
+  showing TTL for the main key and all relation keys, useful for detecting
+  TTL drift.
+
+- ``debug_fields`` instance method on Horreum. Returns a diagnostic hash
+  showing Ruby value, stored JSON, and type for each persistent field.
+
+- Proactive consistency audit infrastructure for Horreum models. Every
+  subclass now has ``health_check``, ``audit_instances``,
+  ``audit_unique_indexes``, ``audit_multi_indexes``, and
+  ``audit_participations`` class methods to detect phantoms (timeline
+  entries without backing keys), missing entries (keys not in timeline),
+  stale index entries, and orphaned participation members. Issue #221.
+
+- ``AuditReport`` data structure (``Data.define``) that wraps audit
+  results with ``healthy?``, ``to_h`` (summary counts), and ``to_s``
+  (human-readable) methods for quick inspection and programmatic use.
+
+- Repair and rebuild operations: ``repair_instances!``,
+  ``rebuild_instances``, ``repair_indexes!``,
+  ``repair_participations!``, and ``repair_all!`` class methods.
+  ``rebuild_instances`` performs a full SCAN-based rebuild with atomic
+  swap via the existing ``RebuildStrategies`` infrastructure.
+
+- ``scan_keys`` helper on ManagementMethods for production-safe
+  enumeration of keys matching a class pattern via SCAN.
+
+- Participation audit reads actual collection contents (not the instances
+  timeline) and repairs use TYPE introspection to dispatch the correct
+  removal command per collection type.
+
+Changed
+-------
+
+- ``find_by_dbkey`` and ``find_by_identifier`` are now read-only.
+  They no longer call ``cleanup_stale_instance_entry`` as a side effect
+  when a key is missing. Ghost cleanup is the explicit responsibility
+  of the audit/repair layer or direct caller invocation.
+  ``cleanup_stale_instance_entry`` is now a public class method.
+
+- Fast writers (``field!``), ``batch_update``, ``batch_fast_write``,
+  and ``save_fields`` now clear dirty tracking state after a successful
+  database write. Note: this currently clears all dirty flags, even for
+  fields that were not part of the partial write. This known limitation
+  is documented in ``try/features/dirty_tracking_try.rb`` and will be
+  addressed in a future release.
+
+Fixed
+-----
+
+- ``commit_fields``, ``batch_update``, ``save_fields``, and fast writers now
+  touch the ``instances`` sorted set via ``touch_instances!``.
+  Previously, only ``save`` updated the timeline, leaving objects created
+  through other write paths invisible to ``instances.to_a`` enumeration.
+
+- Class-level ``destroy!`` now removes the identifier from the ``instances``
+  sorted set, preventing ghost entries after deletion.
+
+Documentation
+-------------
+
+- Added serialization encoding guide to CLAUDE.md showing how each DataType
+  serializes values and what raw Redis output looks like per type.
+
+AI Assistance
+-------------
+
+- Implementation, test authoring, and iterative debugging performed with
+  Claude Opus 4.6 assistance across dirty tracking, write-order guards,
+  TTL reporting, debug_fields, audit/repair infrastructure, and 211 test
+  cases across 14 audit files.
+
+.. _changelog-2.2.0:
+
+2.2.0 — 2026-02-23
+==================
+
+Added
+-----
+
+- Introduced ``reference: true`` option for DataType collection declarations.
+  Collections with this option store member identifiers raw instead of
+  JSON-encoding them, resolving the semantic mismatch between field storage
+  (type-preserving JSON) and collection member storage (identity references).
+
+Fixed
+-----
+
+- Fixed serialization mismatch in ``instances`` sorted set where
+  ``persist_to_storage`` passed a string identifier (JSON-encoded as
+  ``"\"abc-123\""``), while direct calls passed Familia objects (stored raw as
+  ``abc-123``). Now passes ``self`` to ``instances.add`` and declares
+  ``reference: true`` on the collection, ensuring consistent storage.
+  (`#215 <https://github.com/delano/familia/issues/215>`_)
+
+- Fixed ``UnsortedSet#pop`` returning raw Redis strings instead of deserialized
+  values.
+
+- Fixed ``UnsortedSet#move`` passing raw values to Redis instead of serializing
+  them.
+
+- Fixed ``SortedSet#increment`` truncating scores to integer (``.to_i``) instead
+  of preserving float precision (``.to_f``).
+
+Documentation
+-------------
+
+- Added collection member serialization guide to ``docs/guides/field-system.md``
+  explaining the distinction between field serialization (JSON for type
+  preservation) and collection member serialization (raw identifiers for
+  reference collections).
+
+AI Assistance
+-------------
+
+- Claude assisted with systematic audit of all ``.add()`` call sites and
+  collection declarations across the codebase, identifying the root cause of the
+  serialization mismatch and the three additional DataType method bugs discovered
+  during the audit.
+
 .. _changelog-2.1.1:
 
 2.1.1 — 2026-02-02

data/CLAUDE.md

@@ -186,12 +186,96 @@ end
 - `active: true` (Boolean) stores as `"true"` in Redis and loads back as Boolean `true`
 - `metadata: {key: "value"}` (Hash) stores as JSON and loads back as Hash with proper types
 
+**Serialization by Type** (what you see in `redis-cli HGETALL` or `GET`):
+
+| Context | Serialize method | Ruby `"UK"` in Redis | Ruby `123` in Redis | Deserialize method |
+|---|---|---|---|---|
+| Horreum `field` | `serialize_value` (JSON) | `"\"UK\""` | `"123"` | `deserialize_value` (JSON parse) |
+| `StringKey` | `.to_s` (raw) | `"UK"` | `"123"` | raw string (no parse) |
+| `JsonStringKey` | JSON dump | `"\"UK\""` | `"123"` | JSON parse |
+| `List/Set/SortedSet/HashKey` values | `serialize_value` (JSON) | `"\"UK\""` | `"123"` | `deserialize_value` (JSON parse) |
+
+Key distinction: `StringKey` uses raw `.to_s` serialization (not JSON) to support Redis string operations like `INCR`, `DECR`, and `APPEND`. All other types use JSON encoding. When inspecting raw Redis output, a Horreum string field storing `"UK"` appears as `"\"UK\""` (double-quoted), while a `StringKey` storing `"UK"` appears as `"UK"` (no extra quotes).
+
+Use `debug_fields` on a Horreum instance to see Ruby values vs stored JSON side-by-side:
+```ruby
+user.debug_fields
+# => {"country" => {ruby: "UK", stored: "\"UK\"", type: "String"},
+#     "age"     => {ruby: 30,   stored: "30",      type: "Integer"}}
+```
+
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
 
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
 
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.
 
+### Write Model: Deferred vs Immediate
+
+Familia has a two-tier write model. Understanding when data hits Redis is critical for avoiding inconsistencies.
+
+**Scalar fields** (defined with `field`) use deferred writes:
+- Normal setters (`user.name = "Alice"`) only update the in-memory instance variable. Nothing is written to Redis until `save`, `commit_fields`, or `batch_update` is called.
+- Fast writers (`user.name! "Alice"`) perform an immediate `HSET` on the object's hash key. Use these when you need a single field persisted without a full save cycle.
+
+**Collection fields** (defined with `list`, `set`, `zset`, `hashkey`) use immediate writes:
+- Every mutating method (`add`, `push`, `remove`, `clear`, `[]=`) executes the corresponding Redis command (SADD, RPUSH, ZREM, DEL, etc.) right away.
+- Collection fields live on separate Redis keys from the object's hash, so they cannot participate in the same MULTI/EXEC transaction as scalar fields.
+
+**Safe pattern -- scalars first, then collections:**
+```ruby
+plan.name = "Premium"
+plan.region = "US"
+plan.save  # HMSET for all scalar fields
+
+# Collections mutated AFTER scalars are committed
+plan.features.clear
+plan.features.add("sso")
+plan.features.add("priority_support")
+
+# Or use the convenience wrapper:
+plan.save_with_collections do
+  plan.features.clear
+  plan.features.add("sso")
+end
+```
+
+**Unsafe pattern -- collections before save:**
+```ruby
+plan.name = "Premium"
+plan.features.clear           # Immediate: Redis DEL
+plan.features.add("sso")     # Immediate: Redis SADD
+plan.save                     # If this raises, features are already mutated
+```
+
+**Cross-database limitation**: MULTI/EXEC transactions only work within a single Redis database number. If scalar fields and a collection use different `logical_database` values, they cannot share a transaction. The `save_with_collections` pattern handles this by sequencing the operations rather than wrapping them in MULTI.
+
+**Instances timeline**: The class-level `instances` sorted set is a timeline of last-modified times, not a registry. `persist_to_storage` (called by `save`) and `commit_fields`/`batch_update` all call `touch_instances!` to update the timestamp. Use `in_instances?(identifier)` for fast O(log N) checks without loading the object.
+
+### Instances Timeline Lifecycle
+
+Every Horreum subclass has a class-level `instances` sorted set (a `class_sorted_set` with `reference: true`). This timeline maps identifiers to their last-write timestamp (ZADD score).
+
+**Write paths that touch instances** (call `touch_instances!`):
+- `save` / `save_if_not_exists!` (via `persist_to_storage`)
+- `commit_fields`
+- `batch_update`
+- `save_fields`
+- Fast writers (`field_name!`) via `FieldType` and `DefinitionMethods`
+
+**Write paths that remove from instances**:
+- Instance-level `destroy!` (via `remove_from_instances!`)
+- Class-level `destroy!(identifier)` (direct `instances.remove`)
+- `cleanup_stale_instance_entry` in `find_by_dbkey` (lazy, on-access pruning)
+
+**Ghost objects**: When a hash key expires via TTL but the identifier still lingers in `instances`, enumerating `instances.to_a` returns identifiers for objects that no longer exist. These are cleaned lazily: `find_by_dbkey` detects the missing key and calls `cleanup_stale_instance_entry`. Code that enumerates without loading (e.g. `instances.members`) will still see ghosts.
+
+**`in_instances?` vs `exists?`**:
+- `in_instances?(id)` checks the `instances` sorted set -- fast O(log N), but may return true for expired keys (ghost entries) or false for objects created outside Familia
+- `exists?(id)` checks the actual Redis hash key -- authoritative but requires a round-trip
+
+**`load` / `find_by_id` bypasses instances**: These methods read directly from the hash key via HGETALL. They do not consult `instances`. A key can exist in Redis without being in instances (e.g. created by `commit_fields` in an older version), and vice versa.
+
 ## Thread Safety Considerations
 
 ### Current Thread Safety Status (as of 2025-10-21)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.1.1)
+    familia (2.3.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)

data/README.md

@@ -92,7 +92,7 @@ end
 
 ```ruby
 # Create and save
-user = User.create(email: 'alice@example.com', name: 'Alice', created_at: Time.now.to_i)
+user = User.create(email: 'alice@example.com', name: 'Alice', created_at: Familia.now)
 
 # Find by identifier
 user = User.load('alice@example.com')

data/docs/guides/feature-encrypted-fields.md

@@ -241,7 +241,7 @@ doc = SecureDocument.new(
   document_id: 'doc123',
   owner_id: 'user456',
   content: 'Sensitive document content',
-  created_at: Time.now.to_i
+  created_at: Familia.now.to_i
 )
 
 doc.save
@@ -551,9 +551,9 @@ class EncryptionMonitor
     total_time = 0
 
     Familia::Encryption.define_singleton_method(:encrypt) do |data, **opts|
-      start_time = Time.now
+      start_time = Familia.now
       result = original_encrypt.call(data, **opts)
-      total_time += (Time.now - start_time)
+      total_time += (Familia.now - start_time)
       call_count += 1
 
       if call_count % 100 == 0
@@ -813,7 +813,7 @@ class EncryptionHealthCheck
       end
 
       # Test encrypt/decrypt cycle
-      test_data = "health_check_#{Time.now.to_i}"
+      test_data = "health_check_#{Familia.now.to_i}"
       encrypted = Familia::Encryption.encrypt(test_data)
       decrypted = Familia::Encryption.decrypt(encrypted)
       results[:sample_encrypt_decrypt] = (decrypted == test_data)

data/docs/guides/feature-object-identifiers.md

@@ -193,6 +193,10 @@ custom.objid_generator_used     # => nil (unknown provenance)
 - Debugging and auditing benefit from generator tracking
 - Format validation can be performed based on expected generator
 
+## Identifiers in Collections
+
+When object identifiers are stored in DataType collections (sorted sets, sets, lists), they are stored as **raw strings** — not JSON-encoded. This is critical for consistent membership checks and lookups. Collections that hold object references must be declared with `class:` and `reference: true` options so that `serialize_value` treats both Familia objects and plain identifier strings identically. See [Collection Member Serialization](field-system.md#collection-member-serialization) for the full explanation of why this distinction exists.
+
 ## Lookup Management
 
 ### Automatic Mapping

data/docs/guides/feature-relationships-indexing.md

@@ -262,7 +262,7 @@ class Event < Familia::Horreum
   end
 end
 
-today = Time.now.strftime('%Y%m%d')
+today = Familia.now.strftime('%Y%m%d')
 todays_events = user.find_all_by_daily_partition(today)
 ```
 
@@ -366,6 +366,10 @@ company.badge_index.to_h.each do |badge, emp_id|
 end
 ```
 
+## Index Storage Format
+
+Index values (the object identifiers stored in hash keys and sets) are raw strings, not JSON-encoded. This is a deliberate design choice shared across all Familia collections that store object references — it ensures that lookups, membership checks, and key construction all operate on the same byte representation. See [Collection Member Serialization](field-system.md#collection-member-serialization) for the underlying serialization rules.
+
 ## Redis Key Patterns
 
 | Type | Pattern | Example |

data/docs/guides/feature-relationships-participation.md

@@ -175,7 +175,7 @@ active_tasks = project.tasks.range_by_score(1, '+inf')
 participates_in User, :sessions, score: :expires_at
 
 # Query active sessions
-now = Time.now.to_i
+now = Familia.now.to_i
 active = user.sessions.range_by_score(now, '+inf')
 ```
 

data/docs/guides/feature-relationships.md

@@ -91,7 +91,7 @@ class Task < Familia::Horreum
 
   # Lambda-based scoring
   participates_in Sprint, :tasks, score: -> {
-    priority * 100 + (Time.now - created_at) / 3600
+    priority * 100 + (Familia.now - created_at) / 3600
   }
 end
 
@@ -167,6 +167,10 @@ team.members.to_a                         # Just IDs
 team.member_instances                     # Load objects
 ```
 
+## Serialization of Collection Members
+
+Relationship collections (participation sorted sets, index hash keys, instance-scoped sets) store object identifiers as raw strings. When adding objects to these collections, `serialize_value` extracts the `.identifier` from Familia objects and stores it without JSON encoding. This ensures consistent membership checks regardless of whether code passes an object reference or a string identifier. See [Collection Member Serialization](field-system.md#collection-member-serialization) for the authoritative explanation of why reference collections use raw identifiers while value fields use JSON.
+
 ## Best Practices
 
 1. **Use bulk methods** for multiple additions: `add_domains([d1, d2, d3])`

data/docs/guides/feature-system.md

@@ -245,7 +245,7 @@ module Familia
             field: field,
             old_value: instance_variable_was(field),
             new_value: instance_variable_get("@#{field}"),
-            timestamp: Time.now.to_f
+            timestamp: Familia.now.to_f
           }
 
           self.class.audit_log.append(change_record.to_json)

data/docs/guides/field-system.md

@@ -146,6 +146,43 @@ user.preferences["theme"] = "dark"
 user.login_count.increment
 ```
 
+## Collection Member Serialization
+
+DataType collections (lists, sets, sorted sets, hash keys) and hashkey fields use different serialization strategies based on what they store.
+
+### Fields: JSON Serialization for Type Preservation
+
+Hashkey fields store arbitrary Ruby values — integers, booleans, hashes, nil. All values are JSON-encoded so types survive the Redis round-trip. An Integer `35` stores as `"35"` and loads back as Integer `35`, not String `"35"`.
+
+### Collections: Raw Identifiers for Object References
+
+When a collection's members represent references to Familia objects, those members must be stored as **raw identifier strings** — not JSON-encoded. Identifiers are lookup keys: they're matched against, compared with, and used to construct Redis keys (e.g. `customer:abc-def-123:object`). JSON-encoding an identifier produces a different byte sequence (`"\"abc-def-123\""` vs `abc-def-123`), which causes silent duplicates and broken membership checks.
+
+The `class:` and `reference: true` options on a collection declaration tell `serialize_value` that members are object references, not arbitrary values:
+
+```ruby
+class Customer < Familia::Horreum
+  # Members are object references — stored as raw identifiers
+  class_sorted_set :instances, class: self, reference: true
+
+  # Members are arbitrary values — stored as JSON
+  list :activity_log
+end
+```
+
+With these options set, `serialize_value` normalizes both code paths:
+- Passing a Familia object extracts `.identifier` and stores it raw
+- Passing a String identifier for a Familia class stores it raw (same result)
+- Passing any other value JSON-encodes it for type preservation
+
+Without `class:` metadata, a collection has no way to distinguish "this string is an identifier" from "this string is an arbitrary value" — and the two paths silently diverge.
+
+### The `instances` Sorted Set
+
+Every Horreum subclass automatically gets a `class_sorted_set :instances` — a class-level registry of persisted objects. Members are raw identifier strings; scores are timestamps of when each object was last saved. This is the index used to enumerate all known instances of a class, check persistence, or clean up stale entries.
+
+Because `instances` stores object references, it is declared with `class:` and `reference: true` to ensure consistent serialization regardless of whether callers pass an object or a string identifier.
+
 ## Advanced Field Types
 
 ### Creating Custom Field Types
@@ -376,7 +413,7 @@ class AuditedFieldType < Familia::FieldType
 
         # Audit the change
         old_value = hget(field_name)
-        timestamp = Time.now.to_i
+        timestamp = Familia.now.to_i
 
         # Log the change
         puts "AUDIT: #{field_name} changed from #{old_value} to #{val} at #{timestamp}"
@@ -640,8 +677,8 @@ describe TimestampFieldType do
     expect(instance.created_at).to be_a(Time)
     expect(instance.created_at.to_s).to include("2024-01-01 12:00:00")
 
-    instance.created_at = Time.now
-    expect(instance.created_at).to be_a(Time)
+    instance.created_at = Familia.now
+    expect(instance.created_at).to be_a(Familia)
   end
 
   it "serializes to integer" do

data/docs/guides/optimized-loading.md

@@ -466,9 +466,9 @@ domains = Domain.load_multi(domain_ids).compact
 **Step 3**: Profile the change
 ```ruby
 # Add logging temporarily
-start = Time.now
+start = Familia.now
 domains = Domain.load_multi(domain_ids).compact
-duration = Time.now - start
+duration = Familia.now - start
 Rails.logger.info "Loaded #{domains.size} domains in #{duration}s"
 ```
 

data/examples/datatype_standalone.rb

@@ -232,7 +232,7 @@ class DemoApp
     session_data = {
       'user_id' => '12345',
       'username' => 'demo_user',
-      'login_time' => Time.now.to_i,
+      'login_time' => Familia.now.to_i,
       'preferences' => { 'theme' => 'dark', 'lang' => 'en' },
     }
 

data/examples/encrypted_fields.rb

@@ -126,7 +126,7 @@ puts 'Example 3: Performance optimization with request caching'
 entries = []
 
 # Without caching - each field derives keys independently
-start_time = Time.now
+start_time = Familia.now
 5.times do |i|
   private_key_pem = <<~PEM
     -----BEGIN PRIVATE KEY-----
@@ -145,10 +145,10 @@ start_time = Time.now
   entry.save
   entries << entry
 end
-no_cache_time = Time.now - start_time
+no_cache_time = Familia.now - start_time
 
 # With caching - reuses derived keys within the block
-start_time = Time.now
+start_time = Familia.now
 Familia::Encryption.with_request_cache do
   5.times do |i|
     private_key_pem = <<~PEM
@@ -169,7 +169,7 @@ Familia::Encryption.with_request_cache do
     entries << entry
   end
 end
-cached_time = Time.now - start_time
+cached_time = Familia.now - start_time
 
 puts "Encryption without caching: #{(no_cache_time * 1000).round(2)}ms"
 puts "Encryption with caching: #{(cached_time * 1000).round(2)}ms"

data/examples/json_usage_patterns.rb

@@ -58,7 +58,7 @@ mixed_data = {
   user: user.as_json,
   tags: user.tags.as_json,
   permissions: user.permissions.as_json,
-  meta: { timestamp: Time.now.to_i }
+  meta: { timestamp: Familia.now.to_i }
 }
 puts "   Manual preparation + JsonSerializer.dump:"
 puts Familia::JsonSerializer.dump(mixed_data)
@@ -77,7 +77,7 @@ using Familia::Refinements::DearJson
 mixed_hash = {
   user: user,                    # Familia object (will call as_json)
   tags: user.tags,              # Familia DataType (will call as_json)
-  meta: { timestamp: Time.now.to_i }  # Plain hash (passes through)
+  meta: { timestamp: Familia.now.to_i }  # Plain hash (passes through)
 }
 
 mixed_array = [

data/lib/familia/connection/behavior.rb

@@ -217,7 +217,7 @@ module Familia
       #   obj.pipelined do |conn|
       #     conn.hmset(obj.dbkey, obj.to_h)
       #     conn.hincrby(obj.dbkey, 'count', 1)
-      #     conn.hset(obj.dbkey, 'updated_at', Time.now.to_i)
+      #     conn.hset(obj.dbkey, 'updated_at', Familia.now.to_i)
       #   end
       #
       # @note Connection Inheritance:

data/lib/familia/connection/transaction_core.rb

@@ -40,7 +40,7 @@ module Familia
     #
     #   customer.transaction do
     #     customer.increment(:login_count)
-    #     customer.hset(:last_login, Time.now.to_i)
+    #     customer.hset(:last_login, Familia.now.to_i)
     #   end
     #
     # @example Incorrect Pattern: Save Inside Transaction

data/lib/familia/data_type/serialization.rb

@@ -38,6 +38,15 @@ module Familia
           return prepared
         end
 
+        # Priority 1b: If this collection stores object references (reference: true)
+        # and the value is a String, treat it as a raw identifier. This prevents
+        # mismatches when callers pass identifier strings directly instead of
+        # Familia objects.
+        if val.is_a?(String) && opts[:reference]
+          Familia.debug "  String identifier (reference): #{val}"
+          return val
+        end
+
         # Priority 2: Everything else gets JSON serialized for type preservation
         # This unifies behavior with Horreum fields (Issue #190)
         prepared = Familia::JsonSerializer.dump(val)
@@ -80,6 +89,11 @@ module Familia
         Familia.debug "deserialize_values: (#{@opts}) #{values}"
         return [] if values.empty?
 
+        # Reference collections store raw identifiers — return as-is
+        if @opts[:reference]
+          return values.flatten
+        end
+
         # If a class option is specified, use class-based deserialization
         if @opts[:class]
           unless @opts[:class].respond_to?(:from_json)
@@ -94,9 +108,9 @@ module Familia
 
             val
           rescue StandardError => e
-            Familia.info obj
-            Familia.info "Parse error for #{dbkey} (from_json): #{e.message}"
-            Familia.info e.backtrace
+            Familia.debug "[deserialize] from_json error in #{dbkey}: #{e.message}"
+            Familia.debug "  raw value: #{obj.inspect[0..80]}"
+            Familia.trace :DESERIALIZE_ERROR, dbkey, e.message if Familia.debug?
             nil
           end
 
@@ -110,7 +124,7 @@ module Familia
           begin
             Familia::JsonSerializer.parse(obj)
           rescue Familia::SerializerError
-            # Fallback for legacy data stored without JSON encoding
+            Familia.debug "[deserialize] Raw fallback in #{dbkey}: #{obj.inspect[0..80]}"
             obj
           end
         end
@@ -138,6 +152,9 @@ module Familia
 
         return @opts[:default] if val.nil?
 
+        # Reference collections store raw identifiers — return as-is
+        return val if @opts[:reference]
+
         # If a class option is specified, use the existing class-based deserialization
         if @opts[:class]
           ret = deserialize_values val
@@ -149,7 +166,7 @@ module Familia
         begin
           Familia::JsonSerializer.parse(val)
         rescue Familia::SerializerError
-          # Fallback for legacy data stored without JSON encoding
+          Familia.debug "[deserialize] Raw fallback in #{dbkey}: #{val.inspect[0..80]}"
           val
         end
       end

data/lib/familia/data_type/types/counter.rb

@@ -15,11 +15,20 @@ module Familia
     end
 
     def increment_if_less_than(threshold, amount = 1)
-      current = to_i
-      return false if current >= threshold
-
-      incrementby(amount)
-      true
+      lua = <<~LUA
+        local current = tonumber(redis.call('GET', KEYS[1]) or '0')
+        if current < tonumber(ARGV[1]) then
+          return redis.call('INCRBY', KEYS[1], ARGV[2])
+        end
+        return nil
+      LUA
+      result = dbclient.eval(lua, keys: [dbkey], argv: [threshold, amount])
+      if result
+        update_expiration
+        result.to_i
+      else
+        false
+      end
     end
 
     def atomic_increment_and_get(amount = 1)