@farmslot/protocol 0.5.0

package/dist/recipe-compat.js

@@ -0,0 +1,977 @@
+import { RECIPE_ARTIFACT_TYPES } from './step-io.js';
+export const RECIPE_PROTOCOL_SCHEMA_VERSION = 1;
+export const RECIPE_PLAYBACK_SLOW_MS_MIN = 100;
+export const RECIPE_PLAYBACK_SLOW_MS_MAX = 60_000;
+export const OFFICIAL_RECIPE_ACTIONS = [
+    'command',
+    'wait',
+    'assert_file',
+    'assert_json',
+    'assert_exit_code',
+    'assert_output',
+    'state_read',
+    'watch_logs',
+    'index_artifacts',
+    'call',
+    'switch',
+    'manual',
+    'end',
+    'ui.navigate',
+    'ui.press',
+    'ui.key_press',
+    'ui.set_input',
+    'ui.scroll',
+    'ui.gesture',
+    'ui.wait_for',
+    'ui.screenshot',
+    'app.status',
+    'app.lifecycle',
+    'app.hud',
+    'app.trace',
+    'cdp.target',
+    'cdp.storage',
+    'cdp.network',
+    'cdp.emulation',
+    'cdp.metrics',
+    'cdp.trace',
+];
+const PLAYBACK_MODES = new Set(['off', 'auto', 'step']);
+const TERMINAL_STATUSES = new Set(['pass', 'fail', 'unknown']);
+const ARTIFACT_TYPES = new Set(RECIPE_ARTIFACT_TYPES);
+const OFFICIAL_ACTION_SET = new Set(OFFICIAL_RECIPE_ACTIONS);
+function createContext() {
+    return { findings: [], legacy: false };
+}
+function addFinding(ctx, severity, code, path, message) {
+    ctx.findings.push({ severity, code, path, message });
+}
+function addLegacyWarning(ctx, code, path, message) {
+    ctx.legacy = true;
+    addFinding(ctx, 'warning', code, path, message);
+}
+export function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isRelativeArtifactPath(value) {
+    if (value.startsWith('/') || value.startsWith('\\'))
+        return false;
+    if (/^[A-Za-z]:/.test(value))
+        return false;
+    return !value.split(/[\\/]+/).some((segment) => segment === '..');
+}
+function finishResult(ctx) {
+    const errors = ctx.findings.filter((finding) => finding.severity === 'error').length;
+    const warnings = ctx.findings.length - errors;
+    const status = errors
+        ? 'invalid'
+        : ctx.legacy
+            ? 'legacy-compatible'
+            : 'v1-compatible';
+    return { status, findings: ctx.findings, summary: { errors, warnings, legacy: ctx.legacy } };
+}
+function requireV1StringField(ctx, document, field, path, schemaVersionIsV1) {
+    if (isNonEmptyString(document[field]))
+        return;
+    if (!hasOwn(document, field)) {
+        if (schemaVersionIsV1) {
+            addFinding(ctx, 'error', `recipe.missing_${field}`, path, `v1 recipes require ${path}.`);
+        }
+        else {
+            addLegacyWarning(ctx, `recipe.legacy_missing_${field}`, path, `Missing ${path}; existing pre-v1 recipes may still run, but new v1 recipes must include it.`);
+        }
+        return;
+    }
+    addFinding(ctx, 'error', `recipe.invalid_${field}`, path, `${path} must be a non-empty string.`);
+}
+function extractWorkflow(ctx, recipe) {
+    const validate = recipe.validate;
+    if (!isRecord(validate)) {
+        addFinding(ctx, 'error', 'recipe.missing_validate', 'validate', 'Recipe must include validate.');
+        return null;
+    }
+    const workflow = validate.workflow;
+    if (!isRecord(workflow)) {
+        addFinding(ctx, 'error', 'recipe.missing_workflow', 'validate.workflow', 'Recipe must include validate.workflow.');
+        return null;
+    }
+    const entry = workflow.entry;
+    if (!isNonEmptyString(entry)) {
+        addFinding(ctx, 'error', 'workflow.invalid_entry', 'validate.workflow.entry', 'validate.workflow.entry must be a non-empty string.');
+    }
+    const nodes = workflow.nodes;
+    if (!isRecord(nodes) || Object.keys(nodes).length === 0) {
+        addFinding(ctx, 'error', 'workflow.invalid_nodes', 'validate.workflow.nodes', 'validate.workflow.nodes must be a non-empty object.');
+        return null;
+    }
+    const typedNodes = Object.create(null);
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (!isRecord(node)) {
+            addFinding(ctx, 'error', 'workflow.invalid_node', `validate.workflow.nodes.${nodeId}`, `Workflow node ${nodeId} must be an object.`);
+            continue;
+        }
+        typedNodes[nodeId] = node;
+    }
+    const lifecycleNodes = collectLifecycleNodes(ctx, recipe, workflow);
+    if (!isNonEmptyString(entry))
+        return null;
+    return { entry, nodes: typedNodes, lifecycleNodes };
+}
+function collectLifecycleNodes(ctx, recipe, workflow) {
+    const lifecycleNodes = Object.create(null);
+    collectLifecycleArray(ctx, workflow.setup, 'validate.workflow.setup', lifecycleNodes);
+    if (recipe.startState != null) {
+        if (isRecord(recipe.startState)) {
+            lifecycleNodes.startState = { node: recipe.startState, path: 'startState' };
+        }
+        else {
+            addFinding(ctx, 'error', 'workflow.invalid_start_state', 'startState', 'startState must be an action node object when present.');
+        }
+    }
+    collectLifecycleArray(ctx, workflow.teardown, 'validate.workflow.teardown', lifecycleNodes);
+    return lifecycleNodes;
+}
+function collectLifecycleArray(ctx, value, path, lifecycleNodes) {
+    if (value == null)
+        return;
+    if (!Array.isArray(value)) {
+        addFinding(ctx, 'error', 'workflow.invalid_lifecycle', path, `${path} must be an array.`);
+        return;
+    }
+    value.forEach((entry, index) => {
+        const nodePath = `${path}[${index}]`;
+        if (!isRecord(entry)) {
+            addFinding(ctx, 'error', 'workflow.invalid_lifecycle_node', nodePath, `${nodePath} must be an action node object.`);
+            return;
+        }
+        lifecycleNodes[isNonEmptyString(entry.id) ? entry.id : `${path}:${index}`] = {
+            node: entry,
+            path: nodePath,
+        };
+        if (entry.next != null) {
+            addFinding(ctx, 'error', 'workflow.lifecycle_has_transition', `${nodePath}.next`, 'setup and teardown entries are ordered arrays and must not declare next.');
+        }
+    });
+}
+function collectCaseTargets(node, path, ctx, emitFindings = true) {
+    const cases = node.cases;
+    if (cases == null)
+        return [];
+    if (Array.isArray(cases)) {
+        const targets = [];
+        cases.forEach((entry, index) => {
+            if (!isRecord(entry)) {
+                if (emitFindings) {
+                    addFinding(ctx, 'error', 'workflow.invalid_case', `${path}.cases[${index}]`, 'cases entries must be objects.');
+                }
+                return;
+            }
+            const target = entry.next;
+            if (target == null)
+                return;
+            if (isNonEmptyString(target)) {
+                targets.push(target);
+            }
+            else {
+                if (emitFindings) {
+                    addFinding(ctx, 'error', 'workflow.invalid_case_target', `${path}.cases[${index}].next`, 'cases[].next must be a non-empty string when present.');
+                }
+            }
+        });
+        return targets;
+    }
+    if (isRecord(cases)) {
+        const targets = [];
+        for (const [caseName, target] of Object.entries(cases)) {
+            if (isNonEmptyString(target)) {
+                targets.push(target);
+            }
+            else {
+                if (emitFindings) {
+                    addFinding(ctx, 'error', 'workflow.invalid_case_target', `${path}.cases.${caseName}`, 'case targets must be non-empty strings.');
+                }
+            }
+        }
+        return targets;
+    }
+    if (emitFindings) {
+        addFinding(ctx, 'error', 'workflow.invalid_cases', `${path}.cases`, 'cases must be an array or object.');
+    }
+    return [];
+}
+function collectTargets(node, path, ctx, emitFindings = true) {
+    const targets = [];
+    const next = node.next;
+    const defaultTarget = node.default;
+    if (next != null) {
+        if (isNonEmptyString(next)) {
+            targets.push(next);
+        }
+        else {
+            if (emitFindings) {
+                addFinding(ctx, 'error', 'workflow.invalid_next', `${path}.next`, 'next must be a non-empty string.');
+            }
+        }
+    }
+    if (defaultTarget != null) {
+        if (isNonEmptyString(defaultTarget)) {
+            targets.push(defaultTarget);
+        }
+        else {
+            if (emitFindings) {
+                addFinding(ctx, 'error', 'workflow.invalid_default', `${path}.default`, 'default must be a non-empty string.');
+            }
+        }
+    }
+    targets.push(...collectCaseTargets(node, path, ctx, emitFindings));
+    return targets;
+}
+function validatePlayback(ctx, workflow) {
+    if (workflow.playback == null)
+        return;
+    if (!isRecord(workflow.playback)) {
+        addFinding(ctx, 'error', 'workflow.invalid_playback', 'validate.workflow.playback', 'playback must be an object when present.');
+        return;
+    }
+    const playback = workflow.playback;
+    if (playback.mode != null &&
+        (typeof playback.mode !== 'string' || !PLAYBACK_MODES.has(playback.mode))) {
+        addFinding(ctx, 'error', 'workflow.invalid_playback_mode', 'validate.workflow.playback.mode', 'playback.mode must be one of off, auto, or step.');
+    }
+    if (playback.slow_ms != null) {
+        if (typeof playback.slow_ms !== 'number' ||
+            !Number.isInteger(playback.slow_ms) ||
+            playback.slow_ms < RECIPE_PLAYBACK_SLOW_MS_MIN ||
+            playback.slow_ms > RECIPE_PLAYBACK_SLOW_MS_MAX) {
+            addFinding(ctx, 'error', 'workflow.invalid_playback_slow_ms', 'validate.workflow.playback.slow_ms', `playback.slow_ms must be an integer from ${RECIPE_PLAYBACK_SLOW_MS_MIN} through ${RECIPE_PLAYBACK_SLOW_MS_MAX}.`);
+        }
+    }
+}
+function validateWorkflowGraph(ctx, workflow, rawWorkflow) {
+    if (!hasOwn(workflow.nodes, workflow.entry)) {
+        addFinding(ctx, 'error', 'workflow.missing_entry_node', 'validate.workflow.entry', `Entry node ${workflow.entry} does not exist in validate.workflow.nodes.`);
+    }
+    validatePlayback(ctx, rawWorkflow);
+    const reachable = new Set();
+    const queue = hasOwn(workflow.nodes, workflow.entry) ? [workflow.entry] : [];
+    let terminalCount = 0;
+    let reachableTerminalCount = 0;
+    const graphNodes = Object.entries(workflow.nodes).map(([nodeId, node]) => [nodeId, { node, path: `validate.workflow.nodes.${nodeId}` }]);
+    const lifecycleNodes = Object.entries(workflow.lifecycleNodes);
+    for (const [nodeId, entry] of [...graphNodes, ...lifecycleNodes]) {
+        const { node, path } = entry;
+        const action = node.action;
+        if (!isNonEmptyString(action)) {
+            addFinding(ctx, 'error', 'workflow.invalid_action', `${path}.action`, 'Node action must be a non-empty string.');
+            continue;
+        }
+        const isLifecycleNode = hasOwn(workflow.lifecycleNodes, nodeId);
+        const targets = isLifecycleNode ? [] : collectTargets(node, path, ctx);
+        if (action === 'end') {
+            terminalCount += 1;
+            if (node.status == null) {
+                addFinding(ctx, 'error', 'workflow.missing_terminal_status', `${path}.status`, 'end nodes must include status.');
+            }
+            else if (typeof node.status !== 'string' || !TERMINAL_STATUSES.has(node.status)) {
+                addFinding(ctx, 'error', 'workflow.invalid_terminal_status', `${path}.status`, 'end node status must be pass, fail, or unknown.');
+            }
+            if (targets.length > 0) {
+                addFinding(ctx, 'warning', 'workflow.terminal_has_targets', path, 'end nodes should not define transitions.');
+            }
+            continue;
+        }
+        if (!isLifecycleNode && targets.length === 0) {
+            addFinding(ctx, 'error', 'workflow.missing_transition', path, 'Non-terminal nodes must transition via next, cases, or default.');
+        }
+        for (const target of targets) {
+            if (!hasOwn(workflow.nodes, target)) {
+                addFinding(ctx, 'error', 'workflow.missing_target', path, `Node ${nodeId} references missing target node ${target}.`);
+            }
+        }
+    }
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        if (!nodeId || reachable.has(nodeId))
+            continue;
+        if (!hasOwn(workflow.nodes, nodeId))
+            continue;
+        const node = workflow.nodes[nodeId];
+        reachable.add(nodeId);
+        if (node.action === 'end')
+            reachableTerminalCount += 1;
+        for (const target of collectTargets(node, `validate.workflow.nodes.${nodeId}`, ctx, false)) {
+            if (hasOwn(workflow.nodes, target) && !reachable.has(target))
+                queue.push(target);
+        }
+    }
+    if (terminalCount === 0) {
+        addFinding(ctx, 'error', 'workflow.missing_terminal', 'validate.workflow.nodes', 'Workflow must include at least one action:end terminal node.');
+    }
+    else if (hasOwn(workflow.nodes, workflow.entry) && reachableTerminalCount === 0) {
+        addFinding(ctx, 'error', 'workflow.no_reachable_terminal', 'validate.workflow.nodes', 'No terminal end node is reachable from the entry node.');
+    }
+    for (const nodeId of Object.keys(workflow.nodes)) {
+        if (!reachable.has(nodeId)) {
+            addFinding(ctx, 'warning', 'workflow.unreachable_node', `validate.workflow.nodes.${nodeId}`, `Node ${nodeId} is not reachable from the entry node.`);
+        }
+    }
+}
+export function getRecipeWorkflowNodeIds(recipe) {
+    if (!isRecord(recipe) || !isRecord(recipe.validate) || !isRecord(recipe.validate.workflow))
+        return [];
+    const nodes = recipe.validate.workflow.nodes;
+    if (!isRecord(nodes))
+        return [];
+    const ids = Object.keys(nodes);
+    if (isRecord(recipe.startState))
+        ids.push('startState');
+    for (const key of ['setup', 'teardown']) {
+        const lifecycle = recipe.validate.workflow[key];
+        if (!Array.isArray(lifecycle))
+            continue;
+        lifecycle.forEach((node, index) => {
+            if (isRecord(node))
+                ids.push(isNonEmptyString(node.id) ? node.id : `${key}:${index}`);
+        });
+    }
+    return ids;
+}
+export function getRecipeWorkflowActions(recipe) {
+    return getRecipeWorkflowActionEntries(recipe).map((entry) => entry.action);
+}
+function getRecipeWorkflowActionEntries(recipe) {
+    if (!isRecord(recipe) || !isRecord(recipe.validate) || !isRecord(recipe.validate.workflow)) {
+        return [];
+    }
+    const nodes = recipe.validate.workflow.nodes;
+    if (!isRecord(nodes))
+        return [];
+    const actions = [];
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (!isRecord(node))
+            continue;
+        if (isNonEmptyString(node.action)) {
+            actions.push({
+                nodeId,
+                action: node.action,
+                path: `validate.workflow.nodes.${nodeId}.action`,
+            });
+        }
+    }
+    if (isRecord(recipe.startState) && isNonEmptyString(recipe.startState.action)) {
+        actions.push({
+            nodeId: 'startState',
+            action: recipe.startState.action,
+            path: 'startState.action',
+        });
+    }
+    for (const key of ['setup', 'teardown']) {
+        const lifecycle = recipe.validate.workflow[key];
+        if (!Array.isArray(lifecycle))
+            continue;
+        lifecycle.forEach((node, index) => {
+            if (!isRecord(node) || !isNonEmptyString(node.action))
+                return;
+            actions.push({
+                nodeId: isNonEmptyString(node.id) ? node.id : `${key}:${index}`,
+                action: node.action,
+                path: `validate.workflow.${key}[${index}].action`,
+            });
+        });
+    }
+    if (isRecord(recipe.flows)) {
+        for (const [flowId, flow] of Object.entries(recipe.flows)) {
+            if (!isRecord(flow))
+                continue;
+            const workflow = isRecord(flow.workflow) ? flow.workflow : flow;
+            if (!isRecord(workflow.nodes))
+                continue;
+            for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+                if (!isRecord(node) || !isNonEmptyString(node.action))
+                    continue;
+                actions.push({
+                    nodeId: `${flowId}/${nodeId}`,
+                    action: node.action,
+                    path: `flows.${flowId}.workflow.nodes.${nodeId}.action`,
+                });
+            }
+        }
+    }
+    return actions;
+}
+export function getRecipeActionManifestActionNames(manifest) {
+    if (!isRecord(manifest))
+        return [];
+    const actionNames = new Set();
+    if (Array.isArray(manifest.supported_official_actions)) {
+        for (const action of manifest.supported_official_actions) {
+            if (isNonEmptyString(action))
+                actionNames.add(action);
+        }
+    }
+    if (Array.isArray(manifest.custom_actions)) {
+        for (const action of manifest.custom_actions) {
+            if (isRecord(action) && isNonEmptyString(action.name))
+                actionNames.add(action.name);
+        }
+    }
+    return [...actionNames].sort();
+}
+function validateActionCatalogEntry(ctx, entry, path, expectedAction) {
+    if (!isRecord(entry)) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_action_metadata', path, `${path} must be an object.`);
+        return;
+    }
+    for (const stringField of [
+        'description',
+        'when_to_use',
+        'avoid_when',
+        'proof_effect',
+        'safety_notes',
+    ]) {
+        const value = entry[stringField];
+        if (value != null && typeof value !== 'string') {
+            addFinding(ctx, 'error', 'action_manifest.invalid_metadata_field', `${path}.${stringField}`, `${path}.${stringField} must be a string when present.`);
+        }
+    }
+    if (entry.schema != null && !isRecord(entry.schema)) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_schema', `${path}.schema`, `${path}.schema must be a JSON Schema object when present.`);
+    }
+    if (entry.examples == null)
+        return;
+    if (!Array.isArray(entry.examples)) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_examples', `${path}.examples`, `${path}.examples must be an array when present.`);
+        return;
+    }
+    entry.examples.forEach((example, index) => {
+        const examplePath = `${path}.examples[${index}]`;
+        if (!isRecord(example)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_example', examplePath, `${examplePath} must be an object.`);
+            return;
+        }
+        if (example.description != null && typeof example.description !== 'string') {
+            addFinding(ctx, 'error', 'action_manifest.invalid_example_description', `${examplePath}.description`, `${examplePath}.description must be a string when present.`);
+        }
+        if (!isRecord(example.node)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_example_node', `${examplePath}.node`, `${examplePath}.node must be an object.`);
+            return;
+        }
+        if (!isNonEmptyString(example.node.action)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_example_action', `${examplePath}.node.action`, `${examplePath}.node.action must be a non-empty string.`);
+        }
+        else if (expectedAction && example.node.action !== expectedAction) {
+            addFinding(ctx, 'error', 'action_manifest.example_action_mismatch', `${examplePath}.node.action`, `Example action ${example.node.action} must match declared action ${expectedAction}.`);
+        }
+    });
+}
+export function validateRecipeActionManifestDocument(manifest) {
+    const ctx = createContext();
+    if (!isRecord(manifest)) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_document', '$', 'Recipe action manifest must be a JSON object.');
+        return finishResult(ctx);
+    }
+    if (manifest.runner_protocol_version !== RECIPE_PROTOCOL_SCHEMA_VERSION) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_runner_protocol_version', 'runner_protocol_version', `runner_protocol_version must equal ${RECIPE_PROTOCOL_SCHEMA_VERSION}.`);
+    }
+    if (manifest.action_registry_version !== RECIPE_PROTOCOL_SCHEMA_VERSION) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_action_registry_version', 'action_registry_version', `action_registry_version must equal ${RECIPE_PROTOCOL_SCHEMA_VERSION}.`);
+    }
+    const declaredActions = new Set();
+    const officialActions = manifest.supported_official_actions;
+    if (!Array.isArray(officialActions) || officialActions.length === 0) {
+        addFinding(ctx, 'error', 'action_manifest.invalid_supported_official_actions', 'supported_official_actions', 'supported_official_actions must be a non-empty array.');
+    }
+    else {
+        officialActions.forEach((action, index) => {
+            const path = `supported_official_actions[${index}]`;
+            if (!isNonEmptyString(action)) {
+                addFinding(ctx, 'error', 'action_manifest.invalid_supported_action', path, `${path} must be a non-empty string.`);
+                return;
+            }
+            if (!OFFICIAL_ACTION_SET.has(action)) {
+                addFinding(ctx, 'error', 'action_manifest.unknown_official_action', path, `${action} is not in the Farmslot v1 official action registry.`);
+            }
+            if (declaredActions.has(action)) {
+                addFinding(ctx, 'error', 'action_manifest.duplicate_action', path, `${action} is declared more than once.`);
+            }
+            declaredActions.add(action);
+        });
+    }
+    const customActions = manifest.custom_actions;
+    if (customActions != null) {
+        if (!Array.isArray(customActions)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_custom_actions', 'custom_actions', 'custom_actions must be an array when present.');
+        }
+        else {
+            customActions.forEach((action, index) => {
+                const path = `custom_actions[${index}]`;
+                if (!isRecord(action)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_custom_action', path, `${path} must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(action.name)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_custom_action_name', `${path}.name`, `${path}.name must be a non-empty string.`);
+                }
+                else {
+                    if (OFFICIAL_ACTION_SET.has(action.name)) {
+                        addFinding(ctx, 'error', 'action_manifest.custom_action_overlaps_official', `${path}.name`, `${action.name} is official and must be declared in supported_official_actions.`);
+                    }
+                    if (declaredActions.has(action.name)) {
+                        addFinding(ctx, 'error', 'action_manifest.duplicate_action', `${path}.name`, `${action.name} is declared more than once.`);
+                    }
+                    declaredActions.add(action.name);
+                }
+                validateActionCatalogEntry(ctx, action, path, isNonEmptyString(action.name) ? action.name : undefined);
+            });
+        }
+    }
+    if (manifest.action_metadata != null) {
+        if (!isRecord(manifest.action_metadata)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_action_metadata', 'action_metadata', 'action_metadata must be an object when present.');
+        }
+        else {
+            for (const [action, metadata] of Object.entries(manifest.action_metadata)) {
+                if (!declaredActions.has(action)) {
+                    addFinding(ctx, 'error', 'action_manifest.metadata_for_undeclared_action', `action_metadata.${action}`, `Metadata action ${action} is not declared by the manifest.`);
+                }
+                validateActionCatalogEntry(ctx, metadata, `action_metadata.${action}`, action);
+            }
+        }
+    }
+    for (const { field, nameField } of [
+        { field: 'custom_assertion_operators', nameField: 'name' },
+        { field: 'state_refs', nameField: 'name' },
+    ]) {
+        const declarations = manifest[field];
+        if (declarations == null)
+            continue;
+        if (!Array.isArray(declarations)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_declaration_array', field, `${field} must be an array when present.`);
+            continue;
+        }
+        declarations.forEach((entry, index) => {
+            const path = `${field}[${index}]`;
+            if (!isRecord(entry) || !isNonEmptyString(entry[nameField])) {
+                addFinding(ctx, 'error', 'action_manifest.invalid_declaration', path, `${path}.${nameField} must be a non-empty string.`);
+            }
+        });
+    }
+    const preConditions = manifest.pre_conditions;
+    if (preConditions != null) {
+        if (!Array.isArray(preConditions)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_pre_conditions', 'pre_conditions', 'pre_conditions must be an array when present.');
+        }
+        else {
+            preConditions.forEach((entry, index) => {
+                const path = `pre_conditions[${index}]`;
+                if (!isRecord(entry)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_pre_condition', path, `${path} must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(entry.id)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_pre_condition_id', `${path}.id`, `${path}.id must be a non-empty string.`);
+                }
+                if (!isNonEmptyString(entry.description)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_pre_condition_description', `${path}.description`, `${path}.description must be a non-empty string.`);
+                }
+            });
+        }
+    }
+    const nativeBindings = manifest.native_bindings;
+    if (nativeBindings != null) {
+        if (!Array.isArray(nativeBindings)) {
+            addFinding(ctx, 'error', 'action_manifest.invalid_native_bindings', 'native_bindings', 'native_bindings must be an array when present.');
+        }
+        else {
+            nativeBindings.forEach((binding, index) => {
+                const path = `native_bindings[${index}]`;
+                if (!isRecord(binding)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_native_binding', path, `${path} must be an object.`);
+                    return;
+                }
+                if (!isNonEmptyString(binding.action)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_native_binding_action', `${path}.action`, `${path}.action must be a non-empty string.`);
+                }
+                else if (!declaredActions.has(binding.action)) {
+                    addFinding(ctx, 'error', 'action_manifest.native_binding_for_undeclared_action', `${path}.action`, `Native binding action ${binding.action} is not declared by the manifest.`);
+                }
+                if (!isNonEmptyString(binding.implementation)) {
+                    addFinding(ctx, 'error', 'action_manifest.invalid_native_binding_implementation', `${path}.implementation`, `${path}.implementation must be a non-empty string.`);
+                }
+            });
+        }
+    }
+    return finishResult(ctx);
+}
+export function validateRecipeWithManifest(recipe, manifest) {
+    const ctx = createContext();
+    const recipeResult = validateRecipeDocument(recipe);
+    const manifestResult = validateRecipeActionManifestDocument(manifest);
+    ctx.findings.push(...recipeResult.findings, ...manifestResult.findings);
+    ctx.legacy = recipeResult.summary.legacy || manifestResult.summary.legacy;
+    const declaredActions = new Set(getRecipeActionManifestActionNames(manifest));
+    if (declaredActions.size > 0) {
+        const actions = getRecipeWorkflowActionEntries(recipe);
+        actions.forEach(({ action, path }) => {
+            if (!declaredActions.has(action)) {
+                addFinding(ctx, 'error', 'recipe.action_not_declared_by_manifest', path, `Recipe action ${action} is not declared by the runner action manifest.`);
+            }
+        });
+    }
+    const declaredPreconditions = new Set(getRecipeActionManifestPreconditionIds(manifest));
+    for (const gate of getRecipeWorkflowPreconditionEntries(recipe)) {
+        if (!declaredPreconditions.has(gate.id)) {
+            addFinding(ctx, 'error', 'recipe.precondition_not_declared_by_manifest', gate.path, `Recipe precondition ${gate.id} is not declared by the runner action manifest.`);
+        }
+    }
+    return finishResult(ctx);
+}
+export function validateRecipeDocument(recipe) {
+    const ctx = createContext();
+    if (!isRecord(recipe)) {
+        addFinding(ctx, 'error', 'recipe.invalid_document', '$', 'Recipe document must be a JSON object.');
+        return finishResult(ctx);
+    }
+    const schemaVersion = recipe.schema_version;
+    const schemaVersionIsV1 = schemaVersion === RECIPE_PROTOCOL_SCHEMA_VERSION;
+    if (!hasOwn(recipe, 'schema_version')) {
+        addLegacyWarning(ctx, 'recipe.legacy_missing_schema_version', 'schema_version', 'Missing schema_version; existing pre-v1 recipes may still run, but new v1 recipes must set schema_version: 1.');
+    }
+    else if (!schemaVersionIsV1) {
+        addFinding(ctx, 'error', 'recipe.unsupported_schema_version', 'schema_version', `Unsupported schema_version ${JSON.stringify(schemaVersion)}; supported value is ${RECIPE_PROTOCOL_SCHEMA_VERSION}.`);
+    }
+    requireV1StringField(ctx, recipe, 'title', 'title', schemaVersionIsV1);
+    requireV1StringField(ctx, recipe, 'description', 'description', schemaVersionIsV1);
+    const validate = recipe.validate;
+    const rawWorkflow = isRecord(validate) && isRecord(validate.workflow) ? validate.workflow : null;
+    const workflow = extractWorkflow(ctx, recipe);
+    if (workflow && rawWorkflow) {
+        validateWorkflowPreconditions(ctx, rawWorkflow);
+        validateWorkflowGraph(ctx, workflow, rawWorkflow);
+        validateFlowCalls(ctx, recipe, workflow);
+    }
+    validateInlineFlows(ctx, recipe);
+    return finishResult(ctx);
+}
+function validateInlineFlows(ctx, recipe) {
+    const flows = recipe.flows;
+    if (flows == null)
+        return;
+    if (!isRecord(flows)) {
+        addFinding(ctx, 'error', 'flow.invalid_flows', 'flows', 'flows must be an object.');
+        return;
+    }
+    const inlineFlowIds = new Set(Object.keys(flows));
+    const callGraph = new Map();
+    for (const [flowId, flow] of Object.entries(flows)) {
+        const flowPath = `flows.${flowId}`;
+        if (!isRecord(flow)) {
+            addFinding(ctx, 'error', 'flow.invalid_flow', flowPath, `Flow ${flowId} must be an object.`);
+            continue;
+        }
+        const workflow = isRecord(flow.workflow) ? flow.workflow : flow;
+        const entry = workflow.entry;
+        const nodes = workflow.nodes;
+        if (!isNonEmptyString(entry)) {
+            addFinding(ctx, 'error', 'flow.invalid_entry', `${flowPath}.workflow.entry`, `Flow ${flowId} entry must be a non-empty string.`);
+        }
+        if (!isRecord(nodes) || Object.keys(nodes).length === 0) {
+            addFinding(ctx, 'error', 'flow.invalid_nodes', `${flowPath}.workflow.nodes`, `Flow ${flowId} nodes must be a non-empty object.`);
+            continue;
+        }
+        if (isNonEmptyString(entry) && !hasOwn(nodes, entry)) {
+            addFinding(ctx, 'error', 'flow.missing_entry_node', `${flowPath}.workflow.entry`, `Flow ${flowId} entry node ${entry} does not exist.`);
+        }
+        const callees = [];
+        const reachable = new Set();
+        const queue = isNonEmptyString(entry) && hasOwn(nodes, entry) ? [entry] : [];
+        let terminalCount = 0;
+        let reachableTerminalCount = 0;
+        for (const [nodeId, node] of Object.entries(nodes)) {
+            const nodePath = `${flowPath}.workflow.nodes.${nodeId}`;
+            if (!isRecord(node)) {
+                addFinding(ctx, 'error', 'flow.invalid_node', nodePath, `Flow node ${nodeId} must be an object.`);
+                continue;
+            }
+            if (!isNonEmptyString(node.action)) {
+                addFinding(ctx, 'error', 'flow.invalid_action', `${nodePath}.action`, 'Flow node action must be a non-empty string.');
+                continue;
+            }
+            if (node.action === 'call' && isNonEmptyString(node.ref) && inlineFlowIds.has(node.ref)) {
+                callees.push(node.ref);
+            }
+            if (node.action !== 'end') {
+                const targets = collectTargets(node, nodePath, ctx);
+                if (targets.length === 0) {
+                    addFinding(ctx, 'error', 'flow.missing_transition', nodePath, 'Non-terminal flow nodes must transition via next, cases, or default.');
+                }
+                for (const target of targets) {
+                    if (!hasOwn(nodes, target)) {
+                        addFinding(ctx, 'error', 'flow.missing_target', nodePath, `Flow node ${nodeId} references missing target node ${target}.`);
+                    }
+                }
+            }
+            else {
+                terminalCount += 1;
+                if (node.status == null) {
+                    addFinding(ctx, 'error', 'flow.missing_terminal_status', `${nodePath}.status`, 'Flow end nodes must include status.');
+                }
+                else if (typeof node.status !== 'string' || !TERMINAL_STATUSES.has(node.status)) {
+                    addFinding(ctx, 'error', 'flow.invalid_terminal_status', `${nodePath}.status`, 'Flow end node status must be pass, fail, or unknown.');
+                }
+            }
+        }
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            if (!nodeId || reachable.has(nodeId))
+                continue;
+            const node = nodes[nodeId];
+            if (!isRecord(node))
+                continue;
+            reachable.add(nodeId);
+            if (node.action === 'end')
+                reachableTerminalCount += 1;
+            for (const target of collectTargets(node, `${flowPath}.workflow.nodes.${nodeId}`, ctx, false)) {
+                if (hasOwn(nodes, target) && !reachable.has(target))
+                    queue.push(target);
+            }
+        }
+        if (terminalCount === 0) {
+            addFinding(ctx, 'error', 'flow.missing_terminal', `${flowPath}.workflow.nodes`, `Flow ${flowId} must include at least one action:end terminal node.`);
+        }
+        else if (isNonEmptyString(entry) && hasOwn(nodes, entry) && reachableTerminalCount === 0) {
+            addFinding(ctx, 'error', 'flow.no_reachable_terminal', `${flowPath}.workflow.nodes`, `No terminal end node is reachable from flow ${flowId} entry node.`);
+        }
+        for (const nodeId of Object.keys(nodes)) {
+            if (!reachable.has(nodeId)) {
+                addFinding(ctx, 'warning', 'flow.unreachable_node', `${flowPath}.workflow.nodes.${nodeId}`, `Flow node ${nodeId} is not reachable from the entry node.`);
+            }
+        }
+        callGraph.set(flowId, callees);
+    }
+    validateInlineFlowCycles(ctx, callGraph);
+}
+function validateInlineFlowCycles(ctx, callGraph) {
+    const visiting = new Set();
+    const visited = new Set();
+    const stack = [];
+    function visit(flowId) {
+        if (visited.has(flowId))
+            return;
+        if (visiting.has(flowId)) {
+            const cycleStart = stack.indexOf(flowId);
+            const cycle = [...stack.slice(Math.max(cycleStart, 0)), flowId];
+            addFinding(ctx, 'error', 'flow.call_cycle', `flows.${flowId}`, `Inline flow call cycle detected: ${cycle.join(' -> ')}.`);
+            return;
+        }
+        visiting.add(flowId);
+        stack.push(flowId);
+        for (const callee of callGraph.get(flowId) ?? [])
+            visit(callee);
+        stack.pop();
+        visiting.delete(flowId);
+        visited.add(flowId);
+    }
+    for (const flowId of callGraph.keys())
+        visit(flowId);
+}
+function validateWorkflowPreconditions(ctx, workflow) {
+    const value = workflow.pre_conditions;
+    if (value == null)
+        return;
+    if (!Array.isArray(value)) {
+        addFinding(ctx, 'error', 'workflow.invalid_pre_conditions', 'validate.workflow.pre_conditions', 'validate.workflow.pre_conditions must be an array.');
+        return;
+    }
+    value.forEach((entry, index) => {
+        const path = `validate.workflow.pre_conditions[${index}]`;
+        if (typeof entry === 'string') {
+            if (!entry.trim()) {
+                addFinding(ctx, 'error', 'workflow.invalid_pre_condition', path, `${path} must be a non-empty string or object with id.`);
+            }
+            return;
+        }
+        if (!isRecord(entry)) {
+            addFinding(ctx, 'error', 'workflow.invalid_pre_condition', path, `${path} must be a non-empty string or object with id.`);
+            return;
+        }
+        if (!isNonEmptyString(entry.id)) {
+            addFinding(ctx, 'error', 'workflow.invalid_pre_condition_id', `${path}.id`, `${path}.id must be a non-empty string.`);
+        }
+        if (entry.description != null && typeof entry.description !== 'string') {
+            addFinding(ctx, 'error', 'workflow.invalid_pre_condition_description', `${path}.description`, `${path}.description must be a string when present.`);
+        }
+        if (entry.params != null && !isRecord(entry.params)) {
+            addFinding(ctx, 'error', 'workflow.invalid_pre_condition_params', `${path}.params`, `${path}.params must be an object when present.`);
+        }
+        if (entry.required != null && typeof entry.required !== 'boolean') {
+            addFinding(ctx, 'error', 'workflow.invalid_pre_condition_required', `${path}.required`, `${path}.required must be a boolean when present.`);
+        }
+    });
+}
+function getRecipeWorkflowPreconditionEntries(recipe) {
+    if (!isRecord(recipe) || !isRecord(recipe.validate) || !isRecord(recipe.validate.workflow)) {
+        return [];
+    }
+    const entries = recipe.validate.workflow.pre_conditions;
+    if (!Array.isArray(entries))
+        return [];
+    return entries.flatMap((entry, index) => {
+        const path = `validate.workflow.pre_conditions[${index}]`;
+        if (typeof entry === 'string' && entry.trim())
+            return [{ id: entry.trim(), path }];
+        if (isRecord(entry) && isNonEmptyString(entry.id)) {
+            return [{ id: entry.id, path: `${path}.id` }];
+        }
+        return [];
+    });
+}
+function getRecipeActionManifestPreconditionIds(manifest) {
+    if (!isRecord(manifest) || !Array.isArray(manifest.pre_conditions))
+        return [];
+    return manifest.pre_conditions.flatMap((entry) => isRecord(entry) && isNonEmptyString(entry.id) ? [entry.id] : []);
+}
+function validateFlowCalls(ctx, recipe, workflow) {
+    const inlineFlows = isRecord(recipe.flows) ? new Set(Object.keys(recipe.flows)) : new Set();
+    const hasExternalCatalogs = Array.isArray(recipe.uses) && recipe.uses.length > 0;
+    const entries = [
+        ...Object.entries(workflow.nodes).map(([nodeId, node]) => [nodeId, node, `validate.workflow.nodes.${nodeId}`]),
+        ...Object.entries(workflow.lifecycleNodes).map(([nodeId, entry]) => [nodeId, entry.node, entry.path]),
+        ...getInlineFlowNodeEntries(recipe),
+    ];
+    for (const [_nodeId, node, path] of entries) {
+        if (node.action !== 'call')
+            continue;
+        if (!isNonEmptyString(node.ref)) {
+            addFinding(ctx, 'error', 'workflow.invalid_call_ref', `${path}.ref`, 'call.ref must be a non-empty string.');
+            continue;
+        }
+        if (!hasExternalCatalogs && !inlineFlows.has(node.ref)) {
+            addFinding(ctx, 'error', 'workflow.unresolved_call_ref', `${path}.ref`, `Flow ${node.ref} is not declared in recipe.flows and no uses catalogs are present.`);
+        }
+        if (node.params != null && !isRecord(node.params)) {
+            addFinding(ctx, 'error', 'workflow.invalid_call_params', `${path}.params`, 'call.params must be an object when present.');
+        }
+    }
+}
+function getInlineFlowNodeEntries(recipe) {
+    if (!isRecord(recipe.flows))
+        return [];
+    const entries = [];
+    for (const [flowId, flow] of Object.entries(recipe.flows)) {
+        if (!isRecord(flow))
+            continue;
+        const workflow = isRecord(flow.workflow) ? flow.workflow : flow;
+        if (!isRecord(workflow.nodes))
+            continue;
+        for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+            if (!isRecord(node))
+                continue;
+            entries.push([`${flowId}/${nodeId}`, node, `flows.${flowId}.workflow.nodes.${nodeId}`]);
+        }
+    }
+    return entries;
+}
+export function validateArtifactManifestDocument(manifest, options = {}) {
+    const ctx = createContext();
+    if (!isRecord(manifest)) {
+        addFinding(ctx, 'error', 'artifact_manifest.invalid_document', '$', 'artifact-manifest.json must be a JSON object.');
+        return finishResult(ctx);
+    }
+    if (manifest.version !== 1) {
+        addFinding(ctx, 'error', 'artifact_manifest.invalid_version', 'version', 'artifact-manifest.json version must equal 1.');
+    }
+    if (manifest.runStatus != null &&
+        (typeof manifest.runStatus !== 'string' || !TERMINAL_STATUSES.has(manifest.runStatus))) {
+        addFinding(ctx, 'error', 'artifact_manifest.invalid_run_status', 'runStatus', 'runStatus must be pass, fail, or unknown when present.');
+    }
+    const artifacts = manifest.artifacts;
+    if (!Array.isArray(artifacts)) {
+        addFinding(ctx, 'error', 'artifact_manifest.invalid_artifacts', 'artifacts', 'artifact-manifest.json must include an artifacts array.');
+        return finishResult(ctx);
+    }
+    const nodeIds = new Set(getRecipeWorkflowNodeIds(options.recipe));
+    const artifactPathSet = options.artifactPaths ? new Set(options.artifactPaths) : null;
+    artifacts.forEach((artifact, index) => {
+        const path = `artifacts[${index}]`;
+        if (!isRecord(artifact)) {
+            addFinding(ctx, 'error', 'artifact_manifest.invalid_artifact', path, 'Artifact entries must be objects.');
+            return;
+        }
+        if (!isNonEmptyString(artifact.path)) {
+            addFinding(ctx, 'error', 'artifact_manifest.invalid_path', `${path}.path`, 'Artifact path must be a non-empty string.');
+        }
+        else {
+            if (!isRelativeArtifactPath(artifact.path)) {
+                addFinding(ctx, 'error', 'artifact_manifest.unsafe_path', `${path}.path`, 'Artifact path must be relative and must not contain .. segments.');
+            }
+            if (artifactPathSet && !artifactPathSet.has(artifact.path)) {
+                addFinding(ctx, 'error', 'artifact_manifest.missing_file', `${path}.path`, `Artifact file ${artifact.path} was not found in the provided artifact path list.`);
+            }
+        }
+        if (!isNonEmptyString(artifact.type)) {
+            addFinding(ctx, 'error', 'artifact_manifest.invalid_type', `${path}.type`, 'Artifact type must be a non-empty string.');
+        }
+        else if (!ARTIFACT_TYPES.has(artifact.type)) {
+            addFinding(ctx, 'warning', 'artifact_manifest.unknown_type', `${path}.type`, `Artifact type ${artifact.type} is not in the v1 core type vocabulary.`);
+        }
+        for (const optionalField of ['label', 'nodeId', 'mimeType', 'category', 'proofTarget']) {
+            const value = artifact[optionalField];
+            if (value != null && typeof value !== 'string') {
+                addFinding(ctx, 'error', 'artifact_manifest.invalid_optional_field', `${path}.${optionalField}`, `${optionalField} must be a string when present.`);
+            }
+        }
+        if (artifact.covers != null) {
+            if (!Array.isArray(artifact.covers) ||
+                artifact.covers.some((cover) => !isNonEmptyString(cover))) {
+                addFinding(ctx, 'error', 'artifact_manifest.invalid_covers', `${path}.covers`, 'covers must be an array of non-empty strings when present.');
+            }
+        }
+        if (typeof artifact.nodeId === 'string' && nodeIds.size > 0 && !nodeIds.has(artifact.nodeId)) {
+            addFinding(ctx, 'warning', 'artifact_manifest.unknown_node', `${path}.nodeId`, `Artifact references nodeId ${artifact.nodeId}, which is not present in the recipe graph.`);
+        }
+    });
+    return finishResult(ctx);
+}
+export function validateRecipeArtifactPackage(input) {
+    const ctx = createContext();
+    const artifactPaths = new Set(input.artifactPaths ?? []);
+    if (input.artifactPaths != null) {
+        const requiredPaths = ['summary.json', 'trace.json'];
+        if (input.manifest != null)
+            requiredPaths.push('artifact-manifest.json');
+        if (input.recipe != null)
+            requiredPaths.push('recipe.json');
+        for (const requiredPath of requiredPaths) {
+            if (!artifactPaths.has(requiredPath)) {
+                addFinding(ctx, 'error', 'artifact_package.missing_required_file', requiredPath, `Recipe artifact package must include ${requiredPath}.`);
+            }
+        }
+    }
+    if (input.manifest == null) {
+        addLegacyWarning(ctx, 'artifact_package.legacy_missing_manifest', 'artifact-manifest.json', 'Missing artifact-manifest.json; this is compatible with legacy/pre-v1 packages but not v1-complete.');
+    }
+    else {
+        const manifestResult = validateArtifactManifestDocument(input.manifest, {
+            recipe: input.recipe,
+            artifactPaths: input.artifactPaths,
+        });
+        ctx.findings.push(...manifestResult.findings);
+        ctx.legacy = ctx.legacy || manifestResult.summary.legacy;
+    }
+    return finishResult(ctx);
+}
+export function mergeRecipeCompatibilityResults(results) {
+    const ctx = createContext();
+    for (const result of results) {
+        ctx.findings.push(...result.findings);
+        ctx.legacy = ctx.legacy || result.summary.legacy;
+    }
+    return finishResult(ctx);
+}
+//# sourceMappingURL=recipe-compat.js.map