hoi4-agent-tools 3.1.0 → 3.3.0

package/dist/hoi4_agent_tools/mechanic/service.js

@@ -0,0 +1,145 @@
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.js';
+import { copyScenario } from '../core/scenario-model.js';
+import { inspectDecisionCost } from '../decision/cost.js';
+import { decisionSourceInventory } from '../decision/source-inventory.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { evaluateMechanicAssertions } from './assertions.js';
+import { MechanicInterpreter } from './interpreter.js';
+import { scriptedEffectSources, selectMechanicSource } from './source.js';
+export function runMechanicCase(snapshot, test) {
+    // Zod's optional output permits explicit undefined; JSON cloning drops those
+    // keys before the stricter internal scenario interface is used.
+    const scenario = JSON.parse(JSON.stringify(test.scenario));
+    const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
+    const interpreter = new MechanicInterpreter(scenario, definitions, scriptedEffectSources(snapshot));
+    const before = copyScenario(scenario);
+    const checkpoints = [copyScenario(scenario)];
+    const decisions = decisionSourceInventory(snapshot).decisions;
+    for (const step of test.steps) {
+        if (step.kind === 'advance_days')
+            interpreter.advanceDays(step.days);
+        else {
+            const source = selectMechanicSource(snapshot, step.source);
+            for (let iteration = 0; iteration < step.repeat; iteration += 1) {
+                if (step.source.kind === 'decision') {
+                    const decision = decisions.find(({ id }) => id === step.source.id);
+                    if (decision === undefined)
+                        throw new ServiceError('MECHANIC_SOURCE_MISSING', 'Selected decision is absent', step.source);
+                    const cost = inspectDecisionCost(snapshot, decision, interpreter.result().state.scenario);
+                    if (cost.kind === 'invalid' ||
+                        cost.affordable === 'unresolved' ||
+                        cost.unresolved.length > 0) {
+                        interpreter.unresolvedDecision(decision.path, 'Decision cost or eligibility is unresolved');
+                        continue;
+                    }
+                    if (cost.affordable === 'false') {
+                        interpreter.skipDecision(decision.path, 'Decision is unaffordable');
+                        continue;
+                    }
+                    if (cost.kind === 'engine_political_power') {
+                        if (cost.amount === null) {
+                            interpreter.unresolvedDecision(decision.path, 'Engine cost amount is unresolved');
+                            continue;
+                        }
+                        interpreter.payDecisionCost(cost.amount, decision.path);
+                    }
+                }
+                interpreter.execute(source);
+            }
+        }
+        const current = interpreter.result().state;
+        checkpoints.push({
+            scenario: structuredClone(current.scenario),
+            unknown: new Set(current.unknown),
+            day: current.day,
+        });
+    }
+    const execution = interpreter.result();
+    const assertions = evaluateMechanicAssertions(test.assertions, before, execution.state, checkpoints, execution.trace);
+    return {
+        id: test.id,
+        sourceRevision: snapshot.revision,
+        status: assertions.some(({ status }) => status === 'failed')
+            ? 'failed'
+            : assertions.some(({ status }) => status === 'unresolved') || !execution.complete
+                ? 'unresolved'
+                : 'passed',
+        assertions,
+        trace: execution.trace,
+        unresolved: execution.unresolved,
+        finalState: execution.state.scenario,
+        unknown: [...execution.state.unknown].sort(),
+        day: execution.state.day,
+    };
+}
+/** Source-backed, read-only declared mechanic scenario tests. */
+export class MechanicAnalyzer {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async test(input) {
+        const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        if (input.refresh)
+            this.engine.invalidate(input.workspaceId);
+        const snapshot = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+        if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision)
+            throw new ServiceError('MECHANIC_SOURCE_STALE', 'Mechanic source revision changed', {
+                expectedRevision: input.expectedRevision,
+                observedRevision: snapshot.revision,
+            });
+        const report = {
+            schemaVersion: 'mechanic-test.v1',
+            ...runMechanicCase(snapshot, input.test),
+        };
+        const reportHash = hashCanonical(report);
+        const evidence = analysisSourceEvidence(snapshot);
+        const artifact = await this.engine.artifacts.putChunked(workspace, `mechanic-${reportHash.slice(0, 24)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'mechanic-test',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'mechanic-test.v1',
+            sourceHashes: evidence.sourceHashes,
+            metadata: {
+                beforeRevision: snapshot.revision,
+                sourceInventory: evidence.inventory,
+            },
+        }, 'Revision-pinned mechanic trace and assertion evidence', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            sourceRevision: snapshot.revision,
+            reportHash,
+            status: report.status,
+            assertions: report.assertions.length,
+            passed: report.assertions.filter(({ status }) => status === 'passed').length,
+            failed: report.assertions.filter(({ status }) => status === 'failed').length,
+            unresolved: report.assertions.filter(({ status }) => status === 'unresolved').length +
+                report.unresolved.length,
+            steps: input.test.steps.length,
+        });
+        result.code =
+            report.status === 'passed'
+                ? 'MECHANIC_TEST_PASSED'
+                : report.status === 'failed'
+                    ? 'MECHANIC_TEST_FAILED'
+                    : 'MECHANIC_TEST_UNRESOLVED';
+        result.artifacts = [publicArtifactLink(artifact)];
+        setInlineFilesScanned(result, snapshot.files.map(({ displayPath }) => displayPath));
+        result.validation = {
+            passed: report.status === 'passed',
+            checks: [
+                {
+                    id: 'mechanic-assertions',
+                    passed: report.status === 'passed',
+                    message: report.status === 'passed'
+                        ? 'All declared mechanic assertions passed'
+                        : 'Inspect the linked trace for failed or unresolved assertions',
+                },
+            ],
+        };
+        return result;
+    }
+}

package/dist/hoi4_agent_tools/mechanic/source.js

@@ -0,0 +1,89 @@
+import { assignments, firstScalar, parseClausewitz } from '../core/source/index.js';
+import { ServiceError } from '../core/result.js';
+import { decisionSourceInventory } from '../decision/source-inventory.js';
+const eventKinds = new Set([
+    'country_event',
+    'state_event',
+    'news_event',
+    'unit_leader_event',
+    'operative_leader_event',
+]);
+const optionMetadata = new Set([
+    'name',
+    'ai_chance',
+    'trigger',
+    'highlighted',
+    'original_tag_only',
+    'show_but_dont_execute',
+]);
+function activeDocument(snapshot, path) {
+    const file = snapshot.files.find((candidate) => candidate.displayPath === path && candidate.shadowedBy === undefined);
+    return file === undefined ? undefined : parseClausewitz(file.bytes, file.displayPath);
+}
+function source(id, path, block) {
+    if (block === undefined)
+        throw new ServiceError('MECHANIC_SOURCE_MISSING', 'Selected source has no effect block', {
+            id,
+            path,
+        });
+    return { id, path, block };
+}
+export function selectMechanicSource(snapshot, selector) {
+    if (selector.kind === 'decision') {
+        const decision = decisionSourceInventory(snapshot).decisions.find(({ id }) => id === selector.id);
+        return source(selector.id, decision?.path ?? '', decision?.fields.complete_effect[0]?.value.type === 'block'
+            ? decision.fields.complete_effect[0].value
+            : undefined);
+    }
+    const indexedKind = selector.kind === 'focus_reward'
+        ? 'focus'
+        : selector.kind === 'event_option'
+            ? 'event'
+            : 'scripted_effect';
+    const symbol = snapshot.index.find(indexedKind, selector.id);
+    const document = symbol === undefined ? undefined : activeDocument(snapshot, symbol.path);
+    if (document === undefined)
+        throw new ServiceError('MECHANIC_SOURCE_MISSING', 'Selected source definition is absent', selector);
+    if (selector.kind === 'scripted_effect') {
+        const block = assignments(document.root, selector.id)[0]?.value;
+        return source(selector.id, symbol.path, block?.type === 'block' ? block : undefined);
+    }
+    if (selector.kind === 'event_option') {
+        if (selector.option === undefined)
+            throw new ServiceError('MECHANIC_OPTION_REQUIRED', 'Event option selector requires option');
+        const event = assignments(document.root).find((candidate) => eventKinds.has(candidate.key.value) &&
+            candidate.value.type === 'block' &&
+            firstScalar(candidate.value, 'id')?.value === selector.id);
+        const option = event?.value.type === 'block'
+            ? assignments(event.value, 'option').find((candidate) => candidate.value.type === 'block' &&
+                firstScalar(candidate.value, 'name')?.value === selector.option)
+            : undefined;
+        if (option?.value.type !== 'block')
+            throw new ServiceError('MECHANIC_OPTION_MISSING', 'Selected event option is absent', selector);
+        return source(selector.id + ':' + selector.option, symbol.path, {
+            ...option.value,
+            entries: option.value.entries.filter((entry) => entry.type !== 'assignment' || !optionMetadata.has(entry.key.value)),
+        });
+    }
+    const focusTree = assignments(document.root, 'focus_tree');
+    const focus = focusTree
+        .flatMap((tree) => (tree.value.type === 'block' ? assignments(tree.value, 'focus') : []))
+        .find((candidate) => candidate.value.type === 'block' &&
+        firstScalar(candidate.value, 'id')?.value === selector.id);
+    const reward = focus?.value.type === 'block'
+        ? assignments(focus.value, 'completion_reward')[0]?.value
+        : undefined;
+    return source(selector.id, symbol.path, reward?.type === 'block' ? reward : undefined);
+}
+export function scriptedEffectSources(snapshot) {
+    const result = new Map();
+    for (const symbol of snapshot.index.symbols) {
+        if (symbol.kind !== 'scripted_effect' || symbol.overridden || symbol.sourceShadowed)
+            continue;
+        const document = activeDocument(snapshot, symbol.path);
+        const block = document === undefined ? undefined : assignments(document.root, symbol.id)[0]?.value;
+        if (block?.type === 'block')
+            result.set(symbol.id, { id: symbol.id, path: symbol.path, block });
+    }
+    return result;
+}

package/dist/hoi4_agent_tools/package-check/service.js

@@ -0,0 +1,231 @@
+import { readFile, stat } from 'node:fs/promises';
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical, sha256Bytes } from '../core/canonical.js';
+import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.js';
+import { parseClausewitz } from '../core/source/index.js';
+import { scenarioSuiteSchema } from '../schemas/scenarios.js';
+import { PACKAGE_VERSION } from '../version.js';
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+function registrationPresent(bytes, path, token) {
+    if (!/\.(?:txt|gfx|gui|asset)$/iu.test(path))
+        return undefined;
+    const document = parseClausewitz(bytes, path);
+    if (document.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'))
+        return undefined;
+    const visit = (entry) => {
+        if (entry.type === 'scalar')
+            return entry.value === token;
+        if (entry.type === 'block')
+            return entry.entries.some(visit);
+        return entry.key.value === token || visit(entry.value);
+    };
+    return visit(document.root);
+}
+function indexedChecks(snapshot, manifest) {
+    const results = [];
+    const semantic = manifest.calls.length > 0 ? scanImpactSemanticReferences(snapshot) : undefined;
+    const references = semantic === undefined
+        ? snapshot.index.references
+        : [...snapshot.index.references, ...semantic.references];
+    for (const definition of manifest.definitions) {
+        const active = snapshot.index.find(definition.kind, definition.id);
+        const all = snapshot.index.findAll(definition.kind, definition.id);
+        const file = snapshot.files.find(({ displayPath }) => displayPath === active?.path);
+        results.push({
+            category: 'definition',
+            id: `${definition.kind}:${definition.id}`,
+            status: active === undefined
+                ? all.length > 0
+                    ? 'shadowed'
+                    : snapshot.complete
+                        ? 'absent'
+                        : 'unresolved'
+                : 'present',
+            ...(active?.path === undefined ? {} : { path: active.path }),
+            ...(file?.sha256 === undefined ? {} : { sha256: file.sha256 }),
+        });
+    }
+    for (const call of manifest.calls) {
+        const from = snapshot.index.find(call.from.kind, call.from.id);
+        const to = snapshot.index.find(call.to.kind, call.to.id);
+        const reference = references.find((candidate) => candidate.from === call.from.id &&
+            candidate.toKind === call.to.kind &&
+            candidate.to === call.to.id &&
+            candidate.path === from?.path);
+        results.push({
+            category: 'call',
+            id: `${call.from.kind}:${call.from.id}->${call.to.kind}:${call.to.id}`,
+            status: from === undefined || to === undefined
+                ? snapshot.complete
+                    ? 'absent'
+                    : 'unresolved'
+                : reference === undefined
+                    ? snapshot.complete && (semantic?.complete ?? true)
+                        ? 'absent'
+                        : 'unresolved'
+                    : 'present',
+            ...(reference?.path === undefined ? {} : { path: reference.path }),
+        });
+    }
+    for (const id of manifest.localisation) {
+        const symbol = snapshot.index.find('localisation', id) ??
+            snapshot.index.find('localisation', `l_english:${id}`);
+        results.push({
+            category: 'localisation',
+            id,
+            status: symbol === undefined ? (snapshot.complete ? 'absent' : 'unresolved') : 'present',
+            ...(symbol?.path === undefined ? {} : { path: symbol.path }),
+        });
+    }
+    return results;
+}
+/** Declarative package inventory; no manifest field is interpreted as code. */
+export class PackageAnalyzer {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async check(input) {
+        const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        if (input.refresh)
+            this.engine.invalidate(input.workspaceId);
+        const snapshot = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+        if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision)
+            throw new ServiceError('PACKAGE_SOURCE_STALE', 'Package source revision changed', {
+                expectedRevision: input.expectedRevision,
+                observedRevision: snapshot.revision,
+            });
+        const results = indexedChecks(snapshot, input.manifest);
+        const read = async (relativePath) => {
+            const resolved = await this.engine.resolver.resolvePath(input.workspaceId, relativePath, 'read', ['mod', 'game', 'dependency', 'fixture'], input.principal);
+            const metadata = await stat(resolved.path);
+            if (!metadata.isFile() || metadata.size > MAX_FILE_BYTES)
+                throw new ServiceError('PACKAGE_FILE_LIMIT', 'Package file exceeds the bounded reader');
+            return { bytes: await readFile(resolved.path), path: resolved.path };
+        };
+        for (const registration of input.manifest.registrations) {
+            input.signal?.throwIfAborted();
+            try {
+                const file = await read(registration.path);
+                const present = registrationPresent(file.bytes, registration.path, registration.token);
+                results.push({
+                    category: 'registration',
+                    id: `${registration.path}:${registration.token}`,
+                    status: present === undefined ? 'unresolved' : present ? 'present' : 'absent',
+                    path: registration.path,
+                    sha256: sha256Bytes(file.bytes),
+                    ...(present === undefined ? { reason: 'PACKAGE_REGISTRATION_UNSUPPORTED_SOURCE' } : {}),
+                });
+            }
+            catch (error) {
+                if (error.name === 'AbortError')
+                    throw error;
+                results.push({
+                    category: 'registration',
+                    id: `${registration.path}:${registration.token}`,
+                    status: error instanceof ServiceError && error.code === 'PATH_NOT_FOUND_IN_ROOTS'
+                        ? 'absent'
+                        : 'unresolved',
+                    reason: error instanceof ServiceError ? error.code : 'PACKAGE_FILE_READ',
+                });
+            }
+        }
+        for (const asset of input.manifest.assets) {
+            input.signal?.throwIfAborted();
+            try {
+                const file = await read(asset);
+                results.push({
+                    category: 'asset',
+                    id: asset,
+                    status: 'present',
+                    path: asset,
+                    sha256: sha256Bytes(file.bytes),
+                });
+            }
+            catch (error) {
+                if (error.name === 'AbortError')
+                    throw error;
+                results.push({
+                    category: 'asset',
+                    id: asset,
+                    status: error instanceof ServiceError && error.code === 'PATH_NOT_FOUND_IN_ROOTS'
+                        ? 'absent'
+                        : 'unresolved',
+                    reason: error instanceof ServiceError ? error.code : 'PACKAGE_FILE_READ',
+                });
+            }
+        }
+        for (const required of input.manifest.requiredCases) {
+            input.signal?.throwIfAborted();
+            try {
+                const file = await read(required.suite);
+                const suite = scenarioSuiteSchema.parse(JSON.parse(file.bytes.toString('utf8')));
+                results.push({
+                    category: 'required_case',
+                    id: `${required.suite}:${required.caseId}`,
+                    status: suite.cases.some(({ id }) => id === required.caseId) ? 'present' : 'absent',
+                    path: required.suite,
+                    sha256: sha256Bytes(file.bytes),
+                });
+            }
+            catch (error) {
+                if (error.name === 'AbortError')
+                    throw error;
+                results.push({
+                    category: 'required_case',
+                    id: `${required.suite}:${required.caseId}`,
+                    status: error instanceof ServiceError && error.code === 'PATH_NOT_FOUND_IN_ROOTS'
+                        ? 'absent'
+                        : 'unresolved',
+                    reason: error instanceof ServiceError ? error.code : 'PACKAGE_SUITE_INVALID',
+                });
+            }
+        }
+        const report = {
+            schemaVersion: 'package-check.v1',
+            packageId: input.manifest.id,
+            sourceRevision: snapshot.revision,
+            manifestHash: hashCanonical(input.manifest),
+            items: results,
+            complete: snapshot.complete && results.every(({ status }) => status === 'present'),
+        };
+        const reportHash = hashCanonical(report);
+        const evidence = analysisSourceEvidence(snapshot);
+        const artifact = await this.engine.artifacts.putChunked(workspace, `package-${reportHash.slice(0, 24)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'package-check',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'package-check.v1',
+            sourceHashes: evidence.sourceHashes,
+            metadata: { beforeRevision: snapshot.revision, sourceInventory: evidence.inventory },
+        }, 'Revision-pinned package connection inventory', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            sourceRevision: snapshot.revision,
+            reportHash,
+            complete: report.complete,
+            items: results.length,
+            present: results.filter(({ status }) => status === 'present').length,
+            absent: results.filter(({ status }) => status === 'absent').length,
+            shadowed: results.filter(({ status }) => status === 'shadowed').length,
+            unresolved: results.filter(({ status }) => status === 'unresolved').length,
+        });
+        result.code = report.complete ? 'PACKAGE_CHECK_PASSED' : 'PACKAGE_CHECK_INCOMPLETE';
+        result.artifacts = [publicArtifactLink(artifact)];
+        setInlineFilesScanned(result, snapshot.files.map(({ displayPath }) => displayPath));
+        result.validation = {
+            passed: report.complete,
+            checks: [
+                {
+                    id: 'package-connections',
+                    passed: report.complete,
+                    message: report.complete
+                        ? 'Every declared package connection is present'
+                        : 'A declared package connection is absent, shadowed, or unresolved',
+                },
+            ],
+        };
+        return result;
+    }
+}

package/dist/hoi4_agent_tools/probability/evaluation.js

@@ -1,4 +1,5 @@
 import { compareCodeUnits } from '../core/canonical.js';
+import { scenarioFromProbability } from '../core/scenario-model.js';
 import { assignments } from '../core/source/index.js';
 import { Rational, sumRationals, uniformRaceProbabilities } from './rational.js';
 import { withScenarioPathValue } from './scenario-state.js';
@@ -84,8 +85,9 @@ function externalFactor(surface, candidate, scenario) {
     return { factor, trace, unresolved };
 }
 export function evaluateExactCandidates(surface, scenario, definitions) {
+    const declaredConditions = scenarioFromProbability(scenario);
     const candidates = surface.candidates.map((candidate) => {
-        const eligibility = evaluateTriggerBlock(candidate.eligibilityBlock, scenario, candidate, definitions);
+        const eligibility = evaluateTriggerBlock(candidate.eligibilityBlock, declaredConditions, candidate, definitions);
         const value = evaluateCandidateValue(candidate, scenario, definitions);
         const external = externalFactor(surface, candidate, scenario);
         const exactValue = eligibility.state === 'false'