agent-scenario-loop 0.1.0

package/dist/core/planner.js

@@ -0,0 +1,812 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCompatibilityHealth = buildCompatibilityHealth;
+exports.buildUnevaluatedVerdict = buildUnevaluatedVerdict;
+exports.collectProvidedDriverActions = collectProvidedDriverActions;
+exports.collectScenarioDriverActions = collectScenarioDriverActions;
+exports.evaluateRunnerCompatibility = evaluateRunnerCompatibility;
+exports.intersection = intersection;
+exports.uniqueSorted = uniqueSorted;
+exports.validateScenarioAdapterOptions = validateScenarioAdapterOptions;
+/**
+ * Returns `value` when it is already an array; otherwise returns an empty array.
+ *
+ * @param {unknown} value
+ * @returns {unknown[]}
+ */
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Returns non-empty string values with duplicates removed and deterministic ordering.
+ *
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+function uniqueSorted(values) {
+    const strings = values.filter((value) => typeof value === 'string' && value.length > 0);
+    return [...new Set(strings)].sort();
+}
+/**
+ * Finds the unique string values shared by two arrays.
+ *
+ * @param {unknown[]} left
+ * @param {unknown[]} right
+ * @returns {string[]}
+ */
+function intersection(left, right) {
+    const rightSet = new Set(asArray(right));
+    return uniqueSorted(asArray(left).filter((value) => rightSet.has(value)));
+}
+/**
+ * Returns required values that are absent from the available set.
+ *
+ * @param {unknown[]} available
+ * @param {unknown[]} required
+ * @returns {unknown[]}
+ */
+function includesAll(available, required) {
+    const availableSet = new Set(asArray(available));
+    return asArray(required).filter((item) => !availableSet.has(item));
+}
+/**
+ * Creates a structured planner issue.
+ *
+ * @param {string} code
+ * @param {string} message
+ * @param {Record<string, unknown>} [metadata]
+ * @returns {Record<string, unknown>}
+ */
+function createIssue(code, message, metadata = {}) {
+    return {
+        code,
+        message,
+        ...metadata,
+    };
+}
+/**
+ * Returns `value` when it is a plain object; otherwise returns an empty object.
+ *
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+/**
+ * Returns true when a value is a finite number.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * Returns true when a value is a positive integer.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * Resolves the stable scenario step identifier used in planner errors.
+ *
+ * @param {Record<string, unknown>} step
+ * @param {number} index
+ * @returns {string}
+ */
+function getScenarioStepId(step, index) {
+    return typeof step.id === 'string' && step.id.length > 0 ? step.id : `step-${index + 1}`;
+}
+/**
+ * Returns true when a scenario step has a portable selector object.
+ *
+ * @param {Record<string, unknown>} step
+ * @returns {boolean}
+ */
+function hasPortableSelector(step) {
+    const selector = asObject(step.selector);
+    return typeof selector.kind === 'string' && typeof selector.value === 'string' && selector.value.length > 0;
+}
+/**
+ * Returns true when a value can be used as an agent-device ref target.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasAgentDeviceRef(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Returns true when a scenario step has an agent-device tap target.
+ *
+ * @param {Record<string, unknown>} step
+ * @returns {boolean}
+ */
+function hasAgentDeviceTapTarget(step) {
+    const agentDevice = asObject(asObject(step.adapterOptions).agentDevice);
+    return (hasPortableSelector(step) ||
+        hasAgentDeviceRef(agentDevice.ref) ||
+        (isFiniteNumber(agentDevice.x) && isFiniteNumber(agentDevice.y)));
+}
+/**
+ * Returns true when a scenario step has Argent tap coordinates.
+ *
+ * @param {Record<string, unknown>} step
+ * @returns {boolean}
+ */
+function hasArgentTapTarget(step) {
+    const argent = asObject(asObject(step.adapterOptions).argent);
+    return isFiniteNumber(argent.x) && isFiniteNumber(argent.y);
+}
+/**
+ * Resolves the stable scenario identifier used in generated artifacts.
+ *
+ * @param {Record<string, unknown> | null | undefined} scenario
+ * @returns {string}
+ */
+function getScenarioId(scenario) {
+    return scenario?.id ?? scenario?.name ?? 'unknown-scenario';
+}
+/**
+ * Resolves the stable runner identifier used in planner errors.
+ *
+ * @param {Record<string, unknown> | null | undefined} runner
+ * @returns {string}
+ */
+function getRunnerId(runner) {
+    return runner?.runnerId ?? runner?.name ?? 'unknown-runner';
+}
+/**
+ * Keeps only scalar issue metadata so health artifacts remain schema-safe.
+ *
+ * @param {Record<string, unknown>} issue
+ * @returns {Record<string, string | number | boolean | null>}
+ */
+function getIssueMetadata(issue) {
+    return Object.keys(issue)
+        .filter((key) => key !== 'code' && key !== 'message')
+        .sort()
+        .reduce((metadata, key) => {
+        const value = issue[key];
+        if (typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean' ||
+            value === null) {
+            metadata[key] = value;
+        }
+        return metadata;
+    }, {});
+}
+/**
+ * Converts a planner issue into a `health.json` check entry.
+ *
+ * @param {Record<string, unknown>} issue
+ * @param {'failed' | 'warning'} status
+ * @returns {Record<string, unknown>}
+ */
+function issueToHealthCheck(issue, status) {
+    const metadata = getIssueMetadata(issue);
+    return {
+        name: issue.code,
+        status,
+        source: issue.code?.includes('artifact') || issue.code?.includes('evidence')
+            ? 'evidence'
+            : 'planner',
+        code: issue.code,
+        message: issue.message,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+    };
+}
+/**
+ * Returns whether a provider can participate in the selected platform set.
+ *
+ * @param {Record<string, unknown>} provider
+ * @param {string[]} effectivePlatforms
+ * @returns {boolean}
+ */
+function isProviderActiveForPlatforms(provider, effectivePlatforms) {
+    return intersection(asArray(provider?.platforms), effectivePlatforms).length > 0;
+}
+/**
+ * Collects artifacts available from the primary runner and active evidence providers.
+ *
+ * @param {{runner: Record<string, unknown>, evidenceProviders: Record<string, unknown>[], effectivePlatforms: string[]}} options
+ * @returns {{activeProviders: Record<string, unknown>[], artifacts: string[]}}
+ */
+function collectProvidedArtifacts({ runner, evidenceProviders, effectivePlatforms, }) {
+    const activeProviders = evidenceProviders.filter((provider) => isProviderActiveForPlatforms(provider, effectivePlatforms));
+    return {
+        activeProviders,
+        artifacts: uniqueSorted([
+            ...asArray(runner?.artifactOutputs),
+            ...activeProviders.flatMap((provider) => asArray(provider?.artifactOutputs)),
+        ]),
+    };
+}
+/**
+ * Collects capabilities available from the primary runner and active evidence providers.
+ *
+ * @param {{runner: Record<string, unknown>, evidenceProviders: Record<string, unknown>[], effectivePlatforms: string[]}} options
+ * @returns {string[]}
+ */
+function collectProvidedCapabilities({ runner, evidenceProviders, effectivePlatforms, }) {
+    const activeProviders = evidenceProviders.filter((provider) => isProviderActiveForPlatforms(provider, effectivePlatforms));
+    return uniqueSorted([
+        ...asArray(runner?.capabilities),
+        ...activeProviders.flatMap((provider) => asArray(provider?.capabilities)),
+    ]);
+}
+/**
+ * Collects driver operations available from the primary runner and active providers.
+ *
+ * @param {{runner: Record<string, unknown>, evidenceProviders: Record<string, unknown>[], effectivePlatforms: string[]}} options
+ * @returns {string[]}
+ */
+function collectProvidedDriverActions({ runner, evidenceProviders, effectivePlatforms, }) {
+    const activeProviders = evidenceProviders.filter((provider) => isProviderActiveForPlatforms(provider, effectivePlatforms));
+    return uniqueSorted([
+        ...asArray(runner?.driverActions),
+        ...activeProviders.flatMap((provider) => asArray(provider?.driverActions)),
+    ]);
+}
+/**
+ * Collects driver operations required by scenario steps.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {{required: string[], optional: string[]}}
+ */
+function collectScenarioDriverActions(scenario) {
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    const required = [];
+    const optional = [];
+    for (const step of steps) {
+        if (!step || typeof step !== 'object' || typeof step.driverAction !== 'string') {
+            continue;
+        }
+        if (step.required === false) {
+            optional.push(step.driverAction);
+        }
+        else {
+            required.push(step.driverAction);
+        }
+    }
+    return {
+        required: uniqueSorted(required),
+        optional: uniqueSorted(optional),
+    };
+}
+/**
+ * Adds a structured invalid-adapter-options issue.
+ *
+ * @param {{adapter: string, errors: PlannerIssue[], field: string, message: string, scenario: ScenarioManifest, stepId?: string}} options
+ * @returns {void}
+ */
+function pushInvalidAdapterOption({ adapter, errors, field, message, scenario, stepId, }) {
+    errors.push(createIssue('invalid_adapter_options', message, {
+        adapter,
+        field,
+        scenarioId: getScenarioId(scenario),
+        ...(stepId ? { stepId } : {}),
+    }));
+}
+/**
+ * Validates Android adb metadata that built-in runners depend on at runtime.
+ *
+ * @param {{scenario: ScenarioManifest, errors: PlannerIssue[]}} options
+ * @returns {void}
+ */
+function validateAndroidAdbAdapterOptions({ errors, scenario, }) {
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    for (const [index, step] of steps.entries()) {
+        if (!step || typeof step !== 'object') {
+            continue;
+        }
+        const androidAdb = asObject(asObject(step.adapterOptions).androidAdb);
+        const stepId = getScenarioStepId(step, index);
+        if (step.driverAction === 'assertVisible' &&
+            !hasPortableSelector(step)) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'selector',
+                message: `Step \`${stepId}\` uses driverAction \`assertVisible\` but a portable selector is required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'tap' &&
+            !hasPortableSelector(step) &&
+            (!isFiniteNumber(androidAdb.x) || !isFiniteNumber(androidAdb.y))) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'x/y',
+                message: `Step \`${stepId}\` uses driverAction \`tap\` but adapterOptions.androidAdb.x/y are required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'scroll' &&
+            !hasPortableSelector(step) &&
+            (!isFiniteNumber(androidAdb.startX) ||
+                !isFiniteNumber(androidAdb.startY) ||
+                !isFiniteNumber(androidAdb.endX) ||
+                !isFiniteNumber(androidAdb.endY))) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'startX/startY/endX/endY',
+                message: `Step \`${stepId}\` uses driverAction \`scroll\` but adapterOptions.androidAdb.startX/startY/endX/endY are required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if ('durationMs' in androidAdb && !isPositiveInteger(androidAdb.durationMs)) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'durationMs',
+                message: `Step \`${stepId}\` has adapterOptions.androidAdb.durationMs, but it must be a positive integer.`,
+                scenario,
+                stepId,
+            });
+        }
+        if ('logcatLines' in androidAdb && !isPositiveInteger(androidAdb.logcatLines)) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'logcatLines',
+                message: `Step \`${stepId}\` has adapterOptions.androidAdb.logcatLines, but it must be a positive integer.`,
+                scenario,
+                stepId,
+            });
+        }
+        if ('waitMs' in androidAdb && !isPositiveInteger(androidAdb.waitMs)) {
+            pushInvalidAdapterOption({
+                adapter: 'androidAdb',
+                errors,
+                field: 'waitMs',
+                message: `Step \`${stepId}\` has adapterOptions.androidAdb.waitMs, but it must be a positive integer.`,
+                scenario,
+                stepId,
+            });
+        }
+    }
+}
+/**
+ * Validates iOS simctl metadata that built-in runners depend on at runtime.
+ *
+ * @param {{scenario: ScenarioManifest, errors: PlannerIssue[]}} options
+ * @returns {void}
+ */
+function validateIosSimctlAdapterOptions({ errors, scenario, }) {
+    const scenarioIosSimctl = asObject(asObject(scenario.adapterOptions).iosSimctl);
+    if ('repeat' in scenarioIosSimctl && !isPositiveInteger(scenarioIosSimctl.repeat)) {
+        pushInvalidAdapterOption({
+            adapter: 'iosSimctl',
+            errors,
+            field: 'repeat',
+            message: 'Scenario adapterOptions.iosSimctl.repeat must be a positive integer.',
+            scenario,
+        });
+    }
+    if ('commands' in scenarioIosSimctl) {
+        if (!Array.isArray(scenarioIosSimctl.commands)) {
+            pushInvalidAdapterOption({
+                adapter: 'iosSimctl',
+                errors,
+                field: 'commands',
+                message: 'Scenario adapterOptions.iosSimctl.commands must be an array when provided.',
+                scenario,
+            });
+        }
+        else {
+            for (const [index, command] of scenarioIosSimctl.commands.entries()) {
+                const commandOptions = asObject(command);
+                if (typeof commandOptions.command !== 'string' || commandOptions.command.length === 0) {
+                    pushInvalidAdapterOption({
+                        adapter: 'iosSimctl',
+                        errors,
+                        field: `commands[${index}].command`,
+                        message: `Scenario adapterOptions.iosSimctl.commands[${index}].command must be a non-empty string.`,
+                        scenario,
+                    });
+                }
+                if ('waitMs' in commandOptions && !isPositiveInteger(commandOptions.waitMs)) {
+                    pushInvalidAdapterOption({
+                        adapter: 'iosSimctl',
+                        errors,
+                        field: `commands[${index}].waitMs`,
+                        message: `Scenario adapterOptions.iosSimctl.commands[${index}].waitMs must be a positive integer.`,
+                        scenario,
+                    });
+                }
+            }
+        }
+    }
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    for (const [index, step] of steps.entries()) {
+        if (!step || typeof step !== 'object') {
+            continue;
+        }
+        const iosSimctl = asObject(asObject(step.adapterOptions).iosSimctl);
+        if ('waitMs' in iosSimctl && !isPositiveInteger(iosSimctl.waitMs)) {
+            const stepId = getScenarioStepId(step, index);
+            pushInvalidAdapterOption({
+                adapter: 'iosSimctl',
+                errors,
+                field: 'waitMs',
+                message: `Step \`${stepId}\` has adapterOptions.iosSimctl.waitMs, but it must be a positive integer.`,
+                scenario,
+                stepId,
+            });
+        }
+    }
+}
+/**
+ * Validates agent-device metadata that the bundled adapter enforces at runtime.
+ *
+ * @param {{scenario: ScenarioManifest, errors: PlannerIssue[]}} options
+ * @returns {void}
+ */
+function validateAgentDeviceAdapterOptions({ errors, scenario, }) {
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    for (const [index, step] of steps.entries()) {
+        if (!step || typeof step !== 'object') {
+            continue;
+        }
+        const selector = asObject(step.selector);
+        const stepId = getScenarioStepId(step, index);
+        if (typeof selector.match === 'string' &&
+            selector.match !== 'exact' &&
+            ['assertVisible', 'tap'].includes(String(step.driverAction))) {
+            pushInvalidAdapterOption({
+                adapter: 'agentDevice',
+                errors,
+                field: 'selector.match',
+                message: `Step \`${stepId}\` uses selector match \`${selector.match}\`, but the agent-device adapter currently supports exact selector matches only.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'assertVisible' && !hasPortableSelector(step)) {
+            pushInvalidAdapterOption({
+                adapter: 'agentDevice',
+                errors,
+                field: 'selector',
+                message: `Step \`${stepId}\` uses driverAction \`assertVisible\` but a portable selector is required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'tap' && !hasAgentDeviceTapTarget(step)) {
+            pushInvalidAdapterOption({
+                adapter: 'agentDevice',
+                errors,
+                field: 'selector/ref/x/y',
+                message: `Step \`${stepId}\` uses driverAction \`tap\` but requires a selector, adapterOptions.agentDevice.ref, or adapterOptions.agentDevice.x/y.`,
+                scenario,
+                stepId,
+            });
+        }
+    }
+}
+/**
+ * Validates Argent metadata that the optional adapter enforces at runtime.
+ *
+ * @param {{scenario: ScenarioManifest, errors: PlannerIssue[]}} options
+ * @returns {void}
+ */
+function validateArgentAdapterOptions({ errors, scenario, }) {
+    const steps = Array.isArray(scenario.steps) ? scenario.steps : [];
+    for (const [index, step] of steps.entries()) {
+        if (!step || typeof step !== 'object') {
+            continue;
+        }
+        const argent = asObject(asObject(step.adapterOptions).argent);
+        const selector = asObject(step.selector);
+        const stepId = getScenarioStepId(step, index);
+        if (step.driverAction === 'assertVisible' && !hasPortableSelector(step)) {
+            pushInvalidAdapterOption({
+                adapter: 'argent',
+                errors,
+                field: 'selector',
+                message: `Step \`${stepId}\` uses driverAction \`assertVisible\` but a portable selector is required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'tap' && !hasArgentTapTarget(step)) {
+            pushInvalidAdapterOption({
+                adapter: 'argent',
+                errors,
+                field: 'x/y',
+                message: `Step \`${stepId}\` uses driverAction \`tap\` but adapterOptions.argent.x/y are required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if (step.driverAction === 'scroll' &&
+            (!isFiniteNumber(argent.startX) ||
+                !isFiniteNumber(argent.startY) ||
+                !isFiniteNumber(argent.endX) ||
+                !isFiniteNumber(argent.endY))) {
+            pushInvalidAdapterOption({
+                adapter: 'argent',
+                errors,
+                field: 'startX/startY/endX/endY',
+                message: `Step \`${stepId}\` uses driverAction \`scroll\` but adapterOptions.argent.startX/startY/endX/endY are required.`,
+                scenario,
+                stepId,
+            });
+        }
+        if ('durationMs' in argent && !isPositiveInteger(argent.durationMs)) {
+            pushInvalidAdapterOption({
+                adapter: 'argent',
+                errors,
+                field: 'durationMs',
+                message: `Step \`${stepId}\` has adapterOptions.argent.durationMs, but it must be a positive integer.`,
+                scenario,
+                stepId,
+            });
+        }
+    }
+}
+/**
+ * Validates adapter-specific scenario metadata for the selected platform set.
+ *
+ * @param {{scenario: ScenarioManifest, effectivePlatforms: string[], errors: PlannerIssue[], runner?: RunnerManifest}} options
+ * @returns {void}
+ */
+function validateScenarioAdapterOptions({ effectivePlatforms, errors, runner, scenario, }) {
+    const runnerId = runner ? getRunnerId(runner) : '';
+    const usesAndroidAdbOptions = Array.isArray(scenario.steps) &&
+        scenario.steps.some((step) => Object.prototype.hasOwnProperty.call(asObject(asObject(step).adapterOptions), 'androidAdb'));
+    if (effectivePlatforms.includes('android') && (runnerId.includes('adb') || usesAndroidAdbOptions)) {
+        validateAndroidAdbAdapterOptions({ errors, scenario });
+    }
+    if (effectivePlatforms.includes('ios')) {
+        validateIosSimctlAdapterOptions({ errors, scenario });
+    }
+    if (runnerId.includes('agent-device')) {
+        validateAgentDeviceAdapterOptions({ errors, scenario });
+    }
+    const usesArgentOptions = Array.isArray(scenario.steps) &&
+        scenario.steps.some((step) => Object.prototype.hasOwnProperty.call(asObject(asObject(step).adapterOptions), 'argent'));
+    if (runnerId.includes('argent') || usesArgentOptions) {
+        validateArgentAdapterOptions({ errors, scenario });
+    }
+}
+/**
+ * Adds planner errors when the selected runner cannot own a run lifecycle.
+ *
+ * @param {{runner: Record<string, unknown>, errors: Record<string, unknown>[]}} options
+ * @returns {void}
+ */
+function validatePrimaryRunner({ runner, errors, }) {
+    if (!runner || typeof runner !== 'object') {
+        errors.push(createIssue('runner_missing', 'A primary runner capability manifest is required.'));
+        return;
+    }
+    if (runner.kind && runner.kind !== 'primary') {
+        errors.push(createIssue('runner_not_primary', 'The selected runner must have kind `primary`.', {
+            runnerId: getRunnerId(runner),
+            kind: runner.kind,
+        }));
+    }
+}
+/**
+ * Determines the platform set a plan should evaluate and records platform mismatches.
+ *
+ * @param {{scenario: Record<string, unknown>, runner: Record<string, unknown>, platform?: string | null, errors: Record<string, unknown>[]}} options
+ * @returns {string[]}
+ */
+function resolveEffectivePlatforms({ scenario, runner, platform, errors, }) {
+    const scenarioPlatforms = asArray(scenario?.platforms);
+    const runnerPlatforms = asArray(runner?.platforms);
+    if (platform) {
+        if (!scenarioPlatforms.includes(platform)) {
+            errors.push(createIssue('platform_not_supported_by_scenario', 'The scenario does not support the selected platform.', {
+                scenarioId: getScenarioId(scenario),
+                platform,
+                supportedPlatforms: uniqueSorted(scenarioPlatforms),
+            }));
+        }
+        if (!runnerPlatforms.includes(platform)) {
+            errors.push(createIssue('platform_not_supported_by_runner', 'The runner does not support the selected platform.', {
+                runnerId: getRunnerId(runner),
+                platform,
+                supportedPlatforms: uniqueSorted(runnerPlatforms),
+            }));
+        }
+        return [platform];
+    }
+    const commonPlatforms = intersection(scenarioPlatforms, runnerPlatforms);
+    if (commonPlatforms.length === 0) {
+        errors.push(createIssue('platform_mismatch', 'The scenario and runner do not share a supported platform.', {
+            scenarioId: getScenarioId(scenario),
+            runnerId: getRunnerId(runner),
+            scenarioPlatforms: uniqueSorted(scenarioPlatforms),
+            runnerPlatforms: uniqueSorted(runnerPlatforms),
+        }));
+    }
+    return commonPlatforms;
+}
+/**
+ * Evaluates whether a scenario can be served by a primary runner plus evidence providers.
+ *
+ * @param {{scenario?: Record<string, unknown>, runner?: Record<string, unknown>, evidenceProviders?: Record<string, unknown>[], platform?: string | null}} [options]
+ * @returns {{compatible: boolean, errors: Record<string, unknown>[], warnings: Record<string, unknown>[], matched: {platforms: string[], capabilities: string[], driverActions: string[], artifacts: string[], evidenceProviders: string[]}}}
+ */
+function evaluateRunnerCompatibility({ scenario, runner, evidenceProviders = [], platform = null, } = {}) {
+    const errors = [];
+    const warnings = [];
+    validatePrimaryRunner({ runner, errors });
+    const primaryRunner = runner ?? {};
+    if (!scenario || typeof scenario !== 'object') {
+        errors.push(createIssue('scenario_missing', 'A scenario manifest is required.'));
+        return {
+            compatible: false,
+            errors,
+            warnings,
+            matched: {
+                platforms: [],
+                capabilities: [],
+                driverActions: [],
+                artifacts: [],
+                evidenceProviders: [],
+            },
+        };
+    }
+    const effectivePlatforms = resolveEffectivePlatforms({ scenario, runner: primaryRunner, platform, errors });
+    validateScenarioAdapterOptions({ effectivePlatforms, errors, runner: primaryRunner, scenario });
+    const runnerCapabilities = uniqueSorted(asArray(primaryRunner.capabilities));
+    const missingRequiredCapabilities = includesAll(runnerCapabilities, asArray(scenario.requiredCapabilities));
+    for (const capability of missingRequiredCapabilities) {
+        errors.push(createIssue('missing_required_capability', `Runner \`${getRunnerId(primaryRunner)}\` is missing required capability \`${capability}\`.`, {
+            runnerId: getRunnerId(primaryRunner),
+            scenarioId: getScenarioId(scenario),
+            capability,
+        }));
+    }
+    const providedCapabilities = collectProvidedCapabilities({
+        runner: primaryRunner,
+        evidenceProviders,
+        effectivePlatforms,
+    });
+    const missingOptionalCapabilities = includesAll(providedCapabilities, asArray(scenario.optionalCapabilities));
+    for (const capability of missingOptionalCapabilities) {
+        warnings.push(createIssue('missing_optional_capability', `No active runner or provider declares optional capability \`${capability}\`.`, {
+            scenarioId: getScenarioId(scenario),
+            capability,
+        }));
+    }
+    const providedDriverActions = collectProvidedDriverActions({
+        runner: primaryRunner,
+        evidenceProviders,
+        effectivePlatforms,
+    });
+    const scenarioDriverActions = collectScenarioDriverActions(scenario);
+    for (const driverAction of includesAll(providedDriverActions, scenarioDriverActions.required)) {
+        errors.push(createIssue('missing_required_driver_action', `No active runner or provider declares required driver action \`${driverAction}\`.`, {
+            runnerId: getRunnerId(primaryRunner),
+            scenarioId: getScenarioId(scenario),
+            driverAction,
+        }));
+    }
+    for (const driverAction of includesAll(providedDriverActions, scenarioDriverActions.optional)) {
+        warnings.push(createIssue('missing_optional_driver_action', `No active runner or provider declares optional driver action \`${driverAction}\`.`, {
+            runnerId: getRunnerId(primaryRunner),
+            scenarioId: getScenarioId(scenario),
+            driverAction,
+        }));
+    }
+    const { activeProviders, artifacts } = collectProvidedArtifacts({
+        runner: primaryRunner,
+        evidenceProviders,
+        effectivePlatforms,
+    });
+    const requiredArtifacts = asArray(scenario.artifacts?.required);
+    const optionalArtifacts = asArray(scenario.artifacts?.optional);
+    for (const artifact of includesAll(artifacts, requiredArtifacts)) {
+        errors.push(createIssue('missing_required_artifact', `No active runner or evidence provider can produce required artifact \`${artifact}\`.`, {
+            scenarioId: getScenarioId(scenario),
+            artifact,
+        }));
+    }
+    for (const artifact of includesAll(artifacts, optionalArtifacts)) {
+        warnings.push(createIssue('missing_optional_artifact', `No active runner or evidence provider declares optional artifact \`${artifact}\`.`, {
+            scenarioId: getScenarioId(scenario),
+            artifact,
+        }));
+    }
+    return {
+        compatible: errors.length === 0,
+        errors,
+        warnings,
+        matched: {
+            platforms: effectivePlatforms,
+            capabilities: providedCapabilities,
+            driverActions: providedDriverActions,
+            artifacts,
+            evidenceProviders: activeProviders.map((provider) => getRunnerId(provider)),
+        },
+    };
+}
+/**
+ * Builds the initial `health.json` artifact from planner compatibility results.
+ *
+ * @param {{scenario: Record<string, unknown>, runId?: string, compatibility: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildCompatibilityHealth({ scenario, runId, compatibility, }) {
+    const scenarioId = getScenarioId(scenario);
+    const resolvedRunId = typeof runId === 'string' && runId.length > 0 ? runId : 'unknown-run';
+    const errors = compatibility.errors;
+    const warnings = compatibility.warnings;
+    const failedChecks = errors.map((issue) => issueToHealthCheck(issue, 'failed'));
+    const warningChecks = warnings.map((issue) => issueToHealthCheck(issue, 'warning'));
+    const checks = failedChecks.length > 0
+        ? failedChecks
+        : [
+            {
+                name: 'planner_compatibility',
+                status: 'passed',
+                source: 'planner',
+                code: 'planner_compatible',
+                message: 'Scenario requirements are compatible with the selected runner and evidence providers.',
+            },
+        ];
+    return {
+        schemaVersion: '1.0.0',
+        scenarioId,
+        ...(typeof scenario?.flowId === 'string' ? { flowId: scenario.flowId } : {}),
+        runId: resolvedRunId,
+        healthStatus: failedChecks.length > 0 ? 'failed' : 'passed',
+        checks,
+        ...(warningChecks.length > 0 ? { warnings: warningChecks } : {}),
+        matched: {
+            platforms: uniqueSorted(asArray(compatibility?.matched?.platforms)),
+            capabilities: uniqueSorted(asArray(compatibility?.matched?.capabilities)),
+            driverActions: uniqueSorted(asArray(compatibility?.matched?.driverActions)),
+            artifacts: uniqueSorted(asArray(compatibility?.matched?.artifacts)),
+            evidenceProviders: uniqueSorted(asArray(compatibility?.matched?.evidenceProviders)),
+        },
+    };
+}
+/**
+ * Builds a pre-budget `verdict.json` artifact from scenario health.
+ *
+ * @param {{scenario: Record<string, unknown>, runId?: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildUnevaluatedVerdict({ scenario, runId, health, }) {
+    const healthStatus = health?.healthStatus ?? 'failed';
+    const scenarioId = health?.scenarioId ?? getScenarioId(scenario);
+    const resolvedRunId = typeof health?.runId === 'string' && health.runId.length > 0
+        ? health.runId
+        : typeof runId === 'string' && runId.length > 0
+            ? runId
+            : 'unknown-run';
+    const canEvaluateBudgets = healthStatus === 'passed';
+    return {
+        schemaVersion: '1.0.0',
+        scenarioId,
+        ...(typeof health?.flowId === 'string'
+            ? { flowId: health.flowId }
+            : typeof scenario?.flowId === 'string'
+                ? { flowId: scenario.flowId }
+                : {}),
+        runId: resolvedRunId,
+        healthStatus,
+        verdictStatus: canEvaluateBudgets ? 'not_evaluated' : 'inconclusive',
+        budgetChecks: [],
+        summary: canEvaluateBudgets
+            ? 'Scenario health passed; budget evaluation has not run yet.'
+            : 'Scenario health did not pass; do not optimize from this run.',
+    };
+}