@heroiclands/package-build 22.5.1 → 22.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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

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

package/docs/api.md

@@ -627,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. |
 
@@ -1197,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
@@ -1668,6 +1683,10 @@ already carried.
 | **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
 nothing about its own finishedness.
@@ -1763,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
@@ -1780,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/foundry-entries.mjs

@@ -65,6 +65,8 @@ import {
     NEVER_PACKED_TYPES,
     DERIVED_PACKED_TYPES,
 } from "./note-claims.mjs";
+import { DEFAULT_DOCUMENT_SUBTYPES, SYSTEM_DOCUMENT_CLASSES } from "./subtype-registry.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
@@ -207,14 +209,30 @@ export function entriesForNote(fm, name, address, body, ctx) {
             return undefined;
         }
 
-        return compendiumUuid(
-            foundryPackageId,
-            type,
-            id,
+        const docType = routeFm ? packForType(type).docType : "JournalEntry";
+        const pack =
             routeFm ?
-                packRouter.resolveOrNull(routeFm, packForType(type).docType)
-            :   packRouter.defaultOf("JournalEntry"),
-        );
+                packRouter.resolveOrNull(routeFm, docType)
+            :   packRouter.defaultOf("JournalEntry");
+
+        // **A system block is what makes a game document**, so a note carrying
+        // none compiles into no Actor and no Item — and an address naming one
+        // would send every consumer to a document that is not there. The same
+        // statement `pack: none` makes about a pack, made about a system: the
+        // note keeps its address, its page and its prose journal, and publishes
+        // no UUID for the document it does not produce.
+        //
+        // Which block is asked for is the pack's, because the pack decides the
+        // pass: one declaring a `system:` is compiled by that system's pass,
+        // and one declaring none by the fallback, which reads a single block of
+        // its own.
+        if (SYSTEM_DOCUMENT_CLASSES.has(docType)) {
+            const system =
+                (pack && packRouter.systemOf?.(pack)) || DEFAULT_DOCUMENT_SUBTYPES.system;
+            if (!carriesSystemBlock(routeFm, system)) return undefined;
+        }
+
+        return compendiumUuid(foundryPackageId, type, id, pack);
     };
 
     const carriesDoc =

package/engine/generate.mjs

@@ -102,7 +102,22 @@ const COMPILERS = {
 };
 
 /**
- * The system-specific compilers, by the system a pack declares.
+ * Every pass this toolchain ships that writes one system's data.
+ *
+ * The list a system joins, and the only place it is named. Each class already
+ * declares which system it is for (`documentSubtypes`) and which document it
+ * writes (`documentClass`), so the pairing is read off the passes rather than
+ * spelled a second time beside them — a table keyed by system id is a table
+ * free to disagree with the classes it names, and the way it disagrees is
+ * silent: a system absent from it took the fallback pass and compiled its packs
+ * out of a neighbour's blocks.
+ *
+ * @type {readonly Function[]}
+ */
+const SYSTEM_PASSES = Object.freeze([Items, Actors, Hm3Items, Hm3Actors]);
+
+/**
+ * The system-specific compilers, derived from the passes themselves.
  *
  * A repository feeding two systems declares one Item pack and one Actor pack
  * per system — `harn-ensemble` has `actors-hm3` and `actors-sohl` — and each
@@ -111,28 +126,84 @@ const COMPILERS = {
  * `itemBuilders` lookup already read, so nothing new is declared to make the
  * compiler follow it.
  *
- * A system with no entry — or a pack that declares none — falls back to
- * {@link COMPILERS}. That keeps every single-system configuration meaning
- * exactly what it did: SoHL's passes were the only ones, so they stay the
- * answer where nothing says otherwise.
+ * @param {readonly Function[]} passes - The system passes to table.
+ * @returns {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ *   System id → document class → pass.
+ * @throws {Error} When a pass declares no system or no document class, which is
+ *   a pass that cannot be addressed by either question this table answers.
+ */
+export function systemCompilers(passes) {
+    /** @type {Record<string, Record<string, Function>>} */
+    const table = {};
+    for (const pass of passes) {
+        const declared =
+            /** @type {{documentSubtypes?: {system?: string},
+             *   documentClass?: string, name: string}} */ (pass);
+        const system = declared.documentSubtypes?.system;
+        const docType = declared.documentClass;
+        if (!system || !docType) {
+            throw new Error(
+                `${declared.name} is registered as a system pass but declares ` +
+                    `${system ? "no `documentClass`" : "no `documentSubtypes`"} — a pass ` +
+                    `writing a system's data states both, so which system and which ` +
+                    `document it answers for is read from the class itself.`,
+            );
+        }
+        (table[system] ??= {})[docType] = pass;
+    }
+    return Object.freeze(
+        Object.fromEntries(
+            Object.entries(table).map(([system, byType]) => [system, Object.freeze(byType)]),
+        ),
+    );
+}
+
+/** @type {Readonly<Record<string, Readonly<Record<string, Function>>>>} */
+const SYSTEM_COMPILERS = systemCompilers(SYSTEM_PASSES);
+
+/**
+ * The document classes some system writes its own data into.
+ *
+ * Derived from {@link SYSTEM_COMPILERS}, so it is the set of classes for which
+ * "which system?" is a question with consequences. Every other class has one
+ * implementation whatever a pack declares.
  *
- * @type {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ * @type {ReadonlySet<string>}
  */
-const SYSTEM_COMPILERS = Object.freeze({
-    sohl: Object.freeze({ Item: Items, Actor: Actors }),
-    hm3: Object.freeze({ Item: Hm3Items, Actor: Hm3Actors }),
-});
+const SYSTEM_DOCUMENT_CLASSES = Object.freeze(
+    new Set(Object.values(SYSTEM_COMPILERS).flatMap((byType) => Object.keys(byType))),
+);
 
 /**
  * The compiler class a pack of one document type and one system gets.
  *
+ * A pack declaring **no** system takes the fallback pass for its document
+ * class, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} — the
+ * single-system convenience every tree shipping for one system is built on.
+ *
+ * A pack declaring a system this toolchain has no pass for is **refused by
+ * name**. Falling through to the fallback would compile that pack out of
+ * another system's blocks and ship it stamped with the system it asked for,
+ * which is the quiet failure the refusal exists to replace.
+ *
  * @param {string} docType - The Foundry document type the pack holds.
  * @param {string|null} [system] - The system the pack declares, if any.
  * @returns {Function|undefined} The compiler class, or `undefined` for a
  *   document type nothing here compiles — which {@link generatePack} reports
  *   rather than defaulting past.
+ * @throws {Error} When a system-bearing document class is asked for a system
+ *   this toolchain ships no pass for.
  */
 export function compilerFor(docType, system = null) {
+    if (system && SYSTEM_DOCUMENT_CLASSES.has(docType) && !SYSTEM_COMPILERS[system]?.[docType]) {
+        throw new Error(
+            `no ${docType} compiler for system "${system}" — this toolchain ships ` +
+                `passes for ${Object.keys(SYSTEM_COMPILERS).sort().join(", ")}. Declare a ` +
+                `system one of those names, or add the pass that reads a ` +
+                `\`${system}:\` block.`,
+        );
+    }
     return (system && SYSTEM_COMPILERS[system]?.[docType]) || COMPILERS[docType];
 }
 

package/engine/infobox-registry.mjs

@@ -58,24 +58,23 @@ export function infoboxFor(system) {
  * Whether one system compiles a document for one note.
  *
  * This is what a system box's _available_ asserts, and it is the compile's own
- * question rather than a reading of the frontmatter. A note carrying no block
- * is not a note a system has nothing for: where the pack compiling its document
- * declares no `system:`, the document is built from `data:` and the field
- * defaults and ships exactly like any other.
+ * question rather than a reading of the frontmatter.
  *
  * Three statements answer it, and they are the three the compile itself
  * follows:
  *
- * 1. **The map** says which document class this system makes of the note's
+ * 1. **The note's block.** A system block is what makes a game document, so a
+ *    note carrying nothing for this system compiles into no document of it
+ *    anywhere — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside.
+ * 2. **The map** says which document class this system makes of the note's
  *    type. No row, no document — and no box either, which is why a caller
  *    reaching here already has one.
- * 2. **The router** says which pack that document goes to, read from the pack
- *    list this build is driven by.
- * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
- *    system's data and takes only notes that say something about it — the rule
- *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
- *    asked here from outside. Declaring none, it is compiled by the fallback
- *    pass, which needs no block and answers for
+ * 3. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by, and **that pack's `system:`** decides whose
+ *    it is. Declaring one, it writes that system's data. Declaring none, it is
+ *    compiled by the fallback pass, which reads
  *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
  *    so a tree with no HM3 pack ships no HM3 document however a note is
  *    written.
@@ -86,6 +85,8 @@ export function infoboxFor(system) {
  * @returns {boolean} True when this system compiles a document for this note.
  */
 export function compilesSystemDocument(fm, map, router) {
+    if (!carriesSystemBlock(fm, map.block)) return false;
+
     const row = subtypeRow(map, fm?.type);
     if (!row?.document) return false;
 
@@ -94,7 +95,7 @@ export function compilesSystemDocument(fm, map, router) {
 
     const packSystem = router.systemOf(packName);
     if (!packSystem) return map.system === DEFAULT_DOCUMENT_SUBTYPES.system;
-    return packSystem === map.system && carriesSystemBlock(fm, map.block);
+    return packSystem === map.system;
 }
 
 /**

package/engine/item-compiler.mjs

@@ -116,6 +116,18 @@ export class SystemItemCompiler 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 = "Item";
+
     /**
      * An Item carries one piece of art — its icon — which this pass writes from
      * the address the note names, falling back to the type's default art.

package/engine/note-claims.mjs

@@ -94,7 +94,13 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
-import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+import {
+    DEFAULT_DOCUMENT_SUBTYPES,
+    KNOWN_DOCUMENT_SUBTYPE_MAPS,
+    SHIPPED_SYSTEMS,
+    subtypeMapFor,
+} from "./subtype-registry.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { BUNDLE_TYPE } from "./bundle-notes.mjs";
@@ -615,7 +621,92 @@ function authoringMessage(type) {
 }
 
 /**
- * Every note in the content tree that no configured pack would compile.
+ * Which pass would read one system's block, given a configuration's packs.
+ *
+ * A pack declaring `system: hm3` is compiled by the HM3 pass and reads `hm3:`.
+ * A pack declaring **no** system is compiled by the fallback pass, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} and nothing
+ * else — so a systemless pack answers for one system, not for every system a
+ * note might carry. That asymmetry is the whole of this question: the router
+ * will happily route an `hm3:` document into a systemless pack, and the pass
+ * waiting there reads a different block.
+ *
+ * A **prebuilt** pack compiles nothing — its JSON is checked in — so it reads
+ * no block either.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} docType - The document class the block would compile into.
+ * @param {string} system - The system whose block is in question.
+ * @returns {{packs: number, serving: number}} How many non-prebuilt packs of
+ *   that class the configuration has, and how many of them compile that
+ *   system's documents.
+ */
+function packsServing(config, docType, system) {
+    const packs = (config?.packs ?? []).filter((pack) => !pack?.prebuilt && pack?.type === docType);
+    const serving = packs.filter((pack) =>
+        pack.system ? pack.system === system : system === DEFAULT_DOCUMENT_SUBTYPES.system,
+    );
+    return { packs: packs.length, serving: serving.length };
+}
+
+/**
+ * Every system block on one note that no pack in this package will read.
+ *
+ * **A discarded field is the quiet-failure class the diagnostics exist to
+ * close**, and a system block is the largest field a note can write: a whole
+ * document's worth of authored data, compiled by nobody and reported by
+ * nobody. The claim check beside this one asks whether a note's *type* is
+ * claimed; this asks whether its *systems* are.
+ *
+ * `error`, because the data is lost either way and the author cannot see it
+ * happen. It says nothing about a note carrying **no** block — that note is
+ * making a statement, and the statement is that nobody rolls dice against this
+ * person.
+ *
+ * Silent, too, where the class has no pack at all: the note's whole document is
+ * missing, which {@link partialMessage} already reports with the remedy.
+ *
+ * @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 {object} config - The resolved build configuration.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string, type: string}>} One finding per
+ *   discarded block.
+ */
+function discardedSystemBlockFindings(fm, absPath, type, config) {
+    const findings = [];
+    for (const system of SHIPPED_SYSTEMS) {
+        if (!carriesSystemBlock(fm, system)) continue;
+        const docType = subtypeRow(subtypeMapFor(system), type)?.document;
+        // This system makes no document of this note type, so its block says
+        // nothing that could be discarded — it is read for the note's fields
+        // wherever another pass wants them.
+        if (!docType) continue;
+        const { packs, serving } = packsServing(config, docType, system);
+        if (!packs || serving) continue;
+        findings.push({
+            file: absPath,
+            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true }),
+            severity: /** @type {"error"} */ ("error"),
+            type,
+            message:
+                `carries a \`${system}:\` block, and no ${docType} pack in this ` +
+                `package compiles ${system} documents, so the block is discarded — ` +
+                `declare \`system: ${system}\` on one of the \`packs:\`, or remove ` +
+                `the block.`,
+        });
+    }
+    return findings;
+}
+
+/**
+ * Every note in the content tree that no configured pack would compile, and
+ * every system block no configured pack would read.
+ *
+ * Two questions of one walk, because they are the same question asked of a
+ * 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
  * note are passed over, each for a stated reason rather than by omission — a
@@ -672,6 +763,11 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // 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));
+
         // 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

package/engine/subtype-registry.mjs

@@ -68,12 +68,15 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
 /**
  * The map a pack declaring no `system:` compiles its documents against.
  *
- * A pack names the system its documents are shaped for, and one declaring none
- * is compiled by the fallback pass for its document type — a single-system
+ * **The single-system fallback, and not a default any system inherits.** A pack
+ * names the system its documents are shaped for, and one declaring none is
+ * compiled by the fallback pass for its document type — a single-system
  * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
- * follows one map whatever a note carries, which makes this the answer to "a
- * document compiled here belongs to *which* system?" wherever a pack has not
- * said.
+ * reads this map's block and no other, so a note carrying nothing for this
+ * system compiles into no document there; a note carrying another system's
+ * block reaches that system's pass or nothing at all, never this one. This is
+ * the answer to "a document compiled here belongs to *which* system?" wherever
+ * a pack has not said, and it answers nothing about a system that has said.
  *
  * Stated here rather than read off the compiler classes because those are not
  * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
@@ -86,6 +89,40 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
  */
 export const DEFAULT_DOCUMENT_SUBTYPES = SOHL_DOCUMENT_SUBTYPES;
 
+/**
+ * Every system this toolchain ships a map for, by id.
+ *
+ * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
+ * whole of adding a system to every reader that asks "which systems are there?"
+ * — the per-system findings among them.
+ *
+ * @type {readonly string[]}
+ */
+export const SHIPPED_SYSTEMS = Object.freeze(KNOWN_DOCUMENT_SUBTYPE_MAPS.map((map) => map.system));
+
+/**
+ * The Foundry document classes a system compiles its own data into.
+ *
+ * Derived from the shipped maps' rows, so it is the set of classes for which
+ * "which system?" is a question with consequences: a pack of one of these
+ * classes is compiled by one system's pass reading one system's block, and a
+ * note carrying no such block produces nothing there. Every other class — a
+ * JournalEntry, a Macro, a Scene, an Adventure — has one implementation
+ * whatever a pack declares, because it is Foundry's document rather than any
+ * system's.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_DOCUMENT_CLASSES = Object.freeze(
+    new Set(
+        KNOWN_DOCUMENT_SUBTYPE_MAPS.flatMap((map) =>
+            Object.values(map.types)
+                .map((row) => row?.document)
+                .filter(Boolean),
+        ),
+    ),
+);
+
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.5.1",
+    "version": "22.6.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/actor-compiler.d.mts

@@ -199,6 +199,17 @@ export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDi
  * becomes embedded items. Nothing above that line is a system's business.
  */
 export class SystemActorCompiler extends BasePackCompiler {
+    /**
+     * 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: string;
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

package/types/engine/base-compiler.d.mts

@@ -82,13 +82,16 @@ export class BasePackCompiler {
     static readsPackOutputOf: readonly string[];
     /**
      * 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
@@ -265,22 +268,49 @@ export class BasePackCompiler {
      *   routes to no pack at all — a build failure, never a silent drop.
      */
     routesHere(fm: object): boolean;
+    /**
+     * 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(): string | 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: object): boolean;
     /**

package/types/engine/generate.d.mts

@@ -1,11 +1,40 @@
+/**
+ * The system-specific compilers, derived from the passes themselves.
+ *
+ * A repository feeding two systems declares one Item pack and one Actor pack
+ * per system — `harn-ensemble` has `actors-hm3` and `actors-sohl` — and each
+ * pack's `system:` is what says whose data model its documents are shaped for.
+ * That is the same field the `_stats` stamp, the item-catalogue scope and the
+ * `itemBuilders` lookup already read, so nothing new is declared to make the
+ * compiler follow it.
+ *
+ * @param {readonly Function[]} passes - The system passes to table.
+ * @returns {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ *   System id → document class → pass.
+ * @throws {Error} When a pass declares no system or no document class, which is
+ *   a pass that cannot be addressed by either question this table answers.
+ */
+export function systemCompilers(passes: readonly Function[]): Readonly<Record<string, Readonly<Record<string, Function>>>>;
 /**
  * The compiler class a pack of one document type and one system gets.
  *
+ * A pack declaring **no** system takes the fallback pass for its document
+ * class, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} — the
+ * single-system convenience every tree shipping for one system is built on.
+ *
+ * A pack declaring a system this toolchain has no pass for is **refused by
+ * name**. Falling through to the fallback would compile that pack out of
+ * another system's blocks and ship it stamped with the system it asked for,
+ * which is the quiet failure the refusal exists to replace.
+ *
  * @param {string} docType - The Foundry document type the pack holds.
  * @param {string|null} [system] - The system the pack declares, if any.
  * @returns {Function|undefined} The compiler class, or `undefined` for a
  *   document type nothing here compiles — which {@link generatePack} reports
  *   rather than defaulting past.
+ * @throws {Error} When a system-bearing document class is asked for a system
+ *   this toolchain ships no pass for.
  */
 export function compilerFor(docType: string, system?: string | null): Function | undefined;
 /**

package/types/engine/infobox-registry.d.mts

@@ -10,24 +10,23 @@ export function infoboxFor(system: string | undefined): object | undefined;
  * Whether one system compiles a document for one note.
  *
  * This is what a system box's _available_ asserts, and it is the compile's own
- * question rather than a reading of the frontmatter. A note carrying no block
- * is not a note a system has nothing for: where the pack compiling its document
- * declares no `system:`, the document is built from `data:` and the field
- * defaults and ships exactly like any other.
+ * question rather than a reading of the frontmatter.
  *
  * Three statements answer it, and they are the three the compile itself
  * follows:
  *
- * 1. **The map** says which document class this system makes of the note's
+ * 1. **The note's block.** A system block is what makes a game document, so a
+ *    note carrying nothing for this system compiles into no document of it
+ *    anywhere — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside.
+ * 2. **The map** says which document class this system makes of the note's
  *    type. No row, no document — and no box either, which is why a caller
  *    reaching here already has one.
- * 2. **The router** says which pack that document goes to, read from the pack
- *    list this build is driven by.
- * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
- *    system's data and takes only notes that say something about it — the rule
- *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
- *    asked here from outside. Declaring none, it is compiled by the fallback
- *    pass, which needs no block and answers for
+ * 3. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by, and **that pack's `system:`** decides whose
+ *    it is. Declaring one, it writes that system's data. Declaring none, it is
+ *    compiled by the fallback pass, which reads
  *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
  *    so a tree with no HM3 pack ships no HM3 document however a note is
  *    written.

package/types/engine/item-compiler.d.mts

@@ -29,6 +29,17 @@ export function itemDescription(markdown: string, fm: object, name: string): str
  * a configuration one.
  */
 export class SystemItemCompiler extends BasePackCompiler {
+    /**
+     * 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: string;
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

package/types/engine/note-claims.d.mts

@@ -102,7 +102,12 @@ export function claimedNoteTypes(config?: object, sources?: ClaimSources): Reado
  */
 export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
 /**
- * Every note in the content tree that no configured pack would compile.
+ * Every note in the content tree that no configured pack would compile, and
+ * every system block no configured pack would read.
+ *
+ * Two questions of one walk, because they are the same question asked of a
+ * 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
  * note are passed over, each for a stated reason rather than by omission — a

package/types/engine/subtype-registry.d.mts

@@ -50,12 +50,15 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
 /**
  * The map a pack declaring no `system:` compiles its documents against.
  *
- * A pack names the system its documents are shaped for, and one declaring none
- * is compiled by the fallback pass for its document type — a single-system
+ * **The single-system fallback, and not a default any system inherits.** A pack
+ * names the system its documents are shaped for, and one declaring none is
+ * compiled by the fallback pass for its document type — a single-system
  * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
- * follows one map whatever a note carries, which makes this the answer to "a
- * document compiled here belongs to *which* system?" wherever a pack has not
- * said.
+ * reads this map's block and no other, so a note carrying nothing for this
+ * system compiles into no document there; a note carrying another system's
+ * block reaches that system's pass or nothing at all, never this one. This is
+ * the answer to "a document compiled here belongs to *which* system?" wherever
+ * a pack has not said, and it answers nothing about a system that has said.
  *
  * Stated here rather than read off the compiler classes because those are not
  * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
@@ -67,6 +70,30 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
  * @type {import("./document-subtypes.mjs").DocumentSubtypeMap}
  */
 export const DEFAULT_DOCUMENT_SUBTYPES: import("./document-subtypes.mjs").DocumentSubtypeMap;
+/**
+ * Every system this toolchain ships a map for, by id.
+ *
+ * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
+ * whole of adding a system to every reader that asks "which systems are there?"
+ * — the per-system findings among them.
+ *
+ * @type {readonly string[]}
+ */
+export const SHIPPED_SYSTEMS: readonly string[];
+/**
+ * The Foundry document classes a system compiles its own data into.
+ *
+ * Derived from the shipped maps' rows, so it is the set of classes for which
+ * "which system?" is a question with consequences: a pack of one of these
+ * classes is compiled by one system's pass reading one system's block, and a
+ * note carrying no such block produces nothing there. Every other class — a
+ * JournalEntry, a Macro, a Scene, an Adventure — has one implementation
+ * whatever a pack declares, because it is Foundry's document rather than any
+ * system's.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_DOCUMENT_CLASSES: ReadonlySet<string>;
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *