ph-runtime-guest 0.2.0__tar.gz → 0.3.0__tar.gz

{ph_runtime_guest-0.2.0 → ph_runtime_guest-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ph-runtime-guest
-Version: 0.2.0
+Version: 0.3.0
 Summary: The guest half of pH's code runtime: the fd-3 protocol, the run loop, and the binding proxies a cell awaits.
 Project-URL: Homepage, https://github.com/chastabor/pH
 Project-URL: Repository, https://github.com/chastabor/pH

{ph_runtime_guest-0.2.0 → ph_runtime_guest-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ph-runtime-guest"
-version = "0.2.0"
+version = "0.3.0"
 description = "The guest half of pH's code runtime: the fd-3 protocol, the run loop, and the binding proxies a cell awaits."
 readme = "README.md"
 requires-python = ">=3.12"

{ph_runtime_guest-0.2.0 → ph_runtime_guest-0.3.0}/src/ph_runtime/channel.py

@@ -17,13 +17,66 @@ import contextlib
 import json
 import os
 import socket
+from datetime import date, datetime
+from datetime import time as time_of_day
+from decimal import Decimal
+from pathlib import PurePath
 from typing import Any
 
-from .protocol import FD_ENV, PROTOCOL_FD
+from .protocol import FD_ENV, FRAME_BYTES_ENV, PROTOCOL_FD
 
-__all__ = ["MAX_FRAME_BYTES", "Channel"]
+__all__ = ["MAX_FRAME_BYTES", "Channel", "frame_limit", "jsonable"]
 
 MAX_FRAME_BYTES = 64 * 1024 * 1024
+"""The read limit when the host names none — see `FRAME_BYTES_ENV` (F8)."""
+
+
+def frame_limit() -> int:
+    """The largest frame this guest will read: the host's number, else the default.
+
+    The host sizes it from `maxSnapshotBytes`, because one snapshotted variable
+    must fit one frame in *both* directions — a fixed 64 MiB here lost the
+    namespace on restore as soon as a deployment raised the limit past ~48 MiB,
+    base64 being four bytes per three (F8). A value that is not a positive
+    integer is ignored rather than trusted: a zero limit would refuse every frame.
+    """
+    try:
+        named = int(os.environ.get(FRAME_BYTES_ENV, ""))
+    except ValueError:
+        return MAX_FRAME_BYTES
+    return named if named > 0 else MAX_FRAME_BYTES
+
+
+def jsonable(value: object) -> object:
+    """One non-JSON value as something the host can use (F7).
+
+    `default=repr` was the whole rule, and it is silently lossy for the two
+    types a cell passes most: `tools.read(Path("notes.md"))` arrived as the
+    string `"PosixPath('notes.md')"`, and a `datetime` as
+    `"datetime.datetime(2026, 9, 20, 0, 0)"`. Neither is an error anywhere — the
+    tool receives a string where the model wrote a value, and either refuses it
+    with a message about a path that does not exist or, worse, uses it.
+
+    The obvious spellings for the types that have one, and `repr` for the rest:
+    a value with no JSON form is a value the tool's own schema is going to
+    reject, and `repr` is what makes *that* refusal readable. Deliberately not a
+    guest-side raise — the guest does not know the tool's schema, and refusing
+    an argument a tool would have accepted is the worse error.
+
+    It lives here, on the channel, because the lossiness is a property of *the
+    wire* and not of one frame: an argument, a cell's value and every other
+    frame leave through `send`, and a `Path` that survives as one and not the
+    others is the same bug reported twice.
+    """
+    if isinstance(value, PurePath):
+        return str(value)
+    if isinstance(value, datetime | date | time_of_day):
+        return value.isoformat()
+    if isinstance(value, set | frozenset | tuple):
+        return list(value)
+    if isinstance(value, Decimal):
+        return str(value)
+    return repr(value)
 
 
 class Channel:
@@ -45,7 +98,7 @@ class Channel:
             fd = int(os.environ.get(FD_ENV, PROTOCOL_FD))
         sock = socket.socket(fileno=fd)
         sock.setblocking(False)
-        reader, writer = await asyncio.open_connection(sock=sock, limit=MAX_FRAME_BYTES)
+        reader, writer = await asyncio.open_connection(sock=sock, limit=frame_limit())
         return cls(reader, writer)
 
     async def receive(self) -> dict[str, Any] | None:
@@ -77,7 +130,7 @@ class Channel:
         # A dead host is not this process's problem to report: the
         # die-with-parent mechanism is what ends the guest (F3).
         with contextlib.suppress(BrokenPipeError, ConnectionResetError, RuntimeError):
-            self._writer.write(json.dumps(frame, default=repr).encode("utf-8") + b"\n")
+            self._writer.write(json.dumps(frame, default=jsonable).encode("utf-8") + b"\n")
 
     async def drain(self) -> None:
         with contextlib.suppress(BrokenPipeError, ConnectionResetError, RuntimeError):

{ph_runtime_guest-0.2.0 → ph_runtime_guest-0.3.0}/src/ph_runtime/limits.py

@@ -14,6 +14,13 @@ Exceeding it raises `CpuBudgetExceeded`, which derives from `BaseException` on
 purpose: like a denial (C3), a budget is not the program's to catch. A cell that
 could `except Exception` its way past the limit would make the limit advisory.
 
+**Who raises it is the runner's decision, not this module's.** `SIGXCPU` can only
+be turned into an exception safely when the main thread is executing the cell —
+otherwise it lands in whatever library frame the interpreter happens to be in,
+which for a guest that is mostly waiting means `asyncio`'s own internals. So this
+module arms and disarms the limit, and `Runner` installs the handler that knows
+where the cell is.
+
 @module ph_runtime.limits
 """
 
@@ -24,7 +31,23 @@ import math
 import signal
 from typing import Any
 
-__all__ = ["CpuBudgetExceeded", "apply_limits", "arm_cpu_budget", "cpu_seconds_used"]
+__all__ = [
+    "CPU_BUDGET_MESSAGE",
+    "CpuBudgetExceeded",
+    "apply_limits",
+    "arm_cpu_budget",
+    "cpu_seconds_used",
+    "relax_cpu_budget",
+]
+
+
+CPU_BUDGET_MESSAGE = "this cell used its CPU budget"
+"""What both routes out of a budget breach say.
+
+The handler raises on one path and cancels the run on the other, and
+`_on_cpu_budget`'s docstring promises they end in the same `cpu` error. Written
+out at each of them, that promise was two string literals keeping each other
+honest."""
 
 
 class CpuBudgetExceeded(BaseException):
@@ -82,18 +105,41 @@ def apply_limits(*, address_space_bytes: int) -> dict[str, Any]:
     return applied
 
 
-def _on_sigxcpu(_signum: int, _frame: object) -> None:
-    raise CpuBudgetExceeded("this cell used its CPU budget")
+def _uncaught_budget() -> bool:
+    """Whether a `SIGXCPU` would kill this process rather than reach a handler.
+
+    **Never arm a limit whose breach nothing here will catch** (M1). `RLIMIT_CPU`
+    is process-wide and `SIGXCPU`'s default disposition is to terminate, so an
+    arm made where no handler is installed points a timer at whatever process
+    this happens to be — and `Runner` is built in-process by this package's own
+    tests, where that process is pytest. It had been pointed for a while: the
+    per-run arm left the limit at `used + cpuSeconds` on the test runner, which
+    the suite reached on a long run and died of, reading as a run that finished
+    and printed no summary.
+
+    Asked of `signal` rather than remembered by the caller, because a flag on
+    the one caller that exists today is a rule every later caller has to be told
+    about — and this also covers a handler reset after install, or an
+    `install_signal_handlers` that partially failed.
+
+    `getattr` because `SIGXCPU` is POSIX; where it does not exist there is no
+    budget to arm and nothing to catch.
+    """
+    sigxcpu = getattr(signal, "SIGXCPU", None)
+    if sigxcpu is None:  # pragma: no cover - Windows
+        return True
+    return signal.getsignal(sigxcpu) in (signal.SIG_DFL, signal.SIG_IGN)
 
 
 def arm_cpu_budget(cpu_seconds: int) -> None:
     """Give the *next* run `cpu_seconds` of CPU, from whatever is spent so far."""
     if resource is None or cpu_seconds <= 0:  # pragma: no cover
         return
-    signal.signal(signal.SIGXCPU, _on_sigxcpu)
     # `ceil`, not `int`: flooring the CPU already spent hands the next cell less
     # than `cpu_seconds` — a bomb that burned 1.9s floors to 1, so a budget of 1
     # leaves 0.1s and the *next* trivial cell dies on the previous one's spend.
+    if _uncaught_budget():
+        return
     used = math.ceil(cpu_seconds_used())
     soft = used + cpu_seconds
     _, hard = resource.getrlimit(resource.RLIMIT_CPU)
@@ -101,3 +147,27 @@ def arm_cpu_budget(cpu_seconds: int) -> None:
         soft = min(soft, hard)
     with contextlib.suppress(ValueError, OSError):  # pragma: no cover
         resource.setrlimit(resource.RLIMIT_CPU, (soft, hard))
+
+
+def relax_cpu_budget() -> None:
+    """Put the soft limit back to the hard one. **Called first, from the handler.**
+
+    `RLIMIT_CPU` is not a one-shot. Linux delivers `SIGXCPU` when the soft limit
+    is first crossed and then **again every CPU-second** for as long as the
+    process stays over it — and the process stays over it, because the limit is
+    cumulative and nothing gives CPU back. So one budget breach became a signal
+    per second for the rest of the run's teardown: one landed in the cell and
+    unwound it as intended, and the next landed in `_snapshot` or `_settle`,
+    escaped the `try` that was supposed to report the failure, and the `done`
+    frame was never sent. The host has no wall clock of its own on a run, so it
+    waited for a frame that was never coming.
+
+    Disarming at the first delivery is what makes the budget the one-shot the
+    rest of the design assumes. The next `arm_cpu_budget` re-arms it, which is
+    where a per-run budget comes from in the first place.
+    """
+    if resource is None:  # pragma: no cover
+        return
+    _, hard = resource.getrlimit(resource.RLIMIT_CPU)
+    with contextlib.suppress(ValueError, OSError):  # pragma: no cover
+        resource.setrlimit(resource.RLIMIT_CPU, (hard, hard))

{ph_runtime_guest-0.2.0 → ph_runtime_guest-0.3.0}/src/ph_runtime/protocol.py

@@ -44,6 +44,7 @@ from ._json import as_str
 
 __all__ = [
     "FD_ENV",
+    "FRAME_BYTES_ENV",
     "FRAME_FIELDS",
     "GUEST_FRAMES",
     "HOST_FRAMES",
@@ -55,8 +56,33 @@ __all__ = [
     "truncation_marker",
 ]
 
-PROTOCOL_VERSION: Final = 1
-"""One, and it stays there until there is something to be compatible with.
+PROTOCOL_VERSION: Final = 4
+"""Four, since `restore` was split into one frame per variable (O3).
+
+`more` is required — `encode` drops only `None`, so a `bool` default is always
+sent — and a guest that does not read it answers `done` on the first batch,
+leaving the host settled with the namespace half restored and nothing said.
+A required field added, which is the rule the number exists for.
+
+Three, since `boot` gained a required `idleCpuSeconds` (M1).
+
+The rule that moved it to two, applied again: a guest that cannot read the field
+has no budget between runs, and a guest that reads a frame without it raises
+before `boot-ack`. Neither side can ignore the difference, so the pairing is
+refused at boot — and `venv._marker`, which keys on this number and carries no
+content digest, rebuilds a warm `$PH_CACHE/runtime-venv` instead of booting last
+week's guest against today's host. `ping`/`pong` needed no bump on their own:
+an older pairing simply never sends or answers one.
+
+Two, since `call` gained a required `run` (F4).
+
+Moved by exactly the rule below: a **required field added**, which a mismatched
+pairing would misread rather than ignore. A guest that does not send `run` has
+its every binding call refused by a host that requires it — silently, as "not
+available" — so the pairing has to be refused at `boot-ack` instead, and a warm
+venv from before the change has to rebuild. That is what the number is for.
+
+The original note, still the rule:
 
 A version gate exists for two builds that have to understand each other, and
 before a first release there are not two: the host and the guest ship together
@@ -92,10 +118,21 @@ number it has in the *parent*, and re-numbering it to 3 in the child would need
 a `preexec_fn` — which is unsafe in a threaded parent. So the host passes the
 number instead of moving the descriptor."""
 
+FRAME_BYTES_ENV: Final = "PH_RUNTIME_FRAME_BYTES"
+"""The largest frame the guest's reader will assemble, sized by the host (F8).
+
+The host derives it from `maxSnapshotBytes` — its own `frame_cap` — so both
+readers are sized by one expression. In the environment rather than in `boot`
+because the reader's limit is fixed when the connection opens, before any frame
+has been read; `FD_ENV` crosses the same way for the same reason. Absent, the
+guest keeps `channel.MAX_FRAME_BYTES`, which is what an older host expects."""
+
 NAMESPACE_ENV: Final = "PH_NAMESPACE_ID"
 
-HOST_FRAMES: Final = frozenset({"boot", "run", "reply", "restore", "cancel", "shutdown"})
-GUEST_FRAMES: Final = frozenset({"boot-ack", "call", "log", "display", "snapshot", "done", "fault"})
+HOST_FRAMES: Final = frozenset({"boot", "run", "reply", "restore", "cancel", "shutdown", "ping"})
+GUEST_FRAMES: Final = frozenset(
+    {"boot-ack", "call", "log", "display", "snapshot", "done", "fault", "pong"}
+)
 
 UNPRODUCED_FRAMES: Final = frozenset({"display"})
 """Frames defined here that nothing emits yet.
@@ -119,6 +156,9 @@ FRAME_FIELDS: Final[dict[str, tuple[frozenset[str], frozenset[str]]]] = {
                 "type",
                 "protocol",
                 "cpuSeconds",
+                # See `Runner._end_runaway` (M1): what a namespace may burn while
+                # no cell is running, which is the window nothing else bounds.
+                "idleCpuSeconds",
                 "addressSpaceBytes",
                 "maxLogBytes",
                 "maxValueBytes",
@@ -136,16 +176,35 @@ FRAME_FIELDS: Final[dict[str, tuple[frozenset[str], frozenset[str]]]] = {
     # a budget), so the proxy raises what the program is not offered a chance to
     # catch — and the host aborts the run regardless of whether it tries.
     "reply": (frozenset({"type", "id", "ok"}), frozenset({"value", "message", "name", "fatal"})),
-    "restore": (frozenset({"type", "id", "variables"}), frozenset()),
+    # **One frame per variable, like `snapshot` coming back** (O3).
+    # `maxSnapshotBytes` bounds each *value*; a frame carrying the whole
+    # namespace was bounded by nothing, and the guest's reader is sized before
+    # any frame arrives (`FRAME_BYTES_ENV`, F8) — so one value per frame is what
+    # that size can promise to hold. `more` is the batch marker: the guest
+    # accumulates and answers on the frame without it.
+    "restore": (frozenset({"type", "id", "variables", "more"}), frozenset()),
     "cancel": (frozenset({"type"}), frozenset({"id"})),
     "shutdown": (frozenset({"type"}), frozenset()),
     "boot-ack": (frozenset({"type", "protocol", "python", "limits"}), frozenset()),
-    "call": (frozenset({"type", "id", "global", "name", "args"}), frozenset()),
+    "call": (frozenset({"type", "id", "run", "global", "name", "args"}), frozenset()),
     "log": (frozenset({"type", "stream", "text"}), frozenset({"truncated"})),
     "display": (frozenset({"type", "mime", "data"}), frozenset({"meta"})),
     "snapshot": (frozenset({"type", "id", "variables"}), frozenset()),
     "done": (frozenset({"type", "id"}), frozenset({"value", "error", "truncated"})),
     "fault": (frozenset({"type", "message"}), frozenset()),
+    # **The loop's own clock** (M2). `ping` is answered by the guest's reader
+    # task, so the round trip measures how far behind the guest's event loop
+    # is — a cell burning CPU starves that task and the answer is late or
+    # absent, which is a *load* reading and not a death certificate.
+    #
+    # `run` is the host's open run, and it rides on the *question* rather
+    # than the answer. The host waits for `done` with no wall clock of its
+    # own, so it asks the one party that knows: a guest neither running that
+    # run nor owing it a `done` settles it on the spot, through the same
+    # `_send_done` every other terminal path takes. The repair travels as an
+    # ordinary `done`, which leaves the pong carrying nothing but the clock.
+    "ping": (frozenset({"type", "id", "run"}), frozenset()),
+    "pong": (frozenset({"type", "id"}), frozenset()),
 }
 """frame type → (required fields, optional fields).