familia 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5577963e36f6c5ce2ce1fc977458c092b6883430e1c6c3e4c72742ddb4cae795
-  data.tar.gz: bc958eef278b236f894652b4954e7235a917c858f26e8c63427b1fb7bb62713a
+  metadata.gz: 7b0138946cb9d48258b9f43b8a8a81aa895bfded213543feee354b3d383dd98a
+  data.tar.gz: bd5b6ee397c2ef19cef85fe7638ead34b5ed40a81c8362f539ed757d0d713ca2
 SHA512:
-  metadata.gz: 2820cc6134dd2a707a8e7c91855c42b622807748cc428984bb725f71faada7489ed5211ac3dedbe887132e13523cd4e8c565abeaf57c7d9df411566fb60766ed
-  data.tar.gz: 1bc50c330c90ac7edcb460c7f8688d8e47d8329e2770a36b8963e24ea00cb258ee017f2c7ec905a2f19b38949ea609f381a9d65d0460711cc725c26b9f664053
+  metadata.gz: 8108ee045d1f4f1bdc722a1b56a6518a32edebd18ae028dfdcd793a62044cc8bea509e06d8399179c11b1eeef971dd980d1bcd18654cd3a375af99b641c514a6
+  data.tar.gz: 395bcb27503bb30734d0d6e16fa8e95b33fa072dfaca56c2b9b06d33859c4cb915f766923a492cbdaae5407e45db2c76ee074a6c6d7aac245b822332f44d082c

data/CHANGELOG.rst

@@ -7,6 +7,40 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.7.0:
+
+2.7.0 — 2026-05-13
+==================
+
+Added
+-----
+
+- New ``housekeeping`` feature for ``Familia::Horreum``: a declarative DSL
+  (``chore :name do |obj| ... end``) for registering named cleanup blocks on
+  a model class, plus an instance method ``tidy!`` that runs all (or one)
+  registered chore against a single object. The feature owns registration
+  and per-instance execution only -- iteration, batching, scheduling and
+  error aggregation are the consumer application's responsibility, keeping
+  it distinct from ``Familia::Migration`` (which is for versioned, one-shot
+  transformations). Resolves #258.
+
+Documentation
+-------------
+
+- Added ``docs/guides/feature-housekeeping.md`` covering the API, the
+  ``housekeeping`` vs ``migration`` vs defensive-setter trade-off,
+  generated method reference, design constraints, and common patterns
+  (multiple chores, sequential steps in one chore, tracking modified
+  records, error aggregation).
+
+AI Assistance
+-------------
+
+- Drafted the housekeeping feature module, the tryouts test suite, and the
+  guide using Claude Code, working from the API proposal in issue #258 and
+  the existing ``feature-relationships.md`` and ``safe_dump.rb`` as style
+  templates.
+
 .. _changelog-2.6.0:
 
 2.6.0 — 2026-04-17

data/Gemfile.lock

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

data/changelog.d/20260514_034522_claude_review_familia_issue_217.rst

@@ -0,0 +1,46 @@
+Added
+~~~~~
+
+- Instance-scoped ``audit_multi_indexes`` is now fully implemented.
+  Discovers per-scope bucket keys via SCAN, partitions them by scope
+  instance, and reports stale members, orphaned buckets, and missing
+  entries in the same shape as the class-level audit. Orphan entries
+  carry a ``:reason`` (``:scope_missing`` or ``:field_value_unheld``)
+  and a ``:scope_id``. Missing entries are detected via the indexed
+  class's ``participates_in`` relationship to the scope class; when
+  absent, the result carries ``missing_status: :not_audited``.
+  Resolves the ``:not_implemented`` follow-up from #217.
+
+- ``repair_multi_indexes!`` class method that invokes the existing
+  ``rebuild_<index_name>`` methods for both class-level (one call on
+  the indexed class) and instance-scoped (one call per scope
+  instance) multi-indexes. Indexes whose audit status is ``:ok`` are
+  skipped; rebuild methods that don't exist or scope classes
+  without an ``instances`` collection are recorded in ``:skipped``
+  with a reason.
+
+Changed
+~~~~~~~
+
+- ``repair_all!`` now runs each repair stage inside its own rescue
+  boundary; a failure in one dimension no longer prevents the others
+  from running. The return hash gains ``:status`` (``:ok`` or
+  ``:partial_failure``), ``:errors`` (per-stage exception details
+  when raised), and ``:multi_indexes`` (results from the new
+  ``repair_multi_indexes!``). An opt-in ``verify: true`` kwarg
+  re-runs ``health_check`` after repair and exposes the result as
+  ``:post_audit`` / ``:verified`` so callers can confirm the run
+  actually drove the model back to a healthy state.
+
+- ``AuditReport#complete?`` is no longer false-positive due to
+  ``:not_implemented`` stubs in ``multi_indexes`` -- instance-scoped
+  indexes return ``:ok`` or ``:issues_found`` like class-level ones.
+
+AI Assistance
+~~~~~~~~~~~~~
+
+- Instance-scoped multi-index audit algorithm (bucket discovery,
+  scope existence batching, participation-driven missing detection),
+  ``repair_multi_indexes!``, the ``repair_all!`` robustness
+  refactor, and the accompanying tryouts coverage were authored
+  with Claude Code assistance against the #217 review branch.

data/docs/guides/feature-housekeeping.md

@@ -0,0 +1,217 @@
+# Housekeeping Feature Guide
+
+The Housekeeping feature provides a declarative DSL for registering named cleanup chores on Horreum models. It is designed for short-lived, repeated tidying against fields whose values have drifted over time -- not for versioned, one-shot migrations.
+
+> [!TIP]
+> Enable with `feature :housekeeping` and register cleanup blocks with `chore :name do |obj| ... end`. Run them with `obj.tidy!`. Iteration and persistence are the caller's responsibility.
+
+## Quick Start
+
+```ruby
+class Organization < Familia::Horreum
+  feature :housekeeping
+
+  field :planid
+
+  chore :standardize_planid do |org|
+    canonical = case org.planid
+                when "pro", "Pro", "professional_v1" then "professional"
+                when "free", "Free", "basic"         then "free"
+                end
+    if canonical && canonical != org.planid
+      org.planid = canonical
+      org.save
+      true
+    end
+  end
+end
+
+org = Organization.from_identifier("acme-corp")
+org.tidy!
+# => { standardize_planid: true }
+```
+
+## When to Use
+
+| Tool | Use When |
+|------|----------|
+| `Familia::Migration::Base` | Versioned, one-shot transformation tracked across releases |
+| `feature :housekeeping` | Short-lived chore run nightly until data is clean, then removed |
+| Defensive code in setters | Permanent invariant enforced on every write |
+
+Housekeeping fills the gap between migrations (heavy, tracked) and inline coercion (permanent). Register a chore, run it on a schedule for a few days, verify clean data, then delete the chore and the defensive code that handled the messy values.
+
+## Core Capabilities
+
+### Registration -- Class-Level DSL
+
+Each chore is a named block bound to the model class:
+
+```ruby
+class User < Familia::Horreum
+  feature :housekeeping
+
+  field :email, :timezone
+
+  chore :downcase_email do |user|
+    next unless user.email && user.email != user.email.downcase
+    user.email = user.email.downcase
+    user.save
+    true
+  end
+
+  chore :default_timezone do |user|
+    next if user.timezone
+    user.timezone = "UTC"
+    user.save
+    true
+  end
+end
+
+User.chores.keys
+# => [:downcase_email, :default_timezone]
+```
+
+### Execution -- Single Instance
+
+Run all registered chores, or one by name:
+
+```ruby
+user = User.from_identifier("alice@example.com")
+
+user.tidy!
+# => { downcase_email: true, default_timezone: nil }
+
+user.tidy!(:downcase_email)
+# => { downcase_email: true }
+```
+
+The return value is a hash mapping chore name to the block's return value. A truthy result signals "modified"; `nil` or `false` signals "no-op". The feature does not interpret these values -- they are passed through for the caller's stats collection.
+
+### Iteration -- Caller's Responsibility
+
+The feature operates on a single instance. Bulk runs live in the consumer app:
+
+```ruby
+# nightly rake task
+namespace :data do
+  task tidy_orgs: :environment do
+    stats = Hash.new(0)
+    Organization.instances.each do |id|
+      org = Organization.find_by_id(id) or next
+      results = org.tidy!
+      results.each { |name, result| stats[name] += 1 if result }
+    end
+    puts stats.inspect
+  end
+end
+```
+
+The feature has no opinion about batching, SCAN vs KEYS, error aggregation, or scheduling -- the consumer app owns all of that.
+
+## Generated Method Reference
+
+### When a class declares `feature :housekeeping`
+
+| Class | Method | Purpose |
+|-------|--------|---------|
+| **Class** | `chore(name, &block)` | Register a chore |
+| | `chores` | Hash of registered chores |
+| **Instance** | `tidy!(name = nil)` | Run all (or one) chore; returns Hash |
+
+## Design Constraints
+
+1. **No implicit saves.** The block must call `save` (or `commit_fields`) itself. The feature does not auto-persist.
+2. **No iteration.** Operates on a single instance. There is no class-level `tidy_all!`.
+3. **No ordering.** Chores run in registration order, but should not depend on each other. If order matters, write one chore with sequential steps.
+4. **Idempotent by convention.** Use the conditional pattern (`if canonical && canonical != org.planid`) so a second run is a no-op.
+5. **Errors propagate.** The block can raise; the iteration code in the consumer app decides whether to rescue.
+
+## Common Patterns
+
+### Multiple Independent Chores
+
+```ruby
+class Customer < Familia::Horreum
+  feature :housekeeping
+
+  chore :trim_whitespace do |c|
+    next unless c.name && c.name != c.name.strip
+    c.name = c.name.strip
+    c.save
+    true
+  end
+
+  chore :uppercase_country do |c|
+    next unless c.country && c.country != c.country.upcase
+    c.country = c.country.upcase
+    c.save
+    true
+  end
+end
+
+customer.tidy!
+# => { trim_whitespace: true, uppercase_country: nil }
+```
+
+### Sequential Steps in One Chore
+
+When step B depends on step A's result, keep them in one block:
+
+```ruby
+chore :reconcile_billing do |account|
+  changed = false
+  if account.plan_id == "legacy"
+    account.plan_id = "standard"
+    changed = true
+  end
+  if account.plan_id == "standard" && account.billing_cycle.nil?
+    account.billing_cycle = "monthly"
+    changed = true
+  end
+  if changed
+    account.save
+    true
+  end
+end
+```
+
+### Tracking Modified Records
+
+```ruby
+modified = []
+Organization.instances.each do |id|
+  org = Organization.find_by_id(id) or next
+  results = org.tidy!
+  modified << id if results.values.any?
+end
+puts "Modified #{modified.size} records: #{modified.inspect}"
+```
+
+### Error Aggregation
+
+```ruby
+errors = {}
+Organization.instances.each do |id|
+  org = Organization.find_by_id(id) or next
+  begin
+    org.tidy!
+  rescue => e
+    errors[id] = e.message
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep chores short-lived.** Delete the registration once data is clean.
+2. **Use `||=` and conditional checks** so a second run is a no-op.
+3. **Save inside the block** -- the feature does not persist for you.
+4. **Return truthy on modification, nil on no-op** so callers can collect stats.
+5. **Prefer migrations for one-shot, versioned transformations.** Use housekeeping for ongoing tidying that can be run repeatedly.
+
+## See Also
+
+- [**Writing Migrations**](writing-migrations.md) - Versioned, one-shot data transformations
+- [**Field System**](field-system.md) - How field values are stored and serialized
+- [**Feature System**](feature-system.md) - How features are mixed into Horreum classes

data/docs/guides/index.md

@@ -37,9 +37,13 @@ Welcome to the comprehensive documentation for Familia v2.0. This guide collecti
 13. **[Quantization](feature-quantization.md)** - Time-based data bucketing for analytics
 14. **[Time Literals](time-literals.md)** - Time manipulation and formatting utilities
 
+### 🧹 Data Maintenance
+
+15. **[Housekeeping](feature-housekeeping.md)** - Declarative cleanup chores for drifted field values
+
 ### 🛠️ Implementation & Usage
 
-15. **[Optimized Loading](optimized-loading.md)** - Reduce Redis commands by 50-96% for bulk object loading _(new!)_
+16. **[Optimized Loading](optimized-loading.md)** - Reduce Redis commands by 50-96% for bulk object loading _(new!)_
 
 
 ## 🚀 Quick Start Examples

data/lib/familia/features/housekeeping.rb

@@ -0,0 +1,101 @@
+# lib/familia/features/housekeeping.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    # Housekeeping registers named cleanup chores on a Horreum class and runs
+    # them against a single instance. It is intended for short-lived, repeated
+    # tidying of fields whose values have drifted (e.g. running nightly for a
+    # few days, then removing the chore once data is clean).
+    #
+    # The feature owns registration and per-instance execution only. Iteration,
+    # batching, scheduling, error aggregation, and persistence are the caller's
+    # responsibility.
+    #
+    # Example:
+    #
+    #   class Organization < Familia::Horreum
+    #     feature :housekeeping
+    #     field :planid
+    #
+    #     chore :standardize_planid do |org|
+    #       canonical = case org.planid
+    #                   when 'pro', 'Pro', 'professional_v1' then 'professional'
+    #                   when 'free', 'Free', 'basic'         then 'free'
+    #                   end
+    #       if canonical && canonical != org.planid
+    #         org.planid = canonical
+    #         org.save
+    #         true
+    #       end
+    #     end
+    #   end
+    #
+    #   org = Organization.from_identifier('acme-corp')
+    #   org.tidy!
+    #   # => { standardize_planid: true }
+    #
+    #   org.tidy!(:standardize_planid)
+    #   # => { standardize_planid: true }
+    #
+    # See docs/guides/feature-housekeeping.md for the full guide.
+    module Housekeeping
+      Familia::Base.add_feature self, :housekeeping
+
+      def self.included(base)
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
+      end
+
+      # Housekeeping::ModelClassMethods
+      module ModelClassMethods
+        # Register a chore by name. The block receives the instance.
+        #
+        # @param name [Symbol, String] chore identifier
+        # @yield [obj] block invoked with the instance during tidy!
+        # @return [Proc] the registered block
+        # @raise [ArgumentError] if name is blank or no block is given
+        def chore(name, &block)
+          raise ArgumentError, 'chore name required' if name.nil? || name.to_s.empty?
+          raise ArgumentError, "chore #{name.inspect} requires a block" unless block
+
+          chores[name.to_sym] = block
+        end
+
+        # Registered chores in registration order. Subclasses inherit a copy
+        # of their parent's chores on first access, so registering a new chore
+        # on a subclass does not mutate the parent.
+        #
+        # @return [Hash{Symbol => Proc}]
+        def chores
+          @chores ||= if superclass.respond_to?(:chores)
+                        superclass.chores.dup
+                      else
+                        {}
+                      end
+        end
+      end
+
+      # Run all registered chores, or one chore by name.
+      #
+      # @param name [Symbol, String, nil] chore to run; nil runs all
+      # @return [Hash{Symbol => Object}] chore name => block return value
+      # @raise [ArgumentError] if name is given but not registered
+      def tidy!(name = nil)
+        registered = self.class.chores
+
+        if name
+          key = name.to_sym
+          raise ArgumentError, "unknown chore #{name.inspect}" unless registered.key?(key)
+
+          { key => registered[key].call(self) }
+        else
+          registered.each_with_object({}) do |(chore_name, block), results|
+            results[chore_name] = block.call(self)
+          end
+        end
+      end
+    end
+  end
+end