@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/note-claims.mjs

@@ -61,15 +61,21 @@
  * @module
  */
 
-import { walkMarkdownTree } from "./helpers.mjs";
-import { MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES } from "./ids.mjs";
+import { assertSuppliedCorpus } from "./helpers.mjs";
+// The record accessors only: this module is imported by the content index, so
+// importing the index back would close a cycle (#243).
+import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
+import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES, currentType } from "./ids.mjs";
 import { itemTypes } from "./item-registry.mjs";
 import { docEntryTypes } from "./item-docs.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
-import { SOHL_DOCUMENT_SUBTYPES } from "../sohl/document-subtypes.mjs";
+import { FOLDER_TYPE } from "./folder-notes.mjs";
+import { BUNDLE_TYPE } from "./bundle-notes.mjs";
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
 
 /**
  * Note types that compile into **no compendium document, by design**.
@@ -84,19 +90,54 @@ import { SOHL_DOCUMENT_SUBTYPES } from "../sohl/document-subtypes.mjs";
 export const NEVER_PACKED_TYPES = Object.freeze(new Set([HOMEPAGE_TYPE]));
 
 /**
- * The note-type → document-subtype maps this toolchain ships.
+ * Content types the specification states and this toolchain does not yet
+ * compile.
+ *
+ * **Stated, never inferred, and that distinction is the whole point.** An
+ * unimplemented type and a type somebody forgot to route look identical from
+ * the outside: both are documented, both validate, and neither reaches a pass.
+ * The only thing separating them is intent, so intent is written down here.
+ *
+ * Inferring it — "declared, but absent from the configured vocabulary" — reads
+ * correctly and is worthless, because the configured vocabulary is *derived
+ * from the routing*. Take a type's route away and it leaves the vocabulary too,
+ * so the inference excuses precisely the mistake it was meant to catch. That is
+ * not hypothetical: it is #241, where `place`, `lore` and `scenario` were
+ * declared, validated and unrouted, and every gate reported success until a
+ * downstream repository failed on 450 notes.
+ *
+ * A type leaves this set when it is implemented, the way `bundle` did in #259.
+ * The membership is asserted, so it cannot be forgotten in either direction.
  *
- * One today. `hm3/` is #139, and when it lands its map joins this list rather
- * than the claim table below growing a second copy of the same fact.
+ * @type {ReadonlySet<string>}
+ */
+export const UNIMPLEMENTED_TYPES = Object.freeze(new Set(["vehicle"]));
+
+/**
+ * Note types that reach a pack by a route **other than the pack router**.
+ *
+ * A folder is the only one, and it is not unclaimed: it compiles to a real
+ * `Folder` document. What it has no answer to is *which* pack claims it, because
+ * that is not a property of the note — a folder materialises in every pack
+ * holding a document that references it, and its ancestors with it (#257). So
+ * it is exempt from the claim check for the opposite reason a homepage is:
+ * a homepage is in no pack, and a folder may be in several.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const DERIVED_PACKED_TYPES = Object.freeze(new Set([FOLDER_TYPE]));
+
+/**
+ * The note-type → document-subtype maps this toolchain ships.
  *
- * `engine/` importing from `sohl/` is the arrangement `generate.mjs` already
- * has — its `COMPILERS` table names the SoHL compilers by class — and for the
- * same reason: the engine owns the *mechanism* that asks each system what it
- * compiles, and the systems own the answers.
+ * Declared in {@link module:engine/subtype-registry} and re-exported here,
+ * where it has always been read from. It moved to a leaf in #270 so that
+ * `helpers.mjs` could reach it: this module imports `walkMarkdownTree` from
+ * there, so a dependency the other way would have closed a cycle.
  *
  * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
  */
-export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([SOHL_DOCUMENT_SUBTYPES]);
+export { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 
 /**
  * What a claim question is asked against.
@@ -166,7 +207,10 @@ function mappingSystems(maps, type) {
  * pack from appearing to answer for any note.
  *
  * @param {string} docType - The Foundry document type a pack holds.
- * @param {ClaimSources} [sources] - What to answer from. Defaults to the
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once by the
+ *   compile and handed in — required, for the reason above (#243). Defaults to the
  *   configured registries and the systems this toolchain ships.
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
@@ -188,15 +232,21 @@ export function noteTypesClaimedBy(docType, sources) {
         // The actors pass: every note type a system sends to an `Actor`.
         case "Actor":
             return Object.freeze(new Set(maps.flatMap((map) => noteTypesFor(map, "Actor"))));
-        // The journals pass: free prose, plus every doc-carrying type — an
-        // item's, a macro's and a map note's description each compile into a
-        // JournalEntry of their own.
+        // The journals pass: every type whose whole document is a journal,
+        // plus every doc-carrying type — an item's, a macro's and a map note's
+        // description each compile into a JournalEntry of their own.
         case "JournalEntry":
-            return Object.freeze(new Set(["doc", ...docs]));
+            return Object.freeze(new Set([...JOURNAL_TYPES, ...docs]));
         case "Macro":
             return Object.freeze(new Set(["macro"]));
         case "Scene":
             return Object.freeze(new Set(MAP_TYPES));
+        // The bundles pass: an Adventure is what a `bundle` note compiles into
+        // (#259). A **prebuilt** Adventure pack still claims nothing —
+        // {@link claimedNoteTypes} passes over it, because no note is routed
+        // into a pack whose JSON is checked in rather than compiled.
+        case "Adventure":
+            return Object.freeze(new Set([BUNDLE_TYPE]));
         default:
             return Object.freeze(new Set());
     }
@@ -209,14 +259,27 @@ export function noteTypesClaimedBy(docType, sources) {
  * is claimed — which is what keeps a type deliberately unmapped for one system,
  * and claimed for another, silent (#79).
  *
+ * **A prebuilt pack claims nothing.** Its per-document JSON is checked in
+ * rather than compiled, so it has no pass and no note is routed into one —
+ * which `content-config.mjs` already states by refusing `default: true`
+ * alongside `prebuilt`. Counting it would tell an author their note is claimed
+ * by a pack that will never look at it. Before #259 the point could not arise:
+ * the only prebuilt pack in the wild is `harn-adventures`'s Adventure pack, and
+ * no compiler was registered for that document type, so the row answered for
+ * nothing whatever it was asked. Now one is.
+ *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once by the
+ *   compile and handed in — required, for the reason above (#243).
  * @returns {ReadonlySet<string>} The claimed note types.
  */
 export function claimedNoteTypes(config = loadPackConfig(), sources) {
     const claimed = new Set();
     for (const pack of config.packs ?? []) {
+        if (pack.prebuilt) continue;
         for (const type of noteTypesClaimedBy(pack.type, sources)) claimed.add(type);
     }
     return Object.freeze(claimed);
@@ -232,6 +295,9 @@ export function claimedNoteTypes(config = loadPackConfig(), sources) {
  * declare on top.
  *
  * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once by the
+ *   compile and handed in — required, for the reason above (#243).
  * @returns {ReadonlySet<string>} The vocabulary.
  */
 export function noteTypeVocabulary(sources) {
@@ -284,14 +350,18 @@ 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 (#78).
+    const current = currentType(type);
     const documents = mappedDocuments(sources.maps, type);
-    if (!documents.length && sources.itemTypes.has(type)) documents.push("Item");
-    if (!documents.length && PACK_BY_TYPE[type]) documents.push(PACK_BY_TYPE[type].docType);
+    if (!documents.length && sources.itemTypes.has(current)) documents.push("Item");
+    if (!documents.length && PACK_BY_TYPE[current]) documents.push(PACK_BY_TYPE[current].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(type);
+    const needsBuilder = documents.includes("Item") && !sources.itemTypes.has(current);
 
     const into = documents.map((document) => `${article(document)} ${document}`).join(" or ");
     const becomes =
@@ -322,6 +392,32 @@ function configurationMessage(type, config, sources) {
     );
 }
 
+/**
+ * The **specification** finding: the format states the type, nothing compiles it.
+ *
+ * A third thing that can be wrong, and the only one that is not the author's
+ * fault. `docs/content-format.md` documents the type and the vocabulary declares
+ * its properties, so a note written against the published specification is
+ * correct — this toolchain simply has not implemented it yet.
+ *
+ * It earns its own message because the other two would both mislead here.
+ * Naming a missing pack or registry sends an author to
+ * `package-build.config.yaml`, where nothing they can write will help; saying
+ * the type is unknown flatly contradicts the specification they read it in.
+ *
+ * @param {string} type - The note's declared `type`.
+ * @returns {string} The message.
+ */
+function specifiedMessage(type) {
+    return (
+        `no configured pack claims a note of type "${type}", so it compiles ` +
+        `into nothing. The content format specifies "${type}", so the note is ` +
+        `not wrong — this toolchain has not implemented the type yet. Nothing ` +
+        `in this repository's configuration will change that; do not author ` +
+        `the type until a release compiles it.`
+    );
+}
+
 /**
  * The **authoring** finding: nothing anywhere knows the type.
  *
@@ -351,22 +447,41 @@ function authoringMessage(type) {
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once by the
+ *   compile and handed in — required, for the reason above (#243).
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
-export function unclaimedNoteFindings(config = loadPackConfig(), sources) {
+export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
     const resolved = resolveSources(sources);
     const claimed = claimedNoteTypes(config, resolved);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
 
-    for (const { frontmatter: fm, absPath } of walkMarkdownTree(config.paths.content)) {
+    // The corpus this compile derived once (#243), required rather than
+    // derived here: this module is imported *by* the content index, so it
+    // could not derive one without closing a cycle — and the caller that wants
+    // this answer is running a compile and already holds it.
+    assertSuppliedCorpus(records, "unclaimedNoteFindings");
+
+    for (const record of records) {
+        if (!isNoteRecord(record)) continue;
+        const fm = authoredFrontmatter(record);
+        const absPath = noteFile(config.paths.content, record);
         if (!fm) continue;
         const type = typeof fm.type === "string" ? fm.type.trim() : "";
         if (!type) continue;
         if (NEVER_PACKED_TYPES.has(type)) continue;
+        if (DERIVED_PACKED_TYPES.has(type)) continue;
         if (RETIRED_TYPES[type]) continue;
-        if (claimed.has(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 (#78). The rename itself is reported by the frontmatter
+        // lint, which can say what to write instead.
+        const current = currentType(type);
+        if (claimed.has(current)) continue;
 
         findings.push({
             file: absPath,
@@ -374,9 +489,15 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources) {
             severity: /** @type {"error"} */ ("error"),
             type,
             message:
-                vocabulary.has(type) ?
-                    configurationMessage(type, config, resolved)
-                :   authoringMessage(type),
+                // The unimplemented set is asked *first*: such a type is
+                // absent from the configured vocabulary precisely because
+                // 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)
+                : authoringMessage(type),
         });
     }
     return findings;

package/engine/note-ids.mjs

@@ -0,0 +1,112 @@
+/*
+ * 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
+ */
+
+/**
+ * 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 (#270).
+ *
+ * **An authored `id` always wins.** That is the pattern the map compiler
+ * already uses and documents — `regionDocId(sceneId, key, pinned)` returns
+ * `pinned || makeId(…)` — and it is the correction lever an author needs when a
+ * document must keep its identity across a shortcode rename.
+ *
+ * **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.
+ *
+ * `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
+ * ship without a configuration on disk.
+ *
+ * @module
+ */
+
+import { documentId } from "./content-address.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { contentPackage } from "./content-package.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+
+/**
+ * A frontmatter value read as a non-blank string, or `undefined`.
+ *
+ * A blank `id:` is not a pin. It is an author who deleted the value and left
+ * the key, and treating `""` as pinned would file the document under the empty
+ * string — which the LevelDB packer reports only as an opaque key collision.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {string|undefined} The trimmed value, or `undefined` when blank.
+ */
+function text(value) {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+
+/**
+ * The document id a note compiles under: its pin, or its address.
+ *
+ * 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
+ * (`BasePackCompiler.requiresId`).
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {object} [opts]
+ * @param {string} [opts.pkg] - The owning content package. Defaults to the
+ *   configured one, which is the only package a tree's notes belong to (#56).
+ * @param {readonly object[]} [opts.maps] - The document-subtype maps, which
+ *   decide the address's `<system>` segment.
+ * @returns {string|undefined} The document's `_id`, or `undefined` when the
+ *   note has no address to derive one from.
+ */
+export function noteDocId(fm, { pkg, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS } = {}) {
+    if (!fm || typeof fm !== "object") return undefined;
+    const pinned = text(fm.id);
+    if (pinned) return pinned;
+    const type = text(fm.type);
+    const shortcode = text(fm.shortcode);
+    if (!type || !shortcode) return undefined;
+    return documentId(pkg ?? contentPackage(), systemOf(type, maps), type, shortcode);
+}
+
+/**
+ * Fill a note's `id` in place, so everything downstream reads one value.
+ *
+ * The corpus readers each hold their own parsed frontmatter and each ask for
+ * `fm.id` in several places; normalising the field once, where the note is
+ * read, is what makes "the id is derived" true for all of them rather than for
+ * whichever ones remembered to derive it. Idempotent, and a no-op for a note
+ * that authored an id or has no address.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, mutated in place.
+ * @param {object} [opts] - As {@link noteDocId}.
+ * @returns {object|null|undefined} `fm`, for chaining.
+ */
+export function resolveNoteId(fm, opts) {
+    if (!fm || typeof fm !== "object") return fm;
+    const id = noteDocId(fm, opts);
+    if (id) fm.id = id;
+    return fm;
+}

package/engine/note-renames.mjs

@@ -0,0 +1,134 @@
+/*
+ * 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
+ */
+
+/**
+ * The shortcodes a note declares it used to be published under (#278).
+ *
+ * A package's `(type, shortcode)` addresses are a published interface, and
+ * `addresses diff` reports what a build stopped publishing — telling a
+ * **rename** from a **withdrawal** by matching document ids across two
+ * releases. #270 removed the property that rested on. An id is now derived from
+ * the canonical address, which carries the shortcode, so renaming a shortcode
+ * moves the id too: both sides of the join move together, the match finds
+ * nothing, and a rename is reported as a withdrawal with no successor named.
+ *
+ * **The remaining lever needed foresight, which is the wrong thing to ask for.**
+ * An authored `id:` still wins, and pinning one does keep a document's identity
+ * across a rename — but it has to be written *before* the rename, by an author
+ * who does not yet know they will make one. An author who has just renamed a
+ * shortcode knows exactly what the old one was, and that is the only moment
+ * anyone does.
+ *
+ * So a note states it:
+ *
+ * ```yaml
+ * type: weapongear
+ * shortcode: Taburi
+ * renamedFrom: Tabri
+ * ```
+ *
+ * **A declaration is an assertion, not a match, and the diagnostic says which
+ * it had.** That distinction is the whole ethos of `address-diff.mjs`: it
+ * refuses to guess a successor from a similar-looking string, because a wrong
+ * one sends the reader to the wrong fix. An author's declaration is neither a
+ * guess nor an identity match — it is testimony from the one party that knows —
+ * so it is used, attributed, and never silently blended with an id match.
+ *
+ * **It is a list, because renames chain.** The diff is release-to-release and a
+ * shortcode may be renamed more than once between two releases; a baseline
+ * several releases back published a name two renames ago. A single value would
+ * report that as a withdrawal again, which is the bug this closes.
+ *
+ * **It is transient.** Once every baseline a build is compared against post-dates
+ * the rename, the declaration has nothing left to say and may be deleted. That
+ * is the difference from an `id:` pin, which is permanent, opaque, and a second
+ * identity for a thing that already has one (#270).
+ *
+ * **It is one key per note, at the top level, however many systems the note
+ * compiles into.** A shortcode is the note's, not a system block's: a note
+ * carrying `sohl:` and `hm3:` blocks compiles into two documents that share one
+ * shortcode, so a rename moves both and one declaration covers both.
+ *
+ * This module reads the key and says nothing about whether the values are
+ * *sound* — that a value is a well-formed shortcode, is not the note's own, and
+ * does not name an address some live note still publishes are cross-note
+ * questions, and `engine/content-lint.mjs` owns them. Composing a value into an
+ * address key is likewise not here: the diff defines that space and spells the
+ * key once, in `engine/address-diff.mjs`.
+ *
+ * @module
+ */
+
+/**
+ * The `renamedFrom:` entries a note authors, exactly as authored.
+ *
+ * Scalar or list, because one predecessor is the overwhelmingly common case and
+ * requiring `- ` on it would be friction with nothing behind it; both normalize
+ * here so no reader has to ask which form it got.
+ *
+ * Entries are returned **unvalidated** — a number, a nested list, a blank
+ * string all come back as they were written. The lint needs to see them to
+ * report them, and a reader that quietly dropped them would report a correct
+ * tree clean while a typo silently did nothing.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {readonly unknown[]} The authored entries, in authored order; empty
+ *   when the note declares none.
+ */
+export function renamedFromEntries(fm) {
+    if (!fm || typeof fm !== "object") return [];
+    const raw = /** @type {{renamedFrom?: unknown}} */ (fm).renamedFrom;
+    if (raw == null) return [];
+    return Array.isArray(raw) ? raw : [raw];
+}
+
+/**
+ * The well-formed shortcodes among a note's `renamedFrom:` entries.
+ *
+ * Trimmed, de-duplicated, and in authored order. Anything that is not a
+ * non-blank string is skipped rather than coerced: it is reported by the lint,
+ * and a diff that guessed at what a number meant would claim a rename nobody
+ * declared.
+ *
+ * De-duplicating here rather than leaving it to callers is not tidiness — the
+ * predecessor index is a map, so a repeated entry would otherwise be indexed
+ * twice and the second write would look like a conflicting claim.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {string[]} The declared predecessor shortcodes.
+ */
+export function renamedFrom(fm) {
+    const seen = new Set();
+    for (const entry of renamedFromEntries(fm)) {
+        if (typeof entry !== "string") continue;
+        const trimmed = entry.trim();
+        if (trimmed) seen.add(trimmed);
+    }
+    return [...seen];
+}
+
+/**
+ * Whether a note declares the key at all, however malformed its value.
+ *
+ * Separate from {@link renamedFrom} returning nothing, because the two mean
+ * opposite things to a lint: a note declaring no key is silent and correct,
+ * while one declaring `renamedFrom: []` — or a single blank string — has said
+ * something that does nothing, which is worth a word.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} `true` when the key is present and not null.
+ */
+export function declaresRenamedFrom(fm) {
+    if (!fm || typeof fm !== "object") return false;
+    return /** @type {{renamedFrom?: unknown}} */ (fm).renamedFrom != null;
+}

package/engine/note-schemas.mjs

@@ -73,6 +73,29 @@ const JOURNAL_ONLY_FIELDS = Object.freeze([]);
  */
 const ARMORLOCATION_FIELDS = Object.freeze([]);
 
+/**
+ * A `bundle` note — a set of documents taken as a unit, Foundry's `Adventure`.
+ *
+ * Like a folder, it declares no system-block fields: everything it says is a
+ * `data` property. Its `system` names which system's documents it may hold
+ * rather than which system it belongs to, so the note itself is system-neutral.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+const BUNDLE_FIELDS = Object.freeze([]);
+
+/**
+ * A `folder` note — Foundry's `Folder`, the grouping documents are filed in.
+ *
+ * Empty for the same reason a bundle's is: a folder declares no system-block
+ * fields, because a `Folder` is a core Foundry document rather than any
+ * system's. Its two properties — `parent` and `color` — are `data:` keys, held
+ * closed by `engine/note-vocabulary.mjs` (#256).
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+const FOLDER_FIELDS = Object.freeze([]);
+
 /**
  * Every engine-level content type, and what a note of that type may write.
  *
@@ -84,4 +107,6 @@ export const ENGINE_NOTE_SCHEMAS = Object.freeze({
     lore: JOURNAL_ONLY_FIELDS,
     scenario: JOURNAL_ONLY_FIELDS,
     armorlocation: ARMORLOCATION_FIELDS,
+    bundle: BUNDLE_FIELDS,
+    folder: FOLDER_FIELDS,
 });