cloudflare-email 0.2.0 → 0.4.0

data/docs/routing-deliveries.md

@@ -0,0 +1,94 @@
+# Confirm delivery to verified Routing destinations
+
+Cloudflare can deliver mail to a verified Email Routing destination through Routing without producing an Email Sending delivery callback. You can keep using the recipient's normal address. Do not remove its verified destination or rewrite the recipient to obtain a callback.
+
+The optional Routing Analytics integration confirms **positive delivery to the receiving mail server** from authenticated Cloudflare analytics. It does not prove inbox placement or that a person read the message. Missing analytics leave the outcome unresolved; they never authorize a resend or provider fallback.
+
+## Enable it
+
+The plain Ruby client needs no Rails or Active Record dependency:
+
+```ruby
+require "cloudflare/email/routing_analytics"
+
+client = Cloudflare::Email::RoutingAnalytics::Client.new(
+  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
+  zone_id: ENV.fetch("CLOUDFLARE_ANALYTICS_ZONE_ID"),
+  api_token: ENV.fetch("CLOUDFLARE_ANALYTICS_TOKEN")
+)
+client.verify_account!
+```
+
+Use a separate token with **Zone Analytics Read and Zone Read**, restricted to the sending zone. The client verifies that the zone belongs to the supplied account before querying analytics. Keep sending and queue credentials separate. A token is never written into a receipt.
+
+For durable Rails tracking, install the outbox first, then generate the additional receipt table:
+
+```sh
+bin/rails generate cloudflare:email:outbox # only if not already installed
+bin/rails generate cloudflare:email:routing_tracking
+bin/rails db:migrate
+```
+
+Receipts encrypt their JSON evidence using Rails Active Record Encryption. Configure the application's `active_record.encryption.primary_key`, `deterministic_key`, and `key_derivation_salt` before recording receipts (Rails' `db:encryption:init` task generates keys). Keep keys in credentials or protected environment configuration and back them up separately. There is no plaintext fallback enabled by this integration. Receipt metadata includes account and operation identifiers; protect the database and backups as usual.
+
+The generated initializer explicitly requires `cloudflare/email/active_record/routing_deliveries`. Installing the gem alone enables no scheduler, network request, tracking table, or tenancy behavior.
+
+## Collect and apply evidence
+
+Run network requests outside database transactions. The durable outbox must have retained the accepted operation's SMTP envelope and provider Message-ID:
+
+```ruby
+tracking = Cloudflare::Email::ActiveRecord::RoutingDeliveries
+
+client.delivery_evidence(
+  message_id: delivery.provider_message_id,
+  since: delivery.request_started_at,
+  until_time: Time.now.utc
+).each do |evidence|
+  receipt = tracking.record(delivery: delivery, evidence: evidence)
+  tracking.apply(receipt) do |saved_delivery, recipient|
+    # Optional business projection using this same database connection.
+    # Read recipient.state; do not send mail or call external services here.
+  end
+end
+```
+
+`record` commits the original evidence before projection. Repeating it returns the same receipt. A changed authentic event under the same identity, or association with another operation, raises an error. Query windows and other rows returned alongside that event may differ between polls without creating duplicate receipts. Client payloads retain the complete original response envelope, provider row, authenticated account/zone, source, and query window and are immutable through ordinary model updates.
+
+`apply` returns `:applied`, including successful replay. It updates only a nonterminal recipient and marks the receipt applied in the same transaction. It preserves the accepted operation, envelope snapshot, and every existing terminal webhook fact, including a bounce. Thus `:applied` means evidence was processed; inspect the recipient's actual state. A later genuine Sending complaint continues to update the recipient through the existing Sending event API.
+
+Callbacks run only when the recipient changes. Same-database callback errors roll back the recipient, business writes, and receipt completion together; the original pending receipt remains available. A callback must not send email or perform external effects.
+
+This is not a webhook endpoint: accept evidence only from the authenticated client or your protected durable storage. Constructing an `Evidence` object validates its shape and correlation, not its provenance. Never deserialize arbitrary incoming request bodies into trusted analytics evidence.
+
+## Retry projection fairly
+
+```ruby
+result = tracking.replay(account_id: account_id, limit: 100, after_id: saved_cursor)
+result.errors.each do |failure|
+  ErrorReporter.report(failure[:error], receipt_id: failure[:receipt_id])
+end
+save_cursor(result.finished ? 0 : result.after_id)
+```
+
+The batch is bounded to 1–1,000 receipts. Failed receipts advance the cursor, allowing later receipts to proceed. After a complete pass, reset the cursor and revisit failures. Errors remain visible in the return value; your application must report them. Supply the same optional projection callback when replaying. Give fresh analytics discovery a separate scheduling opportunity so repeated projection failures cannot starve new evidence. No database transaction is interrupted by an HTTP or polling timeout.
+
+The client uses a five-second total network deadline, five-second socket timeouts, a 1,000,000-byte streamed response cap and no implicit HTTP retry. A failed request is visible to your scheduler. Queries returning 100 rows are rejected as potentially truncated; use a narrower historical window and retain existing unresolved records. Plan availability, analytics retention and sampling can limit what Cloudflare can prove.
+
+## Deliberately conservative matching
+
+The initial API requires exactly one accepted saved SMTP-envelope recipient, exactly one matching accepted operation in the account, matching sender and normalized provider Message-ID, and a nonempty provider session ID. The event must be `newEmail`, `delivered`, final, unsampled and not an NDR. Its timestamp must fall inside the requested historical window and at or after the saved request start, rounded down to Cloudflare's second precision.
+
+MIME `To` and analytics `to` are never used as envelope identity. Multi-recipient operations, sampled rows, forwarding rows and missing events do not become guessed delivery or failure. Malformed, truncated, conflicting or wrongly scoped qualifying evidence raises. Terminal delivery can override an equal or later nonterminal observation; existing terminal facts stay intact.
+
+## Tenant and cross-database applications
+
+Multi-tenancy remains off by default. If enabled, use the existing `Tenancy.with` or `Mailboxes.for_tenant` context for every outbox and Routing receipt operation, and install the receipt migration in each tenant database. Record instances cannot be moved between tenant contexts. A separate analytics account does not select or authorize a tenant.
+
+The gem checks provider-ID uniqueness inside the selected database. If one Cloudflare account spans several tenant databases, the host must also enforce account-wide provider-ID uniqueness in its shared directory or ledger before calling `record`. Tenant-local lookup alone cannot establish that a matching operation is unique across independent databases.
+
+An application may reserve an explicit physical storage key for system mail, such as `_system_outbound`, using its existing tenant provisioning and backup process. That storage key is not an organization or authorization identity. Keep nil tenant context fail-closed; do not silently map it to shared storage. Reserve and validate the key in the host application so a customer cannot claim it.
+
+For business records on another database, keep the host's own durable intake/projection record. Commit the gem evidence and projection in the selected tenant database, then finish the host projection. If the second commit fails, replay the same gem evidence and finish the host work independently. The gem's callback will not run again after its receipt was applied. There is no distributed transaction or exactly-once external effect guarantee.
+
+Cloudflare references: [Email event subscriptions](https://developers.cloudflare.com/email-service/platform/event-subscriptions/) and [metrics and analytics](https://developers.cloudflare.com/email-service/observability/metrics-analytics/).

data/docs/routing-diagnostics.md

@@ -0,0 +1,75 @@
+# Check whether an address is configured to reach your Worker
+
+This diagnostic is available in gem version 0.3.0.
+
+A mailbox registered in Rails is not proof that Cloudflare can deliver to it.
+Use this read-only check when onboarding a receiving domain, investigating a
+missing message, or checking an existing catch-all before activating addresses.
+
+For wildcard organization subdomains, also use the
+[domain setup guide and public DNS checker](../templates/worker/docs/domain-setup.md).
+This API inspects exact-domain configured records and does not resolve wildcard
+inheritance. Missing exact records can therefore coexist with working inherited
+MX. Public DNS and real delivery checks provide separate evidence; this diagnostic
+is not a requirement to manually onboard every organization in Cloudflare.
+
+```sh
+bin/rails cloudflare:email:check_route \
+  ADDRESS=houston@customer.example.com \
+  WORKER_NAME=cloudflare-email-ingress-production \
+  ACCOUNT_ID=your-cloudflare-account-id
+```
+
+Configure your Cloudflare management token in the normal gem credentials. The
+inspection needs Zone Read, DNS Read, and Email Routing Read permissions. No Edit
+permissions are needed. `WORKER_NAME` defaults to the gem's environment-scoped
+Worker name; `ACCOUNT_ID` falls back to the configured account, if present.
+
+Every check reports `PASS`, `FAIL`, or `UNKNOWN`. The command exits zero only
+when all configuration checks pass. An unavailable API, insufficient permission,
+an unsupported matcher, or ambiguous rule ordering produces `UNKNOWN`, not a
+successful result. Output excludes raw provider responses and credentials.
+
+The check inspects:
+
+- The closest containing Cloudflare zone and its account when an expected account is supplied.
+- Whether Email Routing is enabled for the zone.
+- MX and SPF records for the **exact receiving domain**. Parent-domain records
+  cannot satisfy a subdomain's requirements, and a parent's unrelated MX provider
+  does not conflict with correctly configured subdomain records.
+- Active explicit address rules before falling back to the catch-all. An explicit
+  drop, forwarding action, or different Worker takes precedence over a correct
+  catch-all. Disabled explicit rules are ignored. Multiple matching rules or
+  unsupported matcher forms leave selection unverified rather than guessing
+  priority or tie behavior.
+
+List reads are paginated and bounded to 50 pages per endpoint, responses to 1 MiB,
+and each request to 20 seconds (with shorter connection/read timeouts). An
+incomplete inspection does not report success. This command only issues GET
+requests. It never enables routing, changes DNS, repairs rules, or activates
+mailbox records.
+
+## Use from Ruby
+
+```ruby
+require "cloudflare/email/routing_diagnostics"
+
+report = Cloudflare::Email::RoutingDiagnostics.new(
+  api_token: ENV.fetch("CLOUDFLARE_API_TOKEN")
+).check(
+  address: "houston@customer.example.com",
+  worker_name: "cloudflare-email-ingress-production",
+  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID")
+)
+
+report[:status] # "pass", "fail", or "unknown"
+report[:checks] # [{ name: "zone", status: "pass", message: "..." }, ...]
+```
+
+This API does not require Active Record or enable multi-tenancy. You can use it
+with a custom Worker and an existing application ingestion pipeline. It reports
+a provider configuration snapshot; it does **not** prove public DNS propagation,
+full SPF evaluation, successful live delivery, the Worker's application URL or
+behavior, or application acceptance. Keep those as separate checks, including a
+controlled end-to-end delivery when appropriate. A passing report does not
+automatically change mailbox readiness or constitute delivery evidence.

data/docs/troubleshooting.md

@@ -9,7 +9,7 @@ into public logs or issues.
 
 | What you see | What to check next |
 | --- | --- |
-| New generator or API is missing | Check `Gemfile.lock`. The new features require the [0.2 commit](getting-started.md#install-the-current-code); published 0.1.0 lacks them. |
+| New generator or API is missing | Check `Gemfile.lock`. Use cloudflare-email 0.4.x with mailbox-kit 0.1.x; follow the [installation guide](getting-started.md#install-the-current-code). |
 | Credentials appear to be ignored | Nonempty Rails credentials override environment variables. Check the Rails environment and restart the app after changes. |
 | Authentication or domain error | Run `bin/rails cloudflare:email:doctor`; check account ID, token permissions and sending-domain verification. |
 | `doctor` reports limited read access | A send token may lack diagnostic read permissions. Review the specific result; diagnostics alone cannot prove whether sending works. |
@@ -30,15 +30,15 @@ FROM=hello@mail.example.com TO=you@example.net bin/rails cloudflare:email:send_t
 | --- | --- |
 | Address receives nothing | Verify receiving-subdomain onboarding and the address route's Worker. Sending-domain verification is separate. |
 | Route provisioning refuses a subdomain | Complete Email Routing subdomain setup and DNS preflight first. Do not enable or replace apex routing just to bypass the error. |
-| Worker reports 401 from Rails | Check matching ingress secrets and that Rails and Worker both use the v2 code. Upgrade both together. |
+| Worker reports 401 from Rails | Check matching ingress secrets and compatible signature versions. The Worker defaults to v2. The opt-in v3 [custom-ingress API](custom-ingress.md) requires upgrading Rails before enabling Worker metadata. |
 | Worker reports 408 | Check clock accuracy and the five-minute signing window. |
 | Worker reports 413 or rejects size | Raw MIME exceeds the configured limit. Match `MAX_EMAIL_BYTES` on Rails and Worker and check upstream request limits. |
 | Worker reports 3xx | Point it directly at the final HTTPS ingress URL; redirects are intentionally rejected. |
-| Worker times out | Check Rails availability and request latency. Its upstream request limit is 15 seconds; there is no durable inbound buffer. |
+| Worker times out | Check Rails availability and request latency. Direct mode can reject mail; the default [durable inbound path](../templates/worker/README.md#durable-inbound-delivery) retains it in R2 for retry and scheduled recovery. |
 | Rails returns 200 but your product shows no message | Check ActionMailbox records, job workers, failed routing jobs and your mailbox's `process` method. The default mailbox only logs receipt. |
 | Retrying creates no new inbound record | Identical MIME for the same SMTP recipient is intentionally deduplicated. |
 | Bcc message appears routed to the wrong mailbox | Use `Envelope.for(inbound_email)["to"]` after checking the envelope exists; MIME `To` does not identify every SMTP recipient. |
-| Quoted or internationalized addresses are rejected | The v2 envelope currently supports ASCII dot-atom addresses, not every possible email address syntax. |
+| Quoted or internationalized addresses are rejected | Both v2 and v3 envelopes support ASCII dot-atom addresses, not every possible email address syntax. |
 
 ## Local development
 
@@ -85,6 +85,7 @@ the actor you supply but does not authenticate that person.
 | What you see | What to check next |
 | --- | --- |
 | Queue stays empty | Check the Email Sending subscription, sending domain, selected event types and a real send from that domain. |
+| A verified Routing destination received mail but Sending feedback is missing | Use optional [Routing delivery confirmation](routing-deliveries.md) with its separate read credential. Missing evidence is unresolved, not proof of failure; keep the normal recipient address. |
 | Polling fails before processing | Check the queue ID, separate Queues Read/Write token, HTTP pull configuration and configured event handler. |
 | Events process once then stop | `consume_events` is a one-batch task. Schedule it to run repeatedly. |
 | Events stay unmatched | Check account, normalized provider message ID and recipient. Schedule replay; a receipt can arrive before the send result is saved. |

data/docs/upgrading-0.2.md

@@ -26,6 +26,11 @@ Pause test ingress while updating Rails and the deployed Worker together; verify
 the matching ingress URL and shared secret before resuming delivery. There is no
 legacy routing mode or supported mixed-version rollout.
 
+The 0.3 custom-ingress additions preserve v2 as the default and add
+opt-in v3 for authenticated Worker metadata. That additive upgrade is separate
+from the v1-to-v2 break above: upgrade the Rails receiver before enabling v3 in
+your custom Worker. See [custom ingestion](custom-ingress.md).
+
 Rails stores authenticated metadata before enqueueing routing jobs.
 `Cloudflare::Email::Envelope.for(inbound_email)` returns a string-keyed `from`/`to`
 hash for accepted ingress. It returns `nil` for records from another ingress or

data/docs/upgrading-0.3.md

@@ -0,0 +1,55 @@
+# Upgrade from 0.2 to 0.3
+
+Update your Gemfile to `gem "cloudflare-email", "~> 0.3.0"`, run
+`bundle update cloudflare-email`, and deploy Rails first. Updating the gem does
+not replace your deployed Worker, change DNS, or enable optional mailbox features.
+If you are upgrading from 0.1, complete the [0.2 upgrade](upgrading-0.2.md) too.
+
+## Receiving mail while Rails is down
+
+New installations can use the [Deploy to Cloudflare template](../templates/deploy-to-cloudflare/README.md)
+to provision the Worker resources through Cloudflare's setup form. Existing
+installations should preserve their resources and pending mail using the steps below.
+
+The bundled Worker now stores inbound mail in private R2 before accepting it,
+then delivers through a Queue with scheduled recovery. Before deploying it:
+
+1. Create an R2 bucket and Queue for each environment.
+2. Configure the `INBOUND_EMAIL_STORE` binding, `INBOUND_EMAIL_QUEUE` producer
+   and consumer, and once-per-minute cron from the bundled `wrangler.toml`.
+3. Preserve your ingress URL and shared secret. Deploy with Wrangler first;
+   the Rails deploy task does not provision infrastructure.
+4. Verify that mail queues during a Rails outage, drains after recovery, and
+   retries without duplicating application records. Monitor pending mail and age.
+
+Follow the [durable delivery guide](../templates/worker/docs/durable-inbound.md)
+for commands, retention requirements, capacity limits, and recovery behavior.
+Missing infrastructure fails visibly. To deliberately retain single-attempt
+delivery, explicitly select `INBOUND_DELIVERY_MODE=direct` before deploying.
+Direct mode cannot buffer outages. Keep existing bindings and cron so previously
+stored mail continues to drain. The old `DURABLE_INBOUND_ENABLED` flag is removed.
+
+Messages without a parseable Message-ID now receive a deterministic fallback
+across Rails hosts. Historical records created with the old hostname-dependent
+fallback may duplicate on replay; reconcile old archives before replaying them.
+Retain deduplication records for your recovery horizon and make app processing
+idempotent. Durable transport is not an exactly-once delivery guarantee.
+
+## Optional features
+
+- [Management engine](management-engine.md): mount a server-rendered mailbox UI
+  with host authentication, scopes, and permissions. It is not mounted automatically.
+- [Mailboxes](mailboxes.md): enable domain catch-all explicitly on an existing
+  active address. Follow the catch-all schema upgrade instructions; exact
+  registered addresses still take precedence, and sending remains exact-address only.
+- [Custom ingestion](custom-ingress.md): integrate verified envelopes and raw
+  persistence into an existing app. Deploy Rails before enabling v3 metadata
+  signatures in a custom Worker; ordinary v2 forwarding remains supported.
+- [Routing delivery confirmation](routing-deliveries.md): configure separate
+  analytics credentials and durable receipts if needed. API acceptance alone
+  is not proof of delivery, and ambiguous evidence must not trigger a resend.
+
+Database tenancy remains opt-in. Existing tenant-enabled applications can now
+preload their schemas without selecting a tenant; actual mailbox access still
+requires explicit tenant context. No new database tables are required merely to
+upgrade the gem or use the durable inbound Worker.

data/docs/verification/2026-09-11-custom-ingress.md

@@ -0,0 +1,49 @@
+# Custom ingress and routing diagnostics verification
+
+Scope: upstream gem integration tools informed by Rebulk's existing ingestion
+pipeline. This report covers local synthetic verification, not a Rebulk rollout.
+
+## Results
+
+| Check | Result |
+| --- | --- |
+| Full Ruby suite, Ruby 3.4.1 / Rails 7.2, 8.0, 8.1 | Each: 257 tests, 916 assertions, no failures/errors/skips |
+| Shared ingress unit tests | 12 tests, 98 assertions; independent Node/Ruby v3 binary/Unicode vector, tampering, metadata bounds, short streams, immutable results, retry identity |
+| Custom Rails endpoint | 5 integration tests, 37 assertions; separate SQLite tenant databases, policy before persistence, durable signed metadata and retries |
+| Built-in Rails endpoint | V3 persistence before routing enqueue, binary preservation, retries and unsigned v2 metadata rejection; covered in the full suite |
+| Read-only routing diagnostics | 27 tests, 50 assertions; mocked Cloudflare configuration, exact-domain DNS, rule selection, ambiguous/inaccessible responses and pagination |
+| Worker | 45 tests pass; Wrangler dry-run succeeds |
+| Packaged consumer | Isolated plain Ruby install and packaged Rails installation/ingress fixtures pass |
+| Local workerd → Rails | Real local forwarding, Bcc routing, attachment preservation, wrong/missing secrets, redirects and timeout handling pass |
+
+Independent reviews found two verifier issues: a readable stream can return
+short chunks, and HMAC must use the timestamp's exact transmitted bytes. Both
+were corrected and covered by regression tests. Freshness still parses decimal
+seconds; existing bundled Worker timestamps are unchanged.
+
+## Reproduce
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
+bundle exec ruby script/verify_package.rb
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
+npm --prefix templates/worker test
+npm --prefix templates/worker run check
+```
+
+Use Node 22 for the Worker and local forwarding checks.
+
+## Limits
+
+No Rebulk application code, live DNS, Worker deployment, inbox activation, R2
+archive, or gem publication was changed. The local workerd test exercises the
+default v2 transport; opt-in v3 is covered by Worker tests, an independent shared
+signature vector, and real Rails integration tests, not deployed Cloudflare mail.
+
+Routing diagnostics inspect provider configuration through mocked API tests.
+A passing configuration snapshot does not establish public DNS propagation,
+complete SPF evaluation, Worker application behavior, or live delivery. Signed
+metadata authenticates the forwarding integration's assertions; the host still
+owns original-sender trust, held-message policy, and business processing.

data/docs/verification/2026-09-12-destination-context.md

@@ -0,0 +1,46 @@
+# Destination context and email persistence verification
+
+Scope: standalone accepted-address resolution and destination context yielded
+from the existing persisted receive path. No Rebulk deployment or gem release.
+
+## Results
+
+- Full suites on Ruby 3.4.1 with Rails 7.2, 8.0 and 8.1: each passed with
+  257 top-level tests and 916 assertions. These include subprocess integration
+  fixtures whose internal assertions are not included in that top-level count.
+- The standalone service fixture uses two real SQLite tenant databases with
+  colliding mailbox IDs and no ActionMailbox loaded. It verifies host-owned
+  binary-email persistence, immutable destinations, aliases, inactive records,
+  nested context restoration, host exceptions and missing-tenant refusal without
+  creating a database. Lookup itself creates no mailbox membership.
+- The custom Rails ingress fixture verifies saved raw MIME and signed metadata,
+  mailbox membership, and a host business link created from the destination.
+  Routing jobs execute in the correct tenant after commit. Retries do not
+  duplicate the linked records. A host write failure rolls back the email and
+  membership and schedules no routing job.
+- Existing callbacks remain supported, including strict zero-argument lambdas.
+- Packaged plain Ruby and Rails consumer checks pass, including mailbox ingress,
+  routing and existing retention behavior.
+- Independent review found no remaining blockers. A callback arity compatibility
+  issue was fixed and covered before completion.
+
+## Reproduce
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
+bundle exec ruby script/verify_package.rb
+```
+
+## Boundaries
+
+Destination context is a lifecycle snapshot, not host authorization or a durable
+processing claim. Applications still validate owners and sender policy and make
+downstream work idempotent. The host owns custom-store transactions; `receive`
+preserves the existing shared tenant transaction for ActionMailbox persistence.
+Neither API makes cross-database or external object-store operations atomic.
+
+Managed mailbox memberships protect raw email from automatic incineration;
+deliberate purge, backups and host-reference cleanup remain application policy.
+These local tests do not verify Rebulk's actual queues, sender policy or archive.

data/docs/verification/2026-09-13-action-mailbox-core.md

@@ -0,0 +1,96 @@
+# Action Mailbox composition verification
+
+## Independent review follow-up
+
+The independent architecture review of `63660eb` confirmed the Rails/core/provider
+split and reproduced a missing inbound membership index with SQLite's query planner.
+The follow-up adds that index to both installers and supplies `mailbox_kit:upgrade`
+for existing schemas. The generator fixture verifies indexed lookup, existing
+membership preservation and repeat application. It passes 4 tests / 27 assertions.
+
+Cloudflare configuration now delegates shared validation to the core, and its
+session behavior is an explicit integration module. Handler overrides retain
+their existing extension point. The short core README links to packaged
+integration and upgrade guides.
+
+After these changes, the full suite passes 289 tests / 1,151 assertions. Package
+verification passes for Rails-free Cloudflare, packaged ingress/outbound/tenancy,
+and an independent Rails consumer without Cloudflare in its bundle.
+
+This is local/package verification, not a Rebulk production rollout. Automatic
+model-owner lifecycle bindings and a universal outbound adapter framework remain
+outside this change. Existing application acceptance, ownership and business
+processing claims must be retained.
+
+Mailbox Kit now treats `ActionMailbox::InboundEmail` as the original email record.
+The kit's `Message` remains an inbox membership with read/archive state; no new
+raw-email table, parser, routing job or processing-status model was introduced.
+
+## Verified behavior
+
+- `Mailboxes.receive(recipient:, source:)` resolves the trusted receiving scope
+  before Rails persistence, and attaches the existing record on source replay.
+  Identical source in two inboxes of one tenant produces one Rails email, two
+  memberships and one routing job. Read state remains independent per inbox.
+- Identical source in different tenants sharing a database produces distinct
+  Rails records/jobs. `Session#attach` rejects a row already associated with a
+  different tenant, and resolves IDs only inside the selected connection.
+- `Session#attach(recipient:, inbound_email_id:)` supports already-stored Rails
+  mail. It is idempotent per mailbox/email, preserves alias reservations and
+  refuses suspended addresses or missing records.
+- The stock Rails Postmark ingress was exercised through HTTP in the isolated
+  Rails fixture. Duplicate webhook payloads produced one Rails email; explicit
+  host-authorized attachment created its inbox membership without reprocessing.
+- Cloudflare retains its prior authenticated envelope/metadata identity and
+  stable Message-ID fallback. Its controller uses `receive_into_mailbox!` and
+  repairs missing membership on replay without re-enqueueing Rails routing.
+  The older `persist_action_mailbox!` still returns nil on duplicate delivery.
+- Rails' `incinerate = false` prevents automatic cleanup scheduling without a
+  membership. With normal cleanup enabled, aged processed unassociated mail is
+  removed while inbox-associated mail survives. The guard uses Rails' public
+  inbound-email load hook and the same row lock as attachment and purge.
+- Removing one of two memberships preserves the shared raw email; removing the
+  last through explicit purge removes it. Failed membership persistence rolls
+  back Rails database records and prevents a routing enqueue.
+- PostgreSQL deliveries were synchronized at Rails creation to force a unique
+  conflict. Both calls completed with one inbound record, one membership, one
+  Active Storage blob record and one routing job. A savepoint rollback keeps the
+  losing transaction usable before looking up the winning record.
+
+## Checks
+
+- Full Ruby suite: 289 top-level tests, 1,151 assertions passed. Integration
+  subprocesses exercise the additional Rails behavior rather than inflating these
+  top-level counts.
+- `script/verify_package.rb`: both gem archives built; Rails-free Cloudflare
+  consumer, packaged Cloudflare integration and independent core-only Rails
+  consumer passed. The independent bundle contains no Cloudflare gem.
+- PostgreSQL inbound suite: 25 tests, 273 assertions passed on a disposable local
+  PostgreSQL 15 instance. CI runs the same suite against PostgreSQL 16 alongside
+  the existing outbox tests.
+- SQLite core/compatibility, separate-tenant ingress and custom ingress regression
+  suites were exercised locally. CI covers the supported Ruby/Rails matrix.
+
+Run the PostgreSQL check only against a disposable database:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/postgres.gemfile \
+POSTGRES_TEST_URL=postgres://localhost/cloudflare_email_test \
+bundle exec ruby script/verify_postgres_inbound.rb
+```
+
+The script creates a unique schema and drops that schema when its fixture exits.
+
+## Limits
+
+The Postmark test is a fixed, authorized single-database route, not a live
+Postmark deployment or a complete dynamic-tenant provider adapter. The caller
+must authenticate ingress and authorize the envelope recipient and inbound ID;
+MIME To/X-Original-To headers are not tenant entitlement. Tenant selection after
+ingress cannot relocate raw mail already persisted to another database.
+
+Raw blob uploads and external side effects are not made transactional by Active
+Record. This check does not establish exactly-once business effects, provider
+outage recovery, lost-job recovery, or live delivery. Existing Cloudflare durable
+transport remains responsible for its outage/retry behavior. Owner lifecycle
+macros and a general outbound adapter framework are separate work.

data/docs/verification/2026-09-13-durable-inbound-and-routing.md

@@ -0,0 +1,71 @@
+# Durable inbound and Routing delivery verification
+
+This change brings the verified Routing-delivery correlation from Rebulk into an
+optional gem API and adds inbound storage/recovery for Rails outages. All tests
+below use synthetic messages and disposable local storage. This report does not
+claim the new Worker configuration is deployed in Rebulk production.
+
+## Boundaries verified
+
+- Shared sending/queue HTTP requests stream bounded responses, including gzip
+  expansion, and enforce a total network deadline. Real socket tests cover
+  slow streams, socket cleanup, oversized replies and uncertain queue ACKs.
+  No ambiguous failure automatically resends an accepted email.
+- Authenticated Routing analytics validates account/zone, provider ID, sender,
+  request window and a single saved envelope recipient. Dedicated encrypted
+  receipts preserve provider evidence and support idempotent projection.
+- Inbound R2 persistence finishes before successful Email Worker return. Queue
+  messages contain only a storage pointer. Failed enqueue, Rails errors, lost
+  responses, failed deletion and exhausted retries retain the pending payload.
+  Scheduled pagination advances over poison messages and retries retained mail.
+- A real local workerd instance uses R2 and Queues against Rails with SQLite and
+  disk-backed Active Storage. With queue retries disabled, Rails 503 leaves mail
+  in R2; invoking the scheduled handler after recovery persists one message and
+  removes the pending object. Returning 503 after Rails commits also replays to
+  one record. MIME and binary attachments remain byte-identical.
+- Missing Message-ID fallback remains stable when Rails hostnames change. Valid
+  Message-IDs and raw MIME are preserved. Pre-upgrade fallback IDs require care
+  when replaying historical archive records.
+- Local workerd capacity checks pass for one 25 MiB message and two concurrent
+  25 MiB receipts, followed by concurrent handoffs. The receiver verifies exact
+  SHA256 and HMAC values, and R2 pending objects clear after acknowledgement.
+  Local workerd does not certify production memory-limit enforcement.
+
+## Reproduce
+
+Use Ruby 3.4 and Node 22 or another supported version:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle install
+npm ci --prefix templates/worker
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec rake test
+npm test --prefix templates/worker
+npm run check --prefix templates/worker
+node script/verify_durable_capacity.mjs
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_package.rb
+```
+
+The local runtime harness invokes the real scheduled handler through a temporary
+test-only endpoint. It does not test Cloudflare's production cron scheduler or
+SMTP delivery behavior. No test endpoint is shipped in the Worker.
+
+## Before production enablement
+
+Provision a private R2 bucket, queue and schedule per environment, and keep
+pending objects free of lifecycle expiration. Deploy the updated Rails ingress
+first. Verify maximum message size and recovery throughput with expected traffic,
+then perform a staging outage drill through the actual Cloudflare email route.
+Monitor storage errors and pending object age as well as queue backlog. Keep
+Rails deduplication records throughout the recovery horizon and monitor mailbox
+routing jobs after durable ingestion.
+
+Routing tracking is separately opt-in and needs encryption keys, its migration,
+a restricted analytics read credential, and host scheduling. Cross-database
+applications must retain their durable business projection boundary and enforce
+provider-ID uniqueness across tenant databases. Missing delivery evidence stays
+unresolved; it never authorizes another send.
+
+R2 storage and retry protect mail after a successful storage commit. They cannot
+promise absolute losslessness during upstream storage failure, deletion,
+misconfiguration or account suspension. See the [operating guide](../../templates/worker/docs/durable-inbound.md).

data/lib/cloudflare/email/active_record/base.rb

@@ -1,48 +1,10 @@
-require "active_record"
 require "cloudflare/email/tenancy"
-
+require "mailbox_kit/active_record/base"
 module Cloudflare
   module Email
     module ActiveRecord
-      # Uses the host's abstract tenant connection owner when explicitly configured.
-      class Base < Tenancy.model_base(::ActiveRecord::Base)
-        self.abstract_class = true
-
-        class << self
-          def connection_pool
-            Tenancy.require_context! if Tenancy.enabled?
-            super
-          end
-        end
-
-        before_validation :verify_cloudflare_email_tenant!
-        before_save :verify_cloudflare_email_tenant!
-        before_destroy :verify_cloudflare_email_tenant!
-
-        # These methods can bypass callbacks or load a different row with the same ID.
-        %i[reload update_columns delete touch increment! decrement! association].each do |method_name|
-          define_method(method_name) do |*args, **kwargs, &block|
-            verify_cloudflare_email_tenant!
-            super(*args, **kwargs, &block)
-          end
-        end
-
-        private
-
-        # Both new construction and persisted-row instantiation call this before
-        # assigning inverse associations (which precede after_initialize).
-        def init_internals
-          super
-          @cloudflare_email_tenant_key = Tenancy.require_context! if Tenancy.enabled?
-        end
-
-        def verify_cloudflare_email_tenant!
-          return unless Tenancy.enabled?
-          unless @cloudflare_email_tenant_key == Tenancy.require_context!
-            raise ConfigurationError, "record belongs to a different tenant context"
-          end
-        end
-      end
+      Base = MailboxKit::ActiveRecord::Base
+      TenantConnectionUnavailable = MailboxKit::ActiveRecord::TenantConnectionUnavailable
     end
   end
 end