hoi4-agent-tools 3.4.1 → 3.5.1

package/dist/hoi4_agent_tools/probability/service.js

@@ -962,7 +962,7 @@ export class ProbabilityAnalyzer {
             adapter !== undefined &&
             adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest inspection requires adapter custom_weighted_pool');
-        const snapshot = await this.scan(context, [source?.path], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(context, [source?.path, source?.snapshotPath], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
         if (customPoolManifest !== undefined) {
             const surface = customSurface(customPoolManifest, snapshot.revision);
             const gameVersionVerification = await this.verifyGameVersion(context, 'custom_weighted_pool');
@@ -1150,7 +1150,7 @@ export class ProbabilityAnalyzer {
             request.adapter !== undefined &&
             request.adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest requires the custom_weighted_pool adapter');
-        const snapshot = await this.scan(request, [request.source?.path], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(request, [request.source?.path, request.source?.snapshotPath], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
         const resolvedAdapter = usingManifest
             ? 'custom_weighted_pool'
             : resolveSourceBackedAdapter(snapshot, request.source, request.candidatePool ?? [], request.adapter);

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

@@ -319,6 +319,22 @@ function candidatesFor(context, adapterId) {
     }
 }
 function sourceContexts(snapshot, source) {
+    if (source.snapshotPath !== undefined) {
+        if (source.path === undefined ||
+            source.expectedSourceHash === undefined ||
+            source.inlineClausewitz !== undefined ||
+            source.virtualPatch !== undefined)
+            throw new ServiceError('PROBABILITY_SNAPSHOT_CONTRACT_REQUIRED', 'Frozen source requires a logical path and exact snapshot hash');
+        const snapshotPath = normalized(source.snapshotPath);
+        const selected = snapshot.files.filter((file) => file.shadowedBy === undefined && normalized(file.relativePath) === snapshotPath);
+        if (selected.length !== 1)
+            throw new ServiceError('PROBABILITY_SNAPSHOT_NOT_FOUND', 'Frozen source must resolve to one active authorized file', { snapshotPath: source.snapshotPath });
+        const original = selected[0];
+        if (original.sha256 !== source.expectedSourceHash)
+            throw new ServiceError('PROBABILITY_SOURCE_STALE', 'Frozen probability source hash is stale', { expectedSourceHash: source.expectedSourceHash, actualSourceHashes: [original.sha256] });
+        const file = { ...original, relativePath: normalized(source.path) };
+        return [{ file, document: parseClausewitz(file.bytes, file.displayPath) }];
+    }
     if (source.inlineClausewitz !== undefined || source.virtualPatch !== undefined) {
         const text = source.virtualPatch ?? source.inlineClausewitz ?? '';
         const bytes = Buffer.from(text, 'utf8');

package/dist/hoi4_agent_tools/probability/value-evaluator.js

@@ -198,6 +198,7 @@ export function evaluateValueBlock(block, candidate, scenario, definitions, init
     const trace = [];
     const unresolved = [];
     const referencedProvenance = [];
+    const { candidateOverrides: _eligibilityOverrides, ...modifierScenario } = scenario;
     if (block === undefined)
         return { value: initial, interval: current, trace, unresolved };
     for (const assignment of assignments(block)) {
@@ -257,7 +258,7 @@ export function evaluateValueBlock(block, candidate, scenario, definitions, init
         if (assignment.key.value !== 'modifier')
             continue;
         const modifier = assignment.value;
-        const condition = evaluateTriggerBlock(conditionBlock(modifier), scenario, candidate, definitions);
+        const condition = evaluateTriggerBlock(conditionBlock(modifier), modifierScenario, candidate, definitions);
         const conditionExpression = conditionSignature(conditionBlock(modifier));
         unresolved.push(...condition.unresolved);
         referencedProvenance.push(...(condition.helperProvenance ?? []));

package/dist/hoi4_agent_tools/reference/lines.js

@@ -0,0 +1,52 @@
+import { ServiceError } from '../core/result.js';
+/** Preserve source text while bounding one reply by lines and UTF-8 bytes. */
+export function readBoundedLines(lines, firstLine, startLine, startColumn, maxLines, maxBytes) {
+    let lineIndex = startLine - firstLine;
+    let columnIndex = startColumn - 1;
+    if (lineIndex < 0 || lineIndex >= lines.length || columnIndex > (lines[lineIndex]?.length ?? 0)) {
+        throw new ServiceError('REFERENCE_POSITION_OUTSIDE_SECTION', 'Requested position is outside the selected section');
+    }
+    const first = lines[lineIndex];
+    if (columnIndex > 0 &&
+        /[\uD800-\uDBFF]/u.test(first[columnIndex - 1]) &&
+        /[\uDC00-\uDFFF]/u.test(first[columnIndex] ?? '')) {
+        throw new ServiceError('REFERENCE_POSITION_OUTSIDE_SECTION', 'Requested column splits a Unicode character');
+    }
+    const selected = [];
+    let bytes = 0;
+    let endLine = startLine;
+    while (lineIndex < lines.length && selected.length < maxLines) {
+        const line = lines[lineIndex];
+        const remainder = line.slice(columnIndex);
+        const separator = selected.length === 0 ? 0 : 1;
+        const allowance = maxBytes - bytes - separator;
+        if (allowance <= 0)
+            break;
+        let consumed = 0;
+        let used = 0;
+        for (const character of remainder) {
+            const characterBytes = Buffer.byteLength(character, 'utf8');
+            if (used + characterBytes > allowance)
+                break;
+            consumed += character.length;
+            used += characterBytes;
+        }
+        if (consumed === 0 && remainder.length > 0)
+            break;
+        selected.push(remainder.slice(0, consumed));
+        bytes += separator + used;
+        endLine = firstLine + lineIndex;
+        if (consumed < remainder.length) {
+            columnIndex += consumed;
+            break;
+        }
+        lineIndex++;
+        columnIndex = 0;
+    }
+    return {
+        text: selected.join('\n'),
+        endLine,
+        nextLine: lineIndex < lines.length ? firstLine + lineIndex : null,
+        nextColumn: lineIndex < lines.length ? columnIndex + 1 : null,
+    };
+}

package/dist/hoi4_agent_tools/reference/operations.js

@@ -0,0 +1,41 @@
+import { requireOperationScope, resolveOperationWorkspaceId, } from '../core/operation-context.js';
+import { emptyServiceResult } from '../core/result.js';
+import { toolResult } from '../core/operation-result.js';
+import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, } from '../schemas/reference.js';
+import { ReferenceService } from './service.js';
+import { sourceLookup } from './source-lookup.js';
+const schemas = {
+    'hoi4.reference_search': referenceSearchRequestSchema,
+    'hoi4.reference_read': referenceReadRequestSchema,
+    'hoi4.reference_context': referenceContextRequestSchema,
+    'hoi4.source_lookup': sourceLookupRequestSchema,
+};
+export function isReferenceTool(name) {
+    return Object.hasOwn(schemas, name);
+}
+const sharedReferences = new WeakMap();
+/** One authorization and execution contract for both MCP protocol adapters. */
+export class ReferenceToolService {
+    engine;
+    references;
+    constructor(engine) {
+        this.engine = engine;
+        const cached = sharedReferences.get(engine) ?? new ReferenceService();
+        sharedReferences.set(engine, cached);
+        this.references = cached;
+    }
+    async call(name, input, context, signal) {
+        requireOperationScope(context, 'hoi4:read');
+        const parsed = schemas[name].parse(input);
+        const workspaceId = await resolveOperationWorkspaceId(this.engine, context, parsed.workspaceId, signal);
+        const workspace = this.engine.resolver.get(workspaceId, context.principal);
+        const data = name === 'hoi4.reference_search'
+            ? await this.references.search(workspace, referenceSearchRequestSchema.parse(parsed), signal)
+            : name === 'hoi4.reference_read'
+                ? await this.references.read(workspace, referenceReadRequestSchema.parse(parsed), signal)
+                : name === 'hoi4.reference_context'
+                    ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
+                    : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
+        return toolResult(emptyServiceResult(workspaceId, data));
+    }
+}

package/dist/hoi4_agent_tools/reference/service.js

@@ -0,0 +1,444 @@
+import { open, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { isWithin } from '../core/workspace.js';
+import { readBoundedLines } from './lines.js';
+import { readBoundedFile } from '../core/scanner.js';
+const MAX_FILES = 512;
+const MAX_FILE_BYTES = 2_000_000;
+const MAX_TOTAL_BYTES = 32_000_000;
+const MAX_SECTIONS = 20_000;
+const searchStopWords = new Set([
+    'a',
+    'an',
+    'and',
+    'at',
+    'be',
+    'can',
+    'come',
+    'do',
+    'does',
+    'for',
+    'from',
+    'how',
+    'in',
+    'is',
+    'of',
+    'the',
+    'to',
+    'where',
+    'with',
+    'work',
+]);
+function normalizeTerm(term) {
+    if (term === 'dated')
+        return 'date';
+    if (term.endsWith('ies') && term.length > 5)
+        return `${term.slice(0, -3)}y`;
+    if (term.endsWith('ses') && term.length > 5)
+        return term.slice(0, -2);
+    if (term.endsWith('s') && term.length > 4)
+        return term.slice(0, -1);
+    return term;
+}
+function queryTerms(query) {
+    return [
+        ...new Set((query.toLowerCase().match(/[a-z0-9_.:-]+/gu) ?? [])
+            .map(normalizeTerm)
+            .filter((term) => /[a-z0-9]/u.test(term) && !searchStopWords.has(term))),
+    ];
+}
+function containsTerm(text, term) {
+    if (term.length > 2)
+        return text.includes(term);
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`(^|[^a-z0-9_])${escaped}($|[^a-z0-9_])`, 'u').test(text);
+}
+function snippet(lines, terms = []) {
+    let matching = -1;
+    let best = -1;
+    for (const [index, line] of lines.entries()) {
+        const count = terms.filter((term) => containsTerm(line.toLowerCase(), term)).length;
+        if (count > best) {
+            matching = index;
+            best = count;
+        }
+    }
+    const selected = lines
+        .slice(Math.max(0, matching), Math.max(0, matching) + 3)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(' ');
+    return selected.slice(0, 300);
+}
+function sectionize(root, filePath, content, revision) {
+    const lines = content.replace(/^\uFEFF/u, '').split(/\r?\n/u);
+    const relative = path.relative(root.root, filePath).replaceAll('\\', '/');
+    const title = path
+        .basename(filePath)
+        .replace(/\.(md|log)$/u, '')
+        .replaceAll('_', ' ')
+        .replace(/ - Hearts of Iron 4 Wiki$/u, '');
+    const headings = [];
+    let inFence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/^\s*(```|~~~)/u.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/u.exec(line);
+        if (match)
+            headings.push({ heading: match[2].replace(/<a\b[^>]*><\/a>/gu, '').trim(), start: index });
+        else if (root.kind === 'script_doc' &&
+            filePath.endsWith('.log') &&
+            /^[A-Za-z_][A-Za-z0-9_.:-]*$/u.test(line.trim()) &&
+            !/^\s/u.test(line) &&
+            /^\s+\S/u.test(lines[index + 1] ?? '')) {
+            headings.push({ heading: line.trim(), start: index });
+        }
+    }
+    if (headings.length === 0 || headings[0].start > 0)
+        headings.unshift({ heading: title, start: 0 });
+    return headings.map((current, index) => {
+        const end = headings[index + 1]?.start ?? lines.length;
+        const sectionLines = lines.slice(current.start, end);
+        const id = sha256Bytes(Buffer.from(`${root.kind}\0${relative}\0${current.start + 1}\0${current.heading}`, 'utf8'));
+        return {
+            id,
+            revision,
+            source: root.kind,
+            title,
+            heading: current.heading.slice(0, 512),
+            path: filePath,
+            startLine: current.start + 1,
+            endLine: end,
+            excerpt: snippet(sectionLines),
+            authority: root.authority,
+            lines: sectionLines,
+        };
+    });
+}
+function sourceRoots(workspace) {
+    const gameRoot = workspace.gameRoot ?? (workspace.registration.kind === 'game' ? workspace.modRoot : undefined);
+    return [
+        ...(gameRoot === undefined
+            ? []
+            : [
+                {
+                    kind: 'game_doc',
+                    root: gameRoot,
+                    patterns: ['documentation/**/*.md', 'common/**/*documentation.md'],
+                    authority: 'Installed game documentation',
+                },
+            ]),
+        {
+            kind: 'wiki',
+            root: workspace.wikiRoot ?? path.join(workspace.modRoot, 'paradox_wiki'),
+            patterns: ['**/*.md'],
+            authority: 'Offline Paradox Wiki snapshot',
+        },
+        {
+            kind: 'script_doc',
+            root: workspace.scriptDocsRoot ?? path.join(workspace.modRoot, 'script_docs'),
+            patterns: ['**/*.md', '**/*.log'],
+            authority: 'User-provided game script documentation',
+        },
+    ];
+}
+const surfaceNames = {
+    general: ['Data structures', 'Triggers', 'Effects', 'Modifiers', 'Scopes'],
+    event: [
+        'Event modding',
+        'Data structures',
+        'Effects',
+        'Triggers',
+        'Scopes',
+        'On actions',
+        'Localisation',
+    ],
+    decision: ['Decision modding', 'Effects', 'Triggers', 'Scopes', 'Localisation'],
+    idea: ['Idea modding', 'Modifiers', 'Localisation'],
+    focus: ['National focus modding', 'AI focuses', 'Effects', 'Triggers', 'Localisation'],
+    technology: ['Technology modding', 'Equipment modding', 'Modifiers', 'Localisation'],
+    gui: [
+        'Interface modding',
+        'Scripted GUI modding',
+        'Graphical asset modding',
+        'Localisation',
+        'Scopes',
+    ],
+    map: [
+        'Map modding',
+        'State modding',
+        'Strategic region modding',
+        'Bookmark modding',
+        'Localisation',
+    ],
+    localisation: ['Localisation', 'Data structures'],
+    ai: ['AI modding', 'AI focuses', 'Triggers', 'Scopes'],
+};
+const gameDocNames = {
+    general: ['documentation/script_concept_documentation'],
+    event: [
+        'documentation/effects_documentation',
+        'documentation/triggers_documentation',
+        'common/on_actions/_documentation',
+    ],
+    decision: ['common/decisions/_documentation', 'documentation/effects_documentation'],
+    idea: ['documentation/modifiers_documentation'],
+    focus: [
+        'documentation/effects_documentation',
+        'documentation/triggers_documentation',
+        'common/focus_inlay_windows/documentation',
+    ],
+    technology: ['common/units/equipment/_documentation', 'documentation/modifiers_documentation'],
+    gui: ['common/scripted_guis/_documentation'],
+    map: ['common/map_modes/documentation', 'common/strategic_locations/documentation'],
+    localisation: [
+        'documentation/loc_formatter_documentation',
+        'documentation/loc_objects_documentation',
+    ],
+    ai: ['common/ai_strategy/_documentation', 'documentation/triggers_documentation'],
+};
+/** A workspace-private, read-only reference index over explicitly known local roots. */
+export class ReferenceService {
+    #cache = new Map();
+    #cacheBytes = 0;
+    retain(key, value) {
+        this.#cacheBytes -= this.#cache.get(key)?.bytes ?? 0;
+        this.#cache.delete(key);
+        this.#cache.set(key, value);
+        this.#cacheBytes += value.bytes;
+        while (this.#cacheBytes > MAX_TOTAL_BYTES || this.#cache.size > 1_024) {
+            const oldest = this.#cache.entries().next().value;
+            if (oldest === undefined)
+                break;
+            this.#cache.delete(oldest[0]);
+            this.#cacheBytes -= oldest[1].bytes;
+        }
+    }
+    async inventory(workspace, signal) {
+        const sections = [];
+        const coverage = {
+            game_doc: { files: 0, sections: 0, unavailable: true },
+            wiki: { files: 0, sections: 0, unavailable: true },
+            script_doc: { files: 0, sections: 0, unavailable: true },
+        };
+        let skipped = 0;
+        let bytes = 0;
+        for (const root of sourceRoots(workspace)) {
+            signal?.throwIfAborted();
+            let canonicalRoot;
+            try {
+                canonicalRoot = await realpath(root.root);
+            }
+            catch {
+                coverage[root.kind].unavailable = true;
+                continue;
+            }
+            const configuredAuthorityRoot = root.kind === 'game_doc'
+                ? root.root
+                : root.kind === 'wiki'
+                    ? (workspace.wikiRoot ?? workspace.modRoot)
+                    : (workspace.scriptDocsRoot ?? workspace.modRoot);
+            if (!isWithin(configuredAuthorityRoot, canonicalRoot)) {
+                throw new ServiceError('REFERENCE_ROOT_ESCAPE', 'Reference root resolves outside its configured workspace');
+            }
+            coverage[root.kind].unavailable = false;
+            const names = await fg(root.patterns, {
+                cwd: canonicalRoot,
+                onlyFiles: true,
+                followSymbolicLinks: false,
+                dot: false,
+            });
+            names.sort(compareCodeUnits);
+            for (const name of names) {
+                signal?.throwIfAborted();
+                if (coverage[root.kind].files >= MAX_FILES || sections.length >= MAX_SECTIONS) {
+                    skipped++;
+                    continue;
+                }
+                const candidate = path.join(canonicalRoot, name);
+                const canonical = await realpath(candidate);
+                if (!isWithin(canonicalRoot, canonical)) {
+                    skipped++;
+                    continue;
+                }
+                const metadata = await stat(canonical);
+                if (metadata.size > MAX_FILE_BYTES || bytes + metadata.size > MAX_TOTAL_BYTES) {
+                    skipped++;
+                    continue;
+                }
+                bytes += metadata.size;
+                coverage[root.kind].files++;
+                const key = `${root.kind}:${canonicalRoot}:${canonical}`;
+                const handle = await open(canonical, 'r');
+                let content;
+                try {
+                    const opened = await handle.stat();
+                    const resolvedAfterOpen = await realpath(canonical);
+                    const current = await stat(resolvedAfterOpen);
+                    if (!opened.isFile() ||
+                        !isWithin(canonicalRoot, resolvedAfterOpen) ||
+                        opened.dev !== current.dev ||
+                        opened.ino !== current.ino) {
+                        throw new ServiceError('REFERENCE_SOURCE_CHANGED', 'Reference path changed while opening it; retry the request');
+                    }
+                    content = await readBoundedFile(handle, Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - bytes + metadata.size), signal);
+                }
+                finally {
+                    await handle.close();
+                }
+                bytes += content.length - metadata.size;
+                const revision = sha256Bytes(content);
+                let cached = this.#cache.get(key);
+                if (cached?.revision !== revision) {
+                    cached = {
+                        revision,
+                        bytes: content.length,
+                        sections: sectionize(root, canonical, content.toString('utf8'), revision),
+                    };
+                }
+                this.retain(key, cached);
+                const admitted = cached.sections.slice(0, MAX_SECTIONS - sections.length);
+                if (admitted.length < cached.sections.length)
+                    skipped++;
+                sections.push(...admitted);
+                coverage[root.kind].sections += admitted.length;
+            }
+        }
+        return { sections, coverage, skipped };
+    }
+    async search(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const matches = this.rank(inventory.sections, input.query, input.sources);
+        return {
+            results: matches.slice(0, input.limit).map(({ section, score, excerpt }) => ({
+                ...this.publicSection(section),
+                score,
+                excerpt,
+            })),
+            total: matches.length,
+            coverage: inventory.coverage,
+            skipped: inventory.skipped,
+        };
+    }
+    rank(sections, question, sources) {
+        const query = question.toLowerCase();
+        const terms = queryTerms(query);
+        return sections
+            .flatMap((section) => {
+            if (sources !== undefined && !sources.includes(section.source))
+                return [];
+            const title = section.title.toLowerCase();
+            const heading = section.heading.toLowerCase();
+            const body = section.lines.join('\n').toLowerCase();
+            let matched = 0;
+            let score = 0;
+            for (const term of terms) {
+                const inTitle = containsTerm(title, term);
+                const inHeading = containsTerm(heading, term);
+                const inBody = containsTerm(body, term);
+                if (!inTitle && !inHeading && !inBody)
+                    continue;
+                matched++;
+                score += (inTitle ? 24 : 0) + (inHeading ? 18 : 0) + (inBody ? 3 : 0);
+            }
+            if (matched < Math.max(1, Math.ceil(terms.length * 0.6)))
+                return [];
+            if (heading === query)
+                score += 100;
+            else if (heading.includes(query))
+                score += 70;
+            if (body.includes(query))
+                score += 30;
+            return [{ section, score, excerpt: snippet(section.lines, terms) }];
+        })
+            .sort((left, right) => right.score - left.score ||
+            compareCodeUnits(left.section.path, right.section.path) ||
+            left.section.startLine - right.section.startLine);
+    }
+    async read(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const section = inventory.sections.find(({ id }) => id === input.id);
+        if (section === undefined)
+            throw new ServiceError('REFERENCE_SECTION_UNKNOWN', 'Reference section is not in this workspace');
+        if (section.revision !== input.revision)
+            throw new ServiceError('REFERENCE_REVISION_STALE', 'Reference source changed; search again', {
+                currentRevision: section.revision,
+            });
+        const startLine = input.startLine ?? section.startLine;
+        const selected = readBoundedLines(section.lines, section.startLine, startLine, input.startColumn ?? 1, input.maxLines, 8_000);
+        return {
+            ...this.publicSection(section),
+            sectionStartLine: section.startLine,
+            sectionEndLine: section.endLine,
+            startLine,
+            startColumn: input.startColumn ?? 1,
+            ...selected,
+        };
+    }
+    async context(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const wanted = surfaceNames[input.surface];
+        const ranked = input.question === undefined ? [] : this.rank(inventory.sections, input.question);
+        const required = [];
+        const missing = [];
+        const includeRequired = (name, section) => {
+            if (section === undefined) {
+                missing.push(name);
+                return;
+            }
+            const matching = ranked.find((entry) => entry.section.path === section.path && entry.section.source === section.source);
+            required.push({ name, section: matching?.section ?? section });
+        };
+        for (const name of [...new Set(wanted)]) {
+            const section = inventory.sections.find((entry) => entry.source === 'wiki' && entry.title.toLowerCase() === name.toLowerCase());
+            includeRequired(name, section);
+        }
+        for (const name of gameDocNames[input.surface]) {
+            const section = inventory.sections.find((entry) => entry.source === 'game_doc' &&
+                entry.path.replaceAll('\\', '/').toLowerCase().endsWith(`${name}.md`));
+            includeRequired(name, section);
+        }
+        const questionOrder = new Map(ranked.map(({ section }, index) => [section.id, index]));
+        const byQuestion = (left, right) => (questionOrder.get(left.section.id) ?? Number.MAX_SAFE_INTEGER) -
+            (questionOrder.get(right.section.id) ?? Number.MAX_SAFE_INTEGER);
+        const game = required.filter(({ section }) => section.source === 'game_doc').sort(byQuestion);
+        const wiki = required.filter(({ section }) => section.source === 'wiki').sort(byQuestion);
+        const seen = new Set();
+        const prioritized = [
+            ...[...game.slice(0, 1), ...wiki.slice(0, 1), ...game.slice(1), ...wiki.slice(1)].map(({ section }) => section),
+            ...ranked.slice(0, 5).map(({ section }) => section),
+        ].filter((section) => {
+            if (seen.has(section.id))
+                return false;
+            seen.add(section.id);
+            return true;
+        });
+        const selected = prioritized.slice(0, input.limit);
+        return {
+            surface: input.surface,
+            sections: selected.map((section) => ({
+                ...this.publicSection(section),
+                excerpt: ranked.find((entry) => entry.section.id === section.id)?.excerpt ?? section.excerpt,
+            })),
+            omitted: Math.max(0, prioritized.length - input.limit),
+            omittedSources: required
+                .filter(({ section }) => !selected.some((entry) => entry.path === section.path && entry.source === section.source))
+                .map(({ name }) => name),
+            missing,
+            coverage: inventory.coverage,
+            skipped: inventory.skipped,
+        };
+    }
+    publicSection(section) {
+        const { lines: _lines, ...publicSection } = section;
+        return publicSection;
+    }
+}