bitexoft-verify 0.2.0__tar.gz → 0.2.1__tar.gz

{bitexoft_verify-0.2.0 → bitexoft_verify-0.2.1}/.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 
 # generated
 app/dist/
+app/shots/
 dist/
 build/
 app/src/content/catalog.json

{bitexoft_verify-0.2.0 → bitexoft_verify-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bitexoft-verify
-Version: 0.2.0
+Version: 0.2.1
 Summary: Verifica las entregas de los proyectos de Bitexoft: la misma herramienta en tu máquina y en CI.
 Author: Bitexoft
 License: Proprietary

{bitexoft_verify-0.2.0 → bitexoft_verify-0.2.1}/src/bitexoft_verify/__init__.py

@@ -1,3 +1,3 @@
 """bitexoft-verify: the platform's only definition of "correct"."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

bitexoft_verify-0.2.1/src/bitexoft_verify/checks/assertions.py

@@ -0,0 +1,129 @@
+"""One vocabulary for "this value is not what it should be" (ADR 0049; foundation 09, D5, F12).
+
+Every check that compares a value used to word its own failure, and no two worded it alike. An assertion here
+is a small function from a value to the list of things wrong with it; a check runs one against a value and the
+failures land in its `Problems`, each with a stable issue code and the values behind it (`expected`, `found`), so
+the platform writes the sentence in the learner's language and the terminal reads the same in English.
+
+    equal(expected)         the value is exactly this
+    contains(needle)        the text includes this
+    not_contains(needle)    the text does not include this
+    matches(pattern)        the text matches this regular expression (searched, not anchored)
+    all_of(a, b, ...)       every one holds, and each that does not is reported: not just the first
+    annotated(label, a)     says what was being looked at, in front of whatever `a` finds wrong
+
+    problems = Problems()
+    check_value(problems, annotated("verdict on the stranded frame", equal("BROKEN")), verdict)
+    if problems:
+        return problems.failing("furthest_policy", "The second policy notices a stranded player")
+
+An assertion never raises for a value it did not expect: a value of the wrong type simply does not satisfy it, and
+what the learner's code returned is described, not trusted.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ..report import Issue, Problems, issue
+
+SHOWN = 80  # characters of a found value in a sentence; a long one is cut, with a mark
+
+
+def _shown(value: Any) -> str:
+    text = repr(value) if not isinstance(value, str) else value
+    return text if len(text) <= SHOWN else text[: SHOWN - 1] + "…"
+
+
+@dataclass(frozen=True, slots=True)
+class Failure:
+    """One thing wrong: the English sentence for the terminal and the issue for the platform."""
+
+    text: str
+    issue: Issue
+
+    def with_context(self, context: str) -> Failure:
+        return Failure(f"{context}: {self.text}", Issue(self.issue.code, {**self.issue.params, "context": context}))
+
+
+Assertion = Callable[[Any], list[Failure]]
+
+
+def equal(expected: Any) -> Assertion:
+    """Exact, type included: `3` is not `3.0` and `1` is not `True`."""
+
+    def run(value: Any) -> list[Failure]:
+        if value == expected and type(value) is type(expected):
+            return []
+        return [
+            Failure(
+                f"expected {_shown(expected)} but found {_shown(value)}",
+                issue("assert.not_equal", expected=_shown(expected), found=_shown(value)),
+            )
+        ]
+
+    return run
+
+
+def contains(needle: str) -> Assertion:
+    def run(value: Any) -> list[Failure]:
+        if isinstance(value, str) and needle in value:
+            return []
+        return [
+            Failure(
+                f"expected to find {_shown(needle)} in {_shown(value)}",
+                issue("assert.missing", expected=_shown(needle), found=_shown(value)),
+            )
+        ]
+
+    return run
+
+
+def not_contains(needle: str) -> Assertion:
+    def run(value: Any) -> list[Failure]:
+        if not isinstance(value, str) or needle not in value:
+            return []
+        return [Failure(f"did not expect to find {_shown(needle)}", issue("assert.unexpected", found=_shown(needle)))]
+
+    return run
+
+
+def matches(pattern: str) -> Assertion:
+    compiled = re.compile(pattern)
+
+    def run(value: Any) -> list[Failure]:
+        if isinstance(value, str) and compiled.search(value):
+            return []
+        return [
+            Failure(
+                f"{_shown(value)} does not match {pattern}",
+                issue("assert.no_match", expected=pattern, found=_shown(value)),
+            )
+        ]
+
+    return run
+
+
+def all_of(*assertions: Assertion) -> Assertion:
+    def run(value: Any) -> list[Failure]:
+        return [failure for assertion in assertions for failure in assertion(value)]
+
+    return run
+
+
+def annotated(context: str, assertion: Assertion) -> Assertion:
+    def run(value: Any) -> list[Failure]:
+        return [failure.with_context(context) for failure in assertion(value)]
+
+    return run
+
+
+def check_value(problems: Problems, assertion: Assertion, value: Any) -> bool:
+    """Runs `assertion` on `value`, adds what is wrong to `problems`, and says whether the value held."""
+    failures = assertion(value)
+    for failure in failures:
+        problems.add_group(failure.text, [failure.issue])
+    return not failures

{bitexoft_verify-0.2.0 → bitexoft_verify-0.2.1}/src/bitexoft_verify/checks/common.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import ast
 import importlib
+import random
 import subprocess
 import sys
 from dataclasses import dataclass
@@ -17,7 +18,8 @@ from pathlib import Path
 from typing import Any
 
 from ..manifest import Manifest
-from ..report import Check, Problems, issue
+from ..report import Check, Problems, Trace, issue
+from .execution import run_bounded
 
 FRAMEWORKS = (
     "fastapi",
@@ -47,17 +49,19 @@ class Context:
     root: Path
     manifest: Manifest
     timeout: int = 180
+    # What a check that builds its own inputs draws them from (seeds.py). `seed_used` is how the report knows
+    # whether to say so: a run whose checks never asked for randomness carries no seed, as A1's never do.
+    seed: int = 0
+    seed_used: bool = False
+
+    def random(self, label: str) -> random.Random:
+        """A generator for `label`: the same seed and label always give the same sequence."""
+        self.seed_used = True
+        return random.Random(f"{self.seed}:{label}")
 
     def run(self, args: list[str], timeout: int | None = None) -> subprocess.CompletedProcess[str]:
-        """Runs a command at the root of the learner's repository."""
-        return subprocess.run(
-            args,
-            cwd=self.root,
-            capture_output=True,
-            text=True,
-            timeout=timeout or self.timeout,
-            check=False,
-        )
+        """Runs a command at the root of the learner's repository, within the budget of `execution.py`."""
+        return run_bounded(args, cwd=self.root, timeout=timeout or self.timeout)
 
     def python(self, args: list[str], timeout: int | None = None) -> subprocess.CompletedProcess[str]:
         return self.run([sys.executable, *args], timeout=timeout)
@@ -212,20 +216,58 @@ def check_domain_has_no_io(ctx: Context, check_id: str = "boundary") -> Check:
     return Check(check_id, title, "pass")
 
 
+def trace_of(
+    args: list[str],
+    result: subprocess.CompletedProcess | subprocess.TimeoutExpired,  # type: ignore[type-arg]
+    seconds: float | None = None,
+) -> Trace:
+    """What was run and what came back, for a check that opts in to showing it.
+
+    Takes any `CompletedProcess`: `Executed` carries the seconds and whether the output was cut, and a plain one
+    (a stand-in in a test, or a command run another way) is shown without them."""
+    if isinstance(result, subprocess.TimeoutExpired):
+        return Trace(
+            command=" ".join(args),
+            exit_code=None,
+            stdout=str(result.output or ""),
+            stderr=str(result.stderr or ""),
+            seconds=float(seconds or result.timeout),
+            truncated=False,
+        )
+    return Trace(
+        command=" ".join(args),
+        exit_code=result.returncode,
+        stdout=result.stdout or "",
+        stderr=result.stderr or "",
+        seconds=float(getattr(result, "seconds", 0.0)),
+        truncated=bool(getattr(result, "truncated", False)),
+    )
+
+
 def check_tests_pass(ctx: Context, check_id: str = "tests") -> Check:
     title = "Your test suite passes"
+    command = [sys.executable, "-m", "pytest", "-q", "--no-header", "-x"]
     try:
-        result = ctx.python(["-m", "pytest", "-q", "--no-header", "-x"], timeout=ctx.timeout)
-    except subprocess.TimeoutExpired:
+        result = ctx.run(command, timeout=ctx.timeout)
+    except subprocess.TimeoutExpired as expired:
+        # "timeout", not "fail": the runner turns it back into "fail" for a frozen delivery (ADR 0047).
         return Check(
             check_id,
             title,
-            "fail",
+            "timeout",
             f"the tests did not finish within {ctx.timeout}s",
             (issue("tests.timeout", seconds=ctx.timeout),),
+            trace_of(command, expired, ctx.timeout),
         )
     if result.returncode == 5:
-        return Check(check_id, title, "fail", "no tests were collected", (issue("tests.none_collected"),))
+        return Check(
+            check_id,
+            title,
+            "fail",
+            "no tests were collected",
+            (issue("tests.none_collected"),),
+            trace_of(command, result),
+        )
     if result.returncode != 0:
         tail = (result.stdout or result.stderr).strip().splitlines()[-3:]
         return Check(
@@ -234,6 +276,7 @@ def check_tests_pass(ctx: Context, check_id: str = "tests") -> Check:
             "fail",
             " / ".join(tail) or "pytest returned a non-zero exit code",
             (issue("tests.failed", detail=" / ".join(tail)),),
+            trace_of(command, result),
         )
     return Check(check_id, title, "pass")
 
@@ -257,7 +300,10 @@ def check_tests_cover_invariants(ctx: Context, error_names: list[str], check_id:
         return Check(check_id, title, "fail", "I cannot find any test files", (issue("tests.no_files"),))
     for path in files:
         text = path.read_text(encoding="utf-8", errors="ignore")
-        if "raises" in text and any(name in text for name in error_names):
+        # `pytest.raises` and `unittest`'s `assertRaises` (with its Regex and callable forms) say a refusal is
+        # expected (ADR 0051). Case matters on purpose: a docstring's "Raises:" is not a test. A refusal caught
+        # with try/except is still not seen.
+        if ("raises" in text or "assertRaises" in text) and any(name in text for name in error_names):
             return Check(check_id, title, "pass")
     return Check(
         check_id,
@@ -273,13 +319,14 @@ def check_determinism(ctx: Context, args: list[str], check_id: str = "determinis
     try:
         first = ctx.cli(args, timeout=120)
         second = ctx.cli(args, timeout=120)
-    except subprocess.TimeoutExpired:
+    except subprocess.TimeoutExpired as expired:
         return Check(
             check_id,
             title,
-            "fail",
+            "timeout",
             "one of the two runs did not finish within 120s",
             (issue("determinism.timeout", seconds=120),),
+            trace_of(list(args), expired, 120),
         )
     if first.returncode != 0 or second.returncode != 0:
         return Check(

bitexoft_verify-0.2.1/src/bitexoft_verify/checks/execution.py

@@ -0,0 +1,199 @@
+"""Runs the learner's code with a budget (foundation 09, D4 and F4; ADR 0046).
+
+Every command the verifier runs for a check goes through here, so there is one place that says what learner
+code may do while it is being verified:
+
+    time      a limit; at the limit the WHOLE process tree is killed, not only the process we started
+    output    bounded in memory; a runaway print cannot exhaust it. The head and the tail are kept,
+              because the last lines (a test summary, an exit message) are what a failure message reads
+    secrets   variables that look like credentials are not handed down. In CI the learner's job
+              holds a token, and the learner's code is the one thing here that is not ours
+    input     closed, so a program that waits for a keyboard ends instead of hanging until the limit
+
+It is portable: the learner works on Windows, where the group kill is `taskkill /T`, and on Linux, where it
+is a process group. There is no memory limit: the OS gives no portable way to set one without breaking Python,
+and a limit that is only enforced on one platform would be a promise nobody could rely on.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import locale
+import os
+import re
+import signal
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+# Per stream. Large enough for any real pytest report, small enough that a loop of `print` costs nothing.
+MAX_OUTPUT_BYTES = 30_000
+_HEAD = MAX_OUTPUT_BYTES // 2
+_TAIL = MAX_OUTPUT_BYTES - _HEAD
+
+# Names that hold credentials in practice. Matching on the name is crude and deliberately wide.
+_SECRET_NAME = re.compile(r"(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL)", re.IGNORECASE)
+
+_WINDOWS = sys.platform == "win32"
+# After SIGTERM, how long the group gets before SIGKILL.
+_GRACE_SECONDS = 2.0
+
+
+def scrubbed_environment(env: Mapping[str, str] | None = None) -> dict[str, str]:
+    """The environment for learner code: the current one minus anything that looks like a credential."""
+    source = os.environ if env is None else env
+    return {name: value for name, value in source.items() if not _SECRET_NAME.search(name)}
+
+
+class Executed(subprocess.CompletedProcess):  # type: ignore[type-arg]
+    """What `subprocess.run` returned, plus what the budget did to it."""
+
+    def __init__(
+        self,
+        args: Sequence[str],
+        returncode: int,
+        stdout: str,
+        stderr: str,
+        *,
+        truncated: bool,
+        seconds: float,
+    ) -> None:
+        super().__init__(args, returncode, stdout, stderr)
+        self.truncated = truncated
+        self.seconds = seconds
+
+
+class _Bounded:
+    """Reads a stream to its end, keeping the head and the tail of what is too long."""
+
+    def __init__(self) -> None:
+        self.head = bytearray()
+        self.tail = bytearray()
+        self.total = 0
+
+    def feed(self, chunk: bytes) -> None:
+        self.total += len(chunk)
+        room = _HEAD - len(self.head)
+        if room > 0:
+            self.head += chunk[:room]
+            chunk = chunk[room:]
+        if chunk:
+            self.tail += chunk
+            if len(self.tail) > _TAIL:
+                del self.tail[: len(self.tail) - _TAIL]
+
+    @property
+    def truncated(self) -> bool:
+        return self.total > len(self.head) + len(self.tail)
+
+    def text(self) -> str:
+        encoding = locale.getpreferredencoding(False) or "utf-8"
+        if not self.truncated:
+            return bytes(self.head + self.tail).decode(encoding, errors="replace")
+        omitted = self.total - len(self.head) - len(self.tail)
+        marker = f"\n[... {omitted} bytes of output omitted ...]\n"
+        head = bytes(self.head).decode(encoding, errors="replace")
+        tail = bytes(self.tail).decode(encoding, errors="replace")
+        return head + marker + tail
+
+
+def _pump(stream, sink: _Bounded) -> None:  # noqa: ANN001 - a binary pipe
+    try:
+        while True:
+            chunk = stream.read1(65536) if hasattr(stream, "read1") else stream.read(65536)
+            if not chunk:
+                return
+            sink.feed(chunk)
+    except (OSError, ValueError):
+        return  # the pipe was closed under us when the tree was killed
+
+
+def kill_tree(process: subprocess.Popen) -> None:  # type: ignore[type-arg]
+    """Ends the process and everything it started. Gives a group a moment on POSIX before it forces."""
+    if _WINDOWS:
+        subprocess.run(
+            ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+            capture_output=True,
+            check=False,
+        )
+        with contextlib.suppress(OSError):
+            process.kill()
+        return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except (ProcessLookupError, PermissionError):
+        return
+    deadline = time.monotonic() + _GRACE_SECONDS
+    while time.monotonic() < deadline:
+        try:
+            os.killpg(process.pid, 0)
+        except ProcessLookupError:
+            return
+        time.sleep(0.05)
+    with contextlib.suppress(ProcessLookupError):
+        os.killpg(process.pid, signal.SIGKILL)
+
+
+def run_bounded(
+    args: Sequence[str],
+    *,
+    cwd: Path,
+    timeout: float,
+    env: Mapping[str, str] | None = None,
+) -> Executed:
+    """Runs `args` in `cwd` within the budget. Raises `subprocess.TimeoutExpired` at the limit, after the
+    whole tree has been killed, with whatever it printed so far."""
+    options: dict = {}
+    if _WINDOWS:
+        options["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        options["start_new_session"] = True
+
+    started = time.monotonic()
+    process = subprocess.Popen(
+        list(args),
+        cwd=cwd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=scrubbed_environment(env),
+        **options,
+    )
+    out, err = _Bounded(), _Bounded()
+    readers = [
+        threading.Thread(target=_pump, args=(process.stdout, out), daemon=True),
+        threading.Thread(target=_pump, args=(process.stderr, err), daemon=True),
+    ]
+    for reader in readers:
+        reader.start()
+
+    try:
+        process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        kill_tree(process)
+        process.wait()
+        for reader in readers:
+            reader.join(timeout=_GRACE_SECONDS)
+        raise subprocess.TimeoutExpired(list(args), timeout, output=out.text(), stderr=err.text()) from None
+
+    # The leader exited. A child it left running can keep the pipes open, so do not wait for them for ever;
+    # if they are still open after the grace period, something of the learner's is still running: end it.
+    # Only then: on Windows a process id that has exited can already belong to someone else.
+    for reader in readers:
+        reader.join(timeout=_GRACE_SECONDS)
+    if any(reader.is_alive() for reader in readers):
+        kill_tree(process)
+        for reader in readers:
+            reader.join(timeout=_GRACE_SECONDS)
+
+    return Executed(
+        list(args),
+        process.returncode,
+        out.text(),
+        err.text(),
+        truncated=out.truncated or err.truncated,
+        seconds=round(time.monotonic() - started, 3),
+    )

bitexoft_verify-0.2.1/src/bitexoft_verify/checks/isolated.py

@@ -0,0 +1,138 @@
+"""Calls the learner's code in a child process, under the budget of `execution.py` (ADR 0048).
+
+A1's checks import the learner's symbols into the verifier's own process (`common.import_symbol`) and call them
+there. That is fine while the verifier only reads what a learner built: a hang there is a bug of the learner's
+that the whole run waits on, and A1 is frozen (ADR 0009), so it stays as it is.
+
+From A2 on, a check hands the learner's code something of its own (a stub policy the learner has never seen) and
+calls it. If that code loops, raises `SystemExit` or kills the interpreter, it must take the child with it and
+nothing else. So a check that calls learner code runs its snippet here:
+
+    - the snippet is the verifier's, written as a string and run in a fresh interpreter whose `sys.path` starts
+      with the learner's root; it can `load("package.module:Symbol")` and sets `result` to a JSON value
+    - what the learner prints cannot be mistaken for the answer: the answer is the last thing on stdout, between
+      two markers, and the budget keeps the tail of a long output (`execution.py`)
+    - four outcomes, which a check turns into its own words: `ok`, `raised` (the learner's code raised),
+      `timeout` and `crashed` (the interpreter ended without answering)
+
+It runs whatever interpreter the verifier runs under, as `Context.python` does, so the learner's dependencies are
+the ones installed in that environment.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ..report import Trace
+from .common import Context, trace_of
+from .execution import Executed, run_bounded
+
+START = "<<<bitexoft-result>>>"
+END = "<<<bitexoft-end>>>"
+
+# Runs in the child. Reads the check's snippet and payload from files (stdin is closed by the budget, and a
+# command line has a length limit), imports from the learner's root first, and answers between markers.
+#
+# The answer is base64, so the markers cannot appear inside it. They used to: from Python 3.13 a traceback of code run
+# with `-c` shows its source lines, and the line that writes the markers went into the answer's own `traceback` text, so
+# the parent read a marker from the middle of the answer. An exception message or a learner's `print` can hold them too.
+_BOOT = f"""
+import base64, json, sys, traceback
+root, payload_path, script_path = sys.argv[1:4]
+sys.path.insert(0, root)
+from bitexoft_verify.checks.common import import_symbol
+def emit(answer):
+    sys.stdout.write("\\n{START}" + base64.b64encode(json.dumps(answer).encode("utf-8")).decode("ascii") + "{END}\\n")
+    sys.stdout.flush()
+try:
+    with open(payload_path, encoding="utf-8") as handle:
+        payload = json.load(handle)
+    with open(script_path, encoding="utf-8") as handle:
+        source = handle.read()
+    scope = {{"payload": payload, "load": import_symbol, "result": None}}
+    exec(compile(source, "<check>", "exec"), scope)
+    emit({{"ok": scope["result"]}})
+except BaseException as error:
+    emit({{
+        "raised": type(error).__name__,
+        "message": str(error)[:500],
+        "traceback": "".join(traceback.format_exception(error))[-1500:],
+    }})
+"""
+
+Kind = Literal["ok", "raised", "timeout", "crashed"]
+
+
+@dataclass(frozen=True, slots=True)
+class ChildOutcome:
+    kind: Kind
+    value: Any = None  # `ok`: what the snippet set `result` to
+    error: str | None = None  # `raised`: the exception's type name
+    message: str = ""  # `raised`: its message
+    detail: str = ""  # `raised`: the end of the traceback; `crashed`: the end of stderr
+    exit_code: int | None = None
+    command: tuple[str, ...] = ()
+    executed: Executed | subprocess.TimeoutExpired | None = None
+
+    def trace(self) -> Trace | None:
+        """What was run and what came back, for a check that opts in to showing it."""
+        if self.executed is None:
+            return None
+        return trace_of(list(self.command), self.executed)
+
+
+def _answer(stdout: str) -> dict[str, Any] | None:
+    """The last well-formed answer between the markers, or None if the child never gave one."""
+    end = stdout.rfind(END)
+    start = stdout.rfind(START, 0, end) if end != -1 else -1
+    if start == -1:
+        return None
+    try:
+        answer = json.loads(base64.b64decode(stdout[start + len(START) : end], validate=True))
+    except ValueError:  # not base64 (binascii.Error is one), not UTF-8 or not JSON
+        return None
+    return answer if isinstance(answer, dict) else None
+
+
+def run_in_child(root: Path, script: str, payload: Any = None, timeout: float = 30) -> ChildOutcome:
+    """Runs `script` in a fresh interpreter at `root`, with `payload` visible to it, and says what happened."""
+    with tempfile.TemporaryDirectory(prefix="bitexoft-child-") as folder:
+        payload_path = Path(folder) / "payload.json"
+        script_path = Path(folder) / "script.py"
+        payload_path.write_text(json.dumps(payload), encoding="utf-8")
+        script_path.write_text(script, encoding="utf-8")
+        command = (sys.executable, "-c", _BOOT, str(root.resolve()), str(payload_path), str(script_path))
+        # What a person reads in a trace: not the bootstrap, not temporary paths.
+        shown = (sys.executable, "-c", "<bitexoft: call the code under test>")
+        try:
+            executed = run_bounded(list(command), cwd=root, timeout=timeout)
+        except subprocess.TimeoutExpired as expired:
+            return ChildOutcome("timeout", command=shown, executed=expired)
+
+    answer = _answer(executed.stdout)
+    if answer is None:
+        tail = "\n".join((executed.stderr or "").strip().splitlines()[-6:])
+        return ChildOutcome("crashed", detail=tail, exit_code=executed.returncode, command=shown, executed=executed)
+    if "ok" in answer:
+        return ChildOutcome("ok", value=answer["ok"], exit_code=executed.returncode, command=shown, executed=executed)
+    return ChildOutcome(
+        "raised",
+        error=str(answer.get("raised", "")),
+        message=str(answer.get("message", "")),
+        detail=str(answer.get("traceback", "")),
+        exit_code=executed.returncode,
+        command=shown,
+        executed=executed,
+    )
+
+
+def call_in_child(ctx: Context, script: str, payload: Any = None, timeout: float | None = None) -> ChildOutcome:
+    """`run_in_child` at the learner's repository, within the check's own budget unless one is given."""
+    return run_in_child(ctx.root, script, payload, timeout if timeout is not None else ctx.timeout)