velophex 0.2.0__py3-none-any.whl

velophex/contracts/runtimes.py

@@ -0,0 +1,226 @@
+"""Runtime kinds and the runner's shared vocabulary (phases, levels, fault kinds).
+
+Mirrors ``VeloPhex.Platform.Contracts.Runtimes`` and ``…Contracts.Runner.RunnerVocabulary``.
+A runtime kind stays an open token: the platform recognises a runtime by registering an
+adapter for its kind, never by switching over a closed enum (ADR-P001), so this module
+offers constants and a validator rather than an ``Enum``.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from velophex.contracts.validation import is_runtime_kind
+
+__all__ = [
+    "MAXIMUM_RUNTIME_KIND_LENGTH",
+    "AttemptOutcomes",
+    "ControlSignals",
+    "ExecutionPhases",
+    "FaultCodes",
+    "FaultKinds",
+    "LogLevels",
+    "LogStages",
+    "PhaseStatuses",
+    "RuntimeKind",
+    "RuntimeStatuses",
+    "SignalReasons",
+    "parse_runtime_kind",
+]
+
+MAXIMUM_RUNTIME_KIND_LENGTH: Final = 32
+
+
+class RuntimeKind:
+    """The runtime kinds the platform ships with."""
+
+    VELOPHEX_WORKFLOW: Final = "velophex-workflow"
+    PYTHON: Final = "python"
+
+
+def parse_runtime_kind(value: str | None) -> str:
+    """Return *value* if it is a well-formed runtime kind, else raise :class:`ValueError`."""
+    if not is_runtime_kind(value):
+        raise ValueError(
+            f"{value!r} is not a runtime kind. Use a lowercase token such as 'velophex-workflow' or 'python'."
+        )
+
+    assert value is not None
+    return value
+
+
+class RuntimeStatuses:
+    """Health of a runtime a runner reports it has installed.
+
+    Two values, not three. A runtime the machine does not have is *absent* from the report, not
+    "Unavailable": the Orchestrator places a job only on a runner that reports the runtimes the
+    job needs, so a missing entry already says everything a third status could. ``IsKnown`` on the
+    .NET side rejects anything else, which means a reporter that invented one would be refused.
+    """
+
+    AVAILABLE: Final = "Available"
+    DEGRADED: Final = "Degraded"
+
+
+class ExecutionPhases:
+    """Runtime-neutral log phases. Runtime-specific detail belongs in ``subPhase``."""
+
+    DOWNLOAD: Final = "Download"
+    VERIFY: Final = "Verify"
+    EXTRACT: Final = "Extract"
+    ENVIRONMENT_PREPARE: Final = "EnvironmentPrepare"
+    DEPENDENCY_RESTORE: Final = "DependencyRestore"
+    EXECUTION: Final = "Execution"
+    CLEANUP: Final = "Cleanup"
+
+    ALL: Final = (DOWNLOAD, VERIFY, EXTRACT, ENVIRONMENT_PREPARE, DEPENDENCY_RESTORE, EXECUTION, CLEANUP)
+
+
+class LogStages:
+    """The two stages a log line belongs to; derived from the phase when it is omitted."""
+
+    PREPARATION: Final = "Preparation"
+    EXECUTION: Final = "Execution"
+
+
+class PhaseStatuses:
+    """Status of a preparation phase."""
+
+    STARTED: Final = "Started"
+    SUCCEEDED: Final = "Succeeded"
+    FAILED: Final = "Failed"
+    SKIPPED: Final = "Skipped"
+
+
+class LogLevels:
+    """Log levels of the runner protocol; the worker maps :mod:`logging` levels onto these."""
+
+    TRACE: Final = "Trace"
+    DEBUG: Final = "Debug"
+    INFORMATION: Final = "Information"
+    WARNING: Final = "Warning"
+    ERROR: Final = "Error"
+    CRITICAL: Final = "Critical"
+
+
+class FaultKinds:
+    """How an attempt failed. The kind drives retries."""
+
+    BUSINESS: Final = "Business"
+    APPLICATION: Final = "Application"
+    TIMEOUT: Final = "Timeout"
+    INFRASTRUCTURE: Final = "Infrastructure"
+
+
+class FaultCodes:
+    """Well-known fault codes shared by the runner and the Orchestrator."""
+
+    RUNTIME_NOT_INSTALLED: Final = "RUNTIME_NOT_INSTALLED"
+    RUNTIME_DEGRADED: Final = "RUNTIME_DEGRADED"
+    PACKAGE_VERIFICATION_FAILED: Final = "PACKAGE_VERIFICATION_FAILED"
+    ENVIRONMENT_PREPARATION_FAILED: Final = "ENVIRONMENT_PREPARATION_FAILED"
+    EXECUTOR_START_FAILED: Final = "EXECUTOR_START_FAILED"
+    EXECUTOR_CRASHED: Final = "EXECUTOR_CRASHED"
+    EXECUTOR_PROTOCOL_VIOLATION: Final = "EXECUTOR_PROTOCOL_VIOLATION"
+
+    #: The start inputs do not fit the handler's signature. Mirrors the workflow executor.
+    INVALID_INPUT: Final = "INVALID_INPUT"
+
+    #: project.json, the entry point or the handler module could not be loaded.
+    INVALID_PACKAGE: Final = "INVALID_PACKAGE"
+
+    #: The handler raised something that is not a BusinessError.
+    UNHANDLED_EXCEPTION: Final = "UNHANDLED_EXCEPTION"
+
+    #: The handler's outputs do not fit in one executor frame (16 MiB by default). Application,
+    #: not retryable.
+    RESULT_TOO_LARGE: Final = "RESULT_TOO_LARGE"
+
+    #: The handler returned a value with no JSON form (a ``datetime``, a set, NaN). Application,
+    #: not retryable.
+    RESULT_NOT_SERIALIZABLE: Final = "RESULT_NOT_SERIALIZABLE"
+
+    #: A workflow suspended itself and no host is holding its instance. A Python worker never
+    #: reports this, but the table is the platform's, so a Python tool that reads a fault off the
+    #: Orchestrator must be able to name it.
+    WORKFLOW_SUSPENDED: Final = "WORKFLOW_SUSPENDED"
+
+    #: The executor or the robot was lost after the automation may have acted (crash, lost
+    #: lease, forced timeout). Never retried; an operator reconciles. A Python worker never
+    #: reports it, but a tool reading a fault off the Orchestrator must be able to name it.
+    OUTCOME_UNKNOWN: Final = "VXR-OUTCOME-UNKNOWN"
+
+    #: An unattended job was refused before launch because no run-as account is configured.
+    RUNAS_REQUIRED: Final = "VXR-RUNAS-REQUIRED"
+
+    #: A workflow package was built under a looser expression policy than the tenant's (engine
+    #: ADR 0036). A Python worker never reports it; a tool reading faults must be able to name it.
+    EXPRESSION_POLICY_LOOSER: Final = "EXPRESSION_POLICY_LOOSER"
+
+    # Contracts 0.8.37, agents: the gateway's own refusal codes, carried unchanged into the fault.
+
+    #: The workspace's AI budget is spent. Application, not retryable.
+    AI_BUDGET_EXHAUSTED: Final = "ai_budget_exhausted"
+
+    #: The workspace's AI policy refused the call. Application, not retryable.
+    AI_POLICY_DENIED: Final = "ai_policy_denied"
+
+    #: The model provider failed after the gateway's retries. Infrastructure.
+    AI_PROVIDER_UNAVAILABLE: Final = "ai_provider_unavailable"
+
+    #: The model call is invalid, e.g. an unknown binding. Application, not retryable.
+    AI_REQUEST_INVALID: Final = "ai_request_invalid"
+
+    #: The answer did not satisfy the output schema after one repair turn. Application, not retryable.
+    AGENT_OUTPUT_INVALID: Final = "agent_output_invalid"
+
+    #: The run reached a guardrail (steps, tokens, timeout). Application, not retryable.
+    AGENT_LIMIT_EXCEEDED: Final = "agent_limit_exceeded"
+
+    #: A tool call ended without a known outcome; reconciled by a person, never replayed.
+    TOOL_OUTCOME_UNKNOWN: Final = "tool_outcome_unknown"
+
+
+class FaultRemediations:
+    """Where the remediation of every ``VXR-*`` fault code is documented (contracts 0.8.9).
+
+    The remediation table itself lives in the .NET contract; Python only needs the page.
+    """
+
+    REFERENCE_PAGE: Final = "VeloPhex.Robot/docs/fault-codes.md"
+
+
+class AttemptOutcomes:
+    """Terminal outcome of an attempt or a sub-invocation."""
+
+    SUCCEEDED: Final = "Succeeded"
+    FAILED: Final = "Failed"
+    CANCELED: Final = "Canceled"
+
+    #: The run waits and was checkpointed; the job resumes on a later attempt (durable execution,
+    #: ADR-P015, Contracts 0.8.22). A Python automation never suspends; the value is mirrored so a
+    #: client reading an Orchestrator's attempts knows it.
+    SUSPENDED: Final = "Suspended"
+
+
+class ControlSignals:
+    """What the Orchestrator asks a running attempt to do."""
+
+    NONE: Final = "None"
+
+    #: Ask the automation to end gracefully.
+    STOP: Final = "Stop"
+
+    #: Terminate the automation immediately.
+    KILL: Final = "Kill"
+
+
+class SignalReasons:
+    """Why a stop was asked for."""
+
+    USER: Final = "User"
+    TIMEOUT: Final = "Timeout"
+
+    #: ``canceled.reason`` only: the workflow ended itself with Terminate Workflow (contracts
+    #: 0.8.11). The run is neither Succeeded nor Failed.
+    TERMINATED: Final = "Terminated"

velophex/contracts/signin.py

@@ -0,0 +1,53 @@
+"""The states a sign-in passes through, in every client that signs a person in.
+
+Mirrors ``VeloPhex.Platform.Contracts.Identity.SignInStates`` (design review 2026-09-23, D1,
+D2, D11). The copy table (``SignInCopy``) stays in the .NET contract for now: the CLI has no
+sign-in of its own yet, and when it gets one it prints these states through the same table
+rather than words of its own.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = ["SignInStates"]
+
+
+class SignInStates:
+    """The vocabulary, by value; ``test_vocabulary_mirror`` holds it to the C# source."""
+
+    SIGNED_OUT: Final = "SignedOut"
+    REQUESTING_CODE: Final = "RequestingCode"
+    CODE_SHOWN: Final = "CodeShown"
+    WAITING_FOR_APPROVAL: Final = "WaitingForApproval"
+    APPROVED_COMPLETING: Final = "ApprovedCompleting"
+    APPROVED: Final = "Approved"
+    EXPIRED: Final = "Expired"
+    DENIED: Final = "Denied"
+    NO_TENANT: Final = "NoTenant"
+    UNREACHABLE: Final = "Unreachable"
+    REFUSED: Final = "Refused"
+    SESSION_EXPIRED: Final = "SessionExpired"
+
+    ALL: Final = (
+        SIGNED_OUT,
+        REQUESTING_CODE,
+        CODE_SHOWN,
+        WAITING_FOR_APPROVAL,
+        APPROVED_COMPLETING,
+        APPROVED,
+        EXPIRED,
+        DENIED,
+        NO_TENANT,
+        UNREACHABLE,
+        REFUSED,
+        SESSION_EXPIRED,
+    )
+
+    #: States the flow cannot leave by itself: the person acts, or the client starts over.
+    TERMINAL: Final = (APPROVED, EXPIRED, DENIED, NO_TENANT, UNREACHABLE, REFUSED, SESSION_EXPIRED)
+
+    @classmethod
+    def is_known(cls, state: str | None) -> bool:
+        """Whether *state* is one of the contract's states (``SignInStates.IsKnown`` in .NET)."""
+        return state is not None and state in cls.ALL

velophex/contracts/validation.py

@@ -0,0 +1,158 @@
+"""Lexical rules shared with ``VeloPhex.Platform.Contracts.Validation.ContractPatterns``.
+
+The patterns are the ones in ``schemas/project.schema.json``; they are repeated here because
+a Python project is validated before it is packed, when no .NET tool is in reach.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+__all__ = [
+    "MAXIMUM_PACKAGE_ID_LENGTH",
+    "MAXIMUM_PATH_LENGTH",
+    "MAXIMUM_VERSION_RANGE_LENGTH",
+    "has_build_metadata",
+    "is_capability",
+    "is_entry_point_id",
+    "is_package_id",
+    "is_python_handler",
+    "is_runtime_kind",
+    "is_safe_relative_path",
+    "is_semantic_version",
+    "is_sha512_hex",
+    "is_version_range",
+]
+
+MAXIMUM_PACKAGE_ID_LENGTH: Final = 100
+MAXIMUM_PATH_LENGTH: Final = 260
+MAXIMUM_VERSION_RANGE_LENGTH: Final = 256
+
+_PACKAGE_ID = re.compile(r"^\w+([_.-]\w+)*$")
+# SemVer 2.0 without build metadata; byte for byte ContractPatterns.SemanticVersionPattern and
+# project.schema.json's $defs/semanticVersion.
+_SEMANTIC_VERSION = re.compile(
+    r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
+    r"(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)"
+    r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?$"
+)
+# The same with a mandatory build-metadata part: what used to be accepted and is now refused with
+# its own diagnostic (VPC1028), so the message can say why.
+_SEMANTIC_VERSION_WITH_BUILD_METADATA = re.compile(
+    r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
+    r"(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)"
+    r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
+    r"\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)$"
+)
+_ENTRY_POINT_ID = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]{0,63}$")
+_PYTHON_HANDLER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*$")
+_CAPABILITY = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
+_SHA512_HEX = re.compile(r"^[0-9a-f]{128}$")
+_RUNTIME_KIND = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+# [exact] | (lower?,upper?) | bare, where a version is 1-4 numeric parts with an optional SemVer
+# pre-release and build metadata, and a floating version ends in '*'. Byte for byte the expression
+# in ContractPatterns.VersionRangePattern and in project.schema.json's $defs/versionRange.
+_VERSION_RANGE = re.compile(
+    r"^\s*(?:\[\s*[0-9]+(?:\.[0-9]+){0,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?\s*\]"
+    r"|[\[(]\s*(?:[0-9]+(?:\.[0-9]+){0,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?"
+    r"|\*|[0-9]+(?:\.[0-9]+){0,2}\.\*|[0-9]+(?:\.[0-9]+){0,3}-[0-9A-Za-z.-]*\*)?\s*,\s*"
+    r"(?:[0-9]+(?:\.[0-9]+){0,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?)?\s*[\])]"
+    r"|[0-9]+(?:\.[0-9]+){0,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?"
+    r"|\*|[0-9]+(?:\.[0-9]+){0,2}\.\*|[0-9]+(?:\.[0-9]+){0,3}-[0-9A-Za-z.-]*\*)\s*$"
+)
+
+_FORBIDDEN_CHARACTERS: Final[frozenset[str]] = frozenset('<>"|?*')
+
+
+def is_package_id(value: str | None) -> bool:
+    """True for a NuGet-compatible package id, which is also the project name."""
+    return bool(value) and len(value or "") <= MAXIMUM_PACKAGE_ID_LENGTH and _PACKAGE_ID.match(value or "") is not None
+
+
+def is_semantic_version(value: str | None) -> bool:
+    """True for SemVer 2.0 without a leading ``v`` and without build metadata.
+
+    ``1.0.0`` and ``1.0.0-beta.1``, never ``1.0.0+build.7``: NuGet drops build metadata from a
+    package's identity, so a version carrying it would name one artefact in the manifest and
+    another on the feed (``ContractPatterns.IsSemanticVersion``; audit PRJ-01).
+    """
+    return bool(value) and len(value or "") <= 128 and _SEMANTIC_VERSION.match(value or "") is not None
+
+
+def has_build_metadata(value: str | None) -> bool:
+    """True for a SemVer 2.0 version that is valid but for its build metadata (``1.0.0+build.7``)."""
+    return (
+        bool(value) and len(value or "") <= 128 and _SEMANTIC_VERSION_WITH_BUILD_METADATA.match(value or "") is not None
+    )
+
+
+def is_entry_point_id(value: str | None) -> bool:
+    """True for an entry point id."""
+    return bool(value) and _ENTRY_POINT_ID.match(value or "") is not None
+
+
+def is_python_handler(value: str | None) -> bool:
+    """True for a ``module.path:function`` handler (ADR-P002, OD-11)."""
+    return bool(value) and len(value or "") <= 256 and _PYTHON_HANDLER.match(value or "") is not None
+
+
+def is_capability(value: str | None) -> bool:
+    """True for an execution capability token such as ``network``."""
+    return bool(value) and _CAPABILITY.match(value or "") is not None
+
+
+def is_sha512_hex(value: str | None) -> bool:
+    """True for a lower-case hex SHA-512."""
+    return value is not None and len(value) == 128 and _SHA512_HEX.match(value) is not None
+
+
+def is_version_range(value: str | None) -> bool:
+    """True for a NuGet version range, the value side of ``project.json`` -> ``dependencies``.
+
+    Three spellings: an exact version ``[1.0.0]``, an interval with either bound optional
+    (``[1.0.0,2.0.0)``, ``(,2.0.0]``, ``[1.0.0,)``) or a bare version ``1.0.0``, which NuGet reads
+    as "that version or higher". Floating versions (``*``, ``1.0.*``, ``1.0.0-*``) are accepted
+    where NuGet accepts them: the bare form and the lower bound, never the upper one.
+
+    Lexical only, like :func:`is_semantic_version`: the SDK must be able to validate a project
+    before it is packed, with no NuGet client anywhere in reach.
+    """
+    return (
+        bool(value)
+        and len(value or "") <= MAXIMUM_VERSION_RANGE_LENGTH
+        and _VERSION_RANGE.match(value or "") is not None
+    )
+
+
+def is_runtime_kind(value: str | None) -> bool:
+    """True for a runtime kind token such as ``python``."""
+    return bool(value) and len(value or "") <= 32 and _RUNTIME_KIND.match(value or "") is not None
+
+
+def is_safe_relative_path(value: str | None) -> bool:
+    """True for a relative path that cannot escape its root on any platform.
+
+    Forward slashes only, no rooted or drive paths, no empty, ``.`` or ``..`` segments, no
+    characters Windows forbids and no segment that ends in a dot or a space. These are exactly
+    the rules of ``ContractPatterns.IsSafeRelativePath``; the stricter archive rules (length,
+    reserved device names) belong to the package builder, which mirrors ``PackagePath``.
+    """
+    if not value or len(value) > MAXIMUM_PATH_LENGTH:
+        return False
+
+    if value.startswith("/") or "\\" in value or ":" in value:
+        return False
+
+    for segment in value.split("/"):
+        if not segment or segment in (".", ".."):
+            return False
+
+        if segment.endswith((" ", ".")):
+            return False
+
+        if any(character in _FORBIDDEN_CHARACTERS or ord(character) < 0x20 for character in segment):
+            return False
+
+    return True