@heroiclands/package-build 22.9.2 → 22.10.0

package/engine/content-address.mjs

@@ -45,13 +45,12 @@ import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 // The system vocabulary is the `<system>` segment's own registry, and
 // `engine/systems.mjs` imports nothing but `engine/address-charset.mjs`, so
 // the direction is toward the leaf and cannot close a cycle.
-import { NO_SYSTEM, assertSystemSegment, isSystemSegment } from "./systems.mjs";
-// The asset vocabulary, for the one thing the address grammar asks of it:
-// whether a type's `<system>` segment is fixed. `engine/asset-types.mjs` is a
-// leaf, so the direction cannot close a cycle.
-import { isAssetType } from "./asset-types.mjs";
-import { systemOf } from "./document-subtypes.mjs";
-import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+import { NO_SYSTEM, isSystemSegment } from "./systems.mjs";
+
+// The address grammar, which sits below this module: a page URL is derived from
+// an address, so the rule for reading and writing one is stated there and
+// applied here.
+import { canonicalKey } from "./address.mjs";
 
 // `ids.mjs` is a leaf with no local imports — the module note there says why —
 // so an address may hash itself without any risk of closing a cycle.
@@ -66,6 +65,21 @@ export { DEFAULT_ADDRESS_SCHEME };
  */
 export { NO_SYSTEM };
 
+/**
+ * The address grammar, under the names its callers hold it by.
+ *
+ * One parser, one renderer and one reader, all of them in `engine/address.mjs`:
+ * {@link canonicalKey} renders the four segments, `expandAddress` applies a
+ * position's defaults to a written value and renders the result, and
+ * `readCanonicalKey` reads a rendered address back.
+ */
+export {
+    canonicalKey,
+    expandAddress,
+    readCanonicalKey,
+    CANONICAL_KEY_SEGMENTS,
+} from "./address.mjs";
+
 /** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX = "kb/";
 
@@ -73,7 +87,7 @@ export const KB_PREFIX = "kb/";
  * The single path segment a note is addressed by: `type-shortcode`.
  *
  * Lowercased and hyphen-joined by the same rule as the note's canonical key
- * ({@link canonicalKey}, below, lowercases too), so it is that
+ * ({@link canonicalKey} lowercases too), so it is that
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
@@ -152,63 +166,6 @@ export function packageAddress(fm) {
     return `${addressSlug(fm)}/`;
 }
 
-/**
- * The **canonical** address of a note: fully qualified, one spelling per
- * document, and globally unique.
- *
- * The written form of a link is a **partial** address: it may omit leading
- * segments, and each one it omits is filled in by rule rather than left
- * unconstrained. An omitted package (`[[skill-lang]]`) defaults to the citing
- * note's own, so an unqualified link resolves locally and only locally, and a
- * link into another package must name it. An omitted **system** is a
- * *wildcard*, not a default — most links target items, which belong to a
- * system — and the resolver requires exactly one match: none is a dead link,
- * more than one is an ambiguity reported with every candidate named.
- * Everything internal — index keys, cache keys, every lookup — uses this fully
- * qualified form instead, so no consumer has to know what a short form
- * defaulted to or matched.
- *
- * Global uniqueness is what lets a dependency's index merge straight into a
- * local one: the keys cannot collide by accident, so a key already present on
- * merge is a real conflict rather than an artefact of two packages sharing a
- * namespace. `(type, shortcode)` alone is unique only *within* a package, and
- * two independently authored packages reaching for the same short string is a
- * matter of time.
- *
- * **The system segment.** A package may ship content for more than one
- * system, and one note then compiles into a document per system — an actor in
- * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
- * land on one key, so the address cannot name either of them. `harn-ensemble`
- * carries 2,497 such notes.
- *
- * The value is a system id, or the literal **`none`** for a document no game
- * system defines: a journal, a macro, a scene, and an item's documentation
- * journal — which is `none` however many systems the item itself declares,
- * because it is one journal.
- *
- * `none` rather than `any`: every segment of an address is an exact literal,
- * and `any` reads as a wildcard — "matches under any system" — which is not
- * what it does. A resolver written to that misreading would fail silently,
- * since a lookup miss already returns nothing rather than erroring. And not
- * `null` or `~`, both of which are YAML nulls that parse to an absent value and
- * drop the segment entirely.
- *
- * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
- *   not the Foundry package, which varies per compilation target.
- * @param {string} system - The system whose document this addresses, or `none`.
- * @param {string} type - The note's `type`.
- * @param {string} shortcode - The note's `shortcode`.
- * @returns {string} `package-system-type-shortcode`, lowercased.
- */
-export function canonicalKey(pkg, system, type, shortcode) {
-    // Checked where an address is *written*, not where one is read: a fetched
-    // index naming a system this build has never heard of is data to report,
-    // while emitting one is a defect in this build. The registry is closed, so
-    // an unknown value here can only be a typo or a system nobody declared.
-    assertSystemSegment(system, `the address of ${type}-${shortcode}`);
-    return `${pkg}-${system}-${type}-${shortcode}`.toLowerCase();
-}
-
 /**
  * Which system a frontmatter key path is written under.
  *
@@ -218,7 +175,7 @@ export function canonicalKey(pkg, system, type, shortcode) {
  * top-level frontmatter, the shared `data:` container, and body prose, which has
  * no key path at all and passes `undefined`.
  *
- * It is the block rather than the field, so a `WikiLink` field needs no opinion
+ * It is the block rather than the field, so an `Address` field needs no opinion
  * about systems and no per-field table has to be kept in step with the schema.
  *
  * The first segment must **be** a declared system, not merely look like one:
@@ -235,126 +192,6 @@ export function blockSystem(keyPath) {
     return isSystemSegment(first) && first !== NO_SYSTEM ? first : NO_SYSTEM;
 }
 
-/**
- * Expand a written address to the one canonical address it names.
- *
- * **An omitted segment defaults from where the link is written** — it is
- * not a wildcard, and resolution is not a search. Package omitted means the
- * citing note's own; system omitted means {@link blockSystem} of the key path it
- * was written under. So every short form has exactly one expansion, computed
- * before anything is looked up, and there is no candidate set to disambiguate.
- *
- * **Under `none`, a system-bearing type addresses its documentation journal.**
- * A note's `none` address *is* its `doc<type>` entry — the Item is the one with
- * a system — so a prose `[[affiliation-sirvadar|…]]` names the page, which is
- * almost always what prose means. A link that means the Item states the system
- * and gets it. This is the defaulting rule applied, not an exception carved out
- * of it.
- *
- * **Only a type whose own document carries a system is redirected.** A `macro`
- * and the map types have documentation journals too, but their own documents
- * are core ones and already live at `none` — so `<pkg>-none-macro-x` names the
- * Macro and `<pkg>-none-docmacro-x` its journal, two live addresses that the
- * redirect would collapse into one. The test is the note type's own system,
- * not merely whether it has a doc entry.
- *
- * A `doc<type>` written explicitly is `none` **wherever** it appears, even
- * inside a system block: no game system defines a JournalEntry, so there is no
- * other system for one to belong to.
- *
- * @param {{type: string, shortcode: string, package?: string, system?: string,
- *   itemDoc?: boolean}} read - A qualifier, as `readQualifier` returns one.
- * @param {{package: string, system?: string}} where - The citing context: the
- *   tree's own content package, and the system of the block the link sits in.
- * @returns {string} The canonical `package-system-type-shortcode`.
- */
-export function expandAddress(read, where) {
-    const pkg = read.package ?? where.package;
-    // A documentation journal is a core document, so it is `none` however it was
-    // reached, and an **asset** is `none` for a stronger reason: a file belongs
-    // to no game system, so the segment is a property of the type rather than of
-    // where the reference was written. Without that, a `sohl:` block naming
-    // `icon-anvil` would expand to `sohl-sohl-icon-anvil` and resolve to
-    // nothing, which is exactly where an embedded item's art is written.
-    // Otherwise the block's system, which body prose reports as `none`.
-    const system =
-        read.itemDoc || isAssetType(read.type) ?
-            NO_SYSTEM
-        :   (read.system ?? where.system ?? NO_SYSTEM);
-    const redirected = system === NO_SYSTEM && isSystemBearing(read.type);
-    const type = read.itemDoc || redirected ? `doc${read.type}` : read.type;
-    return canonicalKey(pkg, system, type, read.shortcode);
-}
-
-/**
- * Whether a note type's **own** document carries a game system.
- *
- * True for the types some shipped map compiles into an Item or an Actor; false
- * for the core-document types — `doc`, `lore`, `place`, `scenario`, `macro` and
- * the map types — whose documents Foundry itself defines and which therefore
- * already live at `none`.
- *
- * It is what {@link expandAddress} tests rather than {@link hasDocEntry}: a
- * `macro` has a documentation journal *and* a `none` address of its own, so
- * redirecting on "has a doc entry" would collapse two live addresses into one
- * and a `[[macro-autoattack|]]` would stop naming the Macro.
- *
- * @param {string} type - The note type.
- * @returns {boolean} True when the type compiles into a system document.
- */
-function isSystemBearing(type) {
-    return systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS) !== NO_SYSTEM;
-}
-
-/**
- * How many segments a canonical key has, and therefore how many the reader
- * below counts.
- *
- * Named rather than written as a literal because it is the *grammar*, not an
- * implementation detail of one function: it is the number a change to the
- * address form would move, and the thing a reader of that change has to find.
- *
- * @type {number}
- */
-export const CANONICAL_KEY_SEGMENTS = 4;
-
-/**
- * Reads a canonical key back into its parts.
- *
- * Parsing is plain positional counting: split on the separator, require
- * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
- * **The charset rule is what makes that sound** — every segment matches
- * `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`), so the hyphen is
- * purely a separator and the count alone determines every field. That is
- * enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
- * `defineConfig`, and types are bare words. Were any of them free to
- * carry a hyphen, no amount of counting would recover the fields and the reader
- * would need a vocabulary to match against instead.
- *
- * **Nothing to read and nothing readable are different answers.** A key that
- * cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
- * because the package name carries the separator — yields `null`, while an
- * absent or blank input yields `undefined`. Both are falsy, so
- * every call site (all of which test the result for truthiness) is unaffected;
- * the distinction is there so a caller reporting "this key is unreadable" can
- * tell that it has a key to report about.
- *
- * @param {unknown} key - A canonical key, or nothing.
- * @returns {{package: string, system: string, type: string, shortcode: string}
- *   |null|undefined}
- *   The parts; `null` when there is a string that is not in canonical form;
- *   `undefined` when there is no key at all.
- */
-export function readCanonicalKey(key) {
-    if (key == null || key === "") return undefined;
-    const parts = String(key).split("-");
-    if (parts.length !== CANONICAL_KEY_SEGMENTS) return null;
-    const [pkg, system, type, shortcode] = parts;
-    if (!pkg || !system || !type || !shortcode) return null;
-    return { package: pkg, system, type, shortcode };
-}
-
 /**
  * Where this build serves each package, keyed by package name.
  *

package/engine/content-embeds.mjs

@@ -59,6 +59,7 @@
  * @module
  */
 
+import { parseAddress } from "./address.mjs";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { parseImageDirective, standsAlone } from "./content-images.mjs";
 import { positionInBody } from "./diagnostics.mjs";
@@ -118,16 +119,20 @@ export const EMBED_PATTERN = /!\[\[([^\]\n]+)\]\](\{[^}\n]*\})?/g;
  * @param {string} body - The note's markdown, without its frontmatter.
  * @returns {ParsedEmbed[]} One entry per embed.
  */
-export function embedsIn(body) {
+export function embedsIn(body, context) {
     const text = String(body ?? "");
     return matchAllOutsideCode(text, new RegExp(EMBED_PATTERN.source, "g")).map((match) => {
         const index = /** @type {number} */ (match.index);
         const parsed = parseWikilink(match[1] ?? "");
         const length = match[0].length;
+        const written = parsed.anchor ? `${parsed.target}#${parsed.anchor}` : parsed.target;
         return {
             all: match[0],
             inner: parsed.inner,
-            written: parsed.anchor ? `${parsed.target}#${parsed.anchor}` : parsed.target,
+            written,
+            ...(context ?
+                { target: parseAddress(written, { ...context, type: EMBED_DEFAULT_TYPE }) }
+            :   {}),
             display: parsed.display,
             labelled: parsed.labelled,
             directive: match[2] ?? "",
@@ -157,7 +162,11 @@ export function resolveEmbed(index, embed) {
     // reported before anything is looked up.
     if (!embed.labelled) return { reason: "unlabelled", target: embed.inner };
 
-    const read = readAssetAddress(index, embed.written, EMBED_DEFAULT_TYPE);
+    const read = readAssetAddress(
+        index,
+        embed.target?.reason ? embed.written : (embed.target ?? embed.written),
+        EMBED_DEFAULT_TYPE,
+    );
     if (read.record) {
         return { pathname: read.pathname };
     }
@@ -245,7 +254,12 @@ export function resolveEmbeds(body, { index }) {
     let out = "";
     let last = 0;
 
-    for (const embed of embedsIn(text)) {
+    for (const embed of embedsIn(text, {
+        package: index?.contentPackage ?? index?.packageId,
+        system: "none",
+        types: index?.types,
+        packages: index?.packages,
+    })) {
         problems.push(...embedProblems(embed));
         const resolved = resolveEmbed(index, embed);
         if (!("pathname" in resolved)) {

package/engine/content-format-check.mjs

@@ -103,6 +103,7 @@ import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
+import { authoredKey } from "./system-block.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -493,11 +494,54 @@ export function fieldDriftMessage({ noteType, source, target, name, to }) {
  * A note-level source — the `subType` several tables name — carries no prefix
  * and is returned unchanged.
  *
+ * **What that normalization cannot see is whether the declaration reads the
+ * source at all.** Holding the two spellings equal is right for the question
+ * asked here — do the row and the declaration agree about where the value *goes*
+ * — and blind to whether the declaration can reach where it *is*. That is
+ * `tests/mapped-data-source-is-read.test.ts`, which compares the same pair on
+ * the source rather than the target.
+ *
  * @param {string} path - The source, as either side wrote it.
  * @returns {string} The source without its `data.` prefix.
  */
-function sharedSource(path) {
-    return String(path).replace(/^data\./, "");
+const sharedSource = authoredKey;
+
+/**
+ * The declaration that compiles one mapping row, and what is left over.
+ *
+ * The longest declared name the row's source sits under: a field declared
+ * `impact.die` claims `data.impact.die` ahead of any field declared `impact`,
+ * and a field declared `charges` claims `data.charges.max` with `.max` left
+ * over. Compared on the normalized spelling, so a field naming its source under
+ * `data:` matches at the same length a bare one does.
+ *
+ * Exported because two readers ask it and must agree: {@link
+ * checkDeclaredFields}, which holds the row's target to the declaration's, and
+ * the guard that holds the declaration's *source* to the row's — a second copy
+ * of the match would let the two disagree about which declaration a row is even
+ * about.
+ *
+ * @param {string} source - The row's shared source, as either side spells it.
+ * @param {readonly object[]} fields - The type's authored declarations.
+ * @returns {{field: object, rest: string}|undefined} The declaration and the
+ *   remainder of the source beneath its name, or nothing where no declaration
+ *   names it.
+ */
+export function declarationFor(source, fields) {
+    const path = sharedSource(source);
+    let field;
+    let rest;
+    let matched = "";
+    for (const candidate of fields ?? []) {
+        const name = sharedSource(candidate.name);
+        const remainder = under(path, name);
+        if (remainder === undefined) continue;
+        if (field && name.length <= matched.length) continue;
+        field = candidate;
+        matched = name;
+        rest = remainder;
+    }
+    return field === undefined ? undefined : { field, rest: /** @type {string} */ (rest) };
 }
 
 /**
@@ -550,32 +594,16 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
 
         const authored = authoredFields(declared[noteType]);
         for (const claim of claimsFor(format, noteType, system)) {
-            const source = sharedSource(claim.source);
             const target = claim.target.replace(/^system\./, "");
-            // The longest declared name that the source sits under: a field
-            // declared `impact.die` claims `data.impact.die` ahead of any
-            // field declared `impact`. Compared on the normalized spelling, so
-            // a field that has moved its source under `data:` is the same
-            // length it was.
-            let match;
-            let rest;
-            let matched = "";
-            for (const field of authored) {
-                const name = sharedSource(field.name);
-                const remainder = under(source, name);
-                if (remainder === undefined) continue;
-                if (match && name.length <= matched.length) continue;
-                match = field;
-                matched = name;
-                rest = remainder;
-            }
+            const found = declarationFor(claim.source, authored);
             // No declaration names it. That is coverage, not a contradiction —
             // the specification maps fields no builder emits yet, which is the
             // ordinary mid-migration state and what `schema-check.mjs`
             // already reports as unemitted.
-            if (!match) continue;
+            if (!found) continue;
+            const match = found.field;
             fields += 1;
-            if (under(target, match.to) === rest) continue;
+            if (under(target, match.to) === found.rest) continue;
             findings.push({
                 file: format.file,
                 line: claim.line,

package/engine/content-index.mjs

@@ -86,6 +86,14 @@
  * @module
  */
 
+import { isAddressSegment } from "./address-charset.mjs";
+import { positionOfYamlPath } from "./diagnostics.mjs";
+import {
+    decodeNoteAddresses,
+    decodeIndexAddresses,
+    noteAddressContext,
+    encodeAddresses,
+} from "./note-addresses.mjs";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -442,11 +450,26 @@ export function buildIndexRecord({
     body,
     bodyLine,
     manifest,
+    addressContext,
 }) {
     assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage);
 
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
+    try {
+        decodeNoteAddresses(frontmatter, addressContext ?? { package: contentPackage });
+    } catch (error) {
+        error.file = absPath ?? relPath;
+        if (absPath && error.keyPath) {
+            const yamlText = fs
+                .readFileSync(absPath, "utf8")
+                .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+            const position = positionOfYamlPath(yamlText, error.keyPath, { key: error.addressKey });
+            if (position.line) position.line++;
+            error.position = position;
+        }
+        throw error;
+    }
     const address = noteAddress(frontmatter, contentPackage);
     // Derived from the address the note *would* hold, because a stub still
     // compiles every document derived from `data:` — an unwritten arcane talent
@@ -463,45 +486,48 @@ export function buildIndexRecord({
     const stub = isStubNote(frontmatter, body);
 
     return /** @type {Record<string, any>} */ (
-        sortKeysDeep({
-            ...frontmatter,
-            package: contentPackage,
-            address: stub ? null : address,
-            nameAscii: asciiName(frontmatter?.name?.full),
-            aliasesAscii: asciiAliases(frontmatter?.name?.aliases),
-            // Each anchor carries the link that reaches it, so a section is
-            // addressable from the index without anyone re-deriving how an
-            // anchor is spelled — and its file line, so an editor can jump
-            // there rather than search for the heading.
-            anchors:
-                stub ? null : (
-                    collectAnchors(body, bodyLine).map((a) => ({
-                        ...a,
-                        link: address ? `${address.slug}#${a.slug}` : null,
-                    }))
+        decodeIndexAddresses(
+            {
+                ...frontmatter,
+                package: contentPackage,
+                address: stub ? null : address,
+                nameAscii: asciiName(frontmatter?.name?.full),
+                aliasesAscii: asciiAliases(frontmatter?.name?.aliases),
+                // Each anchor carries the link that reaches it, so a section is
+                // addressable from the index without anyone re-deriving how an
+                // anchor is spelled — and its file line, so an editor can jump
+                // there rather than search for the heading.
+                anchors:
+                    stub ? null : (
+                        collectAnchors(body, bodyLine).map((a) => ({
+                            ...a,
+                            link: address ? `${address.slug}#${a.slug}` : null,
+                        }))
+                    ),
+                foundry: foundryBlock(
+                    entries?.own,
+                    systemOf(frontmatter?.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
                 ),
-            foundry: foundryBlock(
-                entries?.own,
-                systemOf(frontmatter?.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
-            ),
-            // Forward link to the note's documentation journal, which is its
-            // own record. Named rather than nested, because the journal is a
-            // separate document with its own address — see `buildDocRecord`.
-            documentation: entries?.doc?.key ?? null,
-            file: {
-                // Relative to the content root, and deliberately not absolute.
-                // An absolute path is a fact about the machine that built the
-                // index, not about the content: it would differ between two
-                // checkouts of the same tree, so the file would stop being
-                // byte-stable, and a published copy would carry someone's home
-                // directory and be wrong for every reader. Anyone holding the
-                // index knows the root it was built from, and `root + path` is
-                // the absolute form whenever it is wanted.
-                path: posix,
-                folder,
-                name: path.basename(posix, ".md"),
+                // Forward link to the note's documentation journal, which is its
+                // own record. Named rather than nested, because the journal is a
+                // separate document with its own address — see `buildDocRecord`.
+                documentation: entries?.doc?.key ?? null,
+                file: {
+                    // Relative to the content root, and deliberately not absolute.
+                    // An absolute path is a fact about the machine that built the
+                    // index, not about the content: it would differ between two
+                    // checkouts of the same tree, so the file would stop being
+                    // byte-stable, and a published copy would carry someone's home
+                    // directory and be wrong for every reader. Anyone holding the
+                    // index knows the root it was built from, and `root + path` is
+                    // the absolute form whenever it is wanted.
+                    path: posix,
+                    folder,
+                    name: path.basename(posix, ".md"),
+                },
             },
-        })
+            addressContext ?? { package: contentPackage },
+        )
     );
 }
 
@@ -599,7 +625,7 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
  */
 export function collectContentIndex(
     contentBase,
-    { contentPackage, skipDirectories, assetsBase, manifest, problems },
+    { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext },
 ) {
     const records = [];
     // Passed through rather than defaulted away: an absent scope is the
@@ -639,8 +665,20 @@ export function collectContentIndex(
                 body,
                 bodyLine,
                 manifest,
+                addressContext,
             });
         } catch (err) {
+            if (fm.shortcode && !isAddressSegment(fm.shortcode) && err.keyPath) {
+                err.identity = { type: fm.type, shortcode: fm.shortcode };
+                err.keyPath = ["shortcode"];
+                err.message = `shortcode "${fm.shortcode}" is not strictly alphanumeric — lowercase letters and digits only`;
+                const yamlText = fs
+                    .readFileSync(absPath, "utf8")
+                    .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+                err.position = positionOfYamlPath(yamlText, err.keyPath);
+                if (err.position.line) err.position.line++;
+            }
+            err.file = absPath;
             // No `problems` array means the caller wants the old contract: a
             // note that cannot be recorded fails the derivation outright, which
             // is right for the *emitter* — an index quietly missing a note
@@ -653,10 +691,11 @@ export function collectContentIndex(
                 ...(err.position ?? {}),
                 severity: "error",
                 message: String(err.message),
+                ...(err.identity ? { identity: err.identity } : {}),
             });
             continue;
         }
-        records.push(record);
+        records.push(decodeIndexAddresses(record, addressContext ?? { package: contentPackage }));
 
         // An item note is two documents, so it is two records. Derived from
         // the address the note *would* hold rather than from the one its
@@ -703,13 +742,15 @@ export function collectContentIndex(
     records.sort(
         (a, b) =>
             recordPath(a).localeCompare(recordPath(b), "en") ||
-            String(a.address?.canonical ?? "").localeCompare(
-                String(b.address?.canonical ?? ""),
+            String(encodeAddresses(a.address?.canonical) ?? "").localeCompare(
+                String(encodeAddresses(b.address?.canonical) ?? ""),
                 "en",
             ) ||
             String(a.id ?? "").localeCompare(String(b.id ?? ""), "en"),
     );
-    return records;
+    return records.map((record) =>
+        decodeIndexAddresses(record, addressContext ?? { package: contentPackage }),
+    );
 }
 
 /**
@@ -722,7 +763,7 @@ export function collectContentIndex(
  */
 export function serializeContentIndex(records) {
     if (records.length === 0) return "";
-    return `${records.map((r) => JSON.stringify(r)).join("\n")}\n`;
+    return `${records.map((r) => JSON.stringify(sortKeysDeep(encodeAddresses(r)))).join("\n")}\n`;
 }
 
 /**
@@ -781,6 +822,7 @@ export function indexRecordsFor({
     }
     return collectContentIndex(tree, {
         contentPackage: resolved.contentPackage,
+        addressContext: noteAddressContext(resolved),
         skipDirectories: skipDirectories ?? resolved.skipDirectories,
         assetsBase: assetsBase ?? resolved.paths.assets,
         // Only the identities a UUID is a function of — see emitContentIndex.