@spec assert_stamped!() :: :ok

Raises %Mailglass.TenancyError{type: :unstamped} if no tenant is stamped in the current process. Returns :ok otherwise.

Unlike current/0, does NOT fall back to the SingleTenant default. This is the SEND-01 precondition (D-18) — ensures Events.append_multi/3 auto-capture via Tenancy.current/0 does not silently default to "default" in a multi-tenant adopter.

@spec audit_unscoped_bypass(keyword() | map()) :: :ok

Emits an audit breadcrumb when a call intentionally opts into scope: :unscoped access.

This keeps the bypass path explicit and machine-searchable for TENANT-03 reviews.

@spec clear() :: :ok

Clear any tenant scope set in the current process dictionary.

Returns :ok. Primarily used by test on_exit cleanup — encapsulates the internal process-dict key so tests don't need to know the exact atom (:mailglass_tenant_id). Production code should rely on with_tenant/2 block scoping (Pitfall 7), which auto-restores prior scope even on raise.

@spec current() :: String.t() | nil

Returns the current tenant_id or the configured resolver's default.

Reads the process-dict first; falls back to the configured resolver's default when nothing has been stamped. With the default Mailglass.Tenancy.SingleTenant resolver active and no explicit stamping, returns the literal "default". With an adopter resolver configured, returns nil unless the adopter's own fallback is wired in via put_current/1.

@spec put_current(String.t() | nil) :: :ok

Stamps the current tenant in the process dictionary.

Subsequent current/0 calls return this value (until the process exits or put_current/1 is called again). Passing nil deletes the stamp; current/0 then falls back to the resolver's default.

@spec resolve_webhook_tenant(map()) :: {:ok, String.t()} | {:error, term()}

Dispatch to the configured tenancy module's resolve_webhook_tenant/1 callback (Phase 4 D-12 — the optional callback Plan 05 formally declares).

Returns {:ok, tenant_id} on success or {:error, reason} when the adopter's tenancy module cannot map the verified webhook context to a known tenant. Mailglass.Webhook.Plug rescues the latter as a 422 via %Mailglass.TenancyError{type: :webhook_tenant_unresolved}.

The context map shape is documented in CONTEXT D-12:

%{
  provider: :postmark | :sendgrid,
  conn: Plug.Conn.t(),
  raw_body: binary(),
  headers: [{String.t(), String.t()}],
  path_params: map(),
  verified_payload: map() | nil
}

Fallback behaviour

Mailglass.Tenancy.SingleTenant ships a concrete resolve_webhook_tenant/1 impl that returns {:ok, "default"} — the zero-config single-tenant default. Adopter tenancy modules that do not implement the optional callback also fall through to {:ok, "default"} via the dispatcher's function_exported?/3 check; multi-tenant adopters MUST implement the callback to get meaningful tenant routing.

@spec scope(Ecto.Queryable.t(), term()) :: Ecto.Queryable.t()

Scopes queryable to the current (or supplied) tenant context via the configured resolver.

With Mailglass.Tenancy.SingleTenant, this is a no-op. With an adopter resolver, this injects a WHERE tenant_id = ? clause (or equivalent) into the query.

@spec tenant_id!() :: String.t()

Returns the current tenant_id or raises Mailglass.TenancyError.

Unlike current/0, this does NOT fall back to the SingleTenant default. Use this when the caller is certain it holds tenant context (e.g. inside an Oban worker after the middleware has run) and wants to fail loud on the "forgot to stamp" programmer error.

@spec with_tenant(String.t(), (-> any())) :: any()

Runs fun with tenant_id stamped as the current tenant, then restores whatever was stamped before (nil if nothing).

Useful for tests and for Oban middleware serializing context across job boundaries (see Mailglass.Oban.TenancyMiddleware). The prior value is restored even when fun raises.