MAS-WP-0010 proposed: mode reference implementation (contract, email master/slave, stubs)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 5787@bnt-lap001
Assistant-Session: 5db26b82-138b-40cc-9856-4d5eb0f752fd

workplans/MAS-WP-0010-mode-reference-implementation.md

@@ -0,0 +1,171 @@
+---
+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.