mail-address-semantics/SCOPE.md

SCOPE

One-liner

Reference implementation and spec workbench for Mail Address Semantics (MAS): parser, statute discovery, pure policy, generator, CLI, mail gateway, reference ticket service, and a tested Postfix integration profile. It implements v0.1.1 and the v0.2 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 (new; INTENT.md, Mode reference implementation). A language-neutral mode contract (handoffs, statuses, timeouts, master/slave roles, outside-master commands) with JSON schemas and fixtures. The email side implements both roles: master per resource type, or slave to an outside master that issues case ids. Test stubs: a scripted callback mode and a fake outside master. Email is the only real channel.
• 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 and 0008. Postfix profile, v0.1.1 errata, v0.2 draft, address composer, and v0.2 conformance cases.
• Open: MAS-WP-0007 (retire the live MX; backlog, unblocked) and MAS-WP-0009 (declare v0.2 final; waits for a second implementation or deployment).
• v0.2 stays a draft (founder, 2026-10-19).
• P2 is decided: !MODE requests a handoff, defined by the mode contract (founder, 2026-10-19). The mode contract and stubs are not started yet; they need a workplan.
• The live mas-mx pod runs an image built before the profile refactor.
• Tests: .venv/bin/pytest runs 199 tests, offline apart from loopback fixtures and the Docker probe.

Getting Oriented

• Start with: INTENT.md, then docs/experiment-review.md
• Agent instructions: AGENTS.md
• Workplans: workplans/