@heroiclands/package-build 20.4.0 → 20.6.0

package/engine/bundles.mjs

@@ -119,6 +119,15 @@ export function loadBundleSources(sourceDirs) {
     return documents;
 }
 
+/**
+ * Adventure pack compiler.
+ *
+ * Walks the content tree and compiles every `type: bundle` note into one
+ * Adventure per system, holding **copies** of the compiled documents its
+ * `contents` addresses name. Reading other passes' output is what
+ * {@link Bundles.readsPackOutputOf} declares, and what the generator orders the
+ * compile by.
+ */
 export class Bundles extends BasePackCompiler {
     static id = "bundles";
     static label = "bundle";

package/engine/content-address.mjs

@@ -81,11 +81,11 @@ export const KB_PREFIX = "kb/";
  * consumer deriving a `path` from a key drops the *package and the system*, not
  * the package alone.
  *
- * 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.
+ * The hyphen is a separator and never occurs inside a segment: a shortcode
+ * matches `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`, 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`.
@@ -311,10 +311,10 @@ export const CANONICAL_KEY_SEGMENTS = 4;
  *
  * 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 is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `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 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

package/engine/content-index.mjs

@@ -259,19 +259,6 @@ export function asciiAliases(aliases) {
     return aliases.map((alias) => asciiName(alias)).filter((alias) => alias !== null);
 }
 
-/**
- * Build one index record from a note's frontmatter and its place in the tree.
- *
- * @param {object} options - Options.
- * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
- * @param {string} options.relPath - Its path below the content root, POSIX-separated.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
- * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
- * @throws {Error} When the note carries a key this module derives, which would
- *   otherwise be overwritten without a word.
- */
 /**
  * This note's Foundry addresses, or `null` where it has none.
  *
@@ -410,6 +397,29 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
     }
 }
 
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * The frontmatter as authored, plus what the index derives from it: the package
+ * it compiles as, its address, ASCII folds of its name and aliases, the anchors
+ * of its body, its Foundry block, the address of its documentation journal, and
+ * where the file sits within the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} [options.absPath] - The file, read only on the failing path to
+ *   locate the offending key.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word. `file` and, where the file was
+ *   read, `position` ride on the error.
+ */
 export function buildIndexRecord({
     frontmatter,
     relPath,
@@ -466,16 +476,6 @@ export function buildIndexRecord({
     );
 }
 
-/**
- * Read a content tree into index records, in the order they will be written.
- *
- * @param {string} contentBase - The content tree to walk.
- * @param {object} options - Options.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
- * @returns {Array<Record<string, any>>} The records, in a total order that does
- *   not depend on directory-read order.
- */
 /**
  * The record for an item note's **documentation journal**.
  *
@@ -531,6 +531,27 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
     );
 }
 
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * An item note yields two records — the item, and the documentation journal
+ * that is a document in its own right.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {readonly string[]} options.skipDirectories - The walk's scope, stated
+ *   by the caller. An absent one is the caller's omission, and
+ *   {@link module:engine/helpers.walkMarkdownTree} throws on it.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
+ *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
+ *   note throws — the contract the emitter needs, since an index missing a note
+ *   asserts that it does not exist.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
 export function collectContentIndex(
     contentBase,
     { contentPackage, skipDirectories, manifest, problems },

package/engine/content-links.mjs

@@ -301,17 +301,6 @@ export function buildLinkIndex(
         return out;
     }
 
-    /**
-     * The note an **address** names, or `undefined`.
-     *
-     * The qualifier is read with {@link readQualifier} rather than a second
-     * copy of the rule, so this cannot drift from what the builds do — the two
-     * separators, the first-hyphen split, and the optional leading package
-     * segment.
-     *
-     * @param {string} target - The link target, anchor already removed.
-     * @returns {object|undefined} The note it addresses.
-     */
     /**
      * Every indexed entry an address names, matching only the segments it
      * supplies.
@@ -351,6 +340,20 @@ export function buildLinkIndex(
         return matchAddress([...byKey], q).map(([, v]) => v);
     }
 
+    /**
+     * The note an **address** names, or `undefined`.
+     *
+     * The qualifier is read with {@link readQualifier} rather than a second
+     * copy of the rule, so this cannot drift from what the builds do — the two
+     * separators, the first-hyphen split, and the optional leading package
+     * segment.
+     *
+     * @param {string} target - The link target, anchor already removed.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under, which supplies the system an omitted segment defaults to — see
+     *   {@link blockSystem}. Body prose has none.
+     * @returns {object|undefined} The note it addresses.
+     */
     function resolveAddress(target, keyPath) {
         const qualified = readQualifier(target, types, packages);
         if (!qualified || qualified.reason) return undefined;
@@ -379,6 +382,9 @@ export function buildLinkIndex(
      * rather than collapsed here.
      *
      * @param {string} target - The link target.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under, which supplies the system an omitted segment defaults to — see
+     *   {@link blockSystem}. Body prose has none.
      * @returns {object[]} The foreign entries, each carrying its `package`.
      */
     function foreignHits(target, keyPath) {
@@ -411,6 +417,32 @@ export function buildLinkIndex(
         return hits.length === 1 ? hits[0] : null;
     }
 
+    /**
+     * The note or foreign entry a **frontmatter reference** names, or null.
+     *
+     * 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.
+     *
+     * 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 reference as `type-shortcode`.
+     * @returns {object|null} The note or foreign entry declaring it.
+     */
+    function referenceHit(target) {
+        const q = readQualifier(target, types, packages);
+        if (!q || q.reason) return null;
+        const local = matchAddress([...byKey], q);
+        if (local.length) return local[0][1];
+        const abroad = matchAddress([...foreign.index], q);
+        return abroad.length ? abroad[0][1] : null;
+    }
+
     return {
         notes,
         frontmatterLinks,
@@ -434,6 +466,7 @@ export function buildLinkIndex(
         resolveAddress,
         manifestHit,
         foreignHits,
+        referenceHit,
         /** Whether a target reads as a qualified address at all. */
         isAddress: (target) => Boolean(readQualifier(target, types, packages)),
     };

package/engine/content-lint.mjs

@@ -22,10 +22,10 @@
  * disagree without anything detecting it, which the canonical-separator
  * handling already did once on each side.
  *
- * Four rules, all about a note's identity:
+ * Five rules, all about a note's identity:
  *
- * 1. **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the
- *    identity key referenced from saved world data, and it is half of the
+ * 1. **Shape** — a `shortcode` is strictly lowercase ASCII-alphanumeric. It is
+ *    the identity key referenced from saved world data, and it is half of the
  *    `type-shortcode` address, whose parse depends on the separating hyphen
  *    being the only hyphen in the string.
  * 2. **Uniqueness** — `(type, shortcode)` names one note.
@@ -39,6 +39,10 @@
  *    rule 2 read backwards, and it needs the same whole-tree view: an entry can
  *    only be checked against every *other* note's address, and two notes
  *    claiming one predecessor is the uniqueness rule applied to the past.
+ * 5. **The vocabulary a package's kind leaves it** — a package compiling no
+ *    Foundry documents publishes `doc` and `homepage` notes and nothing else.
+ *    It is here rather than with the claim check in `note-claims.mjs` because
+ *    that check runs at compile, and this is the case where no compile runs.
  *
  * **Nothing here writes.** A check reports and an author fixes.
  *
@@ -61,6 +65,9 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
+// The kind that compiles nothing, and the vocabulary that leaves a tree with.
+import { DOCUMENTATION_KIND, compilesFoundryDocuments } from "../content-config.mjs";
+import { DOCUMENTATION_NOTE_TYPES } from "./note-claims.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { assertStatedScope } from "./helpers.mjs";
 // The corpus, read from the one pass that derives it.
@@ -69,7 +76,8 @@ import { checkHomepageCount, isHomepage } from "./homepage.mjs";
 import { declaresRenamedFrom, renamedFrom, renamedFromEntries } from "./note-renames.mjs";
 
 /**
- * The shape every `shortcode` must match: ASCII letters and digits only.
+ * The shape every `shortcode` must match: lowercase ASCII letters and digits
+ * only.
  *
  * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
  * is the last segment of a canonical address, and the rule it is held to is the
@@ -77,9 +85,10 @@ import { declaresRenamedFrom, renamedFrom, renamedFromEntries } from "./note-ren
  * free to drift apart. The name survives because this is where the rule
  * is applied to a note.
  *
- * Case is deliberately **not** constrained: hundreds of authored shortcodes are
- * mixed-case and collide with nothing, so tightening that is a separate
- * decision from this one.
+ * Case is held to that rule with no exception: two shortcodes differing only
+ * in case are two names nobody can tell apart, and `canonicalKey` lowercases
+ * every address it builds regardless, so a mixed-case shortcode addresses the
+ * same document as its lowercase spelling.
  *
  * A consuming system's *runtime* keeps its own copy of this pattern — it cannot
  * import a build-time dependency into shipped code — and is expected to pin the
@@ -225,8 +234,9 @@ function checkRenamedFrom({ fm, file }, raw) {
                 ...at(value),
                 severity: "error",
                 message:
-                    `\`renamedFrom: ${value}\` is not strictly alphanumeric, so ` +
-                    `it is not an address this package ever published — a ` +
+                    `\`renamedFrom: ${value}\` is not strictly alphanumeric — ` +
+                    `lowercase letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}) — ` +
+                    `so it is not an address this package ever published — a ` +
                     `shortcode is held to one charset whether it is current or past`,
             });
             continue;
@@ -285,6 +295,12 @@ export function lintContentTree(
 ) {
     const findings = [];
     const notes = collectNotes(contentBase, { skipDirectories, config, records, problems });
+    // Whether this package's note vocabulary is the narrowed one. Asked of the
+    // configuration once rather than per note, and defaulted to the wide
+    // vocabulary when a caller supplies none — an unconfigured lint holds a
+    // tree to the rules every package shares.
+    const narrowed =
+        Boolean(config) && !compilesFoundryDocuments(/** @type {{packageKind: string}} */ (config));
 
     /** @type {Map<string, Array<{file: string, absPath: string}>>} */
     const byKey = new Map();
@@ -299,6 +315,23 @@ export function lintContentTree(
         // tree costs one pass rather than two.
         const raw = () => fs.readFileSync(absPath, "utf8");
 
+        // Rule 5, and it is the whole of the check for a package that compiles
+        // nothing: no pass downstream would report the note, because the pass
+        // that reports an unclaimed type is a compile pass and none runs.
+        const type = typeof fm.type === "string" ? fm.type.trim() : "";
+        if (narrowed && type && !DOCUMENTATION_NOTE_TYPES.has(type)) {
+            findings.push({
+                file,
+                ...positionInFrontmatter(raw(), "type", type),
+                severity: "error",
+                message:
+                    `\`type: ${type}\` compiles to a Foundry document, and a ` +
+                    `\`${DOCUMENTATION_KIND}\` package compiles none — so the ` +
+                    `note has no destination. Its vocabulary is ` +
+                    `${[...DOCUMENTATION_NOTE_TYPES].map((t) => `\`${t}\``).join(" and ")}`,
+            });
+        }
+
         // Before the keyless `continue` below, because a note declaring a
         // rename while carrying no address of its own is exactly one of the
         // things this reports — and reaching it after the skip would mean it
@@ -332,7 +365,8 @@ export function lintContentTree(
                 ...positionInFrontmatter(raw(), "shortcode", String(shortcode)),
                 severity: "error",
                 message:
-                    `shortcode "${shortcode}" is not strictly alphanumeric; it ` +
+                    `shortcode "${shortcode}" is not strictly alphanumeric — ` +
+                    `lowercase letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}); it ` +
                     `is the identity key and half of the ` +
                     `"${fm.type}-${shortcode}" address, whose parse needs the ` +
                     `separator to be the only hyphen`,

package/engine/content-tables.mjs

@@ -1059,17 +1059,32 @@ export function renderContentTable(spec, rows, linkable, self) {
 /* ------------------------------------------------------------------------ */
 
 /**
- * Expand every fenced `dataview` block in a markdown body.
+ * The `WHERE` clause of a query, as authored, for a message that has to name
+ * what matched nothing.
+ *
+ * The parsed spec holds an expression tree, and rendering that back to text
+ * would be a second dialect of the query language to keep in step. The authored
+ * line is what the author wrote and what they will edit, so it is what the
+ * finding quotes.
+ *
+ * @param {string} query - The fence's contents.
+ * @returns {string} The clause, or "" when the query has none.
+ */
+function whereText(query) {
+    const match = /^\s*WHERE\s+(.+?)\s*$/im.exec(String(query ?? ""));
+    return match ? `\`${match[1]}\`` : "";
+}
+
+/**
+ * Expand every fenced `dataview` and `sql` block in a markdown body.
  *
  * A block that cannot be honoured — malformed or unsupported — is left in the
  * body verbatim and reported in `errors`, so the failure is visible in the
  * output as well as on the console. Every other code fence, and every code
  * span, is left alone (that is how the syntax is documented).
  *
- * A query that matches **no** note is not an error: it renders as an empty
- * table (headers only), which is what the author already sees in Obsidian, and
- * a category with no content yet is a normal state of the corpus rather than a
- * broken build.
+ * A query that selects **no** note is an error unless the fence says
+ * `allow-empty`, which states that an empty table is the intended result.
  *
  * @param {string} markdown - The note body, frontmatter already stripped.
  * @param {object} ctx
@@ -1080,30 +1095,20 @@ export function renderContentTable(spec, rows, linkable, self) {
  * @param {string} [ctx.source] - The note being expanded, for error reports.
  * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
  *   doc: what a query's `this` reads.
+ * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
+ *   document order, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
+ *   no prepared result is an error: nothing here runs a query.
  * @returns {{markdown: string, errors: Array<{source: string, directive: string,
- *   reason: string, line: number}>, lineMap: Array<{line: number,
- *   generated: boolean}>}} `lineMap` is parallel to the emitted lines and says
- *   which authored line each came from, so a diagnostic about the expanded
- *   body can name an authored position. An `errors` entry carries the
- *   0-based line of the directive that failed, for the same reason.
+ *   reason: string, line: number, column?: number}>,
+ *   warnings: Array<{source: string, line: number, column: number,
+ *   reason: string}>, lineMap: Array<{line: number, generated: boolean}>}}
+ *   `lineMap` is parallel to the emitted lines and says which authored line
+ *   each came from, so a diagnostic about the expanded body can name an
+ *   authored position. An `errors` entry carries the 0-based line of the
+ *   directive that failed, for the same reason. `warnings` holds one entry per
+ *   `dataview` directive the body still authors.
  */
-/**
- * The `WHERE` clause of a query, as authored, for a message that has to name
- * what matched nothing.
- *
- * The parsed spec holds an expression tree, and rendering that back to text
- * would be a second dialect of the query language to keep in step. The authored
- * line is what the author wrote and what they will edit, so it is what the
- * finding quotes.
- *
- * @param {string} query - The fence's contents.
- * @returns {string} The clause, or "" when the query has none.
- */
-function whereText(query) {
-    const match = /^\s*WHERE\s+(.+?)\s*$/im.exec(String(query ?? ""));
-    return match ? `\`${match[1]}\`` : "";
-}
-
 export function expandContentTables(
     markdown,
     {

package/engine/folder-notes.mjs

@@ -54,7 +54,7 @@ import path from "node:path";
 import log from "loglevel";
 
 import { NO_SYSTEM, canonicalKey } from "./content-address.mjs";
-import { isAddressSegment } from "./address-charset.mjs";
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 import { makeId } from "./ids.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 
@@ -242,7 +242,9 @@ export function collectFolderNotes(notes, pkg) {
             throw Object.assign(
                 new Error(
                     `folder shortcode "${shortcode}" is not strictly ` +
-                        `alphanumeric, so its address would not parse: ${absPath}`,
+                        `alphanumeric — lowercase letters and digits only ` +
+                        `(${ADDRESS_SEGMENT_PATTERN.source}) — so its address ` +
+                        `would not parse: ${absPath}`,
                 ),
                 { absPath },
             );

package/engine/frontmatter-lint.mjs

@@ -583,9 +583,9 @@ function checkKeyedMap(note, { field, segments, entries, raw, packs }) {
  *
  * **Two checks, in this order** — the charset, then the closed set. The
  * charset is first because it is the more general statement about
- * the same value: a value outside `^[A-Za-z0-9]+$` is refused whatever the type
- * declares, and only once it is a well-formed term is the type's own list the
- * reason to refuse it.
+ * the same value: a value outside `ADDRESS_SEGMENT_PATTERN` is refused
+ * whatever the type declares, and only once it is a well-formed term is the
+ * type's own list the reason to refuse it.
  *
  * There is deliberately no third, retired-spelling check ahead of them
  * accepting `user-guide` as a warning naming `userguide`. Every consumer tree
@@ -674,7 +674,8 @@ function checkSubType(note, { type, entry }) {
  *
  * @param {object} note - The note.
  * @param {object} opts
- * @param {readonly string[]} opts.tags - Every declared tag, flattened.
+ * @param {string} opts.type - The note's declared `type`, which scopes the
+ *   groups checked against.
  * @returns {object[]} Findings.
  */
 function checkTags(note, { type }) {
@@ -729,6 +730,27 @@ const ART_FIELDS = Object.freeze([
     Object.freeze({ key: "portrait", inData: true }),
 ]);
 
+/**
+ * The keys a field declaration is authored at **inside a system block**.
+ *
+ * The first segment of each field's in-block key: `impact.die` is authored as
+ * `impact`, and a field whose shared source moved under `data:` is authored at
+ * the `legacyKey` it declares rather than at its dotted name. Keying on
+ * the name instead would report `sohl.species` as a property no `being` has,
+ * against exactly the notes the sweep has not reached yet.
+ *
+ * Written once and read twice: the note type's own declaration answers for the
+ * system whose vocabulary the caller's `schemas` are, and a second system's
+ * registry answers for its block. Two derivations of one thing would be
+ * free to disagree about which position a note authors.
+ *
+ * @param {readonly object[]|null|undefined} schema - A type's declarations.
+ * @returns {Set<string>} The in-block keys.
+ */
+function inBlockKeys(schema) {
+    return new Set(authoredFields(schema ?? []).map((f) => legacyKeyOf(f).split(".")[0]));
+}
+
 /**
  * The in-block keys a type's own declarations claim for a *different* quantity.
  *
@@ -756,27 +778,6 @@ const ART_FIELDS = Object.freeze([
  * @returns {Set<string>} The in-block keys that are not the note-level field of
  *   the same name.
  */
-/**
- * The keys a field declaration is authored at **inside a system block**.
- *
- * The first segment of each field's in-block key: `impact.die` is authored as
- * `impact`, and a field whose shared source moved under `data:` is authored at
- * the `legacyKey` it declares rather than at its dotted name. Keying on
- * the name instead would report `sohl.species` as a property no `being` has,
- * against exactly the notes the sweep has not reached yet.
- *
- * Written once and read twice: the note type's own declaration answers for the
- * system whose vocabulary the caller's `schemas` are, and a second system's
- * registry answers for its block. Two derivations of one thing would be
- * free to disagree about which position a note authors.
- *
- * @param {readonly object[]|null|undefined} schema - A type's declarations.
- * @returns {Set<string>} The in-block keys.
- */
-function inBlockKeys(schema) {
-    return new Set(authoredFields(schema ?? []).map((f) => legacyKeyOf(f).split(".")[0]));
-}
-
 function collidingBlockKeys(schema) {
     const keys = new Set();
     if (!Array.isArray(schema)) return keys;
@@ -909,8 +910,9 @@ function checkEmbeddedShortcodes(note, blockName) {
  * @param {object} note - A note from the link index (`{fm, file, raw, type}`).
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
- * @param {object} [opts.index] - The link index, for the reference check. Its
- *   absence skips that check rather than reporting every reference as dead.
+ * @param {object} [opts.index] - The link index, for the reference check, which
+ *   runs through its `referenceHit`. Its absence skips that check rather than
+ *   reporting every reference as dead.
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares, as `engine/note-vocabulary.mjs` states them. Supplied
  *   by the caller for the same reason `schemas` is: this module validates a
@@ -1466,19 +1468,14 @@ export function lintNote(
             continue;
         }
 
-        // A reference names another note by shortcode. Resolved through the
-        // link index's own resolver, so a cross-package reference answered by a
-        // fetched index lands exactly as the same address in a wikilink
-        // would — rather than through a second, subtly different rule.
-        //
-        // **As an address, always** — which is now the only namespace there
-        // is. A frontmatter reference is a bare address by construction:
-        // there is no pipe to read intent from, and the field supplies the
-        // type. The resolver once took a namespace argument, and omitting it
-        // read every `ref:` value as an alias, which `type-shortcode` never was.
+        // A reference names another note by shortcode, and the field supplies
+        // the type, so the resolver is handed the whole `type-shortcode` pair.
+        // It resolves in any reachable package: the value is persisted as
+        // written and looked up at runtime among one actor's embedded items,
+        // which come from every package the actor draws on.
         if (field.ref && index && typeof value === "string" && value) {
             const target = `${field.ref}-${value}`;
-            if (!index.resolve(target) && !index.manifestHit(target)) {
+            if (!index.referenceHit(target)) {
                 findings.push({
                     file: note.file,
                     ...at(head, value),

package/engine/generate.mjs

@@ -403,6 +403,11 @@ export function unsatisfiedPassDependencies(running, config) {
  *     document type that routes nowhere. True for the first configured pack of
  *     the type, so one unroutable note yields one error rather than one per
  *     pack.
+ * @param {object} folderNotes - The folder index, which resolves a note's
+ *     `packFolder` address to a Foundry folder id and its ancestor chain.
+ * @param {object} corpus - The corpus this compile derived once, shared by
+ *     every pass so that no two answer "which files are the corpus?"
+ *     differently.
  * @returns {Promise<{errors: number, compiled: number}>} The compiler's error
  *     count (0 on success) and the number of entries it wrote.
  */