recordables 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a183a373143cdec754a8704fb66131ddc8980930ebb3a6e16d7a42309bcdd1f
-  data.tar.gz: eb62d04c3f09067fa95221810da3cdcb4acdf704052ddd88059893735e7b521d
+  metadata.gz: 3cf0fb1698d5bf53e032be066ea8adb125b57cbcd5cd9363858f865e6eba13aa
+  data.tar.gz: 67cbad006b327319749fe63958f727550f347aa9728520e42538eddb491bdeb8
 SHA512:
-  metadata.gz: 33f79c5525fce7dc3cf40c345c77f38d99f7a511cafca9c7be1b5412b5177ca6dd3722346e7b3365ca7e2c71eb1fbc1d9c8c70ca03de34d6a78f0faacb3c2158
-  data.tar.gz: 60c51aa0167f1ac34132cab455cbace4275635f8be85157ac183f5394b26062e3e6506373c8fa7e9d59b6ec6b59bda517f5f1203fd14a8fada865b1e66a90eab
+  metadata.gz: 6280fcd221af39b67dfbc63b74164c2504b5ee5ffbcbc73bbc92396ce0abc66fff9736c724c356884f89bec440d629daea56c6547f0cd130f25983c0bd10a1e7
+  data.tar.gz: 76b116c32281d454c3f691a03f33b69ed562657600e6f2ea6c840426d5d4d33a837e07bc18f52af27a426c9da58de7424f302651ccb690ee2aef44dcfa767f1b

data/CHANGELOG.md

@@ -4,10 +4,34 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.2]
+
+### Removed
+
+- **`trashable`, `Recording#trash!`, `Recording.active`, `Recording#status`.** Soft-delete
+  never belonged in a versioning gem — it's a separate concern that got bundled in by
+  mistake. `Recording` no longer has a `status` column at all; a recordable type that wants
+  its own status (draft/published, say) should model it as a plain column on the recordable
+  itself, not on the Recording.
 
 ### Added
 
+- **`Recording#destroy!(actor:)`** — a real, hard delete. Removes the Recording and its
+  recordable row. Logs a final `"destroyed"` event first, against the recordable that's
+  about to disappear, so the log itself records what was removed and by whom. This is the
+  only removal path now; there is no more soft-delete state to fall back to.
+- **Events outlive their Recording.** Destroying a Recording nullifies `recording_id` on
+  its Events rather than cascading — the fact that something was created, edited, and later
+  destroyed stays part of the permanent log even once the content itself is gone. Needed
+  for real compliance/deletion flows (an account or organization being deleted for good),
+  where a soft-delete flag that keeps content sitting in the table forever isn't good enough.
+- **An event's actor survives the actor being deleted.** `actor_id` is nullified (not
+  cascaded) when the actor row is destroyed, and `actor_name` — a denormalized snapshot
+  taken when the event was logged — keeps the log legible afterward.
+  `event.actor_label` reads `actor&.<label> || actor_name`. The install generator now asks
+  `--actor-label` (default `name`) for which attribute to snapshot.
+- `recordable_belongs_to`, `Recording.creator`, and `Event.actor`/`Event.recording` are all
+  now optional at the association level, matching the nullify-on-delete behavior above.
 - `nested_recordable_attributes_for` accepts `recording_attributes:`, an optional proc
   called once per new child (with the parent record) to build extra attributes for that
   child's Recording. Without it, `apply_#{plural}_attributes!` creating a new child had
@@ -16,6 +40,22 @@ All notable changes to this project are documented here. The format follows
   the common case) hit a hard `NOT NULL` failure the moment a form actually submitted a
   new child row.
 
+### Changed
+
+- `has_children`'s children lookup no longer filters through `Recording.active` — with no
+  soft-delete state, a destroyed child is simply gone from the table, nothing to scope
+  around.
+- The `recordables:backfill` generator no longer needs (or generates) `.with_trashed` —
+  that trap only existed because of `trashable`'s `default_scope`, which is gone.
+
+**Breaking change**, despite the patch version number — pre-1.0 and the only consumer of this
+gem at the time of release is this repo's own author, so a 0.2.x bump was chosen deliberately
+over the stricter semver convention a minor bump would normally signal here. Existing apps
+using `trashable`/`trash!` need to migrate: replace `trash!` calls with `destroy!`, drop the
+`trashable` macro call, and add a migration to drop `recordings.status` (and add
+`events.actor_name`, make `events.recording_id`/`events.actor_id`/`recordings.creator_id`
+nullable with `ON DELETE SET NULL`, if adopting the new destroy/actor behavior).
+
 ## [0.2.0]
 
 ### Added

data/README.md

@@ -21,11 +21,37 @@ recording  ──points at──▶  recordable     the content (Article, Note,
                                           current when it happened
 ```
 
-- **`recordings`** — the spine. Foreign keys, status, position. No text columns, so it stays
-  cheap to index and paginate however large it grows.
+- **`recordings`** — the spine. Foreign keys and position only. No text columns, no status —
+  it stays cheap to index and paginate however large it grows, and never becomes a state
+  machine (see "What recordable is for" below).
 - **recordables** — the content. Immutable: an edit inserts a row, so none of them carry
   `updated_at`.
 - **`events`** — append-only, and the reason history and the activity feed are the same data.
+  Survives its Recording being destroyed — see "Destroying a recordable" below.
+
+## What recordable is for
+
+**Adopt it for content people draft and revise** — an article, a comment, a template someone
+edits over time and might want to compare or restore an earlier version of. That's genuinely
+what this gem is for, and the whole point of the three tables above.
+
+**Don't adopt it for workflow state.** A `Task` moving `initial → in_progress → completed`, an
+order moving `pending → shipped`, isn't content with a history worth version-browsing — it's a
+state machine, and a plain `status` enum column with an ordinary `update!` is the right tool.
+Modeling a status transition as `revise()` (a whole new row, a new id, every associated record
+needing to be repointed) buys none of what versioning is for and costs real complexity: every
+existing reference to the row goes stale the instant the status changes, `#reload` silently
+starts returning the pre-transition version (see Testing, below), and every join or `belongs_to`
+pointed at it needs its own repoint story.
+
+If a type doesn't need "what did this used to say" or "restore an earlier draft," it almost
+certainly doesn't need `recordable` — just a column.
+
+**Status belongs on the recordable, never on the Recording.** If a recordable type genuinely
+does need a status (a document that's `draft`/`published`, say), that's a plain column on the
+recordable's own table, alongside its other content — not something this gem tracks on
+`Recording` on the type's behalf. `Recording` only ever answers "what changed, when, and by
+whom" — it has no opinion on what any particular snapshot's content *means*.
 
 ## Getting started
 
@@ -113,37 +139,65 @@ than the snapshot, so revising content never touches them.
 | | Where it lives |
 |---|---|
 | 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 |
+| `records` / `recordable` macros, `revise`, `revert_to`, `destroy!`, `versions`, `recordable_at`, `copy_content_to` and its guard | **Kept in the gem** |
+| `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 |
+
+Soft-delete (a "trashed but still in the table" state) isn't something this gem provides —
+that's a separate concern from versioning, and conflating them was a mistake an earlier version
+of this gem made. If your app wants soft-delete, layer it on top of your own recordable
+type with your own scope; `recordable` won't fight you, and it won't manage that state for you
+either.
 
 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
+## Destroying a recordable
 
-`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:
+Deleting is a real, hard delete — not a status flip. `destroy!` on a Recording removes the
+Recording and its current recordable row:
 
 ```ruby
 class Article < ApplicationRecord
   recordable
-  trashable
 end
 
-article.recording.trash!(actor: current_user)
+article.recording.destroy!(actor: current_user)
 
-Article.count            # doesn't see it
-Article.with_trashed.count  # does
+Article.exists?(article.id)  # false — really gone
 ```
 
-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:
+What survives is the log: every `Event` this recordable ever produced (`created`, `updated`,
+`reverted`) stays in place, including a final `destroyed` event this call logs before removing
+anything. An event's `recording_id` is nullified rather than cascaded when its Recording goes
+away — the fact that an article was created, edited twice, and later deleted is itself part of
+the record this gem exists to keep, even once the content is gone. This matters for compliance
+flows too: deleting an account or an organization needs an actual purge path, not a soft-delete
+flag that keeps the content sitting in the table forever waiting for a "real" cleanup that
+never has to happen.
+
+The same applies to *who* did something. An event's `actor` can be deleted independently of any
+recordable it acted on — a person leaves the account, say. `actor_id` is nullified rather than
+left dangling, but the event still needs to read sensibly afterward, so a name is snapshotted
+onto the event the moment it's created:
+
+```ruby
+event.actor            # nil, once the actor row is gone
+event.actor_name        # "Jonas" — captured when the event happened, survives regardless
+event.actor_label       # actor&.name || actor_name — whichever is available right now
+```
+
+`recordables:install` asks which attribute to snapshot (`--actor-label`, defaults to `name`) —
+point it at whatever your actor's display name method is, e.g. `--actor-label=display_name`.
+
+The other durability edge is `belongs_to`. Rails' association reader builds its own
+`WHERE id = ...` directly against the target class using whatever id was assigned — but
+`revise()` repoints a Recording at a brand new row the moment content changes, so a plain
+`belongs_to :article` holding an id from before that silently returns the stale, superseded row
+(or nil, if it's since been destroyed) instead of the current one. This is the sharpest edge in
+the whole pattern, and it fails silently: nothing raises, the wrong data just quietly comes
+back. Never hold onto or compare a `recording_id` directly for this reason — always resolve
+through the recordable's own stable id. `recordable_belongs_to` is the fix:
 
 ```ruby
 class Comment < ApplicationRecord
@@ -175,7 +229,8 @@ 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.
+never a second write against a row that's already there. `destroy!` on the Recording is also
+unaffected — it's the sanctioned way to remove an immutable recordable's row.
 
 ## Children: a real has_many, or a child Recording?
 
@@ -222,7 +277,7 @@ Recording), or does something external point at it (repoint_on_revise)?
 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:
+`revise()`/`destroy!` instead of a raw write:
 
 ```ruby
 class Routine < ApplicationRecord
@@ -243,7 +298,7 @@ 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.
+creates, revises, or destroys each one.
 
 ## Testing
 
@@ -275,10 +330,8 @@ 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:
+Scaffolds the migration that creates each existing row's first Recording (and its `created`
+Event), backfilled from the row's own `created_at`:
 
 ```bash
 bin/rails generate recordables:backfill RoutineTemplate
@@ -286,15 +339,11 @@ bin/rails generate recordables:backfill RoutineTemplate
 
 ```ruby
 # generated: db/migrate/..._backfill_routine_templates_recordings.rb
-RoutineTemplate.with_trashed.find_each do |routine_template|
+RoutineTemplate.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
@@ -304,12 +353,10 @@ something downstream (a query, a destroy cascade) turns up rows with no history
 - `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.
+- `Model.delete_all` on a recordable type bypasses `destroy!`, so the Events it would have
+  logged never happen and any content-only associations it owns (rich text, attachments) can
+  be left behind. Prefer looping `recording.destroy!(actor:)` per row, or `destroy_all` if the
+  type has no other before_destroy concerns to skip.
 
 ## Development
 
@@ -319,7 +366,7 @@ bundle exec rake test
 ```
 
 The suite boots a small Rails application in `test/dummy`, so Action Text, Active Storage
-and the generators are exercised for real rather than stubbed. 41 tests cover the snapshot
+and the generators are exercised for real rather than stubbed. The suite covers the snapshot
 lifecycle, rich text and attachment copy-forward, blob sharing, the uncopyable-association
 guard, and all three generators.
 

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

@@ -4,20 +4,11 @@ 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.
+    # Scaffolds the migration for adopting recordable 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

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

@@ -5,12 +5,7 @@ class Backfill<%= class_name.pluralize %>Recordings < ActiveRecord::Migration<%=
     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 %>|
+      <%= class_name %>.find_each do |<%= file_name %>|
         Recording.record(
           <%= file_name %>,
           actor: <%= file_name %>.<%= creator_expression %>,
@@ -27,7 +22,7 @@ class Backfill<%= class_name.pluralize %>Recordings < ActiveRecord::Migration<%=
   end
 
   def down
-    Recording.where(recordable_type: "<%= class_name %>").with_trashed.find_each do |recording|
+    Recording.where(recordable_type: "<%= class_name %>").find_each do |recording|
       recording.events.delete_all
       recording.delete
     end

data/lib/generators/recordables/install/install_generator.rb

@@ -13,6 +13,8 @@ module Recordables
 
       class_option :actor, type: :string, default: "User",
                            desc: "Model that creates recordings and appears on events"
+      class_option :actor_label, type: :string, default: "name",
+                           desc: "Attribute on the actor to snapshot onto events, e.g. name or display_name"
       class_option :buckets, type: :boolean, default: true,
                             desc: "Generate Bucket, the container that owns recordings"
 
@@ -52,6 +54,8 @@ module Recordables
 
         def actor_table = actor_class.tableize
 
+        def actor_label = options[:actor_label]
+
         def migration_version = "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
     end
   end

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

@@ -14,9 +14,8 @@ class CreateRecordablesTables < ActiveRecord::Migration<%= migration_version %>
       t.references :bucket, null: false, foreign_key: true
 <% end -%>
       t.references :parent, foreign_key: { to_table: :recordings }
-      t.references :creator, null: false, foreign_key: { to_table: :<%= actor_table %> }
+      t.references :creator, foreign_key: { to_table: :<%= actor_table %>, on_delete: :nullify }
       t.references :recordable, polymorphic: true, null: false, index: false
-      t.integer :status, null: false, default: 0
       t.integer :position
       t.timestamps
 
@@ -28,9 +27,10 @@ class CreateRecordablesTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     create_table :events do |t|
-      t.references :recording, null: false, foreign_key: true
+      t.references :recording, foreign_key: { on_delete: :nullify }
       t.references :recordable, polymorphic: true, null: false, index: false
-      t.references :actor, null: false, foreign_key: { to_table: :<%= actor_table %> }
+      t.references :actor, foreign_key: { to_table: :<%= actor_table %>, on_delete: :nullify }
+      t.string :actor_name
       t.string :action, null: false
       t.json :details, null: false, default: {}
       t.datetime :created_at, null: false

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

@@ -1,8 +1,15 @@
 class Event < ApplicationRecord
-  belongs_to :recording
+  belongs_to :recording, optional: true
   belongs_to :recordable, polymorphic: true
-  belongs_to :actor, class_name: "<%= actor_class %>"
+  belongs_to :actor, class_name: "<%= actor_class %>", optional: true
+
+  before_create { self.actor_name ||= actor&.<%= actor_label %> }
 
   scope :newest_first, -> { order(created_at: :desc, id: :desc) }
   scope :of_type, ->(type) { where(recordable_type: type) }
+
+  # actor_name is a denormalized snapshot of actor.<%= actor_label %>, taken
+  # when the event was created — it stays legible even after the actor row
+  # itself is deleted, when actor_id is nullified to nil.
+  def actor_label = actor&.<%= actor_label %> || actor_name
 end

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

@@ -4,11 +4,11 @@ class Recording < ApplicationRecord
 <% if buckets? -%>
   belongs_to :bucket
 <% end -%>
-  belongs_to :creator, class_name: "<%= actor_class %>"
+  belongs_to :creator, class_name: "<%= actor_class %>", optional: true
   belongs_to :parent, class_name: "Recording", optional: true
 
   has_many :children, class_name: "Recording", foreign_key: :parent_id, dependent: :destroy
-  has_many :events, dependent: :destroy
+  has_many :events, dependent: :nullify
 
   delegate :commentable?, :publishable?, :nestable?, :summary, to: :recordable
 

data/lib/recordables/has_children.rb

@@ -45,7 +45,7 @@ module Recordables
           target = target_class_name.constantize
           return target.none unless recording
 
-          target.joins(:recordings).merge(::Recording.active.where(parent_id: recording.id))
+          target.joins(:recordings).merge(::Recording.where(parent_id: recording.id))
                 .order("recordings.position")
         end
 

data/lib/recordables/immutable.rb

@@ -6,7 +6,7 @@ module Recordables
   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!
+  # in place after it's first saved — only revise() (a new row) or destroy!
   # (on its Recording) should ever change what a caller sees.
   #
   #   class RoutineTemplate < ApplicationRecord
@@ -31,7 +31,7 @@ module Recordables
 
     included do
       before_update { raise_immutable!(:update) }
-      before_destroy { raise_immutable!(:destroy) }
+      before_destroy { raise_immutable!(:destroy) unless Recordables::Recording.destroying_recordable? }
     end
 
     # update_column/update_columns/delete bypass callbacks entirely (that's
@@ -57,7 +57,7 @@ module Recordables
       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"}
+          recordable — #{verb == :destroy ? "destroy! its Recording" : "call revise(actor:, **changes) on its Recording"}
           instead, so the change goes through the versioning this gem
           exists to provide.
         MESSAGE

data/lib/recordables/macros.rb

@@ -23,20 +23,8 @@ module Recordables
       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
+    # row instead of going through revise()/destroy! on its Recording. See
     # Recordables::Immutable for the mechanics.
     #
     #   class RoutineTemplate < ApplicationRecord
@@ -94,16 +82,17 @@ module Recordables
       __recordables_define_nested_attributes(plural_name, class_name: target_class_name, recording_attributes: recording_attributes)
     end
 
-    # A belongs_to whose target is trashable, resolved through the append-only
+    # A belongs_to whose target is recordable, 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.
+    # query directly against the target class — but revise() repoints a
+    # Recording at a brand new row id, so a plain belongs_to holding the id
+    # from whenever it was assigned silently returns the stale, superseded
+    # row (or nil, if that row's since been destroyed) instead of the
+    # current one. Never store or compare a recording_id directly for this
+    # reason — always resolve through the recordable's own stable id, the
+    # way this does.
     #
     # An Event's recordable_id is set once, at the moment that event
     # happened, and never rewritten — so the "created" event for a given
@@ -111,7 +100,7 @@ module Recordables
     # 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.
+    # revision if the original has since been revised.
     #
     #   class Routine < ApplicationRecord
     #     recordable_belongs_to :routine_template

data/lib/recordables/nested_recordable_attributes.rb

@@ -24,7 +24,7 @@ module Recordables
   # 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!
+  # get updated or destroyed, new ones get created) through revise()/destroy!
   # instead of a raw write.
   #
   # Two-phase, same as accepts_nested_attributes_for from the caller's
@@ -91,7 +91,7 @@ module Recordables
 
             if id && (child = current_by_id[id.to_s])
               if destroy
-                child.recording.trash!(actor: actor)
+                child.recording.destroy!(actor: actor)
               else
                 child.recording.revise(actor: actor, **changes)
               end

data/lib/recordables/recording.rb

@@ -6,13 +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
+    # Set only around #destroy!'s own recordable.destroy! call below, so
+    # Immutable's before_destroy guard can tell "the gem's own sanctioned
+    # destroy path" apart from a caller destroying a recordable directly —
+    # the same distinction record/revise draw by only ever calling
+    # .new(...).save! and never touching an existing row's update!. Module
+    # level (not per-host-Recording-class) since Immutable is mixed into
+    # the recordable, which has no reference to the Recording class itself.
+    def self.destroying_recordable? = Thread.current[:recordables_destroying_recordable] || false
 
     class_methods do
       def record(recordable, actor:, parent: nil, **attributes)
@@ -23,12 +24,6 @@ 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)
@@ -59,14 +54,23 @@ module Recordables
       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)
+    # A real delete: removes this Recording and its recordable row. Events
+    # are never touched here — recording_id is nullified (see the install
+    # migration's foreign_key on_delete: :nullify), not cascaded, so the
+    # log this recordable ever happened stays intact after the content
+    # itself is gone. Logs a final "destroyed" event first, against the
+    # recordable that's about to disappear, so the log itself says what was
+    # removed and by whom.
+    def destroy!(actor: nil)
       transaction do
-        update!(status: :trashed)
-        log!("trashed", recordable, actor: actor)
+        log!("destroyed", recordable, actor: actor)
+        begin
+          Thread.current[:recordables_destroying_recordable] = true
+          recordable.destroy!
+        ensure
+          Thread.current[:recordables_destroying_recordable] = false
+        end
+        super()
       end
     end
   end

data/lib/recordables/repoint_on_revise.rb

@@ -8,7 +8,6 @@ module Recordables
   #
   #   class RoutineTemplate < ApplicationRecord
   #     recordable
-  #     trashable
   #     repoint_on_revise :routine_template_people, :goal_routine_templates
   #   end
   #

data/lib/recordables/version.rb

@@ -1,3 +1,3 @@
 module Recordables
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recordables
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Jonas Medeiros
@@ -80,7 +80,6 @@ files:
 - 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:

data/lib/recordables/trashable.rb

@@ -1,79 +0,0 @@
-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