modwright 0.1.0

package/dist/surfaces/baldursgate3/modsettings.js

@@ -0,0 +1,115 @@
+export const BASE_MODULES = new Set([
+    "gustav",
+    "gustavdev",
+    "gustavx",
+    "shared",
+    "shareddev",
+    "honour",
+    "honourx",
+    "engine",
+    "mainui",
+    "modbrowser",
+    "fw3",
+    "dicesets",
+]);
+export function isBaseModule(name) {
+    return BASE_MODULES.has(name.toLowerCase());
+}
+export function parseModSettings(xml) {
+    const withoutComments = xml.replace(/<!--[\s\S]*?-->/g, "");
+    const entries = [];
+    let index = 0;
+    for (const node of withoutComments.matchAll(/<node\s+id="ModuleShortDesc">([\s\S]*?)<\/node>/g)) {
+        const body = node[1] ?? "";
+        const name = attr(body, "Name");
+        if (!name)
+            continue;
+        const entry = {
+            name,
+            uuid: attr(body, "UUID") ?? "",
+            index: index++,
+        };
+        const folder = attr(body, "Folder");
+        if (folder !== undefined)
+            entry.folder = folder;
+        const version = attr(body, "Version64") ?? attr(body, "Version");
+        if (version !== undefined)
+            entry.version = version;
+        entries.push(entry);
+    }
+    return entries;
+}
+export function diffModSettings(before, after) {
+    const beforeEntries = parseModSettings(before);
+    const afterEntries = parseModSettings(after);
+    const beforeKeys = new Map(beforeEntries.map((e) => [keyOf(e), e]));
+    const afterKeys = new Map(afterEntries.map((e) => [keyOf(e), e]));
+    const removed = beforeEntries.filter((e) => !afterKeys.has(keyOf(e)));
+    const added = afterEntries.filter((e) => !beforeKeys.has(keyOf(e)));
+    const commonBefore = beforeEntries.map(keyOf).filter((k) => afterKeys.has(k));
+    const commonAfter = afterEntries.map(keyOf).filter((k) => beforeKeys.has(k));
+    const reordered = commonBefore.some((key, i) => commonAfter[i] !== key);
+    const userModsBefore = beforeEntries.filter((e) => !isBaseModule(e.name));
+    const userModsAfter = afterEntries.filter((e) => !isBaseModule(e.name));
+    const baseGameOnlyLeft = userModsBefore.length > 0 && userModsAfter.length === 0;
+    return { removed, added, reordered, baseGameOnlyLeft };
+}
+export function describeModSettingsDiff(diff) {
+    const removedUser = diff.removed.filter((e) => !isBaseModule(e.name));
+    const removedBase = diff.removed.filter((e) => isBaseModule(e.name));
+    const addedUser = diff.added.filter((e) => !isBaseModule(e.name));
+    const sentences = [];
+    if (removedUser.length > 0) {
+        sentences.push(`The game dropped ${count(removedUser.length, "user mod")} from modsettings.lsx on ` +
+            `launch: ${list(removedUser)}${removedBase.length > 0
+                ? `, along with ${count(removedBase.length, "base-game module")}`
+                : ""}.`);
+    }
+    else if (removedBase.length > 0) {
+        sentences.push(`The game dropped ${count(removedBase.length, "base-game module")} from ` +
+            `modsettings.lsx on launch (${list(removedBase)}) but left every user mod in place.`);
+    }
+    else if (addedUser.length > 0 && diff.reordered) {
+        sentences.push(`Nothing was dropped from modsettings.lsx: ${count(addedUser.length, "user mod")} was ` +
+            `added (${list(addedUser)}) and the remaining entries changed order.`);
+    }
+    else if (addedUser.length > 0) {
+        sentences.push(`Nothing was dropped from modsettings.lsx; ${count(addedUser.length, "user mod")} was ` +
+            `added (${list(addedUser)}).`);
+    }
+    else if (diff.reordered) {
+        sentences.push("Nothing was dropped from modsettings.lsx, but the entries came back in a different " +
+            "order than they went in.");
+    }
+    else {
+        sentences.push("modsettings.lsx came back unchanged: same entries, same order.");
+    }
+    if (diff.baseGameOnlyLeft) {
+        sentences.push("Only base-game modules are left, so the game reset the profile to a clean one rather " +
+            "than dropping a single entry.");
+    }
+    if (removedUser.length > 0 || diff.baseGameOnlyLeft || diff.reordered) {
+        sentences.push("An order that reverts itself usually means a missing or renamed pak; the crash guard " +
+            "can also disable a mod while it stays listed.");
+    }
+    return sentences.join(" ");
+}
+function attr(body, id) {
+    const match = body.match(new RegExp(`<attribute\\s+id="${id}"[^>]*?value="([^"]*)"`));
+    return match?.[1];
+}
+function keyOf(entry) {
+    return entry.uuid
+        ? `uuid:${entry.uuid.toLowerCase()}`
+        : `name:${entry.name.toLowerCase()}/${(entry.folder ?? "").toLowerCase()}`;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+function list(entries) {
+    const shown = entries
+        .slice(0, 3)
+        .map((e) => (e.uuid ? `${e.name} (${e.uuid})` : `${e.name} (no UUID)`));
+    const rest = entries.length - shown.length;
+    return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
+}

package/dist/surfaces/baldursgate3/pak.js

@@ -0,0 +1,153 @@
+import { promises as fs } from "node:fs";
+import { inflateSync } from "node:zlib";
+import { decodeLz4Block } from "../../core/lz4.js";
+import { parseMetaLsxModuleInfo } from "../../core/lsx.js";
+const MAGIC = 0x4b50534c;
+const HEADER_SIZE = 40;
+const ENTRY_SIZE = 272;
+const SOLID_FLAG = 0x04;
+const MAX_FILE_LIST_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024 * 1024;
+export const META_LSX_MAX_BYTES = 4 * 1024 * 1024;
+const DELETION_MARKER = 0xbeefdeadbeef;
+const META_LSX_RE = /^Mods\/([^/]+)\/meta\.lsx$/i;
+function methodFromFlags(entryFlags) {
+    switch (entryFlags & 0x0f) {
+        case 0:
+            return "none";
+        case 1:
+            return "zlib";
+        case 2:
+            return "lz4";
+        case 3:
+            return "zstd";
+        default:
+            return "unknown";
+    }
+}
+export async function readPakListing(pakPath) {
+    const handle = await fs.open(pakPath, "r");
+    try {
+        const header = Buffer.alloc(HEADER_SIZE);
+        const headerRead = await handle.read(header, 0, HEADER_SIZE, 0);
+        if (headerRead.bytesRead < HEADER_SIZE) {
+            throw new Error(`${pakPath}: too short to contain an LSPK header (got ${headerRead.bytesRead} of ${HEADER_SIZE} bytes)`);
+        }
+        if (header.readUInt32LE(0) !== MAGIC) {
+            throw new Error(`${pakPath}: not an LSPK package (missing "LSPK" magic at offset 0)`);
+        }
+        const version = header.readUInt32LE(4);
+        if (version !== 18) {
+            throw new Error(`${pakPath}: unsupported LSPK version v${version} — only v18 is supported. v15/v16 use a 64-bit-offset ` +
+                `"FileEntry15" struct, a different layout from v18's "FileEntry18" (Norbyte/lslib master, ` +
+                `LSLib/LS/PackageReader.cs, PackageReader.ReadInternal's version switch), so this reader refuses ` +
+                `rather than misreading them.`);
+        }
+        const fileListOffset = Number(header.readBigUInt64LE(8));
+        const flags = header.readUInt8(20);
+        const numParts = header.readUInt16LE(38);
+        if ((flags & SOLID_FLAG) !== 0) {
+            throw new Error(`${pakPath}: this is a "solid" archive (PackageFlags.Solid) — every file is one shared LZ4 frame instead of ` +
+                `independently-offset entries, which this reader does not implement.`);
+        }
+        const listHeader = Buffer.alloc(8);
+        const listHeaderRead = await handle.read(listHeader, 0, 8, fileListOffset);
+        if (listHeaderRead.bytesRead < 8) {
+            throw new Error(`${pakPath}: truncated file list header at offset ${fileListOffset}`);
+        }
+        const numFiles = listHeader.readInt32LE(0);
+        const compressedSize = listHeader.readInt32LE(4);
+        if (numFiles < 0 || compressedSize < 0) {
+            throw new Error(`${pakPath}: malformed file list header at offset ${fileListOffset} (numFiles=${numFiles}, compressedSize=${compressedSize})`);
+        }
+        const entryTableSize = numFiles * ENTRY_SIZE;
+        if (compressedSize > MAX_FILE_LIST_BYTES || entryTableSize > MAX_FILE_LIST_BYTES) {
+            throw new Error(`${pakPath}: implausible file list (numFiles=${numFiles} => ${entryTableSize} entry-table bytes, ` +
+                `compressedSize=${compressedSize}); this reader refuses anything over ${MAX_FILE_LIST_BYTES} bytes rather than ` +
+                `allocating from a corrupt or hostile header.`);
+        }
+        const compressed = Buffer.alloc(compressedSize);
+        const listBodyRead = await handle.read(compressed, 0, compressedSize, fileListOffset + 8);
+        if (listBodyRead.bytesRead < compressedSize) {
+            throw new Error(`${pakPath}: truncated file list (expected ${compressedSize} compressed bytes, got ${listBodyRead.bytesRead})`);
+        }
+        const decompressed = Buffer.from(decodeLz4Block(compressed, entryTableSize));
+        const entries = [];
+        for (let i = 0; i < numFiles; i++) {
+            const base = i * ENTRY_SIZE;
+            const nameBuf = decompressed.subarray(base, base + 256);
+            let nul = nameBuf.indexOf(0);
+            if (nul === -1)
+                nul = 256;
+            const name = nameBuf.toString("utf8", 0, nul);
+            const offsetInFile1 = decompressed.readUInt32LE(base + 256);
+            const offsetInFile2 = decompressed.readUInt16LE(base + 260);
+            const part = decompressed.readUInt8(base + 262);
+            const entryFlags = decompressed.readUInt8(base + 263);
+            const sizeOnDisk = decompressed.readUInt32LE(base + 264);
+            const uncompressedSize = decompressed.readUInt32LE(base + 268);
+            const offset = offsetInFile1 + offsetInFile2 * 2 ** 32;
+            if (offset === DELETION_MARKER)
+                continue;
+            entries.push({ name, offset, sizeOnDisk, uncompressedSize, part, method: methodFromFlags(entryFlags) });
+        }
+        return { version, flags, numParts, entries };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readPakEntry(pakPath, entry, maxBytes = DEFAULT_MAX_ENTRY_BYTES) {
+    if (entry.part !== 0) {
+        throw new Error(`${pakPath}: entry "${entry.name}" lives in archive part ${entry.part}, not part 0 (the pak file itself) — ` +
+            `reading additional archive parts is not supported, and this reader does not guess the part filename.`);
+    }
+    if (entry.sizeOnDisk > maxBytes || entry.uncompressedSize > maxBytes) {
+        throw new Error(`${pakPath}: entry "${entry.name}" declares ${entry.sizeOnDisk} stored / ${entry.uncompressedSize} decompressed bytes, ` +
+            `over this read's ${maxBytes}-byte cap — refusing rather than allocating from a size read straight out of the pak.`);
+    }
+    const handle = await fs.open(pakPath, "r");
+    try {
+        const raw = Buffer.alloc(entry.sizeOnDisk);
+        if (entry.sizeOnDisk > 0) {
+            const read = await handle.read(raw, 0, entry.sizeOnDisk, entry.offset);
+            if (read.bytesRead < entry.sizeOnDisk) {
+                throw new Error(`${pakPath}: truncated entry "${entry.name}" (expected ${entry.sizeOnDisk} bytes at offset ${entry.offset}, got ${read.bytesRead})`);
+            }
+        }
+        switch (entry.method) {
+            case "none":
+                return raw;
+            case "zlib":
+                return inflateSync(raw, { maxOutputLength: maxBytes });
+            case "lz4":
+                return Buffer.from(decodeLz4Block(raw, entry.uncompressedSize));
+            case "zstd":
+                throw new Error(`${pakPath}: entry "${entry.name}" uses zstd compression, which this reader does not support.`);
+            default:
+                throw new Error(`${pakPath}: entry "${entry.name}" has an unrecognized compression method.`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readPakModuleInfos(pakPath) {
+    const listing = await readPakListing(pakPath);
+    const out = [];
+    for (const entry of listing.entries) {
+        if (!META_LSX_RE.test(entry.name))
+            continue;
+        const buf = await readPakEntry(pakPath, entry, META_LSX_MAX_BYTES);
+        const info = parseMetaLsxModuleInfo(buf.toString("utf8"));
+        out.push({
+            pakPath,
+            entryName: entry.name,
+            folder: info?.folder,
+            name: info?.name,
+            uuid: info?.uuid,
+            version64: info?.version64,
+        });
+    }
+    return out;
+}

package/dist/surfaces/baldursgate3/settings.js

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { documents } from "../../core/fsutil.js";
+export function scriptExtenderSettingsFile(install) {
+    return path.join(install.root, "bin", "ScriptExtenderSettings.json");
+}
+export function readScriptExtenderSettings(install) {
+    const file = scriptExtenderSettingsFile(install);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return { present: false, file };
+    }
+    const bool = (key) => (typeof raw[key] === "boolean" ? raw[key] : undefined);
+    const settings = { present: true, file };
+    if (typeof raw.LogDirectory === "string" && raw.LogDirectory.trim())
+        settings.logDirectory = raw.LogDirectory;
+    const enableLogging = bool("EnableLogging");
+    if (enableLogging !== undefined)
+        settings.enableLogging = enableLogging;
+    const logRuntime = bool("LogRuntime");
+    if (logRuntime !== undefined)
+        settings.logRuntime = logRuntime;
+    const logCompile = bool("LogCompile");
+    if (logCompile !== undefined)
+        settings.logCompile = logCompile;
+    const logFailedCompile = bool("LogFailedCompile");
+    if (logFailedCompile !== undefined)
+        settings.logFailedCompile = logFailedCompile;
+    const createConsole = bool("CreateConsole");
+    if (createConsole !== undefined)
+        settings.createConsole = createConsole;
+    const developerMode = bool("DeveloperMode");
+    if (developerMode !== undefined)
+        settings.developerMode = developerMode;
+    return settings;
+}
+export function scriptExtenderLogDirs(install) {
+    const settings = readScriptExtenderSettings(install);
+    const dirs = [];
+    if (settings.logDirectory)
+        dirs.push(settings.logDirectory);
+    const fallback = documents("OsirisLogs");
+    if (!dirs.some((d) => path.resolve(d).toLowerCase() === path.resolve(fallback).toLowerCase()))
+        dirs.push(fallback);
+    return dirs;
+}

package/dist/surfaces/baldursgate3/surface.js

@@ -0,0 +1,232 @@
+import * as path from "node:path";
+import { baldursgate3Compat } from "./compat.js";
+import { localAppData, pathExists, readTextIfExists } from "../../core/fsutil.js";
+import { findInSteam } from "../../core/steam.js";
+import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
+import { bg3Index } from "./index/index.js";
+import { scanModIdentities as scanBg3ModIdentities } from "./identity.js";
+import { SIGNATURES } from "./logs.js";
+import { describeModSettingsDiff, diffModSettings, parseModSettings } from "./modsettings.js";
+import { BRIDGE_VALIDATORS } from "./validators/bridge.js";
+import { FILE_VALIDATORS } from "./validators/files.js";
+import { ITEM_VALIDATORS } from "./validators/items.js";
+import { PROGRESSION_VALIDATORS } from "./validators/progression.js";
+import { STATS_VALIDATORS } from "./validators/stats.js";
+import { STORY_VALIDATORS } from "./validators/story.js";
+import { TEMPLATE_VALIDATORS } from "./validators/templates.js";
+import { readScriptExtenderSettings, scriptExtenderLogDirs } from "./settings.js";
+const LARIAN = localAppData("Larian Studios", "Baldur's Gate 3");
+const BASE_MODULES = new Set([
+    "gustav",
+    "gustavdev",
+    "gustavx",
+    "shared",
+    "shareddev",
+    "honour",
+    "honourx",
+    "engine",
+    "mainui",
+    "modbrowser",
+    "fw3",
+    "dicesets",
+]);
+const MODSETTINGS = path.join(LARIAN, "PlayerProfiles", "Public", "modsettings.lsx");
+const PAKS_ROOT = path.join(LARIAN, "Mods");
+const NON_STEAM_CANDIDATES = [
+    "C:/GOG Games/Baldurs Gate 3",
+    "C:/Program Files (x86)/GOG Galaxy/Games/Baldurs Gate 3",
+];
+export const baldursgate3 = {
+    id: "baldursgate3",
+    name: "Baldur's Gate 3",
+    aliases: ["bg3", "baldurs gate 3", "baldur's gate 3"],
+    summary: "Larian Divinity engine. .pak mods live under %LOCALAPPDATA%/Larian Studios, " +
+        "with an explicit load order in modsettings.lsx and optional Script Extender support.",
+    async detect() {
+        const installs = [];
+        const override = process.env.MODWRIGHT_BG3_ROOT;
+        if (override && (await pathExists(override))) {
+            installs.push({ gameId: "baldursgate3", root: override, source: "env" });
+        }
+        for (const root of await findInSteam(["Baldurs Gate 3"])) {
+            installs.push({ gameId: "baldursgate3", root, source: "steam" });
+        }
+        for (const candidate of NON_STEAM_CANDIDATES) {
+            if (await pathExists(candidate)) {
+                installs.push({ gameId: "baldursgate3", root: candidate, source: "gog" });
+            }
+        }
+        return dedupeByRoot(installs);
+    },
+    modRoots(install) {
+        return roots([
+            {
+                id: "paks",
+                label: "Mods (.pak)",
+                path: PAKS_ROOT,
+                layout: "file",
+                extensions: [".pak"],
+                ordered: true,
+                conflictScope: "opaque",
+                notes: "The real mod folder — under the user profile, NOT the game install. " +
+                    "A .pak here still does nothing until it is listed in modsettings.lsx.",
+            },
+            {
+                id: "loose",
+                label: "Loose file overrides (Data/)",
+                path: path.join(install.root, "Data"),
+                layout: "flat",
+                conflictScope: "merged",
+                notes: "Unpacked overrides shipped as loose files. These win over .pak content " +
+                    "and are the usual cause of a mod that 'cannot be uninstalled'.",
+            },
+            {
+                id: "scriptextender",
+                label: "Script Extender data",
+                path: path.join(LARIAN, "Script Extender"),
+                layout: "directory",
+                conflictScope: "isolated",
+                notes: "BG3SE config and per-mod extender data. Requires DWrite.dll in bin/.",
+            },
+            {
+                id: "nativemods",
+                label: "Native mod loader plugins",
+                path: path.join(install.root, "bin", "NativeMods"),
+                layout: "file",
+                extensions: [".dll"],
+                conflictScope: "isolated",
+                notes: "Native .dll plugins loaded by the BG3 Native Mod Loader.",
+            },
+        ]);
+    },
+    loadOrderFile() {
+        return MODSETTINGS;
+    },
+    diffLoadOrder(before, after) {
+        const diff = diffModSettings(before, after);
+        return {
+            removed: diff.removed.map((entry) => entry.name),
+            added: diff.added.map((entry) => entry.name),
+            reordered: diff.reordered,
+            description: describeModSettingsDiff(diff),
+        };
+    },
+    logSignatures: SIGNATURES,
+    index: bg3Index,
+    validators: [
+        ...ITEM_VALIDATORS,
+        ...PROGRESSION_VALIDATORS,
+        ...STORY_VALIDATORS,
+        ...STATS_VALIDATORS,
+        ...FILE_VALIDATORS,
+        ...BRIDGE_VALIDATORS,
+        ...TEMPLATE_VALIDATORS,
+    ],
+    async loadOrder() {
+        const xml = await readTextIfExists(MODSETTINGS);
+        if (!xml)
+            return [];
+        return parseModSettings(xml).map((entry) => ({
+            index: entry.index,
+            name: entry.name,
+            enabled: true,
+            uuid: entry.uuid || undefined,
+            folder: entry.folder,
+            baseGame: BASE_MODULES.has(entry.name.toLowerCase()),
+        }));
+    },
+    async scanModIdentities(install) {
+        return scanBg3ModIdentities(PAKS_ROOT, path.join(install.root, "Data"));
+    },
+    logs(install) {
+        const seDirs = scriptExtenderLogDirs(install);
+        return logs([
+            {
+                id: "extender",
+                label: "Script Extender console log",
+                candidates: seDirs.map((dir) => path.join(dir, "Extender Runtime *.log")),
+                rootId: "scriptextender",
+                notes: "Lua errors and module load messages from BG3SE, written as " +
+                    "'Extender Runtime <date>.log' under LogDirectory only when LogRuntime is true " +
+                    "in bin/ScriptExtenderSettings.json. SE runs fine without writing any log at all.",
+            },
+            {
+                id: "osiris",
+                label: "Osiris log",
+                candidates: seDirs.map((dir) => path.join(dir, "Osiris*.log")),
+                notes: "Story rule evaluation and compile errors, written as 'Osiris Runtime <date>.log' " +
+                    "under LogDirectory when EnableLogging is true (timestamp in the name is UTC). " +
+                    "Grows to hundreds of MB in one session; only its tail is ever scanned. 'Symbol not " +
+                    "found in story' and missing DB_/PROC_/QRY_ prefixes are the classic failures.",
+            },
+            {
+                id: "network",
+                label: "Game network log",
+                candidates: [path.join(install.root, "bin", "network.*.log")],
+                notes: "First read on any crash: shows whether a level transition started before the game died. " +
+                    "One file per launch, ISO timestamp in the name; the newest wins.",
+            },
+            {
+                id: "crash",
+                label: "Crash dumps",
+                candidates: [path.join(install.root, "bin", "CrashDump*.dmp")],
+                binary: true,
+                notes: "Timestamps corroborate the network log; the dumps themselves are not parsed.",
+            },
+            {
+                id: "gamelog",
+                label: "Game log",
+                candidates: [path.join(install.root, "bin", "gold.*.log")],
+                notes: "Larian's general client log (Discord init, client thread start/end, cloud save " +
+                    "sync), one file per launch beside network.*.log. Same line format as the network log.",
+            },
+        ]);
+    },
+    async explainMissing(install) {
+        const settings = readScriptExtenderSettings(install);
+        if (!settings.present) {
+            const reason = "Script Extender does not appear to be installed or configured: " +
+                `${settings.file} was not found.`;
+            return { extender: reason, osiris: reason };
+        }
+        const logDir = scriptExtenderLogDirs(install)[0];
+        const reasons = {};
+        reasons.extender =
+            settings.logRuntime === false
+                ? `LogRuntime is false in ${settings.file}, so Script Extender never writes its console ` +
+                    `log ('Extender Runtime <date>.log'); set it to true and relaunch. LogDirectory ` +
+                    `resolves to "${logDir}".`
+                : `LogRuntime is enabled in ${settings.file} and LogDirectory resolves to "${logDir}", ` +
+                    "but no Extender Runtime log was found there — has the game been launched since?";
+        reasons.osiris =
+            settings.enableLogging === false
+                ? `EnableLogging is false in ${settings.file}, so Osiris never writes its runtime log ` +
+                    `('Osiris Runtime <date>.log'); set it to true and relaunch. LogDirectory resolves to ` +
+                    `"${logDir}".`
+                : `EnableLogging is enabled in ${settings.file} and LogDirectory resolves to "${logDir}", ` +
+                    "but no Osiris Runtime log was found there — has the game been launched since?";
+        return reasons;
+    },
+    toolNeeds: [
+        { feature: "index", tools: ["divine"], note: "build_index extracts the vanilla paks and converts .lsf/.loca with LSLib's divine." },
+        { feature: "build", tools: ["divine"], note: "The divine-* steps (lsx to lsf, loca, create-package) and verifying a .pak's listing." },
+    ],
+    processNames: ["bg3_dx11.exe", "bg3.exe"],
+    compat: baldursgate3Compat,
+    guidance: "Load order entries identify mods by UUID and module Name, neither of which has to " +
+        "match the .pak filename on disk — ModWright now reads meta.lsx from inside every " +
+        "installed pak (and every loose Data/Mods/*/meta.lsx) to match entries to their real " +
+        "identity, rather than guessing from filenames. Two or more paks can carry the same " +
+        "UUID under different filenames (a hand-built copy and a mod.io re-download, say); " +
+        "which copy the game then loads is not predictable from outside (observed in game: " +
+        "the load order's Folder attribute named a copy whose content did not load, and " +
+        "a plain launch never rewrites that file); load_order's crossCheck and find_conflicts's " +
+        "sharedIdentities list every copy, and Ext.Mod.GetMod(uuid).Info.Directory at the " +
+        "Script Extender console is the live answer. " +
+        "Two failure modes dominate. First, a .pak dropped into Mods/ without a matching " +
+        "ModuleShortDesc entry in modsettings.lsx is inert — always cross-check the load order " +
+        "against the installed paks. Second, mod managers (the in-game one, Vortex, BG3 Mod " +
+        "Manager) rewrite modsettings.lsx and silently drop entries whose UUIDs they cannot " +
+        "match, so an order that 'reverts itself' " +
+        "usually means a missing or renamed pak rather than a corrupt file.",
+};

package/dist/surfaces/baldursgate3/validators/bridge.js

@@ -0,0 +1,7 @@
+import { bridgeNeverShipValidator } from "../../../core/bridge/index.js";
+export const bridgeNeverShipsValidator = bridgeNeverShipValidator({
+    id: "bg3.history.bridge-never-ships",
+    game: "baldursgate3",
+    evidence: ["ModWright research"],
+});
+export const BRIDGE_VALIDATORS = [bridgeNeverShipsValidator];