sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/workflow_async.py

@@ -0,0 +1,197 @@
+"""Optional asynchronous workflow contracts, without execution or polling.
+
+Backends own native status, authority, and record verification. A submission is
+coordination work, not a Run. A pending grading pass is not a Report. Native
+references remain opaque and are excluded from public snapshots.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, TYPE_CHECKING, runtime_checkable
+
+if TYPE_CHECKING:
+    from .progress import ProgressView
+
+from .workflow_contracts import (
+    AdmissionBinding, PlanBinding, ReferenceBinding, ResolvedBinding,
+    WorkflowContractError, _object, _optional_text, _text, _thaw,
+)
+
+
+@dataclass(frozen=True)
+class SubmissionIntent:
+    """Retain the recovery key and exact declared request before its first POST.
+
+    The key identifies one operation. Deliberate new runs need new keys. This
+    metadata does not authenticate source or grant submission permission.
+    """
+
+    idempotency_key: str
+    request_identity: Mapping[str, Any]
+
+    def __post_init__(self) -> None:
+        _text(self.idempotency_key, "idempotency_key")
+        object.__setattr__(self, "request_identity", _object(self.request_identity, "request_identity"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"idempotency_key": self.idempotency_key,
+                "request_identity": _thaw(self.request_identity)}
+
+
+class SubmissionError(WorkflowContractError):
+    """An unsuccessful submission attempt with its original recovery intent."""
+
+    def __init__(self, message: str, *, intent: SubmissionIntent, code: str = "submission_failed") -> None:
+        if not isinstance(intent, SubmissionIntent):
+            raise WorkflowContractError("submission error requires a SubmissionIntent")
+        _text(code, "code")
+        self.intent, self.code = intent, code
+        super().__init__(message)
+
+
+def _state(complete: bool, failed: bool, error_code: str | None, reason: str | None) -> None:
+    if type(complete) is not bool or type(failed) is not bool or (complete and failed):
+        raise WorkflowContractError("complete and failed must be separate boolean states")
+    _optional_text(error_code, "error_code")
+    _optional_text(reason, "reason")
+
+
+@dataclass(frozen=True)
+class SubmissionSnapshot:
+    """Verified native coordination metadata, separate from captured records.
+
+    A reserved run/grading ID may appear before its evidence is ready. Backends
+    expose native_run/native_grading only when those references can be consumed
+    as a Run/Report. Complete execution must provide a native run reference.
+    """
+
+    submission_id: str
+    status: str
+    idempotency_key: str
+    request_identity: Mapping[str, Any]
+    native_ref: Any = field(repr=False, compare=False)
+    run_id: str | None = None
+    grading_id: str | None = None
+    native_run: Any = field(default=None, repr=False, compare=False)
+    native_grading: Any = field(default=None, repr=False, compare=False)
+    complete: bool = False
+    failed: bool = False
+    error_code: str | None = None
+    reason: str | None = None
+    trust_tier: str = "unverified"
+
+    def __post_init__(self) -> None:
+        for name in ("submission_id", "status", "idempotency_key", "trust_tier"):
+            _text(getattr(self, name), name)
+        for name in ("run_id", "grading_id"):
+            _optional_text(getattr(self, name), name)
+        _state(self.complete, self.failed, self.error_code, self.reason)
+        if self.native_run is not None and self.run_id is None:
+            raise WorkflowContractError("native run reference requires its run identity")
+        if self.native_grading is not None and self.grading_id is None:
+            raise WorkflowContractError("native grading reference requires its grading identity")
+        if self.complete and self.native_run is None:
+            raise WorkflowContractError("complete submission must provide a native run reference")
+        object.__setattr__(self, "request_identity", _object(self.request_identity, "request_identity"))
+
+    @property
+    def terminal(self) -> bool:
+        return self.complete or self.failed
+
+    @property
+    def progress(self) -> ProgressView:
+        from .progress import _progress
+        return _progress('submission', self.status,
+                         {'submission_id': self.submission_id, 'idempotency_key': self.idempotency_key,
+                          'run_id': self.run_id, 'grading_id': self.grading_id}, terminal=self.terminal,
+                         complete=self.complete, failed=self.failed)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"submission_id": self.submission_id, "status": self.status,
+                "idempotency_key": self.idempotency_key, "request_identity": _thaw(self.request_identity),
+                "run_id": self.run_id, "grading_id": self.grading_id,
+                "complete": self.complete, "failed": self.failed, "error_code": self.error_code,
+                "reason": self.reason, "trust_tier": self.trust_tier}
+
+
+@dataclass(frozen=True)
+class GradingSnapshot:
+    """Pending native grading handle and optional completed report reference."""
+
+    reference: ReferenceBinding
+    idempotency_key: str
+    request_identity: Mapping[str, Any]
+    native_ref: Any = field(repr=False, compare=False)
+    completed_ref: Any = field(default=None, repr=False, compare=False)
+    complete: bool = False
+    failed: bool = False
+    error_code: str | None = None
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.reference, ReferenceBinding) or self.reference.record_id is None:
+            raise WorkflowContractError("grading snapshot requires its native ReferenceBinding")
+        _text(self.idempotency_key, "idempotency_key")
+        _state(self.complete, self.failed, self.error_code, self.reason)
+        if self.complete != (self.completed_ref is not None):
+            raise WorkflowContractError("only complete grading can expose a completed reference")
+        object.__setattr__(self, "request_identity", _object(self.request_identity, "request_identity"))
+
+    @property
+    def grading_id(self) -> str:
+        assert self.reference.record_id is not None
+        return self.reference.record_id
+
+    @property
+    def run_id(self) -> str | None:
+        return self.reference.run_id
+
+    @property
+    def status(self) -> str:
+        return self.reference.status
+
+    @property
+    def trust_tier(self) -> str:
+        return self.reference.trust_tier
+
+    @property
+    def terminal(self) -> bool:
+        return self.complete or self.failed
+
+    @property
+    def progress(self) -> ProgressView:
+        from .progress import _progress
+        return _progress('grading', self.status,
+                         {'grading_id': self.grading_id, 'run_id': self.run_id,
+                          'idempotency_key': self.idempotency_key}, terminal=self.terminal,
+                         complete=self.complete, failed=self.failed)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"grading_id": self.grading_id, "run_id": self.run_id,
+                "status": self.status, "trust_tier": self.trust_tier,
+                "idempotency_key": self.idempotency_key, "request_identity": _thaw(self.request_identity),
+                "complete": self.complete, "failed": self.failed,
+                "error_code": self.error_code, "reason": self.reason}
+
+
+@runtime_checkable
+class AsyncWorkflowBackend(Protocol):
+    """Additive backend capability; old WorkflowBackend remains unchanged.
+
+    Submission and grading POSTs receive a key retained before the attempt.
+    Snapshot/refresh calls must never submit, execute, or start another grading
+    pass. Backends verify native record linkage before exposing ready refs.
+    """
+
+    def submit(self, plan: PlanBinding, resolved: ResolvedBinding,
+               admission: AdmissionBinding, idempotency_key: str) -> Any: ...
+
+    def submission_snapshot(self, native_ref: Any) -> SubmissionSnapshot: ...
+
+    def refresh_submission(self, native_ref: Any) -> Any: ...
+
+    def start_grading(self, native_run: Any, idempotency_key: str) -> Any: ...
+
+    def grading_snapshot(self, native_ref: Any) -> GradingSnapshot: ...
+
+    def refresh_grading(self, native_ref: Any) -> Any: ...