@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/social-ties.mjs

@@ -9,6 +9,7 @@
  */
 
 import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
+import { AddressEntries } from "./address-values.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 
@@ -16,14 +17,51 @@ export { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES };
 
 const TERMS = new Set(SOCIAL_TIES.map(({ term }) => term));
 
+/**
+ * A being's defining ties, in one shape whichever shape they reach here in.
+ *
+ * Two spellings reach this check, and both read the same entries from here
+ * on:
+ *
+ * - an **{@link AddressEntries}** — the map after the note boundary decoded
+ *   its keys into typed Addresses, the shape every compile sees;
+ * - a **plain map**, the shape a caller reading raw YAML sees.
+ *
+ * `sourceKey` is always the authored key text, so a finding locates on what
+ * the file actually says even when `key` already carries a parsed Address.
+ *
+ * @param {unknown} value - The authored `data.socialTies`.
+ * @returns {{form: "absent"|"map"|"malformed",
+ *   entries: Array<{key: unknown, term: unknown, sourceKey: string}>}}
+ */
+function readSocialTies(value) {
+    if (value === undefined || value === null) return { form: "absent", entries: [] };
+    if (value instanceof AddressEntries) {
+        return {
+            form: "map",
+            entries: value.entries.map((entry) => ({
+                key: entry.target,
+                term: entry.value,
+                sourceKey: entry.sourceKey,
+            })),
+        };
+    }
+    if (typeof value !== "object" || Array.isArray(value))
+        return { form: "malformed", entries: [] };
+    return {
+        form: "map",
+        entries: Object.entries(value).map(([key, term]) => ({ key, term, sourceKey: key })),
+    };
+}
+
 /**
  * Validate a being's map of defining relationships.
  * @param {object} note
  * @param {{index?: object}} [options]
  */
 export function checkSocialTies(note, { index } = {}) {
-    const ties = note.fm?.data?.socialTies;
-    if (ties === undefined || ties === null) return [];
+    const { form, entries } = readSocialTies(note.fm?.data?.socialTies);
+    if (form === "absent") return [];
     const at = (key) => ({
         file: note.file,
         ...positionOfFrontmatterPath(
@@ -33,7 +71,7 @@ export function checkSocialTies(note, { index } = {}) {
         ),
         severity: "error",
     });
-    if (typeof ties !== "object" || Array.isArray(ties))
+    if (form === "malformed")
         return [
             {
                 ...at(),
@@ -42,11 +80,11 @@ export function checkSocialTies(note, { index } = {}) {
         ];
     const findings = [];
     const seen = new Map();
-    for (const [key, term] of Object.entries(ties)) {
+    for (const { key, term, sourceKey } of entries) {
         const tuple = parseAddress(
             key,
             {
-                package: index?.contentPackage ?? note.fm?.package,
+                package: index?.contentPackage,
                 system: "note",
                 types: index?.types,
                 packages: index?.packages,
@@ -55,43 +93,43 @@ export function checkSocialTies(note, { index } = {}) {
         );
         if (tuple.reason) {
             findings.push({
-                ...at(key),
-                message: `data.socialTies key ${JSON.stringify(key)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
+                ...at(sourceKey),
+                message: `data.socialTies key ${JSON.stringify(sourceKey)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
             });
         } else if (!acceptsType(tuple, SOCIAL_TIE_TARGET_TYPES)) {
             findings.push({
-                ...at(key),
+                ...at(sourceKey),
                 message: `data.socialTies accepts being or affiliation, not ${tuple.type}`,
             });
         } else {
             const target = renderAddress(tuple);
             if (seen.has(target)) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies names the same target ${target} as ${JSON.stringify(seen.get(target))}; keep one tie per target`,
                 });
             } else {
-                seen.set(target, key);
+                seen.set(target, sourceKey);
             }
             if (
-                tuple.package === (index?.contentPackage ?? note.fm?.package) &&
+                tuple.package === index?.contentPackage &&
                 tuple.type === "being" &&
                 tuple.shortcode === note.fm?.shortcode
             ) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies cannot address this being itself`,
                 });
             } else if (index?.addressHit && !index.addressHit(target)) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies target ${target} does not resolve`,
                 });
             }
         }
         if (!TERMS.has(term))
             findings.push({
-                ...at(key),
+                ...at(sourceKey),
                 message: `data.socialTies value ${JSON.stringify(term)} must be one of ${SOCIAL_TIES.map(({ term: value }) => value).join(", ")}`,
             });
     }

package/engine/sql-tables.mjs

@@ -35,6 +35,7 @@ import path from "node:path";
 
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
 import { booleanAttribute } from "./extension-attributes.mjs";
+import { findPageListBlocks, preparePageLists } from "./page-lists.mjs";
 import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
@@ -53,6 +54,31 @@ const EMPTY_CELL = "—";
  */
 export const RENDER_ALIASES = Object.freeze({ ref: "_ref", section: "_section" });
 
+/**
+ * The attributes an SQL fence takes, with what each one is for.
+ *
+ * **This is the one list.** The fence is validated against it and the authoring
+ * document is checked against it, so an attribute added here is one the document
+ * must describe, and anything else an author writes is reported by name.
+ *
+ * @type {Readonly<Record<string, Readonly<{value: string, default: string, summary: string}>>>}
+ */
+export const SQL_FENCE_ATTRIBUTES = Object.freeze({
+    "allow-empty": Object.freeze({
+        value: "`true` or `false`",
+        default: "`false`",
+        summary:
+            "Whether a query selecting no rows is allowed. A zero-row result is a finding " +
+            "otherwise, because a table that silently prints nothing is the commonest way a " +
+            "query goes wrong unnoticed.",
+    }),
+    "section-level": Object.freeze({
+        value: "an integer from 1 through 6",
+        default: "`2`",
+        summary: "The heading level given to each group a `_section` column creates.",
+    }),
+});
+
 /** A table cell may not carry a raw `|` or a line break. */
 const escapeCell = (text) =>
     String(text)
@@ -92,7 +118,7 @@ export function findSqlBlocks(markdown) {
         const level = Number(args["section-level"] ?? 2);
         const errors = [...problems];
         for (const key of Object.keys(args)) {
-            if (!["allow-empty", "section-level"].includes(key))
+            if (!Object.hasOwn(SQL_FENCE_ATTRIBUTES, key))
                 errors.push(`${key} is not an SQL fence attribute`);
         }
         let allowEmpty = false;
@@ -569,6 +595,10 @@ export function renderSqlTable(
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
+ * @param {object[]} [opts.records] - Content-index records, narrowed to the
+ *   audience this surface publishes to. Given them, the result also carries
+ *   `pageLists`, so one prepared object answers every corpus-reading directive
+ *   a body can hold and a caller looks results up in one place.
  * **Keyed by note, then by the directive's ordinal within it** — not by its
  * line. The passes do not agree on what a body is: `walkMarkdownTree` trims it,
  * while the link checker strips the frontmatter fence and leaves the newlines
@@ -578,8 +608,9 @@ export function renderSqlTable(
  * @returns {Promise<Map<string, object[]>>} Note to results, in document order,
  *   each carrying either a rendered `markdown` and its `rows`, or a `reason`.
  */
-export async function prepareSqlTables(db, sources, { linkable } = {}) {
+export async function prepareSqlTables(db, sources, { linkable, records } = {}) {
     const prepared = new Map();
+    if (records) prepared.pageLists = preparePageLists(records, sources);
     for (const { source, markdown } of sources) {
         const blocks = findSqlBlocks(markdown);
         if (!blocks.length) continue;
@@ -658,10 +689,14 @@ export async function prepareInlineSqlExpressions(db, sources) {
  * shared index
  * describes, where N passes each derive the corpus their own way.
  *
- * **Nothing is opened for a tree with no `sql` directive.** The corpus is still
- * written entirely in the retiring language, so until a table is converted this
- * costs one walk and no database at all — which is what lets every pass call it
- * unconditionally.
+ * **Every corpus-reading directive is answered here**, which is why one call
+ * precedes every pass: the `sql` tables, the inline scalar queries, and the
+ * page lists, whose results ride on the same object as `pageLists`.
+ *
+ * **Nothing is opened for a tree that asks no query.** A tree with no `sql`
+ * directive costs one walk and no database at all, and so does one whose only
+ * directive is a page list — a page list is a filter over the records. That is
+ * what lets every pass call this unconditionally.
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
@@ -671,8 +706,9 @@ export async function prepareInlineSqlExpressions(db, sources) {
  *   A command that also builds a link index holds them already, and deriving
  *   them twice is the duplicated-corpus failure this closes.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
- * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
- *   nothing when the tree has no such directive.
+ * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
+ *   carrying `inline` and `pageLists` beside them, or nothing when the tree
+ *   holds no such directive.
  */
 export async function prepareTreeSqlTables(
     contentBase,
@@ -701,10 +737,30 @@ export async function prepareTreeSqlTables(
         if (!isNoteRecord(record)) continue;
         const absPath = noteFile(contentBase, record);
         const { body, frontmatter } = parseMarkdownFile(absPath);
-        if (body && (findSqlBlocks(body).length || sqlQueriesInMarkdown(body, frontmatter).length))
+        if (
+            body &&
+            (findSqlBlocks(body).length ||
+                findPageListBlocks(body).length ||
+                sqlQueriesInMarkdown(body, frontmatter).length)
+        )
             sources.push({ source: absPath, markdown: body, frontmatter });
     }
     if (!sources.length) return undefined;
+
+    // A page list is a filter over the records, so it needs no database. A tree
+    // whose only corpus-reading directive is one therefore opens none — which
+    // is the same bargain the early return above makes for a tree with no
+    // directive at all.
+    const needsDatabase = sources.some(
+        ({ markdown, frontmatter }) =>
+            findSqlBlocks(markdown).length || sqlQueriesInMarkdown(markdown, frontmatter).length,
+    );
+    if (!needsDatabase) {
+        const pageOnly = new Map();
+        pageOnly.inline = new Map();
+        pageOnly.pageLists = preparePageLists(indexRecords, sources);
+        return pageOnly;
+    }
     // A cell links only where the address it would emit resolves, so a table
     // never ships a link the wikilink pass will then report dead.
     //
@@ -736,6 +792,7 @@ export async function prepareTreeSqlTables(
     try {
         const prepared = await prepareSqlTables(db, sources, {
             linkable: (ref) => addresses.has(renderAddress(ref)),
+            records: indexRecords,
         });
         prepared.inline = await prepareInlineSqlExpressions(db, sources);
         return prepared;

package/engine/standings.mjs

@@ -40,6 +40,14 @@
  * what lets each be checked — a rung the body does not confer and an office it
  * does not hold are both findings naming the file, line and column.
  *
+ * **An entry states a rung, and `rank` is required.** Belonging to a body is
+ * holding some standing in it, so `1` is the ordinary member and `0` is the rung
+ * for someone cast out — between them they cover every standing a member can
+ * hold, which is what makes the requirement writable. `office` is the optional
+ * half, and an entry carrying one and no rung is the same fault rather than a
+ * second: an office distinguishes a person within a standing rather than
+ * standing in for one.
+ *
  * @module
  */
 
@@ -122,6 +130,10 @@ export function readStandings(value) {
  * than by its position in the list: a body may write its rungs in any order,
  * and several start at zero.
  *
+ * One title per level, which is what the rung check holds a ladder to: two
+ * rungs claiming one level is a finding on the second, so a ladder that reaches
+ * here carries at most one title for any number a member's `rank` can hold.
+ *
  * @param {unknown} ranks - An affiliation's `data.governance.ranks`.
  * @returns {Map<number, string>} Level → the title that level is called.
  */
@@ -177,6 +189,22 @@ export function officeAnchor(office) {
     return slug ? `office-${slug}` : "";
 }
 
+/**
+ * The anchor a rung's row is addressed by.
+ *
+ * The ladder's parallel to {@link officeAnchor}, prefixed apart from it so a
+ * body naming an office the same word as one of its ranks still gets two
+ * destinations rather than one row answering for both.
+ *
+ * @param {string} title - The rung's title, as the body wrote it.
+ * @returns {string} The anchor, or `""` where the title carries nothing
+ *   URL-safe.
+ */
+export function rankAnchor(title) {
+    const slug = slugify(title);
+    return slug ? `rank-${slug}` : "";
+}
+
 /**
  * What an affiliation lends to a reference to it.
  *
@@ -234,12 +262,14 @@ export function standingPhrase(standing, body, digest) {
 /**
  * Validate a being's memberships and the standing it holds in each.
  *
- * Four questions, and the last two are what keying the entry by its body buys:
+ * Five questions, and the last three are what keying the entry by its body
+ * buys:
  *
  * 1. the value is a map keyed by Address (or the list this window still takes);
  * 2. every key names an affiliation that resolves, once;
- * 3. a `rank` is a level the named body's `governance.ranks` declares;
- * 4. an `office` is a key of that body's `governance.offices`.
+ * 3. the entry states a `rank`;
+ * 4. a `rank` is a level the named body's `governance.ranks` declares;
+ * 5. an `office` is a key of that body's `governance.offices`.
  *
  * Both of the last two are read from the named body's own frontmatter as the
  * lint runs, so a renamed rung or a renamed post fails on every being pointing
@@ -287,9 +317,18 @@ export function checkStandings(note, { index } = {}) {
             seen.set(resolved.address, sourceKey);
         }
         if (!isKey) continue;
-        if (standing === undefined || standing === null) continue;
-        if (Array.isArray(standing) && standing.length === 0) continue;
         const named = resolved.address ?? String(body);
+        // An entry with nothing after its key, and an emptied map arriving from
+        // the property editor as `[]`, say exactly what an authored `{}` says:
+        // this being belongs to this body, and no standing in it is stated.
+        if (
+            standing === undefined ||
+            standing === null ||
+            (Array.isArray(standing) && standing.length === 0)
+        ) {
+            findings.push(...absentRankFindings(note, {}, named, path));
+            continue;
+        }
         if (!mapping(standing)) {
             findings.push({
                 ...position(note, path),
@@ -309,6 +348,7 @@ export function checkStandings(note, { index } = {}) {
                     `standing holds ${STANDING_KEYS.map((name) => `\`${name}\``).join(" and ")}`,
             });
         }
+        findings.push(...absentRankFindings(note, standing, named, path));
         findings.push(...rankFindings(note, standing, named, path, resolved));
         findings.push(...officeFindings(note, standing, named, path, resolved));
     }
@@ -344,7 +384,7 @@ function resolveBody(note, index, body) {
     const tuple = parseAddress(
         body,
         {
-            package: index?.contentPackage ?? note.fm?.package,
+            package: index?.contentPackage,
             system: "note",
             type: "affiliation",
             types: index?.types,
@@ -382,6 +422,49 @@ function bodyFindings(note, body, path, isKey, found) {
     return [];
 }
 
+/**
+ * What an entry states no `rank` earns.
+ *
+ * Every member of a body holds some standing in it, and the ladders say so at
+ * both ends: `1` is the ordinary member, and `0` is a real rung rather than a
+ * default — `0 Níding`, `0 Outlaw`, `0 Vrystrith`, `0 Struck from the Roll` all
+ * name someone cast out, who still has a standing. So an entry naming a body
+ * and no rung is incomplete, and it is an **error**.
+ *
+ * **The message carries the rule, not just the gap.** "States no `rank`" sends a
+ * reader to find out which number to write; naming `1` and `0` is the whole
+ * answer, and the two ends are what makes the requirement writable — there is no
+ * standing a member can hold that one of them does not cover.
+ *
+ * **One finding per entry.** An entry carrying an office and no rung is the same
+ * fault and not a second one: an office distinguishes a person *within* a
+ * standing rather than standing in for one, so the office is named here as the
+ * reason the entry looked complete, rather than reported on its own line as well.
+ *
+ * @param {object} note - The note.
+ * @param {object} standing - The authored entry.
+ * @param {string} body - How the body is named in a message.
+ * @param {Array<string|number>} path - The entry's frontmatter path.
+ * @returns {object[]} The finding, or nothing.
+ */
+function absentRankFindings(note, standing, body, path) {
+    if (standing.rank !== undefined && standing.rank !== null) return [];
+    const office = typeof standing.office === "string" ? standing.office.trim() : "";
+    return [
+        {
+            ...position(note, path, true),
+            message:
+                `\`data.affiliations\` entry for ${body} states no \`rank\`` +
+                (office ?
+                    `, and the office ${JSON.stringify(office)} is not one — an office ` +
+                    `distinguishes a person within a standing rather than standing in ` +
+                    `for one`
+                :   " — a being that belongs to a body holds some standing in it") +
+                ". An ordinary member is `1`, and `0` is the rung for someone cast out",
+        },
+    ];
+}
+
 /** Whether a `rank` is a rung the named body confers. */
 function rankFindings(note, standing, body, path, resolved) {
     if (standing.rank === undefined || standing.rank === null) return [];

package/engine/system-block.mjs

@@ -104,21 +104,24 @@
  *
  * A field's `name` is both its identity and the shared property it draws from,
  * and those coincide only while the two vocabularies agree about what the
- * spelling means. They do not always. An `affiliation` item's `system.title` is
- * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
- * `title` is the note's own heading, which the site emitter publishes. Two
- * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ * spelling means — or while the top-level vocabulary admits the spelling at
+ * all. They do not always. An `affiliation` item's `system.title` is the style
+ * of address an office carries — "Ajaw", "Warden"; a note's top-level `title`
+ * is refused outright by the closed top-level vocabulary, which has no `title`
+ * entry. Nothing relates them, and step 3 fed the first from the second anyway.
  *
  * It was not a harmless coincidence either, because step 3 answers **without**
  * applying `field.default` — only step 2 does — so an authored `title: null`
  * reached the field's coercion unguarded and shipped as the literal string
  * `"null"` in fifteen documents.
  *
- * So a field may declare `topLevelMeans`: what the top-level key of that name
- * means *instead*. Declaring it removes the whole shared level — step 3 and the
- * retiring 3b alike, since both read the note's top level and the objection is
- * to that level, not to a spelling — leaving the two positions that describe
- * the document rather than the note. It is deliberately
+ * So a field may declare `topLevelMeans`: why the note's top-level key of this
+ * name is not this field's source — declared wherever that key's spelling
+ * means something else at the note level, or the closed top-level vocabulary
+ * refuses it outright. Declaring it removes the whole shared level — step 3
+ * and the retiring 3b alike, since both read the note's top level and the
+ * objection is to that level, not to a spelling — leaving the two positions
+ * that describe the document rather than the note. It is deliberately
  * a per-field opt-out rather than a change to the order — step 3 is right
  * wherever the two levels state the same quantity, which is nearly everywhere —
  * and its value is the reason rather than a bare flag, so the collision is
@@ -339,17 +342,18 @@ export function sharedProperty(fm, source, defaultValue = undefined) {
 }
 
 /**
- * A property a system block may override, else the shared top-level one.
+ * A property a system block declares, else the default.
  *
- * This is what gives `pack`, `effects`, `flags` and `img` their per-system form
- * without inventing a mechanism for each: a note that wants one value for both
- * systems says it once at the top, and a note that needs them to differ says so
- * in the block that differs.
+ * This is what gives `effects` and `flags` their per-system form without
+ * inventing a mechanism for each: a note states them inside the block whose
+ * document carries them, which is the only position the format accepts for
+ * either. A note needing one value for both systems writes it in both blocks —
+ * they are properties of a document, and there are two documents.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The block key.
  * @param {string} key - The property.
- * @param {any} [defaultValue] - Returned when neither declares it.
+ * @param {any} [defaultValue] - Returned when the block does not declare it.
  * @returns {any} The value.
  */
 export function blockProperty(fm, block, key, defaultValue = undefined) {
@@ -357,27 +361,51 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
     if (declared && declared[key] !== undefined && declared[key] !== null) {
         return declared[key];
     }
-    const shared = isMapping(fm) ? /** @type {Record<string, unknown>} */ (fm)[key] : undefined;
-    return shared === undefined || shared === null ? defaultValue : shared;
+    return defaultValue;
 }
 
 /**
- * A system override followed by a shared `data:` value. The top-level value
- * remains readable while content repositories move their authored fields.
+ * A system override followed by a shared `data:` value followed by the
+ * retiring top-level spelling `data:` gathered it off, reporting which one
+ * answered.
+ *
+ * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
+ * universal `data:` key — `pack` and `packFolder`, declared for every note
+ * type rather than per type, so neither is a `FieldSpec` that resolver takes.
+ * The order is the same shape: a system's own override, then the shared
+ * `data:` position, then the bare top-level key a tree authored before
+ * `data:` existed. The top-level value stays readable while a tree still on
+ * it moves its authored fields.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
  * @param {string} key - The shared property.
  * @param {any} [defaultValue] - Returned when no position declares it.
- * @returns {any} The selected value.
+ * @returns {{value: any, from: FieldSource}} The value, and where it came
+ *   from.
  */
-export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+export function resolveDataProperty(fm, block, key, defaultValue = undefined) {
     const declared = systemBlock(fm, block)?.[key];
-    if (declared !== undefined && declared !== null) return declared;
+    if (declared !== undefined && declared !== null) return { value: declared, from: "block" };
     const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
-    if (shared !== undefined && shared !== null) return shared;
+    if (shared !== undefined && shared !== null) return { value: shared, from: "shared" };
     const legacy = isMapping(fm) ? fm[key] : undefined;
-    return legacy === undefined || legacy === null ? defaultValue : legacy;
+    if (legacy !== undefined && legacy !== null) return { value: legacy, from: "topLevel" };
+    return { value: defaultValue, from: "default" };
+}
+
+/**
+ * {@link resolveDataProperty}'s value alone, for a caller that only compiles
+ * a document and has no use for which position answered.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+    return resolveDataProperty(fm, block, key, defaultValue).value;
 }
 
 /**
@@ -411,12 +439,10 @@ const DATA_PREFIX = "data.";
 /**
  * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
  *
- * `data:` did not invent the facts it holds; it *gathered* them, out of
- * the note's open top level where each was a sibling of `img` and `shortcode`.
- * So the retiring spelling of `data.portrait` is not a second declaration
- * anyone has to write — it is `portrait`, mechanically, and the same holds for
- * every other key that move relocated. Deriving it is what keeps the two
- * spellings of one field from disagreeing the way two declarations would.
+ * The retiring spelling of `data.portrait` is not a second declaration anyone
+ * has to write — it is `portrait`, mechanically, and the same holds for every
+ * other key the container gathered. Deriving it is what keeps the two spellings
+ * of one field from disagreeing the way two declarations would.
  *
  * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
  * paths into containers a note has always written at the top level; they were

package/engine/web-wikilinks.mjs

@@ -64,6 +64,26 @@ export { slugify };
 import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
 import { resolveEmbeds } from "./content-embeds.mjs";
 
+/**
+ * Whether a page's declared anchors include the slug a link names.
+ *
+ * A local page's entry carries a `Set` (built by {@link module:engine/site-index});
+ * a foreign one carries the `{slug: uuid}` map a fetched manifest publishes.
+ * `undefined` means neither build recorded an answer, which keeps a target
+ * this check cannot speak for exactly as unchecked as it always was.
+ *
+ * @param {Set<string>|Record<string, string>|undefined} anchors - The page's
+ *   declared anchors, or `undefined` where none were recorded.
+ * @param {string} slug - The anchor a link names.
+ * @returns {boolean} Whether the anchor is declared, or `true` when `anchors`
+ *   is `undefined` — which reads as "nothing to check against" rather than
+ *   "declares none".
+ */
+function hasAnchor(anchors, slug) {
+    if (!anchors) return true;
+    return anchors instanceof Set ? anchors.has(slug) : Object.hasOwn(anchors, slug);
+}
+
 /**
  * The index key a **piped** target resolves to, or `null` when it does not
  * parse as an address at all.
@@ -315,7 +335,9 @@ function isPlainMap(value) {
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in. `resolved`, when supplied, is the array every resolved
- *   target's index entry is appended to.
+ *   target's index entry is appended to. `anchors` is the `{#slug}` set
+ *   *this* page declares, which a `[[#slug]]` self-link is checked against;
+ *   absent, a self-link is not checked, exactly as before this existed.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body, ctx) {
@@ -399,6 +421,16 @@ export function resolveWebWikilinks(body, ctx) {
 
         // `[[#section-slug|Text]]` — a section of this same page.
         if (isSamePage({ target, anchor })) {
+            // Checked against this page's own anchors, exactly as a link into
+            // another page is: a self-link naming a section the page does not
+            // declare is as dead as one naming a section nowhere does.
+            if (!hasAnchor(ctx.anchors, anchor)) {
+                return report(
+                    all,
+                    { target, reason: "unknown-anchor", anchor, addressed: true },
+                    label ?? anchor,
+                );
+            }
             return `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`;
         }
 
@@ -419,6 +451,21 @@ export function resolveWebWikilinks(body, ctx) {
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
             :   undefined);
         if (hit) {
+            // A `#section` the target declares no heading for. Checked only
+            // where there is a page to check against — a pack-only hit has no
+            // `url` and therefore nothing for the anchor to address, which is
+            // the asset-like case this must not touch. `anchorPageId` on the
+            // pack build and the KB manifest's own `{slug: uuid}` map both
+            // hash any slug into something that resolves, so an undeclared
+            // one otherwise joins onto the URL unchecked and dead-ends for
+            // the reader.
+            if (anchor && hit.url && !hasAnchor(hit.anchors, anchor)) {
+                return report(
+                    all,
+                    { target, reason: "unknown-anchor", anchor, addressed: true },
+                    label ?? hit.name ?? target,
+                );
+            }
             // The edge, for a caller reading the link graph off this pass.
             ctx.resolved?.push(hit);
             // An address with an *empty* label has no prose to show (a