Skip to content

💫 Toolkit to help you get started with SDD or any other process!

6.0 KB
Raw Blame
"""Typed workflow-call boundary; execution and persistence belong to the engine."""

from __future__ import annotations

import json
from pathlib import Path
from typing import Any

from .base import StepContext
from .expressions import evaluate_expression

RESERVED_OUTPUT_NAMES = frozenset(
    {
        "workflow",
        "status",
        "error",
        "aborted",
        "integration",
        "model",
        "options",
        "input",
    }
)
MAX_COMPOSITION_DEPTH = 16


class CallError(ValueError):
    """A treatable violation of the workflow-call boundary."""


def require_json(value: Any) -> None:
    """Reject lossy/non-JSON values, including cycles, before checkpointing."""
    try:
        encoded = json.dumps(value, allow_nan=False)
        if json.loads(encoded) != value:
            raise ValueError("JSON encoding changes the value")
    except (TypeError, ValueError, RecursionError) as exc:
        raise ValueError(f"Value is not JSON-safe: {exc}") from exc


def validate_call(config: dict[str, Any]) -> list[str]:
    from .engine import _ID_PATTERN
    from .overlay.schema import _RESERVED_WORKFLOW_IDS

    errors = []
    target = config.get("workflow")
    if not isinstance(target, str):
        errors.append("'workflow' must be a string")
    elif "{{" not in target and (
        not _ID_PATTERN.fullmatch(target) or target in _RESERVED_WORKFLOW_IDS
    ):
        errors.append("'workflow' must be an exact, safe, non-reserved workflow ID")
    mapping = config.get("input", {})
    if not isinstance(mapping, dict) or any(not isinstance(k, str) for k in mapping):
        errors.append("'input' must be a mapping with string keys")
    else:
        try:
            require_json(mapping)
        except ValueError as exc:
            errors.append(str(exc))
    return errors


def validate_runtime_call(config: dict[str, Any]) -> None:
    """Raise a call-boundary error for an invalid authored call shape."""
    errors = validate_call(config)
    if errors:
        raise CallError("; ".join(errors))


def validate_outputs(outputs: Any) -> list[str]:
    from .engine import _ID_PATTERN

    if not isinstance(outputs, dict):
        return ["'outputs' must be a mapping"]
    errors = []
    for name, entry in outputs.items():
        if not isinstance(name, str) or not _ID_PATTERN.fullmatch(name):
            errors.append(f"Output {name!r} must be a safe identifier")
        elif name in RESERVED_OUTPUT_NAMES:
            errors.append(f"Output {name!r} is reserved")
        if not isinstance(entry, dict) or set(entry) != {"value"}:
            errors.append(f"Output {name!r} must contain exactly 'value'")
        else:
            try:
                require_json(entry["value"])
            except ValueError as exc:
                errors.append(f"Output {name!r}: {exc}")
    return errors


def resolve_target(project_root: Path, target: Any, ancestry: tuple[str, ...]):
    from .catalog import WorkflowRegistry
    from .engine import _ID_PATTERN, validate_workflow
    from .overlay import WorkflowResolver
    from .overlay.schema import _RESERVED_WORKFLOW_IDS

    try:
        if not isinstance(target, str) or not _ID_PATTERN.fullmatch(target):
            raise CallError("Workflow target must be an exact safe workflow ID")
        if target in _RESERVED_WORKFLOW_IDS:
            raise CallError(f"Workflow {target!r} is reserved")
        if target in ancestry:
            raise CallError(
                f"Workflow composition cycle: {' -> '.join((*ancestry, target))}"
            )
        if len(ancestry) > MAX_COMPOSITION_DEPTH:
            raise CallError(
                f"Workflow composition exceeds maximum depth {MAX_COMPOSITION_DEPTH}"
            )
        metadata = WorkflowRegistry(project_root).get(target)
        if not isinstance(metadata, dict):
            raise CallError(f"Workflow {target!r} is not installed")
        if not metadata.get("enabled", True):
            raise CallError(f"Workflow {target!r} is disabled")
        definition = WorkflowResolver(project_root).resolve(target)
        if definition.id != target:
            raise CallError(
                f"Workflow {target!r} resolves to mismatched ID {definition.id!r}"
            )
        errors = validate_workflow(definition)
        if errors:
            raise CallError(f"Invalid workflow {target!r}: {'; '.join(errors)}")
        return definition
    except CallError:
        raise
    except (OSError, ValueError) as exc:
        raise CallError(str(exc)) from exc


def bind_inputs(
    engine,
    definition,
    config: dict[str, Any],
    context: StepContext,
    previous: dict[str, Any] | None = None,
):
    mapping = config.get("input", {})
    if not isinstance(mapping, dict) or any(not isinstance(k, str) for k in mapping):
        raise CallError("'input' must be a mapping with string keys")
    provided = {
        key: evaluate_expression(value, context) for key, value in mapping.items()
    }
    try:
        require_json(provided)
        unknown = provided.keys() - definition.inputs.keys()
        if unknown:
            raise CallError(
                f"Undeclared inputs for workflow {definition.id!r}: {sorted(unknown)}"
            )
        resolved = (
            engine._resolve_inputs(definition, provided)
            if previous is None
            else engine._merge_inputs(definition, previous, provided)
        )
        require_json(resolved)
        return resolved
    except CallError:
        raise
    except (TypeError, ValueError, RecursionError) as exc:
        raise CallError(str(exc)) from exc


def evaluate_outputs(definition, context: StepContext) -> dict[str, Any]:
    errors = validate_outputs(definition.outputs)
    if errors:
        raise CallError("; ".join(errors))
    output = {
        name: evaluate_expression(entry["value"], context)
        for name, entry in definition.outputs.items()
    }
    try:
        require_json(output)
        return output
    except (TypeError, ValueError, RecursionError) as exc:
        raise CallError(str(exc)) from exc