active_storage_quota 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97ca05b6982dba442274c20efc15665e85f174879a9f695b31be021b277bd89e
+  data.tar.gz: '09e144b62a35850cdf84e6994e3f9dcc0fb96805dc5dd02686ab30c0195f9eaf'
+SHA512:
+  metadata.gz: 05d7b59f2dabd66b623d25c0b0391484a0b41e8279ec7ed9685e93cbe32bd75b8e477db9ed34c43391ef2959c5b9d1fd3243e26b16d80ea60007336677186ed3
+  data.tar.gz: 2b29d72c64a566dc27296d93949071bfd69421033c9f85c76cd4f359e9948645b9794e117fcecd4a435652f52419a82a048930d2f40de76a84b900266f748851

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+First release.
+
+### Added
+
+- `has_storage_quota` declares a quota owner, with limits given as an Integer,
+  a Symbol, a callable, or `nil` for unlimited. Readers: `storage_limit`,
+  `storage_usage`, `storage_reserved`, `storage_remaining`,
+  `storage_quota_exceeded?`.
+- `storage_quota_owner` declares which owner a model's attachments are charged
+  to. Works for `has_one_attached` and `has_many_attached` alike, and for every
+  attachment name on the model.
+- Active Storage accounting through documented load hooks, with no
+  monkey-patching. The same blob is charged once per owner and reference
+  counted; different owners are charged independently. Records hidden by a
+  `default_scope` still count, and re-pointing an attachment at another blob
+  moves its charge.
+- Race-safe admission. Capacity is tested and claimed in a single conditional
+  `UPDATE`, so concurrent uploads across processes cannot overshoot a quota.
+  Refused uploads raise `ActiveStorageQuota::QuotaExceeded` and persist nothing.
+- Storage reservations for uploads that span requests, with a hard expiry,
+  `ActiveStorageQuota.release_expired_reservations!` and a rake task. Destroying
+  a blob releases any reservations naming it.
+- `ActiveStorageQuota::DirectUploadsController`, a quota-aware direct-upload
+  endpoint. Subclass it and route to it; the response is Rails' own JSON, so
+  stock `@rails/activestorage` needs no changes. A full quota returns
+  `409 Conflict` with `{"error":"storage_quota_exceeded"}`.
+- `ActiveStorageQuota.audit`, read-only inspection reporting eleven categories
+  of drift with exact totals and bounded samples. Performs no writes of any
+  kind.
+- `reconcile_counters!`, `reconcile_ledger!` and `reconcile!`, repairing
+  counters and the charge ledger under short locked transactions. Dry runs plan
+  through the same logic they apply. Removing charges is opt-in and bounded by
+  a circuit breaker.
+- `ActiveStorageQuota::Backfill`, building the initial ledger for an application
+  adopting the gem with existing attachments. Strictly additive, idempotent and
+  resumable through an opaque cursor.
+- Rake tasks: `audit`, `reconcile`, `reconcile:apply`, `backfill`,
+  `backfill:apply`, `release_expired_reservations`, `install:migrations`.
+
+### Supported
+
+- Ruby >= 3.1; Active Record, Active Storage and Railties >= 7.1 and < 8.2.
+- CI covers Rails 7.1, 7.2, 8.0 and 8.1.
+- PostgreSQL is the primary production target and where concurrency is tested;
+  SQLite and MySQL are supported.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mubasher Khan
+
+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,404 @@
+# ActiveStorageQuota
+
+Race-safe storage quotas for Rails Active Storage.
+
+## The problem
+
+Rails Active Storage stores files but does not enforce how many bytes an owner
+may store. The naive check is a race:
+
+```ruby
+if company.storage_remaining >= file.size   # two requests both read 100MB free
+  company.documents.attach(file)            # both attach 80MB; you are over quota
+end
+```
+
+This gem replaces check-then-act with an atomic capacity claim, so concurrent
+uploads across multiple processes and servers cannot overshoot a quota.
+
+## Requirements
+
+- Ruby >= 3.1
+- Active Record, Active Storage and Railties >= 7.1 and < 8.2
+- CI covers Rails 7.1, 7.2, 8.0 and 8.1
+- PostgreSQL is the primary production target and is where the concurrency
+  guarantees are tested.
+- SQLite is supported for non-concurrency behavior and is covered by the test
+  suite.
+- Other Active Record adapters are not currently part of the CI matrix.
+
+## Installation
+
+```ruby
+gem "active_storage_quota"
+```
+
+```sh
+bundle install
+bin/rails active_storage_quota:install:migrations
+bin/rails db:migrate
+```
+
+## Usage
+
+Declare who holds a quota, and which records' attachments count against it.
+
+```ruby
+class Company < ApplicationRecord
+  has_storage_quota limit: 5.gigabytes
+end
+
+class Property < ApplicationRecord
+  belongs_to :company
+
+  storage_quota_owner :company
+
+  has_many_attached :photos
+  has_one_attached :file
+end
+```
+
+That is the whole setup. Attaching now works exactly as it always did, except
+that an upload which would exceed the quota raises
+`ActiveStorageQuota::QuotaExceeded` and is not persisted.
+
+```ruby
+property.file.attach(io: pdf, filename: "contract.pdf", content_type: "application/pdf")
+property.photos.attach(io: png, filename: "front.png", content_type: "image/png")
+
+company.storage_usage      # => 1_234_567   bytes currently stored
+company.storage_limit      # => 5368709120  bytes, or nil when unlimited
+company.storage_remaining  # => bytes left, floored at 0, or nil when unlimited
+company.storage_reserved   # => bytes held by uploads in flight
+company.storage_quota_exceeded?   # => false
+```
+
+Every byte value is an `Integer`.
+
+### What counts
+
+- **Both attachment macros are supported.** `has_many_attached` and
+  `has_one_attached` behave identically, and every attachment name on a model
+  uses that model's declared `storage_quota_owner`.
+- **The same blob attached twice to one owner is charged once.** Active Storage
+  stores one object, so the owner pays for it once; the charge is reference
+  counted and released when the last attachment goes.
+- **The same blob attached by two different owners is charged to each in
+  full.** A quota is an entitlement, not a bill for physical bytes, so one
+  tenant's usage never depends on what another tenant happens to store.
+- **Soft-deleted records still count.** A record hidden by its model's
+  `default_scope` still owns its attachments, so they stay charged until the
+  attachments themselves are removed.
+- **Swapping a blob in place moves the charge.** `attachment.update!(blob: other)`
+  releases the old blob and admits the new one in the same transaction; if the
+  new blob does not fit, the update is rolled back.
+
+### Dynamic and unlimited limits
+
+`limit:` takes an Integer, a Symbol naming a method on the owner, a callable, or
+`nil`.
+
+```ruby
+has_storage_quota limit: :plan_storage_limit
+has_storage_quota limit: ->(company) { company.subscription.storage_limit }
+has_storage_quota limit: nil          # unlimited: still accounted, never refused
+```
+
+Nothing is coerced. A limit of `"5000"` or `5.0` raises
+`ActiveStorageQuota::ConfigurationError` rather than being rounded off.
+
+### Reads are advisory
+
+`storage_usage`, `storage_remaining` and the other read helpers describe the
+quota at the instant they run. They suit UI such as a usage bar, but must not be
+used as a check-then-act admission guard.
+
+Admission is enforced by the gem's write paths — attaching a file, and issuing
+a direct-upload URL — where the capacity test and the claim are one atomic
+statement.
+
+## Direct uploads
+
+Browser-to-storage direct uploads bypass your server, so the quota has to be
+checked when the browser asks for an upload URL. Subclass the gem's controller,
+say who pays, route to it, and point your file inputs at that route. The gem
+draws no routes of its own.
+
+```ruby
+# app/controllers/quota_direct_uploads_controller.rb
+class QuotaDirectUploadsController < ActiveStorageQuota::DirectUploadsController
+  include Authentication
+  before_action :authenticate!
+
+  private
+    def storage_quota_owner
+      Current.company
+    end
+end
+```
+
+```ruby
+# config/routes.rb
+post "/direct_uploads",
+  to: "quota_direct_uploads#create",
+  as: :quota_direct_uploads
+```
+
+```erb
+<%= form.file_field :documents,
+      multiple: true,
+      data: { direct_upload_url: quota_direct_uploads_url } %>
+```
+
+The `data-direct-upload-url` attribute is all `@rails/activestorage` looks for.
+Do not also pass `direct_upload: true`: Rails would then add a second
+`data-direct-upload-url` pointing at its own endpoint, which issues upload URLs
+without reserving quota.
+
+That is the whole setup. The response is Rails' own direct-upload JSON, so
+stock `@rails/activestorage` needs no custom JavaScript beyond using this
+endpoint — there is no reservation token and nothing of ours in blob metadata.
+Capacity is held against the owner's quota when the URL is issued, and becomes
+usage when the signed blob id is attached.
+
+### Authentication is yours
+
+`ActiveStorageQuota::DirectUploadsController` inherits Active Storage's
+controller, which descends from `ActionController::Base` — **not** from your
+`ApplicationController`. Its `before_action` filters do not run here. Sessions,
+cookies and CSRF protection all work normally.
+
+`storage_quota_owner` is therefore the authorization boundary, and your
+application must establish the authenticated tenant before it is trusted.
+Include your own authentication concern, as above.
+
+Returning `nil` from `storage_quota_owner`, or an object that does not declare
+`has_storage_quota`, raises. Those are wiring mistakes, not request outcomes,
+and the gem deliberately does not dress them up as a friendly 4xx.
+
+### When the quota is full
+
+```http
+409 Conflict
+{"error":"storage_quota_exceeded"}
+```
+
+409 rather than 413: the request is well formed and small — the file is not in
+it — but it conflicts with the account's current state, and the user can resolve
+it by freeing space and retrying. Override `quota_exceeded_status` in your
+subclass if you disagree. No quota figures are returned; stock
+`@rails/activestorage` discards error bodies and surfaces only the status.
+
+### Abandoned and retried uploads
+
+If the browser never uploads, or uploads but never attaches, the reservation is
+released by `ActiveStorageQuota.release_expired_reservations!` and the blob by
+Rails' own `active_storage:purge_unattached`. Two independent janitors; neither
+needs the other.
+
+A retried POST creates a second blob and a second hold, exactly as stock Active
+Storage creates a second blob. Both expire. `reservation_ttl` controls how long
+a duplicate or abandoned request holds capacity.
+
+Destroying an unattached blob releases any holds naming it immediately, since a
+destroyed blob can never be attached.
+
+### Cross-database limitation
+
+A quota refusal always rolls the blob back, because the exception propagates out
+of the blob's transaction — that holds whether or not the quota tables share a
+connection with Active Storage.
+
+What separate databases cannot guarantee is the reverse: if the reservation
+commits and an Active Storage-side operation then fails, the hold outlives the
+blob. It is recovered by the reservation TTL. The gem does not attempt
+distributed transactions or compensating deletes.
+
+### A note on `byte_size`
+
+`byte_size` originates from the direct-upload client. Whether the declared
+length is actually enforced depends on the Active Storage service adapter: S3
+binds it into the signed request and Disk verifies it against a signed token,
+both verified. Other adapters need their own analysis. This gem does not verify
+the stored object's physical size.
+
+## Maintenance
+
+Accounting is a denormalized ledger, so the gem ships tools to inspect and
+repair it. All of them are safe to run against production.
+
+```sh
+bin/rails active_storage_quota:audit            # read-only; writes nothing, ever
+ALL=1 bin/rails active_storage_quota:reconcile  # always a dry run; prints a plan
+bin/rails active_storage_quota:release_expired_reservations
+```
+
+`audit` reports drift without touching anything, and exits non-zero when it
+finds any, so it works as a cron or CI check. Repairs are a separate, explicitly
+named task:
+
+```sh
+OWNER_TYPE=Company OWNER_ID=1 bin/rails active_storage_quota:reconcile:apply
+```
+
+Both reconcile tasks take `OWNER_TYPE` and `OWNER_ID` for one owner, or `ALL=1`
+for every owner, and refuse to run given neither.
+
+Removing charges that nothing backs any more is destructive, so it only happens
+when you supply a budget (`MAX_CHARGE_DELETIONS` and `MAX_REMOVED_FRACTION` on
+the rake tasks), and a circuit breaker stops a run that would remove more than
+you allowed:
+
+```ruby
+ActiveStorageQuota.reconcile!(owner: company,
+                              max_charge_deletions: 10,
+                              max_removed_fraction: 0.25)
+```
+
+Reservations for uploads that were started and abandoned are released by
+`release_expired_reservations`; run it from cron, a recurring job, or whatever
+scheduler you already have. The gem does not ship one, and needs no Redis or
+Sidekiq.
+
+## Adopting active_storage_quota in an existing application
+
+An application that already stores files has historical attachments the gem
+knows nothing about. Backfill builds the initial ledger for them.
+
+The order matters. Backfill writes charges but deliberately does **not** write
+`used_bytes`, so counters understate the ledger until counter reconciliation
+runs. Enforcing quotas against incomplete counters would admit uploads that
+should have been refused, so enforcement stays off until the end.
+
+```
+1.  Install and run the migrations.
+
+2.  Declare the macros:
+
+      class Company < ApplicationRecord
+        has_storage_quota limit: ->(company) {
+          Adoption.enforcing?(company) ? company.plan_limit : nil
+        }
+      end
+
+      class Contract < ApplicationRecord
+        belongs_to :company
+        storage_quota_owner :company
+        has_many_attached :documents
+      end
+
+3.  Deploy with limits resolving to nil.
+    Accounting is now active for new uploads; enforcement is not.
+
+4.  See what backfill would do:
+      bin/rails active_storage_quota:backfill
+
+5.  Create the historical charges, repeating until complete:
+      ALL=1 bin/rails active_storage_quota:backfill:apply
+      CURSOR=<printed cursor> ALL=1 bin/rails active_storage_quota:backfill:apply
+
+6.  Establish the counters from the finished ledger:
+      ActiveStorageQuota.reconcile_counters!(owner: company)
+
+7.  Check the result:
+      bin/rails active_storage_quota:audit
+
+8.  Repair anything the audit flags as repairable:
+      ActiveStorageQuota.reconcile!(owner: company)
+
+9.  Resolve the report-only findings by hand: missing or invalid quota owners,
+    unresolvable record types, byte size mismatches.
+
+10. Switch limits to their real values, one tenant at a time.
+
+11. bin/rails active_storage_quota:audit   # expect it clean
+```
+
+`backfill:apply` refuses to start while any owner still has a real limit,
+precisely because step 6 has not happened yet. Pass
+`ALLOW_ACTIVE_ENFORCEMENT=1` only if you understand that consequence.
+
+### The one exception to the ledger invariant
+
+Normal operation always holds:
+
+```ruby
+account.used_bytes == account.charges.sum(:byte_size)
+```
+
+Backfill is the single sanctioned exception: between step 5 and step 6 charges
+exist that `used_bytes` does not yet reflect. This is safe only while limits
+resolve to nil, and step 6 closes it.
+
+## Troubleshooting
+
+### Rails 8.1 and json 3.x
+
+Some Rails 8.1 releases have a compatibility problem between ActiveSupport's
+JSON decoding, which Active Storage uses for blob metadata, and `json` 3.x.
+
+If Active Storage operations fail with an error like:
+
+```
+wrong number of arguments (given 2, expected 1)
+```
+
+pin the host application to:
+
+```ruby
+gem "json", "< 3"
+```
+
+This is an upstream Rails/json incompatibility, not something
+`active_storage_quota` causes or can fix, and it does not affect every Rails 8.1
+installation.
+
+## Known limitations
+
+- **`detach` is not observed.** Active Storage's `detach` and `purge` paths
+  delete attachment rows without firing callbacks, so a `detach` leaves a stale
+  charge. `bin/rails active_storage_quota:audit` reports it and reconciliation
+  repairs it. Purging is observed through the blob's destruction. Moving an
+  attachment to a different record (`attachment.update!(record: other)`) is not
+  observed either, and is repaired the same way.
+- **Replacing a `has_one_attached` file can briefly count both files.** Active
+  Storage creates the replacement attachment before removing the previous one,
+  so if the two files together exceed the remaining quota the replacement is
+  refused, even when the new file alone would fit. The previous file stays
+  attached and charged.
+- **Variants and previews are not counted.** Generated variant and preview
+  storage is not represented as an attachment owned by your quota-bearing
+  application record, so those generated bytes are not included in quota usage.
+- **Cross-database accounting is not atomic.** When the quota tables live on a
+  different connection from Active Storage, Rails cannot make the two writes one
+  transaction; accounting becomes eventually consistent and audit/reconciliation
+  are the guarantee.
+- **Direct-upload `byte_size` comes from the client.** Whether the declared
+  length is enforced depends on the storage adapter: S3 binds it into the signed
+  request and Disk verifies it against a signed token. Other adapters need their
+  own analysis.
+
+## Development
+
+```sh
+bin/setup                 # or: bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Against a specific Rails version:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rspec
+```
+
+Concurrency specs require PostgreSQL and are skipped on other adapters:
+
+```sh
+DATABASE_URL=postgres://localhost/asq_test bundle exec rspec
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/app/controllers/active_storage_quota/direct_uploads_controller.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ActiveStorageQuota
+  # A quota-aware replacement for Rails' direct-upload endpoint.
+  #
+  # Subclass it, say who pays, and point your direct uploads at it:
+  #
+  #   class QuotaDirectUploadsController < ActiveStorageQuota::DirectUploadsController
+  #     include Authentication
+  #     before_action :authenticate!
+  #
+  #     private
+  #       def storage_quota_owner
+  #         Current.company
+  #       end
+  #   end
+  #
+  #   post "/direct_uploads", to: "quota_direct_uploads#create"
+  #
+  # The gem draws no routes and replaces nothing: opting in is subclassing and
+  # routing. The browser contract is unchanged, so stock @rails/activestorage
+  # needs no modification beyond the endpoint URL -- there is no reservation
+  # token, and nothing of ours goes into blob metadata.
+  #
+  # Only +create+ is overridden. +blob_args+ differs between Rails 7.x
+  # (require/permit) and 8.x (params.expect) and +direct_upload_json+ defines the
+  # response contract, so both stay Rails' responsibility.
+  #
+  # ## Authentication
+  #
+  # This inherits ActiveStorage::BaseController, which descends from
+  # ActionController::Base -- *not* from the application's ApplicationController.
+  # Its before_action filters do not run here. Sessions and cookies do work, and
+  # CSRF protection is inherited unchanged.
+  #
+  # +storage_quota_owner+ is therefore the authorization boundary, and the
+  # application must establish the authenticated tenant before it is trusted.
+  class DirectUploadsController < ActiveStorage::DirectUploadsController
+    def create
+      # Resolved first: a wiring problem should cost nothing, least of all a
+      # stray blob row.
+      owner = resolved_storage_quota_owner
+
+      payload = ActiveStorage::Blob.transaction do
+        blob = ActiveStorage::Blob.create_before_direct_upload!(**blob_args)
+
+        owner.reserve_storage!(blob.byte_size, blob: blob)
+
+        # Built inside the transaction on purpose. Signing the upload URL can
+        # fail, and doing it here means such a failure rolls back the blob and
+        # the reservation rather than leaving either behind.
+        direct_upload_json(blob)
+      end
+
+      render json: payload
+    rescue ActiveStorageQuota::QuotaExceeded
+      render json: { error: "storage_quota_exceeded" }, status: quota_exceeded_status
+    end
+
+    private
+      # The quota owner charged for this upload. Host applications override it.
+      def storage_quota_owner
+        raise NotImplementedError,
+              "#{self.class.name} must define #storage_quota_owner, returning the " \
+              "record that declares has_storage_quota and pays for this upload"
+      end
+
+      # 409 Conflict: the request is well formed, but it conflicts with the
+      # account's current state, and the user can resolve it by freeing space and
+      # resubmitting. 413 would claim the request body was too large, which it is
+      # not -- the file is not in this request.
+      def quota_exceeded_status
+        :conflict
+      end
+
+      def resolved_storage_quota_owner
+        owner = storage_quota_owner
+
+        if owner.nil?
+          raise MissingQuotaOwner.new(
+            "#{self.class.name}#storage_quota_owner returned nil. Authenticate " \
+            "before this point: a missing owner is a wiring problem, not an " \
+            "expected request outcome."
+          )
+        end
+
+        unless owner.respond_to?(:reserve_storage!)
+          raise ConfigurationError,
+                "#{self.class.name}#storage_quota_owner returned " \
+                "#{owner.class.name}, which does not declare has_storage_quota"
+        end
+
+        owner
+      end
+  end
+end

data/db/migrate/20260917000001_create_active_storage_quota_tables.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+class CreateActiveStorageQuotaTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :active_storage_quota_accounts do |t|
+      # Polymorphic owner.
+      #
+      # owner_id is a string, not a bigint, so that owners keyed by bigint,
+      # UUID, ULID or any other primary key type can coexist in one
+      # application. Active Record casts transparently in both directions:
+      # an Integer id of 1 is written and queried as '1'.
+      #
+      # The cost is that ad-hoc SQL joining back to the owner needs a cast
+      # (`JOIN companies c ON c.id::text = a.owner_id`). The gem itself never
+      # joins here; it looks accounts up by owner and loads the owner through
+      # the polymorphic association.
+      #
+      # Column limits keep this unique index inside InnoDB's 3072-byte key
+      # limit for MySQL users: (255 + 255 + 100) * 4 bytes = 2440.
+      t.string :owner_type, null: false, limit: 255
+      t.string :owner_id,   null: false, limit: 255
+
+      # Quota accounts are keyed by owner *and* scope so that named scopes
+      # ("legal", "crm", ...) can be added later without rebuilding this unique
+      # index on a live table. Nothing writes a value other than "default" yet.
+      t.string :scope_name, null: false, limit: 100, default: "default"
+
+      # Committed and in-flight byte counters. bigint because a 32-bit counter
+      # overflows at 2GB.
+      t.bigint :used_bytes,     null: false, default: 0
+      t.bigint :reserved_bytes, null: false, default: 0
+
+      t.timestamps
+
+      t.index %i[owner_type owner_id scope_name],
+              unique: true, name: "index_asq_accounts_on_owner_and_scope"
+
+      # A counter going negative means a reservation was released twice. Fail
+      # loudly at the database rather than silently handing back free quota.
+      t.check_constraint "used_bytes >= 0",
+                         name: "asq_accounts_used_bytes_non_negative"
+      t.check_constraint "reserved_bytes >= 0",
+                         name: "asq_accounts_reserved_bytes_non_negative"
+    end
+
+    create_table :active_storage_quota_reservations do |t|
+      t.references :quota_account, null: false, index: false,
+                   foreign_key: { to_table: :active_storage_quota_accounts }
+
+      t.bigint :byte_size, null: false
+
+      # active -> committed | released. Terminal rows are kept: they make commit
+      # idempotent under job retries and double as the audit log for an account.
+      t.string :status, null: false, limit: 20, default: "active"
+
+      # A hard expiry. commit! guards on `expires_at > :now` and the sweeper on
+      # `expires_at <= :now` -- exact complements, so at any instant an active
+      # row is claimable by exactly one of them.
+      t.datetime :expires_at, null: false
+
+      t.timestamps
+
+      # Per-account lookups: reconciling reserved_bytes against active rows.
+      t.index %i[quota_account_id status]
+      # The sweeper's only query.
+      t.index %i[status expires_at]
+
+      t.check_constraint "byte_size >= 0",
+                         name: "asq_reservations_byte_size_non_negative"
+    end
+  end
+end