@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/system-block.mjs

@@ -28,7 +28,7 @@
  * | `<system>.flags` | `document.flags` |
  * | `<system>.pack` | *nothing on the document* — a build directive naming the compendium |
  *
- * Everything else a system declares — `archetype`, `kbcat`, and the
+ * Everything else a system declares — `templatePriority`, `kbcat`, and the
  * *generators* `items` and `attributes`, which expand into embedded documents
  * rather than mapping anywhere — sits directly under the block, which is why it
  * has to be somewhere the schema cannot claim.
@@ -46,12 +46,35 @@
  * order for a system `S` is:
  *
  * 1. `S.system.<to>` — authored directly, wins outright;
- * 2. `S.<name>` — the legacy in-block position the corpus still writes, kept
- *    until #126 moves it;
+ * 2. `S.<legacyKey>` — the legacy in-block position the corpus still writes,
+ *    kept until #126 moves it;
  * 3. the shared top-level property the field **declares** as its source, which
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
  * 4. the field's own default.
  *
+ * ## Steps 2 and 3 are two declarations, because they are two positions
+ *
+ * They used to be one: both were keyed on `name`, which was fine only while the
+ * shared source and the in-block key were the same word. `data:` (#128) ended
+ * that — a shared source is now a path *into* a container, so `data.species`
+ * and `species` are two spellings of two different places, and no single value
+ * of `name` reached both. `name: "species"` read `hm3.species` and could not
+ * see `data.species`; `name: "data.species"` read the shared source and could
+ * not see `hm3.species`. Each yielded the field's **default** wherever only the
+ * other position was authored — silently, since the field compiles and the
+ * document is emitted with the value simply gone (#305).
+ *
+ * That made every move into `data:` a flag day. Each of this package's other
+ * retirements — `package:`, `image`, `archetype`, `relation` — works because
+ * *both spellings are read while the corpus moves*, and one property could not
+ * offer that here.
+ *
+ * So a field declares `legacyKey` beside `name`: the key it is authored at
+ * inside the block, which step 2 reads and which **falls back to `name`** when
+ * absent, so every declaration written before this resolves unchanged. A field
+ * that declares one is mid-sweep by construction, which is what
+ * {@link module:engine/field-spec.readsLegacyKey} reports on.
+ *
  * ## A name that collides across the two vocabularies skips step 3
  *
  * A field's `name` is both its identity and the shared property it draws from,
@@ -148,7 +171,7 @@ export const BLOCK_DIRECTIVES = Object.freeze(["pack"]);
 /**
  * Every key any system block may carry, whatever the system.
  *
- * A system adds its own on top — `archetype`, `kbcat` and the generators — and
+ * A system adds its own on top — `templatePriority`, `kbcat` and the generators — and
  * names them where it declares its vocabulary; see {@link unknownBlockKeys}.
  *
  * @type {ReadonlySet<string>}
@@ -312,6 +335,27 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
     return shared === undefined || shared === null ? defaultValue : shared;
 }
 
+/**
+ * The key a field is authored at **inside** a system block — step 2.
+ *
+ * `legacyKey` when the field declares one, and `name` otherwise. The fallback
+ * is what makes this change invisible to every declaration written before it:
+ * a field whose shared source and in-block key are the same word says so once,
+ * as it always did.
+ *
+ * Named and exported rather than spelled inline because three readers ask the
+ * question and must agree — the resolver here, the frontmatter lint building
+ * the set of keys a block may carry, and the author-facing surfaces naming
+ * where a value was written.
+ *
+ * @param {{name?: string, legacyKey?: string}} field - The declaration.
+ * @returns {string|undefined} The in-block key, or `undefined` for a field that
+ *   is not authored at all.
+ */
+export function legacyKeyOf(field) {
+    return field?.legacyKey ?? field?.name;
+}
+
 /**
  * Where a declared field's value came from.
  *
@@ -356,16 +400,19 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
         if (own !== undefined) return { value: own, from: "system" };
     }
 
-    // 2. The legacy in-block position. Every note in every tree writes here
-    //    today, and will until #126 moves them; dropping it would be a corpus
-    //    migration disguised as a mechanism change.
+    // 2. The legacy in-block position, keyed on `legacyKey` — the shared
+    //    source is a path into `data:` and the in-block key is a bare word, so
+    //    the two are declared separately (#305). Every note in every tree
+    //    writes here today, and will until #126 moves them; dropping it would
+    //    be a corpus migration disguised as a mechanism change.
     const declared = systemBlock(fm, block);
-    if (declared) {
-        if (field.name in declared) {
-            const value = declared[field.name];
+    const legacyKey = legacyKeyOf(field);
+    if (declared && legacyKey) {
+        if (legacyKey in declared) {
+            const value = declared[legacyKey];
             return { value: value ?? field.default, from: "block" };
         }
-        const nested = getFrontmatter(declared, field.name, undefined);
+        const nested = getFrontmatter(declared, legacyKey, undefined);
         if (nested !== undefined) return { value: nested, from: "block" };
     }
 
@@ -421,6 +468,24 @@ export function systemDataPaths(data, prefix = "") {
  * this is the difference between "the field is lost at load" and "the build
  * told you where".
  *
+ * **A declared *leaf* holds values, not fields.** A schema declares a path that
+ * has no children of its own for two ordinary reasons — a map with **dynamic
+ * keys** (`mystery.skillAptitudes` is skill selector → modifier) and a
+ * **TypedSchemaField** (`strikeModes`, discriminated by `type`) — and in both
+ * the contents are data an author wrote, not paths the schema names. Walking
+ * into one reports every entry as an undeclared field: one finding per skill
+ * aptitude, per strike mode, per standing.
+ *
+ * It stayed invisible while those maps were authored *outside* `<system>.system`
+ * and so were never walked. The moment the corpus moves them to the destination
+ * (#126) every one of them lights up — 62 findings on `sohl-thalorna` alone,
+ * none of them a defect.
+ *
+ * So descent is conditional on the schema declaring something *beneath* the
+ * path. `body.structure` declares `parts` and `zones`, so it is a real
+ * container and an undeclared `adjacent` under it is a real finding;
+ * `skillAptitudes` declares nothing beneath it, so what is beneath is a value.
+ *
  * @param {Record<string, unknown>} data - The authored `system` data.
  * @param {ReadonlySet<string>} declared - Every field path the schema declares
  *   for this subtype, inherited ones included.
@@ -436,7 +501,7 @@ export function undeclaredPaths(data, declared, prefix = "") {
             out.push(path);
             continue;
         }
-        if (isMapping(value) && Object.keys(value).length) {
+        if (isMapping(value) && Object.keys(value).length && declaresChildren(declared, path)) {
             out.push(
                 ...undeclaredPaths(/** @type {Record<string, unknown>} */ (value), declared, path),
             );
@@ -445,6 +510,25 @@ export function undeclaredPaths(data, declared, prefix = "") {
     return out;
 }
 
+/**
+ * Whether the schema declares any path beneath this one.
+ *
+ * The test for "container, not leaf" — see {@link undeclaredPaths}. Asked of
+ * the declared set rather than of the authored value, because it is a question
+ * about the *schema*: an author can nest a map under either.
+ *
+ * @param {ReadonlySet<string>} declared - The declared field paths.
+ * @param {string} path - The path to test.
+ * @returns {boolean} True when something is declared beneath it.
+ */
+function declaresChildren(declared, path) {
+    const prefix = `${path}.`;
+    for (const candidate of declared) {
+        if (candidate.startsWith(prefix)) return true;
+    }
+    return false;
+}
+
 /**
  * Keys directly under a system block that neither this format nor the system
  * recognizes.

package/engine/systems.mjs

@@ -0,0 +1,201 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The closed registry of system ids, and the `none` that stands for no system
+ * at all (#59).
+ *
+ * A canonical address carries the system in a fixed position —
+ * `harnadventures-none-being-grod` — so "which systems exist" is a question the
+ * address grammar asks on every note, and the issue's answer is that it comes
+ * from a **registry rather than from a hardcoded set**: known system ids are
+ * declared here, once, an unknown value is an error, and _adding a system is a
+ * data change_. Before this module the same fact was spelled in as many places
+ * as needed it — a `NO_SYSTEM` constant in the content index, a `map.system`
+ * per document-subtype map, a system-keyed table per compiler — none of which
+ * could refuse a value none of the others had heard of.
+ *
+ * **`none` is a word, deliberately.** It is not a YAML null (`null`, `~`, or an
+ * empty value), because those spell "nobody filled this in", and a note that
+ * belongs to no system has been answered rather than skipped — the distinction
+ * the whole address grammar rests on, since a null cannot occupy a segment.
+ * And it is not `any`, which reads as a wildcard: a `place` does not compile
+ * into every system's document, it compiles into a Foundry core document that
+ * belongs to none of them.
+ *
+ * **A leaf, so that anything may read it.** The only import is the address
+ * charset, itself a leaf with no local imports, so this module can be named by
+ * the configuration loader, by a compiler, and by a lint without closing a
+ * cycle around any of them. In particular the ids are *declared* here rather
+ * than derived from `KNOWN_DOCUMENT_SUBTYPE_MAPS` — deriving them would drag
+ * `sohl/` and `hm3/` behind every import of this file, for a list of two
+ * words. `tests/systems.test.ts` holds the two in step instead, which is where
+ * the agreement between a registry and its implementations belongs.
+ *
+ * @module
+ */
+
+// The one charset, read rather than restated — a system id is an address
+// segment like any other, and a second spelling of the pattern is how the
+// disagreements in #202/#203 happened.
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
+
+/**
+ * The `<system>` segment of a note that belongs to no system.
+ *
+ * Most notes are that: a `doc`, a `place`, a `macro` or a map compiles into a
+ * JournalEntry, a Scene or a Macro, which Foundry defines and no game system
+ * does. `none` is the format's word for it, in the address and in the content
+ * index alike, so the two say "no system" the same way.
+ *
+ * @type {string}
+ */
+export const NO_SYSTEM = "none";
+
+/**
+ * Every game system this toolchain compiles for.
+ *
+ * The registry, and the only place the list is written down. Adding a system
+ * is an edit to this set plus the map and compilers that make it real — a data
+ * change, not a search for every place a name was spelled.
+ *
+ * `none` is **not** a member: it marks the absence of a system, and a caller
+ * asking "is this a system" and a caller asking "is this a well-formed
+ * segment" want different answers. See {@link isSystemId} and
+ * {@link isSystemSegment}.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_IDS = Object.freeze(new Set(["sohl", "hm3"]));
+
+/**
+ * Everything the `<system>` segment of an address may say.
+ *
+ * The systems, plus {@link NO_SYSTEM}. Derived from the registry rather than
+ * listed again, so the two cannot drift.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_SEGMENTS = Object.freeze(new Set([...SYSTEM_IDS, NO_SYSTEM]));
+
+/**
+ * Whether a value names a game system this toolchain knows.
+ *
+ * `none` is rejected: it is a real answer to "which system", but it is not a
+ * system, and a pack, a document-subtype map or a compiler table keyed by it
+ * would be keyed by nothing.
+ *
+ * @param {unknown} value - The candidate id.
+ * @returns {boolean} `true` when {@link SYSTEM_IDS} declares it.
+ */
+export function isSystemId(value) {
+    return typeof value === "string" && SYSTEM_IDS.has(value);
+}
+
+/**
+ * Whether a value is something the `<system>` segment may hold.
+ *
+ * The predicate an address parser wants: a declared system, or `none`.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @returns {boolean} `true` when {@link SYSTEM_SEGMENTS} declares it.
+ */
+export function isSystemSegment(value) {
+    return typeof value === "string" && SYSTEM_SEGMENTS.has(value);
+}
+
+/**
+ * What a caller writing an unknown system is told.
+ *
+ * Separate from {@link assertSystemSegment} so that a pass collecting findings
+ * can report the same sentence it would have thrown — the message is the part
+ * worth sharing, and a reporter that had to invent its own wording is how two
+ * halves of a build come to explain one rule two ways.
+ *
+ * The nullish case is called out by name because it is the likely mistake and
+ * the least legible failure: a YAML `null`, a `~`, or a key written with no
+ * value at all reaches here as `undefined`, and "expected one of sohl, hm3,
+ * none" would leave a reader hunting for the value they cannot see.
+ *
+ * @param {unknown} value - The offending value.
+ * @param {string} [where] - What carried it, for the message — a note path, a
+ *   configuration key, an address.
+ * @returns {string} The message, with no trailing period, in the style of the
+ *   other vocabulary messages.
+ */
+export function unknownSystemMessage(value, where = "the system segment") {
+    const known = [...SYSTEM_SEGMENTS].map((id) => `\`${id}\``).join(", ");
+    if (value == null || value === "") {
+        return (
+            `${where} names no system — an absent value is not how "no system" ` +
+            `is written. A note that belongs to no system says so, with ` +
+            `\`${NO_SYSTEM}\`: the segment is positional, so a null cannot ` +
+            `occupy it, and "answered as none" and "nobody filled this in" ` +
+            `have to stay distinguishable. Known: ${known}`
+        );
+    }
+    return (
+        `${where} names \`${String(value)}\`, which is not a known system. ` +
+        `Known systems come from a closed registry, so adding one is a data ` +
+        `change rather than a value that starts working: ${known}. \`any\` is ` +
+        `not among them either — it reads as a wildcard, and a note outside ` +
+        `every system compiles into a core document rather than into all of them`
+    );
+}
+
+/**
+ * Refuse a value the `<system>` segment may not hold.
+ *
+ * Throws rather than returning a finding, matching the nearest neighbour —
+ * `assertVocabularyCharset` in `engine/note-vocabulary.mjs`, and the
+ * `configFromData` validators — because every caller of this is validating a
+ * declaration rather than surveying content. A note's bad value belongs in a
+ * report; a build asking to route, address or compile an undeclared system has
+ * nowhere to continue to.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @param {string} [where] - What carried it, for the message.
+ * @returns {string} The value, unchanged, so a caller may validate inline.
+ * @throws {Error} Naming the value and the whole known vocabulary.
+ */
+export function assertSystemSegment(value, where = "the system segment") {
+    if (!isSystemSegment(value)) throw new Error(`${unknownSystemMessage(value, where)}.`);
+    return /** @type {string} */ (value);
+}
+
+/**
+ * Refuse a registry declaring an id that could not be an address segment.
+ *
+ * Run over {@link SYSTEM_SEGMENTS} as this module loads, so a declaration that
+ * breaks the charset cannot be imported, let alone shipped. Same reasoning as
+ * `assertVocabularyCharset`: a bad value in one note is one author's mistake,
+ * while a bad *declaration* puts an unreadable segment into every address that
+ * names the system.
+ *
+ * @param {Iterable<string>} segments - The declared ids, including `none`.
+ * @param {string} [where] - What declares them, for the message.
+ * @throws {Error} Naming every offending id at once — a reader fixing a list
+ *   wants the whole list.
+ */
+export function assertSystemCharset(segments, where = "the system registry") {
+    const bad = [...(segments ?? [])].filter((id) => !isAddressSegment(id));
+    if (!bad.length) return;
+    throw new Error(
+        `${where} declares ${bad.map((id) => `"${id}"`).join(", ")}, which ` +
+            `${bad.length === 1 ? "is" : "are"} not ${ADDRESS_SEGMENT_PATTERN.source}. ` +
+            `A system id is a segment of every address that names it, and the ` +
+            `hyphen separates segments rather than occurring inside one.`,
+    );
+}
+
+assertSystemCharset(SYSTEM_SEGMENTS);

package/engine/web-wikilinks.mjs

@@ -43,9 +43,10 @@
 // name (#1409).
 import { readQualifier } from "./wikilinks.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
-// The canonical `package-type-shortcode` key, so a package-qualified address
-// is looked up the way a vendored manifest publishes it.
-import { canonicalKey } from "./kb-manifest.mjs";
+// The canonical `package-system-type-shortcode` key, so a package-qualified
+// address is matched the way a vendored manifest publishes it — by the
+// segments the target supplies, with the system wildcarded unless stated (#59).
+import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
 // The one rule about a link's shape both builds share: it carries a label, and
 // {@link unlabelledLinkMessage} is the one place that says so (#180).
 import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
@@ -84,14 +85,32 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  * @param {object|null} read - From {@link readQualifier}.
  * @returns {string | null} The index key, or `null` when not an address.
  */
-function keyOfRead(read) {
-    if (!read || read.reason) return null;
-    // A package-qualified address keeps its package: the canonical key is what
-    // a vendored manifest publishes, and dropping the segment would resolve
-    // another package's address against this one's short key.
-    return read.package ?
-            canonicalKey(read.package, read.type, read.shortcode)
-        :   `${read.type}/${read.shortcode}`.toLowerCase();
+function lookupRead(index, read) {
+    if (!read || read.reason) return undefined;
+    // An unqualified address stays the system-blind short key, which is the
+    // wildcard an author writing `[[skill-melee]]` means, and resolves within
+    // this package only.
+    if (!read.package) return index.get(`${read.type}/${read.shortcode}`.toLowerCase());
+
+    // A package-qualified one is matched by the segments it supplies, with the
+    // system wildcarded unless stated (#59) — an exact `get` cannot express
+    // that, and would silently miss every address whose system it did not
+    // guess. Exactly one hit resolves; two are an ambiguity for the caller to
+    // report rather than a pick to make here.
+    const type = String(read.type).toLowerCase();
+    const shortcode = String(read.shortcode).toLowerCase();
+    const pkg = String(read.package).toLowerCase();
+    let found;
+    for (const [key, value] of index) {
+        const parts = readCanonicalKey(key);
+        if (!parts) continue;
+        if (parts.package !== pkg) continue;
+        if (read.system && parts.system !== String(read.system).toLowerCase()) continue;
+        if (parts.type !== type || parts.shortcode !== shortcode) continue;
+        if (found) return undefined;
+        found = value;
+    }
+    return found;
 }
 
 /**
@@ -242,8 +261,10 @@ function isPlainMap(value) {
  *
  * **Every target is an address**, parsed by {@link readQualifier} and looked up
  * case-insensitively in the KB-wide `ctx.index` (the canonical
- * `package-type-shortcode`, `type/shortcode`, and the site's own
- * `section/slug`), then in the vendored `ctx.foreign` manifests. A link written
+ * `package-system-type-shortcode`, `type/shortcode`, and the site's own
+ * `section/slug`), then in the vendored `ctx.foreign` manifests. A target is a
+ * *partial* address: an omitted package means this package, an omitted system
+ * is a wildcard, and exactly one match resolves — two are `ambiguous`. A link written
  * without a label addresses nothing at all and is reported as such (#180) —
  * there is no second namespace left for it to name.
  *
@@ -343,10 +364,9 @@ export function resolveWebWikilinks(body, ctx) {
         // recognised. `null` here means the target is not an address at all,
         // which is a defect: there is no other namespace to try.
         const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
-        const hyphenKey = keyOfRead(read);
         const rawKey = target.toLowerCase();
         const hit =
-            (hyphenKey ? ctx.index.get(hyphenKey) : undefined) ??
+            lookupRead(ctx.index, read) ??
             // `section/slug` is the site's own address for a page, and it is in
             // the same map. Admitted only when the target carries a slash, so
             // a page's bare slug cannot answer for an address.
@@ -355,7 +375,7 @@ export function resolveWebWikilinks(body, ctx) {
             // local one (#1446), so a cross-package hit needs no special case
             // below. Local wins: a live build is authoritative and a vendored
             // manifest can only be staler.
-            (hyphenKey ? ctx.foreign?.get(hyphenKey) : undefined);
+            (ctx.foreign ? lookupRead(ctx.foreign, read) : undefined);
         if (hit) {
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**
@@ -384,12 +404,12 @@ export function resolveWebWikilinks(body, ctx) {
         // above already consulted. It parses as no `type/shortcode`, but it did
         // address something and nothing answered — so it is unresolved, not
         // unaddressable. (A prefix that is a content *type* never reaches here:
-        // it yields a `hyphenKey`.)
+        // it parses as an address.)
         const siteAddress = prefix !== null && ctx.sections.has(prefix);
 
         // **An address resolving nowhere is a failure, unconditionally** (#184).
         //
-        // It was gated on `manifestsComplete` — while any linkable package was
+        // It was gated on a manifest-completeness check — while any linkable package was
         // invisible here, `Rules/Bestiary.md` addressing `being-grkrahk` in the
         // `thalorna` package was indistinguishable from a typo, so the form
         // stayed unguarded rather than fail correct content. The gate has
@@ -401,9 +421,19 @@ export function resolveWebWikilinks(body, ctx) {
         // manifest calls for is in the message instead — {@link
         // unresolvedAddressMessage} names both corrections — which informs the
         // author without excusing the link.
+        // The bucket an ambiguity is recorded under is the *short* address —
+        // the only form two packages can collide on, since a qualified one
+        // names its package. A qualified target that matched more than one
+        // document is reported by the matcher instead, not by this set.
+        const collideKey =
+            read && !read.reason && !read.package ?
+                `${read.type}/${read.shortcode}`.toLowerCase()
+            :   rawKey;
         const reason =
-            ctx.collide?.has(hyphenKey ?? rawKey) ? "ambiguous"
-            : hyphenKey !== null || siteAddress ? "unresolved"
+            ctx.collide?.has(collideKey) ? "ambiguous"
+                // "It parsed as an address" is a property of the parse, not of
+                // a key: a partial address has no single key to be non-null.
+            : (read && !read.reason) || siteAddress ? "unresolved"
             : read?.reason === "unknown-type" ? "unknown-type"
                 // Every link is an address, and this is not one. Distinct from
                 // a dead address, because the fix is different: a name has to

package/engine/wikilink-syntax.mjs

@@ -194,11 +194,11 @@ export const LINK_FINDING_REASONS = Object.freeze(
  *
  * **Both corrections, because the author cannot tell which applies.** An
  * address lands nowhere either because the shortcode is wrong or because the
- * package publishing it has no manifest vendored here, and the link itself
- * looks identical in the two cases.
+ * package publishing it is not a declared dependency — or is one whose index
+ * has not been fetched — and the link itself looks identical in every case.
  *
  * This used to be a **warning** in the checker and, in the site build, nothing
- * at all until every linkable package had vendored a manifest — on the
+ * at all until every linkable package's manifest was accounted for — on the
  * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
  * written yet. That reasoning was a property of the bare form, which is retired
  * (#180); the intent behind it now has a real spelling, a `draft`-tagged note
@@ -211,8 +211,8 @@ export const LINK_FINDING_REASONS = Object.freeze(
 export function unresolvedAddressMessage(target) {
     return (
         `address [[${target}]] resolves to no note — no package publishes ` +
-        `it. Fix the shortcode, or vendor the link manifest of the package ` +
-        `that does`
+        `it. Fix the shortcode, or declare the package that does as a ` +
+        `dependency and run \`content-build deps fetch\``
     );
 }
 
@@ -225,6 +225,13 @@ export function unresolvedAddressMessage(target) {
  * message names the claimants so the author can choose between them without
  * going looking.
  *
+ * **The correction is the canonical form**, all four segments (#59). Omission
+ * runs strictly left to right, so there is no `package-type-shortcode` to offer
+ * — naming a package means naming the system before the type. That used to be
+ * the correction here, back when a written target could state three segments at
+ * most; the grammar is positional now, and a three-segment target names a
+ * *system*, not a package.
+ *
  * @param {string} target - The address as authored.
  * @param {Iterable<string>} [packages] - The packages that publish it.
  * @returns {string} The message.
@@ -234,8 +241,8 @@ export function ambiguousAddressMessage(target, packages = []) {
     return (
         `address [[${target}]] is published by ` +
         (named.length ? `${named.join(" and ")}` : `more than one package`) +
-        `, so it names neither — write the package-qualified ` +
-        `[[package-type-shortcode|Text]]`
+        `, so it names neither — write the fully qualified ` +
+        `[[package-system-type-shortcode|Text]]`
     );
 }
 
@@ -265,7 +272,9 @@ export function linkFindingMessage({ reason, target, packages, anchor }) {
         case "not-an-address":
             return (
                 `"${target}" is not an address — the "|" says one was meant, ` +
-                `so write [[type-shortcode|Text]]`
+                `so write [[type-shortcode|Text]], or ` +
+                `[[package-system-type-shortcode|Text]] for a note in another ` +
+                `package`
             );
         case "unknown-type":
             return `address [[${target}]] names no known content type`;