@heroiclands/package-build 20.3.1 → 20.4.0

package/docs/content-format.md

@@ -80,7 +80,7 @@ A tag that classifies the subject is different, because something queries it. A
 settlement tagged `village` appears in the list of villages and an untagged one
 does not, so `vilage` does not merely look wrong: it removes the note from an
 index, silently, and the index still renders. That is the same failure a
-misspelled `data:` key used to be, and it gets the same answer — the vocabulary
+misspelled `data:` key is, and it gets the same answer — the vocabulary
 is declared, so a near miss is a finding that names what you probably meant.
 
 | group               | applies to             | tags                                                                                                                                                                                                                                                                                                                 |
@@ -146,9 +146,9 @@ the corpus moves, with the block winning. A field says so by naming each: its
 shared source, and the legacy in-block key it is being swept off. Reading it
 from the legacy position is _reported_, so the sweep has a progress signal, and
 the note compiles to the identical document either way — the same read-both,
-report-one shape every other retirement in this format uses. Until #305 the two
-were one declaration, so a field could name only one of them, and a row this
-table stated was reachable only by a note that had already moved.
+report-one shape every other retirement in this format uses. As one
+declaration the two would let a field name only one of them, and a row this
+table states would be reachable only by a note that had already moved.
 
 **A field whose spelling means something else at the note level has no shared
 source.** The fallback assumes the two vocabularies agree about what a name
@@ -166,8 +166,8 @@ them.** A data model declares everything a document stores, and part of that is
 what _play_ writes: an affliction's `onsetDate` is the world time its onset
 fired at. Writing `<system>.system.<field>` reaches such a field as directly as
 any other — the block is a verbatim passthrough, and the field really is in the
-schema — so until #330 a note could stamp one, and the compiled pack shipped one
-world's play state to every world that installed it.
+schema — so a note left free to stamp one ships that world's play state to
+every world that installs the compiled pack.
 
 So a field the document writes for itself is **declared as such**, and the
 declaration says both halves of the fact: authoring it is an error naming the
@@ -225,7 +225,7 @@ is a gap in the vocabulary rather than something to write into every note: an
 override that thousands of notes need is a missing subType value.
 
 **A type's `subType` values are stated in one shape**, so that they can be read
-and compared to the vocabulary that enforces them (#345). Under the type's
+and compared to the vocabulary that enforces them. Under the type's
 heading, write `**subType**:` on a line of its own, then one bullet per value —
 `- <value>` or `- <value>: <definition>` — and nothing else between the marker
 and the list. A type that has no `subType`, or whose values are not enumerated
@@ -295,7 +295,7 @@ at the note's top level and `portrait` moved under `data:`, because a note's
 token art is a fact about the _note as a published artefact_ while the portrait
 is a fact about the _subject_.
 
-**A `data:` source is still read at the top level, for now.** `data:` (#128) did
+**A `data:` source is still read at the top level, for now.** `data:` did
 not invent the facts it holds — it gathered them out of the top level, where
 `portrait:` sat beside `img:` — so every key it collected has a **pre-`data:`
 spelling** that is read after the declared one and reported as retiring. Write
@@ -328,7 +328,7 @@ NA on both sides for that type, and its table says so.
 template priority on an Actor and not on an Item: `hm3/actors.mjs` writes
 `flags.hm3.templatePriority`, and HM3's Item pass writes no equivalent, so an HM3
 item compiled from a template note loses the fact that it is one
-(`HeroicLands/package-build#283`). The row states the mapping the format makes;
+The row states the mapping the format makes;
 the gap is in the pass, not in the table.
 
 #### An asset path's first segment says which package owns it
@@ -449,7 +449,7 @@ The shared mapping table above names it `data.templatePriority`, targeting
 
 > **`archetype` is the retiring spelling.** It is still read, in the `sohl:`
 > block and at the top level, so a tree sweeps on its own schedule
-> (`HeroicLands/package-build#266`) — but the frontmatter linter refuses it, and
+> — but the frontmatter linter refuses it, and
 > what is compiled and emitted is `templatePriority` on all three sides.
 >
 > It is more than a rename, and the collision is **already live** rather than
@@ -481,7 +481,7 @@ real priority** — the one SoHL's own templates ship at — not an absence.
 it.** SoHL records it in `system`; HM3 keeps it under its own flag scope,
 `flags.hm3`, and a note that is not a template writes nothing there rather than a
 `null` nothing reads. Both of HM3's passes write it — an Item's flag was missing
-until `HeroicLands/package-build#283`, which made an item note's priority reach
+until an item note's priority reached
 SoHL and stop at HM3, with nothing said on either side.
 
 **How a winner is chosen.** Opening a Create dialog gathers every candidate
@@ -543,7 +543,7 @@ folder pass for a folder, the journals pass for a documentation journal, this
 rule for everything else. Re-deriving one from the `canonical` key alone reads
 correctly and is wrong for a folder, and wrong in a way nothing outside the
 build can detect: the result is a plausible 16-character id that resolves to
-nothing (#310).
+nothing.
 
 **Why the address and not an authored string.** A note used to declare an
 opaque 16-character `id` — 6,343 of them across the four content trees — which
@@ -674,7 +674,7 @@ the journals pack having to declare anything. A folder nothing references
 materialises nowhere.
 
 That derivation is what makes a whole class of defect unrepresentable. The
-folder used to be declared twice, once per pack, in two files free to disagree:
+folder declared twice, once per pack, sits in two files free to disagree:
 `sohl-thalorna` was missing 57 of its item folders from its journal folder file
 and `sohl-kethira-basic` had no journal folder file at all, so both emitted
 documentation journals into folders their own pack never declared — silently.
@@ -689,7 +689,7 @@ the first.
 
 > **`folder:` was a Foundry id**, resolved against a per-pack
 > `*-folders.yaml` — five files per tree. Both halves are **retired** together
-> (#260): the id spelling has nothing left to resolve against once the YAML is
+> : the id spelling has nothing left to resolve against once the YAML is
 > gone, and the YAML has no reader once the spelling is refused. A note that
 > still writes `folder:` fails the build, naming `packFolder` and the line to
 > rewrite, rather than being ignored — a retired field left ignored reads to
@@ -812,11 +812,11 @@ Only a type whose own document carries a system is redirected this way. A
 documents are core ones already at `none`, so `macro-autoattack` names the Macro
 and `docmacro-autoattack` its journal — two live addresses.
 
-**An address is lowercase throughout** (#340). Every segment — package,
+**An address is lowercase throughout**. Every segment — package,
 system, type and shortcode alike — is `^[a-z0-9]+$`, so a capital anywhere in an
 address is an error naming the lowercase form.
 
-The shortcode was the exception until #340: it was case-sensitive and routinely
+The shortcode is the one that would otherwise be case-sensitive and routinely
 mixed (`Clb`, `LtShoe`, `HsTunic`) while the address built from it was lowercased
 wholesale, so the authored name and its address disagreed. Two names differing
 only in case are two names nobody can tell apart, and they collapsed onto one
@@ -829,9 +829,9 @@ alphanumeric — so the hyphen is purely a separator. There is no longest-match
 against a roster and no vocabulary check before splitting.
 
 **`type` and `subType` are held to that charset, not merely expected to meet
-it** (#206). A type is the first segment of every address, so a hyphen in one is
+it**. A type is the first segment of every address, so a hyphen in one is
 read back as a segment boundary that was never meant as one. A `subType` reaches
-no address since #204 retired sections, but it is held to the same rule all the
+no address, sections being retired, but it is held to the same rule all the
 same: it is a vocabulary term the whole toolchain keys on, one closed set away
 from being an address again, and a charset that holds for two of the three
 segments and half of a fourth is a rule nobody can state. Both are checked
@@ -846,7 +846,7 @@ One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
 is now **`userguide`**. The old spelling was accepted for one transitional
 release, as a warning naming the replacement, so the 43 `sohl` notes authoring
 it were not invalidated by the release that renamed them. Every consumer tree
-has swept, so the acceptance is gone (#210) and `user-guide` is refused by the
+has swept, so the acceptance is gone and `user-guide` is refused by the
 charset check — it contains a hyphen, which is the reason that always applied.
 No retirement-specific code outlived the sweep.
 
@@ -870,17 +870,17 @@ There is one namespace, and the pipe is required:
 | `[[WikiLink\|Text]]` | an address  | `Text`                     |
 | `[[Name]]`           | nothing     | a finding                  |
 
-**A link written without a label addresses nothing** (#180), and the correction
+**A link written without a label addresses nothing**, and the correction
 is always the same: write `[[type-shortcode|Text]]`.
 
-The bare form used to name an **alias** — a note's own display name, or one of
+The bare form does not name an **alias** — a note's own display name, or one of
 the names it listed in `aliases:` — looked up within the citing note's type. It
 was measured before it was retired, and the namespace was empty in practice:
 across 8,305 wikilinks in three content trees, **not one** bare link resolved to
 a note. What the index behind it did do was fold every note's `name.full` into
 itself, so two notes of one type could not share a display name — a rules page
 and a user guide page both called "Gear" were a build failure whose every
-available fix moved a published URL (#179).
+available fix moved a published URL.
 
 The top-level `aliases:` that fed it is **retired** and refused. The nested
 `name.aliases:` is **not**: it is reserved for a use that does not exist yet, so
@@ -901,7 +901,7 @@ page it is written on. It is the label that is required, not a target.
 
 #### Every address resolves, and every build says so the same way
 
-An address that names no note **fails the build** (#184) — in the link checker,
+An address that names no note **fails the build** — in the link checker,
 in the pack compilers and in the site build alike.
 
 It was a warning in the checker and, in the site build, nothing at all while any
@@ -909,21 +909,21 @@ linkable package had no vendored manifest. The reasoning was that `[[Sunless
 Vault]]` might be a placeholder for a note somebody meant to write. That was a
 property of the **bare** form, which is retired, and the intent behind it has a
 real spelling now: a note tagged `draft` exists, resolves, compiles and
-publishes, and a link to it renders visibly marked (#183). So an address landing
+publishes, and a link to it renders visibly marked. So an address landing
 nowhere is a typo or an omission, and both want fixing.
 
 There are six ways a link can fail, and each is one **error** with one message
 wherever it is met:
 
-| finding          | what it means                                   | the fix                                                |
-| ---------------- | ----------------------------------------------- | ------------------------------------------------------ |
-| `unlabelled`     | no `\|`, so the link addresses nothing          | write `[[type-shortcode\|Text]]`                       |
-| `not-an-address` | labelled, but the target is not an address      | write the address, not the name                        |
-| `not-lowercase`  | any segment of the address is capitalised       | lowercase it — every segment is lowercase              |
-| `unknown-type`   | qualified, but names no type this build knows   | correct the type segment                               |
-| `unresolved`     | parses as an address; nothing publishes it      | fix the shortcode, or qualify to reach another package |
-| `ambiguous`      | _unreachable since #336; kept for the manifest_ | —                                                      |
-| `unknown-anchor` | the address resolves; the `#section` does not   | correct the anchor                                     |
+| finding          | what it means                                 | the fix                                                |
+| ---------------- | --------------------------------------------- | ------------------------------------------------------ |
+| `unlabelled`     | no `\|`, so the link addresses nothing        | write `[[type-shortcode\|Text]]`                       |
+| `not-an-address` | labelled, but the target is not an address    | write the address, not the name                        |
+| `not-lowercase`  | any segment of the address is capitalised     | lowercase it — every segment is lowercase              |
+| `unknown-type`   | qualified, but names no type this build knows | correct the type segment                               |
+| `unresolved`     | parses as an address; nothing publishes it    | fix the shortcode, or qualify to reach another package |
+| `ambiguous`      | _unreachable; kept for the manifest_          | —                                                      |
+| `unknown-anchor` | the address resolves; the `#section` does not | correct the anchor                                     |
 
 `ambiguous` no longer fires. An omitted segment defaults rather than wildcarding,
 so a written target expands to one canonical address and a lookup returns one
@@ -1021,10 +1021,10 @@ 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.
 
-That has been true of actors only since #337. A being used to produce its Actor
-and nothing else, which left it the one system-bearing note with no address at
-`none` — so a prose link naming it had nowhere to land. It now carries a
-documentation journal like every other such note, addressed
+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
+such note, addressed
 `<package>-none-docbeing-<shortcode>` beside the Actor's
 `<package>-<system>-being-<shortcode>`.
 
@@ -1116,7 +1116,7 @@ still rendered — the finding is the point, not withholding the output.
 ##### In SQL, over the content index
 
 `dataview` is being replaced by **SQL**, queried over the content index, and both
-fences work while the corpus is converted (#246). The query is real SQL, run by
+fences work while the corpus is converted. The query is real SQL, run by
 DuckDB — not a dialect maintained by this package.
 
 ````markdown
@@ -1148,7 +1148,7 @@ relational operations:
 | `_section` | Emits a headed table per distinct value, in the order the rows arrive. |
 
 `_section` is why one query replaces the forty near-identical blocks a grouped
-table used to need: the authored `ORDER BY` decides the section order too.
+table would otherwise need: the authored `ORDER BY` decides the section order too.
 
 **Beware `packFolder`.** It is a note's _pack_ folder, not its directory — the
 directory is `file.folder`. (The `folder` field it replaced is retired; a query
@@ -1351,7 +1351,7 @@ sohl:
         durability: 0
 ```
 
-**A top-level `shortcode:` is retired** (#334). It selected a template, while the
+**A top-level `shortcode:` is retired**. It selected a template, while the
 `system.shortcode` beside it was the compiled item's identity — one word for two
 things — and it could not say which package a template came from, so an address
 resolved into a dependency only because no local pack claimed it and would have
@@ -1391,7 +1391,7 @@ shortcode)` — compendium/world reconciliation, template shadowing, cohort
 membership, effect and expression references. A `name` cannot stand in: it is
 presentation, free to be localized or to diverge.
 
-**Reordering the list moves no id.** The key used to carry the entry's position,
+**Reordering the list moves no id.** A key carrying the entry's position
 so inserting an item renumbered every id after it and a re-import created new
 documents beside the old ones — while nothing about those documents had changed,
 only their neighbours. The same is now true of a note's journal pages: an
@@ -1612,7 +1612,7 @@ the heading its page is published under; an affiliation's `system.title` is _the
 style of address the office carries_, Ajaw or Warden, which a being holds by
 virtue of its rank. So the top-level key is **not** a shared source for this
 field, and a note that writes one is stating its own heading and nothing else
-(#218). Author the style of address on the membership — the `system.title` of the
+. Author the style of address on the membership — the `system.title` of the
 entry in a being's `sohl.items` — or, on a catalogue note that genuinely carries
 one, at `sohl.system.title`.
 
@@ -2111,11 +2111,11 @@ depicts what it depicts. A place's maps are therefore derived — every map whos
 The three differ only in the canvas defaults derived for them, which is why they
 are subTypes of one type rather than three types.
 
-> The three were **types** until package-build#174, which is the shape the notes
-> in the wild still carry. Both are read: a note still writing `type: battlemap`
-> is reported and told what to write instead, exactly as a note writing
-> `type: character` is (SoHL#1580). A consumer's `sections` config keys off the
-> type, so it takes one `map` entry where it carried three.
+> The three are also readable as **types**, which is the shape notes in the
+> wild still carry: a note writing `type: battlemap` is reported and told what
+> to write instead, exactly as a note writing `type: character` is. A
+> consumer's `sections` config keys off the type, so it takes one `map` entry
+> rather than three.
 
 **NoteLocation** is `[GridLocation, anchor]` where the `anchor` is an anchor identified in the body of the note, and `GridLocation` represents a particular grid location on the document.
 
@@ -2153,24 +2153,13 @@ compilation, and the server-side migration shim is version-gated on
 single Level is synthesised from `img`, `overlay`, `levelName` and
 `backgroundColor`.
 
-> **`img`, at the note's top level, as every other type's artwork is.** A map
-> alone named it `image` and read it out of the `sohl:` block, so one idea had
-> two spellings and this table had to hedge rather than state a rule
-> ([package-build#142](https://github.com/HeroicLands/package-build/issues/142)).
-> Art is not system-specific — a Scene is a core Foundry document, and a second
-> system would want the identical art — so the field sits beside every other
-> note's `img` rather than inside a system block.
+> **`img`, at the note's top level, as every other type's artwork is.** Art is
+> not system-specific — a Scene is a core Foundry document, and a second system
+> would want the identical art — so the field sits beside every other note's
+> `img` rather than inside a system block.
 >
-> `image` was **retired in favour of it**, in the three steps `package:` took
-> (#56), and all three have now run
-> ([package-build#149](https://github.com/HeroicLands/package-build/issues/149)).
-> Through the window both spellings were read, `img` won where a note carried
-> both, and a note still writing `image` got a located **warning** rather than a
-> refusal — it compiled to the byte-identical document, so failing a build over
-> it would have redded a tree that had done nothing wrong. The trees were then
-> swept, and the alias dropped. `image` is now simply not a key a map has: in a
-> `sohl:` block it is reported as unknown, and either way the note is refused
-> for the `img` it never declared.
+> `image` is **not a key a map has**: in a `sohl:` block it is reported as
+> unknown, and either way the note is refused for the `img` it never declared.
 
 **Two unit conventions, deliberately.** Geometry — walls, doors, lights, tiles,
 sounds, region shapes — is authored in **pixels**, Foundry's native storage,
@@ -2289,8 +2278,8 @@ way (`homepage-root`).
 
 There is no landing page and no section. A `README.md` used to _be_ its
 section's landing, and a `subType: collection` note with a top-level `section:`
-key was a second way to say the same thing. All of it is retired — the second
-rule in #202, the first in #204 — because a section appears in **no address**: a
+key was a second way to say the same thing. All of it is retired, because a
+section appears in **no address**: a
 page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
 section is what Hugo calls a content directory, and the note format does not
 carry one.
@@ -2440,7 +2429,7 @@ an Adventure pack declared first still compiles last.
 
 Foundry's `Folder` — the grouping documents are filed in, and the last document
 this package compiled from bespoke configuration (`*-folders.yaml`, five files
-per tree) rather than from a note. Those files are retired (#260); a pack that
+per tree) rather than from a note. Those files are retired; a pack that
 still names one is refused.
 
 ```yaml
@@ -2519,4 +2508,4 @@ the namespace is **`folder`**, not the `document` one [every other note hashes
 under](#the-document-id): a folder and an item sharing a shortcode would
 otherwise derive the same id, and Foundry keys the two in separate collections
 so neither would complain. The content index publishes this value, so a consumer
-reads a folder's id rather than recomputing one (#310).
+reads a folder's id rather than recomputing one.

package/e2e.mjs

@@ -19,7 +19,7 @@
  * of labour here. Standing a licensed Foundry up, seeding a world whose
  * Gamemaster password is known, waiting for that world to be *active* rather
  * than merely reachable, tearing it all down again — none of that is one
- * repository's problem, and all of it used to live in one. What runs against
+ * repository's problem, and none of it lives in one. What runs against
  * the served world is named in `packageBuild.e2e.suite`, the same way an asset
  * transform or a manifest-flags module is named: the repository's code, the
  * toolchain's plumbing.
@@ -685,7 +685,7 @@ export function findExecutable(name, { cwd, env = process.env } = {}) {
  *
  * Asked twice per run, and the second asking is the point: an install running
  * alongside the suite can take the runner out from under it mid-flight, which
- * is precisely the failure that reported itself as green (#153).
+ * is precisely the failure that reported itself as green.
  *
  * @param {object} opts
  * @param {readonly string[]} opts.command - The program and its arguments.
@@ -766,7 +766,7 @@ export function freshResults({ paths, since, cwd }) {
  * exit status on its own cannot call a run green, because every way of stopping
  * a runner before it starts — a corrupt install, a missing browser, a killed
  * process, the concurrent `npm ci` that surfaced this — produces a run that
- * executed nothing, and nothing is not a pass (#153).
+ * executed nothing, and nothing is not a pass.
  *
  * This can only ever make a verdict worse. A suite that failed keeps its own
  * status; a suite that passed on no evidence loses the claim. Never the other
@@ -814,7 +814,7 @@ export function suiteVerdict({ status, vanished = [], declared = [], fresh = []
  * `MODULE_NOT_FOUND` naming nothing relevant.
  *
  * The suite is bracketed by checks rather than trusted on its exit status,
- * because a run that never started used to report as green (#153):
+ * because a run that never started used to report as green:
  *
  * - **Before.** Every executable the command needs is resolved, and a missing
  *   one is an error naming it — rather than a container stood up, a world

package/engine/actor-compiler.mjs

@@ -13,14 +13,13 @@
 
 /**
  * **The Actor pass, for any system** — the parts of compiling a note into a
- * Foundry Actor that belong to the note format rather than to a game system
- * (#139).
+ * Foundry Actor that belong to the note format rather than to a game system.
  *
  * The whole of it lived in `sohl/actors.mjs`, where the system-specific facts
- * were already funnelled through one map (`static documentSubtypes`, added by
- * #79) and one block constant. A second system needs everything except the
- * shape of the `system` block itself, so that everything moved here and each
- * half declares what differs:
+ * were already funnelled through one map (`static documentSubtypes`) and one
+ * block constant. A second system needs everything except the shape of the
+ * `system` block itself, so all of it lives here and each half declares what
+ * differs:
  *
  * | stated by the subclass | what it decides |
  * | --- | --- |
@@ -35,7 +34,7 @@
  * - **Reference translation.** A being addresses its embedded items in the
  *   *note* vocabulary and the catalogue is keyed in the *document's*, so
  *   {@link SystemActorCompiler#embeddedSubtype} translates each reference
- *   forward through this system's map before the lookup (#140).
+ *   forward through this system's map before the lookup.
  * - **Embedding.** Merging a note's overlay onto a catalogue entry, deriving a
  *   stable embedded id from the owning actor and the address, and re-keying the
  *   embedded document and its effects for the LevelDB flattening.
@@ -60,15 +59,15 @@ import { BasePackCompiler } from "./base-compiler.mjs";
 import { contentPackage } from "./content-package.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into, and which note
 // types are actors at all. Looked up in the system's declared map, never
-// inferred from the type itself (#79).
+// inferred from the type itself.
 import { mapsNoteType, noteTypesFor, referencedSubtype } from "./document-subtypes.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 // An `items:` entry's `system:` overlay is merged verbatim, so it reaches the
-// document by a path no field declaration sits on — including, until #330, the
+// document by a path no field declaration sits on — including the
 // fields the document is supposed to write for itself in play.
 import { itemFields } from "./item-registry.mjs";
 import { runtimeOnlyIn, runtimeOnlyMessage } from "./runtime-only-fields.mjs";
-// A `model:` is an address, read by the same grammar every wikilink is (#336),
+// A `model:` is an address, read by the same grammar every wikilink is,
 // so an author writes one form and meets one set of messages.
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -132,7 +131,7 @@ export function deepMerge(base, overlay) {
  * vocabulary, so a reference is translated forward through the system's map
  * before it reaches this function; see
  * {@link SystemActorCompiler#embeddedSubtype} for why the translation goes that
- * way and not the other (#140).
+ * way and not the other.
  *
  * @param {string} subType - The Foundry Item subtype.
  * @param {string} shortcode - The item's `system.shortcode`.
@@ -144,7 +143,7 @@ export function itemAddress(subType, shortcode) {
 
 /**
  * The key one predefined item is held under **for the package that publishes
- * it** — the address a `model:` naming that package resolves through (#334).
+ * it** — the address a `model:` naming that package resolves through.
  *
  * The unqualified {@link itemAddress} stays beside it, and the two answer
  * different questions. A `model` that names no package means *this* one and
@@ -174,11 +173,12 @@ export function packagedItemAddress(pkg, subType, shortcode) {
  * A shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
  * `HsTunic` — while an **address** is not: `readQualifier` normalises what it
  * reads, and every canonical address is lowercase. So the moment a `model:` is
- * read as an address (#334), `weapongear-clb` has to find the document whose
- * `system.shortcode` is `Clb`, and an exact match cannot (#346).
+ * read as an address, `weapongear-clb` has to find the document whose
+ * `system.shortcode` is `Clb`, and an exact match cannot.
  *
  * Folding is safe because the fold is already the address: no two items in any
- * published tree differ only by the case of their shortcode, and #340 will make
+ * published tree differ only by the case of their shortcode, and the rule
+ * makes
  * that impossible rather than merely true.
  *
  * **This is not {@link itemAddress}, and must not become it.** That one seeds
@@ -229,13 +229,13 @@ export function embeddedIdentity(item) {
  * four corpora holds 180 items, at which 64 bits collide with probability
  * around 10⁻¹⁵.
  *
- * **It takes no index** (#268). Keying on a position meant reordering a being's
+ * **It takes no index**. Keying on a position meant reordering a being's
  * item list renumbered every id after the change, so a re-import created new
  * documents beside the old ones — while nothing about those documents had
  * changed, only their neighbours. The identity always exists or must be stated;
  * see {@link embeddedIdentity}.
  *
- * Keyed by the **document subtype**, so renaming a note type (#78) leaves every
+ * Keyed by the **document subtype**, so renaming a note type leaves every
  * embedded id where it was.
  *
  * @param {string} actorId - The owning actor's id.
@@ -277,7 +277,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
     const shadowed = [];
     for (const itemsSourceDir of itemsSourceDirs) {
         if (!fs.existsSync(itemsSourceDir)) {
-            // The generator orders the actors pass after every Item pass (#73),
+            // The generator orders the actors pass after every Item pass,
             // so a whole-package build cannot reach this. What can is a run
             // restricted to this one pack, or a caller constructing the
             // compiler itself — neither of which reordering a pack list fixes,
@@ -321,13 +321,13 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             const { _key, ...rest } = doc;
             map.set(address, rest);
             // And under this package's own name, so a `model:` that names this
-            // package explicitly resolves to the same item (#334).
+            // package explicitly resolves to the same item.
             map.set(catalogueKey(doc.type, shortcode, contentPackage()), rest);
         }
     }
     for (const foreignEntry of foreignSourceDirs) {
         // Each dependency's directory arrives with the package that published
-        // it (#334), so a foreign template gets its own canonical address
+        // it, so a foreign template gets its own canonical address
         // rather than sharing the local address space.
         const foreignDir = typeof foreignEntry === "string" ? foreignEntry : foreignEntry.dir;
         const foreignPackage = typeof foreignEntry === "string" ? null : foreignEntry.package;
@@ -352,7 +352,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             // eslint-disable-next-line no-unused-vars
             const { _key, ...rest } = doc;
             // Its own package-qualified address, which a `model:` naming that
-            // package resolves through and nothing local can shadow (#334).
+            // package resolves through and nothing local can shadow.
             if (foreignPackage) {
                 map.set(catalogueKey(doc.type, shortcode, foreignPackage), rest);
             }
@@ -411,8 +411,8 @@ export class SystemActorCompiler extends BasePackCompiler {
      * because {@link SystemActorCompiler#resolveEmbedded} is called per entry
      * and has no note lifecycle of its own.
      *
-     * `frontmatter-lint.mjs` makes the same finding from frontmatter alone
-     * (#228), and this does not replace it — the lint is a separate command, so
+     * `frontmatter-lint.mjs` makes the same finding from frontmatter alone,
+     * and this does not replace it — the lint is a separate command, so
      * without a check here a colliding pair would compile to two documents with
      * one `_id` and reach the LevelDB packer as an opaque duplicate key.
      *
@@ -422,12 +422,12 @@ export class SystemActorCompiler extends BasePackCompiler {
 
     // An actor's embedded items are resolved against the *output* of the item
     // passes, so every Item pack compiles before this one. Declared rather than
-    // left to the order `packs:` happens to list (#73).
+    // left to the order `packs:` happens to list.
     static readsPackOutputOf = Object.freeze(["Item"]);
 
     /**
      * An Actor **is** a system's data, so this pack takes only notes carrying
-     * this system's block (#58).
+     * this system's block.
      */
     static requiresSystemBlock = true;
 
@@ -449,7 +449,7 @@ export class SystemActorCompiler extends BasePackCompiler {
 
     /**
      * Every package a `model:` may name besides this one — the dependencies
-     * whose item catalogues were supplied (#334).
+     * whose item catalogues were supplied.
      *
      * @returns {Set<string>} The dependency package ids.
      */
@@ -465,10 +465,10 @@ export class SystemActorCompiler extends BasePackCompiler {
         super(options);
         // Where the items passes wrote their JSON. Stated by the caller rather
         // than assumed to be this pack's sibling: the packs' locations are
-        // configuration, and a consumer may put them anywhere (#1508). Every
-        // Item pack, because a repository may ship more than one (#1566).
+        // configuration, and a consumer may put them anywhere. Every
+        // Item pack, because a repository may ship more than one.
         //
-        // **Optional, and empty is a legitimate package (#49).** This used to
+        // **Optional, and empty is a legitimate package.** This used to
         // throw unless at least one Item pack was declared, which asked a
         // package to declare the very thing it may exist not to have. An Item
         // pack is system-bound by construction — Foundry requires `system` on
@@ -560,7 +560,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The Foundry Item subtype an embedded reference's `type` addresses.
      *
      * **The reference is in the note vocabulary; the address is in the
-     * document's** (#140). An actor writes `(type, shortcode)` with the type an
+     * document's**. An actor writes `(type, shortcode)` with the type an
      * author authors, while {@link itemAddress} keys the predefined items by
      * the subtype each compiled document carries — so exactly one of the two
      * sides has to translate, and it is this one. The system's map is a
@@ -583,7 +583,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      * descriptor must carry enough fields to stand alone. The embedded
      * item's `_id` is regenerated deterministically from
      * `(actorId, subType, shortcode, indexKey)` so re-exports are stable —
-     * from the **document subtype**, so that renaming a note type (#78) leaves
+     * from the **document subtype**, so that renaming a note type leaves
      * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
      *
@@ -594,7 +594,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   `null` for a stand-alone entry.
      * @param {object} [overlay] - The entry's remaining properties.
      * @param {string} indexKey - Where the reference sits, for a diagnostic.
-     *   It no longer reaches the id (#268) — it names the entry in a message.
+     *   It no longer reaches the id — it names the entry in a message.
      * @param {string} ctx - Diagnostic context (the actor's label).
      * @param {object} [at] - Where to locate a finding.
      * @param {string} [at.fmKey] - The frontmatter key the reference sits
@@ -606,7 +606,7 @@ export class SystemActorCompiler extends BasePackCompiler {
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *
-     * The address grammar is the wikilink one (#336), so a `model` is written at
+     * The address grammar is the wikilink one, so a `model` is written at
      * whatever length says what it means: `skill-wpnc` within this package,
      * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
      * the block the entry sits in — `<system>.items` — which is what makes the
@@ -615,7 +615,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      *
      * It replaced a top-level `shortcode:` that meant something different from
      * the `system.shortcode` beside it and could not say which package a
-     * template came from (#334).
+     * template came from.
      *
      * @param {unknown} model - The authored value.
      * @param {number} index - The entry's position, for the message.
@@ -675,7 +675,7 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        // A `model:` may name the package its template comes from (#334). Where
+        // A `model:` may name the package its template comes from. Where
         // it does, the packaged address is used and nothing local can shadow
         // it; where it does not, the unqualified one is, and a local definition
         // still wins over a dependency's as it always has.
@@ -687,7 +687,7 @@ export class SystemActorCompiler extends BasePackCompiler {
 
         // The entry's `system:` overlay is merged verbatim, so it reaches the
         // document without passing a single field declaration — which left it
-        // the one position a runtime-only field stayed authorable at once #330
+        // the one position a runtime-only field would stay authorable at once
         // closed the item note's own. Asked of the **overlay** rather than of
         // the merged result: the template it merges onto is a compiled
         // document, which by then carries none, and a finding has to name what

package/engine/address-charset.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The one charset every segment of a canonical address is held to (#59).
+ * The one charset every segment of a canonical address is held to.
  *
  * An address is a hyphen-joined tuple — `package-system-type-shortcode`, so
  * `sohl-none-doc-gear` — and it is read back by **counting segments**, with a
@@ -43,7 +43,7 @@
  * digits only.
  *
  * Case *was* deliberately unconstrained, on the reasoning that case has no
- * bearing on the separator — which is true, and beside the point (#340).
+ * bearing on the separator — which is true, and beside the point.
  *
  * **Two names that differ only in case are two names nobody can tell apart.** A
  * shortcode is how a person names a thing when writing a reference —
@@ -55,10 +55,10 @@
  * `sohl-sohl-weapongear-clb` and its `_id` derived from that. The authored name
  * and its address disagreed, and everything downstream keys on the address —
  * which left two notes differing only in case sharing one address, one `_id` and
- * one URL, with nothing to report it. It also forced two exceptions elsewhere:
- * #336 had to exempt the shortcode from the lowercase rule it pinned on every
- * other segment, and #346 had to fold the shortcode's case in the item catalogue
- * because an address is lowercased when read.
+ * one URL, with nothing to report it. It also forces two exceptions elsewhere:
+ * the shortcode has to be exempted from the lowercase rule pinned on every
+ * other segment, and its case has to be folded in the item catalogue because
+ * an address is lowercased when read.
  *
  * One case, one spelling, no exceptions. Every tree already complies but two,
  * and nothing in any of them collides when folded.