familia 2.3.2 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfb3f3aa06c0b96493a86fbe2e3c475e81b9a84d69d7b88e06025adbb597ad8e
-  data.tar.gz: c567f15b73c06a67baad7b1aff36e23d0d544de1a25308716f6edbac235a3ca9
+  metadata.gz: 9dfc0a904fa0458350fcdc3098b01e4ecbbe12846b9ddcb2265929d1f05f3a3d
+  data.tar.gz: ecd74f3b069bde39291fa5c750ed7a4d6f38938f4514563fd87309380b711cba
 SHA512:
-  metadata.gz: 66028adaf4e3004b57bb17b39a99745ad771b2af915253cce02a6ca130e028cdf39e0fc11d90c40729ffa85cc5b5fa8c2c2f1b0320a7c3e21ea74858d173c6b6
-  data.tar.gz: aa3c991ea06b0c2268034784b83fb2dfb5ab6507902de3bca2345149dba3bdb287829769abbb15350c093551c79419c3e2e79558cacac2e589161ebdadd9dd4f
+  metadata.gz: ad072a725504dfe12f19ebe23ff8d257174ae431f8a42bf654e17e14db55f0361811e896b49d9f48eeb137272bcce991ddb65c813b0591379eddf9fffc6dd566
+  data.tar.gz: c74fb2bda18b647f1c32d81e669f275c1a93c88aa0123ff69258262cd3ef31bb14b9fda8b31f57fbd9f96eb188f89bed0435a05d844e2f5cab77bd7ff7e1c822

data/CHANGELOG.rst

@@ -7,6 +7,87 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.4.0:
+
+2.4.0 — 2026-04-06
+==================
+
+Added
+-----
+
+- Added ``staged:`` option to ``participates_in`` for invitation workflows where
+  through models must exist before participants. Creates a staging sorted set
+  alongside the active membership set with three new operations:
+  ``stage_members_instance``, ``activate_members_instance``, ``unstage_members_instance``.
+  Staged models use UUID keys; activated models use composite keys.
+  (`#237 <https://github.com/delano/familia/issues/237>`_)
+
+- Added ``StagedOperations`` module in ``lib/familia/features/relationships/participation/``
+  for staging lifecycle management with lazy cleanup for ghost entries.
+
+- Added ``staged?`` and ``staging_collection_name`` methods to ``ParticipationRelationship``.
+
+Changed
+-------
+
+- **Breaking change**: Through models in staged relationships use UUID keys during staging,
+  composite keys after activation. The staged model is destroyed during activation --
+  any references to it become invalid. Application code calling ``accept!`` on
+  staged memberships should capture and use the returned activated model rather
+  than the original staged model.
+
+- Extended ``participates_in`` signature to accept ``staged:`` option (Symbol or nil).
+  Validation ensures ``staged:`` requires ``through:`` option.
+
+AI Assistance
+-------------
+
+- Claude assisted with architecture design, identifying the impedance mismatch between
+  relational ORM patterns and Redis's materialized indexes, analyzing transaction
+  boundaries, and designing the separation between ``StagedOperations`` and
+  ``ThroughModelOperations`` modules.
+
+.. _changelog-2.3.3:
+
+2.3.3 — 2026-03-30
+==================
+
+Added
+-----
+
+- Encrypt now records the original plaintext encoding in the EncryptedData
+  envelope (``encoding`` field), completing the Phase 2 encoding round-trip
+  fix. Decrypt (Phase 1, #228) already falls back to UTF-8 when the field
+  is absent, so this change is backward-compatible. PR #229
+
+Fixed
+-----
+
+- ``build_aad`` now produces consistent AAD (Additional Authenticated Data)
+  regardless of whether the record has been persisted. Previously, encrypted
+  fields with ``aad_fields`` used different AAD computation paths before and
+  after save, making ``reveal`` fail on any record created via ``create!``.
+  Issue #232, PR #234. No migration needed — the previous behavior was
+  broken (AAD mismatch prevented decryption), so no valid ciphertexts
+  exist under the old inconsistent paths.
+
+- ``build_aad`` no longer uses ``.compact`` on AAD field values. Previously,
+  nil fields were silently dropped, shifting later values left and producing
+  a different hash once the field was populated. Now each field is coerced
+  via ``.to_s`` so that nil and empty string both occupy a fixed position
+  in the joined AAD string. Issue #232, PR #234.
+
+AI Assistance
+-------------
+
+- Implementation and test authoring delegated to backend-dev agents, with
+  orchestration and Phase 1 test fixups handled in the main session. Claude
+  Opus 4.6.
+
+- Claude assisted with implementing the fix, updating affected tests, and
+  writing the round-trip regression test. The issue analysis, root cause
+  identification, and suggested fix were provided in the issue by the author.
+
 .. _changelog-2.3.2:
 
 2.3.2 — 2026-03-12

data/Gemfile.lock

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

data/docs/guides/feature-expiration.md

@@ -622,7 +622,7 @@ Extend current TTL by additional time.
 
 **Returns:** Boolean indicating success
 
-#### `persist!`
+#### `persist!` / `clear_expiration!`
 Remove TTL, making object persistent.
 
 **Returns:** Boolean indicating success

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

@@ -5,6 +5,7 @@ Indexing provides O(1) field-to-object lookups using Redis data structures, enab
 ## Core Concepts
 
 Indexing creates fast lookups for finding objects by field values:
+
 - **O(1) performance** - Hash/Set-based constant-time access
 - **Automatic management** - Class indexes update on save/destroy
 - **Flexible scoping** - Global or parent-scoped uniqueness
@@ -12,12 +13,12 @@ Indexing creates fast lookups for finding objects by field values:
 
 ## Index Types
 
-| Type | Scope | Use Case | Structure |
-|------|-------|----------|-----------|
-| `unique_index` | Class | Global unique fields | Redis HashKey |
-| `unique_index` | Instance | Parent-scoped unique | Redis HashKey |
-| `multi_index` | Class (default) | Global non-unique groupings | Redis Set per value |
-| `multi_index` | Instance | Parent-scoped groupings | Redis Set per value |
+| Type           | Scope           | Use Case                    | Structure           |
+| -------------- | --------------- | --------------------------- | ------------------- |
+| `unique_index` | Class           | Global unique fields        | Redis HashKey       |
+| `unique_index` | Instance        | Parent-scoped unique        | Redis HashKey       |
+| `multi_index`  | Class (default) | Global non-unique groupings | Redis Set per value |
+| `multi_index`  | Instance        | Parent-scoped groupings     | Redis Set per value |
 
 ## Class-Level Unique Indexing
 
@@ -47,12 +48,12 @@ User.find_by_email('alice.smith@example.com')  # => nil
 
 ### Generated Methods
 
-| Method | Description |
-|--------|-------------|
-| `User.find_by_email(email)` | O(1) lookup |
-| `User.index_email_for(user)` | Manual index |
+| Method                         | Description       |
+| ------------------------------ | ----------------- |
+| `User.find_by_email(email)`    | O(1) lookup       |
+| `User.index_email_for(user)`   | Manual index      |
 | `User.unindex_email_for(user)` | Remove from index |
-| `User.reindex_email_for(user)` | Update index |
+| `User.reindex_email_for(user)` | Update index      |
 
 ## Instance-Scoped Unique Indexing
 
@@ -139,20 +140,20 @@ Customer.role_index_for('user').dbkey   # => "customer:role_index:user"
 
 ### Generated Class Methods
 
-| Method | Description |
-|--------|-------------|
-| `Customer.role_index_for(value)` | Factory returning `Familia::UnsortedSet` for the field value |
-| `Customer.find_all_by_role(value)` | Find all objects with that field value |
-| `Customer.sample_from_role(value, count)` | Random sample of objects |
-| `Customer.rebuild_role_index` | Rebuild the entire index from source data |
+| Method                                    | Description                                                  |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `Customer.role_index_for(value)`          | Factory returning `Familia::UnsortedSet` for the field value |
+| `Customer.find_all_by_role(value)`        | Find all objects with that field value                       |
+| `Customer.sample_from_role(value, count)` | Random sample of objects                                     |
+| `Customer.rebuild_role_index`             | Rebuild the entire index from source data                    |
 
 ### Generated Instance Methods
 
-| Method | Description |
-|--------|-------------|
-| `customer.add_to_class_role_index` | Add this object to its field value's index |
-| `customer.remove_from_class_role_index` | Remove this object from its field value's index |
-| `customer.update_in_class_role_index(old_value)` | Move object from old index to new index |
+| Method                                           | Description                                     |
+| ------------------------------------------------ | ----------------------------------------------- |
+| `customer.add_to_class_role_index`               | Add this object to its field value's index      |
+| `customer.remove_from_class_role_index`          | Remove this object from its field value's index |
+| `customer.update_in_class_role_index(old_value)` | Move object from old index to new index         |
 
 ### Update Operations
 
@@ -271,24 +272,28 @@ todays_events = user.find_all_by_daily_partition(today)
 ### Class vs Instance Scoping
 
 **Class-level unique (`unique_index :email, :email_lookup`):**
+
 - Automatic indexing on save/destroy
 - System-wide uniqueness
 - No parent context needed
 - Examples: emails, usernames, API keys
 
 **Class-level multi (`multi_index :role, :role_index`):**
+
 - Default behavior (no `within:` needed)
 - Groups all objects by field value at class level
 - Manual indexing via instance methods
 - Examples: roles, categories, statuses
 
 **Instance-scoped (`unique_index :badge, :badge_index, within: Company`):**
+
 - Manual indexing required
 - Unique within parent only
 - Requires parent context
 - Examples: employee IDs, project names per team
 
 **Instance-scoped multi (`multi_index :dept, :dept_index, within: Company`):**
+
 - Groups objects by field value within parent scope
 - Same field value allowed across different parents
 - Manual indexing with parent context
@@ -297,11 +302,13 @@ todays_events = user.find_all_by_daily_partition(today)
 ### Unique vs Multi Indexing
 
 **Unique index (`unique_index`):**
+
 - 1:1 field-to-object mapping
 - Returns single object or nil
 - Enforces uniqueness within scope
 
 **Multi index (`multi_index`):**
+
 - 1:many field-to-objects mapping
 - Returns array of objects
 - Allows duplicate values
@@ -325,6 +332,7 @@ These methods work because **indexes are derived data** - they're computed from
 > **Important:** Participation data (like `@team.members`) cannot be rebuilt automatically because participations represent business decisions, not derived data. See [Why Participations Can't Be Rebuilt](../../lib/familia/features/relationships/participation/rebuild_strategies.md) for the critical distinction between indexes and participations.
 
 **When to rebuild indexes:**
+
 - After data migrations or bulk imports
 - Recovering from index corruption
 - Adding indexes to existing data
@@ -372,26 +380,29 @@ Index values (the object identifiers stored in hash keys and sets) are raw strin
 
 ## Redis Key Patterns
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Class unique | `{class}:{index_name}` | `user:email_lookup` |
-| Class multi | `{class}:{index_name}:{value}` | `customer:role_index:admin` |
-| Instance unique | `{scope}:{id}:{index_name}` | `company:123:badge_index` |
-| Instance multi | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
+| Type            | Pattern                             | Example                              |
+| --------------- | ----------------------------------- | ------------------------------------ |
+| Class unique    | `{class}:{index_name}`              | `user:email_lookup`                  |
+| Class multi     | `{class}:{index_name}:{value}`      | `customer:role_index:admin`          |
+| Instance unique | `{scope}:{id}:{index_name}`         | `company:123:badge_index`            |
+| Instance multi  | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
 
 ## Troubleshooting
 
 ### Common Issues
 
 **Query methods not generated:**
+
 - Check `query: true` (default) or explicitly set
 - Verify `feature :relationships` declared
 
 **Index not updating:**
+
 - Class indexes: automatic on save/destroy
 - Instance indexes: require manual `add_to_*` calls
 
 **Duplicate key errors:**
+
 - Use `multi_index` for non-unique values
 - Consider instance-scoped for contextual uniqueness
 

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

@@ -189,6 +189,80 @@ def add_members_instance(user, score = nil)
 end
 ```
 
+## Staged Relationships (Invitation Workflows)
+
+Staged relationships enable deferred activation where the through model exists before the participant. Common use case: invitations where a Membership record exists before the invited user accepts.
+
+### Setup
+
+```ruby
+class Membership < Familia::Horreum
+  feature :object_identifier  # Required for UUID-keyed staging
+  field :organization_objid
+  field :customer_objid
+  field :email               # Invitation email
+  field :role
+  field :status
+end
+
+class Customer < Familia::Horreum
+  participates_in Organization, :members,
+    through: Membership,
+    staged: :pending_members  # Enables staging API
+end
+```
+
+### Lifecycle
+
+```ruby
+# Stage (send invitation)
+membership = org.stage_members_instance(
+  through_attrs: { email: 'invite@example.com', role: 'viewer' }
+)
+# → UUID-keyed Membership in pending_members sorted set
+
+# Activate (accept invitation)
+activated = org.activate_members_instance(
+  membership, customer,
+  through_attrs: { status: 'active' }
+)
+# → Composite-keyed Membership, staged model destroyed
+
+# Unstage (revoke invitation)
+org.unstage_members_instance(membership)
+# → Membership destroyed, removed from staging set
+```
+
+### Attribute Handling on Activation
+
+Activation intentionally does **not** auto-merge attributes from the staged model. The application controls what data carries over:
+
+```ruby
+# Explicit attribute carryover
+activated = org.activate_members_instance(
+  staged, customer,
+  through_attrs: staged.to_h.slice(:role, :invited_by).merge(status: 'active')
+)
+```
+
+This design supports workflows where:
+- Staged data (invitation metadata) differs from activated data (membership settings)
+- Certain fields should reset on activation (e.g., `status`, timestamps)
+- Sensitive staging data should not leak to the activated record
+
+### Key Differences from Regular Participation
+
+| Aspect | Regular | Staged |
+|--------|---------|--------|
+| Key type | Composite (target+participant) | UUID during staging |
+| Participant | Required at creation | Set on activation |
+| Through model | Optional | Required |
+| Lifecycle | Single-phase | Two-phase (stage → activate) |
+
+### Ghost Entry Cleanup
+
+Staged models that expire via TTL or are manually deleted leave "ghost entries" in the staging set. These are cleaned lazily when accessed via `load_staged` or enumeration methods.
+
 ## Performance Best Practices
 
 ### Bulk Operations

data/lib/familia/encryption/manager.rb

@@ -15,7 +15,8 @@ module Familia
       end
 
       def encrypt(plaintext, context:, additional_data: nil)
-        return nil if plaintext.to_s.empty?
+        plaintext = plaintext.to_s
+        return nil if plaintext.empty?
 
         key = derive_key(context)
 
@@ -26,7 +27,8 @@ module Familia
           nonce: Base64.strict_encode64(result[:nonce]),
           ciphertext: Base64.strict_encode64(result[:ciphertext]),
           auth_tag: Base64.strict_encode64(result[:auth_tag]),
-          key_version: current_key_version
+          key_version: current_key_version,
+          encoding: plaintext.encoding.name,
         ).to_h
 
         Familia::JsonSerializer.dump(encrypted_data)
@@ -35,7 +37,9 @@ module Familia
       end
 
       def decrypt(encrypted_json_or_hash, context:, additional_data: nil)
-        return nil if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
+        if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
+          return nil
+        end
 
         # Increment counter immediately to track all decryption attempts, even failed ones
         Familia::Encryption.derivation_count.increment

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -221,16 +221,18 @@ module Familia
       if @aad_fields.empty?
         # When no AAD fields specified, use class:field:identifier
         base_components.join(':')
-      elsif record.exists?
-        # For unsaved records, don't enforce AAD fields since they can change
-        # For saved records, include field values for tamper protection
-        values = @aad_fields.map { |field| record.send(field) }
-        all_components = [*base_components, *values].compact
-        Digest::SHA256.hexdigest(all_components.join(':'))
-      # Include specified field values in AAD for persisted records
       else
-        # For unsaved records, only use class:field:identifier for context isolation
-        base_components.join(':')
+        # Always include aad_field values regardless of persistence state.
+        # The field values are available on the record before save and must
+        # produce identical AAD at both encrypt and decrypt time.
+        #
+        # .to_s coerces nil to "" so that every declared AAD field occupies
+        # a fixed position in the join. Without this, a nil field would
+        # shift later values left and produce a different hash once the
+        # field is populated — making existing ciphertext undecryptable.
+        values = @aad_fields.map { |field| record.send(field).to_s }
+        all_components = [*base_components, *values]
+        Digest::SHA256.hexdigest(all_components.join(':'))
       end
     end
   end

data/lib/familia/features/expiration.rb

@@ -385,14 +385,29 @@ module Familia
 
       # Remove expiration, making the object persist indefinitely
       #
+      # Cascades to all related fields by default, following the same
+      # pattern as update_expiration. Relations with `no_expiration: true`
+      # are skipped (they already persist independently).
+      #
       # @return [Boolean] Success of the operation
       #
       # @example Make session persistent
       #   session.persist!
+      #   session.clear_expiration!  # alias
       #
       def persist!
+        # Cascade to relations first, mirroring update_expiration behavior
+        if self.class.relations?
+          self.class.related_fields.each do |name, definition|
+            next if definition.opts[:no_expiration]
+
+            send(name).persist
+          end
+        end
+
         dbclient.persist(dbkey)
       end
+      alias clear_expiration! persist!
 
       # Returns a report of TTL values for the main key and all relation keys.
       #