@heroiclands/package-build 22.10.0 → 22.12.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 22.12.0
+
+### Minor Changes
+
+- **References:** An Address in note data that names no local or declared dependency target now reports an error; missing artwork keeps its fallback warning.
+
+## 22.11.0
+
+### Minor Changes
+
+- **Affiliations:** SoHL common skills link to their exact native Items; authors declare them in the SoHL block, and shared declarations receive an error.
+
 ## 22.10.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1249,6 +1249,12 @@ somewhere other than where they were made, or not at all:
   reference answered by a vendored manifest lands exactly as it would in a
   wikilink. `--no-references` turns this one off for a tree whose cross-package
   references it cannot see.
+- **Dead Address reference** — an Address-valued `data:` field naming no local
+  note, asset or entry in a declared dependency index. The finding names the
+  field and the complete Address it names. A short form means this package;
+  another package requires the full Address. `--no-references` also turns off
+  this target check. Art slots report unresolved art through their own fallback
+  warning.
 
 **A schema says what a note may _write_, not what the compiler emits.** Those
 are different, and the difference is the whole calibration of the check: a note
@@ -1444,6 +1450,27 @@ segment, and returns a complete tuple or a reason. This mode leaves package
 membership to resolution. The lint receives the builder's package separately
 from target lookup, including when reference resolution is disabled.
 
+An affiliation authors native SoHL skill references at
+`sohl.system.commonSkills`:
+
+```yaml
+sohl:
+  system:
+    commonSkills:
+      - herb
+      - sohl-sohl-skill-law
+```
+
+The first Address names this content package's SoHL skill; the second names a
+skill in the declared SoHL dependency. The content index retains their complete
+Addresses. Foundry compilation resolves each exact native skill Item in the
+local or declared dependency index and writes its published Item UUID to the
+affiliation's `system.commonSkills` array. The producer's module ID and pack
+come from that index. An unresolved target or a target without a native Item
+UUID is a located error. The shared `data:` container has no `commonSkills`
+property. Infoboxes use a skill's published documentation journal when it has
+one and show its known name as plain text otherwise.
+
 **There is deliberately no third rule** requiring every note to repeat its own
 `type-shortcode` address in `aliases:`. It would serve one reader — Obsidian, so
 `[[type-shortcode]]` resolves in the editor — and no build reads it: both

package/docs/api.md

@@ -1369,6 +1369,7 @@ Which of SoHL's facts a note's summary panel carries, and how they group. Read o
 | `SOHL_FIELD_PRESENTATION` | `const SOHL_FIELD_PRESENTATION` | —                     | looking up what one of SoHL's fields is called, or why it carries no row            |
 | `PROTECTION_FIELDS`       | `const PROTECTION_FIELDS`       | —                     | reading the declarations of the aspects armour is rated against, in the order shown |
 | `UNSTATED`                | `const UNSTATED`                | —                     | naming what a strike mode shows where a value was not stated                        |
+| `affiliationSections`     | `affiliationSections(fm, ctx)`  | `object[]`            | building an affiliation's box with skill documentation links                        |
 | `armorSections`           | `armorSections(fm, ctx)`        | `object[]`            | building armour's box, protection included                                          |
 | `beingSections`           | `beingSections(fm, ctx)`        | `object[]`            | building a being's attributes, skills, mystical abilities and equipment             |
 | `decodeItem`              | `decodeItem(entry)`             | `object \| undefined` | reading what one `sohl.items` entry names, whichever form it was written in         |

package/docs/commands.md

@@ -1445,7 +1445,7 @@ declaration that compiles it. Otherwise 0.
 $ content-build content-format fields --fields sohl --coverage
 […] 13 type(s) compared against sohl's declarations (56 field pair(s)).
 […] 12 type(s) the format declares are out of reach — no `itemBuilders` entry covers them: being, homepage, vehicle, armorlocation, lore, map, place, scenario, doc, macro, bundle, folder.
-[…] affiliation: format only [commonSkills, demonym, economy, epithet, governance, lore, population, symbol, templatePriority], declaration only [level, office, society, subType, title]
+[…] affiliation: format only [demonym, economy, epithet, governance, lore, population, symbol, templatePriority], declaration only [commonSkills, level, office, society, subType, title]
 ```
 
 **SEE ALSO**

package/docs/content-format.md

@@ -495,6 +495,12 @@ reduction happens at build time, and two things are errors naming the note: an
 Address whose type the field does not accept, and two Addresses that reduce to one
 shortcode, which the field cannot hold both of.
 
+**A SoHL skill Address becomes a native Item UUID.** An affiliation's
+`sohl.system.commonSkills` names skills in its own package or a declared
+dependency. Its `system.commonSkills` contains the exact published Item UUIDs,
+including each foreign module's own pack name. Native skill lookup uses those
+UUIDs; the journal, website and book use documentation links for presentation.
+
 **A `Code` suffix marks a different thing.** `system.assocSkillCode`,
 `system.assocAffiliationCode` and `system.parentSkillCode` hold a `Shortcode` at
 both ends — each is authored as one, under `<system>.system`, and emitted verbatim
@@ -1309,6 +1315,12 @@ Address-keyed relation maps hold typed targets and standing values. Only generat
 output serializes these properties to Address strings. Runtime Shortcodes,
 Foundry UUIDs, file paths and URLs keep their own representations.
 
+An Address-valued `data:` field must name a target in this package or a declared
+dependency index. `content-build lint` reports a missing target as an error at
+the value or map key that names it. A stub counts as a target for data even
+though it publishes no page. Art slots use their own missing-art warning and
+document fallback.
+
 #### An omitted segment defaults from where the link is written
 
 It is **not** a wildcard and resolution is not a search. Every short form expands
@@ -2844,7 +2856,6 @@ rank names the standing, and the standing says.
 | `governance.summary` | `string`                 | summary of the governance situation                                                            |
 | `governance.ranks`   | `Rank[]`                 | The ranks available to members of the affiliation                                              |
 | `governance.offices` | `Map<name, description>` | Official offices in the affiliation                                                            |
-| `commonSkills`       | `Address[]`              | Common skills among members (languages, etc.)                                                  |
 | `seat`               | `Address`                | Where the affiliation's authority sits                                                         |
 | `domains`            | `Address[]`              | Places over which this affiliation holds sway                                                  |
 | `population`         | `number`                 | Number of people in the affiliation (precision 2 significant digits).                          |
@@ -2926,6 +2937,27 @@ If `sohl` is present, this becomes an `affiliation` item.
 | `data.parents`   | `system.parents`   | NA    |
 | `data.relations` | `system.relations` | NA    |
 
+An affiliation writes SoHL common skills under `sohl.system.commonSkills` as a
+list of skill Addresses. An abbreviated value names a skill in the authoring
+package; a skill in the SoHL system package uses its complete Address:
+
+```yaml
+sohl:
+  system:
+    commonSkills:
+      - herb
+      - sohl-sohl-skill-law
+```
+
+The compiled SoHL Item stores the exact published Item UUIDs in
+`system.commonSkills`. An empty or absent list emits `[]`. A foreign target must
+come from a declared `relationships.systems` or `relationships.requires` content
+index. Each UUID uses the module and pack named by that target's published index;
+a missing skill Item or Item UUID is an error at the authored Address. The
+content index retains complete Addresses. Journal, web and book infoboxes link
+to a skill's published documentation journal when one exists and otherwise show
+its name as plain text.
+
 `governance` reaches no system field. Ranks and offices are the note's and the
 web page's — SoHL's affiliation item has nowhere to put them, and inventing a
 mapping for a field no schema declares is the drift these tables exist to catch.
@@ -2989,9 +3021,7 @@ If `sohl` is present, this becomes an `affliction` item.
 | `subType`                          | `system.subType`                     | NA    |
 | `data.transmission`                | `system.transmission`                | NA    |
 | `data.outcome`                     | `system.outcome`                     | NA    |
-| `data.healingRate`                 | `system.healingRateBase`             | NA    |
 | `data.contagionIndex`              | `system.contagionIndexBase`          | NA    |
-| `data.outcomeTraumas`              | `system.outcomeTraumas`              | NA    |
 | `data.onsetDurationFormula`        | `system.onsetDurationFormula`        | NA    |
 | `data.onsetDurationBase`           | `system.onsetDurationBase`           | NA    |
 | `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
@@ -3029,6 +3059,10 @@ that writes one fails the build. They are world times, and `0` is a valid one,
 so there is no blank a note could write either; leave them out and the data
 model's `null` stands.
 
+`data.healingRate` and `data.outcomeTraumas` are page data. SoHL reads an
+affliction’s base healing rate from `sohl.healingRateBase`. Its item declaration
+does not read `data.outcomeTraumas`.
+
 ### type: armorgear
 
 Note: `data.quantity` may not be specified. Quantity is always 1.
@@ -3103,7 +3137,9 @@ if a `sohl` property is present, a SoHL item of type "concoctiongear" will be cr
 | `data.value`      | `system.valueBase`      | NA    |
 | `data.quality`    | `system.qualityBase`    | NA    |
 | `data.durability` | `system.durabilityBase` | NA    |
-| `data.quantity`   | `system.quantity`       | NA    |
+
+`data.quantity` is page data for a concoction. SoHL sets `system.quantity` to
+`1` for each compendium item.
 
 ### type: containergear
 
@@ -3116,19 +3152,21 @@ Note: `data.quantity` may not be specified; quantity is always set to 1.
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `capacity`         | `number` | Container capacity (in lbs)                |
+| `capacity`         | `number` | HM3 container capacity (in lbs)            |
 
 if a `sohl` property is present, a SoHL item of type "containergear" will be created.
 
 if a `hm3` property is present, an HM3 item of type "containergear" will be created.
 
-| shared source     | → sohl                   | → hm3                 |
-| ----------------- | ------------------------ | --------------------- |
-| `data.weight`     | `system.weightBase`      | `system.weight`       |
-| `data.value`      | `system.valueBase`       | `system.value`        |
-| `data.quality`    | `system.qualityBase`     | NA                    |
-| `data.durability` | `system.durabilityBase`  | NA                    |
-| `data.capacity`   | `system.maxCapacityBase` | `system.capacity.max` |
+| shared source     | → sohl                  | → hm3                 |
+| ----------------- | ----------------------- | --------------------- |
+| `data.weight`     | `system.weightBase`     | `system.weight`       |
+| `data.value`      | `system.valueBase`      | `system.value`        |
+| `data.quality`    | `system.qualityBase`    | NA                    |
+| `data.durability` | `system.durabilityBase` | NA                    |
+| `data.capacity`   | NA                      | `system.capacity.max` |
+
+SoHL reads a container’s capacity in pounds from `sohl.maxCapacity`.
 
 ### type: miscgear
 
@@ -3139,7 +3177,7 @@ if a `hm3` property is present, an HM3 item of type "containergear" will be crea
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "miscgear" will be created.
 
@@ -3151,7 +3189,9 @@ if a `hm3` property is present, an HM3 item of type "miscgear" will be created.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: mystery
 
@@ -3187,10 +3227,12 @@ if a `sohl` property is present, a SoHL item of type "mystery" will be created.
 | --------------------- | ----------------------- | ----- |
 | `subType`             | `system.subType`        | NA    |
 | `data.skillAptitudes` | `system.skillAptitudes` | NA    |
-| `data.level`          | `system.levelBase`      | NA    |
 | `data.charges.value`  | `system.charges.value`  | NA    |
 | `data.charges.max`    | `system.charges.max`    | NA    |
 
+`data.level` is page data for a mystery. SoHL reads the item’s level from
+`sohl.levelBase`.
+
 ### type: mysticalability
 
 **subType**:
@@ -3224,13 +3266,15 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 `sohl.system` as shortcodes and have no shared source; `data.assocSkill` and
 `data.assocAffiliation` name the same two notes as Addresses, for the page.
 
-| shared source        | → sohl                    | → hm3         |
-| -------------------- | ------------------------- | ------------- |
-| `subType`            | `system.subType`          | **see above** |
-| `data.masteryLevel`  | `system.masteryLevelBase` | NA            |
-| `data.level`         | `system.levelBase`        | NA            |
-| `data.charges.value` | `system.charges.value`    | NA            |
-| `data.charges.max`   | `system.charges.max`      | NA            |
+| shared source        | → sohl                 | → hm3         |
+| -------------------- | ---------------------- | ------------- |
+| `subType`            | `system.subType`       | **see above** |
+| `data.charges.value` | `system.charges.value` | NA            |
+| `data.charges.max`   | `system.charges.max`   | NA            |
+
+`data.masteryLevel` and `data.level` are page data for an ability. SoHL reads
+the item’s base mastery and level from `sohl.masteryLevelBase` and
+`sohl.levelBase`.
 
 ### type: projectilegear
 
@@ -3250,7 +3294,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "projectilegear" will be created.
 
@@ -3267,7 +3311,9 @@ HM3 side while remaining distinct on the SoHL side.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: skill
 
@@ -3287,7 +3333,7 @@ HM3 side while remaining distinct on the SoHL side.
 | `data` property    | Values    | Description                                |
 | ------------------ | --------- | ------------------------------------------ |
 | `templatePriority` | `number`  | Template priority, _null_ = not a template |
-| `masteryLevel`     | `number`  | Mastery Level                              |
+| `masteryLevel`     | `number`  | HM3 mastery level                          |
 | `parentSkill`      | `Address` | Parent skill this skill specializes        |
 
 if a `sohl` property is present, a SoHL item of type "skill" will be created.
@@ -3300,10 +3346,12 @@ Note: `hm3.system.type` (skill types) use the values "Craft", "Physical", "Commu
 skill this one specializes, and has no shared source; `data.parentSkill` names that
 skill as an Address, for the page.
 
-| shared source       | → sohl                    | → hm3                 |
-| ------------------- | ------------------------- | --------------------- |
-| `subType`           | `system.subType`          | See notes above       |
-| `data.masteryLevel` | `system.masteryLevelBase` | `system.masteryLevel` |
+| shared source       | → sohl           | → hm3                 |
+| ------------------- | ---------------- | --------------------- |
+| `subType`           | `system.subType` | See notes above       |
+| `data.masteryLevel` | NA               | `system.masteryLevel` |
+
+SoHL reads a skill’s base mastery from `sohl.masteryLevelBase`.
 
 ### type: trauma
 
@@ -3903,7 +3951,7 @@ because they were true of something else, and each removal has a home to go to.
 
 **`languages` is a fact about a polity.** A place's languages change when its
 ruler changes, which is what makes them the ruler's property — and
-`affiliation.commonSkills` already holds them. The authored corpus agrees: of 206
+`sohl.system.commonSkills` holds them. The authored corpus agrees: of 206
 places carrying `languages`, 190 were settlements and 16 were regions, and not one
 was a site, a structure or a feature. A ruin has no language.
 

package/engine/address-fields.mjs

@@ -12,16 +12,18 @@
  */
 
 /**
- * **An authored Address, an emitted Shortcode.**
+ * **An authored Address, an emitted native reference.**
  *
  * A declared field may hold an Address where the document it compiles into
- * holds a **Shortcode**. An affiliation's `seat` is the worked case: the note
+ * holds a **Shortcode** or a published Item UUID. An affiliation's `seat` is a Shortcode case: the note
  * names a place at whatever length says what it means — `tashal`,
  * `place-tashal`, `none-place-tashal`, `kethira-none-place-tashal` — and the
  * compiled Item carries `tashal`, which is what the runtime resolves among the
  * items one actor holds, where packages do not exist.
  *
- * So the builder resolves the one into the other, and this module is that step.
+ * The `emit: "uuid"` declaration resolves an exact native target from the
+ * local or declared dependency index. The target supplies its published UUID.
+ * This module performs both conversions at the Foundry output boundary.
  * Storing the written form instead would store a value plus a context that does
  * not travel with it: a four-segment string reaches a runtime that looks up one
  * segment and returns nothing, silently.
@@ -70,10 +72,8 @@
  *
  * ## What this module does not do
  *
- * It resolves nothing against the index: the shortcode is a segment of the
- * Address, so reducing one needs the grammar and the position's declarations
- * and nothing else. Whether the target exists is a separate question, asked
- * where the index is.
+ * Shortcode output needs only the Address grammar. UUID output requires the
+ * exact target in the published index and accepts only Item UUIDs.
  *
  * A failure is a **finding**, never a diagnostic: the caller owns the file and
  * the severity, and locates the finding at the value inside the note.
@@ -107,6 +107,7 @@ export const ADDRESS_FIELD_SHAPES = Object.freeze(["value", "items", "keys"]);
  * @property {readonly string[]} accepts - Every type the position accepts.
  * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
  *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
  */
 
 /**
@@ -171,7 +172,7 @@ function reduceOne(value, field, vocabulary, findings) {
     // Two keys, or two list entries, reducing to one emitted shortcode: the
     // Address each of them named, by the shortcode all of them land on.
     const seen = new Map();
-    const read = (written) => readOne(written, field, defaults, seen, findings, shape);
+    const read = (written) => readOne(written, field, defaults, seen, findings, shape, vocabulary);
 
     if (shape === "keys") {
         if (!isMapping(value)) return undefined;
@@ -212,8 +213,15 @@ function reduceOne(value, field, vocabulary, findings) {
  * @returns {string|undefined} The shortcode, or `undefined` when nothing is
  *   emitted for this value.
  */
-function readOne(written, field, defaults, seen, findings, shape) {
+function readOne(written, field, defaults, seen, findings, shape, vocabulary) {
     const key = findingKey(field);
+    // An embedded Item may inherit an already compiled reference from its model.
+    if (
+        field.address.emit === "uuid" &&
+        typeof written === "string" &&
+        /^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(written)
+    )
+        return written;
     const value =
         isAddressTuple(written) ? renderAddress(written)
         : typeof written === "string" ? written
@@ -231,6 +239,20 @@ function readOne(written, field, defaults, seen, findings, shape) {
     }
 
     const address = renderAddress(tuple);
+    if (field.address.emit === "uuid") {
+        const target =
+            tuple.package === vocabulary.package ?
+                vocabulary.referenceTargets?.get(address)
+            :   vocabulary.foreignReferences?.get(address);
+        const uuid = target?.uuid;
+        if (!uuid || !/^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(uuid)) {
+            report(
+                `\`${key}\` names \`${address}\`, but its exact native Item has no published Item UUID`,
+            );
+            return undefined;
+        }
+        return uuid;
+    }
     const code = tuple.shortcode;
     const first = seen.get(code);
     if (first && first.address !== address) {

package/engine/base-compiler.mjs

@@ -717,6 +717,8 @@ export class BasePackCompiler {
             types: this.linkIndex?.types,
             packages: this.linkIndex?.packages,
             noIndexPackages: this.linkIndex?.noIndexPackages,
+            referenceTargets: this.linkIndex?.referenceTargets,
+            foreignReferences: this.linkIndex?.foreignReferences,
         });
         for (const finding of findings) {
             this.errorCount++;

package/engine/field-spec.mjs

@@ -148,8 +148,9 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   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 and the emitted one is its Shortcode.** The
+ * @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

package/engine/frontmatter-lint.mjs

@@ -68,7 +68,7 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
-import { parseAddress, acceptsType } from "./address.mjs";
+import { parseAddress, acceptsType, renderAddress } from "./address.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
 // The one place the "every pack not named" key is spelled. Imported rather
@@ -421,7 +421,7 @@ function dataBlock(fm) {
  *   was loaded to recognise it would be worse than not checking.
  * @returns {object[]} Findings.
  */
-function checkDataContainer(note, { type, fields, packs, addressContext }) {
+function checkDataContainer(note, { type, fields, packs, addressContext, index }) {
     const findings = [];
     const { present, entries, malformed } = dataBlock(note.fm ?? {});
     if (!present) return findings;
@@ -476,10 +476,12 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
             ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
             severity: "error",
             message:
-                `"${key}" is not a \`data:\` property declared by ${type}; ` +
-                `the container is closed, so unlike a top-level key it is ` +
-                `not passed through to the page` +
-                (guess ? `. Did you mean "${guess}"?` : ""),
+                type === "affiliation" && key === "commonSkills" ?
+                    "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
+                :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
+                    `the container is closed, so unlike a top-level key it is ` +
+                    `not passed through to the page` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
 
@@ -502,7 +504,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
             });
             continue;
         }
-        findings.push(...checkDataReferences(note, field, value, segments, addressContext));
+        findings.push(...checkDataReferences(note, field, value, segments, addressContext, index));
         // A `scalar-or-map` written in its map form is checked entry by entry,
         // because that is the correction an author has to make: one key's
         // value, not the whole map. Quoting the map back would name every
@@ -519,15 +521,16 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
 }
 
 /**
- * Validate typed entries without resolving their targets.
+ * Validate typed entries and resolve declared non-art Address targets.
  * @param {object} note - The authored note.
  * @param {object} field - Its data field declaration.
  * @param {unknown} value - The field value.
  * @param {string[]} segments - The field's path under `data`.
  * @param {object} context - The builder's Address context.
+ * @param {object} [index] - The local and declared dependency Address index.
  * @returns {object[]} Located findings.
  */
-function checkDataReferences(note, field, value, segments, context) {
+function checkDataReferences(note, field, value, segments, context, index) {
     const checks = [];
     if (field.kind === "address") checks.push({ value, path: [], kind: "address" });
     if (field.entryKind) {
@@ -571,10 +574,16 @@ function checkDataReferences(note, field, value, segments, context) {
         let reason;
         if (!matchesKind(check.value, check.kind, defaults))
             reason = `should be ${check.kind === "address" ? "an Address" : "a Shortcode"}`;
-        else if (check.kind === "address" && accepted) {
+        else if (check.kind === "address") {
             const tuple = parseAddress(check.value, defaults, { declared: true });
-            if (!acceptsType(tuple, accepted))
+            if (accepted && !acceptsType(tuple, accepted))
                 reason = `accepts ${accepted.join(" or ")}, not ${tuple.type}`;
+            else if (
+                index?.addressHit &&
+                !ART_SLOTS.some((slot) => slot.key === field.name) &&
+                !index.addressHit(renderAddress(tuple))
+            )
+                reason = `names ${renderAddress(tuple)}, which does not resolve in this package or its declared dependencies`;
         }
         if (!reason) continue;
         const path = ["data", ...segments, ...check.path];
@@ -1517,6 +1526,7 @@ export function lintNote(
                 fields,
                 packs,
                 addressContext: referenceContext,
+                index,
             }),
         );
         findings.push(...checkSubType(note, { type, entry }));

package/engine/holdings.mjs

@@ -124,15 +124,12 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
  * system, only the shortcode {@link module:engine/address} would resolve it
  * to anyway.
  *
- * **The match this shortcode feeds is deliberately package-blind.** `places`
- * and `affiliations` merge this package's own notes with every fetched
- * dependency's into one shortcode space, first declaration wins — the way a
- * dependency's generic geography attaches to whatever a consumer calls the
- * same shortcode, which is the point of _A dependency's places and
- * affiliations take part_ above. Comparing the full Address instead would
- * ask an entry's package to agree with the citing note's, and a fetched
- * entry's own `parents` or `domains` is written in *its* package while the
- * blend it takes part in is *this* one's — see
+ * **The holdings graph has package-blind Shortcode identity.** `places` and
+ * `affiliations` merge local and fetched notes into one shortcode space; the
+ * first declaration wins. A fetched place attaches to a local parent with
+ * the same shortcode, and a fetched affiliation can name both local and
+ * fetched domains. The authored entries remain Addresses; this graph uses
+ * their shortcode projection for containment and tenure. See
  * `tests/site-holdings.test.ts`'s `empire.domains: ["mill", "abroad"]`, where
  * `mill` is local and `abroad` is the dependency's own, both bare, both
  * correct only because neither package is asked.
@@ -321,6 +318,7 @@ export function holdingsPages(nodes) {
         // Read through the one reader, so a caller handing in what a note
         // wrote — an address, a wikilink, a repeat — is read as `holdingsNode`
         // reads it.
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(shortcode, {
             ...node,
             shortcode,

package/engine/map-places.mjs

@@ -108,15 +108,14 @@ const PLACE_TYPES = Object.freeze(new Set(["place"]));
  * since this position asks neither its package nor its system, only the
  * shortcode {@link module:engine/address} would resolve it to anyway.
  *
- * **The match this shortcode feeds is deliberately package-blind.**
- * `world.places` merges this package's own places with every fetched
- * dependency's into one shortcode space, the way a dependency's place
- * attaches to the local containment tree it is drawn beside — see
+ * **The map graph has package-blind Shortcode identity.** `world.places`
+ * merges local and fetched places by shortcode, with local declarations
+ * taking precedence. A fetched place attaches to the local containment tree
+ * by its parent's shortcode. The authored parent remains an Address; the map
+ * uses its shortcode projection for containment, layout, and DOT nodes. See
  * `tests/map.test.ts`'s _loads a dependency's places beside the package's
  * own_, where a fetched place's bare `parents: ["world"]` reaches this
- * package's own root. Comparing the full Address instead would ask the
- * dependency's own package to agree with this one's, which the feature is
- * built to cross.
+ * package's own root.
  *
  * @param {unknown} parent - One `parents` entry.
  * @returns {string} Its shortcode, or `""` for an entry that names nothing.
@@ -193,6 +192,7 @@ export function placesFromRecords(records, { contentBase, base }) {
             // lint's finding.
             if (places.has(shortcode)) continue;
             const data = record.data && typeof record.data === "object" ? record.data : {};
+            // Shortcode identity: local places claim the map node first.
             places.set(shortcode, {
                 shortcode,
                 name,
@@ -243,6 +243,7 @@ function addForeignPlaces(world, foreignIndex) {
         if (entry?.type !== "place") continue;
         const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
         if (!shortcode || world.places.has(shortcode)) continue;
+        // Shortcode identity: fetched places fill only unclaimed map nodes.
         world.places.set(shortcode, {
             shortcode,
             name: String(entry.name ?? shortcode),

package/engine/note-addresses.mjs

@@ -5,7 +5,7 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-import { systemBlocksFor } from "./system-vocabulary.mjs";
+import { declaredSystems, systemBlocksFor } from "./system-vocabulary.mjs";
 import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 import {
     isAddressTuple,
@@ -260,10 +260,25 @@ export function decodeNoteAddresses(fm, context) {
  * @returns {object} Builder defaults and system declarations.
  */
 export function noteAddressContext(config) {
+    const systemBlocks = { ...systemBlocksFor(config) };
+    // A module with one declared system uses its flat Item registry for that
+    // system's Address positions, including fields stored in its content index.
+    const systems = new Set([
+        ...declaredSystems(config),
+        ...(config.relationships?.systems ?? []).map((relationship) => relationship.id),
+    ]);
+    if (
+        systems.size === 1 &&
+        config.itemFields &&
+        Object.keys(config.itemFieldsBySystem ?? {}).length === 0
+    ) {
+        const [system] = systems;
+        systemBlocks[system] = { ...systemBlocks[system], fields: config.itemFields };
+    }
     return {
         package: config.contentPackage,
         system: "none",
-        systemBlocks: systemBlocksFor(config),
+        systemBlocks,
     };
 }
 

package/engine/note-vocabulary.mjs

@@ -761,13 +761,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...ANY,
                 describe: "The named offices it appoints, each with what the office does.",
             },
-            {
-                name: "commonSkills",
-                ...LINKS,
-                ref: "skill",
-                accepts: ["skill"],
-                describe: "Skills common among members — languages first among them.",
-            },
             {
                 name: "seat",
                 ...LINK,

package/engine/populations.mjs

@@ -242,8 +242,10 @@ export function foreignNode(canonical, entry) {
 /**
  * The corpus a link index describes.
  *
- * A shortcode is declared once per type and the first declaration wins, so a
- * local note shadows a dependency's the way the link resolver answers.
+ * Population containment and tenure use the same package-blind Shortcode
+ * identity as holdings and maps. Each type has one node per shortcode, with
+ * local notes taking precedence over fetched entries. A fetched place can
+ * attach to local geography, while its authored `parents` remains an Address.
  *
  * @param {object} index - The link index.
  * @returns {Corpus} The corpus.
@@ -263,6 +265,7 @@ function corpusOf(index) {
         if (!node) return;
         const by = node.type === "place" ? places : affiliations;
         if (by.has(node.shortcode)) return;
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(node.shortcode, node);
         // Not a canonical Address: package-blind by design, so a local place
         // shadows a foreign one of the same type and shortcode. `/` keeps that

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.10.0",
+    "version": "22.12.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/infobox.mjs

@@ -543,6 +543,36 @@ function genericSections(fm, type, ctx) {
     return systemRowsSection(fm, NOTE_SCHEMAS[type], ctx);
 }
 
+/** An affiliation presents skill documentation while retaining native Item identity. */
+export function affiliationSections(fm, ctx) {
+    const field = NOTE_SCHEMAS.affiliation.find((entry) => entry.to === "commonSkills");
+    const sections = systemRowsSection(
+        fm,
+        NOTE_SCHEMAS.affiliation.filter((entry) => entry !== field),
+        ctx,
+    );
+    const { value } = ctx.resolveField(field, fm, { block: ctx.block });
+    if (!Array.isArray(value) || value.length === 0) return sections;
+    const entries = value.map((skill) => {
+        const native = ctx.resolve?.(skill, { type: "skill", system: "sohl" });
+        const docAddress =
+            isAddressTuple(skill) ? completeAddress({ ...skill, system: "none" }) : undefined;
+        const doc = docAddress ? ctx.resolve?.(docAddress, { type: docAddress.type }) : undefined;
+        return {
+            text: doc?.name || native?.name || humanizeValue(skill),
+            ...(doc?.url ? { url: doc.url } : {}),
+            ...(doc?.uuid ? { uuid: doc.uuid } : {}),
+            ...(docAddress && (doc?.url || doc?.uuid) ? { address: docAddress } : {}),
+        };
+    });
+    sections.push({
+        id: "commonskills",
+        layout: "rows",
+        rows: [{ label: "Common skills", kind: "links", value: entries }],
+    });
+    return sections;
+}
+
 /**
  * SoHL's infobox declaration.
  *
@@ -555,6 +585,7 @@ export const SOHL_INFOBOX = defineInfobox({
     presentation: SOHL_FIELD_PRESENTATION,
     sections: {
         being: beingSections,
+        affiliation: affiliationSections,
         armorgear: armorSections,
         weapongear: weaponSections,
         projectilegear: projectileSections,

package/sohl/item-fields.mjs

@@ -178,6 +178,14 @@ const AFFILIATION_ITEMS = Object.freeze({
 /** A map keyed by affiliation: this one's standing toward each. */
 const AFFILIATION_KEYS = Object.freeze({ ...AFFILIATION_ITEMS, holds: "keys" });
 
+/** Native skill references retain the published Item UUID. */
+const SKILL_UUID_ITEMS = Object.freeze({
+    type: "skill",
+    accepts: Object.freeze(["skill"]),
+    holds: "items",
+    emit: "uuid",
+});
+
 /** Standings toward other affiliations, validated against the closed list. */
 const RELATION = Object.freeze({
     shape: "map of affiliation address → standing",
@@ -385,6 +393,15 @@ export const ITEM_FIELDS = Object.freeze({
             default: 0,
             describe: "Standing within the society.",
         },
+        {
+            name: "commonSkills",
+            to: "commonSkills",
+            ...ADDRESS_LIST,
+            address: SKILL_UUID_ITEMS,
+            default: [],
+            topLevelMeans: "Common skills belong to the SoHL affiliation item.",
+            describe: "Native SoHL skill Items common among members, by address.",
+        },
         {
             // Plural because the field holds a map of many standings, one per
             // affiliation — the singular reads as a misnomer.

package/types/engine/address-fields.d.mts

@@ -6,6 +6,7 @@
  * @property {readonly string[]} accepts - Every type the position accepts.
  * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
  *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
  */
 /**
  * What a reduction could not do, for a caller to report.
@@ -69,6 +70,10 @@ export type AddressPosition = {
      * Defaults to `value`.
      */
     holds?: "keys" | "value" | "items" | undefined;
+    /**
+     * - Resolve each exact target to its published Item UUID.
+     */
+    emit?: "uuid" | undefined;
 };
 /**
  * What a reduction could not do, for a caller to report.

package/types/engine/field-spec.d.mts

@@ -277,8 +277,9 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   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 and the emitted one is its Shortcode.** The
+ * @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
@@ -553,8 +554,9 @@ export type FieldSpec = {
      */
     code?: string | undefined;
     /**
-     * - **The
-     * authored value is an Address and the emitted one is its Shortcode.** The
+     * - 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

package/types/sohl/infobox.d.mts

@@ -82,6 +82,8 @@ export function projectileSections(fm: object, ctx: object): object[];
  * @returns {[string, object][]} Mode name → the mode.
  */
 export function strikeModes(declared: unknown): [string, object][];
+/** An affiliation presents skill documentation while retaining native Item identity. */
+export function affiliationSections(fm: any, ctx: any): object[];
 /** What this system's box is called. @type {string} */
 export const SOHL_INFOBOX_TITLE: string;
 /**