pytest-dag 3.0.0__py3-none-any.whl

pytest_dag/__init__.py

@@ -0,0 +1,3 @@
+"""pytest-dag: dependency-driven test ordering and skip propagation."""
+
+__version__ = "0.1.0"

pytest_dag/_build_config.py

@@ -0,0 +1,4 @@
+"""Build-injected official licensing configuration."""
+
+OFFICIAL_LICENSE_ENDPOINT = 'https://pytest-dag.slrsoft.ca'
+OFFICIAL_SIGNING_PUBLIC_KEY_PEM = '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAjY/lRvFw6SFsmerr8q6So+B8mWoMvHXjgYIzI7zeU7E=\n-----END PUBLIC KEY-----'

pytest_dag/_pytest_dag_core.py

@@ -0,0 +1,683 @@
+"""Pure-Python core for pytest-dag.
+
+This module is a drop-in replacement for the previous Rust extension module
+`pytest_dag._pytest_dag_core`.
+"""
+
+from __future__ import annotations
+
+import base64
+import importlib
+import ipaddress
+import json
+import os
+import secrets
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from ._build_config import OFFICIAL_LICENSE_ENDPOINT, OFFICIAL_SIGNING_PUBLIC_KEY_PEM
+from .graph import _detect_cycles, _load_yaml_deps
+
+PLAN_PROTOCOL_VERSION = "1"
+SIG_CLOCK_SKEW_SECS = 30
+HTTP_TIMEOUT_SECS = 5
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/133.0.0.0 Safari/537.36"
+)
+_OUTCOME_ORDER = {
+    "PASSED",
+    "FAILED",
+    "SKIPPED",
+    "DAG_SKIPPED",
+    "XFAILED",
+    "XPASSED",
+    "ERROR",
+}
+
+
+def _debug(msg: str) -> None:
+    if os.getenv("PYTEST_DAG_DEBUG") == "1":
+        print(f"pytest-dag [DEBUG] {msg}", file=os.sys.stderr)
+
+
+def _license_error(message: str) -> RuntimeError:
+    return RuntimeError(message)
+
+
+def _internal_error(message: str) -> RuntimeError:
+    return RuntimeError(message)
+
+
+def _env_true(name: str) -> bool:
+    return os.getenv(name, "").lower() in {"1", "true", "yes", "on"}
+
+
+def _normalize_endpoint(raw: str) -> str:
+    return raw.strip().rstrip("/")
+
+
+def _is_local_or_private_host(host: str) -> bool:
+    h = host.lower()
+    if h in {"localhost", "ip6-localhost"}:
+        return True
+    try:
+        ip = ipaddress.ip_address(h)
+    except ValueError:
+        return False
+    if isinstance(ip, ipaddress.IPv4Address):
+        return ip.is_loopback or ip.is_private or ip.is_link_local
+    return ip.is_loopback
+
+
+def _resolve_endpoint() -> str:
+    raw = OFFICIAL_LICENSE_ENDPOINT.strip()
+    if not raw or raw.startswith("__UNSET_"):
+        raise _internal_error(
+            "Official license endpoint is not configured in this build. "
+            "Set repository environment and regenerate build config."
+        )
+    endpoint = _normalize_endpoint(raw)
+    parsed = urlparse(endpoint)
+    if parsed.scheme != "https":
+        raise _license_error("Official license endpoint must use HTTPS")
+    if not parsed.hostname:
+        raise _license_error("Invalid default license endpoint URL: missing host")
+    return endpoint
+
+
+def _builtin_public_key() -> Ed25519PublicKey:
+    pem = OFFICIAL_SIGNING_PUBLIC_KEY_PEM.strip()
+    if not pem or pem.startswith("__UNSET_"):
+        raise _internal_error(
+            "Official signing public key is not configured in this build. "
+            "Set repository environment and regenerate build config."
+        )
+    try:
+        key = load_pem_public_key(pem.encode("utf-8"))
+    except Exception as exc:
+        raise _internal_error(f"Failed to load built-in public key: {exc}") from None
+    if not isinstance(key, Ed25519PublicKey):
+        raise _internal_error("Failed to load built-in public key: not Ed25519")
+    return key
+
+
+def _load_pem_public_key(pem: str) -> Ed25519PublicKey:
+    try:
+        key = load_pem_public_key(pem.encode("utf-8"))
+    except Exception as exc:
+        raise _internal_error(f"Failed to load custom public key: {exc}") from None
+    if not isinstance(key, Ed25519PublicKey):
+        raise _internal_error("Failed to load custom public key: not Ed25519")
+    return key
+
+
+def _verifying_key_for_endpoint(endpoint: str) -> Ed25519PublicKey:
+    _ = endpoint
+    return _builtin_public_key()
+
+
+def _generate_nonce() -> str:
+    return base64.urlsafe_b64encode(secrets.token_bytes(24)).rstrip(b"=").decode("ascii")
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    try:
+        return json.dumps(
+            {k: data[k] for k in sorted(data)},
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+    except Exception as exc:
+        raise _internal_error(f"canonical_json serialisation failed: {exc}") from None
+
+
+def _b64url_decode(value: str) -> bytes:
+    stripped = value.strip().rstrip("=")
+    padded = stripped + ("=" * ((4 - len(stripped) % 4) % 4))
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except Exception as exc:
+        raise _license_error(f"Base64 decode failed: {exc}") from None
+
+
+def _verify_ed25519(
+    verifying_key: Ed25519PublicKey, message: bytes, signature_bytes: bytes
+) -> None:
+    if len(signature_bytes) != 64:
+        raise _license_error("Invalid Ed25519 signature length")
+    try:
+        verifying_key.verify(signature_bytes, message)
+    except Exception:
+        raise _license_error("Ed25519 signature verification failed") from None
+
+
+def _user_agent() -> str:
+    return os.getenv("PYTEST_DAG_USER_AGENT", DEFAULT_USER_AGENT)
+
+
+def _http_json(
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    payload: dict[str, Any] | None = None,
+    timeout_secs: int = HTTP_TIMEOUT_SECS,
+) -> dict[str, Any]:
+    req_headers = {
+        "User-Agent": _user_agent(),
+        "Accept": "application/json, text/plain, */*",
+        "Accept-Language": "en-US,en;q=0.9",
+        "Cache-Control": "no-cache",
+        "Pragma": "no-cache",
+    }
+    req_headers.update(headers)
+
+    data: bytes | None = None
+    if payload is not None:
+        req_headers["Content-Type"] = "application/json"
+        data = json.dumps(payload).encode("utf-8")
+
+    req = urllib.request.Request(url=url, data=data, headers=req_headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_secs) as resp:
+            body = resp.read().decode("utf-8")
+    except urllib.error.URLError as exc:
+        if method == "GET":
+            raise _license_error(f"pytest-dag: License server unreachable. ({exc})")
+        raise _license_error(
+            f"pytest-dag: License server unreachable during validation. ({exc})"
+        )
+    except Exception as exc:
+        raise _license_error(f"HTTP {method} failed: {exc}") from None
+
+    _debug(f"HTTP {method} response body (first 300): {body[:300]}")
+    try:
+        value = json.loads(body)
+    except Exception as exc:
+        raise _license_error(f"HTTP {method} JSON parse failed: {exc}") from None
+    if not isinstance(value, dict):
+        raise _license_error("License response is not a JSON object")
+    return value
+
+
+def _required_str(data: dict[str, Any], key: str) -> str:
+    v = data.get(key)
+    if isinstance(v, str) and v:
+        return v
+    raise _license_error(f"Missing or invalid signed field: {key}")
+
+
+def _required_i64(data: dict[str, Any], key: str) -> int:
+    v = data.get(key)
+    if isinstance(v, bool):
+        raise _license_error(f"Missing or invalid signed field: {key}")
+    if isinstance(v, int):
+        return v
+    raise _license_error(f"Missing or invalid signed field: {key}")
+
+
+def _build_signed_payload(ctx: str, data: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ctx": ctx,
+        "sig_v": _required_i64(data, "sig_v"),
+        "sig_alg": _required_str(data, "sig_alg"),
+        "sig_kid": _required_str(data, "sig_kid"),
+        "sig_ts": _required_i64(data, "sig_ts"),
+        "sig_exp": _required_i64(data, "sig_exp"),
+        "sig_nonce": _required_str(data, "sig_nonce"),
+    }
+    if ctx == "feature-flag":
+        value = data.get("paywall_enabled")
+        if not isinstance(value, bool):
+            raise _license_error("Missing or invalid signed field: paywall_enabled")
+        payload["paywall_enabled"] = value
+    elif ctx == "validate":
+        value = data.get("valid")
+        if not isinstance(value, bool):
+            raise _license_error("Missing or invalid signed field: valid")
+        payload["valid"] = value
+        payload["reason"] = data.get("reason")
+        payload["expiry"] = data.get("expiry")
+        payload["user_count"] = data.get("user_count")
+        payload["license_type"] = data.get("license_type")
+    elif ctx == "plan-start":
+        payload["plan_session_id"] = _required_str(data, "plan_session_id")
+        order = data.get("execution_order")
+        if not isinstance(order, list) or not all(isinstance(v, str) for v in order):
+            raise _license_error("Missing or invalid signed field: execution_order")
+        payload["execution_order"] = order
+        payload["protocol_version"] = _required_str(data, "protocol_version")
+        payload["server_version"] = _required_str(data, "server_version")
+    else:
+        raise _internal_error(f"Unknown signature context: {ctx}")
+    return payload
+
+
+def _now_unix() -> int:
+    import time
+
+    return int(time.time())
+
+
+def _verify_signed_response(
+    ctx: str, data: dict[str, Any], expected_nonce: str, endpoint: str
+) -> None:
+    sig = _required_str(data, "sig")
+    sig_alg = _required_str(data, "sig_alg")
+    sig_v = _required_i64(data, "sig_v")
+    sig_nonce = _required_str(data, "sig_nonce")
+    sig_ts = _required_i64(data, "sig_ts")
+    sig_exp = _required_i64(data, "sig_exp")
+
+    if sig_alg != "Ed25519":
+        raise _license_error("Unsupported license response signature algorithm")
+    if sig_v != 1:
+        raise _license_error("Unsupported license response signature version")
+    if sig_nonce != expected_nonce:
+        raise _license_error("License response nonce mismatch")
+
+    now = _now_unix()
+    if sig_ts > now + SIG_CLOCK_SKEW_SECS:
+        raise _license_error("License response signature timestamp is in the future")
+    if sig_exp < now - SIG_CLOCK_SKEW_SECS:
+        raise _license_error("License response signature has expired")
+
+    payload = _build_signed_payload(ctx, data)
+    message = _canonical_json(payload)
+    signature = _b64url_decode(sig)
+    key = _verifying_key_for_endpoint(endpoint)
+    _verify_ed25519(key, message, signature)
+
+    _debug(
+        f"{ctx} response signature verified "
+        f"(kid={data.get('sig_kid', '?')}, exp={sig_exp})"
+    )
+
+
+@dataclass
+class DagSession:
+    """Session object compatible with the old Rust DagSession surface."""
+
+    _token: bytes
+    license_checked: bool
+    paywall_was_active: bool
+    deps: dict[str, set[str]] = field(default_factory=dict)
+    reverse_deps: dict[str, set[str]] = field(default_factory=dict)
+    results: dict[str, str] = field(default_factory=dict)
+    ordered: list[str] = field(default_factory=list)
+    license_key: str | None = None
+    endpoint: str = ""
+    plan_session_id: str | None = None
+
+    @property
+    def test_count(self) -> int:
+        return len(self.ordered)
+
+    def __repr__(self) -> str:
+        return (
+            f"<DagSession license_checked={self.license_checked} "
+            f"paywall={self.paywall_was_active} tests={len(self.ordered)}>"
+        )
+
+    def add_dependency(self, dependent: str, dependency: str) -> None:
+        self.deps.setdefault(dependent, set()).add(dependency)
+        self.reverse_deps.setdefault(dependency, set()).add(dependent)
+        self.deps.setdefault(dependency, set())
+        self.reverse_deps.setdefault(dependent, set())
+
+    def blocking_deps(self, nodeid: str, block_on_str: str) -> list[str]:
+        block_on = {s.strip().upper() for s in block_on_str.split(",")}
+        blocked: list[str] = []
+        for dep in self.deps.get(nodeid, set()):
+            outcome = self.results.get(dep)
+            if outcome is None:
+                continue
+            if outcome == "DAG_SKIPPED" or outcome in block_on:
+                blocked.append(dep)
+        return blocked
+
+    def record(self, nodeid: str, outcome: str, overwrite: bool) -> None:
+        value = outcome if outcome in _OUTCOME_ORDER else "FAILED"
+        if overwrite or nodeid not in self.results:
+            self.results[nodeid] = value
+
+
+def _enforce_license(license_key: str | None) -> bool:
+    endpoint = _resolve_endpoint()
+    _debug(f"license endpoint = {endpoint}")
+
+    ff_nonce = _generate_nonce()
+    ff_url = f"{endpoint}/api/pytest-dag/v1/feature-flag"
+    _debug(f"GET {ff_url}")
+    flag = _http_json("GET", ff_url, {"X-Pytest-Dag-Nonce": ff_nonce})
+    try:
+        _verify_signed_response("feature-flag", flag, ff_nonce, endpoint)
+    except RuntimeError as exc:
+        raise _license_error(
+            f"pytest-dag: License server returned an invalid response from {ff_url}.\n"
+            "This usually means the endpoint is not a pytest-dag license server.\n"
+            f"Detail: {exc}\n"
+            "Hint: verify your backend deployment and build-time endpoint configuration.\n\n"
+            "Purchase at:\n"
+            "  https://pytest-dag.slrsoft.ca/licenses/purchase\n"
+            "Support: support@slrsoft.ca"
+        ) from None
+
+    paywall_enabled = bool(flag.get("paywall_enabled", False))
+    _debug(f"paywall_enabled={paywall_enabled}")
+    if not paywall_enabled:
+        _debug("paywall_enabled=false -> no license required, proceeding")
+        return False
+
+    _debug("paywall_enabled=true -> license key required")
+    if license_key is None:
+        raise _license_error(
+            "pytest-dag: License key not provided.\n"
+            "Set PYTEST_DAG_LICENSE_KEY=pd-XXXX-XXXX-XXXX-XXXX or use\n"
+            "--pytest-dag-license-key / --pytest-dag-license-key-file\n\n"
+            "Purchase at:\n"
+            "  https://pytest-dag.slrsoft.ca/licenses/purchase\n"
+            "Support: support@slrsoft.ca"
+        )
+
+    val_nonce = _generate_nonce()
+    val_url = f"{endpoint}/api/pytest-dag/v1/validate"
+    _debug(f"POST {val_url} (key={license_key[:8]}...)")
+    result = _http_json(
+        "POST",
+        val_url,
+        {"X-Pytest-Dag-Nonce": val_nonce},
+        {"license_key": license_key},
+    )
+    try:
+        _verify_signed_response("validate", result, val_nonce, endpoint)
+    except RuntimeError as exc:
+        raise _license_error(
+            "pytest-dag: License server returned an invalid validation response from "
+            f"{val_url}.\n"
+            f"Detail: {exc}\n\n"
+            "Hint: verify the deployed license service is returning Ed25519-signed "
+            "responses for /api/pytest-dag/v1/validate.\n\n"
+            "Purchase at:\n"
+            "  https://pytest-dag.slrsoft.ca/licenses/purchase\n"
+            "Support: support@slrsoft.ca"
+        ) from None
+
+    valid = bool(result.get("valid", False))
+    if not valid:
+        reason = result.get("reason") or "unknown error"
+        expiry = result.get("expiry") or ""
+        msg = f"License validation failed.\n  Reason: {reason}"
+        if expiry:
+            msg += f"\n  Expiry: {expiry}"
+        msg += "\n\nRenew at: https://pytest-dag.slrsoft.ca/licenses/purchase"
+        raise _license_error(msg)
+
+    _debug("license valid -> proceeding")
+    return True
+
+
+def _load_local_test_mode_adapter():
+    module_name = "test_support.pytest_dag_local_test_mode"
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:
+        raise _internal_error(
+            "PYTEST_DAG_TEST_MODE is only supported for local test runs with a local "
+            "test adapter module present. This build/runtime does not provide "
+            "'test_support.pytest_dag_local_test_mode'. Disable PYTEST_DAG_TEST_MODE."
+        ) from exc
+
+    create_session = getattr(module, "create_dag_session", None)
+    if not callable(create_session):
+        raise _internal_error(
+            "Invalid local test adapter: expected callable "
+            "test_support.pytest_dag_local_test_mode.create_dag_session(...)"
+        )
+    return create_session
+
+
+def enforce_and_init(license_key: str | None = None) -> DagSession:
+    token = secrets.token_bytes(32)
+    if os.getenv("PYTEST_DAG_TEST_MODE") == "1":
+        create_session = _load_local_test_mode_adapter()
+        return create_session(
+            token=token,
+            license_key=license_key,
+            session_cls=DagSession,
+            enforce_license=_enforce_license,
+            resolve_endpoint=_resolve_endpoint,
+        )
+    paywall_active = _enforce_license(license_key)
+    return DagSession(
+        token,
+        license_checked=True,
+        paywall_was_active=paywall_active,
+        license_key=license_key,
+        endpoint=_resolve_endpoint(),
+    )
+
+
+def _start_remote_plan(session: DagSession, items: list[dict[str, Any]]) -> list[str]:
+    nonce = _generate_nonce()
+    nodes = [item["nodeid"] for item in items]
+    collected = set(nodes)
+    deps: dict[str, list[str]] = {}
+    for node in nodes:
+        deps[node] = sorted(d for d in session.deps.get(node, set()) if d in collected)
+
+    payload = {
+        "protocol_version": PLAN_PROTOCOL_VERSION,
+        "client_version": get_version(),
+        "license_key": session.license_key,
+        "nodes": nodes,
+        "deps": deps,
+    }
+    url = f"{session.endpoint}/api/pytest-dag/v1/plan/start"
+    result = _http_json("POST", url, {"X-Pytest-Dag-Nonce": nonce}, payload)
+    _verify_signed_response("plan-start", result, nonce, session.endpoint)
+    session.plan_session_id = _required_str(result, "plan_session_id")
+
+    order = result.get("execution_order")
+    if not isinstance(order, list) or not all(isinstance(v, str) for v in order):
+        raise _license_error("Invalid execution_order in plan/start response")
+    if set(order) != set(nodes):
+        raise _license_error("plan/start execution_order does not match collected tests")
+
+    protocol = _required_str(result, "protocol_version")
+    if protocol != PLAN_PROTOCOL_VERSION:
+        raise _license_error(
+            f"Protocol mismatch: server={protocol}, client={PLAN_PROTOCOL_VERSION}"
+        )
+    return order
+
+
+def _report_remote_outcome(session: DagSession, nodeid: str, outcome: str) -> None:
+    if not session.plan_session_id:
+        return
+    url = f"{session.endpoint}/api/pytest-dag/v1/plan/report"
+    _http_json(
+        "POST",
+        url,
+        {},
+        {
+            "plan_session_id": session.plan_session_id,
+            "node_id": nodeid,
+            "outcome": outcome,
+        },
+    )
+
+
+def finalize_session(session: DagSession) -> None:
+    if not session.plan_session_id:
+        return
+    url = f"{session.endpoint}/api/pytest-dag/v1/plan/finish"
+    try:
+        _http_json(
+            "POST",
+            url,
+            {},
+            {"plan_session_id": session.plan_session_id},
+        )
+    finally:
+        session.plan_session_id = None
+
+
+def build_dag(
+    session: DagSession,
+    items: list[dict[str, Any]],
+    dag_file: str | None = None,
+    rootdir: str = ".",
+    strict: bool = True,
+) -> None:
+    nodeid_map = {item["nodeid"]: item["nodeid"] for item in items}
+    short_name_map: dict[tuple[str, str], list[str]] = {}
+    for item in items:
+        nodeid = item["nodeid"]
+        module = nodeid.split("::")[0]
+        short = nodeid.split("::")[-1]
+        short_name_map.setdefault((module, short), []).append(nodeid)
+
+    def _resolve(dep_str: str, context_nodeid: str) -> str | None:
+        if "::" in dep_str:
+            return nodeid_map.get(dep_str)
+        module = context_nodeid.split("::")[0]
+        matches = short_name_map.get((module, dep_str), [])
+        if len(matches) == 1:
+            return matches[0]
+        return None
+
+    errors: list[str] = []
+
+    def _resolve_add(dependent: str, dep_str: str, context_nodeid: str) -> None:
+        resolved = _resolve(dep_str, context_nodeid)
+        if resolved is not None:
+            session.add_dependency(dependent, resolved)
+            return
+        msg = (
+            f"pytest-dag: dependency not found: {dep_str!r} "
+            f"(required by {dependent!r})"
+        )
+        if strict:
+            errors.append(msg)
+        else:
+            virtual = f"<missing:{dep_str}>"
+            session.results[virtual] = "FAILED"
+            session.add_dependency(dependent, virtual)
+
+    for item in items:
+        for dep_str in list(item.get("raw_deps", []) or []):
+            _resolve_add(item["nodeid"], dep_str, item["nodeid"])
+
+    if dag_file:
+        yaml_deps = _load_yaml_deps(dag_file, Path(rootdir))
+        first_nodeid = items[0]["nodeid"] if items else ""
+        for dependent, dep_list in yaml_deps.items():
+            context = dependent if dependent in nodeid_map else first_nodeid
+            for dep_str in dep_list:
+                _resolve_add(dependent, dep_str, context)
+
+    if errors:
+        raise _license_error("\n".join(errors))
+
+    try:
+        _detect_cycles(_StateView(session))
+    except Exception as exc:
+        raise _license_error(str(exc)) from None
+
+
+def topo_sort(session: DagSession, items: list[dict[str, Any]]) -> list[str]:
+    if not items:
+        return []
+    if session.paywall_was_active:
+        return _start_remote_plan(session, items)
+
+    original_order = {item["nodeid"]: idx for idx, item in enumerate(items)}
+    collected = {item["nodeid"] for item in items}
+    in_degree = {nid: 0 for nid in collected}
+    adj: dict[str, list[str]] = {nid: [] for nid in collected}
+
+    for item in items:
+        nid = item["nodeid"]
+        for dep in session.deps.get(nid, set()):
+            if dep in collected:
+                in_degree[nid] += 1
+                adj[dep].append(nid)
+
+    import heapq
+
+    ready: list[tuple[int, str]] = []
+    for nid, deg in in_degree.items():
+        if deg == 0:
+            heapq.heappush(ready, (original_order.get(nid, 10**9), nid))
+
+    result: list[str] = []
+    while ready:
+        _, nid = heapq.heappop(ready)
+        result.append(nid)
+        for dependent in adj.get(nid, []):
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                heapq.heappush(
+                    ready, (original_order.get(dependent, 10**9), dependent)
+                )
+
+    if len(result) != len(items):
+        raise _license_error(
+            "pytest-dag: topological sort failed – remaining cycle in graph"
+        )
+    return result
+
+
+def check_block(session: DagSession, nodeid: str, block_on: str) -> tuple[bool, str]:
+    blocked = session.blocking_deps(nodeid, block_on)
+    if not blocked:
+        return False, ""
+    reasons = [f"{dep} ({session.results.get(dep, 'FAILED')})" for dep in blocked]
+    return True, f"pytest-dag: blocked by {', '.join(reasons)}"
+
+
+def record_outcome(
+    session: DagSession, nodeid: str, outcome: str, overwrite: bool = False
+) -> None:
+    session.record(nodeid, outcome, overwrite)
+    try:
+        _report_remote_outcome(session, nodeid, outcome)
+    except RuntimeError as exc:
+        _debug(f"report outcome failed: {exc}")
+
+
+def get_ordered(session: DagSession) -> list[str]:
+    return list(session.ordered)
+
+
+def set_ordered(session: DagSession, ordered: list[str]) -> None:
+    session.ordered = list(ordered)
+
+
+def get_deps(session: DagSession) -> dict[str, list[str]]:
+    return {k: list(vs) for k, vs in session.deps.items()}
+
+
+def get_outcome(session: DagSession, nodeid: str) -> str | None:
+    return session.results.get(nodeid)
+
+
+def get_version() -> str:
+    return "2.0.7"
+
+
+class _StateView:
+    """Adapter to reuse existing cycle detection from graph.py."""
+
+    def __init__(self, session: DagSession) -> None:
+        self.deps = session.deps
+        self.reverse_deps = session.reverse_deps