core.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
 
"""!
@file core.py
@brief A comprehensive conductor script for the PICurv simulation platform.
 
This script acts as the central user interface for running simulations,
managing configurations, and orchestrating the entire end-to-end workflow.
It translates user-friendly YAML files into C-solver compatible control files,
supports full multi-block configurations, and provides live log streaming.
It features intelligent, content-based config file discovery and robustly
manages data I/O paths for the post-processor. It also supports Slurm job
generation/submission and parameter sweeps via job arrays.
"""
 
import yaml
import sys
import os
import argparse
import subprocess
import shutil
import glob
import csv
import json
import hashlib
import itertools
import re
import shlex
import copy
import math
import difflib
import warnings
from datetime import datetime
import time
import filecmp
import importlib.util
import errno
import tempfile
from pathlib import Path
 
try:
    from .storage import (
        StorageError,
        cold_study_members,
        restore_cold_study_members,
        is_artifact_cold,
        read_artifact_identity,
        STORAGE_LOCK_FILENAME,
        STORAGE_STATE_FILENAME,
        require_storage_payload_local,
        runtime_stage_lock,
        storage_state_summary,
    )
except ImportError:
    # White-box tests also load core.py directly rather than as a package module. The
    # storage package resolves its own siblings by relative import, so it is loaded by
    # putting its parent on the path rather than by file location.
    _package_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    if _package_parent not in sys.path:
        sys.path.insert(0, _package_parent)
    _storage_module = importlib.import_module("picurv_cli.storage")
    StorageError = _storage_module.StorageError
    cold_study_members = _storage_module.cold_study_members
    restore_cold_study_members = _storage_module.restore_cold_study_members
    is_artifact_cold = _storage_module.is_artifact_cold
    read_artifact_identity = _storage_module.read_artifact_identity
    STORAGE_LOCK_FILENAME = _storage_module.STORAGE_LOCK_FILENAME
    STORAGE_STATE_FILENAME = _storage_module.STORAGE_STATE_FILENAME
    require_storage_payload_local = _storage_module.require_storage_payload_local
    runtime_stage_lock = _storage_module.runtime_stage_lock
    storage_state_summary = _storage_module.storage_state_summary
 
_NUMPY_MODULE = None
_MATPLOTLIB_PYPLOT = None
 
 
class _LazyNumpyProxy:
    """!
    @brief Module-like proxy that preserves `picurv.np` without eager import.
    """
 
    def __getattr__(self, name):
        """!
        @brief Resolve a NumPy attribute on first use.
        @param[in] name NumPy attribute name.
        @return Requested NumPy attribute.
        """
        return getattr(require_numpy(), name)
 
 
np = _LazyNumpyProxy()
 
 
def _prune_incompatible_python_site_paths(paths):
    """!
    @brief Remove site-package paths for a different Python major/minor version.
    @param[in] paths Candidate sys.path entries.
    @return Filtered path list.
    """
    current = (sys.version_info[0], sys.version_info[1])
    pattern = re.compile(r"python(?:-)?(\d+)\.(\d+)", re.IGNORECASE)
    filtered = []
    for path in paths:
        text = str(path)
        match = pattern.search(text)
        if match:
            path_version = (int(match.group(1)), int(match.group(2)))
            if path_version != current and ("site-packages" in text or "dist-packages" in text):
                continue
        filtered.append(path)
    return filtered
 
 
def _drop_imported_package(package_name: str):
    """!
    @brief Remove a failed/partial import package tree from sys.modules.
    @param[in] package_name Top-level package name.
    """
    prefix = package_name + "."
    for module_name in list(sys.modules):
        if module_name == package_name or module_name.startswith(prefix):
            sys.modules.pop(module_name, None)
 
 
def require_numpy():
    """!
    @brief Import NumPy only for commands that need numeric reductions.
    @return Imported NumPy module.
    """
    global _NUMPY_MODULE
    if _NUMPY_MODULE is not None:
        return _NUMPY_MODULE
    try:
        import numpy
    except Exception as exc:
        first_error = exc
        original_path = list(sys.path)
        try:
            _drop_imported_package("numpy")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import numpy
        except Exception as retry_exc:
            raise RuntimeError(
                "NumPy is required for this operation, but no compatible NumPy "
                "could be imported for this Python interpreter. PICurv ignored "
                "site-packages paths for other Python versions and retried. "
                f"First error: {first_error}. Retry error: {retry_exc}"
            ) from retry_exc
        finally:
            sys.path = original_path
    _NUMPY_MODULE = numpy
    return _NUMPY_MODULE
 
 
def optional_matplotlib_pyplot():
    """!
    @brief Import matplotlib.pyplot lazily for study plot generation.
    @return matplotlib.pyplot when available, otherwise None.
    """
    global _MATPLOTLIB_PYPLOT
    if _MATPLOTLIB_PYPLOT is not None:
        return _MATPLOTLIB_PYPLOT
    original_path = list(sys.path)
    try:
        import matplotlib.pyplot as pyplot
    except Exception:
        try:
            _drop_imported_package("matplotlib")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import matplotlib.pyplot as pyplot
        except Exception:
            return None
        finally:
            sys.path = original_path
    _MATPLOTLIB_PYPLOT = pyplot
    return _MATPLOTLIB_PYPLOT
 
# --- Global Path Definitions ---
# The implementation package and source-tree entrypoint live in picurv_cli/,
# while generators/ owns standalone generators.
PACKAGE_PATH = os.path.dirname(os.path.realpath(__file__))
PACKAGE_PROJECT_ROOT = os.path.dirname(PACKAGE_PATH)
INVOKED_SCRIPT_DIR = os.environ.get(
    "_PICURV_INVOKED_SCRIPT_DIR",
    PACKAGE_PATH,
)
SCRIPT_PATH = os.environ.get(
    "_PICURV_SCRIPT_PATH",
    PACKAGE_PATH,
)
PROJECT_ROOT = os.path.dirname(SCRIPT_PATH)
GENERATORS_PATH = os.path.join(PACKAGE_PROJECT_ROOT, "generators")
if os.path.basename(SCRIPT_PATH) == "bin":
    DEFAULT_BIN_DIR = SCRIPT_PATH
else:
    DEFAULT_BIN_DIR = os.path.join(PROJECT_ROOT, "bin")
 
VERSION_FILE = os.path.join(PACKAGE_PROJECT_ROOT, "VERSION")
 
 
def _read_release_version() -> str:
    """!
    @brief Read the single release version shared by every PICurv executable.
    @return Release version from VERSION, or a safe development fallback.
    """
    configured = os.environ.get("PICURV_RELEASE_VERSION")
    if configured:
        return configured.strip()
    try:
        with open(VERSION_FILE, "r", encoding="utf-8") as stream:
            value = stream.read().strip()
    except OSError:
        value = "0.0.0"
    return value or "0.0.0"
 
 
def _source_build_identity(release_version: str) -> dict:
    """!
    @brief Resolve reproducible release, commit, and dirty-tree build identity.
    @param[in] release_version Release version read from VERSION.
    @return Mapping suitable for manifests and user-facing status output.
    """
    identity = {
        "release_version": release_version,
        "version": release_version,
        "git_commit": None,
        "git_short_commit": None,
        "dirty": None,
        "build_id": release_version,
    }
    try:
        commit_result = subprocess.run(
            ["git", "rev-parse", "HEAD"], cwd=PACKAGE_PROJECT_ROOT,
            text=True, capture_output=True, check=False,
        )
        dirty_result = subprocess.run(
            ["git", "status", "--porcelain", "--untracked-files=no"],
            cwd=PACKAGE_PROJECT_ROOT, text=True, capture_output=True, check=False,
        )
        if commit_result.returncode == 0:
            commit = commit_result.stdout.strip()
            identity["git_commit"] = commit
            identity["git_short_commit"] = commit[:12]
        if dirty_result.returncode == 0:
            identity["dirty"] = bool(dirty_result.stdout.strip())
    except OSError:
        pass
    # Commits since the release tag, so a development build is visibly ahead of the
    # release it names rather than claiming to be that release.
    identity["dev_distance"] = None
    identity["released"] = False
    try:
        tag_result = subprocess.run(
            ["git", "describe", "--tags", "--match", f"v{release_version}", "--long"],
            cwd=PACKAGE_PROJECT_ROOT, text=True, capture_output=True, check=False,
        )
        if tag_result.returncode == 0:
            parts = tag_result.stdout.strip().rsplit("-", 2)
            if len(parts) == 3 and parts[1].isdigit():
                identity["dev_distance"] = int(parts[1])
        else:
            # No tag for this release yet: every commit is development toward it.
            count_result = subprocess.run(
                ["git", "rev-list", "--count", "HEAD"], cwd=PACKAGE_PROJECT_ROOT,
                text=True, capture_output=True, check=False,
            )
            if count_result.returncode == 0 and count_result.stdout.strip().isdigit():
                identity["dev_distance"] = int(count_result.stdout.strip())
    except OSError:
        pass
    identity["released"] = identity["dev_distance"] == 0 and not identity["dirty"]
    if identity["git_short_commit"]:
        development = "" if identity["dev_distance"] in (0, None) else f".dev{identity['dev_distance']}"
        suffix = f"{development}+g{identity['git_short_commit']}"
        if identity["dirty"]:
            suffix += ".dirty"
        identity["build_id"] = release_version + suffix
        identity["version"] = identity["build_id"]
    return identity
 
 
PICURV_RELEASE_VERSION = _read_release_version()
PICURV_BUILD = _source_build_identity(PICURV_RELEASE_VERSION)
PICURV_VERSION = PICURV_BUILD["version"]
CASE_ORIGIN_METADATA_FILENAME = ".picurv-origin.json"
WORKSPACE_CONFIG_FILENAME = ".picurv-workspace.yml"
WORKSPACE_SCHEMA_VERSION = 1
RUN_MANIFEST_SCHEMA_VERSION = 3
ASSET_MANIFEST_SCHEMA_VERSION = 1
ASSET_LOCK_SCHEMA_VERSION = 1
RUNTIME_EXECUTION_CONFIG_FILENAME = ".picurv-execution.yml"
LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME = ".picurv-local.yml"
RUNTIME_EXECUTION_EXAMPLE_FILENAME = "execution.example.yml"
RUNTIME_EXECUTION_CONFIG_FILENAMES = (
    RUNTIME_EXECUTION_CONFIG_FILENAME,
    LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME,
)
 
DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE = """# Optional shared runtime launcher overrides.
# This file is safe to leave unchanged on ordinary local machines.
# Edit it only when your site needs custom MPI launcher tokens.
#
# Precedence:
#   - local/login-node runs: local_execution -> default_execution -> built-in mpiexec
#   - generated cluster jobs: cluster.yml.execution -> cluster_execution -> default_execution -> built-in srun
#
# Example override:
# default_execution:
#   launcher: "mpirun"
#   launcher_args:
#     - --bind-to
#     - none
default_execution: {}
 
local_execution: {}
 
cluster_execution: {}
"""
 
CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT = "my_project_account"
CLUSTER_TEMPLATE_PLACEHOLDER_MAIL = "user@example.edu"
 
DEFAULT_WALLTIME_GUARD_POLICY = {
    "enabled": True,
    "warmup_steps": 10,
    "multiplier": 2.0,
    "min_seconds": 60.0,
    "estimator_alpha": 0.35,
}
WALLTIME_GUARD_ENV_JOB_START_EPOCH = "PICURV_JOB_START_EPOCH"
WALLTIME_GUARD_ENV_LIMIT_SECONDS = "PICURV_WALLTIME_LIMIT_SECONDS"
POST_RESUME_STATE_FILENAME = "post.resume.json"
POST_LOCK_FILENAME = "post.lock"
POST_LOCK_METADATA_FILENAME = "post.lock.json"
POST_LOCK_WRAPPER_FILENAME = "post_lock_wrapper.py"
POST_RESUME_SCHEMA_VERSION = 1
POST_RECIPE_SIGNATURE_EXCLUDED_KEYS = {"startTime", "endTime"}
CHECKPOINT_FORMAT = "picurv-checkpoint"
CHECKPOINT_VERSION = 1
CHECKPOINT_STEP_WIDTH = 12
CHECKPOINT_REQUIRED_EULERIAN_FIELDS = {"Ucat", "Ucont", "Ucont_rm1", "P", "Nvert"}
 
WORKSPACE_DIRECTORY_LAYOUT = (
    "config",
    "config/studies",
    "config/grids",
    "config/initial_conditions",
    "config/inlet_profiles",
    "inputs",
    "inputs/grids",
    "inputs/initial_conditions",
    "inputs/inlet_profiles",
    "inputs/reference_fields",
    "assets",
    "assets/objects",
    "assets/objects/grids",
    "assets/objects/initial_conditions",
    "assets/objects/inlet_profiles",
    "assets/sets",
    "runs",
    "studies",
)
 
RUN_DIRECTORY_LAYOUT = (
    "config",
    "config/history",
    "config/post-recipes",
    "inputs",
    "inputs/grid",
    "inputs/initial_condition",
    "inputs/inlet_profiles",
    "inputs/restart",
    "output",
    "output/checkpoints",
    "output/analysis",
    "output/analysis/metrics",
    "output/analysis/statistics",
    "output/analysis/spectra",
    "output/analysis/plots",
    "output/visualization",
    "logs",
    "scheduler",
)
 
CANONICAL_RUN_PATHS = {
    "config": "config",
    "inputs": "inputs",
    "restart": "inputs/restart",
    "output": "output",
    "checkpoints": "output/checkpoints",
    "analysis": "output/analysis",
    "metrics": "output/analysis/metrics",
    "statistics": "output/analysis/statistics",
    "spectra": "output/analysis/spectra",
    "plots": "output/analysis/plots",
    "visualization": "output/visualization",
    "logs": "logs",
    "scheduler": "scheduler",
}
 
#: Run-relative path of the staged initial-condition spectrum. It sits beside the
#: post-produced spectra but is a reference overlay, not a selectable spectrum task.
INITIAL_CONDITION_SPECTRUM_RELPATH = os.path.join(
    CANONICAL_RUN_PATHS["spectra"], "initial_condition_spectrum.csv"
)
 
_WORKSPACE_ARTIFACT_ROOT_VALUES = {"runs", "studies"}
_ASSET_SOURCE_REFERENCE_KEYS = {
    "source_file", "path", "config_file", "field_file", "grid_file", "source_case", "script"
}
_PYTHON_INITIAL_CONDITION_PROVIDERS = {"ic_gen", "spectral_random_velocity"}
_FILE_BACKED_GRID_VALUES = {"file", "grid_gen"}
_WORKSPACE_MANAGED_PATHS = {"assets", "inputs", "runs", "studies"}
_VENDORABLE_CONFIG_REFERENCE_KEYS = {"config_file", "script"}
_PLAIN_FILENAME_SENTINELS = {"", ".", ".."}
_VERSION_BUILD_ACTIONS = {"install", "activate"}
 
 
def _find_named_file_upwards(start: str, filename: str):
    """!
    @brief Find a named file at or above an arbitrary filesystem anchor.
    @param[in] start File or directory from which to search.
    @param[in] filename Basename to locate.
    @return Absolute path when found, otherwise None.
    """
    current = os.path.abspath(start or os.getcwd())
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        candidate = os.path.join(current, filename)
        if os.path.isfile(candidate):
            return candidate
        parent = os.path.dirname(current)
        if parent == current:
            return None
        current = parent
 
 
def find_workspace_root(*anchors):
    """!
    @brief Locate the nearest initialized PICurv workspace for supplied anchors.
    @param[in] anchors Candidate config, run, study, or current-working-directory paths.
    @return Workspace root path when found, otherwise None.
    """
    for anchor in anchors or (os.getcwd(),):
        if not anchor:
            continue
        found = _find_named_file_upwards(str(anchor), WORKSPACE_CONFIG_FILENAME)
        if found:
            return os.path.dirname(found)
    return None
 
 
def load_workspace_config(workspace_root: str) -> dict:
    """!
    @brief Load and validate the immutable workspace identity/configuration file.
    @param[in] workspace_root Initialized workspace directory.
    @return Parsed workspace configuration mapping.
    """
    path = os.path.join(os.path.abspath(workspace_root), WORKSPACE_CONFIG_FILENAME)
    payload = read_yaml_file(path)
    if payload.get("schema_version") != WORKSPACE_SCHEMA_VERSION:
        raise ValueError(
            f"{path}: unsupported workspace schema_version "
            f"{payload.get('schema_version')!r}; expected {WORKSPACE_SCHEMA_VERSION}."
        )
    errors: list = []
    _validate_yaml_schema_keys(payload, _WORKSPACE_SCHEMA, path, errors)
    if errors:
        raise ValueError("\n".join(errors))
    return payload
 
 
def enforce_workspace_version(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace PICurv version requirement.
    @param[in] workspace_root Initialized workspace directory.
    @return Current build identity after successful validation.
    """
    payload = load_workspace_config(workspace_root)
    software = payload.get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if requirement in (None, ""):
        return dict(PICURV_BUILD)
    try:
        from packaging.specifiers import SpecifierSet
        from packaging.version import Version
        requirement_text = str(requirement).strip()
        if not any(token in requirement_text for token in "<>=!~"):
            requirement_text = "==" + requirement_text
        matches = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
    except Exception as exc:
        raise ValueError(
            f"{WORKSPACE_CONFIG_FILENAME}: software.picurv={requirement!r} is not a valid "
            "version or version range."
        ) from exc
    if not matches:
        raise ValueError(
            f"Workspace requires PICurv {requirement!r}, but the active release is "
            f"{PICURV_RELEASE_VERSION} (build {PICURV_BUILD['build_id']}).\n"
            f"Activate a matching installation with 'picurv versions activate <version>' "
            "and retry.\n"
            f"Note: {PACKAGE_PROJECT_ROOT} is a single shared installation. Activating "
            "re-points every workspace and every unpinned job that resolves executables "
            "from it, so two workspaces pinned to different releases cannot both be "
            "satisfied at once. Pin a case's executables with 'picurv init --pin-binaries' "
            "when it must survive an activation."
        )
    return dict(PICURV_BUILD)
 
 
def enforce_reproducibility_policy(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace policy demanding a clean, released build.
 
    @details Exploratory work should stay frictionless, so this is opt-in: a workspace
             running a campaign that will be published sets it once, and PICurv then
             refuses to stage from a modified or untagged tree instead of recording the
             compromise in a manifest nobody reads until later.
    @param[in] workspace_root Initialized workspace directory, or None.
    @return The resolved policy mapping, empty when none is configured.
    @throws ValueError when the active build does not satisfy the configured policy.
    """
    if not workspace_root:
        return {}
    payload = load_workspace_config(workspace_root)
    policy = payload.get("reproducibility") or {}
    if not isinstance(policy, dict) or not policy:
        return {}
    if policy.get("require_clean_release"):
        problems = []
        if PICURV_BUILD.get("dirty"):
            problems.append("the source tree has uncommitted changes")
        if PICURV_BUILD.get("dev_distance"):
            problems.append(
                f"HEAD is {PICURV_BUILD['dev_distance']} commit(s) past the "
                f"v{PICURV_RELEASE_VERSION} release tag"
            )
        elif PICURV_BUILD.get("dev_distance") is None:
            problems.append("the release tag could not be resolved from this checkout")
        if problems:
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.require_clean_release, "
                f"but this build is {PICURV_BUILD['build_id']}: " + "; ".join(problems) + ".\n"
                "Commit and tag the release, or clear the policy for exploratory work."
            )
    if policy.get("pin_executables"):
        stale = [
            name for name, identity in sorted(runtime_build_identities().items())
            if identity.get("available") and not identity.get("matches_source")
        ]
        unavailable = [
            name for name, identity in sorted(runtime_build_identities().items())
            if not identity.get("available")
        ]
        if stale or unavailable:
            detail = []
            if stale:
                detail.append("built from another revision: " + ", ".join(stale))
            if unavailable:
                detail.append("no build identity available: " + ", ".join(unavailable))
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.pin_executables, but "
                "the executables do not match the active source (" + "; ".join(detail) + ").\n"
                "Run 'make all' so the run records the build that produced it."
            )
    return dict(policy)
 
 
def resolve_workspace_path(anchor_file: str, candidate: str, *, allow_external: bool = False) -> str:
    """!
    @brief Resolve a user path against its workspace and reject implicit escapes.
    @param[in] anchor_file Config file whose workspace owns the reference.
    @param[in] candidate Workspace-relative path text.
    @param[in] allow_external Whether an explicit import/reference operation permits an absolute path.
    @return Absolute resolved path.
    """
    if not isinstance(candidate, str) or not candidate.strip():
        raise ValueError("Referenced path must be a non-empty string.")
    text = os.path.expanduser(candidate.strip())
    workspace_root = find_workspace_root(anchor_file)
    if not workspace_root:
        return os.path.abspath(text if os.path.isabs(text) else os.path.join(os.path.dirname(os.path.abspath(anchor_file)), text))
    if os.path.isabs(text):
        if allow_external:
            return os.path.abspath(text)
        raise ValueError(
            f"{anchor_file}: absolute path {candidate!r} is not allowed in workspace configuration; "
            "import it with 'picurv inputs import' or use an explicit reference-mode import."
        )
    resolved = os.path.abspath(os.path.join(workspace_root, text))
    if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
        raise ValueError(
            f"{anchor_file}: path {candidate!r} escapes the workspace; parent traversal is not allowed."
        )
    if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
        pointer = read_yaml_file(resolved)
        external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
        if not isinstance(external, str) or not os.path.isabs(external):
            raise ValueError(f"Invalid external-reference descriptor: {resolved}")
        if not os.path.isfile(external):
            raise ValueError(f"Registered external input is unavailable: {external}")
        return external
    return resolved
 
 
def ensure_workspace_layout(workspace_root: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one workspace.
    @param[in] workspace_root Workspace root to initialize.
    """
    for relative in WORKSPACE_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(workspace_root, *relative.split("/")), exist_ok=True)
 
 
def initialize_workspace_root(workspace_root: str, template_name: str) -> str:
    """!
    @brief Create the workspace skeleton and its identity file at one root.
    @param[in] workspace_root Workspace root to initialize.
    @param[in] template_name Example template the workspace was created from.
    @return Path to the written workspace configuration file.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    config_path = os.path.join(workspace_root, WORKSPACE_CONFIG_FILENAME)
    write_yaml_file(config_path, {
        "schema_version": WORKSPACE_SCHEMA_VERSION,
        "workspace": {
            "id": os.path.basename(workspace_root),
            "template": template_name,
            "created_at": datetime.now().astimezone().isoformat(),
        },
        "software": {},
        "paths": {
            "config": "config",
            "inputs": "inputs",
            "assets": "assets",
            "runs": "runs",
            "studies": "studies",
        },
    })
    return config_path
 
 
def ensure_run_layout(run_dir: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one run.
    @param[in] run_dir Run root to initialize.
    """
    for relative in RUN_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(run_dir, *relative.split("/")), exist_ok=True)
 
 
#: Top-level directory names a run owns. Anything else beside them is a peer PICurv
#: does not route, cannot classify for storage, and will not prune.
RUN_DIRECTORY_ROOTS = frozenset(
    relative.split("/")[0] for relative in RUN_DIRECTORY_LAYOUT
)
 
#: Files a run legitimately carries at its own root. Storage's own markers are added
#: at validation time, so this stays the list of what the conductor writes.
RUN_ROOT_ALLOWED_FILES = frozenset({"manifest.json"})
 
 
def validate_run_directory_structure(run_dir: str) -> tuple:
    """!
    @brief Refuse a run whose root has grown a directory the layout does not define.
 
    @details The run topology is a contract: `manifest.json` publishes it, the solver's
             reserved-directory guard defends it, and storage classifies against it. A
             directory beside `output/` breaks all three at once - it is routed by
             nothing, classified as `unclassified`, and therefore archived forever and
             pruned never. Catching it when the run is staged or resumed is the only
             point where the answer is still "move it", rather than "it is already in
             every archive of this run".
 
             Unexpected *files* are reported and allowed. A stray note at a run root
             costs nothing and refusing to resume a long campaign over one would be a
             worse failure than the one being prevented.
    @param[in] run_dir Run root to check.
    @return Tuple of (errors, warnings) as human-readable message lists.
    """
    root = os.path.abspath(run_dir)
    if not os.path.isdir(root):
        return [], []
    allowed_files = set(RUN_ROOT_ALLOWED_FILES) | {
        STORAGE_STATE_FILENAME, STORAGE_LOCK_FILENAME,
    }
    errors, warnings = [], []
    for name in sorted(os.listdir(root)):
        path = os.path.join(root, name)
        if os.path.isdir(path) and not os.path.islink(path):
            if name not in RUN_DIRECTORY_ROOTS:
                errors.append(
                    f"{run_dir}: '{name}/' is not part of the run layout. Scientific "
                    f"output belongs under {CANONICAL_RUN_PATHS['checkpoints']}, "
                    f"{CANONICAL_RUN_PATHS['analysis']}, or "
                    f"{CANONICAL_RUN_PATHS['visualization']}; move or remove '{name}/' "
                    f"before running. Run-owned roots are: "
                    + ", ".join(sorted(RUN_DIRECTORY_ROOTS)) + "."
                )
        elif name not in allowed_files:
            warnings.append(
                f"{run_dir}: unexpected file '{name}' at the run root. It is archived "
                "as unclassified and never pruned."
            )
    return errors, warnings
 
 
def enforce_run_directory_structure(run_dir: str) -> None:
    """!
    @brief Apply `validate_run_directory_structure()` as a refusal at run time.
    @param[in] run_dir Run root to check.
    @return None. Exits non-zero when the run root carries a directory outside the layout.
    """
    errors, warnings = validate_run_directory_structure(run_dir)
    for message in warnings:
        print(f"[WARN] {message}", file=sys.stderr)
    if not errors:
        return
    for message in errors:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="run_layout",
            file_path=os.path.abspath(run_dir),
            message=message,
            hint="Move the directory under output/ or out of the run, then retry.",
        )
    sys.exit(1)
 
 
def case_run_label(case_cfg: dict, case_path: str) -> str:
    """!
    @brief Resolve the stable human-facing portion of a generated run identifier.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case YAML path.
    @return Filesystem-safe case title, name, or source stem.
    """
    metadata = case_cfg.get("metadata") or {}
    candidate = (
        case_cfg.get("title")
        or (metadata.get("title") if isinstance(metadata, dict) else None)
        or (metadata.get("name") if isinstance(metadata, dict) else None)
        or Path(case_path).stem
    )
    label = re.sub(r"[^A-Za-z0-9_.-]+", "-", str(candidate).strip()).strip("-.")
    return label or "case"
 
 
def allocate_generated_run_id(runs_root: str, case_cfg: dict, case_path: str) -> str:
    """!
    @brief Build the generated run identity, disambiguating a same-second collision.
 
    @details The identity is `<run label>_<timestamp>` at one-second resolution, so two
             runs of the same case launched back to back - a script, or a smoke
             sequence - would otherwise name the same directory. Creating a run never
             writes into an existing one, so the identity is advanced instead of the
             launch being refused for a clock artifact.
    @param[in] runs_root Directory generated runs are created beneath.
    @param[in] case_cfg Parsed case configuration supplying the run label.
    @param[in] case_path Case path, for the label's fallback.
    @return Run identity that does not currently exist under `runs_root`.
    """
    base = f"{case_run_label(case_cfg, case_path)}_{datetime.now().strftime('%Y%m%d-%H%M%S')}"
    run_id, suffix = base, 1
    while os.path.exists(os.path.join(runs_root, run_id)):
        suffix += 1
        run_id = f"{base}-{suffix}"
    return run_id
 
 
def discard_unused_run_directory(run_dir: str, *, created: bool) -> bool:
    """!
    @brief Remove a generated run directory that never received any content.
 
    @details Only a directory this invocation created, and which still holds no files,
             is removed: an existing run, or one that already produced output, is never
             touched by a staging failure.
    @param[in] run_dir Run directory that was about to be staged.
    @param[in] created Whether this invocation created the directory.
    @return True when the directory was removed.
    """
    if not created or not os.path.isdir(run_dir):
        return False
    for _root, _dirs, files in os.walk(run_dir):
        if files:
            return False
    shutil.rmtree(run_dir, ignore_errors=True)
    return True
 
 
def _file_sha256(path: str):
    """!
    @brief Content digest of one file, or None when it cannot be read.
    @param[in] path File to digest.
    @return Hex digest, or None.
    """
    digest = hashlib.sha256()
    try:
        with open(path, "rb") as stream:
            for block in iter(lambda: stream.read(1024 * 1024), b""):
                digest.update(block)
    except OSError:
        return None
    return digest.hexdigest()
 
 
def build_software_lock() -> dict:
    """!
    @brief Capture the exact software identity a run is about to execute with.
 
    @details The release and commit say which source is checked out; they do not say
             which bytes ran. Hashing the executables and the generators pins that, so
             a queued job rebuilt out from under it is detectable afterwards rather
             than merely suspected.
    @return Software lock mapping.
    """
    lock = {
        "schema_version": 1,
        "picurv_version": PICURV_RELEASE_VERSION,
        "build_id": PICURV_BUILD.get("build_id"),
        "git_commit": PICURV_BUILD.get("git_commit"),
        "git_dirty": PICURV_BUILD.get("dirty"),
        "captured_at": datetime.now().astimezone().isoformat(),
        "executables": {},
        "generators": {},
        "environment": _toolchain_identity(),
    }
    for name in ("simulator", "postprocessor"):
        path = resolve_runtime_executable(name)
        identity = read_binary_build_identity(path)
        lock["executables"][name] = {
            "path": path,
            "sha256": _file_sha256(path),
            "build_id": identity.get("build_id"),
            "matches_source": identity.get("matches_source"),
        }
    conductor = os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "core.py")
    lock["python_conductor_sha256"] = _file_sha256(conductor)
    if os.path.isdir(GENERATORS_PATH):
        for entry in sorted(os.listdir(GENERATORS_PATH)):
            candidate = os.path.join(GENERATORS_PATH, entry)
            if os.path.isfile(candidate):
                lock["generators"][entry] = _file_sha256(candidate)
    return lock
 
 
def _toolchain_identity() -> dict:
    """!
    @brief Best-effort record of the PETSc, MPI, and compiler the binaries were built on.
    @return Mapping of what could be determined; absent keys mean it could not be read.
    """
    identity = {}
    petsc_dir = os.environ.get("PETSC_DIR")
    if petsc_dir:
        identity["petsc_dir"] = petsc_dir
        version_header = os.path.join(petsc_dir, "include", "petscversion.h")
        try:
            with open(version_header, "r", encoding="utf-8", errors="replace") as stream:
                numbers = {}
                for line in stream:
                    match = re.match(
                        r"#define\s+PETSC_VERSION_(MAJOR|MINOR|SUBMINOR)\s+(\d+)", line
                    )
                    if match:
                        numbers[match.group(1)] = match.group(2)
                if len(numbers) == 3:
                    identity["petsc_version"] = (
                        f"{numbers['MAJOR']}.{numbers['MINOR']}.{numbers['SUBMINOR']}"
                    )
        except OSError:
            pass
    if os.environ.get("PETSC_ARCH"):
        identity["petsc_arch"] = os.environ["PETSC_ARCH"]
    for tool, key in (("mpiexec", "mpi"), ("mpicc", "compiler")):
        executable = shutil.which(tool)
        if not executable:
            continue
        try:
            result = subprocess.run(
                [executable, "--version"], text=True, capture_output=True, timeout=20, check=False
            )
        except (OSError, subprocess.SubprocessError):
            continue
        first = (result.stdout or result.stderr or "").strip().splitlines()
        if first:
            identity[key] = first[0][:200]
    return identity
 
 
def write_software_lock(run_dir: str) -> str:
    """!
    @brief Write the run's software lock beside its asset lock.
    @param[in] run_dir Run directory receiving the lock.
    @return Path to the written lock.
    """
    path = os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "software.lock.json")
    os.makedirs(os.path.dirname(path), exist_ok=True)
    write_json_file(path, build_software_lock())
    return path
 
 
def workspace_artifact_root(workspace_root: str, kind: str) -> str:
    """!
    @brief Return the canonical workspace-owned root for runs or studies.
    @param[in] workspace_root Initialized workspace, or None for standalone mode.
    @param[in] kind Either runs or studies.
    @return Absolute artifact root.
    """
    if kind not in _WORKSPACE_ARTIFACT_ROOT_VALUES:
        raise ValueError(f"Unsupported workspace artifact kind: {kind}")
    if workspace_root:
        return os.path.join(os.path.abspath(workspace_root), kind)
    return os.path.abspath(kind)
 
 
def _relative_to_workspace(path: str, workspace_root: str):
    """!
    @brief Return a portable workspace-relative path when possible.
    @param[in] path Path to normalize.
    @param[in] workspace_root Optional initialized workspace root.
    @return Workspace-relative POSIX path, absolute path, or None.
    """
    if not path:
        return None
    absolute = os.path.abspath(path)
    if workspace_root and os.path.commonpath([absolute, workspace_root]) == os.path.abspath(workspace_root):
        return os.path.relpath(absolute, workspace_root).replace(os.sep, "/")
    return absolute
 
 
def snapshot_run_configuration(run_dir: str, source_paths: dict,
                               continuation: bool = False) -> dict:
    """!
    @brief Snapshot editable YAML inputs without erasing prior continuation state.
    @param[in] run_dir Owning run directory.
    @param[in] source_paths Role-to-source-path mapping.
    @param[in] continuation Whether this is a continuation configuration revision.
    @return Active snapshot metadata.
    """
    config_root = os.path.join(run_dir, "config")
    os.makedirs(config_root, exist_ok=True)
    revision = None
    destination_root = config_root
    if continuation:
        revision = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
        destination_root = os.path.join(config_root, "history", revision)
        os.makedirs(destination_root, exist_ok=False)
    snapshots = {}
    for role, source in source_paths.items():
        if not source:
            continue
        source = os.path.abspath(source)
        suffix = os.path.splitext(source)[1] or ".yml"
        name = f"{role}{suffix}" if role != "cluster" else "cluster.yml"
        destination = os.path.join(destination_root, name)
        shutil.copy2(source, destination)
        snapshots[role] = os.path.relpath(destination, run_dir).replace(os.sep, "/")
    active = {
        "schema_version": 1,
        "revision": revision or "initial",
        "updated_at": datetime.now().astimezone().isoformat(),
        "files": snapshots,
    }
    write_json_file(os.path.join(config_root, "active.json"), active)
    return active
 
 
def load_active_run_configuration(run_dir: str) -> dict:
    """!
    @brief Load the active immutable configuration revision for a run.
    @param[in] run_dir Run directory.
    @return Role-to-absolute-path mapping.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active = _read_json_if_exists(os.path.join(config_root, "active.json"))
    if isinstance(active, dict) and isinstance(active.get("files"), dict):
        return {
            role: os.path.join(run_dir, *relative.split("/"))
            for role, relative in active["files"].items()
            if isinstance(relative, str)
        }
    return {
        role: os.path.join(config_root, f"{role}.yml")
        for role in ("case", "solver", "monitor", "cluster")
        if os.path.isfile(os.path.join(config_root, f"{role}.yml"))
    }
 
 
def archive_active_generated_configuration(run_dir: str, paths: list) -> dict:
    """!
    @brief Preserve generated control sidecars beside a continuation's YAML revision.
    @param[in] run_dir Owning run.
    @param[in] paths Generated control and sidecar paths.
    @return Updated active configuration record.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active_path = os.path.join(config_root, "active.json")
    active = _read_json_if_exists(active_path) or {"schema_version": 1, "revision": "initial", "files": {}}
    revision = active.get("revision", "initial")
    target_root = config_root if revision == "initial" else os.path.join(config_root, "history", revision)
    os.makedirs(target_root, exist_ok=True)
    files = active.setdefault("files", {})
    for source in paths:
        if not source or not os.path.isfile(source):
            continue
        source = os.path.abspath(source)
        destination = os.path.join(target_root, os.path.basename(source))
        if source != destination:
            shutil.copy2(source, destination)
        relative = os.path.relpath(destination, run_dir).replace(os.sep, "/")
        if destination.endswith(".control"):
            files["control"] = relative
        else:
            files.setdefault("generated", []).append(relative)
    active["updated_at"] = datetime.now().astimezone().isoformat()
    write_json_file(active_path, active)
    return active
 
 
#: Storage states in which a run's heavy payload is no longer wholly local. A component
#: absent under one of these was archived, not skipped.
STORAGE_OFFLOADED_STATES = frozenset({"COLD", "PARTIAL"})
 
#: Lifecycle states a run component can be in, as reported by the run manifest.
RUN_COMPONENT_STATES = (
    "not_requested", "planned", "running", "partial", "complete", "failed", "offloaded",
)
 
#: Run components, their canonical home, and the retention class storage applies.
RUN_COMPONENT_LAYOUT = (
    ("configuration", "config", "essential"),
    ("inputs", "inputs", "essential"),
    ("checkpoints", "output/checkpoints", "policy"),
    ("analysis", "output/analysis", "derived"),
    ("field_statistics", "output/analysis/statistics", "derived"),
    ("spectra", "output/analysis/spectra", "derived"),
    ("visualization", "output/visualization", "derived"),
    ("logs", "logs", "essential"),
    ("scheduler", "scheduler", "essential"),
)
 
 
def _run_component_states(run_dir: str, stages_requested: dict) -> dict:
    """!
    @brief Report each run component's home, retention class, and lifecycle state.
 
    @details The skeleton is created whole, so an empty directory says nothing about
             whether its contents were requested. This is where that question is
             answered, and it is answered for every component whether or not it ran.
    @param[in] run_dir Run directory being described.
    @param[in] stages_requested Mapping of requested stage names to booleans.
    @return Component name to `{path, retention, state}` mapping.
    """
    marker = storage_state_summary(run_dir) if os.path.isdir(run_dir) else {"state": "LOCAL"}
    offloaded = marker.get("state") in STORAGE_OFFLOADED_STATES
    solve_requested = bool(stages_requested.get("solve"))
    post_requested = bool(stages_requested.get("post_process"))
    requested = {
        "configuration": True,
        "inputs": True,
        "logs": True,
        "scheduler": True,
        "checkpoints": solve_requested,
        "analysis": post_requested,
        "field_statistics": post_requested,
        "spectra": post_requested,
        "visualization": post_requested,
    }
    components = {}
    for name, relative, retention in RUN_COMPONENT_LAYOUT:
        path = os.path.join(run_dir, *relative.split("/"))
        populated = False
        if os.path.isdir(path):
            populated = any(files for _root, _dirs, files in os.walk(path))
        if populated:
            state = "offloaded" if offloaded and retention != "essential" else "complete"
        elif not requested.get(name, False):
            state = "not_requested"
        elif offloaded:
            state = "offloaded"
        else:
            state = "planned"
        components[name] = {"path": relative, "retention": retention, "state": state}
    return components
 
 
def build_run_lineage(parent_run_dir: str, checkpoint_step: int, *, workspace_root=None,
                      statistics_state=None, requested_source=None) -> dict:
    """!
    @brief Record which run and which checkpoint a branched run was started from.
 
    @details Without this a branch is indistinguishable from a fresh run: the copied
             bundle under `inputs/restart/` carries the parent's geometry and software
             identity but never says which run produced it, so the trajectory a result
             belongs to cannot be reconstructed after the fact.
 
             The parent's own manifest is asked for its identity rather than its
             directory name, so a parent that was renamed or restored under another
             name is still named correctly here.
    @param[in] parent_run_dir Absolute path to the run being branched from.
    @param[in] checkpoint_step Checkpoint step the branch starts from.
    @param[in] workspace_root Optional workspace root, to record a portable path.
    @param[in] statistics_state Resolved field-statistics decision for the branch.
    @param[in] requested_source What the user asked for, e.g. "latest" or a path.
    @return JSON-serializable lineage record.
    """
    parent_identity = read_artifact_identity(parent_run_dir)
    return {
        "relationship": "branch",
        "parent_run_id": parent_identity["run_id"],
        "parent_study_id": parent_identity["study_id"] if parent_identity["case_id"] else None,
        "parent_case_id": parent_identity["case_id"],
        "parent_identity_source": parent_identity["identity_source"],
        "parent_path": _relative_to_workspace(parent_run_dir, workspace_root),
        "checkpoint_step": int(checkpoint_step),
        "statistics_state": statistics_state,
        "requested_source": requested_source,
        "recorded_at": datetime.now().astimezone().isoformat(),
    }
 
 
def build_run_manifest(run_dir: str, run_id: str, *, workspace_root=None,
                       launch_mode: str = "local", num_procs: int = 1,
                       post_num_procs: int = 1, stages_requested=None,
                       stages_completed=None, inputs=None, asset_lock=None,
                       submission=None, lineage=None, artifact_type: str = "run",
                       study_id=None, case_id=None) -> dict:
    """!
    @brief Build the authoritative run identity, topology, and lifecycle manifest.
    @param[in] run_dir Owning run directory.
    @param[in] run_id Stable run identity.
    @param[in] workspace_root Optional initialized workspace root.
    @param[in] launch_mode Local or scheduler-backed launch mode.
    @param[in] num_procs Effective solver process count.
    @param[in] post_num_procs Effective post-process count.
    @param[in] stages_requested Requested stage mapping.
    @param[in] stages_completed Completed or submitted stage names.
    @param[in] inputs Active configuration identities.
    @param[in] asset_lock Resolved run asset lock.
    @param[in] submission Scheduler submission metadata.
    @param[in] lineage Where this run's initial state came from; see `build_run_lineage()`.
    @param[in] artifact_type "run" for a standalone run, "study-case" for a study member.
    @param[in] study_id Owning study identity, for a study member.
    @param[in] case_id Member identity within its study.
    @return JSON-serializable run manifest.
    """
    existing = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    created_at = existing.get("created_at") or datetime.now().astimezone().isoformat()
    payload = {
        "schema_version": RUN_MANIFEST_SCHEMA_VERSION,
        "artifact_type": artifact_type,
        "run_id": run_id,
        "study_id": study_id,
        "case_id": case_id,
        "created_at": created_at,
        "updated_at": datetime.now().astimezone().isoformat(),
        "workspace": (
            (load_workspace_config(workspace_root).get("workspace") or {})
            if workspace_root else None
        ),
        "software": dict(PICURV_BUILD),
        # The conductor's identity says which source staged the run; the binaries'
        # says which build produced its checkpoints. They can differ - an edited C
        # tree that was never rebuilt - so provenance records both.
        "binaries": runtime_build_identities(),
        "launch_mode": launch_mode,
        "num_procs": num_procs,
        "solver_num_procs": num_procs,
        "post_num_procs": post_num_procs,
        "stages_requested": stages_requested or {},
        "stages_completed_or_submitted": stages_completed or [],
        "inputs": inputs or {},
        "paths": dict(CANONICAL_RUN_PATHS),
        # Fixed schema, every component present whatever happened, so a reader never
        # has to distinguish "absent because it was not asked for" from "absent because
        # it failed" by looking for empty directories.
        "components": _run_component_states(run_dir, stages_requested or {}),
        "assets": (asset_lock or {}).get("assets", {}),
        "runtime_providers": (asset_lock or {}).get("runtime_providers", {}),
        # Always present, so a reader distinguishes "this run began from nothing" from
        # "this manifest predates lineage" by the value rather than by the key's absence.
        # A re-staged continuation keeps the lineage recorded when the run was created:
        # what a run branched from does not change because it was resumed.
        "lineage": lineage or existing.get("lineage") or {"relationship": "root"},
        "submission": submission or {},
    }
    return payload
 
 
def _checkpoint_bundle_path(source_dir: str, step: int) -> str:
    """!
    @brief Resolve a run/output root or an exact checkpoint bundle.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Checkpoint step to resolve.
    @return Absolute path to the checkpoint bundle.
    """
    source_dir = os.path.abspath(source_dir)
    if os.path.isfile(os.path.join(source_dir, "checkpoint.meta")):
        return source_dir
    return os.path.join(source_dir, "checkpoints", f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}")
 
 
def _read_checkpoint_options(metadata_path: str) -> dict:
    """!
    @brief Parse the deliberately small PETSc-options checkpoint manifest.
    @param[in] metadata_path Path to checkpoint.meta.
    @return Mapping of option names to scalar text values.
    """
    options = {}
    with open(metadata_path, "r", encoding="utf-8") as stream:
        for line_number, raw_line in enumerate(stream, start=1):
            tokens = shlex.split(raw_line, comments=True, posix=True)
            if not tokens:
                continue
            if len(tokens) != 2 or not tokens[0].startswith("-"):
                raise ValueError(
                    f"Invalid checkpoint metadata line {line_number} in {metadata_path}."
                )
            key = tokens[0][1:]
            if key in options:
                raise ValueError(f"Duplicate checkpoint metadata key '-{key}' in {metadata_path}.")
            options[key] = tokens[1]
    return options
 
 
def validate_committed_checkpoint(source_dir: str, step: int, require_particles: bool = False) -> dict:
    """!
    @brief Validate one committed bundle using the same manifest contract as C.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Expected checkpoint step.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Validated bundle path, metadata, and payload inventory.
    """
    bundle = _checkpoint_bundle_path(source_dir, step)
    metadata_path = os.path.join(bundle, "checkpoint.meta")
    commit_path = os.path.join(bundle, "COMMITTED")
    if not os.path.isfile(metadata_path) or not os.path.isfile(commit_path):
        raise ValueError(f"No committed checkpoint for step {step}: {bundle}")
 
    with open(commit_path, "r", encoding="ascii") as stream:
        expected_digest = stream.read().strip()
    if not re.fullmatch(r"[0-9a-fA-F]{64}", expected_digest):
        raise ValueError(f"Invalid checkpoint commit marker: {commit_path}")
    with open(metadata_path, "rb") as stream:
        actual_digest = hashlib.sha256(stream.read()).hexdigest()
    if actual_digest.lower() != expected_digest.lower():
        raise ValueError(f"Checkpoint metadata hash mismatch: {bundle}")
 
    options = _read_checkpoint_options(metadata_path)
    try:
        saved_version = int(options.get("checkpoint_version", "-1"))
        saved_step = int(options.get("checkpoint_step", "-1"))
        payload_count = int(options.get("checkpoint_payload_count", "-1"))
        particle_count = int(options.get("checkpoint_particle_count", "-1"))
        block_count = int(options.get("checkpoint_block_count", "-1"))
        float(options["checkpoint_time"])
    except (KeyError, TypeError, ValueError) as exc:
        raise ValueError(f"Checkpoint metadata is incomplete or malformed: {metadata_path}") from exc
    if options.get("checkpoint_format") != CHECKPOINT_FORMAT or saved_version != CHECKPOINT_VERSION:
        raise ValueError(f"Unsupported checkpoint format/version: {metadata_path}")
    if saved_step != step:
        raise ValueError(f"Checkpoint records step {saved_step}, expected {step}: {bundle}")
    if payload_count <= 0 or particle_count < 0 or block_count <= 0:
        raise ValueError(f"Checkpoint inventory counts are invalid: {metadata_path}")
 
    payloads = []
    for index in range(payload_count):
        prefix = f"checkpoint_payload_{index}_"
        relative_path = options.get(prefix + "path")
        try:
            expected_bytes = int(options[prefix + "bytes"])
        except (KeyError, TypeError, ValueError) as exc:
            raise ValueError(f"Checkpoint payload {index} has invalid metadata: {metadata_path}") from exc
        if not relative_path or os.path.isabs(relative_path) or ".." in relative_path.split("/"):
            raise ValueError(f"Checkpoint payload {index} has an unsafe path: {relative_path!r}")
        payload_path = os.path.join(bundle, *relative_path.split("/"))
        if not os.path.isfile(payload_path) or os.path.getsize(payload_path) != expected_bytes:
            raise ValueError(f"Checkpoint payload is missing or truncated: {payload_path}")
        payloads.append({
            "path": relative_path,
            "kind": options.get(prefix + "kind"),
            "field": options.get(prefix + "field"),
            "block": options.get(prefix + "block"),
        })
 
    for block in range(block_count):
        fields = {
            item["field"] for item in payloads
            if item["kind"] == "eulerian" and item["block"] == str(block)
        }
        missing = CHECKPOINT_REQUIRED_EULERIAN_FIELDS - fields
        if missing:
            raise ValueError(
                f"Checkpoint block {block} is missing required Eulerian field(s): "
                f"{', '.join(sorted(missing))}."
            )
    particle_payloads = [item for item in payloads if item["kind"] == "particle"]
    has_particles = options.get("checkpoint_particles", "false").lower() == "true"
    if (not has_particles and particle_count != 0) or (has_particles and not particle_payloads):
        raise ValueError(f"Checkpoint particle inventory is inconsistent: {metadata_path}")
    if require_particles and not has_particles:
        raise ValueError(f"Checkpoint step {step} does not contain particle state: {bundle}")
 
    return {
        "bundle": bundle,
        "metadata": options,
        "payloads": payloads,
        "has_particles": has_particles,
        "particle_count": particle_count,
    }
 
 
def _scan_committed_checkpoint_steps(source_dir: str, require_particles: bool = False) -> "set[int]":
    """!
    @brief Return only fully validated, committed checkpoint steps.
    @param[in] source_dir Run/output root containing checkpoints.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Set of valid committed step numbers.
    """
    checkpoints_dir = os.path.join(os.path.abspath(source_dir), "checkpoints")
    if not os.path.isdir(checkpoints_dir):
        return set()
    pattern = re.compile(rf"^step_(\d{{{CHECKPOINT_STEP_WIDTH}}})$")
    steps = set()
    for name in os.listdir(checkpoints_dir):
        match = pattern.fullmatch(name)
        if not match:
            continue
        step = int(match.group(1))
        try:
            validate_committed_checkpoint(source_dir, step, require_particles=require_particles)
        except ValueError:
            continue
        steps.add(step)
    return steps
 
 
def parse_slurm_time_limit_to_seconds(time_text: str) -> int:
    """!
    @brief Parse a Slurm time-limit string into total seconds.
    @param[in] time_text Argument passed to `parse_slurm_time_limit_to_seconds()`.
    @return Value returned by `parse_slurm_time_limit_to_seconds()`.
    """
    text = str(time_text).strip()
    if not text:
        raise ValueError("time limit cannot be empty")
 
    days = 0
    clock_text = text
    if "-" in text:
        day_text, clock_text = text.split("-", 1)
        if not day_text.isdigit():
            raise ValueError(f"invalid day field '{day_text}'")
        days = int(day_text)
        if not clock_text:
            raise ValueError("missing time portion after day field")
 
    parts = clock_text.split(":")
    if len(parts) > 3:
        raise ValueError(f"unsupported time format '{time_text}'")
    if any(part == "" for part in parts):
        raise ValueError(f"malformed time field '{time_text}'")
    if any(not part.isdigit() for part in parts):
        raise ValueError(f"non-numeric time field '{time_text}'")
 
    nums = [int(part) for part in parts]
    if days > 0:
        if len(nums) == 1:
            hours, minutes, seconds = nums[0], 0, 0
        elif len(nums) == 2:
            hours, minutes = nums
            seconds = 0
        else:
            hours, minutes, seconds = nums
    else:
        if len(nums) == 1:
            hours, minutes, seconds = 0, nums[0], 0
        elif len(nums) == 2:
            hours = 0
            minutes, seconds = nums
        else:
            hours, minutes, seconds = nums
 
    if minutes >= 60 or seconds >= 60:
        raise ValueError(f"minutes and seconds must be < 60 in '{time_text}'")
    if days == 0 and len(nums) == 3 and hours < 0:
        raise ValueError(f"hours must be non-negative in '{time_text}'")
 
    total_seconds = (((days * 24) + hours) * 60 + minutes) * 60 + seconds
    if total_seconds <= 0:
        raise ValueError("time limit must be positive")
    return total_seconds
 
 
def resolve_walltime_guard_policy(cluster_cfg: "dict | None") -> "dict | None":
    """!
    @brief Resolve the effective Slurm walltime-guard policy for generated solver jobs.
    @param[in] cluster_cfg Argument passed to `resolve_walltime_guard_policy()`.
    @return Value returned by `resolve_walltime_guard_policy()`.
    """
    if not isinstance(cluster_cfg, dict):
        return None
 
    scheduler = cluster_cfg.get("scheduler", {}) or {}
    if str(scheduler.get("type", "slurm")).lower() != "slurm":
        return None
 
    execution = cluster_cfg.get("execution", {}) or {}
    guard_cfg = execution.get("walltime_guard")
    if guard_cfg is None:
        guard_cfg = {}
    elif not isinstance(guard_cfg, dict):
        raise ValueError("execution.walltime_guard must be a mapping when provided")
 
    policy = copy.deepcopy(DEFAULT_WALLTIME_GUARD_POLICY)
    policy.update(guard_cfg)
    policy["enabled"] = bool(policy["enabled"])
    policy["warmup_steps"] = int(policy["warmup_steps"])
    policy["multiplier"] = float(policy["multiplier"])
    policy["min_seconds"] = float(policy["min_seconds"])
    policy["estimator_alpha"] = float(policy["estimator_alpha"])
    return policy
 
 
def build_walltime_guard_exports(cluster_cfg: "dict | None") -> dict:
    """!
    @brief Build shell-evaluated environment exports for the runtime walltime guard.
    @param[in] cluster_cfg Argument passed to `build_walltime_guard_exports()`.
    @return Value returned by `build_walltime_guard_exports()`.
    """
    policy = resolve_walltime_guard_policy(cluster_cfg)
    if not policy or not policy.get("enabled", False):
        return {}
    walltime_limit_seconds = parse_slurm_time_limit_to_seconds(cluster_cfg.get("resources", {}).get("time", ""))
    return {
        WALLTIME_GUARD_ENV_JOB_START_EPOCH: "$(date +%s)",
        WALLTIME_GUARD_ENV_LIMIT_SECONDS: str(walltime_limit_seconds),
    }
 
def resolve_runtime_executable(executable_name: str) -> str:
    """!
    @brief Resolve solver/post executable path, preferring local sibling binaries.
    @param[in] executable_name Argument passed to `resolve_runtime_executable()`.
    @return Value returned by `resolve_runtime_executable()`.
    """
    local_candidate = os.path.join(INVOKED_SCRIPT_DIR, executable_name)
    if os.path.isfile(local_candidate):
        return os.path.abspath(local_candidate)
    return os.path.join(DEFAULT_BIN_DIR, executable_name)
 
 
#: Identity a native executable prints for `--version`: `<name> <release>+g<commit>[.dirty]`.
_BINARY_VERSION_PATTERN = re.compile(
    r"^(?P<name>\S+)\s+(?P<release>[^+\s]+)\+g(?P<commit>[0-9a-f]+)(?P<dirty>\.dirty)?\s*$"
)
 
 
def read_binary_build_identity(executable_path: str) -> dict:
    """!
    @brief Read the build identity a native executable was compiled with.
 
    @details The Makefile stamps the release, commit, and dirty state into the
             binaries, and they are written into every checkpoint manifest. Reading it
             back is what makes the run manifest's provenance a statement about the
             binary that ran rather than about whatever source happens to be checked
             out when the conductor is invoked.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return Identity mapping, or an `available: False` mapping when it cannot be read.
    """
    if not os.path.isfile(executable_path) or not os.access(executable_path, os.X_OK):
        return {"available": False, "reason": "not built", "path": executable_path}
    try:
        result = subprocess.run(
            [executable_path, "--version"], text=True, capture_output=True, timeout=30,
        )
    except (OSError, subprocess.SubprocessError) as exc:
        return {"available": False, "reason": str(exc), "path": executable_path}
    match = _BINARY_VERSION_PATTERN.match((result.stdout or "").strip())
    if not match:
        # A binary from before the identity flag existed, or a wrapper that prints
        # something else. Recorded as unavailable rather than guessed at.
        return {"available": False, "reason": "no build identity reported",
                "path": executable_path}
    return {
        "available": True,
        "path": executable_path,
        "release_version": match.group("release"),
        "git_commit": match.group("commit"),
        "dirty": bool(match.group("dirty")),
        "build_id": (
            f"{match.group('release')}+g{match.group('commit')}"
            f"{'.dirty' if match.group('dirty') else ''}"
        ),
    }
 
 
def runtime_build_identities() -> dict:
    """!
    @brief Read the build identity of every native executable a run would launch.
    @return Mapping of executable name to its identity, each carrying `matches_source`.
    """
    identities = {}
    source_commit = str(PICURV_BUILD.get("git_commit") or "")
    for name in ("simulator", "postprocessor"):
        identity = read_binary_build_identity(resolve_runtime_executable(name))
        if identity.get("available"):
            # The stamped commit is abbreviated, so compare on the prefix it carries.
            identity["matches_source"] = bool(
                source_commit
                and source_commit.startswith(identity["git_commit"])
                and identity["dirty"] == bool(PICURV_BUILD.get("dirty"))
            )
        identities[name] = identity
    return identities
 
 
def build_identity_problems(identities: dict, workspace_requirement=None) -> list:
    """!
    @brief Report every reason the active build identity is not internally coherent.
 
    @details The conductor, the simulator, and the postprocessor are three artifacts
             that must agree before a run's provenance means anything. This states the
             disagreements rather than printing them, so `version status` can exit on
             them while ordinary staging only warns.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @param[in] workspace_requirement Optional `software.picurv` constraint to check.
    @return Human-readable problem descriptions; empty when the build is coherent.
    """
    problems = []
    for name, identity in sorted(identities.items()):
        if not identity.get("available"):
            problems.append(
                f"{name}: no build identity available ({identity.get('reason', 'unknown')}); "
                "rebuild with 'make all'."
            )
        elif not identity.get("matches_source"):
            problems.append(
                f"{name}: built from {identity['build_id']}, but the active source is "
                f"{PICURV_BUILD['build_id']}; rebuild with 'make all'."
            )
    if workspace_requirement not in (None, ""):
        try:
            from packaging.specifiers import SpecifierSet
            from packaging.version import Version
            requirement_text = str(workspace_requirement).strip()
            if not any(token in requirement_text for token in "<>=!~"):
                requirement_text = "==" + requirement_text
            satisfied = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
        except Exception:
            problems.append(
                f"workspace: software.picurv={workspace_requirement!r} is not a valid "
                "version or version range."
            )
        else:
            if not satisfied:
                problems.append(
                    f"workspace: requires PICurv {workspace_requirement!r}, but the active "
                    f"release is {PICURV_RELEASE_VERSION}."
                )
    return problems
 
 
def warn_on_stale_runtime_binaries(identities: dict) -> list:
    """!
    @brief Report native executables whose build identity is not the active source.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @return Names of executables that disagree with the active source identity.
    """
    stale = [name for name, identity in sorted(identities.items())
             if identity.get("available") and not identity.get("matches_source")]
    for name in stale:
        print(
            f"[WARN] {name} was built from {identities[name]['build_id']}, but the active "
            f"source is {PICURV_BUILD['build_id']}. Checkpoints will record the binary's "
            "identity, not the source's. Run 'make all' to rebuild.",
            file=sys.stderr,
        )
    return stale
 
# Standardized error codes used for CLI/validation reporting.
ERROR_CODE_CLI_USAGE_INVALID = "CLI_USAGE_INVALID"
ERROR_CODE_CFG_MISSING_SECTION = "CFG_MISSING_SECTION"
ERROR_CODE_CFG_MISSING_KEY = "CFG_MISSING_KEY"
ERROR_CODE_CFG_INVALID_TYPE = "CFG_INVALID_TYPE"
ERROR_CODE_CFG_INVALID_VALUE = "CFG_INVALID_VALUE"
ERROR_CODE_CFG_FILE_NOT_FOUND = "CFG_FILE_NOT_FOUND"
ERROR_CODE_CFG_GRID_PARSE = "CFG_GRID_PARSE"
ERROR_CODE_CFG_INCONSISTENT_COMBO = "CFG_INCONSISTENT_COMBO"
ERROR_CODE_DEPENDENCY_MISSING = "DEPENDENCY_MISSING"
 
RESTART_RUN_DIR_REQUIRED_MESSAGE = (
    "--continue and --restart-from both require an existing run directory. "
    "Use --continue --run-dir <run_dir> to resume in place, or "
    "--restart-from <run_dir> to create a new run."
)
 
_ERROR_HINTS = {
    ERROR_CODE_CLI_USAGE_INVALID: "Run 'picurv <command> --help' to see valid argument combinations.",
    ERROR_CODE_CFG_MISSING_SECTION: "Add the missing section using examples/master_template/*.yml as reference.",
    ERROR_CODE_CFG_MISSING_KEY: "Add the missing key in the referenced YAML file.",
    ERROR_CODE_CFG_INVALID_TYPE: "Fix the value type to match the documented schema in docs/pages/14_Config_Contract.md.",
    ERROR_CODE_CFG_INVALID_VALUE: "Adjust the value to a supported range/enum from the config reference pages.",
    ERROR_CODE_CFG_FILE_NOT_FOUND: "Fix the path or create the missing file before running again.",
    ERROR_CODE_CFG_GRID_PARSE: "Validate grid file format and numeric payload (block count, dims, coordinates).",
    ERROR_CODE_CFG_INCONSISTENT_COMBO: "Fix conflicting options/keys so the configuration is internally consistent.",
    ERROR_CODE_DEPENDENCY_MISSING: "Install the named optional dependency for the Python interpreter used by picurv.",
}
 
 
def _sanitize_error_field(value) -> str:
    """!
    @brief Normalize error fields into a single-line string.
    @param[in] value Argument passed to `_sanitize_error_field()`.
    @return Value returned by `_sanitize_error_field()`.
    """
    if value is None:
        return "-"
    text = str(value).strip()
    if not text:
        return "-"
    return " ".join(text.splitlines())
 
 
def emit_structured_error(code: str, key: str = "-", file_path: str = "-",
                          message: str = "", hint: str = None, stream=None):
    """!
    @brief Emit one standardized error line for tooling and users.
    @param[in] code Argument passed to `emit_structured_error()`.
    @param[in] key Argument passed to `emit_structured_error()`.
    @param[in] file_path Argument passed to `emit_structured_error()`.
    @param[in] message Argument passed to `emit_structured_error()`.
    @param[in] hint Argument passed to `emit_structured_error()`.
    @param[in] stream Argument passed to `emit_structured_error()`.
    """
    if stream is None:
        stream = sys.stderr
    resolved_hint = hint if hint is not None else _ERROR_HINTS.get(code, "-")
    print(
        f"ERROR {_sanitize_error_field(code)} | "
        f"key={_sanitize_error_field(key)} | "
        f"file={_sanitize_error_field(file_path)} | "
        f"message={_sanitize_error_field(message)} | "
        f"hint={_sanitize_error_field(resolved_hint)}",
        file=stream,
    )
 
 
def fail_cli_usage(message: str, hint: str = None):
    """!
    @brief Emit a structured CLI usage error and exit with code 2.
    @param[in] message Argument passed to `fail_cli_usage()`.
    @param[in] hint Argument passed to `fail_cli_usage()`.
    """
    emit_structured_error(
        ERROR_CODE_CLI_USAGE_INVALID,
        key="-",
        file_path="-",
        message=message,
        hint=hint or _ERROR_HINTS[ERROR_CODE_CLI_USAGE_INVALID],
    )
    sys.exit(2)
 
 
def _split_error_file_and_message(raw_error: str):
    """!
    @brief Separate a validation error into its source-file and message fields when possible.
    @param[in] raw_error Validation error text, optionally beginning with a file path and colon.
    @return A pair containing the detected file path (or ``-``) and the message text.
    """
    text = str(raw_error).strip()
    match = re.match(r"^(?P<file>[^:]+):\s*(?P<msg>.+)$", text)
    if not match:
        return "-", text
    file_candidate = match.group("file").strip()
    msg = match.group("msg").strip()
    known_suffixes = (".yml", ".yaml", ".cfg", ".picgrid", ".control", ".run", ".txt")
    if "/" in file_candidate or file_candidate.endswith(known_suffixes):
        return file_candidate, msg
    return "-", text
 
 
def _extract_key_path(message: str) -> str:
    """!
    @brief Best-effort key-path extraction from free-form validation messages.
    @param[in] message Argument passed to `_extract_key_path()`.
    @return Value returned by `_extract_key_path()`.
    """
    dotted = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_\[\]-]+)+)\b", message)
    if dotted:
        return dotted.group(1)
 
    bracketed = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*\[[^\]]+\](?:\[[^\]]+\])*)\b", message)
    if bracketed:
        return bracketed.group(1)
 
    quoted = re.findall(r"'([A-Za-z0-9_.\[\]-]+)'", message)
    for token in quoted:
        if "." in token or "[" in token or token.isidentifier():
            return token
    return "-"
 
 
def _classify_error_code(message: str) -> str:
    """!
    @brief Map existing validation/error messages to the standardized code set.
    @param[in] message Argument passed to `_classify_error_code()`.
    @return Value returned by `_classify_error_code()`.
    """
    msg = message.lower()
    if "missing required section" in msg:
        return ERROR_CODE_CFG_MISSING_SECTION
    if "missing required key" in msg or "missing key" in msg:
        return ERROR_CODE_CFG_MISSING_KEY
    if "not found" in msg or "does not exist" in msg:
        return ERROR_CODE_CFG_FILE_NOT_FOUND
    if "invalid dimensions line" in msg or "invalid coordinate row" in msg or "grid file" in msg:
        return ERROR_CODE_CFG_GRID_PARSE
    if (
        "must both be periodic" in msg
        or "inconsistent periodicity" in msg
        or "mismatch" in msg
        or "requires --" in msg
        or "must be 1 (auto) or exactly" in msg
    ):
        return ERROR_CODE_CFG_INCONSISTENT_COMBO
    if (
        "must be a mapping" in msg
        or "must be a list" in msg
        or "must be a string" in msg
        or "must be a boolean" in msg
        or "must be either" in msg
    ):
        return ERROR_CODE_CFG_INVALID_TYPE
    if "unsupported key" in msg or "unsupported top-level section" in msg:
        return ERROR_CODE_CFG_INVALID_VALUE
    return ERROR_CODE_CFG_INVALID_VALUE
 
# ==============================================================================
# HELPER FUNCTIONS
# ==============================================================================
 
def read_yaml_file(filepath: str) -> dict:
    """!
    @brief Safely reads a YAML file and returns its content.
    @param[in] filepath Path to the YAML file.
    @return A dictionary containing the parsed YAML content.
    @throws SystemExit if the file is not found or cannot be parsed.
    """
    if not os.path.exists(filepath):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="-",
            file_path=filepath,
            message="Configuration file not found.",
        )
        sys.exit(1)
    try:
        with open(filepath, 'r') as f:
            return yaml.safe_load(f)
    except yaml.YAMLError as e:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="-",
            file_path=filepath,
            message=f"YAML parse error: {e}",
            hint="Fix YAML syntax/indentation and retry validation.",
        )
        sys.exit(1)
 
def write_yaml_file(filepath: str, data: dict):
    """!
    @brief Write YAML with stable ordering for generated study artifacts.
    @param[in] filepath Argument passed to `write_yaml_file()`.
    @param[in] data Argument passed to `write_yaml_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        yaml.safe_dump(data, f, sort_keys=False)
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 
def write_json_file(filepath: str, payload: dict):
    """!
    @brief Write JSON metadata/manifests with a stable, readable format.
    @param[in] filepath Argument passed to `write_json_file()`.
    @param[in] payload Argument passed to `write_json_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        json.dump(payload, f, indent=2, sort_keys=True)
        f.write("\n")
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 
 
def write_runtime_execution_file(filepath: str, template_source_path: str = None) -> str:
    """!
    @brief Write a default runtime execution config, copying a source template when available.
    @param[in] filepath Argument passed to `write_runtime_execution_file()`.
    @param[in] template_source_path Argument passed to `write_runtime_execution_file()`.
    @return Value returned by `write_runtime_execution_file()`.
    """
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
 
    if template_source_path and os.path.isfile(template_source_path):
        shutil.copy2(template_source_path, filepath)
        return filepath
 
    with open(filepath, "w", encoding="utf-8") as f:
        f.write(DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE)
    return filepath
 
 
def _launcher_arg_contains_whitespace(token) -> bool:
    """!
    @brief Return True when a launcher arg token contains embedded whitespace and should be split.
    @param[in] token Argument passed to `_launcher_arg_contains_whitespace()`.
    @return Value returned by `_launcher_arg_contains_whitespace()`.
    """
    return isinstance(token, str) and any(ch.isspace() for ch in token.strip())
 
 
def resolve_runtime_execution_seed_source(source_project_root: str) -> "str | None":
    """!
    @brief Prefer repo-local ignored runtime config, then tracked example, then built-in defaults.
    @param[in] source_project_root Argument passed to `resolve_runtime_execution_seed_source()`.
    @return Value returned by `resolve_runtime_execution_seed_source()`.
    """
    source_root_abs = os.path.abspath(source_project_root)
    repo_local_runtime = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.isfile(repo_local_runtime):
        return repo_local_runtime
 
    tracked_example = os.path.join(
        source_root_abs,
        "config",
        "runtime",
        RUNTIME_EXECUTION_EXAMPLE_FILENAME,
    )
    if os.path.isfile(tracked_example):
        return tracked_example
    return None
 
 
def ensure_case_runtime_execution_config(case_dir: str, source_project_root: str, overwrite: bool = False) -> dict:
    """!
    @brief Create case-local runtime execution config if missing, seeded from repo-local config when available.
    @param[in] case_dir Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] source_project_root Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] overwrite Argument passed to `ensure_case_runtime_execution_config()`.
    @return Value returned by `ensure_case_runtime_execution_config()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    dest_path = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.exists(dest_path) and not overwrite:
        return {
            "path": dest_path,
            "created": False,
            "seed_source": None,
        }
 
    seed_source = resolve_runtime_execution_seed_source(source_project_root)
    write_runtime_execution_file(dest_path, seed_source)
    return {
        "path": dest_path,
        "created": True,
        "seed_source": seed_source,
    }
 
 
def is_project_root(candidate: str) -> bool:
    """!
    @brief Return True when a directory looks like the PICurv source repository root.
    @param[in] candidate Argument passed to `is_project_root()`.
    @return Value returned by `is_project_root()`.
    """
    if not candidate:
        return False
    candidate_abs = os.path.abspath(candidate)
    return (
        os.path.isfile(os.path.join(candidate_abs, "Makefile"))
        and os.path.isdir(os.path.join(candidate_abs, "src"))
        and os.path.isdir(os.path.join(candidate_abs, "include"))
        and os.path.isdir(os.path.join(candidate_abs, "picurv_cli"))
    )
 
 
def _iter_parent_dirs(start_path: str):
    """!
    @brief Yield a path and all of its parents up to filesystem root.
    @param[in] start_path Argument passed to `_iter_parent_dirs()`.
    """
    current = os.path.abspath(start_path)
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        yield current
        parent = os.path.dirname(current)
        if parent == current:
            break
        current = parent
 
 
def find_project_root_upwards(start_path: str):
    """!
    @brief Search upward from an anchor and return the first matching project root.
    @param[in] start_path Argument passed to `find_project_root_upwards()`.
    @return Value returned by `find_project_root_upwards()`.
    """
    if not start_path:
        return None
    for directory in _iter_parent_dirs(start_path):
        if is_project_root(directory):
            return directory
    return None
 
 
def discover_local_project_root(*extra_anchors):
    """!
    @brief Best-effort source repo discovery from runtime anchors.
    @param[in] extra_anchors Argument passed to `discover_local_project_root()`.
    @return Value returned by `discover_local_project_root()`.
    """
    anchors = list(extra_anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR, SCRIPT_PATH, PROJECT_ROOT]
    seen = set()
    for anchor in anchors:
        if not anchor:
            continue
        anchor_abs = os.path.abspath(anchor)
        if anchor_abs in seen:
            continue
        seen.add(anchor_abs)
        project_root = find_project_root_upwards(anchor_abs)
        if project_root:
            return project_root
    return None
 
 
def find_case_origin_metadata_file(case_dir_hint: str = None):
    """!
    @brief Find the nearest case-origin metadata file from known runtime anchors.
    @param[in] case_dir_hint Argument passed to `find_case_origin_metadata_file()`.
    @return Value returned by `find_case_origin_metadata_file()`.
    """
    search_roots = []
    for candidate in (case_dir_hint, os.getcwd(), INVOKED_SCRIPT_DIR):
        if not candidate:
            continue
        abs_candidate = os.path.abspath(candidate)
        if abs_candidate not in search_roots:
            search_roots.append(abs_candidate)
 
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            metadata_path = os.path.join(directory, CASE_ORIGIN_METADATA_FILENAME)
            if os.path.isfile(metadata_path):
                return metadata_path
    return None
 
 
def load_case_origin_metadata(case_dir_hint: str = None):
    """!
    @brief Load case-origin metadata if present, returning (case_dir, metadata_path, payload).
    @param[in] case_dir_hint Argument passed to `load_case_origin_metadata()`.
    @return Value returned by `load_case_origin_metadata()`.
    """
    metadata_path = find_case_origin_metadata_file(case_dir_hint)
    if not metadata_path:
        return None, None, None
    try:
        with open(metadata_path, "r", encoding="utf-8") as f:
            payload = json.load(f)
        if not isinstance(payload, dict):
            raise ValueError("Case origin metadata must be a JSON object.")
    except Exception as exc:
        raise ValueError(f"Failed to read case origin metadata at {metadata_path}: {exc}") from exc
    return os.path.dirname(metadata_path), metadata_path, payload
 
 
def find_runtime_execution_config_file(*anchors):
    """!
    @brief Find the nearest optional execution config from runtime/case anchors.
    @param[in] anchors Argument passed to `find_runtime_execution_config_file()`.
    @return Value returned by `find_runtime_execution_config_file()`.
    """
    seen = set()
    search_roots = []
    for candidate in list(anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR]:
        if not candidate:
            continue
        current = os.path.abspath(candidate)
        if os.path.isfile(current):
            current = os.path.dirname(current)
        if current in seen:
            continue
        seen.add(current)
        search_roots.append(current)
 
    seen_dirs = set()
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            if directory in seen_dirs:
                continue
            seen_dirs.add(directory)
            for filename in RUNTIME_EXECUTION_CONFIG_FILENAMES:
                config_path = os.path.join(directory, filename)
                if os.path.isfile(config_path):
                    return config_path
    return None
 
 
def _normalize_execution_override_section(payload: dict, section_name: str, config_path: str, config_label: str) -> dict:
    """!
    @brief Validate one execution override section while preserving missing-vs-empty semantics.
    @param[in] payload Argument passed to `_normalize_execution_override_section()`.
    @param[in] section_name Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_path Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_label Argument passed to `_normalize_execution_override_section()`.
    @return Value returned by `_normalize_execution_override_section()`.
    """
    section = payload.get(section_name)
    if section is None:
        return {"launcher": None, "launcher_args": None}
    if not isinstance(section, dict):
        raise ValueError(f"{config_label} at {config_path}: {section_name} must be a mapping.")
 
    launcher = section.get("launcher")
    if launcher is not None and not isinstance(launcher, str):
        raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher must be a string.")
 
    launcher_args = None
    if "launcher_args" in section:
        launcher_args = section.get("launcher_args", [])
        if launcher_args is None:
            launcher_args = []
        if not isinstance(launcher_args, list):
            raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher_args must be a list.")
        for i, token in enumerate(launcher_args):
            if not isinstance(token, (str, int, float)):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a scalar CLI token."
                )
            if _launcher_arg_contains_whitespace(token):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a single CLI token; split whitespace-separated arguments into separate list items."
                )
        launcher_args = [str(x) for x in launcher_args]
 
    return {
        "launcher": launcher,
        "launcher_args": launcher_args,
    }
 
 
def load_runtime_execution_config(config_search_anchor: str = None, extra_search_anchors=None):
    """!
    @brief Load optional shared execution launcher config from the nearest runtime config file.
    @param[in] config_search_anchor Argument passed to `load_runtime_execution_config()`.
    @param[in] extra_search_anchors Argument passed to `load_runtime_execution_config()`.
    @return Value returned by `load_runtime_execution_config()`.
    """
    anchors = []
    if config_search_anchor is not None:
        anchors.append(config_search_anchor)
    if extra_search_anchors:
        anchors.extend(extra_search_anchors)
 
    config_path = find_runtime_execution_config_file(*anchors)
    if not config_path:
        return None, {}
 
    try:
        with open(config_path, "r", encoding="utf-8") as f:
            payload = yaml.safe_load(f) or {}
    except yaml.YAMLError as exc:
        raise ValueError(f"{os.path.basename(config_path)} YAML parse error at {config_path}: {exc}") from exc
 
    if not isinstance(payload, dict):
        raise ValueError(f"{os.path.basename(config_path)} at {config_path} must be a YAML mapping.")
 
    return config_path, {
        "default_execution": _normalize_execution_override_section(
            payload,
            "default_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "local_execution": _normalize_execution_override_section(
            payload,
            "local_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "cluster_execution": _normalize_execution_override_section(
            payload,
            "cluster_execution",
            config_path,
            os.path.basename(config_path),
        ),
    }
 
 
def merge_execution_overrides(base: "dict | None", override: "dict | None") -> dict:
    """!
    @brief Merge execution overrides, letting explicit override values win key-by-key.
    @param[in] base Argument passed to `merge_execution_overrides()`.
    @param[in] override Argument passed to `merge_execution_overrides()`.
    @return Value returned by `merge_execution_overrides()`.
    """
    base = base or {}
    override = override or {}
 
    launcher = override.get("launcher")
    if launcher is None:
        launcher = base.get("launcher")
 
    launcher_args = override.get("launcher_args")
    if launcher_args is None:
        launcher_args = base.get("launcher_args")
 
    return {
        "launcher": launcher,
        "launcher_args": None if launcher_args is None else [str(x) for x in launcher_args],
    }
 
 
def resolve_runtime_execution_context(runtime_execution_cfg: dict, context: str) -> dict:
    """!
    @brief Resolve default plus context-specific execution overrides.
    @param[in] runtime_execution_cfg Argument passed to `resolve_runtime_execution_context()`.
    @param[in] context Argument passed to `resolve_runtime_execution_context()`.
    @return Value returned by `resolve_runtime_execution_context()`.
    """
    if context not in LAUNCH_MODES:
        raise ValueError(f"Unsupported execution context '{context}'.")
    return merge_execution_overrides(
        runtime_execution_cfg.get("default_execution"),
        runtime_execution_cfg.get(f"{context}_execution"),
    )
 
 
def get_git_commit(repo_root: str = None) -> str:
    """!
    @brief Best-effort git commit lookup for run/study manifests and case metadata.
    @param[in] repo_root Argument passed to `get_git_commit()`.
    @return Value returned by `get_git_commit()`.
    """
    cwd = repo_root or PROJECT_ROOT
    try:
        result = subprocess.run(
            ["git", "rev-parse", "HEAD"],
            cwd=cwd,
            text=True,
            capture_output=True,
            check=False
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None
 
 
def write_case_origin_metadata(case_dir: str, source_project_root: str, template_name: str = None,
                               existing: dict = None, template_managed_files=None):
    """!
    @brief Create or refresh case-origin metadata for repo-aware case maintenance commands.
    @param[in] case_dir Argument passed to `write_case_origin_metadata()`.
    @param[in] source_project_root Argument passed to `write_case_origin_metadata()`.
    @param[in] template_name Argument passed to `write_case_origin_metadata()`.
    @param[in] existing Argument passed to `write_case_origin_metadata()`.
    @param[in] template_managed_files Argument passed to `write_case_origin_metadata()`.
    @return Value returned by `write_case_origin_metadata()`.
    """
    payload = dict(existing or {})
    if "initialized_at" not in payload:
        payload["initialized_at"] = datetime.now().isoformat()
    payload["source_repo_root"] = os.path.abspath(source_project_root)
    if template_name:
        payload["template_name"] = template_name
    if template_managed_files is not None:
        payload["template_managed_files"] = sorted(set(str(p) for p in template_managed_files))
    payload["last_known_source_git_commit"] = get_git_commit(source_project_root)
    metadata_path = os.path.join(os.path.abspath(case_dir), CASE_ORIGIN_METADATA_FILENAME)
    write_json_file(metadata_path, payload)
    return metadata_path, payload
 
 
def make_args_include_explicit_goal(make_args: "list[str]") -> bool:
    """!
    @brief Return True when make args contain an explicit target rather than only options/assignments.
    @param[in] make_args Argument passed to `make_args_include_explicit_goal()`.
    @return Value returned by `make_args_include_explicit_goal()`.
    """
    if not make_args:
        return False
 
    options_with_value = {
        "-C", "-f", "-I", "-j", "-l", "-o", "-W",
        "--directory", "--file", "--makefile", "--include-dir", "--jobs",
        "--load-average", "--max-load", "--old-file", "--assume-old",
        "--what-if", "--new-file", "--assume-new",
    }
    assignment_pattern = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*[:+?]?=.*$")
 
    skip_next = False
    for token in make_args:
        if skip_next:
            skip_next = False
            continue
        if token in options_with_value:
            skip_next = True
            continue
        if token.startswith("-"):
            continue
        if assignment_pattern.match(token):
            continue
        return True
    return False
 
 
def resolve_case_origin_context(case_dir_hint: str = None, source_root_override: str = None, template_name_override: str = None):
    """!
    @brief Resolve case directory, source repo root, and optional template metadata.
    @param[in] case_dir_hint Argument passed to `resolve_case_origin_context()`.
    @param[in] source_root_override Argument passed to `resolve_case_origin_context()`.
    @param[in] template_name_override Argument passed to `resolve_case_origin_context()`.
    @return Value returned by `resolve_case_origin_context()`.
    """
    metadata_case_dir, metadata_path, metadata = load_case_origin_metadata(case_dir_hint)
 
    if metadata_case_dir:
        case_dir = metadata_case_dir
    else:
        case_dir = os.path.abspath(case_dir_hint or os.getcwd())
 
    source_project_root = source_root_override
    if source_project_root:
        source_project_root = os.path.abspath(source_project_root)
    elif isinstance(metadata, dict) and isinstance(metadata.get("source_repo_root"), str):
        source_project_root = os.path.abspath(metadata["source_repo_root"])
    else:
        source_project_root = discover_local_project_root(case_dir)
 
    template_name = template_name_override
    if not template_name and isinstance(metadata, dict):
        template_name = metadata.get("template_name")
 
    return {
        "case_dir": case_dir,
        "metadata_path": metadata_path,
        "metadata": metadata or {},
        "source_project_root": source_project_root,
        "template_name": template_name,
    }
 
 
def require_project_root(candidate: str, purpose: str):
    """!
    @brief Validate that a source repo root was resolved and is structurally valid.
    @param[in] candidate Argument passed to `require_project_root()`.
    @param[in] purpose Argument passed to `require_project_root()`.
    @return Value returned by `require_project_root()`.
    """
    if not candidate:
        raise ValueError(
            f"Could not determine the PICurv source repository for {purpose}. "
            "Run this command from an initialized case directory or pass --source-root."
        )
    candidate_abs = os.path.abspath(candidate)
    if not is_project_root(candidate_abs):
        raise ValueError(
            f"Resolved source repository for {purpose} is not a valid PICurv root: {candidate_abs}"
        )
    return candidate_abs
 
 
def require_existing_case_dir(case_dir: str, purpose: str, source_project_root: str = None):
    """!
    @brief Validate that a target case directory exists and is not the source repo root.
    @param[in] case_dir Argument passed to `require_existing_case_dir()`.
    @param[in] purpose Argument passed to `require_existing_case_dir()`.
    @param[in] source_project_root Argument passed to `require_existing_case_dir()`.
    @return Value returned by `require_existing_case_dir()`.
    """
    if not case_dir:
        raise ValueError(f"Could not determine the case directory for {purpose}. Pass --case-dir.")
    case_dir_abs = os.path.abspath(case_dir)
    if not os.path.isdir(case_dir_abs):
        raise ValueError(f"Case directory for {purpose} does not exist: {case_dir_abs}")
    if source_project_root and os.path.abspath(source_project_root) == case_dir_abs:
        raise ValueError(
            f"Refusing to run {purpose} against the source repository root itself: {case_dir_abs}"
        )
    return case_dir_abs
 
 
def resolve_template_directory(source_project_root: str, template_name: str):
    """!
    @brief Resolve an example template directory inside the source repository.
    @param[in] source_project_root Argument passed to `resolve_template_directory()`.
    @param[in] template_name Argument passed to `resolve_template_directory()`.
    @return Value returned by `resolve_template_directory()`.
    """
    if not template_name:
        raise ValueError(
            "Template name is required for config sync. Re-run with --template-name or from a case initialized by current picurv."
        )
    template_dir = os.path.join(source_project_root, "examples", template_name)
    if not os.path.isdir(template_dir):
        raise ValueError(f"Case template '{template_name}' not found at '{template_dir}'")
    return template_dir
 
 
def list_template_relative_files(template_dir: str, excluded_rel_paths=None):
    """!
    @brief List all files in a template directory as case-relative paths.
    @param[in] template_dir Argument passed to `list_template_relative_files()`.
    @param[in] excluded_rel_paths Argument passed to `list_template_relative_files()`.
    @return Value returned by `list_template_relative_files()`.
    """
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
    excluded = set(excluded_rel_paths or [])
    relative_paths = []
    for root, _, files in os.walk(template_dir_abs):
        rel_root = os.path.relpath(root, template_dir_abs)
        for filename in sorted(files):
            rel_path = filename if rel_root == "." else os.path.join(rel_root, filename)
            if rel_path in excluded:
                continue
            relative_paths.append(rel_path)
    return relative_paths
 
 
def list_source_binaries(source_project_root: str):
    """!
    @brief List binary artifacts currently available in the source repo bin directory.
    @param[in] source_project_root Argument passed to `list_source_binaries()`.
    @return Value returned by `list_source_binaries()`.
    """
    source_bin_dir = os.path.join(os.path.abspath(source_project_root), "bin")
    if not os.path.isdir(source_bin_dir):
        raise ValueError(f"Source bin directory not found: {source_bin_dir}. Run 'picurv build' first.")
    binaries = sorted(
        f for f in os.listdir(source_bin_dir)
        if os.path.isfile(os.path.join(source_bin_dir, f)) and f != "picurv"
    )
    if not binaries:
        raise ValueError(f"Source bin directory contains no files: {source_bin_dir}")
    return source_bin_dir, binaries
 
 
def sync_case_binaries(case_dir: str, source_project_root: str):
    """!
    @brief Copy current source-repo binaries into a case directory for version-pinning.
    @param[in] case_dir Argument passed to `sync_case_binaries()`.
    @param[in] source_project_root Argument passed to `sync_case_binaries()`.
    @return Value returned by `sync_case_binaries()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    os.makedirs(case_dir_abs, exist_ok=True)
    source_bin_dir, binaries = list_source_binaries(source_project_root)
    copied = []
    for binary_name in binaries:
        source_path = os.path.join(source_bin_dir, binary_name)
        dest_path = os.path.join(case_dir_abs, binary_name)
        shutil.copy2(source_path, dest_path)
        copied.append(dest_path)
    return copied
 
 
def sync_case_template_files(case_dir: str, template_dir: str, overwrite: bool = False,
                             prune: bool = False, managed_rel_paths=None):
    """!
    @brief Sync template files into a case directory, preserving modified files unless overwrite is requested.
    @param[in] case_dir Argument passed to `sync_case_template_files()`.
    @param[in] template_dir Argument passed to `sync_case_template_files()`.
    @param[in] overwrite Argument passed to `sync_case_template_files()`.
    @param[in] prune Argument passed to `sync_case_template_files()`.
    @param[in] managed_rel_paths Argument passed to `sync_case_template_files()`.
    @return Value returned by `sync_case_template_files()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
 
    summary = {
        "copied": [],
        "overwritten": [],
        "skipped_modified": [],
        "unchanged": [],
        "pruned": [],
        "prune_requested_without_tracking": False,
    }
    excluded_rel_paths = {RUNTIME_EXECUTION_EXAMPLE_FILENAME}
    current_template_files = list_template_relative_files(
        template_dir_abs,
        excluded_rel_paths=excluded_rel_paths,
    )
    current_template_set = set(current_template_files)
 
    for root, _, files in os.walk(template_dir_abs):
        rel_root = os.path.relpath(root, template_dir_abs)
        for filename in sorted(files):
            src_path = os.path.join(root, filename)
            rel_path = filename if rel_root == "." else os.path.join(rel_root, filename)
            if rel_path in excluded_rel_paths:
                continue
            dest_path = os.path.join(case_dir_abs, rel_path)
            os.makedirs(os.path.dirname(dest_path), exist_ok=True)
 
            if not os.path.exists(dest_path):
                shutil.copy2(src_path, dest_path)
                summary["copied"].append(dest_path)
                continue
 
            if filecmp.cmp(src_path, dest_path, shallow=False):
                summary["unchanged"].append(dest_path)
                continue
 
            if overwrite:
                shutil.copy2(src_path, dest_path)
                summary["overwritten"].append(dest_path)
            else:
                summary["skipped_modified"].append(dest_path)
 
    managed_set = set(managed_rel_paths or [])
    if prune:
        if not managed_set:
            summary["prune_requested_without_tracking"] = True
        for rel_path in sorted(managed_set - current_template_set):
            dest_path = os.path.join(case_dir_abs, rel_path)
            if os.path.isfile(dest_path):
                os.remove(dest_path)
                summary["pruned"].append(dest_path)
 
    summary["template_managed_files"] = current_template_files
    return summary
 
 
def compute_case_source_status(case_dir: str, source_project_root: str, template_name: str = None, metadata: dict = None):
    """!
    @brief Compute source/case drift across commits, binaries, and template-managed files.
    @param[in] case_dir Argument passed to `compute_case_source_status()`.
    @param[in] source_project_root Argument passed to `compute_case_source_status()`.
    @param[in] template_name Argument passed to `compute_case_source_status()`.
    @param[in] metadata Argument passed to `compute_case_source_status()`.
    @return Value returned by `compute_case_source_status()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    source_root_abs = os.path.abspath(source_project_root)
    metadata = metadata or {}
    status = {
        "case_dir": case_dir_abs,
        "source_repo_root": source_root_abs,
        "metadata_present": bool(metadata),
        "template_name": template_name,
        "last_known_source_git_commit": metadata.get("last_known_source_git_commit"),
        "current_source_git_commit": get_git_commit(source_root_abs),
    }
    status["source_commit_changed"] = (
        bool(status["last_known_source_git_commit"])
        and bool(status["current_source_git_commit"])
        and status["last_known_source_git_commit"] != status["current_source_git_commit"]
    )
 
    binary_status = {
        "source_bin_present": False,
        "source_bin_missing": [],
        "case_bin_missing": [],
        "case_bin_different": [],
        "case_bin_current": [],
    }
    try:
        source_bin_dir, binaries = list_source_binaries(source_root_abs)
        binary_status["source_bin_present"] = True
        for binary_name in binaries:
            source_path = os.path.join(source_bin_dir, binary_name)
            case_path = os.path.join(case_dir_abs, binary_name)
            if not os.path.isfile(case_path):
                binary_status["case_bin_missing"].append(binary_name)
            elif filecmp.cmp(source_path, case_path, shallow=False):
                binary_status["case_bin_current"].append(binary_name)
            else:
                binary_status["case_bin_different"].append(binary_name)
    except ValueError as exc:
        binary_status["source_bin_missing"].append(str(exc))
    status["binaries"] = binary_status
 
    config_status = {
        "template_available": False,
        "template_files": [],
        "case_missing_files": [],
        "case_modified_files": [],
        "case_current_files": [],
        "template_removed_since_last_sync": [],
        "tracking_available": isinstance(metadata.get("template_managed_files"), list),
    }
    if template_name:
        try:
            template_dir = resolve_template_directory(source_root_abs, template_name)
            template_files = list_template_relative_files(
                template_dir,
                excluded_rel_paths={RUNTIME_EXECUTION_EXAMPLE_FILENAME},
            )
            config_status["template_available"] = True
            config_status["template_files"] = template_files
            for rel_path in template_files:
                src_path = os.path.join(template_dir, rel_path)
                case_path = os.path.join(case_dir_abs, rel_path)
                if not os.path.isfile(case_path):
                    config_status["case_missing_files"].append(rel_path)
                elif filecmp.cmp(src_path, case_path, shallow=False):
                    config_status["case_current_files"].append(rel_path)
                else:
                    config_status["case_modified_files"].append(rel_path)
            managed_files = metadata.get("template_managed_files")
            if isinstance(managed_files, list):
                config_status["template_removed_since_last_sync"] = sorted(set(managed_files) - set(template_files))
        except ValueError:
            pass
    status["config"] = config_status
 
    case_runtime_cfg = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    repo_runtime_seed = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    runtime_status = {
        "case_config_present": os.path.isfile(case_runtime_cfg),
        "repo_seed_present": os.path.isfile(repo_runtime_seed),
        "case_matches_repo_seed": False,
    }
    if runtime_status["case_config_present"] and runtime_status["repo_seed_present"]:
        runtime_status["case_matches_repo_seed"] = filecmp.cmp(
            case_runtime_cfg,
            repo_runtime_seed,
            shallow=False,
        )
    status["runtime_execution"] = runtime_status
    return status
 
 
def print_case_source_status(status: dict):
    """!
    @brief Render human-readable source/case drift details.
    @param[in] status Argument passed to `print_case_source_status()`.
    """
    print(f"[INFO] Case directory      : {status['case_dir']}")
    print(f"[INFO] Source repo        : {status['source_repo_root']}")
    print(f"[INFO] Template           : {status.get('template_name') or '(unknown)'}")
    if status.get("last_known_source_git_commit"):
        print(f"[INFO] Last synced commit : {status['last_known_source_git_commit']}")
    if status.get("current_source_git_commit"):
        print(f"[INFO] Current src commit : {status['current_source_git_commit']}")
    print(f"[INFO] Source changed     : {'yes' if status.get('source_commit_changed') else 'no'}")
 
    binaries = status["binaries"]
    if binaries["source_bin_present"]:
        print(
            f"[INFO] Binaries          : current={len(binaries['case_bin_current'])} "
            f"changed={len(binaries['case_bin_different'])} missing={len(binaries['case_bin_missing'])}"
        )
    else:
        print("[INFO] Binaries          : source bin/ unavailable")
 
    config = status["config"]
    if config["template_available"]:
        print(
            f"[INFO] Template files    : current={len(config['case_current_files'])} "
            f"modified={len(config['case_modified_files'])} missing={len(config['case_missing_files'])}"
        )
        if config["tracking_available"]:
            print(f"[INFO] Prune candidates  : {len(config['template_removed_since_last_sync'])}")
        else:
            print("[INFO] Prune candidates  : tracking unavailable")
    elif status.get("template_name"):
        print("[INFO] Template files    : template unavailable in source repo")
 
    runtime_cfg = status.get("runtime_execution", {})
    print(
        f"[INFO] Runtime config    : case={'yes' if runtime_cfg.get('case_config_present') else 'no'} "
        f"repo-seed={'yes' if runtime_cfg.get('repo_seed_present') else 'no'} "
        f"matches-repo-seed={'yes' if runtime_cfg.get('case_matches_repo_seed') else 'no'}"
    )
 
 
def status_source_command(args):
    """!
    @brief Report source/case drift for an initialized case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "status-source")
        case_dir = require_existing_case_dir(context["case_dir"], "status-source", source_project_root)
        status = compute_case_source_status(
            case_dir,
            source_project_root,
            template_name=context.get("template_name"),
            metadata=context.get("metadata"),
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(status, indent=2, sort_keys=True))
        return
    print_case_source_status(status)
 
def resolve_path(anchor_file: str, candidate: str) -> str:
    """!
    @brief Resolve a potentially relative path against a source YAML file path.
    @param[in] anchor_file Argument passed to `resolve_path()`.
    @param[in] candidate Argument passed to `resolve_path()`.
    @return Value returned by `resolve_path()`.
    """
    if candidate is None:
        return None
    return resolve_workspace_path(anchor_file, candidate)
 
 
POST_RUN_CONTROL_ALIASES = {
    "start_step": ("start_step", "startTime"),
    "end_step": ("end_step", "endTime"),
    "step_interval": ("step_interval", "timeStep"),
}
 
 
GRID_GENERATOR_HYPHEN_KEY_HINTS = {
    "config-file": "config_file",
    "grid-type": "grid_type",
    "cli-args": "cli_args",
}
 
#: Generator keys that used to name their own output destinations. PICurv owns where
#: generated artifacts go, so accepting these would let a configuration file create a
#: competing output directory outside the asset store.
RETIRED_GENERATOR_DESTINATION_KEYS = ("output_file", "stats_file", "vts_file",
                                      "output-file", "stats-file", "vts-file")
 
 
def _mapping_value_with_aliases(mapping: dict, *keys, default=None):
    """!
    @brief Return the first defined value from a mapping across alias keys.
    @param[in] mapping Argument passed to `_mapping_value_with_aliases()`.
    @param[in] default Argument passed to `_mapping_value_with_aliases()`.
    @param[in] keys Argument passed to `_mapping_value_with_aliases()`.
    @return Value returned by `_mapping_value_with_aliases()`.
    """
    if not isinstance(mapping, dict):
        return default
    for key in keys:
        if key in mapping:
            return mapping.get(key)
    return default
 
 
def get_post_run_control_value(post_cfg: dict, canonical_key: str, default=None):
    """!
    @brief Resolve post run_control values with backwards-compatible legacy aliases.
    @param[in] post_cfg Argument passed to `get_post_run_control_value()`.
    @param[in] canonical_key Argument passed to `get_post_run_control_value()`.
    @param[in] default Argument passed to `get_post_run_control_value()`.
    @return Value returned by `get_post_run_control_value()`.
    """
    aliases = POST_RUN_CONTROL_ALIASES.get(canonical_key, (canonical_key,))
    rc = post_cfg.get("run_control", {})
    return _mapping_value_with_aliases(rc, *aliases, default=default)
 
 
def warn_on_grid_generator_hyphen_keys(generator: dict, case_path: str, warnings: list) -> None:
    """!
    @brief Warn when grid.generator uses unsupported hyphenated wrapper keys.
    @param[in] generator grid.generator mapping from case.yml.
    @param[in] case_path Case file path for diagnostics.
    @param[in,out] warnings Warning list to append to.
    """
    if not isinstance(generator, dict):
        return
    for bad_key, expected_key in GRID_GENERATOR_HYPHEN_KEY_HINTS.items():
        if bad_key in generator and bad_key != expected_key:
            warnings.append(
                f"{case_path}: grid.generator.{bad_key} is ignored; use grid.generator.{expected_key}."
            )
 
 
def reject_generator_destination_keys(generator, case_path: str, label: str) -> list:
    """!
    @brief Reject generator settings that try to choose their own output destination.
    @param[in] generator Generator mapping from the case configuration.
    @param[in] case_path Case file path for diagnostics.
    @param[in] label Dotted configuration path being checked, for the message.
    @return List of error strings.
    """
    if not isinstance(generator, dict):
        return []
    return [
        f"  {case_path}: '{label}.{key}' is no longer accepted. PICurv chooses where "
        "generated artifacts go; the published asset carries the payload, its preview, "
        "and its validation record."
        for key in RETIRED_GENERATOR_DESTINATION_KEYS if key in generator
    ]
 
 
def get_post_source_data(post_cfg: dict):
    """!
    @brief Return source_data as a mapping when valid, else an empty mapping.
    @param[in] post_cfg Argument passed to `get_post_source_data()`.
    @return Value returned by `get_post_source_data()`.
    """
    source_cfg = post_cfg.get("source_data", {})
    if isinstance(source_cfg, dict):
        return source_cfg
    return {}
 
 
def get_post_source_directory_template(post_cfg: dict, default: str = "<solver_output_dir>") -> str:
    """!
    @brief Resolve the source directory template from source_data with a safe default.
    @param[in] post_cfg Argument passed to `get_post_source_directory_template()`.
    @param[in] default Argument passed to `get_post_source_directory_template()`.
    @return Value returned by `get_post_source_directory_template()`.
    """
    return get_post_source_data(post_cfg).get("directory", default)
 
 
def get_post_input_extensions(post_cfg: dict):
    """!
    @brief Return post input_extensions, preferring io.* and tolerating legacy source_data.* placement.
    @param[in] post_cfg Argument passed to `get_post_input_extensions()`.
    @return Value returned by `get_post_input_extensions()`.
    """
    io_cfg = post_cfg.get("io", {})
    io_ext = io_cfg.get("input_extensions") if isinstance(io_cfg, dict) else None
    if isinstance(io_ext, dict):
        return io_ext
 
    source_ext = get_post_source_data(post_cfg).get("input_extensions")
    if isinstance(source_ext, dict):
        return source_ext
 
    return {}
 
 
def get_post_statistics_task_tokens(post_cfg: dict):
    """!
    @brief Return normalized statistics pipeline tokens that will be written into post.run.
    @param[in] post_cfg Argument passed to `get_post_statistics_task_tokens()`.
    @return Value returned by `get_post_statistics_task_tokens()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    stats_entries = []
    if isinstance(stats_cfg, list):
        stats_entries = stats_cfg
    elif isinstance(stats_cfg, dict):
        stats_entries = stats_cfg.get("tasks", [])
 
    tokens = []
    for entry in stats_entries:
        if isinstance(entry, str):
            task_name = entry
        elif isinstance(entry, dict):
            task_name = entry.get("task")
        else:
            continue
        try:
            tokens.append(normalize_statistics_task(task_name))
        except ValueError:
            continue
    return tokens
 
 
def get_monitor_output_directory(monitor_cfg: dict, default: str = "output") -> str:
    """!
    @brief Resolve the solver output root from monitor.yml, preserving the default layout.
    @param[in] monitor_cfg Argument passed to `get_monitor_output_directory()`.
    @param[in] default Argument passed to `get_monitor_output_directory()`.
    @return Value returned by `get_monitor_output_directory()`.
    """
    del monitor_cfg, default
    return CANONICAL_RUN_PATHS["output"]
 
 
def get_post_statistics_output_prefix(post_cfg: dict, default: str = "Stats") -> str:
    """!
    @brief Resolve the statistics CSV prefix, preserving legacy top-level override support.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_prefix()`.
    @param[in] default Argument passed to `get_post_statistics_output_prefix()`.
    @return Value returned by `get_post_statistics_output_prefix()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        prefix = stats_cfg.get("output_prefix")
        if isinstance(prefix, str) and prefix.strip():
            return prefix.strip()
 
    legacy_prefix = post_cfg.get("statistics_output_prefix")
    if isinstance(legacy_prefix, str) and legacy_prefix.strip():
        return legacy_prefix.strip()
 
    return default
 
 
def resolve_post_statistics_output_prefix(post_cfg: dict, monitor_cfg=None, default: str = "Stats") -> str:
    """!
    @brief Resolve the runtime statistics prefix, routing bare basenames under the monitor output root.
    @param[in] post_cfg Argument passed to `resolve_post_statistics_output_prefix()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @param[in] default Argument passed to `resolve_post_statistics_output_prefix()`.
    @return Value returned by `resolve_post_statistics_output_prefix()`.
    """
    prefix = get_post_statistics_output_prefix(post_cfg, default=default).strip()
    if os.path.isabs(prefix):
        return prefix
 
    if os.path.dirname(prefix):
        return prefix
 
    del monitor_cfg
    return os.path.join(CANONICAL_RUN_PATHS["statistics"], prefix)
 
 
def get_post_statistics_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None):
    """!
    @brief Predict statistics CSV output paths relative to the postprocessor runtime cwd.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] run_dir Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @return Value returned by `get_post_statistics_output_artifacts()`.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    token_to_suffix = {
        "ComputeMSD": "_msd.csv",
    }
    prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    if os.path.isabs(prefix):
        base_path = os.path.abspath(prefix)
    else:
        base_path = os.path.abspath(os.path.join(run_dir, prefix))
 
    output_paths = []
    for token in get_post_statistics_task_tokens(post_cfg):
        suffix = token_to_suffix.get(token)
        if suffix:
            output_paths.append(base_path + suffix)
 
    return list(dict.fromkeys(output_paths))
 
 
#: Spectra tasks a post recipe may request, with the preconditions each needs.
#:
#: `requires_uniform_cartesian` is checked against the staged PICGRID and
#: `requires_periodic_geometric` against the resolved boundary conditions, both
#: before any field is read. A task whose preconditions the case cannot meet is
#: refused at validation rather than producing a curve with no meaning: a spectrum
#: needs the transform direction to be uniformly spaced, periodic, and statistically
#: homogeneous, and a curvilinear or wall-bounded geometry supplies none of those.
POST_SPECTRA_TASKS = {
    "shell_spectrum": {
        "requires_uniform_cartesian": True,
        "requires_periodic_geometric": True,
        "requires_single_block": True,
        "fields": ("Ucat",),
    },
}
 
#: Binning abscissae a spectra task may request.
POST_SPECTRA_SYMBOLS = ("continuum", "discrete")
 
#: Fluctuation definitions a spectra task may request. `window:<name>` is accepted
#: as a prefixed form and resolved against the accumulated windows.
POST_SPECTRA_MEAN_MODES = ("none", "domain")
 
 
#: Derived outputs a post recipe may request from an accumulated window.
POST_FIELD_STATISTICS_OUTPUTS = ("mean", "reynolds_stress", "rms", "tke", "flux")
 
#: Output formats a post recipe may request. `vtk` writes the derived fields; `csv`
#: appends one convergence row per processed step.
POST_FIELD_STATISTICS_FORMATS = ("vtk", "csv")
 
# ---------------------------------------------------------------------------
# Authoritative public choice sets.
#
# Each of these was a literal written inline at its point of use, which made it
# invisible to the capability census: a set nobody can enumerate is a set nobody can
# document. Naming them here is the discovery contract - the census enumerates
# module-level names with these suffixes and demands a classification for each.
# ---------------------------------------------------------------------------
 
#: How the grid reaches the solver.
GRID_MODES = ("file", "programmatic_c", "grid_gen")
 
#: Geometries the bundled grid generator can produce.
GRID_GENERATOR_TYPES = ("box", "sweep")
 
#: Cross-sections a swept duct may carry. `circle` is the square-to-disc map, not an
#: O-grid: `Metric.c`'s `cgrid` branch for a circumferential seam is reachable only via
#: `programmatic_c`'s `cgrids` flag, and even there `src/grid.c` never builds anything
#: but a Cartesian box, so no path produces real O-grid coordinates to seam.
GRID_CROSS_SECTION_KINDS = ("rectangle", "circle")
 
#: Segment kinds a piecewise wall-height field accepts. A wall is built from these end to
#: end, so a step is one entry in a list rather than a geometry of its own.
GRID_WALL_SEGMENT_KINDS = ("flat", "step", "ramp", "arc", "sine", "gaussian", "hill")
 
#: Centreline segment kinds a swept path accepts.
GRID_PATH_SEGMENT_KINDS = ("straight", "arc")
 
#: Placement and similarity operations applied after a geometry map.
GRID_TRANSFORM_KINDS = ("anchor", "translate", "scale", "rotate", "mirror", "permute")
 
#: Whether a run seeds particles afresh or restores them from a checkpoint.
PARTICLE_RESTART_MODES = ("init", "load")
 
#: Eulerian post-processing kernels selectable per pipeline entry.
POST_EULERIAN_PIPELINE_TASKS = ("q_criterion", "normalize_field", "nodal_average")
 
#: Lagrangian post-processing kernels selectable per pipeline entry.
POST_LAGRANGIAN_PIPELINE_TASKS = ("specific_ke",)
 
#: Study shapes `picurv sweep` knows how to expand and aggregate.
STUDY_TYPES = ("grid_independence", "timestep_independence", "sensitivity")
 
#: Preconditioning models for the Newton-Krylov momentum solve.
NEWTON_KRYLOV_PRECONDITIONER_MODELS = ("none", "frozen_momentum_jacobian")
 
#: Matrix structures a Newton-Krylov preconditioner model may assemble. Determined by
#: the model rather than chosen independently: `frozen_momentum_jacobian` requires
#: `point_block`, and `none` accepts no structure at all.
NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES = ("none", "point_block")
 
#: Outer preconditioners the Poisson solve accepts. One canonical value today; the
#: census fails if this grows without a capability family being registered for it.
POISSON_PRECONDITIONER_TYPES = ("multigrid",)
 
#: Accepted spellings for the Poisson outer preconditioner.
POISSON_PRECONDITIONER_SPELLINGS = {"mg": "multigrid", "pcmg": "multigrid"}
 
# Storage compression policies live in picurv_cli/storage.py, which owns them; core
# imports storage, so declaring them here would be a cycle.
 
#: How a prescribed Eulerian field is supplied.
PRESCRIBED_FLOW_SOURCE_TYPES = ("file", "generated", "field_slice")
 
#: Analytic scalar profiles the verification source may generate.
VERIFICATION_SCALAR_PROFILES = ("CONSTANT", "LINEAR_X", "SIN_PRODUCT")
 
#: Image formats `picurv sweep` can render study plots in.
STUDY_PLOT_FORMATS = ("png", "pdf", "svg")
 
#: How much per-timestep profiling output the monitor emits.
PROFILING_TIMESTEP_MODES = ("off", "selected", "all")
 
#: Krylov methods for which a `gmres.restart` parameter is meaningful. This does NOT
#: restrict `poisson_solver.method`, which passes any PETSc KSP token through.
GMRES_RESTART_METHODS = ("gmres", "fgmres", "lgmres")
 
#: Analytical solution types the Eulerian source can impose.
ANALYTICAL_SOLUTION_TYPES = ("TGV3D", "ZERO_FLOW", "UNIFORM_FLOW")
 
#: Legacy capitalised spellings of the field-initialisation mode, still accepted and
#: resolved through normalize_field_init_mode.
LEGACY_FIELD_INIT_SPELLINGS = ("Zero", "Constant", "Poiseuille")
 
#: Discrete operators the solenoidal projection may use.
PROJECTION_OPERATORS = ("continuum", "picurv_discrete")
 
#: Where `picurv sweep` reads a declared metric from.
METRIC_SOURCE_KINDS = ("statistics_csv", "csv", "log_regex", "log")
 
#: Where a run is launched.
LAUNCH_MODES = ("local", "cluster")
 
 
 
def normalize_post_spectra_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the spectra block of post.yml.
 
    @details The recipe chooses what to measure; whether the case *can* support that
             measurement is a separate question answered by
             `validate_post_spectra_preconditions()`, which needs the grid and the
             boundary conditions. Keeping the two apart means a recipe stays valid on
             its own terms even when it is read without a case beside it.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Normalized mapping with an output prefix and a list of tasks.
    @throws ValueError on a malformed or inconsistent recipe.
    """
    raw = (post_cfg or {}).get("spectra")
    if raw is None:
        return {"output_prefix": "Spectrum", "tasks": []}
    if not isinstance(raw, dict):
        raise ValueError("'spectra' must be a mapping.")
 
    prefix = raw.get("output_prefix", "Spectrum")
    if not isinstance(prefix, str) or not prefix.strip():
        raise ValueError("'spectra.output_prefix' must be a non-empty string.")
 
    tasks = raw.get("tasks")
    if not isinstance(tasks, list) or not tasks:
        raise ValueError("'spectra.tasks' must be a non-empty list.")
 
    cleaned = []
    seen = []
    for position, entry in enumerate(tasks):
        if not isinstance(entry, dict):
            raise ValueError(f"spectra task {position}: each task must be a mapping.")
        name = entry.get("task")
        if name not in POST_SPECTRA_TASKS:
            raise ValueError(
                f"spectra task {position}: unknown task {name!r}. "
                f"Available tasks: {sorted(POST_SPECTRA_TASKS)}."
            )
        spec = POST_SPECTRA_TASKS[name]
 
        field = entry.get("field", spec["fields"][0])
        if field not in spec["fields"]:
            raise ValueError(
                f"spectra task '{name}': field {field!r} is not supported. "
                f"Supported fields: {list(spec['fields'])}."
            )
 
        block = entry.get("block", 0)
        if not isinstance(block, int) or isinstance(block, bool) or block < 0:
            raise ValueError(f"spectra task '{name}': 'block' must be a non-negative integer.")
 
        symbol = entry.get("symbol", "continuum")
        if symbol not in POST_SPECTRA_SYMBOLS:
            raise ValueError(
                f"spectra task '{name}': unknown symbol {symbol!r}. "
                f"Available symbols: {list(POST_SPECTRA_SYMBOLS)}."
            )
 
        subtract_mean = entry.get("subtract_mean", "none")
        if not isinstance(subtract_mean, str) or not subtract_mean.strip():
            raise ValueError(f"spectra task '{name}': 'subtract_mean' must be a string.")
        subtract_mean = subtract_mean.strip()
        if subtract_mean.startswith("window:"):
            window_name = subtract_mean.split(":", 1)[1].strip()
            if not window_name:
                raise ValueError(
                    f"spectra task '{name}': 'subtract_mean: window:<name>' needs a window name."
                )
        elif subtract_mean not in POST_SPECTRA_MEAN_MODES:
            raise ValueError(
                f"spectra task '{name}': unknown subtract_mean {subtract_mean!r}. "
                f"Use one of {list(POST_SPECTRA_MEAN_MODES)} or 'window:<name>'."
            )
 
        # A window mean is only worth subtracting once the window has converged, so the
        # bundle the mean is read from is chosen separately from the step being
        # transformed. Left unset, each step uses its own bundle, whose running mean is
        # undefined at the moment the window activates.
        mean_source_step = entry.get("mean_source_step")
        if mean_source_step is not None:
            if (not isinstance(mean_source_step, int) or isinstance(mean_source_step, bool)
                    or mean_source_step < 0):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' must be a non-negative integer."
                )
            if not subtract_mean.startswith("window:"):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' only applies to "
                    f"'subtract_mean: window:<name>'."
                )
 
        reference = entry.get("reference")
        if reference is not None and (not isinstance(reference, str) or not reference.strip()):
            raise ValueError(f"spectra task '{name}': 'reference' must be a non-empty string.")
 
        # Each task writes its own file, so a repeat would overwrite its own output.
        identity = (name, field, block, symbol)
        if identity in seen:
            raise ValueError(
                f"spectra recipe lists task '{name}' for field {field} on block {block} "
                f"with symbol '{symbol}' more than once."
            )
        seen.append(identity)
        cleaned.append({
            "task": name,
            "field": field,
            "block": block,
            "symbol": symbol,
            "subtract_mean": subtract_mean,
            "mean_source_step": mean_source_step,
            "reference": reference.strip() if isinstance(reference, str) else None,
        })
 
    return {"output_prefix": prefix.strip(), "tasks": cleaned}
 
 
def validate_post_spectra_preconditions(spectra_cfg: dict, case_cfg: dict, post_path: str) -> list:
    """!
    @brief Check spectra tasks against what the case can actually support.
 
    @details Runs before any field is read, so a case with no homogeneous direction is
             refused rather than yielding a curve that means nothing. Only the checks
             the case file can answer are made here: periodicity and block count. Grid
             uniformity is enforced by `generators/spectra.gen`, which reads the staged
             PICGRID and is the only place the real node coordinates are known.
 
    @param[in] spectra_cfg Normalized spectra recipe.
    @param[in] case_cfg Parsed case configuration.
    @param[in] post_path Post recipe path, for error messages.
    @return List of formatted error strings; empty when every task is supportable.
    """
    errors = []
    if not spectra_cfg.get("tasks"):
        return errors
 
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        # The case file reports its own boundary-condition errors; do not repeat them.
        return errors
 
    block_count = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    periodic_faces = {}
    for block_index, block_bcs in enumerate(prepared_blocks):
        faces = {entry.get("face") for entry in block_bcs if entry.get("type") == "PERIODIC"}
        periodic_faces[block_index] = faces
 
    all_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    for task_cfg in spectra_cfg["tasks"]:
        spec = POST_SPECTRA_TASKS[task_cfg["task"]]
        label = f"spectra task '{task_cfg['task']}'"
 
        if spec.get("requires_single_block") and block_count != 1:
            errors.append(
                f"  {post_path}: {label} requires a single-block domain; this case has "
                f"{block_count} blocks."
            )
 
        block = task_cfg["block"]
        if block >= block_count:
            errors.append(
                f"  {post_path}: {label} targets block {block}, but the case defines "
                f"{block_count} block(s)."
            )
            continue
 
        if spec.get("requires_periodic_geometric"):
            missing = sorted(all_faces - periodic_faces.get(block, set()))
            if missing:
                errors.append(
                    f"  {post_path}: {label} requires every face of block {block} to be "
                    f"PERIODIC, because a shell-averaged spectrum is only defined for a "
                    f"triply periodic homogeneous box. Non-periodic faces: {missing}."
                )
    return errors
 
 
def _resolve_spectra_payload(bundle: dict, kind: str, field: str, block: int) -> str:
    """!
    @brief Locate one checkpoint payload by its inventory entry rather than by path shape.
    @param[in] bundle Validated checkpoint bundle mapping.
    @param[in] kind Payload kind recorded in the inventory.
    @param[in] field Payload field name recorded in the inventory.
    @param[in] block Block index the payload belongs to.
    @return Absolute path to the payload file.
    @throws ValueError when the bundle carries no such payload.
    """
    for payload in bundle["payloads"]:
        if (payload["kind"] == kind and payload["field"] == field
                and payload["block"] == str(block)):
            return os.path.join(bundle["bundle"], *payload["path"].split("/"))
    raise ValueError(
        f"checkpoint {os.path.basename(bundle['bundle'])} carries no {kind} payload "
        f"'{field}' for block {block}."
    )
 
 
def _spectra_mean_arguments(task_cfg: dict, bundle: dict, mean_bundle: dict = None) -> list:
    """!
    @brief Build the generator arguments implementing a task's fluctuation choice.
    @param[in] task_cfg Normalized spectra task.
    @param[in] bundle Validated checkpoint bundle for the step being transformed.
    @param[in] mean_bundle Bundle supplying the window mean; defaults to @p bundle.
    @return Argument list to append to the generator command.
    @throws ValueError when a named window is absent from the bundle.
    """
    mode = task_cfg["subtract_mean"]
    if not mode.startswith("window:"):
        return ["--subtract-mean", mode]
    window = mode.split(":", 1)[1].strip()
    block = task_cfg["block"]
    source = mean_bundle or bundle
    mean_path = _resolve_spectra_payload(source, "mean", f"{window}/{task_cfg['field']}_mean", block)
    count_path = _resolve_spectra_payload(source, "occupancy", f"{window}/count", block)
    return ["--subtract-mean", "field", "--mean-file", mean_path, "--count-file", count_path]
 
 
#: Scalar columns the spectra stage records once per processed step.
POST_SPECTRA_SCALAR_COLUMNS = (
    "resolved_kinetic_energy", "spectrum_total_energy", "parseval_residual",
    "spectrum_peak_k", "zero_mode_energy", "integral_length_scale",
    "taylor_microscale", "dissipation_over_viscosity",
)
 
 
#: Stages `picurv run --post-process` can execute, in the order they are listed.
POST_STAGE_NAMES = ("fields", "spectra")
 
 
def resolve_post_stage_selection(only) -> set:
    """!
    @brief Resolve the `--only` selector into the set of post stages to execute.
    @param[in] only Comma-separated selector text, or None for every stage.
    @return Set of stage names.
    @throws ValueError when the selector names an unknown or empty stage.
    """
    if not only:
        return set(POST_STAGE_NAMES)
    requested = [token.strip() for token in str(only).split(",")]
    if not all(requested):
        raise ValueError("--only must not contain an empty stage name.")
    unknown = sorted({token for token in requested if token not in POST_STAGE_NAMES})
    if unknown:
        raise ValueError(
            f"--only names unknown post stage(s) {unknown}. "
            f"Available stages: {list(POST_STAGE_NAMES)}."
        )
    return set(requested)
 
 
def run_post_spectra_stage(run_dir: str, post_cfg: dict, monitor_cfg: dict,
                           source_dir: str, steps, quiet: bool = False) -> dict:
    """!
    @brief Measure spectra for every requested task across a window of committed steps.
 
    @details One spectrum per step per task, because a spectrum is a property of one
             state: averaging across steps would be wrong for a decaying flow, where
             every step is a different statistical state. Results are written in long
             form so a family of curves stays one file, alongside a scalar history that
             plots through the ordinary series machinery.
 
    @param[in] run_dir Run directory receiving the output.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] monitor_cfg Parsed monitor configuration anchoring the output root.
    @param[in] source_dir Directory holding the committed checkpoints.
    @param[in] steps Iterable of checkpoint steps to process, in order.
    @param[in] quiet Suppress progress reporting.
    @return Summary with the written paths and the steps actually processed.
    @throws ValueError when the generator fails or a requested payload is absent.
    """
    spectra = normalize_post_spectra_config(post_cfg)
    if not spectra["tasks"]:
        return {"tasks": [], "steps": [], "artifacts": []}
 
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if not os.path.isfile(staged_grid):
        raise ValueError(f"spectra require a staged PICGRID at {staged_grid}.")
 
    output_dir = os.path.join(
        os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg)
    )
    os.makedirs(output_dir, exist_ok=True)
 
    # Spectra are computed from the staged non-dimensional field on the staged
    # non-dimensional grid, so physical units are the generator's to apply. The run's
    # own configuration snapshot is the authority for the scales it used.
    scale_arguments = []
    if bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False)):
        active_case = load_active_run_configuration(run_dir).get("case")
        case_path = os.path.join(run_dir, active_case) if active_case else None
        if case_path and os.path.isfile(case_path):
            scaling = resolve_fluid_scaling(read_yaml_file(case_path))
            scale_arguments = [
                "--velocity-ref", repr(float(scaling["velocity_ref"])),
                "--length-ref", repr(float(scaling["length_ref"])),
            ]
        elif not quiet:
            print("[WARNING] Spectra: dimensionalize was requested but this run carries no "
                  "readable case snapshot; results stay non-dimensional.", file=sys.stderr)
 
    requested = sorted(set(int(step) for step in steps))
    # The requested window is what the recipe asks for, not what exists. The field
    # post-processor is bounded by the available source frontier and this must be too:
    # a window reaching past the last committed checkpoint is normal while a solve is
    # still running, and is not an error.
    available = _scan_committed_checkpoint_steps(source_dir)
    ordered_steps = [step for step in requested if step in available]
    if not ordered_steps:
        if not quiet:
            print("[INFO] Spectra: no committed checkpoint in the requested window yet; "
                  "nothing measured.")
        return {"tasks": [], "steps": [], "artifacts": []}
    if not quiet and len(ordered_steps) != len(requested):
        print(f"[INFO] Spectra: {len(ordered_steps)} of {len(requested)} requested step(s) "
              f"are committed; measuring those.")
    artifacts = []
    for task_cfg in spectra["tasks"]:
        basename = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        spectrum_path = os.path.join(output_dir, f"{basename}.csv")
        scalar_path = os.path.join(output_dir, f"{basename}_history.csv")
        spectrum_rows = []
        scalar_rows = []
        mean_bundle = None
        if task_cfg["mean_source_step"] is not None:
            mean_bundle = validate_committed_checkpoint(source_dir, task_cfg["mean_source_step"])
 
        for step in ordered_steps:
            bundle = validate_committed_checkpoint(source_dir, step)
            time = float(bundle["metadata"]["checkpoint_time"])
            field_path = _resolve_spectra_payload(
                bundle, "eulerian", task_cfg["field"], task_cfg["block"]
            )
            cmd = [sys.executable, script, "shell-spectrum",
                   "--field-file", field_path, "--source-grid", staged_grid,
                   "--block", str(task_cfg["block"]), "--symbol", task_cfg["symbol"]]
            cmd.extend(_spectra_mean_arguments(task_cfg, bundle, mean_bundle))
            cmd.extend(scale_arguments)
            result = subprocess.run(cmd, text=True, capture_output=True)
            if result.returncode != 0:
                details = (result.stderr or result.stdout or "").strip()
                raise ValueError(
                    f"spectra task '{task_cfg['task']}' failed at step {step} with exit code "
                    f"{result.returncode}. Details:\n{details}"
                )
            summary = json.loads(result.stdout)
            for row in summary["shell_spectrum"]:
                spectrum_rows.append({"step": step, "time": time,
                                      "k": row["k"], "energy": row["energy"]})
            scalar_rows.append({"step": step, "time": time,
                                **{name: summary[name] for name in POST_SPECTRA_SCALAR_COLUMNS}})
 
        with open(spectrum_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=("step", "time", "k", "energy"))
            writer.writeheader()
            writer.writerows(spectrum_rows)
        with open(scalar_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=("step", "time") + POST_SPECTRA_SCALAR_COLUMNS)
            writer.writeheader()
            writer.writerows(scalar_rows)
        artifacts.extend([spectrum_path, scalar_path])
        if not quiet:
            print(f"[INFO] Spectra: wrote {len(scalar_rows)} step(s) for task "
                  f"'{task_cfg['task']}' to {os.path.relpath(spectrum_path, run_dir)}")
 
    return {
        "tasks": [entry["task"] for entry in spectra["tasks"]],
        "steps": ordered_steps,
        "artifacts": artifacts,
    }
 
 
def compute_post_spectra_signature(spectra_cfg: dict) -> str:
    """!
    @brief Reduce a normalized spectra recipe to a stable identity string.
    @param[in] spectra_cfg Normalized spectra recipe.
    @return Hex digest covering every choice that changes the produced spectra.
    """
    payload = json.dumps(spectra_cfg, sort_keys=True, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:16]
 
 
def resolve_post_spectra_output_dir(monitor_cfg=None) -> str:
    """!
    @brief Resolve the run-relative directory spectra CSVs are written to.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Run-relative directory path.
    """
    del monitor_cfg
    return CANONICAL_RUN_PATHS["spectra"]
 
 
def resolve_recipe_spectra_output_dir(post_cfg: dict, monitor_cfg=None) -> str:
    """!
    @brief Resolve the canonical spectra directory for one versioned recipe.
    @param[in] post_cfg Parsed runtime post config.
    @param[in] monitor_cfg Optional monitor config for standalone compatibility.
    @return Run-relative spectra directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    return internal.get("spectra") or resolve_post_spectra_output_dir(monitor_cfg)
 
 
def get_post_spectra_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None) -> list:
    """!
    @brief Predict the spectra CSV paths a recipe will write.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the recipe operates on.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Absolute CSV paths, one per task, in recipe order.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # The recipe reports its own errors during validation; predict nothing here.
        return []
    if not spectra["tasks"]:
        return []
    base = os.path.join(os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg))
    paths = []
    for task_cfg in spectra["tasks"]:
        name = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        paths.append(os.path.join(base, f"{name}.csv"))
    return list(dict.fromkeys(paths))
 
 
def post_spectra_task_basename(task_cfg: dict, output_prefix: str) -> str:
    """!
    @brief Build the file basename one normalized spectra task writes.
    @param[in] task_cfg Normalized task mapping.
    @param[in] output_prefix Recipe output prefix.
    @return Basename without directory or extension.
    """
    parts = [output_prefix, task_cfg["task"], task_cfg["field"],
             f"block{task_cfg['block']:04d}", task_cfg["symbol"]]
    return "_".join(parts)
 
 
def normalize_post_field_statistics_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the field_statistics block of post.yml.
 
    @details The recipe names windows rather than redescribing them, because the
             window definitions already reach the post-processor through the run's
             solver control. Validation therefore covers the recipe's own choices
             only; a name no window matches is caught in C against the resolved list,
             which is the only place the real set is known.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Value returned by `normalize_post_field_statistics_config()`.
    """
    raw = (post_cfg or {}).get("field_statistics")
    if raw is None:
        return {"windows": [], "source_step": None, "outputs": [], "formats": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    windows = raw.get("windows")
    if not isinstance(windows, list) or not windows:
        raise ValueError("'field_statistics.windows' must be a non-empty list of window names.")
    cleaned = []
    for entry in windows:
        if not isinstance(entry, str) or not entry.strip():
            raise ValueError("'field_statistics.windows' entries must be non-empty window names.")
        name = entry.strip()
        # Each window writes its own file, so a repeat would overwrite its own output.
        if name in cleaned:
            raise ValueError(f"field statistics recipe lists window '{name}' more than once.")
        cleaned.append(name)
 
    label = ", ".join(cleaned)
    source_step = raw.get("source_step")
    if source_step is not None:
        if not isinstance(source_step, int) or isinstance(source_step, bool) or source_step < 0:
            raise ValueError(
                f"field statistics recipe for [{label}]: 'source_step' must be a non-negative "
                f"integer (got {source_step!r})."
            )
 
    outputs = raw.get("outputs", list(POST_FIELD_STATISTICS_OUTPUTS))
    if not isinstance(outputs, list) or not outputs:
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' must be a non-empty list.")
    unknown = [item for item in outputs if item not in POST_FIELD_STATISTICS_OUTPUTS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown outputs {unknown}. "
            f"Available outputs: {list(POST_FIELD_STATISTICS_OUTPUTS)}."
        )
    if len(set(outputs)) != len(outputs):
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' lists a duplicate.")
 
    formats = raw.get("formats", ["vtk"])
    if not isinstance(formats, list) or not formats:
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' must be a non-empty list.")
    unknown = [item for item in formats if item not in POST_FIELD_STATISTICS_FORMATS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown formats {unknown}. "
            f"Available formats: {list(POST_FIELD_STATISTICS_FORMATS)}."
        )
    if len(set(formats)) != len(formats):
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' lists a duplicate.")
 
    return {
        "windows": cleaned,
        "source_step": source_step,
        "outputs": list(outputs),
        "formats": list(formats),
    }
 
 
def _post_window_derived_field_count(window_cfg: dict, outputs: list) -> int:
    """!
    @brief Count the derived fields one window would produce for a set of outputs.
 
    @details Mirrors the resolution the C derivation performs, so a recipe that would
             produce an empty file is refused before the run rather than after it. Each
             output resolves against what the window accumulated: a window keeping only
             first moments has no stresses, RMS, or turbulent kinetic energy to give.
 
    @param[in] window_cfg Normalized window definition from monitor.yml.
    @param[in] outputs Requested output kinds.
    @return Value returned by `_post_window_derived_field_count()`.
    """
    fields = window_cfg.get("fields", []) or []
    covariances = window_cfg.get("covariances", []) or []
    with_second = [f for f in fields if "second" in (f.get("moments") or [])]
    total = 0
    for kind in outputs:
        if kind == "mean":
            total += len(fields)
        elif kind == "reynolds_stress":
            for entry in with_second:
                dof = STATISTICS_ELIGIBLE_FIELDS[entry["field"]]["components"]
                total += 6 if dof == 3 else 1
        elif kind == "rms":
            for entry in with_second:
                total += STATISTICS_ELIGIBLE_FIELDS[entry["field"]]["components"]
        elif kind == "tke":
            total += sum(1 for entry in with_second
                         if STATISTICS_ELIGIBLE_FIELDS[entry["field"]]["components"] == 3)
        elif kind == "flux":
            total += len(covariances)
    return total
 
 
def _post_requests_field_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe derives accumulated field statistics.
    @param[in] post_cfg Argument passed to `_post_requests_field_statistics()`.
    @return Value returned by `_post_requests_field_statistics()`.
    """
    try:
        return bool(normalize_post_field_statistics_config(post_cfg)["windows"])
    except ValueError:
        # Malformed configuration is reported by validation, not by this predicate.
        return False
 
 
def get_post_field_statistics_artifacts(post_cfg: dict, run_dir: str):
    """!
    @brief Predict the per-window statistics artifacts a recipe will produce.
    @details Returns one entry per window and format, so resume tracking can tell a
             half-finished window from a completed one.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the outputs are written under.
    @return List of (kind, path_prefix) tuples; kind is 'vtk' or 'csv'.
    """
    config = normalize_post_field_statistics_config(post_cfg)
    if not config["windows"]:
        return []
    io_cfg = post_cfg.get("io", {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    visualization_dir = _post_output_directory_abs(run_dir, post_cfg)
    visualization_prefix = io_cfg.get("output_filename_prefix", "Field")
    csv_prefix_path = None
    if internal.get("field_statistics_prefix"):
        csv_prefix_path = os.path.join(run_dir, internal["field_statistics_prefix"])
    artifacts = []
    for window in config["windows"]:
        if "vtk" in config["formats"]:
            artifacts.append(("vtk", os.path.join(
                visualization_dir, f"{visualization_prefix}_statistics_{window}"
            )))
        if "csv" in config["formats"]:
            csv_base = csv_prefix_path or os.path.join(
                visualization_dir, str(visualization_prefix)
            )
            artifacts.append(("csv", f"{csv_base}_statistics_{window}.csv"))
    return artifacts
 
 
def build_post_recipe_config(post_cfg: dict, monitor_cfg=None) -> dict:
    """!
    @brief Build the flat key=value mapping consumed by the C post-processor.
    @param[in] post_cfg Argument passed to `build_post_recipe_config()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return Value returned by `build_post_recipe_config()`.
    """
    c_config = {}
 
    c_config['startTime'] = get_post_run_control_value(post_cfg, 'start_step', 0)
    c_config['endTime'] = get_post_run_control_value(post_cfg, 'end_step', 0)
    c_config['timeStep'] = get_post_run_control_value(post_cfg, 'step_interval', 1)
 
    eulerian_pipeline_parts = []
    dimensionalize = bool(post_cfg.get('global_operations', {}).get('dimensionalize', False))
    if dimensionalize:
        eulerian_pipeline_parts.append('DimensionalizeAllLoadedFields')
        # The field pipeline is one of three producers. Derived statistics scale in the
        # accumulator and spectra scale in their generator, so the request has to reach
        # them as a setting rather than as a pipeline stage.
        c_config['dimensionalize'] = 'true'
 
    for task in post_cfg.get('eulerian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'q_criterion':
            eulerian_pipeline_parts.append('ComputeQCriterion')
        elif task_name == 'normalize_field':
            field = task.get('field', 'P')
            eulerian_pipeline_parts.append(f'NormalizeRelativeField:{field}')
            ref_point = task.get('reference_point', [1, 1, 1])
            c_config['reference_ip'] = ref_point[0]
            c_config['reference_jp'] = ref_point[1]
            c_config['reference_kp'] = ref_point[2]
        elif task_name == 'nodal_average':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                eulerian_pipeline_parts.append(f'CellToNodeAverage:{in_field}>{out_field}')
 
    if eulerian_pipeline_parts:
        c_config['process_pipeline'] = ";".join(eulerian_pipeline_parts)
 
    lagrangian_pipeline_parts = []
    for task in post_cfg.get('lagrangian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'specific_ke':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                lagrangian_pipeline_parts.append(f'ComputeSpecificKE:{in_field}>{out_field}')
    if lagrangian_pipeline_parts:
        c_config['particle_pipeline'] = ";".join(lagrangian_pipeline_parts)
 
    statistics_pipeline_parts = get_post_statistics_task_tokens(post_cfg)
    statistics_output_prefix = None
    stats_cfg = post_cfg.get('statistics_pipeline')
    if isinstance(stats_cfg, dict):
        statistics_output_prefix = stats_cfg.get('output_prefix')
 
    if statistics_pipeline_parts:
        c_config['statistics_pipeline'] = ";".join(statistics_pipeline_parts)
        statistics_output_prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    elif statistics_output_prefix is None:
        statistics_output_prefix = post_cfg.get('statistics_output_prefix')
    if statistics_output_prefix:
        c_config['statistics_output_prefix'] = statistics_output_prefix
 
    io = post_cfg.get('io', {})
    internal_paths = post_cfg.get('_picurv_paths', {}) or {}
    field_statistics = normalize_post_field_statistics_config(post_cfg)
    if field_statistics["windows"]:
        c_config['field_statistics_windows'] = ",".join(field_statistics["windows"])
        c_config['field_statistics_outputs'] = ",".join(field_statistics["outputs"])
        c_config['field_statistics_formats'] = ",".join(field_statistics["formats"])
        # An omitted source step means each processed step derives from its own
        # bundle, which is what turns a multi-step recipe into a convergence history.
        if field_statistics["source_step"] is not None:
            c_config['field_statistics_source_step'] = field_statistics["source_step"]
        if internal_paths.get("field_statistics_prefix"):
            c_config['field_statistics_output_prefix'] = internal_paths["field_statistics_prefix"]
 
    c_config['output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('output_filename_prefix', 'Field')
    c_config['particle_output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('particle_filename_prefix', 'Particle')
    c_config['output_particles'] = io.get('output_particles', False)
    c_config['particle_output_freq'] = io.get('particle_subsampling_frequency', 1)
    c_config['output_fields_instantaneous'] = ",".join(io.get('eulerian_fields', []))
    c_config['particle_fields_instantaneous'] = ",".join(io.get('particle_fields', []))
    input_extensions = get_post_input_extensions(post_cfg)
    if isinstance(input_extensions, dict):
        for extension_name in ('eulerian', 'particle'):
            extension = input_extensions.get(extension_name)
            if extension and str(extension).strip().lstrip('.').lower() != 'dat':
                raise ValueError(
                    f"post input extension '{extension_name}' must be 'dat'; "
                    "committed checkpoint payload names are fixed."
                )
 
    source_directory = get_post_source_directory_template(post_cfg, default=None)
    if source_directory is not None:
        c_config['source_directory'] = source_directory
 
    # Spectra run in the conductor's Python stage, but the recipe fingerprint is
    # computed over this mapping, so the block has to be represented here or a
    # changed spectra recipe would resume against stale lineage. The C
    # post-processor accepts and ignores the key.
    spectra = normalize_post_spectra_config(post_cfg)
    if spectra["tasks"]:
        c_config['spectra_signature'] = compute_post_spectra_signature(spectra)
 
    return c_config
 
 
def compute_post_recipe_id(post_cfg: dict) -> str:
    """!
    @brief Compute a stable human-readable identity for one post recipe.
    @param[in] post_cfg Parsed post configuration before runtime path injection.
    @return Filesystem-safe recipe identity.
    """
    normalized = copy.deepcopy(post_cfg or {})
    normalized.pop("_picurv_paths", None)
    source = normalized.get("source_data")
    if isinstance(source, dict):
        source.pop("directory", None)
    io = normalized.get("io")
    label = "post"
    if isinstance(io, dict):
        io.pop("output_directory", None)
        raw_label = io.get("output_filename_prefix")
        if isinstance(raw_label, str) and raw_label.strip():
            label = re.sub(r"[^A-Za-z0-9_.-]+", "-", raw_label.strip()).strip("-") or "post"
    run_control = normalized.get("run_control")
    if isinstance(run_control, dict):
        for key in POST_RUN_CONTROL_ALIASES["start_step"] + POST_RUN_CONTROL_ALIASES["end_step"]:
            run_control.pop(key, None)
    digest = hashlib.sha256(
        json.dumps(normalized, sort_keys=True, separators=(",", ":")).encode("utf-8")
    ).hexdigest()[:12]
    return f"{label}-{digest}"
 
 
def apply_canonical_post_paths(post_cfg: dict, run_dir: str) -> "tuple[dict, str]":
    """!
    @brief Route every post artifact into its fixed analysis or visualization home.
    @param[in] post_cfg Parsed user recipe.
    @param[in] run_dir Run receiving derived artifacts.
    @return Runtime-only config copy and stable recipe id.
    """
    recipe_id = compute_post_recipe_id(post_cfg)
    runtime = copy.deepcopy(post_cfg)
    if not isinstance(runtime.get("source_data"), dict):
        runtime["source_data"] = {}
    runtime["source_data"]["directory"] = os.path.join(
        os.path.abspath(run_dir), CANONICAL_RUN_PATHS["output"]
    )
    io = runtime.setdefault("io", {})
    io["output_directory"] = os.path.join(CANONICAL_RUN_PATHS["visualization"], recipe_id)
    output_prefix = io.get("output_filename_prefix", "Field")
    stats_cfg = runtime.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        basename = stats_cfg.get("output_prefix", "Stats")
        stats_cfg["output_prefix"] = os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, os.path.basename(str(basename))
        )
    runtime["_picurv_paths"] = {
        "recipe_id": recipe_id,
        "recipe_root": os.path.join("config", "post-recipes", recipe_id),
        "visualization": io["output_directory"],
        "statistics": os.path.join(CANONICAL_RUN_PATHS["statistics"], recipe_id),
        "field_statistics_prefix": os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, str(output_prefix)
        ),
        "spectra": os.path.join(CANONICAL_RUN_PATHS["spectra"], recipe_id),
    }
    return runtime, recipe_id
 
 
def normalize_post_recipe_signature(recipe_cfg: dict) -> dict:
    """!
    @brief Normalize post recipe settings into a stable signature mapping.
    @param[in] recipe_cfg Argument passed to `normalize_post_recipe_signature()`.
    @return Value returned by `normalize_post_recipe_signature()`.
    """
    signature = {}
    for key, value in (recipe_cfg or {}).items():
        if key in POST_RECIPE_SIGNATURE_EXCLUDED_KEYS or value is None:
            continue
        if isinstance(value, bool):
            text = 'true' if value else 'false'
        else:
            text = str(value).strip()
            if text.lower() in {'true', 'false'}:
                text = text.lower()
        if text:
            signature[str(key)] = text
    return signature
 
 
def compute_post_recipe_fingerprint(recipe_cfg: dict) -> "tuple[dict, str]":
    """!
    @brief Return normalized recipe signature plus SHA-256 fingerprint.
    @param[in] recipe_cfg Argument passed to `compute_post_recipe_fingerprint()`.
    @return Value returned by `compute_post_recipe_fingerprint()`.
    """
    signature = normalize_post_recipe_signature(recipe_cfg)
    payload = json.dumps(signature, sort_keys=True, separators=(',', ':')).encode('utf-8')
    return signature, hashlib.sha256(payload).hexdigest()
 
 
def parse_post_recipe_file(post_recipe_path: str):
    """!
    @brief Parse an existing generated post.run file into a key/value mapping.
    @param[in] post_recipe_path Argument passed to `parse_post_recipe_file()`.
    @return Value returned by `parse_post_recipe_file()`.
    """
    if not post_recipe_path or not os.path.isfile(post_recipe_path):
        return None
    recipe_cfg = {}
    with open(post_recipe_path, 'r', encoding='utf-8', errors='replace') as f:
        for raw_line in f:
            line = raw_line.strip()
            if not line or line.startswith('#') or '=' not in line:
                continue
            key, value = line.split('=', 1)
            recipe_cfg[key.strip()] = value.strip()
    return recipe_cfg
 
 
def get_post_resume_state_path(run_dir: str, post_cfg: dict = None) -> str:
    """!
    @brief Return the JSON resume metadata path for a run directory.
    @param[in] run_dir Argument passed to `get_post_resume_state_path()`.
    @param[in] post_cfg Optional versioned post recipe configuration.
    @return Value returned by `get_post_resume_state_path()`.
    """
    if post_cfg is None:
        return os.path.join(run_dir, 'config', POST_RESUME_STATE_FILENAME)
    return os.path.join(get_post_recipe_root(run_dir, post_cfg), "state.json")
 
 
def get_post_recipe_root(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Return the versioned run-local control directory for one post recipe.
    @param[in] run_dir Owning run root.
    @param[in] post_cfg Runtime post config with canonical paths, or a user recipe.
    @return Absolute recipe control directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    recipe_id = internal.get("recipe_id") or compute_post_recipe_id(post_cfg)
    return os.path.join(os.path.abspath(run_dir), "config", "post-recipes", recipe_id)
 
 
def get_post_lock_paths(run_dir: str, recipe_id: str = None) -> dict:
    """!
    @brief Return lock-wrapper related paths for a run directory.
    @param[in] run_dir Argument passed to `get_post_lock_paths()`.
    @param[in] recipe_id Optional stable recipe identity used to scope the lock.
    @return Value returned by `get_post_lock_paths()`.
    """
    scheduler_dir = os.path.join(run_dir, 'scheduler')
    suffix = f".{recipe_id}" if recipe_id else ""
    return {
        'lock_file': os.path.join(scheduler_dir, f"post{suffix}.lock"),
        'metadata_file': os.path.join(scheduler_dir, f"post{suffix}.lock.json"),
        'wrapper_path': os.path.join(scheduler_dir, POST_LOCK_WRAPPER_FILENAME),
    }
 
 
def _post_output_directory_abs(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Resolve the absolute post output directory for the current recipe.
    @param[in] run_dir Argument passed to `_post_output_directory_abs()`.
    @param[in] post_cfg Argument passed to `_post_output_directory_abs()`.
    @return Value returned by `_post_output_directory_abs()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    relative = internal.get("visualization") or io_cfg.get('output_directory')
    if not relative:
        relative = os.path.join(CANONICAL_RUN_PATHS["visualization"], compute_post_recipe_id(post_cfg))
    return os.path.abspath(os.path.join(run_dir, relative))
 
 
def _post_requests_eulerian_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects Eulerian VTK output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_eulerian_output()`.
    @return Value returned by `_post_requests_eulerian_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('eulerian_fields'))
 
 
def _post_requests_particle_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects particle VTP output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_particle_output()`.
    @return Value returned by `_post_requests_particle_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) and bool(io_cfg.get('particle_fields'))
 
 
def _post_requests_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects statistics CSV artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_statistics()`.
    @return Value returned by `_post_requests_statistics()`.
    """
    return bool(get_post_statistics_task_tokens(post_cfg))
 
 
def _post_needs_particle_source(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe requires particle source files to be present.
    @param[in] post_cfg Argument passed to `_post_needs_particle_source()`.
    @return Value returned by `_post_needs_particle_source()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) or bool(post_cfg.get('lagrangian_pipeline')) or _post_requests_statistics(post_cfg)
 
 
def _iter_post_steps(start_step: int, end_step: int, step_interval: int):
    """!
    @brief Yield configured post-processing steps inclusively.
    @param[in] start_step Argument passed to `_iter_post_steps()`.
    @param[in] end_step Argument passed to `_iter_post_steps()`.
    @param[in] step_interval Argument passed to `_iter_post_steps()`.
    """
    if step_interval <= 0 or end_step < start_step:
        return
    step = start_step
    while step <= end_step:
        yield step
        step += step_interval
 
 
def resolve_post_requested_window(post_cfg: dict, case_cfg: dict = None) -> "tuple[int, int, int]":
    """!
    @brief Resolve post requested start/end/interval, expanding end=-1 via case.yml when available.
    @param[in] post_cfg Argument passed to `resolve_post_requested_window()`.
    @param[in] case_cfg Optional case configuration for end-step expansion.
    @return Value returned by `resolve_post_requested_window()`.
    """
    start_step = int(get_post_run_control_value(post_cfg, 'start_step', 0) or 0)
    end_step = int(get_post_run_control_value(post_cfg, 'end_step', 0) or 0)
    step_interval = int(get_post_run_control_value(post_cfg, 'step_interval', 1) or 1)
    if end_step < 0 and case_cfg:
        case_run = case_cfg.get('run_control', {}) or {}
        case_start = int(case_run.get('start_step', 0) or 0)
        case_total = int(case_run.get('total_steps', 0) or 0)
        end_step = case_start + case_total
    return start_step, end_step, step_interval
 
 
def prepare_effective_post_config(post_cfg: dict, resolved_source_dir: str, start_step: int = None, end_step: int = None) -> dict:
    """!
    @brief Return a copy of post_cfg with resolved source dir and optional effective bounds.
    @param[in] post_cfg Argument passed to `prepare_effective_post_config()`.
    @param[in] resolved_source_dir Argument passed to `prepare_effective_post_config()`.
    @param[in] start_step Argument passed to `prepare_effective_post_config()`.
    @param[in] end_step Argument passed to `prepare_effective_post_config()`.
    @return Value returned by `prepare_effective_post_config()`.
    """
    effective_cfg = copy.deepcopy(post_cfg)
    if not isinstance(effective_cfg.get('source_data'), dict):
        effective_cfg['source_data'] = {}
    effective_cfg['source_data']['directory'] = resolved_source_dir
    rc = effective_cfg.setdefault('run_control', {})
    if start_step is not None:
        rc['start_step'] = int(start_step)
    if end_step is not None:
        rc['end_step'] = int(end_step)
    return effective_cfg
 
 
def _scan_post_vtk_steps(prefix_path: str, extension: str) -> "set[int]":
    """!
    @brief Collect step numbers from VTK files named with a prefix, step suffix, and extension.
    @param[in] prefix_path Output path prefix before the numeric step suffix.
    @param[in] extension VTK file extension to match without its leading dot.
    @return Set of step numbers represented by matching files in the prefix directory.
    """
    directory = os.path.dirname(prefix_path)
    if not os.path.isdir(directory):
        return set()
    basename = os.path.basename(prefix_path)
    pattern = re.compile(rf'^{re.escape(basename)}_(\d+)\.{re.escape(extension)}$')
    steps = set()
    for name in os.listdir(directory):
        match = pattern.match(name)
        if match:
            steps.add(int(match.group(1)))
    return steps
 
 
def _scan_post_statistics_csv_steps(csv_path: str) -> "set[int]":
    """!
    @brief Scan step ids from the first CSV column of a statistics artifact.
    @param[in] csv_path Argument passed to `_scan_post_statistics_csv_steps()`.
    @return Value returned by `_scan_post_statistics_csv_steps()`.
    """
    if not os.path.isfile(csv_path):
        return set()
    steps = set()
    with open(csv_path, 'r', encoding='utf-8', errors='replace', newline='') as f:
        reader = csv.reader(f)
        for row in reader:
            if not row:
                continue
            head = str(row[0]).strip().lower()
            if head in {'step', 'timestep', 'time_step'}:
                continue
            step_val = _parse_int_loose(row[0])
            if step_val is not None:
                steps.add(step_val)
    return steps
 
 
def collect_post_completion_families(run_dir: str, post_cfg: dict, monitor_cfg=None) -> "list[set[int]]":
    """!
    @brief Collect per-family completed-step sets for the current post recipe.
    @param[in] run_dir Argument passed to `collect_post_completion_families()`.
    @param[in] post_cfg Argument passed to `collect_post_completion_families()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return Value returned by `collect_post_completion_families()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    output_dir_abs = _post_output_directory_abs(run_dir, post_cfg)
    families = []
 
    if _post_requests_eulerian_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('output_filename_prefix', 'Field'))
        families.append(_scan_post_vtk_steps(prefix, 'vts'))
 
    if _post_requests_particle_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('particle_filename_prefix', 'Particle'))
        families.append(_scan_post_vtk_steps(prefix, 'vtp'))
 
    for stats_path in get_post_statistics_output_artifacts(post_cfg, run_dir, monitor_cfg):
        families.append(_scan_post_statistics_csv_steps(stats_path))
 
    # Each window and format is its own family, so a run that produced the Eulerian
    # fields but not the statistics is not mistaken for a completed step.
    for kind, path in get_post_field_statistics_artifacts(post_cfg, run_dir):
        if kind == 'vtk':
            families.append(_scan_post_vtk_steps(path, 'vts'))
        else:
            families.append(_scan_post_statistics_csv_steps(path))
 
    return families
 
 
def detect_post_completed_frontier(run_dir: str, post_cfg: dict, monitor_cfg, start_step: int, end_step: int, step_interval: int) -> dict:
    """!
    @brief Detect the highest contiguous fully completed post step for the current recipe.
    @param[in] run_dir Argument passed to `detect_post_completed_frontier()`.
    @param[in] post_cfg Argument passed to `detect_post_completed_frontier()`.
    @param[in] monitor_cfg Argument passed to `detect_post_completed_frontier()`.
    @param[in] start_step Argument passed to `detect_post_completed_frontier()`.
    @param[in] end_step Argument passed to `detect_post_completed_frontier()`.
    @param[in] step_interval Argument passed to `detect_post_completed_frontier()`.
    @return Value returned by `detect_post_completed_frontier()`.
    """
    families = collect_post_completion_families(run_dir, post_cfg, monitor_cfg)
    frontier = None
    if families:
        for step in _iter_post_steps(start_step, end_step, step_interval):
            if all(step in family for family in families):
                frontier = step
            else:
                break
    return {
        'frontier_step': frontier,
        'artifact_family_count': len(families),
    }
 
 
def _nearest_step(steps: "set[int]", target: int):
    """!
    @brief Return the complete source step nearest to a target step.
    @param[in] steps Candidate step numbers.
    @param[in] target Target step number.
    @return Nearest candidate, or None when no candidates exist.
    """
    if not steps:
        return None
    return min(steps, key=lambda step: (abs(step - target), step))
 
 
def _format_optional_step(step) -> str:
    """!
    @brief Format an optional step number for user-facing diagnostics.
    @param[in] step Step number or None.
    @return Printable step text.
    """
    return 'none' if step is None else str(step)
 
 
def _scan_complete_source_steps(source_dir: str, monitor_cfg: dict, post_cfg: dict) -> "tuple[set[int], dict]":
    """!
    @brief Scan source artifacts and return steps with every file required by the recipe.
    @param[in] source_dir Source output root directory.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Tuple of complete source steps and source path metadata.
    """
    del monitor_cfg
    require_particles = _post_needs_particle_source(post_cfg)
    complete_steps = _scan_committed_checkpoint_steps(
        source_dir, require_particles=require_particles
    )
    return complete_steps, {
        'source_dir': os.path.abspath(source_dir),
        'require_particles': require_particles,
    }
 
 
def _expected_source_paths_for_step(step: int, source_scan: dict, post_cfg: dict) -> "list[str]":
    """!
    @brief Build required source file paths for a single post-processing step.
    @param[in] step Requested step number.
    @param[in] source_scan Metadata returned by `_scan_complete_source_steps()`.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Required source artifact paths.
    """
    del post_cfg
    bundle = _checkpoint_bundle_path(source_scan['source_dir'], step)
    paths = [os.path.join(bundle, 'checkpoint.meta'), os.path.join(bundle, 'COMMITTED')]
    if source_scan.get('require_particles'):
        paths.append(os.path.join(bundle, 'particles', 'position.dat'))
    return paths
 
 
def detect_post_source_frontier(source_dir: str, monitor_cfg: dict, post_cfg: dict, start_step: int, end_step: int, step_interval: int) -> dict:
    """!
    @brief Detect the highest contiguous fully available source step for live post-processing.
    @param[in] source_dir Argument passed to `detect_post_source_frontier()`.
    @param[in] monitor_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] post_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] start_step Argument passed to `detect_post_source_frontier()`.
    @param[in] end_step Argument passed to `detect_post_source_frontier()`.
    @param[in] step_interval Argument passed to `detect_post_source_frontier()`.
    @return Value returned by `detect_post_source_frontier()`.
    """
    diagnostic = {
        'first_requested_step': start_step,
        'first_incomplete_step': None,
        'missing_files_for_first_incomplete_step': [],
        'closest_complete_step_to_start': None,
        'closest_complete_step_to_end': None,
    }
    if step_interval <= 0 or end_step < start_step or not os.path.isdir(source_dir):
        return {
            'frontier_step': None,
            'diagnostic': diagnostic,
        }
 
    complete_steps, source_scan = _scan_complete_source_steps(source_dir, monitor_cfg, post_cfg)
    diagnostic['closest_complete_step_to_start'] = _nearest_step(complete_steps, start_step)
    diagnostic['closest_complete_step_to_end'] = _nearest_step(complete_steps, end_step)
 
    frontier = None
    for step in _iter_post_steps(start_step, end_step, step_interval):
        try:
            validate_committed_checkpoint(
                source_dir, step,
                require_particles=source_scan.get('require_particles', False),
            )
        except ValueError:
            expected_paths = _expected_source_paths_for_step(step, source_scan, post_cfg)
            diagnostic['first_incomplete_step'] = step
            diagnostic['missing_files_for_first_incomplete_step'] = [
                os.path.relpath(path, source_dir) for path in expected_paths if not os.path.isfile(path)
            ]
            if not diagnostic['missing_files_for_first_incomplete_step']:
                diagnostic['missing_files_for_first_incomplete_step'] = [
                    os.path.relpath(_checkpoint_bundle_path(source_dir, step), source_dir)
                    + ' (invalid bundle)'
                ]
            break
        frontier = step
    return {
        'frontier_step': frontier,
        'diagnostic': diagnostic,
    }
 
 
def persist_post_resume_state(run_dir: str, plan: dict, last_successful_requested_end_step=None):
    """!
    @brief Persist post resume lineage metadata for future --continue runs.
    @param[in] run_dir Argument passed to `persist_post_resume_state()`.
    @param[in] plan Argument passed to `persist_post_resume_state()`.
    @param[in] last_successful_requested_end_step Argument passed to `persist_post_resume_state()`.
    @return Value returned by `persist_post_resume_state()`.
    """
    state_path = plan.get("resume_state_path") or get_post_resume_state_path(run_dir)
    payload = {
        'schema_version': POST_RESUME_SCHEMA_VERSION,
        'run_id': plan.get('run_id'),
        'recipe_fingerprint': plan.get('recipe_fingerprint'),
        'recipe_signature': plan.get('recipe_signature'),
        'requested_start_step': plan.get('requested_start_step'),
        'requested_end_step': plan.get('requested_end_step'),
        'step_interval': plan.get('step_interval'),
        'source_directory': plan.get('source_data_directory'),
        'resume_match_source': plan.get('resume_match_source'),
        'last_successful_requested_end_step': last_successful_requested_end_step,
        'updated_at': datetime.now().isoformat(),
    }
    write_json_file(state_path, payload)
    return state_path
 
 
def _build_post_lock_wrapper_source() -> str:
    """!
    @brief Return the Python wrapper used to hold an exclusive post-stage lock.
    @return Value returned by `_build_post_lock_wrapper_source()`.
    """
    return """#!/usr/bin/env python3
import argparse
import fcntl
import json
import os
import socket
import subprocess
import sys
import time
 
 
def main():
    parser = argparse.ArgumentParser(description='PICurv post-stage lock wrapper')
    parser.add_argument('--lock-file', required=True)
    parser.add_argument('--metadata-file', required=True)
    parser.add_argument('--run-dir', required=True)
    parser.add_argument('--recipe-fingerprint', required=True)
    parser.add_argument('command', nargs=argparse.REMAINDER)
    args = parser.parse_args()
 
    command = list(args.command or [])
    if not command or command[0] != '--':
        parser.error("expected '-- <command ...>' after wrapper arguments")
    command = command[1:]
 
    os.makedirs(os.path.dirname(args.lock_file), exist_ok=True)
    fd = os.open(args.lock_file, os.O_RDWR | os.O_CREAT, 0o644)
    try:
        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except BlockingIOError:
        owner = None
        try:
            with open(args.metadata_file, 'r', encoding='utf-8') as handle:
                owner = json.load(handle)
        except Exception:
            owner = None
        if owner:
            print(
                f"[FATAL] Post stage already active for {args.run_dir} "
                f"(pid={owner.get('pid')}, host={owner.get('host')}, started_at={owner.get('started_at')}).",
                file=sys.stderr,
            )
        else:
            print(f"[FATAL] Post stage already active for {args.run_dir}.", file=sys.stderr)
        return 2
 
    metadata = {
        'pid': os.getpid(),
        'host': socket.gethostname(),
        'started_at': time.strftime('%Y-%m-%dT%H:%M:%S%z'),
        'run_dir': args.run_dir,
        'recipe_fingerprint': args.recipe_fingerprint,
        'command': command,
    }
    with open(args.metadata_file, 'w', encoding='utf-8') as handle:
        json.dump(metadata, handle, indent=2, sort_keys=True)
        handle.write('\\n')
 
    try:
        result = subprocess.run(command)
        return int(result.returncode)
    finally:
        try:
            os.remove(args.metadata_file)
        except FileNotFoundError:
            pass
        os.close(fd)
 
 
if __name__ == '__main__':
    raise SystemExit(main())
"""
 
 
def ensure_post_lock_wrapper(run_dir: str) -> str:
    """!
    @brief Ensure the lock wrapper exists for a run directory and return its path.
    @param[in] run_dir Argument passed to `ensure_post_lock_wrapper()`.
    @return Value returned by `ensure_post_lock_wrapper()`.
    """
    paths = get_post_lock_paths(run_dir)
    wrapper_path = paths['wrapper_path']
    content = _build_post_lock_wrapper_source()
    existing_content = None
    os.makedirs(os.path.dirname(wrapper_path), exist_ok=True)
    if os.path.isfile(wrapper_path):
        with open(wrapper_path, 'r', encoding='utf-8', errors='replace') as f:
            existing_content = f.read()
    if existing_content != content:
        with open(wrapper_path, 'w', encoding='utf-8') as f:
            f.write(content)
        os.chmod(wrapper_path, 0o755)
    return wrapper_path
 
 
def build_post_locked_command(run_dir: str, recipe_fingerprint: str, wrapped_command: list, create_wrapper: bool = True) -> "tuple[list, dict]":
    """!
    @brief Wrap a postprocessor command behind the run-dir-scoped lock wrapper.
    @param[in] run_dir Argument passed to `build_post_locked_command()`.
    @param[in] recipe_fingerprint Argument passed to `build_post_locked_command()`.
    @param[in] wrapped_command Argument passed to `build_post_locked_command()`.
    @param[in] create_wrapper Argument passed to `build_post_locked_command()`.
    @return Value returned by `build_post_locked_command()`.
    """
    lock_paths = get_post_lock_paths(run_dir)
    wrapper_path = ensure_post_lock_wrapper(run_dir) if create_wrapper else lock_paths['wrapper_path']
    command = [
        wrapper_path,
        '--lock-file', lock_paths['lock_file'],
        '--metadata-file', lock_paths['metadata_file'],
        '--run-dir', run_dir,
        '--recipe-fingerprint', recipe_fingerprint,
        '--',
    ] + list(wrapped_command)
    return command, lock_paths
 
 
def build_post_execution_plan(
    run_dir: str,
    run_id: str,
    case_cfg: dict,
    monitor_cfg: dict,
    post_cfg: dict,
    continue_requested: bool = False,
    allow_source_frontier_scan: bool = True,
) -> dict:
    """!
    @brief Resolve post resume/source-availability behavior into one execution plan.
    @param[in] run_dir Argument passed to `build_post_execution_plan()`.
    @param[in] run_id Argument passed to `build_post_execution_plan()`.
    @param[in] case_cfg Argument passed to `build_post_execution_plan()`.
    @param[in] monitor_cfg Argument passed to `build_post_execution_plan()`.
    @param[in] post_cfg Argument passed to `build_post_execution_plan()`.
    @param[in] continue_requested Argument passed to `build_post_execution_plan()`.
    @param[in] allow_source_frontier_scan Argument passed to `build_post_execution_plan()`.
    @return Value returned by `build_post_execution_plan()`.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    requested_start_step, requested_end_step, step_interval = resolve_post_requested_window(post_cfg, case_cfg)
    resolved_source_dir = _resolve_post_source_directory_preview(run_dir, monitor_cfg, post_cfg)
    resolved_post_cfg = prepare_effective_post_config(post_cfg, resolved_source_dir)
    recipe_cfg = build_post_recipe_config(resolved_post_cfg, monitor_cfg)
    recipe_signature, recipe_fingerprint = compute_post_recipe_fingerprint(recipe_cfg)
 
    state_path = get_post_resume_state_path(run_dir, resolved_post_cfg)
    state_payload = _read_json_if_exists(state_path)
    state_match = bool(isinstance(state_payload, dict) and state_payload.get('recipe_fingerprint') == recipe_fingerprint)
 
    legacy_post_run_path = os.path.join(run_dir, 'config', 'post.run')
    legacy_recipe_cfg = parse_post_recipe_file(legacy_post_run_path)
    legacy_recipe_signature = normalize_post_recipe_signature(legacy_recipe_cfg or {}) if legacy_recipe_cfg else None
    legacy_match = bool(legacy_recipe_signature and legacy_recipe_signature == recipe_signature)
 
    resume_recipe_match = False
    resume_match_source = None
    resume_bootstrapped = False
    if continue_requested:
        if state_match:
            resume_recipe_match = True
            resume_match_source = 'state'
        elif not state_payload and legacy_match:
            resume_recipe_match = True
            resume_match_source = 'legacy_post_run'
            resume_bootstrapped = True
 
    completion_info = detect_post_completed_frontier(
        run_dir,
        resolved_post_cfg,
        monitor_cfg,
        requested_start_step,
        requested_end_step,
        step_interval,
    )
    completed_frontier_step = completion_info['frontier_step']
    if completion_info['artifact_family_count'] == 0 and state_match:
        completed_frontier_step = _parse_int_loose(state_payload.get('last_successful_requested_end_step'))
 
    if continue_requested and resume_recipe_match and completed_frontier_step is not None:
        effective_start_step = completed_frontier_step + step_interval
    else:
        effective_start_step = requested_start_step
 
    source_frontier_step = None
    source_frontier_diagnostic = None
    source_frontier_deferred = not allow_source_frontier_scan
    skip_reason = None
    if effective_start_step > requested_end_step:
        skip_reason = 'already-complete-window'
        effective_end_step = requested_end_step
    elif allow_source_frontier_scan:
        source_frontier_info = detect_post_source_frontier(
            resolved_source_dir,
            monitor_cfg,
            resolved_post_cfg,
            effective_start_step,
            requested_end_step,
            step_interval,
        )
        source_frontier_step = source_frontier_info['frontier_step']
        source_frontier_diagnostic = source_frontier_info['diagnostic']
        if source_frontier_step is None or source_frontier_step < effective_start_step:
            if continue_requested and resume_recipe_match and completed_frontier_step is not None:
                skip_reason = 'already-caught-up-to-current-source-frontier'
            else:
                skip_reason = 'nothing-available-yet'
            effective_end_step = None
        else:
            effective_end_step = min(requested_end_step, source_frontier_step)
    else:
        effective_end_step = requested_end_step
 
    effective_post_cfg = None
    if skip_reason is None:
        effective_post_cfg = prepare_effective_post_config(
            post_cfg,
            resolved_source_dir,
            start_step=effective_start_step,
            end_step=effective_end_step,
        )
 
    return {
        'run_id': run_id,
        'continue_requested': bool(continue_requested),
        'requested_start_step': requested_start_step,
        'requested_end_step': requested_end_step,
        'step_interval': step_interval,
        'source_data_directory': resolved_source_dir,
        'recipe_config': recipe_cfg,
        'recipe_signature': recipe_signature,
        'recipe_fingerprint': recipe_fingerprint,
        'resume_state_path': state_path,
        'resume_state_payload': state_payload,
        'resume_recipe_match': resume_recipe_match,
        'resume_match_source': resume_match_source,
        'resume_bootstrapped': resume_bootstrapped,
        'completed_frontier_step': completed_frontier_step,
        'source_frontier_step': source_frontier_step,
        'source_frontier_diagnostic': source_frontier_diagnostic,
        'source_frontier_deferred': source_frontier_deferred,
        'effective_start_step': effective_start_step,
        'effective_end_step': effective_end_step,
        'skip_reason': skip_reason,
        'resolved_post_cfg': resolved_post_cfg,
        'effective_post_cfg': effective_post_cfg,
        'lock_paths': get_post_lock_paths(
            run_dir, ((resolved_post_cfg.get("_picurv_paths") or {}).get("recipe_id"))
        ),
    }
 
 
def needs_restart_source(case_cfg: dict, solver_cfg: dict) -> bool:
    """!
    @brief Return True when the solver requires restart data from disk.
    @details Correctly identifies that analytical + init + start_step > 0 does NOT
             need a restart source (C code never reads from restart_dir in that case).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @return True if a restart source (--restart-from or --continue) is required.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    euler_needs = (eulerian_source == "load") or (eulerian_source == "solve" and start_step > 0)
    particle_needs = (particle_restart_mode == "load")
    return euler_needs or particle_needs
 
 
def resolve_run_output_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the output data directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the output directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]))
 
 
def resolve_run_restart_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the restart staging directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the restart directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"]))
 
 
def compute_physical_case_identity(case_cfg: dict) -> str:
    """!
    @brief Compute the hidden identity used to guard in-place continuation.
    @details Run length/timestep controls and particle load-vs-init policy do
             not define the physical case. All other case.yml content does.
    @param[in] case_cfg Parsed case configuration.
    @return Lowercase SHA-256 identity of normalized physical-case content.
    """
    normalized = copy.deepcopy(case_cfg)
    if isinstance(normalized, dict):
        normalized.pop("run_control", None)
        particles = (((normalized.get("models") or {}).get("physics") or {}).get("particles"))
        if isinstance(particles, dict):
            particles.pop("restart_mode", None)
    payload = json.dumps(
        normalized, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()
 
 
def validate_continue_case_identity(run_dir: str, case_cfg: dict) -> None:
    """!
    @brief Reject in-place continuation when the physical case has changed.
    @param[in] run_dir Existing run directory being continued.
    @param[in] case_cfg Newly requested case configuration.
    @return None.
    """
    saved_case_path = os.path.join(run_dir, "config", "case.yml")
    if not os.path.isfile(saved_case_path):
        raise ValueError(f"--continue run is missing its saved case.yml: {saved_case_path}")
    saved_case = read_yaml_file(saved_case_path)
    if compute_physical_case_identity(saved_case) != compute_physical_case_identity(case_cfg):
        raise ValueError(
            "--continue cannot change the physical case. Change only run_control, "
            "solver.yml, monitor.yml, or post.yml; use --restart-from for a new case branch."
        )
 
 
def populate_restart_directory(source_output: str, target_restart: str, start_step: int,
                               monitor_cfg: dict, end_step: "int | None" = None,
                               materialize: bool = True):
    """!
    @brief Atomically materialize an immutable checkpoint interval into a run.
    @param[in] source_output Path to the source output directory containing checkpoint data.
    @param[in] target_restart Path to the target restart directory to populate.
    @param[in] start_step First checkpoint step to materialize.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @param[in] end_step Optional inclusive last checkpoint step.
    @param[in] materialize Whether to copy the bundles, or only validate and resolve
               the path a real run would use. The dry-run planner needs the second:
               it reports what a run would refuse, and promises to write nothing.
    @return Canonical restart root containing committed checkpoint bundles.
    """
    del monitor_cfg
    checkpoints_root = os.path.join(os.path.abspath(target_restart), "checkpoints")
    if materialize:
        os.makedirs(checkpoints_root, exist_ok=True)
    final_step = start_step if end_step is None else end_step
    if final_step < start_step:
        raise ValueError("Restart checkpoint interval end must not precede its start.")
    for step in range(start_step, final_step + 1):
        source = validate_committed_checkpoint(source_output, step)["bundle"]
        if not materialize:
            continue
        destination = os.path.join(
            checkpoints_root, f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}"
        )
        if os.path.isdir(destination):
            validate_committed_checkpoint(destination, step)
            print(f"[INFO] Reusing committed restart bundle: {destination}")
            continue
        temporary = os.path.join(
            checkpoints_root,
            f".step_{step:0{CHECKPOINT_STEP_WIDTH}d}.copying.{os.getpid()}",
        )
        if os.path.exists(temporary):
            raise ValueError(f"Restart staging path already exists: {temporary}")
        try:
            os.makedirs(temporary)
            for current, dirnames, filenames in os.walk(source):
                relative = os.path.relpath(current, source)
                target_dir = temporary if relative == "." else os.path.join(temporary, relative)
                os.makedirs(target_dir, exist_ok=True)
                for dirname in dirnames:
                    os.makedirs(os.path.join(target_dir, dirname), exist_ok=True)
                for filename in filenames:
                    _materialize_asset_file(
                        os.path.join(current, filename), os.path.join(target_dir, filename)
                    )
            validate_committed_checkpoint(temporary, step)
            os.replace(temporary, destination)
        except Exception:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary)
            raise
        print(f"[INFO] Materialized committed restart bundle for step {step}: {destination}")
    return os.path.abspath(target_restart)
 
 
def validate_eulerian_checkpoint(source_dir: str, step: int, monitor_cfg: dict):
    """!
    @brief Validate the mandatory Eulerian field set required by `ReadSimulationFields()`.
    @param[in] source_dir Root directory containing the Eulerian subdirectory.
    @param[in] step Checkpoint step to validate.
    @param[in] monitor_cfg Monitor configuration defining the Eulerian subdirectory.
    @return Validated checkpoint description.
    @throws ValueError if any mandatory Eulerian field is absent.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, step)
 
 
def detect_last_checkpoint_step(output_dir: str):
    """!
    @brief Scan output directory for the highest step number available.
    @details Ignores incomplete temporary directories and invalid bundles.
    @param[in] output_dir Path to the output directory.
    @return The highest step number found, or None if no checkpoints exist.
    """
    steps = _scan_committed_checkpoint_steps(output_dir)
    return max(steps) if steps else None
 
 
def detect_case_completion_status(run_dir: str, monitor_cfg: dict, target_final_step: int) -> dict:
    """!
    @brief Determine whether a study case is complete, partially complete, or empty.
    @param[in] run_dir Path to the case run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] target_final_step The step number the case should reach for completion.
    @return Dictionary with keys 'last_step' (int or None), 'target_step' (int),
            and 'status' ('complete', 'partial', or 'empty').
    """
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    last_step = detect_last_checkpoint_step(output_dir)
    if last_step is not None and last_step >= target_final_step:
        status = "complete"
    elif last_step is not None:
        status = "partial"
    else:
        status = "empty"
    return {"last_step": last_step, "target_step": target_final_step, "status": status}
 
 
def validate_load_mode_step_range(source_output: str, start_step: int, total_steps: int, monitor_cfg: dict):
    """!
    @brief Validate that all required eulerian step files exist for "load" mode.
    @details Checks that ufield files exist for every step from start_step through
             start_step + total_steps (inclusive). Reports missing steps clearly.
    @param[in] source_output Path to the output directory containing eulerian data.
    @param[in] start_step First step that will be loaded.
    @param[in] total_steps Number of steps to run.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    """
    missing = []
    for step in range(start_step, start_step + total_steps + 1):
        try:
            validate_eulerian_checkpoint(source_output, step, monitor_cfg)
        except ValueError:
            missing.append(step)
 
    if missing:
        sample = missing[:3] + (["..."] if len(missing) > 6 else []) + missing[-3:]
        raise ValueError(
            f"Eulerian 'load' mode: {len(missing)} committed checkpoint(s) missing in {source_output}. "
            f"Missing steps include: {sample}"
        )
 
 
def validate_particle_checkpoint(source_dir: str, start_step: int, monitor_cfg: dict):
    """!
    @brief Validate that particle checkpoint files exist for the given step.
    @details Checks that at least a position file exists at the expected step in
             the particle subdirectory.
    @param[in] source_dir Path to the directory containing the particle subdirectory.
    @param[in] start_step The step number whose particle checkpoint is expected.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @return Validated checkpoint description.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, start_step, require_particles=True)
 
 
def read_monitor_from_run(run_dir: str) -> dict:
    """!
    @brief Read the monitor.yml from a run directory's config/ subdirectory.
    @param[in] run_dir Path to the run directory.
    @return Parsed monitor YAML dictionary.
    """
    monitor_path = os.path.join(run_dir, "config", "monitor.yml")
    if not os.path.isfile(monitor_path):
        raise ValueError(f"Run directory is missing config/monitor.yml: {monitor_path}")
    return read_yaml_file(monitor_path)
 
 
def resolve_latest_restart_run(case_cfg: dict, case_path: str, start_step: int) -> str:
    """!
    @brief Select the newest local workspace run compatible with a requested restart.
    @param[in] case_cfg Current case configuration.
    @param[in] case_path Current case path.
    @param[in] start_step Required committed checkpoint.
    @return Absolute source run directory.
    """
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError("--from latest requires an initialized workspace.")
    current_graph = build_case_asset_graph(case_cfg, case_path)
    current_grid = next(
        (item for item in current_graph.get("providers", []) if item.get("kind") == "grid"),
        None,
    )
    candidates = []
    for candidate in Path(workspace_root, "runs").iterdir():
        if not candidate.is_dir():
            continue
        manifest = _read_json_if_exists(str(candidate / "manifest.json")) or {}
        lock = read_yaml_file(str(candidate / "inputs" / "assets.lock.yml")) \
            if (candidate / "inputs" / "assets.lock.yml").is_file() else {}
        locked_grid = (lock.get("assets") or {}).get("grid")
        runtime_grid = (lock.get("runtime_providers") or {}).get("grid")
        if current_grid:
            recorded_hash = None
            if isinstance(locked_grid, dict):
                recorded_hash = locked_grid.get("provider_spec_sha256")
            elif isinstance(runtime_grid, dict):
                recorded_hash = runtime_grid.get("provider_spec_sha256")
            if recorded_hash and recorded_hash != current_grid.get("spec_sha256"):
                continue
        output_root = candidate / CANONICAL_RUN_PATHS["output"]
        try:
            validate_committed_checkpoint(str(output_root), start_step)
        except (OSError, ValueError):
            continue
        ordering = manifest.get("updated_at") or manifest.get("created_at") or ""
        candidates.append((ordering, candidate.stat().st_mtime_ns, str(candidate)))
    if not candidates:
        raise ValueError(
            f"No local workspace run has a compatible committed checkpoint at step {start_step}. "
            "Restore a run from storage first, or name one explicitly with --from <run-dir>."
        )
    candidates.sort(reverse=True)
    selected = candidates[0][2]
    print(f"[INFO] Selected latest compatible restart run: {os.path.relpath(selected, workspace_root)}")
    return selected
 
 
def resolve_restart_source(args, case_cfg: dict, solver_cfg: dict, monitor_cfg: dict,
                           run_dir: str, materialize: bool = True):
    """!
    @brief Resolve the restart source directory based on --restart-from or --continue CLI flags.
    @details Implements the full restart resolution logic including smart resolution for
             --continue (checks restart/ first for user-curated data, falls back to output/)
             and direct reference for eulerian "load" mode.
    @param[in] args Parsed CLI arguments (must have restart_from, continue_run, run_dir attrs).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] run_dir Path to the current run directory.
    @param[in] materialize Whether to copy restart bundles into the run. The dry-run
               planner passes False: it still validates and resolves, but writes nothing.
    @return Tuple of (restart_source_dir, continue_mode, lineage) where restart_source_dir
            is the resolved path (or None), continue_mode is a boolean, and lineage is the
            branch provenance record from `build_run_lineage()`, or None when this run did
            not branch from another.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    try:
        total_steps = int(case_cfg.get("run_control", {}).get("total_steps", 0) or 0)
    except (TypeError, ValueError):
        total_steps = 0
 
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
 
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    particle_needs = (particle_restart_mode == "load")
 
    requires_source = needs_restart_source(case_cfg, solver_cfg)
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
 
    if restart_from and continue_run:
        raise ValueError("--restart-from and --continue are mutually exclusive.")
 
    if continue_run and start_step <= 0:
        raise ValueError(
            "--continue with --solve requires run_control.start_step > 0; "
            "start_step=0 is a fresh start. Omit --continue to start a fresh run."
        )
 
    if restart_from:
        requested_restart_source = str(restart_from)
        if str(restart_from).strip().lower() == "latest":
            restart_from = resolve_latest_restart_run(
                case_cfg, getattr(args, "case", "case.yml"), start_step
            )
        # A branch may follow a different physical trajectory than the samples already
        # collected, so the retention of the parent's windows is the user's decision and
        # not a default's. Silently resetting reports a sample count that describes a
        # shorter average than the user expects; silently carrying averages two
        # different flows together. Neither is safe to guess, so the flag is required
        # whenever there are windows to decide about.
        requested_statistics_state = getattr(args, "statistics_state", None)
        statistics_enabled = normalize_field_statistics_config(monitor_cfg or {})["enabled"]
        if requested_statistics_state is None:
            if statistics_enabled:
                raise ValueError(
                    "A branched restart of a run with field_statistics.enabled: true must "
                    "state what happens to the parent's accumulated windows. Pass "
                    "--statistics-state reset to discard them and start the averages over, "
                    "or --statistics-state carry to resume compatible saved window state."
                )
            requested_statistics_state = "reset"
        statistics_state = str(requested_statistics_state).lower()
        if statistics_state == "carry" and not statistics_enabled:
            raise ValueError("--statistics-state carry requires field_statistics.enabled: true.")
 
        # === MODE 1: New run, restart from another run ===
        source_run = os.path.abspath(restart_from)
        if not os.path.isdir(source_run):
            raise ValueError(f"--restart-from run directory does not exist: {source_run}")
        try:
            require_storage_payload_local(source_run, "--restart-from", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        source_monitor = read_monitor_from_run(source_run)
        source_output = resolve_run_output_dir(source_run, source_monitor)
        if not os.path.isdir(source_output):
            raise ValueError(f"Source output directory does not exist: {source_output}")
        lineage = build_run_lineage(
            source_run, start_step,
            workspace_root=find_workspace_root(run_dir),
            statistics_state=statistics_state,
            requested_source=requested_restart_source,
        )
 
        if not requires_source:
            # R7: analytical + init — warn that --restart-from is unused
            print(
                "[WARN] --restart-from specified but no data will be read "
                "(analytical + init does not need restart data).",
                file=sys.stderr,
            )
            return None, False, None
 
        if eulerian_source == "load":
            # A load-mode run may consume a complete saved sequence. Materialize it
            # into this run so storage never depends on another run remaining local.
            validate_load_mode_step_range(source_output, start_step, total_steps, source_monitor)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
        else:
            # Materialize one immutable bundle into the new run's restart input.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
 
    elif continue_run:
        # === MODE 2: Continue in-place ===
        continue_run_dir = getattr(args, 'run_dir', None)
        if not continue_run_dir:
            raise ValueError(RESTART_RUN_DIR_REQUIRED_MESSAGE)
        continue_run_dir = os.path.abspath(continue_run_dir)
        if not os.path.isdir(continue_run_dir):
            raise ValueError(f"--run-dir does not exist: {continue_run_dir}")
        try:
            require_storage_payload_local(continue_run_dir, "--continue", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        validate_continue_case_identity(continue_run_dir, case_cfg)
 
        source_output = resolve_run_output_dir(continue_run_dir, monitor_cfg)
        # Warn if start_step != last checkpoint
        last_step = detect_last_checkpoint_step(source_output)
        if last_step is not None and last_step != start_step:
            print(
                f"[WARN] start_step={start_step} but last checkpoint in output is step {last_step}.",
                file=sys.stderr,
            )
 
        if eulerian_source == "load":
            # Preserve the saved sequence under the run's immutable restart input.
            validate_load_mode_step_range(source_output, start_step, total_steps, monitor_cfg)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, True, None
        elif not requires_source:
            # C6: analytical + init — only log-append behavior, no data needed
            return None, True, None
        else:
            # In-place continuation also uses the fixed restart-input home. Reflink or
            # hardlink materialization normally makes this metadata-cheap.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            validate_committed_checkpoint(
                restart_root if materialize else source_output, start_step,
                require_particles=particle_needs,
            )
            return restart_root, True, None
 
    elif requires_source:
        raise ValueError(
            "Restart data required but no source specified. Use:\n"
            "  --restart-from <run_dir>  (new run from another run's data)\n"
            "  --continue --run-dir <run_dir>  (resume in same directory)"
        )
 
    return None, False, None
 
def absolutize_case_external_paths(case_cfg: dict, case_anchor_path: str):
    """!
    @brief Convert external grid/generator paths in case config to absolute paths.
    @param[in] case_cfg Argument passed to `absolutize_case_external_paths()`.
    @param[in] case_anchor_path Argument passed to `absolutize_case_external_paths()`.
    """
    # Initialized workspaces deliberately keep portable, root-relative paths in
    # every materialized study member.  The run/study directory remains below
    # the workspace, so normal resolution can still find the owning manifest.
    if find_workspace_root(case_anchor_path):
        return
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
    mode = grid_cfg.get("mode")
    if mode == "file":
        source_file = grid_cfg.get("source_file")
        if isinstance(source_file, str):
            grid_cfg["source_file"] = resolve_path(case_anchor_path, source_file)
    elif mode == "grid_gen":
        gen = grid_cfg.get("generator", {})
        if isinstance(gen, dict):
            for key in ("script", "config_file"):
                val = gen.get(key)
                if isinstance(val, str):
                    gen[key] = resolve_path(case_anchor_path, val)
    ic = (case_cfg.get("properties", {}) or {}).get("initial_conditions", {})
    if isinstance(ic, dict):
        if str(ic.get("mode", "")).strip().lower() == "file":
            source_file = ic.get("source_file")
            if isinstance(source_file, str):
                ic["source_file"] = resolve_path(case_anchor_path, source_file)
        elif str(ic.get("generator", "")).strip().lower() == "ic_gen":
            params = ic.get("params", {})
            if isinstance(params, dict):
                for key in ("script", "config_file"):
                    value = params.get(key)
                    if isinstance(value, str):
                        params[key] = resolve_path(case_anchor_path, value)
    boundary_conditions = case_cfg.get("boundary_conditions", [])
    blocks = boundary_conditions if boundary_conditions and isinstance(boundary_conditions[0], list) else [boundary_conditions]
    for block in blocks:
        if not isinstance(block, list):
            continue
        for bc in block:
            if not isinstance(bc, dict) or str(bc.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = ((bc.get("params") or {}).get("source") or {})
            if not isinstance(source, dict):
                continue
            source_type = str(source.get("type", "")).strip().lower()
            if source_type == "file":
                keys = ("path",)
            elif source_type == "generated":
                keys = ("script",)
            elif source_type == "field_slice":
                keys = ("script", "field_file", "grid_file", "source_case")
            else:
                keys = ()
            for key in keys:
                value = source.get(key)
                if isinstance(value, str):
                    source[key] = resolve_path(case_anchor_path, value)
 
 
def prepare_case_for_continuation(run_dir: str, case_id: str, last_step: int,
                                   target_final_step: int, cluster_cfg: dict):
    """!
    @brief Set up a partially-completed study case for continuation in-place.
    @details Updates the case config with new start_step/total_steps, sets particle
             restart_mode to 'load' if checkpoint exists, populates the restart
             directory, and regenerates the solver control file with continue_mode.
             Delegates all restart resolution to resolve_restart_source().
    @param[in] run_dir Path to the case run directory.
    @param[in] case_id The case identifier (e.g. 'case_0002').
    @param[in] last_step The last checkpoint step found in the output directory.
    @param[in] target_final_step The step number the case should reach for completion.
    @param[in] cluster_cfg Parsed cluster YAML dictionary (for num_procs, walltime guard).
    @return The absolute path to the regenerated control file.
    """
    config_dir = os.path.join(run_dir, "config")
    case_cfg = read_yaml_file(os.path.join(config_dir, "case.yml"))
    solver_cfg = read_yaml_file(os.path.join(config_dir, "solver.yml"))
    monitor_cfg = read_yaml_file(os.path.join(config_dir, "monitor.yml"))
 
    remaining = target_final_step - last_step
    case_cfg["run_control"]["start_step"] = last_step
    case_cfg["run_control"]["total_steps"] = remaining
    print(f"[INFO] {case_id}: updating start_step={last_step}, total_steps={remaining}")
 
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    particles_cfg = (case_cfg.get("models", {}).get("physics", {}) or {}).get("particles")
    checkpoint_has_particles = False
    try:
        checkpoint_has_particles = validate_committed_checkpoint(
            output_dir, last_step, require_particles=True
        )["has_particles"]
    except ValueError:
        checkpoint_has_particles = False
    if particles_cfg is not None and checkpoint_has_particles:
        current_mode = str(particles_cfg.get("restart_mode", "init")).strip().lower()
        if current_mode != "load":
            particles_cfg["restart_mode"] = "load"
            print(f"[INFO] {case_id}: setting particle restart_mode='load' (checkpoint found)")
 
    write_yaml_file(os.path.join(config_dir, "case.yml"), case_cfg)
 
    mock_args = argparse.Namespace(restart_from=None, continue_run=True, run_dir=run_dir)
    restart_source_dir, continue_mode, _lineage = resolve_restart_source(
        mock_args, case_cfg, solver_cfg, monitor_cfg, run_dir
    )
 
    source_files = {
        'Case': os.path.join(config_dir, "case.yml"),
        'Solver': os.path.join(config_dir, "solver.yml"),
        'Monitor': os.path.join(config_dir, "monitor.yml"),
    }
    monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    configs = {
        "case": case_cfg, "case_path": source_files['Case'],
        "solver": solver_cfg, "solver_path": source_files['Solver'],
        "monitor": monitor_cfg, "monitor_path": source_files['Monitor'],
        "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
    }
    control_file = generate_solver_control_file(
        run_dir, case_id, configs, cluster_tasks, monitor_files,
        restart_source_dir=restart_source_dir, continue_mode=continue_mode,
    )
    print(f"[SUCCESS] {case_id}: regenerated control file for continuation")
    return control_file
 
 
def is_valid_email(email: str) -> bool:
    """!
    @brief Lightweight email validation for scheduler notifications.
    @param[in] email Argument passed to `is_valid_email()`.
    @return Value returned by `is_valid_email()`.
    """
    if not isinstance(email, str):
        return False
    pattern = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
    return re.match(pattern, email.strip()) is not None
 
def normalize_statistics_task(task_name: str) -> str:
    """!
    @brief Normalizes user-facing statistics task names to C pipeline keywords.
    @param[in] task_name Task name from YAML.
    @return Canonical keyword accepted by C statistics pipeline.
    @throws ValueError if task is unsupported.
    """
    # Only implemented statistics kernels belong here.
    if task_name is None:
        raise ValueError("statistics task cannot be None")
    normalized = str(task_name).strip().lower().replace("-", "_").replace(" ", "_")
    if normalized != "msd":
        raise ValueError(f"Unsupported statistics task '{task_name}'. Currently supported: 'msd'.")
    return "ComputeMSD"
 
def _iter_nonempty_noncomment_lines(file_obj):
    """!
    @brief Yield (lineno, stripped_line) for non-empty, non-comment lines.
    @param[in] file_obj Argument passed to `_iter_nonempty_noncomment_lines()`.
    """
    for lineno, raw in enumerate(file_obj, start=1):
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        yield lineno, line
 
PICGRID_FLOAT_FORMAT = ".17e"
 
 
def format_picgrid_coordinate(value: float) -> str:
    """!
    @brief Format a coordinate with round-trip-safe binary64 precision.
    @param[in] value Coordinate value.
    @return Formatted coordinate.
    """
    return format(value, PICGRID_FLOAT_FORMAT)
 
 
def validate_and_nondimensionalize_picgrid(source_grid: str, dest_grid: str, L_ref: float, expected_nblk: int = None) -> dict:
    """!
    @brief Validates PICGRID payload and writes a non-dimensionalized copy.
    @details Requires canonical PICGRID input with leading "PICGRID" token.
             Output is always written in canonical PICGRID format with header and per-block dims.
    @param[in] source_grid Input grid file path.
    @param[in] dest_grid Output grid file path.
    @param[in] L_ref Reference length for non-dimensionalization.
    @param[in] expected_nblk Optional expected block count.
    @return Summary dictionary with nblk, dims, and total_nodes.
    @throws ValueError on malformed grid.
    """
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero when processing grid coordinates.")
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
 
        if first_token != "PICGRID":
            raise ValueError(
                f"Grid file '{source_grid}' must begin with the canonical PICGRID header token."
            )
        try:
            _, nblk_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
 
        try:
            nblk = int(nblk_line)
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(
                f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}."
            )
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
        total_nodes_expected = sum(im * jm * km for (im, jm, km) in dims)
        os.makedirs(os.path.dirname(dest_grid), exist_ok=True)
        with open(dest_grid, "w") as fout:
            fout.write("PICGRID\n")
            fout.write(f"{nblk}\n")
            for (im, jm, km) in dims:
                fout.write(f"{im} {jm} {km}\n")
 
            total_nodes_seen = 0
            for lineno, coord_line in line_iter:
                parts = coord_line.split()
                if len(parts) != 3:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Expected 3 floats, got: '{coord_line}'."
                    )
                try:
                    x = float(parts[0]) / L_ref
                    y = float(parts[1]) / L_ref
                    z = float(parts[2]) / L_ref
                except ValueError:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Non-numeric values: '{coord_line}'."
                    )
                total_nodes_seen += 1
                if total_nodes_seen > total_nodes_expected:
                    raise ValueError(
                        f"Grid file '{source_grid}' has more coordinates ({total_nodes_seen}) than expected ({total_nodes_expected})."
                    )
                fout.write(
                    f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                    f"{format_picgrid_coordinate(z)}\n"
                )
 
        if total_nodes_seen != total_nodes_expected:
            raise ValueError(
                f"Grid file '{source_grid}' has {total_nodes_seen} coordinates, expected {total_nodes_expected} from header."
            )
 
    return {"nblk": nblk, "dims": dims, "total_nodes": total_nodes_expected}
 
def read_picgrid_header_dimensions(source_grid: str, expected_nblk: int = None) -> list:
    """!
    @brief Read only the canonical PICGRID header dimensions.
    @param[in] source_grid Input grid file path.
    @param[in] expected_nblk Optional expected block count.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError on malformed header.
    """
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
        if first_token != "PICGRID":
            raise ValueError(f"Grid file '{source_grid}' must begin with the canonical PICGRID header token.")
 
        try:
            _, nblk_line = next(line_iter)
            nblk = int(nblk_line)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}.")
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
    return dims
 
def validate_and_nondimensionalize_picslice(source_slice: str, dest_slice: str, U_ref: float,
                                            expected_dims: tuple = None) -> dict:
    """!
    @brief Validate a canonical PICSLICE payload and write a solver-scale copy.
    @param[in] source_slice Input PICSLICE path.
    @param[in] dest_slice Output staged PICSLICE path.
    @param[in] U_ref Reference velocity for non-dimensionalization.
    @param[in] expected_dims Optional expected (n1, n2) slice dimensions.
    @return Summary dictionary with frame_count, dims, value_count, min_speed, max_speed.
    @throws ValueError on malformed slice.
    """
    if U_ref == 0.0:
        raise ValueError("velocity_ref must be non-zero when processing PICSLICE speeds.")
    if not os.path.isfile(source_slice):
        raise ValueError(f"PICSLICE file not found: {source_slice}")
 
    with open(source_slice, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' is empty.")
        if first_token != "PICSLICE":
            raise ValueError(f"PICSLICE file '{source_slice}' must begin with the canonical PICSLICE header token.")
 
        try:
            _, frame_line = next(line_iter)
            frame_count = int(frame_line)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing frame count after PICSLICE header.")
        except ValueError:
            raise ValueError(f"Invalid frame count '{frame_line}' in PICSLICE file '{source_slice}'.")
        if frame_count != 1:
            raise ValueError(
                f"PICSLICE file '{source_slice}' has frame count {frame_count}; Phase 1 supports exactly 1."
            )
 
        try:
            lineno, dim_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing slice dimensions.")
        parts = dim_line.split()
        if len(parts) != 2:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Expected 2 integers, got: '{dim_line}'."
            )
        try:
            n1, n2 = (int(parts[0]), int(parts[1]))
        except ValueError:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Non-integer values: '{dim_line}'."
            )
        if n1 <= 0 or n2 <= 0:
            raise ValueError(f"Invalid PICSLICE dimensions at {source_slice}:{lineno}: ({n1}, {n2}). Must be > 0.")
        if expected_dims is not None and (n1, n2) != tuple(expected_dims):
            raise ValueError(
                f"PICSLICE dimension mismatch for '{source_slice}': expected {tuple(expected_dims)}, found {(n1, n2)}."
            )
 
        values = []
        for lineno, value_line in line_iter:
            parts = value_line.split()
            if len(parts) != 1:
                raise ValueError(
                    f"Invalid PICSLICE value row at {source_slice}:{lineno}. Expected 1 float, got: '{value_line}'."
                )
            try:
                value = float(parts[0])
            except ValueError:
                raise ValueError(f"Invalid PICSLICE value at {source_slice}:{lineno}: '{value_line}'.")
            if not math.isfinite(value):
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be finite.")
            if value < 0.0:
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be nonnegative.")
            values.append(value)
 
    expected_count = n1 * n2
    if len(values) != expected_count:
        raise ValueError(
            f"PICSLICE file '{source_slice}' has {len(values)} values, expected {expected_count} from dimensions {(n1, n2)}."
        )
 
    os.makedirs(os.path.dirname(dest_slice), exist_ok=True)
    with open(dest_slice, "w") as fout:
        fout.write("PICSLICE\n")
        fout.write("1\n")
        fout.write(f"{n1} {n2}\n")
        for value in values:
            fout.write(f"{value / U_ref:.8e}\n")
 
    return {
        "frame_count": frame_count,
        "dims": (n1, n2),
        "value_count": len(values),
        "min_speed": min(values) if values else 0.0,
        "max_speed": max(values) if values else 0.0,
    }
 
def _face_artifact_token(face: str) -> str:
    """!
    @brief Convert a BC face token into a filesystem-friendly artifact token.
    @param[in] face Canonical face token such as -Zeta.
    @return Filesystem-friendly face token.
    """
    return face.replace("+", "pos").replace("-", "neg")
 
def _resolve_run_artifact_path(run_dir: str, configured_path: str, default_path: str,
                               default_to_config_dir: bool = False) -> str:
    """!
    @brief Resolve a run artifact path with run-dir-relative defaults.
    @param[in] run_dir Run/precompute directory root.
    @param[in] configured_path Optional user-provided artifact path.
    @param[in] default_path Default path relative to run_dir.
    @param[in] default_to_config_dir If true, bare relative names are placed under config/.
    @return Absolute artifact path.
    """
    path = configured_path if configured_path else default_path
    if not isinstance(path, str) or not path.strip():
        raise ValueError("generated profile output_file must be a non-empty path when provided.")
    path = path.strip()
    if os.path.isabs(path):
        return os.path.abspath(path)
    if default_to_config_dir and os.path.dirname(path) == "":
        path = os.path.join("config", path)
    return os.path.abspath(os.path.join(run_dir, path))
 
def _resolve_generator_script(configured_script: str, case_path: str, default_name: str) -> str:
    """!
    @brief Resolve an optional generator script override or repository default.
    @param[in] configured_script Optional absolute or case-relative script path.
    @param[in] case_path Current case.yml path used to anchor relative overrides.
    @param[in] default_name Repository generator filename under GENERATORS_PATH.
    @return Absolute generator script path.
    """
    if configured_script is None:
        return os.path.join(GENERATORS_PATH, default_name)
    if not isinstance(configured_script, str) or not configured_script.strip():
        raise ValueError(f"Generator script override for {default_name} must be a non-empty path.")
    script = configured_script.strip()
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    return _resolve_case_relative_path(script, case_dir)
 
def _normalize_square_duct_poiseuille_params(params, field_name: str) -> dict:
    """!
    @brief Validate square-duct Poiseuille generator parameters.
    @param[in] params Generator params mapping.
    @param[in] field_name Human-readable YAML field name for diagnostics.
    @return Normalized params.
    """
    if params is None:
        params = {}
    if not isinstance(params, dict):
        raise ValueError(f"{field_name}.params must be a mapping when provided.")
    unknown = sorted(set(params.keys()) - {"bulk_velocity", "n_terms"})
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}.params: {unknown}. Allowed: ['bulk_velocity', 'n_terms'].")
    bulk_velocity = _to_float(params.get("bulk_velocity", 1.0), f"{field_name}.params.bulk_velocity")
    if bulk_velocity <= 0.0:
        raise ValueError(f"{field_name}.params.bulk_velocity must be positive.")
    try:
        n_terms = int(params.get("n_terms", 101))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    if n_terms <= 0 or n_terms % 2 == 0:
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    return {"bulk_velocity": bulk_velocity, "n_terms": n_terms}
 
GENERATED_PROFILE_GENERATORS = {"square_duct_poiseuille"}
 
def _normalize_field_slice_source(source, field_name: str) -> dict:
    """!
    @brief Validate a prescribed_flow field_slice source block.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    """
    allowed = {
        "type",
        "script",
        "field_file",
        "grid_file",
        "source_case",
        "velocity_scale",
        "source_block",
        "output_file",
        "slice",
    }
    unknown = sorted(set(source.keys()) - allowed)
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: {sorted(allowed)}.")
    field_file = source.get("field_file")
    grid_file = source.get("grid_file")
    if not isinstance(field_file, str) or not field_file.strip():
        raise ValueError(f"{field_name}.field_file must be a non-empty path.")
    if not isinstance(grid_file, str) or not grid_file.strip():
        raise ValueError(f"{field_name}.grid_file must be a non-empty path.")
    if source.get("source_case") is None and source.get("velocity_scale") is None:
        raise ValueError(f"{field_name} requires source_case or velocity_scale.")
 
    normalized = {
        "type": "field_slice",
        "field_file": field_file.strip(),
        "grid_file": grid_file.strip(),
        "slice": _normalize_field_slice_selector(source.get("slice"), f"{field_name}.slice"),
    }
    if source.get("script") is not None:
        script = source.get("script")
        if not isinstance(script, str) or not script.strip():
            raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
        normalized["script"] = script.strip()
    if source.get("source_case") is not None:
        source_case = source.get("source_case")
        if not isinstance(source_case, str) or not source_case.strip():
            raise ValueError(f"{field_name}.source_case must be a non-empty path when provided.")
        normalized["source_case"] = source_case.strip()
    if source.get("velocity_scale") is not None:
        velocity_scale = _to_float(source.get("velocity_scale"), f"{field_name}.velocity_scale")
        if velocity_scale <= 0.0:
            raise ValueError(f"{field_name}.velocity_scale must be positive.")
        normalized["velocity_scale"] = velocity_scale
    if source.get("source_block") is not None:
        try:
            source_block = int(source.get("source_block"))
        except (TypeError, ValueError):
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        if source_block < 0:
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        normalized["source_block"] = source_block
    if source.get("output_file") is not None:
        output_file = source.get("output_file")
        if not isinstance(output_file, str) or not output_file.strip():
            raise ValueError(f"{field_name}.output_file must be a non-empty path when provided.")
        normalized["output_file"] = output_file.strip()
    return normalized
 
def _normalize_field_slice_selector(slice_cfg, field_name: str) -> dict:
    """!
    @brief Validate the field_slice slice selector.
    @param[in] slice_cfg Slice selector mapping.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized selector mapping.
    """
    if not isinstance(slice_cfg, dict):
        raise ValueError(f"{field_name} must be a mapping.")
    orientation = str(slice_cfg.get("orientation", "opposite")).strip().lower()
    if orientation not in {"opposite", "same"}:
        raise ValueError(f"{field_name}.orientation must be 'opposite' or 'same'.")
    normal_tolerance = _to_float(slice_cfg.get("normal_tolerance", 0.99), f"{field_name}.normal_tolerance")
    if normal_tolerance <= 0.0 or normal_tolerance > 1.0:
        raise ValueError(f"{field_name}.normal_tolerance must be in the range (0, 1].")
 
    if slice_cfg.get("face") is not None:
        unknown = sorted(set(slice_cfg.keys()) - {"face", "orientation", "normal_tolerance"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Use either face or axis/index/normal, plus orientation/normal_tolerance."
            )
        face = str(slice_cfg.get("face", "")).strip()
        if face.lower() not in BC_FACE_MAP:
            raise ValueError(f"{field_name}.face must be one of {sorted(BC_FACE_MAP.values())}.")
        return {
            "face": BC_FACE_MAP[face.lower()],
            "orientation": orientation,
            "normal_tolerance": normal_tolerance,
        }
 
    required = {"axis", "index", "normal"}
    missing = sorted(key for key in required if slice_cfg.get(key) is None)
    if missing:
        raise ValueError(f"{field_name} requires either face or axis/index/normal; missing {missing}.")
    unknown = sorted(set(slice_cfg.keys()) - {"axis", "index", "normal", "orientation", "normal_tolerance"})
    if unknown:
        raise ValueError(
            f"Unknown keys in {field_name}: {unknown}. "
            "Use either face or axis/index/normal, plus orientation/normal_tolerance."
        )
    axis = str(slice_cfg.get("axis", "")).strip()
    axis_map = {"xi": "Xi", "eta": "Eta", "zeta": "Zeta"}
    if axis.lower() not in axis_map:
        raise ValueError(f"{field_name}.axis must be one of Xi, Eta, Zeta.")
    normal = str(slice_cfg.get("normal", "")).strip()
    if normal.lower() not in BC_FACE_MAP:
        raise ValueError(f"{field_name}.normal must be one of {sorted(BC_FACE_MAP.values())}.")
    normal = BC_FACE_MAP[normal.lower()]
    if normal[1:].lower() != axis.lower():
        raise ValueError(f"{field_name}.normal must use the same axis as {field_name}.axis.")
    try:
        index = int(slice_cfg.get("index"))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.index must be an integer.")
    if index < 0:
        raise ValueError(f"{field_name}.index must be non-negative.")
    return {
        "axis": axis_map[axis.lower()],
        "index": index,
        "normal": normal,
        "orientation": orientation,
        "normal_tolerance": normal_tolerance,
    }
 
def generate_square_duct_poiseuille_picslice(output_path: str, dims: tuple, params: dict,
                                             target_grid: str = None, target_block: int = 0,
                                             target_face: str = None, script: str = None,
                                             case_path: str = None) -> dict:
    """!
    @brief Generate a dimensional canonical PICSLICE for square-duct Poiseuille flow.
    @param[in] output_path Path to write.
    @param[in] dims PICSLICE dimensions in face storage order (n1, n2).
    @param[in] params Normalized generator params.
    @param[in] target_grid Optional canonical target PICGRID for grid-aware sampling.
    @param[in] target_block Target block index when `target_grid` is provided.
    @param[in] target_face Target inlet face when `target_grid` is provided.
    @param[in] script Optional profile.gen-compatible script override.
    @param[in] case_path Current case.yml path used to anchor relative script overrides.
    @return Summary dictionary.
    """
    n1, n2 = tuple(dims)
    profilegen_script = _resolve_generator_script(script, case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    cmd = [
        sys.executable,
        profilegen_script,
        "square_duct_poiseuille",
        "--output",
        output_path,
        "--dims",
        str(n1),
        str(n2),
        "--bulk-velocity",
        str(float(params["bulk_velocity"])),
        "--n-terms",
        str(int(params["n_terms"])),
    ]
    if target_grid:
        cmd.extend([
            "--target-grid",
            target_grid,
            "--target-block",
            str(int(target_block)),
            f"--target-face={target_face}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 
def generate_field_slice_picslice(output_path: str, expected_dims: tuple, source: dict,
                                  target_grid: str, target_face: str, target_block: int,
                                  case_path: str) -> dict:
    """!
    @brief Invoke profile.gen to extract a field_slice PICSLICE artifact.
    @param[in] output_path Path to write.
    @param[in] expected_dims Expected PICSLICE dimensions.
    @param[in] source Normalized field_slice source mapping.
    @param[in] target_grid Target canonical PICGRID path.
    @param[in] target_face Target inlet face token.
    @param[in] target_block Target block index.
    @param[in] case_path Path to current case.yml for relative source resolution.
    @return Summary dictionary from profile.gen.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    field_file = _resolve_case_relative_path(source["field_file"], case_dir)
    source_grid = _resolve_case_relative_path(source["grid_file"], case_dir)
    velocity_scale = _resolve_field_slice_velocity_scale(source, case_dir)
    profilegen_script = _resolve_generator_script(source.get("script"), case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    n1, n2 = tuple(expected_dims)
    slice_cfg = source["slice"]
    cmd = [
        sys.executable,
        profilegen_script,
        "field-slice",
        "--output",
        output_path,
        "--field-file",
        field_file,
        "--source-grid",
        source_grid,
        "--target-grid",
        target_grid,
        "--source-block",
        str(int(source.get("source_block", 0))),
        "--target-block",
        str(int(target_block)),
        f"--target-face={target_face}",
        "--orientation",
        slice_cfg["orientation"],
        "--normal-tolerance",
        str(float(slice_cfg["normal_tolerance"])),
        "--velocity-scale",
        str(float(velocity_scale)),
        "--expected-dims",
        str(n1),
        str(n2),
    ]
    if "face" in slice_cfg:
        cmd.append(f"--slice-face={slice_cfg['face']}")
    else:
        cmd.extend([
            "--slice-axis",
            slice_cfg["axis"],
            "--slice-index",
            str(int(slice_cfg["index"])),
            f"--slice-normal={slice_cfg['normal']}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen field-slice failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen field-slice did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 
def _resolve_case_relative_path(path_value: str, case_dir: str) -> str:
    """!
    @brief Resolve a path relative to the current case directory.
    @param[in] path_value Path from case.yml.
    @param[in] case_dir Current case directory.
    @return Absolute path.
    """
    if not isinstance(path_value, str) or not path_value.strip():
        raise ValueError("path value must be a non-empty string.")
    workspace_root = find_workspace_root(case_dir)
    if workspace_root:
        if os.path.isabs(path_value):
            raise ValueError(
                f"absolute path {path_value!r} is not allowed in workspace case configuration; "
                "use 'picurv inputs import --mode reference' for an explicit external reference."
            )
        resolved = os.path.abspath(os.path.join(workspace_root, path_value))
        if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
            raise ValueError(f"path {path_value!r} escapes the workspace.")
        if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
            pointer = read_yaml_file(resolved)
            external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
            if not isinstance(external, str) or not os.path.isabs(external):
                raise ValueError(f"Invalid external-reference descriptor: {resolved}")
            if not os.path.isfile(external):
                raise ValueError(f"Registered external input is unavailable: {external}")
            return external
        return resolved
    if os.path.isabs(path_value):
        return os.path.abspath(path_value)
    return os.path.abspath(os.path.join(case_dir, path_value))
 
def _resolve_field_slice_velocity_scale(source: dict, case_dir: str) -> float:
    """!
    @brief Resolve field_slice dimensional velocity scale.
    @param[in] source Normalized field_slice source mapping.
    @param[in] case_dir Current case directory.
    @return Positive velocity scale.
    """
    if source.get("velocity_scale") is not None:
        return float(source["velocity_scale"])
    source_case = _resolve_case_relative_path(source["source_case"], case_dir)
    source_case_cfg = read_yaml_file(source_case)
    try:
        velocity_scale = _to_float(
            source_case_cfg.get("properties", {}).get("scaling", {}).get("velocity_ref"),
            "source_case.properties.scaling.velocity_ref",
        )
    except AttributeError as exc:
        raise ValueError("source_case must contain properties.scaling.velocity_ref.") from exc
    if velocity_scale <= 0.0:
        raise ValueError("source_case.properties.scaling.velocity_ref must be positive.")
    return velocity_scale
 
def resolve_target_grid_for_field_slice(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve the target canonical PICGRID path needed for field_slice normals.
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path.
    """
    grid_cfg = case_cfg.get("grid", {}) or {}
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for field_slice target-grid normals.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return source_grid
    if grid_mode == "grid_gen":
        candidate = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
        if os.path.isfile(candidate):
            return candidate
        staged = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            return staged
        raise ValueError("field_slice requires the generated target PICGRID to exist before profile extraction.")
    raise ValueError(
        f"field_slice requires grid.mode 'file' or 'grid_gen' for target-grid normals; got '{grid_mode}'."
    )
 
def resolve_target_grid_for_generated_profile(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve an optional target canonical PICGRID for generated profile sampling.
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path, or None when no canonical grid is available yet.
    """
    grid_mode = (case_cfg.get("grid", {}) or {}).get("mode")
    if grid_mode == "programmatic_c":
        return None
    return resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
 
def write_profile_info(config_dir: str, summaries: list) -> str:
    """!
    @brief Write a profile.info summary for generated inlet profiles.
    @param[in] config_dir Run/precompute config directory.
    @param[in] summaries Generated profile summaries.
    @return Path to profile.info.
    """
    info_path = os.path.join(config_dir, "profile.info")
    os.makedirs(config_dir, exist_ok=True)
    with open(info_path, "w") as fout:
        fout.write("# PICurv generated profile summary\n")
        fout.write(f"profile_count = {len(summaries)}\n\n")
        for idx, summary in enumerate(summaries):
            dims = summary.get("dims", (0, 0))
            fout.write(f"[profile_{idx}]\n")
            fout.write(f"generator = {summary.get('generator')}\n")
            fout.write(f"block = {summary.get('block')}\n")
            fout.write(f"face = {summary.get('face')}\n")
            fout.write(f"dimensions = {dims[0]} {dims[1]}\n")
            if summary.get("bulk_velocity") is not None:
                fout.write(f"bulk_velocity = {summary.get('bulk_velocity'):.16e}\n")
            if summary.get("n_terms") is not None:
                fout.write(f"n_terms = {summary.get('n_terms')}\n")
            fout.write(f"mean_speed = {summary.get('mean_speed'):.16e}\n")
            if "area_mean_speed" in summary:
                fout.write(f"area_mean_speed = {summary.get('area_mean_speed'):.16e}\n")
            if "discrete_mean_speed" in summary:
                fout.write(f"discrete_mean_speed = {summary.get('discrete_mean_speed'):.16e}\n")
            fout.write(f"min_speed = {summary.get('min_speed'):.16e}\n")
            fout.write(f"max_speed = {summary.get('max_speed'):.16e}\n")
            if summary.get("umax_over_ubulk") is not None:
                fout.write(f"umax_over_ubulk = {summary.get('umax_over_ubulk'):.16e}\n")
            for key in (
                "normalization",
                "sampling",
                "area_weighted_mean_before_normalization",
                "area_weighted_mean_after_normalization",
                "total_inlet_area",
                "face_area_min",
                "face_area_max",
                "source_field",
                "source_grid",
                "target_grid",
                "source_block",
                "target_block",
                "target_face",
                "source_slice",
                "orientation",
                "normal_tolerance",
                "normal_dot",
                "velocity_scale",
            ):
                if key in summary:
                    fout.write(f"{key} = {summary.get(key)}\n")
            fout.write(f"output_file = {summary.get('path')}\n\n")
    return info_path
 
#: Generator flags whose values are drawn from a closed choice set. Checking them where
#: the case is validated turns a mid-run subprocess failure into a startup error.
GRID_GENERATOR_CHOICE_FLAGS = {
    "--cross-section": GRID_CROSS_SECTION_KINDS,
}
 
#: Generator flags taking an ordered `kind:key=value` list whose kinds are closed.
GRID_GENERATOR_SPEC_FLAGS = {
    "--wall-j-lo": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-lo-span": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi-span": GRID_WALL_SEGMENT_KINDS,
    "--cross-section-scale": GRID_WALL_SEGMENT_KINDS,
    "--path": GRID_PATH_SEGMENT_KINDS,
    "--transforms": GRID_TRANSFORM_KINDS,
}
 
 
def validate_grid_generator_cli_args(cli_args, case_path: str) -> list:
    """!
    @brief Check closed-choice values inside the generator's opaque token list.
    @details `cli_args` is passed through to grid.gen untouched, so a misspelled geometry
             selector there is only discovered when the subprocess exits nonzero partway
             into a run. The generator remains the authority; this reports the same set
             earlier, and stays silent on anything it does not recognize.
    @param[in] cli_args Raw token list from grid.generator.cli_args.
    @param[in] case_path Case file path for diagnostics.
    @return List of error strings.
    """
    if not isinstance(cli_args, list):
        return []
    tokens = [str(token) for token in cli_args]
    errors = []
    for index, token in enumerate(tokens):
        values = []
        for follower in tokens[index + 1:]:
            if follower.startswith("--"):
                break
            values.append(follower)
        if token in GRID_GENERATOR_CHOICE_FLAGS:
            allowed = GRID_GENERATOR_CHOICE_FLAGS[token]
            for value in values[:1]:
                if value not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} must be one of "
                        f"{list(allowed)} (got '{value}')."
                    )
        elif token in GRID_GENERATOR_SPEC_FLAGS:
            allowed = GRID_GENERATOR_SPEC_FLAGS[token]
            for value in values:
                kind = value.split(":", 1)[0]
                if kind not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} entry '{value}' "
                        f"names '{kind}', which is not one of {list(allowed)}."
                    )
    return errors
 
 
def run_grid_generator(case_path: str, run_dir: str, grid_cfg: dict,
                       case_cfg: dict = None) -> str:
    """!
    @brief Runs generators/grid.gen to produce a PICGRID file for this run.
    @param[in] case_path Path to case.yml (used for relative path resolution).
    @param[in] run_dir Run directory path.
    @param[in] grid_cfg The grid config section from case.yml.
    @param[in] case_cfg Parsed case configuration, when available. Its reference scales
                        are handed to the generator so the quality report can carry
                        solver and wall units. Reporting only: the generator never scales
                        coordinates, which validate_and_nondimensionalize_picgrid does
                        once for every grid regardless of origin.
    @return Absolute path to generated dimensional PICGRID file.
    @throws ValueError on invalid config or generator failure.
    """
    generator = grid_cfg.get("generator", {})
    if not isinstance(generator, dict):
        raise ValueError("grid.generator must be a mapping when grid.mode is 'grid_gen'.")
 
    case_dir = os.path.dirname(os.path.abspath(case_path))
    gridgen_script = generator.get("script", os.path.join(GENERATORS_PATH, "grid.gen"))
    if generator.get("script"):
        gridgen_script = _resolve_case_relative_path(gridgen_script, case_dir)
    else:
        gridgen_script = os.path.abspath(gridgen_script)
    if not os.path.isfile(gridgen_script):
        raise ValueError(f"grid.gen script not found: {gridgen_script}")
 
    config_file = generator.get("config_file")
    if not config_file:
        raise ValueError("grid.generator.config_file is required when grid.mode is 'grid_gen'.")
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(config_file):
        raise ValueError(f"grid.generator.config_file not found: {config_file}")
 
    output_file = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
    os.makedirs(os.path.dirname(output_file), exist_ok=True)
 
    grid_type = generator.get("grid_type")
    cli_args = generator.get("cli_args", [])
    if cli_args is None:
        cli_args = []
    if not isinstance(cli_args, list):
        raise ValueError("grid.generator.cli_args must be a list of CLI tokens.")
 
    cmd = [sys.executable, gridgen_script, "-c", config_file]
    if grid_type:
        cmd.append(str(grid_type))
    cmd.extend([str(token) for token in cli_args])
    cmd.extend(["--output", output_file])
 
    # Destinations are PICurv's, not the user's. Inspection material is produced
    # unconditionally so a published asset is always something the user can look at,
    # rather than only when a configuration file happened to name an output path.
    vts_file = os.path.abspath(
        os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts")
    )
    os.makedirs(os.path.dirname(vts_file), exist_ok=True)
    cmd.extend(["--vts", vts_file])
 
    stats_file = os.path.abspath(
        os.path.join(run_dir, "output", "analysis", "metrics", "grid.info")
    )
    os.makedirs(os.path.dirname(stats_file), exist_ok=True)
    cmd.extend(["--stats-file", stats_file])
 
    # The case already knows these; the generator would otherwise report a grid in metres
    # with no way to say what it becomes downstream. Resolution is best-effort: a case
    # that omits them still gets its grid, just without the derived-unit sections.
    if case_cfg:
        try:
            scaling = resolve_fluid_scaling(case_cfg)
        except (KeyError, ValueError, TypeError):
            scaling = None
        if scaling:
            cmd.extend(["--length-ref", repr(scaling["length_ref"]),
                        "--velocity-ref", repr(scaling["velocity_ref"]),
                        "--nu", repr(scaling["physical_kinematic_viscosity"])])
 
    print(f"[INFO] Grid generator command: {' '.join(cmd)}")
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        stderr = (result.stderr or "").strip()
        stdout = (result.stdout or "").strip()
        details = stderr if stderr else stdout
        raise ValueError(
            f"grid.gen failed with exit code {result.returncode}. Details:\n{details}"
        )
    if result.stdout:
        print(result.stdout.strip())
    if result.stderr:
        print(result.stderr.strip())
 
    if not os.path.isfile(output_file):
        raise ValueError(f"grid.gen did not produce expected output file: {output_file}")
 
    return output_file
 
 
BC_FACE_MAP = {
    "-xi": "-Xi",
    "+xi": "+Xi",
    "-eta": "-Eta",
    "+eta": "+Eta",
    "-zeta": "-Zeta",
    "+zeta": "+Zeta",
}
 
# Canonical BC selector maps. Add new values only with matching C parser/factory support.
BC_TYPE_MAP = {
    "wall": "WALL",
    "symmetry": "SYMMETRY",
    "inlet": "INLET",
    "outlet": "OUTLET",
    "periodic": "PERIODIC",
}
 
BC_HANDLER_SPECS = {
    # Only handlers that are implemented end-to-end in current C path are allowed.
    "noslip": {
        "types": {"WALL"},
        "required_params": set(),
        "optional_params": set(),
    },
    "constant_velocity": {
        "types": {"INLET"},
        "required_params": {"vx", "vy", "vz"},
        "optional_params": set(),
    },
    "conservation": {
        "types": {"OUTLET"},
        "required_params": set(),
        "optional_params": set(),
    },
    "parabolic": {
        "types": {"INLET"},
        "required_params": {"v_max"},
        "optional_params": set(),
    },
    "prescribed_flow": {
        "types": {"INLET"},
        "required_params": {"source"},
        "optional_params": set(),
    },
    "geometric": {
        "types": {"PERIODIC"},
        "required_params": set(),
        "optional_params": set(),
    },
    "constant_flux": {
        "types": {"PERIODIC"},
        "required_params": {"target_flux"},
        "optional_params": {"enforce_seam_flux", "apply_trim"},
    },
    # Derives its own target from the initial condition, so it takes no target_flux.
    "initial_flux": {
        "types": {"PERIODIC"},
        "required_params": set(),
        "optional_params": {"enforce_seam_flux", "apply_trim"},
    },
}
 
_NUMERIC_BC_PARAMS = {"vx", "vy", "vz", "v_max", "target_flux"}
_BOOL_BC_PARAMS = {"enforce_seam_flux", "apply_trim"}
 
# Deprecated BC param spellings -> canonical name. `apply_trim` said that
# something was trimmed but not what or why; `enforce_seam_flux` names the
# quantity it holds on target. Both are accepted; bcs.run carries the canonical
# name, and the C side also falls back to the old spelling for archived files.
_DEPRECATED_BC_PARAM_ALIASES = {"apply_trim": "enforce_seam_flux"}
 
def _normalize_prescribed_flow_source(source, field_name: str) -> dict:
    """!
    @brief Validate the structured source block for prescribed_flow BCs.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    @throws ValueError on invalid source contract.
    """
    if not isinstance(source, dict):
        raise ValueError(f"{field_name} must be a mapping with type: file, generated, or field_slice.")
    source_type = str(source.get("type", "")).strip().lower()
    if source_type == "file":
        path = source.get("path")
        if not isinstance(path, str) or not path.strip():
            raise ValueError(f"{field_name}.path must be a non-empty file path.")
        unknown = sorted(set(source.keys()) - {"type", "path"})
        if unknown:
            raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: ['path', 'type'].")
        return {"type": "file", "path": path.strip()}
 
    if source_type == "generated":
        generator = str(source.get("generator", "")).strip().lower()
        if generator not in GENERATED_PROFILE_GENERATORS:
            raise ValueError(
                f"{field_name}.generator must be one of {sorted(GENERATED_PROFILE_GENERATORS)} "
                f"(got '{source.get('generator')}')."
            )
        unknown = sorted(set(source.keys()) - {"type", "generator", "script", "output_file", "params"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Allowed: ['generator', 'output_file', 'params', 'script', 'type']."
            )
        normalized = {
            "type": "generated",
            "generator": generator,
            "params": _normalize_square_duct_poiseuille_params(source.get("params", {}), field_name),
        }
        output_file = source.get("output_file")
        if output_file is not None:
            if not isinstance(output_file, str) or not output_file.strip():
                raise ValueError(f"{field_name}.output_file must be a non-empty path when provided.")
            normalized["output_file"] = output_file.strip()
        script = source.get("script")
        if script is not None:
            if not isinstance(script, str) or not script.strip():
                raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
            normalized["script"] = script.strip()
        return normalized
 
    if source_type == "field_slice":
        return _normalize_field_slice_source(source, field_name)
 
    raise ValueError(f"{field_name}.type must be 'file', 'generated', or 'field_slice'.")
 
def _bc_profile_expected_dims(face: str, block_dims: tuple) -> tuple:
    """!
    @brief Return expected PICSLICE dimensions for a face and block node dimensions.
    @param[in] face Canonical BC face token.
    @param[in] block_dims (IM, JM, KM) node counts.
    @return (n1, n2) dimensions in profile storage order.
    """
    im, jm, km = block_dims
    if min(im, jm, km) < 2:
        raise ValueError(
            f"Block dimensions {block_dims} are too small for an inlet profile; each axis needs at least 2 nodes."
        )
    if face in {"-Xi", "+Xi"}:
        return (km - 1, jm - 1)
    if face in {"-Eta", "+Eta"}:
        return (km - 1, im - 1)
    if face in {"-Zeta", "+Zeta"}:
        return (jm - 1, im - 1)
    raise ValueError(f"Unsupported face '{face}' for prescribed_flow profile dimensions.")
 
def resolve_grid_block_dimensions_for_profiles(case_cfg: dict, case_path: str, run_dir: str = None) -> list:
    """!
    @brief Resolve per-block node dimensions for prescribed inlet profile validation.
    @param[in] case_cfg Parsed case.yml configuration.
    @param[in] case_path Path to case.yml for relative path resolution.
    @param[in] run_dir Current run directory, used for optional generated grid outputs.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError when dimensions cannot be resolved.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    grid_cfg = case_cfg.get("grid", {})
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
 
    if grid_mode == "programmatic_c":
        settings = grid_cfg.get("programmatic_settings", {})
        dims_by_axis = []
        for key in ("im", "jm", "km"):
            raw = settings.get(key)
            if raw is None:
                raise ValueError(f"grid.programmatic_settings.{key} is required for prescribed_flow profiles.")
            if isinstance(raw, list):
                if len(raw) != num_blocks:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} has {len(raw)} entries, expected {num_blocks} blocks."
                    )
                values = raw
            else:
                values = [raw] * num_blocks
            try:
                values = [int(v) + 1 for v in values]
            except (TypeError, ValueError):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            if any(v <= 1 for v in values):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            dims_by_axis.append(values)
        return list(zip(dims_by_axis[0], dims_by_axis[1], dims_by_axis[2]))
 
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for file-grid prescribed_flow profile validation.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return read_picgrid_header_dimensions(source_grid, expected_nblk=num_blocks)
 
    if grid_mode == "grid_gen":
        candidates = []
        if run_dir:
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        for candidate in candidates:
            if os.path.isfile(candidate):
                return read_picgrid_header_dimensions(candidate, expected_nblk=num_blocks)
        raise ValueError(
            "prescribed_flow profile dimension validation for grid.mode='grid_gen' requires an existing generated "
            "PICGRID output. Run or stage the grid first, or use grid.mode='file' with the generated .picgrid."
        )
 
    raise ValueError(f"Unsupported grid.mode '{grid_mode}' for prescribed_flow profile validation.")
 
def materialize_generated_prescribed_flow_profiles(run_dir: str, case_cfg: dict, case_path: str,
                                                   profile_grid_dims: list = None) -> list:
    """!
    @brief Generate dimensional PICSLICE artifacts for generated/field_slice prescribed_flow sources.
    @param[in] run_dir Run/precompute directory root.
    @param[in] case_cfg Parsed case.yml.
    @param[in] case_path Path to case.yml for relative grid/source resolution.
    @param[in] profile_grid_dims Optional pre-resolved block node dimensions.
    @return List of generated profile summaries.
    """
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    if not any(
        bc.get("handler") == "prescribed_flow"
        and ((bc.get("params") or {}).get("source") or {}).get("type") in PRESCRIBED_FLOW_SOURCE_TYPES[1:]
        for block in prepared_blocks for bc in block
    ):
        return []
    if profile_grid_dims is None:
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    target_grid = None
    generated_target_grid = None
    summaries = []
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            face = bc["face"]
            dims = _bc_profile_expected_dims(face, profile_grid_dims[block_idx])
            face_token = _face_artifact_token(face)
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            output_path = os.path.join(
                profile_dir,
                f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice",
            )
            if source.get("type") == "generated" and source["generator"] == "square_duct_poiseuille":
                if generated_target_grid is None:
                    generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                summary = generate_square_duct_poiseuille_picslice(
                    output_path,
                    dims,
                    source["params"],
                    target_grid=generated_target_grid,
                    target_block=block_idx,
                    target_face=face,
                    script=source.get("script"),
                    case_path=case_path,
                )
            elif source.get("type") == "generated":
                raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
            else:
                if target_grid is None:
                    target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                summary = generate_field_slice_picslice(
                    output_path,
                    dims,
                    source,
                    target_grid,
                    face,
                    block_idx,
                    case_path,
                )
            summary.update({"block": block_idx, "face": face})
            summaries.append(summary)
            print(
                f"[SUCCESS] Materialized prescribed_flow profile for block {block_idx}, face {face}: "
                f"{os.path.relpath(output_path)} dims={summary['dims']}"
            )
 
    if summaries:
        info_path = write_profile_info(profile_dir, summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
    return summaries
 
def _to_float(value, field_name: str) -> float:
    """!
    @brief Convert a YAML scalar to float with a clear error message.
    @param[in] value Argument passed to `_to_float()`.
    @param[in] field_name Argument passed to `_to_float()`.
    @return Value returned by `_to_float()`.
    """
    try:
        return float(value)
    except (TypeError, ValueError):
        raise ValueError(f"'{field_name}' must be numeric (got {value!r}).")
 
 
def _to_finite_float(value, field_name: str) -> float:
    """!
    @brief Convert a non-boolean YAML scalar to a finite float.
    @param[in] value Raw YAML scalar.
    @param[in] field_name User-facing configuration path.
    @return Finite floating-point value.
    """
    if isinstance(value, bool):
        raise ValueError(f"'{field_name}' must be numeric, not boolean.")
    parsed = _to_float(value, field_name)
    if not math.isfinite(parsed):
        raise ValueError(f"'{field_name}' must be finite (got {value!r}).")
    return parsed
 
def _to_bool(value, field_name: str) -> bool:
    """!
    @brief Convert a YAML scalar/string to bool with a clear error message.
    @param[in] value Argument passed to `_to_bool()`.
    @param[in] field_name Argument passed to `_to_bool()`.
    @return Value returned by `_to_bool()`.
    """
    if isinstance(value, bool):
        return value
    if isinstance(value, str):
        raw = value.strip().lower()
        if raw in {"true", "1", "yes"}:
            return True
        if raw in {"false", "0", "no"}:
            return False
    raise ValueError(f"'{field_name}' must be boolean (got {value!r}).")
 
def normalize_boundary_conditions_layout(all_blocks_bcs, num_blocks: int):
    """!
    @brief Normalize boundary_conditions to list-of-lists form and validate block count.
    @param[in] all_blocks_bcs Argument passed to `normalize_boundary_conditions_layout()`.
    @param[in] num_blocks Argument passed to `normalize_boundary_conditions_layout()`.
    @return Value returned by `normalize_boundary_conditions_layout()`.
    """
    if not all_blocks_bcs:
        raise ValueError("The 'boundary_conditions' section in case.yml is empty.")
 
    is_simple_list = isinstance(all_blocks_bcs[0], dict)
    if num_blocks == 1 and is_simple_list:
        all_blocks_bcs = [all_blocks_bcs]
    elif is_simple_list and num_blocks > 1:
        raise ValueError(
            f"case.yml declares {num_blocks} blocks but boundary_conditions is a single face-list. "
            "Use a list-of-lists, one inner list per block."
        )
 
    if len(all_blocks_bcs) != num_blocks:
        raise ValueError(
            f"Mismatch: case.yml declares {num_blocks} block(s) but found {len(all_blocks_bcs)} BC definitions."
        )
    return all_blocks_bcs
 
def _les_periodic_axes(case_cfg: dict) -> set:
    """!
    @brief Reports which logical axes a case declares periodic on both faces.
    @param[in] case_cfg Parsed case.yml mapping.
    @return Set of axis letters drawn from {'i', 'j', 'k'}.
    """
    axis_faces = {"i": ("-Xi", "+Xi"), "j": ("-Eta", "+Eta"), "k": ("-Zeta", "+Zeta")}
    declared = {}
    entries = case_cfg.get("boundary_conditions") or []
    if entries and isinstance(entries[0], list):
        entries = entries[0]
    for entry in entries:
        if isinstance(entry, dict):
            declared[str(entry.get("face"))] = str(entry.get("type", "")).upper()
    return {
        axis for axis, faces in axis_faces.items()
        if all(declared.get(face) == "PERIODIC" for face in faces)
    }
 
 
def validate_wall_model_pairing(case_cfg: dict, les_cfg, rans_cfg, wall_cfg,
                                case_path: str, errors: list, warnings: list):
    """!
    @brief Rejects wall-model selections that no turbulence treatment can support.
 
    A wall model replaces the near-wall flow with an analytic profile so that the
    boundary layer need not be resolved. That only means something if the unresolved
    motions are modelled somewhere. Three combinations cannot be, and each fails here
    rather than after the mesh is built.
 
    @param case_cfg Parsed case configuration, read for the Reynolds number.
    @param les_cfg  `models.physics.turbulence.les`, or None.
    @param rans_cfg `models.physics.turbulence.rans`, or None.
    @param wall_cfg `models.physics.turbulence.wall_function`, or None.
    @param case_path Case path, for message prefixes.
    @param errors   Collected blocking messages, appended to.
    @param warnings Collected advisory messages, appended to.
    """
    if not isinstance(wall_cfg, dict):
        return
    if not bool(wall_cfg.get('enabled', False)):
        return
 
    try:
        model = normalize_wall_function_model(wall_cfg.get('model', 'log_law'))
    except ValueError:
        return  # The selector's own validation already reported this.
 
    les_on = isinstance(les_cfg, dict) and bool(les_cfg.get('enabled', False)) \
        and str(les_cfg.get('model', 'dynamic_smagorinsky')).strip().lower() != 'none'
    rans_on = isinstance(rans_cfg, dict) and bool(rans_cfg.get('enabled', False))
 
    # A wall model with nothing to sit on. The convective scheme here is QUICK, whose
    # dissipation is linear and upwind-biased; it is not a limiter-based scheme whose
    # truncation error stands in for a subgrid stress, so there is no implicit LES to
    # appeal to.
    if not les_on and not rans_on:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled with no "
            "turbulence model. A wall model supplies the stress of a boundary layer it "
            "does not resolve, which needs the unresolved motions modelled somewhere. "
            "This solver has no implicit-LES scheme to supply that - its convection is "
            "QUICK, whose numerical dissipation is not a subgrid model - so enable "
            "models.physics.turbulence.les, or resolve the wall and disable the wall "
            "function.")
 
    # Cabot carries a mixing-length eddy viscosity in the wall layer, which is itself a
    # RANS closure; nesting it inside a RANS model is two closures for one layer with no
    # defined matching between them. Werner-Wengle applies its power law to an
    # instantaneous filtered velocity, which is an LES construct and has no standing as a
    # RANS wall function.
    if rans_on and model == 3:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function.model 'cabot' cannot "
            "be used with RANS. Cabot solves the wall layer with its own mixing-length "
            "eddy viscosity, so under a RANS model the near-wall layer would carry two "
            "turbulence closures with no matching between them. Use 'log_law' with RANS.")
    if rans_on and model == 2:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function.model 'werner' cannot "
            "be used with RANS. Werner-Wengle applies its power law to the instantaneous "
            "filtered velocity, which is a large-eddy quantity; a RANS field is already "
            "averaged and wants a wall law derived for the mean profile. Use 'log_law' "
            "with RANS.")
 
    # A wall law describes a turbulent boundary layer. Below transition there is no
    # inertial region for it to stand on, and it would impose a profile the flow does not
    # have. The threshold is deliberately far below any transitional value, so that it
    # only catches cases that are unambiguously laminar.
    reynolds = _case_reynolds_number(case_cfg)
    if reynolds is not None and reynolds < 1000.0:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled at "
            f"Reynolds number {reynolds:g}, which is laminar. The log law and the "
            "Werner-Wengle power law both describe a turbulent boundary layer; at this "
            "Reynolds number there is no inertial region for either to represent, and "
            "the model would impose a profile the flow does not have. Resolve the wall "
            "instead.")
 
 
def _case_reynolds_number(case_cfg: dict):
    """!
    @brief Reynolds number implied by a case's scaling and fluid properties.
    @param case_cfg Parsed case configuration.
    @return The Reynolds number, or None when the inputs are absent or unusable.
    """
    try:
        props = case_cfg.get('properties', {}) or {}
        scaling = props.get('scaling', {}) or {}
        fluid = props.get('fluid', {}) or {}
        density = float(fluid.get('density'))
        viscosity = float(fluid.get('viscosity'))
        length_ref = float(scaling.get('length_ref'))
        velocity_ref = float(scaling.get('velocity_ref'))
    except (TypeError, ValueError):
        return None
    if viscosity <= 0.0:
        return None
    return density * velocity_ref * length_ref / viscosity
 
 
def validate_les_configuration(case_cfg: dict, les_cfg: dict, case_path: str,
                               errors: list, warnings: list):
    """!
    @brief Checks the structured LES block for values the closure cannot honour.
    @param[in] case_cfg Parsed case.yml mapping, used to read declared periodicity.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[in] case_path Case file path used to prefix diagnostics.
    @param[out] errors List collecting blocking validation failures.
    @param[out] warnings List collecting advisory messages.
    @return None; findings are appended to `errors` and `warnings`.
    """
    def _numeric(container, key, path, minimum=None, exclusive_minimum=None):
        """!
        @brief Reads one numeric key and records a range or type failure against it.
        @param[in] container Mapping holding the key.
        @param[in] key Key to read; absent keys are accepted silently.
        @param[in] path Dotted key path used in diagnostics.
        @param[in] minimum Inclusive lower bound, or None to impose none.
        @param[in] exclusive_minimum Exclusive lower bound, or None to impose none.
        @return The parsed value, or None when the key is absent or unparseable.
        """
        if key not in container:
            return None
        try:
            value = float(container[key])
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: {path} must be numeric.")
            return None
        if minimum is not None and value < minimum:
            errors.append(f"  {case_path}: {path} must be at least {minimum}.")
        if exclusive_minimum is not None and value <= exclusive_minimum:
            errors.append(f"  {case_path}: {path} must be greater than {exclusive_minimum}.")
        return value
 
    if 'enabled' in les_cfg and not isinstance(les_cfg['enabled'], bool):
        errors.append(f"  {case_path}: models.physics.turbulence.les.enabled must be true or false.")
 
    _numeric(les_cfg, 'constant_cs', "models.physics.turbulence.les.constant_cs", minimum=0.0)
 
    if 'dynamic_frequency' in les_cfg:
        try:
            if int(les_cfg['dynamic_frequency']) <= 0:
                errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be positive.")
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be an integer.")
 
    for key, normalizer in (('filter_width', normalize_les_filter_width),):
        if key in les_cfg:
            try:
                normalizer(les_cfg[key])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
 
    periodic = _les_periodic_axes(case_cfg)
 
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            try:
                kernel = normalize_les_test_filter(test_filter['kernel'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                # The Simpson stencil collapses onto the central eta-plane, which is
                # only a valid average when xi and zeta are homogeneous.
                if kernel == 1 and not {"i", "k"} <= periodic:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.test_filter.kernel "
                        "'simpson_ik' assumes the xi and zeta directions are homogeneous, but "
                        "this case does not declare both of them PERIODIC. Use "
                        "'volume_weighted_box' instead."
                    )
        # A test filter no wider than the grid filter leaves the dynamic procedure with
        # nothing to measure, because both terms of the model tensor coincide.
        _numeric(test_filter, 'width_ratio',
                 "models.physics.turbulence.les.test_filter.width_ratio", exclusive_minimum=1.0)
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        mode = None
        if 'mode' in averaging:
            try:
                mode = normalize_les_averaging_mode(averaging['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        directions = None
        if 'directions' in averaging:
            try:
                directions = normalize_les_averaging_directions(averaging['directions'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not directions:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "cannot be empty; omit the key to use the periodic axes."
                    )
                if mode is not None and mode != 1:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "applies only to mode 'homogeneous'; local and global averaging choose "
                        "their own directions."
                    )
                for axis in directions:
                    if axis not in periodic:
                        warnings.append(
                            f"{case_path}: models.physics.turbulence.les.averaging.directions "
                            f"names '{axis}', which this case does not declare PERIODIC. "
                            "Averaging assumes the flow is statistically homogeneous there."
                        )
        if mode == 1 and directions is None and not periodic:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.averaging.mode 'homogeneous' "
                "derives its directions from the periodic boundary pairs, and this case declares "
                "none. Name the directions explicitly or use 'local'."
            )
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        mode = None
        if 'mode' in clipping:
            try:
                mode = normalize_les_clip_mode(clipping['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        _numeric(clipping, 'max_cs', "models.physics.turbulence.les.clipping.max_cs", minimum=0.0)
        _numeric(clipping, 'min_viscosity_ratio',
                 "models.physics.turbulence.les.clipping.min_viscosity_ratio", minimum=0.0)
        if 'max_cs' in clipping and mode is not None and mode != 0:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.clipping.max_cs applies only to "
                "mode 'clamp'; 'positive' and 'signed' impose no upper bound. Remove the key or "
                "select mode 'clamp'."
            )
 
    diagnostics = les_cfg.get('diagnostics')
    if isinstance(diagnostics, dict):
        if 'cadence' in diagnostics:
            try:
                if int(diagnostics['cadence']) <= 0:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.diagnostics.cadence must be positive."
                    )
            except (TypeError, ValueError):
                errors.append(
                    f"  {case_path}: models.physics.turbulence.les.diagnostics.cadence must be an integer."
                )
        _numeric(diagnostics, 'yoshizawa_ci',
                 "models.physics.turbulence.les.diagnostics.yoshizawa_ci", minimum=0.0)
 
    # The dynamic procedure's controls have no meaning for a prescribed coefficient.
    # Only an explicitly named constant model triggers this: a template that documents
    # every key while LES is switched off should not be rejected on an inferred default.
    try:
        model_code = normalize_les_model(les_cfg['model']) if 'model' in les_cfg else None
    except ValueError:
        model_code = None
    if model_code == 1 and les_cfg.get('enabled', True):
        for key in ('filter_width', 'test_filter', 'averaging', 'clipping'):
            if key in les_cfg:
                errors.append(
                    f"  {case_path}: models.physics.turbulence.les.{key} configures the dynamic "
                    "procedure and cannot be used with model 'constant_smagorinsky'."
                )
 
 
def validate_and_prepare_boundary_conditions(case_cfg: dict):
    """!
    @brief Validate BC entries against currently supported C-side handlers/types and
    @details return normalized entries ready for bcs.run generation.
    @param[in] case_cfg Argument passed to `validate_and_prepare_boundary_conditions()`.
    @return Value returned by `validate_and_prepare_boundary_conditions()`.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    scales = case_cfg.get('properties', {}).get('scaling', {})
    L_ref = _to_float(scales.get('length_ref'), "properties.scaling.length_ref")
    U_ref = _to_float(scales.get('velocity_ref'), "properties.scaling.velocity_ref")
    if U_ref == 0.0:
        raise ValueError("properties.scaling.velocity_ref must be non-zero for non-dimensionalization.")
    if L_ref == 0.0:
        raise ValueError("properties.scaling.length_ref must be non-zero for non-dimensionalization.")
 
    all_blocks_bcs = normalize_boundary_conditions_layout(case_cfg.get('boundary_conditions', []), num_blocks)
    prepared_blocks = []
 
    expected_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    axis_pairs = [("-Xi", "+Xi"), ("-Eta", "+Eta"), ("-Zeta", "+Zeta")]
 
    for bi, block_bcs in enumerate(all_blocks_bcs):
        if not isinstance(block_bcs, list):
            raise ValueError(f"boundary_conditions[{bi}] must be a list of face configs.")
 
        prepared_block = []
        seen_faces = {}
 
        for idx, bc in enumerate(block_bcs):
            if not isinstance(bc, dict):
                raise ValueError(f"boundary_conditions[{bi}][{idx}] must be a mapping.")
 
            for req in ("face", "type", "handler"):
                if req not in bc:
                    raise ValueError(f"boundary_conditions[{bi}][{idx}] missing required key '{req}'.")
 
            face_raw = str(bc["face"]).strip()
            face_key = face_raw.lower()
            face = BC_FACE_MAP.get(face_key)
            if face is None:
                raise ValueError(
                    f"Unsupported BC face '{face_raw}' at boundary_conditions[{bi}][{idx}]. "
                    f"Supported: {sorted(expected_faces)}."
                )
            if face in seen_faces:
                raise ValueError(f"Duplicate face '{face}' in boundary_conditions[{bi}] (entries {seen_faces[face]} and {idx}).")
            seen_faces[face] = idx
 
            bc_type_raw = str(bc["type"]).strip()
            bc_type = BC_TYPE_MAP.get(bc_type_raw.lower())
            if bc_type is None:
                raise ValueError(
                    f"Unsupported BC type '{bc_type_raw}' for face {face} in block {bi}. "
                    f"Supported: {sorted(set(BC_TYPE_MAP.values()))}."
                )
 
            handler = str(bc["handler"]).strip().lower()
            handler_spec = BC_HANDLER_SPECS.get(handler)
            if handler_spec is None:
                raise ValueError(
                    f"Unsupported BC handler '{bc['handler']}' for face {face} in block {bi}. "
                    f"Supported now: {sorted(BC_HANDLER_SPECS.keys())}."
                )
            if bc_type not in handler_spec["types"]:
                raise ValueError(
                    f"Invalid BC combination on block {bi}, face {face}: type '{bc_type}' cannot use handler '{handler}'."
                )
 
            params = bc.get("params", {})
            if params is None:
                params = {}
            if not isinstance(params, dict):
                raise ValueError(f"'params' for block {bi}, face {face} must be a mapping.")
 
            # Reject unsupported older structured keys explicitly.
            if "vector" in params or "velocity" in params:
                raise ValueError(
                    f"Unsupported older params key ('vector'/'velocity') found on block {bi}, face {face}. "
                    "Use scalar keys 'vx', 'vy', 'vz'."
                )
 
            required = handler_spec["required_params"]
            optional = handler_spec["optional_params"]
            allowed = required | optional
 
            missing = sorted(required - set(params.keys()))
            if missing:
                raise ValueError(
                    f"Missing required params for handler '{handler}' on block {bi}, face {face}: {missing}."
                )
            unknown = sorted(set(params.keys()) - allowed)
            if unknown:
                raise ValueError(
                    f"Unknown params for handler '{handler}' on block {bi}, face {face}: {unknown}. "
                    f"Allowed: {sorted(allowed)}."
                )
 
            converted_params = {}
            for key, value in params.items():
                if key in _NUMERIC_BC_PARAMS:
                    numeric = _to_float(value, f"boundary_conditions[{bi}][{idx}].params.{key}")
                    if key in {"vx", "vy", "vz", "v_max"}:
                        converted_params[key] = numeric / U_ref
                    elif key == "target_flux":
                        converted_params[key] = numeric / (U_ref * (L_ref ** 2))
                elif key in _BOOL_BC_PARAMS:
                    canonical = _DEPRECATED_BC_PARAM_ALIASES.get(key, key)
                    if canonical != key:
                        if canonical in params:
                            raise ValueError(
                                f"boundary_conditions[{bi}][{idx}].params sets both '{key}' and its "
                                f"replacement '{canonical}'. Use '{canonical}' only."
                            )
                        print(
                            f"[WARNING] boundary_conditions[{bi}][{idx}].params.{key} is deprecated; "
                            f"use '{canonical}'. It enables the local seam-flux correction on the "
                            "periodic boundary plane, on top of the body force that sustains the bulk "
                            "flow. See docs/pages/54_Geometric_Periodic_Boundaries.md.",
                            file=sys.stderr,
                        )
                    converted_params[canonical] = _to_bool(
                        value, f"boundary_conditions[{bi}][{idx}].params.{key}")
                elif handler == "prescribed_flow" and key == "source":
                    converted_params[key] = _normalize_prescribed_flow_source(
                        value, f"boundary_conditions[{bi}][{idx}].params.source"
                    )
                else:
                    # Defensive fallback; should not happen due unknown-key gate above.
                    converted_params[key] = value
 
            prepared_block.append({
                "face": face,
                "type": bc_type,
                "handler": handler,
                "params": converted_params,
            })
 
        missing_faces = sorted(expected_faces - set(seen_faces.keys()))
        if missing_faces:
            raise ValueError(
                f"boundary_conditions[{bi}] is incomplete. Missing faces: {missing_faces}. "
                "Provide all six faces explicitly."
            )
 
        # Pairwise periodic consistency checks.
        face_map = {entry["face"]: entry for entry in prepared_block}
        for neg_face, pos_face in axis_pairs:
            neg = face_map[neg_face]
            pos = face_map[pos_face]
            neg_periodic = (neg["type"] == "PERIODIC")
            pos_periodic = (pos["type"] == "PERIODIC")
            if neg_periodic != pos_periodic:
                raise ValueError(
                    f"Inconsistent periodicity in block {bi}: {neg_face} and {pos_face} must both be PERIODIC or neither."
                )
 
            driven_handlers = {"constant_flux", "initial_flux"}
            if (neg["handler"] in driven_handlers) or (pos["handler"] in driven_handlers):
                if neg["handler"] != pos["handler"]:
                    raise ValueError(
                        f"In block {bi}, driven periodic handlers on {neg_face}/{pos_face} must match exactly."
                    )
                if not (neg_periodic and pos_periodic):
                    raise ValueError(
                        f"In block {bi}, driven periodic handler '{neg['handler']}' requires PERIODIC type on both faces."
                    )
 
        prepared_blocks.append(prepared_block)
 
    return prepared_blocks
 
 
def _schema_path_text(path: tuple) -> str:
    """!
    @brief Render an internal schema path tuple as a user-facing YAML path.
    @param[in] path Internal path tuple.
    @return Dotted YAML path.
    """
    return ".".join(part for part in path if part != "[]") or "<root>"
 
 
def _lookup_allowed_schema_keys(schema: dict, path: tuple):
    """!
    @brief Return allowed keys for a path, honoring '*' dynamic mapping entries.
    @param[in] schema Role schema mapping.
    @param[in] path Internal path tuple.
    @return Allowed key set, None for free-form mappings, or False when path is not schema-checked.
    """
    if path in schema:
        return schema[path]
    for idx, part in enumerate(path):
        if part == "[]":
            continue
        candidate = path[:idx] + ("*",) + path[idx + 1:]
        if candidate in schema:
            return schema[candidate]
    return False
 
 
def _schema_key_hint(schema: dict, path: tuple, key: str, allowed: set) -> str:
    """!
    @brief Build a concise typo or hierarchy hint for an unsupported YAML key.
    @param[in] schema Role schema mapping.
    @param[in] path Current internal YAML path tuple.
    @param[in] key Unsupported YAML key.
    @param[in] allowed Allowed keys at the current path.
    @return Optional hint string.
    """
    hints = []
    allowed_strings = sorted(str(item) for item in allowed)
    lower_matches = [item for item in allowed_strings if item.lower() == key.lower()]
    close_matches = lower_matches or difflib.get_close_matches(key, allowed_strings, n=1, cutoff=0.80)
    if close_matches:
        hints.append(f"Did you mean '{close_matches[0]}'?")
 
    valid_paths = []
    for schema_path, schema_allowed in schema.items():
        if schema_path == path or not schema_allowed:
            continue
        if key in schema_allowed:
            valid_paths.append(_schema_path_text(schema_path))
    if valid_paths:
        hints.append(f"This key is valid at: {', '.join(sorted(valid_paths))}.")
 
    return " ".join(hints)
 
 
def _validate_yaml_schema_keys(cfg, schema: dict, file_path: str, errors: list, path: tuple = ()) -> None:
    """!
    @brief Reject unsupported YAML keys before they can be silently ignored by staging.
    @param[in] cfg Parsed YAML node.
    @param[in] schema Role schema mapping.
    @param[in] file_path Source file path for diagnostics.
    @param[in,out] errors Validation error accumulator.
    @param[in] path Current internal YAML path tuple.
    """
    if isinstance(cfg, dict):
        allowed = _lookup_allowed_schema_keys(schema, path)
        if allowed is not False and allowed is not None:
            unknown = sorted(str(key) for key in cfg.keys() if key not in allowed)
            for key in unknown:
                hint = _schema_key_hint(schema, path, key, allowed)
                hint_text = f" {hint}" if hint else ""
                errors.append(
                    f"  {file_path}: unsupported key at {_schema_path_text(path)}: '{key}'. "
                    f"Allowed keys: {sorted(allowed)}.{hint_text}"
                )
        if allowed is None:
            return
        for key, value in cfg.items():
            _validate_yaml_schema_keys(value, schema, file_path, errors, path + (key,))
    elif isinstance(cfg, list):
        for item in cfg:
            _validate_yaml_schema_keys(item, schema, file_path, errors, path + ("[]",))
 
 
_CASE_SCHEMA = {
    (): {
        "title", "properties", "run_control", "grid", "models", "boundary_conditions", "solver_parameters",
    },
    ("run_control",): {"start_step", "total_steps", "dt_physical"},
    ("properties",): {"scaling", "fluid", "initial_conditions"},
    ("properties", "scaling"): {"length_ref", "velocity_ref"},
    ("properties", "fluid"): {"density", "viscosity"},
    ("properties", "initial_conditions"): {
        "mode", "generator", "params", "field", "source_file",
        "u_physical", "v_physical", "w_physical", "peak_velocity_physical",
        "velocity_physical", "flow_direction",
    },
    ("properties", "initial_conditions", "params"): None,
    ("grid",): {
        "mode", "source_file", "programmatic_settings", "generator",
        "da_processors_x", "da_processors_y", "da_processors_z",
    },
    ("grid", "programmatic_settings"): {
        "im", "jm", "km", "xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs",
        "rxs", "rys", "rzs", "cgrids",
        "da_processors_x", "da_processors_y", "da_processors_z",
    },
    ("grid", "generator"): {
        "script", "config_file", "grid_type", "cli_args", "output_file", "stats_file", "vts_file",
        # Retained so existing warning behavior for typo-prone hyphen keys is not bypassed.
        "config-file", "grid-type", "output-file", "stats-file", "vts-file",
    },
    ("models",): {"domain", "physics"},
    ("models", "domain"): {"blocks"},
    ("models", "physics"): {"dimensionality", "fsi", "particles", "turbulence"},
    ("models", "physics", "fsi"): {"immersed", "moving_fsi"},
    ("models", "physics", "particles"): {"count", "init_mode", "restart_mode", "point_source"},
    ("models", "physics", "particles", "point_source"): {"x", "y", "z"},
    ("models", "physics", "turbulence"): {"les", "rans", "wall_function"},
    ("models", "physics", "turbulence", "les"): {
        "enabled", "model", "constant_cs", "dynamic_frequency", "filter_width",
        "test_filter", "averaging", "clipping", "gradient_model", "diagnostics",
    },
    ("models", "physics", "turbulence", "les", "test_filter"): {"kernel", "width_ratio"},
    ("models", "physics", "turbulence", "les", "averaging"): {"mode", "directions"},
    ("models", "physics", "turbulence", "les", "clipping"): {
        "mode", "max_cs", "min_viscosity_ratio",
    },
    ("models", "physics", "turbulence", "les", "gradient_model"): {"enabled"},
    ("models", "physics", "turbulence", "les", "diagnostics"): {
        "enabled", "cadence", "yoshizawa_ci",
    },
    ("models", "physics", "turbulence", "rans"): {"enabled", "model"},
    ("models", "physics", "turbulence", "wall_function"): {"enabled", "model", "roughness_height"},
    ("boundary_conditions", "[]"): {"face", "type", "handler", "params"},
    ("boundary_conditions", "[]", "[]"): {"face", "type", "handler", "params"},
    ("boundary_conditions", "[]", "params"): None,
    ("boundary_conditions", "[]", "[]", "params"): None,
    ("solver_parameters",): None,
}
 
 
_SOLVER_SCHEMA = {
    (): {
        "operation_mode", "strategy", "tolerances", "momentum_solver", "poisson_solver",
        "pressure_solver", "interpolation", "petsc_passthrough_options", "verification",
        "scalar_transport",
    },
    ("operation_mode",): {"eulerian_field_source", "analytical_type", "uniform_flow"},
    ("operation_mode", "uniform_flow"): {"u", "v", "w"},
    ("strategy",): {"momentum_solver", "central_diff"},
    ("tolerances",): {
        "max_iterations", "absolute_tol", "relative_tol", "step_tol",
        "residual_absolute_tol", "residual_relative_tol",
    },
    ("momentum_solver",): {
        "type", "dual_time_picard_jameson_rk", "dual_time_picard_rk4", "newton_krylov",
    },
    ("momentum_solver", "dual_time_picard_jameson_rk"): {
        "max_pseudo_steps", "absolute_tol", "relative_tol", "step_tol", "pseudo_cfl",
        "jameson_residual_noise_allowance_factor", "rk4_residual_noise_allowance_factor",
        "ratio_ema_alpha",
    },
    ("momentum_solver", "dual_time_picard_jameson_rk", "pseudo_cfl"): {
        "initial", "minimum", "maximum", "growth_factor", "reduction_factor",
    },
    ("momentum_solver", "dual_time_picard_rk4"): {
        "max_pseudo_steps", "absolute_tol", "relative_tol", "step_tol", "pseudo_cfl",
        "jameson_residual_noise_allowance_factor", "rk4_residual_noise_allowance_factor",
        "ratio_ema_alpha",
    },
    ("momentum_solver", "dual_time_picard_rk4", "pseudo_cfl"): {
        "initial", "minimum", "maximum", "growth_factor", "reduction_factor",
    },
    ("momentum_solver", "newton_krylov"): {
        "jacobian", "preconditioner", "nonlinear_solver", "linear_solver",
    },
    ("momentum_solver", "newton_krylov", "jacobian"): {"type", "finite_difference"},
    ("momentum_solver", "newton_krylov", "jacobian", "finite_difference"): {"mode"},
    ("momentum_solver", "newton_krylov", "preconditioner"): {"model", "structure"},
    ("momentum_solver", "newton_krylov", "preconditioner", "structure"): {"type"},
    ("momentum_solver", "newton_krylov", "nonlinear_solver"): {
        "method", "absolute_tolerance", "relative_tolerance", "step_tolerance",
        "max_iterations", "line_search", "eisenstat_walker",
    },
    ("momentum_solver", "newton_krylov", "nonlinear_solver", "line_search"): {"type"},
    ("momentum_solver", "newton_krylov", "nonlinear_solver", "eisenstat_walker"): {
        "enabled", "version", "initial_relative_tolerance", "maximum_relative_tolerance",
        "gamma", "exponent", "safeguard_exponent", "safeguard_threshold",
    },
    ("momentum_solver", "newton_krylov", "linear_solver"): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations",
        "gmres", "preconditioner",
    },
    ("momentum_solver", "newton_krylov", "linear_solver", "gmres"): {"restart"},
    ("momentum_solver", "newton_krylov", "linear_solver", "preconditioner"): {"type"},
    ("poisson_solver",): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations", "tolerance",
        "gmres", "preconditioner", "multigrid",
    },
    ("pressure_solver",): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations", "tolerance",
        "gmres", "preconditioner", "multigrid",
    },
    ("poisson_solver", "gmres"): {"restart"},
    ("pressure_solver", "gmres"): {"restart"},
    ("poisson_solver", "preconditioner"): {"type"},
    ("pressure_solver", "preconditioner"): {"type"},
    ("poisson_solver", "multigrid"): {
        "levels", "pre_sweeps", "post_sweeps", "cycle", "mode", "semi_coarsening", "level_solvers",
    },
    ("pressure_solver", "multigrid"): {
        "levels", "pre_sweeps", "post_sweeps", "cycle", "mode", "semi_coarsening", "level_solvers",
    },
    ("poisson_solver", "multigrid", "semi_coarsening"): {"i", "j", "k"},
    ("pressure_solver", "multigrid", "semi_coarsening"): {"i", "j", "k"},
    ("poisson_solver", "multigrid", "level_solvers", "*"): {
        "method", "preconditioner", "ksp_type", "pc_type", "max_it", "rtol", "atol",
    },
    ("pressure_solver", "multigrid", "level_solvers", "*"): {
        "method", "preconditioner", "ksp_type", "pc_type", "max_it", "rtol", "atol",
    },
    ("interpolation",): {"method"},
    ("petsc_passthrough_options",): None,
    ("verification",): {"sources"},
    ("verification", "sources"): {"diffusivity", "scalar"},
    ("verification", "sources", "diffusivity"): {"mode", "profile", "gamma0", "slope_x"},
    ("verification", "sources", "scalar"): {
        "mode", "profile", "value", "phi0", "slope_x", "amplitude", "kx", "ky", "kz",
    },
    ("scalar_transport",): {"schmidt_number", "turbulent_schmidt_number"},
}
 
 
_MONITOR_SCHEMA = {
    (): {
        "logging", "profiling", "diagnostics", "io", "solver_monitoring", "solution_monitoring",
        "field_statistics",
    },
    ("logging",): {"verbosity", "enabled_functions"},
    ("profiling",): {"timestep_output", "final_summary"},
    ("profiling", "timestep_output"): {"mode", "functions", "file"},
    ("profiling", "final_summary"): {"enabled"},
    ("diagnostics",): {"petsc", "runtime_memory_log"},
    ("diagnostics", "petsc"): {
        "info", "malloc_debug", "malloc_test", "malloc_dump", "malloc_view", "malloc_view_threshold",
        "memory_view", "log_view", "log_view_memory", "log_all", "log_trace",
        "objects_dump", "options_left",
    },
    ("diagnostics", "petsc", "info"): {"enabled", "classes"},
    ("diagnostics", "runtime_memory_log"): {"enabled", "file"},
    ("io",): {
        "data_output_frequency", "particle_console_output_frequency", "particle_log_interval",
        "statistics_console_output_frequency",
    },
    ("solver_monitoring",): {"momentum", "poisson", "petsc_passthrough_options"},
    ("solver_monitoring", "momentum"): {
        "newton_krylov_history", "snes_monitor", "snes_converged_reason",
        "ksp_monitor", "ksp_converged_reason",
    },
    ("solver_monitoring", "poisson"): {"pic_true_residual", "true_residual", "converged_reason", "view"},
    ("solver_monitoring", "petsc_passthrough_options"): None,
    ("solution_monitoring",): {"convergence"},
    ("solution_monitoring", "convergence"): {
        "enabled", "mode", "periodic_deterministic", "statistical_steady",
    },
    ("solution_monitoring", "convergence", "periodic_deterministic"): {"period_steps"},
    ("solution_monitoring", "convergence", "statistical_steady"): {"window_steps"},
    ("field_statistics",): {"enabled", "windows"},
    ("field_statistics", "windows", "[]"): {
        "name", "start_time", "end_time", "weighting",
        "step_cadence", "time_cadence", "fields", "covariances",
    },
    ("field_statistics", "windows", "[]", "fields", "[]"): {"field", "moments"},
}
 
 
#: Eulerian fields a statistics window may accumulate, with the subsystem each needs.
#:
#: This is a curated subset of the typed catalog rather than a mirror of it. Averaging
#: a grid metric is meaningless, and a face-staggered field has no single pointwise
#: location, so offering the whole catalog would only move the rejection later and
#: make it harder to read. `tests/test_cli_smoke.py` asserts every entry here still
#: exists in `src/field_catalog.c` with the layout recorded, so the two cannot drift.
STATISTICS_ELIGIBLE_FIELDS = {
    "Ucat": {"components": 3, "requires": None},
    "P": {"components": 1, "requires": None},
    "Nvert": {"components": 1, "requires": None},
    "Phi": {"components": 1, "requires": None},
    "Psi": {"components": 1, "requires": "particles"},
    "ParticleCount": {"components": 1, "requires": "particles"},
    "Nu_t": {"components": 1, "requires": "turbulence"},
    "CS": {"components": 1, "requires": "les"},
}
 
#: Moment names one field may request. Higher moments cannot be recovered from
#: centered state after the fact, so they need their own accumulation rather than
#: an extension of this list.
STATISTICS_MOMENT_NAMES = ("first", "second")
 
#: Weighting modes a window may select.
STATISTICS_WEIGHTING_MODES = ("sample", "physical_time")
 
 
_POST_SCHEMA = {
    (): {
        "run_control", "source_data", "global_operations", "eulerian_pipeline",
        "lagrangian_pipeline", "statistics_pipeline", "statistics_output_prefix",
        "field_statistics", "spectra", "io",
    },
    ("field_statistics",): {"windows", "source_step", "outputs", "formats"},
    ("spectra",): {"output_prefix", "tasks"},
    ("spectra", "tasks", "[]"): {
        "task", "field", "block", "symbol", "subtract_mean", "mean_source_step",
        "reference",
    },
    ("run_control",): {
        "start_step", "end_step", "step_interval", "startTime", "endTime", "timeStep",
    },
    ("source_data",): {"directory", "input_extensions"},
    ("source_data", "input_extensions"): {"eulerian", "particle"},
    ("global_operations",): {"dimensionalize"},
    ("eulerian_pipeline", "[]"): {"task", "input_field", "output_field", "field", "reference_point"},
    ("lagrangian_pipeline", "[]"): {"task", "input_field", "output_field"},
    ("statistics_pipeline",): {"output_prefix", "tasks"},
    ("statistics_pipeline", "tasks", "[]"): {"task"},
    ("io",): {
        "output_directory", "output_filename_prefix", "particle_filename_prefix", "output_particles",
        "particle_subsampling_frequency", "input_extensions",
        "eulerian_fields", "particle_fields",
    },
    ("io", "input_extensions"): {"eulerian", "particle"},
}
 
 
_CLUSTER_SCHEMA = {
    (): {"scheduler", "resources", "notifications", "execution"},
    ("scheduler",): {"type"},
    ("resources",): {"account", "partition", "nodes", "ntasks_per_node", "mem", "time"},
    ("notifications",): {"mail_user", "mail_type"},
    ("execution",): {
        "module_setup", "launcher", "launcher_args", "extra_sbatch", "walltime_guard",
    },
    ("execution", "extra_sbatch"): None,
    ("execution", "walltime_guard"): {
        "enabled", "warmup_steps", "multiplier", "min_seconds", "estimator_alpha",
    },
}
 
 
_STUDY_SCHEMA = {
    (): {
        "title", "base_configs", "study_type", "parameters", "parameter_sets", "metrics", "plotting", "execution",
    },
    ("base_configs",): {"case", "solver", "monitor", "post"},
    ("parameters",): None,
    ("parameter_sets", "[]"): None,
    ("metrics", "[]"): {
        "name", "source", "file_glob", "column", "reduction", "normalize_by_parameter",
        "numerator_column", "denominator_column", "denominator_floor",
        "plot_label", "label", "units",
    },
    ("plotting",): {"enabled", "output_format"},
    ("execution",): {"max_concurrent_array_tasks"},
}
 
 
_WORKSPACE_SCHEMA = {
    (): {"schema_version", "workspace", "software", "paths", "reproducibility"},
    ("workspace",): {"id", "template", "created_at"},
    ("software",): {"picurv"},
    ("paths",): {"config", "inputs", "assets", "runs", "studies"},
    ("reproducibility",): {"require_clean_release", "pin_executables"},
}
 
 
# Directories the run owns and writes into. `log` is the safety-critical one: the C
# runtime calls PetscRMTree on it at the start of a fresh solve, so a value that
# escapes the run directory means the solver recursively deletes whatever is there.
RUN_OWNED_DIRECTORY_KEYS = ("log", "output")
UNSAFE_PATHS_OVERRIDE_KEY = "allow_unsafe_paths"
 
# Directory names the run tree already owns. A run-owned directory must not collide
# with one of these: the log directory in particular is recursively deleted at the
# start of a fresh solve, so pointing it at `config` would destroy the run's own
# provenance before the solver had produced anything.
RESERVED_RUN_DIRECTORY_NAMES = ("config", "scheduler", "checkpoints", "visualization")
 
# Defaults the runtime uses when a run-owned directory is not configured. An omitted
# key is not absent at runtime, so collision checks must resolve these first.
RUN_DIRECTORY_DEFAULTS = {"log": "logs", "output": "output"}
 
# Runtime flags that select run-owned directories. The workspace contract owns them;
# raw passthrough must not replace the canonical values emitted by the generator.
RESERVED_DIRECTORY_FLAGS = (
    "-log_dir", "-output_dir", "-restart_dir", "-analysis_dir",
    "-allow_unsafe_log_dir",
)
 
# PETSc indirection that could reintroduce a reserved flag without naming it. An
# options file or an alias is evaluated by PETSc itself, so its contents are outside
# every check this module performs.
RESERVED_INDIRECTION_FLAGS = ("-options_file", "-options_file_yaml", "-alias")
 
 
# Characters that cannot survive a PETSc options line unambiguously. A run
# subdirectory name containing whitespace, quotes, or a comment marker either needs
# quoting the generator does not apply, or changes how PETSc tokenizes the line.
# Rejecting them keeps the generated control file unambiguous by construction.
UNSAFE_DIRECTORY_CHARACTERS = ('"', "'", "#", "\n", "\r", "\t")
 
 
def directory_value_charset_problem(value: str) -> str:
    """!
    @brief Describe why a directory value cannot be written to a PETSc options line.
    @param[in] value Configured directory value.
    @return Human-readable reason, or an empty string when the value is safe.
    """
    if any(character.isspace() for character in value):
        return "contains whitespace"
    for character in UNSAFE_DIRECTORY_CHARACTERS:
        if character in value:
            label = {'"': "a double quote", "'": "a single quote", "#": "a comment marker"}.get(
                character, "a control character"
            )
            return f"contains {label}"
    return ""
 
 
def classify_run_directory_value(value) -> str:
    """!
    @brief Classify a configured run directory value.
 
    @details Containment is judged lexically against the run directory, because the run
             directory does not exist yet at validation time. Beyond escaping, a value
             is rejected when it resolves to the run root itself: the log directory is
             recursively deleted on a fresh solve, so `.` or `a/..` would delete the run.
    @param[in] value Configured directory value from monitor `io.directories`.
    @return One of "contained", "escaping", "tilde", "run_root", or "invalid".
    """
    if not isinstance(value, str) or not value.strip():
        return "invalid"
    candidate = value.strip()
    # `~` is its own verdict because nothing expands it anywhere in the pipeline. The
    # control file is read by PETSc, not by a shell, and both the planner and the C
    # runtime treat a value not starting with `/` as relative to the run - so `~/logs`
    # names a literal `~` directory inside the run tree.
    #
    # It was worse before this verdict existed: physical containment classified `~` as
    # an authorizable external absolute location by expanding it, while every layer
    # that actually used the value treated it literally. The two disagreed about which
    # directory was being deleted. The fix is to refuse the value, not to expand it -
    # expanding it in one layer would only move the disagreement.
    if candidate.startswith("~"):
        return "tilde"
    if os.path.isabs(candidate):
        return "escaping"
    normalized = os.path.normpath(candidate)
    if normalized == os.pardir or normalized.startswith(os.pardir + os.sep):
        return "escaping"
    if normalized in (".", ""):
        return "run_root"
    return "contained"
 
 
def normalized_run_directory(value: str) -> str:
    """!
    @brief Normalized, comparable form of a contained run directory value.
    @param[in] value Configured directory value.
    @return Normalized relative path.
    """
    return os.path.normpath(str(value).strip()).replace(os.sep, "/")
 
 
def paths_overlap(first: str, second: str) -> bool:
    """!
    @brief Whether two run-relative directories are the same or nested in one another.
    @param[in] first Normalized directory.
    @param[in] second Normalized directory.
    @return True when one contains the other.
    """
    if first == second:
        return True
    return first.startswith(second + "/") or second.startswith(first + "/")
 
 
def resolve_unsafe_paths_override(dirs: dict, monitor_path: str) -> tuple:
    """!
    @brief Resolve the unsafe-paths override, requiring a real YAML boolean.
 
    @details A truthy string such as "false" must never enable an override that permits
             a destructive path. Only a genuine boolean `true` enables it; any other
             type is a configuration error rather than a silent interpretation.
    @param[in] dirs The `io.directories` mapping.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (enabled, errors).
    """
    if UNSAFE_PATHS_OVERRIDE_KEY not in dirs:
        return False, []
    raw = dirs[UNSAFE_PATHS_OVERRIDE_KEY]
    if raw is True:
        return True, []
    if raw is False:
        return False, []
    return False, [
        f"  {monitor_path}: 'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}' must be a YAML boolean "
        f"(true or false), got {raw!r}. Quoted strings and numbers are rejected so a value like "
        f"\"false\" cannot silently enable an unsafe path."
    ]
 
 
def evaluate_run_directories(values: dict, override: bool, explicit: set = None) -> tuple:
    """!
    @brief Apply every run-directory safety rule to a set of effective directory values.
 
    @details Single source of truth for the rules, shared by configuration validation and
             submission preflight so the two cannot drift apart. Callers must pass
             *effective* values with defaults filled in.
 
             Two classes of finding are distinguished. **Waivable** findings concern a
             deliberate external location; `allow_unsafe_paths` downgrades those to
             warnings. **Non-waivable** findings concern self-destruction or a value that
             cannot be written unambiguously - the run root itself, a reserved run
             directory, log/output overlap, and malformed characters. The override was
             granted for deliberate external storage, never for deleting the run's own
             config or emitting an ambiguous option line, so those stay errors.
    @param[in] values Effective mapping of directory key to configured value.
    @param[in] override Whether the unsafe-paths override is enabled.
    @param[in] explicit Keys the user actually configured; the rest are reported as defaults.
    @return Tuple of (errors, warnings) as bare messages without a file prefix.
    """
    errors: list = []
    warnings: list = []
    configured_keys = set(values) if explicit is None else set(explicit)
 
    def waivable(message: str) -> None:
        """!
        @brief Record a finding the unsafe-paths override may downgrade.
        @param[in] message Finding text.
        @return None.
        """
        if override:
            warnings.append(
                f"{message} Allowed only because '{UNSAFE_PATHS_OVERRIDE_KEY}: true' is set."
            )
        else:
            errors.append(
                f"{message} Use a directory inside the run tree, or set "
                f"'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}: true' to override deliberately."
            )
 
    def fatal(message: str) -> None:
        """!
        @brief Record a finding the override must never waive.
        @param[in] message Finding text.
        @return None.
        """
        errors.append(f"{message} This cannot be overridden.")
 
    destructive_note = (
        "On a fresh solve the runtime RECURSIVELY DELETES this directory before writing to it."
    )
    resolved: dict = {}
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key not in values:
            continue
        raw = values[key]
        detail = destructive_note if key == "log" else (
            "Run output must stay inside the run directory so it can be archived and restored."
        )
        if not isinstance(raw, str) or not raw.strip():
            fatal(f"'io.directories.{key}' must be a non-empty relative path (got {raw!r}).")
            continue
 
        # Both axes are reported. Escaping is the safety-critical property and leads,
        # but character problems are non-waivable, so a value that is both must not be
        # able to slip through by overriding only the escape.
        verdict = classify_run_directory_value(raw)
        charset_problem = directory_value_charset_problem(raw)
        if charset_problem:
            fatal(
                f"'io.directories.{key}' = {raw!r} {charset_problem}. Run directory names must be "
                f"writable to a PETSc options line without quoting; use a plain relative path such "
                f"as 'logs' or 'diagnostics/run1'."
            )
        if verdict == "tilde":
            fatal(
                f"'io.directories.{key}' = {raw!r} starts with '~', which nothing expands. "
                f"The control file is read by PETSc rather than by a shell, and the C "
                f"runtime resolves a value not starting with '/' relative to the run - so "
                f"this would be planned as one directory and deleted as another. Give a "
                f"real absolute path if an external location is intended. This cannot be "
                f"overridden."
            )
            continue
        if verdict == "escaping":
            if not (isinstance(raw, str) and raw.strip().startswith("/")):
                fatal(
                    f"'io.directories.{key}' = {raw!r} escapes the run directory by relative "
                    f"traversal. {detail} A relative escape lands among sibling runs and study "
                    f"members, so it is never authorizable; give an absolute path if an external "
                    f"location is genuinely intended."
                )
                continue
            # No `continue`: an authorized absolute path must still face the
            # non-waivable checks below, or it could target a run-owned directory such
            # as `/abs/run/config`.
            waivable(f"'io.directories.{key}' = {raw!r} escapes the run directory. {detail}")
        if verdict == "run_root":
            fatal(
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself. "
                + (destructive_note + " That would delete the entire run."
                   if key == "log" else "Run output must live in its own subdirectory.")
            )
            continue
        if charset_problem:
            continue
        normalized = normalized_run_directory(raw)
        resolved[key] = normalized
        # Every segment is checked, not just the first: `./config`, `output/sub`, and
        # `/abs/run/config` all target run-owned directories.
        segments = [s for s in normalized.split("/") if s not in ("", ".")]
        hit = next((s for s in segments if s in RESERVED_RUN_DIRECTORY_NAMES), None)
        if hit:
            fatal(
                f"'io.directories.{key}' = {raw!r} targets the reserved run directory "
                f"'{hit}'. " + (destructive_note if key == "log"
                                else "That directory is owned by the run tree.")
            )
 
    if "log" in resolved and "output" in resolved and paths_overlap(resolved["log"], resolved["output"]):
        log_source = "" if "log" in configured_keys else " (default)"
        out_source = "" if "output" in configured_keys else " (default)"
        fatal(
            f"'io.directories.log' ({resolved['log']!r}{log_source}) and 'io.directories.output' "
            f"({resolved['output']!r}{out_source}) overlap. {destructive_note} "
            f"That would delete solver output."
        )
    return errors, warnings
 
 
# Typed physical verdicts. Waivability is decided on the verdict, never on a substring
# of the message: a finding reading "resolves to the run directory itself" contains no
# word like "escapes", so message matching silently downgraded self-destruction to a
# warning. Message text is for humans; these constants are for the rule.
PHYSICAL_VERDICT_CONTAINED = "contained"
PHYSICAL_VERDICT_RUN_ROOT = "run_root"
PHYSICAL_VERDICT_ANCESTOR = "ancestor"
PHYSICAL_VERDICT_RELATIVE_ESCAPE = "relative_escape"
PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE = "external_absolute"
 
# The only verdict an explicit authorization may waive. An external absolute location
# is a deliberate, if dangerous, choice. Deleting the run itself, or an ancestor of it,
# or following a relative symlink out of the tree, are not choices anyone makes on
# purpose, so no authorization reaches them.
WAIVABLE_PHYSICAL_VERDICTS = frozenset({PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE})
 
 
def classify_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Classify where each run-owned directory physically lands.
 
    @details Lexical containment is not enough: a contained name can be a symlink to an
             external directory, and `PetscRMTree` follows symlinks. This resolves the
             real path - including any symlinked ancestor - and reports a typed verdict
             so the caller can apply the waiver rule structurally.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return List of (key, verdict, message) for every value that is not contained.
    """
    findings: list = []
    try:
        root = os.path.realpath(run_dir)
    except OSError:
        return findings
    for key in RUN_OWNED_DIRECTORY_KEYS:
        raw = values.get(key)
        if not isinstance(raw, str) or not raw.strip():
            continue
        text = raw.strip()
        # Whether the *value* was given as an absolute location, which is the only form
        # an authorization can cover. A relative name that resolves outside the tree got
        # there through a symlink, and that is never what an operator asked for.
        # Only a real absolute path can be waived. `~` is refused before this point by
        # the lexical rules, and is not expanded here either: an earlier version did
        # expand it, which made this layer reason about a home directory no other layer
        # ever resolves.
        absolute = text.startswith("/")
        candidate = os.path.join(run_dir, text)
        real = os.path.realpath(candidate)
 
        if real == root:
            findings.append((key, PHYSICAL_VERDICT_RUN_ROOT,
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself "
                f"({real!r}); deleting it would destroy the run. This cannot be overridden."))
        elif real == os.sep or root.startswith(real.rstrip(os.sep) + os.sep):
            findings.append((key, PHYSICAL_VERDICT_ANCESTOR,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which CONTAINS the run "
                f"directory {root!r}. The runtime deletes this path recursively, so it would "
                f"destroy the run and everything beside it. This cannot be overridden."))
        elif real.startswith(root + os.sep):
            continue
        elif absolute:
            findings.append((key, PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which is outside the run "
                f"directory {root!r}. The runtime deletes its log directory recursively."))
        else:
            findings.append((key, PHYSICAL_VERDICT_RELATIVE_ESCAPE,
                f"'io.directories.{key}' = {raw!r} is a relative name that resolves to {real!r}, "
                f"outside the run directory {root!r} - a symlink leads out of the tree. A "
                f"relative escape is never authorizable; name an absolute path if an external "
                f"location is genuinely intended. This cannot be overridden."))
    return findings
 
 
def check_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Human-readable physical containment violations.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return Violation lines.
    """
    return [message for _, _, message in classify_physical_containment(run_dir, values)]
 
 
def effective_run_directories(configured: dict) -> dict:
    """!
    @brief Fill in defaults for run-owned directories that were not configured.
 
    @details An omitted key is not absent at runtime, it takes its default. Checking
             only explicit keys would miss `log: output`, which collides with the
             default output directory and would delete solver output.
    @param[in] configured Configured directory mapping, possibly partial.
    @return Effective mapping with defaults applied.
    """
    effective = dict(RUN_DIRECTORY_DEFAULTS)
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key in configured:
            effective[key] = configured[key]
    return effective
 
 
def validate_run_directory_containment(monitor_cfg: dict, monitor_path: str) -> tuple:
    """!
    @brief Classify legacy directory values as defense-in-depth during validation.
    @details The monitor schema rejects this removed surface. Keeping the stricter
             classifier here ensures malformed or manually constructed configurations
             still receive the safety findings that protect recursive log cleanup.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (errors, warnings).
    """
    io_cfg = (monitor_cfg or {}).get("io") or {}
    dirs = io_cfg.get("directories")
    if not isinstance(dirs, dict):
        return [], []
    override, override_errors = resolve_unsafe_paths_override(dirs, monitor_path)
    errors, warnings = evaluate_run_directories(
        effective_run_directories(dirs), override, explicit=set(dirs)
    )
    return (
        override_errors + [f"  {monitor_path}: {message}" for message in errors],
        [f"  {monitor_path}: {message}" for message in warnings],
    )
 
 
def validate_reserved_directory_flags(config: dict, config_path: str, label: str) -> list:
    """!
    @brief Reject raw PETSc passthrough options that set run-owned directories.
 
    @details Passthrough surfaces emit `{flag: value}` verbatim into the generated
             control file. Run-owned path flags are reserved for the fixed workspace
             topology and may only be emitted by the generator.
    @param[in] config Parsed configuration mapping to scan.
    @param[in] config_path Path to the file, for error messages.
    @param[in] label Human-readable description of the surface being scanned.
    @return Violation lines.
    """
    violations: list = []
 
    def scan(node, trail: str) -> None:
        """!
        @brief Walk the mapping looking for reserved flags used as keys.
        @param[in] node Current mapping, list, or scalar node.
        @param[in] trail Dotted path to the current node, for error messages.
        @return None.
        """
        if isinstance(node, dict):
            for key, value in node.items():
                token = key.strip() if isinstance(key, str) else key
                if token in RESERVED_DIRECTORY_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets the reserved flag '{token}' at "
                        f"{trail or '<root>'}. Run directories are fixed by the workspace "
                        "contract; raw passthrough cannot override them."
                    )
                elif token in RESERVED_INDIRECTION_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets '{token}' at {trail or '<root>'}. PETSc "
                        f"evaluates that indirection itself, so its contents cannot be checked "
                        "here and could reintroduce a run-directory flag. Remove the indirection."
                    )
                scan(value, f"{trail}.{key}" if trail else str(key))
        elif isinstance(node, list):
            for index, item in enumerate(node):
                scan(item, f"{trail}[{index}]")
 
    scan(config, "")
    return violations
 
 
def validate_simulation_configs(case_cfg: dict, solver_cfg: dict, monitor_cfg: dict,
                                case_path: str, solver_path: str, monitor_path: str):
    """!
    @brief Validates every configuration a simulation run consumes, before any work is done.
    @details Covers the three roles the solver is launched with: the case, the solver,
             and the monitor. Only one of those is a solver configuration, which is
             why this is not named for the solver; the monitor in particular carries
             observation and field-statistics contracts that have nothing to do with
             the numerical scheme.
 
             Checks required sections, required keys, physical sanity, and the
             cross-file combinations no single file can rule out. Post-processing
             configuration is validated separately by `validate_post_config()`.
    @param[in] case_cfg    Parsed case YAML dictionary.
    @param[in] solver_cfg  Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] case_path   Path to case file (for error messages).
    @param[in] solver_path Path to solver file (for error messages).
    @param[in] monitor_path Path to monitor file (for error messages).
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
    errors.extend(validate_reserved_directory_flags(
        case_cfg, case_path, "case solver_parameters / passthrough"))
    errors.extend(validate_reserved_directory_flags(
        solver_cfg, solver_path, "solver petsc_passthrough_options"))
    eulerian_source_mode = "solve"
 
    legacy_statistics = (case_cfg.get("models", {}) or {}).get("statistics") if isinstance(case_cfg, dict) else None
    if legacy_statistics is not None:
        errors.append(
            f"  {case_path}: 'models.statistics' was removed with the legacy averaging system. "
            "Use instantaneous output and offline postprocessing until the replacement "
            "field-statistics pipeline is available."
        )
    if isinstance(solver_cfg, dict) and "solution_convergence" in solver_cfg:
        errors.append(
            f"  {solver_path}: 'solution_convergence' moved to "
            "monitor.yml -> solution_monitoring.convergence."
        )
    if errors:
        _print_validation_errors(errors)
 
    _validate_yaml_schema_keys(case_cfg, _CASE_SCHEMA, case_path, errors)
    _validate_yaml_schema_keys(solver_cfg, _SOLVER_SCHEMA, solver_path, errors)
    _validate_yaml_schema_keys(monitor_cfg, _MONITOR_SCHEMA, monitor_path, errors)
 
    # --- case.yml: required top-level sections ---
    required_case_sections = ['properties', 'run_control', 'grid', 'models', 'boundary_conditions']
    for section in required_case_sections:
        if section not in case_cfg:
            errors.append(f"  {case_path}: missing required section '{section}'.")
 
    if errors:
        _print_validation_errors(errors)
 
    # --- case.yml: properties sub-keys ---
    props = case_cfg.get('properties', {})
    for group, keys in [('scaling', ['length_ref', 'velocity_ref']),
                        ('fluid', ['density', 'viscosity'])]:
        sub = props.get(group, {})
        if not sub:
            errors.append(f"  {case_path}: missing 'properties.{group}' section.")
        else:
            for k in keys:
                if k not in sub:
                    errors.append(f"  {case_path}: missing key 'properties.{group}.{k}'.")
 
    # --- case.yml: run_control sub-keys ---
    rc = case_cfg.get('run_control', {})
    for k in ['start_step', 'total_steps', 'dt_physical']:
        if k not in rc:
            errors.append(f"  {case_path}: missing key 'run_control.{k}'.")
 
    # --- Physical sanity checks ---
    try:
        density = float(props.get('fluid', {}).get('density', 0))
        viscosity = float(props.get('fluid', {}).get('viscosity', 0))
        dt = float(rc.get('dt_physical', 0))
        if density <= 0:
            errors.append(f"  {case_path}: 'properties.fluid.density' must be positive (got {density}).")
        if viscosity < 0:
            errors.append(f"  {case_path}: 'properties.fluid.viscosity' must be non-negative (got {viscosity}).")
        if dt <= 0:
            errors.append(f"  {case_path}: 'run_control.dt_physical' must be positive (got {dt}).")
    except (TypeError, ValueError):
        pass  # Will be caught later during processing
 
    # --- case.yml: grid mode ---
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    valid_grid_modes = list(GRID_MODES)
    if grid_mode not in valid_grid_modes:
        errors.append(f"  {case_path}: 'grid.mode' must be one of {valid_grid_modes} (got '{grid_mode}').")
    elif grid_mode == 'file':
        source_file = grid_cfg.get('source_file')
        if not source_file:
            errors.append(f"  {case_path}: 'grid.source_file' is required when grid.mode is 'file'.")
        else:
            try:
                source_abs = resolve_workspace_path(case_path, source_file)
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not os.path.isfile(source_abs):
                    errors.append(f"  {case_path}: grid.source_file does not exist: {source_abs}")
    elif grid_mode == 'programmatic_c':
        grid_settings = grid_cfg.get('programmatic_settings')
        if not grid_settings:
            errors.append(f"  {case_path}: 'grid.programmatic_settings' is required when grid.mode is 'programmatic_c'.")
        elif not isinstance(grid_settings, dict):
            errors.append(f"  {case_path}: 'grid.programmatic_settings' must be a mapping.")
    elif grid_mode == 'grid_gen':
        gen_cfg = grid_cfg.get('generator')
        if not isinstance(gen_cfg, dict):
            errors.append(f"  {case_path}: 'grid.generator' must be a mapping when grid.mode is 'grid_gen'.")
        else:
            warn_on_grid_generator_hyphen_keys(gen_cfg, case_path, warnings)
            errors.extend(
                reject_generator_destination_keys(gen_cfg, case_path, "grid.generator")
            )
 
            config_file = gen_cfg.get('config_file')
            if not config_file:
                errors.append(f"  {case_path}: 'grid.generator.config_file' is required for grid.mode='grid_gen'.")
            else:
                try:
                    config_abs = resolve_workspace_path(case_path, config_file)
                except ValueError as exc:
                    errors.append(f"  {case_path}: {exc}")
                else:
                    if not os.path.isfile(config_abs):
                        errors.append(f"  {case_path}: grid.generator.config_file does not exist: {config_abs}")
 
            grid_type = gen_cfg.get('grid_type')
            if grid_type is not None and str(grid_type) not in GRID_GENERATOR_TYPES:
                errors.append(f"  {case_path}: grid.generator.grid_type must be one of "
                              f"{list(GRID_GENERATOR_TYPES)} (got '{grid_type}').")
 
            # cli_args is an opaque token list handed straight to the generator, so a bad
            # geometry selector inside it would otherwise surface as a nonzero subprocess
            # exit in the middle of a run rather than as a validation error before one.
            errors.extend(validate_grid_generator_cli_args(gen_cfg.get('cli_args'), case_path))
 
            cli_args = gen_cfg.get('cli_args', [])
            if cli_args is not None and not isinstance(cli_args, list):
                errors.append(f"  {case_path}: grid.generator.cli_args must be a list of CLI tokens.")
    try:
        resolve_grid_da_processor_layout(grid_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: boundary_conditions strict validation ---
    prepared_blocks = None
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: initial_conditions mode-aware validation ---
    ic = props.get('initial_conditions', {})
    resolved_ic = None
    try:
        ic_start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        ic_start_step = 0
    try:
        ic_eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
    except ValueError:
        # The solver-specific validation below reports an invalid source value.
        # Keep IC validation independent of that diagnostic.
        ic_eulerian_source = "solve"
    ic_is_authoritative = ic_eulerian_source == "solve" and ic_start_step == 0
    if not ic:
        errors.append(f"  {case_path}: missing 'properties.initial_conditions' section.")
    elif not isinstance(ic, dict):
        errors.append(f"  {case_path}: 'properties.initial_conditions' must be a mapping.")
    elif 'mode' not in ic:
        errors.append(
            f"  {case_path}: missing key 'properties.initial_conditions.mode'. "
            "Specify 'generated' or 'file' explicitly."
        )
    elif ic_is_authoritative:
        try:
            scaling_contract = resolve_fluid_scaling(case_cfg)
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, U_ref=scaling_contract["velocity_ref"],
                provider_context={"kinematic_viscosity": scaling_contract["nondimensional_kinematic_viscosity"]},
            )
        except KeyError as e:
            errors.append(f"  {case_path}: missing key 'properties.initial_conditions.{e.args[0]}'.")
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
    if (ic_is_authoritative and resolved_ic and
            GENERATED_IC_PROVIDERS.get(resolved_ic.get("kind"), {}).get("requires_fresh_3d")):
        dimensionality = str((((case_cfg.get("models", {}) or {}).get("physics", {}) or {})
                             .get("dimensionality", "3D"))).strip().upper()
        if dimensionality != "3D":
            errors.append(f"  {case_path}: {resolved_ic['label']} requires models.physics.dimensionality: 3D.")
        if grid_mode == "programmatic_c":
            settings = grid_cfg.get("programmatic_settings", {}) or {}
            ratios = [settings.get(key, 1.0) for key in ("rxs", "rys", "rzs")]
            try:
                if any(abs(float(value) - 1.0) > 1.0e-12 for value in ratios):
                    errors.append(f"  {case_path}: {resolved_ic['label']} requires uniform programmatic spacing (rxs/rys/rzs: 1.0).")
            except (TypeError, ValueError):
                pass
    if grid_mode == 'programmatic_c' and resolved_ic and is_generated_ic_provider(resolved_ic):
        try:
            validate_programmatic_generated_ic_grid_settings(grid_cfg.get('programmatic_settings'))
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: particle initialization validation ---
    particles_cfg = case_cfg.get('models', {}).get('physics', {}).get('particles', {})
    if particles_cfg and not isinstance(particles_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.particles' must be a mapping.")
    elif isinstance(particles_cfg, dict):
        init_mode_raw = particles_cfg.get('init_mode', 'Surface')
        try:
            pinit_code = normalize_particle_init_mode(init_mode_raw)
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
            pinit_code = None
 
        restart_mode = particles_cfg.get('restart_mode')
        if restart_mode is not None and str(restart_mode).lower() not in PARTICLE_RESTART_MODES:
            errors.append(
                f"  {case_path}: models.physics.particles.restart_mode must be 'init' or 'load' (got '{restart_mode}')."
            )
        elif 'restart_mode' not in particles_cfg:
            try:
                start_step = int(rc.get('start_step', 0))
                particle_count = int(particles_cfg.get('count', 0) or 0)
            except (TypeError, ValueError):
                start_step = 0
                particle_count = 0
            if start_step > 0 and particle_count > 0:
                warnings.append(
                    f"{case_path}: models.physics.particles.restart_mode is omitted for a particle restart "
                    "(run_control.start_step > 0, count > 0). C will default to 'load'."
                )
 
        if pinit_code == 2:
            point_cfg = particles_cfg.get('point_source', {})
            if not isinstance(point_cfg, dict):
                errors.append(f"  {case_path}: models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
            else:
                for coord in ('x', 'y', 'z'):
                    if coord not in point_cfg:
                        errors.append(
                            f"  {case_path}: models.physics.particles.point_source.{coord} is required when init_mode is PointSource."
                        )
 
    # --- case.yml: turbulence model validation ---
    turbulence_cfg = case_cfg.get('models', {}).get('physics', {}).get('turbulence', {})
    if turbulence_cfg is not None and not isinstance(turbulence_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.turbulence' must be a mapping.")
    elif isinstance(turbulence_cfg, dict) and turbulence_cfg:
        try:
            append_turbulence_flags(case_cfg.get('models', {}), [])
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
        les_cfg = turbulence_cfg.get('les')
        rans_cfg = turbulence_cfg.get('rans')
        wall_cfg = turbulence_cfg.get('wall_function')
 
        if isinstance(les_cfg, dict):
            validate_les_configuration(case_cfg, les_cfg, case_path, errors, warnings)
 
        validate_wall_model_pairing(case_cfg, les_cfg, rans_cfg, wall_cfg, case_path,
                                    errors, warnings)
 
        if isinstance(rans_cfg, dict):
            if 'enabled' in rans_cfg and not isinstance(rans_cfg['enabled'], bool):
                errors.append(f"  {case_path}: models.physics.turbulence.rans.enabled must be true or false.")
            try:
                rans_enabled = bool(rans_cfg.get('enabled', True)) and normalize_rans_model(rans_cfg.get('model', 'k_omega')) != 0
            except ValueError:
                rans_enabled = False
            if rans_enabled:
                warnings.append(
                    f"{case_path}: models.physics.turbulence.rans is accepted, but the k-omega runtime update is currently incomplete."
                )
        elif rans_cfg:
            warnings.append(
                f"{case_path}: models.physics.turbulence.rans is accepted, but the k-omega runtime update is currently incomplete."
            )
 
        if isinstance(wall_cfg, dict):
            if 'enabled' in wall_cfg and not isinstance(wall_cfg['enabled'], bool):
                errors.append(f"  {case_path}: models.physics.turbulence.wall_function.enabled must be true or false.")
            if 'roughness_height' in wall_cfg:
                try:
                    value = float(wall_cfg['roughness_height'])
                    if value < 0.0:
                        errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be nonnegative.")
                except (TypeError, ValueError):
                    errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be numeric.")
                # Only the log law has a roughness formulation. Werner-Wengle has no
                # roughness term and Cabot discards the argument, so accepting the key
                # for either would silently ignore a value the user set deliberately.
                try:
                    wall_model = normalize_wall_function_model(wall_cfg.get('model'))
                except ValueError:
                    wall_model = None
                if wall_model in (2, 3):
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.wall_function.roughness_height "
                        "applies only to model 'log_law'; 'werner' has no roughness formulation and "
                        "'cabot' ignores it. Remove the key or select 'log_law'.")
 
    # --- solver.yml: basic structure ---
    if not isinstance(solver_cfg, dict) or not solver_cfg:
        errors.append(f"  {solver_path}: solver config is empty or not a valid YAML mapping.")
    else:
        strategy_cfg = solver_cfg.get('strategy', {})
        if not isinstance(strategy_cfg, dict):
            errors.append(f"  {solver_path}: 'strategy' must be a mapping.")
        elif 'implicit' in strategy_cfg:
            errors.append(
                f"  {solver_path}: unsupported old key 'strategy.implicit' is not supported. "
                "Use 'strategy.momentum_solver' with named solver values."
            )
        if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
            try:
                normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
            except ValueError as e:
                errors.append(f"  {solver_path}: {e}")
 
        op_mode_cfg = solver_cfg.get('operation_mode', {})
        if op_mode_cfg is not None and not isinstance(op_mode_cfg, dict):
            errors.append(f"  {solver_path}: 'operation_mode' must be a mapping when provided.")
        elif isinstance(op_mode_cfg, dict):
            eulerian_source_mode = None
            normalized_analytical_type = None
            if 'eulerian_field_source' in op_mode_cfg:
                try:
                    eulerian_source_mode = normalize_eulerian_field_source(op_mode_cfg.get('eulerian_field_source'))
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
 
            analytical_type = op_mode_cfg.get('analytical_type')
            if analytical_type is not None:
                try:
                    normalized_analytical_type = normalize_analytical_type(analytical_type)
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
                else:
                    uniform_flow_cfg = op_mode_cfg.get('uniform_flow')
                    if uniform_flow_cfg is not None and not isinstance(uniform_flow_cfg, dict):
                        errors.append(f"  {solver_path}: 'operation_mode.uniform_flow' must be a mapping when provided.")
                    elif normalized_analytical_type == "UNIFORM_FLOW":
                        if not isinstance(uniform_flow_cfg, dict):
                            errors.append(
                                f"  {solver_path}: operation_mode.uniform_flow is required when "
                                "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                            )
                        else:
                            for coord in ("u", "v", "w"):
                                if coord not in uniform_flow_cfg:
                                    errors.append(
                                        f"  {solver_path}: operation_mode.uniform_flow.{coord} is required for UNIFORM_FLOW."
                                    )
                                else:
                                    try:
                                        float(uniform_flow_cfg[coord])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: operation_mode.uniform_flow.{coord} must be numeric."
                                        )
                    elif uniform_flow_cfg is not None:
                        errors.append(
                            f"  {solver_path}: operation_mode.uniform_flow is only valid when "
                            "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                        )
 
            if eulerian_source_mode == "analytical":
                effective_analytical_type = normalized_analytical_type or "TGV3D"
                if effective_analytical_type == "TGV3D":
                    if grid_mode != 'programmatic_c':
                        errors.append(
                            f"  {case_path}: analytical type '{effective_analytical_type}' requires grid.mode "
                            "'programmatic_c'. File-backed analytical ingestion is only supported for "
                            "ZERO_FLOW and UNIFORM_FLOW."
                        )
                    elif isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type resolves to '{effective_analytical_type}'."
                            )
                else:
                    if grid_mode not in (GRID_MODES[1], GRID_MODES[0]):
                        errors.append(
                            f"  {case_path}: grid.mode '{grid_mode}' is not supported when "
                            f"operation_mode.analytical_type is '{effective_analytical_type}'. "
                            "Use 'programmatic_c' or 'file'."
                        )
                    elif grid_mode == 'programmatic_c' and isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type is '{effective_analytical_type}' and "
                                "grid.mode is 'programmatic_c'."
                            )
 
        verification_cfg = solver_cfg.get('verification', {})
        if verification_cfg is not None and not isinstance(verification_cfg, dict):
            errors.append(f"  {solver_path}: 'verification' must be a mapping when provided.")
        elif isinstance(verification_cfg, dict) and verification_cfg:
            sources_cfg = verification_cfg.get('sources', {})
            if sources_cfg is not None and not isinstance(sources_cfg, dict):
                errors.append(f"  {solver_path}: 'verification.sources' must be a mapping when provided.")
            elif isinstance(sources_cfg, dict) and sources_cfg:
                diff_cfg = sources_cfg.get('diffusivity')
                scalar_cfg = sources_cfg.get('scalar')
 
                if diff_cfg is not None:
                    if not isinstance(diff_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.diffusivity' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = diff_cfg.get('mode')
                        profile = diff_cfg.get('profile')
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.mode must be 'analytical'."
                            )
                        if str(profile).strip().upper() != "LINEAR_X":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.profile must be 'LINEAR_X'."
                            )
                        for key in ("gamma0", "slope_x"):
                            if key not in diff_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.diffusivity.{key} is required."
                                )
                            else:
                                try:
                                    float(diff_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.diffusivity.{key} must be numeric."
                                    )
 
                if scalar_cfg is not None:
                    if not isinstance(scalar_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.scalar' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = scalar_cfg.get('mode')
                        profile = str(scalar_cfg.get('profile', '')).strip().upper()
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.mode must be 'analytical'."
                            )
                        if profile not in VERIFICATION_SCALAR_PROFILES:
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.profile must be one of CONSTANT, LINEAR_X, SIN_PRODUCT."
                            )
                        required_scalar_keys = {
                            "CONSTANT": ("value",),
                            "LINEAR_X": ("phi0", "slope_x"),
                            "SIN_PRODUCT": ("amplitude", "kx", "ky", "kz"),
                        }.get(profile, ())
                        for key in required_scalar_keys:
                            if key not in scalar_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.scalar.{key} is required for profile '{profile}'."
                                )
                            else:
                                try:
                                    float(scalar_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.scalar.{key} must be numeric."
                                    )
 
                unknown_source_keys = sorted(set(sources_cfg.keys()) - {"diffusivity", "scalar"})
                if unknown_source_keys:
                    errors.append(
                        f"  {solver_path}: unsupported verification.sources entries: {unknown_source_keys}. "
                        "Currently supported: 'diffusivity', 'scalar'."
                    )
            unknown_verification_keys = sorted(set(verification_cfg.keys()) - {"sources"})
            if unknown_verification_keys:
                errors.append(
                    f"  {solver_path}: unsupported verification keys: {unknown_verification_keys}. "
                    "Currently supported: 'sources'."
                )
 
        transport_cfg = solver_cfg.get('scalar_transport', {})
        if transport_cfg is not None and not isinstance(transport_cfg, dict):
            errors.append(f"  {solver_path}: 'scalar_transport' must be a mapping when provided.")
        elif isinstance(transport_cfg, dict):
            unknown_transport_keys = sorted(set(transport_cfg.keys()) - {"schmidt_number", "turbulent_schmidt_number"})
            if unknown_transport_keys:
                errors.append(
                    f"  {solver_path}: unsupported scalar_transport entries: {unknown_transport_keys}. "
                    "Currently supported: 'schmidt_number', 'turbulent_schmidt_number'."
                )
            for key in ("schmidt_number", "turbulent_schmidt_number"):
                if key in transport_cfg:
                    try:
                        value = float(transport_cfg[key])
                        if value <= 0.0:
                            errors.append(f"  {solver_path}: scalar_transport.{key} must be positive.")
                    except (TypeError, ValueError):
                        errors.append(f"  {solver_path}: scalar_transport.{key} must be numeric.")
 
        tolerances_cfg = solver_cfg.get('tolerances', {})
        if tolerances_cfg is not None and not isinstance(tolerances_cfg, dict):
            errors.append(f"  {solver_path}: 'tolerances' must be a mapping when provided.")
        elif isinstance(tolerances_cfg, dict):
            for key in ("absolute_tol", "relative_tol", "residual_absolute_tol", "residual_relative_tol"):
                if key in tolerances_cfg:
                    try:
                        float(tolerances_cfg[key])
                    except (TypeError, ValueError):
                        errors.append(f"  {solver_path}: tolerances.{key} must be numeric.")
 
        ms_cfg = solver_cfg.get('momentum_solver', {})
        if ms_cfg is not None and not isinstance(ms_cfg, dict):
            errors.append(f"  {solver_path}: 'momentum_solver' must be a mapping when provided.")
        elif isinstance(ms_cfg, dict):
            unsupported_flat_keys = {
                'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                'rk4_residual_noise_allowance_factor'
            }
            present_unsupported = sorted(unsupported_flat_keys.intersection(ms_cfg.keys()))
            if present_unsupported:
                errors.append(
                    f"  {solver_path}: unsupported flat keys in 'momentum_solver' are not supported: {present_unsupported}. "
                    "Use solver-specific sub-blocks (e.g., momentum_solver.dual_time_picard_jameson_rk)."
                )
 
            allowed_ms_keys = {'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
            unknown_ms_keys = sorted(set(ms_cfg.keys()) - allowed_ms_keys)
            if unknown_ms_keys:
                errors.append(
                    f"  {solver_path}: unsupported momentum_solver blocks/keys: {unknown_ms_keys}. "
                    "Currently supported: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
                )
            if 'dual_time_picard_jameson_rk' in ms_cfg and 'dual_time_picard_rk4' in ms_cfg:
                errors.append(
                    f"  {solver_path}: use only momentum_solver.dual_time_picard_jameson_rk; "
                    "do not also set its deprecated dual_time_picard_rk4 alias."
                )
 
            selected_solver = None
            if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
                try:
                    selected_solver = normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
                except ValueError:
                    pass
            if selected_solver is None:
                selected_solver = "DUALTIME_PICARD_JAMESON_RK"
 
            has_dualtime_block = (
                'dual_time_picard_jameson_rk' in ms_cfg or 'dual_time_picard_rk4' in ms_cfg
            )
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK" and has_dualtime_block:
                errors.append(
                    f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk is set but selected solver is "
                    f"{selected_solver}. Solver-specific blocks must match the selected solver."
                )
 
            newton_cfg = ms_cfg.get('newton_krylov')
            if newton_cfg is not None:
                if selected_solver != "newton_krylov":
                    errors.append(
                        f"  {solver_path}: momentum_solver.newton_krylov is set but selected solver is "
                        f"{selected_solver}. Solver-specific blocks must match the selected solver."
                    )
                try:
                    validate_newton_krylov_config(newton_cfg)
                except ValueError as exc:
                    errors.append(f"  {solver_path}: {exc}")
 
            dt_picard_cfg = ms_cfg.get('dual_time_picard_jameson_rk', ms_cfg.get('dual_time_picard_rk4'))
            if dt_picard_cfg is not None:
                if not isinstance(dt_picard_cfg, dict):
                    errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
                else:
                    allowed_dt_keys = {
                        'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                        'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                        'rk4_residual_noise_allowance_factor', 'ratio_ema_alpha'
                    }
                    unknown_dt_keys = sorted(set(dt_picard_cfg.keys()) - allowed_dt_keys)
                    if unknown_dt_keys:
                        errors.append(
                            f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk: {unknown_dt_keys}."
                        )
                    if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                            'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                        errors.append(
                            f"  {solver_path}: use only jameson_residual_noise_allowance_factor; "
                            "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                        )
                    if 'pseudo_cfl' in dt_picard_cfg:
                        pcfl_cfg = dt_picard_cfg['pseudo_cfl']
                        if not isinstance(pcfl_cfg, dict):
                            errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl must be a mapping.")
                        else:
                            allowed_pcfl_keys = {'initial', 'minimum', 'maximum', 'growth_factor', 'reduction_factor'}
                            unknown_pcfl_keys = sorted(set(pcfl_cfg.keys()) - allowed_pcfl_keys)
                            if unknown_pcfl_keys:
                                errors.append(
                                    f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl: {unknown_pcfl_keys}."
                                )
                            numeric_pcfl = {}
                            for key in allowed_pcfl_keys:
                                if key in pcfl_cfg:
                                    try:
                                        numeric_pcfl[key] = float(pcfl_cfg[key])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl.{key} must be numeric."
                                        )
                            if numeric_pcfl.get('minimum', 1.0) <= 0.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.minimum must be positive.")
                            if numeric_pcfl.get('growth_factor', 1.0) < 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.growth_factor must be at least 1.")
                            reduction = numeric_pcfl.get('reduction_factor', 1.0)
                            if reduction <= 0.0 or reduction >= 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.reduction_factor must be in (0, 1).")
                            if all(key in numeric_pcfl for key in ('minimum', 'initial', 'maximum')):
                                if not numeric_pcfl['minimum'] <= numeric_pcfl['initial'] <= numeric_pcfl['maximum']:
                                    errors.append(f"  {solver_path}: pseudo_cfl requires minimum <= initial <= maximum.")
                    noise_key = (
                        'jameson_residual_noise_allowance_factor'
                        if 'jameson_residual_noise_allowance_factor' in dt_picard_cfg
                        else 'rk4_residual_noise_allowance_factor'
                    )
                    if noise_key in dt_picard_cfg:
                        try:
                            if float(dt_picard_cfg[noise_key]) < 1.0:
                                errors.append(f"  {solver_path}: {noise_key} must be at least 1.")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: {noise_key} must be numeric.")
                    if 'ratio_ema_alpha' in dt_picard_cfg:
                        try:
                            alpha_val = float(dt_picard_cfg['ratio_ema_alpha'])
                            if not 0.0 <= alpha_val <= 1.0:
                                errors.append(f"  {solver_path}: ratio_ema_alpha must be in [0, 1].")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: ratio_ema_alpha must be numeric.")
 
    # --- solver.yml: interpolation section ---
    interp_cfg = solver_cfg.get('interpolation', {}) if isinstance(solver_cfg, dict) else {}
    if interp_cfg is not None and not isinstance(interp_cfg, dict):
        errors.append(f"  {solver_path}: 'interpolation' must be a mapping when provided.")
    elif isinstance(interp_cfg, dict) and 'method' in interp_cfg:
        try:
            normalize_interpolation_method(interp_cfg['method'])
        except ValueError as e:
            errors.append(f"  {solver_path}: {e}")
 
    # --- monitor.yml: basic structure ---
    if not isinstance(monitor_cfg, dict) or not monitor_cfg:
        errors.append(f"  {monitor_path}: monitor config is empty or not a valid YAML mapping.")
    else:
        io_cfg = monitor_cfg.get('io', {})
        freq = io_cfg.get('data_output_frequency')
        if freq is not None and (not isinstance(freq, int) or freq <= 0):
            errors.append(f"  {monitor_path}: 'io.data_output_frequency' must be a positive integer (got {freq}).")
        particle_console_freq = io_cfg.get('particle_console_output_frequency')
        if particle_console_freq is not None and (not isinstance(particle_console_freq, int) or particle_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.particle_console_output_frequency' must be a non-negative integer "
                f"(got {particle_console_freq})."
            )
        containment_errors, containment_warnings = validate_run_directory_containment(
            monitor_cfg, monitor_path
        )
        errors.extend(containment_errors)
        warnings.extend(containment_warnings)
        errors.extend(validate_reserved_directory_flags(
            monitor_cfg, monitor_path, "monitor passthrough"))
        try:
            resolve_profiling_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_diagnostics_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_solver_monitoring_flags(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            normalize_solution_monitoring_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        statistics_console_freq = io_cfg.get('statistics_console_output_frequency')
        if statistics_console_freq is not None and (
                not isinstance(statistics_console_freq, int)
                or isinstance(statistics_console_freq, bool)
                or statistics_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.statistics_console_output_frequency' must be a non-negative "
                f"integer (got {statistics_console_freq})."
            )
        try:
            normalize_field_statistics_config(monitor_cfg, case_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
 
    if not errors:
        if needs_restart_source(case_cfg, solver_cfg):
            warnings.append(
                f"{case_path}: This configuration requires restart data (start_step > 0, "
                "eulerian_field_source='load', or particle restart_mode='load'). "
                "Use --restart-from or --continue when running."
            )
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARN] {warning}", file=sys.stderr)
 
 
def check_post_checkpoint_cadence_alignment(post_cfg: dict, monitor_cfg: dict, post_path: str,
                                            monitor_path: str = "monitor.yml") -> "tuple[list, list]":
    """!
    @brief Report post step selections that cannot land on a committed checkpoint.
 
    @details The post-processor reads committed bundles, and the solver commits one
             every `io.data_output_frequency` completed steps. A `step_interval` that
             is not a multiple of that cadence therefore asks for steps that were
             never written: the source-frontier scan stops at the first missing one
             and processes far less than the recipe requested. That is only
             discovered after a solve has already run, so it is caught here instead.
 
             The solver also commits the initial and final states off cadence, which
             is why a misaligned `start_step` is a warning rather than an error: it
             may legitimately be the run's own starting step. `step_interval` has no
             such exemption, because a stride off the cadence cannot land on two
             consecutive checkpoints whatever the run's bounds are.
 
    @param[in] post_cfg     Parsed post-processing configuration.
    @param[in] monitor_cfg  Parsed monitor configuration governing the source run.
    @param[in] post_path    Path to the post file, for error messages.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return `(errors, warnings)`, each a list of message strings. Both are empty when
            the comparison cannot be made, because the inputs that would make it
            meaningful are validated and reported elsewhere.
    """
    errors = []
    warnings = []
    if not isinstance(post_cfg, dict) or not isinstance(monitor_cfg, dict):
        return errors, warnings
 
    io_cfg = monitor_cfg.get("io") or {}
    if not isinstance(io_cfg, dict):
        return errors, warnings
    try:
        cadence = int(io_cfg["data_output_frequency"])
    except (KeyError, TypeError, ValueError):
        # A missing or malformed cadence is reported by the monitor's own checks.
        return errors, warnings
    # A disabled cadence commits only the initial and final states, so there is no
    # stride to align to.
    if cadence <= 0:
        return errors, warnings
 
    try:
        step_interval = int(get_post_run_control_value(post_cfg, "step_interval", 1))
        start_step = int(get_post_run_control_value(post_cfg, "start_step", 0))
    except (TypeError, ValueError):
        # Reported by the run_control checks, which run against the same values.
        return errors, warnings
 
    if step_interval > 0 and step_interval % cadence != 0:
        suggestion = max(cadence, (step_interval // cadence) * cadence)
        errors.append(
            f"  {post_path}: 'run_control.step_interval' is {step_interval}, which is not a "
            f"multiple of 'io.data_output_frequency' ({cadence}) in {monitor_path}. The solver "
            f"only commits a checkpoint every {cadence} steps, so most requested steps were "
            f"never written and post-processing would stop at the first missing one. Use "
            f"{suggestion}, or another multiple of {cadence}, or lower the monitor cadence."
        )
 
    if start_step > 0 and start_step % cadence != 0:
        warnings.append(
            f"{post_path}: 'run_control.start_step' is {start_step}, which is not a multiple of "
            f"'io.data_output_frequency' ({cadence}) in {monitor_path}. That step only exists if "
            f"it is the run's own starting step, which is committed off cadence."
        )
 
    return errors, warnings
 
 
def validate_post_config(post_cfg: dict, post_path: str, monitor_cfg: dict = None, case_cfg: dict = None):
    """!
    @brief Validates the post-processing config before running the post-processor.
    @param[in] post_cfg  Parsed post-processing YAML dictionary.
    @param[in] post_path Path to post file (for error messages).
    @param[in] monitor_cfg Parsed monitor configuration, when available. Two checks
                           span both files: field statistics, where post.yml names
                           the windows and monitor.yml decides what each accumulates,
                           and step cadence, where monitor.yml decides which steps
                           exist to be read. Both run only when the monitor is known.
    @param[in] case_cfg Parsed case configuration, when available. Spectra
                        preconditions need the boundary conditions and block count, so
                        they are checked only when the case is known; validating a
                        recipe on its own still checks it on its own terms.
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
 
    _validate_yaml_schema_keys(post_cfg, _POST_SCHEMA, post_path, errors)
 
    try:
        recipe = normalize_post_field_statistics_config(post_cfg)
    except ValueError as e:
        recipe = None
        errors.append(f"  {post_path}: {e}")
 
    try:
        spectra_recipe = normalize_post_spectra_config(post_cfg)
    except ValueError as e:
        spectra_recipe = None
        errors.append(f"  {post_path}: {e}")
    if spectra_recipe and spectra_recipe["tasks"] and case_cfg is not None:
        errors.extend(validate_post_spectra_preconditions(spectra_recipe, case_cfg, post_path))
    if recipe and recipe["windows"] and monitor_cfg is not None:
        try:
            configured = normalize_field_statistics_config(monitor_cfg)
        except ValueError:
            # The monitor file reports its own errors; do not repeat them here.
            configured = None
        if configured is not None:
            if not configured["enabled"]:
                errors.append(
                    f"  {post_path}: field statistics are requested, but "
                    "'field_statistics.enabled' is not set in the monitor configuration, so no "
                    "window is accumulated."
                )
            else:
                by_name = {window["name"]: window for window in configured["windows"]}
                for name in recipe["windows"]:
                    if name not in by_name:
                        errors.append(
                            f"  {post_path}: field-statistics window '{name}' is not defined in "
                            f"the monitor configuration. Defined windows: {sorted(by_name)}."
                        )
                    elif _post_window_derived_field_count(by_name[name], recipe["outputs"]) == 0:
                        errors.append(
                            f"  {post_path}: outputs {recipe['outputs']} produce no field for "
                            f"window '{name}'; it accumulates none of the state they need. Add "
                            "'second' to a field's moments for stresses, RMS, or turbulent "
                            "kinetic energy, or a covariance for a flux."
                        )
 
    if not isinstance(post_cfg, dict) or not post_cfg:
        errors.append(f"  {post_path}: post-processing config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    # --- run_control ---
    if 'run_control' not in post_cfg:
        errors.append(f"  {post_path}: missing required section 'run_control'.")
    else:
        rc = post_cfg.get('run_control', {})
        if not isinstance(rc, dict):
            errors.append(f"  {post_path}: 'run_control' must be a mapping.")
        else:
            for canonical_key, aliases in POST_RUN_CONTROL_ALIASES.items():
                if not any(alias in rc for alias in aliases):
                    alias_list = "', '".join(aliases)
                    errors.append(
                        f"  {post_path}: missing required key 'run_control.{canonical_key}' "
                        f"(accepted aliases: '{alias_list}')."
                    )
                    continue
                raw_value = _mapping_value_with_aliases(rc, *aliases)
                try:
                    int(raw_value)
                except (TypeError, ValueError):
                    alias_name = next((alias for alias in aliases if alias in rc), canonical_key)
                    errors.append(
                        f"  {post_path}: 'run_control.{alias_name}' must be an integer-compatible value."
                    )
 
    # --- io section ---
    io_cfg = post_cfg.get('io', {})
    source_cfg = post_cfg.get('source_data')
    if source_cfg is not None and not isinstance(source_cfg, dict):
        errors.append(f"  {post_path}: 'source_data' must be a mapping when provided.")
    global_ops = post_cfg.get('global_operations')
    if global_ops is not None:
        if not isinstance(global_ops, dict):
            errors.append(f"  {post_path}: 'global_operations' must be a mapping when provided.")
        elif 'dimensionalize' in global_ops and not isinstance(global_ops.get('dimensionalize'), bool):
            errors.append(f"  {post_path}: 'global_operations.dimensionalize' must be a boolean.")
    if not io_cfg:
        errors.append(f"  {post_path}: missing required section 'io'.")
    elif not isinstance(io_cfg, dict):
        errors.append(f"  {post_path}: 'io' must be a mapping.")
    else:
        for k in ['output_filename_prefix']:
            if k not in io_cfg:
                errors.append(f"  {post_path}: missing required key 'io.{k}'.")
        for key_name in ('output_directory', 'output_filename_prefix', 'particle_filename_prefix'):
            if key_name in io_cfg and not isinstance(io_cfg.get(key_name), str):
                errors.append(f"  {post_path}: 'io.{key_name}' must be a string when provided.")
        if 'output_particles' in io_cfg and not isinstance(io_cfg.get('output_particles'), bool):
            errors.append(f"  {post_path}: 'io.output_particles' must be a boolean when provided.")
        particle_subsampling_frequency = io_cfg.get('particle_subsampling_frequency')
        if particle_subsampling_frequency is not None:
            if not isinstance(particle_subsampling_frequency, int) or particle_subsampling_frequency <= 0:
                errors.append(
                    f"  {post_path}: 'io.particle_subsampling_frequency' must be a positive integer when provided."
                )
        input_extensions = io_cfg.get('input_extensions')
        source_input_extensions = get_post_source_data(post_cfg).get('input_extensions')
        if input_extensions is not None:
            if not isinstance(input_extensions, dict):
                errors.append(f"  {post_path}: 'io.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(f"  {post_path}: 'io.input_extensions.{ext_key}' must be a string extension.")
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'io.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
        if source_input_extensions is not None:
            if not isinstance(source_input_extensions, dict):
                errors.append(f"  {post_path}: 'source_data.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = source_input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be a string extension."
                        )
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
 
        for list_key in ('eulerian_fields', 'particle_fields'):
            list_val = io_cfg.get(list_key)
            if list_val is not None and not isinstance(list_val, list):
                errors.append(f"  {post_path}: 'io.{list_key}' must be a list when provided.")
 
    # --- Check eulerian_pipeline entries have 'task' key ---
    eulerian_pipeline = post_cfg.get('eulerian_pipeline', [])
    if eulerian_pipeline is not None and not isinstance(eulerian_pipeline, list):
        errors.append(f"  {post_path}: 'eulerian_pipeline' must be a list when provided.")
        eulerian_pipeline = []
    for i, entry in enumerate(eulerian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'eulerian_pipeline[{i}]' is missing the 'task' key. "
                          "Check YAML indentation (each entry needs '- task: ...' with proper spacing).")
            continue
        task_name = entry.get('task')
        if task_name == 'q_criterion':
            continue
        if task_name == 'nodal_average':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].output_field' must be a non-empty string.")
            if isinstance(in_field, str) and isinstance(out_field, str) and in_field == out_field:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}]' nodal_average input and output fields must differ."
                )
            continue
        if task_name == 'normalize_field':
            field = entry.get('field', 'P')
            if not isinstance(field, str) or not field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].field' must be a non-empty string.")
            elif field != 'P':
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].field' currently only supports 'P' "
                    f"(got '{field}')."
                )
            reference_point = entry.get('reference_point', [1, 1, 1])
            if not isinstance(reference_point, (list, tuple)) or len(reference_point) != 3:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].reference_point' must be a 3-item list."
                )
            else:
                for rp_idx, coord in enumerate(reference_point):
                    try:
                        int(coord)
                    except (TypeError, ValueError):
                        errors.append(
                            f"  {post_path}: 'eulerian_pipeline[{i}].reference_point[{rp_idx}]' "
                            "must be integer-compatible."
                        )
            continue
        errors.append(
            f"  {post_path}: unsupported eulerian task '{task_name}' at eulerian_pipeline[{i}]. "
            f"Available tasks: {list(POST_EULERIAN_PIPELINE_TASKS)}."
        )
 
    # --- Check lagrangian_pipeline entries have 'task' key ---
    lagrangian_pipeline = post_cfg.get('lagrangian_pipeline', [])
    if lagrangian_pipeline is not None and not isinstance(lagrangian_pipeline, list):
        errors.append(f"  {post_path}: 'lagrangian_pipeline' must be a list when provided.")
        lagrangian_pipeline = []
    for i, entry in enumerate(lagrangian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}]' is missing the 'task' key.")
            continue
        task_name = entry.get('task')
        if task_name == 'specific_ke':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].output_field' must be a non-empty string.")
            continue
        errors.append(
            f"  {post_path}: unsupported lagrangian task '{task_name}' at lagrangian_pipeline[{i}]."
        )
 
    # --- Check statistics pipeline entries ---
    stats_cfg = post_cfg.get('statistics_pipeline')
    stats_entries = []
    if stats_cfg is not None:
        if isinstance(stats_cfg, list):
            stats_entries = stats_cfg
        elif isinstance(stats_cfg, dict):
            stats_entries = stats_cfg.get('tasks', [])
            if not isinstance(stats_entries, list):
                errors.append(f"  {post_path}: 'statistics_pipeline.tasks' must be a list.")
            stats_output_prefix = stats_cfg.get('output_prefix')
            if stats_output_prefix is not None and not isinstance(stats_output_prefix, str):
                errors.append(f"  {post_path}: 'statistics_pipeline.output_prefix' must be a string.")
        else:
            errors.append(
                f"  {post_path}: 'statistics_pipeline' must be either a list of tasks or a mapping with a 'tasks' list."
            )
        for i, entry in enumerate(stats_entries):
            if isinstance(entry, str):
                task_name = entry
            elif isinstance(entry, dict) and 'task' in entry:
                task_name = entry.get('task')
            else:
                errors.append(
                    f"  {post_path}: statistics task entry {i} must be either a string or a mapping with key 'task'."
                )
                continue
            try:
                normalize_statistics_task(task_name)
            except ValueError as e:
                errors.append(f"  {post_path}: {e}")
 
    legacy_stats_output_prefix = post_cfg.get('statistics_output_prefix')
    if legacy_stats_output_prefix is not None and not isinstance(legacy_stats_output_prefix, str):
        errors.append(f"  {post_path}: 'statistics_output_prefix' must be a string when provided.")
 
    # Runs last so it reports against values the run_control checks above have
    # already established are integers.
    cadence_errors, cadence_warnings = check_post_checkpoint_cadence_alignment(
        post_cfg, monitor_cfg, post_path)
    errors.extend(cadence_errors)
    warnings.extend(cadence_warnings)
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARN] {warning}", file=sys.stderr)
 
def validate_cluster_config(cluster_cfg: dict, cluster_path: str):
    """!
    @brief Validate Slurm scheduler configuration from cluster.yml.
    @param[in] cluster_cfg Argument passed to `validate_cluster_config()`.
    @param[in] cluster_path Argument passed to `validate_cluster_config()`.
    """
    errors = []
    warnings = []
    _validate_yaml_schema_keys(cluster_cfg, _CLUSTER_SCHEMA, cluster_path, errors)
    if not isinstance(cluster_cfg, dict) or not cluster_cfg:
        errors.append(f"  {cluster_path}: cluster config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    scheduler = cluster_cfg.get("scheduler", {})
    if not isinstance(scheduler, dict):
        errors.append(f"  {cluster_path}: 'scheduler' must be a mapping.")
    else:
        scheduler_type = scheduler.get("type", "slurm")
        if str(scheduler_type).lower() != "slurm":
            errors.append(f"  {cluster_path}: scheduler.type must be 'slurm' in v1 (got '{scheduler_type}').")
 
    resources = cluster_cfg.get("resources", {})
    if not isinstance(resources, dict):
        errors.append(f"  {cluster_path}: 'resources' must be a mapping.")
    else:
        for req in ("account", "nodes", "ntasks_per_node", "mem", "time"):
            if req not in resources:
                errors.append(f"  {cluster_path}: missing required key 'resources.{req}'.")
        for int_key in ("nodes", "ntasks_per_node"):
            if int_key in resources:
                val = resources.get(int_key)
                if not isinstance(val, int) or val <= 0:
                    errors.append(f"  {cluster_path}: resources.{int_key} must be a positive integer (got {val}).")
        for str_key in ("account", "mem", "time", "partition"):
            if str_key in resources and resources.get(str_key) is not None:
                if not isinstance(resources.get(str_key), str):
                    errors.append(f"  {cluster_path}: resources.{str_key} must be a string when provided.")
        if isinstance(resources.get("time"), str):
            try:
                parse_slurm_time_limit_to_seconds(resources["time"])
            except ValueError as exc:
                errors.append(
                    f"  {cluster_path}: resources.time must be a supported finite Slurm time string ({exc})."
                )
        account = resources.get("account")
        if account == CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT:
            warnings.append(
                f"{cluster_path}: resources.account still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT}'. Edit the cluster profile before submission."
            )
 
    notifications = cluster_cfg.get("notifications", {})
    if notifications is not None and not isinstance(notifications, dict):
        errors.append(f"  {cluster_path}: 'notifications' must be a mapping when provided.")
    elif isinstance(notifications, dict):
        mail_user = notifications.get("mail_user")
        if mail_user is not None and not is_valid_email(mail_user):
            errors.append(f"  {cluster_path}: notifications.mail_user is not a valid email '{mail_user}'.")
        if mail_user == CLUSTER_TEMPLATE_PLACEHOLDER_MAIL:
            warnings.append(
                f"{cluster_path}: notifications.mail_user still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_MAIL}'. Edit the cluster profile before submission."
            )
        mail_type = notifications.get("mail_type")
        if mail_type is not None and not isinstance(mail_type, str):
            errors.append(f"  {cluster_path}: notifications.mail_type must be a string when provided.")
 
    execution = cluster_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {cluster_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        module_setup = execution.get("module_setup", [])
        if module_setup is not None and not isinstance(module_setup, list):
            errors.append(f"  {cluster_path}: execution.module_setup must be a list of shell lines.")
        elif isinstance(module_setup, list):
            for i, line in enumerate(module_setup):
                if not isinstance(line, str):
                    errors.append(f"  {cluster_path}: execution.module_setup[{i}] must be a string.")
 
        launcher = execution.get("launcher")
        if launcher is not None and not isinstance(launcher, str):
            errors.append(f"  {cluster_path}: execution.launcher must be a string when provided.")
        launcher_args = execution.get("launcher_args")
        if launcher_args is not None and not isinstance(launcher_args, list):
            errors.append(f"  {cluster_path}: execution.launcher_args must be a list of CLI tokens.")
        elif isinstance(launcher_args, list):
            for i, token in enumerate(launcher_args):
                if not isinstance(token, (str, int, float)):
                    errors.append(f"  {cluster_path}: execution.launcher_args[{i}] must be a scalar CLI token.")
                elif _launcher_arg_contains_whitespace(token):
                    errors.append(
                        f"  {cluster_path}: execution.launcher_args[{i}] must be a single CLI token; "
                        "split whitespace-separated arguments into separate list items."
                    )
        if (launcher is None or isinstance(launcher, str)) and (launcher_args is None or isinstance(launcher_args, list)):
            try:
                normalize_cluster_launcher(execution)
            except ValueError as exc:
                errors.append(f"  {cluster_path}: {exc}.")
 
        extra_sbatch = execution.get("extra_sbatch")
        if extra_sbatch is not None and not isinstance(extra_sbatch, (dict, list)):
            errors.append(f"  {cluster_path}: execution.extra_sbatch must be a mapping or list when provided.")
 
        walltime_guard = execution.get("walltime_guard")
        if walltime_guard is not None and not isinstance(walltime_guard, dict):
            errors.append(f"  {cluster_path}: execution.walltime_guard must be a mapping when provided.")
        elif isinstance(walltime_guard, dict):
            enabled = walltime_guard.get("enabled")
            if enabled is not None and not isinstance(enabled, bool):
                errors.append(f"  {cluster_path}: execution.walltime_guard.enabled must be boolean when provided.")
 
            warmup_steps = walltime_guard.get("warmup_steps")
            if warmup_steps is not None and (not isinstance(warmup_steps, int) or isinstance(warmup_steps, bool) or warmup_steps <= 0):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.warmup_steps must be a positive integer when provided."
                )
 
            multiplier = walltime_guard.get("multiplier")
            if multiplier is not None:
                if isinstance(multiplier, bool) or not isinstance(multiplier, (int, float)) or multiplier <= 0.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be a positive number when provided."
                    )
                elif float(multiplier) > 5.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be <= 5.0 (got {multiplier})."
                    )
 
            min_seconds = walltime_guard.get("min_seconds")
            if min_seconds is not None and (
                isinstance(min_seconds, bool) or not isinstance(min_seconds, (int, float)) or float(min_seconds) <= 0.0
            ):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.min_seconds must be a positive number when provided."
                )
 
            estimator_alpha = walltime_guard.get("estimator_alpha")
            if estimator_alpha is not None:
                if isinstance(estimator_alpha, bool) or not isinstance(estimator_alpha, (int, float)):
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be a number in (0, 1] when provided."
                    )
                elif float(estimator_alpha) <= 0.0 or float(estimator_alpha) > 1.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be in (0, 1] (got {estimator_alpha})."
                    )
 
    if warnings:
        for warning in warnings:
            print(f"[WARN] {warning}", file=sys.stderr)
 
    if errors:
        _print_validation_errors(errors)
 
def validate_study_config(study_cfg: dict, study_path: str, skip_base_file_check: bool = False):
    """!
    @brief Validate sweep/study specification from study.yml.
    @param[in] study_cfg Argument passed to `validate_study_config()`.
    @param[in] study_path Argument passed to `validate_study_config()`.
    @param[in] skip_base_file_check When True, skip file-existence check for base_configs paths.
    """
    errors = []
    _validate_yaml_schema_keys(study_cfg, _STUDY_SCHEMA, study_path, errors)
    if not isinstance(study_cfg, dict) or not study_cfg:
        errors.append(f"  {study_path}: study config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    base_cfgs = study_cfg.get("base_configs")
    if not isinstance(base_cfgs, dict):
        errors.append(f"  {study_path}: missing required mapping 'base_configs'.")
    else:
        for req in ("case", "solver", "monitor", "post"):
            path_val = base_cfgs.get(req)
            if not path_val or not isinstance(path_val, str):
                errors.append(f"  {study_path}: base_configs.{req} must be a path string.")
            elif not skip_base_file_check:
                resolved = resolve_path(study_path, path_val)
                if not os.path.isfile(resolved):
                    errors.append(f"  {study_path}: base_configs.{req} does not exist: {resolved}")
 
    study_type = study_cfg.get("study_type")
    allowed_types = set(STUDY_TYPES)
    if study_type not in allowed_types:
        errors.append(
            f"  {study_path}: study_type must be one of {sorted(allowed_types)} (got '{study_type}')."
        )
 
    parameters = study_cfg.get("parameters")
    parameter_sets = study_cfg.get("parameter_sets")
    allowed_roots = {"case", "solver", "monitor", "post"}
    if bool(parameters) == bool(parameter_sets):
        errors.append(f"  {study_path}: provide exactly one of 'parameters' or 'parameter_sets'.")
    elif parameter_sets:
        if not isinstance(parameter_sets, list) or not parameter_sets:
            errors.append(f"  {study_path}: 'parameter_sets' must be a non-empty list of key->value mappings.")
        else:
            for set_index, param_set in enumerate(parameter_sets):
                if not isinstance(param_set, dict) or not param_set:
                    errors.append(
                        f"  {study_path}: parameter_sets[{set_index}] must be a non-empty mapping of key->value overrides."
                    )
                    continue
                for key, value in param_set.items():
                    if not isinstance(key, str) or "." not in key:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must use '<target>.<yaml.path>' format."
                        )
                        continue
                    root = key.split(".", 1)[0]
                    if root not in allowed_roots:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must start with one of {sorted(allowed_roots)}."
                        )
                    if isinstance(value, (dict, list)):
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] value for '{key}' must be a scalar, not {type(value).__name__}."
                        )
    else:
        if not isinstance(parameters, dict) or not parameters:
            errors.append(f"  {study_path}: 'parameters' must be a non-empty mapping of key->list.")
        else:
            for key, values in parameters.items():
                if not isinstance(key, str) or "." not in key:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must use '<target>.<yaml.path>' format."
                    )
                    continue
                root = key.split(".", 1)[0]
                if root not in allowed_roots:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must start with one of {sorted(allowed_roots)}."
                    )
                if not isinstance(values, list) or len(values) == 0:
                    errors.append(f"  {study_path}: parameters.{key} must be a non-empty list.")
 
    metrics = study_cfg.get("metrics", [])
    if metrics is not None and not isinstance(metrics, list):
        errors.append(f"  {study_path}: 'metrics' must be a list when provided.")
    elif isinstance(metrics, list):
        for i, metric in enumerate(metrics):
            if isinstance(metric, str):
                continue
            if not isinstance(metric, dict):
                errors.append(
                    f"  {study_path}: metrics[{i}] must be a string or mapping."
                )
                continue
            if "name" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'name'.")
            if "source" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'source'.")
            for label_key in ("plot_label", "label", "units"):
                label_value = metric.get(label_key)
                if label_value is not None and (not isinstance(label_value, str) or not label_value.strip()):
                    errors.append(
                        f"  {study_path}: metrics[{i}].{label_key} must be a non-empty string when provided."
                    )
 
    plotting = study_cfg.get("plotting", {})
    if plotting is not None and not isinstance(plotting, dict):
        errors.append(f"  {study_path}: 'plotting' must be a mapping when provided.")
    elif isinstance(plotting, dict):
        enabled = plotting.get("enabled")
        if enabled is not None and not isinstance(enabled, bool):
            errors.append(f"  {study_path}: plotting.enabled must be boolean when provided.")
        output_format = plotting.get("output_format")
        if output_format is not None and output_format not in STUDY_PLOT_FORMATS:
            errors.append(f"  {study_path}: plotting.output_format must be one of ['png','pdf','svg'].")
 
    execution = study_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {study_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        max_conc = execution.get("max_concurrent_array_tasks")
        if max_conc is not None and (not isinstance(max_conc, int) or max_conc <= 0):
            errors.append(
                f"  {study_path}: execution.max_concurrent_array_tasks must be a positive integer when provided."
            )
 
    if errors:
        _print_validation_errors(errors)
 
def _deep_set(container: dict, dotted_path: str, value):
    """!
    @brief Set nested dictionary value, creating intermediate maps when needed.
    @param[in] container Argument passed to `_deep_set()`.
    @param[in] dotted_path Argument passed to `_deep_set()`.
    @param[in] value Argument passed to `_deep_set()`.
    """
    keys = dotted_path.split(".")
    current = container
    for key in keys[:-1]:
        if key not in current or not isinstance(current[key], dict):
            current[key] = {}
        current = current[key]
    current[keys[-1]] = value
 
def expand_parameter_matrix(parameters: dict) -> list:
    """!
    @brief Expand study parameter lists into cartesian-product combinations.
    @param[in] parameters Argument passed to `expand_parameter_matrix()`.
    @return Value returned by `expand_parameter_matrix()`.
    """
    param_keys = list(parameters.keys())
    all_values = [parameters[k] for k in param_keys]
    combos = []
    for combo in itertools.product(*all_values):
        combos.append(dict(zip(param_keys, combo)))
    return combos
 
 
def expand_study_parameter_combinations(study_cfg: dict) -> list:
    """!
    @brief Expand either cartesian-study parameters or explicit parameter sets.
    @param[in] study_cfg Argument passed to `expand_study_parameter_combinations()`.
    @return Value returned by `expand_study_parameter_combinations()`.
    """
    parameter_sets = study_cfg.get("parameter_sets")
    if parameter_sets:
        return [dict(param_set) for param_set in parameter_sets]
    return expand_parameter_matrix(study_cfg.get("parameters") or {})
 
 
def flatten_study_parameters(parameters: dict) -> dict:
    """!
    @brief Flatten grouped study overrides into scalar dotted-path columns.
 
    @details A grouped override such as `case.run_control: {dt_physical: ...}`
             materializes correctly in case YAML but is not a useful CSV cell or
             plot coordinate. Flattening preserves the actual varied variables.
 
    @param[in] parameters One expanded study parameter combination.
    @return Flat dotted-path-to-scalar mapping.
    """
    flattened = {}
 
    def visit(prefix, value):
        """!
        @brief Recursively flatten one grouped override value.
        @param[in] prefix Current dotted parameter path.
        @param[in] value Scalar or nested mapping at the current path.
        """
        if isinstance(value, dict):
            for child, child_value in value.items():
                visit(f"{prefix}.{child}" if prefix else str(child), child_value)
        else:
            flattened[prefix] = value
 
    for key, value in (parameters or {}).items():
        visit(str(key), value)
    return flattened
 
 
def get_study_parameter_keys(study_cfg: dict) -> list:
    """!
    @brief Collect ordered parameter keys from either cross-product parameter expansions or explicit parameter sets.
    @param[in] study_cfg Argument passed to `get_study_parameter_keys()`.
    @return Value returned by `get_study_parameter_keys()`.
    """
    parameters = study_cfg.get("parameters")
    if isinstance(parameters, dict) and parameters:
        keys = []
        for key, candidates in parameters.items():
            candidate_dicts = [value for value in candidates if isinstance(value, dict)] if isinstance(candidates, list) else []
            expanded = []
            for value in candidate_dicts:
                for flat_key in flatten_study_parameters({key: value}):
                    if flat_key not in expanded:
                        expanded.append(flat_key)
            for flat_key in expanded or [key]:
                if flat_key not in keys:
                    keys.append(flat_key)
        return keys
 
    keys = []
    parameter_sets = study_cfg.get("parameter_sets") or []
    for param_set in parameter_sets:
        if not isinstance(param_set, dict):
            continue
        for key in flatten_study_parameters(param_set):
            if key not in keys:
                keys.append(key)
    return keys
 
 
def get_cluster_total_tasks(cluster_cfg: dict) -> int:
    """!
    @brief Return cluster total tasks.
    @param[in] cluster_cfg Argument passed to `get_cluster_total_tasks()`.
    @return Value returned by `get_cluster_total_tasks()`.
    """
    resources = cluster_cfg.get("resources", {})
    return int(resources.get("nodes", 1)) * int(resources.get("ntasks_per_node", 1))
 
def normalize_extension(ext: str) -> str:
    """!
    @brief Canonicalize a user-supplied filename extension by trimming whitespace and leading dots.
    @param[in] ext Argument passed to `normalize_extension()`.
    @return Value returned by `normalize_extension()`.
    """
    if ext is None:
        return None
    return str(ext).strip().lstrip(".")
 
def resolve_conductor_entry_point() -> list:
    """!
    @brief Resolve how to invoke this conductor again from a batch script.
 
    @details Prefers the `bin/picurv` wrapper, which selects the managed Python
             environment a cluster node needs, and falls back to the running
             interpreter with the package entry point when that wrapper is absent.
 
    @return Argv prefix that re-invokes the conductor.
    """
    wrapper = os.path.join(PACKAGE_PROJECT_ROOT, "bin", "picurv")
    if os.path.isfile(wrapper) and os.access(wrapper, os.X_OK):
        return [wrapper]
    return [sys.executable, os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "picurv")]
 
 
def build_spectra_follow_command(run_dir: str, post_path: str, post_cfg: dict) -> list:
    """!
    @brief Build the batch-script step that measures spectra after the field stage.
 
    @details Spectra are a serial pass over committed checkpoints, so the command is
             returned bare rather than wrapped in the MPI launcher: run under `srun`
             with the post stage's task count it would become one identical copy per
             task, each writing the same files.
 
    @param[in] run_dir Run directory the batch job operates on.
    @param[in] post_path Post recipe path, reachable from the compute node.
    @param[in] post_cfg Effective post configuration.
    @return Argv list, or an empty list when the recipe requests no spectra.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # Validation reports recipe errors; do not raise a second time here.
        return []
    if not spectra["tasks"]:
        return []
    return resolve_conductor_entry_point() + [
        "run", "--post-process", "--only", "spectra",
        "--run-dir", os.path.abspath(run_dir),
        "--post", os.path.abspath(post_path),
    ]
 
 
def render_slurm_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    command: list,
    workdir: str,
    stdout_path: str,
    stderr_path: str = None,
    env_vars: dict = None,
    shell_env_vars: dict = None,
    array_spec: str = None,
    follow_commands: list = None
):
    """!
    @brief Render a Slurm batch script for a single command.
    @param[in] script_path Argument passed to `render_slurm_script()`.
    @param[in] job_name Argument passed to `render_slurm_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_script()`.
    @param[in] command Argument passed to `render_slurm_script()`.
    @param[in] workdir Argument passed to `render_slurm_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_script()`.
    @param[in] env_vars Argument passed to `render_slurm_script()`.
    @param[in] shell_env_vars Argument passed to `render_slurm_script()`.
    @param[in] array_spec Argument passed to `render_slurm_script()`.
    @param[in] follow_commands Commands to run after the launched one, each an argv
                               list. They run in the batch shell rather than under the
                               MPI launcher, so a serial step does not become one copy
                               per task. Supplying any of them drops the `exec`.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    extra_sbatch = execution.get("extra_sbatch")
    module_setup = execution.get("module_setup", []) or []
 
    if stderr_path is None:
        stderr_path = stdout_path.replace(".out", ".err")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    if array_spec:
        lines.append(f"#SBATCH --array={array_spec}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend(
        [
            "",
            "set -euo pipefail",
            "",
            f"cd {shlex.quote(workdir)}",
            'echo "[$(date)] Starting job ${SLURM_JOB_NAME} (${SLURM_JOB_ID})"',
            'echo "[$(date)] Working directory: $PWD"',
        ]
    )
 
    if shell_env_vars:
        for key, value in shell_env_vars.items():
            lines.append(f"export {key}={value}")
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    if env_vars:
        for key, value in env_vars.items():
            lines.append(f"export {key}={shlex.quote(str(value))}")
 
    cmd = " ".join(shlex.quote(str(tok)) for tok in command)
    if follow_commands:
        # `exec` would replace the shell and the trailing commands would never run.
        # `set -e` is already in effect, so a failure in the launched command aborts
        # the job before anything downstream of it executes.
        lines.append(cmd)
        for follow in follow_commands:
            lines.append(" ".join(shlex.quote(str(tok)) for tok in follow))
    else:
        lines.append(f"exec {cmd}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
def split_launcher_tokens(
    launcher: "str | None",
    launcher_args: "list | None" = None,
    label: str = "launcher",
) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize launcher config into executable token plus argv-style flags.
    @param[in] launcher Argument passed to `split_launcher_tokens()`.
    @param[in] launcher_args Argument passed to `split_launcher_tokens()`.
    @param[in] label Argument passed to `split_launcher_tokens()`.
    @return Value returned by `split_launcher_tokens()`.
    """
    normalized_args = [str(x) for x in (launcher_args or [])]
 
    if launcher is None:
        return None, normalized_args
 
    try:
        launcher_tokens = shlex.split(str(launcher))
    except ValueError as exc:
        raise ValueError(f"{label} is not shell-parseable: {exc}") from exc
 
    if not launcher_tokens:
        return None, normalized_args
 
    return launcher_tokens[0], launcher_tokens[1:] + normalized_args
 
 
def normalize_cluster_launcher(execution: dict) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize cluster launcher config into executable token plus argv-style flags.
    @param[in] execution Argument passed to `normalize_cluster_launcher()`.
    @return Value returned by `normalize_cluster_launcher()`.
    """
    return split_launcher_tokens(
        execution.get("launcher"),
        execution.get("launcher_args") or [],
        label="execution.launcher",
    )
 
 
def strip_launcher_size_flags(launcher_name: str, launcher_args: "list[str]") -> "list[str]":
    """!
    @brief Remove explicit MPI task-count flags from known launchers.
    @param[in] launcher_name Basename-normalized launcher executable.
    @param[in] launcher_args Launcher argument list.
    @return Filtered launcher arguments with explicit size flags removed.
    """
    filtered = []
    idx = 0
    while idx < len(launcher_args):
        token = str(launcher_args[idx])
 
        if launcher_name == "srun":
            if token in {"-n", "--ntasks"}:
                idx += 2
                continue
            if token.startswith("--ntasks="):
                idx += 1
                continue
        elif launcher_name in {"mpiexec", "mpirun"}:
            if token in {"-n", "-np"}:
                idx += 2
                continue
            if token.startswith("-n=") or token.startswith("-np="):
                idx += 1
                continue
 
        filtered.append(token)
        idx += 1
 
    return filtered
 
 
def build_local_launch_command(
    executable: str,
    executable_args: list,
    num_procs: int,
    config_search_anchor: str = None,
    allow_single_rank_launcher_override: bool = False,
    force_num_procs: "int | None" = None,
) -> list:
    """!
    @brief Build local launcher command, allowing env or shared config overrides for login-node MPI quirks.
    @param[in] executable Argument passed to `build_local_launch_command()`.
    @param[in] executable_args Argument passed to `build_local_launch_command()`.
    @param[in] num_procs Argument passed to `build_local_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_local_launch_command()`.
    @param[in] allow_single_rank_launcher_override When true, explicit launcher overrides also apply to 1-rank commands.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_local_launch_command()`.
    """
    target_num_procs = force_num_procs if force_num_procs is not None else num_procs
    command = [executable] + executable_args
    if target_num_procs <= 1 and not allow_single_rank_launcher_override:
        return command
 
    launcher_override = os.environ.get("PICURV_MPI_LAUNCHER")
    if launcher_override is None:
        launcher_override = os.environ.get("MPI_LAUNCHER")
 
    try:
        if launcher_override is not None:
            explicit_launcher_config = True
            launcher, launcher_args = split_launcher_tokens(
                launcher_override,
                label="local MPI launcher override",
            )
        else:
            _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor)
            local_execution = resolve_runtime_execution_context(runtime_execution_cfg, "local")
            configured_launcher = local_execution.get("launcher")
            configured_args = local_execution.get("launcher_args") or []
            explicit_launcher_config = configured_launcher is not None or bool(configured_args)
            if target_num_procs <= 1 and not explicit_launcher_config:
                return command
            launcher, launcher_args = split_launcher_tokens(
                configured_launcher if configured_launcher is not None else "mpiexec",
                configured_args,
                label="local_execution.launcher",
            )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if not launcher:
        return command
 
    launcher_name = os.path.basename(launcher).lower()
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
    prefix = [launcher] + launcher_args
 
    if launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
    elif launcher_name in {"mpiexec", "mpirun"}:
        has_n = any(token in {"-n", "-np"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
 
    return prefix + command
 
def resolve_cluster_execution(cluster_cfg: dict, config_search_anchor: str = None, extra_search_anchors=None) -> dict:
    """!
    @brief Resolve cluster execution launcher settings from shared runtime config plus cluster.yml overrides.
    @param[in] cluster_cfg Argument passed to `resolve_cluster_execution()`.
    @param[in] config_search_anchor Argument passed to `resolve_cluster_execution()`.
    @param[in] extra_search_anchors Argument passed to `resolve_cluster_execution()`.
    @return Value returned by `resolve_cluster_execution()`.
    """
    _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor, extra_search_anchors=extra_search_anchors)
    shared_cluster_execution = resolve_runtime_execution_context(runtime_execution_cfg, "cluster")
    execution = cluster_cfg.get("execution", {}) or {}
    cluster_override = {
        "launcher": execution.get("launcher") if "launcher" in execution else None,
        "launcher_args": execution.get("launcher_args") if "launcher_args" in execution else None,
    }
    return merge_execution_overrides(shared_cluster_execution, cluster_override)
 
 
def build_cluster_launch_command(
    cluster_cfg: dict,
    executable: str,
    executable_args: list,
    config_search_anchor: str = None,
    extra_search_anchors=None,
    force_num_procs: "int | None" = None,
) -> list:
    """!
    @brief Build scheduler launcher command from cluster config plus optional shared execution defaults.
    @param[in] cluster_cfg Argument passed to `build_cluster_launch_command()`.
    @param[in] executable Argument passed to `build_cluster_launch_command()`.
    @param[in] executable_args Argument passed to `build_cluster_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_cluster_launch_command()`.
    @param[in] extra_search_anchors Argument passed to `build_cluster_launch_command()`.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_cluster_launch_command()`.
    """
    try:
        execution = resolve_cluster_execution(
            cluster_cfg,
            config_search_anchor=config_search_anchor,
            extra_search_anchors=extra_search_anchors,
        )
        launcher, launcher_args = split_launcher_tokens(
            execution.get("launcher") if execution.get("launcher") is not None else "srun",
            execution.get("launcher_args") or [],
            label="cluster execution launcher",
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    ntasks = int(force_num_procs) if force_num_procs is not None else get_cluster_total_tasks(cluster_cfg)
    launcher_name = launcher.lower() if launcher else ""
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
 
    if launcher and launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        cmd = ["srun"] + launcher_args
        if not has_n:
            cmd += ["-n", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpirun":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpirun"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpiexec":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpiexec"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    # Custom launcher or no launcher.
    cmd = []
    if launcher:
        cmd.append(str(launcher))
    cmd += launcher_args
    cmd += [executable] + executable_args
    return cmd
 
def parse_slurm_job_id(sbatch_output: str) -> str:
    """!
    @brief Extract numeric job id from standard sbatch output.
    @param[in] sbatch_output Argument passed to `parse_slurm_job_id()`.
    @return Value returned by `parse_slurm_job_id()`.
    """
    match = re.search(r"Submitted batch job\s+(\d+)", sbatch_output or "")
    return match.group(1) if match else None
 
def submit_sbatch(script_path: str, dependency: str = None, dependency_type: str = "afterok") -> dict:
    """!
    @brief Submit sbatch script and return submission metadata.
    @param[in] script_path Argument passed to `submit_sbatch()`.
    @param[in] dependency Argument passed to `submit_sbatch()`.
    @param[in] dependency_type Slurm dependency type (default: afterok). Common values: afterok, afterany.
    @return Value returned by `submit_sbatch()`.
    """
    cmd = ["sbatch"]
    if dependency:
        cmd.append(f"--dependency={dependency_type}:{dependency}")
    cmd.append(script_path)
    result = subprocess.run(cmd, text=True, capture_output=True, check=False)
    metadata = {
        "command": cmd,
        "returncode": result.returncode,
        "stdout": (result.stdout or "").strip(),
        "stderr": (result.stderr or "").strip(),
        "script": script_path,
    }
    if result.returncode != 0:
        print(f"[FATAL] sbatch submission failed for {script_path}\n{metadata['stderr']}", file=sys.stderr)
        sys.exit(result.returncode)
    metadata["job_id"] = parse_slurm_job_id(metadata["stdout"])
    if not metadata["job_id"]:
        print(
            f"[FATAL] Could not parse Slurm job id from sbatch output: {metadata['stdout']}",
            file=sys.stderr
        )
        sys.exit(1)
    return metadata
 
 
def _print_validation_errors(errors: list):
    """!
    @brief Prints validation errors and exits.
    @param[in] errors List of error message strings.
    """
    print(f"\n[FATAL] Configuration validation failed with {len(errors)} issue(s):", file=sys.stderr)
    for raw_error in errors:
        file_path, message = _split_error_file_and_message(raw_error)
        key_path = _extract_key_path(message)
        code = _classify_error_code(message)
        emit_structured_error(code, key=key_path, file_path=file_path, message=message)
    print(
        "\nHint: See examples/master_template/ for valid config structure and "
        "docs/pages/14_Config_Contract.md for key-level contract details.",
        file=sys.stderr,
    )
    sys.exit(1)
 
 
def generate_header(run_id: str, source_files: dict) -> str:
    """!
    @brief Creates a standard header block for all generated files.
    @param[in] run_id The unique identifier for the current simulation run.
    @param[in] source_files A dictionary of source profile files used.
    @return A formatted string containing the header.
    """
    header_parts = [
        "# ==============================================================================",
        "#                AUTO-GENERATED CONFIGURATION FILE",
        "# ------------------------------------------------------------------------------",
        f"#   Run ID:       {run_id}",
        f"#   Timestamp:    {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
        "#",
        "#   Source Configuration:"
    ]
    for name, path in source_files.items():
        header_parts.append(f"#     - {name:<12}: {os.path.basename(path)}")
    header_parts.extend([
        "#",
        "#   DO NOT EDIT THIS FILE MANUALLY. IT IS A MACHINE-READABLE ARTIFACT.",
        "# ==============================================================================\n"
    ])
    return "\n".join(header_parts)
 
def generate_simple_list_file(run_dir: str, run_id: str, cfg: dict, section: str, key: str,
                              filename: str, header_sources: dict,
                              config_dir: str = None) -> str:
    """!
    @brief Generic function to create a file containing a simple list of strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] cfg The dictionary containing the configuration data.
    @param[in] section The top-level key in the cfg dictionary.
    @param[in] key The second-level key whose value is the list of strings.
    @param[in] filename The name of the file to generate (e.g., 'whitelist.run').
    @param[in] header_sources A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return The absolute path to the generated file.
    """
    print(f"[INFO] Generating {filename}...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    file_path = os.path.join(config_dir, filename)
    
    lines = [generate_header(run_id, header_sources)]
    items = cfg.get(section, {}).get(key, [])
    lines.extend(items)
 
    with open(file_path, "w") as f: f.write("\n".join(lines))
    print(f"[SUCCESS] Generated {filename}: {os.path.relpath(file_path)}")
    return os.path.abspath(file_path)
 
 
def has_explicit_monitor_whitelist(monitor_cfg: dict) -> bool:
    """!
    @brief Return True when logging.enabled_functions contains at least one entry.
    @param[in] monitor_cfg Argument passed to `has_explicit_monitor_whitelist()`.
    @return Value returned by `has_explicit_monitor_whitelist()`.
    """
    items = monitor_cfg.get("logging", {}).get("enabled_functions", [])
    return bool(items)
 
 
def resolve_profiling_config(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve profiling reporting config from monitor.yml.
    @param[in] monitor_cfg Argument passed to `resolve_profiling_config()`.
    @return Value returned by `resolve_profiling_config()`.
    """
    profiling_cfg = monitor_cfg.get("profiling", {}) or {}
    timestep_cfg = profiling_cfg.get("timestep_output")
    final_cfg = profiling_cfg.get("final_summary")
 
    if timestep_cfg is None:
        mode = "off"
        functions = []
        timestep_file = "Profiling_Timestep_Summary.csv"
    else:
        if not isinstance(timestep_cfg, dict):
            raise ValueError("monitor.profiling.timestep_output must be a mapping when provided.")
        mode = str(timestep_cfg.get("mode", "off")).lower()
        functions = timestep_cfg.get("functions", [])
        timestep_file = str(timestep_cfg.get("file", "Profiling_Timestep_Summary.csv"))
 
    if mode not in PROFILING_TIMESTEP_MODES:
        raise ValueError("monitor.profiling.timestep_output.mode must be one of ['off', 'selected', 'all'].")
    if functions is None:
        functions = []
    if not isinstance(functions, list):
        raise ValueError("monitor.profiling.timestep_output.functions must be a list of function names.")
    if not all(isinstance(item, str) and item.strip() for item in functions):
        raise ValueError("monitor.profiling.timestep_output.functions entries must be non-empty strings.")
    if mode == "selected" and not functions:
        raise ValueError("monitor.profiling.timestep_output.functions must be non-empty when mode is 'selected'.")
    if mode != "selected" and functions:
        raise ValueError("monitor.profiling.timestep_output.functions is only valid when mode is 'selected'.")
    if not timestep_file:
        raise ValueError("monitor.profiling.timestep_output.file must be a non-empty string.")
 
    if final_cfg is None:
        final_enabled = True
    elif isinstance(final_cfg, dict):
        final_enabled = bool(final_cfg.get("enabled", True))
    else:
        raise ValueError("monitor.profiling.final_summary must be a mapping when provided.")
 
    return {
        "mode": mode,
        "functions": functions,
        "timestep_file": timestep_file,
        "final_summary_enabled": final_enabled,
    }
 
 
DIAGNOSTICS_PETSC_KEYS = {
    "info",
    "malloc_debug",
    "malloc_test",
    "malloc_dump",
    "malloc_view",
    "malloc_view_threshold",
    "memory_view",
    "log_view",
    "log_view_memory",
    "log_all",
    "log_trace",
    "objects_dump",
    "options_left",
}
 
 
def _diagnostic_info(value) -> dict:
    """!
    @brief Validate PETSc info logging configuration.
    @param[in] value Boolean or structured PETSc info configuration.
    @return Normalized enabled/class-filter mapping.
    """
    if isinstance(value, bool):
        return {"enabled": value, "classes": []}
    if value is None:
        return {"enabled": False, "classes": []}
    if not isinstance(value, dict):
        raise ValueError("monitor.diagnostics.petsc.info must be boolean, null, or a mapping.")
    unknown = sorted(set(value) - {"enabled", "classes"})
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc.info has unsupported key(s): {unknown}.")
    enabled = value.get("enabled", True)
    classes = value.get("classes", [])
    if not isinstance(enabled, bool):
        raise ValueError("monitor.diagnostics.petsc.info.enabled must be boolean.")
    if not isinstance(classes, list) or not all(
        isinstance(item, str) and item.strip() and "," not in item and ":" not in item
        for item in classes
    ):
        raise ValueError(
            "monitor.diagnostics.petsc.info.classes must be a list of non-empty PETSc class names."
        )
    return {"enabled": enabled, "classes": [item.strip() for item in classes]}
 
 
def _diagnostic_bool_or_path(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or a path/viewer string.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip():
        return value.strip()
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or a non-empty string.")
 
 
def _diagnostic_bool(value, key: str) -> bool:
    """!
    @brief Validate a diagnostics boolean value.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Boolean value.
    """
    if isinstance(value, bool):
        return value
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean.")
 
 
def _diagnostic_bool_or_all(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or "all".
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip().lower() == "all":
        return "all"
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or 'all'.")
 
 
def _diagnostic_default_file(run_dir: str, filename: str) -> str:
    """!
    @brief Return an absolute run-local diagnostics file path.
    @param[in] run_dir Run directory.
    @param[in] filename Diagnostics filename.
    @return Absolute diagnostics path under the run logs directory.
    """
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"], filename))
 
 
def _diagnostic_resolve_path_or_default(value, run_dir: str, default_filename: str):
    """!
    @brief Resolve true/string diagnostics values to a concrete file path.
    @param[in] value Boolean/string diagnostics value.
    @param[in] run_dir Run directory.
    @param[in] default_filename Default file name when value is true.
    @return False, or an absolute/explicit path string.
    """
    if value is True:
        return _diagnostic_default_file(run_dir, default_filename)
    if isinstance(value, str):
        if os.path.isabs(value) or value.startswith(":"):
            return value
        return os.path.abspath(os.path.join(run_dir, "logs", value))
    return False
 
 
def resolve_diagnostics_config(monitor_cfg: dict, run_dir: "str | None" = None, stage_label: str = "Solver") -> dict:
    """!
    @brief Resolve monitor diagnostics config and default run-local log paths.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Optional run directory for default artifact paths.
    @param[in] stage_label Solver/PostProcessor suffix used for PETSc output defaults.
    @return Normalized diagnostics config.
    """
    diagnostics_cfg = (monitor_cfg.get("diagnostics", {}) or {}) if isinstance(monitor_cfg, dict) else {}
    if not isinstance(diagnostics_cfg, dict):
        raise ValueError("monitor.diagnostics must be a mapping when provided.")
 
    petsc_raw = diagnostics_cfg.get("petsc", {}) or {}
    if not isinstance(petsc_raw, dict):
        raise ValueError("monitor.diagnostics.petsc must be a mapping when provided.")
    unknown = sorted(set(petsc_raw.keys()) - DIAGNOSTICS_PETSC_KEYS)
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc has unsupported key(s): {unknown}.")
 
    petsc = {
        "info": _diagnostic_info(petsc_raw.get("info", False)),
        "malloc_debug": _diagnostic_bool(petsc_raw.get("malloc_debug", False), "malloc_debug"),
        "malloc_test": _diagnostic_bool(petsc_raw.get("malloc_test", False), "malloc_test"),
        "malloc_dump": _diagnostic_bool(petsc_raw.get("malloc_dump", False), "malloc_dump"),
        "malloc_view": _diagnostic_bool_or_path(petsc_raw.get("malloc_view", False), "malloc_view"),
        "malloc_view_threshold": petsc_raw.get("malloc_view_threshold"),
        "memory_view": _diagnostic_bool(petsc_raw.get("memory_view", False), "memory_view"),
        "log_view": _diagnostic_bool_or_path(petsc_raw.get("log_view", False), "log_view"),
        "log_view_memory": _diagnostic_bool(petsc_raw.get("log_view_memory", False), "log_view_memory"),
        "log_all": _diagnostic_bool(petsc_raw.get("log_all", False), "log_all"),
        "log_trace": _diagnostic_bool_or_path(petsc_raw.get("log_trace", False), "log_trace"),
        "objects_dump": _diagnostic_bool_or_all(petsc_raw.get("objects_dump", False), "objects_dump"),
        "options_left": petsc_raw.get("options_left"),
    }
    if petsc["malloc_view_threshold"] is not None and not isinstance(petsc["malloc_view_threshold"], (int, float)):
        raise ValueError("monitor.diagnostics.petsc.malloc_view_threshold must be numeric or null.")
    if petsc["options_left"] is not None and not isinstance(petsc["options_left"], bool):
        raise ValueError("monitor.diagnostics.petsc.options_left must be boolean or null.")
 
    memory_raw = diagnostics_cfg.get("runtime_memory_log", {}) or {}
    if not isinstance(memory_raw, dict):
        raise ValueError("monitor.diagnostics.runtime_memory_log must be a mapping when provided.")
    memory_unknown = sorted(set(memory_raw.keys()) - {"enabled", "file"})
    if memory_unknown:
        raise ValueError(f"monitor.diagnostics.runtime_memory_log has unsupported key(s): {memory_unknown}.")
    memory_enabled = memory_raw.get("enabled", True)
    if not isinstance(memory_enabled, bool):
        raise ValueError("monitor.diagnostics.runtime_memory_log.enabled must be boolean.")
    memory_file = str(memory_raw.get("file", "Runtime_Memory.log")).strip()
    if not memory_file:
        raise ValueError("monitor.diagnostics.runtime_memory_log.file must be a non-empty string.")
 
    resolved_petsc = dict(petsc)
    artifacts = []
    if run_dir:
        suffix = "PostProcessor" if stage_label == "PostProcessor" else "Solver"
        resolved_petsc["info"] = False
        defaults = {
            "malloc_view": f"PETSc_MallocView_{suffix}.log",
            "log_view": f"PETSc_LogView_{suffix}.log",
            "log_trace": f"PETSc_LogTrace_{suffix}.log",
        }
        if petsc["info"]["enabled"]:
            info_path = _diagnostic_default_file(run_dir, f"PETSc_Info_{suffix}.log")
            classes = petsc["info"]["classes"]
            resolved_petsc["info"] = info_path + (f":{','.join(classes)}" if classes else "")
            # PetscInfoSetFile appends the emitting MPI rank (for example `.0`).
            artifacts.append(f"{info_path}.*")
        for key, default_name in defaults.items():
            resolved_value = _diagnostic_resolve_path_or_default(petsc[key], run_dir, default_name)
            if key == "log_view" and resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                resolved_value = f":{resolved_value}"
            resolved_petsc[key] = resolved_value
            if resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                artifacts.append(resolved_value)
            elif resolved_value and isinstance(resolved_value, str) and resolved_value.startswith(":"):
                artifacts.append(resolved_value[1:])
        if memory_enabled:
            artifacts.append(
                os.path.abspath(os.path.join(
                    run_dir, CANONICAL_RUN_PATHS["logs"], memory_file
                ))
            )
 
    return {
        "petsc": resolved_petsc,
        "runtime_memory_log": {"enabled": memory_enabled, "file": memory_file},
        "artifacts": artifacts,
    }
 
 
def build_petsc_diagnostics_args(monitor_cfg: dict, run_dir: str, stage_label: str) -> list:
    """!
    @brief Build PETSc diagnostics command-line arguments for a run stage.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Run directory used to resolve default diagnostics files.
    @param[in] stage_label Stage label for default output names.
    @return List of executable arguments.
    """
    diagnostics = resolve_diagnostics_config(monitor_cfg, run_dir, stage_label)
    petsc = diagnostics["petsc"]
    args = []
    if petsc["info"]:
        args.extend(["-info", str(petsc["info"])])
    if petsc["malloc_debug"]:
        args.append("-malloc_debug")
    if petsc["malloc_test"]:
        args.append("-malloc_test")
    for key, flag in (
        ("malloc_dump", "-malloc_dump"),
        ("malloc_view", "-malloc_view"),
        ("memory_view", "-memory_view"),
        ("log_view", "-log_view"),
        ("log_trace", "-log_trace"),
        ("objects_dump", "-objects_dump"),
    ):
        value = petsc.get(key)
        if value is True:
            args.append(flag)
        elif value:
            args.extend([flag, str(value)])
    if petsc["malloc_view_threshold"] is not None:
        args.extend(["-malloc_view_threshold", str(petsc["malloc_view_threshold"])])
    if petsc["log_view_memory"]:
        args.append("-log_view_memory")
    if petsc["log_all"]:
        args.append("-log_all")
    if petsc["options_left"] is not None:
        args.extend(["-options_left", "true" if petsc["options_left"] else "false"])
    return args
 
 
def _statistics_subsystem_available(case_cfg: dict, requirement) -> bool:
    """!
    @brief Report whether the subsystem a statistics field depends on is active.
    @param[in] case_cfg Parsed case configuration.
    @param[in] requirement Subsystem key from `STATISTICS_ELIGIBLE_FIELDS`, or None.
    @return Value returned by `_statistics_subsystem_available()`.
    """
    if requirement is None:
        return True
    physics = ((case_cfg or {}).get("models", {}) or {}).get("physics", {}) or {}
    if requirement == "particles":
        particles = physics.get("particles", {}) or {}
        try:
            return int(particles.get("count", 0) or 0) > 0
        except (TypeError, ValueError):
            return False
    turbulence = physics.get("turbulence", {}) or {}
    les_on = bool((turbulence.get("les", {}) or {}).get("enabled", False))
    rans_on = bool((turbulence.get("rans", {}) or {}).get("enabled", False))
    if requirement == "les":
        return les_on
    if requirement == "turbulence":
        return les_on or rans_on
    return False
 
 
def normalize_field_statistics_config(monitor_cfg: dict, case_cfg: dict = None) -> dict:
    """!
    @brief Validate and canonicalize the field-statistics block of monitor.yml.
 
    @details Rejects every condition the field-statistics contract forbids, naming the
             offending window so a message points at one entry rather than the block.
             Returns a canonical form the flag resolver serializes without further
             interpretation, so validation and emission cannot disagree.
 
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, used to check that each field's
                        subsystem is active. Subsystem checks are skipped when None.
    @return Value returned by `normalize_field_statistics_config()`.
    """
    raw = (monitor_cfg or {}).get("field_statistics")
    if raw is None:
        return {"enabled": False, "windows": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    enabled = raw.get("enabled", False)
    if not isinstance(enabled, bool):
        raise ValueError("'field_statistics.enabled' must be true or false.")
    windows_raw = raw.get("windows", []) or []
    if not isinstance(windows_raw, list):
        raise ValueError("'field_statistics.windows' must be a list.")
    if enabled and not windows_raw:
        raise ValueError("'field_statistics.enabled' is true but no window is defined.")
 
    windows = []
    seen_names = set()
    for index, window in enumerate(windows_raw):
        if not isinstance(window, dict):
            raise ValueError(f"'field_statistics.windows[{index}]' must be a mapping.")
        name = window.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ValueError(f"'field_statistics.windows[{index}]' needs a non-empty 'name'.")
        name = name.strip()
        # Window names identify saved state across a restart, so a duplicate would
        # make two windows indistinguishable in the checkpoint.
        if name in seen_names:
            raise ValueError(f"field statistics window '{name}' is defined more than once.")
        seen_names.add(name)
 
        start_time = window.get("start_time")
        if not isinstance(start_time, (int, float)) or isinstance(start_time, bool):
            raise ValueError(f"field statistics window '{name}': 'start_time' must be a number.")
        end_time = window.get("end_time")
        if end_time is not None:
            if not isinstance(end_time, (int, float)) or isinstance(end_time, bool):
                raise ValueError(f"field statistics window '{name}': 'end_time' must be a number.")
            if float(end_time) <= float(start_time):
                raise ValueError(
                    f"field statistics window '{name}': 'end_time' ({end_time}) must be greater "
                    f"than 'start_time' ({start_time})."
                )
 
        weighting = window.get("weighting")
        if weighting not in STATISTICS_WEIGHTING_MODES:
            raise ValueError(
                f"field statistics window '{name}': 'weighting' must be one of "
                f"{list(STATISTICS_WEIGHTING_MODES)} (got {weighting!r})."
            )
 
        has_step = "step_cadence" in window and window["step_cadence"] is not None
        has_time = "time_cadence" in window and window["time_cadence"] is not None
        if has_step == has_time:
            raise ValueError(
                f"field statistics window '{name}': set exactly one of 'step_cadence' and "
                "'time_cadence'."
            )
        step_cadence = None
        time_cadence = None
        if has_step:
            step_cadence = window["step_cadence"]
            if not isinstance(step_cadence, int) or isinstance(step_cadence, bool) or step_cadence <= 0:
                raise ValueError(
                    f"field statistics window '{name}': 'step_cadence' must be a positive integer "
                    f"(got {step_cadence!r})."
                )
        else:
            time_cadence = window["time_cadence"]
            if (not isinstance(time_cadence, (int, float)) or isinstance(time_cadence, bool)
                    or float(time_cadence) <= 0.0):
                raise ValueError(
                    f"field statistics window '{name}': 'time_cadence' must be a positive number "
                    f"(got {time_cadence!r})."
                )
 
        fields_raw = window.get("fields")
        if not isinstance(fields_raw, list) or not fields_raw:
            raise ValueError(f"field statistics window '{name}': 'fields' must be a non-empty list.")
        fields = []
        for field_entry in fields_raw:
            if not isinstance(field_entry, dict):
                raise ValueError(f"field statistics window '{name}': each 'fields' entry must be a mapping.")
            field_name = field_entry.get("field")
            if field_name not in STATISTICS_ELIGIBLE_FIELDS:
                raise ValueError(
                    f"field statistics window '{name}': field {field_name!r} cannot be accumulated. "
                    f"Available fields: {sorted(STATISTICS_ELIGIBLE_FIELDS)}."
                )
            requirement = STATISTICS_ELIGIBLE_FIELDS[field_name]["requires"]
            if case_cfg is not None and not _statistics_subsystem_available(case_cfg, requirement):
                raise ValueError(
                    f"field statistics window '{name}': field '{field_name}' requires the "
                    f"'{requirement}' subsystem, which is not enabled for this case."
                )
            if any(existing["field"] == field_name for existing in fields):
                raise ValueError(
                    f"field statistics window '{name}': field '{field_name}' is listed more than once."
                )
            moments = field_entry.get("moments")
            if not isinstance(moments, list) or not moments:
                raise ValueError(
                    f"field statistics window '{name}': field '{field_name}' needs a non-empty "
                    "'moments' list."
                )
            unknown = [m for m in moments if m not in STATISTICS_MOMENT_NAMES]
            if unknown:
                raise ValueError(
                    f"field statistics window '{name}': field '{field_name}' requests unknown "
                    f"moments {unknown}. Available moments: {list(STATISTICS_MOMENT_NAMES)}."
                )
            # The first moment is always kept, because every centered product is
            # measured against it.
            fields.append({"field": field_name, "moments": ["first"] + (["second"] if "second" in moments else [])})
 
        covariances_raw = window.get("covariances", []) or []
        if not isinstance(covariances_raw, list):
            raise ValueError(f"field statistics window '{name}': 'covariances' must be a list.")
        requested = {entry["field"] for entry in fields}
        covariances = []
        for pair in covariances_raw:
            if not isinstance(pair, list) or len(pair) != 2:
                raise ValueError(
                    f"field statistics window '{name}': each covariance must be a pair of field names."
                )
            first, second = pair
            for member in (first, second):
                if member not in STATISTICS_ELIGIBLE_FIELDS:
                    raise ValueError(
                        f"field statistics window '{name}': covariance member {member!r} cannot be "
                        f"accumulated. Available fields: {sorted(STATISTICS_ELIGIBLE_FIELDS)}."
                    )
            if first == second:
                raise ValueError(
                    f"field statistics window '{name}': covariance ['{first}', '{second}'] pairs a "
                    "field with itself; request that through moments: [second] instead."
                )
            missing = sorted({first, second} - requested)
            if missing:
                raise ValueError(
                    f"field statistics window '{name}': covariance ['{first}', '{second}'] needs "
                    f"{missing} in 'fields' as well, because a co-moment is centered against their means."
                )
            # Two three-component fields would need a full nine-component tensor,
            # which nothing allocates.
            if (STATISTICS_ELIGIBLE_FIELDS[first]["components"] == 3
                    and STATISTICS_ELIGIBLE_FIELDS[second]["components"] == 3):
                raise ValueError(
                    f"field statistics window '{name}': covariance ['{first}', '{second}'] pairs two "
                    "vector fields, which is not supported."
                )
            if sorted((first, second)) in [sorted(existing) for existing in covariances]:
                raise ValueError(
                    f"field statistics window '{name}': covariance ['{first}', '{second}'] is "
                    "requested more than once."
                )
            covariances.append([first, second])
 
        windows.append({
            "name": name,
            "start_time": float(start_time),
            "end_time": None if end_time is None else float(end_time),
            "weighting": weighting,
            "step_cadence": step_cadence,
            "time_cadence": None if time_cadence is None else float(time_cadence),
            "fields": fields,
            "covariances": covariances,
        })
 
    return {"enabled": bool(enabled), "windows": windows}
 
 
def resolve_field_statistics_flags(monitor_cfg: dict, case_cfg: dict = None) -> list:
    """!
    @brief Serialize field-statistics configuration into control-file option lines.
    @details A window list is variable arity, so its option names are constructed from
             the index. Each name belongs to a family declared in the ingress audit
             manifest.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, for subsystem availability checks.
    @return Value returned by `resolve_field_statistics_flags()`.
    """
    config = normalize_field_statistics_config(monitor_cfg, case_cfg)
    if not config["enabled"]:
        return []
 
    lines = ["-field_statistics_enabled true",
             f"-field_statistics_window_count {len(config['windows'])}"]
    for index, window in enumerate(config["windows"]):
        prefix = f"-field_statistics_window_{index}"
        lines.append(f"{prefix}_name {window['name']}")
        lines.append(f"{prefix}_start_time {window['start_time']!r}")
        # An absent end time is what makes a window open ended, so the option is
        # omitted rather than given a sentinel value.
        if window["end_time"] is not None:
            lines.append(f"{prefix}_end_time {window['end_time']!r}")
        lines.append(f"{prefix}_weighting {window['weighting']}")
        if window["step_cadence"] is not None:
            lines.append(f"{prefix}_step_cadence {window['step_cadence']}")
        else:
            lines.append(f"{prefix}_time_cadence {window['time_cadence']!r}")
        lines.append(f"{prefix}_field_count {len(window['fields'])}")
        for field_index, field_entry in enumerate(window["fields"]):
            lines.append(f"{prefix}_field_{field_index}_name {field_entry['field']}")
            lines.append(f"{prefix}_field_{field_index}_moments {','.join(field_entry['moments'])}")
        lines.append(f"{prefix}_covariance_count {len(window['covariances'])}")
        for pair_index, pair in enumerate(window["covariances"]):
            lines.append(f"{prefix}_covariance_{pair_index} {pair[0]},{pair[1]}")
    return lines
 
 
def resolve_statistics_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Resolve the statistics console cadence, mirroring the particle one.
    @param[in] io_cfg Parsed monitor `io` block.
    @return Value returned by `resolve_statistics_console_output_frequency()`.
    """
    if 'statistics_console_output_frequency' in io_cfg:
        return io_cfg['statistics_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 
 
def normalize_solution_monitoring_config(monitor_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize physical-solution convergence monitoring.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Canonical solution-monitoring configuration.
    @throws ValueError when convergence settings are invalid.
    """
    if not isinstance(monitor_cfg, dict):
        raise ValueError("monitor.yml must be a mapping before solution monitoring can be normalized.")
    monitoring = monitor_cfg.get("solution_monitoring", {}) or {}
    if not isinstance(monitoring, dict):
        raise ValueError("solution_monitoring must be a mapping when provided.")
    convergence = monitoring.get("convergence", {}) or {}
    if not isinstance(convergence, dict):
        raise ValueError("solution_monitoring.convergence must be a mapping when provided.")
    enabled = convergence.get("enabled", True)
    if not isinstance(enabled, bool):
        raise ValueError("solution_monitoring.convergence.enabled must be boolean.")
    mode = normalize_solution_convergence_mode(convergence.get("mode", "steady_deterministic"))
    normalized = {"enabled": enabled, "mode": mode.lower()}
    periodic_cfg = convergence.get("periodic_deterministic")
    statistical_cfg = convergence.get("statistical_steady")
    if mode == "PERIODIC_DETERMINISTIC":
        if not isinstance(periodic_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic is required for periodic_deterministic mode."
            )
        period_steps = periodic_cfg.get("period_steps")
        if isinstance(period_steps, bool) or not isinstance(period_steps, int) or period_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic.period_steps must be a positive integer."
            )
        normalized["periodic_deterministic"] = {"period_steps": period_steps}
    elif periodic_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.periodic_deterministic is only valid for periodic_deterministic mode."
        )
    if mode == "STATISTICAL_STEADY":
        if not isinstance(statistical_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady is required for statistical_steady mode."
            )
        window_steps = statistical_cfg.get("window_steps")
        if isinstance(window_steps, bool) or not isinstance(window_steps, int) or window_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady.window_steps must be a positive integer."
            )
        normalized["statistical_steady"] = {"window_steps": window_steps}
    elif statistical_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.statistical_steady is only valid for statistical_steady mode."
        )
    return {"convergence": normalized}
 
 
def resolve_solution_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Translate solution-monitoring YAML into the existing C convergence flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of convergence options to explicit runtime values.
    """
    convergence = normalize_solution_monitoring_config(monitor_cfg)["convergence"]
    flags = {
        "-solution_convergence_enabled": "true" if convergence["enabled"] else "false",
        "-solution_convergence_mode": f'"{normalize_solution_convergence_mode(convergence["mode"])}"',
    }
    if "periodic_deterministic" in convergence:
        flags["-solution_convergence_period_steps"] = convergence["periodic_deterministic"]["period_steps"]
    if "statistical_steady" in convergence:
        flags["-solution_convergence_window_steps"] = convergence["statistical_steady"]["window_steps"]
    return flags
 
 
def prepare_monitor_files(run_dir: str, run_id: str, monitor_cfg: dict, source_files: dict,
                          config_dir: str = None) -> dict:
    """!
    @brief Generate monitor sidecar files and resolve profiling reporting behavior.
    @param[in] run_dir Argument passed to `prepare_monitor_files()`.
    @param[in] run_id Argument passed to `prepare_monitor_files()`.
    @param[in] monitor_cfg Argument passed to `prepare_monitor_files()`.
    @param[in] source_files Argument passed to `prepare_monitor_files()`.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `prepare_monitor_files()`.
    """
    print("[INFO] Generating monitoring files...")
 
    whitelist_path = None
    if has_explicit_monitor_whitelist(monitor_cfg):
        whitelist_path = generate_simple_list_file(
            run_dir, run_id, monitor_cfg, "logging", "enabled_functions", "whitelist.run", source_files,
            config_dir=config_dir,
        )
    else:
        print("[INFO] logging.enabled_functions is empty; omitting whitelist.run so the C runtime uses its default allow-list.")
 
    profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    profile_path = None
    if profiling_cfg["mode"] == "selected":
        profile_path = generate_simple_list_file(
            run_dir,
            run_id,
            {"profiling": {"selected_functions": profiling_cfg["functions"]}},
            "profiling",
            "selected_functions",
            "profile.run",
            source_files,
            config_dir=config_dir,
        )
    else:
        print(f"[INFO] profiling.timestep_output.mode is '{profiling_cfg['mode']}'; no profile.run function list is needed.")
 
    return {
        "whitelist": whitelist_path,
        "profile": profile_path,
        "profiling": profiling_cfg,
    }
 
def generate_multi_block_bcs(run_dir: str, run_id: str, case_cfg: dict, source_files: dict,
                             config_dir: str = None) -> list:
    """!
    @brief Parses multi-block BCs from YAML, generates a .run file for each block,
           and returns a list of their absolute paths.
    @details Handles both simple list format (for single-block cases) and a
             list-of-lists (for multi-block cases) for boundary conditions.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return A list of absolute paths to the generated BC files.
    @throws ValueError if the number of BC definitions does not match the number of blocks.
    """
    print("[INFO] Generating boundary condition files...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    os.makedirs(profile_dir, exist_ok=True)
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    case_path = source_files.get("Case") if source_files else None
    profile_grid_dims = None
    scales = case_cfg.get('properties', {}).get('scaling', {})
    U_ref = _to_float(scales.get('velocity_ref'), "properties.scaling.velocity_ref")
    if U_ref == 0.0:
        raise ValueError("properties.scaling.velocity_ref must be non-zero for prescribed_flow profile staging.")
 
    if any(bc.get("handler") == "prescribed_flow" for block in prepared_blocks for bc in block):
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    generated_files = []
    generated_profile_summaries = []
    generated_target_grid = None
    field_slice_target_grid = None
    for i, block_bcs_list in enumerate(prepared_blocks):
        file_name = "bcs.run" if num_blocks == 1 else f"bcs_block{i}.run"
        bcs_file_path = os.path.join(config_dir, file_name)
        bcs_lines = [generate_header(run_id, source_files)]
 
        for bc in block_bcs_list:
            face, bc_type, handler = bc['face'], bc['type'], bc['handler']
            params = dict(bc.get('params') or {})
            if handler == "prescribed_flow":
                source = params.pop("source")
                expected_dims = _bc_profile_expected_dims(face, profile_grid_dims[i])
                staged_name = f"inlet_profile_block{i}_{face.replace('+', 'pos').replace('-', 'neg')}.picslice"
                staged_path = os.path.join(profile_dir, staged_name)
                if os.path.isfile(staged_path):
                    with open(staged_path, "r", encoding="utf-8") as stream:
                        header = [line.strip() for line in stream if line.strip() and not line.lstrip().startswith("#")]
                    if len(header) < 3 or header[0] != "PICSLICE":
                        raise ValueError(f"Locked inlet profile is not a PICSLICE file: {staged_path}")
                    try:
                        actual_dims = tuple(int(token) for token in header[2].split())
                    except ValueError as exc:
                        raise ValueError(f"Locked inlet profile has invalid dimensions: {staged_path}") from exc
                    if actual_dims != tuple(expected_dims):
                        raise ValueError(
                            f"Locked inlet profile {staged_path} has dimensions {actual_dims}; "
                            f"expected {tuple(expected_dims)}."
                        )
                    print(
                        f"[INFO] Reusing locked prescribed_flow profile for block {i}, "
                        f"face {face}: {os.path.relpath(staged_path)}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
                    source = None
                elif source["type"] == "file":
                    source_path = _resolve_case_relative_path(
                        source["path"], os.path.dirname(os.path.abspath(case_path))
                    )
                elif source["type"] == "generated":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.generated.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"Generated profile output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if source["generator"] == "square_duct_poiseuille":
                        if generated_target_grid is None:
                            generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                        summary = generate_square_duct_poiseuille_picslice(
                            source_path,
                            expected_dims,
                            source["params"],
                            target_grid=generated_target_grid,
                            target_block=i,
                            target_face=face,
                            script=source.get("script"),
                            case_path=case_path,
                        )
                    else:
                        raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source["type"] == "field_slice":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.sliced.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"field_slice output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if field_slice_target_grid is None:
                        field_slice_target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                    summary = generate_field_slice_picslice(
                        source_path,
                        expected_dims,
                        source,
                        field_slice_target_grid,
                        face,
                        i,
                        case_path,
                    )
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source is not None:
                    raise ValueError(f"Unsupported prescribed_flow source type '{source.get('type')}'.")
                if source is not None:
                    summary = validate_and_nondimensionalize_picslice(source_path, staged_path, U_ref, expected_dims)
                    print(
                        f"[SUCCESS] Staged prescribed_flow profile for block {i}, face {face}: "
                        f"{os.path.relpath(staged_path)} dims={summary['dims']}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
            params_str = ""
            if params:
                parts = []
                for k, v in params.items():
                    if isinstance(v, bool):
                        value_str = "true" if v else "false"
                    else:
                        value_str = str(v)
                    parts.append(f"{k}={value_str}")
                params_str = " ".join(parts)
            bcs_lines.append(f"{face:<20s} {bc_type:<12s} {handler:<20s} {params_str}")
        
        with open(bcs_file_path, "w") as f: f.write("\n".join(bcs_lines))
        
        print(f"[SUCCESS] Generated BCs for Block {i}: {os.path.relpath(bcs_file_path)}")
        generated_files.append(os.path.abspath(bcs_file_path))
 
    if generated_profile_summaries:
        info_path = write_profile_info(profile_dir, generated_profile_summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
        
    return generated_files
 
def format_flag_value(value):
    """!
    @brief Converts Python types to C-style command-line flag values.
    @param[in] value The Python object to convert (bool, list, or other).
    @return A string representation suitable for a C command-line parser.
    """
    if isinstance(value, bool):
        return "1" if value else "0"
    if isinstance(value, list):
        return ",".join(map(str, value))
    return str(value)
 
def translate_programmatic_grid_settings(grid_settings: dict) -> dict:
    """!
    @brief Return programmatic-grid settings translated to the C node-count contract.
    @param[in] grid_settings Argument passed to `translate_programmatic_grid_settings()`.
    @return Value returned by `translate_programmatic_grid_settings()`.
    """
    translated = dict(grid_settings)
    for dim_key in ("im", "jm", "km"):
        if dim_key in translated:
            raw_val = translated[dim_key]
            if not isinstance(raw_val, int) or raw_val <= 0:
                raise ValueError(
                    f"grid.programmatic_settings.{dim_key} must be a positive integer cell count "
                    f"(got {raw_val!r})."
                )
            translated[dim_key] = raw_val + 1
    return translated
 
 
PROGRAMMATIC_GENERATED_IC_GRID_KEYS = (
    "im", "jm", "km",
    "xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs",
    "rxs", "rys", "rzs",
)
 
 
def validate_programmatic_generated_ic_grid_settings(raw_settings: dict) -> None:
    """!
    @brief Validate scalar programmatic grid settings needed by file-generating IC providers.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @throws ValueError when required scalar settings are missing or invalid.
    """
    if not isinstance(raw_settings, dict):
        raise ValueError(
            "grid.programmatic_settings must be a mapping for a generated initial condition."
        )
 
    missing = [key for key in PROGRAMMATIC_GENERATED_IC_GRID_KEYS if key not in raw_settings]
    if missing:
        raise ValueError(
            "grid.programmatic_settings must include "
            f"{missing} when grid.mode is 'programmatic_c' and the initial condition requires a grid file."
        )
 
    for key in ("im", "jm", "km"):
        value = raw_settings[key]
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a positive scalar integer cell count "
                "for programmatic_c with a generated initial condition."
            )
 
    for key in ("xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs", "rxs", "rys", "rzs"):
        value = raw_settings[key]
        if isinstance(value, (list, tuple, dict, bool)):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "for a generated initial condition."
            )
        try:
            numeric = float(value)
        except (TypeError, ValueError):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "for a generated initial condition."
            )
        if not math.isfinite(numeric):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be finite "
                "for a generated initial condition."
            )
        if key in {"rxs", "rys", "rzs"} and numeric <= 0.0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be positive "
                "for a generated initial condition."
            )
 
 
def generate_picgrid_from_programmatic_settings(raw_settings: dict, dest_path: str, L_ref: float) -> dict:
    """!
    @brief Generate a canonical PICGRID file from programmatic Cartesian grid settings.
    @details Implements the same coordinate formula as ComputeStretchedCoord in src/grid.c.
             im/jm/km in raw_settings are cell counts; node counts are im+1, jm+1, km+1.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @param[in] dest_path Destination PICGRID file path.
    @param[in] L_ref Reference length for nondimensionalization (must be non-zero).
    @return Summary dict: nblk, dims [(IM, JM, KM)], total_nodes.
    """
    validate_programmatic_generated_ic_grid_settings(raw_settings)
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero for programmatic grid generation.")
    IM = int(raw_settings.get("im", 0)) + 1
    JM = int(raw_settings.get("jm", 0)) + 1
    KM = int(raw_settings.get("km", 0)) + 1
    if IM < 2 or JM < 2 or KM < 2:
        raise ValueError(
            f"programmatic_settings im/jm/km must each be >= 1 "
            f"(got im={IM-1}, jm={JM-1}, km={KM-1})."
        )
    x_min = float(raw_settings.get("xMins", 0.0))
    x_max = float(raw_settings.get("xMaxs", 1.0))
    y_min = float(raw_settings.get("yMins", 0.0))
    y_max = float(raw_settings.get("yMaxs", 1.0))
    z_min = float(raw_settings.get("zMins", 0.0))
    z_max = float(raw_settings.get("zMaxs", 1.0))
    rx = float(raw_settings.get("rxs", 1.0))
    ry = float(raw_settings.get("rys", 1.0))
    rz = float(raw_settings.get("rzs", 1.0))
 
    def _stretched(idx, N, length, r):
        """!
        @brief Mirror of ComputeStretchedCoord from src/grid.c.
        @param[in] idx Node index along the axis.
        @param[in] N Total node count along the axis.
        @param[in] length Physical length of the axis.
        @param[in] r Geometric stretching ratio.
        @return Coordinate offset from the axis minimum.
        """
        frac = idx / (N - 1.0)
        if abs(r - 1.0) < 1.0e-9:
            return length * frac
        return length * (r ** frac - 1.0) / (r - 1.0)
 
    Lx, Ly, Lz = x_max - x_min, y_max - y_min, z_max - z_min
    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
    with open(dest_path, "w") as fout:
        fout.write("PICGRID\n1\n")
        fout.write(f"{IM} {JM} {KM}\n")
        for k in range(KM):
            z = (z_min + _stretched(k, KM, Lz, rz)) / L_ref
            for j in range(JM):
                y = (y_min + _stretched(j, JM, Ly, ry)) / L_ref
                for i in range(IM):
                    x = (x_min + _stretched(i, IM, Lx, rx)) / L_ref
                    fout.write(
                        f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                        f"{format_picgrid_coordinate(z)}\n"
                    )
    total_nodes = IM * JM * KM
    return {"nblk": 1, "dims": [(IM, JM, KM)], "total_nodes": total_nodes}
 
 
GRID_DA_PROCESSOR_KEYS = ("da_processors_x", "da_processors_y", "da_processors_z")
 
 
def resolve_grid_da_processor_layout(grid_cfg: dict) -> dict:
    """!
    @brief Resolve optional global DMDA layout, preferring grid-level keys over legacy nested keys.
    @param[in] grid_cfg Argument passed to `resolve_grid_da_processor_layout()`.
    @return Value returned by `resolve_grid_da_processor_layout()`.
    """
    top_level = {}
    legacy = {}
 
    for key in GRID_DA_PROCESSOR_KEYS:
        value = grid_cfg.get(key)
        if isinstance(value, (list, tuple)):
            raise ValueError(
                f"grid.{key} must be a scalar integer. "
                "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
            )
        if value is not None:
            if not isinstance(value, int) or value <= 0:
                raise ValueError(f"grid.{key} must be a positive integer when provided (got {value}).")
            top_level[key] = value
 
    legacy_settings = grid_cfg.get("programmatic_settings")
    if isinstance(legacy_settings, dict):
        for key in GRID_DA_PROCESSOR_KEYS:
            value = legacy_settings.get(key)
            if isinstance(value, (list, tuple)):
                raise ValueError(
                    f"grid.programmatic_settings.{key} must be a scalar integer. "
                    "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
                )
            if value is not None:
                if not isinstance(value, int) or value <= 0:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} must be a positive integer when provided (got {value})."
                    )
                legacy[key] = value
 
    resolved = {}
    for key in GRID_DA_PROCESSOR_KEYS:
        top_value = top_level.get(key)
        legacy_value = legacy.get(key)
        if top_value is not None and legacy_value is not None and top_value != legacy_value:
            raise ValueError(
                f"grid.{key} conflicts with legacy grid.programmatic_settings.{key}; "
                "define the processor layout in only one place."
            )
        if top_value is not None:
            resolved[key] = top_value
        elif legacy_value is not None:
            resolved[key] = legacy_value
 
    return resolved
 
 
def append_grid_da_processor_layout(control_lines: list, grid_cfg: dict, num_procs: int) -> None:
    """!
    @brief Append optional global DMDA layout flags for any grid mode.
    @param[in] control_lines Argument passed to `append_grid_da_processor_layout()`.
    @param[in] grid_cfg Argument passed to `append_grid_da_processor_layout()`.
    @param[in] num_procs Argument passed to `append_grid_da_processor_layout()`.
    """
    layout = resolve_grid_da_processor_layout(grid_cfg)
    if not layout:
        if num_procs > 1:
            print("[INFO] Letting PETSc automatically determine processor layout.")
        return
 
    if num_procs == 1:
        print("[INFO] Serial run, ignoring da_processors layout.")
        return
 
    if all(layout.get(key) is not None for key in GRID_DA_PROCESSOR_KEYS):
        total_layout = 1
        for key in GRID_DA_PROCESSOR_KEYS:
            total_layout *= layout[key]
        if total_layout != num_procs:
            printable = " x ".join(str(layout[key]) for key in GRID_DA_PROCESSOR_KEYS)
            raise ValueError(
                "DMDA processor layout mismatch: "
                f"grid.da_processors_x/y/z is {printable} (product {total_layout}), "
                f"but this run requests {num_procs} MPI processes. "
                "Set da_processors_x/y/z to values whose product equals the requested "
                "MPI process count, or remove all three settings to let PETSc choose "
                "the layout automatically."
            )
        print(f"[INFO] Applying user-defined processor layout for {num_procs} processes.")
    else:
        printable = " x ".join(str(layout.get(key, "PETSC_DECIDE")) for key in GRID_DA_PROCESSOR_KEYS)
        print(f"[INFO] Applying partial processor layout: {printable}.")
 
    for key in GRID_DA_PROCESSOR_KEYS:
        value = layout.get(key)
        if value is not None:
            control_lines.append(f"-{key} {value}")
 
def normalize_momentum_solver_type(value: str) -> str:
    """!
    @brief Maps canonical user-facing momentum solver names to C-enum CLI values.
    @param[in] value Canonical momentum solver string from YAML.
    @return Canonical value accepted by -mom_solver_type.
    @throws ValueError if the input cannot be mapped.
    """
    # Only implemented YAML values belong here. Extend only with matching C enum/parser/dispatch support.
    if value is None:
        raise ValueError("momentum solver type cannot be None")
 
    raw = str(value).strip()
    mapped = {
        "Explicit RK4": "EXPLICIT_RK",
        "Dual Time Picard Jameson RK": "DUALTIME_PICARD_JAMESON_RK",
        "Dual Time Picard RK4": "DUALTIME_PICARD_JAMESON_RK",
        "Newton Krylov": "newton_krylov",
    }.get(raw)
    if mapped is None:
        raise ValueError(
            f"Unknown momentum solver '{value}'. Use one of: "
            "'Explicit RK4', 'Dual Time Picard Jameson RK', 'Newton Krylov'."
        )
    return mapped
 
 
def validate_newton_krylov_config(cfg: dict) -> dict:
    """!
    @brief Validate and normalize the structured Newton--Krylov solver block.
    @param[in] cfg Structured `momentum_solver.newton_krylov` mapping.
    @return Normalized copy containing only supported structured fields.
    """
    root = "momentum_solver.newton_krylov"
    if not isinstance(cfg, dict):
        raise ValueError(f"{root} must be a mapping.")
 
    unknown = sorted(set(cfg) - {
        "jacobian", "preconditioner", "nonlinear_solver", "linear_solver",
    })
    if unknown:
        raise ValueError(f"{root} has unsupported key(s): {unknown}.")
 
    normalized = {}
 
    def _mapping(parent: dict, key: str, path: str) -> dict:
        """!
        @brief Read and validate one optional nested Newton mapping.
        @param[in] parent Parent mapping.
        @param[in] key Nested key to read.
        @param[in] path User-facing YAML path for errors.
        @return Nested mapping, or an empty mapping when omitted.
        """
        value = parent.get(key, {})
        if value is None or not isinstance(value, dict):
            raise ValueError(f"{path} must be a mapping when provided.")
        return value
 
    def _method(value, path: str) -> str:
        """!
        @brief Normalize one nonempty PETSc solver/type token.
        @param[in] value YAML token value.
        @param[in] path User-facing YAML path for errors.
        @return Lowercase PETSc token.
        """
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"{path} must be a non-empty string.")
        return value.strip().lower()
 
    def _tolerance(value, path: str):
        """!
        @brief Validate one finite nonnegative tolerance.
        @param[in] value YAML tolerance value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated value.
        """
        if isinstance(value, bool):
            raise ValueError(f"{path} must be numeric and nonnegative.")
        try:
            numeric = float(value)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{path} must be numeric and nonnegative.") from exc
        if not math.isfinite(numeric) or numeric < 0.0:
            raise ValueError(f"{path} must be numeric and nonnegative.")
        return value
 
    def _positive_integer(value, path: str):
        """!
        @brief Validate one positive integer count.
        @param[in] value YAML count value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated integer.
        """
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(f"{path} must be a positive integer.")
        return value
 
    jacobian_path = f"{root}.jacobian"
    if "jacobian" not in cfg:
        normalized["jacobian"] = {
            "type": "finite_difference",
            "finite_difference": {"mode": "matrix_free"},
        }
    else:
        jacobian = _mapping(cfg, "jacobian", jacobian_path)
        unknown = sorted(set(jacobian) - {"type", "finite_difference"})
        if unknown:
            raise ValueError(f"{jacobian_path} has unsupported key(s): {unknown}.")
        if "type" not in jacobian:
            raise ValueError(f"{jacobian_path}.type is required when {jacobian_path} is provided.")
        jacobian_type = _method(jacobian["type"], f"{jacobian_path}.type")
        if jacobian_type == "frozen_momentum_approximation":
            raise ValueError(
                f"{jacobian_path}.type 'frozen_momentum_approximation' is not implemented."
            )
        if jacobian_type != "finite_difference":
            raise ValueError(
                f"{jacobian_path}.type currently supports only 'finite_difference' "
                f"(got '{jacobian_type}')."
            )
        finite_difference_path = f"{jacobian_path}.finite_difference"
        if "finite_difference" not in jacobian:
            raise ValueError(
                f"{finite_difference_path} is required when {jacobian_path}.type is "
                "'finite_difference'."
            )
        finite_difference = _mapping(
            jacobian, "finite_difference", finite_difference_path
        )
        unknown = sorted(set(finite_difference) - {"mode"})
        if unknown:
            raise ValueError(f"{finite_difference_path} has unsupported key(s): {unknown}.")
        if "mode" not in finite_difference:
            raise ValueError(f"{finite_difference_path}.mode is required.")
        finite_difference_mode = _method(
            finite_difference["mode"], f"{finite_difference_path}.mode"
        )
        if finite_difference_mode == "colored_sparse":
            raise ValueError(
                f"{finite_difference_path}.mode 'colored_sparse' is not implemented."
            )
        if finite_difference_mode != "matrix_free":
            raise ValueError(
                f"{finite_difference_path}.mode currently supports only 'matrix_free' "
                f"(got '{finite_difference_mode}')."
            )
        normalized["jacobian"] = {
            "type": jacobian_type,
            "finite_difference": {"mode": finite_difference_mode},
        }
 
    preconditioner = _mapping(
        cfg, "preconditioner", f"{root}.preconditioner"
    ) if "preconditioner" in cfg else {}
    preconditioner_path = f"{root}.preconditioner"
    unknown = sorted(set(preconditioner) - {"model", "structure"})
    if unknown:
        raise ValueError(f"{preconditioner_path} has unsupported key(s): {unknown}.")
    if "preconditioner" in cfg and "model" not in preconditioner:
        raise ValueError(
            f"{preconditioner_path}.model is required when {preconditioner_path} is provided."
        )
    model = _method(preconditioner.get("model", "none"), f"{preconditioner_path}.model")
    if model not in NEWTON_KRYLOV_PRECONDITIONER_MODELS:
        raise ValueError(
            f"{preconditioner_path}.model supports only 'none' or 'frozen_momentum_jacobian'."
        )
    structure = _mapping(
        preconditioner, "structure", f"{preconditioner_path}.structure"
    ) if "structure" in preconditioner else {}
    unknown = sorted(set(structure) - {"type"})
    if unknown:
        raise ValueError(f"{preconditioner_path}.structure has unsupported key(s): {unknown}.")
    structure_type = _method(
        structure.get("type", "none"), f"{preconditioner_path}.structure.type"
    )
    if structure_type not in NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES:
        raise ValueError(
            f"{preconditioner_path}.structure.type supports only 'none' or 'point_block'."
        )
    if model == "none" and structure:
        raise ValueError(f"{preconditioner_path}.model 'none' does not accept a matrix structure.")
    if model == "frozen_momentum_jacobian" and structure_type != "point_block":
        raise ValueError(
            f"{preconditioner_path}.model 'frozen_momentum_jacobian' requires "
            f"{preconditioner_path}.structure.type 'point_block'."
        )
    normalized["preconditioner"] = {
        "model": model,
        "structure": {"type": structure_type},
    }
 
    nonlinear = _mapping(cfg, "nonlinear_solver", f"{root}.nonlinear_solver")
    nonlinear_path = f"{root}.nonlinear_solver"
    unknown = sorted(set(nonlinear) - {
        "method", "absolute_tolerance", "relative_tolerance", "step_tolerance",
        "max_iterations", "line_search", "eisenstat_walker",
    })
    if unknown:
        raise ValueError(f"{nonlinear_path} has unsupported key(s): {unknown}.")
    nonlinear_out = {}
    if "method" in nonlinear:
        nonlinear_out["method"] = _method(nonlinear["method"], f"{nonlinear_path}.method")
    for key in ("absolute_tolerance", "relative_tolerance", "step_tolerance"):
        if key in nonlinear:
            nonlinear_out[key] = _tolerance(nonlinear[key], f"{nonlinear_path}.{key}")
    if "max_iterations" in nonlinear:
        nonlinear_out["max_iterations"] = _positive_integer(
            nonlinear["max_iterations"], f"{nonlinear_path}.max_iterations"
        )
    if "line_search" in nonlinear:
        line_search = _mapping(nonlinear, "line_search", f"{nonlinear_path}.line_search")
        unknown = sorted(set(line_search) - {"type"})
        if unknown:
            raise ValueError(f"{nonlinear_path}.line_search has unsupported key(s): {unknown}.")
        nonlinear_out["line_search"] = {}
        if "type" in line_search:
            nonlinear_out["line_search"]["type"] = _method(
                line_search["type"], f"{nonlinear_path}.line_search.type"
            )
    if "eisenstat_walker" in nonlinear:
        ew_path = f"{nonlinear_path}.eisenstat_walker"
        ew = _mapping(nonlinear, "eisenstat_walker", ew_path)
        ew_keys = {
            "enabled", "version", "initial_relative_tolerance",
            "maximum_relative_tolerance", "gamma", "exponent",
            "safeguard_exponent", "safeguard_threshold",
        }
        unknown = sorted(set(ew) - ew_keys)
        if unknown:
            raise ValueError(f"{ew_path} has unsupported key(s): {unknown}.")
        enabled = ew.get("enabled", True)
        if not isinstance(enabled, bool):
            raise ValueError(f"{ew_path}.enabled must be boolean.")
        if not enabled and set(ew) - {"enabled"}:
            raise ValueError(f"{ew_path} parameters require enabled: true.")
        ew_out = {"enabled": enabled}
        if "version" in ew:
            version = ew["version"]
            if isinstance(version, bool) or not isinstance(version, int) or version not in {1, 2, 3, 4}:
                raise ValueError(f"{ew_path}.version must be one of 1, 2, 3, or 4.")
            ew_out["version"] = version
        bounds = {
            "initial_relative_tolerance": (0.0, 1.0, False, True),
            "maximum_relative_tolerance": (0.0, 1.0, False, True),
            "gamma": (0.0, 1.0, False, False),
            "exponent": (1.0, 2.0, True, False),
            "safeguard_threshold": (0.0, 1.0, True, True),
        }
        for key, (lower, upper, lower_open, upper_open) in bounds.items():
            if key not in ew:
                continue
            value = _tolerance(ew[key], f"{ew_path}.{key}")
            numeric = float(value)
            valid_lower = numeric > lower if lower_open else numeric >= lower
            valid_upper = numeric < upper if upper_open else numeric <= upper
            if not (valid_lower and valid_upper):
                brackets = ("(" if lower_open else "[") + f"{lower}, {upper}" + (")" if upper_open else "]")
                raise ValueError(f"{ew_path}.{key} must be in {brackets}.")
            ew_out[key] = value
        if "safeguard_exponent" in ew:
            ew_out["safeguard_exponent"] = _tolerance(
                ew["safeguard_exponent"], f"{ew_path}.safeguard_exponent"
            )
        nonlinear_out["eisenstat_walker"] = ew_out
    normalized["nonlinear_solver"] = nonlinear_out
 
    linear = _mapping(cfg, "linear_solver", f"{root}.linear_solver")
    linear_path = f"{root}.linear_solver"
    unknown = sorted(set(linear) - {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations",
        "gmres", "preconditioner",
    })
    if unknown:
        raise ValueError(f"{linear_path} has unsupported key(s): {unknown}.")
    linear_out = {}
    method = "gmres"
    if "method" in linear:
        method = _method(linear["method"], f"{linear_path}.method")
        linear_out["method"] = method
    for key in ("absolute_tolerance", "relative_tolerance"):
        if key in linear:
            linear_out[key] = _tolerance(linear[key], f"{linear_path}.{key}")
    if "max_iterations" in linear:
        linear_out["max_iterations"] = _positive_integer(
            linear["max_iterations"], f"{linear_path}.max_iterations"
        )
    if "gmres" in linear:
        gmres = _mapping(linear, "gmres", f"{linear_path}.gmres")
        unknown = sorted(set(gmres) - {"restart"})
        if unknown:
            raise ValueError(f"{linear_path}.gmres has unsupported key(s): {unknown}.")
        linear_out["gmres"] = {}
        if "restart" in gmres:
            if method not in GMRES_RESTART_METHODS:
                raise ValueError(
                    f"{linear_path}.gmres.restart is valid only when {linear_path}.method "
                    "is one of 'gmres', 'fgmres', or 'lgmres'."
                )
            linear_out["gmres"]["restart"] = _positive_integer(
                gmres["restart"], f"{linear_path}.gmres.restart"
            )
    if "preconditioner" in linear:
        compatibility_pc = _mapping(linear, "preconditioner", f"{linear_path}.preconditioner")
        unknown = sorted(set(compatibility_pc) - {"type"})
        if unknown:
            raise ValueError(f"{linear_path}.preconditioner has unsupported key(s): {unknown}.")
        if "type" in compatibility_pc:
            pc_type = _method(compatibility_pc["type"], f"{linear_path}.preconditioner.type")
            if pc_type != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type is a deprecated compatibility alias "
                    "and supports only 'none'."
                )
            if "preconditioner" in cfg and model != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type 'none' conflicts with "
                    f"{preconditioner_path}.model '{model}'."
                )
            warnings.warn(
                f"{linear_path}.preconditioner.type is deprecated; use "
                f"{preconditioner_path}.model: none.",
                FutureWarning,
                stacklevel=3,
            )
    normalized["linear_solver"] = linear_out
    return normalized
 
def normalize_solution_convergence_mode(value: str) -> str:
    """!
    @brief Normalizes the solution-convergence mode selector to the C-side canonical string.
    @param[in] value Human-readable solution-convergence mode selector.
    @return Canonical string accepted by `-solution_convergence_mode`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("solution_convergence.mode cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "steady_deterministic": "STEADY_DETERMINISTIC",
        "periodic_deterministic": "PERIODIC_DETERMINISTIC",
        "statistical_steady": "STATISTICAL_STEADY",
        "transient": "TRANSIENT",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown solution_convergence.mode '{value}'. Use one of: "
            "'steady_deterministic', 'periodic_deterministic', 'statistical_steady', 'transient'."
        )
    return mapped
 
def normalize_field_init_mode(value: str) -> int:
    """!
    @brief Maps canonical field init mode names to C enum/int codes (-finit).
    @param[in] value Canonical field initialization mode.
    @return Canonical integer code accepted by -finit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for field initialization modes.
    if value is None:
        raise ValueError("field initialization mode cannot be None")
 
    mapped = {
        "Zero": 0,
        "Constant": 1,
        "Poiseuille": 2,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions mode '{value}'. Use one of: 'Zero', 'Constant', 'Poiseuille'."
        )
    return mapped
 
def normalize_initial_condition_field(value: str) -> "tuple[str, int]":
    """!
    @brief Normalize a file IC field selector to its staged basename and C enum value.
    @param[in] value User-facing Ucat or Ucont selector.
    @return Tuple of staged field basename and C enum value.
    """
    normalized = str(value or "").strip().lower()
    if normalized == "ucat":
        return "ufield", 0
    if normalized == "ucont":
        return "vfield", 1
    raise ValueError("initial_conditions.field must be 'Ucat' or 'Ucont'.")
 
GENERATED_IC_PROVIDERS = {
    "ic_gen": {
        "requires_grid": True,
        "diagnostic_artifacts": (),
    },
    "spectral_random_velocity": {
        "requires_grid": True,
        "requires_periodic_geometric": True,
        "requires_fresh_3d": True,
        "diagnostic_artifacts": (
            ("summary_json", os.path.join(CANONICAL_RUN_PATHS["metrics"], "initial_condition_summary.json")),
            ("spectrum_csv", INITIAL_CONDITION_SPECTRUM_RELPATH),
        ),
    },
}
 
 
def is_generated_ic_provider(resolved_ic: dict) -> bool:
    """!
    @brief Return whether a resolved IC is backed by a registered file generator.
    @param[in] resolved_ic Resolved initial-condition contract.
    @return True for a registered generated-file provider.
    """
    return resolved_ic.get("kind") in GENERATED_IC_PROVIDERS
 
 
def resolve_fluid_scaling(case_cfg: dict) -> dict:
    """!
    @brief Resolve the shared physical and nondimensional fluid scaling contract.
    @param[in] case_cfg Parsed case configuration.
    @return Resolved scaling, viscosity, and Reynolds-number quantities.
    """
    properties = case_cfg["properties"]
    scaling = properties["scaling"]
    fluid = properties["fluid"]
    length_ref = _to_finite_float(scaling["length_ref"], "properties.scaling.length_ref")
    velocity_ref = _to_finite_float(scaling["velocity_ref"], "properties.scaling.velocity_ref")
    density = _to_finite_float(fluid["density"], "properties.fluid.density")
    dynamic_viscosity = _to_finite_float(fluid["viscosity"], "properties.fluid.viscosity")
    if length_ref <= 0.0 or velocity_ref <= 0.0 or density <= 0.0 or dynamic_viscosity < 0.0:
        raise ValueError("length_ref, velocity_ref, and density must be positive; viscosity must be non-negative.")
    reynolds = density*velocity_ref*length_ref/dynamic_viscosity if dynamic_viscosity else float("inf")
    return {
        "length_ref": length_ref, "velocity_ref": velocity_ref, "density": density,
        "dynamic_viscosity": dynamic_viscosity, "reynolds": reynolds,
        "physical_kinematic_viscosity": dynamic_viscosity/density,
        "nondimensional_kinematic_viscosity": dynamic_viscosity/(density*velocity_ref*length_ref),
    }
 
 
def resolve_initial_condition_config(ic: dict, prepared_blocks, U_ref: float, provider_context=None) -> dict:
    """!
    @brief Resolve legacy and structured initial-condition YAML into one launcher contract.
    @param[in] ic Initial-condition YAML mapping.
    @param[in] prepared_blocks Normalized boundary-condition blocks.
    @param[in] U_ref Physical reference velocity.
    @param[in] provider_context Optional conductor-derived provider context.
    @return Normalized launcher initial-condition contract.
    """
    if not isinstance(ic, dict):
        raise ValueError("properties.initial_conditions must be a mapping.")
    mode = str(ic.get("mode", "")).strip()
 
    # Backward-compatible legacy spelling.
    if mode in LEGACY_FIELD_INIT_SPELLINGS:
        finit_code = normalize_field_init_mode(mode)
        params = resolve_ic_cli_params(ic, finit_code, prepared_blocks, U_ref)
        if finit_code == 1 and params.pop("ic_coordinate_system", 0) == 1:
            finit_code = 3
        return {"finit": finit_code, "cli_params": params, "kind": "builtin", "label": mode}
 
    normalized_mode = mode.lower().replace("-", "_").replace(" ", "_")
    if normalized_mode == "file":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        source_file = ic.get("source_file")
        if not isinstance(source_file, str) or not source_file.strip():
            raise ValueError("initial_conditions.source_file is required when mode is 'file'.")
        field_name, field_code = normalize_initial_condition_field(ic.get("field"))
        return {
            "finit": 4, "cli_params": {}, "kind": "file", "label": "file",
            "source_file": source_file.strip(), "field_name": field_name, "field_code": field_code,
        }
    if normalized_mode != "generated":
        raise ValueError("initial_conditions.mode must be 'generated' or 'file'.")
 
    generator = str(ic.get("generator", "")).strip().lower().replace("-", "_").replace(" ", "_")
    params = ic.get("params", {})
    if not isinstance(params, dict):
        raise ValueError("initial_conditions.params must be a mapping.")
    if generator == "ic_gen":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        script = params.get("script")
        if script is not None and (not isinstance(script, str) or not script.strip()):
            raise ValueError("initial_conditions.params.script must be a non-empty path when provided.")
        field_name, field_code = normalize_initial_condition_field(params.get("field"))
        config_file = params.get("config_file")
        if not isinstance(config_file, str) or not config_file.strip():
            raise ValueError("initial_conditions.params.config_file is required for generator 'ic_gen'.")
        cli_args = params.get("cli_args", [])
        if cli_args is None:
            cli_args = []
        if not isinstance(cli_args, list):
            raise ValueError("initial_conditions.params.cli_args must be a list.")
        return {
            "finit": 4, "cli_params": {}, "kind": "ic_gen", "label": "ic_gen",
            "field_name": field_name, "field_code": field_code,
            "config_file": config_file.strip(),
            "script": script.strip() if script is not None else None,
            "output_file": params.get("output_file"),
            "cli_args": cli_args,
        }
 
    if generator == "spectral_random_velocity":
        if prepared_blocks and len(prepared_blocks) != 1:
            raise ValueError("spectral_random_velocity requires exactly one grid block.")
        if not prepared_blocks or len(prepared_blocks[0]) != 6 or any(
            bc.get("type") != "PERIODIC" or bc.get("handler") != "geometric"
            for bc in prepared_blocks[0]
        ):
            raise ValueError("spectral_random_velocity requires PERIODIC/geometric boundaries on all six faces.")
        allowed = {"field", "seed", "random", "spectrum", "projection", "normalization", "remove_mean",
                   "output_file", "summary_json", "spectrum_csv"}
        unknown = sorted(set(params) - allowed)
        if unknown:
            raise ValueError(f"spectral_random_velocity has unsupported params: {unknown}.")
        for path_key in ("output_file", "summary_json", "spectrum_csv"):
            value = params.get(path_key)
            if value is not None and (not isinstance(value, str) or not value.strip()):
                raise ValueError(f"spectral_random_velocity params.{path_key} must be a non-empty path when provided.")
        field_name, field_code = normalize_initial_condition_field(params.get("field", "Ucat"))
        if field_code != 0:
            raise ValueError("spectral_random_velocity supports only params.field: Ucat.")
        seed = params.get("seed", 12345)
        if isinstance(seed, bool) or not isinstance(seed, int):
            raise ValueError("spectral_random_velocity params.seed must be an integer.")
        random_cfg = params.get("random", {})
        if not isinstance(random_cfg, dict) or set(random_cfg) - {"distribution", "mean"}:
            raise ValueError("spectral_random_velocity params.random supports only distribution and mean.")
        distribution = str(random_cfg.get("distribution", "gaussian")).lower()
        if distribution != "gaussian":
            raise ValueError("spectral_random_velocity supports only random.distribution: gaussian.")
        mean = random_cfg.get("mean", [0.0, 0.0, 0.0])
        if not isinstance(mean, list) or len(mean) != 3:
            raise ValueError("spectral_random_velocity random.mean must be a three-component list.")
        mean = [_to_finite_float(value, f"initial_conditions.params.random.mean[{index}]")
                for index, value in enumerate(mean)]
        spectrum = params.get("spectrum", {})
        if not isinstance(spectrum, dict):
            raise ValueError("spectral_random_velocity params.spectrum must be a mapping.")
        spectrum_type = str(spectrum.get("type", "white")).lower()
        if spectrum_type == "white":
            if set(spectrum) - {"type"}:
                raise ValueError("white spectrum supports only type.")
            normalized_spectrum = {"type": "white"}
        elif spectrum_type == "k4_exponential":
            if set(spectrum) - {"type", "k0", "k_cut"} or "k0" not in spectrum or "k_cut" not in spectrum:
                raise ValueError("k4_exponential spectrum requires only type, k0, and k_cut.")
            normalized_spectrum = {"type": "k4_exponential",
                                   "k0": _to_finite_float(spectrum["k0"], "initial_conditions.params.spectrum.k0"),
                                   "k_cut": _to_finite_float(spectrum["k_cut"], "initial_conditions.params.spectrum.k_cut")}
        else:
            raise ValueError("spectrum.type must be 'white' or 'k4_exponential'.")
        if any(value <= 0 for key, value in normalized_spectrum.items() if key != "type"):
            raise ValueError("spectrum k0 and k_cut values must be positive.")
        projection = params.get("projection", {"type": "none"})
        if not isinstance(projection, dict) or set(projection) - {"type", "operator"}:
            raise ValueError("projection supports only type and operator.")
        projection_type = str(projection.get("type", "none")).lower()
        if projection_type == "none" and "operator" not in projection:
            normalized_projection = {"type": "none"}
        elif projection_type == "solenoidal" and str(projection.get("operator", "")).lower() in PROJECTION_OPERATORS:
            normalized_projection = {"type": "solenoidal", "operator": str(projection["operator"]).lower()}
        else:
            raise ValueError("projection must be none, or solenoidal with continuum/picurv_discrete operator.")
        normalization = params.get("normalization", {"type": "none"})
        if not isinstance(normalization, dict) or set(normalization) - {"type", "target"}:
            raise ValueError("normalization supports only type and target.")
        normalization_type = str(normalization.get("type", "none")).lower()
        if normalization_type == "none" and "target" not in normalization:
            normalized_normalization = {"type": "none"}
        elif normalization_type == "component_rms" and "target" in normalization:
            target = _to_finite_float(normalization["target"], "initial_conditions.params.normalization.target")
            if target <= 0:
                raise ValueError("component_rms normalization.target must be positive.")
            normalized_normalization = {"type": "component_rms", "target": target}
        else:
            raise ValueError("normalization must be none or component_rms with target.")
        remove_mean = params.get("remove_mean", True)
        if not isinstance(remove_mean, bool):
            raise ValueError("spectral_random_velocity remove_mean must be boolean.")
        context = dict(provider_context or {})
        return {
            "finit": 4, "cli_params": {}, "kind": "spectral_random_velocity", "label": "spectral_random_velocity",
            "field_name": field_name, "field_code": field_code, "provider_context": context,
            "params": {"field": "Ucat", "seed": seed,
                       "random": {"distribution": distribution, "mean": mean},
                       "spectrum": normalized_spectrum, "projection": normalized_projection,
                       "normalization": normalized_normalization, "remove_mean": remove_mean},
            "output_file": params.get("output_file"), "summary_json": params.get("summary_json"),
            "spectrum_csv": params.get("spectrum_csv"),
        }
 
    generator_modes = {
        "zero": (0, "Zero"),
        "constant": (1, "Constant"),
        "streamwise_constant": (3, "Constant"),
        "poiseuille": (2, "Poiseuille"),
    }
    if generator not in generator_modes:
        raise ValueError(
            "initial_conditions.generator must be one of: zero, constant, "
            "streamwise_constant, poiseuille, ic_gen, spectral_random_velocity."
        )
    finit_code, legacy_mode = generator_modes[generator]
    legacy_ic = dict(params)
    legacy_ic["mode"] = legacy_mode
    cli_params = resolve_ic_cli_params(
        legacy_ic,
        1 if finit_code == 3 else finit_code,
        prepared_blocks,
        U_ref,
    )
    cli_params.pop("ic_coordinate_system", None)
    return {"finit": finit_code, "cli_params": cli_params, "kind": "builtin", "label": generator}
 
def validate_petsc_vec_binary(path: str) -> dict:
    """!
    @brief Validate the basic PETSc binary VecView envelope used by ReadFieldData.
    @param[in] path PETSc binary vector path.
    @return Summary containing the absolute path and scalar count.
    """
    import struct
    with open(path, "rb") as fin:
        header = fin.read(8)
        if len(header) != 8:
            raise ValueError(f"PETSc Vec file is too short: {path}")
        class_id, scalar_count = struct.unpack(">ii", header)
        if class_id != 1211214 or scalar_count < 0:
            raise ValueError(f"Invalid PETSc Vec header in {path}.")
        payload = fin.read()
    if len(payload) != scalar_count * 8:
        raise ValueError(
            f"PETSc Vec payload size mismatch in {path}: expected {scalar_count * 8} bytes, found {len(payload)}."
        )
    return {"path": os.path.abspath(path), "scalar_count": scalar_count}
 
def run_initial_spectrum_generator(field_path: str, staged_grid: str,
                                   spectrum_path: str, case_dir: str) -> str:
    """!
    @brief Measure the shell-averaged spectrum of a staged initial condition.
 
    The spectrum has a single implementation in `generators/spectra.gen`, so the
    conductor measures the generated field rather than asking the initial-condition
    generator to report a spectrum it would have to bin itself.
 
    @param[in] field_path    Generated PETSc binary Ucat path.
    @param[in] staged_grid   Staged canonical PICGRID path.
    @param[in] spectrum_path Destination `k,energy` CSV path.
    @param[in] case_dir      Working directory for the subprocess.
    @return Absolute path to the written spectrum CSV.
    @throws ValueError when the generator is missing or fails.
    """
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    cmd = [sys.executable, script, "shell-spectrum",
           "--field-file", field_path, "--source-grid", staged_grid,
           "--spectrum-csv", spectrum_path]
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(
            f"initial-condition spectrum failed with exit code {result.returncode}. Details:\n{details}"
        )
    return os.path.abspath(spectrum_path)
 
 
def run_initial_condition_generator(case_path: str, run_dir: str, resolved_ic: dict) -> str:
    """!
    @brief Run the repository IC generator.
    @param[in] case_path Source case YAML path.
    @param[in] run_dir Run or precompute output directory.
    @param[in] resolved_ic Normalized external-generator contract.
    @return Generated PETSc vector path.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path))
    if resolved_ic["kind"] == "spectral_random_velocity":
        script = os.path.join(GENERATORS_PATH, "ic.gen")
        output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
        os.makedirs(os.path.dirname(output_path), exist_ok=True)
        staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if not os.path.isfile(staged_grid):
            raise ValueError("spectral_random_velocity requires a staged PICGRID at inputs/grid/grid.run.")
        summary_path = os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json")
        spectrum_path = os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH)
        os.makedirs(os.path.dirname(summary_path), exist_ok=True)
        os.makedirs(os.path.dirname(spectrum_path), exist_ok=True)
        cmd = [sys.executable, script, "--generator", "spectral_random_velocity",
               "--grid", staged_grid, "--output", output_path,
               "--params-json", json.dumps(resolved_ic["params"], sort_keys=True),
               "--context-json", json.dumps(resolved_ic.get("provider_context", {}), sort_keys=True),
               "--summary-json", summary_path]
        result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
        if result.returncode != 0:
            details = (result.stderr or result.stdout or "").strip()
            raise ValueError(f"spectral_random_velocity failed with exit code {result.returncode}. Details:\n{details}")
        validate_petsc_vec_binary(output_path)
        run_initial_spectrum_generator(output_path, staged_grid, spectrum_path, case_dir)
        return output_path
    script = _resolve_generator_script(resolved_ic.get("script"), case_path, "ic.gen")
    config_file = resolved_ic["config_file"]
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(script):
        raise ValueError(f"ic.gen script not found: {script}")
    if not os.path.isfile(config_file):
        raise ValueError(f"initial-condition generator config file not found: {config_file}")
    output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    cmd = [sys.executable, script, "-c", config_file, "--field",
           "Ucat" if resolved_ic["field_code"] == 0 else "Ucont",
           "--output", output_path]
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if os.path.isfile(staged_grid):
        cmd.extend(["--grid", staged_grid])
    cmd.extend(str(token) for token in resolved_ic.get("cli_args", []))
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"ic.gen failed with exit code {result.returncode}. Details:\n{details}")
    validate_petsc_vec_binary(output_path)
    return output_path
 
def stage_initial_condition_file(run_dir: str, case_path: str, resolved_ic: dict) -> dict:
    """!
    @brief Materialize and stage one file-backed IC in ReadFieldData's expected layout.
    @param[in] run_dir Run or precompute output directory.
    @param[in] case_path Source case YAML path.
    @param[in] resolved_ic Normalized file-backed IC contract.
    @return Source, staged path, and staging-directory summary.
    """
    stage_dir = os.path.join(run_dir, "inputs", "initial_condition")
    os.makedirs(stage_dir, exist_ok=True)
    staged_path = os.path.join(stage_dir, f"{resolved_ic['field_name']}00000_0.dat")
    if os.path.isfile(staged_path):
        validate_petsc_vec_binary(staged_path)
        summary = {
            "source": os.path.abspath(staged_path),
            "staged": os.path.abspath(staged_path),
            "directory": os.path.abspath(stage_dir),
            "reused": True,
        }
        if resolved_ic["kind"] == "spectral_random_velocity":
            summary["diagnostics"] = [
                os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json"),
                os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH),
            ]
        return summary
    if is_generated_ic_provider(resolved_ic):
        source_path = run_initial_condition_generator(case_path, run_dir, resolved_ic)
    else:
        source_path = _resolve_case_relative_path(
            resolved_ic["source_file"], os.path.dirname(os.path.abspath(case_path))
        )
        if not os.path.isfile(source_path):
            raise ValueError(f"Initial-condition source file not found: {source_path}")
        validate_petsc_vec_binary(source_path)
    if os.path.abspath(source_path) != os.path.abspath(staged_path):
        shutil.copy2(source_path, staged_path)
    summary = {"source": os.path.abspath(source_path), "staged": os.path.abspath(staged_path),
               "directory": os.path.abspath(stage_dir)}
    if resolved_ic["kind"] == "spectral_random_velocity":
        summary["diagnostics"] = [
            os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json"),
            os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH),
        ]
    return summary
 
def normalize_flow_direction_token(value: str) -> int:
    """!
    @brief Maps a face-token flow direction string to the C FlowDirection enum integer.
    @param[in] value One of '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'.
    @return Integer 0-5 matching the FlowDirection enum.
    @throws ValueError on unknown value.
    """
    mapped = {
        "+Xi": 0, "-Xi": 1,
        "+Eta": 2, "-Eta": 3,
        "+Zeta": 4, "-Zeta": 5,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions.flow_direction '{value}'. "
            "Use one of: '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'."
        )
    return mapped
 
def _ic_has_inlet(prepared_blocks) -> bool:
    """!
    @brief Return True if any prepared BC block contains an INLET face.
    @param[in] prepared_blocks List of prepared BC lists (one per domain block).
    @return True if at least one INLET entry exists across all blocks.
    """
    if not prepared_blocks:
        return False
    for block_bcs in prepared_blocks:
        for entry in block_bcs:
            if entry.get("type") == "INLET":
                return True
    return False
 
def resolve_ic_cli_params(ic: dict, finit_code: int, prepared_blocks, U_ref: float) -> dict:
    """!
    @brief Resolve all IC parameters and return a dict of PETSc option values.
    @param[in] ic The properties.initial_conditions mapping.
    @param[in] finit_code Normalized -finit integer code.
    @param[in] prepared_blocks Normalized BC blocks (may be None).
    @param[in] U_ref Reference velocity for non-dimensionalization.
    @return Dict with keys matching PETSc option names (without leading dash).
    @throws KeyError if a required key is absent.
    @throws ValueError on invalid combinations or values.
    """
    result = {}
 
    if finit_code == 0:
        return result
 
    if finit_code == 1:  # Constant
        has_cartesian   = any(k in ic for k in ("u_physical", "v_physical", "w_physical"))
        has_curvilinear = "velocity_physical" in ic
 
        if has_cartesian and has_curvilinear:
            raise ValueError(
                "initial_conditions: cannot mix u/v/w_physical (cartesian) and "
                "velocity_physical (curvilinear) — use one or the other."
            )
 
        if has_curvilinear:  # curvilinear: scalar speed along flow_direction axis
            cs_code = 1
            result["ic_coordinate_system"] = cs_code
            try:
                vel_phys = float(ic["velocity_physical"])
            except (TypeError, ValueError) as exc:
                raise ValueError(
                    f"Invalid value for initial_conditions.velocity_physical: {ic['velocity_physical']!r}. "
                    "Expected a numeric value."
                ) from exc
            result["ic_velocity_physical"] = vel_phys / U_ref if U_ref != 0 else 0.0
 
            if "flow_direction" in ic:
                result["flow_direction"] = normalize_flow_direction_token(ic["flow_direction"])
            elif not _ic_has_inlet(prepared_blocks):
                raise ValueError(
                    "initial_conditions.flow_direction is required for curvilinear Constant IC "
                    "when no INLET face exists."
                )
 
        else:  # cartesian: u/v/w_physical → Cart2Contra (default when no velocity_physical)
            if "flow_direction" in ic:
                raise ValueError(
                    "initial_conditions.flow_direction is not valid for cartesian Constant IC. "
                    "Use velocity_physical + flow_direction for curvilinear mode."
                )
            cs_code = 0
            result["ic_coordinate_system"] = cs_code
            u, v, w = parse_initial_velocity_components(ic, finit_code, require_explicit=True)
            scale = 1.0 / U_ref if U_ref != 0 else 0.0
            result["ucont_x"] = u * scale
            result["ucont_y"] = v * scale
            result["ucont_z"] = w * scale
 
    elif finit_code == 2:  # Poiseuille
        if any(k in ic for k in ("u_physical", "v_physical", "w_physical")):
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not u_physical/v_physical/w_physical."
            )
        if "velocity_physical" in ic:
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not velocity_physical."
            )
        if "peak_velocity_physical" not in ic:
            raise KeyError("peak_velocity_physical")
        try:
            peak = float(ic["peak_velocity_physical"])
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for initial_conditions.peak_velocity_physical: "
                f"{ic['peak_velocity_physical']!r}. Expected a numeric value."
            ) from exc
        result["ic_velocity_physical"] = peak / U_ref if U_ref != 0 else 0.0
 
        if "flow_direction" in ic:
            fd_int = normalize_flow_direction_token(ic["flow_direction"])
            # Cross-check: explicit flow_direction must align with INLET face if one exists
            if _ic_has_inlet(prepared_blocks):
                inlet_axis = infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks)
                fd_axis_name = {0: "x", 1: "y", 2: "z"}.get(fd_int // 2, "?")
                if inlet_axis and fd_axis_name != inlet_axis:
                    token = ic["flow_direction"]
                    raise ValueError(
                        f"initial_conditions.flow_direction '{token}' (axis '{fd_axis_name}') "
                        f"does not match INLET face axis '{inlet_axis}'."
                    )
            result["flow_direction"] = fd_int
        elif not _ic_has_inlet(prepared_blocks):
            raise ValueError(
                "initial_conditions.flow_direction is required for Poiseuille IC "
                "when no INLET face exists."
            )
 
    return result
 
def normalize_eulerian_field_source(value: str) -> str:
    """!
    @brief Normalizes the Eulerian field source selector to the C-side canonical string.
    @param[in] value Human-readable or enum-like Eulerian field source.
    @return Canonical string accepted by `-euler_field_source`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("eulerian_field_source cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "solve": "solve",
        "load": "load",
        "analytical": "analytical",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown operation_mode.eulerian_field_source '{value}'. "
            "Use one of: 'solve', 'load', 'analytical'."
        )
    return mapped
 
def normalize_analytical_type(value: str) -> str:
    """!
    @brief Normalizes the analytical solution selector to the C-side canonical string.
    @param[in] value Human-readable analytical solution selector.
    @return Canonical string accepted by `-analytical_type`.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for analytical solution selectors.
    if value is None:
        raise ValueError("analytical_type cannot be None")
 
    normalized = str(value).strip().upper().replace("-", "_").replace(" ", "_")
    if normalized not in ANALYTICAL_SOLUTION_TYPES:
        raise ValueError(
            f"Unknown operation_mode.analytical_type '{value}'. "
            "Use one of: 'TGV3D', 'ZERO_FLOW', 'UNIFORM_FLOW'."
        )
    return normalized
 
def parse_initial_velocity_components(initial_conditions: dict, finit_code: int, *, require_explicit: bool) -> "tuple[float, float, float]":
    """!
    @brief Parse initial-condition velocity components with mode-aware defaults.
    @param[in] initial_conditions The `properties.initial_conditions` mapping from case.yml.
    @param[in] finit_code Normalized `-finit` integer code.
    @param[in] require_explicit If True, all three component keys must be present.
    @return Tuple `(u, v, w)` in physical units.
    @throws KeyError if a required component key is missing.
    @throws ValueError if a component cannot be converted to float.
    """
    component_keys = ("u_physical", "v_physical", "w_physical")
    components = []
    for key in component_keys:
        if key not in initial_conditions:
            if require_explicit:
                raise KeyError(key)
            raw_value = 0.0
        else:
            raw_value = initial_conditions[key]
        try:
            components.append(float(raw_value))
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for properties.initial_conditions.{key}: {raw_value!r}. Expected a numeric value."
            ) from exc
    return tuple(components)
 
def infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks: list) -> "str | None":
    """!
    @brief Infer the unique inlet axis across all blocks using C-side "primary inlet" ordering.
    @param[in] prepared_blocks Normalized BC blocks from `validate_and_prepare_boundary_conditions`.
    @return One of `"x"`, `"y"`, `"z"` if unique, `None` if no inlet exists.
    @throws ValueError if different blocks imply different inlet axes.
    """
    face_order = ("-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta")
    face_axis = {
        "-Xi": "x", "+Xi": "x",
        "-Eta": "y", "+Eta": "y",
        "-Zeta": "z", "+Zeta": "z",
    }
 
    inlet_axes = set()
    for block_bcs in prepared_blocks:
        face_map = {entry["face"]: entry for entry in block_bcs}
        for face in face_order:
            entry = face_map.get(face)
            if entry and entry["type"] == "INLET":
                inlet_axes.add(face_axis[face])
                break
 
    if not inlet_axes:
        return None
    if len(inlet_axes) != 1:
        raise ValueError(
            "properties.initial_conditions.peak_velocity_physical requires all blocks to have a primary INLET "
            f"on the same axis. Found axes: {sorted(inlet_axes)}. Use u_physical/v_physical/w_physical instead."
        )
    return next(iter(inlet_axes))
 
def normalize_particle_init_mode(value: str) -> int:
    """!
    @brief Maps canonical particle init mode names to C enum/int codes (-pinit).
    @param[in] value Canonical particle initialization mode.
    @return Canonical integer code accepted by -pinit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for particle initialization modes.
    if value is None:
        raise ValueError("particle init mode cannot be None")
 
    mapped = {
        "Surface": 0,
        "Volume": 1,
        "PointSource": 2,
        "SurfaceEdges": 3,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown particle init_mode '{value}'. Use one of: "
            "'Surface', 'Volume', 'PointSource', 'SurfaceEdges'."
        )
    return mapped
 
def normalize_interpolation_method(value: str) -> int:
    """!
    @brief Maps interpolation method names to C enum/int codes (-interpolation_method).
    @param[in] value Canonical interpolation method name.
    @return Integer code accepted by -interpolation_method.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("interpolation method cannot be None")
 
    mapped = {
        "Trilinear": 0,
        "CornerAveraged": 1,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown interpolation_method '{value}'. Use one of: "
            "'Trilinear', 'CornerAveraged'."
        )
    return mapped
 
def normalize_les_model(value) -> int:
    """!
    @brief Maps LES model selectors to C enum/int codes (-les).
    @param[in] value LES selector name or legacy integer/bool value.
    @return Integer code accepted by -les.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        return 1 if value else 0
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les must be 0, 1, 2, false/true, or a supported model block.")
    if value is None:
        raise ValueError("LES model cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "none": 0,
        "off": 0,
        "disabled": 0,
        "no_les": 0,
        "constant": 1,
        "constant_smagorinsky": 1,
        "smagorinsky": 1,
        "dynamic": 2,
        "dynamic_smagorinsky": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES model '{value}'. Use one of: 'none', "
            "'constant_smagorinsky', 'dynamic_smagorinsky'."
        )
    return mapped
 
def normalize_les_test_filter(value) -> int:
    """!
    @brief Maps LES test-filter kernel names to the C -les_test_filter_kernel flag.
    @param[in] value Test-filter selector name or integer code.
    @return 0 for the volume-weighted box filter, 1 for the i/k Simpson filter.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must name a filter, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1):
            return value
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must be 0, 1, or a supported filter name.")
    if value is None:
        raise ValueError("LES test_filter.kernel cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "volume_weighted_box": 0,
        "box": 0,
        "simpson_ik": 1,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES test filter kernel '{value}'. Use one of: "
            "'volume_weighted_box', 'simpson_ik'."
        )
    return mapped
 
def normalize_les_filter_width(value) -> int:
    """!
    @brief Maps LES grid-filter-width model names to the C -les_filter_width flag.
    @param[in] value Filter-width model name or integer code.
    @return 0 for cube-root volume, 1 for the geometric mean of the cell extents,
            2 for the longest cell extent.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.filter_width must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.filter_width must be 0, 1, 2, or a supported model name.")
    if value is None:
        raise ValueError("LES filter_width cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "cube_root_volume": 0,
        "geometric_mean": 1,
        "max_edge": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES filter width model '{value}'. Use one of: "
            "'cube_root_volume', 'geometric_mean', 'max_edge'."
        )
    return mapped
 
def normalize_les_averaging_mode(value) -> int:
    """!
    @brief Maps LES coefficient-averaging mode names to the C -les_averaging_mode flag.
    @param[in] value Averaging mode name or integer code.
    @return 0 for pointwise local averaging, 1 for homogeneous directions, 2 for the
            whole block.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.averaging.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.averaging.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES averaging.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "local": 0,
        "homogeneous": 1,
        "global": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES averaging mode '{value}'. Use one of: "
            "'local', 'homogeneous', 'global'."
        )
    return mapped
 
def normalize_les_clip_mode(value) -> int:
    """!
    @brief Maps LES coefficient-limiting mode names to the C -les_clip_mode flag.
    @param[in] value Clipping mode name or integer code.
    @return 0 to clamp into [0, max_cs^2], 1 to discard negatives only, 2 to keep the
            signed coefficient so backscatter survives.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.clipping.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.clipping.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES clipping.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "clamp": 0,
        "clip_negative": 1,
        "none": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES clipping mode '{value}'. Use one of: "
            "'clamp', 'clip_negative', 'none'."
        )
    return mapped
 
#: The logical grid directions an LES averaging set may span, in canonical order.
LES_AVERAGING_DIRECTION_AXES = ("i", "j", "k")
 
def normalize_les_averaging_directions(value) -> str:
    """!
    @brief Maps a list of homogeneous logical directions to the C flag's string form.
    @param[in] value List or string naming a subset of the i, j, and k directions.
    @return The selected directions as a canonically ordered subset of "ijk".
    @throws ValueError if a direction is unknown or repeated.
    """
    if value is None:
        return ""
    if isinstance(value, str):
        tokens = [token for token in value.strip().lower()]
    elif isinstance(value, (list, tuple)):
        tokens = [str(token).strip().lower() for token in value]
    else:
        raise ValueError(
            "models.physics.turbulence.les.averaging.directions must be a list such as [i, k]."
        )
 
    selected = []
    for token in tokens:
        if token not in LES_AVERAGING_DIRECTION_AXES:
            raise ValueError(
                f"Unknown LES averaging direction '{token}'. Use a subset of ['i', 'j', 'k']."
            )
        if token in selected:
            raise ValueError(
                f"LES averaging direction '{token}' is repeated; list each direction once."
            )
        selected.append(token)
    return "".join(axis for axis in LES_AVERAGING_DIRECTION_AXES if axis in selected)
 
def normalize_rans_model(value) -> int:
    """!
    @brief Maps RANS model selectors to the current C -rans switch.
    @param[in] value RANS selector name or legacy integer/bool value.
    @return Integer code accepted by -rans.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        return 1 if value else 0
    if isinstance(value, int):
        if value in (0, 1):
            return value
        raise ValueError("models.physics.turbulence.rans must be 0, 1, false/true, or a supported model block.")
    if value is None:
        raise ValueError("RANS model cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "none": 0,
        "off": 0,
        "disabled": 0,
        "k_omega": 1,
        "komega": 1,
    }.get(key)
    if mapped is None:
        raise ValueError(f"Unknown RANS model '{value}'. Use one of: 'none', 'k_omega'.")
    return mapped
 
def normalize_wall_function_model(value) -> int:
    """!
    @brief Maps wall-function model selectors to the C -wallfunction flag.
    @param[in] value Wall-function selector name, or None for the default.
    @return Integer code accepted by -wallfunction; 1 log law, 2 Werner-Wengle, 3 Cabot.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        return 1
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.wall_function.model must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (1, 2, 3):
            return value
        raise ValueError("models.physics.turbulence.wall_function.model must be 1, 2, 3, or a supported model name.")
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "log_law": 1,
        "loglaw": 1,
        "werner": 2,
        "werner_wengle": 2,
        "cabot": 3,
    }.get(key)
    if mapped is None:
        raise ValueError(
            "Unknown wall_function model '%s'. Use one of: 'log_law', 'werner', 'cabot'." % value)
    return mapped
 
def resolve_enabled_flag(cfg: dict, path: str, default: bool = True) -> bool:
    """!
    @brief Resolves a structured `enabled` flag and rejects non-boolean values.
    @param[in] cfg Mapping that may contain `enabled`.
    @param[in] path Human-readable config path for diagnostics.
    @param[in] default Value used when `enabled` is omitted.
    @return Boolean enabled state.
    @throws ValueError if `enabled` is not a YAML boolean.
    """
    if 'enabled' not in cfg:
        return default
    if not isinstance(cfg['enabled'], bool):
        raise ValueError(f"{path}.enabled must be true or false.")
    return cfg['enabled']
 
def append_les_parameter_flags(les_cfg: dict, control_lines: list):
    """!
    @brief Appends the LES closure parameter flags from a structured les block.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    @throws ValueError if a selector name or nested block shape is unsupported.
    """
    if 'constant_cs' in les_cfg:
        control_lines.append(f"-les_constant_cs {format_flag_value(les_cfg['constant_cs'])}")
    if 'dynamic_frequency' in les_cfg:
        control_lines.append(f"-les_dynamic_frequency {format_flag_value(les_cfg['dynamic_frequency'])}")
    if 'filter_width' in les_cfg:
        control_lines.append(f"-les_filter_width {normalize_les_filter_width(les_cfg['filter_width'])}")
 
    # A bare string is accepted as shorthand for naming only the kernel, matching the
    # way the les block itself accepts either a scalar or a mapping.
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            control_lines.append(
                f"-les_test_filter_kernel {normalize_les_test_filter(test_filter['kernel'])}")
        if 'width_ratio' in test_filter:
            control_lines.append(
                f"-les_test_filter_width_ratio {format_flag_value(test_filter['width_ratio'])}")
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        if 'mode' in averaging:
            control_lines.append(
                f"-les_averaging_mode {normalize_les_averaging_mode(averaging['mode'])}")
        if 'directions' in averaging:
            directions = normalize_les_averaging_directions(averaging['directions'])
            if directions:
                control_lines.append(f"-les_averaging_directions {directions}")
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        if 'mode' in clipping:
            control_lines.append(f"-les_clip_mode {normalize_les_clip_mode(clipping['mode'])}")
        if 'max_cs' in clipping:
            control_lines.append(f"-les_clip_max_cs {format_flag_value(clipping['max_cs'])}")
        if 'min_viscosity_ratio' in clipping:
            control_lines.append(
                f"-les_min_viscosity_ratio {format_flag_value(clipping['min_viscosity_ratio'])}")
 
    gradient_model = les_cfg.get('gradient_model')
    if gradient_model is not None:
        if not isinstance(gradient_model, dict):
            gradient_model = {'enabled': gradient_model}
        enabled = resolve_enabled_flag(gradient_model,
                                       "models.physics.turbulence.les.gradient_model")
        control_lines.append(f"-les_gradient_model {1 if enabled else 0}")
 
    diagnostics = les_cfg.get('diagnostics')
    if diagnostics is not None:
        if not isinstance(diagnostics, dict):
            diagnostics = {'enabled': diagnostics}
        enabled = resolve_enabled_flag(diagnostics, "models.physics.turbulence.les.diagnostics")
        control_lines.append(f"-les_diagnostics {'true' if enabled else 'false'}")
        if 'cadence' in diagnostics:
            control_lines.append(
                f"-les_diagnostics_cadence {format_flag_value(diagnostics['cadence'])}")
        if 'yoshizawa_ci' in diagnostics:
            control_lines.append(
                f"-les_yoshizawa_ci {format_flag_value(diagnostics['yoshizawa_ci'])}")
 
def append_turbulence_flags(models: dict, control_lines: list):
    """!
    @brief Appends turbulence model flags from legacy or structured case.yml blocks.
    @param[in] models Parsed case.yml `models` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    turbulence_cfg = models.get('physics', {}).get('turbulence', {})
    if not turbulence_cfg:
        return
    if not isinstance(turbulence_cfg, dict):
        raise ValueError("models.physics.turbulence must be a mapping.")
 
    les_cfg = turbulence_cfg.get('les')
    rans_cfg = turbulence_cfg.get('rans')
    wall_cfg = turbulence_cfg.get('wall_function')
    les_code = None
    rans_code = None
 
    if isinstance(les_cfg, dict):
        enabled = resolve_enabled_flag(les_cfg, "models.physics.turbulence.les")
        model_value = les_cfg.get('model', 'constant_smagorinsky')
        les_code = normalize_les_model(model_value) if enabled else 0
        control_lines.append(f"-les {les_code}")
        append_les_parameter_flags(les_cfg, control_lines)
    elif les_cfg is not None:
        les_code = normalize_les_model(les_cfg)
        control_lines.append(f"-les {les_code}")
 
    if isinstance(rans_cfg, dict):
        enabled = resolve_enabled_flag(rans_cfg, "models.physics.turbulence.rans")
        model_value = rans_cfg.get('model', 'k_omega')
        rans_code = normalize_rans_model(model_value) if enabled else 0
        control_lines.append(f"-rans {rans_code}")
    elif rans_cfg is not None:
        rans_code = normalize_rans_model(rans_cfg)
        control_lines.append(f"-rans {rans_code}")
 
    if les_code and rans_code:
        raise ValueError("models.physics.turbulence cannot enable both LES and RANS in the same case.")
 
    if isinstance(wall_cfg, dict):
        enabled = resolve_enabled_flag(wall_cfg, "models.physics.turbulence.wall_function")
        # The flag carries the model, with zero meaning disabled, so a selector change
        # reaches the runtime instead of being validated and dropped.
        wall_model = normalize_wall_function_model(wall_cfg.get('model'))
        control_lines.append(f"-wallfunction {wall_model if enabled else 0}")
        if 'roughness_height' in wall_cfg:
            control_lines.append(f"-wall_roughness {format_flag_value(wall_cfg['roughness_height'])}")
    elif wall_cfg is not None:
        control_lines.append(f"-wallfunction {format_flag_value(wall_cfg)}")
 
def control_value(value, context: str):
    """!
    @brief Guard a value that is written verbatim into the generated control file.
 
    @details PETSc reads the control file line by line, so a value containing a newline
             writes additional option lines - which defeats every key-based check by
             smuggling a whole new flag. Rejecting the value is the only safe handling;
             there is no quoting that makes a multi-line option meaningful.
    @param[in] value Configured value destined for a control line.
    @param[in] context YAML path, for the error message.
    @return The value unchanged when it is safe to emit.
    @throws SystemExit when the value would inject an option line.
    """
    text = str(value)
    if any(character in text for character in ("\n", "\r")):
        print(
            f"[FATAL] {context} contains a newline. Values written to the generated control "
            f"file must occupy a single line; a multi-line value would inject additional "
            f"PETSc options.",
            file=sys.stderr,
        )
        sys.exit(1)
    return value
 
 
def append_passthrough_flags(control_lines: list, options: dict):
    """!
    @brief Appends raw CLI flags to the control list from a {flag: value} dict.
    @details Boolean `true` is emitted as a switch with no value. Boolean `false`
             is skipped. All other values are emitted as "<flag> <value>".
    @param[out] control_lines The destination list of control-file lines.
    @param[in] options Mapping of raw CLI flags to values.
    """
    if not options:
        return
    for flag, value in options.items():
        if isinstance(flag, str) and flag.strip() in RESERVED_DIRECTORY_FLAGS:
            # Defense in depth: validation rejects these, but the emitter must never
            # write a run-directory flag from an unvalidated passthrough surface.
            raise ValueError(
                f"Refusing to emit reserved directory flag '{flag.strip()}' from passthrough "
                "options; run directories are fixed by the workspace contract."
            )
        if isinstance(value, bool):
            if value:
                control_lines.append(str(flag))
            continue
        control_lines.append(
            f"{flag} {control_value(format_flag_value(value), f'passthrough option {flag}')}"
        )
 
 
SOLVER_MONITORING_POISSON_FLAG_MAP = {
    "pic_true_residual": "-ps_ksp_pic_monitor_true_residual",
    "true_residual": "-ps_ksp_monitor_true_residual",
    "converged_reason": "-ps_ksp_converged_reason",
    "view": "-ps_ksp_view",
}
 
SOLVER_MONITORING_MOMENTUM_FLAG_MAP = {
    "newton_krylov_history": "-mom_nk_pic_monitor",
    "snes_monitor": "-mom_nk_snes_monitor",
    "snes_converged_reason": "-mom_nk_snes_converged_reason",
    "ksp_monitor": "-mom_nk_ksp_monitor",
    "ksp_converged_reason": "-mom_nk_ksp_converged_reason",
}
 
 
def resolve_solver_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve human-readable solver monitoring YAML to raw control flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of raw C/PETSc flags to values.
    """
    solver_mon_cfg = monitor_cfg.get("solver_monitoring", {}) if isinstance(monitor_cfg, dict) else {}
    if solver_mon_cfg is None:
        return {}
    if not isinstance(solver_mon_cfg, dict):
        raise ValueError("monitor.solver_monitoring must be a mapping when provided.")
 
    flags = {}
 
    momentum_cfg = solver_mon_cfg.get("momentum", {})
    if momentum_cfg is None:
        momentum_cfg = {}
    if not isinstance(momentum_cfg, dict):
        raise ValueError("monitor.solver_monitoring.momentum must be a mapping when provided.")
    unknown_momentum = sorted(set(momentum_cfg.keys()) - set(SOLVER_MONITORING_MOMENTUM_FLAG_MAP.keys()))
    if unknown_momentum:
        raise ValueError(f"monitor.solver_monitoring.momentum has unsupported key(s): {unknown_momentum}.")
    for key, flag in SOLVER_MONITORING_MOMENTUM_FLAG_MAP.items():
        if key in momentum_cfg:
            value = momentum_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.momentum.{key} must be boolean.")
            flags[flag] = value
 
    poisson_cfg = solver_mon_cfg.get("poisson", {})
    if poisson_cfg is None:
        poisson_cfg = {}
    if not isinstance(poisson_cfg, dict):
        raise ValueError("monitor.solver_monitoring.poisson must be a mapping when provided.")
    unknown_poisson = sorted(set(poisson_cfg.keys()) - set(SOLVER_MONITORING_POISSON_FLAG_MAP.keys()))
    if unknown_poisson:
        raise ValueError(f"monitor.solver_monitoring.poisson has unsupported key(s): {unknown_poisson}.")
    for key, flag in SOLVER_MONITORING_POISSON_FLAG_MAP.items():
        if key in poisson_cfg:
            value = poisson_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.poisson.{key} must be boolean.")
            flags[flag] = value
 
    passthrough = solver_mon_cfg.get("petsc_passthrough_options", {})
    if passthrough is None:
        passthrough = {}
    if not isinstance(passthrough, dict):
        raise ValueError("monitor.solver_monitoring.petsc_passthrough_options must be a mapping when provided.")
    flags.update(passthrough)
 
    legacy_raw = {
        key: value
        for key, value in solver_mon_cfg.items()
        if isinstance(key, str) and key.startswith("-")
    }
    flags.update(legacy_raw)
 
    unknown_top = sorted(
        key
        for key in solver_mon_cfg.keys()
        if key not in {"momentum", "poisson", "petsc_passthrough_options"} and not (isinstance(key, str) and key.startswith("-"))
    )
    if unknown_top:
        raise ValueError(
            "monitor.solver_monitoring has unsupported key(s): "
            f"{unknown_top}. Use 'momentum'/'poisson' for structured monitors or "
            "'petsc_passthrough_options' for raw PETSc flags."
        )
 
    return flags
 
 
def resolve_particle_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Return the effective particle-console snapshot cadence from monitor.yml.
    @param[in] io_cfg Argument passed to `resolve_particle_console_output_frequency()`.
    @return Value returned by `resolve_particle_console_output_frequency()`.
    """
    if 'particle_console_output_frequency' in io_cfg:
        return io_cfg['particle_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 
def parse_and_add_model_flags(case_cfg: dict, control_lines: list):
    """!
    @brief Parses the 'models' section of case.yml and adds corresponding C-solver flags.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    models = case_cfg.get('models', {})
    FLAG_MAP = {
        'domain': {'blocks': '-nblk'},
        'physics.fsi': {'immersed': '-imm', 'moving_fsi': '-fsi'},
        'physics.particles': {'count': '-numParticles'},
    }
    for section_path, flags in FLAG_MAP.items():
        current_level = models
        try:
            for key in section_path.split('.'): current_level = current_level[key]
            for yaml_key, flag in flags.items():
                if yaml_key in current_level:
                    control_lines.append(f"{flag} {format_flag_value(current_level[yaml_key])}")
        except KeyError: continue
 
    append_turbulence_flags(models, control_lines)
 
    if models.get('physics', {}).get('dimensionality') == '2D':
        control_lines.append("-TwoD 1")
    
    particles_cfg = models.get('physics', {}).get('particles', {})
    p_init_mode_str = particles_cfg.get('init_mode', 'Surface')
    pinit_code = normalize_particle_init_mode(p_init_mode_str)
    control_lines.append(f"-pinit {pinit_code}")
    print(f"  - Particle Initialization Mode: {p_init_mode_str} (Code: {pinit_code})")
 
    if pinit_code == 2:
        point_cfg = particles_cfg.get('point_source', {})
        if not isinstance(point_cfg, dict):
            raise ValueError("models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
        try:
            psrc_x = float(point_cfg['x'])
            psrc_y = float(point_cfg['y'])
            psrc_z = float(point_cfg['z'])
        except (KeyError, TypeError, ValueError):
            raise ValueError("PointSource init_mode requires numeric point_source.{x,y,z} values.")
        control_lines.append(f"-psrc_x {psrc_x}")
        control_lines.append(f"-psrc_y {psrc_y}")
        control_lines.append(f"-psrc_z {psrc_z}")
        print(f"  - Particle Point Source: ({psrc_x}, {psrc_y}, {psrc_z})")
 
    p_restart_mode = particles_cfg.get('restart_mode')
    if p_restart_mode:
        p_restart_mode_normalized = str(p_restart_mode).lower()
        if p_restart_mode_normalized not in PARTICLE_RESTART_MODES:
            raise ValueError(f"Unknown particle restart_mode '{p_restart_mode}'. Options are 'init' or 'load'.")
        control_lines.append(f"-particle_restart_mode \"{p_restart_mode}\"")
 
# PETSc KSP types whose iteration adapts to the input vector. Any of these used as
# the multigrid coarse solve (level_0) makes the MG preconditioner a nonlinear
# operator; see docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.
KRYLOV_KSP_TYPES = {
    "gmres", "fgmres", "lgmres", "dgmres", "pgmres", "gcr",
    "cg", "cgne", "cgs", "bcgs", "ibcgs", "fbcgs", "fbcgsr", "bcgsl",
    "tfqmr", "tcqmr", "minres", "symmlq", "cr", "lsqr", "pipecg", "pipefgmres",
}
 
def parse_solver_config(solver_cfg: dict) -> dict:
    """!
    @brief Parses the structured solver.yml into a flat dictionary of {flag: value}.
    @param[in] solver_cfg The parsed solver.yml configuration dictionary.
    @return A dictionary where keys are C-solver flags and values are the corresponding settings.
    """
    flags = {}
    if 'operation_mode' in solver_cfg and isinstance(solver_cfg['operation_mode'], dict):
        op_mode = solver_cfg['operation_mode']
        if 'eulerian_field_source' in op_mode:
            normalized_source = normalize_eulerian_field_source(op_mode.get('eulerian_field_source'))
            flags['-euler_field_source'] = f"\"{normalized_source}\""
        if 'analytical_type' in op_mode and op_mode.get('analytical_type') is not None:
            normalized_analytical_type = normalize_analytical_type(op_mode.get('analytical_type'))
            flags['-analytical_type'] = f"\"{normalized_analytical_type}\""
            if normalized_analytical_type == "UNIFORM_FLOW":
                uniform_flow_cfg = op_mode.get('uniform_flow', {})
                if not isinstance(uniform_flow_cfg, dict):
                    raise ValueError("operation_mode.uniform_flow must be a mapping when analytical_type is 'UNIFORM_FLOW'.")
                try:
                    flags['-analytical_uniform_u'] = float(uniform_flow_cfg['u'])
                    flags['-analytical_uniform_v'] = float(uniform_flow_cfg['v'])
                    flags['-analytical_uniform_w'] = float(uniform_flow_cfg['w'])
                except KeyError as exc:
                    raise ValueError(f"operation_mode.uniform_flow.{exc.args[0]} is required when analytical_type is 'UNIFORM_FLOW'.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError("operation_mode.uniform_flow.{u,v,w} must be numeric when analytical_type is 'UNIFORM_FLOW'.") from exc
 
    verification_cfg = solver_cfg.get('verification', {})
    if verification_cfg:
        if not isinstance(verification_cfg, dict):
            raise ValueError("verification must be a mapping when provided.")
        sources_cfg = verification_cfg.get('sources', {})
        if not isinstance(sources_cfg, dict):
            raise ValueError("verification.sources must be a mapping when provided.")
        diff_cfg = sources_cfg.get('diffusivity')
        if diff_cfg is not None:
            if not isinstance(diff_cfg, dict):
                raise ValueError("verification.sources.diffusivity must be a mapping.")
            try:
                flags['-verification_diffusivity_mode'] = f"\"{str(diff_cfg['mode']).strip().lower()}\""
                flags['-verification_diffusivity_profile'] = f"\"{str(diff_cfg['profile']).strip().upper()}\""
                flags['-verification_diffusivity_gamma0'] = float(diff_cfg['gamma0'])
                flags['-verification_diffusivity_slope_x'] = float(diff_cfg['slope_x'])
            except KeyError as exc:
                raise ValueError(f"verification.sources.diffusivity.{exc.args[0]} is required.") from exc
            except (TypeError, ValueError) as exc:
                raise ValueError("verification.sources.diffusivity.{gamma0,slope_x} must be numeric and mode/profile must be scalar strings.") from exc
 
        scalar_cfg = sources_cfg.get('scalar')
        if scalar_cfg is not None:
            if not isinstance(scalar_cfg, dict):
                raise ValueError("verification.sources.scalar must be a mapping.")
            try:
                flags['-verification_scalar_mode'] = f"\"{str(scalar_cfg['mode']).strip().lower()}\""
                flags['-verification_scalar_profile'] = f"\"{str(scalar_cfg['profile']).strip().upper()}\""
            except KeyError as exc:
                raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
 
            scalar_numeric_keys = {
                'CONSTANT': ('value',),
                'LINEAR_X': ('phi0', 'slope_x'),
                'SIN_PRODUCT': ('amplitude', 'kx', 'ky', 'kz'),
            }
            profile = str(scalar_cfg.get('profile', '')).strip().upper()
            for key in scalar_numeric_keys.get(profile, ()):
                try:
                    flags[f'-verification_scalar_{key}'] = float(scalar_cfg[key])
                except KeyError as exc:
                    raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError(f"verification.sources.scalar.{key} must be numeric.") from exc
 
    transport_cfg = solver_cfg.get('scalar_transport', {})
    if transport_cfg:
        if not isinstance(transport_cfg, dict):
            raise ValueError("scalar_transport must be a mapping when provided.")
        transport_map = {
            'schmidt_number': '-schmidt_number',
            'turbulent_schmidt_number': '-turb_schmidt_number',
        }
        unknown_transport_keys = sorted(set(transport_cfg.keys()) - set(transport_map.keys()))
        if unknown_transport_keys:
            raise ValueError(
                f"scalar_transport has unsupported key(s): {unknown_transport_keys}. "
                "Use 'schmidt_number' or 'turbulent_schmidt_number'."
            )
        for key, flag in transport_map.items():
            if key in transport_cfg:
                try:
                    value = float(transport_cfg[key])
                except (TypeError, ValueError) as exc:
                    raise ValueError(f"scalar_transport.{key} must be numeric.") from exc
                if value <= 0.0:
                    raise ValueError(f"scalar_transport.{key} must be positive.")
                flags[flag] = value
 
    selected_solver = None
    if 'strategy' in solver_cfg:
        s = solver_cfg['strategy']
        if 'central_diff' in s:
            flags['-central'] = format_flag_value(s['central_diff'])
        # Preferred selector.
        if 'momentum_solver' in s:
            selected_solver = normalize_momentum_solver_type(s['momentum_solver'])
        elif 'implicit' in s:
            raise ValueError("Legacy key 'strategy.implicit' is not supported. Use 'strategy.momentum_solver'.")
 
    def _warn_inactive_absolute_tol(cfg: dict, where: str):
        """!
        @brief Warn when absolute_tol is set but cannot affect convergence.
 
        absolute_tol bounds the velocity update. Since |dU| ~ dtau*|R|, bounding it
        absolutely is a disguised, step-size-dependent residual bound, so it takes no
        part once a residual tolerance is active -- which is now the default. Setting it
        therefore has no effect, and silently ineffective knobs are what this warning
        exists to prevent. See docs/pages/24_Dual_Time_Picard_Jameson_RK.md.
        @param[in] cfg Tolerance mapping to inspect for `absolute_tol` and the residual keys.
        @param[in] where Config path used to locate the offending key in the warning text.
        @return None; emits a warning on stderr when `absolute_tol` cannot take effect.
        """
        if 'absolute_tol' not in cfg:
            return
        # Residual convergence is enabled unless BOTH residual tolerances are explicitly
        # non-positive; their defaults (1e-8 / 1e-3) are positive.
        def _off(key):
            """!
            @brief Report whether a residual tolerance is explicitly disabled.
            @param[in] key Residual tolerance key to inspect.
            @return True when the key is present and non-positive.
            """
            v = cfg.get(key, None)
            try:
                return v is not None and float(v) <= 0.0
            except (TypeError, ValueError):
                return False
        if _off('residual_absolute_tol') and _off('residual_relative_tol'):
            return
        print(
            f"[WARNING] {where}.absolute_tol is set but takes no part in convergence while a "
            "residual tolerance is active (the default). It is retained only for the legacy "
            "update-only branch, which can converge falsely when dtau collapses. To control "
            "accuracy use residual_relative_tol / residual_absolute_tol. See "
            "docs/pages/24_Dual_Time_Picard_Jameson_RK.md.",
            file=sys.stderr,
        )
 
    ms = solver_cfg.get('momentum_solver', {})
    if selected_solver is None:
        selected_solver = "DUALTIME_PICARD_JAMESON_RK"
    flags['-mom_solver_type'] = f"\"{selected_solver}\""
 
    if 'tolerances' in solver_cfg:
        t = solver_cfg['tolerances']
        tol_map = {
            'max_iterations': '-mom_max_pseudo_steps',
            'absolute_tol': '-mom_atol',
            'relative_tol': '-mom_rtol',
            'residual_absolute_tol': '-mom_resid_atol',
            'residual_relative_tol': '-mom_resid_rtol',
            'step_tol': '-imp_stol'
        }
        for key, flag in tol_map.items():
            if key in t:
                flags[flag] = t[key]
        _warn_inactive_absolute_tol(t, "tolerances")
 
    def _append_dualtime_options(cfg: dict):
        """!
        @brief Append dualtime options.
        @param[in] cfg Argument passed to `_append_dualtime_options()`.
        """
        if 'max_pseudo_steps' in cfg:
            flags['-mom_max_pseudo_steps'] = cfg['max_pseudo_steps']
        if 'absolute_tol' in cfg:
            flags['-mom_atol'] = cfg['absolute_tol']
            _warn_inactive_absolute_tol(
                {**solver_cfg.get('tolerances', {}), **cfg},
                "momentum_solver.dual_time_picard_jameson_rk")
        if 'relative_tol' in cfg:
            flags['-mom_rtol'] = cfg['relative_tol']
        if 'step_tol' in cfg:
            flags['-imp_stol'] = cfg['step_tol']
        if 'pseudo_cfl' in cfg:
            pcfl = cfg['pseudo_cfl']
            if 'initial' in pcfl:
                flags['-pseudo_cfl'] = pcfl['initial']
            if 'minimum' in pcfl:
                flags['-min_pseudo_cfl'] = pcfl['minimum']
            if 'maximum' in pcfl:
                flags['-max_pseudo_cfl'] = pcfl['maximum']
            if 'growth_factor' in pcfl:
                flags['-pseudo_cfl_growth_factor'] = pcfl['growth_factor']
            if 'reduction_factor' in pcfl:
                flags['-pseudo_cfl_reduction_factor'] = pcfl['reduction_factor']
        if 'jameson_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['jameson_residual_noise_allowance_factor']
        elif 'rk4_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['rk4_residual_noise_allowance_factor']
        if 'ratio_ema_alpha' in cfg:
            flags['-mom_ratio_ema_alpha'] = cfg['ratio_ema_alpha']
 
    def _append_newton_krylov_options(cfg: dict):
        """!
        @brief Append validated structured Newton--Krylov PETSc options.
        @param[in] cfg Structured Newton--Krylov mapping.
        """
        cfg = validate_newton_krylov_config(cfg)
        jacobian = cfg["jacobian"]
        flags["-mom_nk_jacobian_type"] = jacobian["type"]
        flags["-mom_nk_jacobian_fd_mode"] = jacobian["finite_difference"]["mode"]
        preconditioner = cfg["preconditioner"]
        flags["-mom_nk_preconditioner_model"] = preconditioner["model"]
        flags["-mom_nk_preconditioner_structure"] = preconditioner["structure"]["type"]
        nonlinear = cfg["nonlinear_solver"]
        nonlinear_map = {
            "method": "-mom_nk_snes_type",
            "absolute_tolerance": "-mom_nk_snes_atol",
            "relative_tolerance": "-mom_nk_snes_rtol",
            "step_tolerance": "-mom_nk_snes_stol",
            "max_iterations": "-mom_nk_snes_max_it",
        }
        for key, flag in nonlinear_map.items():
            if key in nonlinear:
                flags[flag] = nonlinear[key]
        line_search = nonlinear.get("line_search", {})
        if "type" in line_search:
            flags["-mom_nk_snes_linesearch_type"] = line_search["type"]
        ew = nonlinear.get("eisenstat_walker")
        if ew:
            flags["-mom_nk_snes_ksp_ew"] = ew["enabled"]
            if ew["enabled"]:
                ew_map = {
                    "version": "-mom_nk_snes_ksp_ew_version",
                    "initial_relative_tolerance": "-mom_nk_snes_ksp_ew_rtol0",
                    "maximum_relative_tolerance": "-mom_nk_snes_ksp_ew_rtolmax",
                    "gamma": "-mom_nk_snes_ksp_ew_gamma",
                    "exponent": "-mom_nk_snes_ksp_ew_alpha",
                    "safeguard_exponent": "-mom_nk_snes_ksp_ew_alpha2",
                    "safeguard_threshold": "-mom_nk_snes_ksp_ew_threshold",
                }
                for key, flag in ew_map.items():
                    if key in ew:
                        flags[flag] = ew[key]
 
        linear = cfg["linear_solver"]
        linear_map = {
            "method": "-mom_nk_ksp_type",
            "absolute_tolerance": "-mom_nk_ksp_atol",
            "relative_tolerance": "-mom_nk_ksp_rtol",
            "max_iterations": "-mom_nk_ksp_max_it",
        }
        for key, flag in linear_map.items():
            if key in linear:
                flags[flag] = linear[key]
        gmres = linear.get("gmres", {})
        if "restart" in gmres:
            flags["-mom_nk_ksp_gmres_restart"] = gmres["restart"]
 
    if isinstance(ms, dict):
        allowed_ms_keys = {'type', 'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
        unknown_ms_keys = sorted(set(ms.keys()) - allowed_ms_keys)
        if unknown_ms_keys:
            raise ValueError(
                f"Unsupported momentum_solver keys/blocks: {unknown_ms_keys}. "
                "Currently supported blocks: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
            )
 
        if 'dual_time_picard_jameson_rk' in ms and 'dual_time_picard_rk4' in ms:
            raise ValueError(
                "Use only momentum_solver.dual_time_picard_jameson_rk; "
                "do not also set its deprecated dual_time_picard_rk4 alias."
            )
        dt_picard_cfg = ms.get('dual_time_picard_jameson_rk', ms.get('dual_time_picard_rk4'))
        if dt_picard_cfg is not None:
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK":
                raise ValueError(
                    f"momentum_solver.dual_time_picard_jameson_rk is set but selected solver is {selected_solver}."
                )
            if not isinstance(dt_picard_cfg, dict):
                raise ValueError("momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
            if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                    'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                raise ValueError(
                    "Use only jameson_residual_noise_allowance_factor; "
                    "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                )
            _append_dualtime_options(dt_picard_cfg)
        newton_cfg = ms.get('newton_krylov')
        if newton_cfg is not None:
            if selected_solver != "newton_krylov":
                raise ValueError(
                    f"momentum_solver.newton_krylov is set but selected solver is {selected_solver}."
                )
            _append_newton_krylov_options(newton_cfg)
    def _normalize_poisson_method(value) -> str:
        """!
        @brief Normalize a user-facing Poisson linear-solver method name.
        @param[in] value Method value from the solver YAML.
        @return Lowercase PETSc KSP method token.
        """
        method = str(value).strip().lower()
        if not method:
            raise ValueError("poisson_solver.method cannot be empty.")
        return method
 
    def _normalize_poisson_preconditioner(value) -> str:
        """!
        @brief Normalize and validate the outer Poisson preconditioner name.
        @param[in] value Preconditioner value from the solver YAML.
        @return PETSc PC token for the supported outer preconditioner.
        """
        pc = str(value).strip().lower()
        pc = POISSON_PRECONDITIONER_SPELLINGS.get(pc, pc)
        if pc not in POISSON_PRECONDITIONER_TYPES:
            raise ValueError(
                "poisson_solver.preconditioner.type currently supports only 'multigrid'. "
                "The runtime Poisson solver still assumes PETSc PCMG setup."
            )
        return "mg"
 
    def _warn_if_krylov_coarse_solver(ksp_type, source_key: str):
        """!
        @brief Warn when the coarsest multigrid level is given a Krylov solver.
        @param[in] ksp_type PETSc KSP token configured for `level_0`.
        @param[in] source_key Name of the source YAML block, used in the message.
        @details level_0 is the coarse solve at the base of the V-cycle, not a
                 smoother. A Krylov method there makes the multigrid
                 preconditioner a nonlinear operator, which decouples the outer
                 KSP's tracked residual from the true residual b-Ax. This stays a
                 warning rather than an error because it remains legitimate at
                 large scale when tolerances are set against the true residual.
        """
        if str(ksp_type).strip().lower() not in KRYLOV_KSP_TYPES:
            return
        print(
            f"[WARNING] {source_key}.multigrid.level_solvers.level_0.method = '{ksp_type}' "
            "is a Krylov method. level_0 is the multigrid COARSE SOLVE, not a smoother, "
            "so a Krylov method there makes the preconditioner nonlinear and the outer "
            "KSP's tracked residual can stop matching the true residual b-Ax. "
            "Prefer {method: preonly, preconditioner: redundant}. If this is deliberate, "
            "enable solver_monitoring.poisson.pic_true_residual and set tolerances against "
            "the true residual. See docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.",
            file=sys.stderr,
        )
 
    def _poisson_level_number(level_name) -> int:
        """!
        @brief Extract the numeric suffix from a `level_N` multigrid level key.
        @param[in] level_name YAML level key supplied by the user.
        @return Numeric level suffix.
        """
        text = str(level_name).strip()
        match = re.fullmatch(r"level_(\d+)", text)
        if not match:
            raise ValueError(f"Invalid Poisson multigrid level name '{level_name}'. Expected 'level_N'.")
        return int(match.group(1))
 
    def _append_poisson_solver_flags(ps: dict, source_key: str):
        """!
        @brief Append structured Poisson solver options to the flat PETSc flag map.
        @param[in] ps The `poisson_solver` or legacy `pressure_solver` mapping.
        @param[in] source_key Name of the source YAML block, used in error messages.
        """
        if not isinstance(ps, dict):
            raise ValueError(f"{source_key} must be a mapping when provided.")
 
        method = None
        if 'method' in ps:
            method = _normalize_poisson_method(ps['method'])
            flags['-ps_ksp_type'] = method
        if 'absolute_tolerance' in ps:
            flags['-ps_ksp_atol'] = ps['absolute_tolerance']
            flags['-poisson_tol'] = ps['absolute_tolerance']
        if 'relative_tolerance' in ps:
            flags['-ps_ksp_rtol'] = ps['relative_tolerance']
        if 'max_iterations' in ps:
            flags['-ps_ksp_max_it'] = ps['max_iterations']
        if 'tolerance' in ps:
            flags['-poisson_tol'] = ps['tolerance']
 
        gmres_cfg = ps.get('gmres', {})
        if gmres_cfg is not None:
            if not isinstance(gmres_cfg, dict):
                raise ValueError(f"{source_key}.gmres must be a mapping when provided.")
            if 'restart' in gmres_cfg:
                if method is None:
                    method = _normalize_poisson_method(ps.get('method', 'fgmres'))
                    flags.setdefault('-ps_ksp_type', method)
                if method not in GMRES_RESTART_METHODS:
                    raise ValueError(
                        f"{source_key}.gmres.restart is valid only when {source_key}.method "
                        "is one of 'gmres', 'fgmres', or 'lgmres'."
                    )
                flags['-ps_ksp_gmres_restart'] = gmres_cfg['restart']
 
        preconditioner_cfg = ps.get('preconditioner', {})
        if preconditioner_cfg:
            if not isinstance(preconditioner_cfg, dict):
                raise ValueError(f"{source_key}.preconditioner must be a mapping when provided.")
            if 'type' in preconditioner_cfg:
                flags['-ps_pc_type'] = _normalize_poisson_preconditioner(preconditioner_cfg['type'])
 
        if 'multigrid' in ps:
            mg = ps['multigrid']
            if not isinstance(mg, dict):
                raise ValueError(f"{source_key}.multigrid must be a mapping when provided.")
            mg_map = {'levels': '-mg_level', 'pre_sweeps': '-mg_pre_it', 'post_sweeps': '-mg_post_it'}
            for key, flag in mg_map.items():
                if key in mg: flags[flag] = mg[key]
            if 'cycle' in mg:
                cycle = str(mg['cycle']).strip().lower()
                if cycle not in {"v"}:
                    raise ValueError(f"{source_key}.multigrid.cycle currently supports only 'v'.")
            if 'mode' in mg:
                mode = str(mg['mode']).strip().lower()
                if mode not in {"multiplicative"}:
                    raise ValueError(f"{source_key}.multigrid.mode currently supports only 'multiplicative'.")
            if 'semi_coarsening' in mg:
                sc = mg['semi_coarsening']
                if not isinstance(sc, dict):
                    raise ValueError(f"{source_key}.multigrid.semi_coarsening must be a mapping when provided.")
                if 'i' in sc: flags['-mg_i_semi'] = format_flag_value(sc['i'])
                if 'j' in sc: flags['-mg_j_semi'] = format_flag_value(sc['j'])
                if 'k' in sc: flags['-mg_k_semi'] = format_flag_value(sc['k'])
            if 'level_solvers' in mg:
                level_solvers = mg['level_solvers']
                if not isinstance(level_solvers, dict):
                    raise ValueError(f"{source_key}.multigrid.level_solvers must be a mapping when provided.")
                for level_name, settings in level_solvers.items():
                    if not isinstance(settings, dict):
                        raise ValueError(f"{source_key}.multigrid.level_solvers.{level_name} must be a mapping.")
                    level_num = _poisson_level_number(level_name)
                    for key, value in settings.items():
                        mapped_key = {'method': 'ksp_type', 'preconditioner': 'pc_type'}.get(key, key)
                        # PETSc names the coarsest solver separately from positive levels.
                        if level_num == 0:
                            prefix = "-ps_mg_coarse_"
                            if mapped_key == 'ksp_type':
                                _warn_if_krylov_coarse_solver(value, source_key)
                        else:
                            prefix = f"-ps_mg_levels_{level_num}_"
                        flags[f"{prefix}{mapped_key}"] = format_flag_value(value)
 
    if 'poisson_solver' in solver_cfg and 'pressure_solver' in solver_cfg:
        if solver_cfg['poisson_solver'] != solver_cfg['pressure_solver']:
            raise ValueError(
                "Both 'poisson_solver' and legacy 'pressure_solver' are present with different values. "
                "Use 'poisson_solver' only, or make the legacy alias identical."
            )
    poisson_cfg = solver_cfg.get('poisson_solver', solver_cfg.get('pressure_solver'))
    if poisson_cfg is not None:
        source_key = 'poisson_solver' if 'poisson_solver' in solver_cfg else 'pressure_solver'
        _append_poisson_solver_flags(poisson_cfg, source_key)
    interp_cfg = solver_cfg.get('interpolation', {})
    if isinstance(interp_cfg, dict):
        interp_method_str = interp_cfg.get('method', 'Trilinear')
    else:
        interp_method_str = 'Trilinear'
    interp_code = normalize_interpolation_method(interp_method_str)
    flags['-interpolation_method'] = interp_code
    print(f"  - Interpolation Method: {interp_method_str} (Code: {interp_code})")
 
    if 'petsc_passthrough_options' in solver_cfg:
        passthrough = solver_cfg['petsc_passthrough_options']
        if passthrough is None:
            passthrough = {}
        if not isinstance(passthrough, dict):
            raise ValueError("petsc_passthrough_options must be a mapping when provided.")
        if passthrough:
            for key, value in passthrough.items():
                if str(key).strip() == "-ps_mg_coarse_ksp_type":
                    _warn_if_krylov_coarse_solver(value, "petsc_passthrough_options")
                flags[key] = value if isinstance(value, bool) else format_flag_value(value)
    summary_bits = []
    if '-ps_ksp_type' in flags:
        summary_bits.append(f"method={flags['-ps_ksp_type']}")
    if '-ps_ksp_atol' in flags:
        summary_bits.append(f"atol={flags['-ps_ksp_atol']}")
    if '-ps_ksp_rtol' in flags:
        summary_bits.append(f"rtol={flags['-ps_ksp_rtol']}")
    if '-ps_ksp_max_it' in flags:
        summary_bits.append(f"max_it={flags['-ps_ksp_max_it']}")
    if '-mg_level' in flags:
        summary_bits.append(f"mg_levels={flags['-mg_level']}")
    if summary_bits:
        print(f"  - Poisson Solver: {', '.join(summary_bits)}")
    if selected_solver == "DUALTIME_PICARD_JAMESON_RK":
        dualtime_bits = []
        for label, flag in (
            ("initial_pseudo_cfl", "-pseudo_cfl"),
            ("pseudo_cfl_range", None),
            ("max_pseudo_steps", "-mom_max_pseudo_steps"),
        ):
            if flag and flag in flags:
                dualtime_bits.append(f"{label}={flags[flag]}")
            elif label == "pseudo_cfl_range" and "-min_pseudo_cfl" in flags and "-max_pseudo_cfl" in flags:
                dualtime_bits.append(f"pseudo_cfl_range=[{flags['-min_pseudo_cfl']}, {flags['-max_pseudo_cfl']}]")
        print("  - Momentum Solver: Dual Time Picard Jameson RK" +
              (f" ({', '.join(dualtime_bits)})" if dualtime_bits else ""))
    elif selected_solver == "newton_krylov":
        newton_bits = []
        for label, flag in (
            ("jacobian", "-mom_nk_jacobian_type"),
            ("nonlinear", "-mom_nk_snes_type"),
            ("linear", "-mom_nk_ksp_type"),
            ("preconditioner", "-mom_nk_preconditioner_model"),
        ):
            if flag in flags:
                newton_bits.append(f"{label}={flags[flag]}")
        print("  - Momentum Solver: Newton Krylov" +
              (f" ({', '.join(newton_bits)})" if newton_bits else " (PETSc defaults)"))
    else:
        print("  - Momentum Solver: Explicit RK (no pseudo-time controller)")
    return flags
 
def generate_solver_control_file(run_dir, run_id, configs, num_procs, monitor_files,
                                 restart_source_dir=None, continue_mode=False,
                                 config_dir: str = None):
    """!
    @brief Generates the main .control file for the C-solver.
    @details Orchestrates the conversion of all YAML configurations (case, solver, monitor)
    into a single, machine-readable file of command-line flags.
    @param[in] run_dir Argument passed to `generate_solver_control_file()`.
    @param[in] run_id Argument passed to `generate_solver_control_file()`.
    @param[in] configs Argument passed to `generate_solver_control_file()`.
    @param[in] num_procs Argument passed to `generate_solver_control_file()`.
    @param[in] monitor_files Argument passed to `generate_solver_control_file()`.
    @param[in] restart_source_dir Argument passed to `generate_solver_control_file()`.
    @param[in] continue_mode If True, appends -continue_mode flag for the C solver.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `generate_solver_control_file()`.
    """
    print("[INFO] Generating master solver control file...")
    case_cfg, solver_cfg, monitor_cfg = configs['case'], configs['solver'], configs['monitor']
    source_files = {'Case': configs['case_path'], 'Solver': configs['solver_path'], 'Monitor': configs['monitor_path']}
    
    control_lines = []
    try:
        props, run_ctrl = case_cfg['properties'], case_cfg['run_control']
        scales, fluid, ic = props['scaling'], props['fluid'], props['initial_conditions']
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        L_ref = fluid_scaling["length_ref"]
        U_ref = fluid_scaling["velocity_ref"]
        rho = fluid_scaling["density"]
        reynolds = fluid_scaling["reynolds"]
        dt_phys = float(run_ctrl['dt_physical'])
        T_ref = L_ref / U_ref if U_ref != 0 else float('inf')
        dt_nondim = dt_phys / T_ref if T_ref != float('inf') else 0.0
        print(f"  - Reynolds Number (Re) = {reynolds:.4f}")
        print(f"  - Non-Dimensional dt*  = {dt_nondim:.6f}")
        eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
        start_step = int(run_ctrl.get("start_step", 0) or 0)
        ic_is_authoritative = eulerian_source == "solve" and start_step == 0
        ic_cli = []
        if ic_is_authoritative:
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, U_ref,
                provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
            )
            finit_mode_str = resolved_ic["label"]
            finit_code = resolved_ic["finit"]
            ic_params = resolved_ic["cli_params"]
            print(f"  - Initial Condition: {finit_mode_str} (Code: {finit_code})")
            if "ucont_x" in ic_params:
                ic_cli.extend([
                    f"-ucont_x {ic_params['ucont_x']}",
                    f"-ucont_y {ic_params['ucont_y']}",
                    f"-ucont_z {ic_params['ucont_z']}",
                ])
            if "ic_velocity_physical" in ic_params:
                ic_cli.append(f"-ic_velocity_physical {ic_params['ic_velocity_physical']}")
            if "flow_direction" in ic_params:
                ic_cli.append(f"-flow_direction {ic_params['flow_direction']}")
        else:
            print(
                f"[WARN] Ignoring configured initial condition because "
                f"eulerian_field_source={eulerian_source!r} and start_step={start_step} select another source.",
                file=sys.stderr,
            )
            finit_code = 0
            resolved_ic = None
        control_lines.extend([
            f"-start_step {run_ctrl['start_step']}", f"-totalsteps {run_ctrl['total_steps']}",
            f"-ren {reynolds}", f"-dt {dt_nondim}", f"-finit {finit_code}",
            *ic_cli,
            f"-scaling_L_ref {L_ref}", f"-scaling_U_ref {U_ref}", f"-scaling_rho_ref {rho}"
        ])
    except (KeyError, TypeError, ZeroDivisionError, ValueError) as e:
        print(f"[FATAL] Error processing case.yml: {e}", file=sys.stderr)
        sys.exit(1)
        
    # --- CORRECTED: Add paths for whitelist and profile files ---
    if monitor_files.get("whitelist"):
        control_lines.append(f"-whitelist_config_file {monitor_files['whitelist']}")
    if monitor_files.get("profile"):
        control_lines.append(f"-profile_config_file {monitor_files['profile']}")
    append_passthrough_flags(control_lines, resolve_solution_monitoring_flags(monitor_cfg))
    control_lines.extend(resolve_field_statistics_flags(monitor_cfg, case_cfg))
    profiling_cfg = monitor_files.get("profiling", {})
    control_lines.append(f"-profiling_timestep_mode {profiling_cfg.get('mode', 'off')}")
    if profiling_cfg.get("mode") != "off":
        control_lines.append(f"-profiling_timestep_file {profiling_cfg.get('timestep_file', 'Profiling_Timestep_Summary.csv')}")
    control_lines.append(f"-profiling_final_summary {str(bool(profiling_cfg.get('final_summary_enabled', True))).lower()}")
    diagnostics_cfg = resolve_diagnostics_config(monitor_cfg)
    memory_log_cfg = diagnostics_cfg["runtime_memory_log"]
    control_lines.append(f"-runtime_memory_log_enabled {str(bool(memory_log_cfg.get('enabled', True))).lower()}")
    control_lines.append(f"-runtime_memory_log_file {memory_log_cfg.get('file', 'Runtime_Memory.log')}")
 
    walltime_guard_policy = configs.get("walltime_guard_policy")
    if walltime_guard_policy is not None:
        control_lines.extend(
            [
                f"-walltime_guard_enabled {str(bool(walltime_guard_policy.get('enabled', False))).lower()}",
                f"-walltime_guard_warmup_steps {int(walltime_guard_policy.get('warmup_steps', DEFAULT_WALLTIME_GUARD_POLICY['warmup_steps']))}",
                f"-walltime_guard_multiplier {float(walltime_guard_policy.get('multiplier', DEFAULT_WALLTIME_GUARD_POLICY['multiplier']))}",
                f"-walltime_guard_min_seconds {float(walltime_guard_policy.get('min_seconds', DEFAULT_WALLTIME_GUARD_POLICY['min_seconds']))}",
                f"-walltime_guard_estimator_alpha {float(walltime_guard_policy.get('estimator_alpha', DEFAULT_WALLTIME_GUARD_POLICY['estimator_alpha']))}",
            ]
        )
    
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    expected_nblk = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
 
    if grid_mode == 'file':
        print("[INFO] Grid Mode: Using external file...")
        case_file_dir = os.path.dirname(configs['case_path'])
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            source_grid = _resolve_case_relative_path(grid_cfg['source_file'], case_file_dir)
            grid_for_validation = source_grid
            try:
                summary = validate_and_nondimensionalize_picgrid(
                    grid_for_validation, nondim_grid_path, L_ref, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] Validated and non-dimensionalized grid: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Failed to process grid file '{source_grid}': {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'grid_gen':
        print("[INFO] Grid Mode: Generating external grid via grid.gen...")
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            try:
                # grid.gen already converts ncells_* inputs into node-count PICGRID dims.
                generated_grid = run_grid_generator(
                    configs['case_path'], run_dir, grid_cfg, case_cfg=case_cfg)
                summary = validate_and_nondimensionalize_picgrid(
                    generated_grid, nondim_grid_path, L_ref, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] grid.gen output validated and non-dimensionalized: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Grid generation failed: {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'programmatic_c':
        print("[INFO] Grid Mode: Programmatic C...")
        grid_settings = translate_programmatic_grid_settings(grid_cfg.get('programmatic_settings', {}))
        control_lines.append("-grid")
        for p_key in GRID_DA_PROCESSOR_KEYS:
            grid_settings.pop(p_key, None)
        for key, value in grid_settings.items(): control_lines.append(f"-{key} {format_flag_value(value)}")
        if resolved_ic and is_generated_ic_provider(resolved_ic) and ic_is_authoritative:
            # The simulator builds this grid itself and never reads a file for it; this
            # bridge exists only so the Python IC generator (a separate process) can see
            # the same node coordinates. generate_picgrid_from_programmatic_settings uses
            # the identical formula as ComputeStretchedCoord in src/grid.c, so the two are
            # guaranteed to agree. Nothing above is changed: -grid_file is never emitted,
            # so the solver still builds its own grid exactly as before.
            nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
            if not os.path.isfile(nondim_grid_path):
                try:
                    generate_picgrid_from_programmatic_settings(
                        grid_cfg.get('programmatic_settings', {}), nondim_grid_path, L_ref
                    )
                    print(
                        "[SUCCESS] Materialized a bridge grid for the Python initial-condition "
                        f"provider: {os.path.relpath(nondim_grid_path)}"
                    )
                except Exception as e:
                    print(f"[FATAL] Failed to materialize bridge grid for initial-condition generator: {e}",
                          file=sys.stderr)
                    sys.exit(1)
    else:
        raise ValueError(f"Unknown or missing grid mode '{grid_mode}' in case.yml.")
 
    if resolved_ic and (resolved_ic["kind"] == "file" or is_generated_ic_provider(resolved_ic)):
        try:
            staged_ic = stage_initial_condition_file(run_dir, configs["case_path"], resolved_ic)
        except Exception as e:
            print(f"[FATAL] Failed to stage initial condition: {e}", file=sys.stderr)
            sys.exit(1)
        control_lines.extend([
            f"-ic_field {resolved_ic['field_code']}",
            f"-ic_dir {staged_ic['directory']}",
        ])
        print(f"  - Staged initial condition: {os.path.relpath(staged_ic['staged'])}")
 
    try:
        bcs_files = generate_multi_block_bcs(
            run_dir, run_id, case_cfg, source_files, config_dir=config_dir
        )
    except ValueError as e:
        print(f"[FATAL] Invalid boundary_conditions in case.yml: {e}", file=sys.stderr)
        sys.exit(1)
    control_lines.append(f"-bcs_files \"{','.join(bcs_files)}\"")
 
    append_grid_da_processor_layout(control_lines, grid_cfg, num_procs)
    
    parse_and_add_model_flags(case_cfg, control_lines)
    
    if 'solver_parameters' in case_cfg:
        params = case_cfg['solver_parameters']
        if params:
            for key, value in params.items():
                control_lines.append(f"{key} {format_flag_value(value)}")
 
    try:
        solver_flags = parse_solver_config(solver_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid solver.yml settings: {e}", file=sys.stderr)
        sys.exit(1)
    append_passthrough_flags(control_lines, solver_flags)
 
    try:
        solver_monitoring_flags = resolve_solver_monitoring_flags(monitor_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid monitor.yml solver_monitoring settings: {e}", file=sys.stderr)
        sys.exit(1)
    append_passthrough_flags(control_lines, solver_monitoring_flags)
    
    io_cfg = monitor_cfg.get('io', {})
    particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
    if 'data_output_frequency' in io_cfg: control_lines.append(f"-tio {io_cfg['data_output_frequency']}")
    if particle_console_output_freq is not None:
        control_lines.append(f"-particle_console_output_freq {particle_console_output_freq}")
    statistics_console_output_freq = resolve_statistics_console_output_frequency(io_cfg)
    if statistics_console_output_freq is not None:
        control_lines.append(f"-statistics_console_output_freq {statistics_console_output_freq}")
    if 'particle_log_interval' in io_cfg: control_lines.append(f"-logfreq {io_cfg['particle_log_interval']}")
    if restart_source_dir:
        expected_restart = os.path.abspath(
            os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"])
        )
        if os.path.abspath(restart_source_dir) != expected_restart:
            raise ValueError(
                "Restart data was not materialized in the canonical run input: "
                f"expected {expected_restart}, got {restart_source_dir}."
            )
    if continue_mode:
        control_lines.append("-continue_mode true")
    elif str(configs.get("statistics_state", "reset")).lower() == "carry":
        control_lines.append("-field_statistics_continue true")
 
    # Emitted last, and always: PETSc takes the final occurrence of an option, so a
    # validated directory written here wins over anything earlier in the file. Writing
    # them unconditionally also removes the "omitted default" gap, where an absent flag
    # let an environment variable or PETSc configuration choose the directory instead.
    control_lines.append("")
    control_lines.append("# Canonical run-owned directories are fixed by the workspace contract.")
    control_lines.append(f"-output_dir {CANONICAL_RUN_PATHS['output']}")
    control_lines.append(f"-restart_dir {CANONICAL_RUN_PATHS['restart']}")
    control_lines.append(f"-log_dir {CANONICAL_RUN_PATHS['logs']}")
    control_lines.append(f"-analysis_dir {CANONICAL_RUN_PATHS['metrics']}")
 
    final_content = generate_header(run_id, source_files) + "\n".join(control_lines)
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    control_file_path = os.path.join(config_dir, f"{run_id}.control")
    with open(control_file_path, "w") as f: f.write(final_content)
    print(f"[SUCCESS] Generated solver control file: {os.path.relpath(control_file_path)}")
    return os.path.abspath(control_file_path)
 
def generate_post_recipe_file(run_dir: str, run_id: str, post_cfg: dict, source_files: dict, monitor_cfg=None) -> str:
    """!
    @brief Generates a key=value config file (post.run) for the C post-processor.
    @details Translates the structured post-processing YAML into the specific flat
             key-value format required by the C executable, including complex,
             semicolon-separated pipeline strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] post_cfg The parsed post-profile YAML configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return The absolute path to the generated post.run recipe file.
    """
    print("[INFO] Generating post-processor recipe file (post.run)...")
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    config_dir = get_post_recipe_root(run_dir, post_cfg)
    os.makedirs(config_dir, exist_ok=True)
    post_recipe_path = os.path.join(config_dir, "post.run")
 
    lines = [generate_header(run_id, source_files)]
    c_config = build_post_recipe_config(post_cfg, monitor_cfg)
 
    for key, value in c_config.items():
        if value is not None and str(value) != "":
            lines.append(f"{key} = {value}")
 
    with open(post_recipe_path, "w") as f:
        f.write("\n".join(lines))
    print(f"[SUCCESS] Generated post-processor recipe: {os.path.relpath(post_recipe_path)}")
    return os.path.abspath(post_recipe_path)
 
def execute_command(command: list, run_dir: str, log_filename: str, monitor_cfg: dict = None):
    """!
    @brief Executes a command, streaming its output to the console and a log file.
    @details ...
    If None, the process inherits the parent's environment directly.
    @param[in] command Argument passed to `execute_command()`.
    @param[in] run_dir Argument passed to `execute_command()`.
    @param[in] log_filename Argument passed to `execute_command()`.
    @param[in] monitor_cfg Argument passed to `execute_command()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print(f"[INFO] Launching Command...\n  > {format_command_for_display(command)}")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    # --- Environment Handling ---
    popen_kwargs = {
        "stdout": subprocess.PIPE, "stderr": subprocess.STDOUT,
        "cwd": run_dir, "bufsize": 1, "universal_newlines": True,
        "encoding": 'utf-8', "errors": 'replace'
    }
 
    if monitor_cfg:
        print("[INFO] Creating custom environment to set LOG_LEVEL.")
        run_env = os.environ.copy()
        verbosity = monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()
        run_env['LOG_LEVEL'] = verbosity
        print(f"[INFO] Setting LOG_LEVEL={verbosity} for C executable.")
        popen_kwargs['env'] = run_env
    else:
        print("[INFO] Using inherited environment for process.")
 
    print("-" * 60)
    try:
        # Pass the constructed keyword arguments dictionary to Popen
        process = subprocess.Popen(command, **popen_kwargs)
 
        with open(log_path, "w") as log_file:
            for line in process.stdout:
                sys.stdout.write(line)
                log_file.write(line)
        process.wait()
        return_code = process.returncode
        print("-" * 60)
        if return_code == 0:
            print(f"[SUCCESS] Execution finished successfully.")
        else:
            print(f"[FATAL] Execution failed with exit code {return_code}. Check log: {os.path.relpath(log_path)}", file=sys.stderr)
            sys.exit(return_code)
    except FileNotFoundError:
        print(f"[FATAL] Command not found or is not executable: '{command[0]}'", file=sys.stderr)
        print("        Please check that the path is correct and the file has execute permissions.", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"[FATAL] An unexpected error occurred during execution: {e}", file=sys.stderr)
        sys.exit(1)
 
 
def format_command_for_display(command: list) -> str:
    """!
    @brief Render a shell-safe command string for console and log output.
    @param[in] command Argument passed to `format_command_for_display()`.
    @return Value returned by `format_command_for_display()`.
    """
    return " ".join(shlex.quote(str(part)) for part in command)
 
 
def resolve_command_log_path(run_dir: str, log_filename: str) -> str:
    """!
    @brief Resolve a command log filename relative to the run directory.
    @param[in] run_dir Argument passed to `resolve_command_log_path()`.
    @param[in] log_filename Argument passed to `resolve_command_log_path()`.
    @return Value returned by `resolve_command_log_path()`.
    """
    if os.path.dirname(log_filename):
        return os.path.join(run_dir, log_filename)
    return os.path.join(run_dir, "logs", log_filename)
 
 
class CommandExecutionError(RuntimeError):
    """!
    @brief Raised when an external command exits unsuccessfully.
    """
 
    def __init__(self, command: list, returncode: int, details: str = None):
        """!
        @brief Initialize a command execution error.
        @param[in] command Argument passed to `__init__()`.
        @param[in] returncode Argument passed to `__init__()`.
        @param[in] details Argument passed to `__init__()`.
        """
        self.command = command
        self.returncode = returncode
        self.details = details
        detail_suffix = f": {details}" if details else ""
        super().__init__(
            f"Command failed with exit code {returncode}: {format_command_for_display(command)}{detail_suffix}"
        )
 
 
class PlotDependencyError(RuntimeError):
    """!
    @brief Raised when plot.gen reports a missing optional dependency.
    """
 
 
def _run_captured_command(command: list, run_dir: str) -> subprocess.CompletedProcess:
    """!
    @brief Run a command and capture combined stdout/stderr details for later inspection.
    @param[in] command Argument passed to `_run_captured_command()`.
    @param[in] run_dir Argument passed to `_run_captured_command()`.
    @return Value returned by `_run_captured_command()`.
    """
    try:
        return subprocess.run(
            command,
            cwd=run_dir,
            text=True,
            capture_output=True,
            check=False,
            encoding="utf-8",
            errors="replace",
        )
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
 
def _require_successful_command(command: list, result: subprocess.CompletedProcess):
    """!
    @brief Raise `CommandExecutionError` when a captured command failed.
    @param[in] command Argument passed to `_require_successful_command()`.
    @param[in] result Argument passed to `_require_successful_command()`.
    """
    if result.returncode == 0:
        return
    details = (result.stderr or result.stdout).strip()
    raise CommandExecutionError(command, result.returncode, details or None)
 
 
def _capture_command_stdout(command: list, run_dir: str) -> str:
    """!
    @brief Run a command, require success, and return stripped stdout text.
    @param[in] command Argument passed to `_capture_command_stdout()`.
    @param[in] run_dir Argument passed to `_capture_command_stdout()`.
    @return Value returned by `_capture_command_stdout()`.
    """
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return result.stdout.strip()
 
 
def _stream_command_to_console_and_log(command: list, run_dir: str, log_file):
    """!
    @brief Stream command output to stdout and an already-open log file.
    @param[in] command Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] run_dir Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] log_file Argument passed to `_stream_command_to_console_and_log()`.
    """
    display = format_command_for_display(command)
    print(f"[INFO] Running: {display}")
    log_file.write(f"$ {display}\n")
    log_file.flush()
 
    popen_kwargs = {
        "stdout": subprocess.PIPE,
        "stderr": subprocess.STDOUT,
        "cwd": run_dir,
        "bufsize": 1,
        "universal_newlines": True,
        "encoding": "utf-8",
        "errors": "replace",
    }
 
    try:
        process = subprocess.Popen(command, **popen_kwargs)
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
    with process:
        for line in process.stdout:
            sys.stdout.write(line)
            log_file.write(line)
    return_code = process.wait()
    log_file.write("\n")
    log_file.flush()
    if return_code != 0:
        raise CommandExecutionError(command, return_code)
 
 
def _get_git_head_state(run_dir: str) -> dict:
    """!
    @brief Capture the current git HEAD branch name and commit hash.
    @param[in] run_dir Argument passed to `_get_git_head_state()`.
    @return Value returned by `_get_git_head_state()`.
    """
    head_commit = _capture_command_stdout(["git", "rev-parse", "--verify", "HEAD"], run_dir)
    branch_result = _run_captured_command(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], run_dir)
    branch_name = branch_result.stdout.strip() if branch_result.returncode == 0 else None
    return {"branch": branch_name, "commit": head_commit}
 
 
def _get_local_branches_with_upstreams(run_dir: str) -> "list[tuple[str, str | None]]":
    """!
    @brief Return local branch names plus their configured upstreams.
    @param[in] run_dir Argument passed to `_get_local_branches_with_upstreams()`.
    @return Value returned by `_get_local_branches_with_upstreams()`.
    """
    output = _capture_command_stdout(
        ["git", "for-each-ref", "--sort=refname", "--format=%(refname:short)\t%(upstream:short)", "refs/heads"],
        run_dir,
    )
    branches = []
    for line in output.splitlines():
        if not line.strip():
            continue
        branch_name, _, upstream_name = line.partition("\t")
        branches.append((branch_name, upstream_name or None))
    return branches
 
 
def _working_tree_has_tracked_changes(run_dir: str) -> bool:
    """!
    @brief Return `True` when the repository has staged or unstaged tracked changes.
    @param[in] run_dir Argument passed to `_working_tree_has_tracked_changes()`.
    @return Value returned by `_working_tree_has_tracked_changes()`.
    """
    command = ["git", "status", "--porcelain", "--untracked-files=no"]
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return bool(result.stdout.strip())
 
 
def _attempt_pull_cleanup(run_dir: str, rebase: bool, log_file):
    """!
    @brief Best-effort cleanup after a failed `git pull` so the original branch can be restored.
    @param[in] run_dir Argument passed to `_attempt_pull_cleanup()`.
    @param[in] rebase Argument passed to `_attempt_pull_cleanup()`.
    @param[in] log_file Argument passed to `_attempt_pull_cleanup()`.
    """
    cleanup_command = ["git", "rebase", "--abort"] if rebase else ["git", "merge", "--abort"]
    result = _run_captured_command(cleanup_command, run_dir)
    if result.returncode == 0:
        print(f"[INFO] Cleaned up the interrupted {'rebase' if rebase else 'merge'} state.")
        log_file.write(f"$ {format_command_for_display(cleanup_command)}\n")
        if result.stdout:
            sys.stdout.write(result.stdout)
            log_file.write(result.stdout)
        if result.stderr:
            sys.stderr.write(result.stderr)
            log_file.write(result.stderr)
        log_file.write("\n")
        log_file.flush()
        return
 
    details = (result.stderr or result.stdout).strip()
    if details:
        message = (
            f"[WARNING] Could not clean up a failed {'rebase' if rebase else 'merge'} automatically: {details}"
        )
        print(message, file=sys.stderr)
        log_file.write(message + "\n")
        log_file.flush()
 
 
def _restore_git_head(run_dir: str, original_head: dict, log_file):
    """!
    @brief Restore the repository back to the branch or detached commit it started on.
    @param[in] run_dir Argument passed to `_restore_git_head()`.
    @param[in] original_head Argument passed to `_restore_git_head()`.
    @param[in] log_file Argument passed to `_restore_git_head()`.
    """
    current_state = _get_git_head_state(run_dir)
    if original_head["branch"]:
        if current_state["branch"] == original_head["branch"]:
            return
        _stream_command_to_console_and_log(["git", "checkout", original_head["branch"]], run_dir, log_file)
        return
 
    if current_state["branch"] is None and current_state["commit"] == original_head["commit"]:
        return
    _stream_command_to_console_and_log(["git", "checkout", "--detach", original_head["commit"]], run_dir, log_file)
 
 
def pull_all_source_branches(run_dir: str, log_filename: str, rebase: bool = True):
    """!
    @brief Refresh every local tracking branch in the source repository, then restore the starting branch.
    @param[in] run_dir Argument passed to `pull_all_source_branches()`.
    @param[in] log_filename Argument passed to `pull_all_source_branches()`.
    @param[in] rebase Argument passed to `pull_all_source_branches()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print("\n" + "="*23 + " PULL SOURCE STAGE " + "="*22)
    print("[INFO] Refreshing all local source branches that track an upstream.")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    try:
        original_head = _get_git_head_state(run_dir)
        if _working_tree_has_tracked_changes(run_dir):
            raise RuntimeError(
                "Multi-branch pull requires a clean tracked working tree in the source repository. "
                "Commit or stash those changes first, or rerun with --current-branch-only."
            )
        branches = _get_local_branches_with_upstreams(run_dir)
    except (CommandExecutionError, RuntimeError) as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(getattr(exc, "returncode", 1))
 
    if not branches:
        print("[FATAL] No local branches were found in the source repository.", file=sys.stderr)
        sys.exit(1)
 
    if original_head["branch"]:
        branches = [item for item in branches if item[0] != original_head["branch"]] + [
            item for item in branches if item[0] == original_head["branch"]
        ]
 
    skipped_branches = []
    current_operation = None
    pull_error = None
    restore_error = None
 
    with open(log_path, "w", encoding="utf-8") as log_file:
        log_file.write(f"# PICurv pull-source all-branch sync\n")
        log_file.write(f"# repository: {os.path.abspath(run_dir)}\n")
        log_file.write(f"# started: {datetime.now().isoformat()}\n")
        log_file.write(
            f"# original head: {original_head['branch'] if original_head['branch'] else original_head['commit']}\n\n"
        )
 
        try:
            for branch_name, upstream_name in branches:
                if not upstream_name:
                    warning = f"[WARNING] Skipping branch '{branch_name}' because it has no configured upstream."
                    print(warning, file=sys.stderr)
                    log_file.write(warning + "\n")
                    skipped_branches.append(branch_name)
                    continue
 
                print(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.")
                log_file.write(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.\n")
 
                current_operation = f"checkout:{branch_name}"
                _stream_command_to_console_and_log(["git", "checkout", branch_name], run_dir, log_file)
 
                pull_command = ["git", "pull"]
                if rebase:
                    pull_command.append("--rebase")
                current_operation = f"pull:{branch_name}"
                _stream_command_to_console_and_log(pull_command, run_dir, log_file)
                current_operation = None
        except CommandExecutionError as exc:
            pull_error = exc
            if current_operation and current_operation.startswith("pull:"):
                _attempt_pull_cleanup(run_dir, rebase, log_file)
        finally:
            try:
                _restore_git_head(run_dir, original_head, log_file)
            except CommandExecutionError as exc:
                restore_error = exc
 
    print("-" * 60)
    if pull_error:
        if restore_error:
            print(
                f"[FATAL] Multi-branch pull failed and the original branch could not be restored. "
                f"Check log: {os.path.relpath(log_path)}",
                file=sys.stderr,
            )
            sys.exit(restore_error.returncode)
        print(
            f"[FATAL] Multi-branch pull failed. Original branch restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(pull_error.returncode)
 
    if restore_error:
        print(
            f"[FATAL] Branch updates completed, but the original branch could not be restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(restore_error.returncode)
 
    if skipped_branches:
        print(f"[WARNING] Skipped branches with no upstream: {', '.join(skipped_branches)}", file=sys.stderr)
    print("[SUCCESS] All local tracking branches are up to date.")
 
def auto_identify_run_inputs(config_dir: str):
    """!
    @brief Auto-detect case.yml, monitor.yml, and *.control in a run config directory.
    @param[in] config_dir Argument passed to `auto_identify_run_inputs()`.
    @return Value returned by `auto_identify_run_inputs()`.
    """
    run_dir = os.path.dirname(os.path.abspath(config_dir))
    active = load_active_run_configuration(run_dir)
    if active:
        case_path = active.get("case")
        monitor_path = active.get("monitor")
        solver_control_path = active.get("control")
        if all(path and os.path.isfile(path) for path in (case_path, monitor_path, solver_control_path)):
            return case_path, monitor_path, solver_control_path
    all_yml_files = glob.glob(os.path.join(config_dir, "*.yml"))
    case_path, monitor_path = None, None
    for f_path in all_yml_files:
        try:
            content = read_yaml_file(f_path)
            if not isinstance(content, dict):
                continue
            if 'models' in content and 'boundary_conditions' in content:
                case_path = f_path
            elif 'io' in content and 'logging' in content:
                monitor_path = f_path
        except Exception as e:
            print(f"[WARNING] Could not parse or inspect '{f_path}': {e}", file=sys.stderr)
    try:
        solver_control_path = glob.glob(os.path.join(config_dir, "*.control"))[0]
    except IndexError:
        solver_control_path = None
    return case_path, monitor_path, solver_control_path
 
def resolve_post_source_directory(run_dir: str, monitor_cfg: dict, post_cfg: dict, strict: bool = True) -> str:
    """!
    @brief Resolve post source directory token and optionally enforce existence.
    @param[in] run_dir Argument passed to `resolve_post_source_directory()`.
    @param[in] monitor_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] post_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] strict Argument passed to `resolve_post_source_directory()`.
    @return Value returned by `resolve_post_source_directory()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        resolved_source_dir = solver_output_dir_abs
        print(f"[INFO] Post-processor source data: {os.path.relpath(resolved_source_dir)}")
    else:
        resolved_source_dir = os.path.abspath(os.path.join(run_dir, source_dir_template))
        print(f"[INFO] Post-processor source data (user-defined): {os.path.relpath(resolved_source_dir)}")
 
    if strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print(
            f"[FATAL] Source data directory for post-processing not found or empty: {os.path.relpath(resolved_source_dir)}",
            file=sys.stderr
        )
        sys.exit(1)
    if not strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print("[WARNING] Source data directory is not available yet; keeping deferred path for scheduled post job.")
    return resolved_source_dir
 
def render_slurm_array_stage_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    array_spec: str,
    case_index_tsv: str,
    stage: str,
    solver_exe: str,
    post_exe: str,
    stdout_path: str,
    stderr_path: str
):
    """!
    @brief Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts.
    @param[in] script_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] job_name Argument passed to `render_slurm_array_stage_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_array_stage_script()`.
    @param[in] array_spec Argument passed to `render_slurm_array_stage_script()`.
    @param[in] case_index_tsv Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stage Argument passed to `render_slurm_array_stage_script()`.
    @param[in] solver_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] post_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_array_stage_script()`.
    @return Value returned by `render_slurm_array_stage_script()`.
    """
    effective_cluster_cfg = cluster_cfg
    resources = effective_cluster_cfg.get("resources", {})
    notifications = effective_cluster_cfg.get("notifications", {}) or {}
    execution = effective_cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
    extra_sbatch = execution.get("extra_sbatch")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
        f"#SBATCH --array={array_spec}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        "",
        f'CASE_INDEX_FILE={shlex.quote(case_index_tsv)}',
        'LINE=$(sed -n "$((SLURM_ARRAY_TASK_ID + 1))p" "$CASE_INDEX_FILE")',
        'if [ -z "$LINE" ]; then',
        '  echo "No case entry for array index ${SLURM_ARRAY_TASK_ID}" >&2',
        '  exit 1',
        "fi",
        "IFS=$'\\t' read -r CASE_INDEX CASE_ID RUN_DIR CONTROL_FILE POST_RECIPE_FILE LOG_LEVEL POST_PREFIX SOLVE_DIAGNOSTIC_ARGS POST_DIAGNOSTIC_ARGS <<< \"$LINE\"",
        'cd "$RUN_DIR"',
        'echo "[$(date)] Starting case ${CASE_ID} (array index ${SLURM_ARRAY_TASK_ID})"',
    ])
 
    if stage == "solve":
        walltime_guard_exports = build_walltime_guard_exports(effective_cluster_cfg)
        for key, value in walltime_guard_exports.items():
            lines.append(f"export {key}={value}")
 
    lines.append('export LOG_LEVEL="${LOG_LEVEL}"')
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    if stage == "solve":
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            solver_exe,
            ["-control_file", "$CONTROL_FILE"]
        )
    else:
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            post_exe,
            ["-control_file", "$CONTROL_FILE", "-postprocessing_config_file", "$POST_RECIPE_FILE"],
            force_num_procs=get_cluster_total_tasks(effective_cluster_cfg),
        )
 
    # Keep shell variables unresolved inside sbatch script.
    def _token(tok: str) -> str:
        """!
        @brief Preserve shell-variable tokens while safely quoting literal command arguments for an sbatch script.
        @param[in] tok Argument passed to `_token()`.
        @return Value returned by `_token()`.
        """
        if tok.startswith("$"):
            return tok
        return shlex.quote(str(tok))
 
    diag_var = "${SOLVE_DIAGNOSTIC_ARGS}" if stage == "solve" else "${POST_DIAGNOSTIC_ARGS}"
    command_text = " ".join(_token(t) for t in cmd)
    executable_token = _token(solver_exe if stage == "solve" else post_exe)
    # Diagnostic args must be executable args, not launcher args. Insert them
    # immediately before the executable's normal control/recipe options.
    if executable_token and command_text.count(executable_token) == 1:
        command_text = command_text.replace(f"{executable_token} ", f"{executable_token} {diag_var} ", 1)
    lines.append(f"exec {command_text}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 
def render_metrics_aggregate_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    study_dir: str,
    picurv_path: str,
):
    """!
    @brief Generate a single-node sbatch script that runs metrics aggregation.
    @param[in] script_path Path to write the sbatch script.
    @param[in] job_name Slurm job name.
    @param[in] cluster_cfg Parsed cluster YAML dictionary.
    @param[in] study_dir Absolute path to the study directory.
    @param[in] picurv_path Absolute path to the picurv script.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        "#SBATCH --nodes=1",
        "#SBATCH --ntasks-per-node=1",
        "#SBATCH --mem=4G",
        "#SBATCH --time=00:10:00",
        f"#SBATCH --output={os.path.join(scheduler_dir, 'metrics_%j.out')}",
        f"#SBATCH --error={os.path.join(scheduler_dir, 'metrics_%j.err')}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        'echo "[$(date)] Running metrics aggregation"',
        "",
    ])
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    lines.append(
        f"exec {shlex.quote(picurv_path)} sweep --reaggregate"
        f" --study-dir {shlex.quote(study_dir)}"
    )
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 
def reduce_metric_values(values, reduction: str):
    """!
    @brief Reduce a metric series to one scalar according to the requested reducer.
    @param[in] values Sequence of numeric values.
    @param[in] reduction Reduction keyword.
    @return Value returned by `reduce_metric_values()`.
    """
    if not values:
        return None
    np = require_numpy()
    reduction = str(reduction).lower()
    if reduction == "mean":
        return float(np.mean(values))
    if reduction == "min":
        return float(np.min(values))
    if reduction == "max":
        return float(np.max(values))
    if reduction == "p95":
        return float(np.percentile(values, 95.0))
    return float(values[-1])
 
 
def extract_metric_from_csv(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a CSV source.
    @param[in] case_dir Argument passed to `extract_metric_from_csv()`.
    @param[in] spec Argument passed to `extract_metric_from_csv()`.
    @return Value returned by `extract_metric_from_csv()`.
    """
    file_glob = spec.get("file_glob", "**/*_msd.csv")
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    csv_path = candidates[0]
    rows = []
    with open(csv_path, "r", newline="") as f:
        reader = csv.DictReader(f)
        if reader.fieldnames:
            for row in reader:
                rows.append(row)
            if not rows:
                return None
            column = spec.get("column")
            numerator_column = spec.get("numerator_column")
            denominator_column = spec.get("denominator_column")
            denominator_floor = float(spec.get("denominator_floor", 0.0) or 0.0)
            if not column and not numerator_column:
                for name in reversed(reader.fieldnames):
                    if name and name.lower() not in {"step", "time", "timestep"}:
                        column = name
                        break
            if not column and not numerator_column:
                return None
            values = []
            for row in rows:
                try:
                    if numerator_column:
                        numerator = float(row[numerator_column])
                        denominator = float(row[denominator_column])
                        denominator = max(denominator_floor, denominator)
                        if denominator == 0.0:
                            continue
                        values.append(numerator / denominator)
                    else:
                        values.append(float(row[column]))
                except Exception:
                    continue
        else:
            return None
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 
def extract_metric_from_log(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a log file using regex.
    @param[in] case_dir Argument passed to `extract_metric_from_log()`.
    @param[in] spec Argument passed to `extract_metric_from_log()`.
    @return Value returned by `extract_metric_from_log()`.
    """
    file_glob = spec.get("file_glob", "logs/*.log")
    regex = spec.get("regex")
    if not regex:
        return None
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    pattern = re.compile(regex)
    values = []
    for path in candidates:
        try:
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for line in f:
                    m = pattern.search(line)
                    if m:
                        try:
                            values.append(float(m.group(1)))
                        except Exception:
                            pass
        except OSError:
            continue
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 
def normalize_metric_spec(metric):
    """!
    @brief Normalize study metric definitions to a common dictionary form.
    @param[in] metric Argument passed to `normalize_metric_spec()`.
    @return Value returned by `normalize_metric_spec()`.
    """
    if isinstance(metric, str):
        if metric.lower() in {"msd", "msd_final"}:
            return {
                "name": "msd_final",
                "source": "statistics_csv",
                "file_glob": "**/*_msd.csv",
                "reduction": "last",
            }
        return {"name": metric, "source": "log_regex", "regex": metric}
    return dict(metric)
 
def _read_previous_metric_rows(results_dir: str) -> dict:
    """!
    @brief Read the metrics table an earlier aggregation wrote, keyed by case id.
    @param[in] results_dir Study analysis directory holding metrics_table.csv.
    @return Mapping of case id to its previously recorded row, empty when absent.
    """
    path = os.path.join(results_dir, "metrics_table.csv")
    if not os.path.isfile(path):
        return {}
    try:
        with open(path, "r", encoding="utf-8", newline="") as stream:
            return {
                row["case_id"]: row for row in csv.DictReader(stream) if row.get("case_id")
            }
    except (OSError, ValueError):
        return {}
 
 
def aggregate_study_metrics(study_cfg: dict, cases: list, results_dir: str) -> str:
    """!
    @brief Collect metric values from generated case directories into one CSV.
    @param[in] study_cfg Argument passed to `aggregate_study_metrics()`.
    @param[in] cases Argument passed to `aggregate_study_metrics()`.
    @param[in] results_dir Argument passed to `aggregate_study_metrics()`.
    @return Value returned by `aggregate_study_metrics()`.
    """
    metrics = study_cfg.get("metrics", [])
    if not metrics:
        metrics = ["msd_final"]
    normalized_specs = [normalize_metric_spec(m) for m in metrics]
 
    # A member whose payload was archived cannot be re-measured. Its previously
    # aggregated values are the correct answer for it, so they are carried forward
    # rather than overwritten with blanks or the whole table refused.
    preserved = _read_previous_metric_rows(results_dir)
    rows = []
    for case in cases:
        row = {"case_id": case["case_id"]}
        flat_parameters = flatten_study_parameters(case.get("parameters", {}))
        for p_key, p_val in flat_parameters.items():
            row[p_key] = p_val
        if is_artifact_cold(case["run_dir"]):
            retained = preserved.get(case["case_id"])
            if retained:
                for spec in normalized_specs:
                    name = spec.get("name", "metric")
                    row[name] = retained.get(name)
                row["_source"] = "retained"
                rows.append(row)
                continue
            print(
                f"[WARN] {case['case_id']} is in cold storage and no previous metrics "
                "row was found; its values are reported as unavailable.",
                file=sys.stderr,
            )
            for spec in normalized_specs:
                row[spec.get("name", "metric")] = None
            rows.append(row)
            continue
        for spec in normalized_specs:
            name = spec.get("name", "metric")
            source = str(spec.get("source", "")).lower()
            if source in METRIC_SOURCE_KINDS[:2]:
                value = extract_metric_from_csv(case["run_dir"], spec)
            elif source in METRIC_SOURCE_KINDS[2:]:
                value = extract_metric_from_log(case["run_dir"], spec)
            else:
                value = None
 
            normalize_key = spec.get("normalize_by_parameter")
            if value is not None and normalize_key:
                denom = flat_parameters.get(normalize_key)
                try:
                    denom = float(denom)
                except Exception:
                    denom = None
                if denom not in (None, 0.0):
                    value = float(value) / denom
                else:
                    value = None
 
            row[name] = value
        rows.append(row)
 
    if not rows:
        return None
 
    all_keys = []
    seen = set()
    for row in rows:
        for k in row.keys():
            if k not in seen:
                seen.add(k)
                all_keys.append(k)
 
    os.makedirs(results_dir, exist_ok=True)
    out_csv = os.path.join(results_dir, "metrics_table.csv")
    with open(out_csv, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=all_keys)
        writer.writeheader()
        writer.writerows(rows)
    print(f"[SUCCESS] Aggregated metrics table: {os.path.relpath(out_csv)}")
    return out_csv
 
_STUDY_REPORT_COLORS = (
    "#0072B2", "#D55E00", "#009E73", "#CC79A7",
    "#E69F00", "#56B4E9", "#332288", "#999999",
)
 
 
def _study_parameter_label(key: str) -> str:
    """!
    @brief Return a concise report label for a study parameter path.
    @param[in] key Dotted study parameter path.
    @return Report-facing axis or legend label.
    """
    exact = {
        "case.run_control.dt_physical": "Physical timestep, Δt",
        "case.models.physics.particles.count": "Particle count",
        "solver.operation_mode.uniform_flow.u": "Uniform-flow velocity, u",
        "case.grid.programmatic_settings.im": "Grid nodes in i, Nᵢ",
        "case.grid.programmatic_settings.jm": "Grid nodes in j, Nⱼ",
        "case.grid.programmatic_settings.km": "Grid nodes in k, Nₖ",
    }
    return exact.get(key, _humanize_plot_identifier(key))
 
 
def _study_metric_label(study_cfg: dict, metric: str) -> str:
    """!
    @brief Resolve an optional configured metric label or humanize its name.
    @param[in] study_cfg Parsed study configuration.
    @param[in] metric Metric column name.
    @return Report-facing metric label.
    """
    for raw_spec in study_cfg.get("metrics", []) or []:
        spec = normalize_metric_spec(raw_spec)
        if spec.get("name") != metric:
            continue
        label = spec.get("plot_label") or spec.get("label")
        units = spec.get("units")
        base = str(label) if label else _humanize_plot_identifier(metric)
        return f"{base} ({units})" if units else base
    return _humanize_plot_identifier(metric)
 
 
def _numeric_study_column(rows: list, key: str) -> "list | None":
    """!
    @brief Parse one complete, finite numeric study-table column.
    @param[in] rows Metrics-table rows.
    @param[in] key Column name.
    @return Numeric values, or None when the column is incomplete or nonnumeric.
    """
    values = []
    for row in rows:
        try:
            value = float(row[key])
        except (KeyError, TypeError, ValueError):
            return None
        if not math.isfinite(value):
            return None
        values.append(value)
    return values
 
 
def _infer_study_plot_axis(study_cfg: dict, rows: list) -> "dict | None":
    """!
    @brief Infer the scientifically meaningful independent variable of a study.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @return Axis metadata, or None when no numeric independent variable exists.
    """
    params = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    if not params or not rows:
        return None
 
    grid_keys = (
        "case.grid.programmatic_settings.im",
        "case.grid.programmatic_settings.jm",
        "case.grid.programmatic_settings.km",
    )
    if study_cfg.get("study_type") == "grid_independence" and all(key in params for key in grid_keys):
        columns = [_numeric_study_column(rows, key) for key in grid_keys]
        if all(column is not None for column in columns):
            values = [
                (columns[0][index] * columns[1][index] * columns[2][index]) ** (1.0 / 3.0)
                for index in range(len(rows))
            ]
            return {
                "key": "characteristic_grid_resolution",
                "label": "Characteristic grid resolution, (NᵢNⱼNₖ)¹⁄³",
                "slug": "characteristic_grid_resolution",
                "values": values,
                "contributors": set(grid_keys),
            }
 
    preferred = []
    if study_cfg.get("study_type") == "timestep_independence":
        preferred = [key for key in params if key.endswith(".dt_physical")]
    numeric = []
    for key in preferred + [key for key in params if key not in preferred]:
        values = _numeric_study_column(rows, key)
        if values is not None:
            numeric.append((key, values, len(set(values))))
    if not numeric:
        return None
    varied = [candidate for candidate in numeric if candidate[2] > 1]
    key, values, _unique = (varied or numeric)[0]
    return {
        "key": key,
        "label": _study_parameter_label(key),
        "slug": re.sub(r"[^A-Za-z0-9_.-]+", "_", key),
        "values": values,
        "contributors": {key},
    }
 
 
def infer_plot_x_axis(study_cfg: dict, rows: list):
    """!
    @brief Infer x-axis key/values for study plots.
    @param[in] study_cfg Argument passed to `infer_plot_x_axis()`.
    @param[in] rows Argument passed to `infer_plot_x_axis()`.
    @return Value returned by `infer_plot_x_axis()`.
    """
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        return None, None
    return axis["label"], axis["values"]
 
 
def _format_study_group_value(value) -> str:
    """!
    @brief Format a secondary study parameter compactly for a legend.
    @param[in] value Parameter value.
    @return Compact report string.
    """
    try:
        number = float(value)
    except (TypeError, ValueError):
        return str(value)
    if number.is_integer():
        return f"{int(number):,}"
    return f"{number:g}"
 
 
def _study_plot_groups(study_cfg: dict, rows: list, axis: dict, metric: str) -> list:
    """!
    @brief Group metric points by any secondary varied study parameters.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @param[in] axis Inferred independent-axis metadata.
    @param[in] metric Metric column name.
    @return Labeled point groups.
    """
    param_keys = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    secondary = []
    for key in param_keys:
        if key in axis["contributors"]:
            continue
        values = {str(row.get(key)) for row in rows}
        # A control coupled one-to-one with x (for example total_steps paired
        # with dt to keep physical duration fixed, or particle count paired with
        # grid size to keep PPC fixed) describes the same study trajectory. It
        # must not split that trajectory into one-point pseudo-series.
        if 1 < len(values) < len(rows):
            secondary.append(key)
 
    groups = {}
    for row_index, row in enumerate(rows):
        try:
            y_value = float(row[metric])
        except (KeyError, TypeError, ValueError):
            continue
        if not math.isfinite(y_value):
            continue
        identity = tuple(row.get(key) for key in secondary)
        groups.setdefault(identity, []).append([axis["values"][row_index], y_value])
 
    result = []
    for identity, points in groups.items():
        points.sort(key=lambda point: point[0])
        label = ", ".join(
            f"{_study_parameter_label(key)} = {_format_study_group_value(value)}"
            for key, value in zip(secondary, identity)
        )
        result.append({"label": label or "Study cases", "points": points})
    return result
 
 
def _study_use_log_scale(values: list, semantic_hint: bool = False) -> bool:
    """!
    @brief Use log scaling only for positive data spanning a meaningful range.
    @param[in] values Candidate axis values.
    @param[in] semantic_hint Whether the quantity is conventionally read logarithmically.
    @return True when logarithmic scaling improves interpretation.
    """
    if not values or any(value <= 0.0 for value in values):
        return False
    ratio = max(values) / min(values)
    return ratio >= (20.0 if semantic_hint else 100.0)
 
 
def _study_linear_y_limits(values: list) -> "tuple[float, float] | None":
    """!
    @brief Build padded linear limits that include zero for non-negative metrics.
    @param[in] values Finite metric values.
    @return Lower and upper limits, or None for an empty sequence.
    """
    if not values:
        return None
    lower, upper = min(values), max(values)
    if lower >= 0.0:
        lower = 0.0
    span = upper - lower
    padding = max(span * 0.06, abs(upper) * 0.02, 1.0e-12)
    return (lower, upper + padding) if lower == 0.0 else (lower - padding, upper + padding)
 
def generate_study_plots(study_cfg: dict, metrics_csv: str, plots_dir: str):
    """!
    @brief Generate metric-vs-parameter plots for completed studies.
    @param[in] study_cfg Argument passed to `generate_study_plots()`.
    @param[in] metrics_csv Argument passed to `generate_study_plots()`.
    @param[in] plots_dir Argument passed to `generate_study_plots()`.
    @return Value returned by `generate_study_plots()`.
    """
    plotting_cfg = study_cfg.get("plotting", {}) or {}
    if plotting_cfg.get("enabled", True) is False:
        print("[INFO] Plotting disabled by study.yml.")
        return []
    plt = optional_matplotlib_pyplot()
    if plt is None:
        print("[WARNING] matplotlib not available; skipping plot generation.")
        return []
    if not metrics_csv or not os.path.isfile(metrics_csv):
        return []
 
    with open(metrics_csv, "r", newline="") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    if not rows:
        return []
 
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        print("[WARNING] Could not infer numeric x-axis for plots; skipping.")
        return []
 
    configured_metrics = study_cfg.get("metrics", []) or ["msd_final"]
    metric_keys = [
        normalize_metric_spec(metric).get("name", "metric") for metric in configured_metrics
        if normalize_metric_spec(metric).get("name", "metric") in rows[0]
    ]
 
    out_format = plotting_cfg.get("output_format", "png")
    os.makedirs(plots_dir, exist_ok=True)
    generated = []
    for metric in metric_keys:
        groups = _study_plot_groups(study_cfg, rows, axis, metric)
        if not groups:
            continue
        all_x = [point[0] for group in groups for point in group["points"]]
        all_y = [point[1] for group in groups for point in group["points"]]
        metric_label = _study_metric_label(study_cfg, metric)
        metric_hint = metric.lower()
        y_log = _study_use_log_scale(
            all_y,
            any(token in metric_hint for token in ("error", "residual", "drift", "msd")),
        )
        x_log = _study_use_log_scale(all_x)
        grid_cross_product = (
            study_cfg.get("study_type") == "grid_independence"
            and bool(study_cfg.get("parameters")) and len(axis["contributors"]) == 3
            and sum(
                len(set(float(row[key]) for row in rows)) > 1
                for key in axis["contributors"]
            ) > 1
        )
 
        plt.figure(figsize=(9.2, 5.5), facecolor="white")
        for index, group in enumerate(groups):
            x_values = [point[0] for point in group["points"]]
            y_values = [point[1] for point in group["points"]]
            repeated_x = len(set(x_values)) != len(x_values)
            plt.plot(
                x_values, y_values,
                color=_STUDY_REPORT_COLORS[index % len(_STUDY_REPORT_COLORS)],
                marker="o", markersize=5.2, markeredgewidth=0.7,
                linewidth=0.0 if repeated_x or grid_cross_product else 1.8,
                linestyle="none" if repeated_x or grid_cross_product else "-",
                label=group["label"],
            )
        plt.xlabel(axis["label"], fontsize=11)
        plt.ylabel(metric_label, fontsize=11)
        study_label = {
            "grid_independence": "Grid-independence study",
            "timestep_independence": "Timestep-independence study",
            "sensitivity": "Sensitivity study",
        }.get(study_cfg.get("study_type"), "Parameter study")
        plt.title(f"{metric_label} vs. {axis['label']}\n{study_label}", fontsize=13, loc="left", pad=12)
        if x_log and hasattr(plt, "xscale"):
            plt.xscale("log")
        if y_log:
            plt.yscale("log")
        elif hasattr(plt, "ylim"):
            limits = _study_linear_y_limits(all_y)
            if limits:
                plt.ylim(*limits)
        if hasattr(plt, "tick_params"):
            plt.tick_params(axis="both", which="major", labelsize=9.5)
        plt.grid(True, alpha=0.24, which="major", linewidth=0.7)
        if x_log or y_log:
            plt.grid(True, alpha=0.08, which="minor", linewidth=0.5)
        if len(groups) > 1:
            plt.legend(
                loc="upper left", bbox_to_anchor=(1.01, 1.0), borderaxespad=0.0,
                frameon=False, title="Fixed parameters", fontsize=9, title_fontsize=9.5,
            )
            plt.tight_layout(rect=(0.0, 0.0, 0.76, 1.0))
        else:
            plt.tight_layout()
        safe_metric = re.sub(r"[^A-Za-z0-9_.-]+", "_", metric)
        out_path = os.path.join(plots_dir, f"{safe_metric}_vs_{axis['slug']}.{out_format}")
        plt.savefig(out_path, dpi=240, bbox_inches="tight", facecolor="white")
        plt.close()
        generated.append(out_path)
    if generated:
        print(f"[SUCCESS] Generated {len(generated)} plot(s) in {os.path.relpath(plots_dir)}")
    return generated
 
 
def _command_to_string(command_tokens: list) -> str:
    """!
    @brief Render a command list as a shell-safe display string.
    @param[in] command_tokens Argument passed to `_command_to_string()`.
    @return Value returned by `_command_to_string()`.
    """
    return " ".join(shlex.quote(str(tok)) for tok in command_tokens)
 
 
def _resolve_post_source_directory_preview(run_dir: str, monitor_cfg: dict, post_cfg: dict) -> str:
    """!
    @brief Resolve post source directory without side effects or stdout/stderr output.
    @param[in] run_dir Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] monitor_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] post_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @return Value returned by `_resolve_post_source_directory_preview()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        return solver_output_dir_abs
    return os.path.abspath(os.path.join(run_dir, source_dir_template))
 
 
def build_run_dry_plan(args) -> dict:
    """!
    @brief Build a no-write execution plan for `run --dry-run`.
    @param[in] args Command-line style argument list supplied to the function.
    @return Value returned by `build_run_dry_plan()`.
    """
    plan = {
        "mode": "dry-run",
        "created_at": datetime.now().isoformat(),
        "warnings": [],
        "inputs": {},
        "stages": {},
        "artifacts": [],
    }
 
    if args.dry_run and args.no_submit:
        plan["warnings"].append("--dry-run takes precedence over --no-submit; no files will be written.")
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
    run_id = None
    run_dir = None
    solver_control_path = None
    loaded_case_cfg = None
    loaded_monitor_cfg = None
    resolved_restart_source_dir = None
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"--scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"Unsupported scheduler '{scheduler_type}'. Only Slurm is supported in v1.",
            )
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="resources.ntasks_per_node",
                file_path=cluster_path,
                message=(
                    "--num-procs must be 1 (auto) or "
                    f"exactly nodes*ntasks_per_node ({cluster_tasks}) in cluster mode."
                ),
            )
            sys.exit(1)
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        plan["launch_mode"] = "slurm"
        plan["inputs"]["cluster"] = cluster_path
    else:
        if getattr(args, "scheduler", None):
            fail_cli_usage("--scheduler requires --cluster in this version.")
        plan["launch_mode"] = "local"
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False) and not args.post_process:
            print("[WARNING] --continue has no effect without --solve or --post-process and will be ignored.", file=sys.stderr)
 
    if args.solve:
        case_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        loaded_case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        loaded_monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(loaded_case_cfg, solver_cfg, loaded_monitor_cfg, case_path, solver_path, monitor_path)
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            # --continue reuses existing run directory
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(runs_root, loaded_case_cfg, case_path)
            run_dir = os.path.join(runs_root, run_id)
 
        try:
            resolved_restart_source_dir, is_continue, planned_lineage = resolve_restart_source(
                args, loaded_case_cfg, solver_cfg, loaded_monitor_cfg, run_dir,
                materialize=False,
            )
            plan["lineage"] = planned_lineage or {"relationship": "root"}
        except ValueError as e:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=case_path,
                message=str(e),
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        scheduler_dir = os.path.join(run_dir, "scheduler")
        # Report the directories the run will ACTUALLY use, not the defaults. A plan
        # that hides a configured path cannot warn about where output really lands -
        # and the fresh-run log directory is deleted recursively by the C runtime.
        _plan_dirs = {}
        logs_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"])
        planned_output_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
        solver_control_path = os.path.join(config_dir, f"{run_id}.control")
        profile_path = os.path.join(config_dir, "profile.run")
        profiling_preview = resolve_profiling_config(loaded_monitor_cfg)
 
        plan["run_id_preview"] = run_id
        plan["run_dir_preview"] = run_dir
        # A plan that omits what a real run would refuse is not a plan. The run
        # directory does not exist yet, but `realpath` still normalizes it, so the
        # run-root and ancestor verdicts are decidable here.
        _authorized, _ = resolve_unsafe_paths_override(_plan_dirs, "monitor.yml")
        plan.setdefault("blocking", [])
        # A run resumed into a directory that grew an unrouted peer would be refused,
        # so the plan has to say so rather than promising a launch that will not happen.
        structure_errors, structure_warnings = validate_run_directory_structure(run_dir)
        plan["blocking"].extend(structure_errors)
        plan["warnings"].extend(structure_warnings)
        for _key, _verdict, _message in classify_physical_containment(
                run_dir, effective_run_directories(_plan_dirs)):
            if _authorized and _verdict in WAIVABLE_PHYSICAL_VERDICTS:
                plan["warnings"].append(f"{_message} Allowed only because "
                                        f"'allow_unsafe_paths: true' is set.")
            else:
                plan["blocking"].append(_message)
        plan["inputs"].update({"case": case_path, "solver": solver_path, "monitor": monitor_path})
        asset_plan = plan_run_assets(loaded_case_cfg, case_path)
        plan["asset_actions"] = [
            {"kind": item["kind"], "provider": item["provider"], "action": item["action"]}
            for item in asset_plan["actions"]
        ]
        runtime_kinds = {
            item["kind"] for item in asset_plan["actions"]
            if item["execution"] == "runtime-c"
        }
        for item in asset_plan["actions"]:
            blocked_dependencies = runtime_kinds.intersection(item.get("dependencies", []))
            if item["execution"] == "precomputable" and blocked_dependencies:
                plan["blocking"].append(
                    f"{item['kind']}={item['provider']} requires a file-backed "
                    f"{', '.join(sorted(blocked_dependencies))}, but that dependency is generated "
                    "only inside the simulator. Select a precomputable provider for the dependency."
                )
        plan["artifacts"].extend(
            [
                run_dir,
                *(os.path.join(run_dir, *relative.split("/"))
                  for relative in RUN_DIRECTORY_LAYOUT),
                os.path.join(config_dir, "case.yml"),
                os.path.join(config_dir, "solver.yml"),
                os.path.join(config_dir, "monitor.yml"),
                os.path.join(config_dir, "active.json"),
                os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "assets.lock.yml"),
                solver_control_path,
                os.path.join(run_dir, "manifest.json"),
            ]
        )
        add_planned_grid_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_profile_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_initial_condition_artifacts(plan, loaded_case_cfg, solver_cfg, run_dir)
        if has_explicit_monitor_whitelist(loaded_monitor_cfg):
            plan["artifacts"].append(os.path.join(config_dir, "whitelist.run"))
        if profiling_preview["mode"] == "selected":
            plan["artifacts"].append(profile_path)
        solve_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "Solver")
        plan["artifacts"].extend(solve_diagnostics["artifacts"])
        if cluster_mode:
            plan["artifacts"].append(os.path.join(config_dir, "cluster.yml"))
            plan["artifacts"].append(os.path.join(scheduler_dir, "submission.json"))
 
        solver_exe = resolve_runtime_executable("simulator")
        solver_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "Solver") + ["-control_file", solver_control_path]
        if cluster_mode:
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=case_path,
                extra_search_anchors=[cluster_path],
            )
            plan["artifacts"].append(solver_script)
            plan["stages"]["solve"] = {
                "mode": "slurm",
                "script": solver_script,
                "num_procs_effective": solver_num_procs_effective,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        else:
            solver_cmd = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=case_path,
            )
            solver_stream_log = os.path.join(scheduler_dir, f"{run_id}_solver.log")
            plan["artifacts"].append(solver_stream_log)
            plan["stages"]["solve"] = {
                "mode": "local",
                "num_procs_effective": solver_num_procs_effective,
                "stream_log": solver_stream_log,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        if resolved_restart_source_dir:
            plan["stages"]["solve"]["restart_source_directory"] = resolved_restart_source_dir
        if is_continue:
            plan["stages"]["solve"]["continue_mode"] = True
 
    if args.post_process:
        post_path = os.path.abspath(args.post)
        plan["inputs"]["post"] = post_path
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, loaded_monitor_cfg, loaded_case_cfg)
 
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            run_id = os.path.basename(run_dir)
        elif not args.solve:
            fail_cli_usage("--post-process requires --run-dir when not used with --solve.")
 
        if args.run_dir:
            config_dir = os.path.join(run_dir, "config")
            case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
            if not all([case_path, monitor_path, solver_control_path]):
                emit_structured_error(
                    ERROR_CODE_CFG_MISSING_KEY,
                    key="run_dir.config",
                    file_path=config_dir,
                    message=(
                        "Could not auto-identify required run inputs "
                        "(case.yml/monitor.yml/*.control) in run config directory."
                    ),
                )
                sys.exit(1)
            loaded_case_cfg = read_yaml_file(case_path)
            loaded_monitor_cfg = read_yaml_file(monitor_path)
        else:
            config_dir = os.path.join(run_dir, "config")
            case_path = os.path.join(config_dir, "case.yml")
            monitor_path = os.path.join(config_dir, "monitor.yml")
            if solver_control_path is None:
                solver_control_path = os.path.join(config_dir, f"{run_id}.control")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        allow_source_frontier_scan = not args.solve
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            loaded_case_cfg,
            loaded_monitor_cfg,
            post_cfg,
            continue_requested=getattr(args, 'continue_run', False),
            allow_source_frontier_scan=allow_source_frontier_scan,
        )
 
        post_recipe_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.run")
        output_dir_rel = post_cfg.get("io", {}).get("output_directory")
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix")
        if not output_prefix:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key="io.output_filename_prefix",
                file_path=post_path,
                message="Missing required post output filename prefix.",
            )
            sys.exit(1)
        output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
        statistics_output_paths = get_post_statistics_output_artifacts(post_cfg, run_dir, loaded_monitor_cfg)
        post_exe = resolve_runtime_executable("postprocessor")
        post_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "PostProcessor")
        plan["artifacts"].extend(post_diagnostics["artifacts"])
        post_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "PostProcessor") + [
            "-control_file",
            solver_control_path,
            "-postprocessing_config_file",
            post_recipe_path,
        ]
        plan["artifacts"].extend([
            post_recipe_path,
            output_dir_abs,
            post_plan["resume_state_path"],
            post_plan["lock_paths"]["wrapper_path"],
            post_plan["lock_paths"]["lock_file"],
            post_plan["lock_paths"]["metadata_file"],
        ])
        plan["artifacts"].extend(statistics_output_paths)
 
        stage_meta = {
            "source_data_directory": post_plan["source_data_directory"],
            "requested_start_step": post_plan["requested_start_step"],
            "requested_end_step": post_plan["requested_end_step"],
            "step_interval": post_plan["step_interval"],
            "resume_applied": bool(post_plan["continue_requested"] and post_plan["resume_recipe_match"]),
            "resume_recipe_match": post_plan["resume_recipe_match"],
            "resume_bootstrapped": post_plan["resume_bootstrapped"],
            "resume_match_source": post_plan["resume_match_source"],
            "completed_frontier_step": post_plan["completed_frontier_step"],
            "source_frontier_step": post_plan["source_frontier_step"],
            "source_frontier_diagnostic": post_plan["source_frontier_diagnostic"],
            "source_frontier_deferred": post_plan["source_frontier_deferred"],
            "effective_start_step": post_plan["effective_start_step"],
            "effective_end_step": post_plan["effective_end_step"],
            "skip_reason": post_plan["skip_reason"],
            "post_skipped_as_complete": post_plan["skip_reason"] == "already-complete-window",
            "recipe_fingerprint": post_plan["recipe_fingerprint"],
            "num_procs_effective": post_num_procs_effective,
        }
 
        if post_plan["skip_reason"] is None:
            if cluster_mode:
                scheduler_dir = os.path.join(run_dir, "scheduler")
                post_script = os.path.join(scheduler_dir, "post.sbatch")
                post_cluster_cfg = cluster_cfg
                raw_post_cmd = build_cluster_launch_command(
                    post_cluster_cfg,
                    post_exe,
                    post_args,
                    config_search_anchor=case_path,
                    extra_search_anchors=[cluster_path],
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                )
                plan["artifacts"].append(post_script)
                stage_meta.update({
                    "mode": "slurm",
                    "script": post_script,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
            else:
                raw_post_cmd = build_local_launch_command(
                    post_exe,
                    post_args,
                    post_num_procs_effective,
                    config_search_anchor=case_path,
                    allow_single_rank_launcher_override=True,
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                )
                post_stream_log = os.path.join(run_dir, "scheduler", f"{run_id}_{output_prefix}.log")
                plan["artifacts"].append(post_stream_log)
                stage_meta.update({
                    "mode": "local",
                    "stream_log": post_stream_log,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
        else:
            stage_meta.update({
                "mode": "slurm" if cluster_mode else "local",
                "launch_command": [],
                "launch_command_string": "",
            })
 
        plan["stages"]["post-process"] = stage_meta
 
    # Preserve insertion order while removing duplicates.
    deduped = []
    seen = set()
    for item in plan["artifacts"]:
        if item not in seen:
            seen.add(item)
            deduped.append(item)
    plan["artifacts"] = deduped
    if run_id and "run_id_preview" not in plan:
        plan["run_id_preview"] = run_id
    if run_dir and "run_dir_preview" not in plan:
        plan["run_dir_preview"] = run_dir
    plan["solver_num_procs_effective"] = solver_num_procs_effective
    plan["post_num_procs_effective"] = post_num_procs_effective
    plan["num_procs_effective"] = solver_num_procs_effective
    return plan
 
 
def add_planned_grid_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add grid-mode-specific staged artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory for relative artifact resolution.
    """
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
 
    mode = grid_cfg.get("mode")
    grid_dir = os.path.join(run_dir, "inputs", "grid")
 
    if mode == "file":
        plan["artifacts"].append(os.path.join(grid_dir, "grid.run"))
    elif mode == "grid_gen":
        generator = grid_cfg.get("generator", {})
        if not isinstance(generator, dict):
            return
        plan["artifacts"].extend([
            os.path.join(grid_dir, "grid.run"),
            os.path.join(grid_dir, "grid.generated.picgrid"),
            os.path.join(run_dir, "output", "analysis", "metrics", "grid.info"),
            os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts"),
        ])
 
def add_planned_profile_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add generated prescribed-flow profile artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory.
    """
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        return
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    has_generated = False
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            has_generated = True
            face_token = _face_artifact_token(bc["face"])
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            generated_path = os.path.join(
                profile_dir, f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice"
            )
            staged_path = os.path.join(profile_dir, f"inlet_profile_block{block_idx}_{face_token}.picslice")
            plan["artifacts"].append(generated_path)
            plan["artifacts"].append(staged_path)
    if has_generated:
        plan["artifacts"].append(os.path.join(profile_dir, "profile.info"))
 
def add_planned_initial_condition_artifacts(plan: dict, case_cfg: dict, solver_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add authoritative file-backed initial-condition artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan receiving artifact paths.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] run_dir Planned run directory.
    """
    source = normalize_eulerian_field_source(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    )
    start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    if source != "solve" or start_step != 0:
        return
    try:
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            U_ref=fluid_scaling["velocity_ref"],
            provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
        )
    except (KeyError, ValueError):
        return
    if resolved["kind"] != "file" and not is_generated_ic_provider(resolved):
        return
    initial_dir = os.path.join(run_dir, "inputs", "initial_condition")
    plan["artifacts"].append(
        os.path.join(initial_dir, f"{resolved['field_name']}00000_0.dat")
    )
    if is_generated_ic_provider(resolved):
        if (case_cfg.get("grid", {}) or {}).get("mode") == "programmatic_c":
            plan["artifacts"].append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        plan["artifacts"].append(os.path.join(initial_dir, "initial_condition.generated.dat"))
        if resolved["kind"] == "spectral_random_velocity":
            plan["artifacts"].extend([
                os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json"),
                os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH),
            ])
 
 
def render_run_dry_plan(plan: dict, output_format: str = "text"):
    """!
    @brief Render dry-run plan in human or JSON format.
    @param[in] plan Dry-run plan produced by build_run_dry_plan().
    @param[in] output_format Either "text" or "json".
    @return 1 when the plan carries blocking findings, 0 otherwise.
    """
    if output_format == "json":
        print(json.dumps(plan, indent=2, sort_keys=True))
        return 1 if plan.get("blocking") else 0
 
    for message in plan.get("warnings", []):
        print(f"[WARN]   {message}", file=sys.stderr)
    if plan.get("blocking"):
        print("[FATAL] This configuration would be refused. The plan below is what the "
              "run WOULD do; it will not get that far:", file=sys.stderr)
        for message in plan["blocking"]:
            print(f"  {message}", file=sys.stderr)
 
    print("\n" + "=" * 60)
    print("                      DRY-RUN PLAN")
    print("=" * 60)
    print(f"  Launch mode    : {plan.get('launch_mode')}")
    print(f"  Created at     : {plan.get('created_at')}")
    if plan.get("run_id_preview"):
        print(f"  Run ID preview : {plan.get('run_id_preview')}")
    if plan.get("run_dir_preview"):
        print(f"  Run dir preview: {plan.get('run_dir_preview')}")
    lineage = plan.get("lineage") or {}
    if lineage.get("relationship") == "branch":
        print(f"  Branched from  : {lineage.get('parent_run_id')} "
              f"@ step {lineage.get('checkpoint_step')} "
              f"(statistics: {lineage.get('statistics_state')})")
    print(f"  Solver MPI procs: {plan.get('solver_num_procs_effective')}")
    print(f"  Post MPI procs  : {plan.get('post_num_procs_effective')}")
    if plan.get("warnings"):
        print("  Warnings       :")
        for warning in plan["warnings"]:
            print(f"    - {warning}")
 
    if plan.get("inputs"):
        print("\n  Inputs:")
        for key, value in plan["inputs"].items():
            print(f"    - {key}: {value}")
 
    if plan.get("stages"):
        print("\n  Planned stage commands:")
        for stage, details in plan["stages"].items():
            print(f"    - {stage} ({details.get('mode')}):")
            if details.get('skip_reason'):
                print(f"      skipped: {details.get('skip_reason')}")
            else:
                print(f"      {details.get('launch_command_string')}")
 
    if plan.get("asset_actions"):
        print("\n  Asset resolution:")
        for item in plan["asset_actions"]:
            print(f"    - {item['kind']}: {item['action']} ({item['provider']})")
 
    diagnostics_artifacts = [item for item in plan.get("artifacts", []) if "PETSc_" in os.path.basename(str(item)) or os.path.basename(str(item)) == "Runtime_Memory.log"]
    if diagnostics_artifacts:
        print("\n  Diagnostics artifacts:")
        for artifact in diagnostics_artifacts:
            print(f"    - {artifact}")
 
    print("\n  Planned artifacts (no files created in dry-run):")
    for artifact in plan.get("artifacts", []):
        print(f"    - {artifact}")
    print("=" * 60)
 
 
def validate_workflow(args):
    """!
    @brief Implements `picurv validate` without launching solver/post workflows.
    @param[in] args Command-line style argument list supplied to the function.
    """
    checked = []
    solver_group_selected = any([args.case, args.solver, args.monitor])
    any_group_selected = solver_group_selected or any([args.post, args.cluster, args.study])
    case_path = None
    cluster_path = None
 
    if not any_group_selected:
        fail_cli_usage(
            "validate requires at least one config group. Provide solver trio and/or --post/--cluster/--study.",
            hint="Example: picurv validate --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml",
        )
 
    if solver_group_selected and not all([args.case, args.solver, args.monitor]):
        fail_cli_usage("When solver validation is requested, --case, --solver, and --monitor are all required.")
 
    # --- Guard: restart flags without solver group ---
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
    run_dir_val = getattr(args, 'run_dir', None)
    if not solver_group_selected:
        if restart_from:
            print("[WARNING] --restart-from has no effect without --case/--solver/--monitor and will be ignored.", file=sys.stderr)
        if continue_run and not args.post:
            print("[WARNING] --continue has no effect without solver configs or --post and will be ignored.", file=sys.stderr)
    if continue_run and not run_dir_val:
        fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
 
    monitor_cfg = None
    case_cfg = None
    if solver_group_selected:
        case_path = os.path.abspath(args.case)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path)
        checked.extend([case_path, solver_path, monitor_path])
 
        # Validate restart flags if provided
        if restart_from or continue_run:
            target_run_dir = os.path.abspath(run_dir_val) if run_dir_val else os.path.abspath("runs/_validate_dummy")
            try:
                resolve_restart_source(args, case_cfg, solver_cfg, monitor_cfg, target_run_dir)
                print("[SUCCESS] Restart source validation passed.")
            except ValueError as e:
                print(f"[ERROR] Restart validation failed: {e}", file=sys.stderr)
                sys.exit(1)
 
    post_cfg = None
    if args.post:
        post_path = os.path.abspath(args.post)
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
        checked.append(post_path)
 
    cluster_cfg = None
    if args.cluster:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        checked.append(cluster_path)
 
    try:
        runtime_execution_path, _ = load_runtime_execution_config(
            case_path,
            extra_search_anchors=[cluster_path] if cluster_path else None,
        )
    except ValueError as exc:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="runtime_execution",
            file_path=case_path or cluster_path or os.getcwd(),
            message=str(exc),
        )
        sys.exit(1)
    if runtime_execution_path:
        checked.append(runtime_execution_path)
 
    study_cfg = None
    if args.study:
        study_path = os.path.abspath(args.study)
        study_cfg = read_yaml_file(study_path)
        validate_study_config(study_cfg, study_path)
        checked.append(study_path)
 
    if post_cfg is not None and run_dir_val:
        post_path = os.path.abspath(args.post)
        validate_run_dir = os.path.abspath(run_dir_val)
        if os.path.isdir(validate_run_dir):
            monitor_for_post = monitor_cfg if solver_group_selected else None
            if monitor_for_post is None:
                config_dir_candidate = os.path.join(validate_run_dir, "config")
                monitor_candidate = os.path.join(config_dir_candidate, "monitor.yml")
                if os.path.isfile(monitor_candidate):
                    monitor_for_post = read_yaml_file(monitor_candidate)
            if monitor_for_post is not None:
                resolved_source = _resolve_post_source_directory_preview(validate_run_dir, monitor_for_post, post_cfg)
                if os.path.isdir(resolved_source) and os.listdir(resolved_source):
                    print(f"[SUCCESS] Post-processor source data directory exists: {resolved_source}")
                else:
                    print(f"[WARNING] Post-processor source data directory is missing or empty: {resolved_source}", file=sys.stderr)
 
    if args.strict and post_cfg is not None:
        post_path = os.path.abspath(args.post)
        source_dir = post_cfg.get("source_data", {}).get("directory")
        if source_dir and source_dir != "<solver_output_dir>":
            resolved = resolve_path(post_path, source_dir)
            if not os.path.isdir(resolved):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="source_data.directory",
                    file_path=post_path,
                    message=f"strict mode: source_data.directory resolves to missing directory '{resolved}'.",
                )
                sys.exit(1)
 
    if args.strict and study_cfg is not None:
        study_path = os.path.abspath(args.study)
        base_cfgs = study_cfg.get("base_configs", {})
        if isinstance(base_cfgs, dict):
            base_case_path = resolve_path(study_path, base_cfgs.get("case"))
            base_solver_path = resolve_path(study_path, base_cfgs.get("solver"))
            base_monitor_path = resolve_path(study_path, base_cfgs.get("monitor"))
            base_post_path = resolve_path(study_path, base_cfgs.get("post"))
            if all([base_case_path, base_solver_path, base_monitor_path]):
                validate_simulation_configs(
                    read_yaml_file(base_case_path),
                    read_yaml_file(base_solver_path),
                    read_yaml_file(base_monitor_path),
                    base_case_path,
                    base_solver_path,
                    base_monitor_path,
                )
            if base_post_path:
                validate_post_config(read_yaml_file(base_post_path), base_post_path,
                                     read_yaml_file(base_monitor_path) if base_monitor_path else None,
                                     read_yaml_file(base_case_path) if base_case_path else None)
 
    print(f"[SUCCESS] Validation completed for {len(checked)} file(s).")
    for path in checked:
        print(f"  - {path}")
 
ASSET_KIND_DIRECTORIES = {
    "grid": "grids",
    "initial-condition": "initial_conditions",
    "inlet-profiles": "inlet_profiles",
}
 
 
def _asset_file_sha256(path: str) -> str:
    """!
    @brief Hash an asset source or payload without loading it into memory.
    @param[in] path File to hash.
    @return Lowercase SHA-256 digest.
    """
    digest = hashlib.sha256()
    with open(path, "rb") as stream:
        for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()
 
 
def _stable_mapping_sha256(payload) -> str:
    """!
    @brief Hash a JSON-compatible value with deterministic serialization.
    @param[in] payload Value to hash.
    @return Lowercase SHA-256 digest.
    """
    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
    return hashlib.sha256(encoded).hexdigest()
 
 
def _provider_source_fingerprints(value, case_path: str, key: str = "") -> dict:
    """!
    @brief Hash every existing file explicitly referenced by an asset provider.
    @param[in] value Provider subtree to inspect.
    @param[in] case_path Owning case configuration path.
    @param[in] key Current dotted key for diagnostics.
    @return Mapping of dotted path identity to path/content fingerprint.
    """
    result = {}
    if isinstance(value, dict):
        for child_key, child in value.items():
            dotted = f"{key}.{child_key}" if key else str(child_key)
            result.update(_provider_source_fingerprints(child, case_path, dotted))
        return result
    if isinstance(value, list):
        for index, child in enumerate(value):
            result.update(_provider_source_fingerprints(child, case_path, f"{key}[{index}]"))
        return result
    basename = key.rsplit(".", 1)[-1]
    if basename not in _ASSET_SOURCE_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
        return result
    try:
        resolved = resolve_workspace_path(case_path, value)
    except ValueError:
        return result
    if os.path.isfile(resolved):
        workspace_root = find_workspace_root(case_path)
        display = (
            os.path.relpath(resolved, workspace_root).replace(os.sep, "/")
            if workspace_root and os.path.commonpath([workspace_root, resolved]) == workspace_root
            else resolved
        )
        result[key] = {"path": display, "sha256": _asset_file_sha256(resolved)}
    return result
 
 
def build_case_asset_graph(case_cfg: dict, case_path: str) -> dict:
    """!
    @brief Classify case inputs into precomputable or simulator-runtime providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Owning case YAML path.
    @return Provider graph with stable identities and explicit dependencies.
    """
    providers = []
    grid_cfg = copy.deepcopy(case_cfg.get("grid", {}) or {})
    grid_mode = str(grid_cfg.get("mode", "")).strip().lower()
    if isinstance(grid_cfg.get("generator"), dict):
        grid_cfg["generator"].pop("output_file", None)
        grid_cfg["generator"].pop("vts_file", None)
        grid_cfg["generator"].pop("stats_file", None)
    grid_provider = {
        "kind": "grid",
        "provider": grid_mode or "missing",
        "execution": "runtime-c" if grid_mode == "programmatic_c" else "precomputable",
        "dependencies": [],
        "spec": grid_cfg,
    }
    providers.append(grid_provider)
 
    initial = copy.deepcopy(
        ((case_cfg.get("properties") or {}).get("initial_conditions") or {})
    )
    initial_mode = str(initial.get("mode", "generated")).strip().lower()
    initial_generator = str(initial.get("generator", "constant")).strip().lower()
    for key in ("output_file", "summary_json", "spectrum_csv"):
        initial.pop(key, None)
        if isinstance(initial.get("params"), dict):
            initial["params"].pop(key, None)
    generated_python = (
        initial_mode == "generated"
        and initial_generator in _PYTHON_INITIAL_CONDITION_PROVIDERS
    )
    initial_provider = {
        "kind": "initial-condition",
        "provider": "file" if initial_mode == "file" else initial_generator,
        "execution": "precomputable" if initial_mode == "file" or generated_python else "runtime-c",
        "dependencies": ["grid"] if generated_python else [],
        "spec": initial,
    }
    providers.append(initial_provider)
 
    inlet_specs = []
    raw_blocks = case_cfg.get("boundary_conditions") or []
    if raw_blocks and isinstance(raw_blocks[0], dict):
        raw_blocks = [raw_blocks]
    for block_index, block in enumerate(raw_blocks):
        for entry in block or []:
            if not isinstance(entry, dict) or str(entry.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = copy.deepcopy(((entry.get("params") or {}).get("source") or {}))
            source.pop("output_file", None)
            inlet_specs.append({"block": block_index, "face": entry.get("face"), "source": source})
    if inlet_specs:
        field_slice = any((item.get("source") or {}).get("type") == "field_slice" for item in inlet_specs)
        providers.append({
            "kind": "inlet-profiles",
            "provider": "prescribed-flow",
            "execution": "precomputable",
            "dependencies": ["grid"] if field_slice or grid_mode in _FILE_BACKED_GRID_VALUES else [],
            "spec": inlet_specs,
        })
 
    # A provider's identity has to cover every case value its build reads, not only its
    # own configuration subtree. The grid build nondimensionalizes by
    # properties.scaling.length_ref and validates against the declared block count;
    # both are outside `grid:`, and a change to either produces different payload bytes
    # from an identical provider spec. Left out, the staleness check reports `reuse`
    # and the solver silently receives geometry scaled by the wrong reference length.
    scaling = (case_cfg.get("properties") or {}).get("scaling") or {}
    fluid = (case_cfg.get("properties") or {}).get("fluid") or {}
    domain_blocks = (case_cfg.get("models") or {}).get("domain", {}).get("blocks", 1)
    build_contexts = {
        "grid": {
            "length_ref": scaling.get("length_ref"),
            "blocks": domain_blocks,
        },
        # The IC build resolves fluid scaling and the prepared boundary conditions.
        "initial-condition": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "density": fluid.get("density"),
            "viscosity": fluid.get("viscosity"),
            "boundary_conditions": case_cfg.get("boundary_conditions"),
        },
        # Profile generation dimensionalizes against the same scaling contract.
        "inlet-profiles": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "blocks": domain_blocks,
        },
    }
 
    # Hash in dependency order so a provider built on top of another re-identifies when
    # the thing it was built from changes.
    by_kind = {provider["kind"]: provider for provider in providers}
    resolved_order = sorted(
        providers, key=lambda provider: len(provider.get("dependencies") or [])
    )
    for provider in resolved_order:
        provider["build_context"] = build_contexts.get(provider["kind"], {})
        provider["source_files"] = _provider_source_fingerprints(provider["spec"], case_path)
        provider["software"] = {
            "release_version": PICURV_RELEASE_VERSION,
            "git_commit": PICURV_BUILD.get("git_commit"),
        }
        provider["spec_sha256"] = _stable_mapping_sha256({
            "kind": provider["kind"],
            "provider": provider["provider"],
            "spec": provider["spec"],
            "build_context": provider["build_context"],
            "source_files": provider["source_files"],
            "software": provider["software"],
            "dependencies": {
                name: by_kind[name].get("spec_sha256")
                for name in (provider.get("dependencies") or [])
                if name in by_kind
            },
        })
    return {
        "case_sha256": _stable_mapping_sha256(case_cfg),
        "providers": providers,
    }
 
 
def _asset_selection(graph: dict, requested=None, *, precomputable_only: bool = False) -> list:
    """!
    @brief Resolve requested asset kinds plus dependency closure.
    @param[in] graph Provider graph returned by build_case_asset_graph.
    @param[in] requested Optional iterable of requested kind names.
    @param[in] precomputable_only Exclude runtime-C providers for normal-run staging.
    @return Ordered provider list.
    """
    by_kind = {item["kind"]: item for item in graph["providers"]}
    requested_set = set(requested or by_kind)
    unknown = requested_set - set(by_kind)
    if unknown:
        raise ValueError(
            f"No configured provider exists for asset kind(s): {sorted(unknown)}. "
            f"Configured kinds: {sorted(by_kind)}."
        )
    closure = set()
 
    def add(kind):
        """!
        @brief Add one requested asset kind and its dependency closure.
        @param[in] kind Asset kind to include.
        @return None.
        """
        if kind in closure:
            return
        closure.add(kind)
        for dependency in by_kind[kind].get("dependencies", []):
            if dependency in by_kind:
                add(dependency)
 
    for kind in requested_set:
        add(kind)
    selected = [item for item in graph["providers"] if item["kind"] in closure]
    if precomputable_only:
        selected = [item for item in selected if item["execution"] == "precomputable"]
    return selected
 
 
def _asset_payload_files(build_root: str, kind: str) -> list:
    """!
    @brief Enumerate canonical files belonging to one asset kind in a build tree.
    @param[in] build_root Temporary run-like build root.
    @param[in] kind Asset kind.
    @return Absolute payload file paths.
    """
    roots = {
        "grid": ["inputs/grid", "output/analysis/metrics", "output/visualization/precompute"],
        "initial-condition": ["inputs/initial_condition", "output/analysis/spectra", "output/analysis/metrics"],
        "inlet-profiles": ["inputs/inlet_profiles"],
    }[kind]
    result = []
    for relative in roots:
        root = Path(build_root, *relative.split("/"))
        if root.is_dir():
            result.extend(str(path) for path in sorted(root.rglob("*")) if path.is_file())
    intermediate_names = {
        "grid": {"grid.generated.picgrid", "grid.converted.picgrid"},
        "initial-condition": {"initial_condition.generated.dat"},
        "inlet-profiles": set(),
    }[kind]
    return [
        path for path in dict.fromkeys(result)
        if os.path.basename(path) not in intermediate_names
    ]
 
 
def _build_selected_asset_payloads(build_root: str, case_cfg: dict, case_path: str,
                                   selected: list) -> dict:
    """!
    @brief Execute existing generators into one isolated run-like build tree.
    @param[in] build_root Temporary output root.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Owning case path.
    @param[in] selected Ordered selected providers.
    @return Asset-kind to generated file list.
    """
    ensure_run_layout(build_root)
    selected_kinds = {item["kind"] for item in selected}
    payloads = {}
 
    def fingerprint(kind):
        """!
        @brief Snapshot current payload checksums for one asset kind.
        @param[in] kind Asset kind to inspect.
        @return Absolute-path to checksum mapping.
        """
        return {
            path: _asset_file_sha256(path)
            for path in _asset_payload_files(build_root, kind)
        }
 
    def record_changes(kind, before):
        """!
        @brief Record files created or changed by one provider stage.
        @param[in] kind Asset kind whose build just completed.
        @param[in] before Pre-build checksum mapping.
        @return None.
        """
        after = fingerprint(kind)
        payloads[kind] = [
            path for path, digest in after.items()
            if before.get(path) != digest
        ]
 
    grid_cfg = case_cfg.get("grid", {}) or {}
    scaling = (case_cfg.get("properties", {}) or {}).get("scaling", {}) or {}
    length_ref = float(scaling.get("length_ref", 1.0))
    expected_nblk = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    staged_grid = os.path.join(build_root, "inputs", "grid", "grid.run")
    if "grid" in selected_kinds:
        before = fingerprint("grid")
        if grid_cfg.get("mode") == "grid_gen":
            generated = run_grid_generator(case_path, build_root, grid_cfg, case_cfg=case_cfg)
            validate_and_nondimensionalize_picgrid(
                generated, staged_grid, length_ref, expected_nblk=expected_nblk
            )
        elif grid_cfg.get("mode") == "file":
            source = _resolve_case_relative_path(
                grid_cfg.get("source_file"), os.path.dirname(os.path.abspath(case_path))
            )
            validate_and_nondimensionalize_picgrid(
                source, staged_grid, length_ref, expected_nblk=expected_nblk
            )
        record_changes("grid", before)
 
    if "inlet-profiles" in selected_kinds:
        before = fingerprint("inlet-profiles")
        generate_multi_block_bcs(
            build_root, "asset-build", case_cfg,
            {"Case": case_path},
        )
        record_changes("inlet-profiles", before)
 
    if "initial-condition" in selected_kinds:
        before = fingerprint("initial-condition")
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved_ic = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            U_ref=fluid_scaling["velocity_ref"],
            provider_context={
                "kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]
            },
        )
        if (grid_cfg.get("mode") == "programmatic_c" and is_generated_ic_provider(resolved_ic)
                and not os.path.isfile(staged_grid)):
            # "grid" is excluded from this closure when the caller passed
            # precomputable_only=True (materialize_run_assets, staging before a solve): a
            # runtime-C grid is never itself precomputed. But the Python IC generator run
            # below is a separate process from the solver and needs real coordinates on
            # disk regardless. This bridge uses the identical formula as
            # ComputeStretchedCoord in src/grid.c, so it is guaranteed to match what the
            # solver builds moments later; it is not published as its own asset, since a
            # programmatic_c grid is never a persisted asset in its own right.
            generate_picgrid_from_programmatic_settings(
                grid_cfg.get("programmatic_settings", {}), staged_grid, length_ref
            )
        stage_initial_condition_file(build_root, case_path, resolved_ic)
        record_changes("initial-condition", before)
    return payloads
 
 
#: Largest grid, in nodes, for which a published asset carries an inline VTS preview.
#: Beyond this the ASCII payload costs more than the inspection is worth, and
#: validation.json records that it was skipped rather than silently omitting it.
ASSET_PREVIEW_NODE_LIMIT = 2_000_000
 
 
def _picgrid_geometry_summary(path: str) -> dict:
    """!
    @brief Read a canonical PICGRID and summarize what a user would want to check.
    @param[in] path Staged PICGRID file.
    @return Mapping of block dimensions, bounds, and spacing extremes.
    """
    dims = read_picgrid_header_dimensions(path)
    bounds = [[float("inf")] * 3, [float("-inf")] * 3]
    nodes = 0
    with open(path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        # Header token, block count, and one dimension row per block.
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) != 3:
                continue
            try:
                point = [float(value) for value in parts]
            except ValueError:
                continue
            nodes += 1
            for axis in range(3):
                bounds[0][axis] = min(bounds[0][axis], point[axis])
                bounds[1][axis] = max(bounds[1][axis], point[axis])
    extent = [bounds[1][axis] - bounds[0][axis] for axis in range(3)] if nodes else [0.0, 0.0, 0.0]
    return {
        "blocks": len(dims),
        "dimensions": [list(item) for item in dims],
        "total_nodes": nodes,
        "bounds_min": bounds[0] if nodes else None,
        "bounds_max": bounds[1] if nodes else None,
        "extent": extent,
    }
 
 
def _write_structured_grid_preview(picgrid_path: str, destination: str, dims) -> bool:
    """!
    @brief Write a single-block ASCII VTS preview of a staged PICGRID.
 
    @details Only the first block is written: the preview exists so a user can confirm
             the shape they configured, not to reproduce the solver's view of a
             multi-block domain.
    @param[in] picgrid_path Staged PICGRID file.
    @param[in] destination Preview path to write.
    @param[in] dims Per-block dimension triples.
    @return True when a preview was written.
    """
    if not dims:
        return False
    im, jm, km = (int(value) for value in dims[0])
    if im * jm * km > ASSET_PREVIEW_NODE_LIMIT:
        return False
    coordinates = []
    with open(picgrid_path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) == 3:
                coordinates.append(line)
            if len(coordinates) >= im * jm * km:
                break
    if len(coordinates) < im * jm * km:
        return False
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    with open(destination, "w", encoding="utf-8") as out:
        extent = f"0 {im - 1} 0 {jm - 1} 0 {km - 1}"
        out.write('<?xml version="1.0"?>\n')
        out.write('<VTKFile type="StructuredGrid" version="1.0" byte_order="LittleEndian">\n')
        out.write(f'  <StructuredGrid WholeExtent="{extent}">\n')
        out.write(f'    <Piece Extent="{extent}">\n')
        out.write('      <Points>\n')
        out.write('        <DataArray type="Float64" NumberOfComponents="3" format="ascii">\n')
        for row in coordinates:
            out.write(f"          {row}\n")
        out.write('        </DataArray>\n      </Points>\n')
        out.write('    </Piece>\n  </StructuredGrid>\n</VTKFile>\n')
    return True
 
 
def _build_asset_inspection(kind: str, build_root: str, provider: dict,
                            payload_files: list) -> dict:
    """!
    @brief Produce the inspection material published beside an asset's payload.
 
    @details Precompute exists so a user can look at a grid, field, or profile and
             change it before committing a solve. An asset that carries only opaque
             solver input cannot serve that purpose, so every published object gets a
             validation record and, where it is affordable, a preview.
    @param[in] kind Asset kind.
    @param[in] build_root Temporary build tree.
    @param[in] provider Provider metadata for the asset.
    @param[in] payload_files Absolute payload paths produced for this asset.
    @return Mapping of published inspection filename to its absolute source path.
    """
    inspection_dir = os.path.join(build_root, ".inspection")
    os.makedirs(inspection_dir, exist_ok=True)
    published = {}
    validation = {
        "asset_kind": kind,
        "provider": provider["provider"],
        "generated_at": datetime.now().astimezone().isoformat(),
        "files": [os.path.relpath(path, build_root).replace(os.sep, "/") for path in payload_files],
    }
 
    if kind == "grid":
        staged = os.path.join(build_root, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            try:
                geometry = _picgrid_geometry_summary(staged)
                validation["geometry"] = geometry
                preview = os.path.join(inspection_dir, "preview.vts")
                if _write_structured_grid_preview(staged, preview, geometry["dimensions"]):
                    published["preview.vts"] = preview
                else:
                    validation["preview"] = (
                        "skipped: the first block exceeds "
                        f"{ASSET_PREVIEW_NODE_LIMIT} nodes"
                    )
            except (OSError, ValueError, StopIteration) as exc:
                validation["geometry_error"] = str(exc)
        generator_preview = os.path.join(
            build_root, "output", "visualization", "precompute", "grid.vts"
        )
        if os.path.isfile(generator_preview):
            published["preview.vts"] = generator_preview
            validation.pop("preview", None)
        info = os.path.join(build_root, "output", "analysis", "metrics", "grid.info")
        if os.path.isfile(info):
            published["grid.info"] = info
 
    elif kind == "initial-condition":
        # The generators name these for the run tree they were written into; the asset
        # publishes them under the names the object contract uses.
        for published_name, suffix in (
            ("summary.json", "_summary.json"), ("spectrum.csv", "_spectrum.csv"),
        ):
            for candidate in payload_files:
                base = os.path.basename(candidate)
                if base == published_name or base.endswith(suffix):
                    published[published_name] = candidate
                    break
        validation["fields"] = sorted(
            os.path.basename(path) for path in payload_files if path.endswith(".dat")
        )
        summary_source = published.get("summary.json")
        if summary_source:
            try:
                with open(summary_source, "r", encoding="utf-8") as stream:
                    validation["summary"] = json.load(stream)
            except (OSError, ValueError):
                pass
 
    elif kind == "inlet-profiles":
        for candidate in payload_files:
            if os.path.basename(candidate) == "profile.info":
                published["profile.info"] = candidate
        validation["profiles"] = sorted(
            os.path.basename(path) for path in payload_files
            if path.endswith(".picslice")
        )
 
    validation_path = os.path.join(inspection_dir, "validation.json")
    write_json_file(validation_path, validation)
    published["validation.json"] = validation_path
    return published
 
 
def _publish_asset_object(workspace_root: str, build_root: str, provider: dict,
                          payload_files: list) -> dict:
    """!
    @brief Publish one immutable content-addressed asset object atomically.
    @param[in] workspace_root Owning workspace.
    @param[in] build_root Temporary build root.
    @param[in] provider Provider metadata.
    @param[in] payload_files Files produced for the provider.
    @return Asset reference written to the asset set.
    """
    file_inventory = []
    for path in payload_files:
        relative = os.path.relpath(path, build_root).replace(os.sep, "/")
        file_inventory.append({
            "path": relative,
            "bytes": os.path.getsize(path),
            "sha256": _asset_file_sha256(path),
        })
    asset_id = _stable_mapping_sha256({
        "provider_spec_sha256": provider["spec_sha256"],
        "files": file_inventory,
    })
    # Identity is the payload's; inspection material describes it and must not change
    # which object a run resolves to.
    inspection = _build_asset_inspection(
        provider["kind"], build_root, provider, payload_files
    )
    kind_dir = ASSET_KIND_DIRECTORIES[provider["kind"]]
    object_root = os.path.join(workspace_root, "assets", "objects", kind_dir, asset_id)
    if not os.path.isdir(object_root):
        parent = os.path.dirname(object_root)
        os.makedirs(parent, exist_ok=True)
        temporary = tempfile.mkdtemp(prefix=f".{asset_id[:12]}-", dir=parent)
        try:
            for item, source in zip(file_inventory, payload_files):
                destination = os.path.join(temporary, "payload", *item["path"].split("/"))
                os.makedirs(os.path.dirname(destination), exist_ok=True)
                shutil.copy2(source, destination)
            for name, source in sorted(inspection.items()):
                shutil.copy2(source, os.path.join(temporary, name))
            manifest = {
                "schema_version": ASSET_MANIFEST_SCHEMA_VERSION,
                "asset_id": asset_id,
                "kind": provider["kind"],
                "provider": provider["provider"],
                "provider_execution": provider["execution"],
                "provider_spec_sha256": provider["spec_sha256"],
                "provider_spec": provider["spec"],
                "source_files": provider["source_files"],
                "software": provider["software"],
                "created_at": datetime.now().astimezone().isoformat(),
                "files": file_inventory,
                "inspection": sorted(inspection),
            }
            write_json_file(os.path.join(temporary, "asset.json"), manifest)
            try:
                os.replace(temporary, object_root)
            except OSError as exc:
                if exc.errno != errno.ENOTEMPTY and not os.path.isdir(object_root):
                    raise
        finally:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary, ignore_errors=True)
    return {
        "asset_id": asset_id,
        "kind": provider["kind"],
        "provider": provider["provider"],
        "provider_spec_sha256": provider["spec_sha256"],
        "object": os.path.relpath(object_root, workspace_root).replace(os.sep, "/"),
        "files": file_inventory,
        "inspection": sorted(inspection),
    }
 
 
def _workspace_asset_set_name(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return a collision-free, readable mutable asset-set name.
    @param[in] workspace_root Owning initialized workspace.
    @param[in] case_path Source case configuration path.
    @return Stable asset-set filename stem.
    """
    stem = re.sub(r"[^A-Za-z0-9_.-]+", "-", Path(case_path).stem).strip("-") or "case"
    relative = _relative_to_workspace(case_path, workspace_root) or os.path.abspath(case_path)
    digest = hashlib.sha256(str(relative).encode("utf-8")).hexdigest()[:10]
    return f"{stem}-{digest}"
 
 
def _write_workspace_asset_set(workspace_root: str, case_path: str, graph: dict,
                               references: dict) -> str:
    """!
    @brief Atomically update the named asset set and workspace asset catalog.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case YAML.
    @param[in] graph Complete provider graph.
    @param[in] references Newly published or reused asset references.
    @return Asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    set_path = os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
    existing = read_yaml_file(set_path) if os.path.isfile(set_path) else {}
    assets = dict(existing.get("assets") or {})
    assets.update(references)
    payload = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "name": name,
        "case": os.path.relpath(case_path, workspace_root).replace(os.sep, "/"),
        "case_sha256": graph["case_sha256"],
        "updated_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": {
            item["kind"]: {
                "provider": item["provider"],
                "provider_spec_sha256": item["spec_sha256"],
            }
            for item in graph["providers"] if item["execution"] == "runtime-c"
        },
    }
    write_yaml_file(set_path, payload)
    catalog_path = os.path.join(workspace_root, "assets", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "objects": {}
    }
    objects = catalog.setdefault("objects", {})
    for reference in references.values():
        objects[reference["asset_id"]] = {
            "kind": reference["kind"],
            "provider": reference["provider"],
            "object": reference["object"],
        }
    write_yaml_file(catalog_path, catalog)
    return set_path
 
 
def precompute_case_assets(workspace_root: str, case_cfg: dict, case_path: str,
                           requested=None, precomputable_only: bool = False) -> dict:
    """!
    @brief Build and publish a selected deterministic asset dependency closure.
    @param[in] workspace_root Owning workspace.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @param[in] requested Requested asset kinds, or all configured providers.
    @param[in] precomputable_only Drop runtime-C dependencies from the closure instead of
                                  refusing. For internal run-staging only: a run legitimately
                                  depends on a runtime-C grid that its own solver builds
                                  moments later, so its presence in the dependency closure is
                                  expected there, not an error. The standalone `picurv
                                  precompute` command leaves this False, since nothing will
                                  ever build a runtime-C provider in that context.
    @return Provider graph, selected providers, references, and asset-set path.
    """
    enforce_workspace_version(workspace_root)
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested, precomputable_only=precomputable_only)
    if not precomputable_only:
        runtime = [item for item in selected if item["execution"] == "runtime-c"]
        if runtime:
            details = ", ".join(f"{item['kind']}={item['provider']}" for item in runtime)
            raise ValueError(
                "Precompute is atomic and cannot execute simulator-runtime providers. "
                f"Selected dependency graph requires C generation: {details}. "
                "Use --only to select an independent precomputable subset, or run the case; "
                "the simulator will report each runtime provider before generation."
            )
    if not selected:
        raise ValueError("The selected case has no precomputable providers.")
    staging_parent = os.path.join(workspace_root, "assets")
    os.makedirs(staging_parent, exist_ok=True)
    build_root = tempfile.mkdtemp(prefix=".precompute-", dir=staging_parent)
    references = {}
    try:
        payloads = _build_selected_asset_payloads(build_root, case_cfg, case_path, selected)
        for provider in selected:
            files = payloads.get(provider["kind"], [])
            if not files:
                raise ValueError(
                    f"Provider {provider['kind']}={provider['provider']} produced no files."
                )
            references[provider["kind"]] = _publish_asset_object(
                workspace_root, build_root, provider, files
            )
    finally:
        shutil.rmtree(build_root, ignore_errors=True)
    set_path = _write_workspace_asset_set(workspace_root, case_path, graph, references)
    return {"graph": graph, "selected": selected, "assets": references, "set_path": set_path}
 
 
def _workspace_asset_set_path(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return the mutable asset-set pointer associated with a case config name.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case path.
    @return Absolute asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    return os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
 
 
def plan_run_assets(case_cfg: dict, case_path: str) -> dict:
    """!
    @brief Plan reuse/build/runtime actions for all configured run providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @return Workspace, graph, set path, and per-provider actions.
    """
    workspace_root = find_workspace_root(case_path)
    graph = build_case_asset_graph(case_cfg, case_path)
    asset_set = {}
    set_path = None
    if workspace_root:
        set_path = _workspace_asset_set_path(workspace_root, case_path)
        if os.path.isfile(set_path):
            asset_set = read_yaml_file(set_path)
    refs = asset_set.get("assets", {}) if isinstance(asset_set, dict) else {}
    actions = []
    for provider in graph["providers"]:
        reference = refs.get(provider["kind"]) if isinstance(refs, dict) else None
        matches = bool(
            isinstance(reference, dict)
            and reference.get("provider_spec_sha256") == provider["spec_sha256"]
            and workspace_root
            and os.path.isfile(os.path.join(
                workspace_root, reference.get("object", ""), "asset.json"
            ))
        )
        if provider["execution"] == "runtime-c":
            action = "runtime-c"
        elif matches:
            action = "reuse"
        else:
            action = "build"
        actions.append({**provider, "action": action, "reference": reference if matches else None})
    return {
        "workspace_root": workspace_root,
        "graph": graph,
        "asset_set_path": set_path,
        "actions": actions,
    }
 
 
def _materialize_asset_file(source: str, destination: str) -> str:
    """!
    @brief Expose one immutable shared-asset file through reflink, hardlink, or copy.
    @param[in] source Immutable asset payload file.
    @param[in] destination Run-local destination.
    @return Materialization mode used.
    """
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    temporary = f"{destination}.tmp.{os.getpid()}"
    try:
        cp = shutil.which("cp")
        if cp:
            result = subprocess.run(
                [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                text=True, capture_output=True, check=False,
            )
            if result.returncode == 0:
                os.replace(temporary, destination)
                return "reflink"
            if os.path.lexists(temporary):
                os.remove(temporary)
        try:
            os.link(source, temporary)
            os.replace(temporary, destination)
            return "hardlink"
        except OSError:
            if os.path.lexists(temporary):
                os.remove(temporary)
        shutil.copy2(source, temporary)
        os.replace(temporary, destination)
        return "copy"
    finally:
        if os.path.lexists(temporary):
            os.remove(temporary)
 
 
def materialize_run_assets(run_dir: str, case_cfg: dict, case_path: str,
                           require_precomputed: bool = False,
                           fetch_missing: bool = False) -> dict:
    """!
    @brief Resolve/build workspace assets and write the exact run input lock.
    @param[in] run_dir Run receiving immutable input exposures.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Source case path.
    @param[in] require_precomputed Refuse any missing deterministic asset.
    @param[in] fetch_missing Request remote fetch before local build.
    @return Written lock mapping, or a standalone-provider summary outside a workspace.
    """
    plan = plan_run_assets(case_cfg, case_path)
    workspace_root = plan["workspace_root"]
    if not workspace_root:
        return {
            "schema_version": ASSET_LOCK_SCHEMA_VERSION,
            "workspace": None,
            "assets": {},
            "runtime_providers": {
                item["kind"]: item["provider"] for item in plan["actions"]
                if item["execution"] == "runtime-c"
            },
        }
    enforce_workspace_version(workspace_root)
    missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and fetch_missing:
        # Storage imports this module indirectly, so remote asset recovery is routed
        # through a late import that cannot create a module cycle at startup.
        try:
            from .storage import restore_missing_workspace_assets
        except ImportError:
            restore_missing_workspace_assets = getattr(
                _storage_module, "restore_missing_workspace_assets", None
            )
        restored = restore_missing_workspace_assets(
            workspace_root, [item["spec_sha256"] for item in missing]
        ) if restore_missing_workspace_assets else {}
        if restored:
            recovered_refs = {
                item["kind"]: restored[item["spec_sha256"]]
                for item in missing if item["spec_sha256"] in restored
            }
            if recovered_refs:
                _write_workspace_asset_set(
                    workspace_root, case_path, plan["graph"], recovered_refs
                )
            plan = plan_run_assets(case_cfg, case_path)
            missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and require_precomputed:
        names = ", ".join(f"{item['kind']}={item['provider']}" for item in missing)
        raise ValueError(
            f"Required precomputed asset(s) are missing or stale: {names}. "
            f"Run 'picurv precompute --case {case_path} --only "
            + ",".join(item["kind"] for item in missing) + "'."
        )
    if missing:
        precompute_case_assets(
            workspace_root, case_cfg, case_path,
            requested=[item["kind"] for item in missing],
            precomputable_only=True,
        )
        plan = plan_run_assets(case_cfg, case_path)
        still_missing = [item for item in plan["actions"] if item["action"] == "build"]
        if still_missing:
            raise ValueError(
                "Asset generation completed without satisfying: "
                + ", ".join(item["kind"] for item in still_missing)
            )
 
    assets = {}
    for item in plan["actions"]:
        reference = item.get("reference")
        if item["action"] != "reuse" or not isinstance(reference, dict):
            continue
        object_root = os.path.join(workspace_root, reference["object"])
        manifest = _read_json_if_exists(os.path.join(object_root, "asset.json"))
        if not isinstance(manifest, dict) or manifest.get("asset_id") != reference.get("asset_id"):
            raise ValueError(f"Asset object is missing or invalid: {object_root}")
        exposed = []
        for file_info in manifest.get("files", []):
            relative = file_info["path"]
            source = os.path.join(object_root, "payload", *relative.split("/"))
            if _asset_file_sha256(source) != file_info.get("sha256"):
                raise ValueError(f"Asset payload checksum mismatch: {source}")
            destination = os.path.join(run_dir, *relative.split("/"))
            mode = _materialize_asset_file(source, destination)
            exposed.append({"path": relative, "mode": mode, "sha256": file_info["sha256"]})
        assets[item["kind"]] = {**reference, "exposed": exposed}
        print(f"[INFO] Asset {item['kind']}: reuse {reference['asset_id']}")
    runtime_providers = {
        item["kind"]: {
            "provider": item["provider"],
            "provider_spec_sha256": item["spec_sha256"],
        }
        for item in plan["actions"] if item["execution"] == "runtime-c"
    }
    for kind, provider in runtime_providers.items():
        print(f"[INFO] Runtime provider {kind}: {provider['provider']} (generated by simulator)")
    lock = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "workspace": workspace_root,
        "case_sha256": plan["graph"]["case_sha256"],
        "created_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": runtime_providers,
    }
    write_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml"), lock)
    write_software_lock(run_dir)
    return lock
 
 
def precompute_workflow(args):
    """!
    @brief Resolve, preflight, and atomically publish reusable workspace assets.
    @param[in] args Parsed precompute command arguments.
    """
    case_path = os.path.abspath(args.case)
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError(
            "Precompute requires an initialized PICurv workspace. Run 'picurv init ...', "
            "then use its config/case.yml."
        )
    case_cfg = read_yaml_file(case_path)
    raw_only = getattr(args, "only", None)
    requested = None
    if raw_only and str(raw_only).strip().lower() != "all":
        requested = [token.strip() for token in str(raw_only).split(",") if token.strip()]
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested)
    print(f"[INFO] Workspace : {workspace_root}")
    print(f"[INFO] Case      : {os.path.relpath(case_path, workspace_root)}")
    print("[INFO] Asset dependency plan:")
    for provider in selected:
        dependencies = ",".join(provider.get("dependencies", [])) or "none"
        print(
            f"  - {provider['kind']}: {provider['provider']} "
            f"[{provider['execution']}], dependencies={dependencies}"
        )
    result = precompute_case_assets(workspace_root, case_cfg, case_path, requested=requested)
    for kind, reference in sorted(result["assets"].items()):
        print(f"[SUCCESS] {kind}: {reference['asset_id']} ({reference['object']})")
    print(f"[SUCCESS] Asset set: {os.path.relpath(result['set_path'], workspace_root)}")
 
def run_workflow(args):
    """!
    @brief Main orchestrator for the 'run' command (local and Slurm modes).
    @param[in] args Command-line style argument list supplied to the function.
    """
    if getattr(args, "dry_run", False):
        plan = build_run_dry_plan(args)
        render_run_dry_plan(plan, output_format=getattr(args, "output_format", "text"))
        if plan.get("blocking"):
            sys.exit(1)
        return
 
    run_dir = None
    run_id = None
    output_dir_abs = None
    # A post-only invocation never resolves a restart source, so this stays None and
    # `build_run_manifest()` preserves whatever lineage the run was created with.
    run_lineage = None
    statistics_output_paths = []
    workflow_start = time.time()
    stages_completed = []
    configs = None
    submission_meta = {"launch_mode": "local", "no_submit": bool(args.no_submit), "stages": {}}
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            print(
                f"[FATAL] --scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
                file=sys.stderr
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            print(f"[FATAL] Unsupported scheduler '{scheduler_type}'. Only Slurm is supported in v1.", file=sys.stderr)
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            print(
                "[FATAL] In cluster mode, --num-procs must be "
                f"1 (auto) or exactly nodes*ntasks_per_node ({cluster_tasks}).",
                file=sys.stderr
            )
            sys.exit(1)
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        submission_meta["launch_mode"] = "slurm"
        submission_meta["cluster_config"] = cluster_path
        submission_meta["no_submit"] = bool(args.no_submit)
        if args.solve and args.post_process:
            print(
                f"[INFO] Cluster mode enabled (Slurm). Solver and post stages use "
                f"{solver_num_procs_effective} MPI tasks from cluster.yml."
            )
        elif args.solve:
            print(f"[INFO] Cluster mode enabled (Slurm). Solver uses {solver_num_procs_effective} MPI tasks from cluster.yml.")
        else:
            print(f"[INFO] Cluster mode enabled (Slurm). Post stage uses {post_num_procs_effective} MPI tasks from cluster.yml.")
    elif getattr(args, "scheduler", None):
        print("[FATAL] --scheduler requires --cluster in this version.", file=sys.stderr)
        sys.exit(1)
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False) and not args.post_process:
            print("[WARNING] --continue has no effect without --solve or --post-process and will be ignored.", file=sys.stderr)
 
    # --- Stage 1: Solver (if requested) ---
    if args.solve:
        case_input_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_input_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        walltime_guard_policy = resolve_walltime_guard_policy(cluster_cfg) if cluster_mode else None
        configs = {
            'case': read_yaml_file(args.case), 'case_path': case_input_path,
            'solver': read_yaml_file(args.solver), 'solver_path': os.path.abspath(args.solver),
            'monitor': read_yaml_file(args.monitor), 'monitor_path': os.path.abspath(args.monitor),
            'walltime_guard_policy': walltime_guard_policy,
            'statistics_state': getattr(args, "statistics_state", None) or "reset",
        }
 
        print("\n[INFO] Validating configuration files...")
        validate_simulation_configs(
            configs['case'], configs['solver'], configs['monitor'],
            args.case, args.solver, args.monitor
        )
        print("[SUCCESS] All configuration files passed validation.\n")
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(
                runs_root, configs["case"], configs["case_path"]
            )
            run_dir = os.path.join(runs_root, run_id)
 
        if workspace_root and os.path.commonpath([os.path.abspath(run_dir), workspace_root]) != workspace_root:
            fail_cli_usage("A workspace run directory must remain below the owning workspace.")
        if not continue_mode and os.path.exists(run_dir):
            raise ValueError(f"Generated run directory already exists: {run_dir}")
        ensure_run_layout(run_dir)
        # Checked after the skeleton exists so a resumed run is judged on what is
        # actually there, and before any stage writes into it.
        enforce_run_directory_structure(run_dir)
 
        try:
            resolved_restart_source_dir, is_continue, run_lineage = resolve_restart_source(
                args, configs["case"], configs["solver"], configs["monitor"], run_dir
            )
        except ValueError as e:
            # Restart resolution is the first thing that can refuse a run, and the
            # skeleton is already on disk. Leaving it behind puts an empty directory in
            # runs/ that is indistinguishable from a real run to `ls`, to storage
            # status, and to anyone browsing the workspace, once per refused attempt.
            discard_unused_run_directory(run_dir, created=not continue_mode)
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=args.case,
                message=str(e),
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        if continue_mode:
            print(f"[INFO] Continuing in existing run directory: {os.path.relpath(run_dir)}")
        else:
            print(f"[INFO] Created new self-contained run directory: {os.path.relpath(run_dir)}")
 
        active_config = snapshot_run_configuration(
            run_dir,
            {
                "case": args.case,
                "solver": args.solver,
                "monitor": args.monitor,
                "cluster": cluster_path if cluster_mode else None,
            },
            continuation=continue_mode,
        )
        asset_lock = materialize_run_assets(
            run_dir,
            configs["case"],
            configs["case_path"],
            require_precomputed=bool(getattr(args, "require_precomputed", False)),
            fetch_missing=bool(getattr(args, "fetch_missing", False)),
        )
 
        print("\n" + "="*25 + " SOLVER STAGE " + "="*25)
        source_files = {'Case': args.case, 'Solver': args.solver, 'Monitor': args.monitor}
        generated_config_dir = (
            config_dir if active_config["revision"] == "initial"
            else os.path.join(config_dir, "history", active_config["revision"])
        )
        monitor_files = prepare_monitor_files(
            run_dir, run_id, configs['monitor'], source_files,
            config_dir=generated_config_dir,
        )
        if resolved_restart_source_dir:
            print(f"[INFO] Restart source: {resolved_restart_source_dir}")
        if is_continue:
            print("[INFO] Continue mode: logs will be appended, not overwritten.")
        control_file = generate_solver_control_file(
            run_dir,
            run_id,
            configs,
            solver_num_procs_effective,
            monitor_files,
            restart_source_dir=resolved_restart_source_dir,
            continue_mode=is_continue,
            config_dir=generated_config_dir,
        )
        active_config = archive_active_generated_configuration(
            run_dir,
            [
                control_file,
                monitor_files.get("whitelist"),
                monitor_files.get("profile"),
                *glob.glob(os.path.join(generated_config_dir, "bcs*.run")),
            ],
        )
        control_file = load_active_run_configuration(run_dir).get("control", control_file)
 
        solver_exe = resolve_runtime_executable("simulator")
        # Staging is the last point before the binary's identity becomes the one written
        # into this run's checkpoints, so a stale build is worth saying out loud here.
        warn_on_stale_runtime_binaries(runtime_build_identities())
        solver_args = build_petsc_diagnostics_args(configs["monitor"], run_dir, "Solver") + ["-control_file", control_file]
        if cluster_mode:
            scheduler_dir = os.path.join(run_dir, "scheduler")
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_log = os.path.join(scheduler_dir, "solver_%j.out")
            solver_err = os.path.join(scheduler_dir, "solver_%j.err")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=args.case,
                extra_search_anchors=[cluster_path],
            )
            render_slurm_script(
                solver_script,
                f"{run_id}_solve",
                cluster_cfg,
                solver_cmd,
                run_dir,
                solver_log,
                solver_err,
                env_vars={"LOG_LEVEL": configs['monitor'].get('logging', {}).get('verbosity', 'INFO').upper()},
                shell_env_vars=build_walltime_guard_exports(cluster_cfg),
            )
            submission_meta["stages"]["solve"] = {
                "script": solver_script,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
            }
            print(f"[SUCCESS] Generated solver Slurm script: {os.path.relpath(solver_script)}")
            if not args.no_submit:
                submit_info = submit_sbatch(solver_script)
                submission_meta["stages"]["solve"].update(submit_info)
                submission_meta["stages"]["solve"]["submitted"] = True
                print(f"[SUCCESS] Submitted solver job: {submit_info['job_id']}")
            stages_completed.append('solve')
        else:
            command = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=configs["case_path"],
            )
            solver_log = os.path.join("scheduler", f"{run_id}_solver.log")
            submission_meta["stages"]["solve"] = {
                "command": command,
                "command_string": format_command_for_display(command),
                "log_file": solver_log,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
            }
            if args.no_submit:
                print(f"[SUCCESS] Staged local solver command: {solver_log}")
            else:
                try:
                    with runtime_stage_lock(run_dir, "solver"):
                        execute_command(command, run_dir, solver_log, configs['monitor'])
                except StorageError as exc:
                    print(f"[FATAL] {exc}", file=sys.stderr)
                    sys.exit(1)
                submission_meta["stages"]["solve"]["submitted"] = True
                submission_meta["stages"]["solve"]["executed"] = True
                submission_meta["stages"]["solve"]["completed_at"] = datetime.now().isoformat()
            stages_completed.append('solve')
 
    # --- Stage 2: Post-Processing (if requested) ---
    if args.post_process:
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                print(f"[FATAL] Specified run directory not found: {run_dir}", file=sys.stderr)
                sys.exit(1)
            print(f"[INFO] Operating on existing run directory: {os.path.relpath(run_dir)}")
            enforce_run_directory_structure(run_dir)
            run_id = read_artifact_identity(run_dir)["run_id"]
        elif not args.solve:
            print("[FATAL] --post-process requires --run-dir when not used with --solve.", file=sys.stderr)
            sys.exit(1)
 
        print("\n" + "="*20 + " POST-PROCESSING STAGE " + "="*20)
        config_dir = os.path.join(run_dir, "config")
        case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
 
        if not all([case_path, monitor_path, solver_control_path]):
            print(f"[FATAL] Could not automatically identify required config files in {config_dir}", file=sys.stderr)
            if not case_path:
                print("         - No 'case' file found (expected 'models' + 'boundary_conditions').", file=sys.stderr)
            if not monitor_path:
                print("         - No 'monitor' file found (expected 'io' + 'logging').", file=sys.stderr)
            if not solver_control_path:
                print("         - No '.control' file found.", file=sys.stderr)
            sys.exit(1)
 
        print(f"[INFO] Auto-identified Case file:    {os.path.basename(case_path)}")
        print(f"[INFO] Auto-identified Monitor file: {os.path.basename(monitor_path)}")
 
        case_cfg = read_yaml_file(case_path)
        monitor_cfg = read_yaml_file(monitor_path)
        post_cfg = read_yaml_file(args.post)
 
        requested_start, requested_end, requested_interval = resolve_post_requested_window(post_cfg, case_cfg)
        try:
            require_storage_payload_local(
                run_dir,
                "post-processing",
                checkpoints=range(requested_start, requested_end + 1, requested_interval),
            )
        except StorageError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_FILE_NOT_FOUND,
                key="storage",
                file_path=run_dir,
                message=str(exc),
            )
            sys.exit(1)
 
        print("[INFO] Validating post-processing configuration...")
        validate_post_config(post_cfg, args.post, monitor_cfg, case_cfg)
        print("[SUCCESS] Post-processing configuration passed validation.\n")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        archived_post_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.yml")
        os.makedirs(os.path.dirname(archived_post_path), exist_ok=True)
        if os.path.abspath(args.post) != os.path.abspath(archived_post_path):
            shutil.copy2(args.post, archived_post_path)
 
        solver_sources_deferred = bool(args.solve and (cluster_mode or args.no_submit))
        allow_source_frontier_scan = not solver_sources_deferred
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            case_cfg,
            monitor_cfg,
            post_cfg,
            continue_requested=getattr(args, 'continue_run', False),
            allow_source_frontier_scan=allow_source_frontier_scan,
        )
 
        post_stages = resolve_post_stage_selection(getattr(args, 'only', None))
        if post_stages != set(POST_STAGE_NAMES):
            print(f"[INFO] Post stages selected: {','.join(sorted(post_stages))}")
 
        print(f"[INFO] Post recipe: {recipe_id}")
        print(f"[INFO] Post-processor source data: {os.path.relpath(post_plan['source_data_directory'])}")
 
        if getattr(args, 'continue_run', False):
            if post_plan['resume_recipe_match']:
                print(f"[INFO] Post resume recipe match: yes ({post_plan['resume_match_source']}).")
            else:
                print("[INFO] Post resume recipe match: no. Using the configured start_step for this recipe.")
        if post_plan['completed_frontier_step'] is not None:
            print(f"[INFO] Completed post frontier: step {post_plan['completed_frontier_step']}")
        else:
            print("[INFO] Completed post frontier: none")
        if post_plan['source_frontier_deferred']:
            print("[INFO] Source availability frontier: deferred because the solver stage will populate the requested window before post starts.")
        elif post_plan['source_frontier_step'] is not None:
            print(f"[INFO] Current source availability frontier: step {post_plan['source_frontier_step']}")
        else:
            print("[INFO] Current source availability frontier: none")
 
        persist_post_resume_state(run_dir, post_plan, last_successful_requested_end_step=post_plan['completed_frontier_step'])
 
        if post_plan['skip_reason'] == 'already-complete-window':
            print("[INFO] Requested post window is already complete; skipping postprocessor launch.")
            persist_post_resume_state(run_dir, post_plan, last_successful_requested_end_step=post_plan['requested_end_step'])
        elif post_plan['skip_reason'] == 'already-caught-up-to-current-source-frontier':
            print("[INFO] Post outputs are already caught up to the current fully available source frontier; nothing new to launch right now.")
            diagnostic = post_plan.get('source_frontier_diagnostic') or {}
            first_incomplete = diagnostic.get('first_incomplete_step')
            if first_incomplete is not None:
                print(f"[INFO] First incomplete requested source step: {first_incomplete}")
                print(
                    "[INFO] Closest complete source steps: "
                    f"near start={_format_optional_step(diagnostic.get('closest_complete_step_to_start'))}, "
                    f"near end={_format_optional_step(diagnostic.get('closest_complete_step_to_end'))}"
                )
        elif post_plan['skip_reason'] == 'nothing-available-yet':
            diagnostic = post_plan.get('source_frontier_diagnostic') or {}
            first_incomplete = diagnostic.get('first_incomplete_step')
            if first_incomplete is not None:
                print(
                    f"[INFO] First requested source step {first_incomplete} is incomplete; "
                    "skipping postprocessor launch for now."
                )
                print(
                    "[INFO] Closest complete source steps: "
                    f"near start={_format_optional_step(diagnostic.get('closest_complete_step_to_start'))}, "
                    f"near end={_format_optional_step(diagnostic.get('closest_complete_step_to_end'))}"
                )
                missing_files = diagnostic.get('missing_files_for_first_incomplete_step') or []
                if missing_files:
                    print(f"[INFO] Missing files for step {first_incomplete}: {', '.join(missing_files[:4])}")
            else:
                print("[INFO] No fully available source steps exist yet in the requested window; skipping postprocessor launch for now.")
        else:
            print(
                f"[INFO] Effective post window: {post_plan['effective_start_step']}..{post_plan['effective_end_step']} "
                f"(stride {post_plan['step_interval']})"
            )
 
            post_effective_cfg = post_plan['effective_post_cfg']
            post_io_cfg = post_effective_cfg.get('io', {})
            try:
                output_dir_rel = post_io_cfg['output_directory']
                output_prefix = post_io_cfg['output_filename_prefix']
            except KeyError as e:
                print(f"[FATAL] Missing required key '{e.args[0]}' in the 'io' section of {args.post}", file=sys.stderr)
                sys.exit(1)
 
            output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
            os.makedirs(output_dir_abs, exist_ok=True)
            print(f"[INFO] Post-processor output directory: {os.path.relpath(output_dir_abs)}")
            statistics_output_paths = get_post_statistics_output_artifacts(post_effective_cfg, run_dir, monitor_cfg)
            for stats_path in statistics_output_paths:
                print(f"[INFO] Statistics CSV output: {os.path.relpath(stats_path)}")
 
            # Spectra run in the conductor rather than in the submitted job, so they can
            # only be measured when this invocation is the one doing the work. Under a
            # scheduler, with --no-submit, or before the solver has written anything,
            # the sources do not exist yet and the measurement is deferred instead.
            spectra_execute_now = (
                not cluster_mode
                and not args.no_submit
                and not post_plan['source_frontier_deferred']
            )
            if 'spectra' in post_stages and spectra_execute_now:
                spectra_summary = run_post_spectra_stage(
                    run_dir,
                    post_effective_cfg,
                    monitor_cfg,
                    post_plan['source_data_directory'],
                    range(post_plan['effective_start_step'],
                          post_plan['effective_end_step'] + 1,
                          post_plan['step_interval']),
                )
                for artifact in spectra_summary['artifacts']:
                    print(f"[INFO] Spectra output: {os.path.relpath(artifact)}")
            elif 'spectra' in post_stages and not (cluster_mode and 'fields' in post_stages):
                # Under a scheduler with the field stage selected the batch script runs
                # the spectra step itself, so no instruction is printed for that case.
                reason = ("the solver stage has not produced output yet"
                          if post_plan['source_frontier_deferred'] else
                          "this invocation only stages the post job")
                print(f"[INFO] Spectra deferred: {reason}. Measure them once the run has "
                      f"checkpoints with:")
                print(f"[INFO]   picurv run --post-process --only spectra "
                      f"--run-dir {os.path.relpath(run_dir)} --post {args.post}")
 
            if 'fields' not in post_stages:
                # --only selected a subset that excludes the field post-processor.
                print("[INFO] Skipping the field post-processor (--only "
                      f"{','.join(sorted(post_stages))}).")
                stages_completed.append('post-process')
            else:
                source_files_post = {'Case': case_path, 'Post-Profile': args.post}
                post_recipe_file = generate_post_recipe_file(run_dir, run_id, post_effective_cfg, source_files_post, monitor_cfg)
 
                post_exe = resolve_runtime_executable("postprocessor")
                post_args = build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor") + [
                    "-control_file",
                    solver_control_path,
                    "-postprocessing_config_file",
                    post_recipe_file,
                ]
                if cluster_mode:
                    scheduler_dir = os.path.join(run_dir, "scheduler")
                    os.makedirs(scheduler_dir, exist_ok=True)
                    post_script = os.path.join(scheduler_dir, "post.sbatch")
                    post_log = os.path.join(scheduler_dir, "post_%j.out")
                    post_err = os.path.join(scheduler_dir, "post_%j.err")
                    post_cluster_cfg = cluster_cfg
                    raw_post_cmd = build_cluster_launch_command(
                        post_cluster_cfg,
                        post_exe,
                        post_args,
                        config_search_anchor=case_path,
                        extra_search_anchors=[cluster_path],
                        force_num_procs=post_num_procs_effective,
                    )
                    post_cmd, _ = build_post_locked_command(
                        run_dir,
                        post_plan['recipe_fingerprint'],
                        raw_post_cmd,
                        create_wrapper=True,
                    )
                    spectra_follow = []
                    if 'spectra' in post_stages:
                        follow = build_spectra_follow_command(run_dir, args.post, post_effective_cfg)
                        if follow:
                            spectra_follow = [follow]
                            print("[INFO] Spectra will be measured in the post job, after "
                                  "the field post-processor completes.")
                    render_slurm_script(
                        post_script,
                        f"{run_id}_post",
                        post_cluster_cfg,
                        post_cmd,
                        run_dir,
                        post_log,
                        post_err,
                        env_vars={"LOG_LEVEL": monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()},
                        follow_commands=spectra_follow,
                    )
                    submission_meta["stages"]["post-process"] = {
                        "script": post_script,
                        "submitted": False,
                        "num_procs_effective": post_num_procs_effective,
                        "resume_recipe_match": post_plan['resume_recipe_match'],
                        "resume_bootstrapped": post_plan['resume_bootstrapped'],
                        "resume_match_source": post_plan['resume_match_source'],
                        "effective_start_step": post_plan['effective_start_step'],
                        "effective_end_step": post_plan['effective_end_step'],
                        "completed_frontier_step": post_plan['completed_frontier_step'],
                        "source_frontier_step": post_plan['source_frontier_step'],
                        "source_frontier_deferred": post_plan['source_frontier_deferred'],
                        "recipe_fingerprint": post_plan['recipe_fingerprint'],
                    }
                    print(f"[SUCCESS] Generated post Slurm script: {os.path.relpath(post_script)}")
 
                    if not args.no_submit:
                        dependency_job = None
                        if args.solve:
                            dependency_job = submission_meta.get("stages", {}).get("solve", {}).get("job_id")
                        submit_info = submit_sbatch(post_script, dependency=dependency_job)
                        submission_meta["stages"]["post-process"].update(submit_info)
                        submission_meta["stages"]["post-process"]["submitted"] = True
                        if dependency_job:
                            submission_meta["stages"]["post-process"]["dependency"] = f"afterok:{dependency_job}"
                        print(f"[SUCCESS] Submitted post job: {submit_info['job_id']}")
                    stages_completed.append('post-process')
                else:
                    raw_command = build_local_launch_command(
                        post_exe,
                        post_args,
                        post_num_procs_effective,
                        config_search_anchor=case_path,
                        allow_single_rank_launcher_override=True,
                        force_num_procs=post_num_procs_effective,
                    )
                    command, _ = build_post_locked_command(
                        run_dir,
                        post_plan['recipe_fingerprint'],
                        raw_command,
                        create_wrapper=True,
                    )
                    post_log = os.path.join("scheduler", f"{run_id}_{output_prefix}.log")
                    submission_meta["stages"]["post-process"] = {
                        "command": command,
                        "command_string": format_command_for_display(command),
                        "log_file": post_log,
                        "submitted": False,
                        "num_procs_effective": post_num_procs_effective,
                        "resume_recipe_match": post_plan['resume_recipe_match'],
                        "resume_bootstrapped": post_plan['resume_bootstrapped'],
                        "resume_match_source": post_plan['resume_match_source'],
                        "effective_start_step": post_plan['effective_start_step'],
                        "effective_end_step": post_plan['effective_end_step'],
                        "completed_frontier_step": post_plan['completed_frontier_step'],
                        "source_frontier_step": post_plan['source_frontier_step'],
                        "source_frontier_deferred": post_plan['source_frontier_deferred'],
                        "recipe_fingerprint": post_plan['recipe_fingerprint'],
                    }
                    if args.no_submit:
                        print(f"[SUCCESS] Staged local post command: {post_log}")
                    else:
                        execute_command(command, run_dir, post_log, monitor_cfg)
                        persist_post_resume_state(run_dir, post_plan, last_successful_requested_end_step=post_plan['effective_end_step'])
                        submission_meta["stages"]["post-process"]["submitted"] = True
                        submission_meta["stages"]["post-process"]["executed"] = True
                        submission_meta["stages"]["post-process"]["completed_at"] = datetime.now().isoformat()
                    stages_completed.append('post-process')
 
    if run_dir:
        workspace_root = find_workspace_root(run_dir)
        manifest_inputs = {}
        if args.solve:
            manifest_inputs["case"] = _relative_to_workspace(args.case, workspace_root)
            manifest_inputs["solver"] = _relative_to_workspace(args.solver, workspace_root)
            manifest_inputs["monitor"] = _relative_to_workspace(args.monitor, workspace_root)
        if args.post_process:
            manifest_inputs["post"] = _relative_to_workspace(args.post, workspace_root)
        if cluster_mode:
            manifest_inputs["cluster"] = _relative_to_workspace(cluster_path, workspace_root)
        if submission_meta.get("stages"):
            write_json_file(os.path.join(run_dir, "scheduler", "submission.json"), submission_meta)
        asset_lock = read_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml")) \
            if os.path.isfile(os.path.join(run_dir, "inputs", "assets.lock.yml")) else {}
        manifest = build_run_manifest(
            run_dir,
            run_id,
            workspace_root=workspace_root,
            launch_mode="slurm" if cluster_mode else "local",
            num_procs=solver_num_procs_effective,
            post_num_procs=post_num_procs_effective,
            stages_requested={"solve": bool(args.solve), "post_process": bool(args.post_process)},
            stages_completed=stages_completed,
            inputs=manifest_inputs,
            asset_lock=asset_lock,
            submission=submission_meta,
            lineage=run_lineage,
        )
        write_json_file(os.path.join(run_dir, "manifest.json"), manifest)
 
    if stages_completed:
        elapsed = time.time() - workflow_start
        mins, secs = divmod(int(elapsed), 60)
        hrs, mins = divmod(mins, 60)
        if hrs > 0:
            time_str = f"{hrs}h {mins}m {secs}s"
        elif mins > 0:
            time_str = f"{mins}m {secs}s"
        else:
            time_str = f"{secs}s"
 
        print("\n" + "=" * 60)
        print("                       RUN SUMMARY")
        print("=" * 60)
        print(f"  Run ID         : {run_id}")
        print(f"  Run directory  : {os.path.relpath(run_dir)}")
        print(f"  Wall-clock     : {time_str}")
        print(f"  Stages         : {', '.join(stages_completed)}")
        print(f"  Launch mode    : {'slurm' if cluster_mode else 'local'}")
        if args.solve:
            print(f"  Solver MPI procs: {solver_num_procs_effective}")
        if args.post_process:
            print(f"  Post MPI procs  : {post_num_procs_effective}")
        if args.solve and configs:
            total_steps = configs['case'].get('run_control', {}).get('total_steps', '?')
            result_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS['output'])
            print(f"  Steps run      : {total_steps}")
            print(f"  Solver output  : {os.path.relpath(result_dir)}")
        if 'post-process' in stages_completed and output_dir_abs:
            print(f"  Post output    : {os.path.relpath(output_dir_abs)}")
        for stats_path in statistics_output_paths:
            print(f"  Stats output   : {os.path.relpath(stats_path)}")
        # Report the configured log directory, not the default. An authorized external
        # path is exactly the case where the two differ, and it is the case where the
        # reader most needs to know where the logs actually went.
        log_display = os.path.join(run_dir, CANONICAL_RUN_PATHS['logs'])
        relative_log = os.path.relpath(log_display)
        # A relative path that climbs out of the working directory is harder to read
        # than the absolute one it stands for.
        print(f"  Logs           : "
              f"{log_display if relative_log.startswith('..') else relative_log}")
        if cluster_mode or submission_meta.get("stages"):
            submission_file = os.path.join(run_dir, "scheduler", "submission.json")
            print(f"  Submission meta: {os.path.relpath(submission_file)}")
        print("=" * 60)
 
 
def parse_case_index_tsv(tsv_path: str) -> list:
    """!
    @brief Parse a case_index.tsv file back into a list of case entry dicts.
    @param[in] tsv_path Path to the case_index.tsv file.
    @return List of dicts with keys: index, case_id, run_dir, control_file,
            post_recipe_file, log_level, post_prefix.
    """
    entries = []
    with open(tsv_path) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            parts = line.split("\t")
            entries.append({
                "index": int(parts[0]),
                "case_id": parts[1],
                "run_dir": parts[2],
                "control_file": parts[3],
                "post_recipe_file": parts[4],
                "log_level": parts[5],
                "post_prefix": parts[6],
            })
    return entries
 
 
def sweep_workflow(args):
    """!
    @brief Study/sweep orchestration using Slurm job arrays.
    @param[in] args Command-line style argument list supplied to the function.
    """
    study_path = os.path.abspath(args.study)
    cluster_path = os.path.abspath(args.cluster)
    workspace_root = find_workspace_root(study_path, cluster_path, os.getcwd())
    if workspace_root:
        enforce_workspace_version(workspace_root)
        enforce_reproducibility_policy(workspace_root)
 
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    study_name = case_run_label(study_cfg, study_path)
    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
    study_id = f"{study_name}_{timestamp}"
    study_dir = os.path.join(workspace_artifact_root(workspace_root, "studies"), study_id)
    cases_dir = os.path.join(study_dir, "cases")
    scheduler_dir = os.path.join(study_dir, "scheduler")
    results_dir = os.path.join(study_dir, "output", "analysis")
    for path in [cases_dir, scheduler_dir, results_dir, os.path.join(study_dir, "logs")]:
        os.makedirs(path, exist_ok=True)
 
    print(f"[INFO] Creating study directory: {os.path.relpath(study_dir)}")
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: resolve_path(study_path, v) for k, v in base_cfgs.items()}
    base_snapshot_dir = os.path.join(study_dir, "base_configs")
    os.makedirs(base_snapshot_dir, exist_ok=True)
    portable_study_cfg = copy.deepcopy(study_cfg)
    portable_study_cfg["base_configs"] = {}
    for role in ("case", "solver", "monitor", "post"):
        snapshot_name = f"{role}.yml"
        snapshot_path = os.path.join(base_snapshot_dir, snapshot_name)
        shutil.copy2(base_paths[role], snapshot_path)
        portable_study_cfg["base_configs"][role] = os.path.join("base_configs", snapshot_name)
    shutil.copy2(study_path, os.path.join(study_dir, "study.source.yml"))
    write_yaml_file(os.path.join(study_dir, "study.yml"), portable_study_cfg)
    shutil.copy2(cluster_path, os.path.join(study_dir, "cluster.yml"))
 
    base_case = read_yaml_file(base_paths["case"])
    base_solver = read_yaml_file(base_paths["solver"])
    base_monitor = read_yaml_file(base_paths["monitor"])
    base_post = read_yaml_file(base_paths["post"])
    validate_simulation_configs(base_case, base_solver, base_monitor, base_paths["case"], base_paths["solver"], base_paths["monitor"])
    validate_post_config(base_post, base_paths["post"], base_monitor, base_case)
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if not combinations:
        print("[FATAL] Study parameter matrix expanded to zero cases.", file=sys.stderr)
        sys.exit(1)
    print(f"[INFO] Expanded sweep matrix to {len(combinations)} case(s).")
 
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    case_entries = []
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
 
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        run_dir = os.path.join(cases_dir, case_id)
        config_dir = os.path.join(run_dir, "config")
        ensure_run_layout(run_dir)
 
        case_cfg = copy.deepcopy(base_case)
        solver_cfg = copy.deepcopy(base_solver)
        monitor_cfg = copy.deepcopy(base_monitor)
        post_cfg = copy.deepcopy(base_post)
        target_map = {"case": case_cfg, "solver": solver_cfg, "monitor": monitor_cfg, "post": post_cfg}
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            _deep_set(target_map[root], nested, value)
 
        # Preserve file-based/grid-gen workflows when study cases are materialized
        # into new directories by rewriting external paths as absolute.
        absolutize_case_external_paths(case_cfg, base_paths["case"])
 
        case_path = os.path.join(config_dir, "case.yml")
        solver_path = os.path.join(config_dir, "solver.yml")
        monitor_path = os.path.join(config_dir, "monitor.yml")
        post_path = os.path.join(config_dir, "post.yml")
        write_yaml_file(case_path, case_cfg)
        write_yaml_file(solver_path, solver_cfg)
        write_yaml_file(monitor_path, monitor_cfg)
        write_yaml_file(post_path, post_cfg)
        write_json_file(os.path.join(config_dir, "active.json"), {
            "schema_version": 1,
            "revision": "initial",
            "updated_at": datetime.now().astimezone().isoformat(),
            "files": {
                "case": "config/case.yml",
                "solver": "config/solver.yml",
                "monitor": "config/monitor.yml",
            },
        })
 
        validate_simulation_configs(case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
 
        asset_lock = materialize_run_assets(run_dir, case_cfg, case_path)
 
        source_files = {'Case': case_path, 'Solver': solver_path, 'Monitor': monitor_path}
        monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
        configs = {
            "case": case_cfg, "case_path": case_path,
            "solver": solver_cfg, "solver_path": solver_path,
            "monitor": monitor_cfg, "monitor_path": monitor_path,
            "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
        }
        control_file = generate_solver_control_file(run_dir, case_id, configs, cluster_tasks, monitor_files)
        archive_active_generated_configuration(
            run_dir,
            [control_file, monitor_files.get("whitelist"), monitor_files.get("profile"),
             *glob.glob(os.path.join(config_dir, "bcs*.run"))],
        )
 
        source_dir = resolve_post_source_directory(run_dir, monitor_cfg, post_cfg, strict=False)
        if not isinstance(post_cfg.get('source_data'), dict):
            post_cfg['source_data'] = {}
        post_cfg['source_data']['directory'] = source_dir
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix", "post")
        post_recipe = generate_post_recipe_file(run_dir, case_id, post_cfg, {'Case': case_path, 'Post-Profile': post_path}, monitor_cfg)
 
        case_entries.append({
            "index": idx,
            "case_id": case_id,
            "run_dir": os.path.abspath(run_dir),
            "control_file": control_file,
            "post_recipe_file": post_recipe,
            "log_level": str(monitor_cfg.get("logging", {}).get("verbosity", "INFO")).upper(),
            "post_prefix": output_prefix,
            "solve_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "Solver")),
            "post_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor")),
            "parameters": combo,
        })
        write_json_file(
            os.path.join(run_dir, "manifest.json"),
            build_run_manifest(
                run_dir, case_id, workspace_root=workspace_root, launch_mode="slurm",
                artifact_type="study-case", study_id=study_id, case_id=case_id,
                num_procs=cluster_tasks, post_num_procs=cluster_tasks,
                stages_requested={"solve": True, "post_process": True},
                inputs={
                    "case": _relative_to_workspace(case_path, workspace_root),
                    "solver": _relative_to_workspace(solver_path, workspace_root),
                    "monitor": _relative_to_workspace(monitor_path, workspace_root),
                    "post": _relative_to_workspace(post_path, workspace_root),
                },
                asset_lock=asset_lock,
            ),
        )
 
    with open(case_index_file, "w") as f:
        for entry in case_entries:
            f.write(
                "\t".join(
                    [
                        str(entry["index"]),
                        entry["case_id"],
                        entry["run_dir"],
                        entry["control_file"],
                        entry["post_recipe_file"],
                        entry["log_level"],
                        entry["post_prefix"],
                        entry["solve_diagnostic_args"],
                        entry["post_diagnostic_args"],
                    ]
                ) + "\n"
            )
    print(f"[SUCCESS] Wrote sweep case index: {os.path.relpath(case_index_file)}")
 
    max_idx = len(case_entries) - 1
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    array_spec = f"0-{max_idx}"
    if max_conc:
        array_spec = f"{array_spec}%{max_conc}"
 
    solver_exe = resolve_runtime_executable("simulator")
    post_exe = resolve_runtime_executable("postprocessor")
    solver_array_script = os.path.join(scheduler_dir, "solver_array.sbatch")
    post_array_script = os.path.join(scheduler_dir, "post_array.sbatch")
    render_slurm_array_stage_script(
        solver_array_script,
        f"{study_id}_solve",
        cluster_cfg,
        array_spec,
        case_index_file,
        "solve",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "solver_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_%A_%a.err")
    )
    render_slurm_array_stage_script(
        post_array_script,
        f"{study_id}_post",
        cluster_cfg,
        array_spec,
        case_index_file,
        "post",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "post_%A_%a.out"),
        os.path.join(scheduler_dir, "post_%A_%a.err")
    )
    print(f"[SUCCESS] Generated Slurm array scripts in {os.path.relpath(scheduler_dir)}")
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated metrics aggregation script: {os.path.relpath(metrics_aggregate_script)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "solver_array": {"script": solver_array_script, "submitted": False},
        "post_array": {"script": post_array_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_array_script)
        submission["solver_array"].update(solver_submit)
        submission["solver_array"]["submitted"] = True
        post_submit = submit_sbatch(post_array_script, dependency=solver_submit["job_id"])
        submission["post_array"].update(post_submit)
        submission["post_array"]["submitted"] = True
        submission["post_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted solver array job:  {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted post array job:    {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics agg. job:  {metrics_submit['job_id']}")
 
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    summary = {
        "schema_version": 2,
        "artifact_type": "study",
        "study_id": study_id,
        "created_at": datetime.now().isoformat(),
        "software": dict(PICURV_BUILD),
        "study_type": study_cfg.get("study_type"),
        "num_cases": len(case_entries),
        "paths": {
            "study_dir": study_dir,
            "case_index": case_index_file,
            "solver_array_script": solver_array_script,
            "post_array_script": post_array_script,
            "metrics_table": metrics_csv,
            "plots_dir": os.path.join(results_dir, "plots"),
        },
        "submission": submission,
    }
    write_json_file(os.path.join(scheduler_dir, "submission.json"), submission)
    write_json_file(os.path.join(study_dir, "study_manifest.json"), summary)
    write_json_file(os.path.join(results_dir, "summary.json"), {"study_id": study_id, "metrics_csv": metrics_csv, "plots": plots})
 
    print("\n" + "=" * 60)
    print("                     STUDY SUMMARY")
    print("=" * 60)
    print(f"  Study ID        : {study_id}")
    print(f"  Study directory : {os.path.relpath(study_dir)}")
    print(f"  Cases generated : {len(case_entries)}")
    print(f"  Array spec      : {array_spec}")
    print(f"  Solver script   : {os.path.relpath(solver_array_script)}")
    print(f"  Post script     : {os.path.relpath(post_array_script)}")
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
    print("=" * 60)
 
 
def sweep_continue_workflow(args):
    """!
    @brief Continue a partially-completed Slurm parameter sweep study.
    @details Detects incomplete cases, prepares them for continuation (updating
             start_step, populating restart directories, regenerating control files),
             and submits new solver/post/metrics Slurm jobs. If all cases are already
             complete, performs metrics aggregation automatically.
    @param[in] args Parsed CLI arguments with study_dir and optional cluster override.
    """
    study_dir = os.path.abspath(args.study_dir)
    manifest_path = os.path.join(study_dir, "study_manifest.json")
    if not os.path.isfile(manifest_path):
        print(f"[FATAL] Study manifest not found: {manifest_path}", file=sys.stderr)
        sys.exit(1)
    manifest = _read_json_if_exists(manifest_path)
    study_id = manifest["study_id"]
 
    study_path = os.path.join(study_dir, "study.yml")
    cluster_path = os.path.abspath(args.cluster) if args.cluster else os.path.join(study_dir, "cluster.yml")
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    if args.cluster:
        shutil.copy(os.path.abspath(args.cluster), os.path.join(study_dir, "cluster.yml"))
        print(f"[INFO] Updated study cluster config from: {os.path.relpath(args.cluster)}")
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    cases_dir = os.path.join(study_dir, "cases")
    results_dir = os.path.join(study_dir, "output", "analysis")
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
 
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before continuing: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[FATAL] Study continuation requires payload from cold-storage member(s): "
            + ", ".join(cold_cases),
            file=sys.stderr,
        )
        for case_id in cold_cases:
            state = storage_state_summary(os.path.join(cases_dir, case_id))
            print(
                f"        Restore {case_id} with: picurv storage restore --archive-id "
                f"{state.get('archive_id') or '<archive-id>'}",
                file=sys.stderr,
            )
        print(
            "        Or pass --auto-fetch to restore them automatically.",
            file=sys.stderr,
        )
        sys.exit(1)
 
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: resolve_path(study_path, v) for k, v in base_cfgs.items()}
    base_case = read_yaml_file(base_paths["case"])
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    print(f"\n[INFO] Study: {study_id}")
    print(f"[INFO] Scanning {len(combinations)} case(s) for completion status...")
 
    incomplete_indices = []
    all_case_entries = []
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        run_dir = entry["run_dir"]
 
        effective_case = copy.deepcopy(base_case)
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            if root == "case":
                _deep_set(effective_case, nested, value)
        try:
            eff_start = int(effective_case.get("run_control", {}).get("start_step", 0) or 0)
        except (TypeError, ValueError):
            eff_start = 0
        eff_total = int(effective_case["run_control"]["total_steps"])
        target = eff_start + eff_total
 
        monitor_cfg = read_yaml_file(os.path.join(run_dir, "config", "monitor.yml"))
        status = detect_case_completion_status(run_dir, monitor_cfg, target)
        entry["_status"] = status
 
        if status["status"] == "complete":
            print(f"  {case_id}: complete (step {status['last_step']}/{target})")
        elif status["status"] == "partial":
            print(f"  {case_id}: incomplete (step {status['last_step']}/{target}) — will continue")
            incomplete_indices.append(idx)
        else:
            print(f"  {case_id}: no checkpoint — will re-run from scratch")
            incomplete_indices.append(idx)
 
        all_case_entries.append(entry)
 
    if not incomplete_indices:
        print("\n[INFO] All cases are complete. Running metrics aggregation...")
        metrics_csv = aggregate_study_metrics(study_cfg, all_case_entries, results_dir)
        plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
        print("\n" + "=" * 60)
        print("              STUDY CONTINUATION SUMMARY")
        print("=" * 60)
        print(f"  Study ID        : {study_id}")
        print(f"  Status          : ALL COMPLETE")
        if metrics_csv:
            print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
        if plots:
            print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
        print("=" * 60)
        return
 
    print(f"\n[INFO] {len(incomplete_indices)} incomplete case(s) to continue/re-run.")
 
    skipped = []
    for idx in incomplete_indices:
        entry = all_case_entries[idx]
        status = entry["_status"]
        if status["status"] == "partial":
            prepare_case_for_continuation(
                entry["run_dir"], entry["case_id"],
                status["last_step"], status["target_step"],
                cluster_cfg,
            )
        elif status["status"] == "empty":
            print(f"[INFO] {entry['case_id']}: re-running from scratch (no control file changes)")
 
    solver_array_spec = ",".join(str(i) for i in incomplete_indices)
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    if max_conc:
        solver_array_spec = f"{solver_array_spec}%{max_conc}"
 
    max_idx = len(combinations) - 1
    post_array_spec = f"0-{max_idx}"
    if max_conc:
        post_array_spec = f"{post_array_spec}%{max_conc}"
 
    solver_exe = resolve_runtime_executable("simulator")
    post_exe = resolve_runtime_executable("postprocessor")
 
    solver_continue_script = os.path.join(scheduler_dir, "solver_continue_array.sbatch")
    post_continue_script = os.path.join(scheduler_dir, "post_continue_array.sbatch")
    render_slurm_array_stage_script(
        solver_continue_script,
        f"{study_id}_solve_cont",
        cluster_cfg,
        solver_array_spec,
        case_index_file,
        "solve",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "solver_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_cont_%A_%a.err"),
    )
    render_slurm_array_stage_script(
        post_continue_script,
        f"{study_id}_post_cont",
        cluster_cfg,
        post_array_spec,
        case_index_file,
        "post",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "post_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "post_cont_%A_%a.err"),
    )
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_continue_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics_cont",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated continuation scripts in {os.path.relpath(scheduler_dir)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "continuation": True,
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "solver_continue_array": {"script": solver_continue_script, "submitted": False},
        "post_continue_array": {"script": post_continue_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_continue_script)
        submission["solver_continue_array"].update(solver_submit)
        submission["solver_continue_array"]["submitted"] = True
        post_submit = submit_sbatch(post_continue_script, dependency=solver_submit["job_id"])
        submission["post_continue_array"].update(post_submit)
        submission["post_continue_array"]["submitted"] = True
        submission["post_continue_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted continuation solver array: {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted continuation post array:   {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics aggregation job:   {metrics_submit['job_id']}")
 
    write_json_file(os.path.join(scheduler_dir, "submission_continue.json"), submission)
 
    manifest["continuation"] = {
        "continued_at": datetime.now().isoformat(),
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "submission": submission,
    }
    write_json_file(manifest_path, manifest)
 
    print("\n" + "=" * 60)
    print("              STUDY CONTINUATION SUMMARY")
    print("=" * 60)
    print(f"  Study ID          : {study_id}")
    print(f"  Incomplete cases  : {len(incomplete_indices)}/{len(combinations)}")
    print(f"  Solver array spec : {solver_array_spec}")
    print(f"  Post array spec   : {post_array_spec}")
    print(f"  Solver script     : {os.path.relpath(solver_continue_script)}")
    print(f"  Post script       : {os.path.relpath(post_continue_script)}")
    print(f"  Metrics script    : {os.path.relpath(metrics_aggregate_script)}")
    if not args.no_submit:
        print(f"  [Metrics aggregation will run automatically after post-processing]")
    else:
        print(f"  [--no-submit] Scripts generated but not submitted.")
        print(f"  After manual submission and completion, run:")
        print(f"    picurv sweep --reaggregate --study-dir {os.path.relpath(study_dir)}")
    print("=" * 60)
 
 
def sweep_reaggregate_workflow(args):
    """!
    @brief Re-run metrics aggregation and plot generation for an existing study.
    @param[in] args Parsed CLI arguments with study_dir.
    """
    study_dir = os.path.abspath(args.study_dir)
    study_path = os.path.join(study_dir, "study.yml")
    if not os.path.isfile(study_path):
        print(f"[FATAL] Study config not found: {study_path}", file=sys.stderr)
        sys.exit(1)
    study_cfg = read_yaml_file(study_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
 
    case_index_file = os.path.join(study_dir, "scheduler", "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before aggregating: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[INFO] Cold-storage member(s) cannot be re-measured; their previously "
            "aggregated values are carried forward: " + ", ".join(cold_cases)
        )
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    case_entries = []
    for idx, combo in enumerate(combinations):
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        case_entries.append(entry)
 
    results_dir = os.path.join(study_dir, "output", "analysis")
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    print("\n" + "=" * 60)
    print("              REAGGREGATION SUMMARY")
    print("=" * 60)
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots generated : {len(plots)}")
    print("=" * 60)
 
 
_SUMMARY_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
 
 
def _read_yaml_if_exists(filepath: str):
    """!
    @brief Read YAML when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_yaml_if_exists()`.
    @return Value returned by `_read_yaml_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            return yaml.safe_load(f)
    except yaml.YAMLError:
        return None
 
 
def _read_json_if_exists(filepath: str):
    """!
    @brief Read JSON when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_json_if_exists()`.
    @return Value returned by `_read_json_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    with open(filepath, "r", encoding="utf-8") as f:
        return json.load(f)
 
 
def _parse_int_loose(value):
    """!
    @brief Best-effort integer parsing for summary extraction.
    @param[in] value Argument passed to `_parse_int_loose()`.
    @return Value returned by `_parse_int_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return int(text)
    except ValueError:
        try:
            return int(float(text))
        except ValueError:
            return None
 
 
def _parse_float_loose(value):
    """!
    @brief Best-effort float parsing for summary extraction.
    @param[in] value Argument passed to `_parse_float_loose()`.
    @return Value returned by `_parse_float_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return float(text)
    except ValueError:
        return None
 
 
def _extract_numeric_tuple(text: str):
    """!
    @brief Extract a numeric tuple from a string like '(1, 2, 3)'.
    @param[in] text Argument passed to `_extract_numeric_tuple()`.
    @return Value returned by `_extract_numeric_tuple()`.
    """
    if not text:
        return []
    return [float(token) for token in _SUMMARY_NUMERIC_RE.findall(text)]
 
 
def _build_summary_context(run_dir: str) -> dict:
    """!
    @brief Resolve run-local config and artifact paths for summarize.
    @param[in] run_dir Argument passed to `_build_summary_context()`.
    @return Value returned by `_build_summary_context()`.
    """
    run_dir = os.path.abspath(run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    config_dir = os.path.join(run_dir, "config")
    config_paths = {
        "case": os.path.join(config_dir, "case.yml"),
        "solver": os.path.join(config_dir, "solver.yml"),
        "monitor": os.path.join(config_dir, "monitor.yml"),
    }
    monitor_cfg = _read_yaml_if_exists(config_paths["monitor"]) or {}
    case_cfg = _read_yaml_if_exists(config_paths["case"]) or {}
    solver_cfg = _read_yaml_if_exists(config_paths["solver"]) or {}
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
 
    io_cfg = monitor_cfg.get("io", {}) if isinstance(monitor_cfg, dict) else {}
    scheduler_dir = os.path.join(run_dir, "scheduler")
 
    profiling_cfg = {"mode": "off", "functions": [], "timestep_file": "Profiling_Timestep_Summary.csv", "final_summary_enabled": True}
    if monitor_cfg:
        profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    particle_console_output_freq = None
    particle_log_interval = None
    if monitor_cfg:
        particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
        particle_log_interval = io_cfg.get("particle_log_interval")
 
    particle_count_cfg = None
    if case_cfg:
        particle_count_cfg = (
            case_cfg.get("models", {})
            .get("physics", {})
            .get("particles", {})
            .get("count")
        )
 
    return {
        "run_dir": run_dir,
        "config_dir": config_dir,
        "log_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"]),
        "metrics_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"]),
        "scheduler_dir": scheduler_dir,
        "monitor_cfg": monitor_cfg,
        "case_cfg": case_cfg,
        "solver_cfg": solver_cfg,
        "config_paths": config_paths,
        "manifest": manifest,
        "profiling_cfg": profiling_cfg,
        "particle_console_output_freq": particle_console_output_freq,
        "particle_log_interval": particle_log_interval,
        "particle_count_cfg": particle_count_cfg,
    }
 
 
def _require_summary_config(context: dict, name: str) -> dict:
    """!
    @brief Return one explicitly requested copied config or fail with a structured error.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Config selector name.
    @return Parsed config mapping.
    """
    path = context["config_paths"][name]
    cfg = context.get(f"{name}_cfg")
    if not os.path.isfile(path):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' was not found.",
            hint="Use a staged run directory containing the requested copied config.",
        )
        sys.exit(1)
    if not isinstance(cfg, dict) or not cfg:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' is empty or is not a YAML mapping.",
        )
        sys.exit(1)
    return cfg
 
 
def _build_run_overview(context: dict) -> dict:
    """!
    @brief Build timestep-independent run metadata for summarize.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated run metadata mapping.
    """
    manifest = context["manifest"]
    software = manifest.get("software") if isinstance(manifest.get("software"), dict) else {}
    return {
        "run_id": manifest.get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "created_at": manifest.get("created_at"),
        "launch_mode": manifest.get("launch_mode"),
        "release_version": software.get("release_version"),
        "build_id": software.get("build_id"),
        "git_commit": software.get("git_commit", manifest.get("git_commit")),
        "solver_num_procs": manifest.get("solver_num_procs", manifest.get("num_procs")),
        "post_num_procs": manifest.get("post_num_procs"),
        "stages_requested": manifest.get("stages_requested"),
        "stages_completed_or_submitted": manifest.get("stages_completed_or_submitted"),
    }
 
 
def _summarize_turbulence(turbulence_cfg: dict) -> dict:
    """!
    @brief Build compact turbulence and wall-model selections.
    @param[in] turbulence_cfg Case turbulence configuration mapping.
    @return Curated turbulence and wall-model mapping.
    """
    result = {}
    for key in ("les", "rans", "wall_function"):
        value = turbulence_cfg.get(key)
        if isinstance(value, dict):
            result[key] = {
                "enabled": value.get("enabled", True),
                "model": value.get("model"),
                **{k: v for k, v in value.items() if k not in {"enabled", "model"}},
            }
        elif value is not None:
            result[key] = value
    return result
 
 
def _build_case_overview(context: dict) -> dict:
    """!
    @brief Build a curated case.yml summary with useful derived quantities.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated case configuration mapping.
    """
    cfg = _require_summary_config(context, "case")
    props = cfg.get("properties", {})
    scaling = props.get("scaling", {})
    fluid = props.get("fluid", {})
    run = cfg.get("run_control", {})
    grid = cfg.get("grid", {})
    models = cfg.get("models", {})
    domain = models.get("domain", {})
    physics = models.get("physics", {})
    particles = physics.get("particles", {})
    start = int(run.get("start_step", 0))
    total = int(run.get("total_steps", 0))
    dt = float(run.get("dt_physical", 0.0))
    length_ref = float(scaling.get("length_ref"))
    velocity_ref = float(scaling.get("velocity_ref"))
    density = float(fluid.get("density"))
    viscosity = float(fluid.get("viscosity"))
    prepared_bcs = validate_and_prepare_boundary_conditions(cfg)
    first_block_faces = {row["face"]: row for row in prepared_bcs[0]}
    periodic_axes = {
        "i": first_block_faces["-Xi"]["type"] == "PERIODIC",
        "j": first_block_faces["-Eta"]["type"] == "PERIODIC",
        "k": first_block_faces["-Zeta"]["type"] == "PERIODIC",
    }
    bc_blocks = []
    for block_idx, block in enumerate(prepared_bcs):
        bc_blocks.append(
            {
                "block": block_idx,
                "faces": [
                    {"face": row["face"], "type": row["type"], "handler": row["handler"]}
                    for row in block
                ],
            }
        )
    return {
        "run_control": {
            "start_step": start,
            "total_steps": total,
            "end_step": start + total,
            "dt_physical": dt,
            "duration_physical": total * dt,
            "dt_nondimensional": dt * velocity_ref / length_ref,
        },
        "properties": {
            "length_ref": length_ref,
            "velocity_ref": velocity_ref,
            "density": density,
            "viscosity": viscosity,
            "reynolds_number": density * velocity_ref * length_ref / viscosity if viscosity else None,
            "initial_conditions": props.get("initial_conditions", {}),
        },
        "grid": {
            "mode": grid.get("mode"),
            "processor_layout": resolve_grid_da_processor_layout(grid),
            "programmatic_settings": grid.get("programmatic_settings") if grid.get("mode") == "programmatic_c" else None,
            "source_file": grid.get("source_file"),
        },
        "domain": {
            "blocks": domain.get("blocks", 1),
            "dimensionality": physics.get("dimensionality", "3D"),
            "periodic": periodic_axes,
        },
        "physics": {
            "fsi": physics.get("fsi", {}),
            "particles": particles,
            "turbulence": _summarize_turbulence(physics.get("turbulence", {}) or {}),
        },
        "boundary_conditions": bc_blocks,
    }
 
 
def _build_solver_overview(context: dict) -> dict:
    """!
    @brief Build a curated solver.yml summary with normalized selections.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated solver configuration mapping.
    """
    cfg = _require_summary_config(context, "solver")
    strategy = cfg.get("strategy", {}) or {}
    selected = normalize_momentum_solver_type(strategy.get("momentum_solver", "Dual Time Picard Jameson RK"))
    momentum_cfg = cfg.get("momentum_solver", {}) or {}
    dualtime = momentum_cfg.get("dual_time_picard_jameson_rk", momentum_cfg.get("dual_time_picard_rk4", {})) or {}
    newton_krylov = momentum_cfg.get("newton_krylov", {}) or {}
    poisson = cfg.get("poisson_solver", cfg.get("pressure_solver", {})) or {}
    operation_mode = cfg.get("operation_mode", {}) or {}
    operation_mode = {
        **operation_mode,
        "eulerian_field_source": normalize_eulerian_field_source(operation_mode.get("eulerian_field_source", "solve")),
    }
    if operation_mode.get("analytical_type") is not None:
        operation_mode["analytical_type"] = normalize_analytical_type(operation_mode["analytical_type"])
    passthrough = cfg.get("petsc_passthrough_options", {}) or {}
    return {
        "operation_mode": operation_mode,
        "momentum": {
            "type": selected,
            "central_diff": bool(strategy.get("central_diff", False)),
            "tolerances": cfg.get("tolerances", {}),
            "controls": newton_krylov if selected == "newton_krylov" else dualtime,
        },
        "poisson": poisson,
        "interpolation": cfg.get("interpolation", {"method": "Trilinear"}),
        "scalar_transport": cfg.get("scalar_transport", {}),
        "verification": cfg.get("verification", {}),
        "petsc_passthrough": {"count": len(passthrough), "options": sorted(passthrough.keys())},
    }
 
 
def _build_monitor_overview(context: dict) -> dict:
    """!
    @brief Build a curated monitor.yml summary with resolved defaults.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated monitor configuration mapping.
    """
    cfg = _require_summary_config(context, "monitor")
    logging_cfg = cfg.get("logging", {}) or {}
    io_cfg = cfg.get("io", {}) or {}
    diagnostics = resolve_diagnostics_config(cfg, context["run_dir"], "Solver")
    monitoring_flags = resolve_solver_monitoring_flags(cfg)
    solution_monitoring = normalize_solution_monitoring_config(cfg)
    enabled_petsc = sorted(key for key, value in diagnostics["petsc"].items() if value not in (False, None))
    return {
        "logging": {
            "verbosity": logging_cfg.get("verbosity", "WARNING"),
            "enabled_functions": logging_cfg.get("enabled_functions", []),
        },
        "profiling": resolve_profiling_config(cfg),
        "diagnostics": {
            "enabled_petsc": enabled_petsc,
            "petsc": diagnostics["petsc"],
            "runtime_memory_log": diagnostics["runtime_memory_log"],
        },
        "io": {
            "data_output_frequency": io_cfg.get("data_output_frequency"),
            "particle_console_output_frequency": resolve_particle_console_output_frequency(io_cfg),
            "particle_log_interval": io_cfg.get("particle_log_interval"),
            "directories": {
                "output": CANONICAL_RUN_PATHS["output"],
                "restart": CANONICAL_RUN_PATHS["restart"],
                "logs": CANONICAL_RUN_PATHS["logs"],
                "analysis": CANONICAL_RUN_PATHS["analysis"],
            },
        },
        "solver_monitoring": {
            "enabled_flags": sorted(flag for flag, value in monitoring_flags.items() if value not in (False, None)),
            "flags": monitoring_flags,
        },
        "solution_monitoring": solution_monitoring,
    }
 
 
def _parse_continuity_metrics_log(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse Continuity_Metrics.log into latest rows by step plus observed order.
    @param[in] filepath Argument passed to `_parse_continuity_metrics_log()`.
    @return Value returned by `_parse_continuity_metrics_log()`.
    """
    rows_by_step = {}
    step_order = []
    active_step = None
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Timestep"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step = _parse_int_loose(parts[0])
            block = _parse_int_loose(parts[1])
            max_div = _parse_float_loose(parts[2])
            rhs_sum = _parse_float_loose(parts[4])
            flux_in = _parse_float_loose(parts[5])
            flux_out = _parse_float_loose(parts[6])
            net_flux = _parse_float_loose(parts[7])
            if step is None or block is None:
                continue
            if step != active_step:
                active_step = step
                step_order.append(step)
                rows_by_step[step] = {}
            rows_by_step.setdefault(step, {})[block] = {
                "block": block,
                "max_divergence": max_div,
                "max_divergence_location": parts[3],
                "rhs_sum": rhs_sum,
                "flux_in": flux_in,
                "flux_out": flux_out,
                "net_flux": net_flux,
            }
    return {step: list(block_rows.values()) for step, block_rows in rows_by_step.items()}, step_order
 
 
def _parse_particle_metrics_log(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse Particle_Metrics.log into latest rows by step plus observed order.
    @param[in] filepath Argument passed to `_parse_particle_metrics_log()`.
    @return Value returned by `_parse_particle_metrics_log()`.
    """
    rows_by_step = {}
    step_order = []
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Stage"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step = _parse_int_loose(parts[1])
            if step is None:
                continue
            row = {
                "stage": parts[0],
                "total_particles": _parse_int_loose(parts[2]),
                "lost_particles": _parse_int_loose(parts[3]),
                "lost_particles_cumulative": None,
                "migrated_particles": None,
                "occupied_cells": None,
                "load_imbalance": None,
                "migration_passes": None,
            }
            if len(parts) >= 9:
                row.update(
                    {
                        "lost_particles_cumulative": _parse_int_loose(parts[4]),
                        "migrated_particles": _parse_int_loose(parts[5]),
                        "occupied_cells": _parse_int_loose(parts[6]),
                        "load_imbalance": _parse_float_loose(parts[7]),
                        "migration_passes": _parse_int_loose(parts[8]),
                    }
                )
            else:
                row.update(
                    {
                        "migrated_particles": _parse_int_loose(parts[4]),
                        "occupied_cells": _parse_int_loose(parts[5]),
                        "load_imbalance": _parse_float_loose(parts[6]),
                        "migration_passes": _parse_int_loose(parts[7]),
                    }
                )
            rows_by_step[step] = row
            step_order.append(step)
    return rows_by_step, step_order
 
 
def _parse_momentum_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Parse per-block momentum convergence logs.
    @param[in] log_dir Argument passed to `_parse_momentum_convergence_logs()`.
    @return Value returned by `_parse_momentum_convergence_logs()`.
    """
    rows_by_step = {}
    sources = {}
    step_order = []
    patterns = [
        os.path.join(log_dir, "Momentum_Solver_DualTime_Picard_Jameson_RK_History_Block_*.log"),
        os.path.join(log_dir, "Momentum_Solver_Convergence_History_Block_*.log"),
    ]
    # Log format (Phase 3+): dtau [physical time] and cfl_eff [dimensionless Courant number].
    # cfl_eff = dtau * lambda_max; this is the value controlled by pseudo_cfl.* YAML keys.
    regex = re.compile(
        r"Step:\s*(?P<step>\d+)\s*\|\s*PseudoIter\‍(k\‍):\s*(?P<pseudo_iter>\d+)\s*\|"
        r"\s*dtau:\s*(?P<dtau>[-+0-9.eE]+)\s*\|\s*cfl_eff:\s*(?P<cfl_eff>[-+0-9.eE]+)\s*\|"
        r"\s*\|dUk\|:\s*(?P<delta>[-+0-9.eE]+)\s*\|"
        r"\s*\|dUk\|/\|dU0\|:\s*(?P<delta_rel>[-+0-9.eE]+)\s*\|\s*\|Rk\|:\s*(?P<resid>[-+0-9.eE]+)\s*\|"
        r"\s*\|Rk\|/\|R0\|:\s*(?P<resid_rel>[-+0-9.eE]+)"
        r"(?:\s*\|\s*trial_ratio:\s*(?P<trial_ratio>[-+0-9.eE]+)"
        r"(?:\s*\|\s*smoothed_ratio:\s*(?P<smoothed_ratio>[-+0-9.eE]+))?"
        r"\s*\|\s*status:\s*(?P<status>\w+)\s*\|\s*dtau_after:\s*(?P<dtau_after>[-+0-9.eE]+)"
        r"(?:\s*\|\s*cfl_eff_after:\s*(?P<cfl_eff_after>[-+0-9.eE]+))?)?"
    )
 
    # Per (step, block): track accepted/rejected counts and last committed state.
    _state = {}
 
    for path in sorted(path for pattern in patterns for path in glob.glob(pattern)):
        block_match = re.search(r"Block_(\d+)\.log$", path)
        if not block_match:
            continue
        block = int(block_match.group(1))
        sources[block] = path
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                match = regex.search(raw_line)
                if not match:
                    continue
                step = int(match.group("step"))
                step_order.append(step)
                key = (step, block)
                if key not in _state:
                    _state[key] = {"accepted_count": 0, "rejected_count": 0, "last_accepted": None, "last_rejected": None}
                entry = _state[key]
                status = match.group("status")
                row = {
                    "block": block,
                    "pseudo_iterations": int(match.group("pseudo_iter")),
                    "dtau": _parse_float_loose(match.group("dtau")),
                    "cfl_eff": _parse_float_loose(match.group("cfl_eff")),
                    "dtau_after": _parse_float_loose(match.group("dtau_after")),
                    "cfl_eff_after": _parse_float_loose(match.group("cfl_eff_after")),
                    "delta_norm": float(match.group("delta")),
                    "delta_rel": float(match.group("delta_rel")),
                    "residual_norm": float(match.group("resid")),
                    "residual_rel": float(match.group("resid_rel")),
                    "trial_ratio": _parse_float_loose(match.group("trial_ratio")),
                    "smoothed_ratio": _parse_float_loose(match.group("smoothed_ratio")),
                    "status": status,
                }
                if status == "accepted":
                    entry["accepted_count"] += 1
                    entry["last_accepted"] = row
                else:
                    entry["rejected_count"] += 1
                    entry["last_rejected"] = row
 
    for (step, block), entry in _state.items():
        display_row = entry["last_accepted"] or entry["last_rejected"]
        if display_row:
            rows_by_step.setdefault(step, {})[block] = {
                **display_row,
                "accepted_count": entry["accepted_count"],
                "rejected_count": entry["rejected_count"],
            }
 
    newton_pattern = os.path.join(log_dir, "Momentum_Solver_Newton_Krylov_Summary_Block_*.log")
    newton_regex = re.compile(
        r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
        r"\s*solver:\s*(?P<solver>[^|]+?)\s*\|"
        # The runtime includes Jacobian and preconditioner descriptions here.
        # Keep these optional so summaries can also read the original compact logs.
        r"(?:\s*Jacobian:\s*[^|]+?\s*\|\s*Preconditioner:\s*[^|]+?\s*\|)?"
        r"\s*reason:\s*(?P<reason>\S+)\s*\|"
        r"\s*reason_code:\s*(?P<reason_code>-?\d+)\s*\|\s*newton:\s*(?P<newton>\d+)\s*\|"
        r"\s*evals:\s*(?P<evals>\d+)\s*\|\s*krylov:\s*(?P<krylov>\d+)\s*\|"
        r"\s*initial:\s*(?P<initial>[-+0-9.eE]+|unavailable)\s*\|"
        r"\s*final:\s*(?P<final>[-+0-9.eE]+)\s*\|\s*state:\s*(?P<state>\w+)"
    )
    for path in sorted(glob.glob(newton_pattern)):
        block_match = re.search(r"Block_(\d+)\.log$", path)
        if not block_match:
            continue
        file_block = int(block_match.group(1))
        sources[file_block] = path
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                match = newton_regex.search(raw_line)
                if not match:
                    continue
                step = int(match.group("step"))
                block = int(match.group("block"))
                initial_text = match.group("initial")
                step_order.append(step)
                rows_by_step.setdefault(step, {})[block] = {
                    "block": block,
                    "solver": match.group("solver").strip(),
                    "reason": match.group("reason"),
                    "reason_code": int(match.group("reason_code")),
                    "newton_iterations": int(match.group("newton")),
                    "residual_evaluations": int(match.group("evals")),
                    "krylov_iterations": int(match.group("krylov")),
                    "initial_norm": None if initial_text == "unavailable" else float(initial_text),
                    "final_norm": float(match.group("final")),
                    "state": match.group("state"),
                }
 
    return rows_by_step, sources, step_order
 
 
def _parse_poisson_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Parse per-block Poisson convergence logs.
    @param[in] log_dir Argument passed to `_parse_poisson_convergence_logs()`.
    @return Value returned by `_parse_poisson_convergence_logs()`.
    """
    rows_by_step = {}
    sources = {}
    step_order = []
    pattern = os.path.join(log_dir, "Poisson_Solver_Convergence_History_Block_*.log")
    regex = re.compile(
        r"ts:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|\s*iter:\s*(?P<iter>\d+)\s*\|"
        r"\s*Unprecond Norm:\s*(?P<unpre>[-+0-9.eE]+)\s*\|\s*True Norm:\s*(?P<true>[-+0-9.eE]+)"
        r"(?:\s*\|\s*Rel Norm:\s*(?P<rel>[-+0-9.eE]+))?"
    )
 
    for path in sorted(glob.glob(pattern)):
        block_match = re.search(r"Block_(\d+)\.log$", path)
        if not block_match:
            continue
        block = int(block_match.group(1))
        sources[block] = path
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                match = regex.search(raw_line)
                if not match:
                    continue
                step = int(match.group("step"))
                step_order.append(step)
                rows_by_step.setdefault(step, {})[block] = {
                    "block": block,
                    "iterations": int(match.group("iter")),
                    "unpreconditioned_norm": float(match.group("unpre")),
                    "true_norm": float(match.group("true")),
                    "relative_norm": _parse_float_loose(match.group("rel")),
                }
    return rows_by_step, sources, step_order
 
 
def _parse_profiling_timestep_csv(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse profiling timestep CSV into latest rows by step plus observed order.
    @param[in] filepath Argument passed to `_parse_profiling_timestep_csv()`.
    @return Value returned by `_parse_profiling_timestep_csv()`.
    """
    rows_by_step = {}
    step_order = []
    active_step = None
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    with open(filepath, "r", encoding="utf-8", errors="replace", newline="") as f:
        reader = csv.DictReader(f)
        for row in reader:
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            if step != active_step:
                active_step = step
                step_order.append(step)
                rows_by_step[step] = []
            rows_by_step.setdefault(step, []).append(
                {
                    "function": row.get("function"),
                    "calls": _parse_int_loose(row.get("calls")),
                    "step_time_s": _parse_float_loose(row.get("step_time_s")),
                }
            )
    return rows_by_step, step_order
 
 
def _parse_runtime_memory_log(filepath: str) -> "tuple[dict, list[int], dict]":
    """!
    @brief Parse Runtime_Memory.log into latest rows by step and final status.
    @param[in] filepath Runtime memory log path.
    @return Tuple of rows by step, observed step order, and final/shutdown metadata.
    """
    rows_by_step = {}
    step_order = []
    final_row = None
    latest_sample_row = None
    max_process_change_mb = None
    if not os.path.isfile(filepath):
        return rows_by_step, step_order, {"available": False}
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if not line or line.startswith("#") or line.startswith("Step"):
                continue
            parts = line.split()
            if len(parts) < 8:
                continue
            step = _parse_int_loose(parts[0])
            if step is None:
                continue
            row = {
                "step": step,
                "event": parts[1],
                "process_current_mb_max": _parse_float_loose(parts[2]),
                "process_peak_mb_max": _parse_float_loose(parts[3]),
                "petsc_allocated_mb_max": _parse_float_loose(parts[4]),
                "petsc_peak_allocated_mb_max": _parse_float_loose(parts[5]),
                "process_change_mb_max": _parse_float_loose(parts[6]),
                "reason": parts[7],
            }
            if row["process_change_mb_max"] is not None:
                max_process_change_mb = (
                    row["process_change_mb_max"]
                    if max_process_change_mb is None
                    else max(max_process_change_mb, row["process_change_mb_max"])
                )
            if row["event"] in {"Step", "Post"}:
                rows_by_step[step] = row
                step_order.append(step)
                latest_sample_row = row
            elif row["event"] in {"Shutdown", "Final"}:
                final_row = row
 
    meta = {
        "available": bool(rows_by_step or final_row),
        "source": filepath,
        "final_event": final_row.get("event") if final_row else None,
        "final_reason": final_row.get("reason") if final_row else None,
        "max_process_change_mb": max_process_change_mb,
        "latest_sample_row": latest_sample_row,
        "final_row": final_row,
    }
    return rows_by_step, step_order, meta
 
 
def _parse_solution_convergence_log(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse solution_convergence.log into latest rows by step plus observed order.
 
    The log format uses pipe-delimited aligned columns. The first line of the
    file is a banner (starts with '=') containing the mode tag; the second line
    is the column header; the third line is a separator (starts with '-').
    Subsequent lines are one data row per timestep.
 
    @param[in] filepath Path to solution_convergence.log.
    @return Mapping of step number to a dict of column values.
    """
    rows_by_step = {}
    step_order = []
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    mode = None
    col_names = None
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if not line:
                continue
            if line.startswith("="):
                m = re.search(r"\[mode:\s*([\w_]+)", line)
                if m:
                    mode = m.group(1)
                continue
            if line.startswith("-"):
                continue
            if col_names is None:
                col_names = [p.strip() for p in raw_line.split("|")]
                continue
            parts = [p.strip() for p in raw_line.split("|")]
            if len(parts) < 4 or col_names is None:
                continue
            step = _parse_int_loose(parts[0]) if col_names[0] == "step" else None
            if step is None:
                continue
            step_order.append(step)
            row = {"mode": mode}
            for name, val in zip(col_names, parts):
                if not name:
                    continue
                float_val = _parse_float_loose(val)
                int_val = _parse_int_loose(val)
                if float_val is not None and ("." in val or "e" in val.lower()):
                    row[name] = float_val
                elif int_val is not None:
                    row[name] = int_val
                else:
                    row[name] = val
            rows_by_step[step] = row
    return rows_by_step, step_order
 
 
def _find_solver_stream_log_candidates(run_dir: str, log_dir: str) -> "list[str]":
    """!
    @brief Return plausible solver stream logs for local and Slurm runs.
    @param[in] run_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @param[in] log_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @return Value returned by `_find_solver_stream_log_candidates()`.
    """
    patterns = [
        os.path.join(run_dir, "scheduler", "*_solver.log"),
        os.path.join(run_dir, "scheduler", "solver_*.out"),
        os.path.join(log_dir, "*_solver.log"),
    ]
    found = []
    seen = set()
    for pattern in patterns:
        for path in sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True):
            if path not in seen:
                seen.add(path)
                found.append(path)
    return found
 
 
def _parse_particle_snapshot_file(filepath: str) -> dict:
    """!
    @brief Parse sampled particle snapshots from a solver stream log.
    @param[in] filepath Argument passed to `_parse_particle_snapshot_file()`.
    @return Value returned by `_parse_particle_snapshot_file()`.
    """
    snapshots = {}
    if not os.path.isfile(filepath):
        return snapshots
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        lines = f.readlines()
 
    idx = 0
    while idx < len(lines):
        match = re.search(r"Particle states at step\s+(\d+):", lines[idx])
        if not match:
            idx += 1
            continue
        step = int(match.group(1))
        idx += 1
        rows = []
        while idx < len(lines):
            stripped = lines[idx].strip()
            if re.search(r"Particle states at step\s+\d+:", lines[idx]):
                break
            if stripped.startswith("|"):
                parts = [part.strip() for part in stripped.split("|")[1:-1]]
                if len(parts) >= 6 and parts[0] != "Rank":
                    velocity = _extract_numeric_tuple(parts[4])
                    rows.append(
                        {
                            "rank": _parse_int_loose(parts[0]),
                            "pid": _parse_int_loose(parts[1]),
                            "cell": [int(value) for value in _extract_numeric_tuple(parts[2])],
                            "position": _extract_numeric_tuple(parts[3]),
                            "velocity": velocity,
                            "weights": _extract_numeric_tuple(parts[5]),
                            "sample_speed": math.sqrt(sum(component * component for component in velocity)) if len(velocity) == 3 else None,
                        }
                    )
            elif rows and (not stripped or stripped.startswith("Progress:")):
                break
            idx += 1
        if rows:
            snapshots[step] = rows
        else:
            snapshots.setdefault(step, [])
    return snapshots
 
 
def _find_previous_snapshot_step(snapshot_steps: "list[int]", step: int) -> "int | None":
    """!
    @brief Return the nearest earlier snapshot step when available.
    @param[in] snapshot_steps Argument passed to `_find_previous_snapshot_step()`.
    @param[in] step Argument passed to `_find_previous_snapshot_step()`.
    @return Value returned by `_find_previous_snapshot_step()`.
    """
    earlier_steps = [candidate for candidate in snapshot_steps if candidate < step]
    if not earlier_steps:
        return None
    return max(earlier_steps)
 
 
def _compute_particle_snapshot_delta(current_rows: "list[dict]", previous_rows: "list[dict]") -> dict:
    """!
    @brief Compute sampled deltas between two particle snapshot samples.
    @param[in] current_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @param[in] previous_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @return Value returned by `_compute_particle_snapshot_delta()`.
    """
    np = require_numpy()
    previous_by_pid = {
        row.get("pid"): row
        for row in previous_rows
        if row.get("pid") is not None
    }
    current_by_pid = {
        row.get("pid"): row
        for row in current_rows
        if row.get("pid") is not None
    }
    matched_pids = sorted(set(previous_by_pid) & set(current_by_pid))
    if not matched_pids:
        return {"available": False}
 
    displacements = []
    rank_migrations = 0
    cell_changes = 0
    speed_changes = []
    for pid in matched_pids:
        current_row = current_by_pid[pid]
        previous_row = previous_by_pid[pid]
        current_pos = current_row.get("position") or []
        previous_pos = previous_row.get("position") or []
        if len(current_pos) == len(previous_pos) and current_pos:
            displacements.append(
                math.sqrt(
                    sum(
                        (float(current_pos[idx]) - float(previous_pos[idx])) ** 2
                        for idx in range(len(current_pos))
                    )
                )
            )
        current_speed = current_row.get("sample_speed")
        previous_speed = previous_row.get("sample_speed")
        if current_speed is not None and previous_speed is not None:
            speed_changes.append(float(current_speed) - float(previous_speed))
        if current_row.get("rank") is not None and previous_row.get("rank") is not None:
            if current_row["rank"] != previous_row["rank"]:
                rank_migrations += 1
        if current_row.get("cell") and previous_row.get("cell"):
            if current_row["cell"] != previous_row["cell"]:
                cell_changes += 1
 
    payload = {
        "available": True,
        "matched_pids": len(matched_pids),
        "new_count": len(set(current_by_pid) - set(previous_by_pid)),
        "gone_count": len(set(previous_by_pid) - set(current_by_pid)),
        "rank_migrations": rank_migrations,
        "cell_changes": cell_changes,
    }
    if displacements:
        payload["mean_displacement"] = float(np.mean(displacements))
        payload["max_displacement"] = float(np.max(displacements))
    if speed_changes:
        payload["mean_speed_change"] = float(np.mean(speed_changes))
        payload["max_abs_speed_change"] = float(np.max(np.abs(speed_changes)))
    return payload
 
 
def _build_particle_snapshot_summary(
    source: str,
    step: int,
    rows: "list[dict]",
    preview_rows: int,
    particle_console_output_freq,
    particle_log_interval,
    previous_step: "int | None" = None,
    previous_rows: "list[dict] | None" = None,
) -> dict:
    """!
    @brief Build sampled diagnostics for one particle console snapshot.
    @param[in] source Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] preview_rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_console_output_freq Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_log_interval Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_rows Argument passed to `_build_particle_snapshot_summary()`.
    @return Value returned by `_build_particle_snapshot_summary()`.
    """
    np = require_numpy()
    payload = {
        "available": True,
        "sampled": True,
        "source": source,
        "step": step,
        "sampled_rows": len(rows),
        "preview_rows": rows[:preview_rows],
        "cadence": {
            "particle_console_output_frequency": particle_console_output_freq,
            "particle_log_interval": particle_log_interval,
        },
    }
    if not rows:
        return payload
 
    rank_counts = {}
    duplicate_pid_count = 0
    duplicate_cell_count = 0
    nan_count = 0
    inf_count = 0
    zero_weight_count = 0
    negative_weight_count = 0
    unique_pid_count = 0
 
    seen_pids = set()
    cell_counter = {}
    position_components = [[], [], []]
    weight_components = {}
    speeds = []
 
    for row in rows:
        pid = row.get("pid")
        if pid is not None:
            if pid in seen_pids:
                duplicate_pid_count += 1
            else:
                seen_pids.add(pid)
        rank = row.get("rank")
        if rank is not None:
            rank_counts[str(rank)] = rank_counts.get(str(rank), 0) + 1
 
        cell = row.get("cell") or []
        if cell:
            key = tuple(cell)
            cell_counter[key] = cell_counter.get(key, 0) + 1
 
        position = row.get("position") or []
        for idx, value in enumerate(position[:3]):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            position_components[idx].append(float(value))
 
        velocity = row.get("velocity") or []
        if any(not np.isfinite(value) for value in velocity):
            for value in velocity:
                if not np.isfinite(value):
                    if np.isnan(value):
                        nan_count += 1
                    else:
                        inf_count += 1
        speed = row.get("sample_speed")
        if speed is not None and np.isfinite(speed):
            speeds.append(float(speed))
 
        weights = row.get("weights") or []
        for idx, value in enumerate(weights):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            numeric = float(value)
            weight_components.setdefault(idx, []).append(numeric)
            if abs(numeric) <= 1.0e-15:
                zero_weight_count += 1
            if numeric < 0.0:
                negative_weight_count += 1
 
    unique_pid_count = len(seen_pids)
    duplicate_cell_count = sum(1 for count in cell_counter.values() if count > 1)
 
    payload["sampled_distribution"] = {
        "unique_cells": len(cell_counter),
        "duplicate_cells": duplicate_cell_count,
        "rank_counts": rank_counts,
        "unique_pids": unique_pid_count,
    }
    payload["checks"] = {
        "duplicate_pid_count": duplicate_pid_count,
        "nan_count": nan_count,
        "inf_count": inf_count,
        "zero_weight_count": zero_weight_count,
        "negative_weight_count": negative_weight_count,
    }
 
    if speeds:
        payload["speed"] = {
            "min": float(np.min(speeds)),
            "mean": float(np.mean(speeds)),
            "max": float(np.max(speeds)),
            "std": float(np.std(speeds)),
            "stagnant_count": sum(1 for speed in speeds if abs(speed) < 1.0e-6),
        }
 
        fastest_rows = sorted(
            [row for row in rows if row.get("sample_speed") is not None],
            key=lambda row: row["sample_speed"],
            reverse=True,
        )[:3]
        payload["top_speeds"] = [
            {
                "pid": row.get("pid"),
                "rank": row.get("rank"),
                "speed": row.get("sample_speed"),
                "cell": row.get("cell"),
            }
            for row in fastest_rows
        ]
 
    if any(position_components):
        axes = ["x", "y", "z"]
        payload["position_bounds"] = {}
        centroid = []
        for idx, axis in enumerate(axes):
            values = position_components[idx]
            if values:
                payload["position_bounds"][axis] = [float(np.min(values)), float(np.max(values))]
                centroid.append(float(np.mean(values)))
            else:
                centroid.append(None)
        payload["position_centroid"] = centroid
 
    if weight_components:
        payload["weights"] = {}
        for idx, values in sorted(weight_components.items()):
            payload["weights"][f"component_{idx}"] = {
                "min": float(np.min(values)),
                "max": float(np.max(values)),
            }
 
    delta_summary = {"available": False}
    if previous_step is not None and previous_rows:
        delta_summary = _compute_particle_snapshot_delta(rows, previous_rows)
        if delta_summary.get("available"):
            delta_summary["previous_step"] = previous_step
    payload["delta_from_previous_snapshot"] = delta_summary
    return payload
 
 
def _find_particle_snapshot_for_step(
    run_dir: str,
    log_dir: str,
    step: int,
    preview_rows: int,
    particle_console_output_freq,
    particle_log_interval,
) -> dict:
    """!
    @brief Locate and summarize a particle console snapshot for one step.
    @param[in] run_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] log_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] step Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] preview_rows Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_console_output_freq Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_log_interval Argument passed to `_find_particle_snapshot_for_step()`.
    @return Value returned by `_find_particle_snapshot_for_step()`.
    """
    best = None
    for path in _find_solver_stream_log_candidates(run_dir, log_dir):
        snapshots = _parse_particle_snapshot_file(path)
        rows = snapshots.get(step)
        if not rows:
            continue
        if best is None or len(rows) > len(best["rows"]):
            best = {"source": path, "rows": rows, "snapshots": snapshots}
 
    if not best:
        return {"available": False}
 
    previous_step = _find_previous_snapshot_step(list(best["snapshots"].keys()), step)
    previous_rows = best["snapshots"].get(previous_step, []) if previous_step is not None else None
    return _build_particle_snapshot_summary(
        best["source"],
        step,
        best["rows"],
        preview_rows,
        particle_console_output_freq=particle_console_output_freq,
        particle_log_interval=particle_log_interval,
        previous_step=previous_step,
        previous_rows=previous_rows,
    )
 
 
def _resolve_summary_step(
    requested_step,
    continuity_rows,
    particle_rows,
    momentum_rows,
    poisson_rows,
    profiling_rows,
    memory_rows=None,
    convergence_rows=None,
    step_orders=None,
    selection_mode: str = "latest",
):
    """!
    @brief Select a step to summarize from available metric artifacts.
    @param[in] requested_step Argument passed to `_resolve_summary_step()`.
    @param[in] continuity_rows Argument passed to `_resolve_summary_step()`.
    @param[in] particle_rows Argument passed to `_resolve_summary_step()`.
    @param[in] momentum_rows Argument passed to `_resolve_summary_step()`.
    @param[in] poisson_rows Argument passed to `_resolve_summary_step()`.
    @param[in] profiling_rows Argument passed to `_resolve_summary_step()`.
    @param[in] memory_rows Argument passed to `_resolve_summary_step()`.
    @param[in] convergence_rows Argument passed to `_resolve_summary_step()`.
    @param[in] step_orders Argument passed to `_resolve_summary_step()`.
    @param[in] selection_mode Argument passed to `_resolve_summary_step()`.
    @return Value returned by `_resolve_summary_step()`.
    """
    if memory_rows is None:
        memory_rows = {}
    if convergence_rows is None:
        convergence_rows = {}
    if step_orders is None:
        step_orders = []
    available_steps = (
        set(continuity_rows) | set(particle_rows) | set(momentum_rows)
        | set(poisson_rows) | set(profiling_rows) | set(memory_rows) | set(convergence_rows)
    )
    if not available_steps:
        return None, []
 
    if requested_step is not None:
        return requested_step, sorted(available_steps)
 
    if selection_mode == "max_step":
        return max(available_steps), sorted(available_steps)
 
    for order in step_orders:
        if order:
            return order[-1], sorted(available_steps)
    return max(available_steps), sorted(available_steps)
 
 
def _format_summary_float(value, spec: str = ".6e", missing: str = "n/a") -> str:
    """!
    @brief Format optional numeric values for summary text output.
    @param[in] value Argument passed to `_format_summary_float()`.
    @param[in] spec Argument passed to `_format_summary_float()`.
    @param[in] missing Argument passed to `_format_summary_float()`.
    @return Value returned by `_format_summary_float()`.
    """
    if value is None:
        return missing
    return format(value, spec)
 
 
def _summary_source_mtime(paths) -> float:
    """!
    @brief Return the newest modification time among one or more summary sources.
    @param[in] paths Path string, iterable of paths, or mapping of paths.
    @return Newest modification time, or -1.0 when no source exists.
    """
    if isinstance(paths, dict):
        paths = paths.values()
    elif isinstance(paths, str):
        paths = [paths]
    newest = -1.0
    for path in paths or []:
        if path and os.path.isfile(path):
            newest = max(newest, os.path.getmtime(path))
    return newest
 
 
def _order_summary_step_orders(sources: "list[tuple[list[int], object]]") -> "list[list[int]]":
    """!
    @brief Order observed step sequences by the recency of their source files.
    @param[in] sources Pairs of observed steps and filesystem source path(s).
    @return Step-order lists sorted so active append sources are considered first.
    """
    ranked = []
    for priority, (order, paths) in enumerate(sources):
        if order:
            ranked.append((_summary_source_mtime(paths), priority, order))
    ranked.sort(key=lambda item: (-item[0], item[1]))
    return [order for _, _, order in ranked]
 
 
def build_run_summary_payload(run_dir: str, step: "int | None" = None, snapshot_rows: int = 5, selection_mode: str = "latest") -> dict:
    """!
    @brief Build a read-only run-step summary from existing PICurv artifacts.
    @param[in] run_dir Argument passed to `build_run_summary_payload()`.
    @param[in] step Argument passed to `build_run_summary_payload()`.
    @param[in] snapshot_rows Argument passed to `build_run_summary_payload()`.
    @param[in] selection_mode Argument passed to `build_run_summary_payload()`.
    @return Value returned by `build_run_summary_payload()`.
    """
    context = _build_summary_context(run_dir)
    log_dir = context["log_dir"]
    continuity_path = os.path.join(log_dir, "Continuity_Metrics.log")
    particle_metrics_path = os.path.join(log_dir, "Particle_Metrics.log")
 
    continuity_rows, continuity_order = _parse_continuity_metrics_log(continuity_path)
    particle_rows, particle_order = _parse_particle_metrics_log(particle_metrics_path)
    momentum_rows, momentum_sources, momentum_order = _parse_momentum_convergence_logs(log_dir)
    poisson_rows, poisson_sources, poisson_order = _parse_poisson_convergence_logs(log_dir)
 
    profiling_rows = {}
    profiling_order = []
    profiling_path = os.path.join(log_dir, context["profiling_cfg"].get("timestep_file", "Profiling_Timestep_Summary.csv"))
    if context["profiling_cfg"].get("mode") != "off":
        profiling_rows, profiling_order = _parse_profiling_timestep_csv(profiling_path)
 
    diagnostics_cfg = resolve_diagnostics_config(context["monitor_cfg"])
    memory_log_file = diagnostics_cfg["runtime_memory_log"].get("file", "Runtime_Memory.log")
    memory_path = os.path.join(log_dir, memory_log_file)
    memory_rows, memory_order, memory_meta = _parse_runtime_memory_log(memory_path)
 
    convergence_log_path = os.path.join(log_dir, "solution_convergence.log")
    convergence_rows, convergence_order = _parse_solution_convergence_log(convergence_log_path)
    step_orders = _order_summary_step_orders(
        [
            (continuity_order, continuity_path),
            (particle_order, particle_metrics_path),
            (convergence_order, convergence_log_path),
            (profiling_order, profiling_path),
            (memory_order, memory_path),
            (momentum_order, momentum_sources),
            (poisson_order, poisson_sources),
        ]
    )
 
    resolved_step, available_steps = _resolve_summary_step(
        step,
        continuity_rows,
        particle_rows,
        momentum_rows,
        poisson_rows,
        profiling_rows,
        convergence_rows,
        memory_rows,
        step_orders=step_orders,
        selection_mode=selection_mode,
    )
    if resolved_step is None:
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="summary",
            file_path=log_dir,
            message="No summary-capable run artifacts were found under the run log directory.",
            hint="Run the solver first, then retry summarize on a run directory that contains continuity or solver convergence logs.",
        )
        sys.exit(1)
 
    if step is not None and step not in set(available_steps):
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="step",
            file_path=context["run_dir"],
            message=f"Requested step {step} is not present in the available summary artifacts.",
            hint=f"Available steps include: {available_steps[:10]}{'...' if len(available_steps) > 10 else ''}",
        )
        sys.exit(1)
 
    continuity_step_rows = sorted(continuity_rows.get(resolved_step, []), key=lambda row: row["block"])
    continuity_summary = {"available": bool(continuity_step_rows), "blocks": continuity_step_rows}
    if continuity_step_rows:
        divergence_values = [
            abs(row["max_divergence"])
            for row in continuity_step_rows
            if row["max_divergence"] is not None
        ]
        continuity_summary["max_abs_divergence"] = max(divergence_values) if divergence_values else None
        continuity_summary["net_flux"] = continuity_step_rows[0].get("net_flux")
        continuity_summary["flux_in"] = continuity_step_rows[0].get("flux_in")
        continuity_summary["flux_out"] = continuity_step_rows[0].get("flux_out")
 
    momentum_step_rows = [row for _, row in sorted(momentum_rows.get(resolved_step, {}).items())]
    momentum_summary = {"available": bool(momentum_step_rows), "blocks": momentum_step_rows}
 
    poisson_step_rows = [row for _, row in sorted(poisson_rows.get(resolved_step, {}).items())]
    poisson_summary = {"available": bool(poisson_step_rows), "blocks": poisson_step_rows}
 
    particle_summary = {"available": resolved_step in particle_rows}
    if resolved_step in particle_rows:
        particle_summary.update(particle_rows[resolved_step])
 
    profiling_summary = {"available": resolved_step in profiling_rows}
    if resolved_step in profiling_rows:
        functions = sorted(
            profiling_rows[resolved_step],
            key=lambda row: (row.get("step_time_s") or 0.0),
            reverse=True,
        )
        profiling_summary["functions"] = functions
        profiling_summary["total_logged_step_time_s"] = sum(
            row.get("step_time_s") or 0.0 for row in functions
        )
 
    memory_summary = {"available": resolved_step in memory_rows}
    if resolved_step in memory_rows:
        memory_summary.update(memory_rows[resolved_step])
        memory_summary["source"] = memory_path
        memory_summary["max_process_change_mb"] = memory_meta.get("max_process_change_mb")
        memory_summary["final_event"] = memory_meta.get("final_event")
        memory_summary["final_reason"] = memory_meta.get("final_reason")
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = True
    elif memory_meta.get("available"):
        latest_sample_row = memory_meta.get("latest_sample_row")
        if latest_sample_row:
            memory_summary.update(latest_sample_row)
        memory_summary.update(memory_meta)
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = False
 
    snapshot_summary = {"available": False}
    if context["particle_console_output_freq"] and context["particle_console_output_freq"] > 0:
        snapshot_summary = _find_particle_snapshot_for_step(
            context["run_dir"],
            log_dir,
            resolved_step,
            preview_rows=max(1, snapshot_rows),
            particle_console_output_freq=context["particle_console_output_freq"],
            particle_log_interval=context["particle_log_interval"],
        )
 
    monitor_info = {
        "profiling_timestep_mode": context["profiling_cfg"].get("mode"),
        "profiling_timestep_file": context["profiling_cfg"].get("timestep_file"),
        "particle_console_output_frequency": context["particle_console_output_freq"],
        "particle_log_interval": context["particle_log_interval"],
    }
 
    return {
        "run_id": context["manifest"].get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "step": resolved_step,
        "selected_via": "explicit" if step is not None else ("max_step" if selection_mode == "max_step" else "latest_available"),
        "available_steps": available_steps,
        "launch_mode": context["manifest"].get("launch_mode"),
        "created_at": context["manifest"].get("created_at"),
        "monitor": monitor_info,
        "particles_configured": context["particle_count_cfg"],
        "sources": {
            "continuity_log": continuity_path if os.path.isfile(continuity_path) else None,
            "particle_metrics_log": particle_metrics_path if os.path.isfile(particle_metrics_path) else None,
            "momentum_logs": momentum_sources,
            "poisson_logs": poisson_sources,
            "profiling_timestep_csv": profiling_path if os.path.isfile(profiling_path) else None,
            "solution_convergence_log": convergence_log_path if os.path.isfile(convergence_log_path) else None,
            "runtime_memory_log": memory_path if os.path.isfile(memory_path) else None,
        },
        "continuity": continuity_summary,
        "momentum": momentum_summary,
        "poisson": poisson_summary,
        "particles": particle_summary,
        "particle_snapshot": snapshot_summary,
        "profiling": profiling_summary,
        "memory": memory_summary,
        "convergence": convergence_rows.get(resolved_step) if convergence_rows else None,
    }
 
 
def render_run_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render a run-step summary in human or JSON form.
    @param[in] payload Argument passed to `render_run_summary()`.
    @param[in] output_format Argument passed to `render_run_summary()`.
    """
    if output_format == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        return
 
    print("\n" + "=" * 60)
    print("                     RUN STEP SUMMARY")
    print("=" * 60)
    print(f"  Run ID         : {payload.get('run_id')}")
    print(f"  Run directory  : {os.path.relpath(payload.get('run_dir'))}")
    print(f"  Step           : {payload.get('step')} ({payload.get('selected_via')})")
    if payload.get("launch_mode"):
        print(f"  Launch mode    : {payload.get('launch_mode')}")
    if payload.get("created_at"):
        print(f"  Created at     : {payload.get('created_at')}")
 
    continuity = payload.get("continuity", {})
    print("\n  Continuity:")
    if continuity.get("available"):
        if continuity.get("max_abs_divergence") is not None:
            print(f"    max |div|    : {continuity['max_abs_divergence']:.6e}")
        if continuity.get("net_flux") is not None:
            print(f"    net flux     : {continuity['net_flux']:.6e}")
        for row in continuity.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: div={_format_summary_float(row.get('max_divergence'))} "
                f"rhs={_format_summary_float(row.get('rhs_sum'))} location={row['max_divergence_location']}"
            )
    else:
        print("    unavailable")
 
    momentum = payload.get("momentum", {})
    print("\n  Momentum:")
    if momentum.get("available"):
        for row in momentum.get("blocks", []):
            if row.get("solver") == "Newton Krylov":
                print(f"    block {row['block']}: solver=Newton Krylov")
                print(
                    f"      newton={row.get('newton_iterations')} "
                    f"krylov={row.get('krylov_iterations')} "
                    f"evals={row.get('residual_evaluations')}"
                )
                print(
                    f"      final={_format_summary_float(row.get('final_norm'))} "
                    f"reason={row.get('reason')} state={row.get('state')}"
                )
                continue
            status = row.get("status") or "unknown"
            accepted = row.get("accepted_count")
            rejected = row.get("rejected_count")
            counts_str = f" accepted={accepted} rejected={rejected}" if accepted is not None else ""
            # Phase 3+: logged as dtau (physical time) + cfl_eff (dimensionless Courant number).
            dtau_val = row.get("dtau")
            cfl_in   = row.get("cfl_eff")
            cfl_out  = row.get("cfl_eff_after")
            dtau_out = row.get("dtau_after")
            if cfl_in is not None and cfl_out is not None:
                cfl_str = f"cfl_eff {cfl_in:.4f}->{cfl_out:.4f}  dtau {_format_summary_float(dtau_val)}->{_format_summary_float(dtau_out)}"
            elif cfl_in is not None:
                cfl_str = f"cfl_eff={_format_summary_float(cfl_in, '.4f')}  dtau={_format_summary_float(dtau_val)}"
            else:
                cfl_str = "cfl_eff=n/a"
            ratio = row.get("trial_ratio")
            smoothed = row.get("smoothed_ratio")
            if ratio is not None and smoothed is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)} (ema={_format_summary_float(smoothed)})"
            elif ratio is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)}"
            else:
                ratio_str = ""
            print(f"    block {row['block']} [{status}]:{counts_str}  {cfl_str}{ratio_str}")
            print(
                f"      resid={_format_summary_float(row.get('residual_norm'))}"
                f"  delta={_format_summary_float(row.get('delta_norm'))}"
            )
    else:
        print("    unavailable")
 
    poisson = payload.get("poisson", {})
    print("\n  Poisson:")
    if poisson.get("available"):
        for row in poisson.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: iter={row['iterations']} "
                f"true={_format_summary_float(row.get('true_norm'))} "
                f"rel={_format_summary_float(row.get('relative_norm'))}"
            )
    else:
        print("    unavailable")
 
    convergence = payload.get("convergence")
    print("\n  Solution Convergence:")
    if convergence is not None:
        mode = convergence.get("mode", "unknown")
        ref = convergence.get("ref")
        print(f"    mode           : {mode}  (ref={'yes' if ref else 'no'})")
        if mode in ("steady_deterministic", "transient"):
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "periodic_deterministic":
            ph = convergence.get("ph")
            per = convergence.get("per")
            print(f"    phase          : {ph}/{per}")
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "statistical_steady":
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  win={_format_summary_float(convergence.get('spd_win'))}  win_drift={_format_summary_float(convergence.get('spd_win_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  win={_format_summary_float(convergence.get('ke_win'))}  win_drift={_format_summary_float(convergence.get('ke_win_abs'))}")
    else:
        print("    unavailable")
 
    particles = payload.get("particles", {})
    print("\n  Particles:")
    if particles.get("available"):
        loss_summary = f"lost={particles.get('lost_particles')}"
        if particles.get("lost_particles_cumulative") is not None:
            loss_summary = (
                f"lost(step/total)={particles.get('lost_particles')}/"
                f"{particles.get('lost_particles_cumulative')}"
            )
        print(
            "    "
            f"total={particles.get('total_particles')} {loss_summary} "
            f"migrated={particles.get('migrated_particles')} occupied={particles.get('occupied_cells')} "
            f"imbalance={_format_summary_float(particles.get('load_imbalance'), '.2f')}"
        )
    else:
        print("    unavailable")
 
    memory = payload.get("memory", {})
    print("\n  Runtime Memory:")
    if memory.get("available"):
        if memory.get("source"):
            print(f"    source        : {os.path.relpath(memory.get('source'))}")
        if memory.get("step") is not None and not memory.get("step_match", True):
            print(f"    memory step   : {memory.get('step')} (latest memory row; selected step {memory.get('selected_step')} has no row yet)")
        if memory.get("event"):
            print(f"    event         : {memory.get('event')}  reason={memory.get('reason', '-')}")
        print(f"    process max   : {_format_summary_float(memory.get('process_current_mb_max'), '.3f')} MB current, {_format_summary_float(memory.get('process_peak_mb_max'), '.3f')} MB peak")
        print(f"    PETSc max     : {_format_summary_float(memory.get('petsc_allocated_mb_max'), '.3f')} MB allocated, {_format_summary_float(memory.get('petsc_peak_allocated_mb_max'), '.3f')} MB peak")
        print(f"    max change    : {_format_summary_float(memory.get('max_process_change_mb'), '.3f')} MB")
        if memory.get("final_reason"):
            print(f"    final reason  : {memory.get('final_reason')}")
    else:
        print("    unavailable")
 
    snapshot = payload.get("particle_snapshot", {})
    if snapshot.get("available"):
        print("\n  Particle Snapshot (sampled):")
        print(f"    source        : {os.path.relpath(snapshot.get('source'))}")
        cadence = snapshot.get("cadence", {})
        print(
            "    "
            f"cadence       : every {cadence.get('particle_console_output_frequency', 'n/a')} steps, "
            f"row interval {cadence.get('particle_log_interval', 'n/a')}"
        )
        print(f"    sampled rows  : {snapshot.get('sampled_rows')}")
        speed = snapshot.get("speed", {})
        if speed:
            print(
                "    "
                f"sampled speeds: min={_format_summary_float(speed.get('min'))} "
                f"mean={_format_summary_float(speed.get('mean'))} "
                f"max={_format_summary_float(speed.get('max'))} "
                f"std={_format_summary_float(speed.get('std'))} "
                f"stagnant(<1e-6)={speed.get('stagnant_count', 0)}"
            )
        bounds = snapshot.get("position_bounds", {})
        centroid = snapshot.get("position_centroid")
        if bounds:
            bound_parts = []
            for axis in ("x", "y", "z"):
                if axis in bounds:
                    bound_parts.append(
                        f"{axis}=[{_format_summary_float(bounds[axis][0])}, { _format_summary_float(bounds[axis][1])}]"
                    )
            print(f"    sampled bounds: {' '.join(bound_parts)}")
        if centroid:
            print(
                "    "
                f"sampled center: ({_format_summary_float(centroid[0])}, "
                f"{_format_summary_float(centroid[1])}, {_format_summary_float(centroid[2])})"
            )
        distribution = snapshot.get("sampled_distribution", {})
        if distribution:
            print(
                "    "
                f"sampled spread: unique_cells={distribution.get('unique_cells', 'n/a')} "
                f"duplicate_cells={distribution.get('duplicate_cells', 'n/a')} "
                f"unique_pids={distribution.get('unique_pids', 'n/a')} "
                f"ranks={distribution.get('rank_counts', {})}"
            )
        weights = snapshot.get("weights", {})
        if weights:
            weight_parts = []
            for component, summary in sorted(weights.items()):
                weight_parts.append(
                    f"{component}[min/max]=[{_format_summary_float(summary.get('min'))}, { _format_summary_float(summary.get('max'))}]"
                )
            print(f"    sampled weights: {' '.join(weight_parts)}")
        checks = snapshot.get("checks", {})
        if checks:
            print(
                "    "
                f"checks        : duplicate_pid={checks.get('duplicate_pid_count', 0)} "
                f"nan={checks.get('nan_count', 0)} inf={checks.get('inf_count', 0)} "
                f"zero_weight={checks.get('zero_weight_count', 0)} "
                f"negative_weight={checks.get('negative_weight_count', 0)}"
            )
        top_speeds = snapshot.get("top_speeds", [])
        if top_speeds:
            summary = ", ".join(
                f"pid={row.get('pid')} {_format_summary_float(row.get('speed'))}"
                for row in top_speeds
            )
            print(f"    top speeds    : {summary}")
        delta_summary = snapshot.get("delta_from_previous_snapshot", {})
        if delta_summary.get("available"):
            print(
                "    "
                f"vs prev snap  : step={delta_summary.get('previous_step')} "
                f"matched_pids={delta_summary.get('matched_pids')} "
                f"mean_disp={_format_summary_float(delta_summary.get('mean_displacement'))} "
                f"max_disp={_format_summary_float(delta_summary.get('max_displacement'))} "
                f"rank_moves={delta_summary.get('rank_migrations')} "
                f"cell_changes={delta_summary.get('cell_changes')} "
                f"new={delta_summary.get('new_count')} gone={delta_summary.get('gone_count')}"
            )
        print("    preview rows  :")
        for row in snapshot.get("preview_rows", []):
            print(
                "    "
                f"pid={row.get('pid')} rank={row.get('rank')} "
                f"cell={row.get('cell')} pos={row.get('position')} vel={row.get('velocity')}"
            )
 
    profiling = payload.get("profiling", {})
    print("\n  Profiling:")
    if profiling.get("available"):
        print(f"    total logged step time: {profiling.get('total_logged_step_time_s', 0.0):.6f}s")
        for row in profiling.get("functions", [])[:5]:
            print(
                "    "
                f"{row.get('function')}: calls={row.get('calls')} "
                f"time={_format_summary_float(row.get('step_time_s'), '.6f', '0.000000')}s"
            )
    else:
        print("    unavailable")
    print("=" * 60)
 
 
_CONFIG_SUMMARY_WIDTH = 78
 
 
def _summary_display_value(value) -> str:
    """!
    @brief Format one configuration-summary value for compact text output.
    @param[in] value Value to format.
    @return Compact human-readable value.
    """
    if value is None:
        return "-"
    if isinstance(value, bool):
        return "enabled" if value else "disabled"
    if isinstance(value, float):
        return f"{value:.6g}"
    if isinstance(value, (list, tuple)):
        return ", ".join(_summary_display_value(item) for item in value) if value else "none"
    if isinstance(value, dict):
        if not value:
            return "none"
        return ", ".join(f"{key}={_summary_display_value(item)}" for key, item in value.items())
    return str(value)
 
 
def _print_config_header(title: str, subtitle: "str | None" = None):
    """!
    @brief Print a strong dashboard-style configuration summary header.
    @param[in] title Section title.
    @param[in] subtitle Optional one-line section subtitle.
    """
    print("\n" + "=" * _CONFIG_SUMMARY_WIDTH)
    print(f"{title:^78}")
    if subtitle:
        print(f"{subtitle:^78}")
    print("=" * _CONFIG_SUMMARY_WIDTH)
 
 
def _print_config_group(title: str, rows: list):
    """!
    @brief Print an aligned configuration-summary field group.
    @param[in] title Group title.
    @param[in] rows Sequence of `(label, value)` pairs.
    """
    visible_rows = [(label, value) for label, value in rows if value is not None]
    if not visible_rows:
        return
    print(f"\n  {title}")
    print(f"  {'-' * (len(title) + 1)}")
    for label, value in visible_rows:
        print(f"    {label:<32} {_summary_display_value(value)}")
 
 
def _flatten_summary_mapping(mapping: dict, prefix: str = "") -> list:
    """!
    @brief Flatten nested summary mappings into readable dotted field rows.
    @param[in] mapping Mapping to flatten.
    @param[in] prefix Optional parent-field prefix.
    @return Sequence of `(field, value)` pairs.
    """
    rows = []
    for key, value in mapping.items():
        label = f"{prefix}.{key}" if prefix else str(key)
        if isinstance(value, dict) and value:
            rows.extend(_flatten_summary_mapping(value, label))
        else:
            rows.append((label, value))
    return rows
 
 
def _render_run_overview_text(summary: dict):
    """!
    @brief Render run metadata as a compact dashboard.
    @param[in] summary Curated run overview mapping.
    """
    _print_config_header("RUN OVERVIEW", summary.get("run_id"))
    _print_config_group(
        "Identity",
        [
            ("Run directory", os.path.relpath(summary.get("run_dir")) if summary.get("run_dir") else None),
            ("Created", summary.get("created_at")),
            ("Launch mode", summary.get("launch_mode")),
            ("PICurv release", summary.get("release_version")),
            ("Build", summary.get("build_id")),
            ("Git commit", summary.get("git_commit")),
        ],
    )
    _print_config_group(
        "Execution",
        [
            ("Solver MPI processes", summary.get("solver_num_procs")),
            ("Post MPI processes", summary.get("post_num_procs")),
            ("Stages requested", summary.get("stages_requested")),
            ("Stages ready/completed", summary.get("stages_completed_or_submitted")),
        ],
    )
 
 
def _render_case_summary_text(summary: dict):
    """!
    @brief Render the case summary as a glanceable simulation dashboard.
    @param[in] summary Curated case configuration mapping.
    """
    run = summary.get("run_control", {})
    props = summary.get("properties", {})
    grid = summary.get("grid", {})
    domain = summary.get("domain", {})
    physics = summary.get("physics", {})
    subtitle = (
        f"{domain.get('dimensionality', '-')} | {domain.get('blocks', '-')} block(s) | "
        f"Re={_summary_display_value(props.get('reynolds_number'))}"
    )
    _print_config_header("CASE SUMMARY", subtitle)
    _print_config_group(
        "Simulation",
        [
            ("Step range", f"{run.get('start_step')} -> {run.get('end_step')} ({run.get('total_steps')} steps)"),
            ("Physical timestep", run.get("dt_physical")),
            ("Nondimensional timestep", run.get("dt_nondimensional")),
            ("Physical duration", run.get("duration_physical")),
            ("Initial conditions", props.get("initial_conditions")),
        ],
    )
    _print_config_group(
        "Fluid And Scaling",
        [
            ("Reynolds number", props.get("reynolds_number")),
            ("Reference length", props.get("length_ref")),
            ("Reference velocity", props.get("velocity_ref")),
            ("Density", props.get("density")),
            ("Viscosity", props.get("viscosity")),
        ],
    )
    _print_config_group(
        "Domain And Grid",
        [
            ("Grid mode", grid.get("mode")),
            ("Blocks", domain.get("blocks")),
            ("Dimensionality", domain.get("dimensionality")),
            ("Periodic axes", domain.get("periodic")),
            ("MPI grid layout", grid.get("processor_layout")),
            ("Grid source", grid.get("source_file")),
        ],
    )
    if grid.get("programmatic_settings"):
        _print_config_group("Programmatic Grid", _flatten_summary_mapping(grid["programmatic_settings"]))
    _print_config_group(
        "Physics",
        [
            ("Particles", physics.get("particles")),
            ("FSI", physics.get("fsi")),
            ("Turbulence", physics.get("turbulence")),
            ("Statistics", physics.get("statistics")),
        ],
    )
    boundary_blocks = summary.get("boundary_conditions", [])
    if boundary_blocks:
        print("\n  Boundary Conditions")
        print("  --------------------")
        print(f"    {'Block':<7} {'Face':<8} {'Type':<12} Handler")
        print(f"    {'-' * 7} {'-' * 8} {'-' * 12} {'-' * 20}")
        for block in boundary_blocks:
            for face in block.get("faces", []):
                print(
                    f"    {block.get('block', '-')!s:<7} {face.get('face', '-'):<8} "
                    f"{face.get('type', '-'):<12} {face.get('handler', '-')}"
                )
 
 
def _render_solver_summary_text(summary: dict):
    """!
    @brief Render the solver summary as a glanceable numerical-method dashboard.
    @param[in] summary Curated solver configuration mapping.
    """
    momentum = summary.get("momentum", {})
    poisson = summary.get("poisson", {})
    operation = summary.get("operation_mode", {})
    subtitle = (
        f"Field: {operation.get('eulerian_field_source', '-')} | "
        f"Momentum: {momentum.get('type', '-')} | Poisson: {poisson.get('method', '-')}"
    )
    _print_config_header("SOLVER SUMMARY", subtitle)
    _print_config_group("Operation", _flatten_summary_mapping(operation))
    _print_config_group(
        "Primary Methods",
        [
            ("Momentum solver", momentum.get("type")),
            ("Central differencing", momentum.get("central_diff")),
            ("Poisson method", poisson.get("method")),
            ("Interpolation", summary.get("interpolation")),
            ("Convergence mode", summary.get("solution_convergence", {}).get("mode")),
        ],
    )
    _print_config_group("Momentum Tolerances", _flatten_summary_mapping(momentum.get("tolerances", {})))
    control_heading = (
        "Newton--Krylov Controls" if momentum.get("type") == "newton_krylov"
        else "Dual-Time Pseudo-Time Controls" if momentum.get("type") == "DUALTIME_PICARD_JAMESON_RK"
        else "Momentum Controls"
    )
    _print_config_group(control_heading, _flatten_summary_mapping(momentum.get("controls", {})))
    _print_config_group("Poisson Configuration", _flatten_summary_mapping(poisson))
    _print_config_group("Solution Convergence", _flatten_summary_mapping(summary.get("solution_convergence", {})))
    _print_config_group("Scalar Transport", _flatten_summary_mapping(summary.get("scalar_transport", {})))
    _print_config_group("Verification Sources", _flatten_summary_mapping(summary.get("verification", {})))
    passthrough = summary.get("petsc_passthrough", {})
    _print_config_group(
        "Advanced PETSc Options",
        [("Option count", passthrough.get("count")), ("Option names", passthrough.get("options"))],
    )
 
 
def _render_monitor_summary_text(summary: dict):
    """!
    @brief Render the monitor summary as a glanceable observability dashboard.
    @param[in] summary Curated monitor configuration mapping.
    """
    logging_cfg = summary.get("logging", {})
    profiling = summary.get("profiling", {})
    diagnostics = summary.get("diagnostics", {})
    io_cfg = summary.get("io", {})
    memory_log = diagnostics.get("runtime_memory_log", {})
    subtitle = (
        f"Verbosity: {logging_cfg.get('verbosity', '-')} | Profiling: {profiling.get('mode', '-')} | "
        f"Output every {_summary_display_value(io_cfg.get('data_output_frequency'))} steps"
    )
    _print_config_header("MONITOR SUMMARY", subtitle)
    _print_config_group(
        "Logging",
        [
            ("Verbosity", logging_cfg.get("verbosity")),
            ("Enabled functions", logging_cfg.get("enabled_functions")),
        ],
    )
    _print_config_group("Profiling", _flatten_summary_mapping(profiling))
    _print_config_group(
        "Output Cadence",
        [
            ("Field output", io_cfg.get("data_output_frequency")),
            ("Particle snapshots", io_cfg.get("particle_console_output_frequency")),
            ("Particle row interval", io_cfg.get("particle_log_interval")),
        ],
    )
    _print_config_group("Output Directories", _flatten_summary_mapping(io_cfg.get("directories", {})))
    _print_config_group(
        "Diagnostics",
        [
            ("Enabled PETSc diagnostics", diagnostics.get("enabled_petsc")),
            ("Runtime memory log", memory_log.get("enabled")),
            ("Runtime memory file", memory_log.get("file")),
        ],
    )
    _print_config_group("PETSc Diagnostic Settings", _flatten_summary_mapping(diagnostics.get("petsc", {})))
    solver_monitoring = summary.get("solver_monitoring", {})
    _print_config_group(
        "Solver Monitoring",
        [
            ("Enabled flags", solver_monitoring.get("enabled_flags")),
            ("All flags", solver_monitoring.get("flags")),
        ],
    )
 
 
def render_selected_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render selected timestep-independent config views and optional health.
    @param[in] payload Combined selected summary payload.
    @param[in] output_format Output format.
    """
    if output_format == "json":
        json_payload = {key: value for key, value in payload.items() if key != "_health_requested"}
        print(json.dumps(json_payload, indent=2, sort_keys=True))
        return
 
    if payload.get("run_overview") is not None:
        _render_run_overview_text(payload["run_overview"])
    renderers = {
        "case": _render_case_summary_text,
        "solver": _render_solver_summary_text,
        "monitor": _render_monitor_summary_text,
    }
    for key in ("case", "solver", "monitor"):
        if key in payload.get("configuration", {}):
            renderers[key](payload["configuration"][key])
    storage = payload.get("storage")
    if isinstance(storage, dict):
        print("\nSTORAGE")
        print("=" * 78)
        print(f"  State      : {storage.get('state', 'LOCAL')}")
        if storage.get("archive_id"):
            print(f"  Archive ID : {storage['archive_id']}")
        if storage.get("label"):
            print(f"  Label      : {storage['label']}")
    if payload.get("_health_requested"):
        health_payload = {
            key: value for key, value in payload.items()
            if key not in {"run_overview", "configuration", "storage", "_health_requested"}
        }
        render_run_summary(health_payload, output_format="text")
 
 
_SUMMARY_PLOT_LOG_SCALE_FIELDS = {
    "max_divergence", "delta_norm", "delta_rel", "residual_norm", "residual_rel",
    "unpreconditioned_norm", "true_norm", "relative_norm",
    "u_abs_l2", "u_rel_l2", "p_abs_l2", "p_rel_l2",
    "spd_abs", "spd_rel", "ke_abs", "ke_rel",
    "spd_win_abs", "spd_win_rel", "spd_rms_abs", "spd_rms_rel",
    "ke_win_abs", "ke_win_rel", "ke_rms_abs", "ke_rms_rel",
    "parseval_residual", "zero_mode_energy",
}
 
 
_SUMMARY_PLOT_FIELD_LABELS = {
    "max_divergence": "Maximum |divergence|",
    "rhs_sum": "Continuity right-hand-side sum",
    "flux_in": "Inflow flux",
    "flux_out": "Outflow flux",
    "net_flux": "Net boundary flux",
    "total_particles": "Particle count",
    "lost_particles": "Particles lost per step",
    "lost_particles_cumulative": "Cumulative particles lost",
    "migrated_particles": "Migrated particles",
    "occupied_cells": "Occupied cells",
    "load_imbalance": "Particle load imbalance",
    "migration_passes": "Particle migration passes",
    "pseudo_iterations": "Pseudo-iterations to convergence",
    "newton_iterations": "Newton iterations to convergence",
    "iterations": "Linear iterations to convergence",
    "dtau": "Pseudo-time step, Δτ",
    "dtau_after": "Accepted pseudo-time step, Δτ",
    "cfl_eff": "Effective pseudo-CFL",
    "cfl_eff_after": "Accepted effective pseudo-CFL",
    "delta_norm": "Momentum update norm, ‖ΔU‖",
    "delta_rel": "Relative momentum update, ‖ΔU‖/‖ΔU₀‖",
    "residual_norm": "Residual norm",
    "residual_rel": "Relative residual norm",
    "trial_ratio": "Pseudo-CFL trial ratio",
    "smoothed_ratio": "Smoothed pseudo-CFL ratio",
    "unpreconditioned_norm": "Unpreconditioned residual norm",
    "true_norm": "True residual norm",
    "relative_norm": "Relative residual norm",
    "calls": "Calls per physical step",
    "step_time_s": "Wall time per physical step (s)",
    "process_current_mb_max": "Maximum resident memory (MiB)",
    "process_peak_mb_max": "Peak resident memory (MiB)",
    "petsc_allocated_mb_max": "PETSc allocated memory (MiB)",
    "petsc_peak_allocated_mb_max": "Peak PETSc allocated memory (MiB)",
    "process_change_mb_max": "Resident-memory change (MiB)",
    "u_abs_l2": "Velocity L² error",
    "u_rel_l2": "Relative velocity L² error",
    "p_abs_l2": "Pressure L² error",
    "p_rel_l2": "Relative pressure L² error",
    "mean_speed": "Volume-mean speed",
    "spd_ref": "Reference mean speed",
    "spd_abs": "Absolute mean-speed drift",
    "spd_rel": "Relative mean-speed drift",
    "mean_ke": "Mean kinetic energy",
    "ke_ref": "Reference mean kinetic energy",
    "ke_abs": "Absolute kinetic-energy drift",
    "ke_rel": "Relative kinetic-energy drift",
    "spd_win": "Window-mean speed",
    "spd_win_prev": "Previous window-mean speed",
    "spd_win_abs": "Absolute window-mean speed drift",
    "spd_win_rel": "Relative window-mean speed drift",
    "spd_rms_win": "Window RMS mean speed",
    "spd_rms_abs": "Absolute RMS speed drift",
    "spd_rms_rel": "Relative RMS speed drift",
    "ke_win": "Window-mean kinetic energy",
    "ke_win_prev": "Previous window-mean kinetic energy",
    "ke_win_abs": "Absolute window-mean kinetic-energy drift",
    "ke_win_rel": "Relative window-mean kinetic-energy drift",
    "ke_rms_win": "Window RMS kinetic energy",
    "ke_rms_abs": "Absolute RMS kinetic-energy drift",
    "ke_rms_rel": "Relative RMS kinetic-energy drift",
    "resolved_kinetic_energy": "Resolved kinetic energy",
    "spectrum_total_energy": "Integrated spectral energy",
    "parseval_residual": "Parseval residual",
    "spectrum_peak_k": "Peak wavenumber, kₚₑₐₖ",
    "zero_mode_energy": "Zero-mode energy",
    "integral_length_scale": "Integral length scale",
    "taylor_microscale": "Taylor microscale",
    "dissipation_over_viscosity": "Dissipation / kinematic viscosity",
}
 
 
_SUMMARY_PLOT_SOURCE_TITLES = {
    "continuity": "Continuity",
    "particles": "Particle transport",
    "momentum": "Momentum solver",
    "poisson": "Pressure Poisson solver",
    "profiling": "Runtime profile",
    "memory": "Runtime memory",
    "convergence": "Solution convergence",
    "spectra": "Turbulence spectrum",
}
 
 
_SUMMARY_ITERATION_HISTORY_FIELDS = {
    "dtau", "dtau_after", "cfl_eff", "cfl_eff_after", "delta_norm", "delta_rel",
    "residual_norm", "residual_rel", "trial_ratio", "smoothed_ratio",
    "unpreconditioned_norm", "true_norm", "relative_norm",
}
 
 
_SUMMARY_COUNT_FIELDS = {
    "total_particles", "lost_particles", "lost_particles_cumulative",
    "migrated_particles", "occupied_cells", "migration_passes", "calls",
    "pseudo_iterations", "newton_iterations", "iterations",
}
 
 
def _humanize_plot_identifier(value: str) -> str:
    """!
    @brief Convert one machine-oriented identifier into a readable plot label.
    @param[in] value Dotted path or snake-case identifier.
    @return Human-readable label.
    """
    text = str(value).split(".")[-1].replace("_", " ").strip()
    replacements = {
        "l2": "L²", "linf": "L∞", "msd": "mean-squared displacement",
        "pct": "percentage", "p95": "95th percentile", "cfl": "CFL",
        "ke": "kinetic energy", "rms": "RMS",
    }
    words = [replacements.get(word.lower(), word) for word in text.split()]
    return " ".join(words[:1]).capitalize() + (" " + " ".join(words[1:]) if len(words) > 1 else "")
 
 
def _summary_field_label(field: str) -> str:
    """!
    @brief Return the report-facing label for one logged scalar field.
    @param[in] field Logged scalar field name.
    @return Report-facing label.
    """
    return _SUMMARY_PLOT_FIELD_LABELS.get(field, _humanize_plot_identifier(field))
 
 
def _summary_physical_time(context: dict, record: dict) -> "float | None":
    """!
    @brief Resolve a record's physical time from its artifact or copied case configuration.
    @param[in] context Summary context with copied case configuration.
    @param[in] record Collected plot record.
    @return Physical time, or None when it cannot be resolved.
    """
    explicit = record.get("coordinates", {}).get("time")
    if explicit is not None:
        return float(explicit)
    try:
        dt = float((context.get("case_cfg") or {}).get("run_control", {}).get("dt_physical"))
    except (TypeError, ValueError):
        return None
    return float(record["step"]) * dt if math.isfinite(dt) and dt > 0.0 else None
 
 
def _read_runtime_diagnostics_csv(path):
    """!
    @brief Yields `(segment, row)` for each data line of a runtime diagnostics CSV.
 
    The solver's runtime CSVs share one shape: a `step,...` header written once, data
    rows appended across the run, and a comment marker at each seam where a continuation
    resumed. Rows before the header, or whose width disagrees with it, are skipped rather
    than guessed at. `segment` counts the continuations seen so far, so a caller can keep
    restarts as separate series instead of drawing a line across the seam.
 
    @param path Diagnostics CSV to read.
    @return Generator of `(segment_index, {column: text})` pairs.
    """
    segment = 0
    header = []
    with open(path, "r", encoding="utf-8", errors="replace", newline="") as handle:
        for raw_line in handle:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            if raw_line.lstrip().startswith("step,"):
                header = [name.strip() for name in raw_line.strip().split(",")]
                continue
            parts = [part.strip() for part in raw_line.strip().split(",")]
            if not header or len(parts) != len(header):
                continue
            yield segment, dict(zip(header, parts))
 
 
def _append_summary_plot_record(records: list, source: str, step, line: str, values: dict,
                                source_path: str, segment: int = 0, coordinates: dict = None):
    """!
    @brief Append one numeric append-ordered record for summarize plotting.
    @param[out] records Destination record list.
    @param[in] source Qualified source prefix.
    @param[in] step Logged timestep.
    @param[in] line Human-readable line identity.
    @param[in] values Candidate field mapping.
    @param[in] source_path Source artifact path.
    @param[in] segment Zero-based continuation segment within the source artifact.
    @param[in] coordinates Optional independent variables carried by the source row.
    """
    numeric = {
        key: value
        for key, value in values.items()
        if isinstance(value, (int, float)) and not isinstance(value, bool)
    }
    if step is not None and numeric:
        records.append({
            "source": source,
            "step": int(step),
            "line": line,
            "values": numeric,
            "source_path": source_path,
            "segment": int(segment),
            "coordinates": {
                key: value for key, value in (coordinates or {}).items()
                if isinstance(value, (int, float)) and not isinstance(value, bool)
            },
        })
 
 
def _is_summary_plot_continuation_marker(line: str) -> bool:
    """!
    @brief Return whether a log line starts a new continuation segment.
    @param[in] line Candidate raw or stripped log line.
    @return True for the shared continuation marker syntax.
    """
    return bool(re.match(r"^\s*#?\s*=*\s*Continuation from step\s+\d+", line, re.IGNORECASE))
 
 
def _collect_summary_plot_records(context: dict) -> list:
    """!
    @brief Collect append-ordered numeric records from summarize-supported scalar logs.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list.
    """
    records = []
    log_dir = context["log_dir"]
    # The C runtime writes its per-step diagnostics CSVs to the analysis metrics home,
    # not beside the text logs; PicurvOpenDiagnosticsCsv() owns that placement.
    metrics_dir = context["metrics_dir"]
 
    continuity_path = os.path.join(log_dir, "Continuity_Metrics.log")
    if os.path.isfile(continuity_path):
        segment = 0
        with open(continuity_path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                parts = [part.strip() for part in raw_line.split("|")]
                if len(parts) < 8:
                    continue
                step, block = _parse_int_loose(parts[0]), _parse_int_loose(parts[1])
                _append_summary_plot_record(
                    records, "continuity", step, f"block {block}",
                    {
                        "max_divergence": _parse_float_loose(parts[2]),
                        "rhs_sum": _parse_float_loose(parts[4]),
                        "flux_in": _parse_float_loose(parts[5]),
                        "flux_out": _parse_float_loose(parts[6]),
                        "net_flux": _parse_float_loose(parts[7]),
                    },
                    continuity_path, segment,
                )
 
    particle_path = os.path.join(log_dir, "Particle_Metrics.log")
    if os.path.isfile(particle_path):
        segment = 0
        with open(particle_path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                parts = [part.strip() for part in raw_line.split("|")]
                if len(parts) < 8:
                    continue
                step = _parse_int_loose(parts[1])
                offset = 1 if len(parts) >= 9 else 0
                _append_summary_plot_record(
                    records, "particles", step, "particles",
                    {
                        "total_particles": _parse_int_loose(parts[2]),
                        "lost_particles": _parse_int_loose(parts[3]),
                        "lost_particles_cumulative": _parse_int_loose(parts[4]) if offset else None,
                        "migrated_particles": _parse_int_loose(parts[4 + offset]),
                        "occupied_cells": _parse_int_loose(parts[5 + offset]),
                        "load_imbalance": _parse_float_loose(parts[6 + offset]),
                        "migration_passes": _parse_int_loose(parts[7 + offset]),
                    },
                    particle_path, segment,
                )
 
    # Phase 3+: dtau [physical time] + cfl_eff [dimensionless Courant number].
    momentum_regex = re.compile(
        r"Step:\s*(?P<step>\d+)\s*\|\s*PseudoIter\‍(k\‍):\s*(?P<pseudo_iter>\d+)\s*\|"
        r"\s*dtau:\s*(?P<dtau>[-+0-9.eE]+)\s*\|\s*cfl_eff:\s*(?P<cfl_eff>[-+0-9.eE]+)\s*\|"
        r"\s*\|dUk\|:\s*(?P<delta>[-+0-9.eE]+)\s*\|"
        r"\s*\|dUk\|/\|dU0\|:\s*(?P<delta_rel>[-+0-9.eE]+)\s*\|\s*\|Rk\|:\s*(?P<resid>[-+0-9.eE]+)\s*\|"
        r"\s*\|Rk\|/\|R0\|:\s*(?P<resid_rel>[-+0-9.eE]+)"
        r"(?:\s*\|\s*trial_ratio:\s*(?P<trial_ratio>[-+0-9.eE]+)"
        r"(?:\s*\|\s*smoothed_ratio:\s*(?P<smoothed_ratio>[-+0-9.eE]+))?"
        r"\s*\|\s*status:\s*(?P<status>\w+)\s*\|\s*dtau_after:\s*(?P<dtau_after>[-+0-9.eE]+)"
        r"(?:\s*\|\s*cfl_eff_after:\s*(?P<cfl_eff_after>[-+0-9.eE]+))?)?"
    )
    jameson_patterns = [
        os.path.join(log_dir, "Momentum_Solver_DualTime_Picard_Jameson_RK_History_Block_*.log"),
        os.path.join(log_dir, "Momentum_Solver_Convergence_History_Block_*.log"),
    ]
    for path in sorted(path for pattern in jameson_patterns for path in glob.glob(pattern)):
        block_match = re.search(r"Block_(\d+)\.log$", path)
        if not block_match:
            continue
        segment = 0
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                match = momentum_regex.search(raw_line)
                if match:
                    _append_summary_plot_record(
                        records, "momentum", int(match.group("step")), f"block {block_match.group(1)}",
                        {
                            "pseudo_iterations": int(match.group("pseudo_iter")),
                            "dtau": _parse_float_loose(match.group("dtau")),
                            "cfl_eff": _parse_float_loose(match.group("cfl_eff")),
                            "delta_norm": float(match.group("delta")),
                            "delta_rel": float(match.group("delta_rel")),
                            "residual_norm": float(match.group("resid")),
                            "residual_rel": float(match.group("resid_rel")),
                            "trial_ratio": _parse_float_loose(match.group("trial_ratio")),
                            "smoothed_ratio": _parse_float_loose(match.group("smoothed_ratio")),
                            "dtau_after": _parse_float_loose(match.group("dtau_after")),
                            "cfl_eff_after": _parse_float_loose(match.group("cfl_eff_after")),
                        },
                        path, segment,
                        coordinates={"solver_iteration": int(match.group("pseudo_iter"))},
                    )
 
    newton_history_regex = re.compile(
        r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
        r"\s*newton:\s*(?P<newton>\d+)\s*\|\s*nonlinear_norm:\s*(?P<norm>[-+0-9.eE]+)"
    )
    for path in sorted(glob.glob(os.path.join(log_dir, "Momentum_Solver_Newton_Krylov_History_Block_*.log"))):
        segment = 0
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                match = newton_history_regex.search(raw_line)
                if match:
                    _append_summary_plot_record(
                        records, "momentum", int(match.group("step")), f"block {match.group('block')}",
                        {
                            "newton_iterations": int(match.group("newton")),
                            "residual_norm": float(match.group("norm")),
                        },
                        path, segment,
                        coordinates={"solver_iteration": int(match.group("newton"))},
                    )
 
    poisson_regex = re.compile(
        r"ts:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|\s*iter:\s*(?P<iter>\d+)\s*\|"
        r"\s*Unprecond Norm:\s*(?P<unpre>[-+0-9.eE]+)\s*\|\s*True Norm:\s*(?P<true>[-+0-9.eE]+)"
        r"(?:\s*\|\s*Rel Norm:\s*(?P<rel>[-+0-9.eE]+))?"
    )
    for path in sorted(glob.glob(os.path.join(log_dir, "Poisson_Solver_Convergence_History_Block_*.log"))):
        segment = 0
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                match = poisson_regex.search(raw_line)
                if match:
                    _append_summary_plot_record(
                        records, "poisson", int(match.group("step")), f"block {match.group('block')}",
                        {
                            "iterations": int(match.group("iter")),
                            "unpreconditioned_norm": float(match.group("unpre")),
                            "true_norm": float(match.group("true")),
                            "relative_norm": _parse_float_loose(match.group("rel")),
                        },
                        path, segment,
                        coordinates={"solver_iteration": int(match.group("iter"))},
                    )
 
    # The LES coefficient history. cs_effective is the curve an LES run is judged on:
    # for decaying isotropic turbulence it should settle near Lilly's 0.16-0.17.
    les_path = os.path.join(metrics_dir, "les_coefficient.csv")
    if os.path.isfile(les_path):
        for segment, row in _read_runtime_diagnostics_csv(les_path):
            _append_summary_plot_record(
                records, "les", _parse_int_loose(row.get("step")), "coefficient",
                {
                    "cs_effective": _parse_float_loose(row.get("cs_effective")),
                    "cs_mean": _parse_float_loose(row.get("cs_mean")),
                    "coefficient_rms": _parse_float_loose(row.get("coefficient_rms")),
                    "coefficient_min": _parse_float_loose(row.get("coefficient_min")),
                    "coefficient_max": _parse_float_loose(row.get("coefficient_max")),
                    "nu_t_mean": _parse_float_loose(row.get("nu_t_mean")),
                    "nu_t_max": _parse_float_loose(row.get("nu_t_max")),
                    "nu_t_over_nu_mean": _parse_float_loose(row.get("nu_t_over_nu_mean")),
                    "k_sgs_mean": _parse_float_loose(row.get("k_sgs_mean")),
                    "backscatter_fraction": _parse_float_loose(row.get("backscatter_fraction")),
                    "limited_fraction": _parse_float_loose(row.get("limited_fraction")),
                },
                les_path, segment,
            )
 
    # The wall-model history. y_plus_mean is what says whether the first cell sits where
    # the selected law is valid; u_tau is what a channel run is scored against.
    wall_path = os.path.join(metrics_dir, "wall_model.csv")
    if os.path.isfile(wall_path):
        for segment, row in _read_runtime_diagnostics_csv(wall_path):
            _append_summary_plot_record(
                records, "wall_model", _parse_int_loose(row.get("step")), "near wall",
                {
                    "u_tau_mean": _parse_float_loose(row.get("u_tau_mean")),
                    "u_tau_rms": _parse_float_loose(row.get("u_tau_rms")),
                    "u_tau_min": _parse_float_loose(row.get("u_tau_min")),
                    "u_tau_max": _parse_float_loose(row.get("u_tau_max")),
                    "y_plus_mean": _parse_float_loose(row.get("y_plus_mean")),
                    "y_plus_max": _parse_float_loose(row.get("y_plus_max")),
                    "wall_distance_mean": _parse_float_loose(row.get("wall_distance_mean")),
                    "nu_wall_over_nu_mean": _parse_float_loose(row.get("nu_wall_over_nu_mean")),
                    "wall_cells": _parse_int_loose(row.get("wall_cells")),
                },
                wall_path, segment,
            )
 
    profiling_path = os.path.join(log_dir, context["profiling_cfg"].get("timestep_file", "Profiling_Timestep_Summary.csv"))
    if os.path.isfile(profiling_path):
        segment = 0
        columns = None
        with open(profiling_path, "r", encoding="utf-8", errors="replace", newline="") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                values = next(csv.reader([raw_line]))
                if not values:
                    continue
                if columns is None:
                    columns = values
                    continue
                row = dict(zip(columns, values))
                _append_summary_plot_record(
                    records, "profiling", _parse_int_loose(row.get("step")), row.get("function") or "unknown",
                    {"calls": _parse_int_loose(row.get("calls")), "step_time_s": _parse_float_loose(row.get("step_time_s"))},
                    profiling_path, segment,
                )
 
    diagnostics = resolve_diagnostics_config(context["monitor_cfg"])
    memory_path = os.path.join(log_dir, diagnostics["runtime_memory_log"].get("file", "Runtime_Memory.log"))
    if os.path.isfile(memory_path):
        segment = 0
        with open(memory_path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                parts = raw_line.split()
                if len(parts) >= 8 and parts[1] in {"Step", "Post"}:
                    _append_summary_plot_record(
                        records, "memory", _parse_int_loose(parts[0]), "memory",
                        {
                            "process_current_mb_max": _parse_float_loose(parts[2]),
                            "process_peak_mb_max": _parse_float_loose(parts[3]),
                            "petsc_allocated_mb_max": _parse_float_loose(parts[4]),
                            "petsc_peak_allocated_mb_max": _parse_float_loose(parts[5]),
                            "process_change_mb_max": _parse_float_loose(parts[6]),
                        },
                        memory_path, segment,
                    )
 
    convergence_path = os.path.join(log_dir, "solution_convergence.log")
    if os.path.isfile(convergence_path):
        columns = None
        segment = 0
        with open(convergence_path, "r", encoding="utf-8", errors="replace") as f:
            for raw_line in f:
                line = raw_line.strip()
                if _is_summary_plot_continuation_marker(line):
                    segment += 1
                    continue
                if not line or line.startswith(("=", "-")):
                    continue
                if columns is None:
                    columns = [part.strip() for part in raw_line.split("|")]
                    continue
                parts = [part.strip() for part in raw_line.split("|")]
                step = _parse_int_loose(parts[0])
                row = dict(zip(columns, parts))
                values = {
                    name: _parse_float_loose(value)
                    for name, value in row.items()
                    if name not in {"step", "time", "mode", "ref", "ph", "per", "win"}
                }
                _append_summary_plot_record(
                    records, "convergence", step, "convergence", values,
                    convergence_path, segment,
                    coordinates={"time": _parse_float_loose(row.get("time"))},
                )
 
    records.extend(_collect_spectra_plot_records(context))
    return records
 
 
def _collect_spectra_plot_records(context: dict) -> list:
    """!
    @brief Collect the per-step scalar histories written by the spectra post stage.
 
    @details Each spectra task keeps its own history file, so one task becomes one
             plotted line and several tasks compare directly on the same axes.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list; empty when no spectra were measured.
    """
    records = []
    run_dir = context.get("run_dir")
    if not run_dir:
        return records
    spectra_root = os.path.join(
        run_dir, resolve_post_spectra_output_dir(context.get("monitor_cfg") or {})
    )
    for root, _dirs, files in os.walk(spectra_root):
        for filename in sorted(files):
            if not filename.endswith("_history.csv"):
                continue
            history_path = os.path.join(root, filename)
            line = filename[: -len("_history.csv")]
            try:
                with open(history_path, "r", encoding="utf-8", errors="replace") as stream:
                    for row in csv.DictReader(stream):
                        step = _parse_int_loose(row.get("step"))
                        if step is None:
                            continue
                        values = {}
                        for column in POST_SPECTRA_SCALAR_COLUMNS:
                            parsed = _parse_float_loose(row.get(column))
                            if parsed is not None:
                                values[column] = parsed
                        if values:
                            _append_summary_plot_record(
                                records, "spectra", step, line, values, history_path, 0,
                                coordinates={"time": _parse_float_loose(row.get("time"))},
                            )
            except OSError:
                # A history a concurrent post stage is still writing is simply not
                # listed yet; summarize is read-only and must never fail on it.
                continue
    return records
 
 
def _build_summary_plot_catalog(records: list) -> list:
    """!
    @brief Build available qualified-series metadata from plot records.
    @param[in] records Append-ordered plot record list.
    @return Available series catalog.
    """
    catalog = {}
    for record in records:
        for field in record["values"]:
            name = f"{record['source']}.{field}"
            item = catalog.setdefault(name, {"series": name, "lines": {}, "source_paths": set(), "sample_count": 0})
            item["lines"][record["line"]] = item["lines"].get(record["line"], 0) + 1
            item["source_paths"].add(record["source_path"])
            item["sample_count"] += 1
    return [
        {
            **item,
            "lines": [{"label": label, "sample_count": count} for label, count in sorted(item["lines"].items())],
            "source_paths": sorted(item["source_paths"]),
        }
        for _, item in sorted(catalog.items())
    ]
 
 
def _representative_indices(count: int, maximum: int = 6) -> list:
    """!
    @brief Select evenly distributed indices while always retaining both endpoints.
    @param[in] count Number of available ordered states.
    @param[in] maximum Maximum states to retain.
    @return Sorted unique zero-based indices.
    """
    if count <= maximum:
        return list(range(count))
    return sorted({round(index * (count - 1) / (maximum - 1)) for index in range(maximum)})
 
 
def _build_spectrum_plot_request(context: dict, task: str, reference: bool,
                                 linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build a plot.gen request drawing representative measured spectra.
 
    @details A decaying flow has a different spectrum at every step, so states are
             never averaged. Up to six evenly spaced states are retained, including
             the first and last, to show evolution without an unreadable legend.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] task Task basename, or a unique substring of one.
    @param[in] reference Overlay the staged initial-condition spectrum when available.
    @param[in] linear_y Force linear axes instead of the log-log default.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    @throws ValueError when no matching spectrum file exists.
    """
    spectra_dir = os.path.join(
        context["run_dir"],
        resolve_post_spectra_output_dir(context.get("monitor_cfg") or {}),
    )
    candidates = []
    if os.path.isdir(spectra_dir):
        # The staged initial-condition spectrum shares this directory but is the
        # reference overlay, never a task a user can select.
        reference_name = os.path.basename(INITIAL_CONDITION_SPECTRUM_RELPATH)
        candidates = sorted(
            name for name in os.listdir(spectra_dir)
            if name.endswith(".csv")
            and not name.endswith("_history.csv")
            and name != reference_name
        )
    if not candidates:
        raise ValueError(
            "No spectra were found for this run. Run "
            "'picurv run --post-process --only spectra' first."
        )
    matches = [name for name in candidates if task in name] if task else candidates
    if len(matches) != 1:
        available = ", ".join(name[: -len(".csv")] for name in candidates)
        raise ValueError(
            f"Spectrum selector {task!r} matched {len(matches)} files. Available: {available}."
        )
    spectrum_path = os.path.join(spectra_dir, matches[0])
 
    by_step = {}
    times = {}
    with open(spectrum_path, "r", encoding="utf-8", errors="replace") as stream:
        for row in csv.DictReader(stream):
            step = _parse_int_loose(row.get("step"))
            wavenumber = _parse_float_loose(row.get("k"))
            energy = _parse_float_loose(row.get("energy"))
            if step is None or wavenumber is None or energy is None:
                continue
            # A log-log plot cannot carry the zero wavenumber or an empty shell.
            if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                continue
            by_step.setdefault(step, []).append([wavenumber, energy])
            times.setdefault(step, _parse_float_loose(row.get("time")))
    if not by_step:
        raise ValueError(f"{os.path.relpath(spectrum_path)} carries no plottable spectrum rows.")
 
    lines = []
    if reference:
        reference_path = os.path.join(context["run_dir"], INITIAL_CONDITION_SPECTRUM_RELPATH)
        if os.path.isfile(reference_path):
            points = []
            with open(reference_path, "r", encoding="utf-8", errors="replace") as stream:
                for row in csv.DictReader(stream):
                    wavenumber = _parse_float_loose(row.get("k"))
                    energy = _parse_float_loose(row.get("energy"))
                    if wavenumber is None or energy is None:
                        continue
                    if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                        continue
                    points.append([wavenumber, energy])
            if points:
                lines.append({
                    "label": "Initial condition", "points": sorted(points),
                    "role": "reference", "color": "#333333", "line_style": "--",
                })
 
    ordered_steps = sorted(by_step)
    selected_steps = [ordered_steps[index] for index in _representative_indices(len(ordered_steps))]
    spectrum_colors = ("#440154", "#414487", "#2A788E", "#22A884", "#7AD151", "#DCE319")
    for index, step in enumerate(selected_steps):
        time = times.get(step)
        label = f"Step {step}" if time is None else f"t = {time:g} (step {step})"
        lines.append({
            "label": label,
            "points": sorted(by_step[step]),
            "role": "latest" if step == ordered_steps[-1] else "snapshot",
            "color": spectrum_colors[round(index * (len(spectrum_colors) - 1) / max(1, len(selected_steps) - 1))],
            "line_width": 2.4 if step == ordered_steps[-1] else 1.65,
        })
 
    name = matches[0][: -len(".csv")]
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"], f"{name}.png"
    )
    task_match = re.search(r"_(?P<field>[^_]+)_block(?P<block>\d+)_(?P<symbol>[^_]+)$", name)
    subtitle = None
    if task_match:
        subtitle = (
            f"Field {task_match.group('field')} · block {int(task_match.group('block'))} "
            f"· {task_match.group('symbol')} wavenumber"
        )
    return {
        "schema_version": 1,
        "plot_type": "spectrum",
        "series": name,
        "title": "Turbulent kinetic-energy spectrum",
        "subtitle": subtitle,
        "x_label": "Wavenumber, k",
        "y_label": "Energy spectrum, E(k)",
        "x_scale": "linear" if linear_y else "log",
        "y_scale": "linear" if linear_y else "log",
        "legend_title": "Snapshot",
        "show_markers": False,
        "window": {
            "mode": "representative", "last": None,
            "available_steps": len(ordered_steps), "selected_steps": selected_steps,
        },
        "lines": lines,
        "output_path": os.path.abspath(output_path) if output_path else fallback,
    }
 
 
def _build_summary_plot_request(context: dict, records: list, series: str, last_n: "int | None", linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build one normalized plot.gen request from collected summarize records.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] records Append-ordered plot record list.
    @param[in] series Qualified series name.
    @param[in] last_n Optional last-N records per plotted line.
    @param[in] linear_y Whether to force linear scaling.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    """
    source, separator, field = series.partition(".")
    if not separator:
        raise ValueError("plot series must be qualified as '<source>.<field>'")
    matching = [record for record in records if record["source"] == source and field in record["values"]]
    if not matching:
        raise ValueError(f"Plot series '{series}' is unavailable. Use --list-plot-series to inspect available series.")
    latest_segments = {}
    for record in matching:
        source_path = record["source_path"]
        latest_segments[source_path] = max(latest_segments.get(source_path, 0), record.get("segment", 0))
    matching = [
        record for record in matching
        if record.get("segment", 0) == latest_segments[record["source_path"]]
    ]
    is_iteration_history = (
        source in {"momentum", "poisson"} and field in _SUMMARY_ITERATION_HISTORY_FIELDS
        and any("solver_iteration" in record.get("coordinates", {}) for record in matching)
    )
    grouped = {}
    selected_steps = set()
    if is_iteration_history:
        histories = {}
        for record in matching:
            iteration = record.get("coordinates", {}).get("solver_iteration")
            if iteration is None:
                continue
            histories.setdefault((record["source_path"], record["line"]), []).append(record)
        for (_source_path, label), history in histories.items():
            latest_step = max(record["step"] for record in history)
            selected_steps.add(latest_step)
            points = [
                [record["coordinates"]["solver_iteration"], record["values"][field]]
                for record in history if record["step"] == latest_step
            ]
            if last_n is not None:
                points = points[-last_n:]
            grouped.setdefault(f"{label} · step {latest_step}", []).extend(points)
        x_label = "Nonlinear iteration" if source == "momentum" else "Linear iteration"
        x_kind = "integer"
    else:
        uses_physical_time = all(_summary_physical_time(context, record) is not None for record in matching)
        for record in matching:
            x_value = _summary_physical_time(context, record) if uses_physical_time else record["step"]
            grouped.setdefault(record["line"], []).append([x_value, record["values"][field]])
        # Iteration-count fields occur on every nonlinear-history row. Reduce them
        # to the final effort per physical step instead of drawing a y=x staircase.
        if field in {"pseudo_iterations", "newton_iterations", "iterations"}:
            grouped = {
                label: [list(item) for item in {
                    point[0]: max(candidate[1] for candidate in points if candidate[0] == point[0])
                    for point in points
                }.items()]
                for label, points in grouped.items()
            }
        for label, points in grouped.items():
            points.sort(key=lambda point: point[0])
            if last_n is not None:
                grouped[label] = points[-last_n:]
        x_label = "Physical time" if uses_physical_time else "Physical timestep"
        x_kind = "continuous" if uses_physical_time else "integer"
 
    grouped = {label: points for label, points in grouped.items() if points}
    if not grouped:
        raise ValueError(f"Plot series '{series}' has no plottable points in the selected window.")
    if is_iteration_history and len(selected_steps) == 1:
        grouped = {
            label.rsplit(" · step ", 1)[0]: points
            for label, points in grouped.items()
        }
    all_values = [point[1] for points in grouped.values() for point in points]
    use_log = not linear_y and field in _SUMMARY_PLOT_LOG_SCALE_FIELDS and all(value > 0 for value in all_values)
    window_token = f"last-{last_n}" if last_n is not None else "full"
    safe_series = re.sub(r"[^A-Za-z0-9_.-]+", "_", series)
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"],
        f"{safe_series}_{window_token}.png",
    )
    field_label = _summary_field_label(field)
    source_title = _SUMMARY_PLOT_SOURCE_TITLES.get(source, _humanize_plot_identifier(source))
    title = f"{source_title}: {field_label}"
    if is_iteration_history:
        title += " convergence"
    subtitle_bits = []
    if selected_steps:
        ordered = sorted(selected_steps)
        subtitle_bits.append(
            f"Latest physical step {ordered[0]}" if len(ordered) == 1
            else f"Latest available physical steps {ordered[0]}–{ordered[-1]}"
        )
    if last_n is not None:
        subtitle_bits.append(f"Last {last_n} samples per curve")
    legend_title = {
        "continuity": "Block",
        "momentum": "Block",
        "poisson": "Block",
        "profiling": "Function",
        "spectra": "Spectrum task",
    }.get(source, "Series")
    only_label = next(iter(grouped)) if len(grouped) == 1 else None
    show_legend = len(grouped) > 1 or bool(
        only_label and (only_label.lower().startswith("block ") or source == "profiling")
    )
    return {
        "schema_version": 1,
        "plot_type": "iteration_history" if is_iteration_history else "time_history",
        "series": series,
        "title": title,
        "subtitle": " · ".join(subtitle_bits) or None,
        "x_label": x_label,
        "x_kind": x_kind,
        "y_label": field_label,
        "y_scale": "log" if use_log else "linear",
        "include_zero_y": not use_log and all(value >= 0.0 for value in all_values),
        "show_markers": not is_iteration_history,
        "show_legend": show_legend,
        "legend_title": legend_title,
        "window": {"mode": "last" if last_n is not None else "full", "last": last_n},
        "lines": [{"label": label, "points": points} for label, points in sorted(grouped.items())],
        "output_path": os.path.abspath(output_path) if output_path else None,
        "fallback_output_path": fallback,
    }
 
 
def _render_summary_plot_catalog(catalog: list, output_format: str):
    """!
    @brief Render available summarize plot-series metadata.
    @param[in] catalog Available series catalog.
    @param[in] output_format Text or JSON output format.
    """
    if output_format == "json":
        print(json.dumps({"available_series": catalog}, indent=2, sort_keys=True))
        return
    print("\nAVAILABLE PLOT SERIES")
    print("=" * 78)
    for item in catalog:
        labels = ", ".join(line["label"] for line in item["lines"])
        print(f"  {item['series']:<42} samples={item['sample_count']:<5} lines={labels}")
        print(f"    source: {', '.join(os.path.relpath(path) for path in item['source_paths'])}")
 
 
def _invoke_plot_gen(request: dict):
    """!
    @brief Invoke standalone plot.gen with one normalized request over stdin.
    @param[in] request Versioned normalized plot request.
    """
    plotgen_path = os.path.join(GENERATORS_PATH, "plot.gen")
    if not os.path.isfile(plotgen_path):
        raise ValueError(f"plot.gen script not found: {plotgen_path}")
    result = subprocess.run(
        [sys.executable, plotgen_path, "--input", "-"],
        input=json.dumps(request),
        text=True,
        capture_output=True,
        check=False,
    )
    if result.stdout:
        print(result.stdout.rstrip())
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "unknown plotting error").strip()
        if result.returncode == 3:
            raise PlotDependencyError(details)
        raise ValueError(f"plot.gen failed with exit code {result.returncode}: {details}")
 
 
def summarize_workflow(args):
    """!
    @brief Build and render a read-only health summary for a run step.
    @param[in] args Command-line style argument list supplied to the function.
    """
    if args.step is not None and args.step < 0:
        fail_cli_usage("--step must be a non-negative integer.")
    if args.snapshot_rows < 1:
        fail_cli_usage("--snapshot-rows must be at least 1.")
    plot_series = getattr(args, "plot_series", None)
    list_plot_series = bool(getattr(args, "list_plot_series", False))
    plot_spectrum = getattr(args, "plot_spectrum", None)
    last_n = getattr(args, "last_n", None)
    plot_output = getattr(args, "plot_output", None)
    linear_y = bool(getattr(args, "linear_y", False))
    plot_mode = bool(plot_series or list_plot_series or plot_spectrum is not None)
    existing_selectors = any(
        [
            getattr(args, "overview", False),
            getattr(args, "case", False),
            getattr(args, "solver", False),
            getattr(args, "monitor", False),
            args.step is not None,
            getattr(args, "latest", False),
            getattr(args, "max_step", False),
        ]
    )
    if plot_mode and existing_selectors:
        fail_cli_usage("Plot discovery and --plot cannot be combined with config or selected-step selectors.")
    if not plot_series and last_n is not None:
        fail_cli_usage("--last requires --plot.")
    if not plot_series and plot_spectrum is None and (plot_output or linear_y):
        fail_cli_usage("--plot-output and --linear-y require --plot or --plot-spectrum.")
    if last_n is not None and last_n < 1:
        fail_cli_usage("--last must be a positive integer.")
    if plot_series and args.output_format == "json":
        fail_cli_usage("--plot does not support --format json; use --list-plot-series --format json for structured discovery.")
    if plot_mode:
        context = _build_summary_context(args.run_dir)
        try:
            records = _collect_summary_plot_records(context)
            catalog = _build_summary_plot_catalog(records)
            if list_plot_series:
                if not catalog:
                    raise ValueError("No plottable scalar histories were found in the run logs.")
                _render_summary_plot_catalog(catalog, args.output_format)
                return
            if plot_spectrum is not None:
                request = _build_spectrum_plot_request(
                    context, plot_spectrum, True, linear_y, plot_output
                )
            else:
                request = _build_summary_plot_request(
                    context, records, plot_series, last_n, linear_y, plot_output
                )
            _invoke_plot_gen(request)
            return
        except PlotDependencyError as exc:
            emit_structured_error(
                ERROR_CODE_DEPENDENCY_MISSING,
                key="plotting",
                file_path=sys.executable,
                message=str(exc),
            )
            sys.exit(1)
        except ValueError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="plot",
                file_path=context["log_dir"],
                message=str(exc),
            )
            sys.exit(1)
 
    selected_configs = {
        name
        for name in ("case", "solver", "monitor")
        if bool(getattr(args, name, False))
    }
    if getattr(args, "overview", False):
        selected_configs.update({"case", "solver", "monitor"})
    explicit_health = args.step is not None or bool(getattr(args, "latest", False)) or bool(getattr(args, "max_step", False))
    health_requested = explicit_health or (not selected_configs and not getattr(args, "overview", False))
 
    context = None
    combined = {"storage": storage_state_summary(args.run_dir)}
    if selected_configs or getattr(args, "overview", False):
        context = _build_summary_context(args.run_dir)
        if getattr(args, "overview", False):
            combined["run_overview"] = _build_run_overview(context)
        combined["configuration"] = {}
        builders = {
            "case": _build_case_overview,
            "solver": _build_solver_overview,
            "monitor": _build_monitor_overview,
        }
        for name in ("case", "solver", "monitor"):
            if name in selected_configs:
                try:
                    combined["configuration"][name] = builders[name](context)
                except (KeyError, TypeError, ValueError, ZeroDivisionError) as exc:
                    emit_structured_error(
                        ERROR_CODE_CFG_INVALID_VALUE,
                        key=name,
                        file_path=context["config_paths"][name],
                        message=f"Could not summarize copied {name}.yml: {exc}",
                    )
                    sys.exit(1)
 
    if not health_requested:
        combined["_health_requested"] = False
        render_selected_summary(combined, output_format=args.output_format)
        return
 
    requested_step = args.step
    if requested_step is None and getattr(args, "latest", False):
        requested_step = None
    selection_mode = "max_step" if getattr(args, "max_step", False) else "latest"
    health_payload = build_run_summary_payload(
        args.run_dir,
        step=requested_step,
        snapshot_rows=args.snapshot_rows,
        selection_mode=selection_mode,
    )
    if set(combined) == {"storage"}:
        combined = {**health_payload, **combined, "_health_requested": True}
        render_selected_summary(combined, output_format=args.output_format)
        return
    combined = {**health_payload, **combined, "_health_requested": True}
    render_selected_summary(combined, output_format=args.output_format)
 
 
def _resolve_submission_target(run_dir: str = None, study_dir: str = None) -> dict:
    """!
    @brief Resolve a run/study submission target from explicit directory flags.
    @param[in] run_dir Argument passed to `_resolve_submission_target()`.
    @param[in] study_dir Argument passed to `_resolve_submission_target()`.
    @return Value returned by `_resolve_submission_target()`.
    """
    has_run_dir = bool(run_dir)
    has_study_dir = bool(study_dir)
    if has_run_dir == has_study_dir:
        fail_cli_usage("submit requires exactly one of --run-dir or --study-dir.")
 
    target_kind = "run" if has_run_dir else "study"
    target_key = "run_dir" if target_kind == "run" else "study_dir"
    root_dir = os.path.abspath(run_dir if has_run_dir else study_dir)
    if not os.path.isdir(root_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=target_key,
            file_path=root_dir,
            message=f"{'Run' if target_kind == 'run' else 'Study'} directory not found.",
        )
        sys.exit(1)
 
    scheduler_dir = os.path.join(root_dir, "scheduler")
    submission_path = os.path.join(scheduler_dir, "submission.json")
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Target directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-staged run/study directory with scheduler/submission.json, or submit the script manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode == "local" and target_kind != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message="Local staged submission is supported for run directories only.",
            hint="Use --run-dir for local staged execution; study submit remains Slurm-only.",
        )
        sys.exit(1)
    if launch_mode not in {"slurm", "local"}:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Target launch_mode={launch_mode or 'unknown'} is not supported.",
            hint="Use a staged run/study directory with launch_mode 'slurm' or a run directory with launch_mode 'local'.",
        )
        sys.exit(1)
 
    if target_kind == "run":
        script_map = {
            "solve": os.path.join(scheduler_dir, "solver.sbatch"),
            "post-process": os.path.join(scheduler_dir, "post.sbatch"),
        }
        display_label = "Run directory"
        manifest_path = None
    else:
        script_map = {
            "solve": os.path.join(scheduler_dir, "solver_array.sbatch"),
            "post-process": os.path.join(scheduler_dir, "post_array.sbatch"),
        }
        display_label = "Study directory"
        manifest_path = os.path.join(root_dir, "study_manifest.json")
 
    return {
        "target_kind": target_kind,
        "target_key": target_key,
        "root_dir": root_dir,
        "scheduler_dir": scheduler_dir,
        "submission_path": submission_path,
        "submission_meta": submission_meta,
        "launch_mode": launch_mode,
        "script_map": script_map,
        "display_label": display_label,
        "manifest_path": manifest_path,
    }
 
 
def _get_submission_stage_metadata(target_context: dict, stage_name: str) -> dict:
    """!
    @brief Return stored metadata for one staged submission target.
    @param[in] target_context Argument passed to `_get_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_get_submission_stage_metadata()`.
    @return Value returned by `_get_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if not isinstance(stages, dict):
            return {}
        stage_meta = stages.get(stage_name)
        return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
    key = "solver_array" if stage_name == "solve" else "post_array"
    stage_meta = submission_meta.get(key)
    return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
 
def _get_recorded_submission_stages(target_context: dict) -> list:
    """!
    @brief Return stage names explicitly recorded in scheduler submission metadata.
    @param[in] target_context Argument passed to `_get_recorded_submission_stages()`.
    @return Value returned by `_get_recorded_submission_stages()`.
    """
    submission_meta = target_context["submission_meta"]
    recorded = []
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if isinstance(stages, dict):
            for stage_name in ["solve", "post-process"]:
                if isinstance(stages.get(stage_name), dict):
                    recorded.append(stage_name)
        return recorded
 
    if isinstance(submission_meta.get("solver_array"), dict):
        recorded.append("solve")
    if isinstance(submission_meta.get("post_array"), dict):
        recorded.append("post-process")
    return recorded
 
 
def _format_stage_list(stage_names: list) -> str:
    """!
    @brief Format a human-readable stage list for submit diagnostics.
    @param[in] stage_names Argument passed to `_format_stage_list()`.
    @return Value returned by `_format_stage_list()`.
    """
    return ", ".join(stage_names) if stage_names else "none"
 
 
def _build_submit_missing_stage_hint(target_context: dict, requested_stage: str, selected_stages: list) -> str:
    """!
    @brief Build an actionable hint for requested submit stages missing from metadata.
    @param[in] target_context Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] requested_stage Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] selected_stages Argument passed to `_build_submit_missing_stage_hint()`.
    @return Value returned by `_build_submit_missing_stage_hint()`.
    """
    recorded_stages = _get_recorded_submission_stages(target_context)
    recorded_set = set(recorded_stages)
    selected_set = set(selected_stages)
    target_flag = "--run-dir" if target_context["target_kind"] == "run" else "--study-dir"
    target_path = os.path.relpath(target_context["root_dir"])
    submit_prefix = f"picurv submit {target_flag} {target_path}"
    solve_stage_command = (
        "picurv run --solve ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    post_stage_command = (
        "picurv run --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    solve_post_command = (
        "picurv run --solve --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
 
    if requested_stage == "all":
        if recorded_set == {"solve"}:
            return (
                "--stage all requests solve and post-process, but this target records only solve. "
                f"Use `{submit_prefix} --stage solve`, or re-stage with post-processing enabled "
                f"(`{solve_post_command}`)."
            )
        if recorded_set == {"post-process"}:
            return (
                "--stage all requests solve and post-process, but this target records only post-process. "
                f"Use `{submit_prefix} --stage post-process`, or re-stage including the solve stage "
                f"(`{solve_stage_command}`)."
            )
        missing = [stage for stage in selected_stages if stage not in recorded_set]
        if missing:
            return (
                "--stage all requests solve and post-process, but submission metadata records "
                f"{_format_stage_list(recorded_stages)}. Re-stage the missing stage(s): "
                f"{_format_stage_list(missing)}."
            )
 
    if selected_set == {"solve"} and "solve" not in recorded_set:
        return (
            "The solve stage was requested, but submission metadata does not record a staged solve command/script. "
            f"Re-stage with `{solve_stage_command}`."
        )
    if selected_set == {"post-process"} and "post-process" not in recorded_set:
        return (
            "The post-process stage was requested, but submission metadata does not record a staged post-process command/script. "
            f"Re-stage with post-processing enabled (`{post_stage_command}`, or `{solve_post_command}`)."
        )
 
    return "Re-stage the requested stage(s) with picurv run/sweep --no-submit before calling picurv submit."
 
 
def _set_submission_stage_metadata(target_context: dict, stage_name: str, stage_meta: dict):
    """!
    @brief Persist one stage's metadata back into the submission payload.
    @param[in] target_context Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_meta Argument passed to `_set_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages")
        if not isinstance(stages, dict):
            stages = {}
            submission_meta["stages"] = stages
        stages[stage_name] = stage_meta
        return
 
    key = "solver_array" if stage_name == "solve" else "post_array"
    submission_meta[key] = stage_meta
 
 
def _write_submission_target_metadata(target_context: dict):
    """!
    @brief Write updated submission metadata back to disk.
    @param[in] target_context Argument passed to `_write_submission_target_metadata()`.
    """
    write_json_file(target_context["submission_path"], target_context["submission_meta"])
 
    manifest_path = target_context.get("manifest_path")
    if manifest_path and os.path.isfile(manifest_path):
        manifest_payload = _read_json_if_exists(manifest_path)
        if isinstance(manifest_payload, dict):
            manifest_payload["submission"] = target_context["submission_meta"]
            write_json_file(manifest_path, manifest_payload)
 
 
def staged_control_directories(control_path: str) -> tuple:
    """!
    @brief Read run-owned directory values from a staged control file.
 
    @details Tokenizes with `shlex` because PETSc's options-file parser treats a
             double-quoted span as a single token. Splitting on whitespace would read
             `-log_dir "/tmp/VICTIM DIR"` as the value `"/tmp/VICTIM`, which looks
             relative and contained while PETSc would use the absolute path.
 
             Malformed quoting is reported rather than skipped: a line the parser
             cannot interpret is exactly the case where preflight must not assume the
             run is safe.
    @param[in] control_path Path to a generated `.control` file.
    @return Tuple of (values, parse_errors).
    """
    flag_to_key = {
        "-log_dir": "log",
        "-output_dir": "output",
        "-restart_dir": "restart",
        "-analysis_dir": "analysis",
    }
    values: dict = {}
    parse_errors: list = []
    try:
        lines = read_text_file_lines(control_path)
    except OSError as exc:
        return values, [f"could not be read ({exc})"]
    for number, line in enumerate(lines, start=1):
        if not line.strip():
            continue
        try:
            tokens = shlex.split(line, comments=True)
        except ValueError as exc:
            parse_errors.append(
                f"line {number} has malformed quoting and cannot be interpreted ({exc}); "
                f"refusing to assume it is safe"
            )
            continue
        if tokens and tokens[0] in RESERVED_INDIRECTION_FLAGS:
            parse_errors.append(
                f"line {number} uses '{tokens[0]}', which PETSc expands itself; its contents "
                f"cannot be checked here and could set a run directory. Re-stage without it"
            )
            continue
        if len(tokens) >= 2 and tokens[0] in flag_to_key:
            values[flag_to_key[tokens[0]]] = tokens[1]
    return values, parse_errors
 
 
def preflight_config_directories(root_dir: str) -> list:
    """!
    @brief Every config directory under a run or study root that may hold a control file.
 
    @details A study keeps its controls under `cases/<member>/config`, not at the study
             root, so a preflight that only looked at `<root>/config` was empty for every
             study. This walks the tree so members and nested runs are covered.
    @param[in] root_dir Run or study directory.
    @return Sorted config directory paths.
    """
    found: set = set()
    root = os.path.abspath(root_dir)
    direct = os.path.join(root, "config")
    if os.path.isdir(direct):
        found.add(direct)
    for current, dirnames, _ in os.walk(root):
        dirnames[:] = [d for d in dirnames if not os.path.islink(os.path.join(current, d))]
        if os.path.basename(current) == "config" and glob.glob(os.path.join(current, "*.control")):
            found.add(current)
    return sorted(found)
 
 
def preflight_staged_run_directories(root_dir: str) -> tuple:
    """!
    @brief Re-check run-directory safety against an already-staged run or study.
 
    @details Staging validates the configuration it is given, but a staged run can be
             edited, or produced by an older version, before submission. This re-reads the
             effective staged control files - across study members and nested runs - and
             applies the same rules as configuration validation, plus a physical
             containment check that a symlink cannot slip past.
    @param[in] root_dir Run or study directory being submitted.
    @return Tuple of (errors, warnings).
    """
    errors: list = []
    warnings: list = []
    config_dirs = preflight_config_directories(root_dir)
    if not config_dirs:
        return errors, warnings
    canonical = {
        "log": CANONICAL_RUN_PATHS["logs"],
        "output": CANONICAL_RUN_PATHS["output"],
        "restart": CANONICAL_RUN_PATHS["restart"],
        "analysis": CANONICAL_RUN_PATHS["metrics"],
    }
    for config_dir in config_dirs:
        run_root = os.path.dirname(config_dir)
        for control in sorted(glob.glob(os.path.join(config_dir, "*.control"))):
            staged, parse_errors = staged_control_directories(control)
            label = os.path.relpath(control)
            errors.extend(f"  {label}: {message}" for message in parse_errors)
            if not staged:
                continue
            for key, expected in canonical.items():
                actual = staged.get(key)
                if actual is not None and normalized_run_directory(actual) != expected:
                    errors.append(
                        f"  {label}: -{key}_dir is {actual!r}; the canonical value is "
                        f"{expected!r}. Re-stage the run instead of editing its path flags."
                    )
            effective = effective_run_directories(staged)
            control_errors, control_warnings = evaluate_run_directories(
                effective, False, explicit=set(staged)
            )
            errors.extend(f"  {label}: {message}" for message in control_errors)
            warnings.extend(f"  {label}: {message}" for message in control_warnings)
            for _, verdict, message in classify_physical_containment(run_root, effective):
                errors.append(f"  {label}: {message}")
    return errors, warnings
 
 
def read_text_file_lines(path: str) -> list:
    """!
    @brief Read a text file into a list of lines.
    @param[in] path File to read.
    @return List of lines.
    """
    with open(path, "r", encoding="utf-8", errors="replace") as handle:
        return handle.readlines()
 
 
def submit_staged_jobs(args):
    """!
    @brief Submit previously staged Slurm artifacts from an existing run/study directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    target_context = _resolve_submission_target(
        run_dir=getattr(args, "run_dir", None),
        study_dir=getattr(args, "study_dir", None),
    )
    try:
        require_storage_payload_local(target_context["root_dir"], "submission")
    except StorageError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
    preflight_errors, preflight_warnings = preflight_staged_run_directories(
        target_context["root_dir"]
    )
    for warning in preflight_warnings:
        print(f"[WARN] {warning.strip()}", file=sys.stderr)
    if preflight_errors:
        print(
            "[FATAL] Submission preflight failed: the staged run has an unsafe run-directory "
            "configuration.",
            file=sys.stderr,
        )
        for violation in preflight_errors:
            print(violation, file=sys.stderr)
        print(
            "  Re-stage the run so PICurv regenerates its canonical path flags.",
            file=sys.stderr,
        )
        sys.exit(1)
    if target_context["target_kind"] == "study":
        cold_cases = cold_study_members(target_context["root_dir"])
        if cold_cases:
            print(
                "[FATAL] Submission requires cold-storage study member(s): " + ", ".join(cold_cases),
                file=sys.stderr,
            )
            sys.exit(1)
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    selected_stages = stage_order if requested_stage == "all" else [requested_stage]
 
    print(f"[INFO] {target_context['display_label']:<20}: {os.path.relpath(target_context['root_dir'])}")
    print(f"[INFO] Submission metadata  : {os.path.relpath(target_context['submission_path'])}")
    print(f"[INFO] Requested stages    : {', '.join(selected_stages)}")
 
    if target_context.get("launch_mode") == "local":
        submit_staged_local_run(args, target_context, selected_stages)
        return
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    solve_existing_job_id = str(solve_existing_meta.get("job_id", "")).strip()
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        script_path = target_context["script_map"][stage_name]
        missing_stage_hint = _build_submit_missing_stage_hint(target_context, requested_stage, selected_stages)
        if not existing_meta:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.metadata",
                file_path=target_context["submission_path"],
                message=f"Submission metadata does not record stage '{stage_name}'.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if not os.path.isfile(script_path):
            emit_structured_error(
                ERROR_CODE_CFG_FILE_NOT_FOUND,
                key=f"scheduler.{stage_name}.script",
                file_path=script_path,
                message=f"Required {stage_name} sbatch artifact is missing.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to resubmit this stage intentionally.",
            )
            sys.exit(1)
 
        dependency = None
        if stage_name == "post-process":
            if "solve" in selected_stages:
                dependency = "__NEW_SOLVE_JOB_ID__"
            else:
                if not (solve_existing_meta.get("submitted") and solve_existing_job_id):
                    emit_structured_error(
                        ERROR_CODE_CFG_INCONSISTENT_COMBO,
                        key="scheduler.post-process.dependency",
                        file_path=target_context["submission_path"],
                        message="Post-process submission requires a recorded solve job id when solve is not being submitted in the same command.",
                        hint="Submit --stage solve or --stage all first, or use --force only after solve metadata exists.",
                    )
                    sys.exit(1)
                dependency = solve_existing_job_id
 
        stage_plans.append(
            {
                "stage": stage_name,
                "script": script_path,
                "dependency": dependency,
                "existing_meta": existing_meta,
            }
        )
 
    if args.dry_run:
        for plan in stage_plans:
            cmd = ["sbatch"]
            dependency = plan["dependency"]
            if dependency == "__NEW_SOLVE_JOB_ID__":
                cmd.append("--dependency=afterok:<new solve job id>")
            elif dependency:
                cmd.append(f"--dependency=afterok:{dependency}")
            cmd.append(plan["script"])
            print(f"[DRY-RUN] Would run: {' '.join(cmd)}")
        print("[INFO] Dry-run only. No jobs were submitted.")
        return
 
    latest_solve_job_id = None
    for plan in stage_plans:
        dependency = plan["dependency"]
        if dependency == "__NEW_SOLVE_JOB_ID__":
            dependency = latest_solve_job_id
 
        submit_info = submit_sbatch(plan["script"], dependency=dependency)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta.update(submit_info)
        stage_meta["script"] = plan["script"]
        stage_meta["submitted"] = True
        if dependency:
            stage_meta["dependency"] = f"afterok:{dependency}"
        else:
            stage_meta.pop("dependency", None)
 
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Submitted {plan['stage']} job: {submit_info['job_id']}")
 
        if plan["stage"] == "solve":
            latest_solve_job_id = submit_info["job_id"]
 
    _write_submission_target_metadata(target_context)
 
 
def submit_staged_local_run(args, target_context: dict, selected_stages: list):
    """!
    @brief Execute previously staged local run commands from scheduler/submission.json.
    @param[in] args Command-line style argument list supplied to the function.
    @param[in] target_context Resolved submission target context.
    @param[in] selected_stages Ordered stage names selected by the user.
    """
    if target_context["target_kind"] != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=target_context["submission_path"],
            message="Local staged execution is supported for run directories only.",
            hint="Use --run-dir for local staged execution.",
        )
        sys.exit(1)
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    solve_already_done = bool(solve_existing_meta.get("submitted") or solve_existing_meta.get("executed"))
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        command = existing_meta.get("command")
        if not isinstance(command, list) or not command:
            if existing_meta:
                hint = "Re-stage the run with picurv run --no-submit before calling picurv submit."
            else:
                hint = _build_submit_missing_stage_hint(target_context, args.stage, selected_stages)
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.command",
                file_path=target_context["submission_path"],
                message=f"Required local command metadata for stage '{stage_name}' is missing.",
                hint=hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to execute this stage again intentionally.",
            )
            sys.exit(1)
 
        if stage_name == "post-process" and "solve" not in selected_stages and not args.force and not solve_already_done:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.post-process.dependency",
                file_path=target_context["submission_path"],
                message="Post-process local execution requires a recorded completed solve stage when solve is not being executed in the same command.",
                hint="Submit --stage solve or --stage all first, or use --force after confirming source data exists.",
            )
            sys.exit(1)
 
        log_file = existing_meta.get("log_file")
        if not isinstance(log_file, str) or not log_file.strip():
            log_file = os.path.join("scheduler", f"{os.path.basename(target_context['root_dir'])}_{stage_name}.log")
 
        stage_plans.append(
            {
                "stage": stage_name,
                "command": [str(token) for token in command],
                "log_file": log_file,
                "existing_meta": existing_meta,
            }
        )
 
    if args.dry_run:
        for plan in stage_plans:
            print(f"[DRY-RUN] Would run: {format_command_for_display(plan['command'])}")
            print(f"[DRY-RUN] Log file : {plan['log_file']}")
        print("[INFO] Dry-run only. No local commands were executed.")
        return
 
    monitor_cfg = None
    monitor_path = os.path.join(target_context["root_dir"], "config", "monitor.yml")
    if os.path.isfile(monitor_path):
        monitor_cfg = read_yaml_file(monitor_path)
 
    for plan in stage_plans:
        if plan["stage"] == "solve":
            try:
                with runtime_stage_lock(target_context["root_dir"], "solver"):
                    execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
            except StorageError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
        else:
            execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta["command"] = plan["command"]
        stage_meta["command_string"] = format_command_for_display(plan["command"])
        stage_meta["log_file"] = plan["log_file"]
        stage_meta["submitted"] = True
        stage_meta["executed"] = True
        stage_meta["completed_at"] = datetime.now().isoformat()
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Executed local {plan['stage']} stage.")
 
    _write_submission_target_metadata(target_context)
 
 
def cancel_run_jobs(args):
    """!
    @brief Cancel Slurm-submitted jobs for an existing run directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    run_dir = os.path.abspath(args.run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    submission_path = os.path.join(run_dir, "scheduler", "submission.json")
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Run directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-submitted run directory with scheduler/submission.json, or cancel the job manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode != "slurm":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Run directory launch_mode={launch_mode or 'unknown'} is not Slurm.",
            hint="picurv cancel currently supports Slurm-submitted runs only.",
        )
        sys.exit(1)
 
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    selected_stages = stage_order if requested_stage == "all" else [requested_stage]
    recorded_stages = submission_meta.get("stages", {})
    if not isinstance(recorded_stages, dict):
        recorded_stages = {}
 
    job_to_stages = {}
    skipped = []
    for stage_name in selected_stages:
        stage_meta = recorded_stages.get(stage_name)
        if not isinstance(stage_meta, dict):
            skipped.append((stage_name, "no stage metadata recorded"))
            continue
 
        job_id = str(stage_meta.get("job_id", "")).strip()
        if not stage_meta.get("submitted"):
            skipped.append((stage_name, "job was generated but not submitted"))
            continue
        if not job_id:
            skipped.append((stage_name, "submitted stage is missing a recorded job id"))
            continue
 
        job_to_stages.setdefault(job_id, []).append(stage_name)
 
    if not job_to_stages:
        print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
        print(f"[INFO] Submission metadata: {os.path.relpath(submission_path)}")
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
        print("[FATAL] No submitted Slurm job IDs were found for the requested stage selection.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
    print(f"[INFO] Submission metadata: {os.path.relpath(submission_path)}")
    print(f"[INFO] Requested stages   : {', '.join(selected_stages)}")
 
    if skipped:
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
 
    graceful = bool(getattr(args, "graceful", False))
    failures = []
    for job_id, stage_names in job_to_stages.items():
        joined_stage_names = ", ".join(stage_names)
        use_graceful_signal = graceful and "solve" in stage_names
        scancel_cmd = ["scancel"]
        if use_graceful_signal:
            # A directly launched ``mpirun`` replaces the batch shell (via ``exec``)
            # and is therefore not necessarily a Slurm job step.  ``--full`` also
            # signals the batch process and its children, so the MPI launcher can
            # forward SIGUSR1 to the solver ranks.
            scancel_cmd.extend(["--signal=USR1", "--full"])
        scancel_cmd.append(job_id)
 
        if args.dry_run:
            print(f"[DRY-RUN] Would run: {' '.join(scancel_cmd)}  # stage(s): {joined_stage_names}")
            continue
 
        result = subprocess.run(scancel_cmd, text=True, capture_output=True, check=False)
        stderr_text = (result.stderr or "").strip()
        stdout_text = (result.stdout or "").strip()
        if result.returncode == 0:
            if use_graceful_signal:
                print(
                    f"[SUCCESS] Requested graceful shutdown for Slurm job {job_id} for stage(s): {joined_stage_names}. "
                    "Solver jobs trap SIGUSR1 and write the latest safe off-cadence step at the next checkpoint."
                )
            else:
                print(f"[SUCCESS] Canceled Slurm job {job_id} for stage(s): {joined_stage_names}")
            continue
 
        detail = stderr_text or stdout_text or "unknown scancel failure"
        failures.append((job_id, joined_stage_names, detail, result.returncode))
        print(
            f"[ERROR] Failed to cancel Slurm job {job_id} for stage(s) {joined_stage_names}: {detail}",
            file=sys.stderr,
        )
 
    if args.dry_run:
        print("[INFO] Dry-run only. No jobs were canceled.")
        return
 
    if failures:
        sys.exit(1)
 
 
def _workspace_yaml_role(path: str):
    """!
    @brief Infer the owned workspace role of one copied YAML file.
    @param[in] path YAML file copied from an example template.
    @return One of case, solver, monitor, post, cluster, study, or None.
    """
    try:
        payload = read_yaml_file(path)
    except (OSError, ValueError):
        return None
    keys = set(payload)
    if {"grid", "properties", "run_control"} <= keys:
        return "case"
    if "base_configs" in keys and ("study_type" in keys or "parameters" in keys or "parameter_sets" in keys):
        return "study"
    if "scheduler" in keys and "resources" in keys:
        return "cluster"
    if "source_data" in keys or "eulerian_pipeline" in keys or "lagrangian_pipeline" in keys:
        return "post"
    if "io" in keys and ("logging" in keys or "profiling" in keys or "diagnostics" in keys):
        return "monitor"
    if "momentum_solver" in keys or "poisson_solver" in keys or "operation_mode" in keys:
        return "solver"
    return None
 
 
def _rewrite_workspace_path_values(value, replacements: dict):
    """!
    @brief Rewrite copied template path scalars to workspace-root-relative homes.
    @param[in] value YAML subtree to rewrite.
    @param[in] replacements Old relative/basename paths mapped to new workspace paths.
    @return Rewritten YAML subtree.
    """
    if isinstance(value, dict):
        return {key: _rewrite_workspace_path_values(item, replacements) for key, item in value.items()}
    if isinstance(value, list):
        return [_rewrite_workspace_path_values(item, replacements) for item in value]
    if not isinstance(value, str):
        return value
    normalized = value.replace("\\", "/").lstrip("./")
    return replacements.get(normalized, replacements.get(os.path.basename(normalized), value))
 
 
def _choose_primary_workspace_role(candidates: list, role: str, template_name: str):
    """!
    @brief Select the canonical role file from a template that may carry variants.
    @param[in] candidates Candidate absolute YAML paths.
    @param[in] role Config role being selected.
    @param[in] template_name Source example directory name.
    @return Selected absolute path or None.
    """
    if not candidates:
        return None
    preferred = {
        "case": ("case.yml", f"{template_name}.yml", "master_case.yml"),
        "solver": ("solver.yml", "Imp-MG-Standard.yml", "master_solver.yml"),
        "monitor": ("monitor.yml", "Standard_Output.yml", "master_monitor.yml"),
        "post": ("post.yml", "standard_analysis.yml", "master_postprocessor.yml"),
        "cluster": ("cluster.yml", "slurm_cluster.yml", "master_cluster.yml"),
    }.get(role, ())
    by_name = {os.path.basename(path): path for path in candidates}
    for name in preferred:
        if name in by_name:
            return by_name[name]
    return sorted(candidates)[0]
 
 
def organize_initialized_workspace(workspace_root: str, template_name: str,
                                   source_template_root: str = None) -> dict:
    """!
    @brief Convert a copied example into the canonical editable workspace layout.
    @param[in] workspace_root Newly copied workspace root.
    @param[in] template_name Example template identity.
    @param[in] source_template_root Optional original template root used to vendor references.
    @return Mapping of canonical config roles and relocated imported inputs.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    yaml_files = [
        str(path) for path in Path(workspace_root).rglob("*.yml")
        if path.name not in {RUNTIME_EXECUTION_EXAMPLE_FILENAME, RUNTIME_EXECUTION_CONFIG_FILENAME}
        and "runs" not in path.parts and "studies" not in path.parts
    ]
    yaml_files.extend(
        str(path) for path in Path(workspace_root).rglob("*.yaml")
        if path.name not in {RUNTIME_EXECUTION_EXAMPLE_FILENAME, RUNTIME_EXECUTION_CONFIG_FILENAME}
        and "runs" not in path.parts and "studies" not in path.parts
    )
    vendored_replacements = {}
    if source_template_root:
        source_template_root = os.path.abspath(source_template_root)
 
        def vendor_references(value, source_yaml: str, dotted: str = ""):
            """!
            @brief Vendor referenced generator inputs into canonical workspace homes.
            @param[in] value YAML subtree to inspect.
            @param[in] source_yaml Original template YAML path.
            @param[in] dotted Current dotted key path.
            @return None.
            """
            if isinstance(value, dict):
                for key, child in value.items():
                    vendor_references(child, source_yaml, f"{dotted}.{key}" if dotted else str(key))
                return
            if isinstance(value, list):
                for index, child in enumerate(value):
                    vendor_references(child, source_yaml, f"{dotted}[{index}]")
                return
            key = dotted.rsplit(".", 1)[-1]
            if key not in _VENDORABLE_CONFIG_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
                return
            origin = os.path.abspath(os.path.join(os.path.dirname(source_yaml), value))
            if not os.path.isfile(origin):
                return
            if key == "script":
                home = "config/generators"
            elif "grid" in dotted:
                home = "config/grids"
            elif "initial_condition" in dotted:
                home = "config/initial_conditions"
            elif "inlet" in dotted or "boundary_conditions" in dotted:
                home = "config/inlet_profiles"
            else:
                home = "config"
            destination = os.path.join(workspace_root, *home.split("/"), os.path.basename(origin))
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            if not os.path.exists(destination):
                shutil.copy2(origin, destination)
            relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
            vendored_replacements[value.replace("\\", "/").lstrip("./")] = relative
            vendored_replacements[os.path.basename(value)] = relative
 
        for copied_yaml in sorted(set(yaml_files)):
            relative = os.path.relpath(copied_yaml, workspace_root)
            source_yaml = os.path.join(source_template_root, relative)
            if not os.path.isfile(source_yaml):
                continue
            try:
                vendor_references(read_yaml_file(copied_yaml), source_yaml)
            except (OSError, ValueError):
                continue
    roles = {}
    for path in sorted(set(yaml_files)):
        role = _workspace_yaml_role(path)
        if role:
            roles.setdefault(role, []).append(path)
 
    selected = {
        role: _choose_primary_workspace_role(paths, role, template_name)
        for role, paths in roles.items() if role != "study"
    }
    destinations = {}
    occupied = set()
    for role, paths in roles.items():
        for source in paths:
            if role == "study":
                relative = os.path.join("config", "studies", os.path.basename(source))
            elif source == selected.get(role):
                relative = os.path.join("config", f"{role}.yml")
            else:
                relative = os.path.join("config", os.path.basename(source))
            destination = os.path.join(workspace_root, relative)
            if os.path.abspath(source) == os.path.abspath(destination):
                destinations[source] = relative.replace(os.sep, "/")
                occupied.add(os.path.abspath(destination))
                continue
            if os.path.abspath(destination) in occupied or os.path.exists(destination):
                original_relative = os.path.relpath(source, workspace_root)
                relative = os.path.join("config", "variants", original_relative)
                destination = os.path.join(workspace_root, relative)
                counter = 2
                while os.path.abspath(destination) in occupied or os.path.exists(destination):
                    stem, suffix = os.path.splitext(relative)
                    destination = os.path.join(workspace_root, f"{stem}-{counter}{suffix}")
                    counter += 1
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            shutil.move(source, destination)
            destinations[source] = relative.replace(os.sep, "/")
            occupied.add(os.path.abspath(destination))
 
    input_extensions = {
        ".picgrid": "inputs/grids",
        ".vts": "inputs/grids",
        ".picslice": "inputs/inlet_profiles",
        ".dat": "inputs/initial_conditions",
    }
    input_moves = {}
    for path in sorted(Path(workspace_root).rglob("*")):
        if not path.is_file() or path.suffix.lower() not in input_extensions:
            continue
        if any(part in _WORKSPACE_MANAGED_PATHS for part in path.relative_to(workspace_root).parts):
            continue
        destination_dir = os.path.join(workspace_root, *input_extensions[path.suffix.lower()].split("/"))
        destination = os.path.join(destination_dir, path.name)
        if os.path.exists(destination):
            continue
        old_relative = path.relative_to(workspace_root).as_posix()
        shutil.move(str(path), destination)
        new_relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
        input_moves[old_relative] = new_relative
        input_moves[path.name] = new_relative
 
    config_replacements = {}
    basename_counts = {}
    for source in destinations:
        basename = os.path.basename(source)
        basename_counts[basename] = basename_counts.get(basename, 0) + 1
    for source, relative in destinations.items():
        old_relative = os.path.relpath(source, workspace_root).replace(os.sep, "/")
        config_replacements[old_relative] = relative
        if basename_counts[os.path.basename(source)] == 1:
            config_replacements[os.path.basename(source)] = relative
    replacements = {**config_replacements, **input_moves, **vendored_replacements}
    for path in sorted(Path(workspace_root, "config").rglob("*.yml")):
        payload = read_yaml_file(str(path))
        local_replacements = dict(replacements)
        original_source = next(
            (
                source for source, relative in destinations.items()
                if os.path.abspath(os.path.join(workspace_root, relative)) == os.path.abspath(path)
            ),
            None,
        )
        if original_source:
            original_parent = os.path.dirname(original_source)
            for candidate_source, candidate_relative in destinations.items():
                relative_reference = os.path.relpath(candidate_source, original_parent).replace(os.sep, "/")
                local_replacements[relative_reference] = candidate_relative
                if os.path.dirname(candidate_source) == original_parent:
                    local_replacements[os.path.basename(candidate_source)] = candidate_relative
        rewritten = _rewrite_workspace_path_values(payload, local_replacements)
        role = _workspace_yaml_role(str(path))
        if role == "monitor" and isinstance(rewritten.get("io"), dict):
            rewritten["io"].pop("directories", None)
        if role == "case" and path == Path(workspace_root, "config", "case.yml"):
            rewritten.setdefault("title", template_name)
        if role == "post":
            if isinstance(rewritten.get("source_data"), dict):
                rewritten["source_data"].pop("directory", None)
            if isinstance(rewritten.get("io"), dict):
                rewritten["io"].pop("output_directory", None)
        if role == "study" and isinstance(rewritten.get("base_configs"), dict):
            for role in ("case", "solver", "monitor", "post"):
                canonical = os.path.join("config", f"{role}.yml").replace(os.sep, "/")
                if os.path.isfile(os.path.join(workspace_root, canonical)):
                    rewritten["base_configs"][role] = canonical
        write_yaml_file(str(path), rewritten)
 
    return {
        "workspace_config": initialize_workspace_root(workspace_root, template_name),
        "canonical_roles": {
            role: os.path.join(workspace_root, "config", f"{role}.yml")
            for role in ("case", "solver", "monitor", "post", "cluster")
            if os.path.isfile(os.path.join(workspace_root, "config", f"{role}.yml"))
        },
        "input_moves": input_moves,
    }
 
 
WORKSPACE_INPUT_DIRECTORIES = {
    "grid": "inputs/grids",
    "initial-condition": "inputs/initial_conditions",
    "inlet-profile": "inputs/inlet_profiles",
    "reference-field": "inputs/reference_fields",
}
 
 
def import_workspace_input(workspace_root: str, kind: str, source: str,
                           name: str = None, mode: str = "copy") -> dict:
    """!
    @brief Explicitly import or register one workspace input.
    @param[in] workspace_root Initialized workspace root.
    @param[in] kind Semantic input kind.
    @param[in] source Existing source file path.
    @param[in] name Optional destination basename.
    @param[in] mode Copy, reflink, hardlink, or external-reference mode.
    @return Catalog entry describing the durable input identity.
    """
    workspace_root = os.path.abspath(workspace_root)
    load_workspace_config(workspace_root)
    ensure_workspace_layout(workspace_root)
    if kind not in WORKSPACE_INPUT_DIRECTORIES:
        raise ValueError(f"Unsupported input kind: {kind}")
    source = os.path.abspath(os.path.expanduser(source))
    if not os.path.isfile(source):
        raise ValueError(f"Input source is not a file: {source}")
    basename = name or os.path.basename(source)
    if basename != os.path.basename(basename) or basename in _PLAIN_FILENAME_SENTINELS:
        raise ValueError("--name must be a plain filename without directory traversal.")
    target_dir = os.path.join(workspace_root, *WORKSPACE_INPUT_DIRECTORIES[kind].split("/"))
    os.makedirs(target_dir, exist_ok=True)
    if mode == "reference":
        destination = os.path.join(target_dir, basename + ".reference.yml")
        write_yaml_file(destination, {
            "schema_version": 1,
            "picurv_external_reference": source,
            "sha256_at_registration": _asset_file_sha256(source),
            "bytes_at_registration": os.path.getsize(source),
        })
    else:
        destination = os.path.join(target_dir, basename)
        if os.path.exists(destination):
            raise ValueError(f"Workspace input already exists: {destination}")
        temporary = f"{destination}.tmp.{os.getpid()}"
        try:
            if mode == "copy":
                shutil.copy2(source, temporary)
            elif mode == "hardlink":
                os.link(source, temporary)
            elif mode == "reflink":
                cp = shutil.which("cp")
                if not cp:
                    raise ValueError("reflink mode requires the 'cp' command.")
                result = subprocess.run(
                    [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                    text=True, capture_output=True, check=False,
                )
                if result.returncode != 0:
                    raise ValueError((result.stderr or "reflink copy failed").strip())
            else:
                raise ValueError(f"Unsupported import mode: {mode}")
            os.replace(temporary, destination)
        finally:
            if os.path.lexists(temporary):
                os.remove(temporary)
    relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
    entry_id = _stable_mapping_sha256({"kind": kind, "path": relative, "source": source})[:16]
    catalog_path = os.path.join(workspace_root, "inputs", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "inputs": {}
    }
    catalog.setdefault("inputs", {})[entry_id] = {
        "kind": kind,
        "path": relative,
        "mode": mode,
        "sha256": _asset_file_sha256(source),
        "bytes": os.path.getsize(source),
        "source": source if mode == "reference" else None,
        "registered_at": datetime.now().astimezone().isoformat(),
    }
    write_yaml_file(catalog_path, catalog)
    return {"id": entry_id, **catalog["inputs"][entry_id]}
 
 
def inputs_workflow(args):
    """!
    @brief Handle explicit workspace input management.
    @param[in] args Parsed inputs command arguments.
    @return None.
    """
    workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
    if not workspace_root:
        raise ValueError("No initialized workspace found; run picurv init first or pass --workspace.")
    if args.inputs_action != "import":
        raise ValueError(f"Unsupported inputs action: {args.inputs_action}")
    entry = import_workspace_input(
        workspace_root, args.kind, args.source, name=args.name, mode=args.mode
    )
    print(f"[SUCCESS] Registered input {entry['id']}: {entry['path']}")
    if entry["mode"] == "reference":
        print("[WARNING] This is an external reference. Storage will record it but will not copy or prune its target.")
 
 
def version_workflow(args):
    """!
    @brief Report, and for the `status` action validate, the shared build identity.
 
    @details Bare `picurv version` reports and always succeeds; it is an informational
             surface that scripts and documentation already depend on. `picurv version
             status` additionally exits non-zero when the conductor, the executables,
             and the workspace requirement do not agree, so a job script can refuse to
             launch a run whose provenance would be incoherent.
    @param[in] args Parsed version command arguments.
    @return None.
    """
    workspace_root = find_workspace_root(os.getcwd())
    payload = dict(PICURV_BUILD)
    payload["source_root"] = PACKAGE_PROJECT_ROOT
    payload["workspace"] = workspace_root
    payload["workspace_requirement"] = None
    if workspace_root:
        software = load_workspace_config(workspace_root).get("software") or {}
        payload["workspace_requirement"] = software.get("picurv") if isinstance(software, dict) else None
    payload["binaries"] = runtime_build_identities()
    validating = getattr(args, "version_action", None) == "status"
    problems = build_identity_problems(payload["binaries"], payload["workspace_requirement"])
    payload["coherent"] = not problems
    payload["problems"] = problems
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        if validating and problems:
            sys.exit(1)
        return
    print(f"PICurv release : {payload['release_version']}")
    print(f"Build identity : {payload['build_id']}")
    print(f"Git commit     : {payload.get('git_commit') or 'unavailable'}")
    print(f"Dirty tree     : {payload.get('dirty') if payload.get('dirty') is not None else 'unknown'}")
    if workspace_root:
        print(f"Workspace      : {workspace_root}")
        print(f"Requirement    : {payload['workspace_requirement'] or 'latest active version'}")
    print("\nNative executables")
    for name, identity in sorted(payload["binaries"].items()):
        if not identity.get("available"):
            print(f"  {name:<14}: unavailable ({identity.get('reason', 'unknown')})")
            continue
        agreement = "matches source" if identity["matches_source"] else "STALE - rebuild"
        print(f"  {name:<14}: {identity['build_id']} ({agreement})")
    if not validating:
        warn_on_stale_runtime_binaries(payload["binaries"])
        return
    if not problems:
        print("\nBuild identity is coherent.")
        return
    print("\nBuild identity is NOT coherent:", file=sys.stderr)
    for problem in problems:
        print(f"  - {problem}", file=sys.stderr)
    sys.exit(1)
 
 
def _require_clean_source_checkout(action: str) -> None:
    """!
    @brief Refuse version-changing Git operations in a dirty source checkout.
    @param[in] action User-facing action name.
    @return None.
    """
    result = subprocess.run(
        ["git", "status", "--porcelain"], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError(f"{action}: cannot inspect the PICurv Git checkout.")
    if result.stdout.strip():
        raise ValueError(
            f"{action}: the PICurv source checkout has uncommitted changes. "
            "Commit or stash them before changing versions."
        )
 
 
def _git_source_command(arguments: list) -> subprocess.CompletedProcess:
    """!
    @brief Run a checked Git command against the active PICurv source checkout.
    @param[in] arguments Git arguments excluding the executable.
    @return Completed successful Git process.
    """
    result = subprocess.run(
        ["git", *arguments], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError((result.stderr or result.stdout or "Git command failed.").strip())
    return result
 
 
def source_workflow(args):
    """!
    @brief Fetch source history without silently changing the active code.
    @param[in] args Parsed source command arguments.
    @return None.
    """
    if args.source_action != "update":
        raise ValueError(f"Unsupported source action: {args.source_action}")
    _git_source_command(["fetch", "--tags", "--prune", args.remote])
    print(f"[SUCCESS] Fetched branches and tags from {args.remote}; active checkout was not changed.")
 
 
def _workspace_requested_version(workspace_root: str):
    """!
    @brief Resolve an exact version requested by an initialized workspace.
    @param[in] workspace_root Initialized workspace root.
    @return Exact version or tag text.
    """
    software = load_workspace_config(workspace_root).get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if not requirement:
        raise ValueError(
            f"{workspace_root}/{WORKSPACE_CONFIG_FILENAME} has no software.picurv pin; "
            "name a version explicitly."
        )
    if any(token in str(requirement) for token in "<>=!~,*"):
        raise ValueError(
            "Automatic activation needs an exact release/tag, not a version range. "
            f"Pass the desired version explicitly (workspace requires {requirement!r})."
        )
    return str(requirement)
 
 
def versions_workflow(args):
    """!
    @brief List or activate a release using the existing source/build owners.
    @param[in] args Parsed versions command arguments.
    @return None.
    """
    action = args.versions_action
    if action == "list":
        result = _git_source_command(["tag", "--list", "--sort=-version:refname"])
        print(f"Active: {PICURV_BUILD['build_id']}")
        tags = [line for line in result.stdout.splitlines() if line.strip()]
        if tags:
            print("Installed/available tags:")
            for tag in tags:
                print(f"  {tag}")
        else:
            print("No version tags are present in this checkout.")
        return
    version = getattr(args, "version", None)
    if action == "activate" and not version:
        workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
        if not workspace_root:
            raise ValueError("No workspace found and no version was named.")
        version = _workspace_requested_version(workspace_root)
    if action not in _VERSION_BUILD_ACTIONS:
        raise ValueError(f"Unsupported versions action: {action}")
    _require_clean_source_checkout(f"versions {action}")
    # There is one installation, and this rewrites it in place. Anything resolving
    # executables from it - other workspaces, and any running job that did not pin its
    # binaries - is changed by this too, so say what is about to move before it moves.
    print(
        f"[WARNING] {PACKAGE_PROJECT_ROOT} is a single shared installation. Building "
        f"{version!r} here re-points every workspace that resolves executables from it, "
        "including any job already running against them.",
        file=sys.stderr,
    )
    print(
        "          Case-local executables pinned with 'picurv init --pin-binaries' are "
        "unaffected.",
        file=sys.stderr,
    )
    _git_source_command(["fetch", "--tags", "origin"])
    _git_source_command(["checkout", "--detach", str(version)])
    result = subprocess.run(["make", "all"], cwd=PACKAGE_PROJECT_ROOT, check=False)
    if result.returncode != 0:
        raise ValueError(f"Build failed after activating {version!r}.")
    print(f"[SUCCESS] Activated and built PICurv {version}.")
 
 
def init_case(args):
    """!
    @brief Implements the 'init' command.
    @details Creates a new case study directory by copying a template.
             Runtime binaries are resolved from the project bin/ directory
             via PATH; pass --pin-binaries to pin specific versions locally.
    @param[in] args The command-line arguments parsed by argparse.
    """
    context = resolve_case_origin_context(source_root_override=getattr(args, "source_root", None))
    try:
        source_project_root = require_project_root(context["source_project_root"], "init")
        template_path = resolve_template_directory(source_project_root, args.template_name)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    # The destination path is relative to the current working directory.
    dest_path = os.path.abspath(os.path.join(os.getcwd(), args.dest_name if args.dest_name else args.template_name))
 
    if os.path.exists(dest_path):
        print(f"[FATAL] Destination directory '{dest_path}' already exists.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Initializing new case '{os.path.basename(dest_path)}' from template '{args.template_name}'...")
    
    shutil.copytree(template_path, dest_path)
    print(f"[SUCCESS] Copied template files to: {dest_path}")
 
    copied_runtime_example = os.path.join(dest_path, RUNTIME_EXECUTION_EXAMPLE_FILENAME)
    if os.path.isfile(copied_runtime_example):
        os.remove(copied_runtime_example)
 
    try:
        workspace_layout = organize_initialized_workspace(
            dest_path, args.template_name, source_template_root=template_path
        )
        print(f"[INFO] Wrote workspace identity: {os.path.relpath(workspace_layout['workspace_config'])}")
        if workspace_layout["canonical_roles"]:
            print("[INFO] Canonical editable configurations:")
            for role, path in sorted(workspace_layout["canonical_roles"].items()):
                print(f"  - {role}: {os.path.relpath(path)}")
    except Exception as exc:
        print(f"[FATAL] Failed to create canonical workspace layout: {exc}", file=sys.stderr)
        shutil.rmtree(dest_path, ignore_errors=True)
        sys.exit(1)
 
    try:
        runtime_result = ensure_case_runtime_execution_config(dest_path, source_project_root, overwrite=True)
        print(f"[INFO] Wrote optional runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("       Seeded from repo-local '.picurv-execution.yml'.")
        print("       Leave it unchanged for ordinary local runs; edit it only if your site needs custom MPI launcher tokens.")
    except Exception as e:
        print(f"[ERROR] Failed to write runtime execution config: {e}", file=sys.stderr)
 
    try:
        metadata_path, _ = write_case_origin_metadata(
            dest_path,
            source_project_root,
            template_name=args.template_name,
            template_managed_files=list_template_relative_files(
                template_path,
                excluded_rel_paths={RUNTIME_EXECUTION_EXAMPLE_FILENAME},
            ),
        )
        print(f"[INFO] Wrote case origin metadata: {os.path.relpath(metadata_path)}")
    except Exception as e:
        print(f"[ERROR] Failed to write case origin metadata: {e}", file=sys.stderr)
 
    cluster_profile_candidates = sorted(
        {
            os.path.basename(path)
            for pattern in ("*cluster*.yml", "*cluster*.yaml")
            for search_root in (dest_path, os.path.join(dest_path, "config"))
            for path in glob.glob(os.path.join(search_root, pattern))
        }
    )
    if cluster_profile_candidates:
        print("[INFO] Cluster profile sample(s) copied with this case:")
        for profile_name in cluster_profile_candidates:
            print(f"  - {profile_name}")
        print("       Edit account/partition/module_setup and any batch-specific launcher overrides before using --cluster.")
 
    if getattr(args, "pin_binaries", False):
        print("[INFO] Pinning runtime binaries into case directory...")
        try:
            copied_binaries = sync_case_binaries(dest_path, source_project_root)
            for dest_file_path in copied_binaries:
                print(f"  - Pinned '{os.path.basename(dest_file_path)}'")
            print("[SUCCESS] Case directory is ready with pinned binaries.")
            print("          These local copies will be used instead of bin/ originals.")
        except ValueError as exc:
            print(f"[WARNING] {exc}", file=sys.stderr)
            print("          No binaries were pinned. Run 'picurv build' first.", file=sys.stderr)
    else:
        print("[SUCCESS] Case directory is ready.")
        print("          Runtime binaries (simulator, postprocessor) are resolved from the active PICurv installation.")
        print("          Pin software.picurv in .picurv-workspace.yml only when this workspace needs a release constraint.")
    print("          Ensure 'picurv' is on your PATH (source etc/picurv.sh) to run from any directory.")
 
 
def sync_case_config_command(args):
    """!
    @brief Refresh template-managed config/docs files in a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "sync-config")
        case_dir = require_existing_case_dir(context["case_dir"], "sync-config", source_project_root)
        template_name = context.get("template_name")
        template_dir = resolve_template_directory(source_project_root, template_name)
        existing_managed = context.get("metadata", {}).get("template_managed_files")
        if not isinstance(existing_managed, list):
            existing_managed = None
        summary = sync_case_template_files(
            case_dir,
            template_dir,
            overwrite=getattr(args, "overwrite", False),
            prune=getattr(args, "prune", False),
            managed_rel_paths=existing_managed,
        )
        metadata_path, _ = write_case_origin_metadata(
            case_dir,
            source_project_root,
            template_name=template_name,
            existing=context.get("metadata"),
            template_managed_files=summary["template_managed_files"],
        )
        runtime_result = ensure_case_runtime_execution_config(case_dir, source_project_root, overwrite=False)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    print(f"[SUCCESS] Synced template files from '{template_name}' into: {case_dir}")
    print(f"[INFO] Copied new files     : {len(summary['copied'])}")
    print(f"[INFO] Overwritten files   : {len(summary['overwritten'])}")
    print(f"[INFO] Skipped modified    : {len(summary['skipped_modified'])}")
    print(f"[INFO] Already unchanged   : {len(summary['unchanged'])}")
    print(f"[INFO] Pruned stale files  : {len(summary['pruned'])}")
    if runtime_result["created"]:
        print(f"[INFO] Created runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("[INFO] Seed source              : repo-local .picurv-execution.yml")
    if summary.get("prune_requested_without_tracking"):
        print("[WARNING] Prune tracking unavailable for this case; no removed template files were deleted.", file=sys.stderr)
    print(f"[INFO] Case origin metadata refreshed: {os.path.relpath(metadata_path)}")
 
 
def pull_source_repo(args):
    """!
    @brief Refresh source branches in the repository resolved from a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "pull-source")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    rebase = not getattr(args, "no_rebase", False)
    remote = getattr(args, "remote", None)
    branch = getattr(args, "branch", None)
    current_branch_only = (
        getattr(args, "current_branch_only", False)
        or remote is not None
        or branch is not None
    )
 
    if not current_branch_only:
        pull_all_source_branches(source_project_root, "pull-source.log", rebase=rebase)
        return
 
    command = ["git", "pull"]
    if rebase:
        command.append("--rebase")
    if remote:
        command.append(remote)
        if branch:
            command.append(branch)
    elif branch:
        command.extend(["origin", branch])
 
    execute_command(command, source_project_root, "pull-source.log", {})
 
def build_project(args):
    """!
    @brief Implements the 'build' command.
    @details Executes the top-level Makefile directly, passing through any
             additional arguments to `make`. This allows for building,
             cleaning, and other Makefile targets via the orchestrator
             without maintaining a separate build wrapper script.
    @param[in] args The command-line arguments parsed by argparse.
    """
 
    print("\n" + "="*27 + " BUILD STAGE " + "="*27)
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "build")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    makefile_path = os.path.join(source_project_root, "Makefile")
 
    if not os.path.isfile(makefile_path):
        print(f"[FATAL] Makefile not found at expected location: {makefile_path}", file=sys.stderr)
        print("        Please ensure the project root contains a valid Makefile.", file=sys.stderr)
        sys.exit(1)
 
    make_args = list(args.make_args or [])
    if make_args_include_explicit_goal(make_args):
        command = ["make"] + make_args
    else:
        command = ["make", "all"] + make_args
        print("[INFO] No explicit make target supplied; defaulting to 'all'.")
        print("       Use 'picurv build clean-project ...' or another target when you want a non-build make action.")
    # For the build process, we don't have a monitor.yml, so we pass an empty
    # dict to execute_command. The command should be run in the project root.
    execute_command(command, source_project_root, "build.log", {})
   
 
 
 
# ==============================================================================