mail-address-semantics/SCOPE.md

# SCOPE

## One-liner

Reference implementation and spec workbench for Mail Address Semantics
(MAS), and the email building block for a future multimodal communication
framework. Contents: parser, statute discovery, pure policy, generator,
CLI, mail gateway, reference ticket service, a tested Postfix integration
profile, and the mode contract with an email side that works as master or
slave. It implements address spec v0.1.1, the v0.2 draft and mode contract
v0.1 (draft).

## Core Idea

Test whether ordinary email addresses can carry limited, parseable
semantics (opaque targets, `type=id` resources, `+` facets, `!`
interaction preferences) through real mail infrastructure, without
changing SMTP and without making addresses credentials or commands
(INTENT.md). The architectural boundary is fixed: the parser does no I/O,
policy is pure, only `mas_core/discovery.py` touches the network, and
delivery stays external.

## In Scope

- **Normative bundles.** `mas-v0.1-spec/` (v0.1.1 errata) and
  `mas-v0.2-spec/` (draft: stand-ins, destination transforms,
  `resource_id_case`). Spec changes go through
  `docs/spec-change-proposals.md`.
- **`mas_core`.** Parser, model, statute validation and lint, exact-host
  discovery with explicit `inherits`, policy, and the generator with v0.2
  destination transforms.
- **`mas_conformance`.** Address, property, statute and v0.2
  statute-aware corpora, vendored unchanged from the bundles and checked
  for drift.
- **`mas` CLI.** `parse`, `explain`, `discover`, `compose`,
  `lint-statute`, `test`.
- **`mas_gateway`.** MTA `pipe` and provider-style `webhook` to a
  normalized HTTP event. It reads sender authentication only from trusted
  `Authentication-Results`.
- **Examples.** A static statute and the reference ticket service: create,
  correlate by address, closed lifecycle, quarantine, a DMARC-gated reply,
  and a lifetime send cap.
- **MTA integration.** `integrations/postfix/` (profile plus README),
  tested against a real Postfix by `experiments/postfix-probe/` and
  `tests/test_postfix_profile.py` (needs Docker). Exim: notes only
  (`integrations/exim/NOTES.md`).
- **Mode reference implementation** (INTENT.md, *Mode reference
  implementation*). `mas-modes-v0.1-spec/` is a language-neutral contract
  (handoffs, statuses, timeouts, master/slave roles, outside-master
  commands) with JSON schemas, including the gateway event, and
  conformance flows. `mas_modes/` holds the email side in both roles
  (master per resource type over the ticket service, or slave to an
  outside master that issues case ids), a scripted callback stub, a stub
  outside master and the flow runner. Email is the only real channel. See
  `docs/reuse-surface.md`.
- **Live test environment.** `deploy/railiance/`: the MX for
  `mas.coulomb.social`, with replies through Scaleway TEM capped at 300.
  It is temporary; MAS-WP-0007 retires it.

## Out of Scope

- Real non-email modes (telephony, chat, SMS, video), connectors to real
  CMS or ticketing products, and the multimodal framework itself. Other
  modes exist here only as contract-speaking test stubs.
- Implementations in other languages (TypeScript, Go), until a second
  consumer exists. That is also the gate for declaring v0.2 final
  (MAS-WP-0009).
- Postfix policy daemon, Exim profile (until there is demand), mail-client
  plugins and inspectors, browser extensions, a web composer.
- Central MAS registry, signed statutes, implicit parent-domain
  inheritance, production identity federation.
- P3 economic semantics: `$` and `^` stay reserved. Also payments,
  signatures and marketplaces.
- Application business logic in the gateway. Production ticketing. Sender
  policy beyond what the reference service needs to avoid backscatter.
- Irreversible operational actions (cluster teardown, key revocation,
  redeploys) without founder approval.

## Current State

- Status: active. The reference experiment (MAS-WP-0002) passed its
  decision gate on 2026-10-18; the findings are in
  `docs/experiment-review.md`.
- Finished: MAS-WP-0001 to 0006, 0008, 0010 and 0011 (peer
  authentication in the mode contract). Postfix profile, v0.1.1
  errata, v0.2 draft, address composer, v0.2 conformance cases, and the
  mode contract with its reference implementation.
- Open: MAS-WP-0007 (retire the live MX; backlog, kept by decision),
  MAS-WP-0009 (declare v0.2 final; waits for a second implementation),
  and MAS-WP-0012 and 0013 (proposed).
- v0.2 stays a draft (founder, 2026-10-19).
- P2 is decided: `!MODE` requests a handoff (founder, 2026-10-19; SCP-8,
  v0.2 §7.1). The mode contract v0.1 draft and the reference
  implementation are done (MAS-WP-0010); `mas test` runs the contract
  corpus.
- The live MX runs image `mas-live:v0.2-a95f848` (redeployed 2026-10-19)
  and is kept up by founder decision (MAS-WP-0007 stays in backlog).
  Open follow-ups: MAS-WP-0012 (one outbound path and cap), 0013
  (harness-independent flows), 0009 (second implementation, now covering
  both drafts).
- Tests: `.venv/bin/pytest` runs 249 tests, offline apart from loopback
  fixtures and the Docker probe. `mas test` runs four corpora: parser
  62, statute 16, v0.2 statute-aware 29, mode contract 194.
- Assessments: `history/` (latest: `2026-10-19T090725Z-scope-vs-intent.md`).

## Getting Oriented

- Start with: INTENT.md, then `docs/experiment-review.md` and
  `docs/reuse-surface.md`
- Agent instructions: AGENTS.md
- Workplans: workplans/