bouncy 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3caefdf93f208340d8314a9d2f6f7736079471f539651818f202591daf9840f
-  data.tar.gz: e6704bc8c6b3a1adc0961bd13eb34070ce797960037b18efc0f5d9dd5095b86a
+  metadata.gz: 25620e7678f2db3d1aeae8f633654ae92205277b171eea5bddbbd3c3d4d898e1
+  data.tar.gz: f898b5f8180190136a031469ca2a6bd62f4930929378afedd0cae4d3f9a19f4a
 SHA512:
-  metadata.gz: b61276efe0533445572e0cef61645ff54783d69ee68b334225c3f989fda2534e0e36dbcc6dd08711f169e6ddfdb1c421ce47e0f1f297e4097760f9601c368dbe
-  data.tar.gz: 53d8d0c1c56f8391c1ea3d29bee91bf10f262b2d71490c128cddfde1f81cbd26bfa255a17a6b061ec30ba82f4b150066a8e451219a8fa6d3ea0b1f268657639b
+  metadata.gz: d9ebee34cdc50548f939a80ab07cfc3e26cd0284d0c46f5b608f032dd8b41b9b92d7e5101a77b2d7b0107d8fd977aaa2f58da8e822b580362692900f1fd345d2
+  data.tar.gz: 16c591e6c5e1d51d08bd34d8273a2afbc9d08e605f30520635e509b5519104e3b1f13917a740378e88106e3890ef8743606756117a0338087b11a8ee48f5fff1

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-25
+
+Three gaps that the first app to move its own suppression table to Bouncy found. There is no new migration.
+
+### Added
+
+- `Bouncy.import!(email, reason:, at:, note: nil, actor: nil)` records a block that another system recorded, with its reason (`:hard_bounce`, `:complaint` or `:manual`) and its time, as one `imported` event; it calls no hook, writes nothing when it repeats, never weakens a block in force and changes nothing after a later release, because an app that carried its old suppressions had to call the internal `Bouncy::Ingestor`, which treats each call as new webhook feedback. `Bouncy::Ingestor` keeps its 0.2.0 call shape and is now marked internal.
+- `Status#blocked_at` is the time the block in force began (for an import, its `at:` time) and `nil` when the address is not blocked, because an app that shows "not deliverable since" had to read the suppression row itself; a block that follows an expired soft hold now starts at its own time, not at the soft hold's.
+
+### Changed
+
+- The 90-day freshness rule (`config.maximum_event_age`) applies to webhook feedback only, not to imports or manual holds, because it exists to stop a late notification from blocking, while a block that another system kept for a year is still a block: an import dated a year ago drops mail, and a webhook bounce dated a year ago still does not.
+
 ## [0.2.0] - 2026-10-25
 
 Eight features that apps need to replace a hand-rolled SES integration with Bouncy. There is no new migration: the address lock uses database locks, not a column.

data/README.md

@@ -131,6 +131,7 @@ status.knowledge        # :observed, :no_known_block, :unavailable, :unconfigure
 status.provider_listed?  # Exact provider identifiers are present locally
 status.policy_reason    # Why a listed address's sending policy is unverified
 status.stale?           # Address observation is missing or older than stale_after
+status.blocked_at       # When the block in force began, or nil when not blocked
 
 Bouncy.blocked
 Bouncy.events.for("ada@example.com").recent.limit(20)
@@ -196,6 +197,16 @@ Bouncy.release!(address, note: "Verified recovery", actor: "support:42")
 
 Default release removes exact provider variants and verifies absence before clearing local state. Errors leave evidence available for review. Releasing an SES restriction can affect sister apps in that account and region; authorize the action in your app. Release does not resend mail or restore consent after a complaint. See [recovery and partial failures](guides/recovery.md).
 
+### Carry blocks from another system
+
+An app that moves its own suppression table to Bouncy carries each block with its reason and the time the old table recorded it:
+
+```ruby
+Bouncy.import!(address, reason: :hard_bounce, at: old_row.suppressed_at, note: "Carried from the old table", actor: "carry-task")
+```
+
+`reason` is `:hard_bounce`, `:complaint` or `:manual`. A bounce or a complaint is the same evidence as a webhook block, and a manual block is a manual hold. `at` can be of any age: the 90-day window for late webhook feedback does not apply. The import calls no hook, writes nothing when it repeats, never weakens a block in force, and changes nothing when the address was released after `at`, so a carry task is safe to run again. See [migrating](guides/migrating.md).
+
 Use any admin UI. Bouncy has **no Madmin dependency, generator or adapter**. The [admin recipe](guides/admin.md) covers host-owned recovery actions, badges and notifications.
 
 ### Handle repeated mailbox-full bounces

data/guides/api.md

@@ -20,6 +20,7 @@ Bouncy.blocked?("ada@example.com") # Same as status.blocked?
 | `record` | Underlying `Bouncy::Suppression`, or `nil`, for host-owned admin links. |
 | `provider_listed?` | Exact provider entries exist in the local mirror, even if policy verification has not made them enforceable. |
 | `provider_updated_at` | Latest update time among those provider entries, or `nil`. |
+| `blocked_at` | Time the block in force began: when the address became blocked locally, or the `at:` time of the `Bouncy.import!` that blocked it. Stays while further evidence arrives; a block after an expired soft hold starts anew. `nil` when not blocked. |
 | `observed_at` | Provider check time if present, otherwise the last address event time, or `nil`. |
 | `stale?` | True for unavailable/unconfigured knowledge, missing observation time or an observation older than `stale_after`. This is address freshness; use `Bouncy.sync_fresh?` for mirror health. |
 | `policy_unverified?` | A locally listed address whose latest scoped sync did not report verified sending policy. |
@@ -81,6 +82,7 @@ The override applies to status and predicates as well as scopes. Your app must p
 | `Bouncy.blocked` | Scoped ActiveRecord relation of currently restricted suppression rows. |
 | `Bouncy.events` | Scoped event relation; chain `.for(address).recent.limit(50)`. |
 | `Bouncy.block!(address, note:, actor: nil)` | Add a local manual hold; a nonblank note is required. Returns the suppression row. Does not call SES. |
+| `Bouncy.import!(address, reason:, at:, note: nil, actor: nil)` | Record a block that another system recorded at `at`, with `reason` `:hard_bounce`, `:complaint` or `:manual`. Returns the suppression row. Does not call SES. See [imports](#imports). |
 | `Bouncy.release!(address, note: nil, actor: nil, at: :provider)` | Provider-aware release by default, requiring a note and verified provider snapshot. Returns the row; may raise on partial remote success. |
 | `Bouncy.release!(address, at: :local)` | Clear manual and soft holds and their soft-bounce history; fence delayed pre-release soft feedback and preserve provider/webhook blocks. No provider request. A note is optional. |
 | `Bouncy.forget!(address)` | Delete local state and events, including release metadata; no provider mutation. A later sync can reimport the address. |
@@ -94,6 +96,23 @@ The override applies to status and predicates as well as scopes. Your app must p
 | `Bouncy.unblocked { ... }` | Temporarily bypass interception for synchronous delivery in this execution context. Does not travel with queued jobs. |
 | `Bouncy.hold(address) { ... }` | Hold the address while the block runs, and inside a transaction until it ends, so no Bouncy write to it commits between the app's own check and its send. Returns the block's value. See [a sender that checks and sends](delivery.md#a-sender-that-checks-and-sends-in-one-step). |
 
+## Imports
+
+`Bouncy.import!` carries a block from another system, such as the suppression table an app kept before Bouncy. `Bouncy.block!` stays a support action: it holds the address now, needs a note and calls `after_block`. An import records what another system already knew:
+
+```ruby
+Bouncy.import!("ada@example.com", reason: :complaint, at: Time.utc(2025, 3, 1), note: "Carried from the old table", actor: "carry-task")
+```
+
+- A `:hard_bounce` or `:complaint` becomes the same evidence as a webhook block. It drops mail under the same rule (a fresh sync, or `require_fresh_sync = false`), and a sync clears it under the same [absence rule](amazon-ses.md#failure-and-ordering) as webhook evidence. A `:manual` block becomes a manual hold, which applies whatever the sync state and only a release clears.
+- `at` is the time the other system recorded the block, a `Time` or `DateTime` of any age: `maximum_event_age` applies to webhook feedback only. A time more than five minutes ahead raises `ArgumentError`. It becomes `Status#blocked_at` unless the address was blocked earlier.
+- It writes one `imported` event (source `import`, occurred at `at`) and calls no hook: not `after_event`, `after_block` or `on_notification`. It is not new evidence.
+- The same address, reason and time again writes nothing. So does an import that the address already holds.
+- It never weakens a block in force. A complaint outranks a hard bounce, an earlier hold keeps its time and note, and provider evidence and soft holds stay as they are.
+- A release at or after `at` fences it: the import records an `imported` event with `ignored_for_policy` and changes nothing. A newer block applies.
+
+`Bouncy::Ingestor` and `Bouncy::Observation` are internal: they record webhook feedback. Their 0.2.0 call shape still works in 0.2.x, but carry blocks with `Bouncy.import!`.
+
 ## SES notifications
 
 `config.on_notification` receives a `Bouncy::Notification` for every SES notification on an authorized topic, Send and Delivery included:
@@ -126,4 +145,4 @@ All gem errors inherit from `Bouncy::Error`:
 | `AuthenticationError` | SNS authorization/signature failure. |
 | `MalformedMessage` | Invalid SNS input. |
 
-Missing support notes, unsupported release destinations and `Bouncy.hold` without a block raise `ArgumentError`. An address lock that waits too long raises `ActiveRecord::LockWaitTimeout`. Rails/database errors not recognized as connection outages are not silently swallowed. A successful local database transaction does not make remote provider operations atomic. Never display a recovery success message from a rescue branch.
+Missing support notes, unsupported release destinations, an import reason or time that is not supported, and `Bouncy.hold` without a block raise `ArgumentError`. An address lock that waits too long raises `ActiveRecord::LockWaitTimeout`. Rails/database errors not recognized as connection outages are not silently swallowed. A successful local database transaction does not make remote provider operations atomic. Never display a recovery success message from a rescue branch.

data/guides/configuration.md

@@ -28,7 +28,7 @@ Replace the examples with your actual deployment. Set `all_sending_paths_listed`
 | `webhook_blocking` | `:cautious` with `require_fresh_sync`, `:strict` without | Which notifications block. `:cautious` blocks General/NoEmail bounces and complaints naming one recipient; the sync covers the rest. `:strict` blocks every Permanent bounce and every recipient a complaint names. See [bounce handling](bounce-handling.md#ses-event-classification). |
 | `record_deliveries` | `false` | Record normalized per-recipient SES Delivery events when enabled and routed to the topic. Server acceptance is not inbox placement. |
 | `retention` | `90.days` | Delete events older than this by local creation time when the prune job runs. Does not delete state rows. |
-| `maximum_event_age` | `90.days` | Feedback older than this cannot apply a new restriction. Retention must be at least this long; both must be positive. |
+| `maximum_event_age` | `90.days` | Webhook feedback older than this cannot apply a new restriction. `Bouncy.import!` and `Bouncy.block!` do not use it. Retention must be at least this long; both must be positive. |
 | `soft_bounce_threshold` | `nil` | Record-only by default. An integer from 1 to 50 enables escalation for repeated `MailboxFull` bounces. |
 | `soft_bounce_window` | `30.days` | Positive rolling window of eligible occurrence times. |
 | `soft_bounce_block_for` | `30.days` | Positive duration of the temporary local hold triggered by escalation. |

data/guides/delivery.md

@@ -32,7 +32,7 @@ Order.transaction do
 end
 ```
 
-`Bouncy.hold` takes a shared lock for the address. Every Bouncy write to that address (webhook, sync, `block!`, `release!`) takes it exclusively first, before any row lock, until its own transaction ends. A new block therefore commits before the check or after the send. Inside a transaction the hold lasts until that transaction ends, so the outcome commits before the block. Take your own row locks before the hold, as above.
+`Bouncy.hold` takes a shared lock for the address. Every Bouncy write to that address (webhook, sync, `block!`, `import!`, `release!`) takes it exclusively first, before any row lock, until its own transaction ends. A new block therefore commits before the check or after the send. Inside a transaction the hold lasts until that transaction ends, so the outcome commits before the block. Take your own row locks before the hold, as above.
 
 | Database | Lock | Two senders to one address |
 |---|---|---|

data/guides/migrating.md

@@ -3,12 +3,13 @@
 Migration and cutover belong in the implementing app. Bouncy's install migration creates its own two tables; it does not inspect application models or silently replace an existing webhook/interceptor.
 
 1. Inventory every existing writer: webhook controllers, jobs, support actions, interceptors and console operations. Record the source account, region, reason mapping, timestamps and existing soft-hold policy.
-2. Install the additive schema. Write a host data migration using migration-local ActiveRecord classes or explicit SQL pinned to that schema. Never call live Bouncy/host models, callbacks, jobs or AWS from a historical migration.
-3. Preserve manual holds independently. Map complaints as complaints and hard bounces as hard bounces. Account-list refusal is evidence of an existing restriction. Soft trackers are history; active legacy soft holds require an explicit preserved policy, not an accidental new threshold engine. Preserve original expiries for timed soft holds. Preserve indefinite holds as explicit manual holds with a migration note; do not invent a 30-day expiry. New escalation applies only to mailbox-specific evidence. Document that change if the old rule included content failures.
-4. Use stable source IDs to make imported events idempotent. Preserve known provider feedback IDs using Bouncy's recipient-level dedupe identity so retried historical feedback does not count again. Preserve distinct occurrences, exact provider addresses when available, and relevant event times. Missing historical case variants are resolved by complete provider enumeration before recovery.
-5. Rehearse the import against isolated synthetic fixtures. Compare every predicate, support action and customer-facing status that depended on the old table. Rehearse bootstrap as part of this isolated cutover sequence.
-6. Quiesce old writers for cutover, or implement and test dual-write delivery with deterministic identity. Perform the final import, switch the receiver/readers, then run `bouncy:bootstrap` before starting mail workers. It raises unless the mirror is fresh, complete and policy-verified. Ensure feedback received during the switch is retried or durably captured. Do not replace readers while another process continues writing exclusively to the old table.
-7. Rehearse rollback, including restrictions and releases created after cutover. Keeping an old table is not a rollback plan if it missed later changes. Keep old schema until the agreed window ends. Do not delete imported rows in a schema rollback: they may now contain newer state. Fail conflicting imports and stop writers before copying in either direction.
+2. Install the additive schema. Never call live Bouncy/host models, callbacks, jobs or AWS from a historical migration. Carry the blocks from a task instead (step 3); a migration that reads the old table uses migration-local ActiveRecord classes or explicit SQL pinned to its schema.
+3. Preserve manual holds independently. Map complaints as complaints and hard bounces as hard bounces. Carry each block with `Bouncy.import!(address, reason:, at:, note:, actor:)`, with `reason` `:hard_bounce`, `:complaint` or `:manual` and `at` the time the old table recorded it. Do not call `Bouncy::Ingestor`: it records webhook feedback, and feedback older than `maximum_event_age` blocks nothing. An import applies at any age and calls no hook. Run it from a task that you can run again, not from a historical migration: a repeat writes nothing, and an address released after `at` stays released. Account-list refusal is evidence of an existing restriction. Soft trackers are history; active legacy soft holds require an explicit preserved policy, not an accidental new threshold engine. Preserve original expiries for timed soft holds. Preserve indefinite holds as explicit manual holds with a migration note; do not invent a 30-day expiry. New escalation applies only to mailbox-specific evidence. Document that change if the old rule included content failures.
+4. `Bouncy.import!` identifies a block by four values: the normalized address (trimmed and lowercased), the configured scope, the reason, and `at` truncated to microseconds. A call that repeats all four writes nothing, so the old table needs no source ID of its own: read `at` from it unchanged, and a second run of the task writes nothing. A different reason or time is a different block, and the same values in another scope are an independent block. An import takes no provider feedback ID and counts no occurrences: carry the blocks in force, not each historical event. Pass the address as the old table spells it; for a bounce or a complaint, Bouncy keeps that spelling for the sync's provider lookups. Missing historical case variants are resolved by complete provider enumeration before recovery.
+5. Historical webhook feedback is a separate matter, and an import makes a replay unnecessary: it carries what that feedback decided. Bouncy has no public call to replay old notifications. Do not feed them to `Bouncy::Ingestor`: it is internal, and it records feedback older than `maximum_event_age` without blocking. Feedback that arrives during the switch reaches the receiver, which deduplicates each recipient by the provider's feedback ID, so SNS retries count once.
+6. Rehearse the import against isolated synthetic fixtures. Compare every predicate, support action and customer-facing status that depended on the old table. Rehearse bootstrap as part of this isolated cutover sequence.
+7. Quiesce old writers for cutover, or implement and test dual-write delivery with deterministic identity. Perform the final import, switch the receiver/readers, then run `bouncy:bootstrap` before starting mail workers. It raises unless the mirror is fresh, complete and policy-verified. Ensure feedback received during the switch is retried or durably captured. Do not replace readers while another process continues writing exclusively to the old table.
+8. Rehearse rollback, including restrictions and releases created after cutover. Keeping an old table is not a rollback plan if it missed later changes. Keep old schema until the agreed window ends. Do not delete imported rows in a schema rollback: they may now contain newer state. Fail conflicting imports and stop writers before copying in either direction.
 
 Use the app's existing public webhook URL where possible. Test routing alongside unrelated webhooks, and preserve the existing interception mode deliberately. Host admin resources call Bouncy's recovery API; stock row deletion cannot stand in for provider release.
 

data/guides/operations.md

@@ -78,7 +78,7 @@ Bouncy.configure do |config|
 end
 ```
 
-Implement the example jobs in the host. Callbacks receive a committed `Bouncy::Event`. `after_event` runs for every newly created event, including sync summaries and interception observations. `after_block` runs when `details["became_blocked"]` is true, not for every repeated bounce. `after_release` runs for explicit `release` events, including local-only releases; it does not run for `sync_released`. Use `after_event` with a kind check if you need to observe reconciliation releases.
+Implement the example jobs in the host. Callbacks receive a committed `Bouncy::Event`. `after_event` runs for every newly created event, including sync summaries and interception observations, except `imported` events: `Bouncy.import!` calls no hook. `after_block` runs when `details["became_blocked"]` is true, not for every repeated bounce. `after_release` runs for explicit `release` events, including local-only releases; it does not run for `sync_released`. Use `after_event` with a kind check if you need to observe reconciliation releases.
 
 These hooks are best effort. Exceptions emit `hook_error.bouncy` with `hook` and `error_class`, and do not undo the event. They run after the commit of the outermost transaction, after Bouncy released every address lock of it, and, for a write inside `Bouncy.hold`, when the hold ends. A rollback drops them. Rails transactional tests keep 0.1's timing. Bouncy marks the fixture transaction of each pool that `ActiveRecord::TestFixtures` enrolls, as listed in its own `@fixture_connection_pools`: at `setup_transactional_fixtures`, and for a pool established later from a `!connection.active_record` subscriber that runs after Rails' own. It clears the marks in `teardown_transactional_fixtures` (Rails 7.2, 8.0 and 8.1). While a marked transaction is the only one open, hooks run when the app's own transaction commits. A database excluded with `skip_transactional_tests_for_database` (Rails 8.1), or a connection pinned in any other way, keeps the outer-commit rule. A process can stop after commit before notification completes. Use idempotent consumers and a host outbox/reconciliation mechanism for guaranteed external work. Jobs should tolerate an event being pruned before execution.
 

data/guides/privacy.md

@@ -2,7 +2,7 @@
 
 Bouncy stores the normalized address, exact provider identifiers, reasons, event IDs/times, bounded provider diagnostics, support notes and actor references. Those fields can contain personal information. Raw payloads, subjects, bodies and attachments are not stored by this release.
 
-Default event retention is 90 days, measured from local event creation (`created_at`), not provider occurrence time. Schedule `Bouncy::PruneJob` daily; no pruning happens merely by configuring retention. Retention must cover `maximum_event_age`. Feedback older than that acceptance window can be recorded for diagnostics without applying a new restriction, then ages out under normal pruning. Current state and release ordering metadata survive event pruning.
+Default event retention is 90 days, measured from local event creation (`created_at`), not provider occurrence time. Schedule `Bouncy::PruneJob` daily; no pruning happens merely by configuring retention. Retention must cover `maximum_event_age`. Webhook feedback older than that acceptance window can be recorded for diagnostics without applying a new restriction, then ages out under normal pruning. A block carried with `Bouncy.import!` is not feedback and applies at any age. Current state and release ordering metadata survive event pruning.
 
 `Bouncy.forget!(address)` erases local state and events in the configured scope. It does not change the provider list. A subsequent sync or eligible notification can create state again, and erasure also removes local release fences. It is not a complete legal/compliance workflow or a provider recovery action.
 

data/guides/recovery.md

@@ -10,7 +10,7 @@ Bouncy obtains a complete supported-scope snapshot, finds the exact provider var
 
 A partial provider operation raises `Bouncy::ReleaseFailed`. Inspect `error.outcomes` or the `release_failed` event: some variants may have been removed while another failed. Local provider evidence remains blocked until a successful recovery/reconciliation. Remote calls cannot be rolled back with your database transaction.
 
-Inactive rows retain a release-time fence. Older feedback and stale snapshots cannot simply reapply the released evidence. A genuinely newer failure can block the address again. Provider changes after a completed observation remain possible; this is not a permanent deliverability guarantee.
+Inactive rows retain a release-time fence. Older feedback, stale snapshots and imports dated before the release cannot simply reapply the released evidence. A genuinely newer failure can block the address again. Provider changes after a completed observation remain possible; this is not a permanent deliverability guarantee.
 
 ## Local holds
 

data/lib/bouncy/event.rb

@@ -9,7 +9,8 @@ module Bouncy
     scope :for, ->(email) { where(email: Identity.normalize(email)) }
     scope :recent, -> { order(occurred_at: :desc, id: :desc) }
 
-    after_create_commit :notify_host
+    # An import is not new evidence, so it calls no hook.
+    after_create_commit :notify_host, unless: -> { kind == "imported" }
 
     private
 

data/lib/bouncy/importer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Records a block that another system recorded first, for Bouncy.import!.
+  #
+  # A bounce or a complaint becomes the same evidence that a webhook records, and a manual block
+  # becomes a manual hold. The time is the time the other system recorded the block. It is kept
+  # as given, however old: config.maximum_event_age is for webhook feedback that arrives late,
+  # and an old block that another system kept still stops mail.
+  #
+  # An import is not new evidence, so it calls no hook. It is idempotent: the same address,
+  # reason and time a second time writes nothing. It never removes or weakens a block that is
+  # in force, and a release recorded at or after its time fences it.
+  class Importer
+    REASONS = %w[hard_bounce complaint manual].freeze
+    FUTURE_SKEW = 5.minutes
+    # The attributes that an import can change. A difference in them is a change to record.
+    CHANGES = %w[manual_blocked_at manual_note event_blocked_at event_reason last_event_at blocked_at details].freeze
+
+    def call(email, reason:, at:, note:, actor:)
+      reason = reason.to_s
+      raise ArgumentError, "reason must be :hard_bounce, :complaint or :manual" unless REASONS.include?(reason)
+
+      time = time_of(at)
+      exact = email.to_s.strip
+      key = Identity.normalize(email)
+      dedupe_key = Digest::SHA256.hexdigest(JSON.generate(["import", Bouncy.scope, key, reason, time.iso8601(6)]))
+      Store.change(key) do |row|
+        next row if Bouncy.events.exists?(dedupe_key: dedupe_key)
+
+        record(row, reason, time, dedupe_key, exact: exact, note: note.to_s.strip.truncate(1000).presence,
+                                              actor: actor.to_s.truncate(200))
+      end
+    end
+
+    private
+
+    def record(row, reason, time, dedupe_key, exact:, note:, actor:)
+      was_blocked = row.blocked?
+      released_at = fence(row, reason)
+      fenced = !released_at.nil? && time <= released_at
+      unless fenced
+        before = row.attributes.slice(*CHANGES).deep_dup
+        reason == "manual" ? hold(row, time, note) : feedback(row, reason, time, exact)
+        row.blocked_at = [row.blocked_at, time].compact.min
+        return row if row.attributes.slice(*CHANGES) == before
+
+        row.summarize!
+      end
+      Store.event!("imported", email: row.email, source: "import", occurred_at: time, dedupe_key: dedupe_key, details: {
+                     "reason" => reason, "note" => note, "actor" => actor,
+                     "ignored_for_policy" => fenced, "became_blocked" => !was_blocked && row.blocked?
+                   })
+      row
+    end
+
+    # A release clears manual holds and records "soft_released_before". A provider release, or a
+    # sync that no longer finds webhook evidence, clears it and records released_before. An
+    # imported block at or before that time is older than the release, so it changes nothing.
+    def fence(row, reason)
+      return row.released_before unless reason == "manual"
+
+      Time.iso8601(row.details["soft_released_before"].to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # Keeps an earlier hold and its support note.
+    def hold(row, time, note)
+      return if row.manual_blocked_at && row.manual_blocked_at <= time
+
+      row.manual_note = note unless row.manual_blocked_at
+      row.manual_blocked_at = time
+    end
+
+    # Webhook evidence keeps the time of its newest block and the stronger reason: a complaint
+    # outranks a hard bounce, so an imported hard bounce never replaces a complaint.
+    def feedback(row, reason, time, exact)
+      previous = row.event_reason if row.event_blocked_at
+      return if previous == reason && row.event_blocked_at >= time
+      return if previous == "complaint" && row.event_blocked_at >= time
+
+      row.event_reason = previous == "complaint" ? "complaint" : reason
+      row.event_blocked_at = [row.event_blocked_at, time].compact.max
+      row.last_event_at = [row.last_event_at, time].compact.max
+      row.details = row.details.except("absence_count").reverse_merge("exact_email" => exact)
+    end
+
+    # Microsecond precision, as every supported database stores it, so a second import of the
+    # same time compares and deduplicates as equal.
+    def time_of(value)
+      raise ArgumentError, "at must be a Time" unless value.is_a?(Time) || value.is_a?(DateTime)
+
+      time = value.to_time.utc.floor(6)
+      raise ArgumentError, "at must not be in the future" if time > FUTURE_SKEW.from_now
+
+      time
+    end
+  end
+end

data/lib/bouncy/ingestor.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module Bouncy
+  # Internal: one webhook observation for Ingestor. See Ingestor.
   Observation = Data.define(:email, :kind, :provider_event_id, :message_id, :occurred_at, :details, :provider_reason, :status_code, :diagnostic)
 
+  # Internal: the receiver's step for one webhook observation. It is not a public API. Use
+  # Bouncy.import! to record a block from another system. The call shape of Ingestor#call and
+  # Observation stays the same in 0.2.x, because apps on 0.2.0 call them to carry blocks.
+  #
+  # config.maximum_event_age applies here only. It keeps a late webhook notification from
+  # blocking. Bouncy.import! and Bouncy.block! do not apply it.
   class Ingestor
     def call(observation)
       email = observation.email && Identity.normalize(observation.email)

data/lib/bouncy/status.rb

@@ -29,6 +29,9 @@ module Bouncy
     def blocked? = @row ? @row.blocked? : false
     def reasons = @row ? @row.reasons : []
     def reason = (%i[complaint hard_bounce provider_list manual soft_bounces] & reasons).first
+    # The time the block in force began: when the address became blocked here, or the at: time
+    # of the Bouncy.import! that blocked it. nil when the address is not blocked.
+    def blocked_at = blocked? ? @row.blocked_at : nil
     def observed_at = @row&.provider_checked_at || @row&.last_event_at
     def provider_updated_at = @row&.provider_entries&.filter_map { |entry| Time.iso8601(entry.fetch("provider_updated_at")) }&.max
     def last_event = @row && Bouncy.events.for(@row.email).recent.first

data/lib/bouncy/store.rb

@@ -17,7 +17,11 @@ module Bouncy
           row = Suppression.find_or_create_by!(scope: Bouncy.scope, email: key) do |record|
             record.provider = Bouncy.configuration.provider.to_s
           end
-          row.with_lock { yield row }
+          row.with_lock do
+            # A soft hold that ran out leaves its start in blocked_at. The next block starts anew.
+            row.blocked_at = nil unless row.blocked?
+            yield row
+          end
         end
       rescue ActiveRecord::RecordNotUnique, ActiveRecord::StaleObjectError, ActiveRecord::Deadlocked
         attempts += 1

data/lib/bouncy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bouncy
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/bouncy.rb

@@ -48,7 +48,7 @@ module Bouncy
     # True when config.scope is set. An unconfigured Bouncy is inactive: it intercepts nothing,
     # reports no restrictions and returns empty relations, so a host can install the gem before
     # its environment variables exist without breaking mail delivery. Explicit operations
-    # (sync!, block!, release!, forget!) still raise ConfigurationError.
+    # (sync!, block!, import!, release!, forget!) still raise ConfigurationError.
     def configured? = configuration.configured?
 
     def unconfigured!(operation)
@@ -132,6 +132,14 @@ module Bouncy
       end
     end
 
+    # Records a block that another system recorded at the time at, for an app that moves its own
+    # suppression table to Bouncy. reason is :hard_bounce, :complaint or :manual. A bounce or a
+    # complaint is the same evidence as a webhook block; a manual block is a manual hold. The
+    # time can be of any age. The import calls no hook, writes nothing when it repeats, never
+    # weakens a block in force, and changes nothing when a release came at or after its time.
+    # Returns the suppression row. Does not call the provider.
+    def import!(email, reason:, at:, note: nil, actor: nil) = Importer.new.call(email, reason: reason, at: at, note: note, actor: actor)
+
     def forget!(email)
       current_scope = scope
       key = Identity.normalize(email)
@@ -205,6 +213,7 @@ require_relative "bouncy/providers/ses"
 require_relative "bouncy/providers/ses_parser"
 require_relative "bouncy/notification"
 require_relative "bouncy/ingestor"
+require_relative "bouncy/importer"
 require_relative "bouncy/recovery"
 require_relative "bouncy/scope_lock"
 require_relative "bouncy/reconciler"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bouncy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - rameerez
@@ -82,6 +82,7 @@ files:
 - lib/bouncy/engine.rb
 - lib/bouncy/event.rb
 - lib/bouncy/identity.rb
+- lib/bouncy/importer.rb
 - lib/bouncy/ingestor.rb
 - lib/bouncy/interceptor.rb
 - lib/bouncy/model.rb