@rpgm-tools/neo-angband-mod-sdk 0.13.0 → 0.15.0

package/README.md

@@ -21,9 +21,12 @@ compose records without pulling in a game.
 | Area | Exports |
 | --- | --- |
 | Manifests | `validateManifest`, `PackManifest`, `PackShape`, `packFacets`, `hasFacet`, `packRef`, `slugify` |
-| Load order | `resolveLoadOrder`, `satisfies` (the semver subset the manifests use) |
+| Load order | `resolveLoadOrder` (enforces), `satisfies` (the semver subset the manifests use) |
+| Auto-sort | `sortModOrder` (proposes, and cannot fail), `collectSortEdges`, `SortPin`, `SortTier`, `PACK_GROUPS` |
+| Sections | `resolveSectionState`, `expandSections`, `sectionFlag`, `PackSection`, `SECTION_BANDS` — the named parts of a mod |
+| Compatibility | `PackCompat`, `COMPAT_CLAIMS` — what an author may claim about another mod (never binding) |
 | Composition | `composePacks`, `composeContentPacks`, `mergePatch`, `applyFieldPatch`, `composeFieldPatches` |
-| Conflicts | `computeConflictReport`, `RecordConflict`, `FieldTouch`, `RecordOverride` |
+| Conflicts | `computeConflictReport` (records), `contestedSlots` / `describeContested` (every other layer), `Fold`, `foldDiscards` |
 | Record identity | `recordKey`, `keySpecFor`, `KEYED_RECORD_FILES`, `RECORD_KEY_SPECS` |
 | Capabilities | `CapabilitySet`, `parseCapability` — what a scripted plugin is allowed to reach |
 

package/dist/compose.d.ts

@@ -44,6 +44,23 @@ export interface FileContribution {
      * conflicts `patches` produces.
      */
     fieldPatches?: Record<string, FieldPatch>;
+    /**
+     * Contributions attributed to a NAMED PART of this pack, keyed by a section id
+     * the manifest declares (see PackSection). Each value is an ordinary
+     * FileContribution, so a section contributes exactly what the pack itself can.
+     *
+     * Nested rather than a `section` key on each entry because `patches`,
+     * `replaces` and `fieldPatches` are all keyed BY REF - there is no room for a
+     * per-entry tag without changing three shapes, and every existing pack would
+     * have had to be rewritten. This way an unsectioned contribution stays exactly
+     * where it is and belongs to the pack's implicit default part.
+     *
+     * composePacks never sees this: expandSections (sections.ts) drops the
+     * disabled sections and flattens the rest into the pack list, in band order,
+     * BEFORE composition. So a switched-off section is absent rather than
+     * overridden - the same rule a disabled mod's hooks follow.
+     */
+    sections?: Record<string, FileContribution>;
 }
 export interface PackContent {
     manifest: PackManifest;
@@ -62,10 +79,52 @@ export declare class ComposeError extends Error {
 }
 /** Deep merge per the pack patch rules. Returns a new object. */
 export declare function mergePatch(base: JsonRecord, patch: JsonRecord): JsonRecord;
+/**
+ * How composePacks should react to a contribution it cannot honour.
+ *
+ * WHY THIS IS AN OPTION AND NOT A DECISION. The same event has two right answers
+ * depending on who is watching. A mod's BUILD should stop dead on a patch aimed
+ * at nothing, because the author is right there and a silent no-op is the worst
+ * thing you can hand them. A player's GAME should not: their mod was fine when it
+ * was published and the record it patches has since moved, and taking the whole
+ * mod away - or the whole game - is a punishment for the engine's change.
+ *
+ * So the throwing behaviour stays the default (every existing caller and the
+ * author-facing tooling keep it) and the host passes a reporter.
+ */
+export interface ComposePacksOptions {
+    /**
+     * Called instead of throwing, with the offending pack's id kept separate from
+     * the sentence so a host can put the line on that mod's own row. The
+     * contribution is then SKIPPED and composition continues.
+     */
+    readonly onRefuse?: (packId: string, why: string) => void;
+}
+/**
+ * The tail every "no such record" refusal carries, in both merge phases.
+ *
+ * Said because the likeliest cause is not a typo. A pack that composed when it
+ * was published and does not now is usually pointing at a record the engine or
+ * another pack has since renamed, and an author reading "does not exist" about a
+ * ref they know they got right will go looking in the wrong place.
+ */
+export declare const RENAMED_HINT = " - it may have been renamed or removed by a newer version of the pack that owns it";
 /**
  * Compose packs (already in resolved load order) into per-file record
  * maps. Iteration order of each map is deterministic: records appear
  * in the order their owning packs added them.
+ *
+ * ONE BROKEN OP COSTS THAT OP, when `onRefuse` is supplied. Until 2026-08-02 the
+ * only behaviour was to throw, and the caller that mattered - composeContentPacks
+ * on the web host - sat under composeDroppingBroken, which answers a throw by
+ * removing the whole PACK. The result was an asymmetry nobody chose: the 20
+ * passthrough record files reported a missing ref and carried on, and the 24
+ * composable ones took the entire mod down for the same author mistake. A mod
+ * patching forty monsters lost all forty, plus its code and its rules, because
+ * one of the forty had been renamed in the engine.
+ *
+ * That is also the difference between an engine patch that costs mod authors a
+ * release and one that costs them nothing, which is the property this exists for.
  */
-export declare function composePacks(packs: readonly PackContent[]): Map<string, Map<PackRef, ComposedRecord>>;
+export declare function composePacks(packs: readonly PackContent[], options?: ComposePacksOptions): Map<string, Map<PackRef, ComposedRecord>>;
 //# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACjC,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAkB1E;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,WAAW,EAAE,GAC5B,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CA4E3C"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACjC,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAkB1E;AAWD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,uFAC6D,CAAC;AAUvF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,mBAAwB,GAChC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CA8F3C"}

package/dist/compose.js

@@ -47,43 +47,94 @@ function ownerOf(ref) {
     const at = ref.indexOf(":");
     return at === -1 ? "" : ref.slice(0, at);
 }
+/**
+ * The tail every "no such record" refusal carries, in both merge phases.
+ *
+ * Said because the likeliest cause is not a typo. A pack that composed when it
+ * was published and does not now is usually pointing at a record the engine or
+ * another pack has since renamed, and an author reading "does not exist" about a
+ * ref they know they got right will go looking in the wrong place.
+ */
+export const RENAMED_HINT = " - it may have been renamed or removed by a newer version of the pack that owns it";
+/** How a refused op reads, matched to the passthrough path's wording. */
+const REF_VERB = {
+    patches: "patches",
+    replaces: "replaces",
+    fieldPatches: "fieldPatches",
+    removes: "removes",
+};
 /**
  * Compose packs (already in resolved load order) into per-file record
  * maps. Iteration order of each map is deterministic: records appear
  * in the order their owning packs added them.
+ *
+ * ONE BROKEN OP COSTS THAT OP, when `onRefuse` is supplied. Until 2026-08-02 the
+ * only behaviour was to throw, and the caller that mattered - composeContentPacks
+ * on the web host - sat under composeDroppingBroken, which answers a throw by
+ * removing the whole PACK. The result was an asymmetry nobody chose: the 20
+ * passthrough record files reported a missing ref and carried on, and the 24
+ * composable ones took the entire mod down for the same author mistake. A mod
+ * patching forty monsters lost all forty, plus its code and its rules, because
+ * one of the forty had been renamed in the engine.
+ *
+ * That is also the difference between an engine patch that costs mod authors a
+ * release and one that costs them nothing, which is the property this exists for.
  */
-export function composePacks(packs) {
+export function composePacks(packs, options = {}) {
     const game = new Map();
+    const onRefuse = options.onRefuse;
     for (const pack of packs) {
         const pid = pack.manifest.id;
+        /** Report and skip, or throw when nobody is listening. Returns false either way. */
+        const refuse = (why, thrown) => {
+            if (!onRefuse)
+                throw new ComposeError(`${pid}/${thrown}`);
+            onRefuse(pid, why);
+            return false;
+        };
         for (const [file, contrib] of Object.entries(pack.files)) {
             let table = game.get(file);
             if (!table) {
                 table = new Map();
                 game.set(file, table);
             }
+            /**
+             * Can `pid` touch `ref`, and does it exist? Reports the same two reasons
+             * the passthrough path reports, in the same words, so one mod's row does
+             * not read differently depending on which of the two merge phases its file
+             * happened to land in.
+             */
+            const addressable = (kind, ref) => {
+                const verb = REF_VERB[kind];
+                if (!table.has(ref)) {
+                    const noun = kind === "removes" ? "remove" : kind === "replaces" ? "replace" : kind === "patches" ? "patch" : "fieldPatch";
+                    return refuse(`${file} ${verb} "${ref}", but no such record exists in ${file} (identity is the record's name)${RENAMED_HINT}`, `${file}: ${noun} target ${ref} does not exist`);
+                }
+                if (!mayModify(pack.manifest, ownerOf(ref))) {
+                    const act = kind === "removes" ? "remove" : "modify";
+                    return refuse(`${file} ${verb} "${ref}", but ${pid} does not declare ${ownerOf(ref)} as a dependency`, `${file}: cannot ${act} ${ref} without declaring ${ownerOf(ref)} as a dependency`);
+                }
+                return true;
+            };
             for (const rec of contrib.records ?? []) {
                 const name = rec["name"];
                 if (typeof name !== "string" || name.length === 0) {
-                    throw new ComposeError(`${pid}/${file}: record without a name`);
+                    refuse(`${file} contributes a record with no "name", so nothing can address it and it was left out`, `${file}: record without a name`);
+                    continue;
                 }
                 const ref = packRef(pid, name);
                 if (table.has(ref)) {
-                    throw new ComposeError(`${pid}/${file}: duplicate record ${ref}`);
+                    refuse(`${file} adds two records that both resolve to "${ref}", so the second was left out`, `${file}: duplicate record ${ref}`);
+                    continue;
                 }
                 table.set(ref, { ref, owner: pid, modifiedBy: [], value: rec });
             }
             for (const kind of ["patches", "replaces"]) {
                 for (const [refStr, body] of Object.entries(contrib[kind] ?? {})) {
                     const ref = refStr;
+                    if (!addressable(kind, ref))
+                        continue;
                     const existing = table.get(ref);
-                    if (!existing) {
-                        const verb = kind === "patches" ? "patch" : "replace";
-                        throw new ComposeError(`${pid}/${file}: ${verb} target ${ref} does not exist`);
-                    }
-                    if (!mayModify(pack.manifest, ownerOf(ref))) {
-                        throw new ComposeError(`${pid}/${file}: cannot modify ${ref} without declaring ${ownerOf(ref)} as a dependency`);
-                    }
                     existing.value =
                         kind === "patches" ? mergePatch(existing.value, body) : body;
                     existing.modifiedBy.push(pid);
@@ -91,24 +142,16 @@ export function composePacks(packs) {
             }
             for (const [refStr, ops] of Object.entries(contrib.fieldPatches ?? {})) {
                 const ref = refStr;
+                if (!addressable("fieldPatches", ref))
+                    continue;
                 const existing = table.get(ref);
-                if (!existing) {
-                    throw new ComposeError(`${pid}/${file}: fieldPatch target ${ref} does not exist`);
-                }
-                if (!mayModify(pack.manifest, ownerOf(ref))) {
-                    throw new ComposeError(`${pid}/${file}: cannot modify ${ref} without declaring ${ownerOf(ref)} as a dependency`);
-                }
                 existing.value = applyFieldPatch(existing.value, ops);
                 existing.modifiedBy.push(pid);
             }
             for (const refStr of contrib.removes ?? []) {
                 const ref = refStr;
-                if (!table.has(ref)) {
-                    throw new ComposeError(`${pid}/${file}: remove target ${ref} does not exist`);
-                }
-                if (!mayModify(pack.manifest, ownerOf(ref))) {
-                    throw new ComposeError(`${pid}/${file}: cannot remove ${ref} without declaring ${ownerOf(ref)} as a dependency`);
-                }
+                if (!addressable("removes", ref))
+                    continue;
                 table.delete(ref);
             }
         }

package/dist/compose.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"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"}

package/dist/contested.d.ts

@@ -0,0 +1,126 @@
+/**
+ * One conflict report over every composition layer.
+ *
+ * WHAT WAS WRONG. `computeConflictReport` (conflicts.ts) walks `pack.files`, so
+ * it sees CONTENT RECORDS and nothing else. Four other layers collided in
+ * complete silence:
+ *
+ *  - GRAPHICS: two mods claiming one grafID. Nothing said so, and until
+ *    2026-08-01 the loser was the LATER mod, backwards from every other layer.
+ *  - BEHAVIOUR: two mods contributing the same ModHooks member. For a
+ *    last-answer hook the earlier mod's rule simply never runs, and until
+ *    2026-08-02 it was the LATER mod's that did not, backwards from the row the
+ *    player reads.
+ *  - RULES: two mods declaring the same flag string. `resolveModRules` is a flat
+ *    last-wins namespace, so one mod silently reads the other's toggle.
+ *  - CONTROLLER: two mods shipping an autoplayer. There is one slot; the second
+ *    install wins and the first is not told.
+ *
+ * A report that sees one layer of five cannot be the substrate for author-
+ * declared conflict resolution, which is what this whole model needs it to be.
+ *
+ * WHY THE FOLD IS PART OF THE ANSWER. The layers do not resolve the same way and
+ * pretending they do would be the RimWorld trap - XML, then xpath, then C#, each
+ * with its own effective precedence, so "load order" quietly means three
+ * different things. Here the report NAMES the fold, because "these two combine"
+ * and "one of these is being ignored" are different news for the player and only
+ * one of them needs acting on.
+ *
+ * DERIVED, NOT DECLARED. Every claim is observed from what a mod actually
+ * contributes - the refs in its files, the hooks its factory returned, the
+ * grafIDs its manifest claims, the controller it handed over. A `touches` field
+ * in the manifest would have been easier and would drift the first time an
+ * author forgot to update it, which is the failure this report exists to catch.
+ */
+/** Which composition layer a contested slot belongs to. */
+export type ContestedLayer = "record" | "graphics" | "behaviour" | "rule" | "controller";
+/**
+ * How a layer resolves several claims on one slot.
+ *
+ * EVERY ONE OF THESE IS "THE LATER MOD WINS", which is the point: the mod
+ * manager promises the player one lever ("Move later (loads last, wins
+ * conflicts)"), and a lever that means five different things is not a lever. The
+ * folds differ only in whether there is anything for a winner to win.
+ *
+ * The three that DISCARD a claim - `last-wins`, `last-answer`, `single-slot` -
+ * are the ones worth a player's attention; the rest combine, and are reported so
+ * the picture is complete rather than because anything is wrong.
+ */
+export type Fold = "last-wins" | "last-answer" | "single-slot" | "all-must-agree" | "chained" | "any-yes";
+/** Whether a fold silently drops somebody's contribution. */
+export declare function foldDiscards(fold: Fold): boolean;
+/** One mod's claim on one slot. */
+export interface Claim {
+    /** The pack that contributed. */
+    packId: string;
+    /** The section it came from, when the pack attributed it to one. */
+    sectionId?: string;
+    /**
+     * Set when a section's band moved this claim away from its pack's own
+     * position, so the report can explain an order the load list does not show.
+     */
+    band?: string;
+}
+/** One thing more than one mod contributed to. */
+export interface ContestedSlot {
+    layer: ContestedLayer;
+    /** Stable identity, for deduping and tests: "core:kobold.speed", "graphics:2". */
+    key: string;
+    /** What a player would call it: "kobold's speed", "the Graphics row for mode 2". */
+    what: string;
+    /** How this layer resolves the claims, and therefore whether one is discarded. */
+    fold: Fold;
+    /** Every claim, in load order. */
+    claims: Claim[];
+    /** The pack whose claim takes effect, when the fold picks one. */
+    winner?: string;
+}
+/** A pack's display name, for lines a player reads; falls back to the id. */
+export type NameOf = (packId: string) => string;
+/**
+ * One plain-language line per contested slot.
+ *
+ * Written so the sentence tells the player whether to DO anything: a discarding
+ * fold names the loser and the lever that changes it, a combining fold says the
+ * contributions stack. A line that just says "conflict" is what makes players
+ * stop reading conflict lists.
+ */
+export declare function describeContested(slot: ContestedSlot, nameOf?: NameOf): string;
+/**
+ * Build the contested slots for one layer from a flat list of claims.
+ *
+ * `claims` is every claim on every key of that layer, IN LOAD ORDER. Keys with a
+ * single claimant are dropped - one mod changing something is not a conflict,
+ * and listing it would bury the ones that are.
+ *
+ * Two claims from the SAME pack on one key do not contest each other: a pack
+ * whose base contributions and one of its own sections both touch a field has
+ * made one decision in two places, and the pack's own order settles it.
+ */
+export declare function contestedSlots(layer: ContestedLayer, fold: Fold, claims: readonly {
+    key: string;
+    what: string;
+    claim: Claim;
+}[]): ContestedSlot[];
+/**
+ * An author's `conflicts` claim that applies to the current mod set.
+ *
+ * Carried separately from the contested slots because it is a DECLARATION rather
+ * than an observation: nobody measured a collision, an author stated one. It is
+ * shown with their reason attached and it never blocks - ratified decision 18,
+ * the engine labels and does not forbid, and a third-party author does not get a
+ * veto over the player's setup.
+ */
+export interface DeclaredConflict {
+    /** The pack making the claim. */
+    packId: string;
+    /** The pack it names. */
+    with: string;
+    /** The claimant's own sections the claim is about, if it scoped itself. */
+    scope?: string[];
+    /** The author's stated reason. */
+    because: string;
+}
+/** The warning line for a declared conflict. */
+export declare function describeDeclaredConflict(conflict: DeclaredConflict, nameOf?: NameOf): string;
+//# sourceMappingURL=contested.d.ts.map

package/dist/contested.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contested.d.ts","sourceRoot":"","sources":["../src/contested.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,UAAU,GACV,WAAW,GACX,MAAM,GACN,YAAY,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,IAAI,GACZ,WAAW,GACX,aAAa,GACb,aAAa,GACb,gBAAgB,GAChB,SAAS,GACT,SAAS,CAAC;AAEd,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEhD;AAED,mCAAmC;AACnC,MAAM,WAAW,KAAK;IACpB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,EAAE,IAAI,CAAC;IACX,kCAAkC;IAClC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAehD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,MAAmB,GAAG,MAAM,CA0B1F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,EAAE,GAC7D,aAAa,EAAE,CA6BjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gDAAgD;AAChD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,GAAE,MAAmB,GAC1B,MAAM,CAGR"}

package/dist/contested.js

@@ -0,0 +1,131 @@
+/**
+ * One conflict report over every composition layer.
+ *
+ * WHAT WAS WRONG. `computeConflictReport` (conflicts.ts) walks `pack.files`, so
+ * it sees CONTENT RECORDS and nothing else. Four other layers collided in
+ * complete silence:
+ *
+ *  - GRAPHICS: two mods claiming one grafID. Nothing said so, and until
+ *    2026-08-01 the loser was the LATER mod, backwards from every other layer.
+ *  - BEHAVIOUR: two mods contributing the same ModHooks member. For a
+ *    last-answer hook the earlier mod's rule simply never runs, and until
+ *    2026-08-02 it was the LATER mod's that did not, backwards from the row the
+ *    player reads.
+ *  - RULES: two mods declaring the same flag string. `resolveModRules` is a flat
+ *    last-wins namespace, so one mod silently reads the other's toggle.
+ *  - CONTROLLER: two mods shipping an autoplayer. There is one slot; the second
+ *    install wins and the first is not told.
+ *
+ * A report that sees one layer of five cannot be the substrate for author-
+ * declared conflict resolution, which is what this whole model needs it to be.
+ *
+ * WHY THE FOLD IS PART OF THE ANSWER. The layers do not resolve the same way and
+ * pretending they do would be the RimWorld trap - XML, then xpath, then C#, each
+ * with its own effective precedence, so "load order" quietly means three
+ * different things. Here the report NAMES the fold, because "these two combine"
+ * and "one of these is being ignored" are different news for the player and only
+ * one of them needs acting on.
+ *
+ * DERIVED, NOT DECLARED. Every claim is observed from what a mod actually
+ * contributes - the refs in its files, the hooks its factory returned, the
+ * grafIDs its manifest claims, the controller it handed over. A `touches` field
+ * in the manifest would have been easier and would drift the first time an
+ * author forgot to update it, which is the failure this report exists to catch.
+ */
+/** Whether a fold silently drops somebody's contribution. */
+export function foldDiscards(fold) {
+    return fold === "last-wins" || fold === "last-answer" || fold === "single-slot";
+}
+/** "frost", "frost and runes", "frost, runes and mist". */
+function joinNames(names) {
+    if (names.length <= 1)
+        return names.join("");
+    if (names.length === 2)
+        return `${names[0]} and ${names[1]}`;
+    return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+/** "frost" or "frost (kobold rebalance)" when the claim named a section. */
+function claimName(claim, nameOf) {
+    const base = nameOf(claim.packId);
+    return claim.sectionId ? `${base} (${claim.sectionId})` : base;
+}
+/**
+ * One plain-language line per contested slot.
+ *
+ * Written so the sentence tells the player whether to DO anything: a discarding
+ * fold names the loser and the lever that changes it, a combining fold says the
+ * contributions stack. A line that just says "conflict" is what makes players
+ * stop reading conflict lists.
+ */
+export function describeContested(slot, nameOf = (id) => id) {
+    const names = slot.claims.map((c) => claimName(c, nameOf));
+    const who = joinNames(names);
+    const winner = slot.winner ? nameOf(slot.winner) : undefined;
+    /* A band that repositioned the winning claim is the one thing the load-order
+     * list cannot show, so it is worth a clause of its own. */
+    const winning = slot.claims.find((c) => c.packId === slot.winner);
+    const banded = winning?.band && winning.band !== "normal"
+        ? ` (its "${winning.sectionId}" part is set to load ${winning.band})`
+        : "";
+    switch (slot.fold) {
+        case "last-wins":
+            return `${who} all change ${slot.what}; ${winner} wins${banded} because it loads last.`;
+        case "last-answer":
+            return `${who} all handle ${slot.what}; only ${winner} runs${banded} because it loads last - the rest never get asked.`;
+        case "single-slot":
+            return `${who} each provide ${slot.what}, and there is room for one; ${winner} takes it${banded} and the others do nothing.`;
+        case "all-must-agree":
+            return `${who} all have a say in ${slot.what}; every one of them has to agree, so any single refusal decides.`;
+        case "chained":
+            return `${who} all change ${slot.what}, in load order, each one seeing the last one's result.`;
+        case "any-yes":
+            return `${who} all ask for ${slot.what}; one asking is enough, so they do not conflict.`;
+    }
+}
+/**
+ * Build the contested slots for one layer from a flat list of claims.
+ *
+ * `claims` is every claim on every key of that layer, IN LOAD ORDER. Keys with a
+ * single claimant are dropped - one mod changing something is not a conflict,
+ * and listing it would bury the ones that are.
+ *
+ * Two claims from the SAME pack on one key do not contest each other: a pack
+ * whose base contributions and one of its own sections both touch a field has
+ * made one decision in two places, and the pack's own order settles it.
+ */
+export function contestedSlots(layer, fold, claims) {
+    const byKey = new Map();
+    for (const entry of claims) {
+        const slot = byKey.get(entry.key) ?? { what: entry.what, claims: [] };
+        slot.claims.push(entry.claim);
+        byKey.set(entry.key, slot);
+    }
+    const out = [];
+    for (const [key, slot] of byKey) {
+        const packs = new Set(slot.claims.map((c) => c.packId));
+        if (packs.size < 2)
+            continue;
+        /* Every discarding fold now picks the SAME claim - the last one - which is
+         * the property this whole model is for. Kept as a `foldDiscards` test rather
+         * than collapsed into "last unless undefined", so adding a fold that picks
+         * differently has to come here and say so. */
+        const winner = foldDiscards(fold)
+            ? slot.claims[slot.claims.length - 1]?.packId
+            : undefined;
+        out.push({
+            layer,
+            key,
+            what: slot.what,
+            fold,
+            claims: slot.claims,
+            ...(winner === undefined ? {} : { winner }),
+        });
+    }
+    return out;
+}
+/** The warning line for a declared conflict. */
+export function describeDeclaredConflict(conflict, nameOf = (id) => id) {
+    const where = conflict.scope?.length ? ` over ${conflict.scope.join(", ")}` : "";
+    return `${nameOf(conflict.packId)} says it conflicts with ${nameOf(conflict.with)}${where}: ${conflict.because}`;
+}
+//# sourceMappingURL=contested.js.map

package/dist/contested.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contested.js","sourceRoot":"","sources":["../src/contested.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -27,6 +27,21 @@
  * A pack can fail either, both, or neither, and the reasons a player must read are
  * different in each case - so this returns a discriminated verdict rather than a
  * boolean, and the caller keeps them apart.
+ *
+ * AND A FAILED RANGE IS NOT ALWAYS A REFUSAL (2026-08-02). Ratified decision 18
+ * is that the engine LABELS and does not FORBID, and this gate was applying it
+ * backwards: an out-of-range `engine` refused to load a pack of JSON that would
+ * have composed perfectly well. Nothing in a data pack's manifest can make its
+ * data unloadable - the worst case is a patch aimed at a record that has since
+ * moved, and composePacks now reports that one op and keeps the rest.
+ *
+ * So the range is a GATE on a pack that ships code and a LABEL on one that does
+ * not, and `modApi` is the signal, because the manifest already requires it of
+ * exactly the packs that ship a plugin.js. Code is the thing that genuinely
+ * breaks across an engine release: it calls functions, and a function that has
+ * been renamed is a crash rather than a warning. This is the difference between
+ * an engine patch that costs every content author a release and one that costs
+ * them nothing, which is the whole reason the distinction is here.
  */
 import type { PackManifest } from "./manifest.js";
 /**
@@ -43,6 +58,18 @@ export type EngineVerdict = {
 } | {
     readonly ok: false;
     readonly kind: "out-of-range" | "bad-manifest";
+    /**
+     * Whether this is a REFUSAL or a warning to show beside a pack that loads
+     * anyway. True exactly when the pack ships code (`modApi` is declared).
+     *
+     * Separate from `ok` rather than folded into it, because a caller that
+     * only wants to know "did the versions line up" and a caller deciding "do I
+     * load this" are asking different questions, and collapsing them is how the
+     * warning would end up either suppressed or treated as fatal. `ok: false,
+     * blocks: false` is a real and common state: the pack loads, and the player
+     * is told why it might misbehave.
+     */
+    readonly blocks: boolean;
     readonly why: string;
 };
 /**
@@ -58,5 +85,14 @@ export type EngineVerdict = {
  * Pure, and takes the version as an argument rather than importing it, so a test
  * can drive any build and so mod-sdk stays independent of core.
  */
-export declare function engineVerdict(manifest: Pick<PackManifest, "engine">, engineVersion: string): EngineVerdict;
+export declare function engineVerdict(manifest: Pick<PackManifest, "engine" | "modApi">, engineVersion: string, 
+/**
+ * Whether this pack ships CODE, and therefore whether a mismatch is a gate or
+ * a label. Defaults to what the manifest says, and is overridable for the one
+ * caller that knows better: the plugin loader is holding a plugin.js it can
+ * see, and it runs this gate BEFORE it checks whether `modApi` was declared at
+ * all - so a code pack that forgot the field must not buy the lenient path
+ * with the omission.
+ */
+hasCode?: boolean): EngineVerdict;
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAAC;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAIN;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,EACtC,aAAa,EAAE,MAAM,GACpB,aAAa,CAuCf"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAIN;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,QAAQ,CAAC,EACjD,aAAa,EAAE,MAAM;AACrB;;;;;;;GAOG;AACH,OAAO,GAAE,OAAuC,GAC/C,aAAa,CA0Df"}