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 and v0.2, and mode contract v0.1; all are final. A second, independent implementation in JavaScript (impl/js/) validates v0.2 and both sides of the mode contract.

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/ (final 2026-10-19: stand-ins, destination transforms, resource_id_case). Spec changes go through docs/spec-change-proposals.md.
• impl/js/. The second implementation: parser, statute-aware rules, signing, outside master. Zero dependencies; tests/test_js_impl.py and the differential test tests/test_differential.py run it when Node is available.
• 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.
• MAS facility. deploy/railiance/: the MX and statute for mas.coulomb.social, with replies through Scaleway TEM capped at 300. power.sh turns the two Deployments on and off. Off keeps the namespace, evidence volume, credentials, DNS, and LoadBalancer. MAS-WP-0007. Ordinary product mail stays in email-connect. A product speaks the mode contract. Gateway events map into that service's evidence ceiling through docs/mas-email-evidence-v0.1.json.

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.
• Further language implementations beyond impl/js/, and impl/js/ as a published package.
• 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 0015. That covers the Postfix profile, the v0.1.1 errata, v0.2 (final), the address composer, the mode contract v0.1 (final) with authentication, one outbound path and bundle-only flows, the second implementation (impl/js/, both specs, both contract sides), and the switchable MAS facility.
• v0.2 is final (founder, 2026-10-19, after MAS-WP-0009). Mode contract v0.1 is final too (founder, 2026-10-19, after MAS-WP-0014: independent JS email side; MCP-1 to MCP-6).
• P2 is decided: !MODE requests a handoff (founder, 2026-10-19; SCP-8, v0.2 §7.1). The mode contract and its reference implementation are done (MAS-WP-0010); mas test runs the contract corpus.
• The MAS facility runs image mas-live:v0.2-480e69a (redeployed 2026-10-19). Founder decision 2026-11-01: keep it and power it on or off (MAS-WP-0007). It was left on. The 300-reply cap, the side-loaded image, and snakeoil SMTP TLS stay until a later decision.
• Tests: .venv/bin/pytest runs 285 tests, offline apart from loopback fixtures, the Docker probe and Node for impl/js/. mas test runs four corpora: parser 64, statute 16, v0.2 statute-aware 33, mode contract 195. cd impl/js && node --test runs 85 more.
• 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/

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard. It does not contact the hub, alter workplan statuses, or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-21

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index keep their existing source and staged-generation contracts.