mail-address-semantics/impl/js/README.md

# mas-js: second, independent MAS implementation

Written from the specification texts and fixtures only, not ported from
`mas_core` (MAS-WP-0009). It uses Node 20+ and has zero dependencies.

| Module | Covers | Checked by |
|---|---|---|
| `src/parser.mjs` | canonical grammar, P1/P2 (address spec §4) | `mas-v0.2-spec/conformance/addresses.json` |
| `src/statute.mjs` | stand-ins (§6.3), equivalence (§8), destination transforms (§12.1), length (§13) | `mas-v0.2-spec/conformance/statute-aware.json` |
| `src/signing.mjs` | peer authentication (mode contract §7) | `mas-modes-v0.1-spec/conformance/auth.json` |
| `src/master.mjs` | outside master for email's slave role (mode contract §3.2) | `mas-modes-v0.1-spec/conformance/flows.json`, slave setups, run against the Python email side |
| `src/email.mjs` | email side in both roles: case store, handoffs, timeouts, the outbox with one cap and holding, authorization (mode contract §3 to §7) | every flow in `flows.json`, with the Python gateway and callback stub as peers, alone or with `master.mjs` (MAS-WP-0014) |

```bash
cd impl/js && node --test                       # the three bundles, read in place
cd ../.. && .venv/bin/pytest tests/test_js_impl.py tests/test_differential.py
```

`src/batch.mjs` evaluates parse, interpret and destination cases in bulk.
`tests/test_differential.py` compares it with `mas_core` over 1500
generated local-parts per operation. Its first run found two gaps in the
spec text (SCP-9).

Nothing in Python imports this code. The flow runner starts `master.mjs`
and `email.mjs` as separate processes and drives them only through their
loopback control APIs (`mas_modes/external.py`). Writing `email.mjs` from
the contract text found six gaps (MCP-1 to MCP-6,
`docs/mode-contract-proposals.md`). Its mutation check found a missing
flow (a-008).