mail-address-semantics/mas_modes/conformance/FLOWS.md

Conformance flows (mode contract v0.1)

flows.json describes complete conversations that an email-side implementation must handle. A run needs only this bundle: flows.json, scenarios.json and statute.json. Every expectation is observable at the contract boundary: messages the stub parties receive, responses to contract requests, and mail the email side sends. Nothing depends on how an implementation stores data or answers the gateway.

Running a flow

For each flow, start fresh:

1. Email side. An email side for the statute in statute.json (namespace modes.example), configured with the flow's setup, i.e. setups[flow.setup].roles. Its own peer id is email, and it knows the keys in peers. A master role needs a store for its cases. The reference uses its ticket service, but any store that creates a case on intake mail and correlates mail to ticket=ID works.
2. Callback stub. Peer callback-1 speaks the contract and plays scenarios.json, with flow.scenario as its default. It sends nothing until a mode step.
3. Outside master stub. Peer cms-1 records every message it gets, and sends commands only in master steps.
4. Clock. A controllable clock for the email side's timeouts. Only advance steps move it. Signatures use real time.
5. Send cap. When flow.max_sent is set, the email side's send cap is that number, and an SMTP sink counts what is actually sent. Without it there is no cap.

Role configuration fields are those of CONTRACT.md §3. In a setup:

• modes: {MODE: {"peer": ID}} means the mode endpoint of that peer;
• master_peer is the outside master, which implies its event URL;
• "<mode:ID>" stands for the handoff URL of peer ID.

The implementation wires peer ids to its own URLs. The peers keys are public test keys, never to be used in a deployment.

Steps

Step	Meaning
{"mail": {to, text, dmarc?, subject?}}	Inbound mail from customer@example.net to TO@modes.example, through the normal gateway path. dmarc (default "pass") is the trusted Authentication-Results verdict; null means no verdict.
{"mode": "run"}	The callback stub sends every status that is due, until it is waiting, silent or terminal.
{"advance": N}	Move the email side's clock N seconds and let it run its timeouts.
{"master": {"command": C, ...}}	The stub master sends a signed contract command: assign (case.assign; resource_id, plus intake_ref, by default the captured one), send (mail.send; in_reply_to, body), cancel (handoff.cancel; handoff_id), or policy (case.policy). The case is the captured case.
{"inject": {endpoint, as?, sign?, token?, message}}	Send a crafted request straight to the email side: endpoint is master, status (the captured handoff's status URL) or events. as is the claimed peer id. sign is valid (default), none, stale (timestamp 400 s old) or wrong-key. token: "bogus" replaces the status URL token. In message, "case": "current" means the captured case, and the envelope (mas_modes_version, id) is added.

Strings in steps may contain the captures {case_id}, {message_ref}, {intake_ref} and {handoff_id}.

Captures

Captures are updated after every step, from what that step produced, in this order:

1. every message the mode stub and the master stub received;
2. the response to a master or inject step.

The latest value wins.

Capture	From
case (address, key)	the case of any of those messages or responses
{case_id}	the resource id in the captured case address (TYPE=ID@D)
{message_ref}	message_ref of case.message, or of the case.assign response
{intake_ref}	intake_ref of case.intake
{handoff_id}	handoff_id of handoff.request (mode) or handoff.requested (master)

Expectations

expect is checked after the step. Every key listed must match.

Key	Value
event_accepted	the email side answered the step's inbound mail event with 2xx
mode_statuses	statuses of every handoff.status the mode stub sent, in order
mode_received	number of contract messages the mode stub received
mode_received_last	type of the last one
master_received	{type: count} of messages the master stub received; only the listed types are compared
relayed	statuses of every handoff.status the master stub received, in order
mails_sent	number of mails the email side sent (held and refused mail excluded)
last_mail_contains	the body of the last mail sent contains this text
response_ok	ok in the response to the step's command
response_reason	reason in that response
response_held	held in that response (CONTRACT.md §6)
case_address	case.address in that response
http_status	HTTP status of that response
error	error in that response

A runner MUST reject a flow that uses a step or expectation key not defined here.