familia 2.3.3 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 715c43e8b2b403b23fdb6ffbb33c8558a8dbccb6c9cc9dc80a5892a193cdf8c6
-  data.tar.gz: 89a9fafdd21877562178d8b4b103f7fe119b6ee12d50ebec9397691bffbf3094
+  metadata.gz: 9dfc0a904fa0458350fcdc3098b01e4ecbbe12846b9ddcb2265929d1f05f3a3d
+  data.tar.gz: ecd74f3b069bde39291fa5c750ed7a4d6f38938f4514563fd87309380b711cba
 SHA512:
-  metadata.gz: b05dcefb1c009d499f6f41918fe01e29dc7604468365f0b1b6de02ea61544b3948d2e4aa3d8909069b833d413e915a6e489af0228fa4976299b9d00f074a4e3c
-  data.tar.gz: 0b90e00e99299f33f48a689a58dca2a941d3db7bf53c455990a8989768aca41f0837941db7ea71a0568b9f2598f4777acff5570d834d2e8ac188112cc6a67d15
+  metadata.gz: ad072a725504dfe12f19ebe23ff8d257174ae431f8a42bf654e17e14db55f0361811e896b49d9f48eeb137272bcce991ddb65c813b0591379eddf9fffc6dd566
+  data.tar.gz: c74fb2bda18b647f1c32d81e669f275c1a93c88aa0123ff69258262cd3ef31bb14b9fda8b31f57fbd9f96eb188f89bed0435a05d844e2f5cab77bd7ff7e1c822

data/CHANGELOG.rst

@@ -7,6 +7,46 @@ 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.3.3)
+    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-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/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.
       #

data/lib/familia/features/relationships/participation/staged_operations.rb

@@ -0,0 +1,239 @@
+# lib/familia/features/relationships/participation/staged_operations.rb
+#
+# frozen_string_literal: true
+
+require_relative 'through_model_operations'
+
+module Familia
+  module Features
+    module Relationships
+      module Participation
+        # StagedOperations provides lifecycle management for staged (deferred) relationships.
+        #
+        # Staged relationships enable invitation workflows where a through model must exist
+        # before the participant does. The staging set holds through model objids until
+        # the relationship is activated.
+        #
+        # Key characteristics:
+        # - UUID identifier: Staged models use UUID keys (not composite keys)
+        # - Deferred activation: Through model exists before participant
+        # - Clean handoff: Activation creates composite-keyed model, destroys UUID-keyed model
+        # - Lazy cleanup: Ghost entries (deleted models still in staging set) are cleaned on access
+        #
+        # Lifecycle:
+        #   stage    → UUID-keyed through model + ZADD staging set
+        #   activate → composite-keyed through model + ZADD active + SADD participations + cleanup
+        #   unstage  → ZREM staging + destroy through model
+        #
+        # Example:
+        #   class Membership < Familia::Horreum
+        #     feature :object_identifier
+        #     field :organization_objid
+        #     field :customer_objid
+        #     field :email
+        #     field :role
+        #     field :status
+        #   end
+        #
+        #   class Customer < Familia::Horreum
+        #     participates_in Organization, :members,
+        #       through: Membership,
+        #       staged: :pending_members
+        #   end
+        #
+        #   # Stage (invitation sent)
+        #   membership = org.stage_members_instance(
+        #     through_attrs: { email: 'invite@example.com', role: 'viewer' }
+        #   )
+        #
+        #   # Activate (invitation accepted) - explicitly carry over desired attributes
+        #   # Note: attrs are NOT auto-merged from staged model (intentional design)
+        #   activated = org.activate_members_instance(
+        #     membership, customer,
+        #     through_attrs: membership.to_h.slice(:role).merge(status: 'active')
+        #   )
+        #
+        module StagedOperations
+          module_function
+
+          # Stage a new through model for deferred activation.
+          #
+          # Creates a through model with a UUID key (not composite) and sets only the
+          # target foreign key. The participant foreign key remains nil until activation.
+          #
+          # The UUID comes from the through model's `feature :object_identifier` init hook.
+          # This is the key difference from ThroughModelOperations.find_or_create, which
+          # uses build_key to create a composite key from target and participant.
+          #
+          # @note Non-atomic operation: The through model is saved before being added to the
+          #   staging set (by the caller). If the staging set add fails (rare Redis failure),
+          #   an orphaned through model may exist. The lazy cleanup mechanism in `load_staged`
+          #   handles such orphans on subsequent access. This trade-off is acceptable for the
+          #   invitation use case where Redis failures are uncommon.
+          #
+          # @note The staging set score (set by the caller) represents the creation timestamp.
+          #   Retrieve via `staging_collection.score(objid)` if needed.
+          #
+          # @param through_class [Class] The through model class (must have feature :object_identifier)
+          # @param target [Object] The target instance (e.g., organization)
+          # @param attrs [Hash] Attributes to set on the through model
+          # @return [Object] The created through model instance with UUID objid
+          #
+          def stage(through_class:, target:, attrs: {})
+            # Create through model - UUID is auto-generated by object_identifier feature's init hook
+            # No objid parameter passed = feature generates UUID (not composite key like find_or_create)
+            inst = through_class.new
+
+            # Set target foreign key only (participant is nil during staging)
+            target_field = "#{target.class.config_name}_objid"
+            inst.send("#{target_field}=", target.objid) if inst.respond_to?("#{target_field}=")
+
+            # Set custom attributes (validated against field schema)
+            safe_attrs = ThroughModelOperations.validated_attrs(through_class, attrs)
+            safe_attrs.each { |k, v| inst.send("#{k}=", v) }
+
+            # Timestamps
+            inst.created_at = Familia.now.to_f if inst.respond_to?(:created_at=)
+            inst.updated_at = Familia.now.to_f if inst.respond_to?(:updated_at=)
+
+            inst.save
+            inst
+          end
+
+          # Activate a staged through model, completing the relationship.
+          #
+          # This operation:
+          # 1. Validates the staged model belongs to the correct target
+          # 2. Validates the staged model hasn't already been activated
+          # 3. Creates a new composite-keyed through model via ThroughModelOperations
+          # 4. Destroys the UUID-keyed staged model
+          #
+          # The caller is responsible for the sorted set operations (ZADD active,
+          # SADD participations, ZREM staging) which happen in a transaction in
+          # the target method builder.
+          #
+          # @note Attribute handling: This method intentionally does NOT auto-merge
+          #   attributes from the staged model. The application controls what data
+          #   carries over by explicitly passing attrs. This design supports workflows
+          #   where staged data (e.g., invitation metadata) differs from activated data
+          #   (e.g., membership settings), and prevents accidental data leakage between
+          #   lifecycle phases. To carry over staged attributes:
+          #
+          #     activated = org.activate_members_instance(
+          #       staged, customer,
+          #       through_attrs: staged.to_h.slice(:role, :invited_by).merge(status: 'active')
+          #     )
+          #
+          # @param through_class [Class] The through model class
+          # @param staged_model [Object] The staged through model to activate
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance (now exists)
+          # @param attrs [Hash] Attributes for the activated through model (not merged with staged)
+          # @return [Object] The new composite-keyed through model
+          # @raise [ArgumentError] if staged model belongs to a different target
+          # @raise [ArgumentError] if staged model is already activated
+          # @raise [ArgumentError] if staged model does not exist (already destroyed)
+          #
+          def activate(through_class:, staged_model:, target:, participant:, attrs: {})
+            # Validate staged model still exists (may have been destroyed by previous activation or TTL)
+            unless staged_model.exists?
+              raise ArgumentError, 'Staged model does not exist (may have been already activated or expired)'
+            end
+
+            # Validate staged model belongs to this target
+            target_field = "#{target.class.config_name}_objid"
+            if staged_model.respond_to?(target_field)
+              staged_target_objid = staged_model.send(target_field)
+              if staged_target_objid && staged_target_objid != target.objid
+                raise ArgumentError,
+                      "Staged model belongs to different target (expected #{target.objid}, got #{staged_target_objid})"
+              end
+            end
+
+            # Validate staged model doesn't already have a participant (already activated)
+            participant_field = "#{participant.class.config_name}_objid"
+            if staged_model.respond_to?(participant_field)
+              existing_participant = staged_model.send(participant_field)
+              if existing_participant && !existing_participant.to_s.empty?
+                raise ArgumentError, 'Model already activated (participant_objid already set)'
+              end
+            end
+
+            # Create composite-keyed through model via existing machinery
+            activated_model = ThroughModelOperations.find_or_create(
+              through_class: through_class,
+              target: target,
+              participant: participant,
+              attrs: attrs,
+            )
+
+            # Destroy the UUID-keyed staged model
+            staged_model.destroy!
+
+            activated_model
+          end
+
+          # Unstage a through model, removing it from the staging set.
+          #
+          # Used when an invitation is revoked before acceptance.
+          # The caller handles ZREM from staging set.
+          #
+          # @param staged_model [Object] The staged through model to remove
+          # @return [Boolean] true if destroyed, false if model didn't exist
+          #
+          def unstage(staged_model:)
+            return false unless staged_model.exists?
+
+            staged_model.destroy!
+            true
+          end
+
+          # Clean up a stale staging set entry.
+          #
+          # Called when a staged model no longer exists (e.g., TTL expiration, manual deletion)
+          # but its objid is still in the staging set. This implements lazy cleanup similar
+          # to how Familia handles ghost entries in the `instances` sorted set.
+          #
+          # @param staging_collection [Familia::SortedSet] The staging collection
+          # @param staged_objid [String] The objid to clean up
+          # @return [Boolean] true if entry was removed, false if not found
+          #
+          def cleanup_stale_staged_entry(staging_collection:, staged_objid:)
+            removed = staging_collection.remove(staged_objid)
+            Familia.debug "[StagedOperations] Cleaned up stale staging entry: #{staged_objid}" if removed
+            removed
+          end
+
+          # Load a staged model with lazy cleanup.
+          #
+          # Attempts to load the through model by objid. If the model doesn't exist
+          # (ghost entry), cleans up the staging set entry and returns nil.
+          #
+          # @param through_class [Class] The through model class
+          # @param staged_objid [String] The objid to load
+          # @param staging_collection [Familia::SortedSet, nil] Optional staging collection for cleanup
+          # @return [Object, nil] The loaded model or nil if not found
+          #
+          def load_staged(through_class:, staged_objid:, staging_collection: nil)
+            model = through_class.load(staged_objid)
+
+            # Check if model actually exists (not just loaded with empty data)
+            if model.nil? || !model.exists?
+              # Clean up ghost entry if staging collection provided
+              if staging_collection
+                cleanup_stale_staged_entry(
+                  staging_collection: staging_collection,
+                  staged_objid: staged_objid,
+                )
+              end
+
+              return nil
+            end
+
+            model
+          end
+        end
+      end
+    end
+  end
+end