@heroiclands/package-build 17.1.0 → 18.0.0

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

@@ -1,36 +1,20 @@
-/**
- * The `{#slug}` anchors a note's body declares, with where each one sits.
- *
- * Only headings carrying an explicit anchor are collected. A bare `#` heading
- * also starts a journal page, but it declares no slug, so nothing can address
- * it with `#…` — listing it would offer a link that cannot be written.
- *
- * @param {string} body - The note's markdown body, frontmatter already removed.
- * @param {number} [bodyLine] - The 1-based file line the body starts on, from
- *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
- *   so an editor can jump straight to one; passing nothing numbers from the body.
- * @returns {Array<{slug: string, name: string, level: number, line: number}>}
- *   In document order.
- */
-export function collectAnchors(body: string, bodyLine?: number): Array<{
-    slug: string;
-    name: string;
-    level: number;
-    line: number;
-}>;
 /**
  * The address a wikilink writes to reach a note, or `null` when it has none.
  *
  * A wikilink target is an address: `being-aurochs` locally, or
  * `sohl-being-aurochs` from another package (`readQualifier` also accepts
- * `being/aurochs`, the same two fields with a different separator). Both forms
- * are already derivable from `type` and `shortcode`, which every record
- * carries — so this field adds no information. What it adds is the *rule*:
- * the lowercasing and the hyphen join live in one place, and a consumer that
- * reimplements them slightly differently gets a lookup that matches nothing and
- * says nothing about why. That is a real failure, not a hypothetical one — it
- * is precisely how a resolver keyed on a bare `type/shortcode` silently misses
- * every canonical `pkg-type-shortcode` entry.
+ * `being/aurochs`, the same two fields with a different separator). Both are
+ * *partial* addresses — the canonical one this field records is
+ * `sohl-sohl-being-aurochs`, and a target that omits the system is matched
+ * with that segment wildcarded. Every form is already derivable from `type` and
+ * `shortcode`, which every record carries, plus the system the type compiles
+ * into — so this field adds no information. What it adds is the *rule*: the
+ * lowercasing, the hyphen join and the system lookup live in one place, and a
+ * consumer that reimplements them slightly differently gets a lookup that
+ * matches nothing and says nothing about why. That is a real failure, not a
+ * hypothetical one — it is precisely how a resolver keyed on a bare
+ * `type/shortcode` silently misses every canonical
+ * `pkg-system-type-shortcode` entry.
  *
  * Derived by the same functions the link manifest and the site build use, so an
  * index cannot disagree with either about where a note lives.
@@ -38,8 +22,8 @@ export function collectAnchors(body: string, bodyLine?: number): Array<{
  * @param {Record<string, any>} frontmatter - The note's parsed frontmatter.
  * @param {string} contentPackage - The package the tree compiles as.
  * @returns {{slug: string, canonical: string}|null} `slug` is what goes inside
- *   `[[…]]` within this package; `canonical` is the package-qualified key the
- *   manifest files the note under. `null` for a note with no type or no
+ *   `[[…]]` within this package; `canonical` is the fully qualified key the
+ *   manifest files the note under, carrying the package and the system as well. `null` for a note with no type or no
  *   shortcode, which has no address at all and is stated as such rather than
  *   left for every reader to rediscover.
  */
@@ -107,40 +91,21 @@ export function asciiName(name: unknown): string | null;
  *   a consumer iterating it should not have to check first.
  */
 export function asciiAliases(aliases: unknown): Array<string>;
-/**
- * Build one index record from a note's frontmatter and its place in the tree.
- *
- * @param {object} options - Options.
- * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
- * @param {string} options.relPath - Its path below the content root, POSIX-separated.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
- * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
- * @throws {Error} When the note carries a key this module derives, which would
- *   otherwise be overwritten without a word.
- */
-export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine }: {
-    frontmatter: Record<string, any>;
-    relPath: string;
-    contentPackage: string;
-    body?: string | undefined;
-    bodyLine?: number | undefined;
+export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, }: {
+    frontmatter: any;
+    relPath: any;
+    absPath: any;
+    contentPackage: any;
+    body: any;
+    bodyLine: any;
+    manifest: any;
 }): Record<string, any>;
-/**
- * Read a content tree into index records, in the order they will be written.
- *
- * @param {string} contentBase - The content tree to walk.
- * @param {object} options - Options.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
- * @returns {Array<Record<string, any>>} The records, in a total order that does
- *   not depend on directory-read order.
- */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories }: {
-    contentPackage: string;
-    skipDirectories?: string[] | undefined;
-}): Array<Record<string, any>>;
+export function collectContentIndex(contentBase: any, { contentPackage, skipDirectories, manifest, problems }: {
+    contentPackage: any;
+    skipDirectories: any;
+    manifest: any;
+    problems: any;
+}): Record<string, any>[];
 /**
  * Serialize records as JSON Lines.
  *
@@ -150,6 +115,36 @@ export function collectContentIndex(contentBase: string, { contentPackage, skipD
  *   the file is exactly the lines it holds.
  */
 export function serializeContentIndex(records: Array<Record<string, any>>): string;
+/**
+ * The index records for a content tree, without writing anything.
+ *
+ * The half of {@link emitContentIndex} that derives rather than emits, so a
+ * pass that needs the corpus in memory — a SQL content table, the link check,
+ * and in time every reader #243 converts — builds it the same way the artifact
+ * is built, rather than by walking and parsing again with its own idea of the
+ * scope.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.contentBase] - The tree, defaulting to the configured one.
+ * @param {object} [opts.config] - Resolved configuration, defaulting to ambient.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, for a
+ *   caller that resolved one of its own; defaults to the resolved
+ *   configuration's. Stated separately from `config` because a caller that was
+ *   *handed* a scope must be able to pass it on rather than have it silently
+ *   replaced by the one its configuration happens to carry (#243).
+ * @param {object[]} [opts.problems] - Supplied by a **reader**: a note that
+ *   cannot be recorded is pushed here as a diagnostic and skipped, instead of
+ *   aborting the derivation. Omitted, the note throws — which is the contract
+ *   the emitter needs, since an index missing a note asserts that it does not
+ *   exist.
+ * @returns {object[]} One record per note, plus one per documentation entry.
+ */
+export function indexRecordsFor({ contentBase, config, skipDirectories, problems }?: {
+    contentBase?: string | undefined;
+    config?: object | undefined;
+    skipDirectories?: readonly string[] | undefined;
+    problems?: object[] | undefined;
+}): object[];
 /**
  * Emit this package's content index.
  *
@@ -175,20 +170,9 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
     notes: number;
     bytes: number;
 };
-/**
- * The keys this module 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 (package-build#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>;
+import { collectAnchors } from "./anchors.mjs";
+import { authoredFrontmatter } from "./index-records.mjs";
+import { DERIVED_KEYS } from "./index-records.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { noteFile } from "./index-records.mjs";
+export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isNoteRecord, noteFile };

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

@@ -1,12 +1,43 @@
 /**
  * Every `{#anchor}` a note declares on a heading.
  *
+ * **Read from the content index's reader, not a second one.** This module kept
+ * its own until #243, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
+ * {@link module:engine/content-index.collectAnchors} matches `{#([^}]+)}`, so
+ * an anchor with a capital in it — `{#CalendarFormat}` — existed for the index
+ * and for the compiler and did not exist for the link checker. Nothing links to
+ * one today, so the disagreement was latent; the first link to one would have
+ * been reported dead against a heading plainly present in the file.
+ *
+ * The specification puts no charset on the id: "`#id` represents an id anchor
+ * named `id`". The narrower pattern was this module's invention, which is the
+ * argument for there being one reader rather than a well-chosen one.
+ *
  * @param {string} body - The note's markdown body.
  * @returns {Set<string>} The declared anchor slugs.
  */
 export function anchorsOf(body: string): Set<string>;
 /**
- * Load a content tree and build the index a link resolves against.
+ * Read a content tree into the index a link resolves against.
+ *
+ * **The corpus comes from the content index, not from a walk of this module's
+ * own** (#243). Every pass used to answer "which files are the content?" for
+ * itself and throw the answer away; this one now reads
+ * {@link module:engine/content-index.indexRecordsFor}, which is the same
+ * derivation the published artifact and the compilers are driven from. So a
+ * note the index records is a note the link check sees, and the addresses and
+ * anchors it resolves against are the ones every other pass will emit — rather
+ * than a second derivation that agrees with them only by inspection. That was
+ * not hypothetical: this module carried its own anchor reader until the anchor
+ * half of #243, and the two disagreed about which anchors existed.
+ *
+ * **The file is opened for its bytes and nothing else.** The index deliberately
+ * carries no note *body*, and a link lives in the body — so each note is read
+ * once, here, for the prose. Everything *about* the note — its frontmatter, its
+ * addresses, its anchors — is already in the record, and none of it is derived
+ * a second time. That is one read per note rather than the two this module did
+ * before, since the walk read the file and it then read it again for the raw
+ * text.
  *
  * The index mirrors what both builds construct, including the two addresses a
  * doc-carrying note answers to: `type/shortcode` for the document, and
@@ -17,14 +48,28 @@ export function anchorsOf(body: string): Set<string>;
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
- * @param {string} [opts.manifestDir] - Where vendored foreign manifests live.
- *   Omitted, no cross-package address resolves.
- * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @param {object} [opts.config] - The resolved build configuration, whose
+ *   fetched dependency indexes foreign addresses resolve through (#239), and
+ *   whose `contentPackage` every local address is built from. Omitted, the
+ *   ambient configuration is resolved and no cross-package address resolves.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, passed
+ *   on to the index rather than defaulted away.
+ * @param {Map<string, object[]>} [opts.sqlTables] - Prepared `sql` results, by
+ *   note path.
+ * @param {object[]} [opts.records] - Index records the caller already derived,
+ *   so a command that also needs them — every one of them does, to answer its
+ *   `sql` tables — enumerates the corpus once rather than twice.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, as diagnostics, instead of letting one of them abort the check
+ *   before it has reported anything else.
  * @returns {object} The notes, the index, and the resolvers built over it.
  */
-export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectories }?: {
-    manifestDir?: string | undefined;
+export function buildLinkIndex(contentBase: string, { config, skipDirectories, sqlTables, records, problems }?: {
+    config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
+    sqlTables?: Map<string, object[]> | undefined;
+    records?: object[] | undefined;
+    problems?: object[] | undefined;
 }): object;
 /**
  * Every defect in the addresses a package homepage carries.
@@ -46,7 +91,7 @@ export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectori
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   vendored manifest names. Every one of them has a better form to write, which
+ *   a fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
  *   another package's landing (#87).
  *

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

@@ -18,13 +18,22 @@ export function isValidShortcode(value: unknown): boolean;
  *   ignores. Defaults to the configured list.
  * @param {string} [opts.contentPackage] - The package this tree builds, for the
  *   homepage rule. Dropped from that finding when unknown rather than guessed.
+ * @param {object} [opts.config] - The resolved build configuration, which the
+ *   corpus is derived against.
+ * @param {readonly object[]} [opts.records] - Index records the caller already
+ *   derived, so a command reads one corpus (#243).
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, instead of letting one of them silence the lint.
  * @returns {{findings: Array<{file: string, line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>, notes: number,
  *   keys: number}} The findings, and what was inspected to produce them.
  */
-export function lintContentTree(contentBase: string, { skipDirectories, contentPackage }?: {
+export function lintContentTree(contentBase: string, { skipDirectories, contentPackage, config, records, problems }?: {
     skipDirectories?: readonly string[] | undefined;
     contentPackage?: string | undefined;
+    config?: object | undefined;
+    records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -2,7 +2,8 @@
  * The **content** package: the distribution unit this repository's notes belong
  * to, and the **address namespace** every one of them is published under.
  *
- * It is the first segment of every canonical key (`sohl-skill-clmb`), the name
+ * It is the first segment of every canonical key
+ * (`package-system-type-shortcode`, so `sohl-none-doc-gear`), the name
  * of the link manifest this build emits (`sohl.json`), and the package a
  * cross-package wikilink writes to reach one of these notes. So it is the
  * repository's identity in the address space, not a switch — and never dead

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

@@ -73,52 +73,34 @@ export function selectRows(spec: object, docs: Array<ContentTableDoc>, self?: Co
  * @returns {string} The markdown table (no trailing newline).
  */
 export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, linkable: (doc: ContentTableDoc) => boolean, self?: ContentTableDoc): string;
-/**
- * Expand every fenced `dataview` block in a markdown body.
- *
- * A block that cannot be honoured — malformed or unsupported — is left in the
- * body verbatim and reported in `errors`, so the failure is visible in the
- * output as well as on the console. Every other code fence, and every code
- * span, is left alone (that is how the syntax is documented).
- *
- * A query that matches **no** note is not an error: it renders as an empty
- * table (headers only), which is what the author already sees in Obsidian, and
- * a category with no content yet is a normal state of the corpus rather than a
- * broken build.
- *
- * @param {string} markdown - The note body, frontmatter already stripped.
- * @param {object} ctx
- * @param {Array<ContentTableDoc>} ctx.docs - The searchable universe: every
- *   content note the caller considers in scope.
- * @param {(doc: ContentTableDoc) => boolean} [ctx.linkable] - Whether a note can
- *   be linked to from a cell; defaults to never.
- * @param {string} [ctx.source] - The note being expanded, for error reports.
- * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
- *   doc: what a query's `this` reads.
- * @returns {{markdown: string, errors: Array<{source: string, directive: string,
- *   reason: string, line: number}>, lineMap: Array<{line: number,
- *   generated: boolean}>}} `lineMap` is parallel to the emitted lines and says
- *   which authored line each came from, so a diagnostic about the expanded
- *   body can name an authored position (#17). An `errors` entry carries the
- *   0-based line of the directive that failed, for the same reason.
- */
-export function expandContentTables(markdown: string, { docs, linkable, source, self }?: {
-    docs: Array<ContentTableDoc>;
-    linkable?: ((doc: ContentTableDoc) => boolean) | undefined;
+export function expandContentTables(markdown: any, { docs, linkable, source, self, sqlTables, }?: {
+    docs?: never[] | undefined;
+    linkable?: (() => boolean) | undefined;
     source?: string | undefined;
-    self?: ContentTableDoc | undefined;
+    self?: undefined;
+    sqlTables?: undefined;
 }): {
     markdown: string;
-    errors: Array<{
+    errors: ({
         source: string;
         directive: string;
-        reason: string;
+        reason: any;
         line: number;
-    }>;
-    lineMap: Array<{
+        column: number;
+    } | {
+        source: string;
+        directive: string;
+        reason: any;
         line: number;
-        generated: boolean;
-    }>;
+        column?: undefined;
+    })[];
+    warnings: {
+        source: string;
+        line: number;
+        column: number;
+        reason: string;
+    }[];
+    lineMap: any[];
 };
 /**
  * One content note as a content build hands it to the expander: its parsed

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

@@ -53,6 +53,13 @@ export function defineDocumentSubtypes({ system, block, types }?: {
 /**
  * The row a system declares for a note type, or nothing.
  *
+ * The **one** place a map is indexed, so the retirement window for a renamed
+ * type is honoured everywhere a row is asked for — {@link documentSubtype},
+ * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
+ * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
+ * `armor` row, compiles into the `armorgear` document it always did, and keeps
+ * the address it publishes at; only the *report* tells it to move (#78).
+ *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
  * @returns {Readonly<DocumentSubtypeRow>|undefined} The row, or `undefined`
@@ -152,9 +159,17 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  *   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).
+ * reference left behind by a merge would take the unmapped fallback and address
+ * a document of the old name — resolving silently, which is precisely what a
+ * retirement exists to stop.
+ *
+ * A **renamed** spelling is the opposite case and resolves normally, through
+ * the same {@link currentType} every other lookup goes through (#78). It has to
+ * be this side as much as the note's own `type:`: the overwhelming majority of
+ * the 31,000 occurrences of the old names are `(type, shortcode)` references
+ * inside a being's `items:` list, so a window that resolved notes but not
+ * references would silently drop 30,000 embedded items rather than compile them
+ * unchanged.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The type the reference names.
@@ -163,6 +178,24 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * @returns {ReferencedSubtype} The subtype, or why there is none.
  */
 export function referencedSubtype(map: DocumentSubtypeMap, noteType: string | undefined, document: string): ReferencedSubtype;
+/**
+ * Which system defines the document a note of this type compiles into.
+ *
+ * A journal, a macro, a scene and an item's documentation journal belong to no
+ * system and answer {@link NO_SYSTEM}; an item or an actor belongs to whichever
+ * system's map claims its note type.
+ *
+ * `maps` is required rather than defaulted, so this stays reachable from any
+ * pass: the registry of maps lives in `note-claims.mjs`, which imports half the
+ * engine, and defaulting to it here would drag that in wherever an address is
+ * built.
+ *
+ * @param {string} type - The note's `type`.
+ * @param {readonly object[]} maps - The document-subtype maps this build ships.
+ * @returns {string} The system id, or {@link NO_SYSTEM}.
+ */
+export function systemOf(type: string, maps: readonly object[]): string;
+export { NO_SYSTEM };
 /**
  * One row of a system's map: what a note of this type becomes.
  */
@@ -231,3 +264,4 @@ export type ReferencedSubtype = {
      */
     problem?: string | undefined;
 };
+import { NO_SYSTEM } from "./systems.mjs";

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

@@ -1,3 +1,22 @@
+/**
+ * Whether a resolution read a field from the position it is being swept off.
+ *
+ * The sweep's progress signal, in one predicate so the compile-time report and
+ * the frontmatter lint cannot disagree about what counts — the role
+ * {@link module:engine/retired-fields.declaresRetiredAlias} plays for a renamed
+ * field.
+ *
+ * **Only for a field that declares a `legacyKey`.** Every other field's
+ * in-block position is simply where it lives; reporting those would put a
+ * finding on every field of every note in every tree, which is #126's corpus
+ * migration rather than a signal anyone could act on.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @returns {boolean} True when the value came from the retiring position.
+ */
+export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
 /**
  * Read one declared field out of a note's frontmatter.
  *
@@ -14,10 +33,16 @@
  * @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.
+ * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Called with each
+ *   field read from the position it is being swept off (#305). A callback
+ *   rather than a returned list because the caller is a compiler, which already
+ *   knows the note and how to locate a key in it; this module knows neither and
+ *   would have to invent a finding shape to say so.
  * @returns {any} The value to emit.
  */
-export function readField(field: FieldSpec, fm: object, { block }?: {
+export function readField(field: FieldSpec, fm: object, { block, onLegacyKey }?: {
     block?: string | undefined;
+    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
 }): any;
 /**
  * Turn a field declaration into the builder it declares.
@@ -27,10 +52,14 @@ export function readField(field: FieldSpec, fm: object, { block }?: {
  * @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.
+ * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
+ *   {@link readField}: called with each field the note authored at the position
+ *   it is being swept off (#305).
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[], { block }?: {
+export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey }?: {
     block?: string | undefined;
+    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
 }): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
@@ -44,7 +73,6 @@ export function buildFromFields(fields: readonly FieldSpec[], { block }?: {
  * @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 — and,
@@ -60,9 +88,28 @@ export { setPath };
  *   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.
+ *   still read, second, until #126 moves the corpus off it — keyed on
+ *   `legacyKey` where the two spellings differ.
  *
  *   Absent means the value is not authored at all — see `value`.
+ * @property {string} [legacyKey] - **The key this field is authored at inside
+ *   the system block** — the second position of the resolution order — when
+ *   that is not `name`. Absent, the position is keyed on `name`.
+ *
+ *   The two were one property until #305, which held only while a field's
+ *   shared source and its in-block key were the same word. `data:` (#128) ended
+ *   that: a shared source is a path into a container, so `data.species` and
+ *   `species` name two different places and no single value reached both.
+ *   `name: "species"` could not see `data.species`; `name: "data.species"`
+ *   could not see `hm3.species`; and each yielded the field's **default**
+ *   wherever only the other position was authored, with the note compiling and
+ *   the value simply gone.
+ *
+ *   Declaring both restores the shape every other retirement in this package
+ *   uses — read both spellings, let the current one win, and *report* the
+ *   retiring one — so a field can move into `data:` while the corpus catches
+ *   up, instead of on a flag day across four repositories. A declaration that
+ *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
  * @property {string} [topLevelMeans] - **What the note's top-level key of this
  *   name means instead** — declared only where it means something else, and
  *   stating it removes the shared top-level position from this field's
@@ -190,11 +237,33 @@ export type FieldSpec = {
      * 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.
+     * still read, second, until #126 moves the corpus off it — keyed on
+     * `legacyKey` where the two spellings differ.
      *
      * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
+    /**
+     * - **The key this field is authored at inside
+     * the system block** — the second position of the resolution order — when
+     * that is not `name`. Absent, the position is keyed on `name`.
+     *
+     * The two were one property until #305, which held only while a field's
+     * shared source and its in-block key were the same word. `data:` (#128) ended
+     * that: a shared source is a path into a container, so `data.species` and
+     * `species` name two different places and no single value reached both.
+     * `name: "species"` could not see `data.species`; `name: "data.species"`
+     * could not see `hm3.species`; and each yielded the field's **default**
+     * wherever only the other position was authored, with the note compiling and
+     * the value simply gone.
+     *
+     * Declaring both restores the shape every other retirement in this package
+     * uses — read both spellings, let the current one win, and *report* the
+     * retiring one — so a field can move into `data:` while the corpus catches
+     * up, instead of on a flag day across four repositories. A declaration that
+     * names one is mid-sweep by construction; see {@link readsLegacyKey}.
+     */
+    legacyKey?: string | undefined;
     /**
      * - **What the note's top-level key of this
      * name means instead** — declared only where it means something else, and
@@ -284,4 +353,6 @@ export type FieldSpec = {
      */
     describe: string;
 };
+import { legacyKeyOf } from "./system-block.mjs";
 import { setPath } from "./system-block.mjs";
+export { legacyKeyOf, setPath };