@heroiclands/package-build 17.2.0 → 18.0.0

package/types/engine/ids.d.mts

@@ -16,6 +16,39 @@ export function makeId(namespace: string, value: string): string;
  * @throws {Error} Naming the replacement type.
  */
 export function assertTypeNotRetired(type: string, where?: string): void;
+/**
+ * The current spelling of a content type: itself, or what it was renamed to.
+ *
+ * Every table keyed by note type is keyed by the **current** name, and every
+ * lookup goes through this — which is the whole of the window's behaviour, in
+ * one function, so no two readers can disagree about which vocabulary a note
+ * is held to.
+ *
+ * A non-string passes through untouched: callers hand this whatever the
+ * frontmatter carried, and inventing a type for a number would hide the
+ * missing-`type:` finding that belongs to the linter.
+ *
+ * @param {any} type - The type as authored, or as a link spells it.
+ * @returns {any} The current spelling.
+ */
+export function currentType(type: any): any;
+/**
+ * What a note declaring a renamed type is told, in one place.
+ *
+ * Shared by every reporter, because an author meets whichever runs first and
+ * they should read the same. It names the type to write rather than a value to
+ * correct — no value makes the retired spelling right — and it says the note
+ * compiles either way, so a reader knows this is a rename to schedule rather
+ * than a build to unbreak.
+ *
+ * @param {string} retired - The spelling the note used.
+ * @param {string} current - What to write instead.
+ * @param {string} [where] - What carries it — a file path, a link target —
+ *   appended to the message. Omit it where the caller emits through a
+ *   diagnostic, whose locator already starts the line.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function renamedTypeMessage(retired: string, current: string, where?: string): string;
 /**
  * The pack a type's documents live in, in the conventional one-pack-per-type
  * layout.
@@ -94,6 +127,27 @@ export const MAP_TYPES: ReadonlySet<string>;
  * @type {readonly string[]}
  */
 export const MAP_SUBTYPES: readonly string[];
+/**
+ * Content types whose whole document **is** a JournalEntry.
+ *
+ * Prose, and nothing else: each compiles into one journal entry of its own,
+ * with no second document to point at. That is what separates them from the
+ * doc-carrying types in `item-docs.mjs`, whose prose becomes a journal *beside*
+ * an item, a macro or a scene — those are two documents, and the pair is
+ * addressed as `<type>` and `doc<type>`. These are one, so there is no
+ * `docplace` and nothing synthesizes one.
+ *
+ * `doc` was the only member until #241. `place`, `lore` and `scenario` are in
+ * the published content format and were declared for validation in #233, but
+ * nothing routed them: a note of one lint-ed clean and then compiled into
+ * nothing, because {@link PACK_BY_TYPE} did not name it and the open-set
+ * default sent it to the items pack. `sohl-thalorna` could not compile a single
+ * pack for exactly this reason — 450 notes, and the same 450 the linter had
+ * reported before it learned the types.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const JOURNAL_TYPES: ReadonlySet<string>;
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.
@@ -129,6 +183,48 @@ export const PACK_BY_TYPE: Readonly<Record<string, {
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_TYPES: Readonly<Record<string, string>>;
+/**
+ * Content types that were **renamed**, and what each is called now.
+ *
+ * A retired type and a renamed one are different cases, and only the first can
+ * be refused. `character` above was retired *outright* — nothing a note wrote
+ * made it right, so {@link assertTypeNotRetired} throws. A renamed type has a
+ * replacement, the two spellings mean the same thing, and a note carrying the
+ * old one compiles into exactly the document it always did: refusing it would
+ * fail a build over a note that is not wrong.
+ *
+ * So these retire in the three steps `package:` took (#56), and this table is
+ * the **first**: both spellings resolve, the current one is canonical, and the
+ * retired one is *reported* — never refused. The sweep of the content trees and
+ * the refusal come after, once no tree writes the old name. That is the same
+ * rule `RETIRED_FIELD_ALIASES` states for a renamed *field*, and for the same
+ * reason: a consumer must be able to adopt the new toolchain before its content
+ * moves, and there are some 31,000 references to move.
+ *
+ * **Why these three (#78).** `armorgear`, `concoctiongear` and `projectilegear`
+ * named the *SoHL document subtype* a note happened to compile into rather than
+ * the thing the note is about. A note's `type` sits outside the `sohl:` and
+ * `hm3:` blocks precisely because it belongs to no system, and HM3 already
+ * compiles a `projectile` into a `missilegear` — so the suffix was never a fact
+ * about the note. `weapongear` keeps its name: SoHL and HM3 both call the
+ * document that, and #78's table has no row for it.
+ *
+ * **Keyed by the retired spelling**, which is the opposite of
+ * `RETIRED_FIELD_ALIASES`. The direction follows the operation: a field alias
+ * is scoped by the schema that declares the *current* name, so that is what a
+ * reader asks with; a type alias is applied to a value read off a note, so what
+ * a reader has in hand is the retired spelling and what it needs is the
+ * replacement.
+ *
+ * **The address is not normalised.** A note's canonical address — and therefore
+ * its document id — carries its `type` as authored, so both spellings keep the
+ * addresses they already publish and a tree that has not swept compiles
+ * byte-identically. Renaming the type in a note *is* an address move, which is
+ * the sweep's business and not this table's.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RENAMED_TYPES: Readonly<Record<string, string>>;
 /** Where every other content type compiles: the items pack. */
 export const ITEM_PACK: Readonly<{
     pack: "items";

package/types/engine/index-records.d.mts

@@ -0,0 +1,68 @@
+/**
+ * The file a record was read from, as an absolute path.
+ *
+ * **The one composition, because there were four.** `file.path` is recorded
+ * *relative* to the content root deliberately — an absolute one is a fact about
+ * the machine that built the index, would differ between two checkouts of the
+ * same tree, and would put someone's home directory in a published artifact. So
+ * every pass that reads the index and then needs to open a note has to compose
+ * the absolute form, and each of the readers converted for #243 had written its
+ * own `path.join(base, ...record.file.path.split("/"))`. Four copies of one
+ * rule is what #243 exists to remove, so here it is once.
+ *
+ * The split is on `"/"` rather than `path.sep` because the recorded path is
+ * always POSIX — that is what makes the index identical on every platform.
+ *
+ * @param {string} contentBase - Root of the content tree the index was built from.
+ * @param {object} record - An index record.
+ * @returns {string} The note's absolute path.
+ */
+export function noteFile(contentBase: string, record: object): string;
+/**
+ * The note's own frontmatter, as authored, from an index record.
+ *
+ * The inverse of the record's spread, and exact rather than best-effort: a
+ * record is the note's frontmatter plus {@link DERIVED_KEYS}, and a note that
+ * authors one of those keys fails the walk — so removing them cannot remove
+ * anything the note wrote. That enforced pairing is what lets a pass read the
+ * corpus from the index and still lint, route or compile what the *author*
+ * typed, rather than reasoning about `address:` and `anchors:` as though
+ * someone had written them.
+ *
+ * Lives beside the list it is the inverse of, so the two cannot drift.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {Record<string, any>} The frontmatter, without the derived keys.
+ */
+export function authoredFrontmatter(record: Record<string, any>): Record<string, any>;
+/**
+ * Whether a record is a note's, rather than a documentation journal's.
+ *
+ * An item note yields two records — itself and the JournalEntry its prose
+ * compiles into — and the second is a document, not a note: it has no file of
+ * its own to read, no frontmatter an author wrote, and its `type` is the
+ * virtual `doc<type>` that `readQualifier` resolves rather than a type any tree
+ * declares. A reader enumerating the corpus wants the notes; one resolving an
+ * address wants both.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean} True for a note's own record.
+ */
+export function isNoteRecord(record: Record<string, any>): boolean;
+/**
+ * The keys the content index adds to a record, which a note therefore may not
+ * carry itself.
+ *
+ * `package` is the note's distribution unit — the configured `contentPackage`,
+ * since a note declaring its own is a hard error (#56) — and it matches what
+ * the content-table expander puts on the same field, so a query reads the same
+ * value from either. `file` namespaces the note's place in the tree, again
+ * matching the expander's `file.*`.
+ *
+ * Both are checked rather than assumed: `folder` is real frontmatter on most
+ * notes, so the neighbouring names are close enough to a real key that a silent
+ * overwrite is a plausible future rather than a hypothetical one.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const DERIVED_KEYS: ReadonlyArray<string>;

package/types/engine/index.d.mts

@@ -6,17 +6,21 @@ export * as contentTree from "./content-tree.mjs";
 export * as packConfig from "./pack-config.mjs";
 export * as packRouter from "./pack-router.mjs";
 export * as noteClaims from "./note-claims.mjs";
+export * as folderNotes from "./folder-notes.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
+export * as systems from "./systems.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
-export * as foreignManifests from "./foreign-manifests.mjs";
-export * as kbManifest from "./kb-manifest.mjs";
-export * as manifestEmit from "./manifest-emit.mjs";
+export * as subtypeRegistry from "./subtype-registry.mjs";
+export * as noteIds from "./note-ids.mjs";
+export * as noteRenames from "./note-renames.mjs";
+export * as metadataIndex from "./metadata-index.mjs";
+export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
@@ -35,6 +39,8 @@ export * as journals from "./journals.mjs";
 export * as macros from "./macros.mjs";
 export * as mapNotes from "./map-notes.mjs";
 export * as scenes from "./scenes.mjs";
+export * as bundleNotes from "./bundle-notes.mjs";
+export * as bundles from "./bundles.mjs";
 export * as sceneLevels from "./scene-levels.mjs";
 export * as generate from "./generate.mjs";
 export * as compendiums from "./compendiums.mjs";

package/types/engine/item-compiler.d.mts

@@ -0,0 +1,131 @@
+/**
+ * The description an item carries: a pointer to its **item doc**, the
+ * JournalEntry the journals pass compiles this same body into (#1348).
+ *
+ * The prose is not rendered into the item at all. Carrying it would duplicate
+ * it onto every actor holding the item — 7.59 MB of copies across the actors
+ * pack, of which 133 KB was distinct — where a link is 60 bytes and always
+ * current. The two passes derive the target from the note's own id, so neither
+ * has to see the other's output; both split the *converted* markdown, so an H1
+ * carrying a wikilink names the same page on both sides.
+ *
+ * An item with no prose points at nothing, exactly as the journals pass writes
+ * no entry for it.
+ *
+ * @param {string} markdown - The note body, tables expanded and wikilinks
+ *   resolved.
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} name - The item's name.
+ * @returns {string} The pointer, or "" for a note with no body.
+ */
+export function itemDescription(markdown: string, fm: object, name: string): string;
+/**
+ * The Item compile pass of one game system.
+ *
+ * A subclass declares its {@link SystemItemCompiler.documentSubtypes} and, if
+ * its system writes any, the {@link SystemItemCompiler#commonSystem} keys. It
+ * declares nothing else: the class is abstract only in the sense that a map is
+ * required, and instantiating it without one is a programming error rather than
+ * a configuration one.
+ */
+export class SystemItemCompiler extends BasePackCompiler {
+    /**
+     * The note-type → document-subtype map this pass compiles against.
+     *
+     * Stated by the class rather than reached for through a module import, so
+     * every decision the pass makes — which notes it claims, which subtype each
+     * becomes, which registry builds it, which block it reads — reads one
+     * declaration. A second system replaces that declaration and nothing else.
+     *
+     * @type {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined}
+     */
+    static documentSubtypes: import("./document-subtypes.mjs").DocumentSubtypeMap | undefined;
+    /**
+     * The frontmatter block this pass reads, and the registry it addresses.
+     *
+     * @returns {string} The system's block name.
+     */
+    get system(): string;
+    /**
+     * How many of each item type this pass wrote, for the summary. Every type
+     * is present from the start so the tally reads as a census of the
+     * whitelist rather than of what happened to compile.
+     *
+     * @type {Record<string, number>}
+     */
+    counts: Record<string, number>;
+    /**
+     * The Foundry Item subtype a note compiles into.
+     *
+     * **Looked up, not inferred.** For every type this system declares, the
+     * emitted subtype is the map's, so the note vocabulary and the document
+     * vocabulary are two separately-stated things rather than one string
+     * written twice (#79).
+     *
+     * **A type the map does not name belongs to the consumer**, and its
+     * registry entry is the declaration: a repository shipping an item type of
+     * its own writes it once, in the `itemBuilders` table of its
+     * `package-build.config.yaml`, and that key is what the document is a
+     * subtype of. That is an authored statement in the consumer's own
+     * configuration, not a coincidence inside this package's source — and
+     * refusing it here would silently drop every document of a type this system
+     * has no opinion about (#7/#1563).
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {string} The document's `type`.
+     */
+    itemSubtype(fm: object): string;
+    /** An item is named by its own type in the log, not by "item". */
+    noteLabel(fm: any): any;
+    /**
+     * The `system` keys this system's compiler writes on **every** item, beside
+     * whatever the type's declared fields emit.
+     *
+     * Nothing by default, which is the honest position for a system that has
+     * not said otherwise: a key written here lands on every document of every
+     * type, so inventing one that the receiving DataModel does not declare
+     * would be a finding on the whole pack (#155).
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {object} at - What the pass already knows about this note.
+     * @param {string} at.description - The pointer to the note's item doc.
+     * @param {string} at.markdown - The note body, tables expanded and
+     *   wikilinks resolved, for a system that reads an anchored section out of
+     *   it.
+     * @param {string} at.label - Human-readable context for error messages.
+     * @returns {object} The shared `system` fields.
+     */
+    commonSystem(fm: object, { description, markdown, label }: {
+        description: string;
+        markdown: string;
+        label: string;
+    }): object;
+    /**
+     * The document's `flags` — whatever the note authors, and whatever this
+     * system writes there of its own accord.
+     *
+     * The authored flags alone by default, which is the honest position for a
+     * system that has not said otherwise. A system whose data model has nowhere
+     * to record a shared fact keeps it here instead: HM3 writes the template
+     * priority as `flags.hm3.templatePriority`, because it declares no `system`
+     * field for it and an undeclared `system` key is discarded at load without
+     * a word.
+     *
+     * **This is the one emitted key nothing else can check** (#283). A `system`
+     * key this pass invents is caught by the emitted-`system` check against the
+     * receiving schema, but a flag is declared by no schema — so an omission
+     * here is silent, and was: the Actor pass wrote the priority and this one
+     * did not, for as long as there had been two passes.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {object} The flags to emit.
+     */
+    commonFlags(fm: object): object;
+    /** @inheritdoc */
+    onCompiled(fm: any): void;
+    /** @inheritdoc */
+    reportCompiled(stats: any): void;
+    /** @inheritdoc */
+    reportDetail(stats: any): void;
+}
+import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/journals.d.mts

@@ -21,35 +21,73 @@ export function splitPages(body: any, leadName?: string): {
     markdown: string;
 }[];
 /**
- * Two headings in one note sharing an `{#anchor}` derive the same page id, which
- * the LevelDB packer reports only as an opaque duplicate-key collision. Catch it
- * here, where the note and the slug can be named.
+ * Two pages in one note that would derive the same id, which the LevelDB packer
+ * reports only as an opaque duplicate-key collision. Catch it here, where the
+ * note and the page can be named.
  *
- * @param {Array<{anchorSlug: string|null}>} rawPages - From {@link splitPages}.
+ * Both halves of {@link journalPageId} are checked, because each is now keyed
+ * on an identity alone:
+ *
+ * - **An anchor**, declared twice, has always collided.
+ * - **A name**, repeated among the unanchored pages, collides since #268 took
+ *   the index out of the key. `MD024` with `siblings_only` already makes two
+ *   sibling headings with the same text a lint error, so this is the same rule
+ *   restated where the build can enforce it — a lint is a separate command, and
+ *   the compile must not depend on someone having run it.
+ *
+ * The two are counted separately: an anchored page takes its id from the slug
+ * and an unanchored one from the name, so a page named for another's anchor is
+ * not a collision.
+ *
+ * @param {Array<{anchorSlug: string|null, name: string}>} rawPages - From
+ *   {@link splitPages}.
+ * @param {string} noteName - The note, for the error message.
+ * @throws {Error} When two pages in one note share an anchor or a name.
+ */
+export function assertUniquePages(rawPages: Array<{
+    anchorSlug: string | null;
+    name: string;
+}>, noteName: string): void;
+/**
+ * The anchor half of {@link assertUniquePages}, under its former name.
+ *
+ * @deprecated Call {@link assertUniquePages}, which checks page names too.
+ * @param {Array<{anchorSlug: string|null, name: string}>} rawPages - From
+ *   {@link splitPages}.
  * @param {string} noteName - The note, for the error message.
- * @throws {Error} When an anchor is declared twice in the same note.
  */
 export function assertUniqueAnchors(rawPages: Array<{
     anchorSlug: string | null;
+    name: string;
 }>, noteName: string): void;
 /**
  * The id of one page within its entry.
  *
  * An anchored page takes the id its inbound links compute from the note id and
  * the slug, so link and page agree without shared state. Every other page is
- * keyed by its position and name, which is what lets the items pass address an
- * item doc's first page without having compiled it (see
+ * keyed by its **name**, which is what lets the items pass address an item
+ * doc's first page without having compiled it (see
  * {@link sohl.utils.packs.itemDocPointer}).
  *
+ * **It takes no index** (#268). A page used to be keyed by position *and* name,
+ * so inserting a heading renumbered every page after it and a re-import created
+ * new pages beside the old ones — while nothing about those pages had changed.
+ * The anchored case above never took one, and is the shape this now shares.
+ *
+ * The name is a sound identity here in a way it is not for an embedded item: a
+ * page's name is its heading, and `MD024` with `siblings_only` is in the shared
+ * markdownlint rule set, so two sibling headings with the same text are already
+ * a lint error. {@link assertUniquePages} states the same thing at compile
+ * time, where the packer would otherwise report only an opaque duplicate key.
+ *
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {{anchorSlug: string|null, name: string}} page - From {@link splitPages}.
- * @param {number} index - The page's position in the entry.
  * @returns {string} A 16-character Foundry id.
  */
 export function journalPageId(entryId: string, page: {
     anchorSlug: string | null;
     name: string;
-}, index: number): string;
+}): string;
 /**
  * Compile split pages into JournalEntryPage documents.
  *

package/types/engine/metadata-index.d.mts

@@ -0,0 +1,226 @@
+/**
+ * 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: string): string;
+/**
+ * Every dependency whose published index this build resolves addresses through.
+ *
+ * **Every declared dependency, not only those supplying an item catalogue.**
+ * `itemCatalog: true` says a dependency supplies *items*; citing its
+ * *addresses* is a separate edge, and a package may have either without the
+ * other. `harn-ensemble` cites no foreign address and carries 324,016 embedded
+ * item references (`HeroicLands/harn-ensemble#42`); a package citing addresses
+ * and needing no items is the mirror of it. Gating the index on the catalogue
+ * flag would serve neither.
+ *
+ * The declaration is the one already in the emitted `system.json` /
+ * `module.json`, so it cannot drift from what Foundry itself installs, and
+ * there is no new configuration key to keep in step. Each entry carries the
+ * producer's own `manifest` URL, so the fetcher needs no address of its own:
+ * it reads that manifest and takes the `flags.metadataUrl` it advertises.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string,
+ *   verified: string|undefined}>} The dependencies, in declaration order.
+ */
+export function metadataRelationships(config: object): Array<{
+    id: string;
+    manifest: string;
+    kind: string;
+    verified: string | undefined;
+}>;
+/**
+ * The cache directory for one dependency's index at one version.
+ *
+ * Keyed by version so that changing the pinned version is a different cache
+ * rather than a silent overwrite, and so a second build costs nothing — the
+ * same rule the item catalogue's cache follows, for the same reason.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} id - The dependency's package id.
+ * @param {string} version - Its resolved version.
+ * @returns {string} The directory.
+ */
+export function metadataCacheDir(config: object, id: string, version: string): string;
+/**
+ * Mark a dependency's cache complete.
+ *
+ * @param {string} dir - The dependency's cache directory.
+ * @returns {void}
+ */
+export function markComplete(dir: string): void;
+/**
+ * The fetched index files this build resolves foreign addresses against.
+ *
+ * **Reads the cache only.** A cold cache is an error naming the command that
+ * fills it, rather than a download nobody asked for: a compile that reaches the
+ * network is not reproducible and fails strangely offline. That is the item
+ * catalogue's rule, and it holds here for the same reason.
+ *
+ * A half-finished fetch counts as cold. A partial index resolves some addresses
+ * and fails others with nothing to distinguish the two, which is worse than
+ * resolving none — the failure would read as a typo in whichever note happened
+ * to cite the missing half.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} One index file per declared dependency.
+ * @throws {Error} When a declared dependency has not been fetched.
+ */
+export function cachedMetadataFiles(config: object): string[];
+/**
+ * The same fetched indexes, each paired with the package that published it.
+ *
+ * The id is what a SQL content table addresses a dependency's notes by
+ * (`FROM sohl.notes`, #246), so the pairing has to survive the lookup —
+ * {@link cachedMetadataFiles} drops it, and a caller reconstructing the id from
+ * the file name would be parsing a path to recover something the declaration
+ * already stated.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, file: string}>} One entry per declared
+ *   dependency.
+ * @throws {Error} When a declared dependency has not been fetched.
+ */
+export function cachedMetadataIndexes(config: object): Array<{
+    id: string;
+    file: string;
+}>;
+/**
+ * The newest cached version among several version-keyed cache directories.
+ *
+ * Versions are compared **numerically per segment**, not as strings: a plain
+ * sort puts `0.8.10` before `0.8.2`, so a build that had cached both would
+ * silently resolve against the older one. A fetch always writes the currently
+ * declared version, so several present at once means an earlier pin was left
+ * behind rather than that a choice is genuinely open.
+ *
+ * **Both version-keyed caches under `build/cache` choose this way** — the
+ * content index here and the item catalogue in
+ * {@link module:engine/foreign-catalog} — so the comparison lives in one place
+ * rather than being written once per cache. Two copies would be two chances to
+ * get it wrong, and the wrong answer is invisible: every cached version is a
+ * complete, stamped, perfectly valid artifact, so picking the older one reports
+ * nothing and simply resolves against stale data (#272).
+ *
+ * @param {string[]} dirs - Complete cache directories, named `<id>@<version>`.
+ * @returns {string} The newest one.
+ */
+export function newestVersionDir(dirs: string[]): string;
+/**
+ * Resolve every foreign address this build can cite, from the fetched indexes.
+ *
+ * The replacement for the vendored link manifest, and deliberately the same
+ * return shape — a `Map` from canonical address to `{ url, name, uuid, … }` —
+ * so a foreign entry and a local one stay interchangeable at the point of use.
+ * What changed is where the data comes from: a file the producer published,
+ * not a copy a consumer committed.
+ *
+ * **A package this build publishes is skipped**, however it got into the cache.
+ * A build is authoritative in its own addresses, and reading them back from a
+ * fetched artifact would let a stale copy overrule the tree that is being
+ * compiled right now. It is also what stops a cycle forming: the mutual
+ * vendoring this replaces deadlocked because each package had to read the
+ * other's file before it could publish its own.
+ *
+ * **Nothing here can be stale.** The version gate the manifest needed existed
+ * because a vendored copy could sit at any age; a fetched index is pinned to
+ * the version the relationship declares, so `stale` now reports only what is
+ * genuinely unusable — an unreadable file, or a package with pages and no base
+ * to serve them from.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {Iterable<string>} localPackages - Packages this build publishes.
+ * @param {Record<string, string>} [bases] - Where each package is served.
+ * @returns {{index: Map<string, object>, packages: Set<string>,
+ *   stale: Array<{package: string, reason: string}>}} The resolved addresses,
+ *   which packages contributed, and what could not be read.
+ */
+export function loadForeignIndexes(config: object, localPackages: Iterable<string>, bases?: Record<string, string>): {
+    index: Map<string, object>;
+    packages: Set<string>;
+    stale: Array<{
+        package: string;
+        reason: string;
+    }>;
+};
+/**
+ * Where a dependency's fetched index sits, for naming it in a diagnostic.
+ *
+ * Best effort: the newest complete cache for that package, or the directory it
+ * would occupy. A finding has to name *a* file even when the cache is in the
+ * state the finding is about.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} pkg - The dependency's package id.
+ * @returns {string} A path to name in a diagnostic.
+ */
+export function cachedIndexPath(config: object, pkg: string): string;
+/**
+ * Whether a fetched index can still be *addressed*, as distinct from read.
+ *
+ * A consumer resolves cross-package links by canonical key, so it needs both
+ * sides to agree on the key's shape. When they drift the lookup cannot match on
+ * *any* input — and because a miss is indistinguishable from a typo, the
+ * symptom is a pile of dead addresses blamed on the notes that cite them rather
+ * than on the index at fault. A package whose every key is unreadable is
+ * therefore reported against the index, once, instead of once per citing note.
+ *
+ * The realistic cause is a version skew: a dependency released before the
+ * address grammar gained its `<system>` segment (#59) ships three-segment keys.
+ * Re-fetching after that dependency releases is the fix.
+ *
+ * @param {Map<string, object>} foreignIndex - The resolved foreign index.
+ * @returns {Array<{package: string, entries: number, sampleKey: string}>} One
+ *   finding per drifted package, in the order the index first names each.
+ */
+export function unaddressableForeignPackages(foreignIndex: Map<string, object>): Array<{
+    package: string;
+    entries: number;
+    sampleKey: string;
+}>;
+/**
+ * One finding, in the standard `file:line:column: severity: message` form.
+ *
+ * The position is recovered by locating the offending key in the index text:
+ * the finding is about a literal the reader can see in the file, so its
+ * position is implicit rather than absent. When the file cannot be read, or the
+ * key is not in it, the locator degrades to the file alone — a dropped field,
+ * never a guessed `1:1` that would send the reader to the top of a large file
+ * for a finding that is not there.
+ *
+ * @param {{package: string, entries: number, sampleKey: string}} finding - One
+ *   finding from {@link unaddressableForeignPackages}.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string} The formatted diagnostic, path first on the line.
+ */
+export function formatUnaddressableFinding(finding: {
+    package: string;
+    entries: number;
+    sampleKey: string;
+}, config: object): string;
+/**
+ * The relationship kinds that are dependencies, and therefore citable.
+ *
+ * A package may cite what it depends on and nothing else. `recommends` and
+ * `conflicts` are declarations *about* other packages rather than dependencies
+ * on them, so an address resolved through one would emit a link into a package
+ * the consumer does not require — a defect in the citing note, not a lookup to
+ * satisfy.
+ *
+ * @type {readonly string[]}
+ */
+export const METADATA_RELATIONSHIP_KINDS: readonly string[];
+export function isComplete(dir: string): boolean;