@heroiclands/package-build 22.9.2 → 22.11.0

package/engine/content-links.mjs

@@ -24,10 +24,9 @@
  *    dead-ends for the reader.
  * 2. **A dead address.** Every link is an address, and one resolving to no note
  *    is a typo. So is a target that does not parse as an address at all. A
- *    written target is a *partial* address — the segments it omits are
- *    wildcards, and the package it omits is this one — so a target resolving to
- *    *several* notes is an ambiguity rather than a first match, and is reported
- *    naming every candidate.
+ *    written target expands to exactly one canonical address, from the
+ *    position's own defaults — the package it omits is always this one — so a
+ *    lookup finds one entry or none. There is no candidate set to disambiguate.
  * 3. **An unlabelled link.** `[[x]]` addresses nothing: the alias namespace it
  *    once named is retired, and a shortcode is an address rather than
  *    prose, so the link has neither a resolvable target nor text to show. The
@@ -35,7 +34,7 @@
  * 4. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
  *    and copy frontmatter through verbatim, so a link written in a
  *    `description` is never resolved and publishes as literal `[[…]]` text.
- *    Frontmatter is data: a `WikiLink` field is parsed by the address grammar
+ *    Frontmatter is data: an `Address` field is parsed by the address grammar
  *    and a bracketed link there is a finding naming the note and the field.
  *
  * **This resolves links the way the builds do**, calling the same
@@ -54,6 +53,8 @@
  * @module
  */
 
+import { readWikilink } from "./wikilink-syntax.mjs";
+import { encodeAddresses } from "./address-values.mjs";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -208,7 +209,8 @@ export function buildLinkIndex(
         // alongside the notes because `byKey` holds notes, and a caller that
         // reaches for `.fm` or `.body` on one must not be handed a file.
         if (isAssetRecord(record)) {
-            if (record.address?.canonical) byAssetKey.set(record.address.canonical, record);
+            if (record.address?.canonical)
+                byAssetKey.set(encodeAddresses(record.address.canonical), record);
             continue;
         }
         // A documentation journal has a record of its own but no file and no
@@ -247,7 +249,7 @@ export function buildLinkIndex(
             // Taken from the record, which is where the address rule is applied
             // once for the whole build.
             const canonical =
-                record.address?.canonical ??
+                encodeAddresses(record.address?.canonical) ??
                 canonicalKey(pkg, systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS), type, fm.shortcode);
             // A note with no address publishes no page, so its identity is
             // filed where a link cannot reach it and a reference still can.
@@ -285,7 +287,12 @@ export function buildLinkIndex(
         :   { index: new Map(), packages: new Set(), stale: [] };
     for (const v of foreign.index.values()) if (v.type) types.add(v.type);
 
-    const packages = new Set([...(byKey.size ? [pkg] : []), ...foreign.packages]);
+    // A stub counts. It publishes no page, so nothing may *link* to one, but its
+    // address is a name the tree holds and a reference reaches it — a border's
+    // far side is the case that matters. Leaving this package out of the set
+    // whenever every note it holds is a stub would make a fully qualified local
+    // address unreadable in precisely the tree whose relations need it.
+    const packages = new Set([...(byKey.size || byStub.size ? [pkg] : []), ...foreign.packages]);
     // Packages declared `contentIndex: false` — a Foundry dependency only, with
     // no fetched index. A link naming one is refused with a diagnostic that
     // names the key, rather than reading as an undeclared package or a typo.
@@ -414,8 +421,15 @@ export function buildLinkIndex(
         // Code is verbatim, so a `[[…]]` inside a fence, an indented block or an
         // inline span is not a link — the compilers make none of it either.
         for (const [all, rawInner] of matchAllOutsideCode(body, new RegExp(WIKILINK.source, "g"))) {
-            const parsed = parseWikilink(rawInner);
-            const { target, anchor } = parsed;
+            const parsed = readWikilink(rawInner, {
+                package: pkg,
+                system: "none",
+                types,
+                packages,
+                noIndexPackages,
+            });
+            const target = parsed.target.kind ? parsed.rawTarget : parsed.target;
+            const { anchor, rawTarget } = parsed;
             const occurrence = (seen.get(all) ?? 0) + 1;
             seen.set(all, occurrence);
             // `text` is the link exactly as authored, which is what locates it
@@ -423,6 +437,7 @@ export function buildLinkIndex(
             // so the search simply fails and a finding names the file.
             out.push({
                 target,
+                rawTarget,
                 anchor,
                 text: all,
                 occurrence,
@@ -432,45 +447,6 @@ export function buildLinkIndex(
         return out;
     }
 
-    /**
-     * Every indexed entry an address names, matching only the segments it
-     * supplies.
-     *
-     * This is the whole resolution rule in one place: a written
-     * address is a *partial* one, unsupplied segments are wildcards, and the
-     * caller requires exactly one hit. Nothing here decides an ambiguity — zero
-     * and many are different findings with different fixes, so the count is
-     * returned rather than collapsed.
-     *
-     * The **system** is wildcarded unless stated. Defaulting it to `none` would
-     * exclude every link to an item, which is most of them.
-     *
-     * @param {Array<[string, any]>} pairs - Indexed `[canonicalKey, value]`.
-     * @param {object} q - The parsed qualifier.
-     * @returns {Array<[string, any]>} The matching pairs.
-     */
-    function matchAddress(pairs, q) {
-        const type = String(q.type).toLowerCase();
-        const shortcode = String(q.shortcode).toLowerCase();
-        return pairs.filter(([k]) => {
-            const parts = readCanonicalKey(k);
-            if (!parts) return false;
-            if (q.package && parts.package !== String(q.package).toLowerCase()) return false;
-            if (q.system && parts.system !== String(q.system).toLowerCase()) return false;
-            return parts.type === type && parts.shortcode === shortcode;
-        });
-    }
-
-    /**
-     * The local notes an address names, by the same rule.
-     *
-     * @param {object} q - The parsed qualifier.
-     * @returns {object[]} The notes.
-     */
-    function matchLocal(q) {
-        return matchAddress([...byKey], q).map(([, v]) => v);
-    }
-
     /**
      * The note an **address** names, or `undefined`.
      *
@@ -551,7 +527,7 @@ export function buildLinkIndex(
         // saying so is the whole point: a link that resolved into `sohl` only
         // because no local note claimed the address was resolving by accident,
         // and would have retargeted silently the day one did.
-        if (!q.package) return [];
+        if (!q.package || q.package === pkg) return [];
         const hit = foreign.index.get(
             expandAddress(q, { package: q.package, system: blockSystem(keyPath) }),
         );
@@ -573,38 +549,71 @@ export function buildLinkIndex(
     }
 
     /**
-     * The note or foreign entry a **frontmatter reference** names, or null.
+     * The note, asset, stub or foreign entry an **address** names, or
+     * `undefined`.
      *
-     * A `ref:` field holds a shortcode, not an address. The system persists it
-     * verbatim and resolves it at runtime against the items embedded on one
-     * actor, where packages do not exist: an actor assembled from several
-     * packages carries their items side by side. So a reference resolves when
-     * *any* reachable package declares the `(type, shortcode)` pair — package
-     * and system wildcarded, local notes first, then the fetched indexes.
+     * The same rule as {@link resolveAddress} — read with {@link readQualifier},
+     * expanded with {@link expandAddress} against this index's own package and
+     * the citing block's system — consulted against every source this index
+     * holds rather than only the notes a page link may reach: a stub the tree
+     * holds and a fetched foreign package both answer here, where neither
+     * answers a page link. A caller with its own position-specific default
+     * type — a place's `to`, whose default is `place` rather than anything
+     * this index states — parses and expands the value itself and hands this
+     * the canonical string it already computed; every segment that string
+     * states overrides the default that would otherwise apply, so it round-trips
+     * to itself and this is a plain keyed lookup either way.
      *
-     * Distinct from {@link resolveAddress}, which defaults an omitted package
-     * to this one. That is the rule for a link, whose target is a document to
-     * point at; a reference names an item to stand beside.
+     * @param {string} target - The address, or a short form read against this
+     *   index's own defaults.
+     * @param {string} [keyPath] - The dotted frontmatter key path the value
+     *   sits under; body prose has none. Ignored once `target` is already
+     *   canonical.
+     * @returns {object|undefined} The entry.
+     */
+    function addressHit(target, keyPath) {
+        const qualified = readQualifier(target, types, packages, noIndexPackages);
+        if (!qualified || qualified.reason) return undefined;
+        const canonical = expandAddress(qualified, { package: pkg, system: blockSystem(keyPath) });
+        // Stubs and foreign entries answer here and nowhere else in this
+        // index: a reference names an item to stand beside rather than a
+        // document to point at, so a border with a stub — or a place in a
+        // dependency — on the far side is a valid statement about the world.
+        return (
+            byKey.get(canonical) ??
+            byAssetKey.get(canonical) ??
+            byStub.get(canonical) ??
+            foreign.index.get(canonical)
+        );
+    }
+
+    /**
+     * The note, asset, stub or foreign entry a **Shortcode** names, or `null`.
      *
-     * The files this package ships answer here too, and by the same rule: an
-     * asset's address is a `(type, shortcode)` pair like any other, so a field
-     * naming `icon-anvil` resolves to the record that carries the file's path.
+     * A `code:` field's value is a Shortcode, not an address — one segment,
+     * persisted verbatim and resolved at runtime against the items embedded on
+     * one actor, where packages do not exist. So `type` and `shortcode` are
+     * searched for directly rather than assembled into a written form and read
+     * back through the address grammar: a Shortcode never reaches that grammar,
+     * by {@link module:engine/address}'s own contract. It resolves in any
+     * reachable package, because the value comes from every package the actor
+     * draws on — package and system are never part of the search, not defaulted
+     * out of it.
      *
-     * @param {string} target - The reference as `type-shortcode`.
-     * @returns {object|null} The note, asset record or foreign entry declaring it.
+     * @param {string} type - The field's declared `code:`.
+     * @param {string} shortcode - The value as authored, already checked
+     *   against the shortcode charset.
+     * @returns {object|null} The first entry naming the pair, from local notes,
+     *   local assets, local stubs, or a fetched foreign index, in that order.
      */
-    function referenceHit(target) {
-        const q = readQualifier(target, types, packages, noIndexPackages);
-        if (!q || q.reason) return null;
-        // Stubs last, and deliberately included: a reference names an item to
-        // stand beside rather than a document to point at, so a border with a
-        // stub on the far side is a valid statement about the world. Resolving
-        // these against the addressed rows alone would report every one of
-        // them dead.
-        const local = matchAddress([...byKey, ...byAssetKey, ...byStub], q);
-        if (local.length) return local[0][1];
-        const abroad = matchAddress([...foreign.index], q);
-        return abroad.length ? abroad[0][1] : null;
+    function shortcodeHit(type, shortcode) {
+        const wantType = String(type).toLowerCase();
+        const wantCode = String(shortcode).toLowerCase();
+        for (const [key, value] of [...byKey, ...byAssetKey, ...byStub, ...foreign.index]) {
+            const parts = readCanonicalKey(key);
+            if (parts && parts.type === wantType && parts.shortcode === wantCode) return value;
+        }
+        return null;
     }
 
     return {
@@ -646,7 +655,8 @@ export function buildLinkIndex(
         stubAt,
         manifestHit,
         foreignHits,
-        referenceHit,
+        addressHit,
+        shortcodeHit,
         /** Whether a target reads as a qualified address at all. */
         isAddress: (target) => Boolean(readQualifier(target, types, packages, noIndexPackages)),
     };
@@ -936,11 +946,12 @@ export function auditHomepageLinks(index) {
  *   unlabelledLinks: object[], frontmatterLinks: object[],
  *   homepageLinks: object[], usedManifest: Set<string>}} The findings, and
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
- *   carries a `reason` from {@link LINK_FINDING_REASONS} —
- *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), `"no-content-index"`, `"stub"` (with the stub's path) or
- *   `"unresolved"` — and every one of them is an **error**: the three
- *   resolvers agree on severity for every class.
+ *   carries a `reason` from {@link LINK_FINDING_REASONS} — `"not-an-address"`,
+ *   `"unknown-type"`, `"no-content-index"`, `"stub"` (with the stub's path) or
+ *   `"unresolved"`, never `"ambiguous"`: every target here expands to one
+ *   canonical address before anything is looked up, so there is no candidate
+ *   set for two packages to claim — and every reason is an **error**: the
+ *   three resolvers agree on severity for every class.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, embedsOf, resolve, manifestHit, isAddress } = index;
@@ -955,7 +966,7 @@ export function auditLinks(index) {
 
     const deadAnchors = [];
     for (const note of notes) {
-        for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
+        for (const { target, rawTarget, anchor, text, occurrence, labelled } of linksOf(note)) {
             if (!anchor || !labelled) continue;
             const dest = target ? resolve(target) : note;
             // An unresolvable target is reported by the pass below; its anchor
@@ -966,7 +977,7 @@ export function auditLinks(index) {
             if (!(anchors.get(dest) ?? new Set()).has(slugify(anchor))) {
                 deadAnchors.push({
                     note,
-                    link: `${target}#${anchor}`,
+                    link: `${rawTarget}#${anchor}`,
                     dest,
                     text,
                     occurrence,
@@ -979,13 +990,13 @@ export function auditLinks(index) {
     const unlabelledLinks = [];
     const usedManifest = new Set();
     for (const note of notes) {
-        for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
+        for (const { target, rawTarget, anchor, text, occurrence, labelled } of linksOf(note)) {
             // The label is required whatever the link part is, an anchor
             // included — so this is tested before the same-page form.
             if (!labelled) {
                 unlabelledLinks.push({
                     note,
-                    target: target || (anchor ? `#${anchor}` : ""),
+                    target: rawTarget || (anchor ? `#${anchor}` : ""),
                     text,
                     occurrence,
                     // Carried like every other finding's, so a reporter reads
@@ -995,7 +1006,7 @@ export function auditLinks(index) {
                 continue;
             }
             if (!target) continue; // a same-page `[[#anchor|Text]]`
-            const at = { note, target, text, occurrence };
+            const at = { note, target: rawTarget, text, occurrence };
 
             if (!isAddress(target)) {
                 deadAddresses.push({ ...at, reason: "not-an-address" });
@@ -1012,22 +1023,12 @@ export function auditLinks(index) {
                 continue;
             }
             // A manifest answers with the target package's own build output
-            // rather than a reviewed guess.
-            const hits = index.foreignHits(target);
-            if (hits.length === 1) {
-                usedManifest.add(target.toLowerCase());
-                continue;
-            }
-            if (hits.length > 1) {
-                // Two packages publish the short address, so it names neither.
-                // Reported as its own class: "no document has that identity" is
-                // false here — two do — and the fix is the qualified form
-                // rather than a corrected shortcode.
-                deadAddresses.push({
-                    ...at,
-                    reason: "ambiguous",
-                    packages: hits.map((h) => h.package).filter(Boolean),
-                });
+            // rather than a reviewed guess. `manifestHit` is a keyed lookup —
+            // a fully qualified target names one package, so there is nothing
+            // left to disambiguate, and no ambiguity finding this resolver can
+            // report.
+            if (manifestHit(target)) {
+                usedManifest.add(encodeAddresses(target).toLowerCase());
                 continue;
             }
             const read = readQualifier(target, index.types, index.packages, index.noIndexPackages);

package/engine/content-lint.mjs

@@ -160,6 +160,16 @@ function collectNotes(contentBase, { skipDirectories, config, records, problems
             file: path.relative(process.cwd(), absPath),
         });
     }
+    for (let i = (problems?.length ?? 0) - 1; i >= 0; i--) {
+        const problem = problems[i];
+        if (!problem.identity) continue;
+        notes.push({
+            fm: problem.identity,
+            absPath: problem.file,
+            file: path.relative(process.cwd(), problem.file),
+        });
+        problems.splice(i, 1);
+    }
     // The records already come in content-path order, so this only re-states
     // the guarantee findings depend on: they read top to bottom.
     notes.sort((a, b) => (a.absPath < b.absPath ? -1 : 1));
@@ -291,7 +301,7 @@ function checkRenamedFrom({ fm, file }, raw) {
  */
 export function lintContentTree(
     contentBase,
-    { skipDirectories, contentPackage, config, records, problems } = {},
+    { skipDirectories, contentPackage, config, records, problems = [] } = {},
 ) {
     const findings = [];
     const notes = collectNotes(contentBase, { skipDirectories, config, records, problems });

package/engine/content-tables.mjs

@@ -11,6 +11,9 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { completeAddress, renderAddress, isAddressTuple } from "./address.mjs";
+import { contentPackage } from "./content-package.mjs";
+
 /**
  * Generated content tables — Obsidian **Dataview** `TABLE` queries.
  *
@@ -702,6 +705,7 @@ export function resolveField(doc, path) {
 
 /** Render a value as the plain text a comparison or a cell works with. */
 function asText(value) {
+    if (isAddressTuple(value)) return renderAddress(value);
     if (value == null) return "";
     if (isLink(value)) return value.display;
     if (Array.isArray(value)) return value.map(asText).join(", ");
@@ -1035,7 +1039,11 @@ export function renderContentTable(spec, rows, linkable, self) {
             // table cell; the resolvers unescape it before splitting, so the
             // display text itself must not carry one.
             const label = text.replace(/\\?\|/g, "/");
-            return `[[${doc.fm.type}/${doc.fm.shortcode}\\|${label}]]`;
+            const target = completeAddress(
+                { type: doc.fm.type, shortcode: doc.fm.shortcode },
+                { package: doc.fm.package ?? contentPackage(), system: "none" },
+            );
+            return `[[${renderAddress(target)}\\|${label}]]`;
         }),
     );
 

package/engine/field-spec.mjs

@@ -138,10 +138,27 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   several do — `weight` is coerced leniently but is still a number, and
  *   `weight: heavy` is an authoring mistake worth reporting where it was made.
  *   Absent means the lint makes no claim about the value.
- * @property {string} [ref] - The content type a value addresses by shortcode,
- *   for the linter's dead-reference check. Only for references to a **note**:
- *   `bodyLocationCode` names a part inside a being's own body structure, not a
- *   note, so it declares none.
+ * @property {string} [code] - The content type a value names by **Shortcode**,
+ *   for the linter's dead-reference check. The authored value is one segment —
+ *   held to {@link module:engine/address-charset.ADDRESS_SEGMENT_PATTERN} —
+ *   persisted verbatim into the emitted field and resolved at runtime among
+ *   the items embedded on one actor, where packages do not exist; the linter
+ *   still forms the `type-shortcode` pair to check it against the index. Only
+ *   for references to a **note**: `bodyLocationCode` names a part inside a
+ *   being's own body structure, not a note, so it declares none. Distinct
+ *   from a `DataFieldSpec`'s `ref` ({@link module:engine/note-vocabulary}),
+ *   which names an **Address** instead.
+ * @property {import("./address-fields.mjs").AddressPosition} [address] - The
+ *   authored value is an Address. The emitted value is its Shortcode, or the
+ *   exact published Item UUID when `emit: "uuid"` is declared. The
+ *   statement carries the default type an omitted `<type>` segment takes, the
+ *   set of types the position accepts — two separate things, which coincide at
+ *   most positions — and where the Addresses sit: the value itself, every
+ *   element of a list, or every key of a map.
+ *   {@link module:engine/address-fields.reduceAddressFields} performs the
+ *   reduction once the block is assembled, so a value authored at the
+ *   destination is reduced along with one this field read. Distinct from `code`,
+ *   which is a Shortcode at both ends and resolves nothing.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
  * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when

package/engine/folder-notes.mjs

@@ -53,7 +53,9 @@ import path from "node:path";
 
 import log from "loglevel";
 
-import { NO_SYSTEM, canonicalKey } from "./content-address.mjs";
+import { isAddressTuple } from "./address.mjs";
+import { NO_SYSTEM, canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import { parseAddress, renderAddress } from "./address.mjs";
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 import { makeId } from "./ids.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
@@ -65,6 +67,14 @@ import { locateFrontmatterKey } from "./retired-fields.mjs";
  */
 export const FOLDER_TYPE = "folder";
 
+/**
+ * The one type a folder reference may name — {@link parseAddress}'s
+ * vocabulary for a position that accepts exactly one.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const FOLDER_TYPES = Object.freeze(new Set([FOLDER_TYPE]));
+
 /**
  * The id namespace a derived folder id is hashed under.
  *
@@ -135,6 +145,7 @@ function folderFields(fm) {
     const read = (key) => data[key] ?? fm?.[key];
     const text = (value) => {
         if (value == null) return null;
+        if (isAddressTuple(value)) return value;
         const trimmed = String(value).trim();
         return trimmed === "" ? null : trimmed;
     };
@@ -142,7 +153,12 @@ function folderFields(fm) {
     const authored = read("parent");
     /** @type {Record<string, string|null>} */
     const parent = {};
-    if (authored != null && typeof authored === "object" && !Array.isArray(authored)) {
+    if (
+        authored != null &&
+        typeof authored === "object" &&
+        !Array.isArray(authored) &&
+        !isAddressTuple(authored)
+    ) {
         // An explicit `~` under a pack key means "at the root *there*", which
         // is a different statement from saying nothing — so the key is kept
         // with a null value rather than dropped.
@@ -157,8 +173,8 @@ function folderFields(fm) {
 /**
  * An authored `parent` with any wikilink brackets and label stripped.
  *
- * The specification types `parent` as a `WikiLink`, and a frontmatter link is
- * written as a bare address — but `[[address]]` is what an author reaches for,
+ * The specification types `parent` as an `Address`, written bare — but
+ * `[[address]]` is what an author reaches for,
  * and Obsidian wrote that form for years. Accepting both costs one regex and
  * removes a failure whose message would have to explain the difference.
  *
@@ -166,6 +182,7 @@ function folderFields(fm) {
  * @returns {string|null} The bare address.
  */
 export function bareAddress(value) {
+    if (isAddressTuple(value)) return value;
     if (value == null) return null;
     const text = String(value).trim();
     if (!text) return null;
@@ -280,14 +297,15 @@ export function collectFolderNotes(notes, pkg) {
 }
 
 /**
- * Index folder notes by every form an author may address one by, and check the
- * invariants that make the index sound.
+ * Index folder notes by their canonical address, and check the invariants
+ * that make the index sound.
  *
- * Three keys per folder, and no more: the canonical address, the
- * `folder-<shortcode>` short form, and the bare shortcode. They are the
- * suffixes of the canonical address the grammar admits — a `packFolder`
- * or `parent` field supplies the type itself, so a bare shortcode is a complete
- * address there.
+ * A folder reference is resolved by {@link parseAddress}, taking `folder` as
+ * the type an omitted segment fills in — the same suffix ladder every other
+ * position climbs, so `cooking`, `folder-cooking` and the full address all
+ * expand to the one key this index holds. A `packFolder` or `parent` field
+ * supplies no type of its own; the position's default is what makes a bare
+ * shortcode a complete address there.
  *
  * @param {FolderNote[]} folders - From {@link collectFolderNotes}.
  * @returns {{byKey: Map<string, FolderNote>, folders: FolderNote[],
@@ -303,6 +321,12 @@ export function buildFolderNoteIndex(folders) {
     const byShortcode = new Map();
     /** @type {Map<string, FolderNote>} */
     const byId = new Map();
+    // Every folder in one content tree shares one package — a `Folder` is
+    // filed inside the module this build compiles, and nothing addresses one
+    // in another package. Read from the first folder's own canonical address
+    // rather than threaded through as a parameter, so a caller holding
+    // `FolderNote[]` never has to carry the package alongside it.
+    const pkg = folders.length ? readCanonicalKey(folders[0].address)?.package : undefined;
 
     for (const folder of folders) {
         const key = folder.shortcode.toLowerCase();
@@ -339,8 +363,6 @@ export function buildFolderNoteIndex(folders) {
         byId.set(folder.id, folder);
 
         byKey.set(folder.address.toLowerCase(), folder);
-        byKey.set(`${FOLDER_TYPE}-${folder.shortcode}`.toLowerCase(), folder);
-        byKey.set(key, folder);
     }
 
     /**
@@ -355,11 +377,18 @@ export function buildFolderNoteIndex(folders) {
         if (!address) {
             throw new Error("a folder reference is blank");
         }
-        const hit = byKey.get(address.toLowerCase());
+        const tuple = parseAddress(address, {
+            package: pkg,
+            system: NO_SYSTEM,
+            type: FOLDER_TYPE,
+            types: FOLDER_TYPES,
+            packages: pkg ? new Set([pkg]) : undefined,
+        });
+        const hit = tuple.reason ? undefined : byKey.get(renderAddress(tuple).toLowerCase());
         if (!hit) {
             const known = [...byShortcode.values()].map((f) => f.shortcode).sort();
             throw new Error(
-                `no folder note is addressed "${address}" — this package ` +
+                `no folder note is addressed "${isAddressTuple(address) ? renderAddress(address) : address}" — this package ` +
                     `declares ${known.length} folder(s)` +
                     (known.length ? `: ${known.join(", ")}` : ""),
             );

package/engine/foundry-entries.mjs

@@ -58,6 +58,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { noteAddressContext } from "./note-addresses.mjs";
 import { canonicalKey, packageAddress } from "./content-address.mjs";
 import { NO_SYSTEM, systemOf } from "./document-subtypes.mjs";
 import {
@@ -320,6 +321,7 @@ export function collectFoundryEntries(contentBase, ctx) {
     let notes = 0;
     for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(contentBase, {
         skipDirectories: ctx.skipDirectories,
+        addressContext: ctx.addressContext ?? { package: ctx.contentPackage },
     })) {
         if (!fm) continue;
         // Its authored pin, or the id derived from its canonical address.
@@ -376,6 +378,7 @@ export function collectFoundryEntries(contentBase, ctx) {
 export function foundryIdentities(config = loadPackConfig()) {
     return {
         contentPackage: config.contentPackage,
+        addressContext: noteAddressContext(config),
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
         // Carried in the context rather than read from the global config at the