letify 2.7.1__tar.gz → 2.8.0__tar.gz

{letify-2.7.1 → letify-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.7.1
+Version: 2.8.0
 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.7.1 → letify-2.8.0}/PROJECT.md

@@ -190,6 +190,15 @@ cache.fetch_checkpoint("run-1", target)
 cache.resume(runtime, "run-1", path)   # put the newest one inside a session
 ```
 
+### Handoffs
+
+```python
+letify.stash("ckpt", ckpt_dir)         # put a file or directory on the machine's Drive store
+letify.unstash("ckpt", ckpt_dir)       # put it back, or None when no handoff has that name
+```
+
+Both work in the local process and inside a shipped function, on any provider. They need `drive_login` and `drive_project` in the machine configuration and raise `ConfigError` without them. On a one-shot channel, which has no stream back to the local process, they raise `UnsupportedMode` naming the provider. `letify.fetch(tensor)` is a different call and still reads a tensor back.
+
 ### Types
 
 | Name | Is |
@@ -200,6 +209,7 @@ cache.resume(runtime, "run-1", path)   # put the newest one inside a session
 | `Env` | an environment declaration |
 | `Volume` | a content addressed store on a provider |
 | `session_cache` | a value built once per session, keyed by name |
+| `stash`, `unstash` | a named file or directory handed between providers through Drive |
 | `Blob`, `RemoteFile` | references to something that lives in a session |
 | `Function` | what the decorator returns |
 

{letify-2.7.1 → letify-2.8.0}/docs/SPEC.md

@@ -781,6 +781,7 @@ The protocol is one JSON object per line. letify sends `{"id": <int>, "op": <nam
 | `tunnel` | `sandbox`, `port` | `{"host": <text>, "port": <int>, "tls": <bool>}`. The address that reaches `port` inside the sandbox, from `Sandbox.tunnels()`. `tls` is true when the connection has to be made with TLS, which an encrypted port needs |
 | `write` | `sandbox`, `data` | `null`. `data` is base64 of at most 1 MiB. Writes the decoded bytes to the sandbox's standard input and drains it. Modal refuses a write that would buffer more than 2 MiB, so the channel splits a larger frame into `write` requests of 1 MiB, in order |
 | `read_until` | `sandbox`, `prefixes` | `{"lines": [...], "eof": <bool>}`. The sandbox's stdout lines up to and including the first that starts with one of `prefixes`, or every line left when the stream ends |
+| `poll` | `sandbox` | the sandbox's exit code once it has ended, or `null` while it runs. Polls this adapter's own sandbox, or one found with `modal.Sandbox.from_id`. The provider sends it from a second adapter process and closes that process afterwards |
 | `terminate` | `sandbox` | `null`. Also ends a sandbox this adapter did not create, found by id |
 | `billing_summary` | none | `{"metered_cost": <text>, "billed_cost": <text>, "credits": <text>, "start": <Unix seconds>, "end": <Unix seconds>}` for the current month, from `modal.Workspace.billing.summary()`. Amounts are decimal text in USD. `credits` is the `Credits` adjustment, negative when credit was applied |
 | `volume_put` | `volume`, `version`, `path`, `data` | `null`. `data` is base64 |
@@ -987,7 +988,7 @@ A session is never a value the caller holds. Pooling, reuse and teardown are dec
 
 1. **The call.** A session ends when the call that started it finishes. Calls that overlap in time share that span: a session released by one call while another is still running stays up for the next call that matches it, and ends when the last overlapping call finishes.
 2. **A `keep_alive` block.** Inside `with let.keep_alive():` a session is not ended when its call finishes, so the next call in the block that matches its instance and environment reuses it and pays no session start, which is minutes on Colab. When the block exits, every idle session ends; one still serving a call ends when that call finishes. Blocks nest, and only the outermost exit ends anything.
-3. **The lease.** The local process renews a deadline inside the session every 30 seconds, and the worker exits on its own if the deadline passes. The grace period is 300 seconds, so a brief network drop does not kill a training run. A renewal that fails because the session itself is gone, `RuntimeLost`, stops the renewer; the pool notices on its next call. Any other failure, such as a renewal reply delayed behind a large transfer, logs a warning on standard error and is retried on the next interval rather than stopping the renewer. The protocol answers `lease` on the thread that reads frames rather than the one running the current call, so a renewal is not queued behind a checkpoint upload or download of any size; raising the grace period further would only lengthen how long a process that really was killed outright goes on billing, for no corresponding benefit.
+3. **The lease.** The local process renews a deadline inside the session every 30 seconds, and the worker exits on its own if the deadline passes. The grace period is 300 seconds, so a brief network drop does not kill a training run. A renewal that fails because the session itself is gone, `RuntimeLost`, stops the renewer; the pool notices on its next call. Any other failure, such as a renewal reply delayed behind a large transfer, logs a warning on standard error and is retried on the next interval rather than stopping the renewer. Before that retry, the local process asks the provider whether the runtime still exists. A provider that can tell answers ended, running or unknown; Modal answers by polling the sandbox from a second adapter process, because the adapter carrying the call may be blocked. An ended runtime turns the failure into `RuntimeLost`: the renewer stops, the runtime is discarded with reason `runtime_ended`, and a call waiting on it raises `RuntimeLost` saying `the Modal sandbox ended (exit code <n>) while the call was running`, rather than waiting for a reply that cannot come, because a data connection to a sandbox that has ended can stay open with no end-of-stream. A provider that cannot tell, or a poll that itself fails, answers unknown, and the renewer retries as before. The protocol answers `lease` on the thread that reads frames rather than the one running the current call, so a renewal is not queued behind a checkpoint upload or download of any size; raising the grace period further would only lengthen how long a process that really was killed outright goes on billing, for no corresponding benefit.
 
 Keeping is a block rather than a declaration argument because it describes a stretch of the caller's program, not a property of one function: the same function is kept in one script and not in another. A block also has a visible end, so no session outlives the code that asked for it.
 
@@ -1266,6 +1267,18 @@ The runtime keeps a file blob cache at `<workspace root>/data/blobs/<first two h
 
 `bucket = "<name>"` on an account names a Cloud Storage bucket for its data, reached as the `gcs` backend describes. `bucket_prefix` sets the object prefix, `letify` by default, and `bucket_endpoint` and `sts_endpoint` point the client and the token exchange elsewhere. A persistent account ignores `bucket`.
 
+Google Drive is a store, not a volume: it does not attach to a runtime as a disk, it belongs to no provider, and every provider that can reach `googleapis.com` over HTTPS reaches the same one. It is declared once per machine with two top-level settings in `~/.letify/config.toml`: `drive_login = "<alias>"` names the account whose Google login letify uses, and `drive_project = "<project id>"` names the Google Cloud project the Drive API bills its quota to, which has to have the Drive API enabled. Both are needed; either alone is refused naming the other. `drive_endpoint` points the client and the runtime at another Drive API host, for a test. The named account's stored token has to carry the `drive.file` scope, which the Colab login already does, so no new login is asked for. `drive.file` lets letify read and write only the files it created, and never the rest of the person's Drive.
+
+Drive is fast for a few large files and slow for many small ones, which decides what letify puts there. From a Colab runtime and a Kaggle runtime, one 1 GiB file uploaded at 38.1 and 71.6 MiB/s and downloaded at 176.6 and 182.9 MiB/s, and fifty 1 MiB files took 109.3 s and 87.4 s, about two seconds each, because every Drive file is an API call of its own. So letify puts environment archives there, one file per environment, and never project data, which is often many small files and stays on the channel or the bucket.
+
+Letify keeps its files in a folder named `letify` at the root of that Drive, one file per blob named by its digest, and each ref as a small file named `ref <name>` holding the digest. The runtime moves an archive itself in both directions, so it never crosses the client's link: after a sync the worker uploads the packed archive with a resumable upload, and a later session's worker downloads it. For a download the client mints a short-lived access token from the stored refresh token and sends it with the request; the worker uses it for that request only and does not write it to disk. For an upload the client creates the resumable session itself and sends the worker only the session URL, which authorizes that upload alone, so the worker never holds a token for it. A Drive request that fails is not retried into a slower path: a failed restore makes the session sync and say `letify: <runtime>: not using the Drive store (<reason>); syncing`, and a failed pack, which comes after the sync, leaves nothing cached and says `letify: <runtime>: not using the Drive store (<reason>); not caching the environment`.
+
+An ephemeral provider uses the Drive store for its environment archive when the machine declares one and the account sets no `bucket`, which keeps precedence. A provider whose environment survives the session on its own disk or volume does not use it. An archive on Drive is an uncompressed tar, because compression was most of the cost: on a Kaggle runtime, packing a 5.5 GB environment as tar.gz and uploading it took about 12 minutes, against an upload of roughly 77 s for the uncompressed tree at the measured rate.
+
+Whether an archive is worth it is measured, not assumed, because a provider with a fast package index can build faster than it restores. On a Kaggle runtime the same 5.5 GB environment built in 35.4 s and restored from Drive in about 90 s. So after a sync letify packs only when the build took longer than the archive would take to restore, estimated as the project directory's size over 176 MiB/s, the slower Drive download measured, plus the same size over 170 MB/s, the extraction rate measured on a sandbox disk. The record beside the archive keeps the build seconds and, once a session has restored from it, the restore seconds that session measured; a later session restores only while the measured restore is shorter than the measured build, and syncs otherwise, saying `letify: <runtime>: syncing rather than restoring from Drive, because a restore took <s> s against a <s> s build`.
+
+Drive's own limits apply. The archive counts against the Google account's storage, which is the person's own plan. Google documents a daily upload limit of 750 GB per user for Google Workspace accounts, independent of the storage plan; an environment archive is a few gigabytes, so letify does not approach it. Standard use of the Drive API costs nothing, and Google documents that exceeding its request quota is planned to be charged to the project's billing account later in 2026; letify's requests are a handful per session against a quota of 325,000 units per user per minute.
+
 The file blob cache lives inside the runtime's container, so it disappears when the container does. A later container on the same ephemeral provider can therefore fetch from an object store outside the container or from the local process, and from nothing else, which is why `bucket` exists. The two problems are answered separately: the bucket removes the repeated upload of a dataset the account has already sent once, and the send order with the background sender removes the wait before the first step. Neither replaces the other.
 
 Over the channel, a file travels in pieces of at most 8 MiB, each one a `data_put` request carrying the piece as an out-of-band `DATA` frame, its offset, and whether it is the file's last. Every piece of a call, across all of its files, is sent on one stream in send order, and the local process does not wait for a reply between two pieces: it keeps at most 8 pieces unanswered, which is 64 MiB in flight, as Waiting for a reply describes. So the link carries the next piece while the worker writes the one before, and a small file costs no round trip of its own. The worker appends each piece to `<digest>.partial.<pid>` in arrival order and answers it, and after the last piece of a file checks the digest of the whole file and renames it into the cache. A digest that does not match fails that piece's reply, which raises `RuntimeFailure` on the local side, and nothing is renamed. The local process reads every outstanding reply before it sends the call, so the first wave is placed when the body starts.
@@ -1531,6 +1544,29 @@ The access token is looked up in this order, the first that answers wins:
 
 A token is reused until 60 s before it expires. A service account key file is refused with its reason, because exchanging one needs an RSA signature the standard library cannot make; `gcloud auth activate-service-account` followed by rule 3 covers that case. When no rule answers, the backend raises `ProviderUnavailable` for `gcs` saying that no Google login was found and naming `gcloud auth application-default login` and `GOOGLE_OAUTH_ACCESS_TOKEN`.
 
+### Named handoffs on the Drive store <!-- id: drive-handoff -->
+
+> `letify.stash(name, path)` puts a file or directory on the machine's Drive store under a name, and `letify.unstash(name, path)` puts it back, in a later call on any provider or in the local process.
+
+A handoff is what a volume cannot be: a value written on one provider and read on another, such as a checkpoint written on Kaggle and resumed on `dept_gpu`. A volume belongs to one provider and stays attached to it, so letify keeps the two apart. `stash` and `unstash` take no provider and no volume.
+
+`stash(name, path)` packs `path`, a file or a directory, into an uncompressed tar whose members are relative to `path`'s parent, so the tar holds the one entry `path`'s base name. Its digest, letify's content hash as the blob store uses it, names the blob in the `letify` folder, and the ref `ref stash/<name>` holds that digest. It returns the digest once the upload has finished and the ref is written. Stashing a name again moves the ref, and the blob the ref named before is deleted unless another `stash/` ref still names it. An upload of the same digest that Drive already holds sends nothing. The tar keeps each member's modification time, so a file rewritten with the same bytes gives a new digest.
+
+`unstash(name, path)` reads the ref, downloads the blob, checks its digest, and unpacks it so that the tar's one entry lands at `path`, replacing what `path` held. It returns `path` as a `pathlib.Path`. When no ref `stash/<name>` exists it returns `None` and changes nothing, so `if letify.unstash("ckpt", ckpt_dir) is None:` starts from scratch. A digest that does not match raises `RuntimeFailure` and leaves `path` untouched.
+
+A name is 1 to 128 characters of letters, digits, `.`, `_` and `-`, and does not start with `.`; anything else raises `ValueError` naming the rule. Names are shared by every project on the machine's Drive store, so a project that wants its own space puts its name in the handoff name.
+
+The name `unstash` is not `fetch`, because `letify.fetch(tensor)` already reads a tensor back in `host=local`.
+
+Both run in two places with the same result:
+
+- **In the local process**, the client moves the bytes itself with the `DriveBackend` of Google Drive is a store, not a volume.
+- **Inside a shipped function**, the worker moves the bytes between the runtime and Drive and they never cross the client's link. The worker asks the local process for a grant with a one-way request on a reserved stream, as `all_reduce` asks for a peer table, and the local process answers with the light op `drive_grant`: for `stash`, the existing digest or a resumable upload session URL for the archive's size, which the local process creates as Google Drive is a store, not a volume describes; for `unstash`, the blob's media URL with the short-lived request headers, or a reply that the name has no ref. After a `stash` upload the worker reports the Drive file id and the local process writes the ref and deletes the replaced blob. The worker holds no refresh token and writes no header to disk.
+
+A body run on a one-shot channel, which has no stream back to the local process, cannot ask for a grant, so `stash` and `unstash` there raise `UnsupportedMode` naming the provider rather than reading the runtime's own configuration.
+
+When the machine declares no Drive store, both raise `ConfigError` naming `drive_login` and `drive_project`. letify never falls back to another store or to the local disk. A Drive request that fails raises `RuntimeFailure` naming the Drive status and the name, and the function body decides whether to carry on.
+
 ## Environment
 
 > An `Env` is a declaration keyed by the project's uv files, not a built image. Every remote runtime builds it with `uv sync` into a project `.venv` and runs the worker with that `.venv`'s Python.

{letify-2.7.1 → letify-2.8.0}/docs/guide/04-environments-and-data.md

@@ -114,13 +114,18 @@ Chosen by the provider, so your declaration does not mention one.
 
 > 🌏 **For Colab, use a multi-region bucket such as `US`.** You cannot choose where a Colab runtime lands, and a multi-region bucket avoids a cross-region charge on every read. Set a billing alert while you are there.
 
-## Why not Google Drive
+## Google Drive holds environment archives, not data
 
-Drive looks like a disk when mounted, which is the source of the confusion. It is a consumer file service reached one file at a time, and every file access is an HTTP request of tens to hundreds of milliseconds regardless of the file's size.
+Drive is reached one file at a time, and every file access is an HTTP request of tens to hundreds of milliseconds regardless of the file's size. 50,000 images at 100 ms each is over an hour of pure input and output per epoch, with the GPU idle. So letify never puts project data on Drive.
 
-The arithmetic: 50,000 images at 100 ms each is over an hour of pure input and output per epoch, with the GPU idle at 10 to 20% utilization the whole time. The same data as one archive, copied once and unpacked locally, is under a minute.
+One large file is a different case. Measured from Kaggle, Drive downloads at 183 MiB/s and accepts uploads at 72 MiB/s. letify therefore uses Drive for one thing: the packed environment of an ephemeral provider that has no `bucket`. Declare it once for the machine, at the top of `~/.letify/config.toml`:
 
-Drive is a fine warehouse. It is not a working disk. If you already keep data there, pull one archive at session start rather than reading from it during training.
+```toml
+drive_login = "colab_pro"        # the account whose Google login carries the drive.file scope
+drive_project = "letify-511514"  # a Google Cloud project with the Drive API enabled
+```
+
+Either setting alone is refused. A persistent provider ignores both, and an account with `bucket` keeps its bucket. The archive is packed only when the environment took longer to build than it would take to download and unpack, and a later session syncs instead of restoring once a recorded restore has taken longer than the build. Standard Drive API use carries no charge, and the archive counts against your Drive storage.
 
 ## Data your call reads
 

{letify-2.7.1 → letify-2.8.0}/docs/guide/ko/04-/355/231/230/352/262/275/352/263/274-/353/215/260/354/235/264/355/204/260.md

@@ -114,13 +114,18 @@ cache = lab.volume("scratch", backend="filesystem", root="/mnt/data/letify")
 
 > 🌏 **Colab에서는 `US` 같은 멀티리전 버킷을 쓰세요.** Colab 런타임이 어디 뜨는지 고를 수 없고, 멀티리전이면 읽을 때마다 리전 간 요금이 붙는 것을 막아줍니다. 그 참에 결제 알림도 걸어두세요.
 
-## Google Drive를 안 쓰는 이유
+## Google Drive는 데이터가 아니라 환경 아카이브를 담습니다
 
-드라이브는 마운트하면 디스크처럼 보이고, 거기서 오해가 생깁니다. 실제로는 파일 단위로 접근하는 소비자용 파일 서비스이고, 파일 크기와 무관하게 접근마다 수십에서 수백 밀리초의 HTTP 요청이 나갑니다.
+드라이브는 파일 단위로 접근하고, 파일 크기와 무관하게 접근마다 수십에서 수백 밀리초의 HTTP 요청이 나갑니다. 이미지 5만 장에 100ms씩이면 epoch당 순수 입출력만 한 시간이 넘고 그동안 GPU는 놉니다. 그래서 letify는 프로젝트 데이터를 드라이브에 두지 않습니다.
 
-계산해보면, 이미지 5만 장에 100ms씩이면 epoch당 순수 입출력만 한 시간이 넘고 그동안 GPU 사용률은 10~20%입니다. 같은 데이터를 아카이브 하나로 한 번 받아 로컬에 풀면 1분 미만입니다.
+큰 파일 하나는 다릅니다. Kaggle에서 재보면 드라이브는 183 MiB/s로 내려받고 72 MiB/s로 올립니다. 그래서 letify는 드라이브를 한 가지에만 씁니다. `bucket`이 없는 휘발성 프로바이더의 묶은 환경입니다. 머신에 한 번, `~/.letify/config.toml` 맨 위에 선언합니다.
 
-드라이브는 창고로는 괜찮습니다. 작업 디스크가 아닙니다. 이미 거기 데이터가 있다면 학습 중에 읽지 말고 세션 시작에 아카이브 하나를 당겨오세요.
+```toml
+drive_login = "colab_pro"        # drive.file 권한이 있는 Google 로그인을 가진 계정
+drive_project = "letify-511514"  # Drive API를 켠 Google Cloud 프로젝트
+```
+
+둘 중 하나만 있으면 거부합니다. persistent 프로바이더는 둘 다 무시하고, `bucket`이 있는 계정은 버킷을 그대로 씁니다. 아카이브는 환경 빌드가 내려받아 푸는 시간보다 오래 걸렸을 때만 묶고, 기록된 복원 시간이 빌드보다 길었다면 다음 세션은 복원 대신 동기화합니다. 표준 Drive API 사용은 요금이 없고, 아카이브는 드라이브 저장 용량을 차지합니다.
 
 ## 호출이 읽는 데이터
 

{letify-2.7.1 → letify-2.8.0}/letify/__init__.py

@@ -27,6 +27,8 @@ the base install and a provider whose package is missing reports itself unavaila
 
 from __future__ import annotations
 
+import os
+from pathlib import Path
 from typing import Final
 
 from .declare.cache import session_cache
@@ -66,7 +68,7 @@ distributed: Final = Host.distributed
 # The enum class stays importable from letify.declare.instance for letify's own use.
 del Host
 
-__version__ = "2.7.1"
+__version__ = "2.8.0"
 
 
 def fetch(tensor):  # type: ignore[no-untyped-def]
@@ -80,6 +82,27 @@ def fetch(tensor):  # type: ignore[no-untyped-def]
     return queue_fetch(tensor)
 
 
+def stash(name: str, path: str | os.PathLike[str]) -> str:
+    """Put a file or directory on the machine's Drive store under ``name``.
+
+    Returns the digest once the upload has finished and the ref is written. A later call on
+    any provider, or the local process, gets it back with ``unstash(name, path)``.
+    """
+    from .store.handoff import stash as stash_handoff
+
+    return stash_handoff(name, path)
+
+
+def unstash(name: str, path: str | os.PathLike[str]) -> Path | None:
+    """Put the handoff ``name`` at ``path``, replacing what was there.
+
+    Returns ``path``, or None when no handoff has that name, in which case nothing changed.
+    """
+    from .store.handoff import unstash as unstash_handoff
+
+    return unstash_handoff(name, path)
+
+
 __all__ = [
     "AnyInstance",
     "Blob",
@@ -108,12 +131,15 @@ __all__ = [
     "__version__",
     "all_reduce",
     "distributed",
+    "fetch",
     "local",
     "local_steps",
     "mean",
     "rank",
     "remote",
     "session_cache",
+    "stash",
     "sum",
+    "unstash",
     "world_size",
 ]

{letify-2.7.1 → letify-2.8.0}/letify/config/__init__.py

@@ -12,6 +12,7 @@ or the credential lives in the account directory, and the value is resolved when
 from __future__ import annotations
 
 import tomllib
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -91,6 +92,44 @@ def load(path: str | Path | None = None, *, home: bool = True) -> Config:
     return config
 
 
+@dataclass(frozen=True, slots=True)
+class DriveSettings:
+    """The machine's Google Drive store: the login alias, the quota project and the host."""
+
+    login: str
+    project: str
+    endpoint: str | None = None
+
+
+def drive_settings() -> DriveSettings | None:
+    """The Drive store this machine declares at the top level of its configuration, if any.
+
+    Spec "Materializing into a runtime": ``drive_login`` and ``drive_project`` are both
+    needed, and either alone is refused naming the other. ``drive_endpoint`` is optional.
+    """
+    file = config_path()
+    try:
+        settings = _parse(file) if file.is_file() else {}
+    except OSError:
+        settings = {}
+    login = settings.get("drive_login")
+    project = settings.get("drive_project")
+    if not login and not project:
+        return None
+    if not login:
+        raise ConfigError(
+            f"{config_label()} sets drive_project but not drive_login. Set drive_login = "
+            f"'<alias of a Google login>' to keep environment archives in Google Drive."
+        )
+    if not project:
+        raise ConfigError(
+            f"{config_label()} sets drive_login but not drive_project. Set drive_project = "
+            f"'<Google Cloud project id>' with the Drive API enabled."
+        )
+    endpoint = settings.get("drive_endpoint")
+    return DriveSettings(str(login), str(project), str(endpoint) if endpoint else None)
+
+
 def _project_file(path: str | Path | None) -> Path:
     """The project's ``config.toml``, from a ``.letify`` directory, a file, or the default."""
     if path is None:
@@ -157,8 +196,10 @@ __all__ = [
     "GLOBAL_FIELD",
     "RESERVED_ALIASES",
     "Config",
+    "DriveSettings",
     "ProviderConfig",
     "account_directory",
+    "drive_settings",
     "inventory",
     "load",
     "login",

{letify-2.7.1 → letify-2.8.0}/letify/protocol/codec.py

@@ -141,6 +141,18 @@ def _hasher() -> Any:
     return blake3.blake3(max_threads=blake3.blake3.AUTO)
 
 
+def new_hasher() -> Any:
+    """A fresh incremental hasher, the one ``digest_parts`` uses."""
+    return _hasher()
+
+
+def finish_digest(hasher: Any) -> str:
+    """The content address a hasher from ``new_hasher`` has accumulated."""
+    if hasher.name == "blake2b":
+        return str(hasher.hexdigest())
+    return str(hasher.hexdigest(length=16))
+
+
 def digest_parts(parts: Iterable[Any]) -> str:
     """Content address of the concatenation of ``parts``, hashed without joining them.
 
@@ -284,6 +296,8 @@ __all__ = [
     "digest_parts",
     "dumps_call",
     "dumps_call_parts",
+    "finish_digest",
+    "new_hasher",
     "parse",
     "split_output",
     "unwrap",

{letify-2.7.1 → letify-2.8.0}/letify/protocol/driver.py

@@ -30,6 +30,7 @@ _NO_LETIFY = (
     "the project with 'uv add letify' so uv.lock carries it into the runtime."
 )
 _MODULES = {modules_code}
+os.environ["LETIFY_ONE_SHOT"] = {provider!r}
 _WORKSPACE = {workspace_root!r}
 if _MODULES:
     _modules_dir = os.path.join(os.path.expanduser(_WORKSPACE), "modules")
@@ -112,6 +113,7 @@ def build(
     *,
     modules: Sequence[str] = (),
     workspace_root: str = "~/.letify-runtime",
+    provider: str = "this provider",
 ) -> str:
     """Return the script that runs one call and prints its outcome."""
     payload = base64.b64encode(dumps_call(fn, args, kwargs)).decode()
@@ -135,6 +137,7 @@ def build(
         version=PROTOCOL_VERSION,
         modules_code=repr(modules_dict),
         workspace_root=workspace_root,
+        provider=provider,
     )
 
 

{letify-2.7.1 → letify-2.8.0}/letify/protocol/wire.py

@@ -47,6 +47,11 @@ DATA_STREAM = 4
 #: request-reply carrying op "reduce_peers".
 REDUCE_STREAM = 6
 
+#: The stream a function body asks for a Drive grant on, as spec "Named handoffs on the
+#: Drive store" describes. Nothing replies on it either; the client's answer travels as an
+#: ordinary request-reply carrying op "drive_grant".
+DRIVE_STREAM = 8
+
 #: The largest payload of one ``DATA`` frame, so other streams interleave between chunks.
 CHUNK = 8 << 20
 
@@ -615,6 +620,7 @@ __all__ = [
     "CHUNK",
     "DATA",
     "DEVICE_STREAM",
+    "DRIVE_STREAM",
     "HEADER",
     "HELLO",
     "MAGIC",

{letify-2.7.1 → letify-2.8.0}/letify/protocol/worker.py

@@ -1339,6 +1339,38 @@ def _op_reduce_peers(request):
     return {"ok": True, "value": None}
 
 
+#: Guards ``_DRIVE_ANSWERS``, and wakes a ``stash`` or ``unstash`` waiting on an answer.
+_DRIVE_LOCK = threading.Condition()
+
+#: The client's answers to a Drive request, keyed by request id, until the waiting
+#: ``stash`` or ``unstash`` takes them.
+_DRIVE_ANSWERS = {}
+
+
+def _drive_ask(message):
+    """Ask the client for a Drive grant. Nothing replies to this request.
+
+    Mirrors ``_reduce_join``: a one-way request on a reserved stream, answered separately
+    as an ordinary request-reply, op "drive_grant", below.
+    """
+    try:
+        _SENDER.message(REQUEST, DRIVE_STREAM, message)
+    except OSError:
+        pass
+
+
+def _op_drive_grant(request):
+    """The client's answer to a Drive request: a grant, a reply that nothing is there, or a failure.
+
+    The body is blocked waiting for this, so it is answered by the frame reader at once
+    rather than queued behind the call, which is why it is in ``_LIGHT`` below.
+    """
+    with _DRIVE_LOCK:
+        _DRIVE_ANSWERS[request["id"]] = request
+        _DRIVE_LOCK.notify_all()
+    return {"ok": True, "value": None}
+
+
 def _data_state_for(path):
     """The running call a path belongs to, or None."""
     for state in _DATA_CALLS.values():
@@ -2200,7 +2232,7 @@ def _unpack(path, target, links=False):
     interpreter by absolute path.
     """
     os.makedirs(target, exist_ok=True)
-    with tarfile.open(path, "r:gz") as archive:
+    with tarfile.open(path, "r:*") as archive:
         try:
             archive.extractall(target, filter="tar" if links else "data")
         except TypeError:
@@ -2290,6 +2322,8 @@ def _op_pack_blob(request):
     Same archive and member rules as ``pack_dir``, but the archive never exists as one
     bytes object: it is written to a partial file in pieces, and the caller reads it back
     with ``data_stream``. The reply names the directory it used, with ``~`` expanded.
+    The archive is gzip unless the request sets ``gzip`` to false, which writes a plain
+    tar for a store that moves the archive at a disk's speed.
     """
     root = os.path.expanduser(request["path"])
     directory = os.path.expanduser(request["dir"])
@@ -2301,7 +2335,8 @@ def _op_pack_blob(request):
     try:
         with open(partial, "wb") as handle:
             hashed = _HashedFile(handle, hasher)
-            with tarfile.open(fileobj=hashed, mode="w:gz") as archive:
+            mode = "w:gz" if request.get("gzip", True) else "w"
+            with tarfile.open(fileobj=hashed, mode=mode) as archive:
                 archive.add(root, arcname=os.path.basename(root.rstrip("/")), recursive=True)
         digest = hasher.hexdigest() if hasher.name == "blake2b" else hasher.hexdigest(length=16)
         final = _data_file(directory, digest)
@@ -2313,6 +2348,48 @@ def _op_pack_blob(request):
     return {"ok": True, "value": {"digest": digest, "size": hashed.size, "dir": directory}}
 
 
+def _op_push_blob(request):
+    """Upload a blob from the blob cache to a resumable upload session, in pieces.
+
+    The session URL authorizes its own upload, so the request carries no access token.
+    Every piece but the last is a multiple of 256 KiB, as Drive requires, and is answered
+    308 until the last, which is answered with the new file's metadata. The reply names
+    the file id.
+    """
+    import json
+    import urllib.error
+    import urllib.request
+
+    url = request.pop("url")
+    headers = request.pop("headers", None) or {}
+    path = _data_file(os.path.expanduser(request["dir"]), request["digest"])
+    size = os.path.getsize(path)
+    piece = int(request.get("piece") or (64 << 20))
+    remote_id = None
+    with open(path, "rb") as handle:
+        offset = 0
+        while offset < size:
+            block = handle.read(piece)
+            end = offset + len(block)
+            span = "bytes %d-%d/%d" % (offset, end - 1, size)
+            send = urllib.request.Request(url, data=block, method="PUT", headers=headers)
+            send.add_header("Content-Length", str(len(block)))
+            send.add_header("Content-Range", span)
+            try:
+                with urllib.request.urlopen(send, timeout=3600) as response:
+                    remote_id = json.loads(response.read())["id"]
+            except urllib.error.HTTPError as exc:
+                if exc.code != 308:
+                    raise RuntimeError(
+                        "the upload returned %d: %s"
+                        % (exc.code, exc.read()[:300].decode(errors="replace"))
+                    )
+            offset = end
+    if remote_id is None:
+        raise RuntimeError("the upload session never answered with a file")
+    return {"ok": True, "value": {"id": remote_id, "size": size}}
+
+
 def _op_place_blob(request):
     """Move a received file blob to its destination path, and unpack it when asked.
 
@@ -2456,6 +2533,7 @@ _OPS = {
     "get_file": _op_get_file,
     "pack_dir": _op_pack_dir,
     "pack_blob": _op_pack_blob,
+    "push_blob": _op_push_blob,
     "place_blob": _op_place_blob,
     "exec": _op_exec,
     "eval": _op_eval,
@@ -2464,12 +2542,13 @@ _OPS = {
     "stat": _op_stat,
     "lease": _op_lease,
     "reduce_peers": _op_reduce_peers,
+    "drive_grant": _op_drive_grant,
 }
 
 #: Answered by the frame reader at once, so they work while a call runs.
 # ``data_failed`` is light because it must not queue behind the call it is about: the call
 # is blocked on a blob the sender will never send, so a queued answer would deadlock.
-_LIGHT = ("stat", "lease", "reduce_peers", "data_failed")
+_LIGHT = ("stat", "lease", "reduce_peers", "drive_grant", "data_failed")
 
 #: Answered by several replies, the last one marked. These send their own replies.
 _STREAMING = ("data_stream",)

{letify-2.7.1 → letify-2.8.0}/letify/providers/base.py

@@ -45,6 +45,18 @@ if TYPE_CHECKING:
 Persistence = Literal["persistent", "ephemeral"]
 
 
+@dataclasses.dataclass(frozen=True)
+class RuntimeState:
+    """What a provider knows about whether a runtime still exists.
+
+    ``status`` is ``"ended"``, ``"running"`` or ``"unknown"``. ``detail`` is the sentence a
+    waiting call raises ``RuntimeLost`` with when the status is ``"ended"``.
+    """
+
+    status: Literal["ended", "running", "unknown"] = "unknown"
+    detail: str = ""
+
+
 class Provider(abc.ABC):
     """Base class for every provider."""
 
@@ -502,6 +514,15 @@ class Provider(abc.ABC):
         """
         return failure
 
+    def runtime_state(self, runtime: Runtime) -> RuntimeState:
+        """Ask the provider whether the runtime still exists, without using its channel.
+
+        Spec "Lifetime", the lease. The default cannot tell and answers unknown. A provider
+        that can tell answers ended, with a sentence saying how it ended, or running. The
+        answer must not depend on the channel carrying the call, which may be blocked.
+        """
+        return RuntimeState()
+
     def stop(self, runtime: Runtime) -> None:
         """Release whatever the provider allocated for this runtime."""
         return None

{letify-2.7.1 → letify-2.8.0}/letify/providers/colab.py

@@ -502,7 +502,7 @@ class Colab(Shell):
                 return self._exec(name, source, timeout)
 
             files = ColabFiles(self.alias, name, run, workspace=self.workspace_root)
-            return OneShotChannel(run, name=name, files=files)
+            return OneShotChannel(run, name=name, files=files, provider=self.alias)
         return super().open_channel(runtime)
 
 

{letify-2.7.1 → letify-2.8.0}/letify/providers/modal.py

@@ -45,7 +45,7 @@ from ..errors import (
 )
 from ..protocol import wire
 from ..runtime.channel import Connection, FramedChannel
-from .base import Provider
+from .base import Provider, RuntimeState
 from .usage import Usage
 
 if TYPE_CHECKING:
@@ -105,6 +105,9 @@ WORKER_PACKAGES = ("cloudpickle", "blake3")
 #: Seconds ``Modal.stop`` and a channel's shutdown frame wait for a busy adapter.
 STOP_WAIT = 5.0
 
+#: Seconds the second adapter that polls a sandbox may take before it is killed.
+POLL_LIMIT = 30.0
+
 #: Seconds a sandbox may be idle before Modal terminates it, unless the entry sets
 #: ``idle_timeout``.
 IDLE_TIMEOUT = 600
@@ -490,6 +493,33 @@ class Modal(Provider):
             lifetime_s=self.sandbox_timeout_s,
         )
 
+    def runtime_state(self, runtime: Runtime) -> RuntimeState:
+        """Poll the sandbox from a second adapter process, never the one carrying the call.
+
+        Spec "Lifetime", the lease. The adapter carrying the call may be blocked in a
+        request, so a short-lived one asks. Any failure answers unknown.
+        """
+        sandbox = self._sandboxes.get(runtime.name)
+        if sandbox is None:
+            return RuntimeState()
+        other = Adapter.for_account(self.alias)
+        # A poll that hangs ends the second adapter, which makes the request raise.
+        limit = threading.Timer(POLL_LIMIT, other.abort)
+        limit.daemon = True
+        limit.start()
+        try:
+            code = other.request("poll", sandbox=sandbox)
+        except (LetifyError, ValueError, OSError):
+            return RuntimeState()
+        finally:
+            limit.cancel()
+            other.close()
+        if code is None:
+            return RuntimeState("running")
+        return RuntimeState(
+            "ended", f"the Modal sandbox ended (exit code {code}) while the call was running"
+        )
+
     def stop(self, runtime: Runtime) -> None:
         sandbox = self._sandboxes.pop(runtime.name, None)
         if sandbox is None:

{letify-2.7.1 → letify-2.8.0}/letify/providers/modal_adapter.py

@@ -191,6 +191,15 @@ class Adapter:
             pass
         return None
 
+    def op_poll(self, request: dict[str, Any]) -> Any:
+        """The sandbox's exit code once it ended, or None while it runs."""
+        sandbox_id = str(request["sandbox"])
+        stream = self.sandboxes.get(sandbox_id)
+        # Without a stream it was created by another adapter process, such as a blocked one.
+        sandbox = stream.sandbox if stream else load_modal().Sandbox.from_id(sandbox_id)
+        code = sandbox.poll()
+        return None if code is None else int(code)
+
     # -- billing -----------------------------------------------------------------
 
     def op_billing_summary(self, request: dict[str, Any]) -> Any:

{letify-2.7.1 → letify-2.8.0}/letify/providers/shell.py

@@ -483,6 +483,7 @@ class Shell(Provider):
                 link.runner,  # type: ignore[attr-defined]
                 name=runtime.name,
                 files=getattr(link, "files", None),
+                provider=self.alias,
             )
         return PersistentChannel(
             link.ssh_command(

{letify-2.7.1 → letify-2.8.0}/letify/runtime/bootstrap.py

@@ -382,7 +382,7 @@ def pull_source(
         f"if {unpack!r}:\n"
         f"    _target = {target or str(Path(path).parent)!r}\n"
         "    os.makedirs(_target, exist_ok=True)\n"
-        "    with tarfile.open(_path, 'r:gz') as _archive:\n"
+        "    with tarfile.open(_path, 'r:*') as _archive:\n"
         "        _root = os.path.realpath(_target)\n"
         "        for _member in _archive.getmembers():\n"
         "            _destination = os.path.realpath(os.path.join(_root, _member.name))\n"