familia 2.10.0 → 2.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab706939f766966f0471ff1285db5def4d14bfc9b0d428c5b0caf481595d57c2
-  data.tar.gz: 6d08805e52f5acd4a90fc117bb8a6b2e352c036daa9916c0a19079af827ddfec
+  metadata.gz: 7903e14486c85385ad0b682c009b1f7d182e0cff24b107aa0264692529bb8dfd
+  data.tar.gz: 445219dfcd2df1cf2054b07d90e33902fc21532279730bc274629a2082a02f7f
 SHA512:
-  metadata.gz: b328108ed4793a4c94ddd1ef1447e759bd369647fc81aca87bafe92eb1f23a71a53ca1d763726da5a631af19e520966075bb65ab40ff29d4a4563ac1a4b1e34a
-  data.tar.gz: 652d0a36301b9321eba9225ec658f3d72b0aa449bc0133b038055900475fe546fca36e2df2133680f69a938409afd6b637d0541be44dd956f51cf2cb50b205b2
+  metadata.gz: 635d35b86d7c6a85332517e3b238b8b932d4823b0cfad2f58b7c349a530de44ae02b91930c9ddac7ed538c619cea3a6f8355eeaba20ebf52358ebd45f4547067
+  data.tar.gz: d96538d6fbb486fcd92bc329acd52cba07008e40db5df059f338e060cb6dbb4789c8fe0e8e52ee69891662b1b2353eec3832032aa3ccda50848a986d06ea6a4d

data/CHANGELOG.rst

@@ -7,6 +7,75 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.10.1:
+
+2.10.1 — 2026-06-06
+===================
+
+Added
+-----
+
+- ``record_class:`` option for collection DataTypes (``list``/``set``/
+  ``sorted_set``/``hashkey``). This loading-only hint tells ``each_record`` which
+  class to hydrate via ``load_multi`` without changing how the collection
+  serializes or deserializes reads. Use this when you want ``each_record`` lookup
+  behavior but no changes to read behavior. Issue #297
+
+- ``Familia.atomic_write(*instances)`` persists multiple Horreum instances in a
+  single ``MULTI/EXEC``. Includes an optional ``watch_keys:``/``pre_check:``
+  variant for race-safe, write-once semantics. All participating instances must
+  resolve to the same logical database (raising ``Familia::CrossDatabaseError``
+  otherwise) and must share a hash slot on Redis Cluster. #296
+
+Changed
+-------
+
+- ``participates_in`` / ``class_participates_in`` collections now default to
+  using ``record_class:``. This change requires **no data migration and causes no
+  behavior changes**: existing collections already stored raw identifiers, and
+  read operations (``members``, ``to_a``, ``member?``, ``score``) behave exactly
+  as before. The only difference is that ``each_record`` is now supported. Pre-
+  declared collections are left untouched. Issue #297
+
+Fixed
+-----
+
+- Enabled ``each_record`` on ``participates_in`` and ``class_participates_in``
+  collections by automatically declaring them with ``record_class: <participant
+  class>``. This resolves ``Familia::Problem`` exceptions and loads participant
+  records via ``load_multi`` across all collection types. Issue #297
+
+- Suppressed per-member ``[deserialize] Raw fallback`` warning storm when
+  iterating ``record_class`` collections with non-JSON identifiers (such as UUIDs
+  or prefixed IDs). These expected raw values are now logged at the debug level
+  instead of warnings. Issue #297
+
+- Resolved a connection-pooling bug where the ``WATCH``-based optimistic lock
+  in ``atomic_write(watch_keys:)``, ``save_if_not_exists!``, and ``create!`` was
+  silent/inert. The ``WATCH`` and ``MULTI/EXEC`` commands are now driven through
+  the same connection, ensuring concurrent modifications correctly abort and raise
+  as
+  documented. #296
+
+AI Assistance
+-------------
+
+- AI diagnosed the participation iteration bug and identified that ``reference: true``
+  introduced unintended read-behavior changes. Designed and implemented the
+  ``record_class:`` option to decouple ``each_record`` lookup from read deserialization,
+  suppressed a resulting per-member deserialize warning storm, kept intentional
+  raw-string semantics on ``instances`` and ``unique_index``, updated stale
+  flowcharts in ``datatype-collections.md``, and added regression coverage. Issue #297
+
+- Root-caused and fixed a split-connection defect with Claude Code: implemented a
+  single-connection ``execute_watched_transaction`` primitive (avoiding fiber-pinning
+  that degrades atomic commands) and added real concurrent-modification tests to
+  replace simulated aborts. #296
+
+- Designed and built multi-model atomic writes on top of the new ``WATCH`` primitive:
+  implemented the same-database guard, orchestration logic, and a test suite covering
+  two-model commits, rollback on error, cross-database rejection, and race conditions. #296
+
 .. _changelog-2.10.0:
 
 2.10.0 — 2026-06-04

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.10.0)
+    familia (2.10.1)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -15,59 +15,59 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.9)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
-    bigdecimal (3.3.1)
+    bigdecimal (4.1.2)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     csv (3.3.5)
-    date (3.5.0)
-    debug (1.11.0)
+    date (3.5.1)
+    debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    dry-configurable (1.3.0)
-      dry-core (~> 1.1)
+    dry-configurable (1.4.0)
+      dry-core (~> 1.0)
       zeitwerk (~> 2.6)
-    dry-core (1.1.0)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.2.0)
+    dry-inflector (1.3.1)
     dry-initializer (3.2.0)
     dry-logic (1.6.0)
       bigdecimal
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-schema (1.14.1)
+    dry-schema (1.16.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
       dry-core (~> 1.1)
       dry-initializer (~> 3.2)
-      dry-logic (~> 1.5)
-      dry-types (~> 1.8)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-types (1.8.3)
-      bigdecimal (~> 3.0)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
-    erb (5.1.3)
-    ffi (1.17.2)
-    ffi (1.17.2-arm64-darwin)
+    erb (6.0.4)
+    ffi (1.17.4)
+    ffi (1.17.4-arm64-darwin)
     hana (1.3.7)
-    io-console (0.8.1)
+    io-console (0.8.2)
     irb (1.15.3)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.2.1)
+    json (2.19.8)
     json-schema (6.2.0)
       addressable (~> 2.8)
       bigdecimal (>= 3.1, < 5)
@@ -79,15 +79,15 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    mcp (0.8.0)
+    mcp (0.18.0)
       json-schema (>= 4.1)
     minitest (5.27.0)
-    oj (3.16.13)
+    oj (3.17.3)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    parallel (1.28.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -96,25 +96,27 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    psych (5.2.6)
+    psych (5.4.0)
       date
       stringio
     public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     rbnacl (7.1.2)
       ffi (~> 1)
-    rbs (3.9.5)
+    rbs (4.0.2)
       logger
-    rdoc (6.15.1)
+      prism (>= 1.6.0)
+      tsort
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
     redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.26.2)
+    redis-client (0.29.0)
       connection_pool
     reek (6.5.0)
       dry-schema (~> 1.13)
@@ -122,10 +124,10 @@ GEM
       parser (~> 3.3.0)
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
-    regexp_parser (2.11.3)
-    reline (0.6.2)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rexml (3.4.1)
+    rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -135,10 +137,10 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
+    rspec-support (3.13.7)
     rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -151,28 +153,29 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-performance (1.25.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-thread_safety (0.7.3)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.1)
+    ruby-lsp (0.26.9)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
-    ruby-prof (1.7.2)
+    ruby-prof (2.0.4)
       base64
+      ostruct
     ruby-progressbar (1.13.0)
     simpleidn (0.2.3)
-    stackprof (0.2.27)
+    stackprof (0.2.28)
     stringio (3.1.9)
-    timecop (0.9.10)
+    timecop (0.9.11)
     tryouts (3.7.1)
       concurrent-ruby (~> 1.0, < 2)
       irb
@@ -190,8 +193,8 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri-valkey (1.4.0)
-    yard (0.9.37)
-    zeitwerk (2.7.3)
+    yard (0.9.44)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-24

data/changelog.d/20260605_220911_anthropic_sleepy-allen.rst

@@ -0,0 +1,35 @@
+Added
+-----
+
+- Project-wide relationship introspection: ``Familia.index_descriptors``,
+  ``Familia.unique_indexes``, ``Familia.multi_indexes``, and
+  ``Familia.participation_descriptors`` aggregate index/participation metadata
+  across every loaded ``Horreum`` subclass, returning ``Familia::IndexDescriptor``
+  objects (``coordinate``, ``each_record``, ``rebuild!``, ``stale_format?``) that
+  act without the caller knowing index method-naming or storage layout.
+
+- Stale unique-index boot guard: ``Familia.stale_indexes`` and
+  ``Familia.assert_indexes_current!`` detect class-level unique indexes still
+  holding pre-2.10.0 JSON-encoded identifiers and fail fast (or warn) before an
+  un-rebuilt index silently breaks a ``find_by_*`` lookup. Rebuild them with
+  ``Familia.stale_indexes.each(&:rebuild!)``.
+
+- ``Familia.legacy_json_encoded?`` exposes the legacy-format predicate shared by
+  the read path (``strip_legacy_json_encoding``) and the introspection layer, so
+  detection and stripping never disagree.
+
+Documentation
+-------------
+
+- Documented the relationship introspection API — per-class
+  (``indexing_relationships``/``participation_relationships``), project-wide, and
+  per-instance — plus the stale-index boot guard, across the relationships guide
+  and methods reference. Renamed ``docs/migrating/v2.10.0.md`` to
+  ``docs/migrating/v2.10.md`` and noted that the introspection helpers require
+  2.10.1+.
+
+AI Assistance
+-------------
+
+- The introspection helpers, the stale-index boot guard, their tryouts, and the
+  accompanying documentation were drafted with AI assistance.

data/docs/guides/datatype-collections.md

@@ -73,7 +73,7 @@ flowchart TD
   ER --> Validate{"pipeline <= batch_size?"}
   Validate -- no --> Raise["raise ArgumentError"]
   Validate -- yes --> CallEach["each(**filters) do |member|"]
-  CallEach --> Extract["id = member.is_a?(Array) ? member.first : member"]
+  CallEach --> Extract["id = member.is_a?(Array) ? member.last : member"]
   Extract --> Buffer["buffer << id"]
   Buffer --> Full{"buffer.size >= batch_size?"}
   Full -- no --> CallEach
@@ -114,13 +114,41 @@ SortedSet#each exhausted
 |---|---|---|
 | Yields | raw identifier (or `[field, value]` for `HashKey`) | loaded Horreum instance |
 | Redis ops per yield | 0 extra (already paged) | amortized `HGETALL` via `load_multi` batch |
-| Requires `reference: true` + `:class` | no | yes (raises `Familia::Problem` otherwise) |
+| Requires `record_class:` (or `class: + reference: true`) | no | yes (raises `Familia::Problem` otherwise) |
 | Ghost handling | yields the dangling id | `compact` drops them silently |
 | Write pipelining | not built-in | `pipeline:` groups block-body writes into `pipelined` blocks |
 | Filters | type-specific (`since:`, `matching:`, …) | forwarded to underlying `each` |
 
 So `each_record` is a thin orchestration layer: it leans on the type's own `each` for read pagination, then layers (1) batched record hydration and (2) optional write pipelining on top.
 
+### Which collections support `each_record`?
+
+`each_record` needs to know which class to hydrate. Two options supply it, and
+the collections Familia generates for you already set one, so `each_record`
+works on them out of the box:
+
+- `ModelClass.instances` — the per-class timeline. Uses `class: + reference: true`.
+- `unique_index` / `multi_index` lookups — the index hashkey/set points at the indexed class. Uses `class: + reference: true`.
+- `participates_in` / `class_participates_in` collections — point at the participant class. Use `record_class:`.
+
+The two options differ in scope:
+
+- **`record_class: SomeClass`** — a *loading-only* hint. It enables `each_record`
+  but does **not** change how the collection serializes/deserializes reads
+  (`members`/`member?`/`score` keep the generic DataType semantics). Use this when
+  you want `each_record` without any read-behavior change. This is what
+  `participates_in` uses.
+- **`class: SomeClass, reference: true`** — a full *reference type*. It enables
+  `each_record` **and** makes reads return raw-string identifiers (and `member?`
+  match raw strings). Use this when you also want raw-string read semantics. This
+  is what `instances` and the indexes use.
+
+A collection you declare by hand (`sorted_set :foo`, `set :bar`, …) sets neither,
+so calling `each_record` on it raises `Familia::Problem`. Add `record_class:` (or
+`class: + reference: true`) to opt in. Note that if you pre-declare a collection
+that `participates_in` would otherwise auto-create, your hand-declared options
+win — add `record_class:` yourself if you want `each_record` on it.
+
 ## Choosing a `pipeline` mode
 
 `each_record` has two dispatch modes, controlled by `pipeline:`. The parameter answers a single question: **may the dispatch loop wrap your block in a `pipelined { }`?**

data/docs/guides/feature-migrations.md

@@ -0,0 +1,45 @@
+# Migrations
+
+Redis has no DDL, so Familia migrations operate on live data — renaming keys, reshaping hash fields, backfilling values, adjusting TTLs. The migration system provides idempotent execution, dry-run support, dependency ordering, and a Redis-backed registry that tracks what has run.
+
+## Architecture
+
+```
+Base ← Model    (SCAN + per-record callback)
+     ← Pipeline (SCAN + batched Redis pipelining)
+```
+
+**Base** gives you raw `redis` access for key-level operations. **Model** iterates Horreum objects through `process_record(obj, key)`. **Pipeline** adds `should_process?` / `build_update_fields` for bulk HSET-style updates through Redis pipelines.
+
+All three share the same lifecycle: `prepare` → `migration_needed?` → `migrate` (or `process_record` / pipeline dispatch) → optional `down` for rollback.
+
+## Registry
+
+Applied state lives in Redis, not in files or a relational table:
+
+| Key | Type | Content |
+|-----|------|---------|
+| `{prefix}:applied` | Sorted Set | migration_id scored by timestamp |
+| `{prefix}:metadata` | Hash | migration_id → JSON (duration, keys scanned/modified, reversibility) |
+| `{prefix}:schema` | Hash | model_name → SHA256 digest of fields+types |
+| `{prefix}:backup:{id}` | Hash (TTL) | field-level rollback data |
+
+Default prefix: `familia:migrations`. The registry answers `applied?`, `pending`, `status`, `schema_changed?`, and `schema_drift` queries.
+
+## Execution model
+
+`Runner` resolves dependencies via topological sort (Kahn's algorithm), then runs pending migrations in order. Each migration is instantiated, prepared, checked with `migration_needed?`, and executed. The registry is updated only on non-dry-run success.
+
+Rollback validates three preconditions: the migration is applied, no dependents are applied, and the migration implements `down`.
+
+## Dry-run control
+
+`for_realsies_this_time? { ... }` gates destructive operations. In dry-run mode the block is skipped and the registry is not updated. `dry_run_only? { ... }` provides the inverse gate for preview-only logging.
+
+## Lua scripts
+
+`Familia::Migration::Script` provides atomic Redis operations for common migration patterns: `rename_field`, `copy_field`, `delete_field`, `rename_key_preserve_ttl`, `backup_and_modify_field`. Custom scripts can be registered and executed through the same interface.
+
+## Source files
+
+`lib/familia/migration.rb` and `lib/familia/migration/`. Each file's first line states its purpose.

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

@@ -409,9 +409,12 @@ Index values (the object identifiers stored in hash keys and sets) are raw strin
 ### Debugging
 
 ```ruby
-# Check configuration
+# Check configuration — returns Array<IndexingRelationship> (Data objects),
+# distinguished by .cardinality (:unique vs :multi)
 User.indexing_relationships
-# => [{ field: :email, index_name: :email_lookup, ... }]
+# => [#<data IndexingRelationship field=:email, index_name=:email_lookup,
+#            cardinality=:unique, within=nil, ...>]
+User.indexing_relationships.select { |r| r.cardinality == :unique }
 
 # Inspect index contents
 User.email_lookup.to_h
@@ -419,8 +422,13 @@ User.email_lookup.to_h
 
 # Verify membership
 employee.in_company_badge_index?(company)  # => true/false
+user.indexed_in?(:email_lookup)            # => true/false (class-level indexes)
 ```
 
+For the full introspection API — the `IndexingRelationship` fields, a
+project-wide sweep over `Familia.members`, per-instance membership state, and
+the audit/repair layer — see [Introspection](feature-relationships.md#introspection).
+
 ## See Also
 
 - [**Relationships Overview**](feature-relationships.md) - Core concepts

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

@@ -228,6 +228,9 @@ domain.customer_count      # => 2
 customer.domains.size      # Count
 customer.domains.to_a      # All IDs
 customer.domains.range(0, 9)  # First 10
+
+# Iterate as loaded records (batched via load_multi, ghosts filtered)
+customer.domains.each_record { |domain| domain.refresh! }
 ```
 
 ### Working with Indexes
@@ -251,6 +254,44 @@ employee.add_to_company_dept_index(company)
 engineers = company.find_all_by_department('engineering')
 ```
 
+## Introspection Methods
+
+Unlike the methods above, these are always present on any class with
+`feature :relationships` (and its instances) — they are not generated per
+declaration. They report *what is declared* and *what an object currently
+belongs to*.
+
+### Class-Level (configuration)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `indexing_relationships` | `Array<IndexingRelationship>` | All `unique_index` / `multi_index` declarations; `.cardinality` distinguishes `:unique` from `:multi` |
+| `participation_relationships` | `Array<ParticipationRelationship>` | All `participates_in` / `class_participates_in` declarations |
+
+### Instance-Level (current state)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `current_indexings` | `Array<Hash>` | Indexes this object currently appears in |
+| `indexed_in?(:index_name)` | Boolean | Whether the object is in the named class-level index |
+| `current_participations` | `Array<Hash>` | Participation collections this object belongs to |
+| `relationship_status` | Hash | `{ identifier:, current_participations:, index_memberships: }` |
+
+### Project-Wide (every class)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `Familia.index_descriptors(cardinality:, class_level:, owner:)` | `Array<IndexDescriptor>` | Every index across the clan, filterable |
+| `Familia.unique_indexes` / `Familia.multi_indexes` | `Array<IndexDescriptor>` | Cardinality-filtered convenience helpers |
+| `Familia.participation_descriptors(owner:)` | `Array<[Class, ParticipationRelationship]>` | Every participation, paired with its owner |
+| `Familia.stale_indexes(sample:, owner:)` | `Array<IndexDescriptor>` | Class-level unique indexes holding pre-2.10.0 data |
+| `Familia.assert_indexes_current!(on_stale:, owner:)` | Boolean | Boot guard: raise/warn if any index is stale |
+
+Each `IndexDescriptor` exposes the relationship metadata plus `coordinate`,
+`each_record(value:, scope:)`, `rebuild!(scope:)`, and `stale_format?`. For the
+full breakdown and the audit/repair layer, see
+[Introspection](feature-relationships.md#introspection).
+
 ## See Also
 
 - [**Relationships Overview**](feature-relationships.md) - Core concepts and patterns

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

@@ -297,6 +297,42 @@ customer.domains.merge([id1, id2])  # Bulk ID operations
 domain.customer_instances           # Efficient bulk loading
 ```
 
+### Iterating a Collection as Loaded Records
+
+Participation collections carry a `record_class:` pointing at the participant
+class, so you can iterate them with `each_record` — it batches the stored
+identifiers through `load_multi` (pipelined `HGETALL`s), drops ghosts
+(identifiers whose record has expired), and yields fully-loaded records.
+(`record_class:` is a loading-only hint; it does not change how `members`,
+`member?`, or `score` behave.)
+
+```ruby
+# Yields loaded Domain records, not raw identifiers
+customer.domains.each_record { |domain| domain.refresh_dns! }
+
+# Enumerator form composes with Enumerable
+customer.domains.each_record.map(&:created_at)
+
+# Filters forward to the underlying each (sorted sets accept since:/until:)
+customer.domains.each_record(since: 1.day.ago) { |d| notify(d) }
+
+# Class-level participation collections work too
+User.all_users.each_record(pipeline: 50) { |u| u.last_seen_at! Familia.now }
+```
+
+This replaces the manual `load_multi` + `compact` workaround:
+
+```ruby
+# Before — manual batch load
+Domain.load_multi(customer.domains.to_a).compact.each { |d| ... }
+
+# After — each_record does the batching, ghost-filtering, and loading
+customer.domains.each_record { |d| ... }
+```
+
+See [DataType Collections](datatype-collections.md) for the full `each` vs
+`each_record` comparison and `pipeline:` tuning.
+
 ## Troubleshooting
 
 ### Common Issues
@@ -319,9 +355,10 @@ domain.customer_instances           # Efficient bulk loading
 ### Debugging
 
 ```ruby
-# Check configuration
+# Check configuration — returns Array<ParticipationRelationship> (Data objects)
 Domain.participation_relationships
-# => [{ target_class: Customer, collection_name: :domains, ... }]
+# => [#<data ParticipationRelationship target_class=Customer,
+#            collection_name=:domains, type=:sorted_set, ...>]
 
 # Inspect participations
 domain.current_participations
@@ -330,6 +367,10 @@ domain.current_participations
 domain.validate_relationships!
 ```
 
+For the full introspection API — per-class metadata, a project-wide sweep over
+`Familia.members`, per-instance membership state, and the audit/repair layer —
+see [Introspection](feature-relationships.md#introspection).
+
 ## See Also
 
 - [**Relationships Overview**](feature-relationships.md) - Core concepts