Answer architecture round 2: the claims type keeps directives apart from alerts and highlights, two paragraphs reflowed

README.md

@@ -167,12 +167,12 @@ carries it opaquely and restores it unchanged ([`docs/decisions.md`](https://git
 
 `ConvertError` is `{ code, message, path, position? }`. `code` is the exported `ConvertErrorCode`,
 stable across minors and safe to `switch` on exhaustively with no `default`; `message` is free text
-and may change in any release. A parse always names a position, so the three markdown readers
-return `ParseError`, whose `position` reads without a guard; an emit reads no
-source and carries `path` alone; one handler typed on `ConvertError` takes both, which is what the
-calls between markdown and HTML hand back. `path` is the node's place from the
-document root, alternating `'content'` and an index, so `path.map((step) => '/' + step).join('')`
-is a JSON Pointer at the node — the empty path being the document itself.
+and may change in any release. A parse always names a position, so the three markdown readers return
+`ParseError`, whose `position` reads without a guard; an emit reads no source and carries `path`
+alone; one handler typed on `ConvertError` takes both, which is what the calls between markdown and
+HTML hand back. `path` is the node's place from the document root, alternating `'content'` and an
+index, so `path.map((step) => '/' + step).join('')` is a JSON Pointer at the node — the empty path
+being the document itself.
 
 A call reports the first refusal in document order and stops, so a document with several surfaces
 them one per call. Every refusal is deterministic — there is no I/O anywhere — so a retry returns

src/markdown/portable/conventions.ts

@@ -18,8 +18,10 @@ export type Claims = {
 // The writer spells pipe tables and `~~` in every flavour it writes.
 type WrittenClaims = Claims & { pipeTables: true; strikethrough: true }
 
-// No flavour claims directives beside alerts or highlights: an expand directive leaves `inExpand` unset and a directive's slot reads `==`.
-export const flavourClaims: Readonly<{ commonmark: Claims } & Record<WrittenFlavour, WrittenClaims>> = {
+// Directives exclude alerts and highlights: an expand directive leaves `inExpand` unset and a directive's slot reads `==`.
+type ReadClaims = Claims & ({ directives: false } | { alerts: false; directives: true; highlights: false })
+
+export const flavourClaims: Readonly<{ commonmark: ReadClaims } & Record<WrittenFlavour, ReadClaims & WrittenClaims>> = {
   commonmark: { alerts: false, carryFence: false, directives: false, highlights: false, pipeTables: false, strikethrough: false, taskMarkers: false },
   lossless: { alerts: false, carryFence: true, directives: true, highlights: false, pipeTables: true, strikethrough: true, taskMarkers: false },
   portable: { alerts: true, carryFence: false, directives: false, highlights: true, pipeTables: true, strikethrough: true, taskMarkers: true },

todo.md

@@ -128,9 +128,10 @@ and its spelling leaves the README's "Four CommonMark spellings" bullet, which c
 
 ### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and markdown to and from HTML composed through ADF, each call named by its flavour.
 
-Lands after items 6, 59, 60, 61 and 62. Which flavours get a composed call is this item's to
-settle; the CommonMark spec suite also runs against the one reading CommonMark. The README documents HTML as it documents markdown. `htmlToAdf` refuses a value
-that is not a string as `not-a-string` (`docs/decisions.md` §Which code a cause takes).
+Lands after items 6, 59, 60, 61 and 62. Which flavours get a composed call is this item's to settle;
+the CommonMark spec suite also runs against the one reading CommonMark. The README documents HTML as
+it documents markdown. `htmlToAdf` refuses a value that is not a string as `not-a-string`
+(`docs/decisions.md` §Which code a cause takes).
 
 ### 45. Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.