# Operator Trust

`mailglass_admin/docs/operator-trust.md` is the canonical admin trust doc for
the stable operator surface. It documents the semantic seams adopters can rely
on without treating LiveView, component, or DOM details as stable.

## Stable seams

The stable admin seams are:

- `MailglassAdmin.Router.mailglass_admin_routes/2` and
  `MailglassAdmin.Router.mailglass_operator_routes/2` as the documented mount
  macros
- the `MailglassAdmin.Auth` `authorize/2` callback as the adopter-owned
  authorization seam
- the explicit operator session contract for `subject_id`, optional
  `tenant_id`, optional `auth_method`, and optional `recent_auth_at`
- mount-time authorization through `:operator_access`
- action-time authorization through `:destructive_action`

These are semantic promises. They describe what adopters can mount, authorize,
and reason about. They do not freeze the implementation that renders the UI.

## Session contract

`mailglass_operator_routes/2` takes an explicit `:session` whitelist. The
operator session contract includes:

- required `subject_id`
- optional `tenant_id`
- optional `auth_method`
- optional `recent_auth_at`

`MailglassAdmin.Router` copies only those explicit keys into the operator
LiveView session. It does not pass through the entire Plug session, and it does
not promise any internal assign names beyond the documented actor semantics.

## Authorization timing

Authorization is split across two stable moments:

- `:operator_access` runs at mount time to decide whether the operator surface
  can be entered at all.
- `:destructive_action` runs at action time immediately before a sensitive
  operation such as replay.

This means mount-time access is not treated as blanket approval for later
destructive actions. Adopters keep ownership of the policy through
the `MailglassAdmin.Auth` `authorize/2` callback.

## Replay semantics

Replay is an operator recovery action against one exact stored inbound receive
truth for one selected delivery.

- Replay is exact-target, not delivery-wide guessing.
- Replay stays tenant-scoped.
- Replay is ledger-audited as requested, succeeded, or failed facts.
- Replay runs after canonical and raw evidence truth already exists; it is not
  a fresh provider receipt.
- Replay can honestly end in `new work` or `no change`.

Fresh provider receipt and later execution are intentionally distinct. The
durable promise is the stored inbound receive truth. Execution may happen later
through Oban-backed durable jobs or, when Oban is unavailable, through a
bounded Task.Supervisor fallback with no automatic retry. Replay is the
recovery tool when operators need to rerun stored truth after best-effort
fallback loss or a previous failure.

Replay and reconcile are intentionally distinct. Replay reruns one exact stored
inbound target through local semantics and does not silently reroute to a
different mailbox. Reconcile is background-first backlog maintenance for
unmatched webhook rows and is not a delivery-detail replay tool.

Known replay failure cases are also part of the honest operator story:

- `no_prior_match` means fresh execution history only proves `:no_match`, so
  replay cannot safely infer a mailbox target.
- `execution_history_missing` means the record predates execution-lineage
  capture or lacks the stored facts replay needs to rerun mailbox execution.

When execution history is incomplete, replay fails explicitly rather than
guessing. The current failure vocabulary includes `:no_prior_match` for records
whose fresh history never matched a mailbox and `:execution_history_missing`
for records that predate execution-lineage capture.

## Intentionally internal

The following remain intentionally internal for `v1.x`:

- LiveView modules
- component modules
- DOM/CSS shape
- event names
- modal details and layout
- internal assign names
- internal mount-hook and implementation wiring

Adopters should not depend on those details even if they are visible in source,
tests, or generated docs.