@heroiclands/package-build 22.5.0 → 22.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @heroiclands/package-build
 
+## 22.6.0
+
+### Minor Changes
+
+**Compendium content**
+
+- A person or thing with no game-system data no longer becomes a blank
+  compendium entry — the note still publishes its page and its journal, so
+  somebody can be written without being statted.
+- A package carrying data for a game system it ships no compendium for is now
+  told so, rather than having it quietly dropped.
+
+## 22.5.1
+
+### Patch Changes
+
+**Unwritten notes**
+
+- A note left unwritten builds: an empty body no longer stops a package
+  compiling its packs.
+- An unwritten note offers no compendium link, so nothing sends a reader to a
+  journal that was never made.
+
 ## 22.5.0
 
 ### Minor Changes

package/CONTENT.md

@@ -867,7 +867,12 @@ has no art.
 A note is **system-agnostic**. The only system-specific things it carries are
 the properties named after a system, and one note may carry more than one — a
 `being` in `harn-ensemble` compiles into a SoHL `being` _and_ an HM3
-`character`. Within a system's block:
+`character`.
+
+**The block is what makes a game document.** A note carrying none produces no
+Actor and no Item at all, in any package; its prose still compiles into a page,
+a PDF page and a JournalEntry, so a person can be written without being statted.
+Within a system's block:
 
 | property           | maps to                                                       |
 | ------------------ | ------------------------------------------------------------- |
@@ -1006,12 +1011,19 @@ hold this package at a build that does not write it. A subtree the schema
 declares but describes no further — a discriminated `TypedSchemaField`, stored
 flat — is left alone rather than reported wholesale.
 
-**A pack that declares a `system:` takes only notes carrying that block.** A
-note that says nothing about a system has no system data, and compiling it there
-would emit a hollow document — a subtype, and none of the fields the subtype
-exists for. The build fails naming the note and the pack. A pack declaring no
-system constrains nothing, and a pass whose document is not system data at all —
-journals, macros, scenes — is not subject to the rule.
+**An Actor or Item pass takes only notes carrying the block it reads.** A note
+that says nothing about a system has no system data, and compiling it would emit
+a hollow document — a subtype, and none of the fields the subtype exists for. So
+a note carrying no block for any system produces no Actor and no Item anywhere,
+and is passed over in silence; its prose still compiles into a page, a PDF page
+and a JournalEntry. The question is asked of the pass's own system rather than
+of the pack's `system:`: a pack declaring none is compiled by the fallback pass,
+which reads one block like any other. A pass whose document is not system data
+at all — journals, macros, scenes — is not subject to the rule.
+
+**A block for a system no pack of the class compiles is an error**, reported
+once per note per system with the position of the block key, because the
+authored data is discarded either way.
 
 **`(type, shortcode)` resolves inside one system's catalogue.** A being names its
 embedded items by address and never by pack, so the Item packs are read as one
@@ -1096,11 +1108,17 @@ was never the key count.)
 ### An empty body is a stub, on purpose
 
 A note whose body is empty is a **stub**: it carries its frontmatter into the
-content index and is queryable there, it keeps its `id` and the Foundry document
-its type compiles, and it publishes no page, no address and no link target. A
-note with a body and the `draft` tag is a **draft**, and one with a body and no
-tag is **full**. `docs/content-format.md` states the rule; this is what the lint
-does with it.
+content index and is queryable there, it keeps its `id`, and it publishes no
+page, no address and no link target. A note with a body and the `draft` tag is a
+**draft**, and one with a body and no tag is **full**.
+`docs/content-format.md` states the rule; this is what the lint does with it.
+
+**A document that would be empty is not created**, and the index then names no
+artefact — `uuid`, `path` and `address` are `null`. An unwritten note still
+compiles every document derived from `data:`, so an arcane talent is still its
+Item; what it compiles no journal for is its prose, because there is none. An
+infobox does not count as content: the panel renders `data:` the index already
+carries.
 
 Four findings and two reports:
 

package/docs/api.md

@@ -416,15 +416,16 @@ Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book.
 
 The three states of a note — **stub**, **draft**, **full** — and the one observable fact they rest on. A note whose body is empty is a stub: it carries its facts into the index and is queryable there, and it has no page, no address and no link target. Nothing is stored: the ladder is derived once in the SQL `entries` view and no note can assert its own state.
 
-| Export                | Signature                                   | Returns                                 | Use it when                                                                                                 |
-| --------------------- | ------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                     |
-| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                    |
-| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` are structural and exempt |
-| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                    |
-| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                              |
-| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub     |
-| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting the prose a reader meets, with a wikilink counting as the one word it renders                      |
+| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                |
+| --------------------- | ------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                    |
+| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                   |
+| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` are structural and exempt                |
+| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                   |
+| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
+| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
+| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting the prose a reader meets, with a wikilink counting as the one word it renders                                     |
 
 ### `engine.stubLint`
 
@@ -626,6 +627,8 @@ Which note-type → document-subtype maps this toolchain ships, and the two ques
 | `KNOWN_DOCUMENT_SUBTYPE_MAPS` | `const KNOWN_DOCUMENT_SUBTYPE_MAPS`      | —                                                                                                                                 | The note-type → document-subtype maps this toolchain ships.                                                                            |
 | `ACTOR_TYPES`                 | `const ACTOR_TYPES`                      | —                                                                                                                                 | Every note type any shipped map compiles into an **Actor**.                                                                            |
 | `DEFAULT_DOCUMENT_SUBTYPES`   | `const DEFAULT_DOCUMENT_SUBTYPES`        | —                                                                                                                                 | The map a pack declaring no `system:` compiles its documents against.                                                                  |
+| `SHIPPED_SYSTEMS`             | `const SHIPPED_SYSTEMS`                  | —                                                                                                                                 | Every system this toolchain ships a map for, by id.                                                                                    |
+| `SYSTEM_DOCUMENT_CLASSES`     | `const SYSTEM_DOCUMENT_CLASSES`          | —                                                                                                                                 | The Foundry document classes a system compiles its own data into.                                                                      |
 | `subtypeMapFor`               | `function subtypeMapFor(system)`         | {import("./document-subtypes.mjs").DocumentSubtypeMap\|undefined} Its map, or `undefined` where this toolchain ships none for it. | The map one system ships, by its id.                                                                                                   |
 | `schemaSubtypeOf`             | `function schemaSubtypeOf(system, type)` | {string} The document subtype to look up.                                                                                         | The document subtype a note type compiles into for one system — the translation the _schema_ check needs, and the reason it needs one. |
 
@@ -1196,6 +1199,7 @@ Pack JSON generation — in-repo Markdown → per-entry JSON (build-only). Reads
 
 | Export                        | Signature                                               | Returns                                                                                                                                                                                                         | Use it when                                                                                                         |
 | ----------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `systemCompilers`             | `function systemCompilers(passes)`                      | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                                                               | The system-specific compilers, derived from the passes themselves.                                                  |
 | `compilerFor`                 | `function compilerFor(docType, system`                  | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past.                                            | The compiler class a pack of one document type and one system gets.                                                 |
 | `emittedArtFor`               | `function emittedArtFor(type)`                          | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made — a retired type, which is reported as retired instead. | The art fields a note of one content type reaches its document through, and the document it reaches.                |
 | `packJsonDir`                 | `const packJsonDir`                                     | {string} The pack's JSON directory.                                                                                                                                                                             | Root of the build-only JSON tree for one pack.                                                                      |

package/docs/content-format.md

@@ -197,13 +197,14 @@ _Not available_ on every affiliation page would suggest a gap in the note when
 the truth is about the system's scope.
 
 Whether a document was produced is the compile's own answer rather than a
-reading of the frontmatter. The note's type must map to the system; the note
-must route to a pack of the document class that map names; and where **that
-pack declares a `system:`**, the note must carry that system's block, which is
-the same rule the pack itself compiles under. A pack declaring **no** system
-compiles every note it claims from `data:` and the field defaults, so a note
-with no block still produces a document and its box still carries content —
-which is the ordinary arrangement in a package built for one system.
+reading of the frontmatter. Three things must hold: the note must carry that
+system's block, its type must map to the system, and it must route to a pack of
+the document class that map names. The block is the first of them because a
+system block is what makes a game document — see
+[A system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
+A pack declaring **no** system is compiled by the fallback pass, which reads one
+system's block and no other, so the question is the same one whether or not the
+pack answered it.
 
 #### Four section layouts
 
@@ -788,8 +789,9 @@ _compendium_ receives its document.
 — an item's prose compiling into a `JournalEntry` of its own — is not what the
 author was addressing, and is routed by the pass that produces it.
 
-**`<system>.pack` overrides it for one system.** A note that compiles into two
-systems can send each document to its own pack:
+**`<system>.pack` names the pack for one system's document.** Routing is per
+system: each block the note carries sends its own document where that block
+says, and a note carrying two blocks may place them in two packs.
 
 ```yaml
 pack: items-sohl
@@ -797,9 +799,22 @@ hm3:
   pack: items-hm3
 ```
 
-**Unstated, the document goes to the pack of its type marked `default: true`.**
-Where no pack of that type is the default, the build refuses rather than
-guessing, and names the candidates.
+**Unstated, a system's document goes to that system's default pack of its
+class** — the pack of the class declaring that `system:`, or, where none does,
+the pack of the class marked `default: true`. Where nothing answers, the build
+refuses rather than guessing, and names the candidates.
+
+**`pack` and `packFolder` are different questions.** `pack` names _which
+compendium_ receives a document; `packFolder` names the folder note whose
+address the document is filed under _within_ whichever compendium that is. They
+compose, and both are read per system, so a note may place its two systems'
+documents in different packs and different folders:
+
+```yaml
+sohl:
+  pack: characteristics
+  packFolder: miscgear
+```
 
 **`pack: none` compiles the note into no document.** The note is walked,
 published as a page, present in the content index with an address and no
@@ -1662,11 +1677,15 @@ convention rather than declared in a field — see
 A note has three states, and two of them are nothing but conventions the format
 already carried.
 
-| State     | Body    | Marker          | Page        | Document                         | Link target |
-| --------- | ------- | --------------- | ----------- | -------------------------------- | ----------- |
-| **stub**  | empty   | none            | no          | yes, where its type compiles one | no          |
-| **draft** | written | `tags: [draft]` | yes, marked | yes                              | yes         |
-| **full**  | written | none            | yes         | yes                              | yes         |
+| State     | Body    | Marker          | Page        | Document                          | Link target |
+| --------- | ------- | --------------- | ----------- | --------------------------------- | ----------- |
+| **stub**  | empty   | none            | no          | yes, where one would not be empty | no          |
+| **draft** | written | `tags: [draft]` | yes, marked | yes                               | yes         |
+| **full**  | written | none            | yes         | yes                               | yes         |
+
+"Document" here is the document a note's frontmatter earns. A system's Actor or
+Item is earned by that system's block, in every state —
+[a system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
 
 **Full is the absence of everything.** It is the default and carries no marker,
 which is right: the overwhelming majority of a finished corpus should say
@@ -1706,10 +1725,35 @@ column a table renderer already reads.
 It keeps everything else:
 
 - **`file`**, which is what you edit and what every diagnostic names.
-- **`id` and `foundry`**, because a **document is derived from `data:`, not from
-  prose**. An unwritten arcane talent still compiles into its Item, and its
-  documentation journal is still a document in its own right. **The empty body
-  suppresses the page, never the document.**
+- **`id`**, which is the identity every diagnostic and every table reads.
+- **`foundry`**, naming each document that was made.
+
+#### A document that would be empty is not created
+
+> **If the resulting document would be empty, it is not created** — and the
+> index then names no artefact: `uuid`, `path` and `address` are `null`, which
+> is how a record says one was not made.
+
+The test is about the **output**, which is what lets one rule cover every case:
+
+| The note                           | The document                           | Made? |
+| ---------------------------------- | -------------------------------------- | ----- |
+| `place`, `lore`, `doc`, `scenario` | its JournalEntry, which _is_ the prose | no    |
+| any item type, `macro`             | the Item or Macro, from `data:`        | yes   |
+| the same note's documentation      | a JournalEntry of the same prose       | no    |
+| `map`                              | the Scene, from `data:`                | yes   |
+
+An unwritten arcane talent still compiles into its Item, because an Item is its
+`data:` and that is not empty. What it has no documentation journal for is the
+same thing an unwritten `place` has no journal for: there is nothing to put in
+one.
+
+**An infobox does not count as content.** The panel is a rendering of `data:`
+that the index already publishes, so an entry holding nothing else would tell a
+reader exactly what the record told them.
+
+Nothing anywhere names a document that was not made: a compendium UUID for one
+would send every consumer that resolves it to a document the pack does not hold.
 
 What is suppressed with the page is the web address and the link target: a
 wikilink into a stub is refused, and a table cell listing one prints its name as
@@ -1738,8 +1782,8 @@ cannot be is the target of a wikilink, because a wikilink points at a page.
 
 Note types fall into two groups, and only the first has a mapping table.
 
-**Types producing a system document** — a SoHL or HM3 Actor or Item, one per
-system, described by the tables further down.
+**Types that _may_ produce a system document** — a SoHL or HM3 Actor or Item,
+one per system, described by the tables further down.
 
 **Types producing only a core document** — `lore`, `place`, `scenario`, `doc`,
 `map`, `macro` and `homepage`. A core document is one Foundry defines rather than
@@ -1755,6 +1799,54 @@ having nothing worth summarising.
 Every note in **both** groups still produces its JournalEntry and its web page.
 The difference is only whether a system Actor or Item is created as well.
 
+#### A system block is what makes a game document
+
+> **A note produces a system's Actor or Item only where it carries that
+> system's block.** A note carrying no block for any system produces no Actor
+> and no Item anywhere, whatever its packs declare.
+
+The block is not a place to put optional detail — it is the statement that this
+person or thing is meant to be played. Its absence is a statement too, and it is
+made silently: the note is passed over by the Actor and Item passes exactly as
+any note they do not own, with no finding.
+
+**Prose is untouched by this.** A body with content still compiles into one
+JournalEntry, one web page and one PDF page, however many blocks the note
+carries and whether or not it carries any; an empty body still compiles none of
+the three. So a note has three states, and each reaches the next by one edit in
+one file, with its address, its id, its index record and every link into it
+unchanged:
+
+| The note carries           | Produces                                       |
+| -------------------------- | ---------------------------------------------- |
+| no block, empty body       | an index record — a name that can be queried   |
+| no block, a written body   | a page, a PDF page and a JournalEntry          |
+| a block, a written body    | all of those, plus that system's Actor or Item |
+| two blocks, a written body | one document per system, and one of each other |
+
+Write the person; add a system block when someone will need a token. A setting's
+cast is mostly people nobody rolls dice against, and a note about one of them
+carries no block and occupies no slot in a compendium a referee browses.
+
+**A note carrying no document publishes no UUID for one.** Its address, its
+page and its documentation journal are published as they are for any other note,
+and the `foundry` entry that would name an Actor or an Item is absent — the same
+statement [`pack: none`](#the-pack-a-note-compiles-into) makes about a pack,
+made about a system.
+
+**A block for a system this package ships no pack for is an error.** The
+authored data would be discarded either way, so the build says so, once per note
+per system, naming the system and the document class:
+
+```
+assets/content/People/Aelric.md:7:1: error: carries a `hm3:` block, and no Actor pack in this package compiles hm3 documents, so the block is discarded — declare `system: hm3` on one of the `packs:`, or remove the block.
+```
+
+A pack declaring no `system:` is compiled by the fallback pass, which reads one
+system's block — so a systemless Actor pack serves that system and not every
+system a note might write. A package shipping for a second system declares
+`system:` on a pack of each class it compiles.
+
 That includes actors. A being producing its Actor and nothing else would be
 the one system-bearing note with no address at `none`, leaving a prose link
 naming it nowhere to land. It carries a documentation journal like every other

package/engine/actor-compiler.mjs

@@ -501,6 +501,18 @@ export class SystemActorCompiler extends BasePackCompiler {
      */
     static requiresSystemBlock = true;
 
+    /**
+     * The Foundry document class this pass writes.
+     *
+     * Declared by the class that does the writing, so the table pairing a
+     * system with its passes is derived from the passes themselves rather than
+     * written out a second time — see
+     * {@link module:engine/generate.systemCompilers}.
+     *
+     * @type {string}
+     */
+    static documentClass = "Actor";
+
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

package/engine/base-compiler.mjs

@@ -183,13 +183,16 @@ export class BasePackCompiler {
 
     /**
      * Whether this pass's document **is** a system's data, and therefore takes
-     * only notes that carry that system's block.
+     * only notes that carry the block this pass reads.
      *
-     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
-     * and an `actors-sohl` from one tree — and the note-side half of that is
-     * the block named after the system. A note carrying no such block has
-     * nothing to say about it, so compiling it there would emit a **hollow
-     * document**: a subtype, and none of the fields the subtype exists for.
+     * The question is asked of {@link BasePackCompiler#system} — the pass's own
+     * system, which an Actor or Item pass always has — rather than of the
+     * pack's `system:`, which a pack need not declare. A note carrying no such
+     * block has nothing to say about that system, so compiling it would emit a
+     * **hollow document**: a subtype, and none of the fields the subtype exists
+     * for. `harn-ensemble` ships an `actors-hm3` and an `actors-sohl` from one
+     * tree, and `sohl-thalorna` ships one `actors` declaring nothing; the rule
+     * is the same in both, because it is the pass that reads a block.
      *
      * False by default, because most passes write documents that are not
      * system data at all. A JournalEntry of prose is the same document under
@@ -428,44 +431,56 @@ export class BasePackCompiler {
         );
     }
 
+    /**
+     * The system block this pass reads, where it reads one.
+     *
+     * `undefined` on the base class, because most passes read none: a
+     * JournalEntry, a Macro, a Scene and an Adventure are Foundry's documents
+     * rather than any system's. The Actor and Item passes answer with the
+     * block their {@link SystemActorCompiler.documentSubtypes} names, which is
+     * the same declaration that says which notes they claim and what each
+     * becomes.
+     *
+     * Stated here so {@link BasePackCompiler#eligibleFor} is total: a pass
+     * declaring `requiresSystemBlock` without a system reads no block, and a
+     * note can carry nothing for it.
+     *
+     * @returns {string|undefined} The block key, or `undefined`.
+     */
+    get system() {
+        return undefined;
+    }
+
     /**
      * Whether a claimed, routed note may become this pack's document at all.
      *
-     * The pack-eligibility gate, and it fails rather than skipping: a note that
-     * routed *here* and carries nothing for this pack's system is an authoring
-     * mistake with a hollow document at the end of it, not a note that belongs
-     * to another pass. Skipping it quietly is how a whole tree compiles to
-     * documents nobody can use.
+     * **A system block is what makes a game document.** A pass whose document
+     * *is* a system's data compiles a note only where the note carries the
+     * block that pass reads, so a note saying nothing about any system becomes
+     * no Actor and no Item anywhere — its prose still compiles into a page, a
+     * PDF leaf and a JournalEntry, which are documents no system defines.
+     *
+     * Asked of this pass's own {@link BasePackCompiler#system}, never of the
+     * pack's `system:`. A pack declaring none is a single-system convenience
+     * compiled by the fallback pass for its document type, and that pass still
+     * reads exactly one block — so the note-side question is the same one
+     * whether or not the pack answered it.
+     *
+     * A note this pass has nothing to compile is **skipped**, counted like any
+     * other note the pack does not own. A deliberately unstatted person is the
+     * ordinary case, and a block deleted by accident shows in the diff that
+     * deleted it; what would otherwise be discarded in silence is the block
+     * written for a system no pack of the class serves, and that is reported by
+     * {@link module:engine/note-claims.unclaimedNoteFindings} rather than here,
+     * where a pass can see only its own half of the configuration.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True when the note may be compiled here; `false` when
-     *   it belongs to another system's pass of the same document type, which is
-     *   skipped as quietly as any other note this pack does not own.
-     * @throws {Error} When this pack's system is absent from the note and no
-     *   other configured system claims it. The error carries a `position` where
-     *   the note's own file can be read.
+     *   it carries nothing for this pass's system.
      */
     eligibleFor(fm) {
-        if (!this.constructor.requiresSystemBlock || !this.packSystem) return true;
-        if (carriesSystemBlock(fm, this.packSystem)) return true;
-        // Another system's pack of this document type will claim it. A
-        // note carrying only `hm3:` routes here because this pack is the
-        // *default* of its document type, and defaults are declared per type
-        // rather than per system — but it is not an incomplete note, it is
-        // another pass's. The single-system case is untouched: with no second
-        // system declared there is nothing for this to find, and the error
-        // below still fires.
-        const claimant = (this.router?.systemsOfType?.(this.docType) ?? []).find(
-            (system) => system !== this.packSystem && carriesSystemBlock(fm, system),
-        );
-        if (claimant) return false;
-        const label = fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "this note";
-        throw new Error(
-            `${label} carries no \`${this.packSystem}:\` block, so it has no ` +
-                `${this.packSystem} data to compile — but it routes to pack ` +
-                `"${this.packName}", which declares \`system: ${this.packSystem}\`. ` +
-                `Add the block, or route the note to a pack of another system.`,
-        );
+        if (!this.constructor.requiresSystemBlock) return true;
+        return carriesSystemBlock(fm, this.system);
     }
 
     /**

package/engine/content-index.mjs

@@ -422,9 +422,10 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
- *   holds no address and offers no anchor. It keeps everything else, its `id`
- *   and its `foundry` block included, because the document it compiles is
- *   derived from `data:` rather than from prose.
+ *   holds no address and offers no anchor. It keeps its `id`, and a `foundry`
+ *   block naming every document that was made — which is every document
+ *   derived from `data:`, and no journal, because a journal of an empty body
+ *   would be empty and is not created.
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
@@ -443,16 +444,18 @@ export function buildIndexRecord({
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
     const address = noteAddress(frontmatter, contentPackage);
-    // Derived from the address the note *would* hold, because a stub keeps its
-    // Foundry document: a document is derived from `data:`, not from prose, and
-    // the empty body suppresses the page rather than the document.
+    // Derived from the address the note *would* hold, because a stub still
+    // compiles every document derived from `data:` — an unwritten arcane talent
+    // is its Item. The one document it has none of is the one that would be
+    // empty, and `entriesForNote` withholds that UUID, so this block names
+    // nothing that was not made.
     const entries = foundryEntries({ frontmatter, address, body, manifest });
     // A stub — an empty body on a type an empty body suppresses — publishes no
     // page, so it holds no address and offers no anchor to link to. **The
     // absent address is the signal**, and it is the column the table renderer
     // already reads through `_ref`. Everything else the note declares is kept:
     // its file is what the author edits and what every diagnostic names, and
-    // its `id` and `foundry` block are the document it still compiles.
+    // its `id` is the identity every diagnostic and every table reads.
     const stub = isStubNote(frontmatter, body);
 
     return /** @type {Record<string, any>} */ (
@@ -530,6 +533,12 @@ export function buildIndexRecord({
  * @returns {Record<string, any>} The documentation journal's index record.
  */
 function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anchors }) {
+    // **The entry names a document only where one was made**, and where it does
+    // not, nothing on this record may name one either: no id, no address and no
+    // anchors. The record itself stays, because the index records what a note
+    // produces and `null` is how it says a document was not produced — the same
+    // signal a stub's absent address already is.
+    const made = Boolean(entry.uuid);
     return /** @type {Record<string, any>} */ (
         sortKeysDeep({
             package: contentPackage,
@@ -540,13 +549,13 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
             // re-derived: every entry the index gives an identity to publishes
             // both the id and the UUID, computed once by whatever owns that
             // entry's derivation.
-            id: entry.id,
+            id: made ? entry.id : null,
             nameAscii: asciiName(frontmatter?.name?.full),
-            address: { slug: address.slug, canonical: entry.key },
+            address: made ? { slug: address.slug, canonical: entry.key } : null,
             // The record this is the documentation *for*. `documentation` is
             // the forward link on that record, so either end reaches the other.
             documents: address.canonical,
-            anchors,
+            anchors: made ? anchors : null,
             foundry: foundryBlock(entry), // a journal: no system key
             file,
         })
@@ -637,8 +646,8 @@ export function collectContentIndex(
 
         // An item note is two documents, so it is two records. Derived from
         // the address the note *would* hold rather than from the one its
-        // record carries: a stub withholds its own address and still compiles
-        // both documents, and the journal is one of them.
+        // record carries, because a stub withholds its own address; the second
+        // record says whether the journal beside the item was made.
         const address = noteAddress(fm, contentPackage);
         const doc = foundryEntries({ frontmatter: fm, address, body, manifest })?.doc;
         if (doc?.key && address) {