mail-address-semantics/mas-modes-v0.1-spec/CONTRACT.md

# MAS mode contract v0.1 (draft)

How email hands a conversation to another communication mode, and how
email works inside a control flow it does not own. The bundle is
versioned separately from the MAS address specification. In MAS terms,
`ticket!callback@D` *requests* a handoff to `callback` (address spec §7).
This contract defines what can happen to that request.

The keywords MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.

## 1. Concepts

- **Case.** A unit of communication. It is addressed by a canonical MAS
  resource address (`ticket=gs-1@D`), and identified by that address and
  its equivalence key (address spec §8).
- **Thread.** The durable record of a case: inbound and outbound mail, plus
  every mode status.
- **Mode.** A communication channel other than email (`callback`, `chat`,
  ...), reached through a **mode endpoint** that speaks this contract.
- **Handoff.** One attempt to continue a case in a mode. It has a
  `handoff_id` and a status (§4).
- **Role.** For each resource type, email is either **master** or **slave**
  (§3). The role is fixed for the life of a case.
- **Outside master.** In the slave role, the system that owns the control
  flow (a CMS, ticketing or support system, or a framework).

## 2. Parties and transport

There are three parties: `email`, `mode` and `master`. Messages are JSON
objects, sent as HTTP `POST` with `Content-Type: application/json`. Every
message carries the envelope:

| Field | Meaning |
|---|---|
| `mas_modes_version` | `"0.1"` |
| `type` | message type (§5) |
| `id` | sender-chosen unique id; the idempotency key |
| `case` | `{address, key}`: canonical resource address and equivalence key. Absent only in `case.intake` and `case.assign`. |

- **Idempotency.** A receiver MUST treat a repeated `id` as already
  processed, and SHOULD return the original response.
- **Ordering.** `handoff.status` carries `seq`, increasing per handoff. A
  receiver MUST ignore a status whose `seq` is not greater than the last
  one it accepted, and answers `{"ok": true, "ignored": "stale"}`.
- **Responses.** `2xx` with `{"ok": true, ...}` means the message was
  accepted. `4xx` with `{"ok": false, "error": CODE, "detail": ...}` means
  it was refused and MUST NOT be retried unchanged. `5xx` or no answer
  means the sender MAY retry with the same `id`.

## 3. Roles

### 3.1 Email as master

Email owns the case, the thread and the timeouts.

1. On `!MODE` to an intake or resource address, email creates or finds the
   case. Then it sends `handoff.request` to the mode endpoint configured
   for that resource type and mode. If none is configured, or the statute
   does not enable the mode, email records a `refused` status itself and
   continues by email.
2. Email sets a **deadline** for each handoff. If no terminal status
   (§4) has arrived by then, email records `timed-out`, sends
   `handoff.cancel` to the mode, and resumes by email.
3. Every status is recorded in the thread. On every terminal status, email
   **resumes**: it sends the case's participant one mail from the case
   address, saying what happened. Principle 10 (§6) applies.
4. Negotiation: `negotiating` with `needs` makes email ask the participant
   by email for the missing details. A reply on the case address that
   supplies them is sent to the mode as `handoff.update`.

### 3.2 Email as slave

The outside master owns the control flow, case identifiers and timeouts.

1. **Case identifiers come from the master.** Intake mail (no case yet) is
   reported as `case.intake` with an `intake_ref`. The master answers with
   `case.assign`, giving the resource id, which email adopts as the case
   address `TYPE=ID@D`. Email MUST NOT invent case identifiers in this
   role. Until assigned, the intake stays pending. `case.assign` MAY carry
   the case's initial `policy`. A mode requested in the intake mail
   (`requested_mode`) is handled under that policy once the case exists.
2. Inbound mail on a case is reported as `case.message`.
3. **Sending.** Email sends only on `mail.send` from the master, unless the
   case policy (`case.policy`) sets `autonomous_send: true`. Then email
   MAY also send acknowledgements and negotiation questions itself. A
   `mail.send` is always a reply to a message already recorded on the case
   (`in_reply_to`): the recipient is that message's sender. A requested
   send can still be refused under §6, and the refusal is the response.
   Policy fields the master does not set take the email side's defaults
   for the resource type.
4. **Transfers.** The case policy sets `transfers` to `"block"` or to
   `{"webhook": URL}`. With `block`, a `!MODE` request is reported as
   `handoff.requested` with `"forwarded": false`, and nothing else
   happens. With a webhook, email sends `handoff.request` to that URL,
   relays every `handoff.status` to the master, and does the negotiation
   (3.1 item 4) only when `autonomous_send` is true.
5. **Timeouts belong to the master.** Email sets no deadline and never
   records `timed-out`. The master MAY end a handoff with `handoff.cancel`.

## 4. Handoff status machine

| From | Allowed next statuses |
|---|---|
| (new) | `requested` |
| `requested` | `negotiating`, `scheduled`, `running`, `refused`, `failed`, `cancelled`, `timed-out` |
| `negotiating` | `negotiating`, `scheduled`, `refused`, `expired`, `cancelled`, `timed-out` |
| `scheduled` | `running`, `attempted`, `expired`, `cancelled`, `timed-out` |
| `attempted` | `scheduled`, `failed`, `expired`, `cancelled`, `timed-out` |
| `running` | `completed`, `failed`, `cancelled`, `timed-out` |

**Terminal** statuses are `completed`, `failed`, `expired`, `refused`,
`cancelled` and `timed-out`. Nothing follows a terminal status.

- `requested`: recorded by email when it sends `handoff.request`.
- `negotiating`: the mode needs details. `needs` lists field names
  (`phone`, `time`, ...).
- `scheduled`: has `at` (RFC 3339) when known. Going from `attempted` to
  `scheduled` is a retry.
- `attempted`: an attempt did not reach the participant. `outcome`, e.g.
  `no-answer`.
- `refused`: has `reason`, one of `mode-unavailable`, `mode-not-enabled`,
  `declined`, `out-of-hours`, `blocked`.
- `timed-out`: recorded only by the timeout owner: email as master, or the
  master's own bookkeeping. A mode MUST NOT send it.
- `cancelled`: after `handoff.cancel`.

A receiver MUST refuse a transition that the table does not allow
(`error: invalid-transition`).

## 5. Message types

| Type | From → to | Payload |
|---|---|---|
| `handoff.request` | email → mode | `handoff_id`, `mode`, `details` (known fields), `status_url` (where statuses go), `participant` (`{address}`) |
| `handoff.update` | email → mode | `handoff_id`, `details` |
| `handoff.cancel` | email → mode, master → email | `handoff_id`, `reason` |
| `handoff.status` | mode → email, email → master (relay) | `handoff_id`, `seq`, `status`, plus `needs` / `at` / `outcome` / `reason` / `detail` |
| `case.intake` | email → master | `intake_ref`, `resource_type`, `event` (gateway event), `requested_mode` |
| `case.assign` | master → email | `intake_ref`, `resource_id`, optional `policy` (`{autonomous_send, transfers}`) |
| `case.message` | email → master | `event`, `message_ref` |
| `case.policy` | master → email | `autonomous_send` (bool), `transfers` (`"block"` or `{"webhook": URL}`) |
| `handoff.requested` | email → master | `handoff_id`, `mode`, `forwarded` (bool) |
| `mail.send` | master → email | `in_reply_to` (a `message_ref`), `subject`, `body` |

`event` is the normalized gateway event (`schema/mas-event-v0.1.schema.json`).
`message_ref` is the email side's id for a recorded inbound message.

`mail.send` responses: `{"ok": true, "sent": true}`, or `{"ok": false,
"error": "refused", "reason": R}` with R one of `unauthenticated-sender`,
`automated-sender`, `send-cap-reached`, `unknown-message`.

## 6. Principle 10 in both roles

Email MUST NOT send mail to a sender that did not pass DMARC (as read
from trusted `Authentication-Results`), to automated mail (`Auto-Submitted`
other than `no`, or `Precedence: bulk | list | junk`), or to the null
sender. It MUST NOT send once its send cap is reached. These rules hold
whoever asks for the send: email itself as master, the case's autonomous
policy, or a master's `mail.send`.

## 7. Conformance

`conformance/` holds valid and invalid messages, the transition table as
data, and scripted flows. Each flow is a sequence of inbound mail,
contract messages and clock ticks, with the expected email-side reaction.
An email-side implementation claims `MAS-MODES-EMAIL-MASTER`
or `MAS-MODES-EMAIL-SLAVE` by passing the flows for that role.