mail-address-semantics/INTENT.md

MAS — Mail Address Semantics

Status

Phase 1 (reference experiment) passed its decision gate on 2026-10-18 (MAS-WP-0002, docs/experiment-review.md). All ten success criteria were met, including the live run through Gmail, Microsoft 365 and Postfix. Phase 2 is described in Phase 2 intent below. The phase-1 sections are kept as the record of what was tested; where phase 2 changes them, it says so.

Intent (phase 1)

Build the smallest practical implementation of Mail Address Semantics (MAS) v0.1 that can prove whether the specification is useful in real email workflows.

The project should demonstrate that ordinary email addresses can carry limited, human-readable and machine-parseable semantics for:

• opaque organizational targets,
• resource addressing,
• facets,
• optional interaction preferences,

without modifying SMTP and without turning addresses into credentials, commands, contracts, or payment instructions.

The implementation must preserve the core architectural boundary of MAS:

Parsing is local and deterministic. Discovery is networked. Policy is pure. Delivery remains external.

The first implementation should be deliberately narrow. Its purpose is not to build a full MAS ecosystem, but to test the convention against real messages, real routing, resource lifecycle, malformed input, and namespace metadata.

---

Core hypothesis

MAS is valuable if the following can be made both simple and reliable:

ticket!callback@great-service.example

can express:

initiate a ticket interaction with callback as the preferred continuation mode

and result in a stable resource address:

ticket=GS-41872@great-service.example

that can subsequently be used to correlate email with that ticket without embedding application identifiers in subject lines.

If this lifecycle works cleanly through ordinary email infrastructure, MAS has demonstrated its core value.

---

Design principles

1. The parser does not use the network

Parsing operates only on the address syntax.

It must:

• validate canonical MAS syntax,
• produce an explicit parse tree,
• identify which MAS profile the syntax requires,
• never perform statute discovery,
• never infer person, actor, or function kind from ., -, or _.

Example:

ticket!callback

parses structurally as an interaction-bearing target and records:

required_profile = P2

Whether the addressed namespace supports P2 is decided later.

---

2. Discovery returns facts or typed failure

MAS discovery is responsible only for retrieving and validating the exact-host statute.

Given:

anna.mueller@acme.coulomb.social

discovery targets:

https://acme.coulomb.social/.well-known/mas

It must not walk parent domains implicitly.

Discovery should return either:

ValidatedStatute

or a typed failure such as:

NotFound
HttpFailure
CrossHostRedirect
SchemaInvalid
NamespaceMismatch
InheritanceCycle
UnsupportedVersion

Failure to discover MAS metadata does not invalidate the email address.

---

3. Policy is pure

Policy evaluation takes:

parse tree
+
validated statute
+
optional local registry

and produces semantic interpretation.

Policy performs no network access.

This allows the same policy implementation to be exercised entirely through the conformance corpus.

---

4. No semantic inference from naming punctuation

The following remain naming hints only:

.
-
_

Therefore:

bernd.worsch@
research-companion@
invoice_ingest@

may visually suggest person, actor, and function, but machine classification requires statute or registry metadata.

No statute means:

kind = opaque

not:

kind = person-like

---

5. Resource semantics are the primary proof

The initial implementation should strongly support:

type=id@

Resource addresses must remain usable as correlation identifiers while remaining independent of authorization.

Example:

ticket=GS-41872@

identifies the ticket communication endpoint.

It does not grant permission to inspect or mutate ticket GS-41872.

---

6. Resource addressability outlives mutability

Closed resources remain addressable.

A closed ticket may:

• archive later email,
• reject mutation,
• return lifecycle information,
• create a linked follow-up ticket.

It must not become mutable merely because mail can still reach its address.

---

7. Facets degrade safely

A facet:

ticket=GS-41872+comments@

may be stripped by existing email infrastructure.

If so, the remaining address:

ticket=GS-41872@

still identifies the base resource.

Facet preservation is desirable but never assumed.

---

8. Interaction remains a preference

The P2 syntax:

ticket!callback@

requests that the addressed endpoint continue through callback.

It does not imply:

• who initiates the callback,
• that callback is available,
• that callback has been accepted,
• an SLA,
• a command.

The application decides whether and how to satisfy the request.

---

9. Economic syntax remains closed

The characters:

$
^

remain reserved only.

No implementation work on price, reward, conditions, offers, contracts, or settlement belongs in this phase.

---

10. Auto-reply endpoints are gated and capped

(Added in phase 2, from the live run.)

An address that answers automatically, such as ticket!callback@, turns any forged From: into outbound mail to a third party. Any endpoint that replies automatically therefore:

• replies only when the sender is authenticated (DMARC pass, read from trusted Authentication-Results);
• never replies to automated mail or to the null sender;
• caps how much it can send in total.

This is application policy, not MAS syntax. But a MAS deployment that leaves it out reflects mail at third parties, and the reference implementation must show how to avoid that.

---

Initial architecture

The first repository should contain only the pieces needed for the experiment.

mas/
├── mas_core/
│   ├── parser
│   ├── model
│   ├── discovery
│   ├── policy
│   └── lint
├── cli/
│   └── mas
├── conformance/
│   ├── addresses
│   ├── statutes
│   └── properties
├── examples/
│   ├── statute/
│   └── ticket_service/
├── gateway/
│   └── smtp_or_webhook_to_http/
└── docs/

The existing MAS v0.1 specification bundle is the normative basis.

---

Initial components

mas-core

Python reference implementation.

Responsibilities:

• parse canonical MAS syntax,
• expose structured parse objects,
• identify required profile,
• validate statutes,
• discover exact-host statutes,
• apply equivalence rules,
• evaluate semantics from parse tree plus statute,
• lint statutes.

The first implementation should be clear and auditable rather than clever.

---

mas-cli

Primary human interface.

Initial commands:

mas parse ADDRESS
mas explain ADDRESS
mas discover HOST
mas lint-statute FILE
mas test

mas explain should clearly distinguish:

syntactic facts
discovered namespace facts
policy-derived semantics
unknowns

A discovery failure must remain visible.

---

mas-conformance

The conformance corpus should become a first-class package rather than an incidental test directory.

It should contain:

• positive syntax cases,
• negative syntax cases,
• parser expectations,
• generator expectations,
• statute validation cases,
• discovery policy cases,
• property and boundary cases.

Every future language implementation should consume this corpus unchanged.

---

Static statute

The first service does not need a statute server framework.

A static file served at:

/.well-known/mas

is sufficient.

The point is to test discovery semantics, not middleware.

---

Generic mail gateway

The first mail integration should translate inbound mail into a simple HTTP request.

It may receive mail via:

• a local SMTP listener, or
• a provider-style inbound webhook.

Its responsibility should be minimal:

email recipient
→ MAS parse
→ statute/policy resolution
→ normalized HTTP event

It should not contain ticket-specific business logic.

---

Reference ticket service

A deliberately small example application proving the canonical lifecycle.

Required behavior:

Initial interaction

Mail to:

ticket!callback@great-service.example

creates a ticket.

The service generates:

ticket=GS-41872@great-service.example

Subsequent correlation

Mail sent to:

ticket=GS-41872@great-service.example

is associated with that ticket without depending on the subject line.

Closed lifecycle

After the ticket is closed, its address remains routable.

Later mail must not silently reopen or mutate the resource unless application policy explicitly allows it.

---

Explicit non-goals (phase 1)

Phase 2 removes the address composer and the MTA integration profile from this list (see Phase 2 intent). The rest still applies.

The initial implementation does not include:

• TypeScript reference library,
• Go implementation,
• Postfix policy daemon,
• central MAS registry,
• mail client plugin,
• browser extension,
• address composer,
• payment semantics,
• electronic signatures,
• generalized service marketplace,
• production identity federation,
• automatic DNS-parent inheritance.

These should be considered only after the reference experiment succeeds.

---

Success criteria

The first experiment succeeds if:

1. the parser conforms to the shared fixture corpus;
2. parser behavior requires no network access;
3. discovery produces validated statute or typed failure;
4. policy evaluation is deterministic and offline;
5. mas explain never invents semantics on discovery failure;
6. the ticket lifecycle works end to end;
7. ticket identifiers no longer need to be encoded in subject lines;
8. closed resources remain addressable without becoming mutable;
9. facet loss degrades safely;
10. the experiment exposes no need to change SMTP itself.

---

Phase 2 intent

Phase 1 showed that the convention works through ordinary infrastructure once the MTA is configured correctly, and that resource addressing is the strongest part of MAS. Phase 2 turns the experiment into a usable reference. It still stays narrow.

Role of this repository

This repository is the spec workbench as well as the reference implementation. It maintains the normative bundles (mas-v0.1-spec/ as v0.1.1 errata, and the mas-v0.2-spec/ draft) and records every change as a proposal in docs/spec-change-proposals.md. Every spec change needs:

• evidence from a test or a live run;
• conformance fixtures in the bundle;
• an implementation in mas_core.

Implementation and spec move together. A version is declared final only after a second implementation or deployment has passed its corpus unchanged.

Goals

1. Adoptable integration. A documented, tested MTA profile, so that P2 addresses survive. Default Postfix drops them. Postfix is done; Exim only on demand.
2. Forwarder-safe generation. Provider forms refuse = and fold case. The generator and mas compose emit the canonical form and, where the statute allows it, a forwarder-safe form. When that form would be misread, they refuse to emit it.
3. v0.2 to final. Settle stand-ins, destination transforms and resource_id_case. Finalize once an independent implementation validates the corpus.
4. Safe reference behavior. The reference service demonstrates principle 10.

Open question: the value of interaction (P2)

Phase 1 proved resource addressing strongly, and interaction only partly. !callback states the intent, but the service still has to ask for a number and a time. The link from the opaque intake target ticket to the resource type ticket exists only through a statute registry entry. Phase 2 must decide one of two things:

• define "type intake" semantics, so that an opaque target naming a declared resource type has a specified meaning; or
• narrow P2 to a pure preference hint, and stop adding mechanism for it (such as the --- stand-in) until a use case needs it.

Still not in phase 2

Other language implementations (except one used to validate v0.2), a policy daemon, a central registry, mail-client plugins, signed statutes, implicit parent inheritance, and economic semantics. A web composer is out until something asks for one.

Phase 2 is done when

1. a fresh Postfix install, using only integrations/postfix/, delivers the full corpus unchanged and refuses relaying;
2. mas compose produces correct forms for every destination observed so far, and refuses the rest;
3. v0.2 is declared final, or is withdrawn with recorded reasons;
4. the P2 question above is decided and recorded in the spec;
5. the live test environment is retired, with its evidence archived.

---

Longer-term direction

If the experiment validates the concept, MAS may later grow into:

• additional language libraries,
• infrastructure gateways,
• mail client affordances,
• signed semantic metadata,
• richer interaction discovery,
• economic profiles,
• service-market coordination.

Those extensions should remain subordinate to the core principle:

MAS should add useful semantics to email without making ordinary email depend on MAS.