@heroiclands/package-build 23.1.1 → 23.2.0

package/engine/note-addresses.mjs

@@ -2,11 +2,17 @@
  * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
  * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
  *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 import { declaredSystems, systemBlocksFor } from "./system-vocabulary.mjs";
-import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
+import { inBlockKey } from "./system-block.mjs";
 import {
     isAddressTuple,
     parseAddress,
@@ -23,6 +29,7 @@ import { SHIPPED_SYSTEMS } from "./subtype-registry.mjs";
 import { EVENT_ADDRESS_POSITIONS } from "./note-events.mjs";
 
 import { AddressEntries, AddressLink, readPublishedAddresses } from "./address-values.mjs";
+import { formatDiagnostic } from "./diagnostics.mjs";
 export {
     AddressEntries,
     encodeAddresses,
@@ -72,12 +79,8 @@ export const STRUCTURED_ADDRESSES = Object.freeze([
 export function addressPositions(fm, context = {}) {
     const out = [];
     for (const field of dataFields(fm.type) ?? []) {
-        // A field that admits both a list and a map declares both halves, and
-        // which one a note wrote is not knowable from the declaration — so the
-        // position says "either" and the conversion reads the value's shape.
         const shape =
             field.kind === "address" ? "value"
-            : field.kind === "list-or-map" ? "keys-or-list"
             : field.keyKind === "address" ? "keys"
             : field.entryKind === "address" ? field.kind
             : undefined;
@@ -87,6 +90,7 @@ export function addressPositions(fm, context = {}) {
                 shape,
                 type: field.ref,
                 accepts: field.accepts,
+                ...(field.declines === undefined ? {} : { declines: field.declines }),
                 ...(field.anchors ? { anchors: field.anchors } : {}),
                 ...(ASSET_TYPE_NAMES.has(field.ref) || field.ref === "folder" ?
                     { system: "none" }
@@ -120,7 +124,6 @@ export function addressPositions(fm, context = {}) {
             path: [system, "items", "*", "model"],
             shape: "value",
             system,
-            legacyShortcodeCase: true,
         });
         for (const slot of ART_SLOTS)
             out.push({
@@ -145,7 +148,7 @@ export function addressPositions(fm, context = {}) {
                             system,
                             types: new Set([...Object.keys(NOTE_VOCABULARY), ...ASSET_TYPE_NAMES]),
                         },
-                        { declared: true, legacyShortcodeCase: true },
+                        { declared: true },
                     );
             const type = model && !model.reason ? model.type : entry?.type;
             for (const field of spec?.fields?.[type] ?? []) {
@@ -182,30 +185,90 @@ export function addressPositions(fm, context = {}) {
                     :   system,
             };
             out.push({ ...position, path: [system, "system", ...field.to.split(".")] });
-            out.push({
-                ...position,
-                path: [system, ...(field.legacyKey ?? field.name).split(".")],
-            });
+            const inBlock = inBlockKey(field);
+            if (inBlock !== undefined) {
+                out.push({ ...position, path: [system, ...inBlock.split(".")] });
+            }
             if (field.name?.startsWith("data.") && field.topLevelMeans === undefined)
                 out.push({ ...position, path: field.name.slice(5).split(".") });
         }
     }
-    for (const position of [...out]) {
-        const last = position.path.at(-1);
-        const retired = RETIRED_FIELD_ALIASES[last];
-        if (retired) out.push({ ...position, path: [...position.path.slice(0, -1), retired] });
-    }
     return out;
 }
 
+/**
+ * The finding for a declared Address whose shortcode carries a capital.
+ *
+ * A shortcode is lowercase, and a declared Address is read as written, so the
+ * value is refused rather than folded. Where the lowercase spelling names
+ * something the context declares, the message names that shortcode.
+ *
+ * @param {import("./address.mjs").AddressProblem} problem - The parser's verdict.
+ * @param {Array<string|number>} path - The value's key path.
+ * @param {{shape?: string}} position - The Address position it sits in.
+ * @param {{declaresAddress?: (tuple: object) => boolean}} context - The
+ *   decode context; `declaresAddress` answers whether a complete Address names
+ *   a declared note or item.
+ * @returns {Error & {keyPath: Array<string|number>, addressKey: boolean}} The
+ *   located error.
+ */
+function shortcodeCaseError(problem, path, position, context) {
+    const declared =
+        context.declaresAddress?.(problem.lowercase) ?
+            `; the declared shortcode is \`${problem.lowercase.shortcode}\``
+        :   "";
+    const error = new Error(
+        `\`${path.join(".")}\` shortcode \`${problem.shortcode}\` must be lowercase${declared}`,
+    );
+    error.keyPath = path;
+    error.addressKey = position.shape === "keys";
+    return /** @type {any} */ (error);
+}
+
 /**
  * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
+ *
+ * A declared Address is read as written. A shortcode spelled with a capital is
+ * refused, and every such value in the note is collected before the decode
+ * throws, so each reference is reported at its own position: the thrown error
+ * describes the first, and its `findings` carry all of them.
+ *
  * @param {object} fm - Parsed YAML or an index record.
- * @param {object} context - The builder's package and known types.
+ * @param {object} context - The builder's package and known types, and
+ *   optionally `declaresAddress`, which names the lowercase spelling of a
+ *   refused shortcode when it is declared.
  * @returns {object} The same note carrying typed Address properties.
+ * @throws {Error} When a declared Address is refused; `keyPath` locates it, and
+ *   `findings`, where present, lists every refused shortcode.
  */
 export function decodeNoteAddresses(fm, context) {
     if (!fm || typeof fm !== "object") return fm;
+    /** @type {Array<Error & {keyPath: Array<string|number>}>} */
+    const refused = [];
+    try {
+        decodePositions(fm, context, refused);
+    } catch (error) {
+        if (refused.length && error?.keyPath) error.findings = [...refused, error];
+        throw error;
+    }
+    if (refused.length) {
+        const [first] = refused;
+        /** @type {any} */ (first).findings = refused;
+        throw first;
+    }
+    return fm;
+}
+
+/**
+ * The body of {@link decodeNoteAddresses}: every Address position, decoded in
+ * place.
+ *
+ * @param {object} fm - The note.
+ * @param {object} context - The decode context.
+ * @param {Error[]} refused - Collects each refused shortcode.
+ * @returns {void}
+ */
+function decodePositions(fm, context, refused) {
     const types = new Set([
         ...Object.keys(NOTE_VOCABULARY),
         ...ASSET_TYPE_NAMES,
@@ -223,11 +286,14 @@ export function decodeNoteAddresses(fm, context) {
                 `\`${path.join(".")}\` ${description}: ${JSON.stringify(value)}`,
             );
             error.keyPath = path;
-            error.addressKey = position.shape === "keys" || position.shape === "keys-or-list";
+            error.addressKey = position.shape === "keys";
             throw error;
         };
         const read = (value, path) => {
             if (value == null || value === "") return value;
+            // The word a position declines with is not an Address; it stays as
+            // written so every later stage can tell it from an image.
+            if (position.declines !== undefined && value === position.declines) return value;
             if (value instanceof AddressLink) {
                 if (!position.anchors)
                     fail(
@@ -248,10 +314,11 @@ export function decodeNoteAddresses(fm, context) {
                     "takes no anchor — it names a whole note, so write the Address without `#…`",
                 );
             const { address: written, anchor } = anchored ? splitAnchor(value) : { address: value };
-            const tuple = parseAddress(written, defaults, {
-                declared: true,
-                legacyShortcodeCase: position.legacyShortcodeCase,
-            });
+            const tuple = parseAddress(written, defaults, { declared: true });
+            if (tuple.reason === "shortcode-not-lowercase" && !position.lenient) {
+                refused.push(shortcodeCaseError(tuple, path, position, context));
+                return value;
+            }
             if (tuple.reason) fail(value, path, "is not an accepted Address");
             if (position.accepts && !acceptsType(tuple, position.accepts))
                 fail(
@@ -269,15 +336,7 @@ export function decodeNoteAddresses(fm, context) {
         };
         const convert = (value, path) => {
             if (value == null || value === "") return value;
-            // Whichever of the two shapes the note wrote, read as that one. An
-            // empty list is the property editor's emptied map and converts to
-            // nothing either way.
-            const shape =
-                position.shape === "keys-or-list" ?
-                    Array.isArray(value) && value.length ?
-                        "list"
-                    :   "keys"
-                :   position.shape;
+            const shape = position.shape;
             if (shape === "keys") {
                 if (value instanceof AddressEntries) return value;
                 if (Array.isArray(value) && value.length === 0) return value;
@@ -338,7 +397,6 @@ export function decodeNoteAddresses(fm, context) {
         const decoded = visit(fm, position.path);
         Object.assign(fm, decoded);
     }
-    return fm;
 }
 
 /**
@@ -378,11 +436,56 @@ export function noteAddressContext(config) {
  * {@link AddressLink} where it carries an anchor, before the declared
  * positions are read.
  *
+ * With a `source`, the record is a dependency's, read from its cached index.
+ * Every decode failure then leaves as a located finding that names the
+ * dependency, the cached file, the record, the field and the remedy, because
+ * the shape of a published index is the dependency's to correct and no note in
+ * the reading tree is at fault.
+ *
  * @param {object} record - The record.
  * @param {object} context - Builder defaults.
+ * @param {{package: string, file: string, line?: number}} [source] - The
+ *   dependency and the cached index file the record was read from, with the
+ *   record's 1-based line when known.
  * @returns {object} The typed record.
+ * @throws {Error} A located finding (`located: true`) when `source` is given
+ *   and the record cannot be decoded; otherwise the decode error itself.
  */
-export function decodeIndexAddresses(record, context) {
+export function decodeIndexAddresses(record, context, source) {
+    if (!source) return decodeIndexRecord(record, context);
+    try {
+        return decodeIndexRecord(record, context);
+    } catch (error) {
+        const field = error.keyPath?.join(".") ?? error.indexField;
+        const named = [record?.type, record?.shortcode].filter(Boolean).join(" ");
+        const detail = error.message.replace(/^Index /, "");
+        const error_ = new Error(
+            formatDiagnostic({
+                file: source.file,
+                ...(Number.isInteger(source.line) ? { line: source.line } : {}),
+                severity: "error",
+                message:
+                    `${source.package} published an index this package-build does not read` +
+                    (named ? ` (record ${named}` : " (record") +
+                    (field ? `, field ${field}` : "") +
+                    `): ${detail}. Take a release of ${source.package} built with this ` +
+                    `package-build, then run \`package-build deps fetch\` again.`,
+            }),
+            { cause: error },
+        );
+        error_.located = true;
+        throw error_;
+    }
+}
+
+/**
+ * Decode one index record's Address properties.
+ *
+ * @param {object} record - The record.
+ * @param {object} context - Builder defaults.
+ * @returns {object} The typed record.
+ */
+function decodeIndexRecord(record, context) {
     Object.assign(record, readPublishedAddresses(record));
     decodeNoteAddresses(record, context);
     const canonical = (value, keyPath) => {
@@ -402,8 +505,13 @@ export function decodeIndexAddresses(record, context) {
     if (record.address?.canonical != null)
         record.address.canonical = canonical(record.address.canonical, ["address", "canonical"]);
     for (const anchor of record.anchors ?? []) {
-        if (anchor.link != null && !(anchor.link instanceof AddressLink))
-            throw new Error(`Index anchor link is not an Address: ${JSON.stringify(anchor.link)}`);
+        if (anchor.link != null && !(anchor.link instanceof AddressLink)) {
+            const error = new Error(
+                `Index anchor link is not an Address: ${JSON.stringify(anchor.link)}`,
+            );
+            error.indexField = "anchors[].link";
+            throw error;
+        }
     }
     return record;
 }

package/engine/note-claims.mjs

@@ -87,12 +87,12 @@ import { assertSuppliedCorpus, parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only: this module is imported by the content index, so
 // importing the index back would close a cycle.
 import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
-import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES, currentType } from "./ids.mjs";
+import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE } from "./ids.mjs";
 import { itemTypes } from "./item-registry.mjs";
 import { docEntryTypes } from "./item-docs.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
-import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { locateFrontmatterKey } from "./diagnostics.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
 import {
     DEFAULT_DOCUMENT_SUBTYPES,
@@ -359,7 +359,7 @@ export const CLAIMABLE_DOCUMENT_TYPES = Object.freeze([
  * the answer is the type's full potential — every document such a note *could*
  * produce — which is what a caller asking about a type rather than a note wants.
  *
- * @param {string} type - The note's declared `type`, current spelling.
+ * @param {string} type - The note's declared `type`.
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {(() => boolean)|boolean} [opts.hasProse] - Whether *this note* carries
@@ -497,18 +497,14 @@ function article(word) {
  * @returns {string} The message.
  */
 function configurationMessage(type, config, sources) {
-    // Every table below is keyed by the current spelling of a note type; the
-    // message quotes the authored one, which is what the reader has in front of
-    // them.
-    const current = currentType(type);
     const documents = mappedDocuments(sources.maps, type);
-    if (!documents.length && sources.itemTypes.has(current)) documents.push("Item");
-    if (!documents.length && PACK_BY_TYPE[current]) documents.push(PACK_BY_TYPE[current].docType);
+    if (!documents.length && sources.itemTypes.has(type)) documents.push("Item");
+    if (!documents.length && PACK_BY_TYPE[type]) documents.push(PACK_BY_TYPE[type].docType);
 
     const systems = mappingSystems(sources.maps, type);
     const configured = new Set((config.packs ?? []).map((pack) => pack.type));
     const packless = documents.filter((document) => !configured.has(document));
-    const needsBuilder = documents.includes("Item") && !sources.itemTypes.has(current);
+    const needsBuilder = documents.includes("Item") && !sources.itemTypes.has(type);
 
     const into = documents.map((document) => `${article(document)} ${document}`).join(" or ");
     const becomes =
@@ -668,7 +664,7 @@ function packsServing(config, docType, system) {
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} absPath - The note's path, for the finding's position.
- * @param {string} type - The note's current type.
+ * @param {string} type - The note's type.
  * @param {object} config - The resolved build configuration.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per
@@ -708,12 +704,10 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
  * note's type and of a note's systems, and a note can fail either while passing
  * the other — see {@link discardedSystemBlockFindings}.
  *
- * Read-only: it walks the tree and reports, and writes nothing. Three kinds of
+ * Read-only: it walks the tree and reports, and writes nothing. Two kinds of
  * note are passed over, each for a stated reason rather than by omission — a
  * file with no frontmatter is not a note; a note with no `type:` is the
- * frontmatter linter's finding, which can say what a type is *for*; and a
- * retired type is answered by `assertTypeNotRetired` in `ids.mjs`, which names the
- * replacement.
+ * frontmatter linter's finding, which can say what a type is *for*.
  *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
@@ -755,24 +749,16 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         if (!type) continue;
         if (NEVER_PACKED_TYPES.has(type)) continue;
         if (DERIVED_PACKED_TYPES.has(type)) continue;
-        if (RETIRED_TYPES[type]) continue;
-        // A **renamed** spelling is a live type, not an unknown one: it resolves
-        // to the same row, the same registry entry and the same pack. So the
-        // claim is asked of the current spelling while the finding quotes the
-        // authored one. The rename itself is reported by the frontmatter
-        // lint, which can say what to write instead.
-        const current = currentType(type);
-
         // Asked first, and asked whatever the type's claim turns out to be: a
         // note whose documents all have packs may still carry a block none of
         // them reads, and that is invisible to every question below.
-        findings.push(...discardedSystemBlockFindings(fm, absPath, current, config));
+        findings.push(...discardedSystemBlockFindings(fm, absPath, type, config));
 
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
         // the half-claimed one — invisible while the question is only "is anything
         // claiming this note", because the answer there is yes.
-        const produces = documentClassesFor(current, resolved, {
+        const produces = documentClassesFor(type, resolved, {
             // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
             // go asks, so a tree with a JournalEntry pack — which is most of
             // them — reads no bodies at all.
@@ -824,9 +810,9 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
                 // nothing routes it, so the `vocabulary.has` branch would never
                 // reach it — and reading its absence as the reason is the
                 // inference {@link UNIMPLEMENTED_TYPES} exists to replace.
-                UNIMPLEMENTED_TYPES.has(current) ? specifiedMessage(type)
-                : vocabulary.has(current) ? configurationMessage(type, config, resolved)
-                : Object.hasOwn(NOTE_VOCABULARY, current) ? specifiedMessage(type)
+                UNIMPLEMENTED_TYPES.has(type) ? specifiedMessage(type)
+                : vocabulary.has(type) ? configurationMessage(type, config, resolved)
+                : Object.hasOwn(NOTE_VOCABULARY, type) ? specifiedMessage(type)
                 : authoringMessage(type),
         });
     }

package/engine/note-dates.mjs

@@ -430,9 +430,9 @@ export function parseNoteDate(value, options) {
             );
         }
         if (DOTLESS_TOKEN_PATTERN.test(trimmed)) {
-            // The message an author who learned a retired spelling meets. No
-            // table says which direction that spelling counted, so it states
-            // the rule rather than guessing a concrete replacement.
+            // A token with no dot names no era. Nothing says which direction
+            // a bare token would count, so the message states the rule rather
+            // than guessing a concrete replacement.
             return refuse(
                 `${subject} names no era — a reckoning is written ` +
                     `\`<calendar shortcode>.<era shortcode>\`: a year before ` +

package/engine/note-frontmatter.mjs

@@ -2,6 +2,12 @@
  * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
  * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
  *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 

package/engine/note-ids.mjs

@@ -14,13 +14,10 @@
 /**
  * The id a note's document is filed under, and the one rule that decides it.
  *
- * A note used to author its `id` — an opaque 16-character string, 6,343 of them
- * across the four content trees, each a *second* identity for a thing that
- * already had one. The note's canonical address (`sohl-none-miscgear-bowlcer`)
- * says everything the id said, is readable, and is the identity `content-lint`
- * already guards: a duplicate address is a build error, while a duplicate `id`
- * was checked nowhere. So the derived id inherits a guarantee, where the
- * authored one had none.
+ * A note's canonical address (`sohl-none-miscgear-bowlcer`) is the identity
+ * `content-lint` guards: a duplicate address is a build error. The id derived
+ * from it inherits that guarantee, and an authored `id` would be a second
+ * identity for a thing that already has one.
  *
  * **An authored `id` always wins.** That is the pattern the map compiler
  * already uses and documents — `regionDocId(sceneId, key, pinned)` returns
@@ -30,8 +27,7 @@
  * **This is one function because every pass must agree.** Half a dozen corpus
  * readers ask what a note's document id is — the pack passes, the wikilink
  * index, the content index, the Foundry-address pass, the address diff — and
- * they never see each other's answer. They agreed before because they all read
- * one authored field; they agree now because they all call this.
+ * they never see each other's answer. They agree because they all call this.
  *
  * `maps` and `pkg` are parameters with defaults rather than values resolved
  * inside, so a test can pose a package and a registry this toolchain does not
@@ -49,7 +45,7 @@ import { NOTE_SYSTEM } from "./systems.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 // The folder id's derivation, taken from the pass that owns it rather than
 // restated here — see the `folder` branch below. `folder-notes.mjs` reaches
-// only `content-address`, `address-charset`, `ids` and `retired-fields`, none
+// only `content-address`, `address-charset` and `ids`, none
 // of which reach this module, so the direction closes no cycle.
 import { FOLDER_TYPE, folderDocId } from "./folder-notes.mjs";
 
@@ -88,10 +84,8 @@ function text(value) {
  *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
- * and inventing an id for one would file it under nothing. Every caller already
- * had to handle an absent id (that is what the authored field's absence meant),
- * so this reports the same thing rather than throwing where a walk used to
- * skip; whether an id is *required* stays each pass's own decision
+ * and inventing an id for one would file it under nothing. This reports the
+ * absence rather than throwing, so a walk skips such a file; whether an id is *required* stays each pass's own decision
  * (`BasePackCompiler.requiresId`).
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.

package/engine/note-package.mjs

@@ -19,28 +19,11 @@
  * single-sourced in the repository that ships it — so the package is a property
  * of the *repository*, not of the note, and no note declares it.
  *
- * It is not a property of the note, and not a **selector**: as one, the compile loop
- * read `package:` out of frontmatter and skipped anything that did not match
- * the configured value. That is the defect this module exists to remove.
- * The skip was silent and it was bucketed as "belongs to another pass",
- * so a tree whose notes named a package no configuration answered to compiled
- * **zero notes and exited 0** — which is exactly the state the un-migrated
- * `hm-loc-*` / `hm-adv-*` repositories are in today.
- *
- * The field was retired in three steps, and all three have landed:
- *
- * 1. **Optional** (3.3.0). An absent `package:` was normal and a present one
- *    was accepted while it agreed. Non-breaking, so a consumer adopted it
- *    before changing a note.
- * 2. **Swept** out of every content tree on the org — 6,235 notes across
- *    `sohl`, `thalorna`, `kethira` and `harnensemble`.
- * 3. **Rejected outright**, as this major. A note declaring the field fails the
- *    build naming the file, whatever the value says.
- *
- * Step 3 is deliberately a rejection rather than continued tolerance: a field
- * accepted while it agrees is a field that grows back, one note at a time, and
- * every one of them is a line restating a constant the configuration already
- * carries. There is no value that makes writing it correct, so the diagnostic
+ * It is not a property of the note, and not a **selector**: a compile loop that
+ * skipped notes naming another package would compile zero notes and exit 0 on a
+ * tree whose notes named a package no configuration answered to. A note
+ * declaring the field fails the build naming the file, whatever the value
+ * says: there is no value that makes writing it correct, so the diagnostic
  * says what to write instead rather than which value to change.
  *
  * SQL queries can refer to the configured package. Search readers receive that
@@ -50,7 +33,7 @@
  */
 
 import { contentPackage } from "./content-package.mjs";
-import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { locateFrontmatterKey } from "./diagnostics.mjs";
 
 /**
  * A copy of frontmatter carrying the configured package for query evaluation.
@@ -67,7 +50,7 @@ export function searchableFrontmatter(fm, configured) {
  * Refuse a note that declares `package:` at all.
  *
  * Presence is the whole test — a declaration that *agrees* with the
- * configuration is as retired as one that disagrees, and an empty one
+ * configuration is refused like one that disagrees, and an empty one
  * (`package:`, which parses as `null`) is still the field.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
@@ -95,7 +78,7 @@ export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {})
         :   `\`package: ${declared}\``;
 
     const err = new Error(
-        `${wrote} is a retired frontmatter field — delete it` +
+        `${wrote} is not a frontmatter field — delete it` +
             (file ? ` — ${file}` : "") +
             `. A note's package is this repository's configured ` +
             `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +

package/engine/note-state.mjs

@@ -62,9 +62,7 @@ export const NOTE_STATES = Object.freeze(["stub", "draft", "full"]);
  * either state.
  *
  * An HTML comment is deliberately not empty. An invisible marker deciding
- * whether a page exists is the failure the retired `draft:` field was removed
- * for, and reintroducing it in comment form would be worse, because nothing
- * would report it.
+ * whether a page exists would be a failure nothing reports.
  *
  * @param {string|null|undefined} body - The note body, frontmatter stripped.
  * @returns {boolean} Whether the body is empty.