@heroiclands/package-build 21.1.0 → 22.0.0

package/engine/map-notes.mjs

@@ -59,7 +59,6 @@ import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.m
 // A map's background art is `img`, as every other note type's art is. `image`,
 // the spelling a map alone once used, is retired and gone.
 import { sohlField } from "./frontmatter.mjs";
-import { resolveImg } from "./helpers.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -880,7 +879,8 @@ function buildRegion(key, spec, geom, ctx) {
  *   `packageId`, `journalEntryId`, `journalPack` (the pack the note's derived
  *   JournalEntry landed in), `pageIds` (heading key → page id),
  *   `resolveRegionRef` / `resolveBehaviorRef` / `resolveEffectRef` (address →
- *   UUID), `knownActions`, `warnings`, and optionally `folder` and `stats`.
+ *   UUID), `art` (an art address → the path each surface serves),
+ *   `knownActions`, `warnings`, and optionally `folder` and `stats`.
  * @returns {object} The Scene document, keyed for the pack.
  * @throws {Error} On any authoring mistake Foundry would accept silently.
  */
@@ -905,11 +905,11 @@ export function buildScene(fm, ctx) {
                 "match the art",
         );
     }
-    // Read from the note rather than from its `sohl:` block: art is not
-    // system-specific, so `img` is authored at the top level like every other
-    // type's, and `sohlField` honours the block for anything already there.
-    const img = resolveImg(sohlField(fm, "img"));
-    if (!img) throw new Error("a map note needs an `img`");
+    // A Scene has no `img`, so a map's background is its own slot, authored
+    // under `data:` with the other art. It is an `image` address like every
+    // other art reference, and the record it resolves to carries the path.
+    const img = ctx.art(fm.data?.bgImage, "bgImage", "image");
+    if (!img) throw new Error("a map note needs a `bgImage`");
 
     const warn = (message) => {
         if (ctx.warnings) ctx.warnings.push(message);
@@ -934,7 +934,7 @@ export function buildScene(fm, ctx) {
         tokenVision: profile.tokenVision,
         fog: { mode: profile.fog.mode },
         initialLevel: DEFAULT_LEVEL_ID,
-        levels: [buildLevel(sohl, sceneId, img)],
+        levels: [buildLevel(sohl, sceneId, img, ctx.art)],
         drawings: [],
         tokens: [],
         lights: buildLights(sohl, geom, inner),
@@ -980,13 +980,16 @@ export function buildScene(fm, ctx) {
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
- * @param {string} [img] - The background art, already resolved from the note.
- *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to the block's own `img`, so a direct two-argument call
- *   still works.
+ * @param {string} img - The background art, already resolved from the note's
+ *   `bgImage` address by {@link buildScene}. Passed rather than resolved here,
+ *   because an address is answered by the compile's index and this function
+ *   takes none.
+ * @param {(value: unknown, key: string, type: string) => string|null} [art] -
+ *   The art resolver, for the foreground overlay. Omitted, a note naming one
+ *   gets no overlay rather than a path nothing serves.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId, img = resolveImg(sohlField({ sohl }, "img"))) {
+export function buildLevel(sohl, sceneId, img, art = () => null) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",
@@ -995,9 +998,9 @@ export function buildLevel(sohl, sceneId, img = resolveImg(sohlField({ sohl }, "
             color: sohl.backgroundColor ?? "#999999",
             src: img,
         },
-        // The overlay is a pathname like the background, and resolves by the
-        // same rule — a scene draws the two from one authored statement each.
-        foreground: { src: resolveImg(sohl.overlay ?? null) },
+        // The overlay is an `image` address like the background, and resolves
+        // by the same rule — a scene draws the two from one statement each.
+        foreground: { src: art(sohl.overlay ?? null, "overlay", "image") },
         sort: 0,
         _key: `!scenes.levels!${sceneId}.${DEFAULT_LEVEL_ID}`,
     };
@@ -1120,9 +1123,11 @@ export function buildTiles(sohl, geom, ctx) {
             rotation: spec.rotation ?? 0,
             alpha: spec.alpha ?? 1,
             sort: 0,
-            // A tile's texture is a pathname, resolved by the same rule the
-            // scene's own background is.
-            texture: { src: resolveImg(spec.image) },
+            // A tile's texture is an address, resolved by the same rule the
+            // scene's own background is. Its key is named for the type it
+            // reaches, so a tile placing a glyph rather than artwork qualifies
+            // — `sohl-none-icon-chest` — and the default needs no memorising.
+            texture: { src: ctx.art(spec.image, "image", "image") },
             _key: `!scenes.tiles!${ctx.sceneId}.${id}`,
         };
     });
@@ -1143,7 +1148,7 @@ export function buildSounds(sohl, geom, ctx) {
     return Object.entries(sohl.sounds ?? {}).map(([key, spec]) => {
         const label = `sounds.${key}`;
         const [x, y] = requirePosition(spec.position, { ...geom, label });
-        if (!spec.path) throw new Error(`${label}: an ambient sound needs a path`);
+        if (!spec.audio) throw new Error(`${label}: an ambient sound needs an \`audio\` address`);
         const id = spec._id || makeId("scene-sound", `${ctx.sceneId}:${key}`);
         return {
             _id: id,
@@ -1151,8 +1156,10 @@ export function buildSounds(sohl, geom, ctx) {
             x,
             y,
             radius: spec.radius ?? 0,
-            // An ambient sound is a file a package ships, like the pictures.
-            path: resolveImg(spec.path),
+            // An ambient sound is a file a package ships, like the pictures, so
+            // it is an address too. The emitted field stays Foundry's own
+            // `path`, which is what a Scene's AmbientSound calls it.
+            path: ctx.art(spec.audio, "audio", "audio"),
             repeat: spec.repeat ?? true,
             volume: spec.volume ?? 0.5,
             walls: spec.walls ?? true,

package/engine/metadata-index.mjs

@@ -43,6 +43,12 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { formatDiagnostic, positionOfLiteral } from "./diagnostics.mjs";
+// The artifact's name, declared with the package registry so the toolchain's
+// own index can name its file without importing this module back.
+import { metadataFileName, PACKAGEBUILD_PACKAGE } from "./packages.mjs";
+import { packageBuildRecords } from "./packagebuild-index.mjs";
+
+export { metadataFileName };
 import { PACKAGE_BASE, readCanonicalKey, resolvePackageUrl } from "./content-address.mjs";
 
 /**
@@ -67,26 +73,6 @@ const STAMP = ".complete";
  */
 export const METADATA_RELATIONSHIP_KINDS = Object.freeze(["systems", "requires"]);
 
-/**
- * What a package's content index is called, wherever it is written or fetched.
- *
- * **The local index and the published artifact are one file.** A package emits
- * this, ships it as a release asset, and advertises it as `flags.metadataUrl`;
- * a consumer fetches that same file into its cache and reads it. Naming it in
- * one function is what keeps the emitter, the release and the fetcher from
- * drifting into three spellings of one artifact.
- *
- * The `-metadata` suffix earns its place: a bare `<package>.jsonl` says nothing
- * about what it holds, and these files land in a cache directory beside other
- * packages' artifacts where the name is all a reader has.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The file name, e.g. `sohl-metadata.jsonl`.
- */
-export function metadataFileName(pkg) {
-    return `${pkg}-metadata.jsonl`;
-}
-
 /**
  * Every dependency whose published index this build resolves addresses through.
  *
@@ -312,22 +298,14 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
     const packages = new Set();
     const stale = [];
 
-    for (const file of cachedMetadataFiles(config)) {
-        let records;
-        try {
-            records = fs
-                .readFileSync(file, "utf8")
-                .split("\n")
-                .filter((line) => line.trim())
-                .map((line) => JSON.parse(line));
-        } catch (err) {
-            stale.push({ package: packageOfCache(file), reason: `unreadable: ${err.message}` });
-            continue;
-        }
-
-        const pkg = records[0]?.package ?? packageOfCache(file);
-        if (local.has(pkg)) continue;
-
+    /**
+     * Fold one package's records into the index.
+     *
+     * @param {string} pkg - The package that published them.
+     * @param {Array<Record<string, any>>} records - Its index records.
+     * @returns {void}
+     */
+    const ingest = (pkg, records) => {
         // A base is only needed to resolve a page *URL*, so a pack-only
         // dependency — Foundry addresses and no site, which `kethira` is by
         // licensing rather than by accident — needs none. Demanding one would
@@ -367,10 +345,40 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // an infobox sorting a being's skills — has no other way to
                 // learn it about a note another package publishes.
                 subType: record.subType ?? undefined,
+                // A file the other package ships, carried through whole. Its
+                // `path` is that package's path, so a consumer joins its own
+                // root onto it and resolves in one step — which is the point of
+                // the record naming a path at all.
+                asset: record.asset ?? undefined,
                 package: pkg,
             });
         }
         packages.add(pkg);
+    };
+
+    // The toolchain's own files, first and unconditionally. `packagebuild` is
+    // an npm dependency of every consumer rather than a Foundry package, so
+    // there is nothing to declare and nothing to fetch — the tree is already on
+    // disk beside this module. The special case is entirely in the
+    // *acquisition*: the records join the index like any other package's, so
+    // every lookup stays one path.
+    ingest(PACKAGEBUILD_PACKAGE, packageBuildRecords());
+
+    for (const file of cachedMetadataFiles(config)) {
+        let records;
+        try {
+            records = fs
+                .readFileSync(file, "utf8")
+                .split("\n")
+                .filter((line) => line.trim())
+                .map((line) => JSON.parse(line));
+        } catch (err) {
+            stale.push({ package: packageOfCache(file), reason: `unreadable: ${err.message}` });
+            continue;
+        }
+        const pkg = records[0]?.package ?? packageOfCache(file);
+        if (local.has(pkg)) continue;
+        ingest(pkg, records);
     }
 
     return { index, packages, stale };

package/engine/note-vocabulary.mjs

@@ -105,6 +105,10 @@ import { currentType } from "./ids.mjs";
  *   entry of the map is. A finding names the entry at fault rather than
  *   quoting the whole map back, so the string an author has to correct is the
  *   one the message holds.
+ * @property {string} [ref] - The type a bare value takes. An art slot declares
+ *   one — `icon` for `icon` and `tokenIcon`, `image` for `bgImage` and
+ *   `banner` — so `icon: anvil` names `icon-anvil` while a value carrying the
+ *   separator states its own address.
  * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
  *   `"pack"` means each is a pack this package declares, so a key naming none
  *   is a finding of its own: it addresses a hierarchy nothing will ever read.
@@ -185,6 +189,57 @@ const TEMPLATE_PRIORITY = Object.freeze({
     describe: "Template priority; unset means the note is not a template.",
 });
 
+/**
+ * What a token on the canvas wears — an Actor type's second piece of art.
+ *
+ * Declared once and shared by the two Actor types, beside
+ * {@link TEMPLATE_PRIORITY} and for the same reason. Unset it follows `icon`:
+ * a token has to read at grid scale and when a map is zoomed out, so it is an
+ * `icon` rather than an `image` and its fallback has to be `icon`-typed too.
+ *
+ * @type {DataFieldSpec}
+ */
+const TOKEN_ICON = Object.freeze({
+    name: "tokenIcon",
+    ...LINK,
+    ref: "icon",
+    describe: "What a token on the canvas wears — an `icon` address; unset, it follows `icon`.",
+});
+
+/**
+ * The `data:` keys **every** note type accepts, whatever it is.
+ *
+ * `data:` is a closed container and the per-type vocabularies are the only
+ * lists there are, so a key legal on every type needs somewhere that is not one
+ * type's list — including the types whose own vocabulary is empty. Repeating a
+ * row in twenty-five tables would be twenty-five chances for one of them to
+ * disagree with the rest.
+ *
+ * Both are art slots, and they are legal everywhere for different reasons.
+ * `icon` is the document's profile art and most types compile into a document
+ * that carries one; where a type's passes emit none, the frontmatter lint says
+ * so as a warning rather than the vocabulary refusing the key, because the
+ * value may still be read by a page template. `banner` reaches no compiled
+ * document at all — it is the page's hero image — and a page is what every note
+ * publishes.
+ *
+ * @type {readonly DataFieldSpec[]}
+ */
+export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "icon",
+        ...LINK,
+        ref: "icon",
+        describe: "The document's profile art — an `icon` address, resolved into `img`.",
+    }),
+    Object.freeze({
+        name: "banner",
+        ...LINK,
+        ref: "image",
+        describe: "The page's hero image — an `image` address. Reaches no compiled document.",
+    }),
+]);
+
 /**
  * The four gear values every carried thing declares.
  *
@@ -477,14 +532,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         // values here would put a second, weaker answer beside the real one.
         subTypes: null,
         data: Object.freeze([
-            {
-                name: "portrait",
-                ...TEXT,
-                describe:
-                    "Path to the portrait image. Its first segment says which package owns " +
-                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
-                    "else is this package's own and is rooted under its assets.",
-            },
+            TOKEN_ICON,
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
@@ -527,17 +575,7 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     vehicle: Object.freeze({
         subTypes: null,
-        data: Object.freeze([
-            {
-                name: "portrait",
-                ...TEXT,
-                describe:
-                    "Path to the portrait image. Its first segment says which package owns " +
-                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
-                    "else is this package's own and is rooted under its assets.",
-            },
-            TEMPLATE_PRIORITY,
-        ]),
+        data: Object.freeze([TOKEN_ICON, TEMPLATE_PRIORITY]),
     }),
 
     /* ----- items ---------------------------------------------------- */
@@ -999,16 +1037,13 @@ export const NOTE_VOCABULARY = Object.freeze({
         // derived for them, which is precisely what a subType decides.
         subTypes: Object.freeze(["battlemap", "localmap", "regionalmap"]),
         data: Object.freeze([
-            // `img`, as every other note type spells its artwork. A map alone
-            // read `image` out of its `sohl:` block; that spelling is retired
-            // and gone, so the two names are one again.
+            // A Scene has no `img`, so the shared art key reaches nothing here:
+            // a map's background is its own slot, and an `image` address.
             {
-                name: "img",
-                ...TEXT,
-                describe:
-                    "Path to the map art, owned by whichever package its first segment " +
-                    "names — `systems/…` and `modules/…` unchanged, anything else this " +
-                    "package's own.",
+                name: "bgImage",
+                ...LINK,
+                ref: "image",
+                describe: "The map's background art — an `image` address.",
             },
             {
                 name: "dimensions",
@@ -1150,12 +1185,19 @@ assertVocabularyCharset(NOTE_VOCABULARY);
  * @param {string} type - The note's `type`.
  * @param {Readonly<Record<string, TypeVocabulary>>} [vocabulary] - The registry
  *   to read, defaulting to {@link NOTE_VOCABULARY}.
+ * {@link SHARED_DATA_FIELDS} come first, because they are part of every type's
+ * declaration and a caller asking what a type accepts must be told all of it.
+ *
  * @returns {readonly DataFieldSpec[]|undefined} The declaration, or `undefined`
  *   when the type declares none — which is not the same as declaring an empty
  *   one, and is why the lint makes no claim rather than refusing every key.
  */
 export function dataFields(type, vocabulary = NOTE_VOCABULARY) {
-    return vocabulary?.[currentType(type)]?.data;
+    const entry = vocabulary?.[currentType(type)];
+    if (!entry) return undefined;
+    // The shared keys first, so a type's own declarations keep their authored
+    // order behind them and a reader meets the art before the mechanics.
+    return Object.freeze([...SHARED_DATA_FIELDS, ...(entry.data ?? [])]);
 }
 
 /**

package/engine/pack-router.mjs

@@ -371,6 +371,20 @@ export function createPackRouter(packs) {
             return out;
         },
 
+        /**
+         * The system one pack declares, if it declares one.
+         *
+         * A pack declaring none takes the compiler its document type falls
+         * back to, so `undefined` here is an answer rather than a gap: it says
+         * the pack's documents are whichever system that pass writes.
+         *
+         * @param {string} name - The pack name.
+         * @returns {string|undefined} Its `system:`, or `undefined`.
+         */
+        systemOf(name) {
+            return byName.get(name)?.system || undefined;
+        },
+
         /**
          * The pack of a type that receives notes declaring none.
          *

package/engine/packagebuild-index.mjs

@@ -0,0 +1,124 @@
+/*
+ * 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 toolchain's own content index — the files it ships, addressed.
+ *
+ * package-build ships a set of images, section banners chiefly, that many
+ * packages draw on. `packagebuild-none-image-<shortcode>` lets a note reach one
+ * without declaring a dependency on some parent system or module it otherwise
+ * has no relationship with, which is the whole point: the alternative is every
+ * package depending on one of the others just to borrow a banner.
+ *
+ * **Every other package's index is fetched; this one is read from disk.**
+ * package-build is an npm dependency of every consumer rather than a Foundry
+ * package, so there is no release archive to fetch and no reason to fetch one —
+ * `node_modules/@heroiclands/package-build/assets/` is already there. That is
+ * the one difference, and it is entirely about *acquisition*: the records join
+ * `foreign.index` like any other package's, so every lookup stays one path.
+ *
+ * **A cold cache is not a failure mode here**, and the walk is why. The records
+ * are derived from the shipped tree each time they are asked for rather than
+ * read back from a file, so an installed copy and a git checkout answer alike
+ * and nothing can be half-fetched. {@link emitPackageBuildIndex} publishes the
+ * same walk as a file for the readers that are not this process — the website,
+ * the book, the Foundry runtime — and a guard holds the two together.
+ *
+ * **These addresses have no Foundry form, by construction.** Foundry installs
+ * no package for this one, so `packageAddresses` has no entry and
+ * `resolvePathname` yields `null` rather than deriving
+ * `modules/packagebuild/assets/…`, which installs nowhere. The only slot that
+ * names them is `banner`, which reaches no compiled document at all.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { collectAssetRecords } from "./asset-index.mjs";
+import { recordPath, sortKeysDeep } from "./index-records.mjs";
+import { PACKAGEBUILD_PACKAGE, metadataFileName } from "./packages.mjs";
+
+/**
+ * This package's own root, wherever it is installed.
+ *
+ * Derived from this module's location rather than from a configuration: the
+ * files being indexed sit beside it in the same tarball, so the one reliable
+ * answer is "up from here". A consuming repository's `rootDir` names its own
+ * tree and says nothing about where its dependencies live.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * The asset directory this package ships.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_ASSETS = path.join(PACKAGEBUILD_ROOT, "assets");
+
+/**
+ * Where the published index sits, beside the files it describes.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_INDEX_FILE = path.join(
+    PACKAGEBUILD_ROOT,
+    metadataFileName(PACKAGEBUILD_PACKAGE),
+);
+
+/**
+ * The index records for the files this package ships.
+ *
+ * Walked rather than read back, so an installed copy and a git checkout answer
+ * alike and there is no state to be stale. The tree is small — a handful of
+ * banners — so the walk costs nothing a build would notice.
+ *
+ * @param {string} [assetsBase] - The asset directory, for a caller testing
+ *   against a tree of its own.
+ * @returns {Array<Record<string, any>>} One record per addressable file.
+ */
+export function packageBuildRecords(assetsBase = PACKAGEBUILD_ASSETS) {
+    const records = collectAssetRecords(assetsBase, {
+        contentPackage: PACKAGEBUILD_PACKAGE,
+    }).map((record) => /** @type {Record<string, any>} */ (sortKeysDeep(record)));
+    // Ordered and key-sorted like every other index, and for the same reason:
+    // directory-read order is a fact about the filesystem, so two runs over an
+    // unchanged tree have to produce an identical file.
+    records.sort((a, b) => recordPath(a).localeCompare(recordPath(b), "en"));
+    return records;
+}
+
+/**
+ * Publish the index as a file, for the readers that are not this process.
+ *
+ * The website, the book and the Foundry runtime each read a package's index as
+ * JSON Lines; this package's has to be one too, and it ships in the tarball
+ * beside the images it describes.
+ *
+ * @param {object} [options] - Options.
+ * @param {string} [options.assetsBase] - The asset directory to walk.
+ * @param {string} [options.file] - Where to write it.
+ * @returns {{file: string, assets: number, bytes: number}} Where it was
+ *   written, how many files it holds, and its size.
+ */
+export function emitPackageBuildIndex({ assetsBase, file = PACKAGEBUILD_INDEX_FILE } = {}) {
+    const records = packageBuildRecords(assetsBase);
+    const text = records.length ? `${records.map((r) => JSON.stringify(r)).join("\n")}\n` : "";
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text);
+    return { file, assets: records.length, bytes: Buffer.byteLength(text) };
+}

package/engine/packages.mjs

@@ -0,0 +1,83 @@
+/*
+ * 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 `<package>` segment's own registry: the names no repository may claim.
+ *
+ * A content package names itself, so the registry is open — and exactly one
+ * name is held back from it.
+ *
+ * **`packagebuild` is a package that is not a package.** package-build is an npm
+ * package rather than a system or a module, and it ships a set of images —
+ * section banners chiefly — that many packages draw on. Addressing them as
+ * `packagebuild-none-image-<shortcode>` lets a note reach one without declaring a
+ * dependency on some parent system or module it otherwise has no relationship
+ * with, which is the whole point: the alternative is every package depending on
+ * one of the others just to borrow a banner.
+ *
+ * So nothing may create a real package that collides with the name, and its
+ * resolution is special-cased, because no installed directory sits behind it.
+ *
+ * This module is a **leaf with no local imports**, so the configuration
+ * validator can name it without closing a cycle around `content-config.mjs`.
+ *
+ * @module
+ */
+
+/**
+ * The address namespace package-build's own assets publish under.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_PACKAGE = "packagebuild";
+
+/**
+ * Every package name a repository may not claim.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const RESERVED_PACKAGES = Object.freeze(new Set([PACKAGEBUILD_PACKAGE]));
+
+/**
+ * What a package's content index is called, wherever it is written or fetched.
+ *
+ * **The local index and the published artifact are one file.** A package emits
+ * this, ships it as a release asset, and advertises it as `flags.metadataUrl`;
+ * a consumer fetches that same file into its cache and reads it. Naming it in
+ * one function is what keeps the emitter, the release and the fetcher from
+ * drifting into three spellings of one artifact.
+ *
+ * The `-metadata` suffix earns its place: a bare `<package>.jsonl` says nothing
+ * about what it holds, and these files land in a cache directory beside other
+ * packages' artifacts where the name is all a reader has.
+ *
+ * It lives here rather than beside the loader because the loader reaches the
+ * toolchain's own index, which has to name its file without importing the
+ * loader back.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file name, e.g. `sohl-metadata.jsonl`.
+ */
+export function metadataFileName(pkg) {
+    return `${pkg}-metadata.jsonl`;
+}
+
+/**
+ * Whether a package name is held back from the open registry.
+ *
+ * @param {unknown} pkg - The candidate `contentPackage`.
+ * @returns {boolean} True when the name is reserved.
+ */
+export function isReservedPackage(pkg) {
+    return typeof pkg === "string" && RESERVED_PACKAGES.has(pkg.toLowerCase());
+}