@heroiclands/package-build 23.1.0 → 23.2.0

package/types/engine/site-build.d.mts

@@ -74,10 +74,16 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * @param {import("./related-pages.mjs").Related} [options.related] - The
  *   homepage's backlinks and mentions. Absent where nothing connects to it,
  *   and when the tree contains only a homepage, where no content link resolves.
+ * @param {readonly object[]} [options.records] - The corpus, so a `data.banner`
+ *   address resolves against the images this package ships.
+ * @param {object} [options.foreign] - The dependencies' vendored indexes, so a
+ *   `data.banner` may name an image a dependency ships.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related }?: {
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related, records, foreign }?: {
     related?: import("./related-pages.mjs").Related | undefined;
+    records?: readonly object[] | undefined;
+    foreign?: object | undefined;
 }): number;
 /**
  * The integrity gates a site build runs before it writes anything.
@@ -147,9 +153,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is retired and refused before a build reaches
- * here, which makes this a guard rather than a working path. It is a list of
- * names a reader might call the note. Hugo reads
+ * An authored `aliases` is a list of names a reader might call the note. Hugo reads
  * `aliases` as **URL redirects**, so passing them through would publish a
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
@@ -171,7 +175,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * `<base><slug>/`.
  *
  * A content page carries the package the build **derived**. No note
- * declares one — `package:` is retired — so the note's frontmatter alone
+ * declares one, so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
  * emitted page is what a theme reads: `breadcrumbs.html` reads
  * `.Params.package`. Writing the derived value keeps a page

package/types/engine/site-index.d.mts

@@ -104,11 +104,10 @@ export function resolveCrossNoteFigures(target: string, { contentTypes, packages
  *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
- * There is deliberately **no `manifestsComplete`**. It used to let a resolver
- * soften an unresolved cross-package address while any package's manifest was
- * missing; the softening is retired, since the pack compilers and the link
- * checker never had it and one authored link must not get two verdicts. A
- * caller still passing it is ignored rather than obeyed.
+ * There is deliberately **no `manifestsComplete`**: an unresolved cross-package
+ * address is never softened while a manifest is missing, since the pack
+ * compilers and the link checker do not soften it and one authored link must
+ * not get two verdicts.
  */
 export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets, resolved }: {
     src: string;

package/types/engine/site-root.d.mts

@@ -42,7 +42,7 @@ export function indexSite(where: {
  * sits there. Left in place it would redirect the prefix root — the homepage —
  * to an address nothing publishes. The same holds for a `pagefind/` left by an
  * earlier build when `search` is off: deployed, it is a working search over
- * pages that may no longer exist, so it goes too.
+ * pages that may not exist, so it goes too.
  *
  * `_headers` is written before the index is built, so a failed index leaves
  * the root files as they would be — the failure is the indexer's, reported as

package/types/engine/sql-tables.d.mts

@@ -98,7 +98,7 @@ export function runSqlQuery(db: object, sql: string): Promise<{
  * ships a link that does not resolve. A `_section` alias splits the result into
  * a headed table per distinct value, in the order the rows arrive — so the
  * authored `ORDER BY` decides the section order too, and one query replaces the
- * forty near-identical blocks the language used to require.
+ * forty near-identical blocks it would otherwise take.
  *
  * **A result selecting nothing still renders its header and rule.** The finding
  * is the point, not withholding the output: an authored heading with an empty
@@ -212,6 +212,8 @@ export function generatedSectionsFor(db: object | undefined, records: object[],
  *   From {@link generatedSectionsFor}.
  * @param {Array<{source: string, markdown: string, frontmatter?: object}>} sources -
  *   The bodies to answer, extended in place.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [parsed] -
+ *   Notes already parsed, keyed by file; a note absent from it is read.
  * @returns {void}
  */
 export function joinGeneratedSections(generated: {
@@ -221,6 +223,9 @@ export function joinGeneratedSections(generated: {
     source: string;
     markdown: string;
     frontmatter?: object;
+}>, parsed?: Map<string, {
+    body: string;
+    frontmatter: object | null;
 }>): void;
 /**
  * Record each note's generated sections on its prepared results, where the
@@ -235,6 +240,17 @@ export function joinGeneratedSections(generated: {
 export function attachGeneratedSections(prepared: Map<string, object[]>, generated: {
     sections: Map<string, string>;
 }): void;
+/**
+ * Each declared dependency's cached index, as {@link openNotesDatabase} attaches
+ * them. Empty where none has been fetched.
+ *
+ * @param {object} [config] - Resolved configuration, defaulting to ambient.
+ * @returns {Promise<Array<{id: string, file: string}>>} The dependencies.
+ */
+export function cachedDependencies(config?: object): Promise<Array<{
+    id: string;
+    file: string;
+}>>;
 /**
  * Answer every `sql` directive in a content tree.
  *
@@ -259,6 +275,14 @@ export function attachGeneratedSections(prepared: Map<string, object[]>, generat
  * @param {object[]} [opts.records] - Index records the caller already derived.
  *   A command that also builds a link index holds them already, and deriving
  *   them twice is the duplicated-corpus failure this closes.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] -
+ *   The notes {@link module:engine/content-index.indexRecordsFor} parsed for
+ *   `records`, keyed by file, so no note is parsed twice. A note absent from it
+ *   is read.
+ * @param {object} [opts.database] - An open notes database over `records`, from
+ *   {@link openNotesDatabase} with this call's `audience` and the declared
+ *   dependencies from {@link cachedDependencies}. It is queried and left open;
+ *   absent, one is opened and closed here.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes the
  *   generated sections take in, where the caller holds them already; absent,
@@ -267,10 +291,15 @@ export function attachGeneratedSections(prepared: Map<string, object[]>, generat
  *   carrying `inline` and `pageLists` beside them, or nothing when the tree
  *   holds no such directive and no note is given a generated section.
  */
-export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, audience, foreignIndex }?: {
+export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, parsed, database, audience, foreignIndex }?: {
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     records?: object[] | undefined;
+    parsed?: Map<string, {
+        body: string;
+        frontmatter: object | null;
+    }> | undefined;
+    database?: object | undefined;
     audience?: "all" | "public" | undefined;
     foreignIndex?: Map<string, object> | undefined;
 }): Promise<Map<string, object[]> | undefined>;

package/types/engine/standing-terms.d.mts

@@ -21,7 +21,8 @@ export const STANDING_BODY_TYPES: readonly string[];
  *
  * `rank` is the level on the body's own `governance.ranks` ladder, and every
  * membership states one. `office` is a key of its `governance.offices` map, and
- * is stated only where the being holds a post.
+ * is stated only where the being holds a post. `societies` names the societies
+ * the membership is held in, as a list because a membership can span several.
  *
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */

package/types/engine/standings.d.mts

@@ -1,14 +1,12 @@
 /**
  * The standings a being authored, in one shape whichever shape it wrote.
  *
- * The list form names bodies and no standings; the map form names both. Three
- * spellings reach here and every reader downstream takes the same entries, so
- * none of them asks which it was handed:
+ * Two spellings reach here and every reader downstream takes the same entries,
+ * so none of them asks which it was handed:
  *
  * - an **{@link AddressEntries}** — the map after the note boundary decoded its
  *   keys into typed Addresses, which is the shape every compile sees;
- * - a **plain map**, which is the shape a checker reading raw YAML sees;
- * - a **list**, which names bodies and says nothing about standing in them.
+ * - a **plain map**, which is the shape a checker reading raw YAML sees.
  *
  * An emptied map arrives from the property editor as `[]` and means what `{}`
  * means — this being authors no membership — so both read as no entries.
@@ -18,12 +16,12 @@
  * Address is what a finding should name.
  *
  * @param {unknown} value - The authored `data.affiliations`.
- * @returns {{form: "absent"|"list"|"map"|"malformed",
+ * @returns {{form: "absent"|"map"|"malformed",
  *   entries: Array<{body: unknown, sourceKey: string|number, standing: unknown}>}}
  *   The form it was written in, and its entries.
  */
 export function readStandings(value: unknown): {
-    form: "absent" | "list" | "map" | "malformed";
+    form: "absent" | "map" | "malformed";
     entries: Array<{
         body: unknown;
         sourceKey: string | number;
@@ -128,7 +126,7 @@ export function standingLead(standing: object, digest?: {
  * Five questions, and the last three are what keying the entry by its body
  * buys:
  *
- * 1. the value is a map keyed by Address (or the list this window still takes);
+ * 1. the value is a map keyed by Address;
  * 2. every key names an affiliation that resolves, once;
  * 3. the entry states a standing at all — what a stated standing holds is the
  *    inner-key check's, read from {@link STANDING_FIELDS};
@@ -136,7 +134,7 @@ export function standingLead(standing: object, digest?: {
  * 5. an `office` is a key of that body's `governance.offices`.
  *
  * Both of the last two are read from the named body's own frontmatter as the
- * lint runs, so a renamed rung or a renamed post fails on every being pointing
+ * lint runs, so a rung or a post that does not exist fails on every being pointing
  * at it rather than on a list somebody has to remember to edit.
  *
  * @param {object} note - The note.

package/types/engine/system-block.d.mts

@@ -95,17 +95,14 @@ export function sharedProperty(fm: object, source: string, defaultValue?: any):
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
 /**
- * A system override followed by a shared `data:` value followed by the
- * retiring top-level spelling `data:` gathered it off, reporting which one
+ * A system override followed by a shared `data:` value, reporting which one
  * answered.
  *
  * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
  * universal `data:` key — `pack` and `packFolder`, declared for every note
  * type rather than per type, so neither is a `FieldSpec` that resolver takes.
  * The order is the same shape: a system's own override, then the shared
- * `data:` position, then the bare top-level key a tree authored before
- * `data:` existed. The top-level value stays readable while a tree still on
- * it moves its authored fields.
+ * `data:` position.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
@@ -132,46 +129,15 @@ export function blockDataProperty(fm: object, block: string, key: string, defaul
 /**
  * The key a field is authored at **inside** a system block — step 2.
  *
- * `legacyKey` when the field declares one, and `name` otherwise. The fallback
- * is what makes this change invisible to every declaration written before it:
- * a field whose shared source and in-block key are the same word says so once,
- * as it always did.
- *
- * Named and exported rather than spelled inline because three readers ask the
- * question and must agree — the resolver here, the frontmatter lint building
- * the set of keys a block may carry, and the author-facing surfaces naming
- * where a value was written.
- *
- * @param {{name?: string, legacyKey?: string}} field - The declaration.
- * @returns {string|undefined} The in-block key, or `undefined` for a field that
- *   is not authored at all.
- */
-export function legacyKeyOf(field: {
-    name?: string;
-    legacyKey?: string;
-}): string | undefined;
-/**
- * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
- *
- * The retiring spelling of `data.portrait` is not a second declaration anyone
- * has to write — it is `portrait`, mechanically, and the same holds for every
- * other key the container gathered. Deriving it is what keeps the two spellings
- * of one field from disagreeing the way two declarations would.
- *
- * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
- * paths into containers a note has always written at the top level; they were
- * never `blunt:` or `die:`, and reading those would invent a position rather
- * than remember one.
- *
- * A field declaring {@link module:engine/field-spec.FieldSpec `topLevelMeans`}
- * has no shared position at all, retiring or otherwise — the resolver checks
- * that before asking.
+ * The field's `name`, except that a name which is a path into `data:` has no
+ * in-block position. Named and exported because the resolver and the
+ * frontmatter lint, which builds the set of keys a block may carry, must agree.
  *
  * @param {{name?: string}} field - The declaration.
- * @returns {string|undefined} The retiring top-level path, or `undefined` for a
- *   field whose shared source never lived there.
+ * @returns {string|undefined} The in-block key, or `undefined` for a field that
+ *   is not authored in the block.
  */
-export function retiredTopLevelKey(field: {
+export function inBlockKey(field: {
     name?: string;
 }): string | undefined;
 /**
@@ -198,7 +164,7 @@ export function authoredKey(name: string | undefined): string;
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  *
- * @typedef {"system"|"block"|"shared"|"topLevel"|"default"|"value"} FieldSource
+ * @typedef {"system"|"block"|"shared"|"default"|"value"} FieldSource
  */
 /**
  * Resolve one declared field against a note, in the declared order.
@@ -394,4 +360,4 @@ export const SYSTEM_BLOCK_KEYS: ReadonlySet<string>;
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  */
-export type FieldSource = "system" | "block" | "shared" | "topLevel" | "default" | "value";
+export type FieldSource = "system" | "block" | "shared" | "default" | "value";

package/types/engine/walk-files.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Every file under a root, minus the directories nothing should walk.
+ *
+ * @param {string} root - Absolute path to walk.
+ * @param {object} [hooks]
+ * @param {(dir: string) => void} [hooks.enter] - Called with each directory
+ *   before its entries are read.
+ * @param {(abs: string, isDirectory: boolean) => boolean} [hooks.skip] -
+ *   Whether to leave a path out; a skipped directory is not entered.
+ * @returns {string[]} Absolute file paths, in directory order.
+ */
+export function walkFiles(root: string, hooks?: {
+    enter?: ((dir: string) => void) | undefined;
+    skip?: ((abs: string, isDirectory: boolean) => boolean) | undefined;
+}): string[];

package/types/engine/wikilink-syntax.d.mts

@@ -56,15 +56,10 @@ export function authoredLabel({ display }: {
  * the form to write rather than a value to correct: there is no value that
  * makes an unlabelled link resolve.
  *
- * **Why there is nothing left for a bare link to mean**. The pipe used
- * to select between two namespaces — address and alias — and the alias one was
- * empty in practice: across 8,305 wikilinks in three content trees, not one
- * bare `[[Alias]]` resolved to a note. What the index it looked up in *did* do
- * was fold every note's `name.full` into itself, which forbade two notes of a
- * type from sharing a display name. So the namespace is gone, every
- * link is an address, and an address needs the pipe that says so.
- *
- * The **link part may still be an anchor**: `[[#slug|Text]]` addresses a
+ * **A bare link has nothing to mean.** Every link is an address, and an
+ * address needs the pipe that says so.
+ *
+ * The **link part may be an anchor**: `[[#slug|Text]]` addresses a
  * section of the page it is written on. It is the label that is required, not
  * a target.
  *
@@ -100,13 +95,9 @@ export function isEventAnchor(hit: {
  * package publishing it is not a declared dependency — or is one whose index
  * has not been fetched — and the link itself looks identical in every case.
  *
- * As a **warning** in the checker and, in the site build, nothing
- * at all until every linkable package's manifest was accounted for — on the
- * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
- * written yet. That reasoning was a property of the bare form, which is retired;
- * the intent behind it now has a real spelling, a `draft`-tagged note
- * that exists and resolves and renders marked. So an address naming no
- * note is a typo or an omission, both want fixing, and all three builds say so.
+ * An address naming no note is a typo or an omission: the intent of a
+ * placeholder for a note nobody has written yet is spelled as a `draft`-tagged
+ * note that exists, resolves and renders marked. Both want fixing, and all three builds say so.
  *
  * @param {string} target - The address as authored, named in the message.
  * @returns {string} The message, unpunctuated at the end as a finding is.
@@ -165,17 +156,23 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {string} [finding.type] - For `not-an-asset`, the type the address
  *   named.
  * @param {string} [finding.stub] - For `stub`, where the stub is.
+ * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
+ *   shortcode as written.
+ * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
+ *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type, stub }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
     anchor?: string | undefined;
     type?: string | undefined;
     stub?: string | undefined;
+    shortcode?: string | undefined;
+    declared?: string | undefined;
 }): string;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
@@ -221,8 +218,8 @@ export function readWikilink(inner: string, context: object): object;
  *
  * The one rule about a link's *shape* that both resolvers share also lives here
  * — **a link carries a label** ({@link unlabelledLinkMessage}) — because the
- * two used to state it in their own words and the author met whichever ran
- * first.
+ * two state it through one message and the author reads the same words
+ * whichever ran first.
  *
  * For the same reason, so does the **vocabulary of link findings**
  * ({@link LINK_FINDING_REASONS}) and the message each one reports through
@@ -261,6 +258,8 @@ export const WIKILINK: RegExp;
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
  * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `shortcode-not-lowercase` — the shortcode segment carries a capital. A
+ *   shortcode is lowercase, and the link is refused rather than lowercased.
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.

package/types/engine/yaml-lint.d.mts

@@ -22,10 +22,11 @@
  * - `no-empty-key`, `no-empty-document` — a fence or a file that parses to
  *   nothing at all.
  *
- * **GitHub workflows are exempt from `no-empty-mapping-value`**, because an
- * empty value is the language there: `on:` `push:` and `workflow_dispatch:`
- * carry their meaning by being present, and writing `push: null` to satisfy a
- * linter would be worse YAML, not better.
+ * **Workflows are exempt from `no-empty-mapping-value`**, under
+ * `.github/workflows/` and Gitea's `.gitea/workflows/` alike, because an empty
+ * value is the language there: `on:` `push:` and `workflow_dispatch:` carry
+ * their meaning by being present, and writing `push: null` to satisfy a linter
+ * would be worse YAML, not better.
  *
  * @param {object} plugin - The `eslint-plugin-yml` module.
  * @returns {object[]} A complete flat config, for `overrideConfig`.

package/types/hm3/actors.d.mts

@@ -10,8 +10,7 @@ export const ACTOR_FIELDS: readonly import("../engine/field-spec.mjs").FieldSpec
 /**
  * The two `data:` facts HM3 declares on a `character` and not on a `creature`.
  *
- * Both name their shared source and their legacy in-block key, for the reason
- * {@link ACTOR_FIELDS} does.
+ * Both name a shared source in `data:`, which is the only place they are authored.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */

package/types/hm3/item-fields.d.mts

@@ -7,10 +7,8 @@
  * a registry is addressed by what a note calls itself. What the document is
  * called is the map's answer, and only the map's.
  *
- * Each field names both of its authored positions, as
- * {@link module:hm3/actors} does and for the same reason: `name` is the shared
- * source the content format's mapping tables state, and `legacyKey` is the key
- * the `hm3:` block still carries.
+ * A field whose `name` is a path into `data:` is authored there and nowhere
+ * else: `name` is the shared source the content format's mapping tables state.
  *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */

package/types/hm3/template-priority.d.mts

@@ -6,13 +6,12 @@
  * than a `null` nothing reads.
  *
  * **Read through the shared resolver, not a field declaration**. A
- * `FieldSpec`'s shared source is a single position, and this value has five:
- * `data:`, this block, the top level, and the retiring `archetype` spelling in
- * the latter two. The resolver is the single implementation of what a note said,
- * so the two systems cannot disagree about it. It is read against **this**
- * block: the `sohl:` block is not a source for an HM3 document, so a tree that
- * still states the priority there (`harn-ensemble`, on 2,502 notes) writes no
- * HM3 flag until it sweeps to `data:`.
+ * `FieldSpec`'s shared source is a single position, and this value has three:
+ * `data:`, this block, and the top level. The resolver is the single
+ * implementation of what a note said, so the two systems cannot disagree about
+ * it. It is read against **this** block: the `sohl:` block is not a source for
+ * an HM3 document, so a note that states the priority only there writes no HM3
+ * flag.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - This pass's system block.

package/types/manifest.d.mts

@@ -190,8 +190,9 @@ export function publishedRelationships(relationships: Record<string, unknown>):
  *   a key Foundry adds later needs no release of this package. The one
  *   exception is `descriptionHtml`, folded into the description below rather
  *   than surviving under its own name.
- * - **Derived** — the identity, the description, the release addresses, the
- *   version, the Foundry and system compatibility ranges, and the pack list.
+ * - **Derived** — the identity, the description, the authors (the top-level
+ *   `authors` list without its roles), the release addresses, the version, the
+ *   Foundry and system compatibility ranges, and the pack list.
  *   These are refused if also declared (`description` directly; `descriptionHtml`
  *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged

package/types/release.d.mts

@@ -8,6 +8,10 @@
  * failure is timing-dependent, so it survives every run that happens to be
  * fast enough, which is what makes it worth being explicit about.
  *
+ * **The archive is reproducible.** Entries are written in path order with one
+ * date (`SOURCE_DATE_EPOCH` when set, otherwise 1980-01-01) and fixed
+ * permissions, so a rebuild of one staged tree is byte-identical.
+ *
  * @param {object} [opts]
  * @param {string} [opts.stageDir] - The staged package tree.
  * @param {string} [opts.outDir] - Where the release assets are written.
@@ -15,17 +19,18 @@
  *   Determines both asset names.
  * @param {string} [opts.metadataDir] - Where the build writes its content
  *   index, consulted when the advertised file was not staged.
- * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
+ * @param {boolean} [opts.pdf] - Whether to build the books that ship beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   schema?: string, pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdfs: string[], pdfFindings: object[], pdfSkipped: string|null,
  *   bytes: number, version: string}>} The paths written, what the book build
  *   found, the archive's size, and the version the manifest declares.
  *   `metadata` is absent when the manifest advertises no content index,
- *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
- *   absent when no book was written. `pdfSkipped` is `null` when a book was
- *   built, and otherwise the reason none was — itself `null` when the book
- *   builder could not be loaded, which is reported through `pdfFindings`.
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdfs` is
+ *   every book's PDF that was written, in declared order. `pdfSkipped` is
+ *   `null` when a book was built, and otherwise the reason none was — itself
+ *   `null` when the book builder could not be loaded or a book failed, which
+ *   is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -40,7 +45,7 @@ export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?:
     manifest: string;
     metadata?: string;
     schema?: string;
-    pdf?: string;
+    pdfs: string[];
     pdfFindings: object[];
     pdfSkipped: string | null;
     bytes: number;

package/types/sohl/actors.d.mts

@@ -26,7 +26,8 @@ export class Actors extends SystemActorCompiler {
      * The body's own compiled item is the model, so a membership carries
      * whatever that body declares — its subtype, its common skills, its
      * standings toward others — and the being adds only what is true of *this*
-     * membership: the rung it stands on and the post it holds.
+     * membership: the rung it stands on, the post it holds, and the society it
+     * is held in.
      *
      * A being naming a body that compiles to no item is a finding rather than a
      * silently dropped membership: the note says the being belongs somewhere,

package/types/sohl/document-subtypes.d.mts

@@ -3,8 +3,7 @@
  * becomes.
  *
  * The Item rows are the thirteen types the item registry declares; the one
- * Actor row is `being`, which was two types (`character` and `creature`)
- * compiling to the same actor before they were retired. Types this
+ * Actor row is `being`. Types this
  * map does not name — `doc`, `macro`, the three map types — compile into
  * documents that carry no system subtype at all, so they have no row and never
  * needed one.

package/types/sohl/item-fields.d.mts

@@ -6,13 +6,9 @@ export const COMBAT_TECHNIQUE_STRIKE_MODE: import("../engine/field-spec.mjs").Fi
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
  *
- * **A field whose shared source is a path into `data:` names both positions.**
- * `name` is the source the content format's mapping tables state — `data.seat`,
- * `data.weight` — and `legacyKey` is the key the system block still carries, which
- * wins while a tree writes it. Naming only the source would move the in-block
- * read to a key spelled `data.seat`, which nothing authors; naming only the key
- * leaves the container the specification points at unread, and the field then
- * compiles its default over an authored value with nothing said.
+ * **A field whose shared source is a path into `data:` is authored there and
+ * nowhere else.** `name` is the source the content format's mapping tables
+ * state — `data.seat`, `data.weight`.
  *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */