From ff1e139e8b52fea1b042dddeeb0e985fa3ded619 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 19 Oct 2026 11:11:17 +0200 Subject: [PATCH] Residuals of the 2026-10-19 assessment: MAS-WP-0011 (contract transport security), 0012 (one outbound path/cap), 0013 (harness-independent flows); MAS-WP-0009 widened 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 --- history/2026-10-19T090725Z-scope-vs-intent.md | 16 +++--- workplans/MAS-WP-0009-declare-v0-2-final.md | 7 ++- ...P-0011-mode-contract-transport-security.md | 57 +++++++++++++++++++ workplans/MAS-WP-0012-single-outbound-path.md | 51 +++++++++++++++++ .../MAS-WP-0013-harness-independent-flows.md | 48 ++++++++++++++++ 5 files changed, 171 insertions(+), 8 deletions(-) create mode 100644 workplans/MAS-WP-0011-mode-contract-transport-security.md create mode 100644 workplans/MAS-WP-0012-single-outbound-path.md create mode 100644 workplans/MAS-WP-0013-harness-independent-flows.md diff --git a/history/2026-10-19T090725Z-scope-vs-intent.md b/history/2026-10-19T090725Z-scope-vs-intent.md index 903153f..d0b725f 100644 --- a/history/2026-10-19T090725Z-scope-vs-intent.md +++ b/history/2026-10-19T090725Z-scope-vs-intent.md @@ -117,11 +117,13 @@ test` corpora, the undeployed Dockerfile); and the Getting Oriented section points to `docs/reuse-surface.md` and to this `history/` folder. In Scope and Out of Scope were already aligned with INTENT.md and are unchanged. -## Suggested next work (not yet recorded as work items) +## Follow-up work -1. Contract v0.1: transport security (risk B). Highest priority before any - integration. -2. One outbound path and one cap (risk C). Small. -3. Flow fixtures independent of the harness, and a second-language - consumer of both drafts (risk A, MAS-WP-0009). -4. Decision on MAS-WP-0007 (risk E). +Recorded on 2026-10-19, after this assessment: + +1. Contract transport security (risk B): **MAS-WP-0011**. Highest + priority before any integration. +2. One outbound path and one cap (risk C): **MAS-WP-0012**. +3. Flows independent of the harness (risk A): **MAS-WP-0013**. MAS-WP-0009 + is widened so the second-language consumer covers both drafts. +4. Live MX retire-or-redeploy (risk E): founder decision on MAS-WP-0007. diff --git a/workplans/MAS-WP-0009-declare-v0-2-final.md b/workplans/MAS-WP-0009-declare-v0-2-final.md index e0b4dd5..c307dbb 100644 --- a/workplans/MAS-WP-0009-declare-v0-2-final.md +++ b/workplans/MAS-WP-0009-declare-v0-2-final.md @@ -31,7 +31,12 @@ state_hub_task_id: "65fe7a3f-4142-5834-bca8-3de6b8839986" Wait for, or build, an implementation independent of `mas_core`, or a second deployment by another operator. It must pass `mas-v0.2-spec/conformance/addresses.json` and `statute-aware.json` -unchanged. Record every case where the fixtures or the spec text had to be +unchanged. It also covers the second draft (scope widened after the +assessment `history/2026-10-19T090725Z-scope-vs-intent.md`, risk A): a +small consumer in a second language that parses addresses and acts as +an outside master in the slave role is enough, provided it passes +`mas-modes-v0.1-spec/conformance/flows.json` unchanged. It depends on +MAS-WP-0013. Record every case where the fixtures or the spec text had to be read in a way `mas_core` does not. ## Declare final diff --git a/workplans/MAS-WP-0011-mode-contract-transport-security.md b/workplans/MAS-WP-0011-mode-contract-transport-security.md new file mode 100644 index 0000000..43dec5c --- /dev/null +++ b/workplans/MAS-WP-0011-mode-contract-transport-security.md @@ -0,0 +1,57 @@ +--- +id: MAS-WP-0011 +type: workplan +title: "Mode contract: peer authentication and transport security" +domain: communication +repo: mail-address-semantics +status: proposed +owner: claude +topic_slug: coulomb-social +created: "2026-10-19" +updated: "2026-10-19" +origin: residual +origin_ref: MAS-WP-0010 +--- + +# Mode contract: peer authentication and transport security + +Risk B in `history/2026-10-19T090725Z-scope-vs-intent.md`. `mail.send`, +`case.assign` and `case.policy` steer real outbound mail, and +`handoff.status` changes what email tells customers. Yet +`mas-modes-v0.1-spec/CONTRACT.md` does not say how email knows that a +master or mode is who it claims to be. The reference endpoints are +unauthenticated. This must be fixed before anyone integrates. + +## Design + +```task +id: MAS-WP-0011-T01 +status: todo +priority: high +``` + +Add a transport-security section to CONTRACT.md: +- per-peer authentication: a shared-secret HMAC over the body plus a + timestamp (replay window), or mTLS. Pick one as MUST and allow the other; +- bind each handoff to its mode endpoint: `handoff.status` is accepted + only from the endpoint that got the `handoff.request`. `status_url` + carries an unguessable per-handoff token; +- the slave master is configured per resource type, and commands from + any other peer are refused; +- error codes `unauthenticated-peer` and `replayed`. + +Review with the founder before implementing. + +## Implement and test + +```task +id: MAS-WP-0011-T02 +status: todo +priority: high +``` + +Put the chosen scheme into `mas_modes.contract` (sign and verify), into +`EmailMode` (all three endpoints) and into both stubs. Add fixtures +(signed and unsigned messages, a replayed message, a wrong peer) and +flows. Update `docs/reuse-surface.md`, which still says the endpoints are +loopback-only. diff --git a/workplans/MAS-WP-0012-single-outbound-path.md b/workplans/MAS-WP-0012-single-outbound-path.md new file mode 100644 index 0000000..013332b --- /dev/null +++ b/workplans/MAS-WP-0012-single-outbound-path.md @@ -0,0 +1,51 @@ +--- +id: MAS-WP-0012 +type: workplan +title: "One outbound path and one send cap" +domain: communication +repo: mail-address-semantics +status: proposed +owner: claude +topic_slug: coulomb-social +created: "2026-10-19" +updated: "2026-10-19" +origin: residual +origin_ref: MAS-WP-0010 +--- + +# One outbound path and one send cap + +Risk C in `history/2026-10-19T090725Z-scope-vs-intent.md`. With both +roles in one deployment, the ticket service and `mas_modes.mailer` each +keep their own outbox and cap. Total outbound can then reach about twice +the configured cap. They also act differently over the cap: the ticket +service keeps replies unsent, while the mailer refuses with +`send-cap-reached`. Principle 10 says "caps how much it can send in +total". + +## Route all mail through the mailer + +```task +id: MAS-WP-0012-T01 +status: todo +priority: medium +``` + +Make `mas_modes.mailer.Mailer` the only outbound path. The ticket service +then sends through a Mailer it is given, sharing the DB or an outbox +service, instead of its own `outbox` table and cap. Settle one behavior +over the cap, and record it in CONTRACT.md §6. Keep the ticket service's +`/outbox` inspection working, and keep the deployment's `--max-sent` +semantics. + +## Test the shared cap + +```task +id: MAS-WP-0012-T02 +status: todo +priority: medium +``` + +Add a test that a deployment with both roles stops at exactly N sends in +total, and that the live entrypoint still passes `MAS_MAX_SENT` to the +single cap. diff --git a/workplans/MAS-WP-0013-harness-independent-flows.md b/workplans/MAS-WP-0013-harness-independent-flows.md new file mode 100644 index 0000000..747662a --- /dev/null +++ b/workplans/MAS-WP-0013-harness-independent-flows.md @@ -0,0 +1,48 @@ +--- +id: MAS-WP-0013 +type: workplan +title: "Mode contract flows independent of the Python harness" +domain: communication +repo: mail-address-semantics +status: proposed +owner: claude +topic_slug: coulomb-social +created: "2026-10-19" +updated: "2026-10-19" +origin: residual +origin_ref: MAS-WP-0010 +--- + +# Mode contract flows independent of the Python harness + +Risk A in `history/2026-10-19T090725Z-scope-vs-intent.md`. +`mas-modes-v0.1-spec/conformance/flows.json` is language-neutral in +format, but it relies on harness details: the stub master assigns +`EXT-100`, `EXT-101`, ...; the role configuration is implied; and +expectation keys mirror `mas_modes.runner`. A second implementation could +not run the flows from the bundle alone. + +## Make flows self-describing + +```task +id: MAS-WP-0013-T01 +status: todo +priority: medium +``` + +Write the inputs into each flow: role configuration, assigned ids, and +the stub scenarios. Define every expectation key in CONTRACT.md §7 or a +`conformance/FLOWS.md`, in terms of contract messages and sent mail only. +Remove any expectation that only the Python harness can observe. + +## Runner follows the bundle + +```task +id: MAS-WP-0013-T02 +status: todo +priority: medium +``` + +Update `mas_modes.runner` and the stubs to read everything from the flow. +Keep `mas test` green. Add a fixture-level check that the bundle's flows +do not use undefined keys.