hoi4-agent-tools 3.0.9 → 3.2.0

package/dist/hoi4_agent_tools/core/transaction-execution.js

@@ -0,0 +1,134 @@
+import { canonicalJson } from './canonical.js';
+import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
+import { ServiceError } from './result.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { postValidateTransaction } from './domain-validation.js';
+import { MAX_INLINE_ARTIFACT_LINKS } from './result.js';
+export class AutonomousRewriteError extends ServiceError {
+    manifest;
+    artifacts;
+    constructor(cause, manifest, artifacts = []) {
+        const restored = manifest.state === 'rolled_back' && manifest.rollbackStatus === 'applied';
+        const code = cause.code.startsWith('TRANSACTION_')
+            ? `REWRITE_${cause.code.slice('TRANSACTION_'.length)}`
+            : cause.code;
+        super(code, restored
+            ? 'Rewrite verification failed and the original files were restored'
+            : 'Rewrite failed and automatic recovery could not be completed', {
+            execution: 'failed',
+            automaticRecovery: restored ? 'restored' : 'incomplete',
+        });
+        this.manifest = manifest;
+        this.artifacts = artifacts;
+        this.name = 'AutonomousRewriteError';
+    }
+}
+async function storeAutonomousValidationEvidence(engine, manifest, postValidation, principal, signal) {
+    const diagnostics = [...manifest.diagnostics, ...postValidation.diagnostics];
+    const checks = [...manifest.validation.checks, ...postValidation.checks];
+    const passed = manifest.validation.passed &&
+        checks.every((check) => check.passed) &&
+        !diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+    const sourceEvidence = boundedSourceHashEvidence(Object.fromEntries(manifest.files.flatMap(({ relativePath, afterSha256 }) => afterSha256 === null ? [] : [[relativePath, afterSha256]])));
+    const artifact = await engine.artifacts.putChunked(engine.resolver.get(manifest.workspaceId, principal), `${manifest.operationKind}.execution-validation.json`, 'application/json', `${canonicalJson({
+        schemaVersion: 1,
+        execution: passed ? 'post-validation-passed' : 'post-validation-failed',
+        operationKind: manifest.operationKind,
+        files: manifest.files.map(({ relativePath, afterSha256, afterSize, mediaType }) => ({
+            relativePath,
+            afterSha256,
+            afterSize,
+            mediaType,
+        })),
+        validation: { passed, checks },
+        diagnostics,
+        resources: postValidation.artifacts,
+    })}\n`, {
+        kind: 'autonomous-rewrite-execution-validation',
+        toolVersion: PACKAGE_VERSION,
+        schemaVersion: 'autonomous-rewrite-execution-validation.v1',
+        sourceHashes: sourceEvidence.sourceHashes,
+        metadata: {
+            operationKind: manifest.operationKind,
+            fileCount: manifest.files.length,
+            checkCount: checks.length,
+            diagnosticCount: diagnostics.length,
+            sourceHashInventory: sourceEvidence.inventory,
+        },
+    }, 'Complete rewrite and post-write validation evidence', signal);
+    return publicArtifactLink(artifact);
+}
+function uniqueArtifacts(artifacts) {
+    const unique = new Map();
+    for (const artifact of artifacts)
+        unique.set(artifact.uri, artifact);
+    return [...unique.values()].slice(0, MAX_INLINE_ARTIFACT_LINKS);
+}
+export function autonomousResultArtifacts(execution) {
+    return uniqueArtifacts([
+        ...execution.artifacts,
+        ...(execution.transaction.executionArtifacts ?? []),
+        ...execution.transaction.artifacts,
+    ]);
+}
+/**
+ * Complete a validated domain rewrite inside one MCP tool call. Hash checks, durable recovery,
+ * post-write validation, and automatic failure recovery remain internal guarantees.
+ */
+export async function executePlannedTransaction(engine, transaction, principal, signal, hooks = {}) {
+    if (!transaction.validation.passed) {
+        return { transaction, outcome: 'blocked', artifacts: [] };
+    }
+    if (transaction.files.length === 0)
+        return { transaction, outcome: 'unchanged', artifacts: [] };
+    signal?.throwIfAborted();
+    await hooks.beforeApply?.(transaction);
+    signal?.throwIfAborted();
+    let executionArtifacts = [];
+    try {
+        const applied = await engine.transactions.apply(transaction.workspaceId, transaction.transactionId, transaction.planHash, {
+            ...(principal === undefined ? {} : { principal }),
+            ...(signal === undefined ? {} : { signal }),
+            postValidate: async (manifest, validationSignal) => {
+                const validation = await postValidateTransaction(engine, manifest, principal, validationSignal);
+                executionArtifacts = [...validation.artifacts];
+                executionArtifacts.unshift(await storeAutonomousValidationEvidence(engine, manifest, validation, principal, validationSignal));
+                return { ...validation, artifacts: executionArtifacts };
+            },
+        });
+        // Post-validation already invalidates and rebuilds the shared index before apply can succeed.
+        return { transaction: applied, outcome: 'applied', artifacts: executionArtifacts };
+    }
+    catch (error) {
+        engine.invalidate(transaction.workspaceId);
+        try {
+            const manifest = await engine.transactions.status(transaction.workspaceId, transaction.transactionId, principal);
+            const cause = error instanceof ServiceError
+                ? error
+                : new ServiceError('AUTONOMOUS_REWRITE_FAILED', 'Autonomous rewrite failed');
+            throw new AutonomousRewriteError(cause, manifest, executionArtifacts);
+        }
+        catch (statusError) {
+            if (statusError instanceof AutonomousRewriteError)
+                throw statusError;
+            throw error;
+        }
+    }
+}
+export function autonomousFailureContext(error) {
+    if (!(error instanceof AutonomousRewriteError))
+        return undefined;
+    const manifest = error.manifest;
+    return {
+        proposedFiles: manifest.files.slice(0, 100).map(({ relativePath }) => relativePath),
+        changedFiles: manifest.rollbackStatus === 'failed'
+            ? manifest.files.slice(0, 100).map(({ relativePath }) => relativePath)
+            : [],
+        artifacts: uniqueArtifacts([
+            ...error.artifacts,
+            ...(manifest.executionArtifacts ?? []),
+            ...manifest.artifacts,
+        ]),
+        validation: manifest.validation,
+    };
+}

package/dist/hoi4_agent_tools/core/transactions.js

@@ -312,6 +312,7 @@ export class TransactionManager {
                 diagnostics,
                 validation: { passed, checks: validation.checks },
                 artifacts,
+                executionArtifacts: [],
                 appliedFiles: [],
                 rollbackStatus: 'available',
             };
@@ -398,11 +399,17 @@ export class TransactionManager {
                 }
                 if (manifest.diagnostics.length + result.diagnostics.length > TRANSACTION_MAX_DIAGNOSTICS ||
                     manifest.validation.checks.length + result.checks.length >
-                        TRANSACTION_MAX_VALIDATION_CHECKS) {
-                    throw new ServiceError('TRANSACTION_STRUCTURE_LIMIT', 'Post-write validation exceeds the supported transaction review structure limits');
+                        TRANSACTION_MAX_VALIDATION_CHECKS ||
+                    (manifest.executionArtifacts?.length ?? 0) + (result.artifacts?.length ?? 0) >
+                        TRANSACTION_MAX_ARTIFACTS) {
+                    throw new ServiceError('TRANSACTION_STRUCTURE_LIMIT', 'Post-write validation exceeds the supported transaction review or artifact limits');
                 }
                 manifest.diagnostics.push(...result.diagnostics);
                 manifest.validation.checks.push(...result.checks);
+                manifest.executionArtifacts ??= [];
+                for (const artifact of result.artifacts ?? [])
+                    if (!manifest.executionArtifacts.some(({ uri }) => uri === artifact.uri))
+                        manifest.executionArtifacts.push(artifact);
                 manifest.validation.passed =
                     manifest.validation.passed &&
                         result.checks.every(({ passed }) => passed) &&
@@ -513,6 +520,61 @@ export class TransactionManager {
             totalSize: cached.bytes.length,
         };
     }
+    /** Reconcile one interrupted job's journal without sweeping unrelated transactions. */
+    async recoverTransaction(workspaceId, transactionId, principal, signal) {
+        signal?.throwIfAborted();
+        const workspace = this.resolver.get(workspaceId, principal);
+        // Authenticate the selected journal and authorize its owner before changing protected state.
+        const initial = await this.load(workspace, transactionId, {
+            headMode: 'none',
+            ...(signal === undefined ? {} : { signal }),
+        });
+        this.assertRecoveryPrincipal(initial, principal);
+        return this.withWorkspaceLock(workspace, transactionId, async () => {
+            signal?.throwIfAborted();
+            // Never restore a pre-lock snapshot: a writer may have committed since the first read.
+            const current = await this.load(workspace, transactionId, {
+                headMode: 'none',
+                ...(signal === undefined ? {} : { signal }),
+            });
+            this.assertRecoveryPrincipal(current, principal);
+            const manifest = await this.load(workspace, transactionId, {
+                headMode: 'reconcile',
+                ...(signal === undefined ? {} : { signal }),
+            });
+            signal?.throwIfAborted();
+            if (manifest.state === 'applying' || manifest.state === 'rolling_back') {
+                await this.restoreInterruptedTransaction(workspace, manifest, principal);
+            }
+            return manifest;
+        });
+    }
+    assertRecoveryPrincipal(manifest, principal) {
+        if (principal !== undefined && (manifest.principal ?? null) !== principal) {
+            throw new ServiceError('TRANSACTION_PRINCIPAL_MISMATCH', 'Transaction recovery belongs to another principal');
+        }
+    }
+    async restoreInterruptedTransaction(workspace, manifest, principal) {
+        // Restoration and authenticated journal advancement are a non-cancellable critical phase.
+        try {
+            await this.restoreBeforeState(workspace, manifest, principal);
+            manifest.state = 'rolled_back';
+            manifest.failure = {
+                code: 'TRANSACTION_RECOVERED',
+                message: 'Incomplete transaction was rolled back during recovery',
+            };
+            await this.writeManifest(workspace, manifest);
+        }
+        catch (error) {
+            manifest.rollbackStatus = 'failed';
+            manifest.state = 'failed';
+            manifest.failure = this.safeFailure(error, 'TRANSACTION_RECOVERY_FAILED', 'Interrupted transaction could not be recovered safely');
+            await this.writeManifest(workspace, manifest);
+            if (error instanceof ServiceError)
+                throw error;
+            throw new ServiceError('TRANSACTION_RECOVERY_FAILED', 'Interrupted transaction could not be recovered safely');
+        }
+    }
     async recover(workspaceId, principal, signal) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
@@ -536,38 +598,29 @@ export class TransactionManager {
             if (!transactionIdPattern.test(entry.name))
                 continue;
             const manifest = await this.load(workspace, entry.name, {
-                headMode: 'reconcile',
+                headMode: 'none',
                 ...(signal === undefined ? {} : { signal }),
             });
-            if (principal !== undefined && (manifest.principal ?? null) !== principal) {
-                throw new ServiceError('TRANSACTION_PRINCIPAL_MISMATCH', 'Transaction recovery belongs to another principal');
-            }
-            if (manifest.state !== 'applying' && manifest.state !== 'rolling_back')
-                continue;
-            await this.withWorkspaceLock(workspace, manifest.transactionId, async () => {
-                signal?.throwIfAborted();
-                // Once source restoration starts, recovery and authenticated journal
-                // advancement form a non-cancellable critical phase.
+            this.assertRecoveryPrincipal(manifest, principal);
+            const interrupted = manifest.state === 'applying' || manifest.state === 'rolling_back';
+            if (!interrupted) {
                 try {
-                    await this.restoreBeforeState(workspace, manifest, principal);
-                    manifest.state = 'rolled_back';
-                    manifest.failure = {
-                        code: 'TRANSACTION_RECOVERED',
-                        message: 'Incomplete transaction was rolled back during recovery',
-                    };
-                    await this.writeManifest(workspace, manifest);
+                    // Ordinary startup must not contend with a live writer just to read terminal journals.
+                    await this.load(workspace, entry.name, {
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+                    continue;
                 }
                 catch (error) {
-                    manifest.rollbackStatus = 'failed';
-                    manifest.state = 'failed';
-                    manifest.failure = this.safeFailure(error, 'TRANSACTION_RECOVERY_FAILED', 'Interrupted transaction could not be recovered safely');
-                    await this.writeManifest(workspace, manifest);
-                    if (error instanceof ServiceError)
+                    if (!(error instanceof ServiceError) ||
+                        error.code !== 'TRANSACTION_HEAD_RECONCILIATION_REQUIRED')
                         throw error;
-                    throw new ServiceError('TRANSACTION_RECOVERY_FAILED', 'Interrupted transaction could not be recovered safely');
                 }
-            });
-            recovered.push(manifest);
+            }
+            const reconciled = await this.recoverTransaction(workspaceId, entry.name, principal, signal);
+            if (interrupted) {
+                recovered.push(reconciled);
+            }
         }
         return recovered;
     }

package/dist/hoi4_agent_tools/decision/ai.js

@@ -0,0 +1,104 @@
+import { ProbabilityAnalyzer } from '../probability/service.js';
+import { decisionSourceInventory } from './source-inventory.js';
+function selected(snapshot, id) {
+    return decisionSourceInventory(snapshot).decisions.find(({ id: candidate }) => candidate === id);
+}
+function summary(result) {
+    return {
+        analysisId: result.analysisId,
+        status: result.status,
+        adapter: result.adapter.id,
+        sourceHash: result.metadata.sourceHash,
+        scenarios: result.scenarios.map((scenario) => ({
+            id: scenario.id,
+            candidates: scenario.candidates.map((candidate) => ({
+                id: candidate.id,
+                eligibility: candidate.eligibility,
+                supportLevel: candidate.supportLevel,
+                ...(candidate.rawValue === undefined ? {} : { rawValue: candidate.rawValue }),
+                unresolved: candidate.unresolved,
+            })),
+            unresolved: scenario.unresolved,
+        })),
+        unresolved: result.unresolved,
+        ...(result.comparison === undefined ? {} : { comparison: result.comparison }),
+        resources: result.resources,
+    };
+}
+/** Uses the existing score-only probability adapters; never invents decision selection odds. */
+export async function inspectDecisionAi(engine, before, id, scenarios, overlay, principal, signal) {
+    const source = selected(before, id);
+    const proposed = overlay === undefined ? undefined : selected(overlay.snapshot, id);
+    const baselineWeighted = (source?.fields.ai_will_do.length ?? 0) > 0;
+    const proposedWeighted = (proposed?.fields.ai_will_do.length ?? 0) > 0;
+    if (!baselineWeighted && !proposedWeighted)
+        return undefined;
+    const subject = source ?? proposed;
+    const adapter = subject.kind === 'mission' ? 'mission_ai_will_do' : 'decision_ai_will_do';
+    const scenarioSet = {
+        schemaVersion: '1.0',
+        id: `decision-${id}`,
+        scenarios: scenarios.map(({ closedFlags: _closedFlags, ...scenario }) => scenario),
+    };
+    const analyzer = new ProbabilityAnalyzer(engine);
+    const workspaceId = before.workspaceId;
+    const context = {
+        workspaceId,
+        adapter,
+        scenarioSet,
+        outputs: ['json'],
+        ...(principal === undefined ? {} : { principal }),
+        ...(signal === undefined ? {} : { signal }),
+    };
+    const sourceFile = source === undefined
+        ? undefined
+        : before.files.find(({ displayPath }) => displayPath === source.path);
+    const baselineSelector = sourceFile === undefined
+        ? undefined
+        : { path: sourceFile.relativePath, identifier: id, expectedSourceHash: sourceFile.sha256 };
+    const proposedFile = proposed === undefined
+        ? undefined
+        : overlay?.snapshot.files.find(({ displayPath }) => displayPath === proposed.path);
+    const proposedSelector = proposedFile === undefined
+        ? undefined
+        : { virtualPatch: proposedFile.bytes.toString('utf8'), identifier: id };
+    const isolatedProposal = overlay?.changes.length === 1 &&
+        proposedFile !== undefined &&
+        overlay.changes[0]?.path === proposedFile.displayPath;
+    if (baselineWeighted &&
+        proposedWeighted &&
+        isolatedProposal &&
+        baselineSelector &&
+        proposedSelector) {
+        const compared = await analyzer.compare({
+            ...context,
+            before: baselineSelector,
+            after: proposedSelector,
+        });
+        return { mode: 'compare', ...summary(compared) };
+    }
+    if (baselineWeighted && baselineSelector) {
+        const evaluated = await analyzer.evaluate({ ...context, source: baselineSelector });
+        return {
+            mode: 'baseline',
+            ...summary(evaluated),
+            ...(overlay === undefined
+                ? {}
+                : {
+                    proposedUnresolved: 'The proposal changes multiple sources or adds/removes the weighted decision; use probability_compare with explicit source selectors',
+                }),
+        };
+    }
+    if (proposedWeighted && proposedSelector) {
+        const evaluated = await analyzer.evaluate({ ...context, source: proposedSelector });
+        return {
+            mode: 'proposed',
+            ...summary(evaluated),
+            baselineUnresolved: 'The baseline has no matching weighted decision',
+        };
+    }
+    return {
+        mode: 'unresolved',
+        reason: 'Weighted decision source could not be selected for probability analysis',
+    };
+}

package/dist/hoi4_agent_tools/decision/comparison.js

@@ -0,0 +1,106 @@
+import { hashCanonical } from '../core/canonical.js';
+import { inspectDecisionCost } from './cost.js';
+import { evaluateDecisionGates } from './evaluation.js';
+import { inspectDecisionLifecycle } from './lifecycle.js';
+import { decisionSourceInventory, decisionTargetCatalog, } from './source-inventory.js';
+export function inspectDecisionScenario(snapshot, id, scenario) {
+    const source = decisionSourceInventory(snapshot).decisions.find((candidate) => candidate.id === id);
+    if (source === undefined)
+        return null;
+    return {
+        targeting: decisionTargetCatalog(source),
+        gates: evaluateDecisionGates(snapshot, id, scenario),
+        cost: inspectDecisionCost(snapshot, source, scenario),
+        lifecycle: inspectDecisionLifecycle(snapshot, source, scenario),
+    };
+}
+function differences(before, after) {
+    if (before === null || after === null)
+        return before === after ? [] : ['definition'];
+    const fields = [
+        ['targeting', before.targeting, after.targeting],
+        ['category_allowed', before.gates.categoryAllowed.state, after.gates.categoryAllowed.state],
+        ['decision_allowed', before.gates.decisionAllowed.state, after.gates.decisionAllowed.state],
+        ['category_visible', before.gates.categoryVisible.state, after.gates.categoryVisible.state],
+        [
+            'decision_visible',
+            before.gates.decisionVisible?.state ?? null,
+            after.gates.decisionVisible?.state ?? null,
+        ],
+        [
+            'category_available',
+            before.gates.categoryAvailable.state,
+            after.gates.categoryAvailable.state,
+        ],
+        [
+            'decision_available',
+            before.gates.decisionAvailable.state,
+            after.gates.decisionAvailable.state,
+        ],
+        ['eligible', before.gates.eligible, after.gates.eligible],
+        ['visible', before.gates.visible, after.gates.visible],
+        ['available', before.gates.available, after.gates.available],
+        ['target_selection', before.gates.targetSelection.state, after.gates.targetSelection.state],
+        ['target_trigger', before.gates.targetTrigger.state, after.gates.targetTrigger.state],
+        ['cost_kind', before.cost.kind, after.cost.kind],
+        ['cost_amount', before.cost.amount, after.cost.amount],
+        ['affordable', before.cost.affordable, after.cost.affordable],
+        [
+            'payment_effects',
+            before.cost.paymentEffects.map(({ resource, amount, operation, scope }) => ({
+                resource,
+                amount,
+                operation,
+                scope,
+            })),
+            after.cost.paymentEffects.map(({ resource, amount, operation, scope }) => ({
+                resource,
+                amount,
+                operation,
+                scope,
+            })),
+        ],
+        ['lifecycle', before.lifecycle, after.lifecycle],
+    ];
+    return fields
+        .filter(([, left, right]) => hashCanonical(left) !== hashCanonical(right))
+        .map(([field]) => field);
+}
+/** Compare declared scenarios against two revision-pinned source snapshots. */
+export function compareDecisionScenarios(before, after, id, scenarios) {
+    if (before.workspaceId !== after.workspaceId)
+        throw new Error('Decision comparison crosses workspace boundaries');
+    if (scenarios.length < 1 || scenarios.length > 64)
+        throw new RangeError('Decision comparison requires 1-64 scenarios');
+    if (id.length === 0 || id.length > 512)
+        throw new RangeError('Decision identifier is invalid');
+    const seen = new Set();
+    const cases = scenarios.map((scenario) => {
+        if (seen.has(scenario.id))
+            throw new Error(`Duplicate decision scenario: ${scenario.id}`);
+        seen.add(scenario.id);
+        const baseline = inspectDecisionScenario(before, id, scenario);
+        const proposed = inspectDecisionScenario(after, id, scenario);
+        return {
+            scenarioId: scenario.id,
+            before: baseline,
+            after: proposed,
+            changed: differences(baseline, proposed),
+        };
+    });
+    return {
+        id,
+        beforeRevision: before.revision,
+        afterRevision: after.revision,
+        complete: before.complete &&
+            after.complete &&
+            cases.every(({ before: baseline, after: proposed }) => (baseline !== null || proposed !== null) &&
+                (baseline?.gates.complete ?? true) &&
+                (proposed?.gates.complete ?? true) &&
+                (baseline?.cost.unresolved.length ?? 0) === 0 &&
+                (proposed?.cost.unresolved.length ?? 0) === 0 &&
+                (baseline?.lifecycle.unresolved.length ?? 0) === 0 &&
+                (proposed?.lifecycle.unresolved.length ?? 0) === 0),
+        cases,
+    };
+}

package/dist/hoi4_agent_tools/decision/cost.js

@@ -0,0 +1,177 @@
+import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
+import { evaluateTriggerBlock, resolveConditionNumber } from '../core/condition-evaluator.js';
+import { rootScopeContext } from '../core/scenario-state.js';
+import { assignments, nodeLocation } from '../core/source/index.js';
+function scalar(assignment) {
+    return assignment?.value.type === 'scalar' ? assignment.value.value : undefined;
+}
+function unresolved(source, message) {
+    return {
+        code: 'DECISION_COST_UNRESOLVED',
+        message,
+        candidateId: source.id,
+        provenance: {
+            path: source.path,
+            rootKind: source.rootKind,
+            loadOrder: source.loadOrder,
+            sourceHash: source.sourceHash,
+            ...(source.location === undefined ? {} : { location: source.location }),
+            symbol: source.id,
+        },
+    };
+}
+function directPayments(snapshot, source, scenario, definitions) {
+    const paymentEffects = [];
+    const conditionalOrHelperEffects = [];
+    for (const effect of source.fields.complete_effect) {
+        if (effect.value.type !== 'block') {
+            conditionalOrHelperEffects.push('malformed complete_effect');
+            continue;
+        }
+        for (const entry of assignments(effect.value)) {
+            const key = entry.key.value;
+            let resource;
+            let operation;
+            let expression;
+            if (key === 'add_political_power' || key === 'add_command_power') {
+                resource = key.slice(4);
+                operation = 'add';
+                expression = scalar(entry);
+            }
+            else if (key === 'add_to_variable' || key === 'subtract_from_variable') {
+                if (entry.value.type === 'block') {
+                    const values = assignments(entry.value).filter(({ key: field }) => field.value !== 'tooltip');
+                    if (values.length === 1) {
+                        resource = `variable.${values[0].key.value}`;
+                        operation = key === 'add_to_variable' ? 'add' : 'subtract';
+                        expression = scalar(values[0]);
+                    }
+                }
+            }
+            if (resource !== undefined && operation !== undefined) {
+                const amount = expression === undefined
+                    ? undefined
+                    : resolveConditionNumber(expression, scenario, rootScopeContext(scenario), definitions, source.path);
+                const normalizedOperation = amount !== undefined && amount < 0
+                    ? operation === 'add'
+                        ? 'subtract'
+                        : 'add'
+                    : operation;
+                paymentEffects.push({
+                    resource,
+                    amount: amount === undefined ? null : Math.abs(amount),
+                    operation: normalizedOperation,
+                    scope: 'ROOT',
+                    location: nodeLocation(source.document, entry, key),
+                });
+                if (amount === undefined)
+                    conditionalOrHelperEffects.push(`dynamic payment: ${key}`);
+            }
+            else if (key === 'add_political_power' ||
+                key === 'add_command_power' ||
+                key === 'add_to_variable' ||
+                key === 'subtract_from_variable') {
+                conditionalOrHelperEffects.push(`unparsed payment: ${key}`);
+            }
+            else if (snapshot.index.find('scripted_effect', key) !== undefined ||
+                ['if', 'else_if', 'else', 'random', 'random_list', 'ROOT', 'FROM', 'meta_effect'].includes(key)) {
+                conditionalOrHelperEffects.push(key);
+            }
+        }
+    }
+    return { paymentEffects, conditionalOrHelperEffects };
+}
+/** Cost and payment evidence is source-bounded; a custom cost is never treated as automatic payment. */
+export function inspectDecisionCost(snapshot, source, scenario) {
+    const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
+    const base = directPayments(snapshot, source, scenario, definitions);
+    const cost = source.fields.cost;
+    const custom = source.fields.custom_cost_trigger;
+    const findings = [];
+    const deductions = base.paymentEffects.filter(({ operation }) => operation === 'subtract');
+    const seenDeductions = new Set();
+    for (const deduction of deductions) {
+        if (seenDeductions.has(deduction.resource))
+            findings.push(unresolved(source, `Multiple direct payments deduct ${deduction.resource}`));
+        seenDeductions.add(deduction.resource);
+    }
+    if (cost.length > 1 || custom.length > 1 || (cost.length > 0 && custom.length > 0)) {
+        findings.push(unresolved(source, 'Conflicting or repeated decision cost declarations'));
+        return {
+            kind: 'invalid',
+            expression: null,
+            amount: null,
+            affordable: 'unresolved',
+            ...base,
+            unresolved: findings,
+        };
+    }
+    if (cost.length === 1) {
+        if (deductions.some(({ resource }) => resource === 'political_power'))
+            findings.push(unresolved(source, 'Engine political-power cost also has an explicit political-power deduction'));
+        const expression = scalar(cost[0]);
+        const amount = expression === undefined
+            ? undefined
+            : resolveConditionNumber(expression, scenario, rootScopeContext(scenario), definitions, source.path);
+        const politicalPower = resolveConditionNumber('political_power', scenario, rootScopeContext(scenario), definitions, source.path);
+        if (amount === undefined || amount < 0)
+            findings.push(unresolved(source, 'Engine political-power cost is not a resolved nonnegative number'));
+        if (politicalPower === undefined)
+            findings.push(unresolved(source, 'Scenario does not declare current political power'));
+        return {
+            kind: 'engine_political_power',
+            expression: expression ?? null,
+            amount: amount ?? null,
+            affordable: amount === undefined || amount < 0 || politicalPower === undefined
+                ? 'unresolved'
+                : politicalPower >= amount
+                    ? 'true'
+                    : 'false',
+            ...base,
+            unresolved: findings,
+        };
+    }
+    if (custom.length === 1) {
+        const trigger = custom[0].value;
+        const evaluated = trigger.type === 'block'
+            ? evaluateTriggerBlock(trigger, { ...scenario, closedFlags: scenario.closedFlags ?? false }, {
+                id: source.id,
+                document: source.document,
+                provenance: [
+                    {
+                        path: source.path,
+                        rootKind: source.rootKind,
+                        loadOrder: source.loadOrder,
+                        sourceHash: source.sourceHash,
+                        ...(source.location === undefined ? {} : { location: source.location }),
+                        symbol: source.id,
+                    },
+                ],
+            }, definitions)
+            : {
+                state: 'unresolved',
+                unresolved: [unresolved(source, 'custom_cost_trigger is not a block')],
+            };
+        findings.push(...evaluated.unresolved);
+        if (base.conditionalOrHelperEffects.length > 0)
+            findings.push(unresolved(source, 'Custom payment crosses a conditional, helper, dynamic, or unparsed effect path'));
+        if (base.paymentEffects.length === 0 && base.conditionalOrHelperEffects.length === 0)
+            findings.push(unresolved(source, 'Custom cost has no recognized direct payment effect; other effect semantics remain unverified'));
+        return {
+            kind: 'custom',
+            expression: scalar(source.fields.custom_cost_text[0]) ?? null,
+            amount: null,
+            affordable: evaluated.state,
+            ...base,
+            unresolved: findings,
+        };
+    }
+    return {
+        kind: 'none',
+        expression: null,
+        amount: 0,
+        affordable: 'true',
+        ...base,
+        unresolved: findings,
+    };
+}