mail-address-semantics/workplans/MAS-WP-0010-mode-reference-implementation.md

---
id: MAS-WP-0010
type: workplan
title: "Mode reference implementation: contract, email master/slave roles, stubs"
domain: communication
repo: mail-address-semantics
status: proposed
owner: claude
topic_slug: coulomb-social
created: "2026-10-19"
updated: "2026-10-19"
---

# Mode reference implementation

Implements the *Mode reference implementation* and *Current scope and
reuse surface* sections of INTENT.md (founder interview, 2026-10-19).
`!MODE` requests a handoff from email to another mode. A language-neutral
**mode contract** defines handoffs, and email implements it in two roles,
configured per resource type:

- **master**: email owns the durable thread and timeouts, and resumes after
  another mode ends;
- **slave**: an outside master issues case ids, decides per case whether
  email may send on its own, blocks transfers or primes them with a mode
  webhook, and owns timeouts.

Email is the only real channel. Other modes are contract-speaking test
stubs, callback first. Principle 10 (gated and capped auto-replies) holds
in both roles.

Order: T01 → T02 → (T03, T04) → T05 → T06 → T07. T08 can run once T01 is
done.

## Contract design

```task
id: MAS-WP-0010-T01
status: todo
priority: high
```

Write `mas-modes-v0.1-spec/CONTRACT.md`. It is a bundle of its own,
versioned apart from the address spec. It defines:
- concepts: case, thread, mode, handoff, role, status, timeout, refusal;
- message types, from mode to email: handoff request, mode status
  updates, completion. From the outside master to email: assign case id,
  send, set the send-on-its-own policy, block or prime transfers (mode
  webhook URL);
- the handoff status machine: requested → negotiating → scheduled →
  running → completed | failed | expired | refused | timed-out. It records
  who owns each timeout in each role;
- how refusals and principle-10 refusals are reported;
- transport: JSON over HTTP, idempotency keys and ordering;
- correlation: every message carries the case's canonical resource
  address and equivalence key.

Review the design with the founder before T02.

## Schemas and conformance fixtures

```task
id: MAS-WP-0010-T02
status: todo
priority: high
```

Write JSON schemas for every message type in T01. Add conformance fixtures
in the bundle: valid and invalid messages, a table of allowed and refused
status transitions per role, and scripted flows (sequences with expected
email-side reactions). Vendor them into the package with a drift test, as
for `mas_conformance`.

## Gateway event schema

```task
id: MAS-WP-0010-T03
status: todo
priority: medium
```

Formalize the existing normalized event (`mas_event_version`,
`recipient`, `mas`, `message`, trusted `authentication`) as a JSON schema.
Validate gateway output against it in tests. It becomes a reuse-surface
item, so slave-mode masters can consume inbound events directly.

## Callback stub mode server

```task
id: MAS-WP-0010-T04
status: todo
priority: high
```

A scriptable stub that speaks the contract. Scenarios are deterministic,
selected by a fixture or a test header, and reproducible:
- negotiation over email: number or time missing → question → reply →
  schedulable;
- outcome lifecycle: scheduled, attempted with no answer, retried,
  completed, failed, expired;
- refusals: mode unavailable or not enabled, declined, out of hours.

It never contacts a person or service. Optionally, add a trivial second
stub to show that the contract is generic.

## Email as master

```task
id: MAS-WP-0010-T05
status: todo
priority: high
```

Extend the reference ticket service, or put a thin email-mode layer over
the gateway, so that resource types configured as master:
- on `!MODE`, negotiate missing details by email, then hand off to the
  stub;
- record every mode status in the ticket thread;
- own the timeouts, and resume by email after a timeout, failure,
  completion or refusal;
- keep principle 10 for every outbound mail.

Add end-to-end tests against the callback stub for every scenario.

## Email as slave, with a stub outside master

```task
id: MAS-WP-0010-T06
status: todo
priority: high
```

Build a minimal fake CMS/ticketing master, plus the email slave role for
the resource types configured that way:
- the master issues the case id; email exposes it as a resource address
  (`case=EXT-123@`) and maps it but never invents it. Intake mail without
  a case is reported, and the master answers with the id;
- inbound mail goes to the master as events (T03);
- outbound mail only on instruction, or under the master's per-case
  send-on-its-own policy. Principle-10 refusals are reported back;
- transfers are blocked, or call the primed mode webhook; timeouts are
  left to the master.

Add end-to-end tests: stub master + email slave + callback stub.

## Conformance runner and reuse docs

```task
id: MAS-WP-0010-T07
status: todo
priority: medium
```

Add a runner (`mas test` and pytest) that checks the email side against
the T02 fixtures in both roles. Write a reuse-surface README covering what
a framework can depend on and how stable it is (contract, schemas,
`mas_core`, address spec), and what is only an example (ticket service,
stubs). Update SCOPE.md.

## Record handoff semantics in the address spec

```task
id: MAS-WP-0010-T08
status: todo
priority: medium
```

Write a spec change proposal (SCP-8) and put it into the v0.2 draft:
§7 says `!MODE` requests a handoff whose behavior the mode contract
defines, and points to `mas-modes-v0.1-spec/`. No grammar or statute
change. Add CHANGELOG and CONFORMANCE notes.