recordables 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c0cb9bc821c580bd8f8f9e0e321ad0433b6905b98420ebacc0c2b960556017a
+  data.tar.gz: 9dc7a3de73258300b9b09ab6ab68c8ce3e8909e120e5e0480c7038cea52bc2c6
+SHA512:
+  metadata.gz: bd212dc151fbc5013e6f5f76d72da3eaadaedd955d97aa0c34572bc6f323dc309dbcacbc2aa6ce8d9888efdeec14bf9e45b7f19635206eab5c036e08936aa0ab
+  data.tar.gz: 71de19f67e01f321d3c86d20368bcf04462af941cbc5472333cfa6f3768ecafc878ec4ace7a281fed1ad04825e452f485d55d03481f58ee2cb25cf3507f130a4

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+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]
+
+### Fixed
+
+- `revise` silently discarded edits to rich text: changes were merged into the column
+  attributes before `copy_content_to` ran, so the copy overwrote them with the previous
+  body. Changes are now applied after the copy and always win.
+- `recordables:install --actor` accepted any string, generating models with a broken
+  `class_name:` reference (e.g. `--actor="bad name"`) that only failed at runtime, far
+  from the mistake. It now validates the same way `recordables:type` and
+  `recordables:bucket` already did.
+
+### Added
+
+- `records` and `recordable` class macros on `ActiveRecord::Base`.
+- `recordables:install` generator — migration, `Recording`, `Event`, the `Recordable`
+  concern, and optionally `Bucket` / `Bucketable` (`--skip-buckets` to omit).
+- `recordables:type` generator — an immutable content type, registered in `Recordable::TYPES`.
+- `recordables:bucket` generator — a container type, registered in `Bucketable::TYPES`.
+- `revise`, `revert_to`, `versions`, `recordable_at` for snapshot versioning and history.
+- `copy_content_to` carries ActionText rich text and Active Storage attachments onto a new
+  snapshot, discovered by reflection rather than per-type configuration.
+- `Recordables::Recordable::UncopyableAssociation` — raised instead of silently dropping
+  ordinary `has_many` / `has_one` associations a snapshot cannot carry.
+- A dummy Rails application under `test/dummy`, so the suite exercises Action Text,
+  Active Storage and the generators against a real Rails environment.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jonas Medeiros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# recordables
+
+[![Gem Version](https://badge.fury.io/rb/recordables.svg)](https://rubygems.org/gems/recordables)
+[![CI](https://github.com/jonasmedeiros/recordables/actions/workflows/ci.yml/badge.svg)](https://github.com/jonasmedeiros/recordables/actions/workflows/ci.yml)
+
+Versioned, immutable content for Rails. Every edit writes a new snapshot instead of
+overwriting a row, so document history, "restore this version", and a single activity feed
+across every content type all come from the same three tables.
+
+Built on Rails' own `delegated_type`.
+
+## The idea
+
+A blog post is normally one row that you `UPDATE`. The old text is gone, and nothing in the
+database knows a post and a message are the same *kind* of thing. This splits it in three:
+
+```
+recording  ──points at──▶  recordable     the content (Article, Note, Comment)
+    │
+    └──has many──▶  events                every change, and which snapshot was
+                                          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.
+- **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.
+
+## Getting started
+
+```ruby
+gem "recordables"
+```
+
+```bash
+bin/rails generate recordables:install
+bin/rails generate recordables:bucket Project name:string
+bin/rails generate recordables:type Article title:string
+bin/rails db:migrate
+```
+
+Models read the way Rails reads:
+
+```ruby
+class Recording < ApplicationRecord
+  records :recordable, types: Recordable::TYPES
+end
+
+class Article < ApplicationRecord
+  recordable
+end
+```
+
+## Versioning a document
+
+```ruby
+doc = Recording.record(Article.new(title: "Spec v1"), actor: current_user, bucket: bucket)
+
+doc.revise(actor: current_user, title: "Spec v2")
+doc.revise(actor: current_user, title: "Spec v3")
+
+doc.versions                      # every snapshot, with who and when
+doc.recordable_at(2.days.ago)     # what it said then
+doc.revert_to(first_snapshot, actor: current_user)
+```
+
+Three edits leave one recording and three snapshots. Restoring is a single foreign-key
+update — nothing is deleted, and the revert is itself recorded:
+
+```
+v1  created   by Jonas  Spec v1
+v2  updated   by Jonas  Spec v2
+v3  updated   by Jonas  Spec v3
+```
+
+## One feed across every type
+
+```ruby
+Event.newest_first.limit(50)
+bucket.timeline
+```
+
+Adding a content type costs nothing here — generate it and it appears. No new query, no new
+branch in the feed code.
+
+## Rich text and attachments
+
+This is the part worth having a library for. `attributes` only carries columns, so a naive
+snapshot copy drops ActionText bodies and Active Storage files **without raising**. You would
+ship it and find out months later that every edited document lost its images.
+
+`copy_content_to` finds them by reflection and carries them across. Files are shared rather
+than duplicated — four versions of a document with a cover image produce four attachment rows
+and one blob, and Rails reference-counts blobs, so purging one version leaves the others
+readable.
+
+## It refuses rather than lose data
+
+A snapshot cannot carry ordinary `has_many` / `has_one` associations, so `revise` raises
+instead of quietly dropping them:
+
+```
+Article owns notes, which a new snapshot cannot carry.
+Model these as child recordings, or override #copy_content_to.
+```
+
+Children modelled the intended way — as child *recordings* — hang off the recording rather
+than the snapshot, so revising content never touches them.
+
+## What is generated, and what the gem keeps
+
+| | 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** |
+
+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.
+
+## Caveats
+
+- Never put a `uniqueness` validation on a recordable. Old snapshots still hold the old
+  value, so the second edit would fail.
+- Every edit inserts a row. Cheap for text; decide on retention before putting large uploads
+  through it.
+- `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.
+
+## Development
+
+```bash
+bundle install
+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
+lifecycle, rich text and attachment copy-forward, blob sharing, the uncopyable-association
+guard, and all three generators.
+
+## License
+
+MIT.

data/lib/generators/recordables/bucket/bucket_generator.rb

@@ -0,0 +1,36 @@
+require "rails/generators"
+require "rails/generators/active_record"
+require "recordables/generator_helpers"
+
+module Recordables
+  module Generators
+    class BucketGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+      include Recordables::GeneratorHelpers
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a bucket type — a container that owns recordings and defines access."
+
+      def validate!
+        validate_name!
+      end
+
+      def create_model
+        template "model.rb.tt", File.join("app/models", class_path, "#{file_name}.rb")
+      end
+
+      def create_bucket_migration
+        migration_template "migration.rb.tt", "db/migrate/create_#{table_name}.rb"
+      end
+
+      def register_type
+        register_type_in "app/models/concerns/bucketable.rb", "TYPES"
+      end
+
+      private
+
+        def generator_example = "bin/rails generate recordables:bucket Project name:string"
+    end
+  end
+end

data/lib/generators/recordables/bucket/templates/migration.rb.tt

@@ -0,0 +1,10 @@
+class Create<%= class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+<% attributes.each do |attribute| -%>
+      t.<%= attribute.type %> :<%= attribute.name %>, null: false
+<% end -%>
+      t.timestamps
+    end
+  end
+end

data/lib/generators/recordables/bucket/templates/model.rb.tt

@@ -0,0 +1,7 @@
+class <%= class_name %> < ApplicationRecord
+  include Bucketable
+<% if attributes.any? -%>
+
+  validates <%= attributes.map { |attribute| ":#{attribute.name}" }.join(", ") %>, presence: true
+<% end -%>
+end

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

@@ -0,0 +1,58 @@
+require "rails/generators"
+require "rails/generators/active_record"
+require "recordables/generator_helpers"
+
+module Recordables
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate the recordings/events spine, and optionally the bucket container."
+
+      class_option :actor, type: :string, default: "User",
+                           desc: "Model that creates recordings and appears on events"
+      class_option :buckets, type: :boolean, default: true,
+                            desc: "Generate Bucket, the container that owns recordings"
+
+      def validate!
+        return if actor_class.match?(Recordables::GeneratorHelpers::CONSTANT_NAME)
+
+        raise Rails::Generators::Error,
+              "Invalid --actor #{options[:actor].inspect}. Give a single CamelCase class name, " \
+              "for example: --actor=Person"
+      end
+
+      def create_spine_migration
+        migration_template "create_recordables_tables.rb.tt", "db/migrate/create_recordables_tables.rb"
+      end
+
+      def create_models
+        template "recording.rb.tt", "app/models/recording.rb"
+        template "event.rb.tt", "app/models/event.rb"
+        template "recordable.rb.tt", "app/models/concerns/recordable.rb"
+        return unless buckets?
+
+        template "bucket.rb.tt", "app/models/bucket.rb"
+        template "bucketable.rb.tt", "app/models/concerns/bucketable.rb"
+      end
+
+      def report
+        say "\nNext:", :green
+        say "  bin/rails generate recordables:bucket Project name:string" if buckets?
+        say "  bin/rails generate recordables:type Article title:string"
+      end
+
+      private
+
+        def buckets? = options[:buckets]
+
+        def actor_class = options[:actor].camelize
+
+        def actor_table = actor_class.tableize
+
+        def migration_version = "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+class Bucket < ApplicationRecord
+  delegated_type :bucketable, types: Bucketable::TYPES, inverse_of: :bucket
+
+  has_many :recordings, dependent: :destroy
+  has_many :events, through: :recordings
+
+  def self.open(bucketable)
+    bucketable.save! if bucketable.new_record?
+    find_or_create_by!(bucketable: bucketable)
+  end
+
+  def timeline = events.includes(:actor, :recordable, :recording).newest_first
+end

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

@@ -0,0 +1,11 @@
+module Bucketable
+  extend ActiveSupport::Concern
+
+  TYPES = %w[].freeze
+
+  included do
+    has_one :bucket, as: :bucketable, dependent: :destroy
+  end
+
+  def bucket! = Bucket.open(self)
+end

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

@@ -0,0 +1,42 @@
+class CreateRecordablesTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+<% if buckets? -%>
+    create_table :buckets do |t|
+      t.references :bucketable, polymorphic: true, null: false, index: false
+      t.timestamps
+
+      t.index [:bucketable_type, :bucketable_id], unique: true
+    end
+
+<% end -%>
+    create_table :recordings do |t|
+<% if buckets? -%>
+      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 :recordable, polymorphic: true, null: false, index: false
+      t.integer :status, null: false, default: 0
+      t.integer :position
+      t.timestamps
+
+      t.index [:recordable_type, :recordable_id]
+<% if buckets? -%>
+      t.index [:bucket_id, :recordable_type, :created_at]
+<% end -%>
+      t.index [:parent_id, :position]
+    end
+
+    create_table :events do |t|
+      t.references :recording, null: false, foreign_key: true
+      t.references :recordable, polymorphic: true, null: false, index: false
+      t.references :actor, null: false, foreign_key: { to_table: :<%= actor_table %> }
+      t.string :action, null: false
+      t.json :details, null: false, default: {}
+      t.datetime :created_at, null: false
+
+      t.index [:recording_id, :created_at]
+      t.index [:action, :created_at]
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+class Event < ApplicationRecord
+  belongs_to :recording
+  belongs_to :recordable, polymorphic: true
+  belongs_to :actor, class_name: "<%= actor_class %>"
+
+  scope :newest_first, -> { order(created_at: :desc, id: :desc) }
+  scope :of_type, ->(type) { where(recordable_type: type) }
+end

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

@@ -0,0 +1,3 @@
+module Recordable
+  TYPES = %w[].freeze
+end

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

@@ -0,0 +1,19 @@
+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 -%>
+  belongs_to :creator, class_name: "<%= actor_class %>"
+  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
+
+  delegate :commentable?, :publishable?, :nestable?, :summary, to: :recordable
+
+  scope :newest_first, -> { order(created_at: :desc, id: :desc) }
+  scope :sorted, -> { order(:position, :id) }
+end

data/lib/generators/recordables/type/templates/migration.rb.tt

@@ -0,0 +1,10 @@
+class Create<%= class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+<% attributes.each do |attribute| -%>
+      t.<%= attribute.type %> :<%= attribute.name %>, null: false
+<% end -%>
+      t.datetime :created_at, null: false
+    end
+  end
+end

data/lib/generators/recordables/type/templates/model.rb.tt

@@ -0,0 +1,9 @@
+class <%= class_name %> < ApplicationRecord
+  recordable
+<% if attributes.any? -%>
+
+  validates <%= attributes.map { |attribute| ":#{attribute.name}" }.join(", ") %>, presence: true
+<% end -%>
+
+  def summary = <%= summary_expression %>
+end

data/lib/generators/recordables/type/type_generator.rb

@@ -0,0 +1,44 @@
+require "rails/generators"
+require "rails/generators/active_record"
+require "recordables/generator_helpers"
+
+module Recordables
+  module Generators
+    class TypeGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+      include Recordables::GeneratorHelpers
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate an immutable recordable type and register it with the Recordable concern."
+
+      def validate!
+        validate_name!
+      end
+
+      def create_model
+        template "model.rb.tt", File.join("app/models", class_path, "#{file_name}.rb")
+      end
+
+      def create_type_migration
+        migration_template "migration.rb.tt", "db/migrate/create_#{table_name}.rb"
+      end
+
+      def register_type
+        register_type_in "app/models/concerns/recordable.rb", "TYPES"
+      end
+
+      private
+
+        def generator_example = "bin/rails generate recordables:type Article title:string"
+
+        def summary_expression
+          attribute = attributes.find { |candidate| candidate.type == :string } ||
+                      attributes.find { |candidate| candidate.type == :text }
+          return "model_name.human" unless attribute
+
+          attribute.type == :text ? "#{attribute.name}.truncate(40)" : attribute.name
+        end
+    end
+  end
+end

data/lib/recordables/generator_helpers.rb

@@ -0,0 +1,33 @@
+module Recordables
+  module GeneratorHelpers
+    CONSTANT_NAME = /\A[A-Z][A-Za-z0-9]*(::[A-Z][A-Za-z0-9]*)*\z/
+
+    def self.included(base)
+      base.argument :attributes, type: :array, default: [], banner: "field:type field:type"
+    end
+
+    def validate_name!
+      return if class_name.match?(CONSTANT_NAME)
+
+      raise Rails::Generators::Error,
+            "Invalid name #{name.inspect}. Give a single CamelCase class name, " \
+            "then the fields — for example: #{generator_example}"
+    end
+
+    private
+
+      def register_type_in(concern, constant)
+        unless File.exist?(File.join(destination_root, concern))
+          say_status :skip, "#{concern} not found — run recordables:install first", :red
+          return
+        end
+
+        gsub_file concern, /#{constant} = %w\[[^\]]*\]/ do |match|
+          names = (match[/\[([^\]]*)\]/, 1].to_s.split + [class_name]).uniq
+          "#{constant} = %w[#{names.join(' ')}]"
+        end
+      end
+
+      def migration_version = "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+  end
+end

data/lib/recordables/macros.rb

@@ -0,0 +1,26 @@
+module Recordables
+  # Class macros mixed into ActiveRecord::Base, so a model reads the way the
+  # rest of Rails does — `records`, not `include SomeModule`.
+  module Macros
+    # The spine. Wraps delegated_type so one call sets up the pointer, the type
+    # scopes, and the snapshot/version API together.
+    #
+    #   class Recording < ApplicationRecord
+    #     records :recordable, types: Recordable::TYPES
+    #   end
+    def records(role, types:, **options)
+      include Recordables::Recording
+
+      delegated_type role, types: types, **options
+    end
+
+    # An immutable content type: edits insert a new row instead of updating one.
+    #
+    #   class Post < ApplicationRecord
+    #     recordable
+    #   end
+    def recordable
+      include Recordables::Recordable
+    end
+  end
+end

data/lib/recordables/railtie.rb

@@ -0,0 +1,11 @@
+require "rails/railtie"
+
+module Recordables
+  class Railtie < ::Rails::Railtie
+    initializer "recordables.macros" do
+      ActiveSupport.on_load(:active_record) do
+        extend Recordables::Macros
+      end
+    end
+  end
+end

data/lib/recordables/recordable.rb

@@ -0,0 +1,89 @@
+require "active_support/concern"
+
+module Recordables
+  module Recordable
+    extend ActiveSupport::Concern
+
+    # Raised when a snapshot owns associations the copy-forward cannot carry.
+    # Losing them silently is the failure this gem exists to prevent.
+    class UncopyableAssociation < StandardError; end
+
+    included do
+      has_many :recordings, as: :recordable
+      has_many :events, as: :recordable
+    end
+
+    def commentable? = false
+    def publishable? = false
+    def nestable? = false
+
+    def summary = model_name.human
+
+    def revisable_attributes = attributes.except("id", "created_at")
+
+    # Column values ride along in #attributes, but rich text and attached files
+    # live in their own tables and would vanish from a new snapshot in silence.
+    def copy_content_to(revision)
+      guard_uncopyable_associations!
+      copy_rich_text_to(revision)
+      copy_attachments_to(revision)
+      revision
+    end
+
+    private
+
+      def guard_uncopyable_associations!
+        names = uncopyable_association_names
+        return if names.empty?
+
+        raise UncopyableAssociation,
+              "#{self.class.name} owns #{names.join(', ')}, which a new snapshot cannot carry. " \
+              "Model these as child recordings, or override #copy_content_to."
+      end
+
+      def uncopyable_association_names
+        self.class.reflect_on_all_associations.filter_map do |reflection|
+          next if reflection.options[:class_name] == "ActionText::RichText"
+          next if reflection.name.to_s.start_with?("rich_text_")
+          next unless %i[has_many has_one].include?(reflection.macro)
+          next if %i[recordings events].include?(reflection.name)
+          next if attachment_reflection_names.include?(reflection.name)
+
+          reflection.name
+        end
+      end
+
+      def attachment_reflection_names
+        return [] unless self.class.respond_to?(:attachment_reflections)
+
+        self.class.attachment_reflections.flat_map do |name, _reflection|
+          [name.to_sym, :"#{name}_attachment", :"#{name}_attachments", :"#{name}_blob", :"#{name}_blobs"]
+        end
+      end
+
+      def rich_text_names
+        self.class.reflect_on_all_associations(:has_one)
+            .select { |reflection| reflection.options[:class_name] == "ActionText::RichText" }
+            .map { |reflection| reflection.name.to_s.delete_prefix("rich_text_") }
+      end
+
+      def copy_rich_text_to(revision)
+        rich_text_names.each do |name|
+          existing = public_send(name)
+          revision.public_send(:"#{name}=", existing.body) if existing&.body
+        end
+      end
+
+      def copy_attachments_to(revision)
+        return unless self.class.respond_to?(:attachment_reflections)
+
+        self.class.attachment_reflections.each do |name, reflection|
+          attached = public_send(name)
+          next unless attached.attached?
+
+          blobs = reflection.macro == :has_many_attached ? attached.blobs : [attached.blob]
+          revision.public_send(name).attach(*blobs)
+        end
+      end
+  end
+end

data/lib/recordables/recording.rb

@@ -0,0 +1,48 @@
+require "active_support/concern"
+
+module Recordables
+  module Recording
+    extend ActiveSupport::Concern
+
+    VERSION_ACTIONS = %w[created updated reverted].freeze
+
+    class_methods do
+      def record(recordable, actor:, parent: nil, **attributes)
+        transaction do
+          recordable.save!
+          recording = create!(recordable: recordable, creator: actor, parent: parent, **attributes)
+          recording.log!("created", recordable, actor: actor)
+          recording
+        end
+      end
+    end
+
+    def revise(actor:, **changes)
+      transaction do
+        revision = recordable.class.new(recordable.revisable_attributes)
+        recordable.copy_content_to(revision)
+        changes.each { |name, value| revision.public_send(:"#{name}=", value) }
+        revision.save!
+        update!(recordable: revision)
+        log!("updated", revision, actor: actor, details: { "changed" => changes.keys.map(&:to_s) })
+        revision
+      end
+    end
+
+    def revert_to(snapshot, actor:)
+      transaction do
+        update!(recordable: snapshot)
+        log!("reverted", snapshot, actor: actor, details: { "restored_id" => snapshot.id })
+        snapshot
+      end
+    end
+
+    def versions = events.where(action: VERSION_ACTIONS).order(:created_at, :id)
+
+    def recordable_at(time) = versions.where(created_at: ..time).last&.recordable
+
+    def log!(action, snapshot, actor:, details: {})
+      events.create!(recordable: snapshot, actor: actor, action: action, details: details)
+    end
+  end
+end

data/lib/recordables/version.rb

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

data/lib/recordables.rb

@@ -0,0 +1,11 @@
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/recordables/railtie.rb")
+loader.setup
+
+module Recordables
+end
+
+require "recordables/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: recordables
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jonas Medeiros
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Scaffolds a recordings/recordables/events content spine into a Rails
+  app, and keeps the snapshot copy-forward logic that is easy to get silently wrong.
+email:
+- jonas.g.medeiros@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/recordables/bucket/bucket_generator.rb
+- lib/generators/recordables/bucket/templates/migration.rb.tt
+- lib/generators/recordables/bucket/templates/model.rb.tt
+- lib/generators/recordables/install/install_generator.rb
+- lib/generators/recordables/install/templates/bucket.rb.tt
+- lib/generators/recordables/install/templates/bucketable.rb.tt
+- lib/generators/recordables/install/templates/create_recordables_tables.rb.tt
+- lib/generators/recordables/install/templates/event.rb.tt
+- lib/generators/recordables/install/templates/recordable.rb.tt
+- lib/generators/recordables/install/templates/recording.rb.tt
+- lib/generators/recordables/type/templates/migration.rb.tt
+- lib/generators/recordables/type/templates/model.rb.tt
+- lib/generators/recordables/type/type_generator.rb
+- lib/recordables.rb
+- lib/recordables/generator_helpers.rb
+- lib/recordables/macros.rb
+- lib/recordables/railtie.rb
+- lib/recordables/recordable.rb
+- lib/recordables/recording.rb
+- lib/recordables/version.rb
+homepage: https://github.com/jonasmedeiros/recordables
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jonasmedeiros/recordables
+  source_code_uri: https://github.com/jonasmedeiros/recordables
+  changelog_uri: https://github.com/jonasmedeiros/recordables/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jonasmedeiros/recordables/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generators and runtime helpers for versioned delegated types.
+test_files: []