@heroiclands/package-build 18.2.0 → 20.0.0

package/engine/actor-compiler.mjs

@@ -63,6 +63,14 @@ import { contentPackage } from "./content-package.mjs";
 // inferred from the type itself (#79).
 import { mapsNoteType, noteTypesFor, referencedSubtype } from "./document-subtypes.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
+// An `items:` entry's `system:` overlay is merged verbatim, so it reaches the
+// document by a path no field declaration sits on — including, until #330, the
+// fields the document is supposed to write for itself in play.
+import { itemFields } from "./item-registry.mjs";
+import { runtimeOnlyIn, runtimeOnlyMessage } from "./runtime-only-fields.mjs";
+// A `model:` is an address, read by the same grammar every wikilink is (#336),
+// so an author writes one form and meets one set of messages.
+import { readQualifier } from "./wikilinks.mjs";
 
 /**
  * Strip compendium-only fields from a predefined item before embedding it
@@ -134,6 +142,61 @@ export function itemAddress(subType, shortcode) {
     return `${subType}:${shortcode}`;
 }
 
+/**
+ * The key one predefined item is held under **for the package that publishes
+ * it** — the address a `model:` naming that package resolves through (#334).
+ *
+ * The unqualified {@link itemAddress} stays beside it, and the two answer
+ * different questions. A `model` that names no package means *this* one and
+ * takes the unqualified key, where a local definition still shadows a
+ * dependency's. A `model` that names a package takes this one, which nothing
+ * can shadow: that is the whole point of writing the package down.
+ *
+ * Not the canonical wikilink address, because this map is keyed in the
+ * **document's** vocabulary — a Foundry Item subtype — while a canonical address
+ * carries the *note* type. The two differ wherever a system maps a type to a
+ * differently-named subtype, and translating here would put the translation in
+ * two places.
+ *
+ * @param {string} pkg - The content package that publishes the item.
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`.
+ * @returns {string} The address, `package:subType:shortcode`.
+ */
+export function packagedItemAddress(pkg, subType, shortcode) {
+    return `${pkg}:${subType}:${shortcode}`;
+}
+
+/**
+ * The key one predefined item is held under **in the catalogue**, with the
+ * shortcode folded to lower case.
+ *
+ * A shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
+ * `HsTunic` — while an **address** is not: `readQualifier` normalises what it
+ * reads, and every canonical address is lowercase. So the moment a `model:` is
+ * read as an address (#334), `weapongear-clb` has to find the document whose
+ * `system.shortcode` is `Clb`, and an exact match cannot (#346).
+ *
+ * Folding is safe because the fold is already the address: no two items in any
+ * published tree differ only by the case of their shortcode, and #340 will make
+ * that impossible rather than merely true.
+ *
+ * **This is not {@link itemAddress}, and must not become it.** That one seeds
+ * {@link embeddedItemId}, so folding there would change the `_id` of every
+ * embedded item whose identity carries a capital — a silent re-identification of
+ * documents nothing about which had changed. The catalogue is a lookup table;
+ * an id is a promise.
+ *
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`, in any case.
+ * @param {string} [pkg] - The publishing package, for the qualified form.
+ * @returns {string} The catalogue key.
+ */
+export function catalogueKey(subType, shortcode, pkg) {
+    const folded = String(shortcode).toLowerCase();
+    return pkg ? packagedItemAddress(pkg, subType, folded) : itemAddress(subType, folded);
+}
+
 /**
  * What identifies one embedded item on its actor.
  *
@@ -243,7 +306,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             }
             const shortcode = doc?.system?.shortcode;
             if (!doc?.type || !shortcode) continue;
-            const address = itemAddress(doc.type, shortcode);
+            const address = catalogueKey(doc.type, shortcode);
             const owner = source.get(address);
             if (owner && owner !== itemsSourceDir) {
                 throw new Error(
@@ -257,9 +320,17 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             // eslint-disable-next-line no-unused-vars
             const { _key, ...rest } = doc;
             map.set(address, rest);
+            // And under this package's own name, so a `model:` that names this
+            // package explicitly resolves to the same item (#334).
+            map.set(catalogueKey(doc.type, shortcode, contentPackage()), rest);
         }
     }
-    for (const foreignDir of foreignSourceDirs) {
+    for (const foreignEntry of foreignSourceDirs) {
+        // Each dependency's directory arrives with the package that published
+        // it (#334), so a foreign template gets its own canonical address
+        // rather than sharing the local address space.
+        const foreignDir = typeof foreignEntry === "string" ? foreignEntry : foreignEntry.dir;
+        const foreignPackage = typeof foreignEntry === "string" ? null : foreignEntry.package;
         for (const name of fs.readdirSync(foreignDir)) {
             if (!name.endsWith(".json")) continue;
             if (name.startsWith("folder_")) continue;
@@ -277,14 +348,19 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             }
             const shortcode = doc?.system?.shortcode;
             if (!doc?.type || !shortcode) continue;
-            const address = itemAddress(doc.type, shortcode);
+            const address = catalogueKey(doc.type, shortcode);
+            // eslint-disable-next-line no-unused-vars
+            const { _key, ...rest } = doc;
+            // Its own package-qualified address, which a `model:` naming that
+            // package resolves through and nothing local can shadow (#334).
+            if (foreignPackage) {
+                map.set(catalogueKey(doc.type, shortcode, foreignPackage), rest);
+            }
             if (map.has(address)) {
                 // Deliberate: this repository defines it, so its version wins.
                 if (source.has(address)) shadowed.push(address);
                 continue;
             }
-            // eslint-disable-next-line no-unused-vars
-            const { _key, ...rest } = doc;
             map.set(address, rest);
         }
     }
@@ -310,6 +386,21 @@ export class SystemActorCompiler extends BasePackCompiler {
     static id = "actors";
     static label = "actor";
 
+    /**
+     * **Both**, and they are two independent pictures: `img` is the actor's
+     * token art — written onto `document.img` and the prototype token's texture
+     * — and `portrait` is the sheet portrait, a declared field each system
+     * lands under its own name (`system.portrait` for SoHL,
+     * `system.bioImage` for HM3).
+     *
+     * Declared on the shared class because both subclasses emit both. A system
+     * whose actor genuinely carried only one would override it here rather than
+     * leave the claim standing.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img", "portrait"]);
+
     /**
      * Which `(actor, subType:identity)` each resolved entry claimed, and the
      * entry that claimed it first.
@@ -356,6 +447,20 @@ export class SystemActorCompiler extends BasePackCompiler {
     itemsSourceDirs;
     foreignSourceDirs;
 
+    /**
+     * Every package a `model:` may name besides this one — the dependencies
+     * whose item catalogues were supplied (#334).
+     *
+     * @returns {Set<string>} The dependency package ids.
+     */
+    get foreignPackages() {
+        return new Set(
+            (this.foreignSourceDirs ?? [])
+                .map((entry) => (typeof entry === "string" ? null : entry?.package))
+                .filter(Boolean),
+        );
+    }
+
     constructor({ itemsSourceDirs = [], foreignSourceDirs = [], ...options }) {
         super(options);
         // Where the items passes wrote their JSON. Stated by the caller rather
@@ -498,7 +603,66 @@ export class SystemActorCompiler extends BasePackCompiler {
      * @returns {object|null} The embedded item, or null when it resolved to
      *   nothing — always with a finding emitted.
      */
-    resolveEmbedded(itemsMap, actorId, type, shortcode, overlay, indexKey, ctx, { fmKey } = {}) {
+    /**
+     * Read an entry's `model:` — the address of the item it is a copy of.
+     *
+     * The address grammar is the wikilink one (#336), so a `model` is written at
+     * whatever length says what it means: `skill-wpnc` within this package,
+     * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
+     * the block the entry sits in — `<system>.items` — which is what makes the
+     * short form name an *Item* here while the same string in body prose names
+     * a page.
+     *
+     * It replaced a top-level `shortcode:` that meant something different from
+     * the `system.shortcode` beside it and could not say which package a
+     * template came from (#334).
+     *
+     * @param {unknown} model - The authored value.
+     * @param {number} index - The entry's position, for the message.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @returns {{type: string, shortcode: string, package: string|null}|null}
+     *   The parsed address, or `null` after reporting why it is not one.
+     */
+    readModel(model, index, ctx) {
+        const key = `${this.documentSubtypes.block}.items`;
+        const where = () =>
+            locateFrontmatterKey(this.currentNote?.absPath, "items", String(model ?? ""));
+        if (typeof model !== "string" || !model.trim()) {
+            this.noteError(`${ctx}: ${key}[${index}] \`model\` must be an address`, where());
+            this.errorCount++;
+            return null;
+        }
+        // The types this system maps, which are the ones a `model` may name, and
+        // every package one may reach: this repository's own plus each
+        // dependency whose item catalogue was loaded.
+        const types = new Set(Object.keys(this.documentSubtypes.types));
+        const packages = new Set([contentPackage(), ...this.foreignPackages]);
+        const read = readQualifier(model.trim(), types, packages);
+        if (!read || read.reason) {
+            const why =
+                read?.reason === "not-lowercase" ?
+                    "capitalises a package, system or type segment — those three " +
+                    "are lowercase, and only the shortcode keeps its case"
+                : read?.reason === "unknown-type" ? "names no known content type"
+                : "is not an address — write `type-shortcode`, or " +
+                    "`package-system-type-shortcode` for another package's item";
+            this.noteError(`${ctx}: ${key}[${index}] \`model: ${model}\` ${why}`, where());
+            this.errorCount++;
+            return null;
+        }
+        return { type: read.type, shortcode: read.shortcode, package: read.package ?? null };
+    }
+
+    resolveEmbedded(
+        itemsMap,
+        actorId,
+        type,
+        shortcode,
+        overlay,
+        indexKey,
+        ctx,
+        { fmKey, modelPackage = null } = {},
+    ) {
         // Where a finding about this reference points. The value locates the
         // exact entry in a list; the key is the fallback when it cannot be
         // found, which still beats naming the note alone.
@@ -511,7 +675,33 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        const address = itemAddress(/** @type {string} */ (subType), shortcode ?? "");
+        // A `model:` may name the package its template comes from (#334). Where
+        // it does, the packaged address is used and nothing local can shadow
+        // it; where it does not, the unqualified one is, and a local definition
+        // still wins over a dependency's as it always has.
+        const address = catalogueKey(
+            /** @type {string} */ (subType),
+            shortcode ?? "",
+            modelPackage ?? undefined,
+        );
+
+        // The entry's `system:` overlay is merged verbatim, so it reaches the
+        // document without passing a single field declaration — which left it
+        // the one position a runtime-only field stayed authorable at once #330
+        // closed the item note's own. Asked of the **overlay** rather than of
+        // the merged result: the template it merges onto is a compiled
+        // document, which by then carries none, and a finding has to name what
+        // this note wrote.
+        const [runtimeOnly] = runtimeOnlyIn(overlay?.system, itemFields(type, this.system));
+        if (runtimeOnly) {
+            this.noteError(
+                `${ctx}: ${indexKey}: ` +
+                    `${runtimeOnlyMessage(`${indexKey}.system.${runtimeOnly.to}`, runtimeOnly)}.`,
+                where(),
+            );
+            this.errorCount++;
+            return null;
+        }
 
         let base = null;
         if (shortcode) {

package/engine/address-charset.mjs

@@ -39,15 +39,33 @@
  */
 
 /**
- * The shape every address segment must match: ASCII letters and digits only.
+ * The shape every address segment must match: **lowercase** ASCII letters and
+ * digits only.
  *
- * Case is deliberately **not** constrained. Hundreds of authored shortcodes are
- * mixed-case and collide with nothing, and case has no bearing on the
- * separator, which is the whole of what this pattern is protecting.
+ * Case *was* deliberately unconstrained, on the reasoning that case has no
+ * bearing on the separator — which is true, and beside the point (#340).
+ *
+ * **Two names that differ only in case are two names nobody can tell apart.** A
+ * shortcode is how a person names a thing when writing a reference —
+ * `model: weapongear-dgr`, `[[skill-melee|…]]` — and `Dgr` beside `dgr` is a
+ * distinction you cannot say out loud and can only see by looking twice.
+ *
+ * The toolchain had already half-decided it: {@link canonicalKey} lowercases the
+ * address it builds, so a note declaring `Clb` published
+ * `sohl-sohl-weapongear-clb` and its `_id` derived from that. The authored name
+ * and its address disagreed, and everything downstream keys on the address —
+ * which left two notes differing only in case sharing one address, one `_id` and
+ * one URL, with nothing to report it. It also forced two exceptions elsewhere:
+ * #336 had to exempt the shortcode from the lowercase rule it pinned on every
+ * other segment, and #346 had to fold the shortcode's case in the item catalogue
+ * because an address is lowercased when read.
+ *
+ * One case, one spelling, no exceptions. Every tree already complies but two,
+ * and nothing in any of them collides when folded.
  *
  * @type {RegExp}
  */
-export const ADDRESS_SEGMENT_PATTERN = /^[A-Za-z0-9]+$/;
+export const ADDRESS_SEGMENT_PATTERN = /^[a-z0-9]+$/;
 
 /**
  * Whether a value is a well-formed address segment.

package/engine/base-compiler.mjs

@@ -78,6 +78,7 @@ import {
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
+import { assertNoDeclaredFolder } from "./folder-notes.mjs";
 import {
     assertNoAliasesField,
     assertNoDraftField,
@@ -198,6 +199,34 @@ export class BasePackCompiler {
      */
     static requiresSystemBlock = false;
 
+    /**
+     * The **art fields** this pass reads off a note and writes onto its
+     * document — `img`, `portrait`, whichever of them reaches the output.
+     *
+     * Empty by default, and every shipped pass states its own, for the reason
+     * {@link BasePackCompiler.readsPackOutputOf} does: the fact belongs to the
+     * class that does the writing, and a second list of it somewhere else is a
+     * list free to disagree with what is actually emitted.
+     *
+     * The reader is the frontmatter lint. `img` is a *shared top-level* field —
+     * legal on every note whatever its type, because
+     * `BLOCK_DOCUMENT_PROPERTIES` maps it onto `document.img` — so a note whose
+     * document has no such property authors it, validates, compiles, and loses
+     * the value with nothing said. That is #349: `Parrot` in `sohl-thalorna`
+     * had declared `img:` since long before the art rule existed and compiled
+     * `img: null` exactly as a note declaring nothing does. Naming the fields
+     * here is what lets the lint tell an inert key from a live one.
+     *
+     * A pass that emits art **anywhere** in its document declares it, not only
+     * one that writes a top-level `img`: the scenes pass puts the path on the
+     * scene's background rather than on a property called `img`, and the value
+     * is no less live for it. The question this answers is whether the authored
+     * path reaches the output at all.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze([]);
+
     /** @type {string} */
     contentBase;
     /** @type {string} */
@@ -270,8 +299,9 @@ export class BasePackCompiler {
      * @param {string} options.dest - Where this pass writes its JSON.
      * @param {readonly string[]} options.skipDirectories - Directories the walk
      *   never descends into. Required: see {@link assertStatedScope}.
-     * @param {(path: string|null) => string|null} [options.folderResolver] -
-     *   Resolves a `sohl.folder` id against this pack's folder hierarchy.
+     * @param {(address: string|null) => string|null} [options.folderResolver] -
+     *   Resolves a `packFolder` — a folder note's address — to the Foundry
+     *   folder id it materialises as in this pack (#255, #257).
      * @param {string} [options.packName] - The pack this pass writes.
      * @param {string} [options.docType] - The Foundry document type it holds.
      * @param {{resolve: Function}} [options.router] - The pack router. Omit it
@@ -414,6 +444,31 @@ export class BasePackCompiler {
         );
     }
 
+    /**
+     * A refusal only this pass can make, because its subject is the note's
+     * **type** (#330).
+     *
+     * The `assertNo*Field` family above it in the walk is type-agnostic by
+     * construction: it runs before `selects`, so that a note declaring a
+     * retired field is answered whichever pass would have claimed it. A rule
+     * about what a *`trauma`* may write cannot live there — it needs the type's
+     * field declaration, which only the pass that compiles the type can reach.
+     *
+     * So it is a hook, called once the note is known to be this pass's, and its
+     * throw is counted and located exactly as the family's is: the note is
+     * declined rather than skipped, and the build fails naming the line.
+     *
+     * The default refuses nothing, which is the honest position for a pass
+     * whose documents have no schema to have opinions about.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {void}
+     * @throws {Error} When the note authors something its type forbids. The
+     *   error may carry a `position` for the diagnostic.
+     */
+    // eslint-disable-next-line no-unused-vars
+    assertAuthorable(fm) {}
+
     /**
      * Whether this pass claims a note. **Required.**
      *
@@ -895,6 +950,7 @@ export class BasePackCompiler {
             // neither message may repeat it.
             try {
                 assertNoDeclaredPackage(fm, { absPath });
+                assertNoDeclaredFolder(fm, { absPath });
                 assertNoDraftField(fm, { absPath });
                 assertNoAliasesField(fm, { absPath });
                 assertNoSectionField(fm, { absPath });
@@ -965,6 +1021,13 @@ export class BasePackCompiler {
                     stats.skippedOther++;
                     continue;
                 }
+                // The type-specific half of the retired-field family (#330):
+                // what a note of *this* type may not write, which needs the
+                // type's own field declaration and so cannot be asked before
+                // `selects`. Counted as a declined note for the same reason
+                // they are — the alternative is a tree that compiles fewer
+                // documents than it has notes and exits 0.
+                this.assertAuthorable(fm);
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;

package/engine/bundles.mjs

@@ -135,6 +135,15 @@ export class Bundles extends BasePackCompiler {
      */
     static readsPackOutputOf = Object.freeze(["Actor", "Item", "JournalEntry", "Macro", "Scene"]);
 
+    /**
+     * An Adventure carries an `img` — what Foundry shows on the import card.
+     * There is no default for it: a bundle naming none ships a blank tile,
+     * deliberately, since no stand-in artwork means "a set of documents".
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /**
      * The JSON directories this pass reads its members from, by document type.
      *

package/engine/content-address.mjs

@@ -45,7 +45,9 @@ import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 // The system vocabulary is the `<system>` segment's own registry, and
 // `engine/systems.mjs` imports nothing but `engine/address-charset.mjs`, so
 // the direction is toward the leaf and cannot close a cycle.
-import { NO_SYSTEM, assertSystemSegment } from "./systems.mjs";
+import { NO_SYSTEM, assertSystemSegment, isSystemSegment } from "./systems.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 
 // `ids.mjs` is a leaf with no local imports — the module note there says why —
 // so an address may hash itself without any risk of closing a cycle.
@@ -203,6 +205,95 @@ export function canonicalKey(pkg, system, type, shortcode) {
     return `${pkg}-${system}-${type}-${shortcode}`.toLowerCase();
 }
 
+/**
+ * Which system a frontmatter key path is written under.
+ *
+ * The **enclosing system block** decides, at any depth within it, and nothing
+ * else does: `sohl.items[3].model` and `sohl.system.body.structure` are both
+ * `sohl` because both sit under `sohl:`. Everywhere else is {@link NO_SYSTEM} —
+ * top-level frontmatter, the shared `data:` container, and body prose, which has
+ * no key path at all and passes `undefined`.
+ *
+ * It is the block rather than the field, so a `WikiLink` field needs no opinion
+ * about systems and no per-field table has to be kept in step with the schema.
+ *
+ * The first segment must **be** a declared system, not merely look like one:
+ * `sohlish.items` is a key called `sohlish`, and `notes.sohl.thing` names no
+ * block at all.
+ *
+ * @param {string} [keyPath] - The dotted frontmatter key path, or `undefined`
+ *   for body prose.
+ * @returns {string} The system id, or `none`.
+ */
+export function blockSystem(keyPath) {
+    if (typeof keyPath !== "string" || !keyPath) return NO_SYSTEM;
+    const first = keyPath.split(".")[0].trim().toLowerCase();
+    return isSystemSegment(first) && first !== NO_SYSTEM ? first : NO_SYSTEM;
+}
+
+/**
+ * Expand a written address to the one canonical address it names.
+ *
+ * **An omitted segment defaults from where the link is written** (#336) — it is
+ * not a wildcard, and resolution is not a search. Package omitted means the
+ * citing note's own; system omitted means {@link blockSystem} of the key path it
+ * was written under. So every short form has exactly one expansion, computed
+ * before anything is looked up, and there is no candidate set to disambiguate.
+ *
+ * **Under `none`, a system-bearing type addresses its documentation journal.**
+ * A note's `none` address *is* its `doc<type>` entry — the Item is the one with
+ * a system — so a prose `[[affiliation-sirvadar|…]]` names the page, which is
+ * almost always what prose means. A link that means the Item states the system
+ * and gets it. This is the defaulting rule applied, not an exception carved out
+ * of it.
+ *
+ * **Only a type whose own document carries a system is redirected.** A `macro`
+ * and the map types have documentation journals too, but their own documents
+ * are core ones and already live at `none` — so `<pkg>-none-macro-x` names the
+ * Macro and `<pkg>-none-docmacro-x` its journal, two live addresses that the
+ * redirect would collapse into one. The test is the note type's own system,
+ * not merely whether it has a doc entry.
+ *
+ * A `doc<type>` written explicitly is `none` **wherever** it appears, even
+ * inside a system block: no game system defines a JournalEntry, so there is no
+ * other system for one to belong to.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A qualifier, as `readQualifier` returns one.
+ * @param {{package: string, system?: string}} where - The citing context: the
+ *   tree's own content package, and the system of the block the link sits in.
+ * @returns {string} The canonical `package-system-type-shortcode`.
+ */
+export function expandAddress(read, where) {
+    const pkg = read.package ?? where.package;
+    // A documentation journal is a core document, so it is `none` however it was
+    // reached; otherwise the block's system, which body prose reports as `none`.
+    const system = read.itemDoc ? NO_SYSTEM : (read.system ?? where.system ?? NO_SYSTEM);
+    const redirected = system === NO_SYSTEM && isSystemBearing(read.type);
+    const type = read.itemDoc || redirected ? `doc${read.type}` : read.type;
+    return canonicalKey(pkg, system, type, read.shortcode);
+}
+
+/**
+ * Whether a note type's **own** document carries a game system.
+ *
+ * True for the types some shipped map compiles into an Item or an Actor; false
+ * for the core-document types — `doc`, `lore`, `place`, `scenario`, `macro` and
+ * the map types — whose documents Foundry itself defines and which therefore
+ * already live at `none`.
+ *
+ * It is what {@link expandAddress} tests rather than {@link hasDocEntry}: a
+ * `macro` has a documentation journal *and* a `none` address of its own, so
+ * redirecting on "has a doc entry" would collapse two live addresses into one
+ * and a `[[macro-autoattack|]]` would stop naming the Macro.
+ *
+ * @param {string} type - The note type.
+ * @returns {boolean} True when the type compiles into a system document.
+ */
+function isSystemBearing(type) {
+    return systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS) !== NO_SYSTEM;
+}
+
 /**
  * How many segments a canonical key has, and therefore how many the reader
  * below counts.

package/engine/content-format.mjs

@@ -46,6 +46,16 @@
  * A mapping table's remaining header cells name the systems (`→ sohl`,
  * `→ hm3`), so the system vocabulary comes from the document too.
  *
+ * **The other half of a type's vocabulary is a bullet list, not a table.** A
+ * type's `subType` values are stated as `**subType**:` followed by one bullet
+ * per value, `- <value>` or `- <value>: <definition>`, and that is read here
+ * for the same reason the tables are: so the specification and
+ * `note-vocabulary.mjs` cannot disagree about which genres exist (#345). The
+ * one shape is enforced rather than guessed at — the document wrote them five
+ * ways, and a reader that accepted every spelling would accept the sixth by
+ * reading the section as declaring nothing, which is the drift it exists to
+ * catch. An unrecognised shape throws.
+ *
  * **A mapping table before the first `### type:` heading is the shared one.**
  * The document states the rows every type maps identically once, at the top,
  * and omits them from all sixteen per-type tables — so a parser that only ever
@@ -92,6 +102,9 @@ export const CONTENT_FORMAT_PATH = path.join(
  *   property — what a note actually writes. `appearance.eye_color` is authored
  *   as `appearance`, so that is the key recorded.
  * @property {Set<string>} dataPaths - The declared paths, whole.
+ * @property {string[]} subTypes - The `subType` values the section enumerates,
+ *   in document order — empty when it states none, which is the ordinary case
+ *   for a type that has no `subType` at all.
  */
 
 /**
@@ -178,6 +191,79 @@ function columnOfCell(line, index) {
     return at + lead + 2;
 }
 
+/** The one shape the specification states a type's `subType` values in. */
+const SUBTYPE_MARKER = "**subType**:";
+
+/** Any line that reads as a `subType` marker, canonical or not. */
+const SUBTYPE_MARKER_ISH = /^\s*\**\s*subTypes?\s*\**\s*:?\s*$/i;
+
+/** One bullet of a values list: `- <value>` or `- <value>: <definition>`. */
+const SUBTYPE_BULLET = /^-\s+(\S+?)\s*(?::|$)/;
+
+/**
+ * A parse failure, positioned where the document went wrong.
+ *
+ * Thrown rather than collected, because there is nothing partial to report: a
+ * marker the reader does not understand yields a section that appears to
+ * declare no subTypes, and every comparison against it then passes vacuously
+ * (#345). The message carries the compiler-parseable position the rest of the
+ * toolchain's diagnostics use.
+ *
+ * @param {string} file - The document being read.
+ * @param {number} line - 1-based line the fault is on.
+ * @param {string} message - What is wrong, and what to write instead.
+ * @returns {Error} The failure to throw.
+ */
+function specError(file, line, message) {
+    return new Error(`${file}:${line}:1: error: ${message}`);
+}
+
+/**
+ * The `subType` values a section enumerates under its marker.
+ *
+ * Reads the one contiguous bullet list directly below the marker and stops
+ * there: several sections state another closed vocabulary of their own a blank
+ * line later — `TransmissionTypes`, `GovernanceModel` — and reading on would
+ * quietly attribute its values to `subType`.
+ *
+ * @param {string[]} lines - The document's lines.
+ * @param {number} at - Index of the marker line.
+ * @param {string} file - The document, for the failure message.
+ * @returns {string[]} The values, in document order.
+ */
+function subTypeValues(lines, at, file) {
+    /** @type {string[]} */
+    const values = [];
+    let i = at + 1;
+    while (i < lines.length && lines[i].trim() === "") i += 1;
+    for (; i < lines.length; i += 1) {
+        const line = lines[i];
+        // A wrapped definition is indented under its own bullet.
+        if (values.length && /^\s+\S/.test(line)) continue;
+        if (!line.startsWith("-")) break;
+        const bullet = SUBTYPE_BULLET.exec(line);
+        const value = bullet?.[1].replace(/`/g, "");
+        if (!value || !/^[A-Za-z0-9]+$/.test(value)) {
+            throw specError(
+                file,
+                i + 1,
+                `\`${SUBTYPE_MARKER}\` takes one bullet per value, ` +
+                    "`- <value>` or `- <value>: <definition>`, and this bullet states none.",
+            );
+        }
+        values.push(value);
+    }
+    if (!values.length) {
+        throw specError(
+            file,
+            at + 1,
+            `\`${SUBTYPE_MARKER}\` enumerates no values. A type whose subType values the ` +
+                "specification does not state omits the marker.",
+        );
+    }
+    return values;
+}
+
 /**
  * Parse the specification's tables.
  *
@@ -211,12 +297,28 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
                 line: i + 1,
                 dataKeys: new Set(),
                 dataPaths: new Set(),
+                subTypes: [],
             };
             types.set(current.name, current);
             table = undefined;
             continue;
         }
 
+        if (current && SUBTYPE_MARKER_ISH.test(line)) {
+            if (line.trim() !== SUBTYPE_MARKER) {
+                throw specError(
+                    file,
+                    i + 1,
+                    `a type's subType values are stated as \`${SUBTYPE_MARKER}\`, ` +
+                        `not \`${line.trim()}\`. The specification had five spellings and ` +
+                        "converged on one, so that a section is never read as declaring none.",
+                );
+            }
+            current.subTypes = subTypeValues(lines, i, file);
+            table = undefined;
+            continue;
+        }
+
         const cells = cellsOf(line);
         if (!cells) {
             // Any non-table line ends the table. A blank line between two