@heroiclands/package-build 13.0.0 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # @heroiclands/package-build
 
+## 14.0.0
+
+### Major Changes
+
+- a0a113b: **`publish.address.landing` is deleted.** `prefix` is the whole address scheme:
+  
+  ```yaml
+  publish:
+    address:
+      prefix: kb/ # default: "" — the package root
+  ```
+  
+  The key named which note addressed a whole section rather than a page within
+  one. #202 retired the second of its two rules and #204 retired the concept both
+  rules chose between — a section is a Hugo content directory the note format does
+  not carry, a page's address names no directory, and so no note lands one. What
+  survived was the key itself: resolved, refused-by-name for the retired value,
+  checked against a one-element vocabulary, frozen into the configuration, and
+  read by nobody. `LANDING_RULES` said so in its own doc comment — _"Inert since
+  #204."_
+  
+  **A configuration still declaring it is refused, at the line it is written on.**
+  Not reported as an unrecognized option, which names a spelling to correct and
+  leaves the author to work out that the mechanism is gone:
+  
+  ```text
+  package-build.config.yaml:14:9: error: package-build config:
+  `publish.address.landing` is a retired option — delete it. It named which note
+  addressed a whole section rather than a page within one, and there are no
+  sections to address: a section is a Hugo content directory the note format does
+  not carry, so no note lands one and every page is addressed
+  `<type>-<shortcode>`. Nothing replaces it.
+  ```
+  
+  Presence is the whole test, as it is for a retired frontmatter field: no value
+  makes declaring it right, so `readme` and the already-retired `collection` are
+  refused alike, by `RETIRED_ADDRESS_KEYS` — the configuration-side twin of
+  `engine/retired-fields.mjs`.
+  
+  **Why the key outlived its mechanism by one release.** `content-config.mjs` has
+  no warning channel — every finding goes through `fail()`, which throws — so
+  while both publishing consumers still declared the then-true `landing: readme`
+  the only options were to break them over a correct statement or to accept the
+  key in silence, and silent acceptance is what this codebase refuses everywhere
+  else. So it took the three steps `package:` took (#56): retire the value, have
+  consumers drop the key, delete the key. No consumer declares it now.
+  
+  **The plumbing goes with it.** `packageAddress` took an address scheme only to
+  validate the `landing` rule it then discarded — its own docstring already said
+  the `prefix` half never applied, because an address is `(type, shortcode)`, a
+  package-wide identity that takes no mount. It is now a function of the
+  frontmatter and nothing else, and `manifestContext` no longer carries a `scheme`
+  that nothing reads.
+  
+  | Removed                                                                                                                              | Where                        |
+  | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+  | `LANDING_RULES`, `RETIRED_LANDING_RULES`                                                                                             | `content-config.mjs`         |
+  | `DEFAULT_ADDRESS_SCHEME.landing`, `ADDRESS_KEYS`' second entry, `normalizePublish`'s resolve-and-check, `AddressSchemeInput.landing` | `content-config.mjs`         |
+  | The `LANDING_RULES` re-export, `packageAddress`'s `{ scheme }` parameter and its landing check                                       | `engine/content-address.mjs` |
+  | `manifestContext`'s `scheme`, and the argument `collectManifestEntries` passed on with it                                            | `engine/manifest-emit.mjs`   |
+  
+  **Nothing a consumer emits moves.** Verified against pristine
+  `git archive origin/main` extractions of all three consumers, before and after:
+  `lint`, `links`, `manifest`, `package compile` and `site` produce **identical
+  console output, line for line**, and every emitted file is byte-identical —
+  31,197 files across the three trees, with only LevelDB's own timestamped `LOG`
+  differing. `sohl` stays green (2,988 manifest entries, 3,125 pack documents,
+  1,671 emitted pages); `sohl-thalorna` stays exactly as red as it was for its own
+  content gap (1,983 lint findings, 122 link findings); `sohl-kethira-basic` stays
+  green.
+  
+  Closes #215
+- 98ac362: **`subType: user-guide` is refused.** #206 renamed the `doc` subType
+  `user-guide` to `userguide` and held every `type` and `subType` to the address
+  charset, but shipped a **transitional acceptance** for the old spelling — a
+  warning naming the replacement rather than a refusal — because 43 `sohl` notes
+  authored it and no consumer can sweep ahead of the release that renames a value.
+  Every consumer tree has now swept: `sohl` **0**, `sohl-thalorna` **0**,
+  `sohl-kethira-basic` **0**, counted on a pristine extraction of each
+  `origin/main`. So the acceptance guards nothing, and this is the follow-up #207
+  named.
+  
+  `RETIRED_SUBTYPES`, `retiredSubType()` and `retiredSubTypeMessage()` are gone
+  from `engine/note-vocabulary.mjs`, along with the retired-spelling branch that
+  ran ahead of the charset check in `checkSubType`. Nothing replaces them:
+  `user-guide` now falls through to the **charset** check and is refused as an
+  error, for the reason that always applied — it contains a hyphen. That is why
+  the acceptance could be deleted rather than promoted to an error: the permanent
+  rule already covers the case, so no retirement-specific code outlived the sweep.
+  
+  **Breaking**, though the diff only removes code. A spelling that built at exit 0
+  one release ago now fails the build, and three exported symbols no longer exist.
+  A tree that has swept sees no change at all — which all three consumers have,
+  and each was verified unaffected.
+  
+  **The subType charset diagnostic is reworded.** It justified the rule by "the
+  hyphen separates the segments of an address", true of a `subType` when #206
+  shipped — `sectionOf` returned a `doc`'s subType, so the value was a URL path
+  segment — and not true since #204 retired sections. The rule stands on its own
+  footing instead: a subType is a vocabulary term the whole toolchain keys on, one
+  closed set away from being an address segment again, and a charset holding for a
+  type, a shortcode and a `contentPackage` but not for a subType would be a rule
+  nobody could state in a sentence. `typeCharsetMessage` is untouched — a type
+  genuinely is the first segment of every address.
+  
+  The same correction is applied to `assertVocabularyCharset`'s throw, which
+  carried the identical claim in a second place — _"A type and a subType are both
+  address segments"_ — where it would go unread until it fires, which is exactly
+  when it would be taken at face value. It now states the reason **per key**: the
+  address half for a type, the vocabulary-term half for a subType. The guard
+  itself is unchanged and stays where it is, running over `NOTE_VOCABULARY` as the
+  module loads.
+  
+  Closes #210
+
+### Minor Changes
+
+- 45b5bd0: **A section can say what it lists.** `site.sections` / `site.readmeSections`
+  take two more keys, `listType` and `listSubType`, and both reach the generated
+  `_index.md`:
+  
+  ```yaml
+  sections:
+    weapongear: { title: Weapons, listType: weapongear }
+    user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+  ```
+  
+  Since #204 a content page is written flat under the mount, so a declared
+  section's directory holds nothing but the landing this build writes for it and a
+  layout reading Hugo's `.Pages` finds no members. The membership survives in the
+  `site.sections` map and in nothing a theme can read — not on the page, not on
+  the landing, not in any URL — so every section landing served by a generic list
+  layout renders empty. `sohl` was unaffected only because its eleven catalog
+  layouts already query `site.RegularPages` by `Params.type`; a consumer rendering
+  through the shared theme has no layout of its own to edit. The landing now
+  states that query and the theme runs it
+  (HeroicLands/heroiclands-hugo-theme#50).
+  
+  **Two keys of their own, not `type` / `subType`.** On an `_index.md`, `type` is
+  Hugo's own layout selector: verified against Hugo 0.165, a section landing
+  carrying `type: doc` renders through `layouts/doc/list.html` rather than the
+  default list template — behaviour this build already relies on deliberately, for
+  the mount's own `landing`. Spelling the content type there would silently change
+  which template serves the landing.
+  
+  **Two keys added to the closed set, not an open passthrough.** `site.landing` is
+  passed through unvalidated because it is written once, for the mount, in one
+  landing template's own vocabulary; a section entry is written fourteen to twenty
+  times per build against a contract every package and every section shares.
+  Unbounded there, a mistyped `listTpye:` would publish into front matter, list
+  nothing, and report no error — which is the bug being fixed, moved one step
+  downstream where no build can see it. `normalizeSectionMeta` stays the one place
+  the vocabulary is bounded, and the writers still name no keys.
+  
+  **Both values are checked, because both ways of writing an inert declaration are
+  silent.** They name a content type and subType, so each must be an address
+  segment (`^[A-Za-z0-9]+$`), and a `listSubType` with no `listType` is refused —
+  a subType tells pages apart only within a type, so alone it names no query. The
+  charset check is the trap this came from: a section is named for a URL the site
+  chose and need not match the address (`/sohl/kb/user-guide/` is the section,
+  `userguide` the subType, #207), and copying the section's name in would match no
+  page at exit 0. All three refusals are located at the offending key:
+  
+  ```text
+  package-build.config.yaml:504:90: error: package-build config:
+  `site.sections.user-guide.listSubType` is `user-guide`, which is not
+  alphanumeric. …
+  ```
+  
+  **Additive.** A section that declares neither key emits exactly the bytes it
+  did before. Verified on a pristine `origin/main` extraction of `sohl`, the only
+  consumer running `content-build site` with declared sections: 1670 emitted files
+  byte-identical, and with the keys declared on two of its nineteen sections
+  exactly those two `_index.md` files change.
+  
+  Closes #212
+
 ## 13.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -138,7 +138,6 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
-    landing: readme
 
 # How this repository frames the website `content-build site` publishes.
 # Framing only: addresses come from `publish.address` above.
@@ -806,15 +805,15 @@ rule is checked ahead of the closed-set check, which is what makes it reach a
 type whose values are declared but not yet enumerated:
 
 ```text
-assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. …
+assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. …
 ```
 
 One declared value broke that rule: a `doc`'s `user-guide`, now **`userguide`**.
-The old spelling is accepted for one transitional release and reported as a
-**warning** naming the replacement — an error would red every tree that took the
-release before it had a chance to sweep, and the note still compiles to the
-correct page. A later release removes the acceptance, and the old spelling then
-falls through to the ordinary undeclared-value error.
+The old spelling was accepted for one transitional release, as a warning naming
+the replacement, because an error would have redded every tree that took the
+release before it had a chance to sweep. Every tree has swept, so the acceptance
+is gone (#210): `user-guide` is refused by the charset check like any other
+hyphenated value, and nothing retirement-specific was left to remove.
 
 The vocabulary lives in `engine/note-vocabulary.mjs`, one entry per note type,
 taken from the content-format specification. It is note-format knowledge rather
@@ -1247,9 +1246,8 @@ per section, and that is now the _only_ thing that makes one exist — see
 
 ### The address scheme
 
-Where the content tree mounts _inside the package_, and which note addresses a
-whole section rather than a page within one, differ between repositories and are
-both load-bearing. They are one setting, read by this command **and** by the page
+Where the content tree mounts _inside the package_ differs between repositories
+and is load-bearing. It is one setting, read by this command **and** by the page
 emitter, so the address a manifest publishes is the address a page is emitted at
 — stating it twice is how a manifest comes to assert a URL that resolves at build
 time and 404s for the reader.
@@ -1260,7 +1258,6 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
-    landing: readme # inert since #204; still accepted
 ```
 
 - **`prefix`** — the content tree's mount within the package: the Hugo directory
@@ -1270,14 +1267,9 @@ publish:
   content, so it has no prefix. It must end in a slash and must not begin with
   one — where the _package_ is mounted is the consuming build's knowledge and is
   never recorded here.
-- **`landing`** — **inert, and accepted only so it keeps loading.** It named
-  which note addressed a whole section rather than a page within one. There are
-  no sections in the note format (#204) and so no landings, so it selects
-  nothing; it is still accepted because both publishing consumers declare
-  `landing: readme` and refusing a correct statement would break them. It is
-  removed once no configuration writes it. The retired second rule, `collection`,
-  is still refused by name (#202), along with the `collection` subtype and the
-  top-level `section:` key.
+
+`prefix` is the whole scheme. The `collection` subtype and the top-level
+`section:` key are refused by name (#202).
 
 A note's `subType` is checked against the values its type declares, and only
 those. It briefly had a second reading — a `README` landing's `subType` was the
@@ -1431,7 +1423,8 @@ Two consequences follow, and neither is optional:
   `_index.md`, so a layout reading `.Pages` finds nothing. A layout that queries
   `site.RegularPages` by `Params.type` is unaffected, and that is the shape a
   content catalog wants anyway — it groups by what a page _is_, not by where its
-  file happened to be written.
+  file happened to be written. A section that wants that query run for it says
+  so with `listType` — see below.
 
 Whatever the entry may carry is the whole of what the section can say.
 
@@ -1440,18 +1433,63 @@ Whatever the entry may carry is the whole of what the section can say.
 | `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
 | `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
 | `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
+| `listType`    | no       | The content **type** whose pages this section lists.                      |
+| `listSubType` | no       | Narrows that to one **subType**. Only with a `listType`.                  |
 
-`readmeSections` takes the same three, for a **`trees`** entry: those pages keep
+`readmeSections` takes the same keys, for a **`trees`** entry: those pages keep
 their source layout below a named section, so the tree's own `README.md` is that
 section's landing. What the section declares wins over what the `README` happens
 to carry — the landing has to match the card that links to it. No content note
 reaches this map any more.
 
+#### Saying what a section lists
+
+A generic list layout has nothing to render, because the membership a section
+landing used to get free from Hugo's page tree no longer exists anywhere the
+theme can read: not on the page, not on the landing, not in any URL — only here.
+So a section states its own query, and a layout substitutes it when `.Pages` is
+empty:
+
+```yaml
+sections:
+  being: { title: Beings, listType: being }
+  rules: { title: Rules, listType: doc, listSubType: rules }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
+
+emits, for the last of those, `user-guide/_index.md`:
+
+```yaml
+---
+title: User Guide
+listType: doc
+listSubType: userguide
+---
+```
+
+Three things about the spelling, each of them load-bearing:
+
+- **Not `type`.** On an `_index.md` that is Hugo's own layout selector — a
+  landing carrying `type: doc` is rendered by `layouts/doc/list.html` rather
+  than the default list template — so writing the content type there would
+  silently change which template serves the landing. This build already relies
+  on that behaviour for the mount's own `landing`.
+- **Not inferred from the section's name.** A section is named for a URL the
+  site chose; a type and a subType are addresses. They need not agree, and on
+  `sohl` they do not: the section is `user-guide`, because that is a published
+  URL, while the subType is `userguide` because an address segment is
+  alphanumeric (#207). Both values are checked against that charset here, so
+  copying the section's name in is refused rather than quietly matching nothing.
+- **`listSubType` needs a `listType`.** A subType only tells pages apart within
+  a type — `rules`, `userguide` and `reference` are all `doc` — so alone it
+  names no query.
+
 **The vocabulary is closed, and a key outside it is refused by name:**
 
 ```text
 package-build config: `site.sections.affliction.descrption` is not a
-recognized option (expected one of: title, banner, description).
+recognized option (expected one of: title, banner, description, listType,
+listSubType).
 ```
 
 That refusal is the point. `landing` is passed through unvalidated because it is
@@ -1460,7 +1498,10 @@ entry is written fourteen to twenty times per build against a contract every
 package and every section shares, so an unbounded one would let a mistyped
 `descrption:` publish into front matter, be read by nobody, and say nothing to
 anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
-buys a build that cannot quietly emit a key no theme reads.
+buys a build that cannot quietly emit a key no theme reads. `listType` and
+`listSubType` are that growth: two named keys, checked, rather than an open
+passthrough in which `listTpye:` would publish and no landing would list
+anything.
 
 The **writers** name no keys: a section's `_index.md` is whatever the entry
 resolved to, `title` first. So extending the vocabulary is a change to the
@@ -1624,7 +1665,7 @@ path now rides on the error, and the loader that read the file resolves it
 against the YAML, so all of them come out located:
 
 ```text
-package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner).
+package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner, description, listType, listSubType).
 ```
 
 The same two rules apply. A key the file never declares — a required one that is

package/MIGRATING.md

@@ -49,12 +49,18 @@ That is the shape a content catalog wants regardless — it groups by what a pag
 _is_ rather than by where its file happened to be written — and it is what
 `sohl`'s catalog layouts already do.
 
-## 4. `publish.address.landing` is inert, and still accepted
+A site rendering through a **shared theme** has no layout of its own to edit. As
+of 13.1.0 the section declares its query instead, and the theme runs it:
 
-It named which note addressed a whole section. There are no landings, so it
-selects nothing; `landing: readme` keeps loading because it stated something true
-when it was written, and the key is removed once no configuration declares it.
-`landing: collection` is still refused by name (#202).
+```yaml
+sections:
+  weapongear: { title: Weapons, listType: weapongear }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
+
+`listType` is the content type, not the section's name — the two need not agree,
+and `listSubType` narrows a type whose genres share it. See
+[What a section may declare](CONTENT.md#what-a-section-may-declare).
 
 ## What did not change
 

package/content-config.mjs

@@ -68,7 +68,7 @@ import path from "node:path";
 
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
-import { isAddressSegment } from "./engine/address-charset.mjs";
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
 
 /**
@@ -116,44 +116,37 @@ export const PACK_DOCUMENT_TYPES = /** @type {const} */ ([
 ]);
 
 /**
- * The landing-page rules a repository may route by. **Inert since #204.**
- *
- * A *landing page* was a note that addressed a whole section rather than a page
- * within one, so it had no slug of its own. There are no sections in the note
- * format any more — a section is a Hugo content directory, and a page's address
- * names no directory — so there are no landings and this selects nothing.
- *
- * The key survives its own mechanism on purpose. Both publishing consumers
- * declare `landing: readme`, which stated something true when they wrote it;
- * refusing it now would break them over a correct statement, and silently
- * ignoring an unknown value would be worse. So `readme` stays accepted, the
- * retired `collection` stays refused by name (below), and the key is deleted
- * once no configuration writes it — `content-config.mjs` has no warning channel
- * with which to say "accepted, and does nothing" in between.
- *
- * @type {readonly string[]}
- */
-export const LANDING_RULES = Object.freeze(["readme"]);
-
-/**
- * What a configuration naming the retired `collection` landing rule is told.
- *
- * A retired *value* is refused the way a retired *field* is (see
- * `engine/retired-fields.mjs`): left merely unrecognized it would be reported
- * as a bad value, which names something to correct and leaves the author to
- * work out for themselves that the mechanism is gone. The message says the rule
- * is retired, what lands a section instead, and what to do with the key.
+ * Address-scheme keys a configuration may no longer declare.
+ *
+ * A retired key has exactly two possible fates, and only one of them is honest
+ * — the same reasoning `engine/retired-fields.mjs` applies to a retired
+ * frontmatter field. Left honoured, it keeps doing whatever it did, which is
+ * why it was retired. Left *ignored*, it reads to its author as though it still
+ * works: the configuration says one thing and the build does another, and
+ * nothing says so. This module has no third option, because it has no warning
+ * channel — every finding goes through `fail()`, which throws. So a retired
+ * key is **refused**, at the line it was written on, with a message that says
+ * the mechanism is gone rather than naming a value to correct.
+ *
+ * **What `landing` did (#204).** It named which note addressed a whole section
+ * rather than a page within one — a *landing page*, which therefore had no slug
+ * of its own. #203 retired the second of its two rules and #204 retired the
+ * concept both rules chose between: a section is a Hugo content directory that
+ * the note format does not carry, a page's address names no directory, and so
+ * no note lands anything. The key outlived its mechanism by one release only
+ * because both publishing consumers still declared the then-true
+ * `landing: readme`, and neither breaking them over a correct statement nor
+ * accepting the key in silence was acceptable. Neither declares it now.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const RETIRED_LANDING_RULES = Object.freeze({
-    collection:
-        "the `collection` landing rule is retired, and so is the mechanism it " +
-        "chose between: a section is a Hugo directory the note format does not " +
-        "carry, so no note lands one. Delete this key. A page that introduces " +
-        "the notes of a type is an ordinary note — `type: doc`, " +
-        "`subType: reference`, `shortcode: <type>` — addressed `doc-<type>`; " +
-        "the `section:` frontmatter key the rule read is retired with it",
+export const RETIRED_ADDRESS_KEYS = Object.freeze({
+    landing:
+        "is a retired option — delete it. It named which note addressed a " +
+        "whole section rather than a page within one, and there are no " +
+        "sections to address: a section is a Hugo content directory the note " +
+        "format does not carry, so no note lands one and every page is " +
+        "addressed `<type>-<shortcode>`. Nothing replaces it",
 });
 
 /**
@@ -166,11 +159,12 @@ export const RETIRED_LANDING_RULES = Object.freeze({
  * knowledge, held in `PACKAGE_BASE` (`engine/kb-manifest.mjs`) and prefixed at
  * resolve time, so it is never recorded here (#1465).
  *
- * `landing` is inert — see {@link LANDING_RULES}.
+ * It is the whole scheme: `landing`, the key that named which note addressed a
+ * whole section, is retired with the sections themselves — see
+ * {@link RETIRED_ADDRESS_KEYS}.
  */
 export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     prefix: "",
-    landing: "readme",
 });
 
 /**
@@ -471,10 +465,7 @@ export function publishesContentPages(config) {
 
 /**
  * @typedef {object} AddressSchemeInput
- * @property {string} [prefix]   Where the content tree mounts inside the package.
- * @property {string} [landing]  Which note addressed a whole section. Inert
- *   since #204 retired sections from the note format — see
- *   {@link LANDING_RULES}.
+ * @property {string} [prefix]  Where the content tree mounts inside the package.
  */
 
 /**
@@ -658,7 +649,7 @@ const SITE_KEYS = [
     "backfillSections",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
-const SECTION_META_KEYS = ["title", "banner", "description"];
+const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
 const RELATIONSHIP_KEYS = ["id", "type", "manifest", "compatibility", "itemCatalog"];
@@ -695,7 +686,7 @@ const STATS_KEYS = ["lastModifiedBy"];
 export const DERIVED_SYSTEM_VERSION = Symbol.for("package-build.derivedSystemVersion");
 const PUBLISH_KEYS = ["site", "manifests", "address"];
 const MANIFEST_KEYS = ["publish", "consume"];
-const ADDRESS_KEYS = ["prefix", "landing"];
+const ADDRESS_KEYS = ["prefix"];
 
 /** @param {unknown} value */
 function isPlainObject(value) {
@@ -1134,9 +1125,36 @@ function normalizeDocs(value) {
  * add to its title. Each is left off entirely rather than written as
  * `undefined`, which is not a value YAML can carry.
  *
+ * **`listType` / `listSubType` say what the section lists**
+ * (heroiclands-hugo-theme#50). Since #204 a section's directory holds nothing
+ * but the `_index.md` written here, so a layout reading Hugo's `.Pages` finds
+ * no members and renders an empty landing. The membership survives in this map
+ * and nowhere a theme can reach it, so the landing states it and a layout
+ * substitutes the equivalent `site.RegularPages` query — the same one `sohl`'s
+ * catalog layouts already run, which is why `sohl`'s landings never broke.
+ *
+ * They are two keys of their own rather than `type` / `subType` because `type`
+ * on an `_index.md` is **Hugo's own layout selector**: verified against Hugo
+ * 0.165, a section landing carrying `type: doc` renders through
+ * `layouts/doc/list.html` rather than the default list template, so spelling
+ * the content type there would silently change which template serves the
+ * landing. (This build already uses that behaviour deliberately, for the
+ * mount's own landing.)
+ *
+ * Both are checked as **address segments**, which is the trap this came from:
+ * a section is named for the URL a consumer chose and a subType is an address
+ * segment, and the two need not agree — `/sohl/kb/user-guide/` is the section,
+ * `userguide` the subType (#207). Copying the section's name into the
+ * declaration would select no page at all, and an empty landing reported by
+ * nobody is the failure being fixed. A `listSubType` with no `listType` is
+ * refused for the same reason: a subType is only distinguishing *within* a
+ * type — `rules`, `userguide` and `reference` are all `doc` — so alone it names
+ * no query.
+ *
  * @param {unknown} value - The declared entry.
  * @param {string} where - Dotted path, for the error.
- * @returns {Readonly<{title: string, banner?: string, description?: string}>}
+ * @returns {Readonly<{title: string, banner?: string, description?: string,
+ *   listType?: string, listSubType?: string}>}
  */
 function normalizeSectionMeta(value, where) {
     if (!isPlainObject(value)) fail(where, "must be a mapping");
@@ -1149,6 +1167,32 @@ function normalizeSectionMeta(value, where) {
     if (input.description !== undefined) {
         out.description = requireNonEmptyString(input.description, `${where}.description`);
     }
+    for (const key of ["listType", "listSubType"]) {
+        if (input[key] === undefined) continue;
+        const segment = requireNonEmptyString(input[key], `${where}.${key}`);
+        if (!isAddressSegment(segment)) {
+            fail(
+                `${where}.${key}`,
+                `is \`${segment}\`, which is not alphanumeric. It names a ` +
+                    "content type or subType, and those are address segments " +
+                    `(${ADDRESS_SEGMENT_PATTERN.source}) — not the section's ` +
+                    "own name, which is a URL this site chose and need not " +
+                    "match (`user-guide` is the section, `userguide` the " +
+                    "subType). A value no page carries selects nothing and " +
+                    "leaves the landing empty",
+            );
+        }
+        out[key] = segment;
+    }
+    if (out.listSubType !== undefined && out.listType === undefined) {
+        fail(
+            `${where}.listSubType`,
+            "is declared without a `listType`. A subType tells pages apart " +
+                "only within a type — `rules`, `userguide` and `reference` " +
+                "are all `doc` — so on its own it names no query for a layout " +
+                "to run",
+        );
+    }
     return Object.freeze(out);
 }
 
@@ -1731,6 +1775,15 @@ function normalizePublish(value) {
         fail("publish.address", "must be an object");
     }
     const address = /** @type {Record<string, unknown>} */ (addressInput ?? {});
+    // A retired key is refused by name, ahead of the vocabulary check: reported
+    // as merely unrecognized it would read as a misspelling of the one key that
+    // survives, and the author would correct the spelling rather than learn
+    // that the mechanism is gone (#215).
+    for (const key of Object.keys(address)) {
+        if (Object.hasOwn(RETIRED_ADDRESS_KEYS, key)) {
+            fail(`publish.address.${key}`, RETIRED_ADDRESS_KEYS[key]);
+        }
+    }
     rejectUnknownKeys(address, ADDRESS_KEYS, "publish.address.");
 
     const prefix =
@@ -1749,24 +1802,9 @@ function normalizePublish(value) {
         fail("publish.address.prefix", "must not begin with a slash");
     }
 
-    const landing =
-        address.landing === undefined ?
-            DEFAULT_ADDRESS_SCHEME.landing
-        :   optionalString(address.landing, "publish.address.landing");
-    // A retired rule is refused by name, before the vocabulary check: reported
-    // as merely unrecognized it would read as a misspelling of the one that
-    // survives, and the author would correct the value rather than learn that
-    // the mechanism is gone (#202).
-    if (Object.hasOwn(RETIRED_LANDING_RULES, landing)) {
-        fail("publish.address.landing", RETIRED_LANDING_RULES[landing]);
-    }
-    if (!LANDING_RULES.includes(landing)) {
-        fail("publish.address.landing", `must be one of ${LANDING_RULES.join(", ")}`);
-    }
-
     return Object.freeze({
         site: normalizeSiteMode(publish.site),
-        address: Object.freeze({ prefix, landing }),
+        address: Object.freeze({ prefix }),
         manifests: Object.freeze({
             publish: optionalBoolean(manifests.publish, "publish.manifests.publish", false),
             consume: optionalBoolean(manifests.consume, "publish.manifests.consume", false),

package/docs/content-format.md

@@ -249,17 +249,16 @@ against the same constant a shortcode is checked against, and a note carrying a
 hyphenated value is reported where it wrote it:
 
 ```text
-Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. The hyphen separates the segments of an address, so a value containing one is read back as two segments and resolves to nothing
+Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. It is a vocabulary term the whole toolchain keys on, and one closed set away from being an address segment again, so a charset that held for every term but this one would be a rule nobody could state in a sentence
 ```
 
 One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
-is now **`userguide`**. The old spelling is accepted for one transitional
-release and reported as a **warning** naming the replacement, so a tree that has
-not yet swept still builds:
-
-```text
-User_Guide/Actions.md:3:1: warning: `subType` "user-guide" is a retired spelling of "userguide" on a doc; write "userguide". …
-```
+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
+charset check — it contains a hyphen, which is the reason that always applied.
+No retirement-specific code outlived the sweep.
 
 That is a guarantee rather than an observation, and it holds: of **4,456 distinct
 shortcodes** across the four content trees, not one contains a character outside

package/engine/content-address.mjs

@@ -32,12 +32,12 @@
 // The scheme vocabulary is part of the configuration contract — a
 // repository names its scheme in `package-build.config.yaml` — so it is
 // declared beside the rest of that vocabulary rather than here, and this
-// module reads it. `config.mjs` is the leaf entry point and imports nothing
-// but `node:path` and `engine/ids.mjs`, so the direction cannot close a
-// cycle (see `engine/pack-config.mjs`).
-import { DEFAULT_ADDRESS_SCHEME, LANDING_RULES } from "../content-config.mjs";
+// module re-exports it beside the addresses it derives. `config.mjs` is the
+// leaf entry point and imports nothing but `node:path` and `engine/ids.mjs`,
+// so the direction cannot close a cycle (see `engine/pack-config.mjs`).
+import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 
-export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };
+export { DEFAULT_ADDRESS_SCHEME };
 
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX = "kb/";
@@ -116,26 +116,18 @@ export function contentAddress(fm) {
  * `/<package>/api/` for generated API docs, neither of which contains a hyphen
  * or names a type.
  *
+ * **It takes no address scheme.** It took one until #215, to validate the
+ * `landing` rule it then discarded; with that key retired, `prefix` was the
+ * only thing left in the scheme and the paragraph above is the reason it never
+ * applied. A parameter read by nothing is the defect this deletion is about.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {object} [options] - Options.
- * @param {{prefix?: string, landing?: string}} [options.scheme] - The
- *   repository's address scheme; defaults to {@link DEFAULT_ADDRESS_SCHEME}.
- *   `landing` is validated against {@link LANDING_RULES} and selects nothing —
- *   it is accepted so a configuration declaring the still-true `landing: readme`
- *   keeps loading, and is removed once none does.
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no type or no shortcode to be addressed by.
  *   Such a note is not published, and inventing an address for one would put a
  *   dead entry in the manifest.
  */
-export function packageAddress(fm, { scheme } = {}) {
-    const { landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
-    if (!LANDING_RULES.includes(landing)) {
-        throw new Error(
-            `unknown landing rule ${JSON.stringify(landing)} — expected one ` +
-                `of ${LANDING_RULES.join(", ")}`,
-        );
-    }
+export function packageAddress(fm) {
     return `${addressSlug(fm)}/`;
 }

package/engine/frontmatter-lint.mjs

@@ -61,13 +61,7 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
-import {
-    declaredTags,
-    retiredSubType,
-    retiredSubTypeMessage,
-    subTypeCharsetMessage,
-    typeCharsetMessage,
-} from "./note-vocabulary.mjs";
+import { declaredTags, subTypeCharsetMessage, typeCharsetMessage } from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
@@ -342,11 +336,18 @@ function checkDataContainer(note, { type, fields }) {
  * called, and `rules`, `userguide`, `reference` mean three genres and nothing
  * else.
  *
- * **Three checks, in this order** — retired spelling, then charset, then the
- * closed set (#206, #204). Each is ahead of the next because it is the more
- * specific statement about the same value: a retired spelling has a named
- * replacement, a hyphenated value is unaddressable whatever the type declares,
- * and only then is the type's own list the reason.
+ * **Two checks, in this order** — the charset, then the closed set (#206,
+ * #204). The charset is first because it is the more general statement about
+ * the same value: a value outside `^[A-Za-z0-9]+$` is refused whatever the type
+ * declares, and only once it is a well-formed term is the type's own list the
+ * reason to refuse it.
+ *
+ * There were three. #206 ran a retired-spelling check ahead of both, accepting
+ * `user-guide` as a warning naming `userguide`, so the 43 `sohl` notes
+ * authoring it were not invalidated by the release that renamed it. Every
+ * consumer tree has swept, so the acceptance guarded nothing and is gone: the
+ * old spelling now falls through to the charset check, which refuses it for the
+ * reason that always applied — it contains a hyphen (#210).
  *
  * @param {object} note - The note.
  * @param {object} opts
@@ -374,26 +375,7 @@ function checkSubType(note, { type, entry }) {
         ];
     }
 
-    // A retired spelling is **accepted**, and said out loud (#206). Checked
-    // before the charset, because the note is not wrong about the charset in
-    // some general way — it is wrong about one value, and naming the
-    // replacement is the whole of what the author needs. A warning rather than
-    // an error for the same reason the retired field aliases below are: the
-    // note compiles to the correct page, and erroring would red every tree the
-    // moment it took this release, ahead of any chance to sweep.
-    const replacement = retiredSubType(type, value);
-    if (replacement) {
-        return [
-            {
-                file: note.file,
-                ...at,
-                severity: "warning",
-                message: retiredSubTypeMessage(type, value, replacement),
-            },
-        ];
-    }
-
-    // The charset, before the closed set: a hyphenated value is unaddressable
+    // The charset, before the closed set: a value outside it is refused
     // whatever the type declares, and the type's list is not the reason it is
     // refused. Reported here rather than only for an enumerated type, so a
     // `subTypes: null` type — whose values nothing may yet check — is still

package/engine/manifest-emit.mjs

@@ -210,8 +210,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
  * exist.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter,
- *   scheme }`.
+ * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter }`.
  * @returns {{entries: Array<object>, notes: number,
  *   skipped: Array<{file: string, reason: string}>}}
  */
@@ -249,7 +248,7 @@ export function collectManifestEntries(contentBase, ctx) {
 
         let address;
         try {
-            address = packageAddress(fm, { scheme: ctx.scheme });
+            address = packageAddress(fm);
         } catch (err) {
             skipped.push({ file: rel, reason: err.message });
             continue;
@@ -261,7 +260,7 @@ export function collectManifestEntries(contentBase, ctx) {
 }
 
 /**
- * The identities and scheme an emission runs against, from configuration.
+ * The identities an emission runs against, from configuration.
  *
  * Resolved in one place and passed down, rather than read at each use, so the
  * pass itself is a pure function of its context and a test can drive it without
@@ -269,15 +268,13 @@ export function collectManifestEntries(contentBase, ctx) {
  *
  * @param {object} [config] - A resolved configuration; loaded when omitted.
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
- *   scheme: {prefix: string, landing: string}, web: boolean,
- *   skipDirectories: readonly string[]}}
+ *   web: boolean, skipDirectories: readonly string[]}}
  */
 export function manifestContext(config = loadPackConfig()) {
     return {
         contentPackage: config.contentPackage,
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
-        scheme: config.publish.address,
         web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.

package/engine/note-vocabulary.mjs

@@ -663,11 +663,11 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
-        // `userguide`, not `user-guide`: a `doc` routes by its subType, so the
-        // value is a path segment, and a segment carries no hyphen (#206). The
-        // old spelling is accepted transitionally — see {@link RETIRED_SUBTYPES}
-        // — but it is not declared here, because this list is what the format
-        // says a note *should* write.
+        // `userguide`, not `user-guide`: a subType is held to the address
+        // charset, and a segment carries no hyphen (#206). The old spelling was
+        // accepted transitionally for one release so the consumer trees could
+        // sweep; they have, so it is refused by the charset check now, with no
+        // retirement-specific code left over (#210).
         subTypes: Object.freeze(["rules", "userguide", "reference"]),
         data: Object.freeze([]),
     }),
@@ -732,83 +732,32 @@ export const NOTE_VOCABULARY = Object.freeze({
 });
 
 /**
- * The retired spelling of a subType a type declares → what to write now (#206).
- *
- * Keyed by type, because a retirement is a statement about *that type's*
- * vocabulary: `user-guide` on a `doc` is the old spelling of `userguide`, while
- * the same string on any other type is nothing but a charset violation, and
- * saying "did you mean userguide" there would be a guess dressed as a fact.
- *
- * **Recorded here rather than left in `subTypes`** so the declared list stays
- * the list of values a note *should* write. A retired value is accepted, not
- * declared — the difference is exactly what makes the finding possible.
- *
- * **Deliberately not the shape of a type rename** ({@link
- * import("./ids.mjs").RETIRED_TYPES}), which is an error: a retired type routes
- * a note to the wrong pack, whereas a retired subType still compiles to the
- * correct page. The sweep is the consumer's, and the ordering is the reverse of
- * the usual — the acceptance ships *first*, because declaring only the new
- * spelling while 43 `sohl` notes still author the old one would invalidate all
- * 43 with a release they had no chance to sweep ahead of. A later change
- * removes this map, and the old spelling then falls through to the ordinary
- * undeclared-value error with no code left to remove.
- *
- * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
- */
-export const RETIRED_SUBTYPES = Object.freeze({
-    doc: Object.freeze({ "user-guide": "userguide" }),
-});
-
-/**
- * What to write in place of a retired subType value, if it is one.
+ * What a note carrying a subType outside the address charset is told.
  *
- * @param {string} type - The note's `type`.
- * @param {string} value - The authored `subType`.
- * @param {Readonly<Record<string, Readonly<Record<string, string>>>>} [retired]
- *   The map to read, defaulting to {@link RETIRED_SUBTYPES}.
- * @returns {string|undefined} The current spelling, or `undefined` when the
- *   value is not a retired one — which is not the same as it being valid.
- */
-export function retiredSubType(type, value, retired = RETIRED_SUBTYPES) {
-    const forType = retired?.[type];
-    if (!forType || !Object.hasOwn(forType, value)) return undefined;
-    return forType[value];
-}
-
-/**
- * What a note carrying a retired subType is told.
+ * **Why the charset holds for a subType, which reaches no address.** #206 said
+ * "the hyphen separates the segments of an address", and that was true of a
+ * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
+ * was a URL path segment. #204 retired sections and it is not one now. The rule
+ * stays, on its own footing: a subType is a vocabulary term the whole toolchain
+ * keys on, and it is one closed set away from being an address segment again —
+ * so the reason to spell it in the address charset is that a charset holding
+ * for a type, a shortcode and a `contentPackage` but not for a subType is a
+ * rule nobody can state in a sentence.
  *
- * One message, so the lint and any later refusal cannot describe the same
- * retirement differently.
- *
- * @param {string} type - The note's `type`.
- * @param {string} value - The retired spelling the note carries.
- * @param {string} replacement - What to write instead.
- * @returns {string} The message.
- */
-export function retiredSubTypeMessage(type, value, replacement) {
-    return (
-        `\`subType\` "${value}" is a retired spelling of "${replacement}" on a ` +
-        `${type}; write "${replacement}". A subType is an address segment, and ` +
-        `a segment is ${ADDRESS_SEGMENT_PATTERN.source} — the hyphen separates ` +
-        `segments, so it can never occur inside one. The old spelling is still ` +
-        `accepted, and will stop being accepted once the trees have swept`
-    );
-}
-
-/**
- * What a note carrying a subType outside the address charset is told.
+ * Contrast {@link typeCharsetMessage}, which keeps the address reasoning
+ * because a type genuinely is the first segment of every address.
  *
  * @param {string} value - The authored `subType`.
  * @returns {string} The message.
  */
 export function subTypeCharsetMessage(value) {
     return (
-        `\`subType\` "${value}" is not an address segment — a subType is ` +
+        `\`subType\` "${value}" is not a well-formed subType — a subType is ` +
         `letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same ` +
-        `charset a shortcode is held to. The hyphen separates the segments of ` +
-        `an address, so a value containing one is read back as two segments ` +
-        `and resolves to nothing`
+        `charset a type, a shortcode and a contentPackage are held to. It is a ` +
+        `vocabulary term the whole toolchain keys on, and one closed set away ` +
+        `from being an address segment again, so a charset that held for every ` +
+        `term but this one would be a rule nobody could state in a sentence`
     );
 }
 
@@ -836,6 +785,11 @@ export function typeCharsetMessage(type) {
  * a note's bad value is one author's mistake and belongs in a report, while a
  * bad *declaration* would tell every author to write something unaddressable.
  *
+ * The message states the reason **per key**, as {@link typeCharsetMessage} and
+ * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
+ * has not been one since #204 retired sections, so a single claim covering both
+ * would be half wrong (#210).
+ *
  * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
  * @param {string} [where] - What declares it, for the message.
  * @throws {Error} Naming every offending type and subType at once, rather than
@@ -854,9 +808,13 @@ export function assertVocabularyCharset(vocabulary, where = "the note vocabulary
     if (!bad.length) return;
     throw new Error(
         `${where} declares ${bad.join(", ")}, which ${bad.length === 1 ? "is" : "are"} ` +
-            `not ${ADDRESS_SEGMENT_PATTERN.source}. A type and a subType are both ` +
-            `address segments, and the hyphen separates segments rather than ` +
-            `occurring inside one.`,
+            `not ${ADDRESS_SEGMENT_PATTERN.source}. A type is an address segment, ` +
+            `and the hyphen separates segments rather than occurring inside one. ` +
+            `A subType reaches no address since #204 retired sections, and is ` +
+            `held to the same charset anyway: it is a vocabulary term the whole ` +
+            `toolchain keys on, one closed set away from being a segment again, ` +
+            `and a charset holding for every term but that one would be a rule ` +
+            `nobody could state in a sentence.`,
     );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "13.0.0",
+    "version": "14.0.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/content-config.d.mts

@@ -56,36 +56,31 @@ export namespace DEFAULT_PATHS {
  */
 export const PACK_DOCUMENT_TYPES: readonly ["Actor", "Adventure", "Item", "JournalEntry", "Macro", "Scene"];
 /**
- * The landing-page rules a repository may route by. **Inert since #204.**
- *
- * A *landing page* was a note that addressed a whole section rather than a page
- * within one, so it had no slug of its own. There are no sections in the note
- * format any more — a section is a Hugo content directory, and a page's address
- * names no directory — so there are no landings and this selects nothing.
- *
- * The key survives its own mechanism on purpose. Both publishing consumers
- * declare `landing: readme`, which stated something true when they wrote it;
- * refusing it now would break them over a correct statement, and silently
- * ignoring an unknown value would be worse. So `readme` stays accepted, the
- * retired `collection` stays refused by name (below), and the key is deleted
- * once no configuration writes it — `content-config.mjs` has no warning channel
- * with which to say "accepted, and does nothing" in between.
- *
- * @type {readonly string[]}
- */
-export const LANDING_RULES: readonly string[];
-/**
- * What a configuration naming the retired `collection` landing rule is told.
- *
- * A retired *value* is refused the way a retired *field* is (see
- * `engine/retired-fields.mjs`): left merely unrecognized it would be reported
- * as a bad value, which names something to correct and leaves the author to
- * work out for themselves that the mechanism is gone. The message says the rule
- * is retired, what lands a section instead, and what to do with the key.
+ * Address-scheme keys a configuration may no longer declare.
+ *
+ * A retired key has exactly two possible fates, and only one of them is honest
+ * — the same reasoning `engine/retired-fields.mjs` applies to a retired
+ * frontmatter field. Left honoured, it keeps doing whatever it did, which is
+ * why it was retired. Left *ignored*, it reads to its author as though it still
+ * works: the configuration says one thing and the build does another, and
+ * nothing says so. This module has no third option, because it has no warning
+ * channel — every finding goes through `fail()`, which throws. So a retired
+ * key is **refused**, at the line it was written on, with a message that says
+ * the mechanism is gone rather than naming a value to correct.
+ *
+ * **What `landing` did (#204).** It named which note addressed a whole section
+ * rather than a page within one — a *landing page*, which therefore had no slug
+ * of its own. #203 retired the second of its two rules and #204 retired the
+ * concept both rules chose between: a section is a Hugo content directory that
+ * the note format does not carry, a page's address names no directory, and so
+ * no note lands anything. The key outlived its mechanism by one release only
+ * because both publishing consumers still declared the then-true
+ * `landing: readme`, and neither breaking them over a correct statement nor
+ * accepting the key in silence was acceptable. Neither declares it now.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const RETIRED_LANDING_RULES: Readonly<Record<string, string>>;
+export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
 /**
  * A repository's address scheme, with the defaults an unconfigured one gets.
  *
@@ -96,11 +91,12 @@ export const RETIRED_LANDING_RULES: Readonly<Record<string, string>>;
  * knowledge, held in `PACKAGE_BASE` (`engine/kb-manifest.mjs`) and prefixed at
  * resolve time, so it is never recorded here (#1465).
  *
- * `landing` is inert — see {@link LANDING_RULES}.
+ * It is the whole scheme: `landing`, the key that named which note addressed a
+ * whole section, is retired with the sections themselves — see
+ * {@link RETIRED_ADDRESS_KEYS}.
  */
 export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
-    landing: "readme";
 }>;
 /**
  * How much of a package reaches the web.
@@ -515,12 +511,6 @@ export type AddressSchemeInput = {
      * Where the content tree mounts inside the package.
      */
     prefix?: string | undefined;
-    /**
-     * Which note addressed a whole section. Inert
-     * since #204 retired sections from the note format — see
-     * {@link LANDING_RULES}.
-     */
-    landing?: string | undefined;
 };
 /**
  * One entry of a consumer's `itemBuilders` registry.

package/types/engine/content-address.d.mts

@@ -55,27 +55,20 @@ export function contentAddress(fm: object): string;
  * `/<package>/api/` for generated API docs, neither of which contains a hyphen
  * or names a type.
  *
+ * **It takes no address scheme.** It took one until #215, to validate the
+ * `landing` rule it then discarded; with that key retired, `prefix` was the
+ * only thing left in the scheme and the paragraph above is the reason it never
+ * applied. A parameter read by nothing is the defect this deletion is about.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {object} [options] - Options.
- * @param {{prefix?: string, landing?: string}} [options.scheme] - The
- *   repository's address scheme; defaults to {@link DEFAULT_ADDRESS_SCHEME}.
- *   `landing` is validated against {@link LANDING_RULES} and selects nothing —
- *   it is accepted so a configuration declaring the still-true `landing: readme`
- *   keeps loading, and is removed once none does.
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no type or no shortcode to be addressed by.
  *   Such a note is not published, and inventing an address for one would put a
  *   dead entry in the manifest.
  */
-export function packageAddress(fm: object, { scheme }?: {
-    scheme?: {
-        prefix?: string;
-        landing?: string;
-    } | undefined;
-}): string;
+export function packageAddress(fm: object): string;
+export { DEFAULT_ADDRESS_SCHEME };
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX: "kb/";
 import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
-import { LANDING_RULES } from "../content-config.mjs";
-export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };

package/types/engine/manifest-emit.d.mts

@@ -51,8 +51,7 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  * exist.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter,
- *   scheme }`.
+ * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter }`.
  * @returns {{entries: Array<object>, notes: number,
  *   skipped: Array<{file: string, reason: string}>}}
  */
@@ -65,7 +64,7 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
     }>;
 };
 /**
- * The identities and scheme an emission runs against, from configuration.
+ * The identities an emission runs against, from configuration.
  *
  * Resolved in one place and passed down, rather than read at each use, so the
  * pass itself is a pure function of its context and a test can drive it without
@@ -73,17 +72,12 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
  *
  * @param {object} [config] - A resolved configuration; loaded when omitted.
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
- *   scheme: {prefix: string, landing: string}, web: boolean,
- *   skipDirectories: readonly string[]}}
+ *   web: boolean, skipDirectories: readonly string[]}}
  */
 export function manifestContext(config?: object): {
     contentPackage: string;
     foundryPackageId: string;
     packRouter: object;
-    scheme: {
-        prefix: string;
-        landing: string;
-    };
     web: boolean;
     skipDirectories: readonly string[];
 };

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

@@ -36,30 +36,20 @@ export function hasTag(fm: object | null | undefined, tag: string): boolean;
  */
 export function isDraftNote(fm: object | null | undefined): boolean;
 /**
- * What to write in place of a retired subType value, if it is one.
- *
- * @param {string} type - The note's `type`.
- * @param {string} value - The authored `subType`.
- * @param {Readonly<Record<string, Readonly<Record<string, string>>>>} [retired]
- *   The map to read, defaulting to {@link RETIRED_SUBTYPES}.
- * @returns {string|undefined} The current spelling, or `undefined` when the
- *   value is not a retired one — which is not the same as it being valid.
- */
-export function retiredSubType(type: string, value: string, retired?: Readonly<Record<string, Readonly<Record<string, string>>>>): string | undefined;
-/**
- * What a note carrying a retired subType is told.
+ * What a note carrying a subType outside the address charset is told.
  *
- * One message, so the lint and any later refusal cannot describe the same
- * retirement differently.
+ * **Why the charset holds for a subType, which reaches no address.** #206 said
+ * "the hyphen separates the segments of an address", and that was true of a
+ * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
+ * was a URL path segment. #204 retired sections and it is not one now. The rule
+ * stays, on its own footing: a subType is a vocabulary term the whole toolchain
+ * keys on, and it is one closed set away from being an address segment again —
+ * so the reason to spell it in the address charset is that a charset holding
+ * for a type, a shortcode and a `contentPackage` but not for a subType is a
+ * rule nobody can state in a sentence.
  *
- * @param {string} type - The note's `type`.
- * @param {string} value - The retired spelling the note carries.
- * @param {string} replacement - What to write instead.
- * @returns {string} The message.
- */
-export function retiredSubTypeMessage(type: string, value: string, replacement: string): string;
-/**
- * What a note carrying a subType outside the address charset is told.
+ * Contrast {@link typeCharsetMessage}, which keeps the address reasoning
+ * because a type genuinely is the first segment of every address.
  *
  * @param {string} value - The authored `subType`.
  * @returns {string} The message.
@@ -80,6 +70,11 @@ export function typeCharsetMessage(type: string): string;
  * a note's bad value is one author's mistake and belongs in a report, while a
  * bad *declaration* would tell every author to write something unaddressable.
  *
+ * The message states the reason **per key**, as {@link typeCharsetMessage} and
+ * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
+ * has not been one since #204 retired sections, so a single claim covering both
+ * would be half wrong (#210).
+ *
  * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
  * @param {string} [where] - What declares it, for the message.
  * @throws {Error} Naming every offending type and subType at once, rather than
@@ -288,31 +283,6 @@ export const NOTE_VOCABULARY: Readonly<{
         })[];
     }>;
 }>;
-/**
- * The retired spelling of a subType a type declares → what to write now (#206).
- *
- * Keyed by type, because a retirement is a statement about *that type's*
- * vocabulary: `user-guide` on a `doc` is the old spelling of `userguide`, while
- * the same string on any other type is nothing but a charset violation, and
- * saying "did you mean userguide" there would be a guess dressed as a fact.
- *
- * **Recorded here rather than left in `subTypes`** so the declared list stays
- * the list of values a note *should* write. A retired value is accepted, not
- * declared — the difference is exactly what makes the finding possible.
- *
- * **Deliberately not the shape of a type rename** ({@link
- * import("./ids.mjs").RETIRED_TYPES}), which is an error: a retired type routes
- * a note to the wrong pack, whereas a retired subType still compiles to the
- * correct page. The sweep is the consumer's, and the ordering is the reverse of
- * the usual — the acceptance ships *first*, because declaring only the new
- * spelling while 43 `sohl` notes still author the old one would invalidate all
- * 43 with a release they had no chance to sweep ahead of. A later change
- * removes this map, and the old spelling then falls through to the ordinary
- * undeclared-value error with no code left to remove.
- *
- * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
- */
-export const RETIRED_SUBTYPES: Readonly<Record<string, Readonly<Record<string, string>>>>;
 /**
  * One `data:` key a note type may carry.
  *