cloudflare-email 0.1.0 → 0.2.0

data/docs/mailboxes.md

@@ -0,0 +1,299 @@
+# Create and manage mailboxes from Rails
+
+The optional mailbox module lets your app create mailboxes and aliases, receive
+mail into them, track read/archive state, and send through the durable outbox.
+It works in one SQLite database or with a separate database per organization.
+It supplies models and services; your app supplies permissions and the UI.
+
+This module is available in version 0.2.0. Install `gem "cloudflare-email", "~> 0.2.0"`.
+
+**Database multi-tenancy is off by default.** The mailbox generator works with
+one ordinary database. Calling `for_tenant` groups and scopes mailbox records;
+it does not create databases or install a tenant adapter. Separate databases
+require explicit `Tenancy.configure(...)` before models load. Neither Rails nor
+`activerecord-tenanted` is added to plain Ruby applications by this module.
+
+## Install
+
+First configure [sending and receiving](getting-started.md). Then run:
+
+```sh
+bin/rails generate cloudflare:email:mailboxes
+bin/rails db:migrate
+```
+
+The generator includes the outbox and tracking generators. Do not generate those
+migrations a second time if you already installed them; inspect existing
+generator conflicts and retain your installed migrations. Restart Rails after
+configuration changes. The generated initializer explicitly loads:
+
+```ruby
+require "cloudflare/email/mailboxes"
+```
+
+Loading this module enables mailbox lookup on the gem's Cloudflare ingress.
+Existing receiving addresses must be registered and activated before switching
+an existing application over. Unregistered or suspended destinations return
+HTTP 422 and the Worker rejects the delivery; there is no default-mailbox fallback.
+
+For separate organization databases, follow the
+[activerecord-tenanted setup](activerecord-tenanted.md) **before loading the
+models**. It covers shared versus tenant migrations, tenant-specific framework
+storage, early initialization and background jobs. Rails and ActiveStorage must
+use the same tenant connection as the mailbox tables for atomic incoming storage.
+
+## Register an organization's domain
+
+Run directory management from your authorized administration/provisioning code.
+Do not expose arbitrary domain claims to customers without ownership checks.
+
+```ruby
+inboxes = Cloudflare::Email::Mailboxes
+domain = inboxes.register_domain(
+  domain: "acme.example.com",
+  tenant_key: "organization-123",
+  account_id: Cloudflare::Email::Credentials.account_id,
+)
+```
+
+This creates a **pending directory entry**, not DNS records. Set up the receiving
+subdomain in Cloudflare and deploy the Worker. Then record your verification:
+
+```ruby
+inboxes.activate_domain!(domain.id,
+  evidence: "Receiving DNS and the development Worker verified in setup ticket 42",
+  sending_enabled: false,
+)
+```
+
+Activation records an operator assertion; the gem does not independently verify
+domain ownership from this string. Set `sending_enabled: true` only after
+Cloudflare has also verified this sending domain. Incoming routing and outgoing
+domain verification are separate setup steps. An address's route is activated
+separately below.
+
+Each exact domain belongs to one tenant. Domain ownership, tenant key and
+Cloudflare account identity cannot be reassigned through normal model updates.
+Keep tenant keys stable and resolve them to provisioned databases through your
+trusted tenant adapter. Use customer/organization IDs rather than deriving a
+database filename directly from an email address.
+
+## Create a mailbox and activate its route
+
+Even in a single database, use an explicit tenant key and the scoped session:
+
+```ruby
+inboxes.for_tenant("organization-123") do |account|
+  mailbox = account.create(
+    name: "Customer support",
+    address: "support@acme.example.com",
+    owner_ref: "team:42",
+  )
+  address = account.addresses(mailbox.id).first
+
+  provisioner = Cloudflare::Email::RoutingProvisioner.new(
+    api_token: Cloudflare::Email::Credentials.management_token,
+  )
+  account.provision_address!(address.id,
+    provisioner: provisioner,
+    worker_name: "cloudflare-email-ingress-development",
+  )
+end
+```
+
+`owner_ref` is your application's optional stable reference to a user, site,
+team or customer. The gem stores it; it does not load that record or authorize
+the person using it. Authorize the organization and mailbox in your app first.
+
+The address stays pending if provisioning fails. The provisioner upserts an
+individual address rule, so you can retry setup. Run provisioning outside a
+database transaction. DNS propagation and an actual inbound test are still
+needed after the API succeeds.
+
+If you already configured a route separately, record that explicitly:
+
+```ruby
+account.activate_address!(address.id, evidence: "Existing route verified in ticket 43")
+```
+
+This example assumes the same `for_tenant` block and local variables as above.
+The gem does not change a zone-wide catch-all while creating a mailbox.
+
+## Aliases, suspension and ownership
+
+An alias is another address attached to the same mailbox:
+
+```ruby
+inboxes.for_tenant("organization-123") do |account|
+  mailbox = account.mailboxes.find_by!(owner_ref: "team:42")
+  alias_address = account.add_address(mailbox.id, address: "help@acme.example.com")
+  # Provision alias_address exactly as you provisioned the first address.
+
+  account.suspend(mailbox.id) # Stops new ingress and queued mailbox sends.
+  account.resume(mailbox.id)
+  # To suspend only one address:
+  account.suspend_address(mailbox.id, alias_address.id)
+end
+```
+
+Suspension is enforced by Rails; it does not delete the Cloudflare route. Mail
+already accepted and stored remains available for processing and inspection.
+Use `activate_address!` with new evidence to reactivate an address. Domain-wide
+suspension is an administrative update of `ReceivingDomain#state` to `suspended`.
+
+Addresses use lowercase ASCII dot-atom local parts and domains. Alias addresses
+are explicit: the module does not automatically strip `+tags` or invent address
+fallbacks. Reserve application-specific names such as Rebulk's `tracking` in
+your mailbox-management policy before creation.
+
+## Read incoming mail
+
+The Worker signs the SMTP recipient. Rails verifies the whole request, resolves
+the domain, enters its tenant context and stores raw mail plus a mailbox
+membership in one database transaction. MIME To/Cc headers do not select the
+tenant. Retries for the same raw message and exact SMTP recipient are deduplicated.
+
+Inside your authenticated application's mailbox view/service:
+
+```ruby
+inboxes.for_tenant("organization-123") do |account|
+  mailbox = account.mailboxes.find_by!(owner_ref: "team:42")
+  account.messages(mailbox.id).inbox.unread.order(id: :desc).limit(25).each do |entry|
+    inbound = account.inbound_email(mailbox.id, entry.id)
+    subject = inbound.mail.subject
+    raw_mime = inbound.raw_email.download
+    # Build your authorized UI response here; sanitize rendered mail content.
+  end
+end
+```
+
+Perform tenant record access inside the block, rather than retaining lazy
+relations or framework records for use under another tenant. Numeric record IDs
+can overlap in separate tenant databases.
+
+For a message entry you have already authorized:
+
+```ruby
+account.mark_read(mailbox.id, entry.id)
+account.mark_read(mailbox.id, entry.id, read: false)
+account.archive(mailbox.id, entry.id)
+account.archive(mailbox.id, entry.id, archived: false)
+```
+
+These calls also belong inside the tenant block. Raw mail with a mailbox
+membership is protected from ActionMailbox's normal automatic incineration.
+Archive hides it from the inbox scope but retains the content. For deliberate
+permanent deletion, use `account.purge_message(mailbox.id, entry.id)`; it deletes
+the raw inbound record only when no other mailbox membership references it.
+ActiveStorage schedules its attachment cleanup jobs. Apply your own retention,
+encryption and backup policies; archive is not a retention policy.
+
+## Send from the mailbox
+
+Use a rendered ActionMailer message whose From and SMTP envelope sender are an
+active address belonging to the mailbox. The domain must be enabled for sending.
+`ReplyMailer` below is your application's mailer, not a generated gem class.
+
+```ruby
+inboxes.for_tenant("organization-123") do |account|
+  mailbox = account.mailboxes.find_by!(owner_ref: "team:42")
+  operation = account.prepare(mailbox.id,
+    operation_key: "draft:789:revision:1",
+    mail: ReplyMailer.reply(draft).message,
+  )
+  account.enqueue(mailbox.id, operation_key: operation.operation_key)
+end
+```
+
+Authorize the send before preparation. If preparation is part of an application
+transaction, enqueue only after its **outer commit**. The job queue must process
+`mailers`. Do not also call `deliver_later` on the mailer.
+
+The caller's operation key is namespaced by tenant and mailbox. Save the returned
+operation key and reuse it when enqueueing a retry. Re-rendering an already
+prepared operation may change MIME headers and raises a snapshot conflict.
+The job serializes tenant, mailbox ID and operation key—not MIME or credentials.
+It checks the current mailbox/address/domain state again before sending.
+
+Inspect `account.outbound_messages(mailbox.id)` and each link's
+`outbound_delivery` for the saved operation, provider ID and recipient outcomes.
+Accepted or partial attempts are never automatically resent. Uncertain attempts
+need [audited reconciliation](outbox.md#reconcile-uncertainty), available through
+`account.reconcile(mailbox.id, operation_key: saved_key, **evidence)`.
+
+For several Cloudflare accounts, configure a runtime client resolver **before
+loading mailbox models**:
+
+```ruby
+Cloudflare::Email::Mailboxes.configure(
+  directory_base: DirectoryRecord,
+  client_resolver: ->(tenant_key, account_id) {
+    Cloudflare::Email::Client.new(account_id: account_id,
+      api_token: YourSecretStore.email_token(tenant_key, account_id),
+      retry_ambiguous: false)
+  },
+)
+```
+
+`DirectoryRecord` and `YourSecretStore` are application examples. For one account,
+the default resolver uses the existing gem credentials and verifies the account
+matches. Cloudflare account IDs and your tenant keys are separate identities.
+
+## Delivery events and recovery
+
+Configure the [Cloudflare Queue subscription and token](delivery-events.md).
+Use shared intake for tenant mailboxes, rather than selecting a tenant from the
+event's recipient or Cloudflare account:
+
+```ruby
+Rails.application.config.x.cloudflare_email.event_domains = ["acme.example.com"]
+Rails.application.config.x.cloudflare_email.event_handler = ->(event) {
+  Cloudflare::Email::Mailboxes::Events.record(event)
+}
+```
+
+Schedule `cloudflare:email:consume_events` to poll batches. Also schedule these
+jobs regularly, starting at the beginning of each scan:
+
+```ruby
+Cloudflare::Email::Mailboxes::ReplayEventsJob.perform_later
+Cloudflare::Email::Mailboxes::RecoverJob.perform_later("organization-123")
+```
+
+Schedule recovery for each provisioned organization in your own directory. Each
+job processes a bounded page and enqueues its continuation. Recovery dispatches
+prepared operations, repairs accepted-result callbacks and registers provider
+correlation; it does not clear uncertain send claims. Domain suspension leaves
+events retained for later projection.
+
+Shared event intake commits before queue acknowledgement. After an accepted
+send, the gem registers account/message/recipient correlation to the tenant's
+outbox record. Events arriving first remain unmatched until replay. Tenant
+projection commits before shared completion; a crash between those commits
+causes safe redelivery to the tenant's deduplicating receipt ledger. Ambiguous
+correlations remain unprojected.
+
+The existing `config.x.cloudflare_email.outbox_delivery_handler` and
+`outbox_recipient_handler` callbacks work here too. Keep them idempotent and on
+the same tenant connection when atomicity is required. External effects cannot
+be rolled back. Provider acceptance, shared storage and tenant storage are not
+one transaction; this is not exactly-once delivery.
+
+## Isolation and rollout
+
+The scoped session API checks tenant/mailbox ownership and sender addresses.
+It does not authenticate Rails users. Protect admin directory APIs, choose the
+tenant through your access resolver, and authorize every mailbox operation.
+Direct/unscoped ActiveRecord access is an application-level privileged interface,
+particularly in shared-database mode; it is not a row-level authorization system.
+
+For database tenancy, configure all framework storage on the tenant connection
+and exclude ingress from hostname/session tenant selection. New framework jobs
+capture tenant context before serialization and restore it before GlobalID
+lookup. Drain existing ActionMailbox/ActiveStorage queues before enabling this
+mode: previously serialized jobs without the new metadata are rejected.
+
+The gem does not create organizations/users, verify customer domain ownership,
+provide IMAP/POP, or supply an inbox UI. The original Rebulk document-processing
+Worker contract and sender-review policy still need a separate application
+migration; installing this module does not replace that live pipeline.

data/docs/outbox.md

@@ -0,0 +1,175 @@
+# Durable outbound email for Rails
+
+The optional Active Record layer supplies immutable send snapshots, single-attempt delivery claims, recipient outcomes, delivery-event receipts, and audited reconciliation. Use it when background retries, process crashes, or missing provider responses must not silently resend an email. The plain Ruby client and ordinary ActionMailer delivery method remain available without these tables.
+
+This is delivery infrastructure. Your application still authorizes sending, decides what belongs in a conversation, reviews drafts, and controls operator access.
+
+## Install
+
+After configuring the gem's sending credentials, generate both sets of tables:
+
+```sh
+bin/rails generate cloudflare:email:tracking
+bin/rails generate cloudflare:email:outbox
+bin/rails db:migrate
+```
+
+Skip a generator whose migration is already installed. The outbox initializer requires `cloudflare/email/active_record`, which loads the models, `Outbox`, `prepare_mail`, and `DeliveryEvents`, and also loads both jobs. For manual setup without the generator, require:
+
+```ruby
+require "cloudflare/email/active_record"
+require "cloudflare/email/send_job"
+require "cloudflare/email/replay_events_job"
+```
+
+Use a durable ActiveJob backend and a recurring scheduler suitable for your application. The gem does not install a job backend or Cloudflare Queue subscription. Configure delivery events and the separate queue token as described in [delivery-events.md](delivery-events.md).
+
+## Prepare once, dispatch after commit
+
+Render the mail, snapshot it together with your application update, and enqueue only after the outer database transaction commits:
+
+```ruby
+outbox = Cloudflare::Email::ActiveRecord::Outbox
+account_id = Cloudflare::Email::Credentials.account_id
+
+# Inside an application service that runs outside an existing transaction:
+delivery = nil
+Draft.transaction do
+  draft.lock!
+  # Apply the application's owner/approval checks here.
+  mail = ReplyMailer.reply(draft).message
+  delivery = outbox.prepare_mail(
+    account_id: account_id,
+    operation_key: "draft:#{draft.id}:revision:#{draft.revision}",
+    mail: mail
+  )
+  draft.update!(outbound_operation_key: delivery.operation_key)
+end
+
+Cloudflare::Email::SendJob.perform_later(account_id, delivery.operation_key)
+```
+
+`Draft`, `revision`, and `outbound_operation_key` above are application examples, not generated gem models. For nested application transactions, use an actual after-commit hook; returning from an inner transaction does not necessarily commit the outer one.
+
+`prepare_mail` accepts a rendered `Mail::Message` or an ActionMailer message delivery. It reads the SMTP envelope and encodes the MIME once, preserving attachments and To/Cc/Bcc delivery. It rejects `perform_deliveries == false`. Mailer rendering callbacks run during rendering; delivery callbacks are bypassed when sending the saved snapshot. Put required delivery authorization before preparation or in your application service.
+
+For an existing MIME source:
+
+```ruby
+delivery = outbox.prepare(
+  account_id: account_id,
+  operation_key: "invoice:123:notification:1",
+  from: "billing@example.com",
+  recipients: ["customer@example.net"],
+  mime_message: raw_mime
+)
+```
+
+The account plus operation key identifies one immutable attempt. Preparing the same envelope and MIME returns the existing operation. Changing its snapshot raises `Outbox::SnapshotConflict`. Recipient order is preserved, duplicate addresses are removed, domains are lowercased, and local parts retain their case. MIME is stored as binary data. Re-rendering a mail can change generated headers, so job retries use the saved operation identity instead of calling the mailer again.
+
+`Outbox.deliver(delivery, client: optional_client)` sends synchronously and refuses an ambient database transaction. Its `prepared → sending` claim commits before network I/O. A supplied client must match the account and expose `retry_ambiguous == false`. The standard `SendJob` uses the configured sending account/token and forces ambiguous retries off; applications managing several Cloudflare accounts can use their own account-aware job and pass the appropriate client.
+
+## States and retries
+
+| Operation state | Meaning and permitted action |
+| --- | --- |
+| `prepared` | Snapshot saved; safe to dispatch. |
+| `sending` | A process claimed the attempt. Another job cannot send it. A crashed process can leave this state indefinitely. |
+| `accepted` | All recipients have acceptance evidence. Repeated delivery returns the record without a network request. |
+| `partial` | Some recipients have acceptance evidence, while others were rejected or remain unknown. Repeated delivery never resends the batch. |
+| `rejected` | Available outcomes show rejection. The operation is terminal; correcting and sending again requires a new operation key. |
+| `unknown` | Acceptance cannot be established safely. Investigate and reconcile before deciding on another attempt. |
+| `confirmed_not_sent` | An operator confirmed the whole operation was not sent. Old jobs stay blocked; a deliberate new attempt needs a new key. |
+
+Each `outbound_recipients` row stores `acceptance_state` separately from lifecycle `state`. A later complaint or bounce must not erase evidence that the original send was accepted. Lifecycle `occurred_at` stays nil for immediate send results and operator reconciliation: local clock time is not a provider event timestamp.
+
+Malformed success responses, conflicting provider message IDs, timeouts, ambiguous transport errors, and failures saving an accepted response remain uncertain. Explicit supported provider rejection responses can produce `rejected`. Errors are re-raised after recording the conservative outcome. A database outage may leave the already committed `sending` claim instead of `unknown`; both block resend.
+
+This is not exactly-once delivery. Provider acceptance and a database commit cannot be one transaction. Client pre-send/rate-limit retry behavior remains available, but automatic ambiguous retries are prohibited by the outbox.
+
+## Recover dispatch and application projections
+
+An application can commit its snapshot and crash before enqueueing. Schedule a scan of `prepared` operations and enqueue their saved identities. Multiple scanners/jobs are safe because only one can claim an operation. Do not reset `sending` operations merely because they are old.
+
+Operational commands:
+
+```sh
+bin/rails cloudflare:email:pending_deliveries
+OPERATION_KEY='invoice:123:notification:1' bin/rails cloudflare:email:deliver
+bin/rails cloudflare:email:replay_events
+```
+
+The listing includes prepared, sending, unknown, and partial operations for the configured account; it does not automatically dispatch them. `deliver` uses `SendJob.perform_now` with the saved snapshot.
+
+Optional Rails callbacks reduce application glue:
+
+```ruby
+settings = Rails.application.config.x.cloudflare_email
+settings.outbox_delivery_handler = ->(delivery) {
+  # Idempotently project the saved operation into application records.
+}
+settings.outbox_recipient_handler = ->(delivery, recipient) {
+  # Project a lifecycle change into application records.
+}
+```
+
+The delivery callback runs under a delivery row lock after the result has been saved. If application projection fails after acceptance, retrying the job repairs the projection without another provider send. The recipient callback runs inside receipt processing's transaction. Keep callbacks idempotent and use the same database connection for atomic application writes. External side effects cannot be rolled back; schedule them through a durable application mechanism.
+
+## Consume and replay events
+
+Wire the supplied projector into the event consumer:
+
+```ruby
+settings = Rails.application.config.x.cloudflare_email
+settings.event_handler = ->(event) {
+  Cloudflare::Email::ActiveRecord::DeliveryEvents.record(event) do |delivery, recipient|
+    settings.outbox_recipient_handler&.call(delivery, recipient)
+  end
+}
+```
+
+`DeliveryEvents.record` commits the receipt before projecting it. Callback failures roll back projection and leave the saved receipt available for retry. It matches the account, normalized provider Message-ID, and recipient; ambiguous matches remain unmatched. Known events apply with lifecycle ordering and terminal-state guards. Event identity provides durable deduplication. Unknown future event statuses remain unmatched for later support.
+
+An event may arrive before the send result is saved. `SendJob` replays matching receipts after its delivery callback, and a recurring `ReplayEventsJob.perform_later(account_id)` covers later recovery. Direct callers can use:
+
+```ruby
+Cloudflare::Email::ActiveRecord::DeliveryEvents.replay(
+  account_id: account_id, message_id: delivery.provider_message_id
+) do |operation, recipient|
+  # Optional application projection.
+end
+```
+
+Message-ID normalization removes surrounding angle brackets; it is correlation, not authorization. No provider ID means there is no safe automatic provider-ID match.
+
+## Reconcile uncertainty
+
+Restrict this operation to an authorized application operator. The gem records the supplied actor string; it does not authenticate that actor or verify external evidence.
+
+```ruby
+outbox.reconcile(
+  delivery,
+  outcome: :accepted,
+  actor: "User:42",
+  reason: "Provider support confirmed acceptance",
+  evidence: "Support ticket 123 and retained provider response",
+  provider_message_id: "provider-message-id",
+  recipients: ["customer@example.net"]
+) do |operation|
+  # Optional application update, atomic with the audit and state change.
+end
+```
+
+`outcome: :accepted` requires a valid provider Message-ID. `outcome: :not_sent` requires evidence of nonacceptance. Actor, reason, and evidence must be nonempty strings. Reconciliation can run inside an application transaction; callbacks and audit writes roll back together if it fails. Existing audit records are read-only through the model.
+
+For a partial operation, only unresolved recipients can be reconciled. Omit `recipients` to select the unresolved subset. Known outcomes and lifecycle state are preserved; later decisions can resolve another unknown subset. A conflicting provider ID is refused. A batch with all recipients confirmed not sent becomes `confirmed_not_sent`; a mixed batch remains partial or otherwise reflects the remaining acceptance evidence. Never retry a complete partial batch to reach one unresolved recipient.
+
+For a `sending` operation, first stop the original sender and verify it cannot resume. Reconciliation additionally requires `confirm_sender_stopped: true` and a claim at least 15 minutes old. Elapsed time alone is insufficient. There is no automatic lease expiry or timeout-based resend.
+
+## Data ownership and migration
+
+The gem owns its operation, recipient, receipt, and reconciliation infrastructure. The inbox owns mailbox permissions, conversations, approval policy, AI drafts, and UI. Link product records to operations by a stable key or application foreign key instead of copying the ledger algorithm.
+
+The MIME snapshot contains email bodies, addresses, and attachments. Apply your application's database access, encryption, backup, and retention policies. Removing ledgers or replaying old backups can discard uncertainty and deduplication evidence; quiesce sending and reconcile provider activity during recovery.
+
+Importing historical attempts is application-specific. If the old application did not save exact MIME, a reconstructed snapshot is historical metadata, not proof of the original bytes. Preserve its known/unknown state and do not turn imported accepted or uncertain attempts into dispatchable `prepared` operations. The generated outbox and receipt migrations refuse rollback to preserve delivery and deduplication evidence; use a forward fix or a reconciled backup.

data/docs/tenant-mailboxes-plan.md

@@ -0,0 +1,149 @@
+# Tenant-aware mailbox layer — implementation proposal
+
+Status: original design record. The reusable mailbox module and tenant adapter
+are implemented on the feature branch; see [mailboxes](mailboxes.md) and
+[tenant setup](activerecord-tenanted.md) for the actual API. Rebulk application
+migration and live customer rollout remain separate work. Based on the gem's merged 0.2
+code and Rebulk/rebulk-system main at
+`17ffafccb69968dae022acdbb4620b84c65bedfb`.
+
+## Product goal
+
+Let a Rails application create, suspend and manage named mailboxes for its
+organizations, sites or users. Support organization subdomains such as
+`houston@venezia.rebulk.com`. Reuse the gem's transport, outbox and receipts;
+do not create another delivery ledger. SQLite remains the default integration
+target, including separate SQLite databases with `activerecord-tenanted`.
+
+## Rebulk already has the foundations
+
+- `Organization` is shared and carries `email_subdomain`.
+- `TenantRecord` uses `activerecord-tenanted` and requires a tenant context.
+- Sites have per-organization email local parts. `tracking@<org>.rebulk.com`
+  is an existing reserved organization-level destination.
+- `Customer` is a buyer within an organization, not the tenant root. A customer
+  mailbox can belong to that record without creating another tenant database.
+- ActiveStorage is tenant-specific. Mail must resolve its tenant before blob
+  access, persistence or job deserialization that needs tenant records.
+- `InboundEmail` records document-processing outcomes inside the tenant.
+  `CommunicationMessage` is a shared, encrypted cross-channel operational view.
+  Preserve these product roles instead of replacing them with duplicate models.
+- Existing ingest has its own Worker contract, sender authentication and
+  authorization, raw archive and document processing. It is not currently the
+  gem's ActionMailbox pipeline. Its policy cannot be discarded during migration.
+- `OrganizationEmailDomain` supports sign-in auto-join. Receiving-domain
+  ownership must be separate; creating a receiving domain must never grant users
+  membership or change login policy.
+
+## Database and routing boundary
+
+Keep a minimal shared receiving-domain directory: exact canonical domain,
+immutable tenant identity, tenant connection key, lifecycle state and provisioning
+evidence. Enforce domain ownership with a database uniqueness constraint. Never
+construct a SQLite path from an arbitrary recipient string or request parameter.
+
+Keep mailbox definitions, address aliases, message memberships, outbox records
+and tenant receipts in the tenant database. Support an application-selected
+ActiveRecord base class so every related gem model uses the intended connection.
+Merely wrapping today's hardcoded `ActiveRecord::Base` models in `with_tenant`
+does not establish that connection contract.
+
+The ingress sequence must be:
+
+1. Bound the body and verify the complete Worker signature and envelope.
+2. Resolve the exact signed recipient domain in the shared active directory.
+3. Enter the mapped tenant context, without creating a tenant implicitly.
+4. Resolve the registered active mailbox/alias inside that tenant.
+5. Persist raw mail and mailbox membership idempotently, then schedule processing.
+6. Restore tenant context even when processing raises.
+
+No MIME To/Cc, browser session fallback, sender domain or guessed organization
+slug may select the receiving tenant. Unknown/suspended domains and addresses
+must have explicit rejection or restricted quarantine outcomes, with no fallback
+to an arbitrary tenant/mailbox. Directory changes and mailbox suspension must
+also be checked when deferred work resumes; never silently reassign old mail.
+
+## Optional mailbox module
+
+Add explicit opt-in loading and a generator. The initial contract should cover:
+
+- Tenant/domain registration and verified provisioning state.
+- Mailbox creation, aliases, suspension and lookup by registered address.
+- Application ownership links for user/site/customer mailboxes, checked within
+  the resolved tenant; authenticated actor authorization stays in the host app.
+- Incoming message membership and deduplication without another copy of MIME.
+- Outgoing preparation through an active mailbox with an allowed From address,
+  linked to the existing outbox. A customer cannot select another tenant's
+  sender merely because both share the same Cloudflare account token.
+- An explicit tenant context adapter and connection-class configuration;
+  `activerecord-tenanted` is an optional integration, not a plain-Ruby dependency.
+
+Do not claim a finished inbox UI, IMAP/POP service, thread model, AI workflow,
+search engine or membership system. Rebulk supplies those product decisions.
+Document local-part case policy, reserved names and alias behavior before schema
+implementation; normalization must agree across directory, mailbox and send APIs.
+
+## Jobs, events and cross-database commits
+
+Jobs carry stable tenant and operation/mailbox identities. Establish tenant
+context before loading records. Never rely on a previous request's `Current`
+state, a naked numeric record ID or a Cloudflare account ID as a tenant key.
+Cloudflare account identity and application tenant identity are different.
+
+Queue events arrive without a Rails tenant context and may precede a saved send
+response. Use a shared durable receipt intake and a provider correlation
+directory populated by tenant outbox results. Retain unmatched events and retry
+when correlation becomes available; do not infer tenant ownership solely from
+the recipient's external domain. Ambiguous mappings remain unprojected.
+
+Delivery from shared intake to tenant projection is at least once. A tenant
+receipt deduplicates it. Mark shared processing complete only after tenant commit;
+crashes between commits cause safe replay. Writes to the shared directory,
+tenant SQLite and job queue are not one transaction. Recovery must cover each
+gap without allowing another send or prematurely acknowledging an event.
+
+## Customer subdomains and Cloudflare
+
+An organization may use a Rebulk-owned subdomain or, later, an explicitly verified
+customer-owned domain. Track receive readiness and send-domain verification
+separately. A Rails database record or wildcard DNS entry alone does not enable
+Cloudflare email routing or sending.
+
+Prefer explicit address rules for the first supported provisioner. Reconcile
+desired state with Cloudflare and retain failures for retry rather than marking
+a mailbox active before its route is ready. Multiple tenants may share a Worker
+and ingress secret within one application/environment; tenant routing stays in
+Rails. Separate Cloudflare accounts require account-aware credentials/jobs.
+
+The current catch-all task operates at zone scope. Do not alter the Rebulk apex
+catch-all or promise automatic subdomain catch-alls as part of mailbox creation.
+Verify provider support and limits for the exact subdomain topology before a
+live rollout. Custom domains need ownership verification and safe offboarding.
+
+## Implementation slices and acceptance checks
+
+1. **Tenant foundation:** configurable model connections, tenant-aware job
+   wrappers and migrations in the tenant migration path. Test two real SQLite
+   tenant databases with overlapping IDs, missing context, retries and cleanup.
+2. **Mailbox registry:** shared domain mapping plus tenant mailboxes/aliases,
+   lifecycle and ownership APIs. Test exact matching, uniqueness races,
+   suspension, reserved addresses and isolation for lookup and sending.
+3. **Tenant ingress:** authenticated envelope resolution before ActionMailbox
+   storage. Test Bcc routing, raw bytes, duplicate delivery, unknown destinations,
+   tenant-specific blob access and processing jobs after process restart.
+4. **Outbound/event integration:** reuse saved MIME/claims, enforce mailbox sender
+   identity, add durable shared-to-tenant event dispatch and repair scans. Test
+   event-before-response, duplicate receipts and crashes at each commit boundary.
+5. **Rebulk adoption:** map existing org/site addresses, preserve tracking and
+   sender-review policies, link existing communication/ingest records, and add
+   mailbox management through Rebulk's access resolver. Start behind a feature
+   flag on an isolated development address; keep current production routes intact.
+6. **Provisioning and live verification:** test domain/route setup with bounded
+   retries, then a real send/reply/attachment/event flow for two test tenants.
+   Verify the deployed revision and preserve a dated report before customer rollout.
+
+Required regressions include existing plain-Ruby, single-database SQLite and
+PostgreSQL behavior. Do not call the integration complete merely because a
+single-tenant send works. Existing Rebulk sender-authentication metadata must
+remain authenticated through the new Worker contract before its old ingress
+can be retired; the gem's v2 envelope alone does not supply that policy evidence.

data/docs/thread-correlation.md

@@ -0,0 +1,27 @@
+# Thread correlation
+
+Store the provider's returned `message_id` with the intended recipient and your
+application conversation. The ActionMailer delivery method updates the Mail
+object's message ID when Cloudflare returns one. Plain Ruby callers can read
+`response.message_id`.
+
+Normalize stored IDs and parsed `In-Reply-To` / `References` values with
+`Cloudflare::Email::MessageId.normalize(value)`. This removes surrounding whitespace
+and one complete angle-bracket pair; it preserves case. Parse multiple-ID headers
+with your mail parser first. Match `In-Reply-To` first, then `References` from most
+recent to oldest, scoped to the authenticated recipient's mailbox.
+
+Outgoing replies should set `In-Reply-To` and `References` using the parent
+message's ID. Keep unmatched replies available for application handling when an
+ID is missing or unknown. Send acceptance and saving the returned ID are not one
+atomic transaction.
+
+The old `SecureMessageId` helper was removed before the 0.2 release. Cloudflare
+controls Message-ID and our [live test](verification/2026-09-10-live.md) confirmed
+replacement of custom IDs for both raw MIME and ActionMailer sends. The provider's
+returned IDs matched received headers and supported reply correlation.
+
+Email headers locate a conversation; they do not authorize access to it. Scope
+lookups by the trusted SMTP recipient obtained through `Envelope.for(inbound)`.
+The SMTP envelope sender and MIME From header do not authenticate a person.
+Sensitive actions require your application's authentication and approval policy.