letify 2.10.0__tar.gz → 2.10.2__tar.gz

{letify-2.10.0 → letify-2.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.10.0
+Version: 2.10.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.10.0 → letify-2.10.2}/docs/SPEC.md

@@ -1089,7 +1089,7 @@ A call has exactly one owner at a time, and the session still ends with the call
 
 1. **The registry keeps an orphan.** The record also holds `project`, the project root the call was sent from, and `lease_deadline`, the Unix time at which the runtime's lease ends unless renewed, rewritten at each renewal. It also holds what a second process needs to reach the call and finish it: `door`, the path of the worker's socket below; `config`, the project `config.toml` that names the account; and `call_dir`, `blobs` and `outputs`, the runtime paths and the output locations to write back, each location stored relative to `project` when it lies inside it. No secret is among them. A record whose owner pid is gone is no longer removed when read while its `lease_deadline` is in the future: `letify runs` lists it with `owner` `gone` and the seconds left, and it can be taken over. After the deadline it is removed as stale.
 2. **The worker keeps a second door.** While a call runs, the worker listens on a Unix socket on the runtime, `<workspace root>/.letify/run-<run id>.sock`, mode 0600. When that path is longer than 100 bytes, the limit of a Unix socket address, the worker and the relay reach the socket through `/proc/self/fd/<n>`, a descriptor of its directory, so it stays at that path; where `/proc` is missing the worker reports that the run has no second door. A channel that closes while a call runs, with no shutdown frame before it, does not end the worker: the body keeps running until the lease deadline passes. A shutdown frame is different: it is the owner ending the run on purpose, as [A deliberate shutdown](#run-shutdown) describes. Output the body makes while no channel is open is kept, the last 256 KiB per stream, and is sent to the next owner first. A body that returns while no channel is open keeps its result for a new owner until the lease deadline; on a provider with no lease the worker ends then, as before.
-3. **The new owner connects.** `letify takeover <run>` reads the record, opens a channel to the same runtime through the record's provider and runtime name, and starts a relay to that socket instead of a new worker. It then sends `adopt` with the run id. The worker answers once with the call's state, which is `running` or `finished`, and from then on sends the call's output and its reply on the new channel, the reply as the last piece of the same answer. The old channel, if still open, is told `moved` on the call's stream and answers every later request on it with `moved`. A door takes one connection at a time and no request but `adopt` before it, and a second owner can adopt after the first one's connection has closed.
+3. **The new owner connects.** `letify takeover <run>` reads the record, opens a channel to the same runtime through the record's provider and runtime name, and starts a relay to that socket instead of a new worker. It then sends `adopt` with the run id. The worker answers once with the call's state, which is `running` or `finished`, and from then on sends the call's output and its reply on the new channel, the reply as the last piece of the same answer. The old channel, if still open, is told `moved` on the call's stream, after the worker has switched the call's output to the new channel, so everything the body prints once the old owner knows of the move reaches the new owner. It answers every later request on it with `moved`. A door takes one connection at a time and no request but `adopt` before it, and a second owner can adopt after the first one's connection has closed. The adoption is atomic with respect to the old channel: if the old channel closes while the adoption is under way, the worker decides what that close means only after the adoption has finished, sees that the call has moved, and does nothing. The new owner's channel is then never marked as having lost its input, and no exit hook runs for the close.
 4. **The old owner lets go.** When the old owner is alive, takeover first asks it through its control socket to release the run. Its waiting call raises `OwnershipMoved` naming the run and the new owner's pid, it stops renewing that runtime's lease, and it drops the runtime from its pool without stopping it. A `keep_alive` block in the old owner no longer holds that session. An old owner that does not answer within 5 s is treated as gone.
 5. **The call ends at the new owner.** `letify takeover` prints the body's output as it arrives. When the call returns it prints the `repr` of the value, or with `--result PATH` writes the value with pickle to `PATH`, and exits 0. When the body raises it prints the traceback and exits 1. With `--json` the last line is one object with `run`, `ok`, `value_repr` or `error`, and `result_path`. The call's outputs are written back under the record's `project`, not the current directory. The session is then ended.
 6. **The same from Python.** `letify.takeover(run)` does the same in the calling process and returns the value or raises the body's exception, as a call does. It holds no handle: it returns once the call has ended and the session is gone. A darkpyonix kernel uses this to adopt a run started elsewhere.
@@ -1333,7 +1333,7 @@ connection, but a call's second large blob is split whenever splitting is faster
 
 A connection that costs something to open has to pay for itself, so a provider reports `transfer_connection_cost_s`, the seconds one more connection takes. It is 0 for a provider that dials an address, and about 10 for one reached by a hole punch, because that is what a punch measures. The streams are opened only when the transfer is expected to finish sooner with them: the estimate uses the probe's upload rate, assumes the streams scale and that their connections are opened at the same time, and keeps one stream when `size / (rate x streams) + cost` is not less than `size / rate`. A measured case: a Kaggle runtime at a 44.7 ms round trip carried 128 MiB at 21.0 MiB/s on one stream and 9.5 MiB/s on four, 2.2 times worse, because three more punches cost more than the transfer saved. The same account at a 193 ms round trip carried 1.57 MiB/s on one raw SSH connection and 6.10 MiB/s on four, so the gain is real where the link is slow enough and the blob large enough for it to be worth 10 s.
 
-The connections have to be real ones. Every SSH command letify builds carries `ControlMaster=auto`, which multiplexes further sessions onto the first connection, so opening more channels that way would add streams inside one TCP connection and gain nothing. A transfer channel therefore sets `ControlPath=none` and `ControlMaster=no`, and a punched link gives each its own socket, so each transfer channel is its own kernel connection. A punched link holds the spare sockets of its punch, `PUNCH_SOCKETS` of them in all, [Rendezvous](#rendezvous), and hands one to each SSH command before it redials. The worker channel and the first transfer channels therefore cost no rendezvous, and `transfer_connection_cost_s` applies only to the streams beyond the spares.
+The connections have to be real ones. Every SSH command letify builds carries `ControlMaster=auto`, which multiplexes further sessions onto the first connection, so opening more channels that way would add streams inside one TCP connection and gain nothing. A transfer channel therefore sets `ControlPath=none` and `ControlMaster=no`, and a punched link gives each its own socket, so each transfer channel is its own kernel connection. A punched link holds the spare sockets of its punch, `PUNCH_SOCKETS` of them in all, [Rendezvous](#rendezvous), and hands one to each SSH command before it redials. The worker channel and the first transfer channels therefore cost no rendezvous, and `transfer_connection_cost_s` applies only to the streams beyond the spares: with `k` spares still unused and `s` streams wanted, `s - 1 - k` punches are needed, and when that is above 0 the estimate adds the cost once (the punches run at the same time), otherwise it adds 0. The link reports `k` as `spare_connections()`, which is 0 for every link but a punched one.
 
 The worker's `data_put` appends to one handle per digest and hashes as it goes, which assumes the pieces arrive in order on one stream. Parallel senders cannot use it, so they use two other requests:
 
@@ -2683,6 +2683,11 @@ The worker records the first failure and skips the operators after it until a sy
 
 A lost worker process or link raises `RuntimeLost`, and the session is discarded.
 
+An executor that ends because of an exception sends one last message, a failure naming the exception, before it stops, so the client stops waiting at once instead of waiting for a reply that cannot come. This holds at startup and in the middle of a session, on the call worker's channel and as a process of its own. The client discards the executor and raises:
+
+- `ConfigError` when the executor could not start because a module is missing from the runtime's environment, such as `torch`. The message names the exception, for example `ModuleNotFoundError: No module named 'torch'`, and for `torch` says to add it to the project's dependencies. It is not retried, because a fresh runtime builds the same environment from the same lock.
+- `RuntimeLost`, carrying the executor's exception and traceback, for any other exception.
+
 ### Version guards <!-- id: forwarding-versions -->
 
 > PyTorch 2.1 or newer is required locally and on the runtime.

{letify-2.10.0 → letify-2.10.2}/letify/__init__.py

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

{letify-2.10.0 → letify-2.10.2}/letify/protocol/worker.py

@@ -3549,11 +3549,12 @@ def _reader_ended(door, shutdown=False):
     Spec "A deliberate shutdown": a shutdown frame on the channel that owns a running call
     ends the body and the worker. End of input alone leaves the body for a takeover.
     """
-    if door is None and _TAKE["moved"]:
-        # The call was adopted away; this channel closing is the old owner leaving.
-        return
     during = False
     with _TAKE_COND:
+        if door is None and _TAKE["moved"]:
+            # The call was adopted away; this channel closing is the old owner leaving. Read
+            # under the lock, because an adoption in progress holds it until it has moved.
+            return
         if door is None or (_TAKE["owner"] is door and _TAKE["live"]):
             during = _TAKE["run"] is not None
             if door is not None or during:
@@ -3702,12 +3703,6 @@ def _door_adopt(door, stream, request):
         moved = _moved_outcome()
         if _TAKE["owner"] is not None:
             moved["last"] = True
-        # Told on a thread, because a former owner that has stopped reading can block the write.
-        told = threading.Thread(
-            target=_answer, args=(former, former_stream, moved), daemon=True
-        )
-        told.start()
-        told.join(2.0)
         state = {
             "run": run,
             "state": "finished" if _TAKE["finished"] else "running",
@@ -3728,6 +3723,14 @@ def _door_adopt(door, stream, request):
         )
         _SENDER = door.sender
         _TAKE_COND.notify_all()
+        # Told last, after the output has been switched, so that nothing the body prints from
+        # the moment the former owner learns of the move is sent to a channel that has stopped
+        # reading. A thread, because a former owner that has stopped reading can block the write.
+        told = threading.Thread(
+            target=_answer, args=(former, former_stream, moved), daemon=True
+        )
+        told.start()
+        told.join(2.0)
 
 
 def _deliver_call(stream, outcome):

{letify-2.10.0 → letify-2.10.2}/letify/remoting/device/client.py

@@ -29,7 +29,7 @@ from typing import Any
 import torch
 from blake3 import blake3
 
-from ...errors import RemoteError, RuntimeLost
+from ...errors import ConfigError, RemoteError, RuntimeLost
 from .executor import E_DEFINE, E_OP, E_REQUEST, E_STEP, E_STEP_DEFINE, UPLOAD_CACHE_BYTES
 from .frames import ChannelTransport, StreamTransport, Transport, TransportClosed
 from .guard import check_torch_version, check_worker_version
@@ -279,6 +279,7 @@ class Client:
         """Read the executor's first message, check its PyTorch, and start the threads."""
         head, _buffers = self._recv()
         self.hello = pickle.loads(head)
+        self._raise_fatal(self.hello)
         check_worker_version(local=torch.__version__, remote=str(self.hello["torch"]))
         self._sender = threading.Thread(
             target=self._send_loop, name=f"{self.name}-send", daemon=True
@@ -811,6 +812,7 @@ class Client:
         head, buffers = self._recv()
         consumers = self._replies.popleft()
         reply = pickle.loads(head)
+        self._raise_fatal(reply)
         results = reply["results"]
         failure = reply.get("failure")
         for note in reply.get("notes", ()):
@@ -1016,6 +1018,25 @@ class Client:
         detail = f"\n--- device worker stderr ---\n{tail}" if tail else ""
         return RuntimeLost(f"{self.name}: the device worker was lost: {reason}{detail}")
 
+    def _raise_fatal(self, message: dict) -> None:
+        """Raise the failure an executor sent as its last message, discarding the executor."""
+        fatal = message.get("fatal")
+        if fatal is None:
+            return
+        error = fatal["error"]
+        if fatal["started"] or fatal["missing"] is None:
+            where = "the device executor stopped" if fatal["started"] else "could not start"
+            lost = self._lose(f"{where}: {error}\n{fatal['traceback']}")
+            raise lost
+        self._lose(error)
+        hint = (
+            "; add torch to the project's dependencies (uv add torch) so the runtime's "
+            "environment has it"
+            if fatal["missing"] == "torch"
+            else "; add it to the project's dependencies"
+        )
+        raise ConfigError(f"{self.name}: the device executor could not start: {error}{hint}")
+
     def _check_open(self) -> None:
         if os.getpid() != self._pid:
             raise RuntimeLost(
@@ -1113,10 +1134,10 @@ def connect(
 
         transport.raw(count_line(source) + source)
         client.start()
-    except (TransportClosed, RuntimeLost) as exc:
+    except (TransportClosed, RuntimeLost, ConfigError) as exc:
         process.kill()
         process.wait()
-        if isinstance(exc, RuntimeLost):
+        if isinstance(exc, (RuntimeLost, ConfigError)):
             raise
         raise client._lose(str(exc)) from exc
     return client
@@ -1132,7 +1153,11 @@ def attach(
     channel.request(
         {"op": "device", "device": device, "source": worker_source(None).decode()}, timeout=600
     )
-    client.start()
+    try:
+        client.start()
+    except (RuntimeLost, ConfigError):
+        transport.close()
+        raise
     return client
 
 

{letify-2.10.0 → letify-2.10.2}/letify/remoting/device/executor.py

@@ -946,14 +946,37 @@ class Executor:
 
 
 def serve_transport(device: str, transport) -> None:
-    """Announce the executor on ``transport`` and answer its messages until it closes."""
-    executor = Executor(device)
-    transport.send(pickle.dumps(executor.hello(), protocol=5), [])
-    while True:
+    """Announce the executor on ``transport`` and answer its messages until it closes.
+
+    An exception that ends the executor is sent as a last message, so the client stops
+    waiting for a reply that cannot come, as spec "Failure semantics" describes.
+    """
+    started = False
+    try:
+        executor = Executor(device)
+        transport.send(pickle.dumps(executor.hello(), protocol=5), [])
+        started = True
+        _answer(executor, transport)
+    except TransportClosed:
+        return
+    except BaseException as exc:
+        detail = traceback.format_exc()
+        print(detail, file=sys.stderr, flush=True)
+        fatal = {
+            "error": f"{type(exc).__name__}: {exc}",
+            "traceback": detail,
+            "started": started,
+            "missing": exc.name if isinstance(exc, ImportError) else None,
+        }
         try:
-            head, buffers = transport.recv()
-        except TransportClosed:
-            return
+            transport.send(pickle.dumps({"fatal": fatal}, protocol=5), [])
+        except Exception:  # pragma: no cover - the link is gone as well
+            pass
+
+
+def _answer(executor: Executor, transport) -> None:
+    while True:
+        head, buffers = transport.recv()
         message = pickle.loads(head)
         head = None
         if message.get("close"):
@@ -962,10 +985,7 @@ def serve_transport(device: str, transport) -> None:
         buffers = None
         if reply is not None:
             reply_head, views, keep = reply
-            try:
-                transport.send(reply_head, views)
-            except TransportClosed:
-                return
+            transport.send(reply_head, views)
             del keep
 
 

{letify-2.10.0 → letify-2.10.2}/letify/store/pathdata.py

@@ -1096,6 +1096,7 @@ def streams_for(
     size: int,
     rate_bps: float | None = None,
     cost_s: float = 0.0,
+    spares: int = 0,
 ) -> int:
     """How many connections this blob is worth splitting across.
 
@@ -1103,14 +1104,16 @@ def streams_for(
     connections to send a few megabytes costs more than it saves; one on a short link,
     because there a single stream already carries everything the link will carry; never
     more streams than there are chunks to send; and, when a connection costs something to
-    open, only as many as finish the transfer sooner than one would.
+    open, only as many as finish the transfer sooner than one would. The extra streams
+    (all but one) that the link's ``spares`` cover cost nothing, so the cost applies only
+    when ``count - 1`` exceeds them.
     """
     if streams <= 1 or size < threshold_mib * (1 << 20):
         return 1
     if rtt_ms is None or rtt_ms < PARALLEL_RTT_MS:
         return 1
     count = max(1, min(streams, (size + CHUNK - 1) // CHUNK))
-    if cost_s > 0 and count > 1:
+    if cost_s > 0 and count - 1 > max(0, spares):
         if not rate_bps or rate_bps <= 0:
             # Nothing to weigh the cost against, and the cost is real, so do not pay it.
             return 1
@@ -1147,6 +1150,15 @@ def _measured_rtt(provider: Any, runtime: Any) -> float | None:
     return getattr(_measured_link(provider, runtime), "rtt_ms", None)
 
 
+def _spares_of(link: Any) -> int:
+    """The spare connections ``link`` still holds, 0 where it has no such query."""
+    query = getattr(link, "spare_connections", None)
+    try:
+        return max(0, int(query())) if callable(query) else 0
+    except Exception:
+        return 0
+
+
 def _streams_for(runtime: Any, size: int, *, warm: bool = False) -> int:
     """``streams_for`` with the account's settings and the link's measured round trip.
 
@@ -1167,6 +1179,7 @@ def _streams_for(runtime: Any, size: int, *, warm: bool = False) -> int:
         threshold_mib=int(getattr(provider, "transfer_parallel_mib", PARALLEL_MIB) or 0),
         rate_bps=rate,
         cost_s=cost_s,
+        spares=_spares_of(link),
         rtt_ms=rtt,
         size=size,
     )

{letify-2.10.0 → letify-2.10.2}/letify/transport/link.py

@@ -44,6 +44,10 @@ class Link:
         """A stream the probe can run over, or None when this link cannot carry it."""
         return None
 
+    def spare_connections(self) -> int:
+        """Connections handed out with no rendezvous. Spec "Several connections at once"."""
+        return 0
+
     def ssh_command(self, remote_command: str | None = None) -> list[str]:
         raise RuntimeFailure(f"the {self.strategy} link carries no SSH session")
 
@@ -150,6 +154,11 @@ class PunchedLink(Link):
                 sock = self._spares.pop(0)
         return sock if sock is not None else self._redial()
 
+    def spare_connections(self) -> int:
+        """The spare sockets of the punch that no SSH command has taken yet."""
+        with self._lock:
+            return len(self._spares)
+
     def ssh_command(self, remote_command: str | None = None) -> list[str]:
         listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         # Port 0: the operating system chooses, because Windows reserves ranges per machine.

{letify-2.10.0 → letify-2.10.2}/letify-core/Cargo.lock

@@ -138,11 +138,11 @@ dependencies = [
 
 [[package]]
 name = "letify"
-version = "2.10.0"
+version = "2.10.2"
 
 [[package]]
 name = "letify-quic"
-version = "2.10.0"
+version = "2.10.2"
 dependencies = [
  "quinn",
  "rcgen",

{letify-2.10.0 → letify-2.10.2}/letify-core/Cargo.toml

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

{letify-2.10.0 → letify-2.10.2}/letify-ext/package-lock.json

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

{letify-2.10.0 → letify-2.10.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.10.0",
+  "version": "2.10.2",
   "publisher": "darkpyonix",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

{letify-2.10.0 → letify-2.10.2}/pyproject.toml

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

{letify-2.10.0 → letify-2.10.2}/tests/test_device.py

@@ -2027,3 +2027,114 @@ def test_the_environment_variable_turns_the_automatic_behaviour_off(monkeypatch)
     monkeypatch.delenv("LETIFY_AUTO_FETCH")
     assert auto_fetch_enabled(False) is False
     assert auto_fetch_enabled(None) is True
+
+
+# -- Spec: Failure semantics ---------------------------------------------------------
+
+
+class _Loopback:
+    """The client's end of a pair of queues whose other end is ``serve_transport``."""
+
+    def __init__(self, incoming, outgoing):
+        self.incoming = incoming
+        self.outgoing = outgoing
+
+    def send(self, head, buffers) -> None:
+        self.outgoing.put((bytes(head), [bytes(b) for b in buffers]))
+
+    def recv(self):
+        message = self.incoming.get(timeout=20)
+        if message is None:
+            raise frames.TransportClosed("the loopback closed")
+        return message
+
+    def close(self) -> None:
+        self.outgoing.put(None)
+
+
+def _serve_in_thread(monkeypatch, make_executor):
+    """Run the real ``serve_transport`` in a thread and return the client on its other end."""
+    import queue
+    import threading
+
+    from letify.remoting.device import executor as executor_module
+
+    requests, replies = queue.Queue(), queue.Queue()
+    monkeypatch.setattr(executor_module, "Executor", make_executor)
+    server = _Loopback(requests, replies)
+    thread = threading.Thread(
+        target=executor_module.serve_transport,
+        args=("cpu", server),
+        daemon=True,
+    )
+    thread.start()
+    return forwarding.Client(_Loopback(replies, requests), name="loopback"), thread
+
+
+def test_a_device_executor_that_dies_mid_session_fails_the_waiting_read(monkeypatch) -> None:
+    from letify.remoting.device import executor as executor_module
+
+    real = executor_module.Executor
+
+    class Dying(real):
+        def run(self, message, buffers):
+            raise ValueError("the executor broke")
+
+    client, thread = _serve_in_thread(monkeypatch, Dying)
+    client.start()
+    with client.activate(), pytest.raises(letify.RuntimeLost, match="the executor broke"):
+        torch.ones(2, device="cuda").cpu()
+    thread.join(5)
+    assert not thread.is_alive()
+
+
+def test_a_device_executor_that_cannot_start_fails_the_hello_naming_the_cause(
+    monkeypatch,
+) -> None:
+    class Broken:
+        def __init__(self, device):
+            raise RuntimeError("no device to start on")
+
+    client, _thread = _serve_in_thread(monkeypatch, Broken)
+    with pytest.raises(letify.RuntimeLost, match="no device to start on"):
+        client.start()
+
+
+_WITHOUT_TORCH = (
+    "import sys\n"
+    "class _NoTorch:\n"
+    "    def find_spec(self, name, path=None, target=None):\n"
+    "        if name == 'torch':\n"
+    "            raise ModuleNotFoundError(\"No module named 'torch'\", name='torch')\n"
+    "sys.meta_path.insert(0, _NoTorch())\n"
+)
+
+
+def test_a_device_worker_that_cannot_import_torch_fails_the_call_naming_it(
+    let, cpu, monkeypatch
+) -> None:
+    from letify.remoting.device import client as client_module
+
+    real = client_module.worker_source
+    future_line = b"from __future__ import annotations\n"
+
+    def without_torch(device):
+        return real(device).replace(future_line, future_line + _WITHOUT_TORCH.encode(), 1)
+
+    monkeypatch.setattr(client_module, "worker_source", without_torch)
+
+    @let.function(device=cpu, host="local")
+    def step() -> float:
+        return float(torch.ones(2, device="cuda").sum().item())
+
+    # The call must fail at once instead of waiting for a reply that never comes.
+    import concurrent.futures
+
+    pool = concurrent.futures.ThreadPoolExecutor(1)
+    try:
+        future = pool.submit(step)
+        with pytest.raises(letify.ConfigError, match="No module named 'torch'") as caught:
+            future.result(timeout=60)
+    finally:
+        pool.shutdown(wait=False)
+    assert "add torch" in str(caught.value).lower() or "dependencies" in str(caught.value)

{letify-2.10.0 → letify-2.10.2}/tests/test_parallel_placement.py

@@ -548,3 +548,82 @@ class _Measured:
     def __init__(self, rtt_ms: float, upload_bps: float) -> None:
         self.rtt_ms = rtt_ms
         self.upload_bps = upload_bps
+
+
+def test_spare_sockets_let_a_transfer_open_streams_without_paying_a_punch() -> None:
+    """Spec "Several connections at once": streams covered by spares cost no rendezvous.
+
+    128 MiB at 56.8 MiB/s takes 2.3 s, so a 10 s punch keeps one stream. With three
+    spares the three extra streams of a four stream split need no punch and are kept.
+    """
+    from letify.store.pathdata import streams_for
+
+    MIB = 1 << 20
+    near = dict(streams=4, threshold_mib=64, rtt_ms=44.7, size=128 * MIB, rate_bps=56.8 * MIB)
+    assert streams_for(**near, cost_s=10.0, spares=0) == 1
+    assert streams_for(**near, cost_s=10.0, spares=3) == 4
+    assert streams_for(**near, cost_s=10.0, spares=4) == 4
+
+
+def test_streams_beyond_the_spares_pay_the_connection_cost() -> None:
+    """Spec: with fewer spares than extra streams, one punch is paid, once, for all of them."""
+    from letify.store.pathdata import streams_for
+
+    MIB = 1 << 20
+    near = dict(streams=4, threshold_mib=64, rtt_ms=44.7, size=128 * MIB, rate_bps=56.8 * MIB)
+    assert streams_for(**near, cost_s=10.0, spares=2) == 1
+    far = dict(streams=4, threshold_mib=64, rtt_ms=193.0, size=1024 * MIB, rate_bps=12.8 * MIB)
+    assert streams_for(**far, cost_s=10.0, spares=2) == 4
+
+
+def test_a_punched_link_reports_the_spare_sockets_it_still_holds() -> None:
+    """Spec: a punched link holds the spares of its punch; any other link holds none."""
+    import socket
+
+    from letify.transport.link import Link, PunchedLink
+
+    assert Link("x", 0).spare_connections() == 0
+    pairs = [socket.socketpair() for _ in range(4)]
+    socks = [a for a, _ in pairs]
+    link = PunchedLink("tcp_punch", 0, socks[0], lambda port, cmd: [], lambda: socks[0], socks[1:])
+    try:
+        assert link.spare_connections() == 3
+        link._take()  # the punched connection itself
+        assert link.spare_connections() == 3
+        link._take()  # first spare
+        assert link.spare_connections() == 2
+    finally:
+        link.close()
+        for _, b in pairs:
+            b.close()
+
+
+def test_the_placement_reads_the_spares_from_the_link(monkeypatch) -> None:
+    """Spec: `_streams_for` passes the link's spare count, so a Kaggle shard splits for free."""
+    from conftest import provider_of
+
+    from letify.providers import Kaggle
+    from letify.store.pathdata import _streams_for
+
+    MIB = 1 << 20
+    provider = provider_of(Kaggle, "kaggle_a")
+
+    class Runtime:
+        name = "letify-t4-cd14ab"
+
+    def make(spares: int):
+        class Link:
+            strategy = "tcp_punch"
+            rtt_ms = 44.7
+            upload_bps = 56.8 * MIB
+
+            def spare_connections(self) -> int:
+                return spares
+
+        return Link()
+
+    Runtime.provider = provider
+    provider._links[Runtime.name] = make(0)
+    assert _streams_for(Runtime(), 128 * MIB) == 1
+    provider._links[Runtime.name] = make(3)
+    assert _streams_for(Runtime(), 128 * MIB) == 4