From 831bd2d41d5d55feb82be4d6ab9cb32184f3b815 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 19 Oct 2026 10:37:21 +0200 Subject: [PATCH] MAS-WP-0010 proposed: mode reference implementation (contract, email master/slave, stubs) Co-Authored-By: Claude Opus 5.5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 5787@bnt-lap001 Assistant-Session: 5db26b82-138b-40cc-9856-4d5eb0f752fd --- ...S-WP-0010-mode-reference-implementation.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 workplans/MAS-WP-0010-mode-reference-implementation.md diff --git a/workplans/MAS-WP-0010-mode-reference-implementation.md b/workplans/MAS-WP-0010-mode-reference-implementation.md new file mode 100644 index 0000000..9e496be --- /dev/null +++ b/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.