hugpy-wrapper 0.1.0__py3-none-any.whl

fitevict/adapters/llama_cpp.py

@@ -0,0 +1,1298 @@
+"""A minimal llama.cpp adapter STUB — the concrete seam, not a working engine.
+
+It shows how `EngineHost.footprint` would price a GGUF from its typed structure
+following llama.cpp's placement rules (clean-room; no hugpy import):
+
+  * `--n-gpu-layers L` puts the top L of `block_count` blocks on the GPU; the
+    output tensor rides the GPU only when all layers do.
+  * `--n-cpu-moe N` keeps the expert tensors of the first N blocks on the CPU;
+    every other tensor of a GPU block stays on the GPU.
+  * KV rides its block (a GPU layer holds its KV slice on the GPU).
+
+`gguf_footprint` is pure math over a structure dict; a real adapter would read
+that structure from the file and implement `measure` / `list_residents` /
+`evict` / `load` against the running engine. Only the pricing seam is made
+concrete here, deliberately — geometry belongs in the adapter, never the core.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..types import ModelFootprint
+
+_GPU_MARGIN = 1.15
+_RAM_MARGIN = 1.15
+_DTYPE_BYTES = 2.0
+_COMPUTE_CUSHION_BYTES = 512 * 2 ** 20
+
+
+def gguf_footprint(struct: dict, *, ctx_tokens: int, n_gpu_layers: int = -1,
+                   n_cpu_moe: int = 0, ctx_pct: Optional[int] = None,
+                   ctx_deviation_pct: Optional[float] = None) -> ModelFootprint:
+    """Price a GGUF load into a `ModelFootprint`.
+
+    `struct` carries the typed per-layer bytes the way a GGUF inspector would
+    report them::
+
+        {"block_count": int,
+         "token_embd_bytes": int, "output_bytes": int, "global_bytes": int,
+         "is_moe": bool, "output_tied": bool,
+         "kv_elems_per_token": int,        # full-attention KV elems / token / layer
+         "layers": {i: {"always_bytes": int, "expert_bytes": int}}}
+
+    The returned footprint's `weights_bytes`/`kv_bytes` are the GPU-side figures
+    (what admission gates on); `expert_bytes`/`non_expert_bytes` carry the MoE
+    split so the planner can reason about an expert spill."""
+    layers = {int(k): v for k, v in (struct.get("layers") or {}).items()}
+    n_block = int(struct.get("block_count") or len(layers))
+    ngl = int(n_gpu_layers if n_gpu_layers is not None else -1)
+    if ngl < 0 or ngl > n_block:
+        start, out_on_gpu = 0, True
+    else:
+        start, out_on_gpu = n_block - ngl, False
+    gpu_layers = {i for i in layers if i >= start} if ngl != 0 else set()
+
+    is_moe = bool(struct.get("is_moe"))
+    ncm = max(0, int(n_cpu_moe or 0)) if is_moe else 0
+
+    gw = rw = experts_gpu = experts_cpu = non_expert = 0
+    for i, L in layers.items():
+        a = int(L.get("always_bytes") or 0)
+        e = int(L.get("expert_bytes") or 0)
+        non_expert += a
+        if i in gpu_layers:
+            gw += a
+            if i < ncm:
+                rw += e
+                experts_cpu += e
+            else:
+                gw += e
+                experts_gpu += e
+        else:
+            rw += a + e
+            experts_cpu += e
+
+    embd = int(struct.get("token_embd_bytes") or 0)
+    outb = int(struct.get("output_bytes") or 0)
+    glob = int(struct.get("global_bytes") or 0)
+    non_expert += embd + outb + glob
+    rw += embd  # input layer is always on the CPU
+    if out_on_gpu:
+        gw += outb + glob + (embd if struct.get("output_tied") else 0)
+    else:
+        rw += outb + glob
+
+    # KV: full-attention per-token elems * ctx * dtype, shared by GPU layers.
+    per_tok = int(struct.get("kv_elems_per_token") or 0)
+    kv_total = int(ctx_tokens * per_tok * _DTYPE_BYTES)
+    n_gpu = len(gpu_layers)
+    kv_gpu = int(kv_total * (n_gpu / float(n_block))) if n_block else 0
+    cushion = _COMPUTE_CUSHION_BYTES if (gpu_layers and is_moe) else 0
+
+    gpu_weights = int(gw * _GPU_MARGIN)
+    gpu_total = gpu_weights + kv_gpu + cushion
+    return ModelFootprint(
+        weights_bytes=gpu_weights,
+        kv_bytes=kv_gpu,
+        total_bytes=gpu_total,
+        layers=n_block,
+        moe=is_moe,
+        expert_bytes=int(experts_gpu + experts_cpu) or None,
+        non_expert_bytes=int(non_expert) or None,
+        ctx_pct=ctx_pct,
+        ctx_deviation_pct=ctx_deviation_pct,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LlamaCppHost — the concrete EngineHost that RUNS llama-server children.
+#
+# GLUE (new code, the only kind the task allows here): it maps the LIFTED results
+# onto fitevict's types and executes drive()'s plan. Every fact comes from a
+# lifted function or a live measurement — nothing is hardcoded:
+#   * footprint  <- lifted gguf_inspect.gguf_structure + fit.gguf_need.gguf_need
+#   * measure    <- lifted hardware.detect_gpus + spill reserve/free_* closure
+#   * resolution <- lifted model_resolve (is_model_dir / get_gguf_file / marker)
+#   * binary     <- lifted native_resolve.server_bin
+#   * launch     <- lifted procutil.popen_detached, argv per slot_agent._build_cmd
+#   * stop       <- lifted procutil.terminate_tree
+#   * timings    <- lifted timings.tok_s_from_timings / generation_split
+# ─────────────────────────────────────────────────────────────────────────────
+import json as _json
+import os as _os
+import socket as _socket
+import subprocess as _subprocess
+import time as _time
+import urllib.request as _urllib
+import uuid as _uuid
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from ..types import (
+    DeviceBudget, FitPlan, HostBudget, ModelFootprint, Resident, VRAM,
+)
+from ..lifted import (
+    hardware as _hw,
+    model_resolve as _mr,
+    native_resolve as _nr,
+    spill_reserve as _spill,
+    timings as _tm,
+)
+from ..lifted.gguf_need import gguf_need as _gguf_need, structure_for as _structure_for
+
+
+def discover_models(models_home: Optional[str] = None) -> "Dict[str, str]":
+    """{model_key: gguf_path} for every GGUF model dir on disk, via the lifted
+    legacy resolution (walk MODELS_HOME, keep dirs is_model_dir() accepts with a
+    model GGUF get_gguf_file() elects). model_key = the repo dir basename, or
+    ``owner~repo`` when two owners hold a repo of the same name (hugpy's key
+    convention). A vision projector is never elected as the model. This box's
+    discovery is THE catalog: the front door publishes it to the DB."""
+    from ..lifted.constants import MODELS_HOME
+    root = _os.path.join(models_home or MODELS_HOME, "gguf")
+    found: "list[tuple[str, str, str]]" = []
+    if not _os.path.isdir(root):
+        return {}
+    for owner in sorted(_os.listdir(root)):
+        od = _os.path.join(root, owner)
+        if not _os.path.isdir(od):
+            continue
+        for repo in sorted(_os.listdir(od)):
+            rd = _os.path.join(od, repo)
+            if not _os.path.isdir(rd) or not _mr.is_model_dir(rd):
+                continue
+            g = _mr.get_gguf_file(rd)
+            if g and ("/mmproj/" in g or _os.path.basename(g).lower().startswith("mmproj")):
+                g = None
+            if g:
+                found.append((owner, repo, g))
+    # transformers chat dirs (the other engine hugpy serves chat with)
+    from . import transformers as _tf
+    for owner, repo, d in _tf.discover(models_home or MODELS_HOME):
+        found.append((owner, repo, d))
+    counts: Dict[str, int] = {}
+    for _o, repo, _g in found:
+        counts[repo] = counts.get(repo, 0) + 1
+    out: Dict[str, str] = {}
+    for owner, repo, g in found:
+        out[f"{owner}~{repo}" if counts[repo] > 1 else repo] = g
+    return out
+
+
+def engine_of_path(path: Optional[str]) -> str:
+    """'gguf' for a GGUF file, 'transformers' for a model dir."""
+    return "gguf" if path and str(path).lower().endswith(".gguf") else "transformers"
+
+
+def model_weights(key: str, gguf_path: str) -> dict:
+    """Discovery detail for one model: its directory, the GGUF the loader elects,
+    and EVERY weight file in the directory (quant + bytes; the mmproj projector
+    flagged). Pure filesystem facts — nothing is opened or priced."""
+    from ..lifted.gguf_election import quant_token
+    if engine_of_path(gguf_path) == "transformers":
+        from ..lifted import tf_facts as _tff
+        d = gguf_path
+        weights = []
+        for root, _dn, files in _os.walk(d):
+            for f in sorted(files):
+                if f.endswith(_tff.WEIGHT_EXT):
+                    p = _os.path.join(root, f)
+                    try:
+                        size = _os.path.getsize(p)
+                    except OSError:
+                        size = None
+                    weights.append({"file": _os.path.relpath(p, d), "path": p, "quant": None,
+                                    "bytes": size, "mmproj": False, "elected": True})
+        mp = _os.path.join(d, "hugpy.json")
+        hj, hje = None, None
+        try:
+            with open(mp, "r", encoding="utf-8") as fh:
+                hj = _json.load(fh)
+        except (OSError, ValueError) as exc:
+            hje = f"{type(exc).__name__}: {exc}"
+        return {"dir": d, "path": d, "hugpy_json": hj, "hugpy_json_error": hje,
+                "file": "dir", "quant": "dir", "engine": "transformers",
+                "bytes": _tff.dir_bytes(d), "mmproj": None, "weights": weights}
+    d = _os.path.dirname(gguf_path)
+    while d and _os.path.basename(d) != key and _os.path.dirname(d) != d:
+        d = _os.path.dirname(d)
+    if _os.path.basename(d) != key:
+        d = _os.path.dirname(gguf_path)
+    weights = []
+    for g in _mr.get_guffs_in_dir(d):
+        try:
+            size = _os.path.getsize(g)
+        except OSError:
+            size = None
+        weights.append({"file": _os.path.relpath(g, d), "path": g,
+                        "quant": quant_token(g) or None, "bytes": size,
+                        "mmproj": _mr.is_mmproj_file(g),
+                        "elected": g == gguf_path})
+    elected = next((w for w in weights if w["elected"]), None)
+    hugpy_json, hugpy_json_error = None, None
+    mp = _os.path.join(d, "hugpy.json")
+    if _os.path.isfile(mp):
+        try:
+            with open(mp, "r", encoding="utf-8") as fh:
+                hugpy_json = _json.load(fh)
+        except (OSError, ValueError) as exc:
+            hugpy_json_error = f"{type(exc).__name__}: {exc}"
+    else:
+        hugpy_json_error = "no hugpy.json in the model dir"
+    return {"dir": d, "path": gguf_path, "hugpy_json": hugpy_json,
+            "hugpy_json_error": hugpy_json_error,
+            "file": _os.path.basename(gguf_path),
+            "quant": (elected or {}).get("quant"),
+            "bytes": (elected or {}).get("bytes"),
+            "mmproj": _mr.find_mmproj(gguf_path),
+            "weights": weights}
+
+
+def _compute_apps_vram() -> "Dict[int, int]":
+    """{pid: used_vram_bytes} — EXACT bytes from NVML (lifted.nvml); nvidia-smi's
+    whole-MiB rows only when NVML is unavailable."""
+    try:
+        from ..lifted import nvml as _nvml
+        procs = _nvml.processes()
+        if procs is not None:
+            return {int(pid): int(r["bytes"]) for pid, r in procs.items()}
+    except Exception:  # noqa: BLE001
+        pass
+    smi = _hw.resolve_bin("nvidia-smi")
+    if not smi:
+        return {}
+    try:
+        out = _subprocess.check_output(
+            [smi, "--query-compute-apps=pid,used_memory",
+             "--format=csv,noheader,nounits"],
+            stderr=_subprocess.DEVNULL, timeout=10).decode("utf-8", "replace")
+    except Exception:  # noqa: BLE001
+        return {}
+    res: Dict[int, int] = {}
+    for line in out.strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) >= 2 and parts[0].isdigit() and parts[1].isdigit():
+            res[int(parts[0])] = int(parts[1]) * 1024 * 1024
+    return res
+
+
+_SERVER_FLAG_CACHE: dict = {}
+
+
+def _server_supports_flag(server_bin, flag) -> bool:
+    """Lifted from slot_agent._server_supports_flag: probe `llama-server --help`
+    once and cache whether `flag` appears. Can't probe -> assume unsupported."""
+    key = (str(server_bin), str(flag))
+    cached = _SERVER_FLAG_CACHE.get(key)
+    if cached is not None:
+        return cached
+    ok = False
+    try:
+        out = _subprocess.run([server_bin, "--help"], capture_output=True,
+                              text=True, timeout=15)
+        ok = flag in ((out.stdout or "") + (out.stderr or ""))
+    except Exception:  # noqa: BLE001
+        ok = False
+    _SERVER_FLAG_CACHE[key] = ok
+    return ok
+
+
+def _proc_rss_bytes(pid: int) -> Optional[int]:
+    try:
+        with open(f"/proc/{pid}/status") as fh:
+            for line in fh:
+                if line.startswith("VmRSS:"):
+                    return int(line.split()[1]) * 1024
+    except Exception:  # noqa: BLE001
+        return None
+    return None
+
+
+def _gpu_changed(reason: str) -> None:
+    """Tell the live GPU-state publisher the card just changed (fitevict.gpu_state)."""
+    try:
+        from .. import gpu_state as _gs
+        _gs.changed(reason)
+    except Exception:  # noqa: BLE001 — telemetry never stops a load/evict
+        pass
+
+
+# llama-server parallel slots per model (operator 2026-10-03: one): a hybrid
+# model's recurrent state is allocated PER SLOT (4 slots = 4x the state).
+_PARALLEL = int(_os.environ.get("FITEVICT_PARALLEL", "1"))
+
+
+def _db_kv_structure(worker, file):
+    from . import db as _db
+    return _db.get_kv_structure(worker, file)
+
+
+def _db_get_driver(worker, device):
+    from . import db as _db
+    return int(_db.get_cuda_context(worker, device + ":driver") or 0)
+
+
+# the request whose placement is evicting (set by the front door under its placement lock)
+_CURRENT_REQUEST: dict = {"id": None}
+
+
+@dataclass
+class _Child:
+    key: str
+    proc: object
+    port: int
+    model_file: str
+    struct: dict
+    need: dict
+    n_gpu_layers: int
+    n_cpu_moe: Optional[int]
+    ctx: int
+    total_layers: Optional[int]
+    is_moe: bool
+    quant: str
+    mmproj: Optional[str]
+    resident_since: float
+    weights_staged_at: Optional[float] = None
+    weights_loaded_at: Optional[float] = None
+    load_error: Optional[str] = None
+    last_used: Optional[float] = None
+    calls: int = 0
+    vram_at_load: Optional[int] = None
+    argv: Optional[list] = None
+    contract: Optional[dict] = None
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+
+_HOSTROWS = __import__("re").compile(r"\|\s*-\s*([A-Za-z0-9_]+)\s*\|\s*(\d+)\s*=\s*(\d+)\s*\+\s*(\d+)\s*\+\s*(\d+)")
+
+
+def host_rows_first_block(text):
+    """Every host-side row (Host, CPU_REPACK, ...) of llama.cpp's FIRST memory
+    breakdown (the initial full config), summed: [total, model, context, compute]
+    in MiB, or None. CUDA rows have the '= free + (self = ...)' shape and never match.
+    CPU_REPACK (weights repacked for the CPU kernels, anonymous memory) is its own
+    row — reading only '- Host' missed 35,450 MiB on Qwen3-Coder-Next (2026-10-03)."""
+    i = text.find("memory breakdown")
+    j = text.find("projected to use", i if i >= 0 else 0)
+    if i < 0 or j < 0:
+        return None
+    rows = _HOSTROWS.findall(text[i:j])
+    if not rows:
+        return None
+    out = [sum(int(r[k]) for r in rows) for k in (1, 2, 3, 4)]
+    out.append(sum(int(r[2]) for r in rows if r[0] != "Host"))   # [4] repacked weights (CPU_REPACK, ...)
+    return out
+
+
+class LlamaCppHost:
+    """Concrete `EngineHost`: measures the box, prices GGUFs, launches/stops
+    llama-server children, and lists the children IT started as residents."""
+
+    def __init__(self, ctx: int = 4096, main_gpu: int = 0,
+                 log_dir: Optional[str] = None):
+        self.ctx = int(ctx)
+        self.main_gpu = int(main_gpu)
+        self.children: "Dict[str, _Child]" = {}
+        self.models: Dict[str, str] = {}
+        self._models_published = False
+        self.refresh_models()
+        self.contracts: Dict[str, dict] = {}
+        # Host constraints handed down by the harness (never knobs): a ceiling
+        # on what this front door may hold, and seats it must never evict.
+        self.gpu_limit: Optional[int] = None
+        self.ram_limit: Optional[int] = None
+        self.protected: set = set()
+        # 🔒static models (DB: the worker's config.residency) — never evicted
+        # once loaded; refreshed before every placement.
+        self.static_keys: set = set()
+        self.server_bin = _nr.server_bin()
+        self.log_dir = log_dir or _os.path.join(
+            _os.path.expanduser("~"), ".fitevict", "run-logs")
+        _os.makedirs(self.log_dir, exist_ok=True)
+        self._port_next = int(_os.environ.get("FITEVICT_PORT_BASE", "8190"))
+
+    # ── measurement ─────────────────────────────────────────────────────────
+    def measure(self) -> HostBudget:
+        gpus = _hw.detect_gpus()
+        g0 = gpus[self.main_gpu] if len(gpus) > self.main_gpu else {}
+        total = _hw.total_vram_bytes(self.main_gpu) or g0.get("memory_total")
+        free = _spill.free_vram_bytes()           # budgetable (reserve removed)
+        if free is None:
+            free = g0.get("memory_free")
+        # a dry-run projection probe (HUGPY_PROBE) is transient — its bytes and
+        # its G7 driver bytes are not taken from the room a placement sees
+        if free is not None:
+            try:
+                from .. import gpu_state as _gs
+                procs = _compute_apps_vram()
+                drv = int(_db_get_driver(self._worker(), self._device_key()) or 0)
+                free = int(free) + sum(int(b) + drv for pid, b in procs.items() if b and _gs._is_probe(int(pid)))
+            except Exception:  # noqa: BLE001
+                pass
+        ram_free = _spill.free_ram_bytes()
+        if self.gpu_limit is not None or self.ram_limit is not None:
+            apps = _compute_apps_vram()
+            mine_vram = mine_ram = 0
+            for ch in self.children.values():
+                if self._alive(ch):
+                    pid = getattr(ch.proc, "pid", None)
+                    mine_vram += int(apps.get(pid) or 0)
+                    mine_ram += int(_proc_rss_bytes(pid) or 0) if pid else 0
+            if self.gpu_limit is not None:
+                total = min(int(total or self.gpu_limit), int(self.gpu_limit))
+                room = max(0, int(self.gpu_limit) - mine_vram)
+                free = room if free is None else min(int(free), room)
+            if self.ram_limit is not None:
+                room = max(0, int(self.ram_limit) - mine_ram)
+                ram_free = room if ram_free is None else min(int(ram_free), room)
+        dev = DeviceBudget(id=self.main_gpu, total_bytes=total, free_bytes=free,
+                           external_floor_bytes=_spill.vram_reserve_bytes())
+        ram_total = None
+        try:
+            import psutil
+            ram_total = int(psutil.virtual_memory().total)
+        except Exception:  # noqa: BLE001
+            ram_total = None
+        return HostBudget(devices=(dev,), ram_free_bytes=ram_free,
+                          ram_total_bytes=ram_total,
+                          ram_reserve_bytes=_spill.ram_reserve_bytes(),
+                          now=_time.time())
+
+    def refresh_static(self) -> None:
+        from . import db as _db
+        got = _db.static_keys(_os.environ.get("FITEVICT_WORKER", "ae"))
+        if got is not None:
+            self.static_keys = got
+
+    def refresh_models(self) -> int:
+        """Re-walk this box's disk (the catalog's source) and publish it to the
+        DB (inference_engine.models) whenever it changed."""
+        found = discover_models()
+        if found != self.models or not self._models_published:
+            self.models = found
+            from . import db as _db
+            rows = []
+            for key, path in sorted(found.items()):
+                w = model_weights(key, path)
+                files = w.get("files") or w.get("weights") or []
+                rows.append({"key": key, "path": path, "model_dir": w.get("dir"),
+                             "quant": w.get("quant"), "engine": engine_of_path(path),
+                             "bytes": (_os.path.getsize(path) if _os.path.exists(path) else None),
+                             "files": files})
+            worker = _os.environ.get("FITEVICT_WORKER", "ae")
+            self._models_published = _db.write_models(worker, rows)
+        return len(self.models)
+
+    def list_residents(self) -> "List[Resident]":
+        apps = _compute_apps_vram()
+        res: List[Resident] = []
+        for key, ch in list(self.children.items()):
+            if not self._alive(ch):
+                continue
+            pid = getattr(ch.proc, "pid", None)
+            vram = apps.get(pid)
+            if vram is not None:
+                ch.vram_at_load = vram
+            res.append(Resident(
+                key=key, device_id=self.main_gpu, vram_bytes=vram,
+                ram_bytes=_proc_rss_bytes(pid) if pid else None,
+                last_used=ch.last_used, calls=ch.calls, pref=VRAM,
+                resident_since=ch.resident_since,
+                protected=key in self.protected or key in self.static_keys))
+        return res
+
+    # ── pricing ──────────────────────────────────────────────────────────────
+    # ── per-call load contract (the caller's knobs; never stored past the call) ─
+    def set_contract(self, key: str, knobs: Optional[dict]) -> dict:
+        """Resolve the caller's knobs for ``key`` into a load contract:
+        ``path`` (gguf_file inside the model's dir, else the elected file) and
+        ``moe`` (True = experts in RAM, False = no expert split, None = auto).
+        Unknown/unsafe knob values fall back to the default, never fail."""
+        knobs = knobs if isinstance(knobs, dict) else {}
+        path = self.models.get(key)
+        want = knobs.get("gguf_file")
+        if path and engine_of_path(path) == "gguf" and isinstance(want, str) and want.strip():
+            d = _os.path.dirname(path)
+            while d and _os.path.basename(d) != key and _os.path.dirname(d) != d:
+                d = _os.path.dirname(d)
+            if _os.path.basename(d) != key:
+                d = _os.path.dirname(path)
+            cand = _os.path.realpath(_os.path.join(d, want.strip()))
+            if cand.startswith(_os.path.realpath(d) + _os.sep) and _os.path.isfile(cand) \
+                    and cand.lower().endswith(".gguf"):
+                path = cand
+        moe = knobs.get("moe")
+        mode = knobs.get("alloc_mode")
+        mode = mode if mode in ("gpu-only", "ram-only", "max-gpu", "max-ram", "explicit") else None
+
+        def _layers(v):
+            try:
+                return int(v) if v is not None and int(v) >= -1 else None
+            except (TypeError, ValueError):
+                return None
+        # ctx pin (ctx_pct of the trained window) -> the launch context; absent
+        # = the host default. 4-bit (bitsandbytes) applies to transformers only.
+        ctx = None
+        try:
+            pct = knobs.get("ctx_pct")
+            if pct is not None and path:
+                if engine_of_path(path) == "transformers":
+                    from . import transformers as _tf
+                    trained = int(_tf.geometry(path).get("ctx_train") or 0)
+                else:
+                    trained = int((_structure_for(path) or {}).get("ctx_train") or 0)
+                if trained:
+                    ctx = max(1024, (int(trained * float(pct) / 100) // 1024) * 1024)
+        except (TypeError, ValueError):
+            ctx = None
+        kvt = str(knobs.get("kv_cache_type") or "f16").lower()
+        kvt = kvt if kvt in ("f16", "q8_0", "q4_0") else "f16"
+        c = {"path": path, "moe": moe if isinstance(moe, bool) else None,
+             "alloc_mode": mode, "ctx": ctx, "kv_type": kvt,
+             "flash_attn": knobs.get("flash_attn") is True or kvt != "f16",
+             "bnb4": knobs.get("bnb_4bit") is True and bool(path) and engine_of_path(path) == "transformers",
+             # explicit placement in llama.cpp terms (legacy 0.2.6 explicit panel)
+             "n_gpu_layers": _layers(knobs.get("attention_gpu_layers", knobs.get("n_gpu_layers"))),
+             "n_cpu_moe": _layers(knobs.get("experts_cpu_layers", knobs.get("n_cpu_moe")))}
+        self.contracts[key] = c
+        return c
+
+    def apply_ctx(self, key: str, info: dict, knobs: Optional[dict]) -> Optional[int]:
+        """The launch context from the DB (operator 2026-10-03): a pinned ctx_pct
+        is that tick's own ctx (kv_cost.ticks), no pin = the history default
+        (model_default_ctx). Sets contract ctx / ctx_start; returns the ctx."""
+        c = self.contracts.get(key)
+        if c is None or not info:
+            return None
+        ticks = info.get("ticks") or {}
+        pct = (knobs or {}).get("ctx_pct")
+        ctx = None
+        if pct is not None:
+            t = ticks.get(str(max(1, min(100, int(pct))))) or {}
+            ctx = int(t["ctx"]) if t.get("ctx") else c.get("ctx")
+            c["ctx_source"] = "pinned"
+        elif info.get("default_ctx"):
+            ctx = int(info["default_ctx"])
+            c["ctx_source"] = f"history ({info.get('basis')}, largest used {info.get('need_tokens')} tokens)"
+        if ctx:
+            c["ctx"] = ctx
+            c["ctx_start"] = ctx
+            c["ctx_ladder"] = sorted({int(v["ctx"]) for v in ticks.values() if isinstance(v, dict) and v.get("ctx")})
+            c["ctx_need"] = info.get("need_tokens")
+        return ctx
+
+    def contract_of(self, key: str) -> dict:
+        return self.contracts.get(key) or {"path": self.models.get(key), "moe": None,
+                                           "alloc_mode": None, "n_gpu_layers": None,
+                                           "n_cpu_moe": None, "ctx": None, "bnb4": False,
+                                           "kv_type": "f16", "flash_attn": False}
+
+    def footprint(self, key: str, quant: Optional[str] = None) -> ModelFootprint:
+        c = self.contract_of(key)
+        path = c["path"]
+        if not path:
+            return ModelFootprint()                # unknown -> planner fails open
+        if engine_of_path(path) == "transformers":
+            from . import transformers as _tf
+            f = _tf.footprint(path, c.get("ctx") or self.ctx, bnb4=bool(c.get("bnb4")),
+                              worker=self._worker(), key=key)
+            return ModelFootprint(
+                weights_bytes=f["weights_bytes"] + f["compute_bytes"],
+                kv_bytes=f["kv_bytes"], total_bytes=f["total_bytes"],
+                layers=f["layers"], moe=False)
+        struct = _structure_for(path)
+        mmproj = _mr.find_mmproj(path)
+        mmproj_bytes = _os.path.getsize(mmproj) if mmproj and _os.path.isfile(mmproj) else 0
+        ngl, ncm = self._placement(c, struct)
+        ctx = c.get("ctx") or self.ctx
+        p = self.project(path, ctx, ngl, ncm, c.get("kv_type") or "f16", bool(c.get("flash_attn")))
+        cuda = 0 if ((key in self.children and self._alive(self.children[key])) or ngl == 0) \
+            else self.cuda_context_bytes()     # RAM-only (ngl 0, device none) has no CUDA process
+        need = _gguf_need(struct, ctx=ctx, n_gpu_layers=ngl, n_cpu_moe=ncm, mmproj_bytes=mmproj_bytes,
+                          gpu_margin=1.0, ram_margin=1.0, cushion_bytes=0)
+        if p:   # formula sheet G2/G5 (fitevict.sizing): measured if this config ran, else page-rounded projection + context
+            from .. import sizing as _S
+            new_proc = bool(cuda)
+            drv = int(_db_get_driver(self._worker(), self._device_key())) if new_proc else 0
+            # KV: llama.cpp's own projected context buffers (KV + recurrent state).
+            # K1 is NOT used over a projection: on hybrid models it omits the
+            # recurrent-state buffers (measured 2026-10-03, Qwen3.6-35B-A3B ctx
+            # 169,984: K1 3,547,136,000 vs llama.cpp 3,744,464,896 -> OOM at load)
+            st = _db_kv_structure(self._worker(), _os.path.basename(path))
+            kvt_ = c.get("kv_type") or "f16"
+            kv_k2 = None
+            if st and ngl < 0 and not ncm:   # K2 (measured structure) for whole-GPU loads
+                cell = int(st["k_cell_bytes"]) + int(st["v_cell_bytes"])
+                cell = cell if kvt_ == "f16" else cell * (17 if kvt_ == "q8_0" else 9) // 32
+                kv_k2 = _S.kv_device_bytes(ctx, cell, 0, int(st.get("rs_bytes") or 0))
+            pred = _S.gguf_predict(p, cuda, measured_process=p.get("measured_process") if new_proc else None,
+                                   kv_exact=kv_k2, driver=drv)
+            kv = int(p["dev_context"])
+            total = int(pred["device_bytes"]) + (0 if pred["exact"] else _S.page(mmproj_bytes))
+            # G8: what the process grows by once it serves (cuBLAS handle +
+            # workspace, pool growth) — must be free after the load
+            if ngl != 0:
+                from . import db as _db8
+                g8, g8_src = _db8.serving_growth(self._worker(), _os.path.basename(path), ctx, ngl, ncm,
+                                                 c.get("kv_type") or "f16")
+                total += int(g8)
+                self.last_g8 = {"bytes": int(g8), "source": g8_src}
+        else:   # llama.cpp could not project: the structure's exact tensor + KV bytes
+            kv = int(need["kv_gpu_bytes"])
+            total = int(need["gpu_bytes"]) + cuda
+        # R1: what a RAM-only load of this config holds in host memory
+        ram_only = None
+        try:
+            from .. import sizing as _S1
+            from . import db as _db1
+            kvt1 = c.get("kv_type") or "f16"
+            mh = _db1.get_measured_host(self._worker(), _os.path.basename(path), ctx, 0, 0, kvt1) or {}
+            p0 = None if (mh.get("anon") is not None) else self.project(path, ctx, 0, 0, kvt1, bool(c.get("flash_attn")))
+            ram_only = int(_S1.ram_only_bytes(p0, _S1.gguf_file_bytes(path) + mmproj_bytes,
+                                              mh.get("anon"), mh.get("file"))["bytes"])
+        except Exception as exc:  # noqa: BLE001
+            print(f"[ram_only] {key}: {exc}")
+        return ModelFootprint(
+            weights_bytes=max(0, total - kv),
+            kv_bytes=kv,
+            total_bytes=total,
+            ram_only_bytes=ram_only,
+            layers=int(need["block_count"]) or None,
+            moe=bool(need["is_moe"]),
+            expert_bytes=int(need["experts_gpu_bytes"] + need["experts_cpu_bytes"]) or None,
+            non_expert_bytes=int(need["gpu_weights_bytes"]) or None,
+        )
+
+    def _placement(self, c: dict, struct: dict) -> "tuple[int, int]":
+        """(n_gpu_layers, n_cpu_moe) the contract asks for (before any partial plan)."""
+        ncm = int(struct.get("block_count") or 0) if (c.get("moe") and struct.get("is_moe")) else 0
+        ngl = -1
+        if c.get("alloc_mode") == "explicit":
+            if c.get("n_gpu_layers") is not None:
+                ngl = int(c["n_gpu_layers"])
+            if c.get("n_cpu_moe") is not None and struct.get("is_moe"):
+                ncm = int(c["n_cpu_moe"])
+        elif c.get("alloc_mode") == "ram-only":
+            ngl, ncm = 0, 0
+        return ngl, ncm
+
+    # ── exact sizing ──────────────────────────────────────────────────────────
+    def _worker(self) -> str:
+        return _os.environ.get("FITEVICT_WORKER", "ae")
+
+    def _device_key(self) -> str:
+        return f"cuda{self.main_gpu}"
+
+    def cuda_context_bytes(self) -> int:
+        """The MEASURED per-process CUDA context on this card (a new process pays
+        it); 0 until the first load on this box has measured it."""
+        from . import db as _db
+        return int(_db.get_cuda_context(self._worker(), self._device_key()) or 0)
+
+    def project(self, path: str, ctx: int, ngl: int, ncm: int, kv: str = "f16",
+                flash: bool = False) -> "Optional[dict]":
+        """llama.cpp's OWN projected device memory for this file at these params
+        (common_params_fit: model / context / compute buffers, no weights
+        loaded), cached in the DB. None when llama.cpp cannot project."""
+        from . import db as _db
+        file = _os.path.basename(path)
+        hit = _db.get_projection(self._worker(), file, ctx, ngl, ncm, kv)
+        if hit and hit.get("dev_self") is not None:
+            return hit
+        import re as _re, select as _select
+        port = self._free_port()
+        argv = [self.server_bin, "-m", path, "--host", "127.0.0.1", "--port", str(port),
+                "-c", str(int(ctx)), "--n-gpu-layers", "all" if int(ngl) < 0 else str(int(ngl)),
+                "-t", "6", "--fit", "on", "-lv", "4", "-np", str(_PARALLEL)]
+        if ncm:
+            argv += ["--n-cpu-moe", str(int(ncm))]
+        if kv != "f16":
+            argv += ["--cache-type-k", kv, "--cache-type-v", kv]
+        if flash or kv != "f16":
+            argv += ["-fa", "on"]
+        env = dict(_os.environ)
+        env["CUDA_VISIBLE_DEVICES"] = str(self.main_gpu)
+        env["HUGPY_PROBE"] = "projection"   # gpu_state: a transient probe, never external use
+        if int(ngl) == 0:          # RAM-only: no GPU at all
+            argv += ["-dev", "none"]
+            env["CUDA_VISIBLE_DEVICES"] = ""
+        from ..lifted.procutil import popen_detached, terminate_tree
+        proc = popen_detached(argv, stdout=_subprocess.PIPE, stderr=_subprocess.STDOUT, env=env)
+        dev = host = None
+        deadline = _time.time() + 120
+        row = _re.compile(r"CUDA\d+[^|]*\|.*?\(\s*(\d+)\s*=\s*(\d+)\s*\+\s*(\d+)\s*\+\s*(\d+)\s*\)")
+        hrow = _re.compile(r"-\s*Host\s*\|\s*(\d+)\s*=\s*(\d+)\s*\+\s*(\d+)\s*\+\s*(\d+)")
+        try:
+            buf = b""
+            while _time.time() < deadline and proc.poll() is None:
+                r, _, _ = _select.select([proc.stdout], [], [], 1.0)
+                if not r:
+                    continue
+                chunk = _os.read(proc.stdout.fileno(), 65536)
+                if not chunk:
+                    break
+                buf += chunk
+                text = buf.decode("utf-8", "replace")
+                if dev is None:
+                    m = row.search(text)
+                    if m:
+                        dev = [int(x) for x in m.groups()]
+                if "projected to use" in text:      # the first breakdown block is complete
+                    host = host_rows_first_block(text)
+                    break
+        finally:
+            try:
+                terminate_tree(proc)
+                proc.wait(timeout=20)
+            except Exception:  # noqa: BLE001
+                pass
+            # wait until the driver has RELEASED the probe's device memory (NVML
+            # no longer lists it) — a placement must never price around a dying probe
+            _deadline = _time.time() + 30.0
+            while proc.pid in _compute_apps_vram() and _time.time() < _deadline:
+                _time.sleep(0.02)
+        if dev is None and int(ngl) == 0 and host is not None:
+            dev = [0, 0, 0, 0]       # device none: nothing on the GPU
+        if dev is None:
+            return None
+        M = 2 ** 20
+        out = {"dev_self": dev[0] * M, "dev_model": dev[1] * M, "dev_context": dev[2] * M,
+               "dev_compute": dev[3] * M,
+               "host_model": host[1] * M if host else None, "host_context": host[2] * M if host else None,
+               "host_compute": host[3] * M if host else None,
+               "host_repack": host[4] * M if host else None}
+        _db.put_projection(self._worker(), file, ctx, ngl, ncm, kv, out)
+        return out
+
+    # ── execution ─────────────────────────────────────────────────────────────
+    def _alive(self, ch: _Child) -> bool:
+        p = ch.proc
+        return bool(p) and p.poll() is None
+
+    def evict(self, key: str, reason: str = "evict-to-fit") -> int:
+        """Stop ``key``'s process and MEASURE the unload: NVML process bytes and
+        device free before, the exit time, and the time the card's free memory
+        rose by those bytes (polled every 20 ms, up to 30 s). Recorded in
+        inference_engine.evictions; returns the bytes actually freed."""
+        ch = self.children.get(key)
+        if ch is None:
+            return 0
+        from ..lifted.procutil import terminate_tree
+        from ..lifted import nvml as _nvml
+        from . import db as _db
+
+        def _free():
+            for d in (_nvml.devices() or []):
+                if d["index"] == int(self.main_gpu):
+                    return d.get("free")
+            return None
+        pid = getattr(ch.proc, "pid", None)
+        held = _compute_apps_vram().get(pid)
+        free_before = _free()
+        started = _time.time()
+        terminate_tree(ch.proc)
+        try:
+            ch.proc.wait(timeout=30)
+        except Exception:  # noqa: BLE001
+            pass
+        exited = _time.time()
+        released = None
+        free_after = _free()
+        if held and free_before is not None:
+            deadline = exited + 30.0
+            while free_after is not None and free_after - free_before < int(held) and _time.time() < deadline:
+                _time.sleep(0.02)
+                free_after = _free()
+            if free_after is not None and free_after - free_before >= int(held):
+                released = _time.time()
+        elif not held:
+            released = exited            # nothing on the GPU (RAM-only) — released at exit
+        self.children.pop(key, None)
+        _gpu_changed(f"evict {key}")
+        try:   # an eviction frees room: missing sizing facts may be measurable now
+            from .. import gpu_state as _gsw
+            _gsw.FACTS_WAKE.set()
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            _db.put_eviction({"worker": self._worker(), "key": key,
+                              "engine": engine_of_path(ch.model_file), "request_id": _CURRENT_REQUEST.get("id"),
+                              "reason": reason, "pid": pid, "process_bytes": held,
+                              "free_before": free_before, "free_after": free_after,
+                              "started_at": started, "exited_at": exited, "released_at": released})
+        except Exception as exc:  # noqa: BLE001
+            print(f"[eviction] record failed: {exc}")
+        if free_before is not None and free_after is not None:
+            freed = max(0, int(free_after) - int(free_before))
+            if held and released and freed > int(held):     # G7: driver bytes per process
+                try:
+                    _db.put_cuda_context(self._worker(), self._device_key() + ":driver", freed - int(held))
+                except Exception:  # noqa: BLE001
+                    pass
+            return freed
+        return int(held or 0)
+
+    def load(self, key: str, plan: FitPlan) -> None:
+        """Launch a llama-server child per the committed plan. argv flag mapping
+        follows the lifted slot_agent._build_cmd reference."""
+        contract = dict(self.contract_of(key))
+        path = contract["path"] or self.models[key]
+        if engine_of_path(path) == "transformers":
+            return self._load_transformers(key, path, plan, contract)
+        struct = _structure_for(path)
+        mmproj = _mr.find_mmproj(path)
+        mmproj_bytes = _os.path.getsize(mmproj) if mmproj and _os.path.isfile(mmproj) else 0
+
+        # Placement from the plan: partial -> the offload's layer/expert split;
+        # otherwise the whole model on the GPU (-ngl -1), no forced expert split.
+        n_gpu_layers = -1
+        n_cpu_moe: Optional[int] = None
+        if getattr(plan, "placement", None) == "ram":
+            n_gpu_layers = 0                       # the plan put 0 B on the card
+        elif plan.action == "partial" and plan.offload is not None:
+            n_gpu_layers = int(plan.offload.n_gpu_layers)
+            n_cpu_moe = plan.offload.n_cpu_moe
+        # Caller's MoE knob: True = every layer on the card with ALL experts in
+        # RAM; False = never split experts (a partial plan keeps its layer split).
+        if contract.get("moe") is True and struct.get("is_moe") and n_gpu_layers != 0:
+            n_gpu_layers, n_cpu_moe = -1, int(struct.get("block_count") or 0) or None
+        elif contract.get("moe") is False:
+            n_cpu_moe = None
+        # explicit allocation: the operator's exact layer counts (llama.cpp terms)
+        if contract.get("alloc_mode") == "explicit":
+            if contract.get("n_gpu_layers") is not None:
+                n_gpu_layers = int(contract["n_gpu_layers"])
+            if contract.get("n_cpu_moe") is not None and struct.get("is_moe"):
+                n_cpu_moe = int(contract["n_cpu_moe"]) or None
+        elif contract.get("alloc_mode") == "ram-only" or contract.get("decided_mode") == "ram-only":
+            n_gpu_layers, n_cpu_moe = 0, None        # pinned, or sizing.decide() chose RAM-only
+        ctx = contract.get("ctx") or self.ctx
+        need = _gguf_need(struct, ctx=ctx, n_gpu_layers=n_gpu_layers,
+                          n_cpu_moe=n_cpu_moe or 0, mmproj_bytes=mmproj_bytes,
+                          gpu_margin=1.0, ram_margin=1.0, cushion_bytes=0)
+
+        kvt0 = contract.get("kv_type") or "f16"
+        port = self._free_port()
+        # Flag mapping follows the lifted slot_agent._build_cmd reference: when
+        # the binary is --fit capable, turn its own auto-fit OFF (fitevict is the
+        # fit authority now) and pass -ngl "all" for the whole-model case.
+        fit_capable = _server_supports_flag(self.server_bin, "--fit")
+        ngl_arg = "all" if (fit_capable and n_gpu_layers == -1) else str(n_gpu_layers)
+        # max-gpu (pinned): llama.cpp's own --fit picks the layer split that fits
+        # the card, keeping a DERIVED margin = G8 (serving growth) + G7 (driver
+        # bytes per process) + one PAGE per device buffer (model, KV, RS,
+        # compute: the page rounding llama.cpp's raw sizes do not include)
+        fit_solver = fit_capable and contract.get("alloc_mode") == "max-gpu" and n_gpu_layers != 0 \
+            and not n_cpu_moe
+        argv = [self.server_bin, "-m", path,
+                "--host", "127.0.0.1", "--port", str(port)]
+        if not fit_solver:
+            argv += ["--n-gpu-layers", ngl_arg]
+        argv += ["-c", str(ctx), "-t", "6", "-np", str(_PARALLEL)]
+        if fit_solver:
+            from . import db as _dbf
+            from .. import sizing as _Sf
+            g8 = _dbf.serving_growth(self._worker(), _os.path.basename(path), ctx, -1, 0, kvt0)[0]
+            g7 = int(_db_get_driver(self._worker(), self._device_key()) or 0)
+            margin = int(g8) + g7 + 4 * _Sf.PAGE
+            argv += ["--fit", "on", "-fitt", str(-(-margin // _Sf.MiB))]
+        elif fit_capable:
+            argv += ["--fit", "off"]
+        argv += ["-lv", "4"]          # formula sheet G1 source B: per-buffer sizes in the load log
+        if n_cpu_moe and _server_supports_flag(self.server_bin, "--n-cpu-moe"):
+            argv += ["--n-cpu-moe", str(int(n_cpu_moe))]
+        if mmproj:
+            argv += ["--mmproj", mmproj]
+        kvt = contract.get("kv_type") or "f16"
+        if kvt != "f16":
+            argv += ["--cache-type-k", kvt, "--cache-type-v", kvt]
+        if contract.get("flash_attn") or kvt != "f16":
+            argv += ["-fa", "on"]
+
+        if n_gpu_layers == 0:      # RAM-only: no GPU at all (no CUDA process, no device buffers)
+            argv += ["-dev", "none"]
+        logf = open(_os.path.join(self.log_dir, f"{key}.{port}.log"), "ab")
+        from ..lifted.procutil import popen_detached
+        env = dict(_os.environ)
+        if self.main_gpu is not None:
+            env["CUDA_VISIBLE_DEVICES"] = str(self.main_gpu)
+        if n_gpu_layers == 0:
+            env["CUDA_VISIBLE_DEVICES"] = ""
+        staged = _time.time()
+        proc = popen_detached(argv, stdout=logf, stderr=logf, env=env)
+        ch = _Child(key=key, proc=proc, port=port, model_file=path, struct=struct,
+                    need=need, n_gpu_layers=n_gpu_layers, n_cpu_moe=n_cpu_moe,
+                    ctx=ctx, total_layers=int(need["block_count"]) or None,
+                    is_moe=bool(need["is_moe"]), quant=_os.path.basename(path),
+                    mmproj=mmproj, resident_since=staged)
+        ch.weights_staged_at = staged
+        ch.argv = list(argv)
+        ch.contract = contract
+        self.children[key] = ch
+        ok, err = self._wait_healthy(ch)
+        if ok and fit_solver:     # the split llama.cpp chose: "offloaded X/Y layers to GPU"
+            try:
+                import re as _ref
+                with open(_os.path.join(self.log_dir, f"{key}.{port}.log"), "r", encoding="utf-8", errors="replace") as fh:
+                    m = list(_ref.finditer(r"offloaded (\d+)/(\d+) layers to GPU", fh.read()))
+                if m:
+                    ch.n_gpu_layers = n_gpu_layers = int(m[-1].group(1))
+            except Exception:  # noqa: BLE001
+                pass
+        if ok:
+            ch.weights_loaded_at = _time.time()
+            self._measure_cuda_context(ch, path, ctx, n_gpu_layers, n_cpu_moe or 0, kvt,
+                                       bool(contract.get("flash_attn")), mmproj_bytes)
+            if n_gpu_layers == 0:          # R1: RAM-only host bytes, measured
+                try:
+                    from . import db as _dbh
+                    rss = {}
+                    with open(f"/proc/{proc.pid}/status") as fh:
+                        for line in fh:
+                            if line.startswith(("RssAnon:", "RssFile:")):
+                                rss[line.split(":")[0]] = int(line.split()[1]) * 1024
+                    if rss:
+                        _dbh.put_measured_host(self._worker(), _os.path.basename(path), ctx, 0, 0, kvt,
+                                               rss.get("RssAnon", 0), rss.get("RssFile", 0))
+                except Exception as exc:  # noqa: BLE001
+                    print(f"[host] measure failed: {exc}")
+        else:
+            ch.load_error = err
+        _gpu_changed(f"load {key}")
+
+    def _load_transformers(self, key: str, path: str, plan: FitPlan, contract: dict) -> None:
+        """Launch the lifted tf_child for a transformers model per the plan:
+        ram -> CPU; partial -> the plan's GPU share, the rest in RAM; else the
+        whole model on the card (device_map=auto capped to it, no CPU spill)."""
+        from . import transformers as _tf
+        ctx = contract.get("ctx") or self.ctx
+        bnb4 = bool(contract.get("bnb4"))
+        f = _tf.footprint(path, ctx, bnb4=bnb4, worker=self._worker(), key=key)
+        mode = contract.get("alloc_mode")
+        if getattr(plan, "placement", None) == "ram" or mode == "ram-only" or contract.get("decided_mode") == "ram-only":
+            placement, gpu_b = "ram", None
+        elif plan.action == "partial" and plan.offload is not None and f["layers"]:
+            placement = "split"
+            frac = max(0, int(plan.offload.n_gpu_layers)) / float(f["layers"])
+            gpu_b = int(f["weights_bytes"] * frac)
+        else:
+            placement = "gpu"
+            gpu_b = f["total_bytes"]
+        port = self._free_port()
+        argv = _tf.argv(key, path, port, ctx, placement=placement, gpu_bytes=gpu_b, bnb4=bnb4)
+        logf = open(_os.path.join(self.log_dir, f"{key}.{port}.log"), "ab")
+        from ..lifted.procutil import popen_detached
+        env = dict(_os.environ)
+        if self.main_gpu is not None and placement != "ram":
+            env["CUDA_VISIBLE_DEVICES"] = str(self.main_gpu)
+        if placement == "ram":
+            env["CUDA_VISIBLE_DEVICES"] = ""
+        staged = _time.time()
+        proc = popen_detached(argv, stdout=logf, stderr=logf, env=env)
+        layers = f["layers"]
+        ngl = 0 if placement == "ram" else (-1 if placement == "gpu"
+                                             else int(plan.offload.n_gpu_layers))
+        ch = _Child(key=key, proc=proc, port=port, model_file=path, struct={},
+                    need={"gpu_bytes": gpu_b or 0, "kv_gpu_bytes": f["kv_bytes"] if placement != "ram" else 0,
+                          "gpu_weights_bytes": f["weights_bytes"] if placement == "gpu" else (gpu_b or 0)},
+                    n_gpu_layers=ngl, n_cpu_moe=None, ctx=ctx, total_layers=layers,
+                    is_moe=False, quant="dir-bnb4" if bnb4 else "dir", mmproj=None, resident_since=staged)
+        ch.weights_staged_at = staged
+        ch.argv = list(argv)
+        ch.contract = contract
+        self.children[key] = ch
+        ok, err = self._wait_healthy(ch, hard_cap=1800.0, stall=180.0)
+        if ok:
+            ch.weights_loaded_at = _time.time()
+            if placement != "ram":
+                try:
+                    from . import db as _db
+                    used = _compute_apps_vram().get(getattr(proc, "pid", None))
+                    if used:
+                        _db.put_tf_measure(self._worker(), key, bnb4, ctx,
+                                           tensor_bytes=f["weights_bytes"], load_bytes=int(used))
+                        if int(used) > f["weights_bytes"]:
+                            _db.put_cuda_context(self._worker(), "torch", int(used) - f["weights_bytes"])
+                except Exception as exc:  # noqa: BLE001
+                    print(f"[tf_measure] {key}: {exc}")
+        else:
+            ch.load_error = err
+        _gpu_changed(f"load {key}")
+
+    def record_host(self, key: str) -> None:
+        """R1 after a call: a RAM-only resident's RssAnon / RssFile grow as mmap'd
+        pages fault in — keep the configuration's MAX measured host bytes."""
+        ch = self.children.get(key)
+        cfg = self.config_of(key)
+        if ch is None or cfg is None or cfg[2] != 0:
+            return
+        from . import db as _db
+        rss = {}
+        try:
+            with open(f"/proc/{ch.proc.pid}/status") as fh:
+                for line in fh:
+                    if line.startswith(("RssAnon:", "RssFile:")):
+                        rss[line.split(":")[0]] = int(line.split()[1]) * 1024
+        except OSError:
+            return
+        old = _db.get_measured_host(self._worker(), *cfg) or {}
+        anon = max(rss.get("RssAnon", 0), int(old.get("anon") or 0))
+        filb = max(rss.get("RssFile", 0), int(old.get("file") or 0))
+        if (anon, filb) != (old.get("anon"), old.get("file")):
+            _db.put_measured_host(self._worker(), *cfg, anon, filb)
+
+    def live_room(self) -> "tuple[Optional[int], Optional[int]]":
+        """(room_gpu, room_ram) NOW by the shared formulas (sizing.room_gpu /
+        room_ram — central computes the console's room with the same ones)."""
+        from .. import sizing as _S
+        from .. import gpu_state as _gs
+        from ..lifted import nvml as _nvml
+        rg = rr = None
+        try:
+            d = next((x for x in (_nvml.devices() or []) if x["index"] == int(self.main_gpu)), None)
+            procs = _compute_apps_vram()
+            ours = {getattr(c.proc, "pid", None) for c in self.children.values() if self._alive(c)}
+            static = {getattr(c.proc, "pid", None) for k, c in self.children.items()
+                      if self._alive(c) and k in (getattr(self, "static_keys", None) or set())}
+            probes = {p for p in procs if _gs._is_probe(int(p))}
+            if d and d.get("total") is not None:
+                rg = _S.room_gpu({"usable": int(d["total"]) - int(d.get("reserved") or 0), "used": int(d["used"]),
+                                  "processes": procs}, ours - {None}, static - {None}, probes,
+                                 int(_db_get_driver(self._worker(), self._device_key()) or 0))
+            mem = {}
+            with open("/proc/meminfo") as fh:
+                for line in fh:
+                    k, _, v = line.partition(":")
+                    if v.split():
+                        mem[k] = int(v.split()[0]) * 1024
+            anon = {}
+            for pid in ours - {None}:
+                try:
+                    with open(f"/proc/{pid}/status") as fh:
+                        for line in fh:
+                            if line.startswith("RssAnon:"):
+                                anon[str(pid)] = int(line.split()[1]) * 1024
+                except OSError:
+                    pass
+            rr = _S.room_ram(mem.get("MemAvailable", 0), anon, static - {None})
+        except Exception as exc:  # noqa: BLE001
+            print(f"[room] {exc}")
+        return rg, rr
+
+    def ensure_facts(self, key: str, facts: dict, kv: str = "f16") -> bool:
+        """Measure the projection points decide() is missing: llama.cpp dry runs
+        at the ladder's two ends for the GPU (ngl -1) and RAM-only (ngl 0) —
+        every tick in between is linear from them. One-off per quant (facts are
+        keyed to the exact configuration and never go stale). Returns True when
+        anything was measured."""
+        c = self.contract_of(key)
+        path = c.get("path") or self.models.get(key)
+        ladder = sorted(int(x) for x in (facts.get("ladder") or []))
+        if not path or not ladder or engine_of_path(path) == "transformers":
+            return False
+        have_g = {int(p["ctx"]) for p in facts.get("gpu_points") or [] if p.get("model") is not None}
+        have_r = {int(p["ctx"]) for p in facts.get("ram_points") or [] if p.get("host_repack") is not None}
+        did = False
+        for ctx in {ladder[0], ladder[-1]}:
+            if ctx not in have_g:
+                did |= self.project(path, ctx, -1, 0, kv) is not None
+            if ctx not in have_r:
+                did |= self.project(path, ctx, 0, 0, kv) is not None
+        return did
+
+    def config_of(self, key: str) -> "Optional[tuple]":
+        """(file, ctx, n_gpu_layers, n_cpu_moe, kv) of a resident — the key every
+        measured term (G3/G5/G8) is stored under."""
+        ch = self.children.get(key)
+        if ch is None or engine_of_path(ch.model_file) == "transformers":
+            return None
+        kvt = (getattr(ch, "contract", None) or {}).get("kv_type") or "f16"
+        return (_os.path.basename(ch.model_file), int(ch.ctx), int(ch.n_gpu_layers), int(ch.n_cpu_moe or 0), kvt)
+
+    def measure_full_ctx(self, key: str) -> "Optional[dict]":
+        """Formula sheet G8/A: send the resident ONE request that fills its whole
+        context, through the SAME path and parameters real traffic uses
+        (self.chat -> /v1/chat/completions; measured 2026-10-03: the raw
+        /completion path grows the process 2,097,152 B less than chat does).
+        Prompt = the chat template + k copies of one token, k = n_ctx − template
+        tokens − 1 (the single generated token takes the last position). Then
+        read the NVML process bytes; stored on the configuration's row."""
+        import json as _json, urllib.request as _ur
+        from . import db as _db
+        ch = self.children.get(key)
+        cfg = self.config_of(key)
+        if ch is None or cfg is None or cfg[2] == 0:
+            return None
+        pid = getattr(ch.proc, "pid", None)
+        base = ch.base_url
+
+        def _post(path, body, timeout):
+            req = _ur.Request(base + path, _json.dumps(body).encode(), {"Content-Type": "application/json"})
+            return _json.loads(_ur.urlopen(req, timeout=timeout).read())
+        props = _json.loads(_ur.urlopen(base + "/props", timeout=10).read())
+        n_ctx = int((props.get("default_generation_settings") or {}).get("n_ctx") or ch.ctx)
+        empty = _post("/apply-template", {"messages": [{"role": "user", "content": ""}]}, 10).get("prompt") or ""
+        overhead = len(_post("/tokenize", {"content": empty, "parse_special": True}, 10).get("tokens") or [])
+        one = _post("/tokenize", {"content": " word word"}, 10).get("tokens") or []
+        if len(one) != 2 or one[0] != one[1]:
+            return None                      # " word" is not one token here: cannot size exactly
+        k = n_ctx - overhead - 1
+        # repeat the fill until the process stops growing: measured 2026-10-03,
+        # the SECOND full-context request adds one more 2 MiB allocation, then
+        # it plateaus — the max is reached when two readings agree
+        before = _compute_apps_vram().get(pid)
+        t0 = _time.time()
+        readings = []
+        while True:
+            res = self.chat(key, [{"role": "user", "content": " word" * k}], max_tokens=1)
+            if not res.get("ok"):
+                return None
+            readings.append(_compute_apps_vram().get(pid))
+            if len(readings) >= 2 and readings[-1] == readings[-2]:
+                break
+        secs = _time.time() - t0
+        after = readings[-1]
+        if not after:
+            return None
+        used = res.get("prompt_tokens")
+        rid = "g8-" + __import__("uuid").uuid4().hex[:16]
+        _db.put_full_ctx(self._worker(), *cfg, int(after), int(used or k + overhead), secs, rid)
+        return {"request_id": rid, "prompt_tokens": used, "n_ctx": n_ctx, "template_tokens": overhead,
+                "readings": readings, "fills": len(readings),
+                "prefill_s": secs, "process_before": before, "process_after": after, "config": cfg}
+
+    def _measure_cuda_context(self, ch, path, ctx, ngl, ncm, kv, flash, mmproj_bytes) -> None:
+        """Formula sheet G3 + G5: process = NVML bytes of the new process;
+        context = process − Σ page(device buffers from its load log)."""
+        try:
+            from .. import sizing as _S
+            from . import db as _db
+            pid = getattr(ch.proc, "pid", None)
+            used = _compute_apps_vram().get(pid)
+            logp = _os.path.join(self.log_dir, f"{ch.key}.{ch.port}.log")
+            with open(logp, "r", encoding="utf-8", errors="replace") as fh:
+                bufs = _S.load_log_buffers(fh.read())
+            dev = [b for (d, _k, b) in bufs if d.startswith("CUDA") and d != "CUDA_Host"]
+            if not used or not dev:
+                return
+            context = _S.gguf_context(int(used), dev)
+            _db.put_measured(self._worker(), _os.path.basename(path), ctx, ngl, ncm, kv, int(used), context)
+            # K2: the exact KV / recurrent-state structure + the engine's slot count
+            try:
+                with open(logp, "r", encoding="utf-8", errors="replace") as fh2:
+                    st = _S.kv_structure_from_log(fh2.read())
+                if st:
+                    import json as _j, urllib.request as _u
+                    slots = _j.loads(_u.urlopen(ch.base_url + "/props", timeout=10).read()).get("total_slots")
+                    _db.put_kv_structure(self._worker(), _os.path.basename(path), st, slots, ctx, logp)
+                    if st["kv_type"] == "f16":
+                        _db.rewrite_ticks(_os.path.basename(path), st)
+            except Exception as exc:  # noqa: BLE001
+                print(f"[kv_structure] {exc}")
+            if context > 0:
+                _db.put_cuda_context(self._worker(), self._device_key(), context)
+        except Exception as exc:  # noqa: BLE001
+            print(f"[measure] failed: {exc}")
+
+    def _free_port(self) -> int:
+        """Next port from the base that nothing is bound to. A port held by a
+        stray llama-server would answer our health check for a child that
+        never bound it."""
+        while True:
+            port = self._port_next
+            self._port_next += 1
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as s:
+                try:
+                    s.bind(("127.0.0.1", port))
+                except OSError:
+                    continue
+            return port
+
+    # health wait (lifted slot_agent._wait_healthy logic: progress/stall aware)
+    def _wait_healthy(self, ch: _Child, hard_cap: float = 600.0,
+                      stall: float = 90.0) -> "tuple[bool, Optional[str]]":
+        start = _time.time()
+        last_progress = 0
+        last_progress_ts = start
+        while True:
+            if not self._alive(ch):
+                rc = getattr(ch.proc, "returncode", None)
+                return False, f"child exited rc={rc}"
+            if self._health(ch) and self._alive(ch):
+                return True, None
+            now = _time.time()
+            if now - start >= hard_cap:
+                return False, f"hard cap {hard_cap:.0f}s"
+            pid = getattr(ch.proc, "pid", None)
+            cur = (_proc_rss_bytes(pid) or 0) + (_compute_apps_vram().get(pid, 0))
+            if cur - last_progress >= 8 * 2 ** 20:
+                last_progress, last_progress_ts = cur, now
+            elif now - last_progress_ts >= stall:
+                return False, f"stalled (no RSS/VRAM progress {stall:.0f}s)"
+            _time.sleep(1.0)
+
+    def _health(self, ch: _Child) -> bool:
+        try:
+            req = _urllib.Request(ch.base_url + "/health")
+            with _urllib.urlopen(req, timeout=2.0) as r:
+                return r.status == 200
+        except Exception:  # noqa: BLE001
+            return False
+
+    # ── a real chat call through the running seat ─────────────────────────────
+    def chat(self, key: str, messages: list, max_tokens: int = 64) -> dict:
+        ch = self.children[key]
+        forwarded = {"messages": messages, "max_tokens": max_tokens,
+                     "temperature": 0.1, "cache_prompt": False}
+        body = _json.dumps(forwarded).encode()
+        req = _urllib.Request(ch.base_url + "/v1/chat/completions", data=body,
+                              headers={"Content-Type": "application/json"})
+        call_start = _time.time()
+        try:
+            with _urllib.urlopen(req, timeout=600) as r:
+                payload = _json.loads(r.read().decode("utf-8", "replace"))
+            ok, error = True, None
+        except Exception as exc:  # noqa: BLE001
+            payload, ok, error = {}, False, repr(exc)
+        responded = _time.time()
+        ch.last_used = responded
+        ch.calls += 1
+
+        timings = payload.get("timings") if isinstance(payload, dict) else {}
+        usage = payload.get("usage") if isinstance(payload, dict) else {}
+        usage = usage if isinstance(usage, dict) else {}
+        comp = (usage.get("completion_tokens")
+                or (timings.get("predicted_n") if isinstance(timings, dict) else None))
+        split = _tm.generation_split(timings, elapsed_s=responded - call_start,
+                                     completion_tokens=comp)
+        tok_s = _tm.tok_s_from_timings(payload)
+        text = ""
+        try:
+            text = payload["choices"][0]["message"]["content"]
+        except Exception:  # noqa: BLE001
+            pass
+        prompt_s = split.get("prompt_s")
+        gen_s = split.get("generation_s")
+        first_token_at = call_start + (prompt_s or 0.0)
+        ended_at = first_token_at + (gen_s or 0.0)
+        return {
+            "ok": ok, "error": error, "payload": payload, "text": text,
+            "forwarded_body": forwarded,
+            "timings": timings, "usage": usage, "tok_s": tok_s, "split": split,
+            "call_start": call_start, "first_token_at": first_token_at,
+            "ended_at": ended_at, "responded_at": responded,
+            "prompt_tokens": usage.get("prompt_tokens")
+            or (timings.get("prompt_n") if isinstance(timings, dict) else None),
+            "completion_tokens": comp,
+            "decode_tokens": split.get("gen_tokens"),
+        }
+
+    def shutdown(self) -> None:
+        for key in list(self.children):
+            self.evict(key, reason="front door shutdown")
+
+
+__all__ = ["gguf_footprint", "LlamaCppHost", "discover_models", "model_weights", "engine_of_path"]