letify 2.5.0__tar.gz → 2.5.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.5.0
+Version: 2.5.1
 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.1}/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,7 @@ 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 stub compares what it read against the count and raises `SystemExit` with `the letify worker source arrived short: <read> of <expected> bytes` rather than compiling a truncated program, because a program cut anywhere fails as a `SyntaxError` at whatever construct the cut landed inside, which names the symptom and hides the cause.
 
 ### Frames <!-- id: frames -->
 

{letify-2.5.0 → letify-2.5.1}/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.1"
 
 
 def fetch(tensor):  # type: ignore[no-untyped-def]

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

@@ -40,7 +40,12 @@ BOOTSTRAP = (
     "import sys;"
     "b=sys.stdin.buffer;"
     "n=int(b.readline());"
-    "exec(compile(b.read(n).decode(),'letify-worker','exec'))"
+    "s=b.read(n);"
+    # Spec "Channels": a source cut anywhere compiles as whatever construct the cut landed
+    # inside, or runs and exits without serving, so the count is checked before it is run.
+    "len(s)==n or sys.exit("
+    "'the letify worker source arrived short: %d of %d bytes'%(len(s),n));"
+    "exec(compile(s.decode(),'letify-worker','exec'))"
 )
 
 _BODY = r'''

{letify-2.5.0 → letify-2.5.1}/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.1}/letify/providers/kaggle_adapter.py

@@ -34,7 +34,12 @@ STUB = (
     "import sys;"
     "b=sys.stdin.buffer;"
     "n=int(b.readline());"
-    "exec(compile(b.read(n).decode(),'letify-worker','exec'))"
+    "s=b.read(n);"
+    # Spec "Channels": a source cut anywhere compiles as whatever construct the cut landed
+    # inside, or runs and exits without serving, so the count is checked before it is run.
+    "len(s)==n or sys.exit("
+    "'the letify worker source arrived short: %d of %d bytes'%(len(s),n));"
+    "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 +72,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.1}/letify-core/Cargo.lock

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

{letify-2.5.0 → letify-2.5.1}/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.1"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/DarkPyonix/letify"

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

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

{letify-2.5.0 → letify-2.5.1}/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.1",
   "publisher": "darkpyonix",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

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

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

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

@@ -1649,3 +1649,70 @@ 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, 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=b"%d\n" % len(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"
+    )