# Specification map

This document maps the normative sources this project implements to the code
that implements them, and notes the deliberate deviations or scope choices.

The project's own process specification is a 58-section document (module name,
layout, line budgets, test counts, verification commands, documentation set,
hard constraints). The sections that govern the artifact are captured here and
in [reproduction.md](reproduction.md); this file focuses on the **protocol**
specifications — RFC 8288, RFC 9264, RFC 8187, RFC 3986 — and the IANA
registry.

## RFC 8288 — HTTP Link Header (Web Linking)

Implemented by the root library; the entry point is `parse_link_header` /
`serialize_link_header` / `canonicalize_link_header`.

| RFC 8288 requirement | Where implemented |
| --- | --- |
| §3 link-value = "<" URI-Reference ">" link-params* | `link_parser.mbt` (URI-Reference via `uri_ref.mbt`) |
| §3 link-param, parameter names are case-insensitive ABNF literals | `token.mbt` ASCII fold; `link_parser.mbt` dispatch |
| §3 anchor, hreflang, media, title, title\*, type parameters | `link_parser.mbt`, `model.mbt` |
| §3 extension link-params | `link_parser.mbt`, `parameter.mbt` |
| §3.1 relation types (case-insensitive tokens) | `relation.mbt`, `link_query.mbt` |
| §3.2 target attributes | `link_parser.mbt` |
| §3.3 anchor attribute | `link_parser.mbt`, `uri_ref.mbt` |
| §3.4 hreflang (RFC 5646 language tags) | `link_parser.mbt` (syntax-level) |
| §3.5 media (RFC 7231 media type) | `link_parser.mbt` |
| §3.6 title (quoted-string) | `quoted_string.mbt` |
| §3.7 title\* (RFC 8187 ext-value) | `rfc8187.mbt` |
| §3.8 type (media type) | `link_parser.mbt` |
| §4 relation types are registered; "registered relation types" | `relation_registry.mbt` + `generated_relations.mbt` |
| §5 serialization rules | `link_serializer.mbt`, `canonicalize.mbt` |
| §5.1 rel precedence; multiple rels | `link_serializer.mbt`, `model.mbt` |
| §5.2 target attributes serialization order | `canonicalize.mbt` |
| §6 security considerations | `docs/security.md`; `limits.mbt` |
| IANA link relations registry (registered relation types) | `generated_relations.mbt` (134-entry offline snapshot) |

## RFC 9264 — Linkset

| RFC 9264 requirement | Where implemented |
| --- | --- |
| §4.1 application/linkset (text) format | `linkset_text.mbt` |
| §4.2 application/linkset+json format | `linkset_json.mbt` |
| §4.2 JSON shape: `{"linkset": [{anchor?, <rel>: [{href, ...}]}]}` | `linkset_json.mbt` |
| member-per-relation structure | `linkset_json.mbt` |
| semantics-preserving conversion between representations (supported scope) | `conversion.mbt` |

## RFC 8187 — Indicating Character Encoding (extended parameter values)

| Requirement | Where implemented |
| --- | --- |
| ext-value = charset "'" [language] "'" value-chars | `rfc8187.mbt` |
| percent-decoding of UTF-8 | `rfc8187.mbt` |
| encoding of `name*` parameters | `rfc8187.mbt` (pure serializer) |
| `title*`, `name*` integration with the parser | `link_parser.mbt`, `model.mbt` |

## RFC 3986 — URI syntax

| Requirement | Where implemented |
| --- | --- |
| URI-reference grammar (used for link targets and anchors) | `uri_ref.mbt` |
| §5.2.2 reference resolution (merge + remove-dot-segments) | `uri_ref.mbt` |
| scheme-based normalization is out of scope | `docs/limitations.md` |

## IANA Link Relation Types registry

- Snapshot source and provenance: `testdata/iana/SOURCE.json`,
  `testdata/iana/link-relations.csv` (134 records, retrieved 2026-08-11,
  sha256 `37109cf6ccf9e4e5e035e8ca1d2fb9f41f5972f7656c033f07e9c58a66769dd4`).
- Generated MoonBit data: `generated_relations.mbt` (regenerated by
  `scripts/import_iana_relations.py`; integrity checked by
  `scripts/verify_iana_snapshot.py`).
- The runtime is fully offline: no code path touches the network.

## Process specification (the 58-section document)

The hard constraints and verification targets are reproduced in
[reproduction.md](reproduction.md); the verification entry point is
[scripts/verify_all.ps1](../scripts/verify_all.ps1) (34 steps) and
[scripts/count_code.py](../scripts/count_code.py) (line budgets and named-test
count).