velophex 0.2.0__py3-none-any.whl

velophex/contracts/project.py

@@ -0,0 +1,1008 @@
+"""``project.json`` - the single project manifest (ADR-P002).
+
+The model mirrors ``VeloPhex.Platform.Contracts.Projects.ProjectManifest`` and the language
+neutral definition in ``schemas/project.schema.json``. Reading uses pydantic; **writing does
+not**, because the order and the escaping of the output are part of the contract: the
+package manifest hashes ``content/project.json``, so the Python CLI has to emit the same
+bytes Studio would. Every model therefore has an explicit :meth:`to_json_value` that lists
+its members in the order the .NET record declares them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Final
+from uuid import UUID
+
+from pydantic import Field
+
+from velophex import _json
+from velophex.contracts._model import ContractModel, omit_none
+from velophex.contracts.diagnostics import Diagnostic
+from velophex.contracts.diagnostics import ProjectDiagnosticCodes as Codes
+from velophex.contracts.runtimes import RuntimeKind
+from velophex.contracts.validation import (
+    has_build_metadata,
+    is_capability,
+    is_entry_point_id,
+    is_package_id,
+    is_python_handler,
+    is_safe_relative_path,
+    is_semantic_version,
+    is_version_range,
+)
+
+__all__ = [
+    "AutomationDependency",
+    "DesignerSettings",
+    "EntryPoint",
+    "ExecutionSettings",
+    "ExpressionLanguages",
+    "ExpressionPolicy",
+    "ExpressionPolicyValues",
+    "ExpressionSettings",
+    "OutputTypes",
+    "ProjectConstant",
+    "ProjectFiles",
+    "ProjectGlobalVariable",
+    "ProjectManifest",
+    "RuntimeSpec",
+    "TestCaseSettings",
+    "read_project_manifest",
+    "validate_project_manifest",
+    "write_project_manifest",
+]
+
+CURRENT_SCHEMA_VERSION: Final = "1.0"
+SCHEMA_URI: Final = "https://schemas.velophex.com/platform/project/1.0/project.schema.json"
+
+
+class ProjectFiles:
+    """Well-known file names of a VeloPhex project. Use these instead of string literals."""
+
+    MANIFEST_FILE_NAME: Final = "project.json"
+    LOCK_FILE_NAME: Final = "project.lock.json"
+    PYTHON_LOCK_FILE_NAME: Final = "uv.lock"
+    WORKFLOW_EXTENSION: Final = ".xaml"
+    DEFAULT_MAIN_WORKFLOW: Final = "Main.xaml"
+    MAXIMUM_MANIFEST_BYTES: Final = 1024 * 1024
+    MAXIMUM_PNG_ICON_BYTES: Final = 1024 * 1024
+    MAXIMUM_SVG_ICON_BYTES: Final = 16 * 1024
+
+
+class OutputTypes:
+    """What a project produces."""
+
+    PROCESS: Final = "process"
+    LIBRARY: Final = "library"
+    TESTS: Final = "tests"
+
+    ALL: Final = (PROCESS, LIBRARY, TESTS)
+
+    @staticmethod
+    def is_known(value: str | None) -> bool:
+        """True for a known output type."""
+        return value in OutputTypes.ALL
+
+    @staticmethod
+    def requires_entry_points(value: str | None) -> bool:
+        """True when a project of this output type must declare at least one entry point."""
+        return value in (OutputTypes.PROCESS, OutputTypes.TESTS)
+
+
+class ExpressionLanguages:
+    """Expression languages of VeloPhex workflow projects."""
+
+    CSHARP: Final = "csharp"
+    VISUAL_BASIC: Final = "vb"
+
+    ALL: Final = (CSHARP, VISUAL_BASIC)
+
+    @staticmethod
+    def is_known(value: str | None) -> bool:
+        """Case-sensitive: the token set is the canon shared with the workflow XAML root attribute."""
+        return value in ExpressionLanguages.ALL
+
+
+class ExpressionPolicyValues:
+    """The expression policy values (engine ADR 0036), ordered strict < default < default+types."""
+
+    STRICT: Final = "strict"
+    DEFAULT: Final = "default"
+    DEFAULT_PLUS_TYPES: Final = "default+types"
+
+    ALL: Final = (STRICT, DEFAULT, DEFAULT_PLUS_TYPES)
+
+    @staticmethod
+    def is_known(value: str | None) -> bool:
+        """Case-sensitive, like every other contract token."""
+        return value in ExpressionPolicyValues.ALL
+
+
+#: What no policy and no extra type lifts; mirrors ``ExpressionPolicy.Floor`` in .NET.
+EXPRESSION_FLOOR: Final = (
+    "System.Reflection",
+    "System.Runtime.Loader",
+    "System.Runtime.CompilerServices",
+    "System.Runtime.InteropServices",
+    "System.Type",
+    "System.Activator",
+    "System.AppDomain",
+    "System.AppContext",
+    "System.GC",
+    "System.Delegate",
+    "System.MulticastDelegate",
+    "System.RuntimeTypeHandle",
+    "System.RuntimeMethodHandle",
+    "System.RuntimeFieldHandle",
+    "System.TypedReference",
+    "System.ArgIterator",
+    "System.Runtime.ProfileOptimization",
+    "System.Runtime.GCSettings",
+    "System.Runtime.MemoryFailPoint",
+    "System.Runtime.ControlledExecution",
+    "System.Diagnostics.Process",
+    "System.Diagnostics.ProcessStartInfo",
+    "Microsoft.CodeAnalysis",
+    "Microsoft.CSharp",
+)
+
+_TYPE_SEGMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+def expression_floor_entry(type_name: str) -> str | None:
+    """The floor entry that covers *type_name*, or ``None``."""
+    return next(
+        (entry for entry in EXPRESSION_FLOOR if type_name == entry or type_name.startswith(entry + ".")),
+        None,
+    )
+
+
+def is_type_name(name: str | None) -> bool:
+    """Two or more dot-separated identifiers (ASCII letters, digits, ``_``; no leading digit)."""
+    if not name or len(name) > 512:
+        return False
+
+    segments = name.split(".")
+    return len(segments) >= 2 and all(_TYPE_SEGMENT.match(segment) for segment in segments)
+
+
+def expression_fingerprint(value: str, tier_version: int, extra_types: list[str]) -> str:
+    """``ExpressionPolicy.ComputeFingerprint``: SHA-256 of the canonical JSON, nothing escaped."""
+    extras = ",".join(f'"{item}"' for item in sorted(extra_types))
+    canonical = f'{{"extraTypes":[{extras}],"tierVersion":{tier_version},"value":"{value}"}}'
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def expression_policy_problems(value: str, extra_types: list[str], tier_version: int | None = None) -> list[str]:
+    """``ExpressionPolicy.Validate``: one sentence per problem, empty when valid."""
+    problems: list[str] = []
+
+    if not ExpressionPolicyValues.is_known(value):
+        problems.append(f"Expression policy '{value}' is not one of: {', '.join(ExpressionPolicyValues.ALL)}.")
+
+    if tier_version is not None and tier_version < 1:
+        problems.append(f"Tier version {tier_version} is not a positive number.")
+
+    for item in extra_types:
+        if not is_type_name(item):
+            problems.append(f"Extra type '{item}' is not a full type name such as System.IO.FileInfo.")
+        elif (floor := expression_floor_entry(item)) is not None:
+            problems.append(
+                f"Extra type '{item}' is on the expression floor ({floor}) and cannot be allowed; "
+                "use an activity or Invoke Code."
+            )
+
+    return problems
+
+
+class ExpressionSettings(ContractModel):
+    """``project.json`` ``expressions``: the policy the project is built under (engine ADR 0036)."""
+
+    policy: str = ExpressionPolicyValues.DEFAULT
+    extra_types: list[str] = Field(default_factory=list, alias="extraTypes")
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``ExpressionSettings`` record."""
+        return {"policy": self.policy, "extraTypes": list(self.extra_types)} | self.extras()
+
+
+class ExpressionPolicy(ContractModel):
+    """A package's record of its expression policy (manifest ``expressionPolicy``)."""
+
+    value: str
+    tier_version: int | None = Field(default=None, alias="tierVersion")
+    extra_types: list[str] = Field(default_factory=list, alias="extraTypes")
+    fingerprint: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``ExpressionPolicy`` record."""
+        return (
+            omit_none(
+                {
+                    "value": self.value,
+                    "tierVersion": self.tier_version,
+                    "extraTypes": list(self.extra_types),
+                    "fingerprint": self.fingerprint,
+                }
+            )
+            | self.extras()
+        )
+
+
+class ProjectGlobalVariable(ContractModel):
+    """``project.json`` ``globals``: a project-level global variable (contracts 0.8.11)."""
+
+    name: str
+    type: str
+    default: str | None = None
+    sensitive: bool = False
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET record; ``sensitive`` only when true."""
+        return (
+            omit_none(
+                {
+                    "name": self.name,
+                    "type": self.type,
+                    "default": self.default,
+                    "sensitive": True if self.sensitive else None,
+                }
+            )
+            | self.extras()
+        )
+
+
+class ProjectConstant(ContractModel):
+    """``project.json`` ``constants``: a project-level constant, fixed at compile time."""
+
+    name: str
+    type: str
+    value: str
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``ProjectConstant`` record."""
+        return {"name": self.name, "type": self.type, "value": self.value} | self.extras()
+
+
+# A name both C# and Visual Basic accept as an identifier (ProjectSymbolNames in .NET).
+_SYMBOL_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,127}$")
+
+
+# ISO 8601 duration, the subset project.schema.json accepts (days, hours, minutes, seconds).
+_DURATION = re.compile(r"^P(?!$)([0-9]+D)?(T(?=[0-9])([0-9]+H)?([0-9]+M)?([0-9]+(\.[0-9]+)?S)?)?$")
+
+
+class RuntimeSpec(ContractModel):
+    """The runtime a project targets and its runtime-specific settings."""
+
+    kind: str
+    engine_version: str | None = Field(default=None, alias="engineVersion")
+    target_framework: str | None = Field(default=None, alias="targetFramework")
+    expression_language: str | None = Field(default=None, alias="expressionLanguage")
+    python_version: str | None = Field(default=None, alias="pythonVersion")
+    lock_file: str | None = Field(default=None, alias="lockFile")
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``RuntimeSpec`` record."""
+        return (
+            omit_none(
+                {
+                    "kind": self.kind,
+                    "engineVersion": self.engine_version,
+                    "targetFramework": self.target_framework,
+                    "expressionLanguage": self.expression_language,
+                    "pythonVersion": self.python_version,
+                    "lockFile": self.lock_file,
+                }
+            )
+            | self.extras()
+        )
+
+
+def split_data_source(data_source: str) -> tuple[str, str | None]:
+    """Split a data source into its file and, for an ``.xlsx``, its sheet (``TestCaseSettings.ParseDataSource``).
+
+    The text after the first ``.xlsx#`` (case-insensitive) is the sheet, which may itself contain
+    ``#``; any other source is a file with no sheet.
+    """
+    index = data_source.lower().find(".xlsx#")
+    return (data_source, None) if index < 0 else (data_source[: index + 5], data_source[index + 6 :])
+
+
+def _is_data_source_file(source: str) -> bool:
+    file, sheet = split_data_source(source)
+
+    if sheet is not None:
+        return 1 <= len(sheet) <= 31 and not any(character in sheet for character in "/\\?*[]:")
+
+    return file.lower().endswith((".csv", ".json", ".xlsx"))
+
+
+class TestCaseSettings(ContractModel):
+    """The per-entry-point ``testCase`` marker (contracts 0.8.25).
+
+    An empty object marks a plain test case; ``dataSource`` (a project-relative ``.csv``,
+    ``.json`` or, from contracts 0.8.30, ``.xlsx`` file with an optional ``#Sheet``; VeloPhex
+    workflow only) makes it data-driven: one run and one result per row.
+    """
+
+    data_source: str | None = Field(default=None, alias="dataSource")
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``TestCaseSettings`` record."""
+        return omit_none({"dataSource": self.data_source}) | self.extras()
+
+
+class EntryPoint(ContractModel):
+    """A way to start the project, with the JSON Schema of its inputs and outputs."""
+
+    id: str
+    path: str
+    handler: str | None = None
+    display_name: str | None = Field(default=None, alias="displayName")
+    description: str | None = None
+    input: Any | None = None
+    output: Any | None = None
+    test_case: TestCaseSettings | None = Field(default=None, alias="testCase")
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``EntryPoint`` record."""
+        return (
+            omit_none(
+                {
+                    "id": self.id,
+                    "path": self.path,
+                    "handler": self.handler,
+                    "displayName": self.display_name,
+                    "description": self.description,
+                    "input": self.input,
+                    "output": self.output,
+                    "testCase": None if self.test_case is None else self.test_case.to_json_value(),
+                }
+            )
+            | self.extras()
+        )
+
+
+class AutomationDependency(ContractModel):
+    """A published automation this project invokes as a step (hybrid, ADR-P007)."""
+
+    package_id: str = Field(alias="packageId")
+    version: str
+    runtime: str
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``AutomationDependency`` record."""
+        return {"packageId": self.package_id, "version": self.version, "runtime": self.runtime} | self.extras()
+
+
+class ExecutionSettings(ContractModel):
+    """How and where the project may run."""
+
+    requires_user_interaction: bool = Field(default=False, alias="requiresUserInteraction")
+    supports_attended: bool = Field(default=True, alias="supportsAttended")
+    supports_unattended: bool = Field(default=True, alias="supportsUnattended")
+    supports_persistence: bool = Field(default=False, alias="supportsPersistence")
+    timeout: str | None = None
+    capabilities: list[str] = Field(default_factory=list)
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``ExecutionSettings`` record."""
+        return (
+            omit_none(
+                {
+                    "requiresUserInteraction": self.requires_user_interaction,
+                    "supportsAttended": self.supports_attended,
+                    "supportsUnattended": self.supports_unattended,
+                    "supportsPersistence": self.supports_persistence,
+                    "timeout": self.timeout,
+                    "capabilities": list(self.capabilities),
+                }
+            )
+            | self.extras()
+        )
+
+
+class DesignerSettings(ContractModel):
+    """Written by Studio; ignored at run time."""
+
+    studio_version: str | None = Field(default=None, alias="studioVersion")
+    profile: str | None = None
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``DesignerSettings`` record."""
+        return omit_none({"studioVersion": self.studio_version, "profile": self.profile}) | self.extras()
+
+
+class ProjectManifest(ContractModel):
+    """Identity, runtime, entry points and dependencies of a VeloPhex project."""
+
+    schema_: str | None = Field(default=None, alias="$schema")
+    schema_version: str = Field(alias="schemaVersion")
+    project_id: UUID = Field(alias="projectId")
+    name: str
+    version: str
+    description: str | None = None
+    authors: list[str] | None = None
+    icon: str | None = None
+    output_type: str = Field(default=OutputTypes.PROCESS, alias="outputType")
+    runtime: RuntimeSpec
+    main: str | None = None
+    entry_points: list[EntryPoint] = Field(default_factory=list, alias="entryPoints")
+    dependencies: dict[str, str] = Field(default_factory=dict)
+    automation_dependencies: list[AutomationDependency] = Field(default_factory=list, alias="automationDependencies")
+    execution: ExecutionSettings = Field(default_factory=ExecutionSettings)
+    designer: DesignerSettings | None = None
+    ui_automation: Any | None = Field(default=None, alias="uiAutomation")
+    expressions: ExpressionSettings | None = None
+    globals_: list[ProjectGlobalVariable] | None = Field(default=None, alias="globals")
+    constants: list[ProjectConstant] | None = None
+    exception_handler_workflow: str | None = Field(default=None, alias="exceptionHandlerWorkflow")
+
+    def required_runtimes(self) -> list[str]:
+        """Runtimes a machine needs: this project's own plus every automation it invokes.
+
+        Distinct and ordinally sorted, which is what the Orchestrator matches against a
+        runner's reported runtimes when it places a job.
+        """
+        kinds = {dependency.runtime for dependency in self.automation_dependencies if dependency.runtime}
+
+        if self.runtime.kind:
+            kinds.add(self.runtime.kind)
+
+        return sorted(kinds)
+
+    def default_entry_point(self) -> EntryPoint | None:
+        """The entry point named by ``main``, else the first one."""
+        if self.main is not None:
+            for entry in self.entry_points:
+                if entry.path == self.main:
+                    return entry
+
+        return self.entry_points[0] if self.entry_points else None
+
+    def is_test_case(self, entry: EntryPoint) -> bool:
+        """True when *entry* carries ``testCase`` or the project's output type is ``tests``."""
+        return entry.test_case is not None or self.output_type == OutputTypes.TESTS
+
+    def find_entry_point(self, entry_point_id: str | None) -> EntryPoint | None:
+        """The entry point with *entry_point_id*, or the default when it is ``None`` or empty."""
+        if not entry_point_id:
+            return self.default_entry_point()
+
+        for entry in self.entry_points:
+            if entry.id.casefold() == entry_point_id.casefold():
+                return entry
+
+        return None
+
+    def normalized(self) -> ProjectManifest:
+        """A copy with ``$schema`` set and dependencies sorted, as the .NET writer normalizes."""
+        return self.model_copy(
+            update={
+                "schema_": SCHEMA_URI,
+                "dependencies": dict(sorted(self.dependencies.items(), key=lambda pair: pair[0].casefold())),
+            }
+        )
+
+    def to_json_value(self) -> dict[str, Any]:
+        """Ordered mapping in the member order of the .NET ``ProjectManifest`` record."""
+        return (
+            omit_none(
+                {
+                    "$schema": self.schema_,
+                    "schemaVersion": self.schema_version,
+                    "projectId": str(self.project_id),
+                    "name": self.name,
+                    "version": self.version,
+                    "description": self.description,
+                    "authors": list(self.authors) if self.authors is not None else None,
+                    "icon": self.icon,
+                    "outputType": self.output_type,
+                    "runtime": self.runtime.to_json_value(),
+                    "main": self.main,
+                    "entryPoints": [entry.to_json_value() for entry in self.entry_points],
+                    "dependencies": dict(self.dependencies),
+                    "automationDependencies": [item.to_json_value() for item in self.automation_dependencies],
+                    "execution": self.execution.to_json_value(),
+                    "designer": self.designer.to_json_value() if self.designer is not None else None,
+                    "uiAutomation": self.ui_automation,
+                    "expressions": self.expressions.to_json_value() if self.expressions is not None else None,
+                    "globals": [item.to_json_value() for item in self.globals_] if self.globals_ is not None else None,
+                    "constants": [item.to_json_value() for item in self.constants]
+                    if self.constants is not None
+                    else None,
+                    "exceptionHandlerWorkflow": self.exception_handler_workflow,
+                }
+            )
+            | self.extras()
+        )
+
+
+def write_project_manifest(manifest: ProjectManifest) -> bytes:
+    """Serialize *manifest* exactly as ``ProjectManifestSerializer.WriteUtf8`` does.
+
+    Deterministic: ``$schema`` set, dependencies sorted, 2-space indentation, LF endings and
+    a trailing newline.
+    """
+    return (_json.dumps_document(manifest.normalized().to_json_value()) + "\n").encode("utf-8")
+
+
+def read_project_manifest(
+    payload: bytes | str,
+    root_path: str = "$",
+) -> tuple[ProjectManifest | None, list[Diagnostic]]:
+    """Parse and validate ``project.json``.
+
+    Returns the manifest and its diagnostics; the manifest is ``None`` only when the document
+    could not be parsed at all.
+    """
+    raw = payload if isinstance(payload, (bytes, bytearray)) else payload.encode("utf-8")
+
+    if len(raw) > ProjectFiles.MAXIMUM_MANIFEST_BYTES:
+        message = f"The document is {len(raw)} bytes; the limit is {ProjectFiles.MAXIMUM_MANIFEST_BYTES} bytes."
+        return None, [Diagnostic.error(Codes.DOCUMENT_TOO_LARGE, root_path, message)]
+
+    try:
+        document = _json.loads(raw)
+    except ValueError as error:
+        return None, [Diagnostic.error(Codes.INVALID_JSON, root_path, str(error))]
+
+    if not isinstance(document, dict):
+        return None, [Diagnostic.error(Codes.INVALID_JSON, root_path, "The document is not a JSON object.")]
+
+    try:
+        manifest = ProjectManifest.model_validate(document)
+    except Exception as error:  # pydantic ValidationError, or a bad GUID
+        return None, [Diagnostic.error(Codes.INVALID_JSON, root_path, str(error))]
+
+    return manifest, validate_project_manifest(manifest, root_path)
+
+
+def validate_project_manifest(manifest: ProjectManifest, root_path: str = "$") -> list[Diagnostic]:
+    """Apply the platform rules to *manifest*, mirroring ``ProjectManifestValidator``."""
+    diagnostics: list[Diagnostic] = []
+
+    _validate_identity(manifest, root_path, diagnostics)
+    _validate_runtime(manifest.runtime, f"{root_path}.runtime", diagnostics)
+    _validate_entry_points(manifest, root_path, diagnostics)
+    _validate_dependencies(manifest, root_path, diagnostics)
+    _validate_execution(manifest.execution, f"{root_path}.execution", diagnostics)
+    _validate_symbols(manifest, root_path, diagnostics)
+    _validate_exception_handler(manifest, root_path, diagnostics)
+
+    if manifest.icon is not None and (not is_safe_relative_path(manifest.icon) or not is_icon_file(manifest.icon)):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_ICON,
+                f"{root_path}.icon",
+                "The package icon is a '.png' or '.svg' file relative to the project root, "
+                "with '/' separators and no '.' or '..' segments.",
+            )
+        )
+
+    if manifest.expressions is not None:
+        for problem in expression_policy_problems(manifest.expressions.policy, manifest.expressions.extra_types):
+            diagnostics.append(Diagnostic.error(Codes.INVALID_EXPRESSION_POLICY, f"{root_path}.expressions", problem))
+
+    return diagnostics
+
+
+def is_icon_file(path: str) -> bool:
+    """Mirror of ``ProjectFiles.IsIconFile``: a package icon is a ``.png`` or ``.svg`` file."""
+    return path.lower().endswith((".png", ".svg"))
+
+
+def maximum_icon_bytes(path: str) -> int:
+    """Mirror of ``ProjectFiles.MaximumIconBytes``: 16 KiB for ``.svg``, 1 MiB (NuGet's limit) for ``.png``."""
+    return ProjectFiles.MAXIMUM_SVG_ICON_BYTES if path.lower().endswith(".svg") else ProjectFiles.MAXIMUM_PNG_ICON_BYTES
+
+
+def _validate_exception_handler(manifest: ProjectManifest, root: str, diagnostics: list[Diagnostic]) -> None:
+    """Mirror of ``ProjectManifestValidator.ValidateExceptionHandler`` (VPC1031, contracts 0.8.16)."""
+    handler = manifest.exception_handler_workflow
+
+    if handler is None:
+        return
+
+    path = f"{root}.exceptionHandlerWorkflow"
+
+    if manifest.runtime.kind != RuntimeKind.VELOPHEX_WORKFLOW:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_EXCEPTION_HANDLER_WORKFLOW,
+                path,
+                "Only a VeloPhex workflow project has a Global Exception Handler; "
+                "a Python automation handles its own exceptions.",
+            )
+        )
+    elif not is_safe_relative_path(handler) or not handler.lower().endswith(ProjectFiles.WORKFLOW_EXTENSION):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_EXCEPTION_HANDLER_WORKFLOW,
+                path,
+                f"The Global Exception Handler is a '{ProjectFiles.WORKFLOW_EXTENSION}' workflow path relative to "
+                "the project root, with '/' separators and no '.' or '..' segments.",
+            )
+        )
+
+
+def _validate_symbols(manifest: ProjectManifest, root: str, diagnostics: list[Diagnostic]) -> None:
+    """Mirror of ``ProjectManifestValidator.ValidateSymbols``: identifiers, unique ignoring case."""
+    names: set[str] = set()
+
+    def check(path: str, name: str, type_: str, kind: str) -> None:
+        if not _SYMBOL_NAME.match(name or ""):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_PROJECT_SYMBOL,
+                    f"{path}.name",
+                    f"The {kind} name '{name}' is not an identifier: start with a letter or '_' and use "
+                    "letters, digits or '_' (max 128).",
+                )
+            )
+        elif name.casefold() in names:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_PROJECT_SYMBOL,
+                    f"{path}.name",
+                    f"'{name}' names more than one global or constant; names are compared ignoring case, "
+                    "as Visual Basic does.",
+                )
+            )
+        else:
+            names.add(name.casefold())
+
+        if not (type_ or "").strip():
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_PROJECT_SYMBOL,
+                    f"{path}.type",
+                    f"The {kind} '{name}' needs a type, e.g. System.String.",
+                )
+            )
+
+    for index, item in enumerate(manifest.globals_ or []):
+        check(f"{root}.globals[{index}]", item.name, item.type, "global")
+
+    for index, constant in enumerate(manifest.constants or []):
+        path = f"{root}.constants[{index}]"
+        check(path, constant.name, constant.type, "constant")
+
+        if not (constant.value or "").strip():
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_PROJECT_SYMBOL, f"{path}.value", f"The constant '{constant.name}' needs a value."
+                )
+            )
+
+
+def _validate_identity(manifest: ProjectManifest, root: str, diagnostics: list[Diagnostic]) -> None:
+    if not (manifest.schema_version == CURRENT_SCHEMA_VERSION or manifest.schema_version.startswith("1.")):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.UNSUPPORTED_SCHEMA_VERSION,
+                f"{root}.schemaVersion",
+                f"Schema version '{manifest.schema_version}' is not supported; "
+                f"this platform reads {CURRENT_SCHEMA_VERSION}.",
+            )
+        )
+
+    if manifest.project_id.int == 0:
+        diagnostics.append(
+            Diagnostic.error(Codes.MISSING_PROJECT_ID, f"{root}.projectId", "The project id must be a non-empty GUID.")
+        )
+
+    if not is_package_id(manifest.name):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_NAME,
+                f"{root}.name",
+                "The name becomes the package id: use letters, digits, '_', '.' or '-', "
+                "starting and ending with a letter or digit (max 100).",
+            )
+        )
+
+    if has_build_metadata(manifest.version):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.VERSION_HAS_BUILD_METADATA,
+                f"{root}.version",
+                f"'{manifest.version}' carries build metadata after '+'. NuGet drops it from a package's "
+                "identity, so the published package would not be the version the manifest names; "
+                "use a pre-release label instead (1.0.0-build.7).",
+            )
+        )
+    elif not is_semantic_version(manifest.version):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_VERSION,
+                f"{root}.version",
+                f"'{manifest.version}' is not a SemVer 2.0 version such as 1.0.0 or 1.0.0-beta.1.",
+            )
+        )
+
+    if not OutputTypes.is_known(manifest.output_type):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.UNKNOWN_OUTPUT_TYPE,
+                f"{root}.outputType",
+                f"Output type '{manifest.output_type}' is not one of: {', '.join(OutputTypes.ALL)}.",
+            )
+        )
+
+
+def _validate_runtime(runtime: RuntimeSpec, path: str, diagnostics: list[Diagnostic]) -> None:
+    if runtime.kind == RuntimeKind.VELOPHEX_WORKFLOW:
+        if runtime.expression_language is not None and not ExpressionLanguages.is_known(runtime.expression_language):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.UNSUPPORTED_EXPRESSION_LANGUAGE,
+                    f"{path}.expressionLanguage",
+                    f"Expression language '{runtime.expression_language}' is not supported; "
+                    f"use one of: {', '.join(ExpressionLanguages.ALL)}.",
+                )
+            )
+    elif runtime.kind == RuntimeKind.PYTHON:
+        if not (runtime.python_version or "").strip():
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.MISSING_PYTHON_VERSION,
+                    f"{path}.pythonVersion",
+                    "Python projects must declare a Python version specifier, e.g. '>=3.12,<3.13'.",
+                )
+            )
+
+        if not is_safe_relative_path(runtime.lock_file):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.MISSING_LOCK_FILE,
+                    f"{path}.lockFile",
+                    "Python projects must name their lock file with a relative path, normally "
+                    f"'{ProjectFiles.PYTHON_LOCK_FILE_NAME}'.",
+                )
+            )
+    else:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.UNKNOWN_RUNTIME,
+                f"{path}.kind",
+                f"Runtime '{runtime.kind}' is not supported; "
+                f"use '{RuntimeKind.VELOPHEX_WORKFLOW}' or '{RuntimeKind.PYTHON}'.",
+            )
+        )
+
+
+def _validate_entry_points(manifest: ProjectManifest, root: str, diagnostics: list[Diagnostic]) -> None:
+    if OutputTypes.requires_entry_points(manifest.output_type) and not manifest.entry_points:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.MISSING_ENTRY_POINTS,
+                f"{root}.entryPoints",
+                f"A '{manifest.output_type}' project needs at least one entry point.",
+            )
+        )
+
+    seen: set[str] = set()
+
+    for index, entry in enumerate(manifest.entry_points):
+        path = f"{root}.entryPoints[{index}]"
+
+        if not is_entry_point_id(entry.id):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_ENTRY_POINT_ID,
+                    f"{path}.id",
+                    "An entry point id starts with a letter and uses letters, digits, '_', '.' or '-' (max 64).",
+                )
+            )
+        elif entry.id.casefold() in seen:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.DUPLICATE_ENTRY_POINT, f"{path}.id", f"Entry point id '{entry.id}' is used more than once."
+                )
+            )
+        else:
+            seen.add(entry.id.casefold())
+
+        if not is_safe_relative_path(entry.path):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.UNSAFE_PATH,
+                    f"{path}.path",
+                    "Entry point paths are relative to the project root and use '/' separators "
+                    "without '.' or '..' segments.",
+                )
+            )
+
+        _validate_entry_point_for_runtime(manifest.runtime.kind, entry, path, diagnostics)
+        _validate_test_case(manifest, entry, path, diagnostics)
+        _validate_argument_schema(entry.input, f"{path}.input", diagnostics)
+        _validate_argument_schema(entry.output, f"{path}.output", diagnostics)
+
+    if manifest.main is not None and not any(entry.path == manifest.main for entry in manifest.entry_points):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.MAIN_NOT_AN_ENTRY_POINT,
+                f"{root}.main",
+                f"Main '{manifest.main}' must be the path of one of the entry points.",
+            )
+        )
+
+
+def _validate_test_case(manifest: ProjectManifest, entry: EntryPoint, path: str, diagnostics: list[Diagnostic]) -> None:
+    """Mirror of ``ProjectManifestValidator.ValidateTestCase`` (VPC1032, contracts 0.8.25)."""
+    if entry.test_case is None:
+        return
+
+    if manifest.output_type == OutputTypes.LIBRARY:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_TEST_CASE,
+                f"{path}.testCase",
+                "A library's entry points are the activities it publishes; they cannot be test cases. "
+                "Move the test case to a 'tests' project.",
+            )
+        )
+
+    source = entry.test_case.data_source
+
+    if source is None:
+        return
+
+    if manifest.runtime.kind != RuntimeKind.VELOPHEX_WORKFLOW:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_TEST_CASE,
+                f"{path}.testCase.dataSource",
+                "Data-driven test cases are VeloPhex workflow test cases; remove the data source.",
+            )
+        )
+    elif not is_safe_relative_path(source) or not _is_data_source_file(source):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_TEST_CASE,
+                f"{path}.testCase.dataSource",
+                "A test case's data source is a '.csv', '.json' or '.xlsx' file (an '.xlsx' may name its sheet as "
+                "'file.xlsx#Sheet', 1 to 31 characters, none of / \\ ? * [ ] :), relative to the project root "
+                "with '/' separators and no '.' or '..' segments.",
+            )
+        )
+
+
+def _validate_entry_point_for_runtime(kind: str, entry: EntryPoint, path: str, diagnostics: list[Diagnostic]) -> None:
+    if kind == RuntimeKind.VELOPHEX_WORKFLOW:
+        if not entry.path.lower().endswith(ProjectFiles.WORKFLOW_EXTENSION):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_WORKFLOW_ENTRY_PATH,
+                    f"{path}.path",
+                    f"VeloPhex workflow entry points must be '{ProjectFiles.WORKFLOW_EXTENSION}' files.",
+                )
+            )
+
+        if entry.handler is not None:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.UNEXPECTED_HANDLER,
+                    f"{path}.handler",
+                    "Only Python entry points have a handler.",
+                )
+            )
+    elif kind == RuntimeKind.PYTHON and not is_python_handler(entry.handler):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_PYTHON_HANDLER,
+                f"{path}.handler",
+                "Python entry points need a handler in the form 'module.path:function'.",
+            )
+        )
+
+
+def _validate_argument_schema(schema: Any, path: str, diagnostics: list[Diagnostic]) -> None:
+    if schema is not None and not isinstance(schema, dict):
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_ARGUMENT_SCHEMA, path, "Inputs and outputs are described by a JSON Schema object."
+            )
+        )
+
+
+def _validate_dependencies(manifest: ProjectManifest, root: str, diagnostics: list[Diagnostic]) -> None:
+    for package, version_range in manifest.dependencies.items():
+        if not is_package_id(package) or not version_range.strip():
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_DEPENDENCY,
+                    f"{root}.dependencies['{package}']",
+                    'Dependencies map a package id to a NuGet version range, e.g. "[1.0.0]" or "[1.0.0,2.0.0)".',
+                )
+            )
+        elif not is_version_range(version_range):
+            # Parsed, not merely "not empty": restore reads the value as a range, and a consumer
+            # that hands "[0.2.0]" to a version parser throws. Saying so here is the difference
+            # between a diagnostic at authoring time and a crash in the IDE.
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_DEPENDENCY_VERSION_RANGE,
+                    f"{root}.dependencies['{package}']",
+                    f"'{version_range}' is not a NuGet version range: use an exact version "
+                    '"[1.0.0]", an interval "[1.0.0,2.0.0)", or a bare version "1.0.0" for that '
+                    "version or higher.",
+                )
+            )
+
+    seen: set[str] = set()
+
+    for index, dependency in enumerate(manifest.automation_dependencies):
+        path = f"{root}.automationDependencies[{index}]"
+        key = dependency.package_id.casefold()
+
+        well_formed = (
+            is_package_id(dependency.package_id)
+            and bool(dependency.version.strip())
+            and bool(dependency.runtime)
+            and key not in seen
+        )
+        seen.add(key)
+
+        if not well_formed:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_AUTOMATION_DEPENDENCY,
+                    path,
+                    "Each automation dependency needs a unique package id, a version range and the runtime it runs on.",
+                )
+            )
+        elif not is_version_range(dependency.version):
+            # The same gap `dependencies` had, and it bites harder here: the Orchestrator
+            # resolves this value as a range when a job is created (ADR-P007), so a value that
+            # is not one is not caught until a start is refused - long after authoring.
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_AUTOMATION_DEPENDENCY_VERSION_RANGE,
+                    f"{path}.version",
+                    f"'{dependency.version}' is not a NuGet version range: use an exact version "
+                    '"[1.0.0]", an interval "[1.0.0,2.0.0)", or a bare version "1.0.0" for that '
+                    "version or higher.",
+                )
+            )
+
+        if key == manifest.name.casefold():
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.SELF_DEPENDENCY, f"{path}.packageId", "A project cannot invoke itself as a dependency."
+                )
+            )
+
+
+def _validate_execution(execution: ExecutionSettings, path: str, diagnostics: list[Diagnostic]) -> None:
+    if execution.timeout is not None and _DURATION.match(execution.timeout) is None:
+        diagnostics.append(
+            Diagnostic.error(
+                Codes.INVALID_TIMEOUT,
+                f"{path}.timeout",
+                f"'{execution.timeout}' is not a positive ISO 8601 duration such as PT30M or PT2H.",
+            )
+        )
+
+    for index, capability in enumerate(execution.capabilities):
+        if not is_capability(capability):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_CAPABILITY,
+                    f"{path}.capabilities[{index}]",
+                    "Capabilities are lowercase tokens such as 'network' or 'filesystem'.",
+                )
+            )
+
+    if not execution.supports_attended and not execution.supports_unattended:
+        diagnostics.append(
+            Diagnostic.warning(
+                Codes.NO_RUN_MODE_ALLOWED,
+                path,
+                "The project allows neither attended nor unattended runs, so it can never be started.",
+            )
+        )