@heroiclands/package-build 3.2.0 → 3.4.0

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;
     /**

package/types/engine/base-compiler.d.mts

@@ -1,11 +1,19 @@
 /**
  * The tallies one pass accumulates while walking the tree.
  *
+ * `declined` and `skippedOther` are deliberately separate numbers. A declined
+ * note is one this build **refused** — it names a package this repository does
+ * not compile — and it is an error; a skipped one legitimately belongs to
+ * another pass, and there are thousands of those. Folding the first into the
+ * second is what let a whole tree be filtered out in silence (#56).
+ *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedDraft - Notes marked `draft: true`.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
+ * @property {number} declined - Notes refused because they declare another
+ *   package. Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -136,8 +144,9 @@ export class BasePackCompiler {
     /**
      * Whether this pass claims a note. **Required.**
      *
-     * Called only for a note of the configured content package, so a subclass
-     * decides on `type` alone.
+     * Called only for a note this build compiles — every note in the tree
+     * belongs to the configured content package (#56) — so a subclass decides
+     * on `type` alone.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True to compile it.
@@ -299,6 +308,12 @@ export class BasePackCompiler {
 }
 /**
  * The tallies one pass accumulates while walking the tree.
+ *
+ * `declined` and `skippedOther` are deliberately separate numbers. A declined
+ * note is one this build **refused** — it names a package this repository does
+ * not compile — and it is an error; a skipped one legitimately belongs to
+ * another pass, and there are thousands of those. Folding the first into the
+ * second is what let a whole tree be filtered out in silence (#56).
  */
 export type PassStats = {
     /**
@@ -317,4 +332,9 @@ export type PassStats = {
      * - Notes this pass does not claim.
      */
     skippedOther: number;
+    /**
+     * - Notes refused because they declare another
+     * package. Counted as errors, never as skips.
+     */
+    declined: number;
 };

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

@@ -1,10 +1,23 @@
 /**
- * The **content** package: the distribution unit a note declares in its
- * `package:` frontmatter. The pack compilers select their entries by it.
+ * 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
+ * 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
+ * configuration, whatever else changes.
+ *
+ * It was also, until #56, a **selector**: a note declared the same value in its
+ * `package:` frontmatter and the compilers kept the ones that matched. Every
+ * content tree is single-package — each is single-sourced in the repository that
+ * ships it — so the field restated this constant once per note while a value
+ * that matched nothing filtered the whole tree out in silence. The field is
+ * being retired; the value stays, here, where it is declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
- * second game system, its notes would still declare `package: sohl` — only the
- * Foundry package below would differ.
+ * second game system, it would still be published as `sohl` — only the Foundry
+ * package below would differ.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -18,7 +31,7 @@ export function contentPackage(): string;
  * compendium UUID the compilers emit.
  *
  * Distinct from {@link contentPackage}, and equal to it only by coincidence
- * here: a note says `package: sohl` and its documents are addressed as
+ * here: a note is published under `sohl` and its documents are addressed as
  * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
  * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
  * than one — treating them as interchangeable is what #1498 was.

package/types/engine/generate.d.mts

@@ -20,9 +20,9 @@ export function itemPackJsonDirs(config?: object): string[];
  * The passes that compiled nothing when they were expected to compile
  * something — a build failure, not a quiet no-op.
  *
- * A pack compiler selects its entries by the configured content package, so a
- * single wrong package id rejects every note in a perfectly good tree and every
- * pack ships blank while the build exits 0 (#1502). The empty-tree guard in
+ * A pack ships blank whenever every note in a full tree was rejected — by a
+ * `selects` that claims nothing, or a `pack:` that routes everything elsewhere
+ * — and the build then exits 0 (#1502). The empty-tree guard in
  * {@link generatePacksJson} cannot see that: the tree is full, it is the
  * *output* that is empty.
  *

package/types/engine/helpers.d.mts

@@ -274,14 +274,17 @@ export function collectContentDocs(contentBase: string): Array<{
  * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
  * are resolved — so a generated cell may itself be a wikilink.
  *
- * A table searches only notes of the source note's own `package`, so a SoHL
- * page never tabulates setting-package content (and vice versa).
+ * A table searches only notes of the source note's own package, so a SoHL page
+ * never tabulates setting-package content (and vice versa). Each candidate's
+ * package is **derived** rather than read out of its frontmatter: `package:` is
+ * optional, and comparing a declared value with an absent one would drop every
+ * unswept — or every swept — note from the table (#56).
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
  * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
  * @param {string} ctx.name - The note, for the error message.
- * @param {string} [ctx.pkg] - The source note's `package`.
+ * @param {string} [ctx.pkg] - The source note's package.
  * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,

package/types/engine/index.d.mts

@@ -5,6 +5,7 @@ export * as contentTree from "./content-tree.mjs";
 export * as packConfig from "./pack-config.mjs";
 export * as packRouter from "./pack-router.mjs";
 export * as contentPackage from "./content-package.mjs";
+export * as notePackage from "./note-package.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";

package/types/engine/macros.d.mts

@@ -122,8 +122,8 @@ export const DEFAULT_MACRO_IMG: "icons/svg/dice-target.svg";
 /**
  * Macros pack compiler.
  *
- * Walks the content tree and compiles every `package: sohl`, `type: macro`
- * note into one Macro document. The same note's documentation is compiled by
+ * Walks the content tree and compiles every `type: macro` note into one Macro
+ * document. The same note's documentation is compiled by
  * the journals pass; neither pass reads the other's output.
  */
 export class Macros extends BasePackCompiler {

package/types/engine/manifest-emit.d.mts

@@ -39,9 +39,12 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  *
  * Drafts are excluded because the site does not publish them, and an entry for
  * an unpublished page is exactly the dead link the manifest exists to prevent.
- * A note belonging to another content package is skipped for the same reason in
- * reverse: this build is not authoritative for it, and its own build says where
- * it lives.
+ *
+ * Every note in the tree is this package's note, whether or not it says so:
+ * `package:` is optional and merely has to agree (#56). A note naming a
+ * different package **throws** rather than being skipped — this build is not
+ * authoritative for it, and skipping it silently is how a whole tree came to be
+ * filtered out of a manifest that then claimed the package published nothing.
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an

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

@@ -0,0 +1,54 @@
+/**
+ * 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: object | null | undefined, configured?: string): string;
+/**
+ * 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: object | null | undefined, configured?: string): object | null | undefined;
+/**
+ * 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: object | null | undefined, { file, configured }?: {
+    file?: string | undefined;
+    configured?: string | undefined;
+}): string;

package/types/engine/pack-router.d.mts

@@ -46,8 +46,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/types/engine/site-build.d.mts

@@ -16,7 +16,9 @@ export function walkSiteTree(dir: string, skip?: readonly string[]): string[];
  * 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: string, ctx: object): {
@@ -82,6 +84,16 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
  *
+ * A content page carries the package the build **derived**, whether or not the
+ * note declared one (#65). `package:` became optional in 3.3.0, so a swept tree
+ * declares none — and the note's frontmatter alone would then publish a page
+ * that does not say which package it belongs to. The emitted page is what a
+ * theme reads: `breadcrumbs.html` builds its middle crumb from
+ * `.Params.package`, so without it that crumb degrades from a linked, labelled
+ * section to a bare type slug. Writing the derived value keeps a page
+ * self-describing and makes sweeping the field out of a content tree
+ * output-preserving for a site as it already is for the packs.
+ *
  * @param {object} page - The page.
  * @param {object} options - `{ sections, readmeSections, decorate }`.
  * @returns {object} The frontmatter to write.

package/types/sohl/actors.d.mts

@@ -25,6 +25,33 @@ export class Actors extends BasePackCompiler {
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
      */
     buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): any[];
+    /**
+     * 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: object[], ctx: string): void;
     buildBeing(itemsMap: any, fm: any, body: any): {
         name: any;
         type: string;

package/types/sohl/skill-base.d.mts

@@ -0,0 +1,53 @@
+/**
+ * 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: number[]): number;
+/**
+ * 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: string | null | undefined, attrs?: Record<string, number>): {
+    value: number;
+    error?: string;
+};
+/**
+ * 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?: object, attrs?: Record<string, number>): {
+    value: number | null;
+    error?: string;
+};