@heroiclands/package-build 17.1.0 → 18.0.0

package/types/engine/folder-notes.d.mts

@@ -0,0 +1,159 @@
+/**
+ * An authored `parent` with any wikilink brackets and label stripped.
+ *
+ * The specification types `parent` as a `WikiLink`, and a frontmatter link is
+ * written as a bare address — but `[[address]]` is what an author reaches for,
+ * and Obsidian wrote that form for years. Accepting both costs one regex and
+ * removes a failure whose message would have to explain the difference.
+ *
+ * @param {string|null} value - As authored.
+ * @returns {string|null} The bare address.
+ */
+export function bareAddress(value: string | null): string | null;
+/**
+ * The canonical address of a folder note in this package.
+ *
+ * @param {string} pkg - The content package.
+ * @param {string} shortcode - The folder's shortcode.
+ * @returns {string} `<pkg>-none-folder-<shortcode>`.
+ */
+export function folderAddress(pkg: string, shortcode: string): string;
+/**
+ * Collect every folder note in a content tree.
+ *
+ * The walk is the caller's to supply, so this stays testable without a tree on
+ * disk and so one build cannot disagree with another about what the corpus is
+ * (#243).
+ *
+ * @param {Iterable<{frontmatter: object|null, absPath: string}>} notes - As
+ *   yielded by `walkMarkdownTree`.
+ * @param {string} pkg - The content package, for the canonical address.
+ * @returns {FolderNote[]} One record per folder note, in walk order.
+ * @throws {Error} When a folder note is unusable on its own terms — no
+ *   shortcode, a shortcode that is not an address segment, or no name.
+ */
+export function collectFolderNotes(notes: Iterable<{
+    frontmatter: object | null;
+    absPath: string;
+}>, pkg: string): FolderNote[];
+/**
+ * Index folder notes by every form an author may address one by, and check the
+ * invariants that make the index sound.
+ *
+ * Three keys per folder, and no more: the canonical address, the
+ * `folder-<shortcode>` short form, and the bare shortcode. They are the
+ * suffixes of the canonical address the grammar admits (#273) — a `packFolder`
+ * or `parent` field supplies the type itself, so a bare shortcode is a complete
+ * address there.
+ *
+ * @param {FolderNote[]} folders - From {@link collectFolderNotes}.
+ * @returns {{byKey: Map<string, FolderNote>, folders: FolderNote[],
+ *   resolve: (value: string) => FolderNote, ancestorsOf: (folder: FolderNote)
+ *   => FolderNote[], parentOf: (folder: FolderNote) => FolderNote|null}}
+ * @throws {Error} On a duplicate shortcode, a duplicate id, a dead `parent`,
+ *   or a parent cycle.
+ */
+export function buildFolderNoteIndex(folders: FolderNote[]): {
+    byKey: Map<string, FolderNote>;
+    folders: FolderNote[];
+    resolve: (value: string) => FolderNote;
+    ancestorsOf: (folder: FolderNote) => FolderNote[];
+    parentOf: (folder: FolderNote) => FolderNote | null;
+};
+/**
+ * The Foundry `Folder` document one folder note compiles to, for one pack.
+ *
+ * The same folder materialises in several packs — the items pack and the
+ * journals pack both hold it when both hold something filed in it — and each
+ * copy differs only in `type`, which is the document class the folder holds.
+ * The `_id` is shared deliberately: a documentation journal filed beside its
+ * item is the whole point, and two ids would put them in two folders that
+ * merely looked alike.
+ *
+ * @param {FolderNote} folder - The folder note.
+ * @param {FolderNote|null} parent - Its parent, already resolved.
+ * @param {string} documentType - `"Item"`, `"JournalEntry"`, …
+ * @param {object} stats - The `_stats` block every emitted document carries.
+ * @returns {object} The Folder document.
+ */
+export function folderDocument(folder: FolderNote, parent: FolderNote | null, documentType: string, stats: object): object;
+/**
+ * The note type a folder is authored as.
+ *
+ * @type {string}
+ */
+export const FOLDER_TYPE: string;
+/**
+ * The id namespace a derived folder id is hashed under.
+ *
+ * Distinct from every other document's namespace so a folder and an item
+ * sharing a shortcode cannot derive the same id — the collision would be
+ * silent, since Foundry keys folders and documents in separate collections and
+ * neither would complain.
+ *
+ * @type {string}
+ */
+export const FOLDER_ID_NAMESPACE: string;
+/**
+ * One folder note, read from the tree.
+ *
+ * @typedef {object} FolderNote
+ * @property {string} shortcode - Its `(type, shortcode)` identity.
+ * @property {string} address - The canonical `<pkg>-none-folder-<shortcode>`.
+ * @property {string} name - The display name.
+ * @property {string|null} color - CSS hex, or `null`.
+ * @property {Record<string, string|null>} parent - The parent's authored
+ *   address per pack, keyed by pack name with {@link DEFAULT_PARENT} for the
+ *   unstated case. A folder's identity is one thing; its hierarchy is per-pack.
+ * @property {string} id - The Foundry id: authored, or derived from `address`.
+ * @property {boolean} derivedId - Whether `id` was derived rather than authored.
+ * @property {string} absPath - The file it was read from, for diagnostics.
+ */
+/**
+ * The key a per-pack `parent` map uses for "everywhere else".
+ *
+ * Spelled out rather than left as the absence of a key, so a map that states
+ * only exceptions still reads as a complete answer.
+ *
+ * @type {string}
+ */
+export const DEFAULT_PARENT: string;
+/**
+ * One folder note, read from the tree.
+ */
+export type FolderNote = {
+    /**
+     * - Its `(type, shortcode)` identity.
+     */
+    shortcode: string;
+    /**
+     * - The canonical `<pkg>-none-folder-<shortcode>`.
+     */
+    address: string;
+    /**
+     * - The display name.
+     */
+    name: string;
+    /**
+     * - CSS hex, or `null`.
+     */
+    color: string | null;
+    /**
+     * - The parent's authored
+     * address per pack, keyed by pack name with {@link DEFAULT_PARENT} for the
+     * unstated case. A folder's identity is one thing; its hierarchy is per-pack.
+     */
+    parent: Record<string, string | null>;
+    /**
+     * - The Foundry id: authored, or derived from `address`.
+     */
+    id: string;
+    /**
+     * - Whether `id` was derived rather than authored.
+     */
+    derivedId: boolean;
+    /**
+     * - The file it was read from, for diagnostics.
+     */
+    absPath: string;
+};

package/types/engine/foreign-catalog.d.mts

@@ -92,6 +92,59 @@ export function fetchCatalog(config: object, rel: {
 export function fetchCatalogFromPath(config: object, rel: {
     id: string;
 }, source: string): Promise<string>;
+/**
+ * Fetch one dependency's published content index (#239).
+ *
+ * **The chain is entirely declared.** The relationship names the dependency's
+ * manifest, the manifest advertises `flags.metadataUrl`, and that URL is the
+ * index — so nothing here holds an address of its own, and a dependency that
+ * moves its release assets does not break its consumers.
+ *
+ * Pinned by the same rule as the catalogue: `compatibility.verified` is the
+ * version this repository was built against, so a floating `releases/latest`
+ * URL is rewritten to it. A consumer resolving addresses against whatever the
+ * dependency published this morning is not reproducible.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string, verified?: string}} rel - The declared
+ *   relationship.
+ * @returns {Promise<string>} The cached index file.
+ */
+export function fetchMetadata(config: object, rel: {
+    id: string;
+    manifest: string;
+    verified?: string;
+}): Promise<string>;
+/**
+ * Fill the index cache from a locally built artifact rather than a release.
+ *
+ * The counterpart of {@link fetchCatalogFromPath}, and the same escape hatch
+ * for the same reason: two packages being changed together cannot each wait for
+ * the other to ship. The index is looked for beside the manifest — which is
+ * where a build leaves it and where the release publishes it — so a package
+ * directory and an unpacked zip are both usable as-is.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string}} rel - The declared relationship.
+ * @param {string} source - Path to the artifact or its directory.
+ * @returns {Promise<string>} The cached index file.
+ */
+export function fetchMetadataFromPath(config: object, rel: {
+    id: string;
+}, source: string): Promise<string>;
+/**
+ * Fetch every declared dependency's content index.
+ *
+ * A wider set than {@link fetchAllCatalogs}: an index is fetched for *every*
+ * dependency, a catalogue only for those declaring `itemCatalog: true`. See
+ * {@link metadataRelationships} for why the two sets differ.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Promise<number>} How many indexes were fetched.
+ */
+export function fetchAllMetadata(config: object): Promise<number>;
 /**
  * Fetch every opted-in dependency. The `deps fetch` command.
  *

package/types/engine/{manifest-emit.d.mts → foundry-entries.d.mts}

@@ -55,7 +55,7 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  * @returns {{entries: Array<object>, notes: number,
  *   skipped: Array<{file: string, reason: string}>}}
  */
-export function collectManifestEntries(contentBase: string, ctx: object): {
+export function collectFoundryEntries(contentBase: string, ctx: object): {
     entries: Array<object>;
     notes: number;
     skipped: Array<{
@@ -74,7 +74,7 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
  *   web: boolean, skipDirectories: readonly string[]}}
  */
-export function manifestContext(config?: object): {
+export function foundryIdentities(config?: object): {
     contentPackage: string;
     foundryPackageId: string;
     packRouter: object;
@@ -82,45 +82,23 @@ export function manifestContext(config?: object): {
     skipDirectories: readonly string[];
 };
 /**
- * Emits this package's link manifest.
+ * The identities an emission runs against, from configuration.
  *
- * One package, because a configuration declares exactly one `contentPackage`
- * and nothing in the surface can express a second. {@link writeManifests} keeps
- * its package→entries map — it is the general writer — but there is no setting
- * here to choose with.
+ * {@link foundryIdentities} plus what only a *manifest* emission needs. The
+ * split is what lets the content index derive the same Foundry addresses from
+ * the same code without also depending on whether the package publishes pages,
+ * which is no part of a UUID (#239).
  *
- * @param {object} [options] - Options.
- * @param {string} [options.contentBase] - The content tree; defaults to the
- *   configured `paths.content`.
- * @param {string} [options.outDir] - Where to write; defaults to the configured
- *   `paths.manifestOut`.
- * @param {object} [options.config] - A resolved configuration; loaded when
- *   omitted.
- * @returns {{written: Array<{package: string, file: string, count: number}>,
- *   entries: number, notes: number,
- *   skipped: Array<{file: string, reason: string}>}}
- * @throws {Error} When the repository does not declare that it publishes a
- *   manifest, when the tree is absent, or when it yields no published note — a
- *   manifest claiming this package publishes nothing is worse than none, since
- *   a consumer reads it as authoritative and turns every link into this package
- *   into a reported typo.
+ * @param {object} [config] - A resolved configuration; loaded when omitted.
+ * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
+ *   web: boolean, skipDirectories: readonly string[]}}
  */
-export function emitLinkManifest({ contentBase, outDir, config }?: {
-    contentBase?: string | undefined;
-    outDir?: string | undefined;
-    config?: object | undefined;
-}): {
-    written: Array<{
-        package: string;
-        file: string;
-        count: number;
-    }>;
-    entries: number;
-    notes: number;
-    skipped: Array<{
-        file: string;
-        reason: string;
-    }>;
+export function entryContext(config?: object): {
+    contentPackage: string;
+    foundryPackageId: string;
+    packRouter: object;
+    web: boolean;
+    skipDirectories: readonly string[];
 };
 /**
  * The reserved anchor name for a journal's **first** page.

package/types/engine/frontmatter-lint.d.mts

@@ -29,9 +29,13 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {readonly string[]} [opts.packs] - The pack names this package
+ *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
+ *   caller like `schemas` and `vocabulary`, and absent it no claim is made
+ *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, systems }: {
+export function lintNote(note: object, { schemas, index, vocabulary, packs, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
@@ -39,6 +43,7 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems }:
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
+    packs?: readonly string[] | undefined;
 }): object[];
 /**
  * Check every note in a built index against its type's schema.
@@ -51,10 +56,12 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems }:
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {readonly string[]} [opts.packs] - The declared pack names; see
+ *   {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, packs, references, systems }: {
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
@@ -62,6 +69,7 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, references
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
+    packs?: readonly string[] | undefined;
 }): {
     findings: object[];
     notes: number;

package/types/engine/frontmatter.d.mts

@@ -9,6 +9,40 @@ export function getFrontmatter(fm: any, key: any, defaultValue?: undefined): any
  * Falls back to top-level `fm[key]` if `sohl` doesn't carry the key.
  */
 export function sohlField(fm: any, key: any, defaultValue?: undefined): any;
+/**
+ * Read a `sohl:` field, seeing the **destination** position as well (#126).
+ *
+ * Five declarations resolve their value by re-reading the note rather than by
+ * taking the one {@link module:engine/system-block.resolveFieldValue} handed
+ * them — `subType`, `charges`, a mystery's `skillAptitudes`, an affiliation's
+ * `relations` and a projectile's impact die — because each validates a *shape
+ * spread over several keys* rather than coercing one scalar.
+ *
+ * That was equivalent while every note authored inside the block, and stopped
+ * being so once a note may author at `sohl.system.<to>` instead: {@link
+ * sohlField} sees `sohl.<key>` and the top level, never inside `sohl.system`.
+ * So those five read as unset and shipped their empty value — a missing
+ * `subType` is a thrown build error, and the other four ship empty in silence,
+ * which is the failure class the passthrough exists to prevent.
+ *
+ * The **destination wins**, matching every other field's resolution order.
+ *
+ * `legacyKey` is for the one pair whose two positions are spelled differently:
+ * a projectile authors `impact.die` and stores `impactBase.die`, so the reader
+ * has to be told both. It is the same split `FieldSpec.name`/`legacyKey` makes
+ * (#305), for the same reason — one name cannot key two positions.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} to - The key at the destination, dotted for a nested one.
+ * @param {any} [defaultValue] - What an unauthored field reads as.
+ * @param {object} [options] - Options.
+ * @param {string} [options.legacyKey] - The key the block still carries, when
+ *   it is not spelled `to`. Defaults to `to`.
+ * @returns {any} The value.
+ */
+export function sohlSystemField(fm: object, to: string, defaultValue?: any, { legacyKey }?: {
+    legacyKey?: string | undefined;
+}): any;
 /**
  * Resolve the `charges` block shared by Mystery and Mystical Ability items.
  *
@@ -97,3 +131,33 @@ export function parseValueDesc(raw: any): {
     label: string;
     maxValue: number;
 }[];
+/**
+ * The compendium folder a note names, and how it named it.
+ *
+ * Two spellings, deliberately not merged into one value: `packFolder:` is a
+ * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
+ * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
+ * the string — both are alphanumeric — so the field it was written in is what
+ * says, and that answer is carried rather than re-derived (#251).
+ *
+ * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
+ * and is an address now (#255). A path encoded the hierarchy *in the value*, so
+ * reparenting a folder made every note naming it wrong — a structural edit
+ * became a corpus-wide rewrite. An address is stable under reparenting, which
+ * is exactly why a note is addressed by `(type, shortcode)` and never by
+ * `file.path`. The path form is **removed rather than deprecated**: it had no
+ * authors to migrate, which is the whole reason the change was cheap enough to
+ * make.
+ *
+ * `packFolder` wins where both are present. Nothing about `folder` changes: a
+ * note that names one is read, resolved and emitted exactly as before, until
+ * #260 retires it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {{value: string|null, isAddress: boolean}} The authored value, and
+ *   whether it is a folder note's address.
+ */
+export function folderField(fm: object | null | undefined): {
+    value: string | null;
+    isAddress: boolean;
+};

package/types/engine/generate.d.mts

@@ -1,3 +1,13 @@
+/**
+ * The compiler class a pack of one document type and one system gets.
+ *
+ * @param {string} docType - The Foundry document type the pack holds.
+ * @param {string|null} [system] - The system the pack declares, if any.
+ * @returns {Function|undefined} The compiler class, or `undefined` for a
+ *   document type nothing here compiles — which {@link generatePack} reports
+ *   rather than defaulting past.
+ */
+export function compilerFor(docType: string, system?: string | null): Function | undefined;
 /**
  * The generated JSON of **every** configured Item pack — what the actors pass
  * reads its predefined items from.
@@ -31,6 +41,34 @@
  *   `(type, shortcode)` instead, naming the being (#49).
  */
 export function itemPackJsonDirs(config?: object, system?: string | null): string[];
+/**
+ * The compiled JSON a bundle may hold copies of, by document type.
+ *
+ * An `Adventure` carries **copies**, not references, so a bundle resolves its
+ * `contents` against compiled output rather than against the content tree — the
+ * same arrangement the actors pass has for `itemsSourceDirs`, generalised to
+ * every document class an Adventure can hold (#259).
+ *
+ * Two kinds of pack are left out, each because it holds nothing a note
+ * addresses. A **prebuilt** pack's JSON is checked in rather than compiled, so
+ * no note is routed into it and nothing in it answers to an address. An
+ * **Adventure** pack holds Adventures, and Foundry's `contentFields` has no
+ * field for one — a bundle of bundles is not a shape the document admits.
+ *
+ * **Scoped to one system when the pack has one**, exactly as
+ * {@link itemPackJsonDirs} is: a pack declaring `system: sohl` reads that
+ * system's packs and the system-neutral ones, so a `(type, shortcode)` that
+ * exists in two systems is read out of the right catalogue. Asking for no
+ * system reads them all, which is every single-system build.
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @param {string|null} [system] - The system whose documents are wanted.
+ *   Omitted or `null`, every pack is read.
+ * @returns {Record<string, string[]>} Each readable pack's JSON directory, by
+ *   the Foundry document type it holds.
+ */
+export function bundleSourceJsonDirs(config?: object, system?: string | null): Record<string, string[]>;
 /**
  * The passes to run, ordered so that each one follows the output it reads.
  *

package/types/engine/helpers.d.mts

@@ -41,10 +41,45 @@ export function parseMarkdownFile(filePath: any): {
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  *   Defaults to the configured list.
  */
-export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
-    skipDirectories?: readonly string[] | undefined;
-}): Generator<{
-    file: string & NonSharedBuffer;
+/**
+ * Refuse a corpus read whose scope its caller did not state.
+ *
+ * The rule of #243 in one place, so every reader of the tree refuses the same
+ * way and says so in the same words. It is shared rather than repeated because
+ * the corpus is no longer read only by {@link walkMarkdownTree}: a pass that
+ * reads the content index instead is making the identical claim about which
+ * files it is looking at, and must be held to the identical requirement — a
+ * scope that quietly defaulted there would reintroduce exactly the second
+ * answer the walk's requirement removed.
+ *
+ * @param {readonly string[]|undefined} skipDirectories - The stated scope.
+ * @param {string} who - The reader, named in the message.
+ * @throws {Error} When no scope was stated.
+ * @returns {void}
+ */
+export function assertStatedScope(skipDirectories: readonly string[] | undefined, who: string): void;
+/**
+ * Refuse a corpus read whose records its caller did not supply.
+ *
+ * The sibling of {@link assertStatedScope}, and required for the same reason
+ * one step further on. These two readers cannot derive the corpus themselves:
+ * deriving it reaches the pack router and the manifest emitter, which reach the
+ * compilers, which load this module — so importing the index here closes a
+ * cycle. They take the records their caller already holds.
+ *
+ * That is not a workaround dressed up as a rule. A compile runs several passes
+ * over one tree, and the whole of #243 is that they must not each answer "which
+ * files are the corpus?" for themselves. Requiring the answer to be handed in
+ * makes the sharing structural rather than remembered.
+ *
+ * @param {readonly object[]|undefined} records - The supplied corpus.
+ * @param {string} who - The reader, named in the message.
+ * @throws {Error} When no corpus was supplied.
+ * @returns {void}
+ */
+export function assertSuppliedCorpus(records: readonly object[] | undefined, who: string): void;
+export function walkMarkdownTree(rootDir: any, { skipDirectories }?: {}): Generator<{
+    file: string;
     absPath: string;
     frontmatter: null;
     body: string;
@@ -52,7 +87,7 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
     bodyLine?: undefined;
     bodyColumn?: undefined;
 } | {
-    file: string & NonSharedBuffer;
+    file: string;
     absPath: string;
     frontmatter: any;
     body: string;
@@ -61,45 +96,74 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
     bodyColumn: number;
 }, void, unknown>;
 /**
- * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
+ * The template priority a note states, for a system that treats an unstated one
+ * as "not a template" rather than as an authoring error (#266).
+ *
+ * Reads exactly the positions {@link resolveTemplatePriority} reads, including
+ * the retiring `archetype` spelling, and refuses the same contradiction — so
+ * the two systems cannot disagree about what a note said. It differs only in
+ * what silence means: SoHL requires the statement, while HM3 keeps the value in
+ * a flag it simply omits, so there is no tri-state for an absent value to
+ * corrupt and nothing to demand.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @param {object} [options] Options.
+ * @param {string} [options.block="sohl"] The system block being compiled.
+ * @returns {number|null}  The priority, or `null` when the note is not a
+ *   template or states nothing.
+ * @throws {Error} When both spellings are present and disagree.
+ */
+export function statedTemplatePriority(fm: object, label: string, { block }?: {
+    block?: string | undefined;
+}): number | null;
+/**
+ * Resolve the required `templatePriority` frontmatter for an Item/Actor entry
  * (the archetype contract, #604). The property is a nullable number that
  * authors must state explicitly:
- *   - a number → the document is an archetype of that priority.
- *   - `null`   → the document is not an archetype.
- *   - absent   → an authoring error (throws), so "not an archetype" is never
+ *   - a number → the document is a template of that priority.
+ *   - `null`   → the document is not a template.
+ *   - absent   → an authoring error (throws), so "not a template" is never
  *                silently assumed.
  *
- * Reads `sohl.archetype`, falling back to a top-level `archetype` key to match
- * {@link sohlField}'s nested-then-top-level resolution.
+ * Reads the positions {@link findTemplatePriority} lists: `data.templatePriority`
+ * first — the specified home — then the system block and the top level, and
+ * finally the retiring `archetype` spelling in the same two places (#266).
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
- * @returns {number|undefined}  The archetype priority, or `undefined` when null.
- * @throws {Error} When `sohl.archetype` is absent or is not a number/null.
+ * @param {object} [options] Options.
+ * @param {string} [options.block="sohl"] The system block being compiled.
+ * @returns {number|undefined}  The template priority, or `undefined` when null.
+ * @throws {Error} When the property is absent, is not a number/null, or both
+ *   spellings are present and disagree.
  */
-export function resolveArchetype(fm: object, label: string): number | undefined;
+export function resolveTemplatePriority(fm: object, label: string, { block }?: {
+    block?: string | undefined;
+}): number | undefined;
 /**
- * The value a document's `system.archetype` carries, from the required
- * `sohl.archetype` frontmatter (#126, sohl#1780).
+ * The value a document's `system.templatePriority` carries, from the required
+ * `templatePriority` frontmatter (#126, sohl#1780, renamed off `archetype` by
+ * #266 / sohl#1836).
  *
  * A **schema field**, so the tri-state is written out in full rather than
- * expressed by a key's presence: a number is an archetype at that priority,
- * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * expressed by a key's presence: a number is a template at that priority, and
+ * `null` is not a template. This is where {@link resolveTemplatePriority}'s
  * `undefined` becomes the field's `null` — an emitted `undefined` would be
  * dropped by `JSON.stringify`, leaving the compiled document with no
- * `archetype` at all and the tri-state readable as two.
+ * `templatePriority` at all and the tri-state readable as two.
  *
- * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
- * and it is falsy, so this returns it unchanged and every caller must ask
+ * **`0` is a template.** It is the priority SoHL's own templates ship at, and
+ * it is falsy, so this returns it unchanged and every caller must ask
  * `typeof v === "number"` rather than testing truthiness.
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
- * @returns {number|null}  The archetype priority, or `null` for a document
- *   that is not an archetype.
- * @throws {Error} When `sohl.archetype` is absent or invalid.
+ * @returns {number|null}  The template priority, or `null` for a document that
+ *   is not a template.
+ * @throws {Error} When the property is absent or invalid.
  */
-export function systemArchetype(fm: object, label: string): number | null;
+export function systemTemplatePriority(fm: object, label: string): number | null;
 /**
  * Generates a compendium-source filename: `Name_id.json` with non-
  * alphanumeric runs replaced by underscores.
@@ -280,7 +344,7 @@ export function defaultStats(): object;
  *   this repository's own.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase: string, router?: object): {
+export function buildContentLinkIndex(contentBase: string, router?: object, { skipDirectories, config, records, problems }?: {}): {
     byShortcode: Map<any, any>;
     types: Set<any>;
 };
@@ -320,7 +384,7 @@ export function convertNoteWikilinks(body: string, { type, id, pack, docPack, in
  * @returns {Array<{fm: object, path: string, tld: string, folder: string,
  *   absPath: string}>}
  */
-export function collectContentDocs(contentBase: string): Array<{
+export function collectContentDocs(contentBase: string, { skipDirectories, config, records, problems }?: {}): Array<{
     fm: object;
     path: string;
     tld: string;
@@ -352,7 +416,7 @@ export function collectContentDocs(contentBase: string): Array<{
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
  */
-export function expandNoteTables(body: string, { docs, name, fm, bodyLine }: {
+export function expandNoteTables(body: string, { docs, name, fm, bodyLine, sqlTables }: {
     docs: Array<object>;
     name: string;
     fm?: object | undefined;
@@ -384,7 +448,7 @@ export function loadFolders(foldersFile: any): any[];
  * Returns { resolver, folders } where folders is the validated list.
  */
 export function buildFolderResolver(folders: any): {
-    resolver: (folderId: any) => string | null;
+    resolver: (value: string | null | undefined) => string | null;
     folders: any;
 };
 /**
@@ -402,4 +466,4 @@ export function writeFolderDocs(folders: any, stats: any, destDir: any, document
 export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";
-export { getFrontmatter, sohlField, resolveCharges, resolveSkillAptitudes, resolveRelation, requireSubType, parseValueDesc } from "./frontmatter.mjs";
+export { getFrontmatter, sohlField, folderField, resolveCharges, resolveSkillAptitudes, resolveRelation, requireSubType, parseValueDesc } from "./frontmatter.mjs";