letify 2.5.0__tar.gz → 2.5.2__tar.gz

{letify-2.5.0 → letify-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.5.0
+Version: 2.5.2
 Summary: Declarations that become infrastructure.
 Project-URL: Homepage, https://github.com/DarkPyonix/letify
 Project-URL: Documentation, https://github.com/DarkPyonix/letify/tree/main/docs

{letify-2.5.0 → letify-2.5.2}/docs/SPEC.md

@@ -269,7 +269,7 @@ letify starts the session itself, on a notebook created fresh for that run alone
 The URL is split into the server base, the URL without its query string, and the token, the `token` query parameter when present. A routed proxy URL carries no query, so the token is in the path and every REST request goes to `<base>/api/...` with no `token` query and no `Authorization` header, through the standard library HTTP client. The full URL and the token never appear in a message, a log or a command line; a message names only the host.
 
 1. **Start.** `open_channel` reads the account's cookie, refusing the run with a `ConfigError` when it is missing, past its `exp`, or within one hour of it. It creates a fresh notebook for this run (see "Kaggle session token chain" below), started with the session's internet access enabled (`compute.internet.isEnabled` in `CommitAndRun`), because the environment step downloads from PyPI and the uv installer from astral.sh; Kaggle grants that access only to a phone-verified account, and a run it refuses fails with Kaggle's own error. It runs the token chain to get the routed URL, waits for `<base>/api/status` to answer, then creates one kernel with `POST <base>/api/kernels` and body `{"name": "python3"}` and keeps its id for the runtime. `stop` deletes the kernel with `DELETE <base>/api/kernels/<id>`, cancels the run, then deletes the notebook through the official CLI only. All three are best effort, and a notebook neither delete reaches is reported with a warning naming the notebook, never the cookie, so it can be deleted by hand on kaggle.com.
-2. **The worker.** The session carries one worker for the life of the runtime, not one program per request. The Kaggle adapter, `letify/providers/kaggle_adapter.py`, is a bridge process started by `uv run --no-project --python 3.13 --with "jupyter-kernel-client<1" python -P`, and it receives the URL and the kernel id in the environment variables `LETIFY_JUPYTER_URL` and `LETIFY_KERNEL_ID`. It executes one cell in that kernel which runs until the runtime ends, and that cell carries a shim rather than the bootstrap stub of Channels. A kernel answers `input()` and nothing else: the cell's `sys.stdin` is a `TextIOWrapper` whose `buffer` reads empty instead of raising `input_request`, so a worker reading binary from standard input would read nothing at all. The shim therefore reads base64 lines with `input()`, decodes each one, and writes the bytes into a pipe the worker reads as its standard input, with the worker's own standard output going back out as `stream` messages. The bridge moves the lines on two threads, one per kernel channel, and never on one: what it reads on its standard input one thread hands to the cell by answering `input_request`, and every `stream` message the cell writes the other thread copies to its standard output. One thread is required rather than a convenience. Answering an `input_request` from the same loop that reads the cell's output blocks that loop in a standard-input read, and while it blocks no `stream` message is delivered. The worker announces itself with a `stream` message, so a single-loop bridge holds that hello behind an `input_request` the channel does not answer until it has seen the hello, which is a deadlock, and the same deadlock returns on every large response, where the cell reads the next request while the worker is still writing output. The letify process never imports `jupyter_kernel_client`.
+2. **The worker.** The session carries one worker for the life of the runtime, not one program per request. The Kaggle adapter, `letify/providers/kaggle_adapter.py`, is a bridge process started by `uv run --no-project --python 3.13 --with "jupyter-kernel-client<1" python -P`, and it receives the URL and the kernel id in the environment variables `LETIFY_JUPYTER_URL` and `LETIFY_KERNEL_ID`. It executes one cell in that kernel which runs until the runtime ends, and that cell carries a shim rather than the bootstrap stub of Channels. A kernel answers `input()` and nothing else: the cell's `sys.stdin` is a `TextIOWrapper` whose `buffer` reads empty instead of raising `input_request`, so a worker reading binary from standard input would read nothing at all. The shim therefore reads base64 lines with `input()`, decodes each one, and writes the bytes into a pipe the worker reads as its standard input, with the worker's own standard output going back out as `stream` messages. A line that does not decode is reported on standard error as `the letify shim could not decode a line of <length> characters` before the shim stops, because a line truncated in transit otherwise ends the shim silently, closes the worker's standard input, and leaves the worker compiling whatever arrived. The client writes at most 36 KiB of bytes per line, so no line exceeds 48 KiB of base64 and the worker source crosses as several lines rather than as one reply of 145 KiB; this is the limit Channels already states for a Modal sandbox, for the same reason. The bridge moves the lines on two threads, one per kernel channel, and never on one: what it reads on its standard input one thread hands to the cell by answering `input_request`, and every `stream` message the cell writes the other thread copies to its standard output. One thread is required rather than a convenience. Answering an `input_request` from the same loop that reads the cell's output blocks that loop in a standard-input read, and while it blocks no `stream` message is delivered. The worker announces itself with a `stream` message, so a single-loop bridge holds that hello behind an `input_request` the channel does not answer until it has seen the hello, which is a deadlock, and the same deadlock returns on every large response, where the cell reads the next request while the worker is still writing output. The letify process never imports `jupyter_kernel_client`.
 
    The channel is a `FramedChannel` with `text_frames` set, so the worker writes each frame as a base64 line, as the Modal sandbox already does for the same reason: a kernel's `stream` messages carry text, not bytes. `persistent_channel` is therefore true, which is what gives Kaggle an object table, a blob table that keeps a large argument across calls, and the option of `host="local"` if a link ever makes it worth using. The bridge's standard input is an unbuffered pipe, and a blocking write into a full pipe returns short when a signal arrives while it waits, as `SIGCHLD` does when a process with a handler for it, such as one where PyTorch has forked data loader workers, sees an earlier worker exit. So the channel writes each base64 line until every byte of it is in the pipe, and counts the piece as sent only then.
 
@@ -656,7 +656,15 @@ A **persistent channel** keeps one worker process alive behind a pipe pair. Mess
 
 A **one-shot channel** can only run a command and collect its output. Every call starts a fresh process, so nothing persists. It exists because some transports offer nothing more, and it refuses the operations that need persistence rather than pretending.
 
-The worker source cannot be sent on standard input as a script, because `python -` reads to end of file before compiling anything and the pipe has to stay open for requests. A small bootstrap stub passed with `-c` reads one line holding a decimal byte count from `sys.stdin.buffer`, reads that many bytes of UTF-8 worker source, executes them, and leaves standard input where it was. From then on both pipes carry frames only.
+The worker source cannot be sent on standard input as a script, because `python -` reads to end of file before compiling anything and the pipe has to stay open for requests. A small bootstrap stub passed with `-c` reads one line holding a decimal byte count from `sys.stdin.buffer`, reads that many bytes of UTF-8 worker source, executes them, and leaves standard input where it was. From then on both pipes carry frames only. The count line is `<byte count> <digest>`, where the digest is the first 16 bytes of the source's
+blake2b in hexadecimal, from `hashlib` so the stub needs nothing installed. The stub exits rather
+than compiling when either disagrees: `the letify worker source arrived short: <read> of <expected>
+bytes`, or `the letify worker source arrived corrupted: <read> bytes, digest <found>, expected
+<wanted>`. A program cut or shifted anywhere fails as a `SyntaxError` at whatever construct the
+damage landed inside, which names the symptom and hides the cause. The count alone is not enough,
+because a transport that loses one run of bytes and gains another of the same length keeps the count
+intact: a Kaggle session reported an unterminated triple-quoted string at a line that holds no quote
+in the source, which is what a shifted source looks like and what a digest catches.
 
 ### Frames <!-- id: frames -->
 

{letify-2.5.0 → letify-2.5.2}/letify/__init__.py

@@ -66,7 +66,7 @@ distributed: Final = Host.distributed
 # The enum class stays importable from letify.declare.instance for letify's own use.
 del Host
 
-__version__ = "2.5.0"
+__version__ = "2.5.2"
 
 
 def fetch(tensor):  # type: ignore[no-untyped-def]

{letify-2.5.0 → letify-2.5.2}/letify/protocol/worker.py

@@ -37,12 +37,35 @@ from . import wire as _wire
 #: enough to survive shell quoting reads a byte count line and that many bytes of source,
 #: execs them, and leaves standard input where it was.
 BOOTSTRAP = (
-    "import sys;"
+    "import sys,hashlib;"
     "b=sys.stdin.buffer;"
-    "n=int(b.readline());"
-    "exec(compile(b.read(n).decode(),'letify-worker','exec'))"
+    "h=b.readline().split();"
+    "n=int(h[0]);"
+    "s=b.read(n);"
+    # Spec "Channels": a source cut or shifted anywhere compiles as whatever construct the
+    # damage landed inside, or runs and exits without serving. The count catches a cut and
+    # the digest catches a shift, which keeps the count intact.
+    "len(s)==n or sys.exit("
+    "'the letify worker source arrived short: %d of %d bytes'%(len(s),n));"
+    "d=hashlib.blake2b(s,digest_size=16).hexdigest();"
+    "d==h[1].decode() or sys.exit("
+    "'the letify worker source arrived corrupted: %d bytes, digest %s, expected %s'"
+    "%(len(s),d,h[1].decode()));"
+    "exec(compile(s.decode(),'letify-worker','exec'))"
 )
 
+def count_line(body: bytes) -> bytes:
+    """The line the bootstrap stub reads before the source: its length and its digest.
+
+    Spec "Channels": the digest is the first 16 bytes of blake2b in hexadecimal, from
+    ``hashlib`` so the stub needs nothing installed.
+    """
+    import hashlib
+
+    digest = hashlib.blake2b(body, digest_size=16).hexdigest()
+    return b"%d %s\n" % (len(body), digest.encode("ascii"))
+
+
 _BODY = r'''
 import hashlib, io, queue, sys, tarfile, time, traceback
 

{letify-2.5.0 → letify-2.5.2}/letify/providers/kaggle.py

@@ -1006,7 +1006,11 @@ class KaggleChannel(FramedChannel):
     text_frames = True
 
     #: Bytes handed to the bridge per write, matching the Modal channel.
-    WRITE_LIMIT = 1 << 20
+    #: Bytes per base64 line. Spec "Kaggle Jupyter Server session": a kernel carries one
+    #: line as one input reply, so the 108 KB worker source went as one reply of 145 KiB.
+    #: 36 KiB is a multiple of three, so every line decodes on its own, and it is the limit
+    #: Channels already states for a Modal sandbox, for the same reason.
+    WRITE_LIMIT = 36 * 1024
 
     def __init__(
         self, command: list[str], env: dict[str, str], *, name: str, session: Session

{letify-2.5.0 → letify-2.5.2}/letify/providers/kaggle_adapter.py

@@ -31,10 +31,21 @@ UNREACHABLE = 4
 #: The stub the shim starts the worker with, the one Channels describes: a byte count line,
 #: then that many bytes of source.
 STUB = (
-    "import sys;"
+    "import sys,hashlib;"
     "b=sys.stdin.buffer;"
-    "n=int(b.readline());"
-    "exec(compile(b.read(n).decode(),'letify-worker','exec'))"
+    "h=b.readline().split();"
+    "n=int(h[0]);"
+    "s=b.read(n);"
+    # Spec "Channels": a source cut or shifted anywhere compiles as whatever construct the
+    # damage landed inside, or runs and exits without serving. The count catches a cut and
+    # the digest catches a shift, which keeps the count intact.
+    "len(s)==n or sys.exit("
+    "'the letify worker source arrived short: %d of %d bytes'%(len(s),n));"
+    "d=hashlib.blake2b(s,digest_size=16).hexdigest();"
+    "d==h[1].decode() or sys.exit("
+    "'the letify worker source arrived corrupted: %d bytes, digest %s, expected %s'"
+    "%(len(s),d,h[1].decode()));"
+    "exec(compile(s.decode(),'letify-worker','exec'))"
 )
 
 #: The cell that keeps the worker alive. It reads base64 lines with input(), because that is
@@ -67,7 +78,13 @@ while True:
     try:
         _worker.stdin.write(base64.b64decode(_text))
         _worker.stdin.flush()
-    except (OSError, ValueError):
+    except ValueError:
+        sys.stderr.write(
+            "the letify shim could not decode a line of %%d characters\\n" %% len(_text)
+        )
+        sys.stderr.flush()
+        break
+    except OSError:
         break
 
 try:

{letify-2.5.0 → letify-2.5.2}/letify/remoting/device/client.py

@@ -99,9 +99,21 @@ class Pending:
 
 
 #: Passed to ``python -c`` to start the worker: read a length-prefixed source, execute it.
+#: Spec "Channels": the count catches a cut and the digest catches a shift, which keeps the
+#: count intact, so neither failure reaches the compiler as a syntax error.
 BOOTSTRAP = (
-    "import sys;n=int(sys.stdin.buffer.readline());"
-    "exec(compile(sys.stdin.buffer.read(n),'letify-device','exec'))"
+    "import sys,hashlib;"
+    "b=sys.stdin.buffer;"
+    "h=b.readline().split();"
+    "n=int(h[0]);"
+    "s=b.read(n);"
+    "len(s)==n or sys.exit("
+    "'the letify device source arrived short: %d of %d bytes'%(len(s),n));"
+    "d=hashlib.blake2b(s,digest_size=16).hexdigest();"
+    "d==h[1].decode() or sys.exit("
+    "'the letify device source arrived corrupted: %d bytes, digest %s, expected %s'"
+    "%(len(s),d,h[1].decode()));"
+    "exec(compile(s,'letify-device','exec'))"
 )
 
 
@@ -1089,7 +1101,9 @@ def connect(
         target=client._drain_stderr, args=(process.stderr,), name=f"{name}-stderr", daemon=True
     ).start()
     try:
-        transport.raw(b"%d\n" % len(source) + source)
+        from ...protocol.worker import count_line
+
+        transport.raw(count_line(source) + source)
         client.start()
     except (TransportClosed, RuntimeLost) as exc:
         process.kill()

{letify-2.5.0 → letify-2.5.2}/letify/runtime/channel.py

@@ -654,14 +654,14 @@ class FramedChannel(Channel):
 
     def _send_worker(self) -> None:
         """Hand the worker source to the bootstrap stub: a byte count line, then the source."""
-        from ..protocol.worker import source
+        from ..protocol.worker import count_line, source
 
         connection = self._connection
         assert connection is not None
         data = source(text_frames=self.text_frames).encode("utf-8")
         connection.hello = None
         try:
-            connection.sender.raw(b"%d\n" % len(data) + data)
+            connection.sender.raw(count_line(data) + data)
         except OSError:
             # The worker is already gone. Waiting for its hello reports why.
             pass

{letify-2.5.0 → letify-2.5.2}/letify-core/Cargo.lock

@@ -138,7 +138,7 @@ dependencies = [
 
 [[package]]
 name = "letify-agent"
-version = "2.5.0"
+version = "2.5.2"
 dependencies = [
  "letify-wire",
  "libloading",
@@ -146,7 +146,7 @@ dependencies = [
 
 [[package]]
 name = "letify-driver"
-version = "2.5.0"
+version = "2.5.2"
 dependencies = [
  "letify-wire",
 ]
@@ -164,7 +164,7 @@ dependencies = [
 
 [[package]]
 name = "letify-wire"
-version = "2.5.0"
+version = "2.5.2"
 
 [[package]]
 name = "libc"

{letify-2.5.0 → letify-2.5.2}/letify-core/Cargo.toml

@@ -8,7 +8,7 @@ resolver = "3"
 members = ["letify-wire", "letify-driver", "letify-agent", "letify-quic"]
 
 [workspace.package]
-version = "2.5.0"
+version = "2.5.2"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/DarkPyonix/letify"

{letify-2.5.0 → letify-2.5.2}/letify-ext/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "letify-status",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "letify-status",
-      "version": "2.5.0",
+      "version": "2.5.2",
       "license": "SEE LICENSE IN LICENSE",
       "devDependencies": {
         "@types/node": "^18.19.0",

{letify-2.5.0 → letify-2.5.2}/letify-ext/package.json

@@ -2,7 +2,7 @@
   "name": "letify-status",
   "displayName": "letify Status",
   "description": "letify quota and GPU activity in the status bar, read from the letify CLI.",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "publisher": "darkpyonix",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

{letify-2.5.0 → letify-2.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "letify"
-version = "2.5.0"
+version = "2.5.2"
 description = "Declarations that become infrastructure."
 readme = "README.md"
 requires-python = ">=3.11"

{letify-2.5.0 → letify-2.5.2}/tests/fake_kaggle_adapter.py

@@ -63,13 +63,9 @@ except (urllib.error.URLError, OSError) as exc:
 # The cell a real bridge executes carries a shim, because a kernel answers input() and not a
 # binary read. Here the same shape is a subprocess whose standard input and output are pipes:
 # the bridge copies lines in and out, exactly as it would copy them to input_request replies
-# and from stream messages.
-STUB = (
-    "import sys;"
-    "b=sys.stdin.buffer;"
-    "n=int(b.readline());"
-    "exec(compile(b.read(n).decode(),'letify-worker','exec'))"
-)
+# and from stream messages. The stub is the real one rather than a copy: a copy of it drifted
+# from the real stub when the count line gained a digest, and the drift read as a dead worker.
+from letify.providers.kaggle_adapter import STUB  # noqa: E402
 
 worker = subprocess.Popen(
     [sys.executable, "-u", "-c", STUB],

{letify-2.5.0 → letify-2.5.2}/tests/test_kaggle.py

@@ -1649,3 +1649,113 @@ def test_a_gap_that_never_clears_stops_blocking_the_account(
         time.sleep = monkeypatched
 
     assert sum(slept) <= 40.0, f"waited {sum(slept):.0f} s, over four times the interval"
+
+
+def test_the_stub_refuses_a_worker_source_that_arrived_short() -> None:
+    """Spec "Channels": a cut program fails as a SyntaxError that hides the cause.
+
+    KICT reported a Kaggle session dying with "unterminated triple-quoted string literal"
+    inside the worker source. A truncated source compiles as whatever construct the cut
+    landed inside, so the stub checks the count it was given instead.
+    """
+    import subprocess
+
+    from letify.protocol.worker import BOOTSTRAP, count_line, source
+
+    body = source().encode("utf-8")
+    # The count says the whole source; the pipe carries all but the last 284 bytes.
+    done = subprocess.run(
+        [sys.executable, "-u", "-c", BOOTSTRAP],
+        input=count_line(body) + body[:-284],
+        capture_output=True,
+        timeout=120,
+    )
+    assert b"arrived short" in done.stderr, done.stderr[-2000:]
+    assert str(len(body)).encode() in done.stderr
+    assert b"SyntaxError" not in done.stderr
+
+
+def test_the_shim_says_which_line_it_could_not_decode() -> None:
+    """Spec "Kaggle Jupyter Server session": a line cut in transit ended the shim silently.
+
+    It closed the worker's standard input, so the worker compiled whatever had arrived and
+    the only report was the worker's own SyntaxError.
+    """
+    import subprocess
+
+    from letify.providers.kaggle_adapter import SHIM, STUB
+
+    cell = SHIM % {"stub": STUB}
+    done = subprocess.run(
+        [sys.executable, "-u", "-c", cell],
+        # Five base64 characters, which is not a whole group, so decoding raises.
+        input=b"abcde\n",
+        capture_output=True,
+        timeout=120,
+    )
+    assert b"could not decode a line" in done.stderr, done.stderr[-2000:]
+    assert b"of 5 characters" in done.stderr
+
+
+def test_a_kernel_line_stays_inside_the_limit_a_kernel_carries() -> None:
+    """Spec "Kaggle Jupyter Server session": at most 36 KiB per line, so no line is 145 KiB.
+
+    The worker source is about 108 KB, which went as one base64 reply of about 145 KiB.
+    Channels states the same 36 KiB limit for a Modal sandbox, for the same reason.
+    """
+    import base64
+
+    from letify.protocol.worker import source
+    from letify.providers.kaggle import KaggleChannel
+
+    assert KaggleChannel.WRITE_LIMIT <= 36 * 1024
+    # A multiple of three bytes, so every line decodes on its own.
+    assert KaggleChannel.WRITE_LIMIT % 3 == 0
+    # 48 KiB of base64 plus the newline, which is the bound Channels states for Modal.
+    assert len(base64.b64encode(b"x" * KaggleChannel.WRITE_LIMIT)) <= 48 * 1024
+    assert len(source().encode("utf-8")) > KaggleChannel.WRITE_LIMIT, (
+        "the source must cross as several lines, or this pins nothing"
+    )
+
+
+def test_the_stub_refuses_a_worker_source_whose_bytes_were_shifted() -> None:
+    """Spec "Channels": the count alone misses a loss and a gain of the same length.
+
+    KICT's Kaggle session reported an unterminated triple-quoted string at generated line
+    3077, which holds `job = _JOBS.get()` in that build and no quote at all, so the source
+    was shifted rather than cut. A shift keeps the byte count intact.
+    """
+    import subprocess
+
+    from letify.protocol.worker import BOOTSTRAP, count_line, source
+
+    body = source().encode("utf-8")
+    # Four bytes lost from the middle and four gained at the end: the same length.
+    shifted = body[:50_000] + body[50_004:] + b"\n" * 4
+    assert len(shifted) == len(body)
+    done = subprocess.run(
+        [sys.executable, "-u", "-c", BOOTSTRAP],
+        input=count_line(body) + shifted,
+        capture_output=True,
+        timeout=120,
+    )
+    assert b"arrived corrupted" in done.stderr, done.stderr[-2000:]
+    assert b"SyntaxError" not in done.stderr
+
+
+def test_a_worker_source_that_arrives_whole_still_runs() -> None:
+    """Spec "Channels": the check costs the good case nothing, so the worker still starts."""
+    import subprocess
+
+    from letify.protocol.worker import BOOTSTRAP, count_line, source
+
+    body = source().encode("utf-8")
+    done = subprocess.run(
+        [sys.executable, "-u", "-c", BOOTSTRAP],
+        input=count_line(body) + body,
+        capture_output=True,
+        timeout=120,
+    )
+    # The worker announces itself and then reads, so closing its input ends it cleanly.
+    assert b"arrived" not in done.stderr, done.stderr[-2000:]
+    assert done.stdout, "the worker said nothing, so it never started"

{letify-2.5.0 → letify-2.5.2}/tests/test_protocol.py

@@ -187,10 +187,10 @@ def test_a_worker_call_whose_body_imports_letify_while_running_names_the_reason(
 
         return inside.session_cache("value", lambda: 1)
 
-    from letify.protocol.worker import SOURCE
+    from letify.protocol.worker import SOURCE, count_line
 
     source = SOURCE.encode()
-    stdin = bytearray(b"%d\n" % len(source) + source)
+    stdin = bytearray(count_line(source) + source)
     sender = wire.Sender(lambda view: stdin.extend(view) or view.nbytes)
     head, buffers = codec.dumps_call_parts(work, (), {})
     sender.message(wire.REQUEST, 1, {"op": "call", "payload": head, "buffers": buffers})

{letify-2.5.0 → letify-2.5.2}/tests/test_providers.py

@@ -1457,7 +1457,7 @@ def test_a_sandbox_channel_sends_the_worker_once_and_then_framed_requests(
 ) -> None:
     import base64
 
-    from letify.protocol.worker import SOURCE
+    from letify.protocol.worker import SOURCE, count_line
     from letify.protocol.worker import source as worker_source
 
     provider = provider_of(Modal, "m")
@@ -1471,7 +1471,7 @@ def test_a_sandbox_channel_sends_the_worker_once_and_then_framed_requests(
         written = b"".join(base64.b64decode(r["data"]) for r in fake_modal.requests("write"))
         # The worker source went out exactly once, behind its byte count line, with the flag
         # that makes the sandbox write its frames as base64 lines.
-        assert written.count(b"%d\n" % len(source) + source) == 1
+        assert written.count(count_line(source) + source) == 1
         assert SOURCE.encode() not in written
     finally:
         provider.stop(runtime)