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:
```text
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:
```text
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:
```text
ticket!callback
```
parses structurally as an interaction-bearing target and records:
```text
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:
```text
anna.mueller@acme.coulomb.social
```
discovery targets:
```text
https://acme.coulomb.social/.well-known/mas
```
It must not walk parent domains implicitly.
Discovery should return either:
```text
ValidatedStatute
```
or a typed failure such as:
```text
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:
```text
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:
```text
.
-
_
```
Therefore:
```text
bernd.worsch@
research-companion@
invoice_ingest@
```
may visually suggest person, actor, and function, but machine classification requires statute or registry metadata.
No statute means:
```text
kind = opaque
```
not:
```text
kind = person-like
```
---
### 5. Resource semantics are the primary proof
The initial implementation should strongly support:
```text
type=id@
```
Resource addresses must remain usable as correlation identifiers while remaining independent of authorization.
Example:
```text
ticket=GS-41872@
```
identifies the ticket communication endpoint.
It does not grant permission to inspect or mutate ticket GS-41872.
