@heroiclands/package-build 8.1.0 → 10.0.0

package/types/engine/content-format.d.mts

@@ -0,0 +1,101 @@
+/**
+ * Parse the specification's tables.
+ *
+ * Pure: text in, model out, so a test states a miniature document rather than
+ * asserting against the real one and its 1,100 lines of prose.
+ *
+ * @param {string} text - The document's contents.
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Path recorded on the result, for diagnostics.
+ * @returns {ContentFormat} What the document declares.
+ */
+export function parseContentFormat(text: string, { file }?: {
+    file?: string | undefined;
+}): ContentFormat;
+/**
+ * Read and parse the specification from disk.
+ *
+ * @param {string} [file] - The document. Defaults to {@link CONTENT_FORMAT_PATH}.
+ * @returns {ContentFormat} What it declares.
+ */
+export function loadContentFormat(file?: string): ContentFormat;
+/**
+ * The specification this package ships.
+ *
+ * Resolved from this module rather than from the working directory: a consumer
+ * runs `content-build content-format` inside its own repository, and the
+ * document it should be checked against is the one that came with the toolchain
+ * version it resolved — the same rule `--version` follows.
+ *
+ * @type {string}
+ */
+export const CONTENT_FORMAT_PATH: string;
+/**
+ * What one note type's section declares.
+ */
+export type TypeSpec = {
+    /**
+     * - The note type, as the `### type:` heading spells it.
+     */
+    name: string;
+    /**
+     * - 1-based line of that heading.
+     */
+    line: number;
+    /**
+     * - The head segment of each declared `data`
+     * property — what a note actually writes. `appearance.eye_color` is authored
+     * as `appearance`, so that is the key recorded.
+     */
+    dataKeys: Set<string>;
+    /**
+     * - The declared paths, whole.
+     */
+    dataPaths: Set<string>;
+};
+/**
+ * One `system.*` target the specification names for one note type.
+ */
+export type MappingClaim = {
+    /**
+     * - The type whose section makes the claim.
+     */
+    noteType: string;
+    /**
+     * - The system column it sits under, from the header.
+     */
+    system: string;
+    /**
+     * - The shared source cell, stripped of its backticks.
+     */
+    source: string;
+    /**
+     * - The dotted path, `system.` prefix included.
+     */
+    target: string;
+    /**
+     * - 1-based line of the row.
+     */
+    line: number;
+    /**
+     * - 1-based column of the cell's first character.
+     */
+    column: number;
+};
+/**
+ * The specification, as data.
+ */
+export type ContentFormat = {
+    /**
+     * - Where it was read from, for diagnostics.
+     */
+    file: string;
+    /**
+     * - Note type → what its section declares.
+     */
+    types: Map<string, TypeSpec>;
+    /**
+     * - Every `system.*` target, in document order.
+     */
+    claims: MappingClaim[];
+};

package/types/engine/content-links.d.mts

@@ -86,15 +86,30 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
 /**
  * Every link in a tree that lands nowhere.
  *
+ * **The two failure modes are separate findings, because they are separate
+ * problems** (#131). A piped target the author declared to be an address, and
+ * which resolves nowhere, is a typo: every package it could name is either
+ * built here or vendored, so there is no third possibility. An unpiped target
+ * naming no note of the source's type may be exactly that typo — or a
+ * worldbuilding placeholder, which is a long-standing convention in the
+ * setting trees. So the first is an error and the second a warning, and the
+ * caller can tell them apart without parsing a message.
+ *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
+ *   deadAliases: object[], aliasCollisions: object[],
  *   frontmatterLinks: object[], homepageLinks: object[],
  *   usedManifest: Set<string>}} The findings, and which addresses a foreign
- *   manifest answered.
+ *   manifest answered. Each `deadAddresses` entry carries a `reason`:
+ *   `"not-an-address"` when the target does not parse as one at all,
+ *   `"unknown-type"` when it is qualified but names no known type, and
+ *   `"unresolved"` when it parses and nothing answers it.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];
     deadAddresses: object[];
+    deadAliases: object[];
+    aliasCollisions: object[];
     frontmatterLinks: object[];
     homepageLinks: object[];
     usedManifest: Set<string>;

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

@@ -39,6 +39,12 @@ export function lintContentTree(contentBase: string, { skipDirectories, contentP
 /**
  * The shape every `shortcode` must match: ASCII letters and digits only.
  *
+ * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
+ * is the last segment of a canonical address, and the rule it is held to is the
+ * rule *every* segment is held to — so the two are one constant rather than two
+ * free to drift apart (#59). The name survives because this is where the rule
+ * is applied to a note.
+ *
  * Case is deliberately **not** constrained: hundreds of authored shortcodes are
  * mixed-case and collide with nothing, so tightening that is a separate
  * decision from this one.

package/types/engine/diagnostics.d.mts

@@ -210,3 +210,32 @@ export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string |
  * @returns {Array<string|number>} Its segments, sequence indices as numbers.
  */
 export function yamlKeyPath(field: string): Array<string | number>;
+/**
+ * Where a key sits **inside a note's frontmatter fence**, addressed by path.
+ *
+ * {@link positionInFrontmatter} searches the fence for a key by name, which is
+ * the right tool while a note's vocabulary is flat: a key appears once and the
+ * first line matching it is the one. It stops being the right tool the moment
+ * the same name is legal in two regions — `data.weight` and a top-level
+ * `weight` are different keys, and a search finds whichever comes first.
+ *
+ * So this is the located form for the closed regions (#128). It reuses
+ * {@link positionOfYamlPath} rather than repeating its parse, which is what
+ * keeps a finding about `data.weight` pointing at `data.weight`.
+ *
+ * @param {string} raw - The note's full contents, frontmatter included.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node, from the
+ *   top of the frontmatter.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when there is no fence or the path resolves to nothing — dropped rather
+ *   than guessed.
+ */
+export function positionOfFrontmatterPath(raw: string, keyPath: ReadonlyArray<string | number>, { key }?: {
+    key?: boolean | undefined;
+}): {
+    line?: number;
+    column?: number;
+};

package/types/engine/document-subtypes.d.mts

@@ -0,0 +1,233 @@
+/**
+ * One row of a system's map: what a note of this type becomes.
+ *
+ * @typedef {object} DocumentSubtypeRow
+ * @property {string} document - The Foundry document class — `"Item"`,
+ *   `"Actor"`, and so on. It must agree with what the engine's own
+ *   {@link packForType} routes the type to; they are two statements about one
+ *   fact, and a test holds them together.
+ * @property {string} [subType] - The document subtype, for a one-to-one row.
+ *   Mutually exclusive with `discriminator`.
+ * @property {string} [discriminator] - For a one-to-many row: the key the note
+ *   supplies in this system's own frontmatter block to say which subtype it
+ *   is.
+ * @property {readonly string[]} [subTypes] - The subtypes `discriminator` may
+ *   name. Required with it, and never empty — a row permitting nothing is a
+ *   row that can never resolve.
+ */
+/**
+ * A system's whole declaration: which system it belongs to, which frontmatter
+ * block its notes write, and every note type it maps.
+ *
+ * @typedef {object} DocumentSubtypeMap
+ * @property {string} system - The system this map belongs to (`"sohl"`).
+ * @property {string} block - The note frontmatter block this system's notes
+ *   write, and the only place a discriminator is read from. Defaults to
+ *   `system`.
+ * @property {Readonly<Record<string, DocumentSubtypeRow>>} types - Note type →
+ *   row.
+ */
+/**
+ * Declare one system's note-type → document-subtype map.
+ *
+ * Every malformed row is refused **here**, at module evaluation, rather than
+ * when some note happens to reach it: a map is a small piece of authored data
+ * loaded once per build, so a mistake in it should stop the build immediately
+ * and name the row, not surface as a missing document a thousand notes later.
+ *
+ * @param {object} declaration - The system's declaration.
+ * @param {string} declaration.system - The system this map belongs to.
+ * @param {string} [declaration.block] - The frontmatter block its notes write.
+ *   Defaults to `system`.
+ * @param {Readonly<Record<string, DocumentSubtypeRow>>} declaration.types -
+ *   Note type → row.
+ * @returns {DocumentSubtypeMap} The frozen map, rows and all.
+ * @throws {Error} When the declaration names no system, or any row is neither
+ *   of the two permitted shapes.
+ */
+export function defineDocumentSubtypes({ system, block, types }?: {
+    system: string;
+    block?: string | undefined;
+    types: Readonly<Record<string, DocumentSubtypeRow>>;
+}): DocumentSubtypeMap;
+/**
+ * The row a system declares for a note type, or nothing.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @returns {Readonly<DocumentSubtypeRow>|undefined} The row, or `undefined`
+ *   where this system maps the type at all.
+ */
+export function subtypeRow(map: DocumentSubtypeMap, noteType: string | undefined): Readonly<DocumentSubtypeRow> | undefined;
+/**
+ * Whether a system maps a note type — optionally, onto one document class.
+ *
+ * This is what a pass asks to decide whether it claims a note, which is the
+ * whole of the "no mapping, no document" property: a type the map does not
+ * carry is skipped exactly as quietly as the thousands of notes that belong to
+ * another pass.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @param {string} [document] - Restrict the question to one document class.
+ * @returns {boolean} True when the map carries a matching row.
+ */
+export function mapsNoteType(map: DocumentSubtypeMap, noteType: string | undefined, document?: string): boolean;
+/**
+ * Every note type a system maps onto one document class, sorted.
+ *
+ * A pass reports what it skipped by naming what it would have claimed, and
+ * that list is the map's — never a constant restating it.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string} document - The Foundry document class.
+ * @returns {string[]} The note types, in sorted order.
+ */
+export function noteTypesFor(map: DocumentSubtypeMap, document: string): string[];
+/**
+ * The document subtype a note compiles into for one system.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @param {object} fm - The note's frontmatter, read only for a one-to-many
+ *   row's discriminator.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, appended to the message.
+ *   Omit it where the caller emits through a diagnostic, which already puts
+ *   the locator at the start of the line.
+ * @param {string} [options.absPath] - The note's file on disk, read only on
+ *   the failing path to locate the offending line. The position rides on the
+ *   thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {string|undefined} The subtype, or `undefined` where this system
+ *   maps nothing for the type — which means no document, not an error.
+ * @throws {Error} When a one-to-many row's discriminator is absent, blank, or
+ *   names a value the row does not permit.
+ */
+export function documentSubtype(map: DocumentSubtypeMap, noteType: string | undefined, fm: object, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): string | undefined;
+/**
+ * The answer {@link referencedSubtype} gives: a subtype, or why there is none.
+ *
+ * Exactly one of the two fields is set. A `problem` is a sentence a caller
+ * prefixes with its own context and emits as a finding — it never throws,
+ * because the caller resolving a reference is walking a list and has to report
+ * this one and carry on.
+ *
+ * @typedef {object} ReferencedSubtype
+ * @property {string} [subType] - The document subtype the reference addresses.
+ * @property {string} [problem] - Why the reference names no document subtype.
+ */
+/**
+ * The document subtype a `(type, shortcode)` **reference** addresses (#140).
+ *
+ * A being's frontmatter names each embedded item by the *note's* type — the
+ * vocabulary an author writes — while the predefined items it resolves against
+ * are compiled documents, which carry only the *subtype*. One side has to
+ * translate, and it is this one: the map is a function from note type to
+ * subtype by construction, whereas the reverse is not — two note types may
+ * compile into one subtype, and a compiled document records nothing about the
+ * note that produced it. So the addresses stay keyed on the **document
+ * subtype**, which is the only vocabulary both a local pack and an extracted
+ * dependency catalogue actually carry, and a reference is translated forward
+ * here before it is looked up.
+ *
+ * Four answers, and only the first resolves:
+ *
+ * - _A one-to-one row_ → the subtype it declares. `armor` addresses an
+ *   `armorgear`.
+ * - _No row at all_ → the note type itself. A consumer declares its own item
+ *   types in its `itemBuilders` table rather than in this system's map, and the
+ *   Item pass stamps such a document with the note type; the reference has to
+ *   agree, or a consumer's own items would stop resolving the moment a map
+ *   existed.
+ * - _A row for another document class_ → a problem. A being is not an item,
+ *   however the address is spelled.
+ * - _A one-to-many row_ → a problem naming the candidates. The note that owns
+ *   such a row resolves it from its own frontmatter block; a reference has no
+ *   block, so nothing here can choose, and choosing anyway would be right about
+ *   half the time. No system declares a one-to-many **Item** row today, so this
+ *   is a guard rather than a behaviour — but it is a loud one, which is the
+ *   whole point of the issue.
+ *
+ * A **retired** spelling is refused by name before any of that. Without it a
+ * reference left behind by a rename would take the unmapped fallback and
+ * address a document of the old name — resolving silently, which is precisely
+ * what a retirement exists to stop (#78).
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The type the reference names.
+ * @param {string} document - The Foundry document class the reference must
+ *   address — `"Item"` for a being's embedded items.
+ * @returns {ReferencedSubtype} The subtype, or why there is none.
+ */
+export function referencedSubtype(map: DocumentSubtypeMap, noteType: string | undefined, document: string): ReferencedSubtype;
+/**
+ * One row of a system's map: what a note of this type becomes.
+ */
+export type DocumentSubtypeRow = {
+    /**
+     * - The Foundry document class — `"Item"`,
+     * `"Actor"`, and so on. It must agree with what the engine's own
+     * {@link packForType} routes the type to; they are two statements about one
+     * fact, and a test holds them together.
+     */
+    document: string;
+    /**
+     * - The document subtype, for a one-to-one row.
+     * Mutually exclusive with `discriminator`.
+     */
+    subType?: string | undefined;
+    /**
+     * - For a one-to-many row: the key the note
+     * supplies in this system's own frontmatter block to say which subtype it
+     * is.
+     */
+    discriminator?: string | undefined;
+    /**
+     * - The subtypes `discriminator` may
+     * name. Required with it, and never empty — a row permitting nothing is a
+     * row that can never resolve.
+     */
+    subTypes?: readonly string[] | undefined;
+};
+/**
+ * A system's whole declaration: which system it belongs to, which frontmatter
+ * block its notes write, and every note type it maps.
+ */
+export type DocumentSubtypeMap = {
+    /**
+     * - The system this map belongs to (`"sohl"`).
+     */
+    system: string;
+    /**
+     * - The note frontmatter block this system's notes
+     * write, and the only place a discriminator is read from. Defaults to
+     * `system`.
+     */
+    block: string;
+    /**
+     * - Note type →
+     * row.
+     */
+    types: Readonly<Record<string, DocumentSubtypeRow>>;
+};
+/**
+ * The answer {@link referencedSubtype} gives: a subtype, or why there is none.
+ *
+ * Exactly one of the two fields is set. A `problem` is a sentence a caller
+ * prefixes with its own context and emits as a finding — it never throws,
+ * because the caller resolving a reference is walking a list and has to report
+ * this one and carry on.
+ */
+export type ReferencedSubtype = {
+    /**
+     * - The document subtype the reference addresses.
+     */
+    subType?: string | undefined;
+    /**
+     * - Why the reference names no document subtype.
+     */
+    problem?: string | undefined;
+};

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

@@ -1,31 +1,37 @@
-/**
- * Write `value` at a dotted path, creating the intermediate objects.
- *
- * Insertion order is the emitted JSON's key order, so a declaration's order is
- * the compiled document's order — which is what lets a field list replace a
- * hand-written object literal without changing a single byte of output.
- *
- * @param {object} target - The object to write into (mutated).
- * @param {string} dotted - Path, e.g. `"locations.flexible"`.
- * @param {any} value - The value to set.
- * @returns {object} `target`, for chaining.
- */
-export function setPath(target: object, dotted: string, value: any): object;
 /**
  * Read one declared field out of a note's frontmatter.
  *
+ * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
+ * first, then the legacy in-block key, then the declared shared source, then
+ * the default (#58). The **coercion** is applied here, once, wherever the value
+ * came from: a field's `read` is a statement about the field, not about where
+ * an author happened to write it, so `weight: "7"` reads as `7` at every one of
+ * those positions.
+ *
  * @param {FieldSpec} field - The declaration.
  * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options.
+ * @param {string} [options.block="sohl"] - Which system's block to resolve
+ *   against. The default is the one block every existing tree authors; a
+ *   second system passes its own.
  * @returns {any} The value to emit.
  */
-export function readField(field: FieldSpec, fm: object): any;
+export function readField(field: FieldSpec, fm: object, { block }?: {
+    block?: string | undefined;
+}): any;
 /**
  * Turn a field declaration into the builder it declares.
  *
  * @param {readonly FieldSpec[]} fields - The declaration, in emission order.
+ * @param {object} [options] - Options.
+ * @param {string} [options.block="sohl"] - Which system's block the builder
+ *   reads. One declaration compiles against any block, which is what lets two
+ *   systems declare the same shared source and different destinations.
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[]): (fm: object) => object;
+export function buildFromFields(fields: readonly FieldSpec[], { block }?: {
+    block?: string | undefined;
+}): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
  *
@@ -38,12 +44,25 @@ export function buildFromFields(fields: readonly FieldSpec[]): (fm: object) => o
  * @returns {FieldSpec[]} Only the fields with a frontmatter `name`.
  */
 export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
+export { setPath };
 /**
  * @typedef {object} FieldSpec
- * @property {string} to - Dotted path in the emitted `system` block.
- * @property {string} [name] - Frontmatter key under `sohl:`, dotted for a
- *   nested one (`impact.die`). Absent means the value is not authored — see
- *   `value`.
+ * @property {string} to - Dotted path in the emitted `system` block — and,
+ *   since #58, the path a note authors the field at directly:
+ *   `<system>.system.<to>`.
+ * @property {string} [name] - The **shared, top-level property this field draws
+ *   from** when the note authors no value at `<system>.system.<to>`. Dotted for
+ *   a path into a shared container (`data.portrait`), which is now the ordinary
+ *   case: `data:` (#128) puts every type-specific fact under one.
+ *
+ *   It used to mean "frontmatter key under `sohl:`", and that reading is the
+ *   degenerate case where the shared source and the system destination happen
+ *   to share a name. They constantly do not — one shared `data.portrait` feeds
+ *   `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
+ *   declared rather than matched by spelling (#58). The in-block position is
+ *   still read, second, until #126 moves the corpus off it.
+ *
+ *   Absent means the value is not authored at all — see `value`.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -51,6 +70,15 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  * @property {any} [default] - Emitted when the note does not carry the field.
  * @property {boolean} [required] - Whether a note must carry it. A required
  *   field's `read` is expected to throw when it is missing.
+ * @property {boolean} [shared] - Whether the field is authored at the note's
+ *   **top level** rather than inside a system block, because what it states is
+ *   not system-specific — a map's background art is the same art whichever
+ *   system reads the note. It changes no reader: the top level is already the
+ *   third step of {@link module:engine/system-block.resolveFieldValue}'s order,
+ *   so the value resolves whichever region carries it. What it tells the
+ *   author-facing surfaces is which of the two is the field's *home*, so a
+ *   message about it names `img` rather than sending an author to `sohl.img`
+ *   (#142).
  * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
  *   shape, for the frontmatter linter (#19). Distinct from `shape`, which is
  *   prose for a reader, and from `read`, which is what the compiler does: a
@@ -121,13 +149,25 @@ export const BLANK_IS_DEFAULT: Readonly<{
 }>;
 export type FieldSpec = {
     /**
-     * - Dotted path in the emitted `system` block.
+     * - Dotted path in the emitted `system` block — and,
+     * since #58, the path a note authors the field at directly:
+     * `<system>.system.<to>`.
      */
     to: string;
     /**
-     * - Frontmatter key under `sohl:`, dotted for a
-     * nested one (`impact.die`). Absent means the value is not authored — see
-     * `value`.
+     * - The **shared, top-level property this field draws
+     * from** when the note authors no value at `<system>.system.<to>`. Dotted for
+     * a path into a shared container (`data.portrait`), which is now the ordinary
+     * case: `data:` (#128) puts every type-specific fact under one.
+     *
+     * It used to mean "frontmatter key under `sohl:`", and that reading is the
+     * degenerate case where the shared source and the system destination happen
+     * to share a name. They constantly do not — one shared `data.portrait` feeds
+     * `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
+     * declared rather than matched by spelling (#58). The in-block position is
+     * still read, second, until #126 moves the corpus off it.
+     *
+     * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
     /**
@@ -152,6 +192,18 @@ export type FieldSpec = {
      * field's `read` is expected to throw when it is missing.
      */
     required?: boolean | undefined;
+    /**
+     * - Whether the field is authored at the note's
+     * **top level** rather than inside a system block, because what it states is
+     * not system-specific — a map's background art is the same art whichever
+     * system reads the note. It changes no reader: the top level is already the
+     * third step of {@link module :engine/system-block.resolveFieldValue}'s order,
+     * so the value resolves whichever region carries it. What it tells the
+     * author-facing surfaces is which of the two is the field's *home*, so a
+     * message about it names `img` rather than sending an author to `sohl.img`
+     * (#142).
+     */
+    shared?: boolean | undefined;
     /**
      * - The value's
      * shape, for the frontmatter linter (#19). Distinct from `shape`, which is
@@ -179,3 +231,4 @@ export type FieldSpec = {
      */
     describe: string;
 };
+import { setPath } from "./system-block.mjs";

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

@@ -20,11 +20,25 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
  * @param {object} [opts.index] - The link index, for the reference check. Its
  *   absence skips that check rather than reporting every reference as dead.
+ * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
+ *   it declares, as `engine/note-vocabulary.mjs` states them (#128). Supplied
+ *   by the caller for the same reason `schemas` is: this module validates a
+ *   note against whatever its type declares and knows no type names of its
+ *   own. Its absence skips the `data:` and `subType` checks rather than
+ *   reporting every key as unknown.
+ * @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}.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index }: {
+export function lintNote(note: object, { schemas, index, vocabulary, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
+    vocabulary?: Record<string, object> | undefined;
+    systems?: Readonly<Record<string, {
+        known?: readonly string[];
+        fieldVocabulary?: boolean;
+    }>> | undefined;
 }): object[];
 /**
  * Check every note in a built index against its type's schema.
@@ -32,13 +46,22 @@ export function lintNote(note: object, { schemas, index }: {
  * @param {object} index - From `buildLinkIndex`.
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
+ *   it declares (#128); see {@link lintNote}.
  * @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}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, references }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems }: {
     schemas: Record<string, readonly object[]>;
+    vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
+    systems?: Readonly<Record<string, {
+        known?: readonly string[];
+        fieldVocabulary?: boolean;
+    }>> | undefined;
 }): {
     findings: object[];
     notes: number;
@@ -72,3 +95,25 @@ export function lintFrontmatter(index: object, { schemas, references }: {
  * @type {ReadonlySet<string>}
  */
 export const UNIVERSAL_KEYS: ReadonlySet<string>;
+/**
+ * The system blocks a build checks, and what each accepts beyond the shared
+ * vocabulary.
+ *
+ * One entry, because one system is what every existing tree declares — and the
+ * default is a *declaration*, not a hard-coded assumption: a build that ships
+ * content for two systems passes both, and each block is then checked against
+ * its own vocabulary rather than against the other's (#58). A block nothing
+ * declares is not checked, because nothing can say what it may carry, and
+ * inventing a rule for it would report a correct tree red.
+ *
+ * `fieldVocabulary` says the note type's own declared field names are keys of
+ * this block. True for `sohl` and untrue in general: those names come from the
+ * `itemBuilders` registry that this system declares, and a second system's
+ * notes write a second system's fields.
+ *
+ * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ */
+export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, {
+    known?: readonly string[];
+    fieldVocabulary?: boolean;
+}>>;