mail-address-semantics/mas-v0.1-spec/SPECIFICATION.md

# Mail Address Semantics (MAS) v0.1

## 1. Status and normative language

This document defines MAS v0.1.

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**,
**RECOMMENDED**, **MAY**, and **OPTIONAL** are to be interpreted as described
in BCP 14 when, and only when, they appear in uppercase.

MAS is an overlay on ordinary email addressing. It does not replace SMTP,
establish identity, grant authority, define delivery topology, or create
contractual commitments.

## 2. Scope

MAS v0.1 standardizes:

1. non-structural naming hints for people, actors, and functions;
2. structured resource targets using `=`;
3. facets using `+`;
4. an optional interaction profile using `!`;
5. exact-host statute discovery;
6. conservative equivalence behavior;
7. parser and generator conformance.

`$` and `^` are reserved. They have no MAS v0.1 meaning.

## 3. Profiles

### 3.1 Profile P1 — Naming + Resource

P1 is the base v0.1 profile.

- `.` MAY be used as a person-style naming separator.
- `-` MAY be used as an actor-style naming separator.
- `_` MAY be used as a function-style naming separator.
- `=` structurally binds a resource type to a resource identifier.
- `+` structurally adds one facet.

`.`, `-`, and `_` never classify an address by themselves.

### 3.2 Profile P2 — Interaction

P2 extends P1 with `!`.

`TARGET!MODE` requests that the addressed endpoint continue the interaction
using `MODE` as the preferred interaction mode.

The address does not state which party initiates a non-email leg and does not
constitute acceptance. Acceptance is external to the address.

### 3.3 Profile P3 — Economic

P3 is not defined in v0.1.

`$` and `^` are reserved so that later profiles may define consideration and
conditions without creating v0.1 parsing ambiguity.

## 4. Canonical ASCII local-part

The normative v0.1 machine grammar is the ABNF in
`grammar/mas-v0.1.abnf`.

Canonical MAS v0.1 local-parts are unquoted ASCII dot-atom-like strings.
Quoted local-parts and SMTPUTF8 local-parts are outside the canonical v0.1
machine grammar.

A MAS-aware implementation MAY transport such non-canonical email addresses
as ordinary email, but MUST NOT claim that they are canonical MAS v0.1
addresses.

### 4.1 Target

A target is non-empty.

A target without `=` is opaque. Its semantic kind MUST NOT be inferred from
`.`, `-`, or `_`.

If a target contains `=`, the target is a resource target:

- text before the first `=` is `resource-type`;
- text after the first `=` is `resource-id`;
- neither may be empty;
- subsequent `=` characters are resource-id data.

Examples:

    ticket=PR42
    invoice=RE=2026-4711

The second example has resource type `invoice` and resource id
`RE=2026-4711`.

### 4.2 Facet

A facet is introduced by `+`.

`+` MAY occur at most once and its value MUST be non-empty.

    ticket=PR42+comments

The base target remains meaningful if a mail system strips the facet. MAS
therefore treats facet loss as graceful degradation:

    ticket=PR42+comments  ->  ticket=PR42

This is a semantic design property, not a preservation guarantee.

### 4.3 Interaction

An interaction preference is introduced by `!`.

`!` MAY occur at most once and its value MUST be non-empty.

P2 examples:

    ticket!callback
    ticket=PR42!web

Canonical operator order is:

    TARGET [+FACET] [!INTERACTION]

Non-canonical order is invalid MAS syntax. A conforming parser MUST reject it
and MUST NOT silently reorder it.

### 4.4 Composition rule

A parser implementing P2 MUST be able to parse the canonical combined form:

    TARGET+FACET!INTERACTION

A v0.1 generator MUST NOT emit both `+` and `!` in the same generated
local-part. Implementations requiring both semantics SHOULD move one of them
to external metadata.

This deliberately makes receivers slightly more tolerant than generators
while retaining one canonical parse.

### 4.5 Reserved characters

Within canonical MAS v0.1 structured values:

    + ! $ ^

are reserved.

MAS v0.1 defines no escaping mechanism.

A percent-looking sequence such as `%2B` is ordinary data in v0.1 and MUST NOT
be percent-decoded by the MAS parser.

## 5. Naming semantics

The following are style conventions only:

    bernd.worsch@example.org       person-like
    research-companion@example.org actor-like
    invoice_ingest@example.org     function-like

They are not classifier rules.

Examples such as these remain opaque without statute metadata:

    anne-marie.schmidt@example.org
    support@example.org
    happy-helper.v2@example.org

A domain registry or statute metadata determines semantic kind.

## 6. Resource semantics

A resource address identifies a communication endpoint associated with a
resource.

    ticket=PR42@example.org

It does not grant access to, mutation of, or knowledge about the resource.

Resource addressability and resource mutability are independent.

A closed resource MAY remain addressable. A receiver MAY archive the mail,
reject mutation, return lifecycle information, or create a linked follow-up
resource.

### 6.1 Resource types

A statute SHOULD enumerate resource types it recognizes.

Unknown resource types MUST NOT acquire application semantics solely because
they use `=` syntax.

### 6.2 Resource identifiers

Resource identifiers are correlation identifiers, not credentials.

Predictable identifiers are enumerable. Deployments SHOULD prefer
non-guessable external identifiers when addresses are widely forwarded or
exposed and enumeration is undesirable.

High entropy does not transform an identifier into an authorization token.

## 7. Interaction semantics

The recommended P2 initiation pattern is:

    ticket!callback@great-service.example

followed by creation or disclosure of a resource:

    ticket=GS-41872@great-service.example

The first address expresses interaction intent. The second names the resource
created or selected by the service.

`!callback` is a preference/request, not a command, guarantee, SLA, or proof
of acceptance.

## 8. Address equivalence

MAS does not impose case folding, dot folding, alias folding, or Unicode
normalization in the absence of a successfully discovered statute.

If no statute is available, comparison is exact over the presented canonical
ASCII local-part.

A statute MAY declare:

- `exact` local-part comparison;
- `ascii-insensitive` local-part comparison;
- dot folding for explicitly named address kinds or registry entries.

Dot folding MUST NOT be assumed by default.

A-label/U-label domain processing follows the underlying IDNA-aware HTTPS and
DNS stack; MAS does not invent a second IDN mapping algorithm.

## 9. Unicode

SMTPUTF8 allows non-ASCII local-parts, but MAS v0.1 does not define a
canonical Unicode local-part grammar.

A statute may declare `unicode_local_part: true` for experimental/private
extensions. Such addresses MUST NOT be advertised as canonical MAS v0.1
machine syntax.

A future MAS version may define NFC normalization and Unicode comparison
rules. v0.1 deliberately avoids doing so.

## 10. Statute discovery

The intended discovery URI is:

    https://HOST/.well-known/mas

where `HOST` is the exact domain appearing after `@`.

For:

    anna.mueller@acme.coulomb.social

the lookup host is:

    acme.coulomb.social

A client MUST NOT walk to parent domains implicitly.

### 10.1 Registration caveat

RFC 8615 requires applications minting a new well-known URI suffix to
register it for general Internet use.

Therefore `/.well-known/mas` is a candidate MAS discovery location in this
draft. General public deployment SHOULD wait for the required registration.
Controlled deployments MAY use it by agreement.

### 10.2 Retrieval

A statute-aware client:

1. constructs the HTTPS URI for the exact host;
2. performs an HTTPS GET;
3. requires a successful 2xx response;
4. requires a document conforming to the v0.1 statute schema;
5. verifies that `namespace` equals the queried host after normal domain-name
   canonicalization;
6. otherwise treats discovery as failed.

Discovery failure does not make the email address invalid. It means MAS
semantics are unconfirmed.

### 10.3 Redirects

Clients SHOULD NOT follow cross-origin redirects for statute discovery.

Same-origin redirects MAY be followed.

A cross-origin policy transfer requires an explicit future delegation
mechanism and is not defined in v0.1.

### 10.4 Inheritance

No parent-domain inheritance is implicit.

A child statute MAY contain an `inherits` URI. v0.1 inheritance is
**defaults-only**:

- the parent document is fetched and validated independently;
- the child remains authoritative for its exact namespace;
- child values override inherited defaults;
- address registry entries are never inherited;
- resource types and interaction modes MAY be inherited;
- an inheritance cycle is invalid.

Implementations MAY choose not to implement inheritance. If they do not,
they MUST ignore `inherits` rather than walking DNS parents.

## 11. Statute document

The normative schema is:

    schema/mas-statute-v0.1.schema.json

The document describes:

- namespace and version;
- enabled profiles;
- accepted resource types;
- accepted interaction modes;
- equivalence policy;
- optional explicit address classification;
- optional inheritance.

The statute is metadata, not an authorization database.

## 12. Deliverability and rewriting

RFC-validity is weaker than ecosystem compatibility.

Mailing lists, SRS, VERP, gateways, web forms, validators, and security
products may reject or rewrite otherwise legal local-parts.

Deployments MUST NOT assume preservation of MAS syntax through arbitrary
rewriting.

`+` is intentionally degradation-friendly: loss of a facet leaves the base
target.

`!` is intended primarily for cooperating environments where all relevant
systems are known to preserve it.

## 13. Length

An SMTP local-part is limited to 64 octets.

Generators MUST enforce the underlying transport limit after encoding.

Because the budget is small, v0.1 permits at most one facet and one
interaction, and generators MUST NOT emit both simultaneously.

## 14. Security

1. MAS identifiers are not credentials.
2. Resource knowledge grants no authority.
3. Interaction selectors are not commands.
4. Dynamic addresses MUST define handling for bounces, unknown resources,
   expired resources, verification traffic, and abuse.
5. Receivers MUST avoid backscatter behavior.
6. Syntax-derived classifications MUST NOT substitute for statute metadata.
7. `$` and `^` MUST NOT be rendered as payment/contract semantics in v0.1.
8. Authentication remains external to MAS.
9. A statute endpoint is security-relevant configuration and SHOULD be
   protected with the same care as other origin-wide metadata.

## 15. Conformance classes

### 15.1 P1 parser

A P1 parser:

- validates canonical ASCII syntax;
- parses resource binding and facet;
- rejects `!`, `$`, and `^` as MAS operators;
- does not classify opaque target kind by punctuation.

### 15.2 P2 parser

A P2 parser additionally parses `!`.

### 15.3 Generator

A generator:

- emits only canonical operator order;
- emits no empty component;
- emits no reserved operator within a value;
- emits at most one `+`;
- emits at most one `!`;
- MUST NOT emit both `+` and `!` in v0.1;
- enforces the SMTP local-part octet limit.

### 15.4 Statute-aware implementation

A statute-aware implementation additionally validates the discovery document
against the normative schema and applies only explicitly declared equivalence
and classification rules.

## 16. Reserved future work

Future specifications may define:

- Unicode canonical grammar;
- escaping;
- signed statutes and signed semantic assertions;
- interaction negotiation;
- service discovery;
- economic request/offer/acceptance/settlement;
- condition tokens;
- IANA registrations.

## 17. One-sentence definition

**Mail Address Semantics is a voluntary convention for naming people, actors
and functions, and for addressing resources, facets, and optional interaction
preferences through ordinary email addresses while keeping classification,
authority, authentication, equivalence, and delivery implementation explicit
and external to the address syntax.**