@heroiclands/package-build 3.2.0 → 3.3.0

package/engine/note-package.mjs

@@ -0,0 +1,126 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Which content package a note belongs to.
+ *
+ * **It is the repository's configured `contentPackage`.** A content tree holds
+ * exactly one package's notes — every package is single-sourced in the
+ * repository that ships it — so the package is a property of the *repository*,
+ * not of the note.
+ *
+ * It used to be a property of the note, and a **selector**: the compile loop
+ * read `package:` out of frontmatter and skipped anything that did not match
+ * the configured value. That is the defect this module exists to remove
+ * (#56). The skip was silent and it was bucketed as "belongs to another pass",
+ * so a tree whose notes named a package no configuration answered to compiled
+ * **zero notes and exited 0** — which is exactly the state the un-migrated
+ * `hm-loc-*` / `hm-adv-*` repositories are in today.
+ *
+ * So the field is being retired, in three steps, of which this is the first:
+ *
+ * 1. **Optional here.** An absent `package:` is normal and the note compiles; a
+ *    present one is accepted while it agrees, and is a loud, named error when
+ *    it does not. Non-breaking, so a consumer adopts it before changing a note.
+ * 2. **Swept** out of every content tree in the org, on this version.
+ * 3. **Rejected outright**, as a major, once the sweeps have merged.
+ *
+ * The distinction between the two functions here is which question is being
+ * asked. {@link assertNotePackage} is for a site that used to *select* — it
+ * answers "may this build compile this note", and a disagreement is a finding.
+ * {@link notePackage} is for a site that *derives an address* — it answers
+ * "which package's namespace does this address sit in", where a disagreement
+ * has already been reported by the compile pass and repeating it would print
+ * the same fault twice.
+ *
+ * @module
+ */
+
+import { contentPackage } from "./content-package.mjs";
+
+/**
+ * The package a note belongs to.
+ *
+ * Non-validating: the answer for a note that declares nothing, and for one that
+ * declares the configured package, is the same value. A note declaring some
+ * *other* package is answered literally here rather than corrected — the
+ * compile pass reports that, once, through {@link assertNotePackage}.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {string} [configured] - The package this build compiles. Defaults to
+ *   the configured `contentPackage`; passed explicitly by callers that already
+ *   carry it in a context object, so a caller's configuration drives every read.
+ * @returns {string} The package.
+ */
+export function notePackage(fm, configured) {
+    const declared = fm?.package;
+    // A blank is a declaration of nothing, not a package named "".
+    if (declared != null && declared !== "") return declared;
+    // Resolved only when it is needed, so a caller holding a note that declares
+    // one never touches the configuration (#2).
+    return configured ?? contentPackage();
+}
+
+/**
+ * A note's frontmatter as a generated table searches it — its package present
+ * whether or not the note declares one.
+ *
+ * A `dataview` query resolves `package` out of frontmatter like any other
+ * field, so a collection note that scopes itself with `WHERE … and package =
+ * "sohl"` matches nothing once the field is deleted, and renders an **empty
+ * table** in silence. Deriving the value here keeps the two spellings
+ * equivalent, so a sweep that deletes the field is mechanical rather than a
+ * trap (#56) — and a query that never mentions `package` is unaffected either
+ * way.
+ *
+ * The declared value is left alone when there is one, so nothing about an
+ * unswept tree changes.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} [configured] - The package this build compiles.
+ * @returns {object|null|undefined} The frontmatter itself when it declares a
+ *   package, else a shallow copy carrying the derived one.
+ */
+export function searchableFrontmatter(fm, configured) {
+    if (!fm || typeof fm !== "object") return fm;
+    if (fm.package != null && fm.package !== "") return fm;
+    return { ...fm, package: notePackage(fm, configured) };
+}
+
+/**
+ * The package a note belongs to, refusing one that names another package.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.configured] - The package this build compiles.
+ *   Defaults to the configured `contentPackage`.
+ * @returns {string} The package, which is always `configured`.
+ * @throws {Error} When the note declares a different package.
+ */
+export function assertNotePackage(fm, { file, configured } = {}) {
+    const target = configured ?? contentPackage();
+    const pkg = notePackage(fm, target);
+    if (pkg === target) return target;
+    throw new Error(
+        `note declares \`package: ${pkg}\`, but this repository compiles ` +
+            `"${target}"` +
+            (file ? ` — ${file}` : "") +
+            `. A note's package is the configured \`contentPackage\`, so the ` +
+            `field is redundant and is being retired: delete it, or correct ` +
+            `\`contentPackage\` in package-build.config.yaml.`,
+    );
+}

package/engine/pack-router.mjs

@@ -69,8 +69,9 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to `package:` and deliberately not the same word: a note's
- * `package:` says which *distribution* owns it, `pack:` which *compendium*
+ * Deliberately close to the retiring `package:` and deliberately not the same
+ * word: `package:` said which *distribution* owned a note — now the
+ * repository's `contentPackage` (#56) — while `pack:` says which *compendium*
  * receives its document.
  */
 export const PACK_FIELD = "pack";

package/engine/scenes.mjs

@@ -63,7 +63,7 @@ import { BasePackCompiler } from "./base-compiler.mjs";
 import { buildJournalEntry, splitPages, journalPageId } from "./journals.mjs";
 import { compendiumUuid, makeId, packForType } from "./ids.mjs";
 import { packRouter } from "./pack-router.mjs";
-import { contentPackage, foundryPackageId } from "./content-package.mjs";
+import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
 import {
     behaviorDocId,
@@ -192,7 +192,11 @@ export class Scenes extends BasePackCompiler {
         for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
             this.contentBase,
         )) {
-            if (!fm || fm.package !== contentPackage() || !fm.id) continue;
+            // No package test: every note in the tree is this package's, and
+            // this pass's own walk — the shared compile loop — is where a note
+            // declaring another one is reported, once (#56). Repeating the
+            // check here would either double the diagnostic or throw past it.
+            if (!fm || !fm.id) continue;
             if (
                 fm.shortcode &&
                 Array.isArray(fm.effects) &&

package/engine/site-build.mjs

@@ -62,6 +62,7 @@ import {
 } from "./foreign-manifests.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { notePackage, searchableFrontmatter } from "./note-package.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -117,7 +118,9 @@ function readNote(file) {
  * The content tree's pages, and what could not be addressed.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ packages, skipDirectories, mount, scheme }`.
+ * @param {object} ctx - `{ packages, contentPackage, skipDirectories, mount,
+ *   scheme }`. `contentPackage` is the package a note that declares none
+ *   belongs to.
  * @returns {{pages: object[], slugFindings: object[], fmLinkFindings: object[]}}
  */
 export function collectContentPages(contentBase, ctx) {
@@ -129,7 +132,12 @@ export function collectContentPages(contentBase, ctx) {
         const note = readNote(file);
         if (!note) continue;
         const { fm, body } = note;
-        if (!ctx.packages.has(fm.package) || !fm.type) continue;
+        // Derived rather than read: `package:` is optional, and a note that
+        // declares nothing belongs to the package this repository compiles
+        // (#56). Once the field is retired outright this collapses to
+        // `ctx.contentPackage` and the set membership becomes a formality.
+        const pkg = notePackage(fm, ctx.contentPackage);
+        if (!ctx.packages.has(pkg) || !fm.type) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -154,6 +162,10 @@ export function collectContentPages(contentBase, ctx) {
         pages.push({
             kind: "content",
             fm,
+            // The page's package, resolved once here so every consumer — the
+            // index's canonical keys, the table universe, the local-package set
+            // — reads one derived value instead of frontmatter (#56).
+            pkg,
             body,
             name,
             slug,
@@ -287,7 +299,7 @@ export function siteGates(pages, findings, { manifestDir }) {
     // and that is only known once the tree is walked — reading it from a
     // configured list instead silently discarded the manifest of any package
     // the list named but the tree did not contain.
-    const localPackages = new Set(content.map((p) => p.fm.package));
+    const localPackages = new Set(content.map((p) => p.pkg));
     const foreign = loadForeignManifests(manifestDir, localPackages);
     out.foreign = foreign;
     if (foreign.stale.length) {
@@ -332,10 +344,12 @@ export function tableUniverse(pages) {
     const byPackage = new Map();
     for (const p of pages) {
         if (p.kind !== "content") continue;
-        const pkg = p.fm.package;
+        const pkg = p.pkg;
         if (!byPackage.has(pkg)) byPackage.set(pkg, []);
         byPackage.get(pkg).push({
-            fm: p.fm,
+            // Package present however the note spells it — see
+            // {@link searchableFrontmatter} (#56).
+            fm: searchableFrontmatter(p.fm, pkg),
             path: p.relPath,
             tld: p.tld,
             folder: p.folder,
@@ -457,10 +471,13 @@ export function renderPages(pages, options) {
         let body = page.body;
         if (page.kind === "content") {
             const { markdown, errors } = expandContentTables(body, {
-                docs: universe.get(page.fm.package) ?? [],
+                docs: universe.get(page.pkg) ?? [],
                 linkable,
                 source: src,
-                self: { fm: page.fm, path: page.relPath },
+                self: {
+                    fm: searchableFrontmatter(page.fm, page.pkg),
+                    path: page.relPath,
+                },
             });
             tableErrors.push(...errors);
             body = markdown;
@@ -697,6 +714,8 @@ export function buildSite({ config, outRoot } = {}) {
 
     const ctx = {
         packages,
+        // What a note that declares no `package:` belongs to (#56).
+        contentPackage: resolved.contentPackage,
         skipDirectories: resolved.skipDirectories,
         mount,
         scheme,

package/engine/site-index.mjs

@@ -53,6 +53,7 @@ import path from "node:path";
 
 import { canonicalKey, readCanonicalKey } from "./kb-manifest.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
+import { notePackage } from "./note-package.mjs";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -238,7 +239,13 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // stays because a bare `[[skill-lang]]` defaults to the citing
             // note's own package and must keep resolving unchanged; the
             // canonical form is what cross-package links use (#1499).
-            index.set(canonicalKey(e.fm.package, type, shortcode), value);
+            // The page's package is derived — the site collection resolves it
+            // and records it as `pkg` — rather than read out of frontmatter,
+            // where `package:` is optional and on its way out (#56).
+            index.set(
+                canonicalKey(e.pkg ?? notePackage(e.fm), type, shortcode),
+                value,
+            );
             // In Foundry an item and its documentation are two documents, so
             // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
             // item note renders as one page which *is* its documentation, so

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/actors.mjs

@@ -55,6 +55,7 @@ import {
     md,
 } from "../engine/helpers.mjs";
 import { emitDiagnostic } from "../engine/diagnostics.mjs";
+import { openingMasteryLevel } from "./skill-base.mjs";
 import { BasePackCompiler } from "../engine/base-compiler.mjs";
 import { contentPackage } from "../engine/content-package.mjs";
 
@@ -498,9 +499,63 @@ export class Actors extends BasePackCompiler {
             });
         }
 
+        this.openUnopenedSkills(items, ctx);
         return items;
     }
 
+    /**
+     * Bake each unopened skill's opening mastery level into the document (#46).
+     *
+     * A skill whose `masteryLevelBase` is still null once the note's frontmatter
+     * has been merged onto the catalogue entry is *not yet opened*, and the
+     * client fills it in on import — `Skill Base × initSkillMult`, in
+     * `SkillLogic.initialize`. Computing it here instead leaves the compiled
+     * pack self-describing: what a being's skills open at is visible in the
+     * document, reviewable in a diff, and testable without standing up Foundry.
+     *
+     * This runs last because the Skill Base formula reads the actor's
+     * attributes, so every attribute item has to exist first. It only ever
+     * fills nulls — a skill that states a `masteryLevelBase`, whether from the
+     * catalogue or the note, keeps it untouched.
+     *
+     * **The scores used are the ones just written.** `SkillLogic` resolves
+     * `attr.<code>` to an attribute's *effective* score, after active effects;
+     * all this pass has is the `scoreBase` it set from `sohl.attributes`. For a
+     * compiled being carrying no attribute-altering effects the two agree,
+     * which is every being in content today. One that did carry such an effect
+     * would bake a Skill Base its client then disagrees with — that is the
+     * limit of doing this at build time, and the point to revisit if it bites.
+     *
+     * @param {object[]} items - The actor's embedded items, attributes included.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     */
+    openUnopenedSkills(items, ctx) {
+        const skills = items.filter(
+            (item) =>
+                item.type === "skill" &&
+                item.system &&
+                item.system.masteryLevelBase == null,
+        );
+        if (!skills.length) return;
+
+        const attrs = {};
+        for (const item of items) {
+            if (item.type !== "attribute") continue;
+            const code = item.system?.shortcode?.toLowerCase();
+            if (code) attrs[code] = Number(item.system.scoreBase) || 0;
+        }
+
+        for (const skill of skills) {
+            const { value, error } = openingMasteryLevel(skill.system, attrs);
+            if (error) {
+                this.noteError(`${ctx}: skill "${skill.name}": ${error}`);
+                this.errorCount++;
+                continue;
+            }
+            if (value !== null) skill.system.masteryLevelBase = value;
+        }
+    }
+
     buildBeing(itemsMap, fm, body) {
         const name = resolveName(fm);
         const id = fm.id;

package/sohl/skill-base.mjs

@@ -0,0 +1,280 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Build-time Skill Base evaluation — the small part of SoHL's `SafeExpression`
+ * needed to compile a skill's opening mastery level into the pack (#46).
+ *
+ * A skill's `skillBaseFormula` is a `SafeExpression` in the `skill.base` scope:
+ * an expression over one binding, `attr` (attribute scores by shortcode), with
+ * the helper library in scope — in practice always `sb(attr.x, attr.y)`. The
+ * client evaluates it in `SkillLogic.computeSkillBase`. Nothing here talks to
+ * Foundry, so this reproduces the evaluation rather than importing it.
+ *
+ * **Reproduced deliberately, and it must not drift**: if SoHL changes `sb()`'s
+ * rounding or the clamp, a pack compiled here and the client reading it stop
+ * agreeing. The two rules copied are:
+ *
+ * - `sb()` (SoHL `ExpressionHelperRegistry`) — one value is itself; two are
+ *   averaged and rounded **up** iff the first exceeds the second, **down**
+ *   otherwise (so equal values round down); three or more are averaged and
+ *   rounded to nearest.
+ * - The clamp (SoHL `SkillLogic.computeSkillBase`) — the result is
+ *   `Math.max(0, n)`, and a formula that does not yield a finite number is an
+ *   error rather than a silent zero.
+ *
+ * What is **not** reproduced is the rest of the grammar. This evaluator accepts
+ * numeric literals, `attr.<code>` / `attr["<code>"]` reads, calls to the
+ * helpers below, parentheses and ordinary arithmetic — and rejects everything
+ * else outright. A formula this cannot evaluate is reported, not guessed at.
+ */
+
+import { parse } from "acorn";
+
+/**
+ * The HârnMaster Skill Base reduction, mirroring SoHL's `sb()` helper exactly.
+ *
+ * @param {...number} values - One or more attribute values.
+ * @returns {number} The reduced Skill Base.
+ * @throws {Error} If called with no arguments.
+ */
+export function sb(...values) {
+    if (values.length === 0) {
+        throw new Error("sb() requires at least one attribute value");
+    }
+    const nums = values.map((v) => Number(v));
+    if (nums.length === 1) return nums[0];
+    if (nums.length === 2) {
+        const average = (nums[0] + nums[1]) / 2;
+        return nums[0] > nums[1] ? Math.ceil(average) : Math.floor(average);
+    }
+    const sum = nums.reduce((acc, n) => acc + n, 0);
+    return Math.round(sum / nums.length);
+}
+
+/**
+ * The helper functions a `skill.base` formula may call. SoHL's registry carries
+ * far more; only those a Skill Base formula has any use for are offered here,
+ * so an unsupported call fails loudly instead of evaluating to something
+ * plausible.
+ */
+const HELPERS = Object.freeze({
+    sb,
+    min: (...v) => Math.min(...v.map(Number)),
+    max: (...v) => Math.max(...v.map(Number)),
+    floor: (v) => Math.floor(Number(v)),
+    ceil: (v) => Math.ceil(Number(v)),
+    round: (v) => Math.round(Number(v)),
+    abs: (v) => Math.abs(Number(v)),
+});
+
+/** Binary operators the evaluator honours. */
+const BINARY = Object.freeze({
+    "+": (a, b) => a + b,
+    "-": (a, b) => a - b,
+    "*": (a, b) => a * b,
+    "/": (a, b) => a / b,
+    "%": (a, b) => a % b,
+    "**": (a, b) => a ** b,
+});
+
+/**
+ * Read `attr.<code>`, case-insensitively, defaulting to `0`.
+ *
+ * SoHL wraps its `attr` context in a Proxy so an attribute the actor does not
+ * have reads as `0` instead of throwing (`SkillLogic.buildAttrContext`). A
+ * plain lookup with the same fallback is equivalent for evaluation.
+ *
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @param {string} code - The attribute shortcode referenced.
+ * @returns {number} The score, or `0` when the actor has no such attribute.
+ */
+function readAttr(attrs, code) {
+    const value = attrs[String(code).toLowerCase()];
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Evaluate one parsed expression node.
+ *
+ * @param {object} node - An acorn expression node.
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @returns {number} The node's value.
+ * @throws {Error} On any construct outside the supported subset.
+ */
+function evalNode(node, attrs) {
+    switch (node.type) {
+        case "Literal": {
+            if (typeof node.value !== "number") {
+                throw new Error(
+                    `unsupported literal ${JSON.stringify(node.value)}`,
+                );
+            }
+            return node.value;
+        }
+        case "MemberExpression": {
+            // Only `attr.<code>` and `attr["<code>"]`. Any other object, and
+            // any computed key that is not a plain string, is out of scope.
+            if (node.object?.type !== "Identifier") {
+                throw new Error(
+                    "only `attr.<code>` member reads are supported",
+                );
+            }
+            if (node.object.name !== "attr") {
+                throw new Error(
+                    `unknown binding "${node.object.name}" — the skill.base scope binds only \`attr\``,
+                );
+            }
+            if (node.computed) {
+                if (
+                    node.property.type !== "Literal" ||
+                    typeof node.property.value !== "string"
+                ) {
+                    throw new Error(
+                        "a computed `attr[...]` read needs a literal string shortcode",
+                    );
+                }
+                return readAttr(attrs, node.property.value);
+            }
+            return readAttr(attrs, node.property.name);
+        }
+        case "CallExpression": {
+            if (node.callee?.type !== "Identifier") {
+                throw new Error(
+                    "only direct calls to a named helper are supported",
+                );
+            }
+            const helper = HELPERS[node.callee.name];
+            if (!helper) {
+                throw new Error(
+                    `unknown helper "${node.callee.name}()" in a skill base formula`,
+                );
+            }
+            return helper(...node.arguments.map((a) => evalNode(a, attrs)));
+        }
+        case "BinaryExpression": {
+            const op = BINARY[node.operator];
+            if (!op) {
+                throw new Error(`unsupported operator "${node.operator}"`);
+            }
+            return op(evalNode(node.left, attrs), evalNode(node.right, attrs));
+        }
+        case "UnaryExpression": {
+            const value = evalNode(node.argument, attrs);
+            if (node.operator === "-") return -value;
+            if (node.operator === "+") return value;
+            throw new Error(`unsupported unary operator "${node.operator}"`);
+        }
+        case "ParenthesizedExpression":
+            return evalNode(node.expression, attrs);
+        default:
+            throw new Error(`unsupported expression node "${node.type}"`);
+    }
+}
+
+/**
+ * Evaluate a `skillBaseFormula` against an actor's attribute scores.
+ *
+ * Mirrors `SkillLogic.computeSkillBase`: an absent or blank formula is Skill
+ * Base `0` (not an error — a skill may legitimately have none), and the result
+ * is clamped to `>= 0`.
+ *
+ * @param {string|null|undefined} formula - The expression source.
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @returns {{ value: number, error?: string }} The Skill Base, or the reason it
+ *   could not be computed. On error `value` is `0`, matching the client.
+ */
+export function evaluateSkillBase(formula, attrs = {}) {
+    const source = typeof formula === "string" ? formula.trim() : "";
+    if (!source) return { value: 0 };
+    let node;
+    try {
+        const program = parse(source, { ecmaVersion: 2022 });
+        if (
+            program.body.length !== 1 ||
+            program.body[0].type !== "ExpressionStatement"
+        ) {
+            return {
+                value: 0,
+                error: `skill base formula "${source}" is not a single expression`,
+            };
+        }
+        node = program.body[0].expression;
+    } catch {
+        return {
+            value: 0,
+            error: `skill base formula "${source}" could not be parsed`,
+        };
+    }
+    try {
+        const raw = evalNode(node, attrs);
+        if (!Number.isFinite(raw)) {
+            return {
+                value: 0,
+                error: `skill base formula "${source}" did not return a number (got ${String(raw)})`,
+            };
+        }
+        return { value: Math.max(0, raw) };
+    } catch (err) {
+        return {
+            value: 0,
+            error: `skill base formula "${source}": ${err.message}`,
+        };
+    }
+}
+
+/**
+ * The mastery level an unopened skill opens at, or `null` when it does not
+ * open at all.
+ *
+ * The client's rule (`SkillLogic.initialize`) is `Skill Base × initSkillMult`,
+ * applied only when `masteryLevelBase` is unset and the skill is on an actor.
+ * Two build-side refinements, neither of which changes what a client computes:
+ *
+ * - **A zero or absent `initSkillMult` stays `null`.** The multiplier is the
+ *   switch for whether a skill opens at all, so writing the `0` the arithmetic
+ *   yields would claim the skill opened at zero rather than that it never
+ *   opened. `null` is what the field means by *not yet opened*, and the client
+ *   arrives at the same place either way.
+ * - **A fractional product is an error, not a rounding.** `masteryLevelBase` is
+ *   an integer field (`min: 0`), so a fractional value cannot be persisted
+ *   honestly — where the client multiplies raw into a modifier and is free to
+ *   carry the fraction, this is not. Reporting it follows
+ *   `resolveSkillAptitudes`, which rejects a fractional modifier rather than
+ *   rounding one.
+ *
+ * @param {object} system - The merged skill `system` block.
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @returns {{ value: number|null, error?: string }} The opening mastery level,
+ *   `null` to leave the field unset, or the reason it could not be computed.
+ */
+export function openingMasteryLevel(system = {}, attrs = {}) {
+    const mult = Number(system.initSkillMult);
+    if (!Number.isFinite(mult) || mult <= 0) return { value: null };
+
+    const base = evaluateSkillBase(system.skillBaseFormula, attrs);
+    if (base.error) return { value: null, error: base.error };
+
+    const opened = base.value * mult;
+    if (!Number.isInteger(opened)) {
+        return {
+            value: null,
+            error:
+                `opening mastery level is ${opened} (skill base ${base.value} × ` +
+                `initSkillMult ${mult}), but masteryLevelBase is a whole number — ` +
+                `give the skill a multiplier that divides evenly, or state its ` +
+                `masteryLevelBase outright`,
+        };
+    }
+    return { value: opened };
+}

package/types/content-config.d.mts

@@ -426,9 +426,9 @@ export type ContentBuildConfigInput = {
      */
     rootDir: string;
     /**
-     * Content package name — the value each
-     * content note carries in its `package:`
-     * frontmatter.
+     * Content package name — the address
+     * namespace every note in this
+     * repository is published under.
      */
     contentPackage: string;
     /**