@heroiclands/package-build 10.0.1 → 11.0.0

package/bin/content-build.mjs

@@ -103,6 +103,8 @@ import {
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
+// The one place a link finding is worded, shared with both builds (#184).
+import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
 import {
     emitDiagnostic,
     positionInFrontmatter,
@@ -189,6 +191,26 @@ function reportFailure(err) {
     else log.error(message);
 }
 
+/**
+ * A note's source text, or `""` when it cannot be read.
+ *
+ * Used only to turn a link finding into a position. A path that no longer
+ * resolves — a page a build generated, a tree walked from somewhere else —
+ * yields `""`, and {@link positionOfLiteral} then reports nothing, so the
+ * diagnostic drops the line and column rather than guessing them.
+ *
+ * @param {string|undefined} file - Absolute path to the note.
+ * @returns {string} The file's contents, or `""`.
+ */
+function readRawNote(file) {
+    if (!file) return "";
+    try {
+        return fs.readFileSync(file, "utf8");
+    } catch {
+        return "";
+    }
+}
+
 /**
  * The declaration sets this package ships, addressable by system id.
  *
@@ -1022,8 +1044,7 @@ function linksCommand() {
                 const {
                     deadAnchors,
                     deadAddresses,
-                    deadAliases,
-                    aliasCollisions,
+                    unlabelledLinks,
                     frontmatterLinks,
                     homepageLinks,
                     usedManifest,
@@ -1039,62 +1060,19 @@ function linksCommand() {
                             `heading in ${d.dest.rel} declares`,
                     });
                 }
-                // The pipe says the author meant an address (#131), so all
-                // three of these are errors — but they read differently
-                // because the corrections differ.
-                for (const d of deadAddresses) {
+                // Every link is an address (#180) and every address must
+                // resolve (#184), so all of these are errors — but they read
+                // differently because the corrections differ. The wording comes
+                // from the shared table, so the checker cannot describe a
+                // defect differently from the build that also refuses it.
+                for (const d of [...deadAddresses, ...unlabelledLinks]) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message:
-                            d.reason === "not-an-address" ?
-                                `"${d.target}" is written as an address — the ` +
-                                `"|" says so — but it is not one; write ` +
-                                `[[type-shortcode|Text]], or drop the "|" to ` +
-                                `name it as an alias within this note's type`
-                            : d.reason === "unknown-type" ?
-                                `address [[${d.target}]] names no known ` + `content type`
-                            :   `dead address [[${d.target}]] — no document ` + `has that identity`,
+                        message: linkFindingMessage(d),
                     });
                 }
-                // An alias that names nothing may be a worldbuilding
-                // placeholder — a long-standing convention in the setting
-                // trees — so it is reported and does not fail the build. The
-                // ambiguous case is the collision below, reported at its
-                // claimants rather than here.
-                for (const d of deadAliases) {
-                    emitDiagnostic({
-                        file: d.note.file,
-                        ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
-                        severity: "warning",
-                        message:
-                            d.ambiguous ?
-                                `alias [[${d.target}]] is claimed by ` +
-                                `${d.claimants.length} ${d.note.type} notes, ` +
-                                `so it names none of them; address the ` +
-                                `intended one as [[type-shortcode|Text]]`
-                            :   `unresolved alias [[${d.target}]] — no ` +
-                                `${d.note.type} note claims that name`,
-                    });
-                }
-                // Reported once per claimant, at the claimant, because the
-                // note that merely cites an ambiguous alias is innocent (#13).
-                for (const c of aliasCollisions) {
-                    const others = c.claimants.map((n) => n.rel).join(", ");
-                    for (const claimant of c.claimants) {
-                        emitDiagnostic({
-                            file: claimant.file,
-                            ...positionInFrontmatter(claimant.raw, "aliases", c.alias),
-                            severity: "error",
-                            message:
-                                `alias "${c.alias}" is claimed by ` +
-                                `${c.claimants.length} ${c.type} notes ` +
-                                `(${others}), so [[${c.alias}]] names none of ` +
-                                `them; rename all but one`,
-                        });
-                    }
-                }
                 for (const f of frontmatterLinks) {
                     emitDiagnostic({
                         file: f.note.file,
@@ -1119,12 +1097,10 @@ function linksCommand() {
                     });
                 }
 
-                // Warnings are reported and do not fail: a dead alias may be a
-                // note not yet written, which is the placeholder convention.
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
-                    aliasCollisions.reduce((n, c) => n + c.claimants.length, 0) +
+                    unlabelledLinks.length +
                     frontmatterLinks.length +
                     homepageLinks.length;
                 if (failures) {
@@ -1132,21 +1108,14 @@ function linksCommand() {
                     process.exitCode = 1;
                 } else {
                     log.info(
-                        `${index.notes.length} notes: every anchor link lands ` +
-                            `and every address resolves ` +
-                            `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no alias claimed twice, no ` +
+                        `${index.notes.length} notes: every link is a labelled ` +
+                            `address, every anchor link lands and every ` +
+                            `address resolves (${usedManifest.size} ` +
+                            `cross-package reference(s) via manifest), no ` +
                             `wikilink in frontmatter, every homepage address ` +
                             `resolvable.`,
                     );
                 }
-                if (deadAliases.length) {
-                    log.warn(
-                        `${deadAliases.length} unresolved alias(es) — a bare ` +
-                            `[[Name]] naming no note may be a placeholder, so ` +
-                            `these are reported rather than failed.`,
-                    );
-                }
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1275,16 +1244,13 @@ function siteCommand() {
                             `page verbatim, and reaches the reader as brackets`,
                     });
                 }
-                for (const f of gates.slugErrors) {
+                for (const f of gates.addressErrors) {
                     emitDiagnostic({
                         file: f.file,
                         severity: "error",
                         message: `cannot derive a URL: ${f.reason}`,
                     });
                 }
-                for (const c of gates.collisions) {
-                    log.error(`${c.url} claimed by ${c.sources.join(", ")}`);
-                }
                 for (const s of gates.staleManifests) {
                     emitDiagnostic({
                         file: path.join(loadPackConfig().paths.manifests, `${s.package}.json`),
@@ -1310,8 +1276,21 @@ function siteCommand() {
                 for (const e of result.tableErrors) {
                     log.error(`bad content table: ${e.reason}  (${e.source})`);
                 }
+                // Reported the way the pack build reports the very same
+                // finding: `file:line:column: error: message`, path first, and
+                // the message from the shared table (#184). It used to be a
+                // `log.error` whose timestamp prefix sat where a parser reads
+                // the path from, and whose text named a `reason` code rather
+                // than saying what to do — so one authored link produced a
+                // machine-readable diagnostic from one build and prose from
+                // another.
                 for (const e of result.wikiErrors) {
-                    log.error(`bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`);
+                    emitDiagnostic({
+                        file: e.file,
+                        ...positionOfLiteral(readRawNote(e.file), e.link, e.occurrence),
+                        severity: "error",
+                        message: linkFindingMessage(e),
+                    });
                 }
                 if (result.tableErrors.length || result.wikiErrors.length) {
                     process.exitCode = 1;
@@ -1319,11 +1298,16 @@ function siteCommand() {
                 }
 
                 if (result.manifests && !result.manifests.complete) {
+                    // Not a softening any more (#184): an address into one of
+                    // these packages fails like any other that resolves
+                    // nowhere. The warning names them so an author meeting that
+                    // failure knows the fix may be to vendor a manifest rather
+                    // than to correct a shortcode.
                     log.warn(
-                        `cross-package address checking is OFF — no manifest ` +
-                            `for ${result.manifests.missing.join(", ")}. ` +
-                            `Unresolved addresses are tolerated until every ` +
-                            `package publishes one.`,
+                        `no link manifest vendored for ` +
+                            `${result.manifests.missing.join(", ")} — an ` +
+                            `address into one of those packages resolves ` +
+                            `nowhere and fails the build.`,
                     );
                 }
 

package/docs/content-format.md

@@ -74,8 +74,8 @@ silently become a theme parameter, which is exactly why these cannot live
 together.
 
 **Tags are open, except the ones that classify.** `tags:` shares the top level's
-openness: a tag naming a theme, a region or a working state — `underworld`,
-`byzaria`, `draft` — is the author's own and this build has no opinion about it.
+openness: a tag naming a theme or a region — `underworld`,
+`byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
 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
@@ -91,6 +91,17 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **being station**   | `being`                | `tradesfolk`, `common-folk`, `soldiery`, `administration`, `clergy`, `mages`, `underworld`, `dependents`, `guilded`, `unguilded`                                                                                                                                                                                     |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                              |
 
+**`draft` is the one tag either build reads.** A note tagged `draft` exists so a
+link into it is not dead, and a link into it renders marked — as
+`<span class="sohl-draft-link" title="Draft — not yet written">…</span>` in a
+compiled journal and on the website alike, with the appearance supplied by the
+consuming system's stylesheet or the site theme. **Nothing else changes**: the
+note compiles, validates, publishes and resolves exactly as any other, and it
+stays in the packs, in the link manifest and on the site. That is what separates
+the tag from the retired `draft:` field, whose whole effect was to move a note
+from published to unresolvable without saying so — and which is refused, by name,
+if you write it.
+
 **The group's scope is what makes the check work.** A group names the types it
 applies to, and a place's kinds are only ever checked on a place. Without that
 the rule is wrong on every note it touches: `azravan` on a faith, `barter` on an
@@ -235,49 +246,78 @@ resolution with nothing to say so.
 `type/shortcode` with a slash is the legacy form, still resolved so links written
 before the vault migrated do not silently die. A slash is _unconditionally_ an
 address separator — pipe or no pipe — so an unknown type before one is an error
-rather than a fallback to the alias index.
+rather than something to guess at.
 
-#### The pipe decides how a target resolves
+#### Every link is an address, and every link carries a label
 
-There are two namespaces, and the pipe says which one to consult:
+There is one namespace, and the pipe is required:
 
 | written              | resolved as | displays                   |
 | -------------------- | ----------- | -------------------------- |
-| `[[Alias]]`          | an alias    | the alias, as written      |
 | `[[WikiLink\|]]`     | an address  | the target note's own name |
 | `[[WikiLink\|Text]]` | an address  | `Text`                     |
-
-**No pipe means look this up in the alias index. A pipe means parse this as an
-address.** The two never compete, and neither falls back to the other: a failure
-in one namespace is a dead link, not an invitation to try the other.
-
-That is what makes positional parsing safe. Note names contain hyphens —
-`Grukar-ahk` is a name, not a `Grukar` of type `ahk` — and under a
-resolve-by-shape rule the reader would have to consult the type vocabulary before
-it dared split. Under the pipe rule it never faces the question: an unpiped
-target is taken whole, hyphens and all, and only a piped target is ever split.
-
-The empty label is not an oversight and not a way of writing no label. It says
-_address this target, and show whatever it calls itself_ — so a note renamed later
-takes its new name at every citation with no link edited. Omitting the pipe says
-something else entirely: the phrase in the brackets is the alias, and the alias is
-also what the reader sees.
-
-So the two are worth keeping distinct even though both display a name: one is a
-promise to follow the target, the other is a phrase the author chose.
-
-#### An alias resolves only within its own type
-
-A bare `[[awareness]]` in a `skill` note finds the `skill` whose alias is
-`awareness` — not an `affliction` that happens to share the name. The alias index
-is keyed by `(source note's type, alias)`, so the same word may be an alias in
-several types without colliding.
-
-Two notes of the **same** type claiming one alias is an error, and the report
-names the claimants rather than the note that merely cited them. An ambiguous
-alias never resolves to whichever was indexed first.
-
-#### In frontmatter, a link is a bare address — never an alias
+| `[[Name]]`           | nothing     | a finding                  |
+
+**A link written without a label addresses nothing** (#180), 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 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).
+
+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
+it is permitted and read by nothing — no index, no resolver, no lint rule, no
+derived address. A note carrying one behaves exactly as one without it.
+
+Requiring the label is also what makes positional parsing safe. Note names
+contain hyphens — `Grukar-ahk` is a name, not a `Grukar` of type `ahk` — so a
+target that does not parse as an address is reported as one that does not, rather
+than split at an arbitrary place or quietly looked up somewhere else.
+
+The **empty** label is not a way of writing no label. It says _address this
+target, and show whatever it calls itself_ — so a note renamed later takes its new
+name at every citation with no link edited. `[[x|]]` is labelled; `[[x]]` is not.
+
+The link part may still be an anchor: `[[#slug|Text]]` addresses a section of the
+page it is written on. It is the label that is required, not a target.
+
+#### 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,
+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
+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
+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           |
+| `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 vendor the manifest |
+| `ambiguous`      | more than one package publishes the short form | write `[[package-type-shortcode\|Text]]`  |
+| `unknown-anchor` | the address resolves; the `#section` does not  | correct the anchor                        |
+
+The vocabulary and the messages live in one module (`engine/wikilink-syntax.mjs`)
+precisely because an author meets whichever build ran first. Three resolvers read
+one authored link; they must not describe the same mistake in three ways, and
+they must never disagree about whether it is a mistake at all.
+
+#### In frontmatter, a link is a bare address
 
 A `WikiLink` **field** takes the address with no brackets:
 
@@ -292,17 +332,10 @@ not `[[hexhodai]]`. The field is declared as a `WikiLink`, so the schema already
 knows the value is an address and reads it as one; brackets would be punctuation
 the reader has to strip before it can do anything.
 
-**Aliases are not permitted here.** A frontmatter value is always parsed by the
-address grammar above, so a single-segment value such as `hexhodai` is a
-_shortcode_, not an alias — the same spelling means different things in a
-frontmatter field and in body prose, and this is the rule that says which.
-
-The reason is that frontmatter is structure rather than prose. An alias is an
-authorial convenience for writing a sentence that reads well; a field value is a
-reference something else will compile against, and it should say exactly what it
-points at. There is also nowhere to put the pipe: the distinction body text draws
-with punctuation has no equivalent in a YAML scalar, so the region as a whole
-picks one namespace and keeps it.
+A frontmatter value is parsed by the address grammar above, so a single-segment
+value such as `hexhodai` is a _shortcode_. Frontmatter is structure rather than
+prose: a field value is a reference something else will compile against, and it
+should say exactly what it points at.
 
 **The field supplies the type.** Every `WikiLink` field declares the note type it
 targets — `seat` a `place`, `parents` an `affiliation`, `stations` a `lore` — so
@@ -339,15 +372,10 @@ So the ladder has one rung where the field helps and three where it only checks:
 a bare shortcode takes its type from the declaration, and every longer form
 states the type itself and is verified against it.
 
-This also settles the alias question on its own. Aliases resolve within the
-_source_ note's type, and a field almost always points at a different type — a
-being's `stations` are `lore` notes — so an alias in a field would be looked up
-in the wrong namespace even where one existed to find.
-
 This is enforced rather than merely preferred: the build walks every frontmatter
-value, reports each bracketed link it finds, each value that resolves only as an
-alias, and each value whose qualification contradicts its field. A successful run says so — _no wikilink in frontmatter_ is part
-of what `content-build links` reports when it passes.
+value, reports each bracketed link it finds, and reports each value whose
+qualification contradicts its field. A successful run says so — _no wikilink in
+frontmatter_ is part of what `content-build links` reports when it passes.
 
 Brackets belong in prose, where a link sits inside a sentence and needs marking
 off from the words around it. A frontmatter value has nothing to be marked off
@@ -355,21 +383,16 @@ from.
 
 #### Not yet implemented
 
-Two rules in this section are settled but unbuilt, and describe the target rather
+One rule in this section is settled but unbuilt, and describes the target rather
 than current behaviour:
 
 - **The `<system>` segment.** `readQualifier` reads package, type and shortcode;
   there is no system segment. A four-segment target today parses as
   `package-type-shortcode` with a hyphenated shortcode, or fails.
-- **The pipe rule.** Today the pipe affects only the _label_: resolution runs the
-  same either way, trying the address first and falling back to the alias — so a
-  target is read by shape rather than by punctuation, and an author cannot say
-  which of the two they meant.
-
-The corpus is close to the rule already. Of 12,056 links, 10,413 are
-`[[type-shortcode|Label]]`, which is correct as written. Two authored links use
-an unpiped multi-segment target, and 69 use a pipe with a note name where an
-address belongs; those are the migration.
+  The corpus is close to the rule already. Of 12,056 links, 10,413 are
+  `[[type-shortcode|Label]]`, which is correct as written. Two authored links use
+  an unpiped multi-segment target, and 69 use a pipe with a note name where an
+  address belongs; those are the migration.
 
 ### What a note produces
 

package/engine/base-compiler.mjs

@@ -77,7 +77,7 @@ import {
 } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoDraftField } from "./retired-fields.mjs";
+import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
 import { carriesSystemBlock } from "./system-block.mjs";
 import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
@@ -770,6 +770,11 @@ export class BasePackCompiler {
             // - `draft:` (#69): it excluded the note from the packs, the
             //   manifest and the site, and no checker reported the links that
             //   left dangling.
+            // - `aliases:` (#180): it fed the alias index, which the bare
+            //   `[[Alias]]` form was looked up in; the form is retired, so the
+            //   list has no reader left. The nested `name.aliases` is a
+            //   different field and is **not** refused — it is reserved, and
+            //   deliberately neither read nor validated.
             //
             // Both are reported and counted — never skipped, which is how a
             // tree naming a package nothing answers to used to compile zero
@@ -778,6 +783,7 @@ export class BasePackCompiler {
             try {
                 assertNoDeclaredPackage(fm, { absPath });
                 assertNoDraftField(fm, { absPath });
+                assertNoAliasesField(fm, { absPath });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;

package/engine/content-address.mjs

@@ -18,9 +18,17 @@
  * knowledgebase build renders the page, and the link manifest records the
  * address other packages link to. Stating it twice is how a manifest comes to
  * assert a URL that resolves at build time and 404s for the reader.
+ *
+ * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181). It
+ * used to be derived from `name.full`, which made a display string load-bearing
+ * in three separate ways: a rename moved the URL and nothing redirected, two
+ * notes in one section could derive the same URL so a uniqueness check had to
+ * run, and a long name had to be abbreviated through a word table to keep the
+ * result short. `(type, shortcode)` is unique within a package by rule
+ * (`engine/content-lint.mjs`), so the address is **unique by construction** —
+ * there is no check to run, and no rename to survive.
  */
 
-import { contentSlug } from "./content-slug.mjs";
 // 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
@@ -49,22 +57,54 @@ export function sectionOf(fm) {
 }
 
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction/aconite/`.
+ * The single path segment a note is addressed by: `type-shortcode`.
+ *
+ * Lowercased, so it is exactly the tail of the note's canonical key
+ * (`canonicalKey` in `engine/kb-manifest.mjs` lowercases too) — which is what
+ * makes a manifest entry's `path` derivable from the key it is filed under
+ * rather than transported beside it.
+ *
+ * The hyphen is a separator and never occurs inside a segment: a shortcode is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
+ * and a type is a bare word. That is the same charset guarantee positional key
+ * parsing rests on, so the address and the key cannot disagree about where one
+ * ends and the other begins.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string} The address segment, e.g. `weapongear-dagger`.
+ * @throws {Error} When the note declares no type or no shortcode — either way
+ *   it has no address, which is reported rather than papered over: inventing
+ *   one would publish a page nothing can link to and record a manifest entry
+ *   pointing at it.
+ */
+export function addressSlug(fm) {
+    const type = typeof fm?.type === "string" ? fm.type.trim() : "";
+    if (!type) {
+        throw new Error("note declares no type, so it has no address");
+    }
+    const shortcode = typeof fm?.shortcode === "string" ? fm.shortcode.trim() : "";
+    if (!shortcode) {
+        throw new Error(
+            `note declares no shortcode, so it has no address — a page is ` +
+                `addressed as "${type}-<shortcode>"`,
+        );
+    }
+    return `${type}-${shortcode}`.toLowerCase();
+}
+
+/**
+ * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
  *
  * A `README.md` **is** its section's landing page rather than a page within it,
- * so it addresses the section itself and has no slug of its own.
+ * so it addresses the section itself and has no address of its own.
  *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; the slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {boolean} isReadme - Whether the file is a `README.md`.
- * @returns {string} The section-relative address, with a trailing slash.
- * @throws {Error} When the name yields no usable slug.
+ * @returns {string} The mount-relative address, with a trailing slash.
+ * @throws {Error} When the note has no address.
  */
-export function contentAddress(fm, name, isReadme) {
-    const sec = sectionOf(fm);
-    return isReadme ? `${sec}/` : `${sec}/${contentSlug(name)}/`;
+export function contentAddress(fm, isReadme) {
+    return isReadme ? `${sectionOf(fm)}/` : `${addressSlug(fm)}/`;
 }
 
 /**
@@ -92,17 +132,30 @@ function landingOf(fm, isReadme, landing) {
 }
 
 /**
- * A note's address relative to its **package**, e.g. `kb/affliction/aconite/`.
+ * A note's address relative to its **package**, e.g. `affliction-aconite/`.
  *
  * This is the form the link manifest records and the site build emits pages at,
  * and it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
+ * **The prefix does not apply to a page's own address.** `prefix` says where the
+ * content tree *mounts inside the package* — where its section directories and
+ * their landing pages live — and a landing page is addressed by that mount
+ * (`kb/rules/`). An ordinary page is addressed by `(type, shortcode)`, which is
+ * a package-wide identity and takes no mount: `sohl` publishes
+ * `/sohl/affliction-aconite/` while its section landings stay at
+ * `/sohl/kb/affliction/`. The `type-` half is what keeps that flat namespace
+ * clear of the package's fixed mounts — `/<package>/` for the landing,
+ * `/<package>/api/` for generated API docs, neither of which contains a hyphen
+ * or names a type.
+ *
+ * **The section still decides where the *file* is written**, which is why a
+ * note without one still has no address: Hugo derives a section from a page's
+ * directory rather than from its URL, so a page with nowhere to be filed is a
+ * page with no section landing, no `.CurrentSection` and no per-section layout.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; a page slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {object} [options] - Options.
  * @param {boolean} [options.isReadme] - Whether the file is a `README.md`.
  * @param {{prefix?: string, landing?: string}} [options.scheme] - The
@@ -110,11 +163,11 @@ function landingOf(fm, isReadme, landing) {
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no address — no section, a landing page
- *   naming no section, or a name yielding no usable slug. Each is a note that
+ *   naming no section, or no shortcode to be addressed by. Each is a note that
  *   is not published, and inventing an address for one would put a dead entry
  *   in the manifest.
  */
-export function packageAddress(fm, name, { isReadme = false, scheme } = {}) {
+export function packageAddress(fm, { isReadme = false, scheme } = {}) {
     const { prefix, landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
     if (!LANDING_RULES.includes(landing)) {
         throw new Error(
@@ -133,5 +186,5 @@ export function packageAddress(fm, name, { isReadme = false, scheme } = {}) {
     if (typeof sec !== "string" || !sec) {
         throw new Error(`type "${fm.type}" has no section`);
     }
-    return `${prefix}${sec}/${contentSlug(name)}/`;
+    return `${addressSlug(fm)}/`;
 }

package/engine/content-format-check.mjs

@@ -269,7 +269,7 @@ function nearest(key, candidates) {
  * @type {ReadonlySet<string>}
  */
 export const NOTE_LEVEL_KEYS = Object.freeze(
-    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name", "aliases"]),
+    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name"]),
 );
 
 /** Whether a value is a plain object a block could be written as. */