polytypo 1.6.3 → 1.8.0

data/lib/polytypo/data/rules/modes.md

@@ -7,10 +7,13 @@ for all five runtimes and is parser-agnostic by construction: `parse5`, `nokogir
 `golang.org/x/net/html` and PHP's DOM disagree about almost everything this document does not
 forbid them from doing. `yaml` mode is parser-**free** rather than parser-agnostic, for the
 reason §3.8.1 measures.
-**Spec version:** 1.5.0 (0.1.0 for everything except §3.3's class-membership table rows for
+**Spec version:** 1.8.0 (0.1.0 for everything except §3.3's class-membership table rows for
 `nbsp` and `apostrophe`, split in 1.2.0, §3.8, added in 1.3.0, §3.3's note on `quotes`'
 span-boundary elision veto reading the marker as a trigger, added in 1.4.0 — which changes no
-row of the table it follows — and §3.3's `CLOSEDELIM` entry, added in 1.5.0).
+row of the table it follows — §3.3's `CLOSEDELIM` entry, added in 1.5.0, and §3.7.4 with the
+amendments it carries to §3.1's definitions, §3.2's Model C, §3.5 step 3, §3.7.3's frontmatter
+bullet, §3.8.6's accepted-cost paragraph, §5, §6 and §7, added in 1.7.0, and §3.7.3a, added in
+1.8.0).
 
 ---
 
@@ -49,6 +52,10 @@ sees; the pipeline decides what to do with them.
   identified by its offsets in the **original source**, and those offsets are the only handle
   the mode layer keeps.
 - The **span sequence** `S₁ … Sₘ` is the processable spans in document order.
+- A **text unit** is one span sequence and the array built from it (§3.5 step 2). A document has
+  exactly one, **except** in `markdown` with `frontmatterKeys` (§3.7.4, spec 1.7.0), where the
+  frontmatter block's spans form a second unit and the pipeline runs once per unit. The term is
+  defined here because §4 and §6 already used it informally for "the concatenation".
 - `text` mode is the degenerate case: one span covering the whole input, no skipped regions.
   Every statement below holds for it trivially.
 
@@ -88,7 +95,9 @@ each rule is behaving exactly as specified on the input it was given.
 
 **Model C — concatenation with an explicit boundary marker. Adopted.** The spans are
 concatenated with a **boundary marker** between each adjacent pair. The pipeline runs once, over
-the whole marker-separated array. Edits are then redistributed to spans by offset.
+the whole marker-separated array — once per **text unit** (§3.1), which for every mode but
+`markdown` with `frontmatterKeys` (§3.7.4) means once per document. Edits are then
+redistributed to spans by offset.
 
 The marker gives the rules what Model A denies them — the knowledge that `'hi'` sits inside a
 larger quotation — while denying them what Model B wrongly grants: the belief that the last
@@ -365,7 +374,9 @@ reaches the edge-growth rule. `--` is the live carrier.)
    gives flow collections no spans — see `quotes.md` §3.2, which depends on the answer for
    nothing but states the obligation it creates: a rule must key off the marker, never off the
    mode.
-3. Run the pipeline **once**, in `order.json` order, over that array.
+3. Run the pipeline **once**, in `order.json` order, over that array. A document with a second
+   text unit — `markdown` with `frontmatterKeys`, and only that (§3.1, §3.7.4) — repeats steps 1
+   to 4 for it. The two edit sets are disjoint, because no span of one unit lies inside the other.
 4. Each edit lies wholly within one span (§3.4). Map it back to source offsets.
 5. Emit the **original source bytes**, with those replacements applied and nothing else changed.
 
@@ -477,7 +488,9 @@ Two constraints on the throw:
 Skipped, exhaustively:
 
 - **frontmatter** — a metadata block at the very start of the document, delimited by `---`
-  (YAML) or `+++` (TOML), skipped whole including its delimiters. Without it the closing `---`
+  (YAML) or `+++` (TOML), skipped whole including its delimiters. **Since 1.7.0 a caller may
+  name keys inside a YAML block to process — §3.7.4 — and the skip stands unchanged when they
+  do not.** Without it the closing `---`
   reads as a setext underline, `title: Une note` becomes a paragraph, and `fr` inserts a narrow
   no-break space before the colon of a machine-read field. That is a guaranteed false positive
   on the M4 corpus (PLAN.md §8), where every file opens with frontmatter;
@@ -512,6 +525,349 @@ lower-cases JSX names before matching will skip a component's children.
 Nesting follows the same rule as `html`: a skipped construct is skipped whole, including
 anything that looks processable inside it.
 
+#### 3.7.3a Where the frontmatter block begins and ends
+
+**Spec 1.8.0.** §3.7.3 skips "a metadata block at the very start of the document, delimited by
+`---` (YAML) or `+++` (TOML)". That is prose, and frontmatter is in neither CommonMark nor GFM,
+so until now each runtime reached the construct through its own parser's frontmatter support —
+four extensions, four answers. Measured on the published 1.7.0 line, `en-US`, `commonmark`,
+asking only whether the block is skipped or typeset as prose:
+
+| document                                    | JS      | Python  | Go          | Ruby        |
+| ------------------------------------------- | ------- | ------- | ----------- | ----------- |
+| `---` / `title: "x - y"` / `---`            | skipped | skipped | skipped     | skipped     |
+| trailing space on the **opening** delimiter | skipped | skipped | **typeset** | **typeset** |
+| trailing space on the **closing** delimiter | skipped | skipped | **typeset** | **typeset** |
+| `...` as the closer                         | typeset | typeset | typeset     | typeset     |
+| `---` after a leading blank line            | typeset | typeset | typeset     | typeset     |
+
+Two of four turn `date: "2026-09-26"` into a quoted-and-curled string over one trailing space
+that no author typed on purpose, and both were conformant, because no fixture pinned the edge.
+
+> **The block's extent is decided by the scan below, not by a parser's frontmatter support.** A
+> runtime whose parser also recognises the construct must produce the same extent as this scan; the
+> scan is what a fixture pins and what a disagreement is measured against.
+>
+> **And the parser is handed the block masked out.** The source given to the Markdown parser is the
+> document with the located block — both delimiter lines included, **and the leading U+FEFF of step
+> 1 if there is one** — replaced by U+0020, line terminators kept as they are, so that nothing
+> inside the block can form or close a construct in the body.
+>
+> **The masked source must be positionally aligned with the original in the unit the runtime maps
+> parser offsets back through.** That is the invariant, and it is not the same as "one U+0020 per
+> code point": a runtime that hands its parser's byte offsets straight through owes byte-length
+> preservation, and masking `😀` to a single space shortens its source by three and shifts every
+> body offset after it. A runtime that converts offsets against the **masked** source before
+> reading them against the original owes code-point alignment only, which one U+0020 per code point
+> gives it — and in a language whose strings are sequences of code points, byte-length preservation
+> cannot even be expressed. Both are conformant; stating it as an index-unit count was not, and the
+> port that indexes code points while its parser counts bytes is what showed it.
+>
+> **And no span may lie inside the block, whatever the parser did with the masked text.** Masking
+> is what makes that true for most parsers and it is not sufficient for all of them: measured,
+> tree-sitter-markdown reads a final all-space line with no terminator as a paragraph, so a
+> document whose closing `---` ends the file comes back with a span over the delimiter itself —
+> the parser did not see the block at all, and step 5's "end of input ends a line" is the clause it
+> does not implement. A runtime whose parser emits such a span **clips it to the part outside the
+> block, and drops it when nothing is left**: the block's own characters must not reach the rules,
+> and body prose past the block must not be lost to a parser's mistake about where the block ended.
+> The mask is there so the parse is not deformed; this rule is there so the spans cannot be wrong
+> even when it is.
+>
+> The mark is masked with the block because leaving it out breaks both: a first line of U+FEFF
+> followed by spaces is not blank, no parser is required to strip the mark, and goldmark does not.
+
+Masking is not an implementation note, and the runtime that skipped it is measured. Suppressing a
+span inside the block's range is not enough, because the parser has already read the block's
+characters by then: a fenced-code line inside a metadata value pairs with the body's own fence, and
+the body's code block and its prose swap places. One document, the same call in four runtimes, on
+published 1.7.0:
+
+````
+--- 
+x: |
+  ```
+---
+
+```
+code "q"
+```
+
+Body "q".
+````
+
+| runtime    | result                                                                      |
+| ---------- | --------------------------------------------------------------------------- |
+| JS, Python | `code "q"` stays straight, `Body “q”` converts — correct                    |
+| Go         | **`code “q”` is typeset inside the code block**, and `Body "q"` is missed    |
+| Ruby       | correct with this bare-looking fence, wrong the moment the fence has a space |
+
+Go reaches that by parsing the whole source and suppressing spans in the block's range, which is
+the obvious way to do it without a frontmatter-aware parser and is wrong for a reason no span-level
+rule can see: the damage is in what the parser concluded, not in which spans were emitted. Masking
+costs one pass over a known range and removes the class.
+
+**The scan**, over the source's code-point array, in §3.8.4's terms:
+
+1. the document must **begin** with the delimiter — `---` or `+++` at offset 0, no leading blank
+   line and no indentation. **A single leading U+FEFF is stepped over first** and is not part of
+   the document for this scan. It is a byte-order mark, not content: every editor that writes one
+   writes it before the fence, and reading it as content would deny the block to every file some
+   Windows editors produce. Measured on 1.7.0, JS and Python already step over it and Go and Ruby
+   do not — the same two-against-two split, on the same damaging side, as the trailing space;
+2. the rest of that line must be only U+0020 and U+0009. Anything else and there is no block, and
+   what the line then is belongs to the dialect rather than to this scan: `--- yaml` is not a
+   thematic break, since a break admits only spaces and tabs after its run;
+3. the **closing line** is the first later line whose first code point begins the same delimiter,
+   followed by only U+0020 and U+0009. Indentation disqualifies it exactly as it disqualifies the
+   opening line — a closer is not searched for inside a line, it is a line. `...` is not a closer
+   in either matter, a delimiter of the other kind is not one either, and a fourth delimiter
+   character is not whitespace, so `----` closes nothing;
+4. with no such line there is **no block**, and the opening delimiter is whatever the dialect makes
+   of it — a thematic break for `---`, ordinary paragraph text for `+++` — with everything after it
+   prose, which is what `en-us-markdown-commonmark-frontmatter-unterminated` already pins;
+5. a **line ends as CommonMark ends one** — at U+000A, at a U+000D that is not followed by
+   U+000A, or at the end of input — and the terminator is never part of the line. So a CRLF
+   document gives the same block as the same bytes with LF, a file whose last line is `---\r`
+   with no final U+000A still closes its block, and a document written with lone U+000D line
+   endings has one at all.
+
+   **This is the Markdown document's line model, and it is deliberately not §3.8.4's.** The block
+   is a Markdown construct, so it ends its lines the way the language around it does. The content
+   inside it keeps §3.8.4's LF-only model — and the reason is not that YAML agrees, because it
+   does not: YAML 1.2.2 §5.4 admits a lone U+000D as a line break too. §3.8.4 is a deliberate
+   simplification, taken and measured in 1.3.0, and this section does not widen it, because
+   widening the content scan's line model is a change to `yaml` mode for every caller and wants
+   its own measurement. A port that harmonises the two has silently made that change. What it
+   costs here is recorded in §7.13.
+
+   All three shapes above are documents whose metadata a stricter reading hands to the rules, and
+   the reference runtime already treats all three as blocks — measured on 1.7.0.
+
+**Which way to be wrong, and why this way.** A locator errs in one of two directions and they are
+not the same size. Recognising a block that is not one skips text that was prose: a miss, and
+§3.8.3 already accepts misses by the dozen. Failing to recognise a block that is one hands the
+metadata to the rules as prose: `title: Q3 review: what changed` takes a no-break space before
+its colon in `fr` — U+00A0, since `fr` puts `:` in `beforePunctuation` and only `;`, `!` and `?`
+in the narrow list — and a date grows quotation marks. The first is invisible and harmless;
+the second is the damage §3.7.3 exists to prevent. **So the wider reading wins every edge where
+the runtimes disagree**, and the trailing-space clause of steps 2 and 3 is that reading written
+down.
+
+The accepted cost is stated rather than hidden: a document whose very first line is a thematic
+break written as `--- `, followed by prose and another `---` line, has **everything up to that
+line** skipped — not one paragraph but the whole first section, heading included, since the scan
+takes the first later delimiter line whatever lies between. It is skipped by JS and Python today,
+has been for every release, and nobody has reported it — while a frontmatter block carrying
+trailing whitespace on its fence is what any editor that trims nothing produces.
+
+**What this costs each runtime.** JS and Python already behave this way, so the change there is
+that the extent stops being their parser's opinion and becomes this scan's — which also removes
+the second parse `frontmatterKeys` cost them (polytypo/polytypo#59), since locating the block no
+longer needs one. Go and Ruby change behaviour: both must widen their locator to admit trailing
+U+0020 and U+0009 on either delimiter. Go already owns a hand-written locator for exactly this
+reason and `detectFrontmatter` is where it lives.
+
+#### 3.7.4 Frontmatter by named keys — the one opt-out from §3.7.3
+
+**Spec 1.7.0.** §3.7.3 skips the frontmatter block whole and its reason for doing so still holds.
+It is also the one place where the default hides the sentence most readers of the page will see:
+where frontmatter carries `title`, `description` and `summary`, those strings are the heading,
+the `<title>`, the meta description and the card text, so the single most visible string on the
+page is the one polytypo will not touch. Both reports that asked for this — polytypo/polytypo#13,
+and the production integration in #26 over 196 MDX posts, independently — hand-rolled it instead,
+and the first of them corrupted its own content doing so: its extractor knew double-quoted YAML
+scalars and silently skipped every single-quoted one.
+
+> **`markdown` mode takes an optional `frontmatterKeys` option: the mapping keys in the
+> document's YAML frontmatter block whose scalar values are processable.** Absent means
+> §3.7.3 unchanged — the block is skipped whole, delimiters included. An **empty list is
+> legal** and yields no spans, as it does for `keys` (§3.8.2). A value that is not a list of
+> strings throws `POLYTYPO_INVALID_OPTION`.
+
+**Ratified by the operator as public contract, 2026-09-25**, under this name rather than by
+widening `keys`. Three reasons, in the order that decided it: `keys` is **required** in `yaml`
+mode and optional here, so one name would carry two requiredness contracts; `polytypo` 1.6.3
+**accepts a `keys` it ignores** in `markdown` mode — measured, not assumed — so reusing the name
+would silently begin typesetting frontmatter for any caller who passes one options object to both
+modes; and the name says which block it governs, which a bare `keys` on a mode whose body is also
+full of keys does not.
+
+**What the option governs, in source offsets.** The block is the frontmatter construct §3.7.3
+already recognises, and the option only changes what happens inside it:
+
+- the **content** is the source from the code point after the opening delimiter line's
+  terminator to the code point that begins the closing delimiter line. A U+000D before that
+  terminator belongs to the terminator, exactly as in §3.8.4, so a CRLF document and the same
+  bytes with LF give the same content;
+- **a line of that content containing a U+000D not followed by U+000A yields no spans**, exactly
+  as §3.8.4 step 1 already declines a line containing U+0009 and for the same kind of reason. The
+  two line models meet here and do not compose: §3.7.3a step 5 finds the block in a lone-U+000D
+  document, and §3.8.4's LF-only scan then reads that whole block as one line. Measured, the
+  result of letting it through is not merely inert — `title: a "b` and `c" d` on two mapping
+  lines pair their marks across the boundary, an unlisted line inside the listed key's scalar
+  takes `fr`'s spacing, and the U+000D lands **inside a span**, which §3.8.4 forbids in the same
+  breath. Per line rather than per block, because a stray U+000D inside one quoted value is
+  something people produce by accident and it should cost that value rather than the whole block:
+  a lone-U+000D document is one §3.8.4 line and loses everything, a document with one such value
+  loses that line and keeps the rest. **The test runs to the start of the next line, not to the
+  end of this one**, because §3.8.4's own splitter treats a trailing U+000D as a terminator even
+  without a U+000A after it — so a block whose single line ends in one looks clean if the
+  terminator is excluded, and one of the four lone-U+000D fixtures separates the two readings.
+  **The decline drops the spans the content scan produced for that line; it does not alter the
+  content the scan is given, and a span reaching a declined position is dropped whole rather than
+  trimmed.** Three ports reached for the shortcut of substituting the U+000D for another
+  character the scan already declines, and it is not equivalent: substitution moves the character
+  to a different line and can end a value run, so `title` / `slug` / a content-final U+000D
+  converts both keys instead of one, and a stray U+000D on a key whose value run continues onto
+  an indented line converts a key that is not a key. Both shapes are pinned, and both agree with
+  what `yaml` mode already does with the same characters — measured in two shipped runtimes.
+  **Where this rule and `yaml` mode part is on purpose, and it is one shape:** a content line
+  whose terminator is a bare U+000D is clean to `yaml` mode, which strips it, and declined here,
+  because the window includes it. So `title` / `slug` / a content-final U+000D converts `slug` in
+  `yaml` mode and does not here. The wider decline is the direction this section takes everywhere
+  else — a miss is invisible, a U+000D inside a span is not — and the cost is conversions lost in
+  documents written with line endings from the last century. Widening §3.8.4 instead would be a
+  change to `yaml` mode for every caller and wants its own measurement;
+- **both delimiter lines stay outside every span**, as does every line terminator, so no edit
+  can reach `---` itself and §3.7.3's setext-underline hazard is unreachable;
+- an **unterminated** block is not a block — §3.7.3 already yields no frontmatter construct
+  there, and the option adds no spans to it;
+- a **TOML block (`+++`) yields no spans, with the option given or not.** TOML's quoting is a
+  second grammar — basic strings escape with U+005C, literal strings do not escape at all, and
+  both have multi-line forms — and §3.8.3's posture applies: a construct the scan cannot claim
+  with certainty yields no spans. Neither report asked for TOML and no corpus measured here
+  contains one, so specifying a TOML locator would be scope taken on speculation. Recorded as an
+  accepted miss in §7.13.
+
+**The option adds spans only where §3.7.3's skip removed them.** If there is no block — an
+unterminated one, a `---` that is not at the start of the document, an opening line carrying
+anything but whitespace — the text is ordinary prose in the body's own unit and the option
+contributes nothing. That coupling is what makes double processing unreachable: no source position
+can belong to both units — **and since 1.8.0 it is §3.7.3a's mask and its no-span rule that enforce
+it**, not an agreement between two locators. Measured while that mask was still being specified, a
+block whose closer the body's parser did not accept had its content emitted twice, once by each
+unit: `more: b - c` came back as `more: b—cb—c`. **Since 1.8.0 the block's extent is §3.7.3a's
+scan** rather than whatever each parser's frontmatter support decided, so the option no longer
+inherits a variance that was measured in eleven documents out of twenty.
+
+**Key matching is §3.8.2's, which means bare names at any depth.** `title` is processable wherever
+it occurs in the block, `seo.title` included — measured: `seo:` then an indented `title:` is
+processed under `frontmatterKeys: ["title"]` — with the cost §7.12 already accepts for `keys`: no
+paths, no globs, so a caller with a machine-read `title` nested somewhere must either take it too
+or name none. Matching is exact, code point for code point, with no case folding.
+
+**The scan is §3.8's, unchanged.** §3.8.4 steps 1–9, §3.8.5 and §3.8.6 apply to the block content
+verbatim, with `frontmatterKeys` as step 8's key predicate in place of `keys`. Nothing about YAML
+is specified twice: frontmatter **is** YAML, and the argument that made §3.8 a hand-written scan
+rather than a parser call (§3.8.1 — two of the five ecosystems' libraries cannot report an end
+offset) applies here for the same reason and with the same measurements. Every miss §7.11 lists
+is inherited with it, the quoted-escape bails included, and §7.13 gives what that costs on a real
+corpus.
+
+**The frontmatter block is its own text unit, and this is the part that is not obvious.** §3.2
+concatenates a document's spans into one array and runs the pipeline once over it, and §7.10
+records that a quotation opened in one paragraph can still pair with a mark in the next, because
+the stack is not reset at a −2 marker. Measured on `polytypo` 1.6.3 in `yaml` mode, which has
+exactly this shape:
+
+```
+a: he said "hello          →    a: he said ‘hello
+b: world" she said              b: world’ she said
+```
+
+Two spans, a −2 marker between them, and the marks paired across it. If frontmatter spans joined
+the body's array, the same mechanism would let an unbalanced mark in `title` pair with one in the
+first paragraph — and the body's output would then depend on the document's metadata.
+
+> **The frontmatter block's spans form a text unit of their own.** The pipeline runs over
+> that array and over the body's array separately; the two edit sets are disjoint by
+> construction, since no span of one lies inside the other.
+
+That is one more pipeline run per document and it buys a claim worth having, which a port can
+test directly: **`frontmatterKeys` cannot change a byte outside the frontmatter block**, so every
+case released before 1.7.0 keeps its recorded output — those cases set no option, and the body is
+not reachable from one. The narrower claim is the true one: a released case's *block* would
+convert if the option named a key in it. Measured, `fr-markdown-commonmark-frontmatter-nbsp`:
+`title: Une note ; suite` takes its narrow no-break space under `frontmatterKeys: ["title"]`,
+which is the whole point of the option and not a change to that case. The
+asymmetry with `yaml` mode, where one document's keys do pair across each other, is deliberate:
+there the whole document is data with prose in it, while here the block is metadata *about* a
+document whose prose is the body, and the two are not one sentence in any document.
+
+**The option applies to both dialects**, `commonmark` and `mdx`. YAML frontmatter is the same
+construct in both, and §3.7.3 already lists it once for both.
+
+**Validation.** `nbsp.md` §3.1a fixes the order through `dialect` — `mode` → `narrowNbsp` →
+`rules` → `locale` → `dialect` — and `ARCHITECTURE.md`'s options table carries the whole of it.
+`frontmatterKeys` joins that chain **after `dialect`**, and, like every option, is checked **before
+the parse**. Both halves decide a case that is otherwise ambiguous. A call naming neither a valid
+`dialect` nor a valid `frontmatterKeys` raises `POLYTYPO_INVALID_DIALECT`, because `dialect` is
+first — and unlike `dialect` and `keys`, which belong to different modes and so never both apply,
+these two do, which is what makes their order observable at all. A document that does not parse in
+its dialect, called with a `frontmatterKeys` that is not a list of strings, raises
+`POLYTYPO_INVALID_OPTION` and not `POLYTYPO_MALFORMED_INPUT`.
+
+In `text`, `html` and `yaml` modes the option is **ignored and not validated**, exactly as
+`dialect` is ignored in `text` and `html` (§3.7.1). That is the weaker of
+the two choices and it is taken for consistency: a mode-specific option that throws in one mode and
+is ignored in another teaches a caller nothing they can act on, and `dialect` set the precedent
+before this option existed.
+
+**What a fixture cannot express here**, the same gap `nbsp.md` §3.1a records for `narrowNbsp`: the
+schema admits only a list of strings and only on a `markdown` case, so neither the throw above nor
+the ignored-elsewhere rule has a fixture. Both are each runtime's own unit test, and the order in
+this paragraph is what those tests assert.
+
+##### 3.7.4.1 What this was tested against
+
+The corpus is **187 `.mdx` files** — the author's own site content, all of `content/`, of which the
+107 under `content/blog/` are the M4 corpus proper (PLAN.md §8). Every one of them opens with YAML
+frontmatter and none with TOML. Keys `title`, `summary`,
+`description`, `subtitle`, `quote`: **447 listed scalars**. Eight locales (`en-GB`, `en-US`,
+`de-DE`, `fr`, `ru`, `es`, `sv`, `tr`), so 1496 file/locale cases per configuration.
+
+Measured with `polytypo` 1.6.3's **`yaml` mode over the extracted block** — the scan this section
+reuses — because `markdown` mode with the option exists in no runtime yet. The separate-unit rule
+above is what makes that a faithful proxy rather than an approximation: the body cannot
+participate.
+
+Three configurations, 4488 cases — the corpus as authored, the corpus de-typeset, and the corpus
+de-typeset with **every one of its 39 frontmatter keys** listed: **no byte changed outside a
+listed scalar, no parse failure, no structural change, no change to an unlisted leaf, no
+idempotency failure.** The de-typeset corpus is derived, and reported as derived: the site's
+content is already typeset, so the characters polytypo inserts were folded back to their ASCII
+originals to obtain input that has something to convert. It is a weaker corpus than found text,
+and it is the only way this corpus can show a conversion at all.
+
+- **The M4 bar holds as written.** As authored, in `en-GB` — the site's own locale — **0 of 187
+  files change**. Each of the other six changes 13 files and `fr` changes 117, every one of them
+  inside a listed scalar and from that locale's own conventions rather than from anything missed.
+- **De-typeset, 247 of the 447 listed scalars convert** in `en-GB`, and none of the other 200
+  is a miss: the pipeline leaves them alone in `text` mode too.
+- **The measurement is discriminating, which was checked rather than assumed.** The naive thing
+  a caller hand-rolls — the same blocks through `text` mode, no scan and no key list — damages
+  **every single case**: of 748 (187 files in `en-GB`, `de-DE`, `fr` and `ru`), **420 no longer
+  parse as YAML at all, 82 come back with different mapping keys, 246 with different values, and
+  none comes back unchanged.** The witnesses are ordinary: `fr` turns the key `name:` into
+  `name :`, and `en-GB` turns `slug: "pierre-moreau-architecture"` into
+  `slug: "‘pierre-moreau-architecture’"`. A harness reporting clean for both runs would prove
+  nothing; this one separates them completely.
+- **What the key list protects here.** Listing all 39 keys converts four values the recommended
+  five do not, and two of them are damage rather than coverage: in `fr`, `seoTitle` gains a
+  narrow no-break space before the colon of a string written for a search engine, and a client
+  name `"HTPBE?"` becomes `"HTPBE ?"`. The other two are improvements a caller might well want
+  (`"Niamh O'Sullivan"` → `"Niamh O’Sullivan"`), which is the point: only the caller can tell
+  those apart, and that is the same argument §3.8.2 makes.
+- **The inherited escape bail, measured.** Re-emitting each of the 247 convertible values in
+  one quoting style and running the scan over it: **single-quoted, 130 of 247 yield no spans**;
+  double-quoted, none do. The reason is §3.8.6's — an apostrophe inside a single-quoted scalar
+  is written `''`, which spells content with more characters than it has. Every listed scalar in
+  this corpus as written is double-quoted, so the bail never fires on it; a caller whose YAML
+  style is single quotes gets nothing on half of their prose, silently. That number is the
+  accepted cost of reusing §3.8's scan rather than a defect of this section, and §7.13 records it
+  where a reader will look for it.
+
 ### 3.8 Skip list — `yaml`
 
 **Spec 1.3.0.** `yaml` is the fourth mode id, and PLAN.md §3.2's "exactly three modes" is amended
@@ -785,7 +1141,9 @@ The length test of §3.4 separates exactly the two, with no knowledge of YAML
 makes it bind rules not yet written, while a per-rule observation would not.
 
 The accepted cost is that a conversion whose replacement would **grow** against a colon or a hash
-is missed: `fr` inserts no narrow no-break space before a colon inside a YAML scalar, and
+is missed: `fr` inserts no narrow no-break space before a colon inside a **plain** YAML scalar —
+inside a quoted one the colon is content, no split applies and the space is inserted, which
+`fr-markdown-commonmark-frontmatter-keys-colon` pins — and
 `one--two` takes its spaced dash only where the split leaves it interior to a span. That is the
 same trade §7.3 already made for `mot<em>!</em>`, and in the same direction: a miss is visible to
 the author and fixable in the source; a corrupted document is neither.
@@ -982,6 +1340,16 @@ they do not carry it over for free either. Write `M` for the whole mode transfor
    > §3.8.2's `keys` option is the repair: the predicate reads the **key**, which lies outside
    > every span and which no rule can reach, so the partition is a function of the source alone.
 
+   **`markdown` with `frontmatterKeys` (§3.7.4) inherits both**, and adds one obligation of its
+   own that is discharged by the same observation. The block's spans are selected by §3.8's scan
+   over YAML, so the four parts and the fifth hold verbatim — the predicate is `frontmatterKeys`
+   against a key, and a key is outside every span. What is new is that the document now has **two
+   units** rather than one, and `M` must partition it into the same two on the second run: the
+   boundary between them is the frontmatter construct's own delimiter lines, which lie outside
+   every span in either unit, so no edit can move, create or destroy one. A document whose
+   frontmatter is processed therefore has a partition that is a function of the source alone,
+   exactly as one whose frontmatter is skipped does.
+
    A content-dependent predicate is not merely risky here, it is unarguable: item 2's whole
    method is to show that the characters rules may write and the positions they may write to are
    disjoint from what decides structure. A predicate over span content puts the rules' own output
@@ -1004,7 +1372,9 @@ tests none of this document. In `yaml` the sweep alphabet must include `:`, `#`,
 as one token**, since those are the characters whose adjacency the argument above turns on and a
 three-dash run is not reachable from single dashes at a bounded payload length; and it must
 include U+0022 and U+005C, without which the sweep cannot reach a quoted scalar's delimiters at
-all. §3.8.7 records what each run did and did not establish — including that a sweep comparing
+all. Since 1.7.0 the `markdown` run must also carry a template with a **frontmatter block and
+`frontmatterKeys` naming a key in it** — a document with two text units (§3.1) tests a composition
+the single-unit templates cannot reach. §3.8.7 records what each run did and did not establish — including that a sweep comparing
 structure and types is blind to a string whose content is damaged, and that an alphabet without
 `---` reported clean twice while §3.4's `r = d` hole was open.
 
@@ -1020,7 +1390,11 @@ means the claim holds in those modes only.
   **[P: html, markdown, yaml]** and is now _defined_ rather than assumed — §3.6, §3.7 and §3.8
   are what those bullets refer to. In `text` mode there are no skipped regions and the bullet is
   vacuous. In `yaml` the definition runs the other way round (§3.8.2): the skipped region is
-  everything the scan did not claim.
+  everything the scan did not claim. Since 1.7.0 one region in `markdown` is skipped
+  **conditionally** — the frontmatter block, whenever `frontmatterKeys` names a key in it
+  (§3.7.4) — so the bullet is read against the options the call was made with. No rule's §4
+  changes: the block is either skipped whole, as before, or decomposed by §3.8's scan, whose
+  own claims §3.8 already states.
 - **`dashes` §4 "URLs, code spans, fenced code, HTML attributes"** — **[P: html, markdown]**.
   In `text` mode a URL is ordinary text. The rule is nevertheless safe there, but by its own
   guards (P1 declines the tight hyphens in `a-b`, the cluster guard declines `2026-08-15`), not
@@ -1040,9 +1414,13 @@ means the claim holds in those modes only.
   mark that would have been unbalanced within its own span may now pair across an element, which
   converts more, never less.
 - **`nbsp` §4 "The start or end of a text unit"** — **[P] in all modes, and strengthened.** A
-  "text unit" is the concatenation, and §3.4 additionally refuses any insertion at a span
-  boundary, so no span ever begins or ends with a character `nbsp` put there. The guarantee is
-  now about element boundaries as well as document boundaries.
+  "text unit" is §3.1's — the concatenation — and §3.4 additionally refuses any insertion at a
+  span boundary, so no span ever begins or ends with a character `nbsp` put there. The guarantee
+  is now about element boundaries as well as document boundaries. Since 1.7.0 a document may have
+  two units (§3.7.4), and the guarantee is read **per unit**: the frontmatter block's first and
+  last positions are unit extremities of their own, which refuses more than one unit would, never
+  less. That is also what makes `-separate-unit` deterministic rather than a coincidence — the
+  same reading `quotes` gives a unit edge.
 
 - **`dashes` §4, the `-spaced` forms** — a new **[R]** consequence in `html`/`markdown`, not a
   change to any existing bullet. A `-spaced` locale converts a dash only where the replacement
@@ -1223,6 +1601,47 @@ rule-local.
     document has yet needed it. If one does, this is where it reopens, and the extension is
     additive — a caller passing bare names keeps today's behaviour.
 
+13. **What `frontmatterKeys` deliberately does not claim (spec 1.7.0).** Three entries, and the
+    last is a number rather than a construct:
+
+    - **TOML frontmatter (`+++`) yields no spans**, with the option given or not. Its quoting is a
+      second grammar — U+005C escapes in basic strings, none in literal strings, multi-line forms
+      of both — and §3.8.3's posture is to claim only what the scan has proved. Neither report
+      behind the option (polytypo/polytypo#13, #26) asked for TOML, and the 187-file corpus of
+      §3.7.4.1 contains none. Widening to TOML is additive: a caller passing keys today keeps
+      today's behaviour.
+    - **~~The block itself is recognised by the mode, not by a scan specified here.~~ Closed in
+      1.8.0 by §3.7.3a.** It was here because §3.7.4's content range is exact once there is a
+      block, while the block itself came from each parser's own frontmatter support — and the
+      measurement that followed found those disagreeing two against two on a trailing space,
+      with the two that declined the block typesetting the metadata. The locator is now
+      specified, which is where it belonged: it governs the skip for every caller, not only
+      those who pass the option.
+    - **A lone-U+000D document has a block, and `frontmatterKeys` yields nothing inside it.**
+      §3.7.3a step 5 finds the block by CommonMark's line model and §3.8.4 reads content by its
+      own, so the block reaches the content scan as a single line. An earlier draft let that
+      stand and called it inert; measuring it showed it was not. On two mapping lines a quotation
+      opened on one paired with a mark on the other, an unlisted line inside the listed key's
+      scalar took `fr`'s spacing, and the U+000D landed inside a span — which §3.8.4 forbids in
+      the same breath. §3.7.4 therefore declines any content line carrying such a U+000D — per
+      line, so that a stray one inside a single quoted value costs that value and not the block.
+      The block is still skipped, so nothing machine-read is typeset either way. A lone-U+000D
+      document is one line to §3.8.4 and therefore loses the whole block, which is the price of
+      not widening that section here.
+    - **§3.8.6's single-quoted bail costs more here than anywhere it has been measured before.**
+      Of the 1858 corpus values a locale would convert across eight locales, **1040 yield no spans
+      when written as a single-quoted scalar** — 130 of 247 in `en-GB` alone, the figure 1.7.0
+      shipped with, and `scripts/miss-census.mjs` in this repository is what reproduces either on
+      demand. An apostrophe inside such a scalar is spelled `''`, and an apostrophe
+      is exactly what `apostrophe` and `quotes` convert, so the bail falls hardest on the values
+      the option exists for. Double-quoted, none bail. The corpus as authored is entirely
+      double-quoted, so its own author never meets this; a caller whose YAML style is single
+      quotes gets nothing on half their prose, and gets it silently. The repair is not this
+      section's to make: §3.8.6 is ratified and measured, and the obvious extension — treating
+      `''` as an opaque two-code-point unit, exactly as §3.8.6 already treats `:` and `#` inside a
+      plain scalar — changes `yaml` mode for every caller and needs its own measurement and its
+      own sign-off.
+
 ## 8. Fixture coverage strategy (non-normative)
 
 This section records why `spec/fixtures/` does not carry the full every-locale × four-modes

data/lib/polytypo/data/rules/order.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.6.3",
+  "spec": "1.8.0",
   "$comment": "Single source of truth for pipeline order. Rules run in ascending `order`. Disabling a rule removes it from the sequence and never reorders the rest. Rule ids are public API (see docs/ARCHITECTURE.md section 5). \"spec\" here must track spec/VERSION exactly — it is not itself the global version source; scripts/validate-spec.mjs enforces the match.",
   "rules": [
     {

data/lib/polytypo/data/schema/fixtures.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://polytypo.org/schema/fixtures.schema.json",
   "title": "polytypo conformance fixtures",
-  "description": "Executable form of the rule semantics. Every case is also an idempotency case: a runner must additionally assert transform(out) == out, passing the case's own options (mode, dialect, keys, rules, narrowNbsp) on that second call exactly as on the first — a case is a fixed point under its own options, not under the defaults.",
+  "description": "Executable form of the rule semantics. Every case is also an idempotency case: a runner must additionally assert transform(out) == out, passing the case's own options (mode, dialect, keys, frontmatterKeys, rules, narrowNbsp) on that second call exactly as on the first — a case is a fixed point under its own options, not under the defaults.",
   "type": "object",
   "additionalProperties": false,
   "required": ["spec", "locale", "cases"],
@@ -29,6 +29,11 @@
             "if": { "properties": { "mode": { "const": "yaml" } }, "required": ["mode"] },
             "then": { "required": ["keys"] },
             "else": { "not": { "required": ["keys"] } }
+          },
+          {
+            "if": { "properties": { "mode": { "const": "markdown" } }, "required": ["mode"] },
+            "then": true,
+            "else": { "not": { "required": ["frontmatterKeys"] } }
           }
         ],
         "oneOf": [{ "required": ["out"] }, { "required": ["throws"] }],
@@ -62,6 +67,12 @@
             "items": { "type": "string" },
             "description": "Required when mode is \"yaml\" — spec/rules/modes.md §3.8.2 gives the option no default, so a fixture must name the processable keys exactly as a caller would. An empty array is legal and processes nothing. Meaningless for the other modes."
           },
+          "frontmatterKeys": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Optional, spec 1.7.0, and only meaningful when mode is \"markdown\" — spec/rules/modes.md §3.7.4's opt-out from the frontmatter skip. Absent means the block is skipped whole, exactly as before 1.7.0; an empty array is legal and yields no spans. A runner passes it through to transform() as it passes dialect.",
+            "$comment": "The block is its own text unit (§3.7.4), so this option cannot change a byte of the body — every case released before 1.7.0 keeps its recorded output whatever it is set to."
+          },
           "in": { "type": "string" },
           "out": { "type": "string" },
           "throws": {

data/lib/polytypo/engine/pipeline.rb

@@ -59,6 +59,35 @@ module Polytypo
       value.to_set
     end
 
+    # modes.md 3.7.4: "markdown" mode's `frontmatter_keys` option (spec 1.7.0).
+    #
+    # Optional, unlike `keys` -- nil means the frontmatter block is skipped whole, which is every
+    # pre-1.7.0 document's behaviour -- and an empty Array is legal, exactly as it is for `keys`.
+    # Checked after dialect and before the parse, which is what decides that a document failing to
+    # parse in its dialect still reports the option error rather than CODE_MALFORMED_INPUT.
+    def self.resolve_frontmatter_keys(value)
+      return nil if value.nil?
+
+      unless value.is_a?(Array)
+        raise Polytypo::Error.new(
+          Polytypo::CODE_INVALID_OPTION,
+          '"frontmatter_keys" must be an Array of Strings when given (modes.md 3.7.4). ' \
+          "Received #{value.inspect}.",
+        )
+      end
+
+      value.each do |key|
+        next if key.is_a?(String)
+
+        raise Polytypo::Error.new(
+          Polytypo::CODE_INVALID_OPTION,
+          "\"frontmatter_keys\" must contain only Strings; received #{key.inspect}.",
+        )
+      end
+
+      value.to_set
+    end
+
     # Resolves the locale, builds the rule plan, and runs each enabled rule in
     # spec/rules/order.json order over a code-point array, applying its edits before the next
     # rule sees it. No module-level mutable state beyond the immutable, load-once-on-first-use