@heroiclands/package-build 11.1.0 → 13.0.0

package/engine/frontmatter-lint.mjs

@@ -55,15 +55,19 @@
  * @module
  */
 
-import path from "node:path";
-
 import { authoredFields } from "./field-spec.mjs";
-import { DEFAULT_ADDRESS_SCHEME, sectionOf } from "./content-address.mjs";
 import { resolveFieldValue, SYSTEM_BLOCK_KEYS, unknownBlockKeys } from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
-import { declaredTags } from "./note-vocabulary.mjs";
+import { isAddressSegment } from "./address-charset.mjs";
+import {
+    declaredTags,
+    retiredSubType,
+    retiredSubTypeMessage,
+    subTypeCharsetMessage,
+    typeCharsetMessage,
+} from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
@@ -72,6 +76,7 @@ import {
     draftRetiredMessage,
     readAliasedField,
     retiredAliasMessage,
+    sectionRetiredMessage,
 } from "./retired-fields.mjs";
 
 /**
@@ -316,83 +321,40 @@ function checkDataContainer(note, { type, fields }) {
     return findings;
 }
 
-/**
- * Whether this note's `subType` names the **section it lands at** rather than a
- * sub-kind of its type (#197).
- *
- * Under `landing: readme` a `README.md` addresses its whole section, and the
- * segment is what `sectionOf` reads — for a `doc`, its `subType`. So that one
- * field is spelled once and read twice: as a genre on an ordinary note, and as
- * an address on a landing. The two vocabularies are not the same set, and the
- * closed one cannot answer for the open one.
- *
- * Asked of {@link sectionOf} rather than by naming a type, because which types
- * route by their `subType` is address knowledge and this module deliberately
- * knows no type names of its own.
- *
- * @param {object} note - The note.
- * @param {string} landing - The repository's landing rule.
- * @returns {boolean} Whether the value is an address.
- */
-function subTypeIsSection(note, landing) {
-    if (landing !== "readme") return false;
-    const file = typeof note.file === "string" ? note.file : "";
-    if (path.basename(file).toLowerCase() !== "readme.md") return false;
-    const fm = note.fm ?? {};
-    return typeof fm.subType === "string" && sectionOf(fm) === fm.subType;
-}
-
 /**
  * Check a note's top-level `subType` against the values its type declares
- * (#128), or — for a `README` landing — against the sections that can exist
- * (#197, #200).
+ * (#128).
  *
  * `subType` stays at the top level — it is what each system's map reads to
  * derive a document type, so it describes the note rather than the subject —
  * but it is not open like the rest of that region: a type either declares a
  * `subType` or does not, and a type that does declares its values.
  *
- * **A landing page's is an address, and an address is checked against the
- * addresses that exist.** A `README` under `landing: readme` addresses its
- * section through this field, and a section is `weapongear` or `being` as
- * readily as it is `rules`. What can legitimately appear there is the range of
- * {@link sectionOf} over every note the format permits, plus whatever the
- * repository names:
- *
- * 1. **Every declared content type.** `sectionOf` returns `fm.type` for a
- *    non-`doc` note, so `being`, `lore` and `weapongear` are sections *by
- *    construction*, configured or not.
- * 2. **The type's own subtypes** — `rules`, `user-guide`, `reference` for a
- *    `doc`, since a `doc` routes by its subtype.
- * 3. **The configured sections**, which may name one that is neither: `sohl`
- *    configures `credits` and `dev-docs`.
- *
- * Checking only (3) was #197's fix and keyed on configuration a consumer may
- * legitimately not have: `sohl-thalorna` has no `site:` block at all, so five
- * of its landings were refused for naming their own content type (#200).
- *
- * **The guard survives.** A misspelling is none of the three, so it still
- * fails, with the near miss drawn from the whole union. What is deliberately no
- * longer caught is a landing for a section that exists but is empty — which is
- * legitimate, and is why the set is the types the format *declares* rather than
- * the types *present in the tree*: `sohl` ships two such landings above tables
- * that stay empty until the first note of each type does.
+ * **It is a genre, and only a genre.** #197 gave the field a second reading: a
+ * `README.md` was its section's landing page, and the segment it landed at was
+ * its `subType`, so the value had to be checked against the sections that could
+ * exist — every content type, plus whatever a repository configured — rather
+ * than against the genres its type declares. Two vocabularies in one field is
+ * what #198, #200 and #201 were each spent on, and #204 removed the cause rather
+ * than the symptom: a section is a Hugo directory the note format does not
+ * carry, and a page introducing a type is an ordinary note addressed
+ * `doc-<type>`. So the closed list answers for every note, whatever it is
+ * called, and `rules`, `userguide`, `reference` mean three genres and nothing
+ * else.
+ *
+ * **Three checks, in this order** — retired spelling, then charset, then the
+ * closed set (#206, #204). Each is ahead of the next because it is the more
+ * specific statement about the same value: a retired spelling has a named
+ * replacement, a hyphenated value is unaddressable whatever the type declares,
+ * and only then is the type's own list the reason.
  *
  * @param {object} note - The note.
  * @param {object} opts
  * @param {string} opts.type - The note's type, for the message.
  * @param {object} opts.entry - The type's vocabulary entry.
- * @param {boolean} [opts.asSection] - Whether the value is a section address —
- *   see {@link subTypeIsSection}.
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares. Empty leaves a landing checked against its genres and the
- *   configured sections alone.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures. Empty when it configures none, which is ordinary rather than a
- *   defect.
  * @returns {object[]} Findings.
  */
-function checkSubType(note, { type, entry, asSection = false, types = [], sections = [] }) {
+function checkSubType(note, { type, entry }) {
     const fm = note.fm ?? {};
     if (!Object.hasOwn(fm, "subType") || fm.subType == null || fm.subType === "") return [];
 
@@ -412,33 +374,46 @@ function checkSubType(note, { type, entry, asSection = false, types = [], sectio
         ];
     }
 
-    const values = entry.subTypes;
-    // `null` is "declared, values not yet enumerated" — presence is legal and
-    // the value is nobody's to check yet.
-    if (values == null || values.includes(value)) return [];
+    // A retired spelling is **accepted**, and said out loud (#206). Checked
+    // before the charset, because the note is not wrong about the charset in
+    // some general way — it is wrong about one value, and naming the
+    // replacement is the whole of what the author needs. A warning rather than
+    // an error for the same reason the retired field aliases below are: the
+    // note compiles to the correct page, and erroring would red every tree the
+    // moment it took this release, ahead of any chance to sweep.
+    const replacement = retiredSubType(type, value);
+    if (replacement) {
+        return [
+            {
+                file: note.file,
+                ...at,
+                severity: "warning",
+                message: retiredSubTypeMessage(type, value, replacement),
+            },
+        ];
+    }
 
-    if (asSection) {
-        if (types.includes(value) || sections.includes(value)) return [];
-        const guess = nearest(value, [...types, ...values, ...sections]);
+    // The charset, before the closed set: a hyphenated value is unaddressable
+    // whatever the type declares, and the type's list is not the reason it is
+    // refused. Reported here rather than only for an enumerated type, so a
+    // `subTypes: null` type — whose values nothing may yet check — is still
+    // held to the one rule that does not depend on knowing them.
+    if (!isAddressSegment(value)) {
         return [
             {
                 file: note.file,
                 ...at,
                 severity: "error",
-                message:
-                    `\`subType\` "${value}" is the section this README lands ` +
-                    `at, and nothing declares it. A section is a content type ` +
-                    `(${types.join(", ")}), a subtype ${type} declares ` +
-                    `(${values.join(", ")})` +
-                    (sections.length ?
-                        `, or a section configured under \`site.sections\` / ` +
-                        `\`site.readmeSections\` (${sections.join(", ")})`
-                    :   "") +
-                    (guess ? `. Did you mean "${guess}"?` : ""),
+                message: subTypeCharsetMessage(value),
             },
         ];
     }
 
+    const values = entry.subTypes;
+    // `null` is "declared, values not yet enumerated" — presence is legal and
+    // the value is nobody's to check yet.
+    if (values == null || values.includes(value)) return [];
+
     const guess = nearest(value, values);
     return [
         {
@@ -521,33 +496,9 @@ function checkTags(note, { type }) {
  * @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 {string} [opts.landing] - The repository's landing rule, from
- *   `publish.address.landing`. It decides which note addresses a whole section,
- *   and so whether a `subType` is a genre or an address (#197).
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares — the sections that exist by construction (#200). Read from
- *   `docs/content-format.md` rather than from `schemas`, because the two answer
- *   different questions: whether an address is real, and whether this build can
- *   check a note's fields. A type the specification declares and no schema
- *   covers is a real section, and its notes are reported on their own account.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures, from `declaredSections`. Supplied by the caller for the same
- *   reason `vocabulary` is: this module checks a note against what it is
- *   handed.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(
-    note,
-    {
-        schemas,
-        index,
-        vocabulary,
-        systems = DEFAULT_SYSTEM_BLOCKS,
-        landing = DEFAULT_ADDRESS_SCHEME.landing,
-        types = [],
-        sections = [],
-    },
-) {
+export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_SYSTEM_BLOCKS }) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
@@ -578,6 +529,17 @@ export function lintNote(
             message: draftRetiredMessage(),
         });
     }
+    // Anchored at column 1 for the same reason `aliases` is: `section` names a
+    // configuration key too (`site.trees[].section`), and a nested one under
+    // some other block is not this field (#202).
+    if (Object.hasOwn(fm, "section")) {
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(raw(), "section", undefined, { topLevel: true }),
+            severity: "error",
+            message: sectionRetiredMessage(),
+        });
+    }
     // Only the top-level `aliases` is retired. `name.aliases` writes the same
     // key indented under `name:` and is **permitted** — reserved and unread —
     // so both the test and the locator are anchored at column 1 (#180).
@@ -609,6 +571,25 @@ export function lintNote(
         });
     }
 
+    // The type's charset, before anything that looks the type up (#206). A
+    // hyphenated type is unaddressable, and every lookup below would report it
+    // as a type nobody declared — true, but not the reason, and it would send
+    // the author to declare one rather than to rename it.
+    //
+    // Guarded on a non-empty type: an absent one is a missing key, not a
+    // charset violation, and is reported as the missing schema it causes.
+    // There is **no transitional path** here, deliberately: no tree authors a
+    // hyphenated type, so an acceptance would guard a case that does not exist.
+    if (type && !isAddressSegment(type)) {
+        findings.push({
+            file: note.file,
+            ...at("type", type),
+            severity: "error",
+            message: typeCharsetMessage(type),
+        });
+        return findings;
+    }
+
     const replacement = RETIRED_TYPES[type];
     if (replacement) {
         findings.push({
@@ -644,15 +625,7 @@ export function lintNote(
     const entry = vocabulary?.[type];
     if (entry) {
         findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [] }));
-        findings.push(
-            ...checkSubType(note, {
-                type,
-                entry,
-                asSection: subTypeIsSection(note, landing),
-                types,
-                sections,
-            }),
-        );
+        findings.push(...checkSubType(note, { type, entry }));
     }
 
     const fields = authoredFields(schema);
@@ -809,19 +782,10 @@ export function 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}.
- * @param {string} [opts.landing] - The repository's landing rule; see
- *   {@link lintNote}.
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares; see {@link lintNote}.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(
-    index,
-    { schemas, vocabulary, references = true, systems, landing, types, sections },
-) {
+export function lintFrontmatter(index, { schemas, vocabulary, references = true, systems }) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -835,9 +799,6 @@ export function lintFrontmatter(
                 vocabulary,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
-                ...(landing ? { landing } : {}),
-                ...(types ? { types } : {}),
-                ...(sections ? { sections } : {}),
             }),
         );
     }

package/engine/manifest-emit.mjs

@@ -32,19 +32,16 @@
  * **An entry's `path` is derivable from the key it is filed under** (#181).
  * `sohl-affliction-aconite` publishes at `affliction-aconite/`, because a page's
  * URL *is* its address; nothing in it comes from a display name, so a rename
- * moves no URL and no uniqueness check stands between the two. The field is
- * still written rather than left for a consumer to compute, because a landing
- * page is the one entry that is not derivable — it addresses its section under
- * the configured mount — and because an absent `path` already means something
- * else entirely (a package that publishes no pages).
+ * moves no URL and no uniqueness check stands between the two. Every entry is
+ * derivable that way since #204 retired the section landing, which was the one
+ * that was not. The field is still written rather than left for a consumer to
+ * compute, because an absent `path` already means something else entirely (a
+ * package that publishes no pages).
  *
- * **The address scheme is configuration, and it is shared with the site build.**
- * Where the content tree mounts inside the package and which note is a section's
- * landing page differ between repositories and are both load-bearing — `sohl`
- * records `kb/rules/` for the landing of its rules section and `thalorna`
- * records `affiliation/` for its own. Reading one setting here and in the page
- * emitter is what stops a manifest asserting an address the site does not
- * publish, which resolves at build time and 404s for the reader.
+ * **The address is derived by one function, shared with the site build.** An
+ * address is `(type, shortcode)` in both, so a manifest cannot assert an address
+ * the site does not publish — the failure that resolves at build time and 404s
+ * for the reader.
  *
  * **Anchors are computed, not approximated.** The pass that splits a note into
  * journal pages is {@link splitPages}, a pure function over the markdown body,
@@ -65,7 +62,11 @@ import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
+import {
+    assertNoAliasesField,
+    assertNoDraftField,
+    assertNoSectionField,
+} from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -233,6 +234,7 @@ export function collectManifestEntries(contentBase, ctx) {
         });
         assertNoDraftField(fm, { file: rel, absPath });
         assertNoAliasesField(fm, { file: rel, absPath });
+        assertNoSectionField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
         // A homepage is addressed like every other note since #182, and a
         // shortcode alone would now put it here. It stays out for the reason it
@@ -243,15 +245,11 @@ export function collectManifestEntries(contentBase, ctx) {
         // no index.
         if (isHomepage(fm)) continue;
 
-        const base = path.basename(absPath);
         const name = fm.name?.full ?? path.basename(absPath, ".md");
 
         let address;
         try {
-            address = packageAddress(fm, {
-                isReadme: base.toLowerCase() === "readme.md",
-                scheme: ctx.scheme,
-            });
+            address = packageAddress(fm, { scheme: ctx.scheme });
         } catch (err) {
             skipped.push({ file: rel, reason: err.message });
             continue;

package/engine/note-vocabulary.mjs

@@ -53,9 +53,31 @@
  * one is already reported as a type no schema declares, which is the finding it
  * deserves until the type exists.
  *
+ * **A type name and a subType value are held to the address charset** (#206), so
+ * both are `^[A-Za-z0-9]+$` — the charset `engine/address-charset.mjs` states
+ * and the shortcode is already held to. For a type that is literal: it is the
+ * first segment of every address (`type-shortcode`), the hyphen is the
+ * separator between segments and can therefore never occur inside one, and a
+ * hyphenated name would be read back as two segments and resolve to nothing,
+ * reporting nothing about why.
+ *
+ * A subType reaches no address of its own. It did when this rule was written —
+ * a `doc`'s was its section, a path segment — and #204 retired sections from
+ * the note format one release later. It keeps the rule regardless, and the
+ * reason is not inertia: a subType is a vocabulary term the whole toolchain
+ * keys on, it is one closed set away from being an address again, and a charset
+ * that held for a type, a shortcode and a package but not for a subType would
+ * be a rule nobody could state in one sentence. The registry below is checked
+ * against it as this module loads, so a declaration that breaks it cannot be
+ * imported, let alone shipped.
+ *
  * @module
  */
 
+// The one charset, read rather than restated. A second spelling of the pattern
+// is how the three disagreements found in #202/#203 happened.
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
+
 /**
  * One `data:` key a note type may carry.
  *
@@ -641,7 +663,12 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
-        subTypes: Object.freeze(["rules", "user-guide", "reference"]),
+        // `userguide`, not `user-guide`: a `doc` routes by its subType, so the
+        // value is a path segment, and a segment carries no hyphen (#206). The
+        // old spelling is accepted transitionally — see {@link RETIRED_SUBTYPES}
+        // — but it is not declared here, because this list is what the format
+        // says a note *should* write.
+        subTypes: Object.freeze(["rules", "userguide", "reference"]),
         data: Object.freeze([]),
     }),
 
@@ -704,6 +731,137 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 });
 
+/**
+ * The retired spelling of a subType a type declares → what to write now (#206).
+ *
+ * Keyed by type, because a retirement is a statement about *that type's*
+ * vocabulary: `user-guide` on a `doc` is the old spelling of `userguide`, while
+ * the same string on any other type is nothing but a charset violation, and
+ * saying "did you mean userguide" there would be a guess dressed as a fact.
+ *
+ * **Recorded here rather than left in `subTypes`** so the declared list stays
+ * the list of values a note *should* write. A retired value is accepted, not
+ * declared — the difference is exactly what makes the finding possible.
+ *
+ * **Deliberately not the shape of a type rename** ({@link
+ * import("./ids.mjs").RETIRED_TYPES}), which is an error: a retired type routes
+ * a note to the wrong pack, whereas a retired subType still compiles to the
+ * correct page. The sweep is the consumer's, and the ordering is the reverse of
+ * the usual — the acceptance ships *first*, because declaring only the new
+ * spelling while 43 `sohl` notes still author the old one would invalidate all
+ * 43 with a release they had no chance to sweep ahead of. A later change
+ * removes this map, and the old spelling then falls through to the ordinary
+ * undeclared-value error with no code left to remove.
+ *
+ * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
+ */
+export const RETIRED_SUBTYPES = Object.freeze({
+    doc: Object.freeze({ "user-guide": "userguide" }),
+});
+
+/**
+ * What to write in place of a retired subType value, if it is one.
+ *
+ * @param {string} type - The note's `type`.
+ * @param {string} value - The authored `subType`.
+ * @param {Readonly<Record<string, Readonly<Record<string, string>>>>} [retired]
+ *   The map to read, defaulting to {@link RETIRED_SUBTYPES}.
+ * @returns {string|undefined} The current spelling, or `undefined` when the
+ *   value is not a retired one — which is not the same as it being valid.
+ */
+export function retiredSubType(type, value, retired = RETIRED_SUBTYPES) {
+    const forType = retired?.[type];
+    if (!forType || !Object.hasOwn(forType, value)) return undefined;
+    return forType[value];
+}
+
+/**
+ * What a note carrying a retired subType is told.
+ *
+ * One message, so the lint and any later refusal cannot describe the same
+ * retirement differently.
+ *
+ * @param {string} type - The note's `type`.
+ * @param {string} value - The retired spelling the note carries.
+ * @param {string} replacement - What to write instead.
+ * @returns {string} The message.
+ */
+export function retiredSubTypeMessage(type, value, replacement) {
+    return (
+        `\`subType\` "${value}" is a retired spelling of "${replacement}" on a ` +
+        `${type}; write "${replacement}". A subType is an address segment, and ` +
+        `a segment is ${ADDRESS_SEGMENT_PATTERN.source} — the hyphen separates ` +
+        `segments, so it can never occur inside one. The old spelling is still ` +
+        `accepted, and will stop being accepted once the trees have swept`
+    );
+}
+
+/**
+ * What a note carrying a subType outside the address charset is told.
+ *
+ * @param {string} value - The authored `subType`.
+ * @returns {string} The message.
+ */
+export function subTypeCharsetMessage(value) {
+    return (
+        `\`subType\` "${value}" is not an address segment — a subType is ` +
+        `letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same ` +
+        `charset a shortcode is held to. The hyphen separates the segments of ` +
+        `an address, so a value containing one is read back as two segments ` +
+        `and resolves to nothing`
+    );
+}
+
+/**
+ * What a note carrying a type outside the address charset is told.
+ *
+ * @param {string} type - The authored `type`.
+ * @returns {string} The message.
+ */
+export function typeCharsetMessage(type) {
+    return (
+        `content type "${type}" is not an address segment — a type is letters ` +
+        `and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same charset ` +
+        `a shortcode is held to. A type is the first segment of every address ` +
+        `("type-shortcode"), so a hyphenated one is read back as two segments ` +
+        `and resolves to nothing`
+    );
+}
+
+/**
+ * Refuse a vocabulary that declares a type or subType outside the charset.
+ *
+ * Run over {@link NOTE_VOCABULARY} as this module loads, so a declaration that
+ * breaks the rule cannot be imported. That is stricter than a lint on purpose:
+ * a note's bad value is one author's mistake and belongs in a report, while a
+ * bad *declaration* would tell every author to write something unaddressable.
+ *
+ * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
+ * @param {string} [where] - What declares it, for the message.
+ * @throws {Error} Naming every offending type and subType at once, rather than
+ *   stopping at the first — a reader fixing a list wants the whole list.
+ */
+export function assertVocabularyCharset(vocabulary, where = "the note vocabulary") {
+    const bad = [];
+    for (const [type, entry] of Object.entries(vocabulary ?? {})) {
+        if (!isAddressSegment(type)) bad.push(`type "${type}"`);
+        const values = entry?.subTypes;
+        if (!Array.isArray(values)) continue;
+        for (const value of values) {
+            if (!isAddressSegment(value)) bad.push(`subType "${value}" on ${type}`);
+        }
+    }
+    if (!bad.length) return;
+    throw new Error(
+        `${where} declares ${bad.join(", ")}, which ${bad.length === 1 ? "is" : "are"} ` +
+            `not ${ADDRESS_SEGMENT_PATTERN.source}. A type and a subType are both ` +
+            `address segments, and the hyphen separates segments rather than ` +
+            `occurring inside one.`,
+    );
+}
+
+assertVocabularyCharset(NOTE_VOCABULARY);
+
 /**
  * The `data:` keys a note type may carry.
  *