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

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

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

id: MAS-WP-0010-T01
status: todo
priority: high
state_hub_task_id: "1b4915f8-a6c4-5d0f-8d51-0e0437e0ebc6"

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

id: MAS-WP-0010-T02
status: todo
priority: high
state_hub_task_id: "e0af967d-15e8-50ad-8930-ad569224cddf"

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

id: MAS-WP-0010-T03
status: todo
priority: medium
state_hub_task_id: "045bb7b0-59b3-57a6-b226-cf268b7c9690"

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

id: MAS-WP-0010-T04
status: todo
priority: high
state_hub_task_id: "1552686b-da8c-518e-8e81-49a6f7d312ff"

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

id: MAS-WP-0010-T05
status: todo
priority: high
state_hub_task_id: "8b75fec4-97e3-540f-b377-aa4e0166e1c4"

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

id: MAS-WP-0010-T06
status: todo
priority: high
state_hub_task_id: "fbef3fea-c0b6-5e79-bdf9-95bbf98c9bc6"

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

id: MAS-WP-0010-T07
status: todo
priority: medium
state_hub_task_id: "0fcb541f-cab8-5014-aee0-4332fc7e0642"

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

id: MAS-WP-0010-T08
status: todo
priority: medium
state_hub_task_id: "7d5dca10-184f-5b96-a280-b59dd8d77c60"

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.