activestorage-aws-record 0.1.0

data/lib/active_storage/aws_record/persistence.rb

@@ -0,0 +1,89 @@
+require 'securerandom'
+
+module ActiveStorage
+  module AwsRecord
+    # Generic aws-record plumbing shared by every model that participates in the
+    # Active Storage owner contract — both the gem's own entities and the
+    # application's owner models (which include {Owner}). It deliberately holds
+    # *no* single-table key logic (that lives in {Item}, mixed only into the
+    # gem's three entities), so an application owner keeps its own key schema.
+    #
+    # Provides: aws-record + GlobalID, the shared client, equality by class + id,
+    # +changed?+ → aws-record +dirty?+, raw attribute access, and helpers to mark
+    # an instance persisted/destroyed after a raw write.
+    module Persistence
+      extend ActiveSupport::Concern
+
+      included do
+        include Aws::Record
+        include GlobalID::Identification
+
+        # Defined here, after +include Aws::Record+, so it shadows aws-record's
+        # +find(opts)+ class method with the contract's +find(id)+. Single
+        # hash-key owners (the common case) use this as-is; the gem's own
+        # composite-key entities override it.
+        def self.find(id)
+          record = find_with_opts(key: { hash_key => id })
+          record || raise(ActiveStorage::RecordNotFound, "Couldn't find #{name} with id=#{id.inspect}")
+        rescue Aws::Record::Errors::KeyMissing
+          raise ActiveStorage::RecordNotFound, "Couldn't find #{name} with id=#{id.inspect}"
+        end
+      end
+
+      class_methods do
+        # @return [Aws::DynamoDB::Client] the shared client.
+        def dynamodb_client
+          ActiveStorage::AwsRecord.dynamodb_client
+        end
+      end
+
+      def dynamodb_client
+        self.class.dynamodb_client
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && id.present? && id == other.id
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [self.class, id].hash
+      end
+
+      # Active Storage's generic owner path checks +changed?+; aws-record names
+      # the same concept +dirty?+.
+      def changed?
+        dirty?
+      end
+
+      # Raw attribute access via aws-record's data object (it has no AR-style
+      # +self[:attr]+), for use inside overridden accessors.
+      def read_attribute(name)
+        instance_variable_get('@data').get_attribute(name)
+      end
+
+      def write_attribute(name, value)
+        instance_variable_get('@data').set_attribute(name, value)
+      end
+
+      # Mark this instance persisted after a raw (non-aws-record) write.
+      def mark_persisted!
+        data = instance_variable_get('@data')
+        data.new_record = false
+        data.destroyed = false
+        data.clean!
+      end
+
+      # Mark this instance destroyed after a raw delete.
+      def mark_destroyed!
+        instance_variable_get('@data').destroyed = true
+      end
+
+      private
+
+      def generate_uuid
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/railtie.rb

@@ -0,0 +1,53 @@
+require 'rails/railtie'
+
+module ActiveStorage
+  module AwsRecord
+    # Wires the gem into a Rails app: maps +config.activestorage_aws_record+ onto
+    # the gem's {Configuration}, registers the three classes as Active Storage's
+    # persistence classes before class indirection resolves, then — once the app
+    # is initialized — discovers the table layout and declares the models' key
+    # attributes, sets up the service registry (the custom blob class does not
+    # load the default Active Record blob that normally does this), and installs
+    # the +preview_image+ / +image+ attachments.
+    class Railtie < ::Rails::Railtie
+      config.activestorage_aws_record = ActiveSupport::OrderedOptions.new
+
+      initializer 'activestorage_aws_record.configure', before: 'active_storage.class_indirection' do |app|
+        options = app.config.activestorage_aws_record
+
+        ActiveStorage::AwsRecord.configure do |config|
+          config.table_name     = options.table_name     if options.table_name
+          config.namespace      = options.namespace      if options.namespace
+          config.separator      = options.separator      if options.separator
+          config.manage_table   = options.manage_table   unless options.manage_table.nil?
+          config.index_name     = options.index_name     if options.index_name
+          config.client_options = options.client_options if options.client_options
+          config.client         = options.client         if options.client
+        end
+
+        app.config.active_storage.blob_class = 'ActiveStorage::AwsRecord::Blob'
+        app.config.active_storage.attachment_class = 'ActiveStorage::AwsRecord::Attachment'
+        app.config.active_storage.variant_record_class = 'ActiveStorage::AwsRecord::VariantRecord'
+      end
+
+      # Run after the app is fully initialized so Active Storage's app/models
+      # (Servable, Variant, ...) are autoloadable when our model classes load.
+      config.after_initialize do |app|
+        # Discover the table layout and declare the models' key attributes +
+        # shared client.
+        ActiveStorage::AwsRecord.install!
+
+        # The default AR blob initializes the service registry on load; the
+        # custom backend must do it explicitly.
+        ActiveStorage::Services.setup_from_app_config(app)
+
+        # Install the owner attachments now that class indirection is configured.
+        ActiveStorage::AwsRecord.install_attachments!
+      end
+
+      rake_tasks do
+        load File.expand_path('tasks.rake', __dir__)
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/relation.rb

@@ -0,0 +1,163 @@
+module ActiveStorage
+  module AwsRecord
+    # A lazy relation returned by +Attachment.where+ / +Attachment.find_by+. It
+    # mirrors the in-memory reference +Relation+: it collects filters/exclusions
+    # and, on materialization, runs the cheapest access path for the single-table
+    # layout — an owner-adjacency query — then applies residual filters,
+    # exclusions, and ordering in Ruby (the attachment set for one owner+name is
+    # small). Unsupported filters raise +ActiveStorage::QueryNotSupported+ rather
+    # than silently scanning.
+    #
+    # In Mode A the query is a strongly-consistent base-table query; in Mode B it
+    # runs against the string-keyed GSI (eventually consistent).
+    class Relation
+      include Enumerable
+
+      def initialize(model, filters: {}, exclusions: [])
+        @model = model
+        @filters = filters.transform_keys(&:to_sym)
+        @exclusions = exclusions
+      end
+
+      def where(attributes = nil)
+        return WhereChain.new(self) if attributes.nil?
+
+        self.class.new(@model, filters: @filters.merge(attributes), exclusions: @exclusions)
+      end
+
+      def not(attributes)
+        self.class.new(@model, filters: @filters, exclusions: @exclusions + [attributes.transform_keys(&:to_sym)])
+      end
+
+      def order(*attributes)
+        Ordered.new(to_a, attributes.flatten)
+      end
+
+      def find_by(attributes)
+        where(attributes).first
+      end
+
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      def pluck(*attrs)
+        to_a.map do |record|
+          values = attrs.map { |a| record.public_send(a) }
+          attrs.size == 1 ? values.first : values
+        end
+      end
+
+      # Detach-many's bulk delete. Wrapped in the model's transaction so the rows
+      # (and their coalesced blob refcount decrements) commit atomically instead
+      # of one-at-a-time, matching the contract's +attachment_class.transaction+
+      # expectation for grouped deletes.
+      def delete_all
+        records = to_a
+        @model.transaction { records.each(&:delete) }
+        records
+      end
+
+      def to_a
+        @to_a ||= filtered(query_records)
+      end
+
+      def reload
+        @to_a = nil
+        self
+      end
+      alias_method :reset, :reload
+
+      # Backend filtering beyond the supported keys is not available on the
+      # generated collections; query the model class directly instead.
+      def method_missing(name, *, &)
+        raise ActiveStorage::QueryNotSupported,
+          "#{name} is not supported on #{self.class.name}; query #{@model.name}.where(...) directly."
+      end
+
+      def respond_to_missing?(*)
+        false
+      end
+
+      private
+
+      # The contract always supplies (record_type, record_id[, name]); anything
+      # else has no single-table access path and must not silently scan.
+      def query_records
+        unless @filters.key?(:record_type) && @filters.key?(:record_id)
+          raise ActiveStorage::QueryNotSupported,
+            "Unsupported attachment query #{@filters.keys.inspect}; supported: (record_type, record_id[, name])."
+        end
+
+        owner_query
+      end
+
+      def owner_query
+        schema = ActiveStorage::AwsRecord.schema
+        partition = @model.owner_partition(@filters[:record_type], @filters[:record_id])
+        prefix = @model.attachment_prefix(@filters[:name])
+
+        opts = {
+          key_condition_expression: '#h = :h AND begins_with(#r, :r)',
+          expression_attribute_values: { ':h' => partition, ':r' => prefix },
+        }
+        if schema.range_mode?
+          opts[:expression_attribute_names] = { '#h' => schema.partition_attr, '#r' => schema.sort_attr }
+          opts[:consistent_read] = true
+        else
+          opts[:index_name] = schema.index_name
+          opts[:expression_attribute_names] = { '#h' => schema.index_partition_attr, '#r' => schema.index_sort_attr }
+        end
+        @model.query(opts).to_a
+      end
+
+      # Apply residual equality filters and exclusions in Ruby.
+      def filtered(records)
+        records.select do |record|
+          @filters.all? { |attr, value| matches?(record.public_send(attr), value) } &&
+            @exclusions.none? { |excl| excl.any? { |attr, value| matches?(record.public_send(attr), value) } }
+        end
+      end
+
+      def matches?(actual, expected)
+        if expected.is_a?(Array)
+          expected.map(&:to_s).include?(actual.to_s)
+        else
+          actual.to_s == expected.to_s
+        end
+      end
+
+      # Materialized, ordered result that still supports the collection helpers.
+      class Ordered
+        include Enumerable
+
+        def initialize(records, attributes)
+          @records = records.sort_by { |record| attributes.map { |attr| sort_value(record.public_send(attr)) } }
+          @attributes = attributes
+        end
+
+        def each(&block) = @records.each(&block)
+        def to_a = @records.dup
+        def pluck(*attrs)
+          @records.map { |r| attrs.size == 1 ? r.public_send(attrs.first) : attrs.map { |a| r.public_send(a) } }
+        end
+
+        private
+
+        def sort_value(value)
+          value.nil? ? '' : value.to_s
+        end
+      end
+
+      class WhereChain
+        def initialize(relation)
+          @relation = relation
+        end
+
+        def not(attributes)
+          @relation.not(attributes)
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/schema.rb

@@ -0,0 +1,148 @@
+module ActiveStorage
+  module AwsRecord
+    # The resolved physical layout of the single table, discovered once at boot
+    # from +describe_table+ (with optional config overrides) and cached read-only
+    # thereafter. Two modes, chosen by the range key's type:
+    #
+    # * +:range+ (range key is String "S") — the gem writes its +#+-composite
+    #   adjacency keys straight into the table's (partition, sort) attributes. All
+    #   reads are on the base table and strongly consistent. No GSI.
+    # * +:index+ (range key is Number "N") — composite strings cannot live in a
+    #   numeric range key, so each item is keyed by a unique +item_id+ plus a
+    #   constant +0+ range, and the adjacency keys move to a string-keyed GSI that
+    #   serves listing queries (eventually consistent). Point lookups, the
+    #   refcount, and the foreign-key guard stay on the base table (strong).
+    #
+    # The partition key must be String in both modes (it stores +item_id+/key
+    # strings); a numeric partition key is rejected.
+    class Schema
+      # DynamoDB attribute names the gem stores for its own logical attributes.
+      # Detected key attributes must not collide with these (see {.guard_names!}).
+      RESERVED_ATTRIBUTE_NAMES = %w[
+        as_id as_key as_filename as_content_type as_byte_size as_checksum
+        as_metadata as_service_name as_created_at as_attachments_count
+        as_record_type as_record_id as_name as_blob_id as_variation_digest
+        as_entity
+      ].freeze
+
+      attr_reader :mode, :partition_attr, :sort_attr,
+                  :index_name, :index_partition_attr, :index_sort_attr
+
+      # Inspect the live table and resolve the layout.
+      #
+      # @param client [Aws::DynamoDB::Client]
+      # @param config [Configuration]
+      # @return [Schema]
+      # @raise [ConfigurationError] when the table cannot be adapted.
+      def self.discover(client, config)
+        table = describe(client, config.table_name)
+        new(table, config)
+      end
+
+      def self.describe(client, table_name)
+        client.describe_table(table_name: table_name).table
+      rescue Aws::DynamoDB::Errors::ResourceNotFoundException
+        raise ConfigurationError, "DynamoDB table #{table_name.inspect} does not exist. " \
+          'Create it first, or set config.manage_table = true in development.'
+      end
+
+      def initialize(table, config)
+        types = table.attribute_definitions.each_with_object({}) { |d, h| h[d.attribute_name] = d.attribute_type }
+
+        @partition_attr = key_name(table.key_schema, 'HASH')
+        @sort_attr      = key_name(table.key_schema, 'RANGE')
+
+        validate!(types)
+
+        case types[@sort_attr]
+        when 'S'
+          @mode = :range
+        when 'N'
+          @mode = :index
+          resolve_index!(table, config, types)
+        else
+          raise ConfigurationError, "Range key #{@sort_attr.inspect} must be type String (S) or Number (N), " \
+            "got #{types[@sort_attr].inspect}."
+        end
+
+        self.class.guard_names!(self)
+      end
+
+      # @return [Boolean] true in Mode A (string range key, base-table adjacency).
+      def range_mode? = @mode == :range
+
+      # @return [Boolean] true in Mode B (numeric range key, GSI adjacency).
+      def index_mode? = @mode == :index
+
+      private
+
+      def key_name(key_schema, type)
+        key_schema.find { it.key_type == type }&.attribute_name
+      end
+
+      def validate!(types)
+        raise ConfigurationError, 'Table has no partition key' unless @partition_attr
+        raise ConfigurationError, "Table #{@partition_attr.inspect} has no range key; a " \
+          'composite (partition + sort) key is required.' unless @sort_attr
+
+        partition_type = types[@partition_attr]
+        if partition_type && partition_type != 'S'
+          raise ConfigurationError, "Partition key #{@partition_attr.inspect} must be type String (S), " \
+            "got #{partition_type.inspect}."
+        end
+      end
+
+      # Mode B needs a string-keyed GSI carrying the adjacency keys. Locate it by
+      # the configured name and adopt its actual key attribute names. Absent on an
+      # app-managed table → tell the operator exactly what to add rather than
+      # silently mutating their indexes. The GSI must have a (String, String) key
+      # and project ALL.
+      def resolve_index!(table, config, types)
+        @index_name = config.index_name
+        gsi = (table.global_secondary_indexes || []).find { it.index_name == @index_name }
+        unless gsi
+          raise ConfigurationError, "Range key #{@sort_attr.inspect} is numeric (N), so a string-keyed " \
+            "GSI named #{@index_name.inspect} is required (a String partition + String sort key, " \
+            'projection ALL). Add it to the table, or set config.manage_table = true in development.'
+        end
+
+        @index_partition_attr = key_name(gsi.key_schema, 'HASH')
+        @index_sort_attr      = key_name(gsi.key_schema, 'RANGE')
+
+        validate_index!(gsi, types)
+      end
+
+      def validate_index!(gsi, types)
+        unless @index_partition_attr && @index_sort_attr
+          raise ConfigurationError, "GSI #{@index_name.inspect} must have both a partition and a sort key."
+        end
+
+        [@index_partition_attr, @index_sort_attr].each do |attr|
+          type = types[attr]
+          if type && type != 'S'
+            raise ConfigurationError, "GSI #{@index_name.inspect} key #{attr.inspect} must be type String (S), " \
+              "got #{type.inspect}."
+          end
+        end
+
+        projection = gsi.projection&.projection_type
+        if projection && projection != 'ALL'
+          raise ConfigurationError, "GSI #{@index_name.inspect} must project ALL attributes (got #{projection.inspect})."
+        end
+      end
+
+      # Reject a table whose key (or index key) attribute names collide with the
+      # gem's stored attributes — aws-record cannot map two attributes to one
+      # DynamoDB name.
+      def self.guard_names!(schema)
+        names = [schema.partition_attr, schema.sort_attr,
+                 schema.index_partition_attr, schema.index_sort_attr,].compact
+        clash = names & RESERVED_ATTRIBUTE_NAMES
+        unless clash.empty?
+          raise ConfigurationError, "Key attribute name(s) #{clash.inspect} collide with attributes the gem " \
+            'stores. Use different key attribute names for this table.'
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/tables.rb

@@ -0,0 +1,82 @@
+module ActiveStorage
+  module AwsRecord
+    # Creates / deletes the gem's single DynamoDB table. Intended for development
+    # and tests (gated by +config.manage_table+); production tables are managed by
+    # the application. The created table uses a String (partition, sort) key —
+    # i.e. Mode A — with on-demand (PAY_PER_REQUEST) billing and no GSI. Point the
+    # gem at an existing table (any key-attribute names; numeric range → Mode B)
+    # to integrate with an app that owns its schema.
+    module Tables
+      module_function
+
+      def client
+        ActiveStorage::AwsRecord.dynamodb_client
+      end
+
+      def table_name
+        ActiveStorage::AwsRecord.config.table_name
+      end
+
+      # Partition / sort key attribute names for a gem-created (Mode A) table.
+      # Production tables are app-managed and may use any names (auto-detected).
+      def partition_key
+        'pk'
+      end
+
+      def sort_key
+        'sk'
+      end
+
+      # Create the table if it does not already exist.
+      def ensure!
+        return if exist?
+
+        create!
+      end
+
+      def exist?
+        client.describe_table(table_name: table_name)
+        true
+      rescue Aws::DynamoDB::Errors::ResourceNotFoundException
+        false
+      end
+
+      def create!
+        client.create_table(
+          table_name: table_name,
+          attribute_definitions: [
+            { attribute_name: partition_key, attribute_type: 'S' },
+            { attribute_name: sort_key, attribute_type: 'S' },
+          ],
+          key_schema: [
+            { attribute_name: partition_key, key_type: 'HASH' },
+            { attribute_name: sort_key, key_type: 'RANGE' },
+          ],
+          billing_mode: 'PAY_PER_REQUEST'
+        )
+        client.wait_until(:table_exists, table_name: table_name)
+      rescue Aws::DynamoDB::Errors::ResourceInUseException
+        nil
+      end
+
+      def delete!
+        client.delete_table(table_name: table_name)
+        wait_until_gone!
+      rescue Aws::DynamoDB::Errors::ResourceNotFoundException
+        nil
+      end
+
+      # Drop and recreate (used by the test harness for a clean slate).
+      def reset!
+        delete!
+        create!
+      end
+
+      def wait_until_gone!
+        client.wait_until(:table_not_exists, table_name: table_name)
+      rescue Aws::Waiters::Errors::WaiterFailed
+        nil
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/tasks.rake

@@ -0,0 +1,15 @@
+namespace :activestorage_aws_record do
+  namespace :table do
+    desc 'Create the Active Storage DynamoDB table'
+    task create: :environment do
+      ActiveStorage::AwsRecord::Tables.create!
+      puts "Created/verified table: #{ActiveStorage::AwsRecord.config.table_name}"
+    end
+
+    desc 'Delete the Active Storage DynamoDB table'
+    task delete: :environment do
+      ActiveStorage::AwsRecord::Tables.delete!
+      puts 'Deleted Active Storage DynamoDB table.'
+    end
+  end
+end

data/lib/active_storage/aws_record/transaction.rb

@@ -0,0 +1,132 @@
+module ActiveStorage
+  module AwsRecord
+    # Raised, before any write, when a batched attachment change would exceed
+    # DynamoDB's hard 100-action limit for +transact_write_items+. The operation
+    # fails closed rather than chunking or falling back to per-row deletes — both
+    # of which would reintroduce the partial-clear bug this batching exists to
+    # prevent. Split the change into smaller batches instead.
+    class TransactionTooLarge < StandardError; end
+
+    # A fiber-local accumulator that batches the attachment *destroys* opened
+    # inside an +Attachment.transaction+ block into a single DynamoDB
+    # +transact_write_items+, so a multi-attachment clear / replace / detach is
+    # atomic: DynamoDB deletes every row (and adjusts every blob refcount) or
+    # none, instead of deleting some rows before a later one fails (the
+    # partial-clear bug the generic +has_many+ paths would otherwise hit).
+    #
+    # *Creates are intentionally not buffered.* Active Storage's own create paths
+    # (+CreateOne+/+CreateMany+) clean up newly-built blob/attachment records when
+    # a +save!+ raises synchronously; deferring those writes to commit would move
+    # the failure past that cleanup. Only destroys — whose sole failure mode is
+    # *partial* multi-row deletion — are batched here.
+    #
+    # Fiber-safe (Falcon): the active context lives in +Fiber[]+, never a class or
+    # thread global, so independent request fibers (Falcon assigns one per request)
+    # each get their own transaction. The grouped-destroy blocks are executed
+    # synchronously on one fiber; +Fiber[]+ is inherited by a *child* fiber, so do
+    # not spawn an Async task / +Fiber.new+ inside an +Attachment.transaction+ block
+    # (it would join the parent's buffer rather than open its own).
+    class Transaction
+      # DynamoDB's hard ceiling on actions in one +transact_write_items+ call.
+      MAX_TRANSACT_ITEMS = 100
+
+      FIBER_KEY = :active_storage_aws_record_transaction
+
+      class << self
+        # @return [Transaction, nil] the transaction active on this fiber.
+        def current
+          Fiber[FIBER_KEY]
+        end
+
+        # Run +block+ inside a transaction. A *nested* call joins the enclosing
+        # transaction — its buffered destroys flush only at the outermost commit.
+        # The outermost call commits the buffer on success; on any exception it
+        # discards the buffer *unwritten*, so the block is atomic (nothing is
+        # deleted). The fiber-local context is always cleared on the way out.
+        #
+        # @param model [Class] the Attachment class that opened the transaction.
+        def run(model)
+          return yield if current # nested: join the outer transaction
+
+          tx = new(model)
+          Fiber[FIBER_KEY] = tx
+          begin
+            result = yield
+            tx.commit!
+            result
+          ensure
+            Fiber[FIBER_KEY] = nil
+          end
+        end
+      end
+
+      def initialize(model)
+        @model = model
+        @destroys = []
+      end
+
+      # Buffer one attachment destroy/delete for the commit.
+      def enqueue_destroy(attachment)
+        @destroys << attachment
+      end
+
+      # Flush the buffered destroys:
+      # * 0 → nothing;
+      # * 1 → the existing per-row path (+#commit_destroy!+), which keeps its
+      #   idempotent duplicate-purge / orphaned-blob recovery;
+      # * ≥2 → one coalesced +transact_write_items+ (one delete per attachment row,
+      #   one refcount +ADD+ per *distinct* blob, since DynamoDB forbids two
+      #   actions on the same item in a transaction).
+      def commit!
+        return if @destroys.empty?
+
+        if @destroys.size == 1
+          @destroys.first.commit_destroy!
+          return
+        end
+
+        items = transact_items
+        if items.size > MAX_TRANSACT_ITEMS
+          deletes = items.count { |item| item.key?(:delete) }
+          raise TransactionTooLarge,
+            "Atomic attachment change needs #{items.size} DynamoDB actions, over the " \
+            "#{MAX_TRANSACT_ITEMS}-action transaction limit (#{deletes} attachments, " \
+            "#{items.size - deletes} blobs). Split the change into smaller batches."
+        end
+
+        @model.dynamodb_client.transact_write_items(transact_items: items)
+        @destroys.each(&:mark_destroyed!)
+      rescue Aws::DynamoDB::Errors::TransactionCanceledException => e
+        # A conditional failure cancels the *whole* batch (a row or blob vanished
+        # under a concurrent change), so nothing was written. Surface it as a
+        # destroy failure; the generic path resets its deferred purges and
+        # re-raises. Refusing a partial result here is the point of batching.
+        raise ActiveStorage::RecordNotDestroyed.new(
+          "Failed to destroy #{@destroys.size} attachments atomically: #{e.message}", @destroys.first
+        )
+      rescue Aws::DynamoDB::Errors::ServiceError => e
+        # Any other DynamoDB failure (throttling, network) also wrote nothing;
+        # map it to RecordNotDestroyed too, matching the per-row #destroy contract.
+        raise ActiveStorage::RecordNotDestroyed.new("Failed to destroy attachment: #{e.message}", @destroys.first)
+      end
+
+      private
+
+      # One delete per attachment row, plus one coalesced refcount update per
+      # distinct blob (delta = −the number of its buffered destroys), so the same
+      # blob attached twice yields a single +ADD #c -2+ rather than two rejected
+      # operations on one item. Rows are de-duplicated by physical key first: the
+      # generic paths only ever enqueue distinct rows, but the public reentrant
+      # +Attachment.transaction+ could buffer the *same* row twice (e.g. a nested
+      # purge), which DynamoDB would reject as two actions on one item — collapsing
+      # it to a single delete keeps that an idempotent no-op, as the per-row path is.
+      def transact_items
+        rows    = @destroys.uniq(&:physical_key)
+        deletes = rows.map { |attachment| { delete: attachment.delete_transact_item } }
+        deltas  = rows.each_with_object(Hash.new(0)) { |attachment, h| h[attachment.blob_id] -= 1 }
+        updates = deltas.map { |blob_id, delta| { update: @model.blob_count_update(blob_id, delta) } }
+        deletes + updates
+      end
+    end
+  end
+end