recordables 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0cb9bc821c580bd8f8f9e0e321ad0433b6905b98420ebacc0c2b960556017a
-  data.tar.gz: 9dc7a3de73258300b9b09ab6ab68c8ce3e8909e120e5e0480c7038cea52bc2c6
+  metadata.gz: 7355a9bfb7d1440a8b7746b13b4fa810304eb837c97d8dc850011d12091241b6
+  data.tar.gz: 4f13296e03d0467244273af7f96566d21129d48013ec3279d2967236806181a5
 SHA512:
-  metadata.gz: bd212dc151fbc5013e6f5f76d72da3eaadaedd955d97aa0c34572bc6f323dc309dbcacbc2aa6ce8d9888efdeec14bf9e45b7f19635206eab5c036e08936aa0ab
-  data.tar.gz: 71de19f67e01f321d3c86d20368bcf04462af941cbc5472333cfa6f3768ecafc878ec4ace7a281fed1ad04825e452f485d55d03481f58ee2cb25cf3507f130a4
+  metadata.gz: 8053edc2e2c5cfa59c71c19658f2faba977bbc29e48b933d6eccd3086a548bb5d76ebcb6a0f65e8e8468f60694587a9c47b76ce2ee8c47a286f3fb631318868b
+  data.tar.gz: 504f8827f44890f43442e17f3af80874feb8dcdd88685f362e7e6bd78a00266e2e7710c387ad331480bc67e741facffdc897d97b9bc66eba13749f80b306fcab

data/CHANGELOG.md

@@ -6,6 +6,57 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+### Added
+
+- `trashable` — `default_scope` + `with_trashed` for a recordable type whose Recording
+  can be trashed, so a trashed row stops showing up in normal queries. Paired with
+  `Recording.active` and `Recording#trash!`.
+- `recordable_belongs_to` — a `belongs_to` replacement for a target that's `trashable`.
+  Plain `belongs_to` builds its own `WHERE id = ...` directly against the target class,
+  bypassing `trashable`'s `default_scope` entirely, and silently returns a stale,
+  superseded row instead of the current one. Resolves through the append-only Event log
+  instead, which always names the current version.
+- `immutable` — raises if `update`, `update!`, `update_column(s)`, `save` (with pending
+  changes), `destroy`, `delete`, or class-level `update_all` are called directly against
+  a persisted recordable, instead of silently mutating a row that's supposed to be an
+  immutable snapshot. `record`/`revise` are unaffected — they only ever save a fresh,
+  not-yet-persisted instance.
+- `has_children` — the child-Recording pattern (a Task under its Routine) as two
+  generated methods per name: a read-only, ordered listing and an `add_*` that creates
+  the child with its own Recording, parented to the current one.
+- `nested_recordable_attributes_for` — the `accepts_nested_attributes_for` shape for a
+  `has_children` association, since the real thing can't work here (it writes straight
+  to association rows at `assign_attributes` time; a child needs a Recording, which
+  needs the parent to be saved/revised first). Two-phase: `#{plural}_attributes=` stores
+  the submitted rows, `apply_#{plural}_attributes!` creates/revises/trashes them once
+  the parent has a current Recording.
+- `repoint_on_revise` — for a real `has_many` pointed at a recordable type by a plain
+  foreign key (not a child Recording): repoints every row at the new id `revise()`
+  creates, in the same transaction, instead of leaving them FK'd to what just became
+  obsolete. Also defines `copy_content_to` as a no-op, since these associations were
+  never content to copy forward in the first place.
+- `Recordables::Testing#current_recordable` — the fix for the most common test mistake
+  this gem's pattern invites: `#reload` on a recordable after an action that revised it
+  re-fetches by the object's own, now-superseded primary key, silently returning what
+  the row looked like *before*. Capture the Recording first, resolve through it after.
+- `recordables:backfill` generator — scaffolds the migration for adopting
+  `recordable`/`trashable` on a table that already has rows. Exists because of one
+  specific trap: once a model has `trashable`, a bare `Model.find_each` inside the very
+  migration meant to create that model's first Recordings iterates zero rows — every
+  row is invisible under a scope that hides anything without an active Recording yet,
+  which at backfill time is all of them. `Model.with_trashed.find_each` fixes it, but
+  the migration "succeeds" having touched nothing if it's missing, and nothing about
+  that looks wrong until much later.
+- `Recordable#recording` — the current Recording pointing at a snapshot
+  (`recordings.last`). Previously left for every consumer to define for themselves.
+- `delete_all` / `destroy_all` on a `trashable` type now raise instead of silently only
+  clearing rows with an active Recording — the ambiguity that trips up a test teardown's
+  `delete_all`, a `DatabaseCleaner` truncation strategy, or a rake task clearing a table,
+  all expecting the table to end up actually empty. `with_trashed.delete_all` (or scoping
+  down first, e.g. `Model.where(...).delete_all`) says which is meant.
+
+## [0.1.0]
+
 ### Fixed
 
 - `revise` silently discarded edits to rich text: changes were merged into the column

data/README.md

@@ -114,11 +114,187 @@ than the snapshot, so revising content never touches them.
 |---|---|
 | Migrations, `Recording`, `Event`, `Bucket`, the concerns, each content type | **Generated into your app.** You own and edit these; the gem never touches them again |
 | `records` / `recordable` macros, `revise`, `revert_to`, `versions`, `recordable_at`, `copy_content_to` and its guard | **Kept in the gem** |
+| `trashable`, `recordable_belongs_to`, `immutable`, `has_children`, `repoint_on_revise`, `nested_recordable_attributes_for`, `Recordables::Testing` | **Kept in the gem** — all opt-in, none of it changes behavior for a model that doesn't call it |
 
 The rule: **generate what's opinionated, keep what fails silently.** Permissions, controllers
 and tree semantics are deliberately yours — that is why the generated files are plain Rails
 you can rewrite freely.
 
+## Trashing, and the belongs_to trap
+
+`recordable` alone doesn't give you soft-delete — a "trashed" Recording still leaves its
+row visible to every plain query, since `trash!` only changes the *Recording's* status,
+nothing about the row itself. `trashable` closes that gap:
+
+```ruby
+class Article < ApplicationRecord
+  recordable
+  trashable
+end
+
+article.recording.trash!(actor: current_user)
+
+Article.count            # doesn't see it
+Article.with_trashed.count  # does
+```
+
+The one thing this doesn't fix by itself is `belongs_to`. Rails' association reader builds
+its own `WHERE id = ...` directly against the target class, bypassing `trashable`'s
+`default_scope` entirely — so a plain `belongs_to :article` on some other model silently
+returns the stale, trashed-or-superseded row instead of nil or the current version. This is
+the sharpest edge in the whole pattern, and it fails silently: nothing raises, the wrong data
+just quietly comes back. `recordable_belongs_to` is the fix:
+
+```ruby
+class Comment < ApplicationRecord
+  recordable_belongs_to :article
+end
+```
+
+It resolves through the append-only `Event` log instead of the raw foreign key — an event's
+`recordable_id` is set once, when that event happened, and never rewritten, so it still names
+the right lineage no matter how many times the target's been revised since.
+
+## Enforcing immutability
+
+Nothing about `recordable` stops a `template.update!(name: "x")` from working even after
+you've adopted `revise()` everywhere else — it just silently mutates the row in place. No new
+snapshot, no history entry, no way to revert, and anything reading `cache_version` or
+`updated_at` through the Recording never sees the change. `immutable` turns that into a hard
+failure instead of a silent one:
+
+```ruby
+class Article < ApplicationRecord
+  recordable
+  immutable
+end
+
+article.update!(title: "x")   # raises Recordables::ImmutableRecordable
+article.update_column(:title, "x")  # raises too — callbacks alone don't catch this
+Article.update_all(title: "x")      # raises at the class level
+```
+
+`record`/`revise` are unaffected — they only ever save a fresh, not-yet-persisted instance,
+never a second write against a row that's already there.
+
+## Children: a real has_many, or a child Recording?
+
+Two different shapes both look like "this recordable owns other rows," and mixing them up
+either loses data or silently orphans it.
+
+**A child Recording** (`has_children`) is for content that's genuinely part of the parent's
+lineage — a `Task` under its `Routine`, a line item under an order. A plain foreign key would
+orphan every child the moment the parent is revised (a new row, a new id) — the fix is
+letting the *child's own Recording* carry the parent link instead, via `parent_id`, which
+survives revisions because a Recording's own id never changes:
+
+```ruby
+class Routine < ApplicationRecord
+  recordable
+  has_children :tasks
+end
+
+routine.tasks                              # current children, ordered
+routine.add_task(actor: current_user, name: "Stretch")
+```
+
+**A real `has_many`** (`repoint_on_revise`) is for join rows that point *at* a recordable by a
+plain foreign key, and need to follow a revision rather than travel with the child-Recording
+tree — a tagging table, an assignment. `revise()` alone would leave every one of those rows
+FK'd to the old, now-superseded id. `repoint_on_revise` moves them to the new one in the same
+transaction, and also defines `copy_content_to` as a no-op — these associations were never
+content to *copy forward*, they're pointers *at* the row, so the default
+`UncopyableAssociation` guard doesn't apply here:
+
+```ruby
+class RoutineTemplate < ApplicationRecord
+  recordable
+  repoint_on_revise :routine_template_people
+end
+```
+
+If in doubt: does the association exist to organize the recordable's own content (child
+Recording), or does something external point at it (repoint_on_revise)?
+
+## Nested forms
+
+`accepts_nested_attributes_for` can't work on a `has_children` association — it writes
+straight to association rows at `assign_attributes` time, but a new child needs its own
+Recording, which needs the parent to already be saved or revised. `nested_recordable_attributes_for`
+does the same job (a form posts an array of `{id:, ...fields, _destroy:}` hashes) through
+`revise()`/`trash!` instead of a raw write:
+
+```ruby
+class Routine < ApplicationRecord
+  recordable
+  has_children :tasks
+  nested_recordable_attributes_for :tasks
+end
+```
+
+```erb
+<%= form_with model: @routine do |f| %>
+  <%= f.fields_for :tasks, @routine.tasks_for_form do |task_fields| %>
+    ...
+  <% end %>
+<% end %>
+```
+
+Two-phase, matching how a controller/interactor already has to split "assign" from "save"
+here: `tasks_attributes=` stores the submitted rows without writing anything, then
+`apply_tasks_attributes!(actor:)` — called once the routine itself has a current Recording —
+creates, revises, or trashes each one.
+
+## Testing
+
+The most common mistake this whole pattern invites: calling `#reload` on a recordable after
+an action that revised it.
+
+```ruby
+task = create_a_task
+complete_the_task(task)
+task.reload.status   # => "initial", not "complete"
+```
+
+`revise()` gives an edit a brand new row — a new primary key — and repoints the Recording at
+it. `task` still holds the *old* primary key, so `#reload` re-fetches by that key: not an
+error, not nil, just exactly the row the action was supposed to replace. A test asserting on
+`task` after the action silently checks what things looked like *before*.
+
+```ruby
+class ActiveSupport::TestCase
+  include Recordables::Testing
+end
+```
+
+```ruby
+recording = task.recording      # capture before — a Recording's id never changes
+complete_the_task(task)
+assert_equal "complete", current_recordable(recording).status
+```
+
+## Adopting recordable on an existing table
+
+Once a model has `trashable`, its `default_scope` hides any row with no active
+Recording — which, the moment you first add `trashable`, is every existing row. The
+migration that's supposed to create each row's first Recording has to bypass that scope to
+see them at all:
+
+```bash
+bin/rails generate recordables:backfill RoutineTemplate
+```
+
+```ruby
+# generated: db/migrate/..._backfill_routine_templates_recordings.rb
+RoutineTemplate.with_trashed.find_each do |routine_template|
+  Recording.record(routine_template, actor: routine_template.actor, created_at: routine_template.created_at)
+end
+```
+
+Miss `.with_trashed` here — plain `find_each` — and the migration doesn't error. It "succeeds"
+in milliseconds, having created zero Recordings, and nothing about that looks wrong until
+something downstream (a query, a destroy cascade) turns up rows with no history at all.
+
 ## Caveats
 
 - Never put a `uniqueness` validation on a recordable. Old snapshots still hold the old
@@ -128,6 +304,12 @@ you can rewrite freely.
 - `events.details` is a `json` column. Ruby 4 ships json 3.x, whose `JSON.parse` moved to
   keyword arguments while ActiveSupport 8.1 still calls it positionally. Pin
   `gem "json", "~> 2.7"` until that is fixed upstream.
+- On a `trashable` type, `Model.delete_all` / `Model.destroy_all` raise rather than run.
+  Under `default_scope` they'd only ever touch rows with an active Recording — anything
+  already trashed survives, silently — which is exactly backwards from what a test
+  teardown's `delete_all` or a `DatabaseCleaner` truncation strategy expects. Call
+  `Model.with_trashed.delete_all` if you mean it, or scope down first
+  (`Model.where(...).delete_all`) if you meant only some of the active rows.
 
 ## Development
 

data/lib/generators/recordables/backfill/backfill_generator.rb

@@ -0,0 +1,55 @@
+require "rails/generators"
+require "rails/generators/active_record"
+require "recordables/generator_helpers"
+
+module Recordables
+  module Generators
+    # Scaffolds the migration for adopting recordable/trashable on a table
+    # that already has rows: create the first Recording (and "created"
+    # Event) for each one.
+    #
+    #   bin/rails generate recordables:backfill RoutineTemplate
+    #
+    # Exists because of one specific, easy-to-miss trap: once a model has
+    # trashable's default_scope, `Model.find_each` inside the very
+    # migration meant to create that model's first Recordings iterates
+    # zero rows — every row is invisible under a scope that hides anything
+    # without an active Recording yet, which at backfill time is all of
+    # them. The fix (`Model.with_trashed.find_each`) is one word, but
+    # silent when missing: the migration "succeeds" in milliseconds having
+    # touched nothing, and nothing about that looks wrong until much later.
+    class BackfillGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+      include Recordables::GeneratorHelpers
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a migration that backfills the first Recording for every existing row of a type."
+
+      class_option :creator, type: :string, default: nil,
+                             desc: "Attribute on the row holding who created it, e.g. person_id"
+      class_option :account, type: :string, default: nil,
+                             desc: "Attribute on the row holding its account/tenant, e.g. account_id"
+
+      def validate!
+        validate_name!
+      end
+
+      def create_backfill_migration
+        migration_template "backfill_migration.rb.tt", "db/migrate/backfill_#{table_name}_recordings.rb"
+      end
+
+      private
+
+        def generator_example = "bin/rails generate recordables:backfill RoutineTemplate"
+
+        def creator_expression
+          options[:creator].presence || "actor"
+        end
+
+        def account_expression
+          options[:account].presence || "account"
+        end
+    end
+  end
+end

data/lib/generators/recordables/backfill/templates/backfill_migration.rb.tt

@@ -0,0 +1,35 @@
+class Backfill<%= class_name.pluralize %>Recordings < ActiveRecord::Migration<%= migration_version %>
+  def up
+    <%= class_name %>.reset_column_information
+
+    say_with_time "Creating a Recording for every existing <%= file_name %>" do
+      count = 0
+
+      # trashable's default_scope hides any row with no active Recording —
+      # exactly every row this backfill is about to create the first one
+      # for. Without with_trashed this silently iterates zero rows: the
+      # migration "succeeds" in milliseconds having touched nothing, which
+      # is easy to miss since nothing about it raises or looks wrong.
+      <%= class_name %>.with_trashed.find_each do |<%= file_name %>|
+        Recording.record(
+          <%= file_name %>,
+          actor: <%= file_name %>.<%= creator_expression %>,
+<% if account_expression != "nil" -%>
+          account: <%= file_name %>.<%= account_expression %>,
+<% end -%>
+          created_at: <%= file_name %>.created_at
+        )
+        count += 1
+      end
+
+      "#{count} <%= table_name %>"
+    end
+  end
+
+  def down
+    Recording.where(recordable_type: "<%= class_name %>").with_trashed.find_each do |recording|
+      recording.events.delete_all
+      recording.delete
+    end
+  end
+end

data/lib/generators/recordables/install/templates/recording.rb.tt

@@ -1,8 +1,6 @@
 class Recording < ApplicationRecord
   records :recordable, types: Recordable::TYPES, inverse_of: :recordings
 
-  enum :status, { active: 0, archived: 1, trashed: 2 }
-
 <% if buckets? -%>
   belongs_to :bucket
 <% end -%>

data/lib/recordables/has_children.rb

@@ -0,0 +1,60 @@
+require "active_support/concern"
+
+module Recordables
+  # Opt-in alongside `recordable` for a type whose Recording parents other
+  # Recordings — a Task under its Routine, a TaskTemplate under its
+  # RoutineTemplate. Not a real has_many: a child's own Recording carries
+  # the parent link (parent_id), not a foreign key on the child row itself
+  # — a plain FK would silently orphan every child the moment its parent
+  # is revised, since revise() replaces the parent row with a new id.
+  #
+  #   class RoutineTemplate < ApplicationRecord
+  #     recordable
+  #     has_children :task_templates, class_name: "TaskTemplate"
+  #   end
+  #
+  # Defines two methods per name:
+  #
+  #   template.task_templates
+  #     # => current children, ordered
+  #   template.add_task_template(actor:, recording: {}, **attrs)
+  #     # => Recording.record(TaskTemplate.new(attrs), actor:, parent:, **recording)
+  #
+  # Read-heavy chaining (.count, .where, .order, .each, .find, ...) works
+  # the same as a real has_many. Building/creating a child goes through
+  # add_* instead — "create a child" is a recording operation (it needs
+  # its own Recording, parented to this one), not a plain attribute
+  # assignment a bare .build could do.
+  #
+  # attrs become the child model's own attributes; recording: carries
+  # anything that belongs on the Recording itself instead (account:,
+  # bucket:, or any other extra column the host app's Recording has) —
+  # kept as an explicit, separate argument rather than guessed at by
+  # inspecting attrs, since a model attribute happening to share a name
+  # with a Recording column would otherwise route to the wrong place
+  # silently.
+  module HasChildren
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def __recordables_define_children(plural_name, class_name: nil)
+        singular_name = plural_name.to_s.singularize
+        target_class_name = class_name&.to_s || plural_name.to_s.classify
+
+        define_method(plural_name) do
+          target = target_class_name.constantize
+          return target.none unless recording
+
+          target.joins(:recordings).merge(::Recording.active.where(parent_id: recording.id))
+                .order("recordings.position")
+        end
+
+        define_method(:"add_#{singular_name}") do |actor: nil, recording: {}, **attrs|
+          target = target_class_name.constantize
+
+          ::Recording.record(target.new(attrs), actor: actor, parent: self.recording, **recording)
+        end
+      end
+    end
+  end
+end

data/lib/recordables/immutable.rb

@@ -0,0 +1,66 @@
+require "active_support/concern"
+
+module Recordables
+  # Raised by a write attempted directly against a persisted immutable
+  # recordable — see Immutable for why, and what to call instead.
+  class ImmutableRecordable < StandardError; end
+
+  # Opt-in alongside `recordable` for a type that should never be updated
+  # in place after it's first saved — only revise() (a new row) or trash!
+  # (on its Recording) should ever change what a caller sees.
+  #
+  #   class RoutineTemplate < ApplicationRecord
+  #     recordable
+  #     immutable
+  #   end
+  #
+  # Nothing in Rails stops a plain `template.update!(name: "x")` from
+  # working even after adopting the revise() pattern — it just silently
+  # mutates the row in place instead of raising or inserting a new one.
+  # The row still looks "current" to every reader, but no new Recording
+  # snapshot was created: no history entry, no way to revert, and any
+  # cache_version or updated_at logic that reads through the Recording
+  # never sees the change. That's exactly the failure this gem exists to
+  # prevent, and nothing about #recordable on its own stops it.
+  #
+  # Only guards persisted rows: the record/revise flow itself calls
+  # `.new(...).save!` on a fresh, not-yet-persisted instance, which is
+  # the one write path this is not meant to catch.
+  module Immutable
+    extend ActiveSupport::Concern
+
+    included do
+      before_update { raise_immutable!(:update) }
+      before_destroy { raise_immutable!(:destroy) }
+    end
+
+    # update_column/update_columns/delete bypass callbacks entirely (that's
+    # their whole point), so before_update/before_destroy above never see
+    # them — each needs its own override to still be caught.
+    def update_column(...) = raise_immutable!(:update_column)
+    def update_columns(...) = raise_immutable!(:update_columns)
+    def delete = raise_immutable!(:delete)
+
+    class_methods do
+      def update_all(...)
+        raise Recordables::ImmutableRecordable, <<~MESSAGE.squish
+          #{name}.update_all writes directly to the row instead of calling
+          revise() on each recordable's Recording — no new snapshot, no
+          history entry, nothing to revert to. Loop and call
+          recording.revise(actor:, **changes) per row instead.
+        MESSAGE
+      end
+    end
+
+    private
+
+      def raise_immutable!(verb)
+        raise Recordables::ImmutableRecordable, <<~MESSAGE.squish
+          #{self.class.name}##{verb} was called directly on a persisted
+          recordable — #{verb == :destroy ? "trash! its Recording" : "call revise(actor:, **changes) on its Recording"}
+          instead, so the change goes through the versioning this gem
+          exists to provide.
+        MESSAGE
+      end
+  end
+end

data/lib/recordables/macros.rb

@@ -22,5 +22,113 @@ module Recordables
     def recordable
       include Recordables::Recordable
     end
+
+    # Adds default_scope + with_trashed to a recordable type, so a trashed
+    # Recording's row stops showing up in normal queries. See
+    # Recordables::Trashable for the mechanics.
+    #
+    #   class RoutineTemplate < ApplicationRecord
+    #     recordable
+    #     trashable
+    #   end
+    def trashable
+      include Recordables::Trashable
+    end
+
+    # Raises if anything tries to write directly to a persisted recordable
+    # row instead of going through revise()/trash! on its Recording. See
+    # Recordables::Immutable for the mechanics.
+    #
+    #   class RoutineTemplate < ApplicationRecord
+    #     recordable
+    #     immutable
+    #   end
+    def immutable
+      include Recordables::Immutable
+    end
+
+    # Repoints real has_many associations (plain FK, not a child Recording)
+    # at each new row a revision creates, instead of leaving them pointed
+    # at what revise() just made obsolete. See Recordables::RepointOnRevise
+    # for the mechanics.
+    #
+    #   class RoutineTemplate < ApplicationRecord
+    #     recordable
+    #     repoint_on_revise :routine_template_people
+    #   end
+    def repoint_on_revise(*association_names)
+      include Recordables::RepointOnRevise
+      self.repointed_association_names = association_names
+    end
+
+    # A recordable type whose Recording parents other Recordings — a Task
+    # under its Routine. See Recordables::HasChildren for the mechanics.
+    #
+    #   class RoutineTemplate < ApplicationRecord
+    #     recordable
+    #     has_children :task_templates
+    #   end
+    def has_children(plural_name, class_name: nil)
+      include Recordables::HasChildren
+      __recordables_define_children(plural_name, class_name: class_name)
+    end
+
+    # The accepts_nested_attributes_for shape for a has_children
+    # association — a fields_for form editing a recordable parent's
+    # children. See Recordables::NestedRecordableAttributes for the
+    # mechanics. Requires has_children for the same name first.
+    #
+    #   class RoutineTemplate < ApplicationRecord
+    #     recordable
+    #     has_children :task_templates, class_name: "TaskTemplate"
+    #     nested_recordable_attributes_for :task_templates, class_name: "TaskTemplate"
+    #   end
+    def nested_recordable_attributes_for(plural_name, class_name: nil)
+      include Recordables::NestedRecordableAttributes
+      target_class_name = class_name&.to_s || plural_name.to_s.classify
+      __recordables_define_nested_attributes(plural_name, class_name: target_class_name)
+    end
+
+    # A belongs_to whose target is trashable, resolved through the append-only
+    # Event log instead of the raw foreign key.
+    #
+    # Rails' belongs_to association reader builds its own `WHERE id = ...`
+    # query directly against the target class — bypassing trashable's
+    # default_scope entirely, since that scope is added to the class's own
+    # query interface, not baked into every possible query Rails might build
+    # against it. A plain belongs_to therefore silently returns the stale,
+    # trashed-or-superseded row instead of nil once the target's been revised
+    # or trashed — exactly the case this exists to handle.
+    #
+    # An Event's recordable_id is set once, at the moment that event
+    # happened, and never rewritten — so the "created" event for a given
+    # target id still names that id no matter how many times the target's
+    # been revised since. That event's Recording is the stable pointer for
+    # the whole lineage, so walking through it reaches whatever version is
+    # current right now: the original row if it still is, or the latest
+    # revision if the original has since been revised or trashed.
+    #
+    #   class Routine < ApplicationRecord
+    #     recordable_belongs_to :routine_template
+    #   end
+    #
+    # Accepts the same options as belongs_to (class_name, foreign_key,
+    # optional, etc) and still defines the plain association under the hood
+    # — for eager loading, FK validation, forms — only the reader method is
+    # overridden.
+    def recordable_belongs_to(name, class_name: nil, foreign_key: nil, **options)
+      belongs_to name, class_name: class_name, foreign_key: foreign_key, **options
+
+      target_class_name = class_name&.to_s || name.to_s.camelize
+      fk = foreign_key&.to_s || "#{name}_id"
+
+      define_method(name) do
+        id = public_send(fk)
+        next nil if id.blank?
+
+        ::Event.where(recordable_type: target_class_name, recordable_id: id)
+               .first&.recording&.recordable
+      end
+    end
   end
 end

data/lib/recordables/nested_recordable_attributes.rb

@@ -0,0 +1,100 @@
+require "active_support/concern"
+
+module Recordables
+  # Opt-in alongside `has_children` for the accepts_nested_attributes_for
+  # shape (a form with fields_for) on a recordable parent's children.
+  #
+  #   class RoutineTemplate < ApplicationRecord
+  #     recordable
+  #     has_children :task_templates, class_name: "TaskTemplate"
+  #     nested_recordable_attributes_for :task_templates, class_name: "TaskTemplate"
+  #   end
+  #
+  # accepts_nested_attributes_for can't work here: it writes at
+  # assign_attributes time, straight to a real association's rows — but
+  # task_templates isn't a real has_many (see HasChildren), and a child
+  # needs its own Recording the moment it's created, which a plain
+  # attribute assignment can't set up. This does the same job (a form
+  # posts an array of {id:, ...fields, _destroy:} hashes; existing rows
+  # get updated or trashed, new ones get created) through revise()/trash!
+  # instead of a raw write.
+  #
+  # Two-phase, same as accepts_nested_attributes_for from the caller's
+  # side but not under the hood: fields_for-style form submission first
+  # calls #{plural}_attributes= (stores the raw rows, writes nothing yet),
+  # then the interactor/controller explicitly calls
+  # apply_#{plural}_attributes! once the parent itself is saved/revised —
+  # a new child needs a *current* Recording to parent under, which only
+  # exists after that.
+  module NestedRecordableAttributes
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def __recordables_define_nested_attributes(plural_name, class_name:)
+        singular_name = plural_name.to_s.singularize
+        target_class_name = class_name.to_s
+        pending_ivar = :"@pending_#{plural_name}_attributes"
+        rendered_ivar = :"@rendered_#{plural_name}"
+
+        attr_reader :"pending_#{plural_name}_attributes"
+
+        define_method(:"#{plural_name}_attributes=") do |attributes|
+          instance_variable_set(pending_ivar, attributes.is_a?(Hash) ? attributes.values : attributes)
+        end
+
+        # Blank row for an "add" button in the form — mirrors what
+        # `children.build` would do on a real has_many. In-memory only.
+        define_method(:"build_#{singular_name}") do
+          send(:"rendered_#{plural_name}") << target_class_name.constantize.new
+        end
+
+        # What the form actually iterates via fields_for: the just-submitted
+        # rows if the form was just posted (so a validation error re-renders
+        # what the user typed, the same as accepts_nested_attributes_for
+        # would), otherwise the persisted children.
+        define_method(:"rendered_#{plural_name}") do
+          instance_variable_get(rendered_ivar) || instance_variable_set(rendered_ivar, begin
+            pending = instance_variable_get(pending_ivar)
+
+            if pending
+              pending.filter_map do |attrs|
+                attrs = attrs.to_h.symbolize_keys
+                next if ActiveModel::Type::Boolean.new.cast(attrs[:_destroy])
+
+                target_class_name.constantize.new(attrs.except(:id, :_destroy))
+              end
+            else
+              public_send(plural_name).to_a
+            end
+          end)
+        end
+
+        define_method(:"apply_#{plural_name}_attributes!") do |actor: nil|
+          pending = instance_variable_get(pending_ivar)
+          next unless pending
+
+          current_by_id = public_send(plural_name).index_by { |child| child.id.to_s }
+
+          pending.each do |attrs|
+            attrs = attrs.to_h.symbolize_keys
+            id = attrs[:id].presence
+            destroy = ActiveModel::Type::Boolean.new.cast(attrs[:_destroy])
+            changes = attrs.except(:id, :_destroy)
+
+            if id && (child = current_by_id[id.to_s])
+              if destroy
+                child.recording.trash!(actor: actor)
+              else
+                child.recording.revise(actor: actor, **changes)
+              end
+            elsif !destroy && changes.present?
+              public_send(:"add_#{singular_name}", actor: actor, **changes)
+            end
+          end
+
+          instance_variable_set(pending_ivar, nil)
+        end
+      end
+    end
+  end
+end

data/lib/recordables/recordable.rb

@@ -17,6 +17,14 @@ module Recordables
     def publishable? = false
     def nestable? = false
 
+    # The one Recording currently pointing at this snapshot. A row can end
+    # up with more than one recordings row over its lifetime only in the
+    # sense that revise()/revert_to repoint a Recording between many rows
+    # — but at any moment, exactly one Recording points at this specific
+    # row (or, once it's been superseded, none). .last is a reasonable
+    # proxy for "the current one" without a dedicated column to query.
+    def recording = recordings.last
+
     def summary = model_name.human
 
     def revisable_attributes = attributes.except("id", "created_at")

data/lib/recordables/recording.rb

@@ -6,6 +6,14 @@ module Recordables
 
     VERSION_ACTIONS = %w[created updated reverted].freeze
 
+    included do
+      # The install generator's migration creates the status column
+      # (integer, default 0, not null) but doesn't declare the enum itself
+      # — active/trash! need this exact mapping to exist, so it lives here
+      # rather than being left for every consumer to redeclare correctly.
+      enum :status, { active: 0, archived: 1, trashed: 2 }
+    end
+
     class_methods do
       def record(recordable, actor:, parent: nil, **attributes)
         transaction do
@@ -15,6 +23,12 @@ module Recordables
           recording
         end
       end
+
+      # Every other scope on this table should build on this one rather than
+      # querying status directly — trashable's default_scope depends on
+      # filtering through exactly this relation so a model swap here (e.g.
+      # adding a soft-delete concern upstream) only has one place to change.
+      def active = where(status: :active)
     end
 
     def revise(actor:, **changes)
@@ -44,5 +58,16 @@ module Recordables
     def log!(action, snapshot, actor:, details: {})
       events.create!(recordable: snapshot, actor: actor, action: action, details: details)
     end
+
+    # "Deleting" a recordable never removes a row — it marks this pointer
+    # trashed and logs the transition, the same way revise/revert_to never
+    # delete either. A trashed Recording keeps recordable/versions/events
+    # working exactly as before; only .active-scoped lookups stop seeing it.
+    def trash!(actor: nil)
+      transaction do
+        update!(status: :trashed)
+        log!("trashed", recordable, actor: actor)
+      end
+    end
   end
 end

data/lib/recordables/repoint_on_revise.rb

@@ -0,0 +1,58 @@
+require "active_support/concern"
+
+module Recordables
+  # Opt-in alongside `recordable` for a type that owns real has_many
+  # associations pointed at it by a plain foreign key (not a child
+  # Recording) — join rows that need to follow a revision, not vanish
+  # when the row they FK to gets replaced.
+  #
+  #   class RoutineTemplate < ApplicationRecord
+  #     recordable
+  #     trashable
+  #     repoint_on_revise :routine_template_people, :goal_routine_templates
+  #   end
+  #
+  # Two problems, one macro:
+  #
+  # 1. #copy_content_to's default UncopyableAssociation guard exists to
+  #    stop a real association from silently vanishing off a new snapshot
+  #    — but these associations were never content to copy in the first
+  #    place, they're FK pointers *at* the row. Nothing to carry forward;
+  #    they need to be repointed instead. This overrides copy_content_to
+  #    to a no-op, same as hand-rolling `def copy_content_to(r) = r` would.
+  #
+  # 2. revise() alone leaves every one of those rows FK'd to the OLD,
+  #    now-superseded id — invisible to anything that reads the
+  #    association off the new row, and (worse) silently orphaned if that
+  #    old row is later trashed or garbage collected. This overrides
+  #    revise() to repoint each named association's foreign key at the new
+  #    row in the same transaction as the revision itself.
+  #
+  # update_all skips touch callbacks, so updated_at is bumped by hand —
+  # otherwise any fragment cache keyed on those rows (e.g. one that reads
+  # `join_row.routine_template.name`) would invalidate late.
+  module RepointOnRevise
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :repointed_association_names, default: []
+    end
+
+    def copy_content_to(revision) = revision
+
+    def revise(actor: nil, **changes)
+      transaction do
+        new_row = recording.revise(actor: actor, **changes)
+
+        self.class.repointed_association_names.each do |association_name|
+          reflection = self.class.reflect_on_association(association_name)
+          foreign_key = reflection.foreign_key
+
+          public_send(association_name).update_all(foreign_key => new_row.id, :updated_at => Time.current)
+        end
+
+        new_row
+      end
+    end
+  end
+end

data/lib/recordables/testing.rb

@@ -0,0 +1,30 @@
+module Recordables
+  # Include in a test base class to get current_recordable, the fix for the
+  # single most common test mistake this gem's pattern invites: calling
+  # `#reload` on a recordable after an action that revised it.
+  #
+  #   class ActiveSupport::TestCase
+  #     include Recordables::Testing
+  #   end
+  #
+  # revise() gives a change a brand new row — a new primary key — and
+  # repoints the Recording at it. The Ruby object still on hand still
+  # carries the OLD primary key, so `#reload` re-fetches by that key: not
+  # an error, not nil, just the exact row the action was supposed to
+  # replace. A test asserting on that object after the action reads
+  # whatever the row looked like BEFORE, and can pass while checking
+  # nothing about what actually happened.
+  #
+  # Capture the Recording before the action runs — its id is the one
+  # thing revise() never changes — then resolve through it afterward:
+  #
+  #   recording = task.recording
+  #   complete_the_task(task)
+  #   assert_equal "complete", current_recordable(recording).status
+  module Testing
+    def current_recordable(recording_or_id)
+      recording = recording_or_id.is_a?(::Recording) ? recording_or_id : ::Recording.find(recording_or_id)
+      recording.reload.recordable
+    end
+  end
+end

data/lib/recordables/trashable.rb

@@ -0,0 +1,79 @@
+require "active_support/concern"
+
+module Recordables
+  # Raised by delete_all/destroy_all on a trashable model — see Trashable
+  # for why those are ambiguous under a default_scope that hides trashed
+  # rows, and what to call instead.
+  class AmbiguousBulkDelete < StandardError; end
+
+  # Opt-in alongside `recordable` for a type whose Recording can be trashed.
+  # Without this, a trashed Recording's recordable row stays visible to every
+  # plain query — trash! only changes the Recording's own status, nothing
+  # about the row a bare Model.find or Model.where sees. This scopes normal
+  # queries down to rows with an active Recording, the same way a real DELETE
+  # would look to callers that never think about trashing at all.
+  #
+  #   class RoutineTemplate < ApplicationRecord
+  #     recordable
+  #     trashable
+  #   end
+  #
+  # Uses a subquery, not a join, so it composes safely everywhere — including
+  # inside Recording#recordable itself, which must still resolve a trashed
+  # row's own class via a plain Model.find under the hood.
+  module Trashable
+    extend ActiveSupport::Concern
+
+    included do
+      # ::Recording, not Recording — inside this module's lexical scope,
+      # plain `Recording` resolves to Recordables::Recording (the concern
+      # mixed into the host app's Recording class) rather than the host
+      # app's top-level Recording class itself.
+      default_scope {
+        where(primary_key => ::Recording.active.where(recordable_type: name).select(:recordable_id))
+      }
+    end
+
+    class_methods do
+      # Lifts the trashed-row filter only — unlike .unscoped, every other
+      # condition already built on the relation stays intact (an account's
+      # scoping association chain, an explicit .find(id), etc). Needed
+      # anywhere that has to see trashed rows on purpose: an admin trash-can
+      # view, a cascading destroy that has to clean up what it can still see,
+      # or a backfill migration creating the very first Recording a row will
+      # ever have (see the docs on that gotcha below).
+      def with_trashed
+        unscope(where: primary_key)
+      end
+
+      # A bare Model.delete_all/destroy_all under default_scope only ever
+      # touches rows with an active Recording — anything already trashed is
+      # invisible to it and survives untouched. That's silent and easy to
+      # mistake for "the table's empty now" (a test teardown's delete_all,
+      # a DatabaseCleaner truncation strategy, a rake task clearing a
+      # table) when it's actually only ever cleared the active subset.
+      # Raising forces the caller to say which they mean; scoping down
+      # first (e.g. Model.where(...).delete_all) still works exactly like
+      # any other ActiveRecord relation.
+      def delete_all(...)
+        raise Recordables::AmbiguousBulkDelete, <<~MESSAGE.squish
+          #{name}.delete_all only deletes rows with an active Recording —
+          anything already trashed stays behind, silently. Call
+          #{name}.with_trashed.delete_all if that's really what you want,
+          or scope down first (e.g. #{name}.where(...).delete_all) if you
+          meant only the active rows matching some condition.
+        MESSAGE
+      end
+
+      def destroy_all(...)
+        raise Recordables::AmbiguousBulkDelete, <<~MESSAGE.squish
+          #{name}.destroy_all only destroys rows with an active Recording —
+          anything already trashed stays behind, silently. Call
+          #{name}.with_trashed.destroy_all if that's really what you want,
+          or scope down first (e.g. #{name}.where(...).destroy_all) if you
+          meant only the active rows matching some condition.
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/recordables/version.rb

@@ -1,3 +1,3 @@
 module Recordables
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recordables
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jonas Medeiros
@@ -54,6 +54,8 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/recordables/backfill/backfill_generator.rb
+- lib/generators/recordables/backfill/templates/backfill_migration.rb.tt
 - lib/generators/recordables/bucket/bucket_generator.rb
 - lib/generators/recordables/bucket/templates/migration.rb.tt
 - lib/generators/recordables/bucket/templates/model.rb.tt
@@ -69,10 +71,16 @@ files:
 - lib/generators/recordables/type/type_generator.rb
 - lib/recordables.rb
 - lib/recordables/generator_helpers.rb
+- lib/recordables/has_children.rb
+- lib/recordables/immutable.rb
 - lib/recordables/macros.rb
+- lib/recordables/nested_recordable_attributes.rb
 - lib/recordables/railtie.rb
 - lib/recordables/recordable.rb
 - lib/recordables/recording.rb
+- lib/recordables/repoint_on_revise.rb
+- lib/recordables/testing.rb
+- lib/recordables/trashable.rb
 - lib/recordables/version.rb
 homepage: https://github.com/jonasmedeiros/recordables
 licenses: