hoi4-agent-tools 3.9.0 → 4.0.0

package/dist/hoi4_agent_tools/probability/operations.js

@@ -1,6 +1,6 @@
 import { emptyServiceResult } from '../core/result.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
-import { probabilityCompareRequestSchema, probabilityEvaluateRequestSchema, probabilityInspectRequestSchema, probabilityRenderRequestSchema, probabilitySequenceRequestSchema, probabilitySimulateRequestSchema, probabilitySweepRequestSchema, } from '../schemas/probability-requests.js';
+import { probabilityCompareRequestSchema, probabilityEvaluateRequestSchema, probabilityInspectRequestSchema, probabilityRenderRequestSchema, probabilitySequenceRequestSchema, probabilitySimulateRequestSchema, probabilitySweepRequestSchema, probabilityAnalyzeRequestSchema, splitProbabilityAnalyzeRequest, } from '../schemas/probability-requests.js';
 function runtime(context, refresh) {
     return {
         workspaceId: context.workspaceId,
@@ -9,6 +9,83 @@ function runtime(context, refresh) {
         ...(refresh === undefined ? {} : { refresh }),
     };
 }
+const INLINE_RANKING_SCENARIOS = 4;
+const INLINE_RANKING_CANDIDATES = 12;
+const INLINE_MISSING_INPUTS = 16;
+const INLINE_COMPARISON_CHANGES = 12;
+function rounded(value, digits = 6) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return null;
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
+}
+function compareIds(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** The answer itself, inline: the strongest candidates of the first scenarios. */
+function inlineRanking(result) {
+    return result.scenarios.slice(0, INLINE_RANKING_SCENARIOS).map((scenario) => {
+        const ranked = [...scenario.candidates].sort((left, right) => (right.conditionalProbability ?? -1) - (left.conditionalProbability ?? -1) ||
+            (right.rawValue?.value ?? Number.NEGATIVE_INFINITY) -
+                (left.rawValue?.value ?? Number.NEGATIVE_INFINITY) ||
+            compareIds(left.id, right.id));
+        return {
+            scenarioId: scenario.id,
+            poolComplete: scenario.poolComplete,
+            candidates: ranked.slice(0, INLINE_RANKING_CANDIDATES).map((candidate) => ({
+                id: candidate.id,
+                eligible: candidate.eligibility,
+                weight: rounded(candidate.rawValue?.value),
+                ...((candidate.rawValue === undefined || candidate.rawValue === null) &&
+                    candidate.rawInterval !== undefined
+                    ? {
+                        weightRange: [rounded(candidate.rawInterval.min), rounded(candidate.rawInterval.max)],
+                    }
+                    : {}),
+                probability: rounded(candidate.conditionalProbability),
+                ...(candidate.effectiveMtthDays === undefined
+                    ? {}
+                    : { mtthDays: rounded(candidate.effectiveMtthDays, 2) }),
+            })),
+            ...(ranked.length > INLINE_RANKING_CANDIDATES
+                ? { omittedCandidates: ranked.length - INLINE_RANKING_CANDIDATES }
+                : {}),
+        };
+    });
+}
+/** Facts the scenarios did not declare but a condition or value needs. */
+function missingInputs(result) {
+    const inputs = new Set();
+    for (const { code, path, details } of result.unresolved) {
+        if (typeof details?.scenarioInput === 'string')
+            inputs.add(details.scenarioInput);
+        else if (code === 'VALUE_UNRESOLVED' && path !== undefined && !/^(?:@|constant:)/u.test(path))
+            inputs.add(path);
+    }
+    return [...inputs].sort(compareIds).slice(0, INLINE_MISSING_INPUTS);
+}
+function inlineComparison(result) {
+    if (result.comparison === undefined)
+        return [];
+    return [...result.comparison.scenarioChanges]
+        .sort((left, right) => Math.abs(right.probabilityDelta ?? 0) - Math.abs(left.probabilityDelta ?? 0) ||
+        Math.abs(right.rawDelta ?? 0) - Math.abs(left.rawDelta ?? 0) ||
+        compareIds(left.candidateId, right.candidateId))
+        .slice(0, INLINE_COMPARISON_CHANGES)
+        .map((change) => ({
+        scenarioId: change.scenarioId,
+        candidateId: change.candidateId,
+        ...(change.rawDelta === undefined ? {} : { weightDelta: rounded(change.rawDelta) }),
+        ...(change.probabilityDelta === undefined
+            ? {}
+            : { probabilityDelta: rounded(change.probabilityDelta) }),
+        ...(change.eligibilityChange === undefined
+            ? {}
+            : {
+                eligibility: `${change.eligibilityChange.before}->${change.eligibilityChange.after}`,
+            }),
+    }));
+}
 export function probabilityAnalysisData(result) {
     return {
         operation: result.operation,
@@ -41,6 +118,9 @@ export function probabilityAnalysisData(result) {
             : { comparisonChanges: result.comparison.scenarioChanges.length }),
         visualResources: result.resources.filter(({ mimeType }) => mimeType.startsWith('image/'))
             .length,
+        ranking: inlineRanking(result),
+        missingInputs: missingInputs(result),
+        ...(result.comparison === undefined ? {} : { changes: inlineComparison(result) }),
     };
 }
 export function probabilityAnalysisServiceResult(workspaceId, result) {
@@ -88,19 +168,82 @@ export function normalizeProbabilityCompareRequest(input) {
 export function normalizeProbabilityRenderRequest(input) {
     return probabilityRenderRequestSchema.parse(input);
 }
+const DEFAULT_SCENARIO_SET = {
+    schemaVersion: '1.0',
+    id: 'source-defaults',
+    description: 'One scenario with no declared facts; conditions that need facts stay unresolved.',
+    scenarios: [{ id: 'no-facts', state: {} }],
+};
+/** Discover the weighted surface and, unless evaluate is false, evaluate it in the same call. */
 export async function inspectProbabilities(analyzer, input, context) {
-    const inspected = await analyzer.inspect(runtime(context, input.refresh), input.adapter, input.source, input.candidatePool, input.customPoolManifest);
-    const sourceRequiredInputPaths = (inspected.surface?.requiredInputs ?? []).filter((path) => path !== 'focus.external_factors_complete' && path !== 'technology.external_factors_complete');
-    const adapterRequiredInputPaths = (inspected.surface?.requiredInputs ?? []).filter((path) => path === 'focus.external_factors_complete' || path === 'technology.external_factors_complete');
+    let source = input.source;
+    const candidatePool = input.candidatePool ?? [];
+    // A pool alone names what to inspect: its first ID finds the defining file.
+    if (source === undefined && input.customPoolManifest === undefined && candidatePool.length > 0)
+        source = { identifier: candidatePool[0] };
+    const customPoolManifest = input.customPoolManifest;
+    let inspected = await analyzer.inspect(runtime(context, input.refresh), input.adapter, source, candidatePool, customPoolManifest);
+    // A wrong adapter guess, such as a mission named as a decision, should not cost another call.
+    const suggested = inspected.discovery?.suggestedAdapter;
+    if (input.evaluate !== false &&
+        inspected.surface === undefined &&
+        suggested !== undefined &&
+        suggested !== input.adapter &&
+        (inspected.discovery?.reason === 'candidate_pool_not_found' ||
+            inspected.discovery?.reason === 'requested_adapter_empty' ||
+            inspected.discovery?.reason === 'identifier_not_found'))
+        inspected = await analyzer.inspect(runtime(context), suggested, source, candidatePool, customPoolManifest);
+    const surface = inspected.surface;
+    if (input.evaluate !== false &&
+        surface !== undefined &&
+        (source !== undefined || customPoolManifest !== undefined)) {
+        const analyzed = await analyzer.evaluate({
+            ...runtime(context),
+            adapter: surface.adapter.id,
+            ...(source === undefined ? {} : { source }),
+            ...(customPoolManifest === undefined ? {} : { customPoolManifest }),
+            ...(candidatePool.length === 0 ? {} : { candidatePool }),
+            scenarioSet: (input.scenarioSet ??
+                DEFAULT_SCENARIO_SET),
+            ...(input.horizonDays === undefined ? {} : { horizonDays: input.horizonDays }),
+            ...(input.metrics === undefined ? {} : { metrics: input.metrics }),
+            ...(input.acceptanceBands === undefined
+                ? {}
+                : {
+                    acceptanceBands: input.acceptanceBands,
+                }),
+            ...(input.diagnosticThresholds === undefined
+                ? {}
+                : {
+                    diagnosticThresholds: input.diagnosticThresholds,
+                }),
+            ...(input.outputs === undefined ? {} : { outputs: input.outputs }),
+        });
+        const result = probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+        result.artifacts = [...result.artifacts, ...inspected.artifacts];
+        if (input.scenarioSet === undefined)
+            result.diagnostics = [
+                {
+                    code: 'PROBABILITY_DEFAULT_SCENARIO',
+                    severity: 'info',
+                    category: 'configuration',
+                    message: 'Evaluated without declared facts; pass scenarioSet with the facts in missingInputs to resolve the remaining conditions',
+                },
+                ...result.diagnostics,
+            ];
+        return result;
+    }
+    const sourceRequiredInputPaths = (surface?.requiredInputs ?? []).filter((path) => path !== 'focus.external_factors_complete' && path !== 'technology.external_factors_complete');
+    const adapterRequiredInputPaths = (surface?.requiredInputs ?? []).filter((path) => path === 'focus.external_factors_complete' || path === 'technology.external_factors_complete');
     const result = emptyServiceResult(context.workspaceId, {
         adapters: inspected.adapters.length,
-        ...(inspected.surface === undefined
+        ...(surface === undefined
             ? {}
             : {
-                adapterId: inspected.surface.adapter.id,
-                sourceRevision: inspected.surface.sourceRevision,
-                sourceHash: inspected.surface.sourceHash,
-                poolComplete: inspected.surface.poolComplete,
+                adapterId: surface.adapter.id,
+                sourceRevision: surface.sourceRevision,
+                sourceHash: surface.sourceHash,
+                poolComplete: surface.poolComplete,
             }),
         ...(inspected.discovery === undefined
             ? {}
@@ -115,7 +258,7 @@ export async function inspectProbabilities(analyzer, input, context) {
                 sourceRevision: inspected.discovery.sourceRevision,
                 sourceHash: inspected.discovery.sourceHash,
             }),
-        candidates: inspected.surface?.candidateCount ?? 0,
+        candidates: surface?.candidateCount ?? 0,
         availableCandidates: inspected.discovery?.availableAdapters.reduce((sum, { candidateCount }) => sum + candidateCount, 0) ?? 0,
         availableAdapters: inspected.discovery?.availableAdapters.map((available) => ({
             adapterId: available.adapterId,
@@ -124,14 +267,14 @@ export async function inspectProbabilities(analyzer, input, context) {
             candidatePoolMatches: available.candidatePoolMatchCount,
         })) ?? [],
         candidateExamples: inspected.discovery?.exampleCandidateIds ?? [],
-        requiredInputs: inspected.surface?.requiredInputs.length ?? 0,
+        requiredInputs: surface?.requiredInputs.length ?? 0,
         requiredInputPaths: sourceRequiredInputPaths.slice(0, 32),
         requiredInputPathsTruncated: sourceRequiredInputPaths.length > 32,
         adapterRequiredInputPaths,
-        unresolved: inspected.surface?.unsupported.length ?? 0,
+        unresolved: surface?.unsupported.length ?? 0,
     });
     result.code =
-        inspected.surface !== undefined
+        surface !== undefined
             ? 'PROBABILITY_SOURCE_INSPECTED'
             : inspected.discovery !== undefined
                 ? 'PROBABILITY_SOURCE_DISCOVERED'
@@ -140,6 +283,25 @@ export async function inspectProbabilities(analyzer, input, context) {
     setInlineFilesScanned(result, inspected.filesScanned);
     return result;
 }
+/** Compare, sweep, simulate, sequence, or render through one entry point. */
+export async function analyzeProbabilities(analyzer, input, context) {
+    const split = splitProbabilityAnalyzeRequest(input);
+    switch (split.analysis) {
+        case 'compare':
+            return compareProbabilities(analyzer, split.request, context);
+        case 'sweep':
+            return sweepProbabilities(analyzer, split.request, context);
+        case 'simulate':
+            return simulateProbabilities(analyzer, split.request, context);
+        case 'sequence':
+            return sequenceProbabilities(analyzer, split.request, context);
+        case 'render':
+            return renderProbabilities(analyzer, split.request, context);
+    }
+}
+export function normalizeProbabilityAnalyzeRequest(input) {
+    return probabilityAnalyzeRequestSchema.parse(input);
+}
 export async function evaluateProbabilities(analyzer, input, context) {
     const analyzed = await analyzer.evaluate({
         ...runtime(context, input.refresh),

package/dist/hoi4_agent_tools/probability/source-analysis.js

@@ -388,6 +388,28 @@ function samePool(candidate, selected) {
         return candidate.metadata.randomListId === selected.metadata.randomListId;
     return candidate.id === selected.id;
 }
+/**
+ * A pool entry that names no candidate but names a categorical pool, such as an event ID for
+ * its options or a random_list ID, stands for every candidate of that pool.
+ */
+export function expandCandidatePool(candidates, candidatePool) {
+    if (candidatePool.length === 0)
+        return [];
+    const ids = new Set(candidates.map(({ id }) => id));
+    const expanded = new Set();
+    for (const entry of candidatePool) {
+        if (ids.has(entry)) {
+            expanded.add(entry);
+            continue;
+        }
+        const members = candidates.filter(({ metadata }) => metadata.eventId === entry || metadata.randomListId === entry);
+        if (members.length === 0)
+            expanded.add(entry);
+        for (const { id } of members)
+            expanded.add(id);
+    }
+    return [...expanded];
+}
 function candidatesAtSourceLine(candidates, adapterId, line) {
     if (line === undefined)
         return candidates;
@@ -421,11 +443,11 @@ function candidatesAtSourceLine(candidates, adapterId, line) {
 }
 export function inventoryWeightedSurfaces(snapshot, source, candidatePool = [], adapterIds = sourceBackedAdapterIds) {
     const contexts = sourceContexts(snapshot, source);
-    const wanted = new Set(candidatePool);
     const adapters = adapterIds
         .filter((adapterId) => adapterId !== 'custom_weighted_pool')
         .map((adapterId) => {
         const candidates = candidatesAtSourceLine(contexts.flatMap((context) => candidatesFor(context, adapterId)), adapterId, source.line).sort((left, right) => compareCodeUnits(left.id, right.id));
+        const wanted = new Set(expandCandidatePool(candidates, candidatePool));
         return {
             adapterId,
             candidateCount: candidates.length,
@@ -457,6 +479,7 @@ export function discoverWeightedSurface(snapshot, adapterId, source, candidatePo
     let candidates = contexts.flatMap((context) => candidatesFor(context, adapterId));
     candidates.sort((left, right) => compareCodeUnits(left.id, right.id));
     candidates = candidatesAtSourceLine(candidates, adapterId, source.line);
+    candidatePool = expandCandidatePool(candidates, candidatePool);
     const localCategoricalPool = adapterId === 'event_option_ai_chance' || adapterId === 'random_list';
     let completeLocalPoolIds;
     if (source.identifier !== undefined) {

package/dist/hoi4_agent_tools/reference/error-log.js

@@ -0,0 +1,359 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ServiceError } from '../core/result.js';
+import { knownMistakeForLogMessage } from './known-mistakes.js';
+/** The newest part of a very large log is read; the game writes it anew on every launch. */
+const MAX_LOG_BYTES = 16 * 1024 * 1024;
+const MAX_MESSAGE_CHARACTERS = 600;
+const SOURCE_EXTENSIONS = 'txt|gui|gfx|yml|csv|asset|lua|mod|shader|fxh|json|map|bmp|dds|tga|png';
+const headerPattern = /^\[(\d{2}:\d{2}:\d{2})\]\[([^\]:]+?)(?:\.cpp)?(?::\d+)?\]:\s?(.*)$/u;
+const quotedFilePattern = new RegExp(`(?:in |)file:?\\s*"([^"]+\\.(?:${SOURCE_EXTENSIONS}))"`, 'giu');
+const barePathPattern = new RegExp(`((?:[A-Za-z]:)?[\\w .\\-/\\\\]*?(?:common|events|history|interface|gfx|localisation|localisation_synced|map|music|sound|portraits|tutorial)[/\\\\][^\\s"',;:]+?\\.(?:${SOURCE_EXTENSIONS}))\\b`, 'gu');
+const linePattern = /(?:near\s+)?line:?\s*(\d{1,7})/giu;
+/** Rules in order; the first that matches classifies an entry. */
+const categoryRules = [
+    [
+        'syntax',
+        /unexpected (?:token|end)|missing (?:closing |opening )?(?:brace|bracket)|parse error|malformed|unbalanced/iu,
+    ],
+    [
+        'duplicate',
+        /duplicate|already (?:exists|defined|registered)|defined (?:twice|multiple times)/iu,
+    ],
+    ['localisation', /locali[sz]/iu],
+    ['effect', /\beffect\b/iu],
+    ['trigger', /\btrigger\b|\bcondition\b/iu],
+    ['scope', /\bscope\b/iu],
+    ['graphics', /texture|sprite|\.dds|\.tga|\.png|gfx|\bfont\b|\bmesh\b|\bentity\b|animation/iu],
+    ['interface', /\bgui\b|window|\bwidget\b|scripted ?gui/iu],
+    ['map', /province|strategic ?region|\bstate\b|adjacenc|supply|railway|\bmap\b/iu],
+    [
+        'missing_reference',
+        /not found|unknown|doesn'?t exist|does not exist|invalid|missing|could not find|failed to (?:find|load)/iu,
+    ],
+];
+const moduleCategories = [
+    [/locali[sz]/iu, 'localisation'],
+    [/^(?:effect|effectbase|effects)/iu, 'effect'],
+    [/^(?:trigger|triggerbase|triggers)/iu, 'trigger'],
+    [/gfx|texture|sprite|font|graphic/iu, 'graphics'],
+    [/gui|window|widget/iu, 'interface'],
+    [/province|map|state|region|supply|railway|adjacenc/iu, 'map'],
+    [/persistent|parse|pdx_?data|script/iu, 'syntax'],
+];
+/** What to do about each kind of entry; names the tool that narrows it down. */
+const categoryHints = {
+    syntax: 'Check braces, quotes and assignments near the named line; hoi4.script_validate with the file path pinpoints it.',
+    duplicate: 'Two active definitions share a name: rename one, or remove the copy that overrides the other.',
+    localisation: 'Add the key to a UTF-8 with BOM .yml under localisation/<language>/ (key: "Text", no :0), or correct the key name.',
+    effect: 'Check that the effect exists and takes these arguments in this scope: hoi4.script_validate on the file, hoi4.reference_search for its documentation.',
+    trigger: 'Check that the trigger exists and takes these arguments in this scope: hoi4.script_validate on the file, hoi4.reference_search for its documentation.',
+    scope: 'A command runs in the wrong scope: check the enclosing scope changes with hoi4.script_validate.',
+    graphics: 'Register the sprite in a .gfx file, and check the texture path, file name case and DDS format.',
+    interface: 'Check the .gui element and sprite names; hoi4.gui_inspect shows the window and its missing assets.',
+    map: 'Check the named province, state or region with hoi4.map_inspect; map errors can stop the game loading without debug mode.',
+    missing_reference: 'The named object is not defined in any active layer: hoi4.source_lookup confirms, then define it or fix the name.',
+    other: 'Read the message and the named file; hoi4.source_lookup locates the definition.',
+};
+/** Reduce a message to its shape: names, numbers, quoted values and paths become placeholders. */
+export function errorLogPattern(message) {
+    return (message
+        .toLowerCase()
+        .replace(/"[^"]*"/gu, '<v>')
+        .replace(new RegExp(`[\\w./\\\\:-]+\\.(?:${SOURCE_EXTENSIONS})\\b`, 'gu'), '<file>')
+        .replace(/\b[a-z_][\w]*\.\d+\b/gu, '<id>')
+        // snake_case script names (keys, effects, sprites) differ between otherwise equal messages.
+        .replace(/\b[a-z0-9]+(?:_[a-z0-9]+)+\b/gu, '<name>')
+        .replace(/-?\b\d+(?:\.\d+)?\b/gu, '<n>')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, 300));
+}
+const HISTORY_FILE = 'error-log-history.json';
+const MAX_HISTORY_ENTRIES = 5_000;
+function entryKey(module, message) {
+    return createHash('sha256').update(`${module}\0${message}`).digest('hex').slice(0, 24);
+}
+async function readHistory(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Remember the entries of each log this server reads, keyed by the log's write time, so the
+ * next launch's log can say which errors are new and which a fix removed. The history lives
+ * in the server's own cache folder, never in the mod.
+ */
+async function compareWithPreviousLaunch(workspace, modifiedAt, entries) {
+    const file = path.join(workspace.cacheRoot, HISTORY_FILE);
+    const history = await readHistory(file);
+    const current = { modifiedAt, entries: {} };
+    for (const entry of entries.slice(0, MAX_HISTORY_ENTRIES))
+        current.entries[entryKey(entry.module, entry.message)] = {
+            category: entry.category,
+            message: entry.message.slice(0, 300),
+            ...(entry.relativePath === undefined ? {} : { relativePath: entry.relativePath }),
+        };
+    if (history.current?.modifiedAt === modifiedAt)
+        return { ...(history.previous === undefined ? {} : { previous: history.previous }), current };
+    const next = {
+        ...(history.current === undefined ? {} : { previous: history.current }),
+        current,
+    };
+    try {
+        await mkdir(workspace.cacheRoot, { recursive: true });
+        const temporary = `${file}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify(next));
+        await rename(temporary, file);
+    }
+    catch {
+        // The comparison is a convenience; an unwritable cache leaves the read itself intact.
+    }
+    return { ...(next.previous === undefined ? {} : { previous: next.previous }), current };
+}
+function classify(module, message) {
+    for (const [category, pattern] of categoryRules)
+        if (category !== 'missing_reference' && pattern.test(message))
+            return category;
+    for (const [pattern, category] of moduleCategories)
+        if (pattern.test(module))
+            return category;
+    return categoryRules.at(-1)[1].test(message) ? 'missing_reference' : 'other';
+}
+/** The reviewed known mistake a logged message reports, when there is one. */
+function knownMistakeOf(message) {
+    const rule = knownMistakeForLogMessage(message);
+    return rule === undefined ? {} : { knownMistake: { id: rule.id, fix: rule.fix } };
+}
+/** The user-data folder that holds `logs/`, in order of preference. */
+function userDataCandidates(workspace, configured) {
+    const candidates = [];
+    if (configured !== undefined)
+        candidates.push(path.resolve(configured));
+    const modParent = path.dirname(workspace.modRoot);
+    if (path.basename(modParent).toLowerCase() === 'mod')
+        candidates.push(path.dirname(modParent));
+    const home = os.homedir();
+    const userFolder = path.join('Paradox Interactive', 'Hearts of Iron IV');
+    if (process.platform === 'win32') {
+        if (process.env.OneDrive !== undefined)
+            candidates.push(path.join(process.env.OneDrive, 'Documents', userFolder));
+        candidates.push(path.join(home, 'Documents', userFolder));
+    }
+    else if (process.platform === 'darwin') {
+        candidates.push(path.join(home, 'Documents', userFolder));
+    }
+    else {
+        candidates.push(path.join(home, '.local', 'share', userFolder));
+    }
+    return [...new Set(candidates)];
+}
+async function readTail(file, size) {
+    const start = Math.max(0, size - MAX_LOG_BYTES);
+    const handle = await open(file, 'r');
+    try {
+        const buffer = Buffer.alloc(size - start);
+        await handle.read(buffer, 0, buffer.length, start);
+        let text = buffer.toString('utf8');
+        // Drop the partial first line of a truncated read.
+        if (start > 0)
+            text = text.slice(text.indexOf('\n') + 1);
+        return { text, truncated: start > 0 };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The last source file a message names, relative to its source root, and its line. */
+function locate(message, roots) {
+    const files = [
+        ...[...message.matchAll(quotedFilePattern)].map((match) => match[1]),
+        ...[...message.matchAll(barePathPattern)].map((match) => match[1].trim()),
+    ];
+    const raw = files.at(-1);
+    if (raw === undefined)
+        return undefined;
+    let normalized = raw.replaceAll('\\', '/').replace(/^\.\//u, '');
+    for (const root of roots) {
+        const prefix = `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/`;
+        if (normalized.toLowerCase().startsWith(prefix.toLowerCase())) {
+            normalized = normalized.slice(prefix.length);
+            break;
+        }
+    }
+    // Paths under any mod folder are made relative to that mod.
+    const modMatch = /\/mod\/[^/]+\/(.+)$/u.exec(normalized);
+    if (modMatch !== null && path.isAbsolute(raw))
+        normalized = modMatch[1];
+    const lines = [...message.matchAll(linePattern)].map((match) => Number(match[1]));
+    return { relativePath: normalized, ...(lines.length === 0 ? {} : { line: lines.at(-1) }) };
+}
+async function layerOf(workspace, relativePath, logModified) {
+    const layers = [
+        ['mod', workspace.modRoot],
+        ...workspace.dependencyRoots.map((root) => [
+            'dependency',
+            root,
+        ]),
+        ...(workspace.gameRoot === undefined
+            ? []
+            : [['game', workspace.gameRoot]]),
+    ];
+    for (const [layer, root] of layers) {
+        const candidate = path.resolve(root, relativePath);
+        if (!candidate.startsWith(path.resolve(root) + path.sep))
+            continue;
+        const info = await stat(candidate).catch(() => undefined);
+        if (info?.isFile() === true)
+            return { layer, changedSinceLog: info.mtimeMs > logModified };
+    }
+    return { layer: 'unknown', changedSinceLog: false };
+}
+export async function readErrorLog(workspace, input, configuredUserRoot, signal) {
+    let found;
+    for (const root of userDataCandidates(workspace, configuredUserRoot)) {
+        const file = path.join(root, 'logs', 'error.log');
+        const info = await stat(file).catch(() => undefined);
+        if (info?.isFile() === true) {
+            found = { file, size: info.size, modified: info.mtimeMs };
+            break;
+        }
+    }
+    if (found === undefined)
+        throw new ServiceError('ERROR_LOG_NOT_FOUND', 'No logs/error.log was found in the game user-data folder; launch the game once, or set gameUserRoot in the server configuration');
+    signal?.throwIfAborted();
+    const { text, truncated } = await readTail(found.file, found.size);
+    const roots = [workspace.modRoot, ...workspace.dependencyRoots, workspace.gameRoot ?? ''].filter(Boolean);
+    // Join continuation lines to the entry they belong to.
+    const raw = [];
+    text.split(/\r?\n/u).forEach((line, index) => {
+        const header = headerPattern.exec(line);
+        if (header !== null)
+            raw.push({ time: header[1], module: header[2], message: header[3], logLine: index + 1 });
+        else if (line.trim() !== '' && raw.length > 0)
+            raw.at(-1).message += ` ${line.trim()}`;
+        else if (line.trim() !== '')
+            raw.push({ module: '', message: line.trim(), logLine: index + 1 });
+    });
+    const grouped = new Map();
+    for (const [order, item] of raw.entries()) {
+        signal?.throwIfAborted();
+        const message = item.message.slice(0, MAX_MESSAGE_CHARACTERS);
+        const key = `${item.module}\0${message}`;
+        const existing = grouped.get(key);
+        if (existing !== undefined) {
+            existing.count += 1;
+            continue;
+        }
+        const located = locate(message, roots);
+        const source = located === undefined
+            ? undefined
+            : {
+                relativePath: located.relativePath.slice(0, 1024),
+                ...(located.line === undefined ? {} : { line: located.line }),
+                ...(await layerOf(workspace, located.relativePath, found.modified)),
+            };
+        grouped.set(key, {
+            category: classify(item.module, message),
+            module: item.module.slice(0, 128),
+            message,
+            count: 1,
+            firstLogLine: item.logLine,
+            ...(item.time === undefined ? {} : { time: item.time }),
+            ...(source === undefined ? {} : { source }),
+            order,
+        });
+    }
+    const layerRank = { mod: 0, dependency: 1, unknown: 2, game: 3 };
+    const all = [...grouped.values()].sort((left, right) => layerRank[left.source?.layer ?? 'unknown'] - layerRank[right.source?.layer ?? 'unknown'] ||
+        left.order - right.order);
+    const selected = all.filter((entry) => (input.scope === 'all' ||
+        (input.scope === 'mod' && entry.source?.layer === 'mod') ||
+        (input.scope === 'unlocated' && entry.source === undefined)) &&
+        (input.category === undefined || entry.category === input.category) &&
+        (input.query === undefined ||
+            entry.message.toLowerCase().includes(input.query.toLowerCase()) ||
+            entry.source?.relativePath.toLowerCase().includes(input.query.toLowerCase()) === true));
+    const launches = await compareWithPreviousLaunch(workspace, new Date(found.modified).toISOString(), all.map((entry) => ({
+        module: entry.module,
+        message: entry.message,
+        category: entry.category,
+        ...(entry.source === undefined ? {} : { relativePath: entry.source.relativePath }),
+    })));
+    const previousKeys = launches.previous === undefined ? undefined : new Set(Object.keys(launches.previous.entries));
+    const currentKeys = new Set(Object.keys(launches.current.entries));
+    const patterns = new Map();
+    for (const entry of selected) {
+        const pattern = errorLogPattern(entry.message);
+        const totals = patterns.get(pattern) ?? {
+            category: entry.category,
+            distinct: 0,
+            entries: 0,
+            example: entry.message,
+        };
+        totals.distinct += 1;
+        totals.entries += entry.count;
+        patterns.set(pattern, totals);
+    }
+    const categories = new Map();
+    for (const entry of selected) {
+        const totals = categories.get(entry.category) ?? { entries: 0, distinct: 0 };
+        totals.entries += entry.count;
+        totals.distinct += 1;
+        categories.set(entry.category, totals);
+    }
+    const page = selected.slice(input.offset, input.offset + input.limit);
+    return {
+        log: {
+            path: 'user:logs/error.log',
+            modifiedAt: new Date(found.modified).toISOString(),
+            bytes: found.size,
+            truncated,
+            entries: raw.length,
+        },
+        scope: input.scope,
+        totalEntries: selected.reduce((sum, entry) => sum + entry.count, 0),
+        distinctEntries: selected.length,
+        modEntries: all.filter((entry) => entry.source?.layer === 'mod').length,
+        changedSinceLog: all.filter((entry) => entry.source?.changedSinceLog === true).length,
+        categories: [...categories]
+            .map(([category, totals]) => ({ category, ...totals, hint: categoryHints[category] }))
+            .sort((left, right) => right.entries - left.entries),
+        patterns: [...patterns]
+            .filter(([, totals]) => totals.distinct > 1)
+            .sort(([, left], [, right]) => right.distinct - left.distinct || right.entries - left.entries)
+            .slice(0, 8)
+            .map(([pattern, totals]) => ({ pattern, ...totals })),
+        ...(launches.previous === undefined || previousKeys === undefined
+            ? {}
+            : {
+                sinceLastLaunch: {
+                    previousLogAt: launches.previous.modifiedAt,
+                    newEntries: [...currentKeys].filter((key) => !previousKeys.has(key)).length,
+                    persistingEntries: [...currentKeys].filter((key) => previousKeys.has(key)).length,
+                    resolvedEntries: [...previousKeys].filter((key) => !currentKeys.has(key)).length,
+                    resolvedExamples: Object.entries(launches.previous.entries)
+                        .filter(([key]) => !currentKeys.has(key))
+                        .slice(0, 5)
+                        .map(([, entry]) => entry),
+                },
+            }),
+        entries: page.map(({ order: _order, ...entry }) => ({
+            ...entry,
+            ...knownMistakeOf(entry.message),
+            ...(previousKeys === undefined
+                ? {}
+                : { new: !previousKeys.has(entryKey(entry.module, entry.message)) }),
+        })),
+        offset: input.offset,
+        ...(input.offset + page.length < selected.length
+            ? { nextOffset: input.offset + page.length }
+            : {}),
+    };
+}