# 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. ## 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 280 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.