@nm-lang/cli 0.4.0 → 0.6.0

package/python/nm_bridge.py

@@ -0,0 +1,524 @@
+"""Bounded local N/M JSON/CLI bridge (Python 3.10+, standard library only).
+
+Not a Python evaluator, checkpoint, hardware connector or permission-bearing IR.
+The npm CLI must be built/installed separately. No network or shell is used here.
+"""
+from __future__ import annotations
+
+import copy
+import html
+import importlib.metadata
+import json
+import math
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from collections.abc import Mapping, Sequence
+
+FORMAT = "nm-python-bridge"
+VERSION = 1
+MAX_REQUEST_BYTES = 262_144
+MAX_RESPONSE_BYTES = 4_194_304
+MAX_STDERR_BYTES = 65_536
+MAX_REQUEST_DEPTH = 32
+MAX_RESPONSE_DEPTH = 64
+
+_COPY = {
+    "en": {
+        "input": "Invalid or oversized JSON bridge input.",
+        "transport": "The local CLI did not return a valid complete bridge response.",
+        "timeout": "Bridge deadline exceeded; the process was killed. No completed precision evidence is available.",
+        "cancel": "Bridge cancelled; the process was killed. No completed result is available.",
+        "output": "Bridge output exceeded its byte limit; no partial result was accepted.",
+        "node": "Node.js was not found in an absolute PATH directory outside the working directory. Install Node.js or supply a trusted command sequence.",
+        "cli": "A trusted absolute N/M CLI file is required. Install the adjacent npm CLI or supply cli_path= or a trusted command sequence.",
+        "title": "N/M local bridge", "status": "Execution succeeded", "failed": "Execution failed",
+        "rejected": "Request rejected", "shots": "Total shots used / budget", "remaining": "Unallocated shots",
+        "pilot": "Pilot shots (allocation only)", "held_out": "Held-out estimation shots",
+        "cost": "Final sampled cost", "observed": "Latest observed cost (not a final-parameter certificate)",
+        "interval": "Simultaneous 95% confidence interval", "se": "Standard error",
+        "precision": "Final-cost precision target", "bound": "Absolute error bound", "floor": "Numeric resolution floor",
+        "required_shots": "Estimated shots needed for final cost", "above_limit": "Above the 4096 limit",
+        "estimate_assumptions": "Estimate assumptions",
+        "estimate_large": "Estimate exceeds the safe integer range", "estimate_resolution": "Target cannot be certified at the current numeric resolution",
+        "estimate_note": "Assumes final estimation-group proportions and the current confidence calculation; final-cost shots only, not a total training budget or a guarantee. No extra shots are taken.",
+        "met": "met", "not-met": "not met", "incomplete": "incomplete", "source": "Original source",
+        "notice": "Local record, not a signature. Confidence applies to the recorded sampling assumptions; it is not a convergence, optimum, hardware or numerical-model certificate. Replaying source requires independent caller permission.",
+        "field": "Field", "value": "Value",
+        "unavailable": "unavailable",
+    },
+    "tr": {
+        "input": "JSON köprü girdisi geçersiz veya boyut sınırını aşıyor.",
+        "transport": "Yerel CLI geçerli ve tam bir köprü yanıtı döndürmedi.",
+        "timeout": "Köprü süre sınırı aşıldı; işlem sonlandırıldı. Tamamlanmış hassasiyet kanıtı yoktur.",
+        "cancel": "Köprü iptal edildi; işlem sonlandırıldı. Tamamlanmış sonuç yoktur.",
+        "output": "Köprü çıktısı bayt sınırını aştı; kısmi sonuç kabul edilmedi.",
+        "node": "Çalışma dizini dışındaki mutlak PATH dizinlerinde Node.js bulunamadı. Node.js kurun veya güvenilir bir komut dizisi verin.",
+        "cli": "Güvenilir mutlak N/M CLI dosyası gerekir. Komşu npm CLI'yi kurun veya cli_path= ya da güvenilir bir komut dizisi verin.",
+        "title": "N/M yerel köprüsü", "status": "Yürütme başarılı", "failed": "Yürütme başarısız",
+        "rejected": "İstek reddedildi", "shots": "Kullanılan toplam ölçüm / bütçe", "remaining": "Dağıtılmamış ölçüm",
+        "pilot": "Pilot ölçümler (yalnız dağılım için)", "held_out": "Ayrı değerlendirme ölçümleri",
+        "cost": "Son örnek maliyet", "observed": "Son gözlenen maliyet (son parametrelerin belgesi değildir)",
+        "interval": "Eşzamanlı %95 güven aralığı", "se": "Standart hata",
+        "precision": "Son maliyet hassasiyet hedefi", "bound": "Mutlak hata sınırı", "floor": "Sayısal çözünürlük alt sınırı",
+        "required_shots": "Son maliyet için tahmini ölçüm ihtiyacı", "above_limit": "4096 sınırının üzerinde",
+        "estimate_assumptions": "Tahmin varsayımları",
+        "estimate_large": "Tahmin güvenli tamsayı aralığının üzerinde", "estimate_resolution": "Hedef mevcut sayısal çözünürlükle doğrulanamaz",
+        "estimate_note": "Son değerlendirmedeki grup oranları ve mevcut güven hesabı varsayılır; yalnız son maliyet ölçümleridir, toplam eğitim bütçesi veya garanti değildir. Ek ölçüm alınmaz.",
+        "met": "karşılandı", "not-met": "karşılanmadı", "incomplete": "tamamlanmadı", "source": "Özgün kaynak",
+        "notice": "Yerel kayıttır; imza değildir. Güven aralığı kayıtlı örnekleme varsayımları için geçerlidir; yakınsama, optimum, donanım veya sayısal model belgesi değildir. Yeniden yürütme bağımsız çağıran izni gerektirir.",
+        "field": "Alan", "value": "Değer",
+        "unavailable": "belirlenmedi",
+    },
+}
+
+
+class NMBridgeError(RuntimeError):
+    """Transport/validation failure. It never contains a partial success result."""
+    def __init__(self, code: str, key: str, locale: str = "en"):
+        self.code = code
+        super().__init__(f"{code}: {_COPY[locale][key]}")
+
+
+def _resolve_node(locale: str) -> str:
+    """Search explicit absolute PATH entries, never Windows' implicit cwd search."""
+    try:
+        working_directory = Path.cwd().resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise NMBridgeError("NM-PY-011", "node", locale) from None
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry or not Path(entry).is_absolute():
+            continue
+        try:
+            directory = Path(entry).resolve(strict=True)
+            if directory == working_directory:
+                continue
+            executable = (directory / ("node.exe" if os.name == "nt" else "node")).resolve(strict=True)
+            if executable.parent != working_directory and executable.is_file() and os.access(executable, os.X_OK):
+                return str(executable)
+        except (OSError, RuntimeError, ValueError):
+            continue
+    raise NMBridgeError("NM-PY-011", "node", locale)
+
+
+def _strict_json(text: str, limit: int, *, safe_integers: bool = False, depth_limit: int = MAX_REQUEST_DEPTH):
+    if not isinstance(text, str) or len(text.encode("utf-8")) > limit:
+        raise ValueError("JSON byte limit")
+    depth, quoted, escaped = 0, False, False
+    for char in text:
+        if quoted:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                quoted = False
+        elif char == '"':
+            quoted = True
+        elif char in "[{":
+            depth += 1
+            if depth > depth_limit:
+                raise ValueError("JSON depth limit")
+        elif char in "]}":
+            depth -= 1
+
+    def finite(value):
+        number = float(value)
+        if not math.isfinite(number) or safe_integers and number.is_integer() and abs(number) > 9007199254740991:
+            raise ValueError("Non-finite JSON number")
+        return number
+
+    def integer(value):
+        number = int(value)
+        if abs(number) > 9007199254740991:
+            if safe_integers:
+                raise ValueError("Unsafe integer JSON number")
+            # Runtime numbers are IEEE-754, not arbitrary-precision Python ints.
+            # JS may serialize an integral double as its shortest decimal,
+            # e.g. 1000000000000000100 denotes the double 1000000000000000128.
+            return finite(value)
+        return number
+
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ValueError("Duplicate JSON key")
+            result[key] = value
+        return result
+
+    def invalid(_value):
+        raise ValueError("Non-JSON constant")
+
+    return json.loads(text, parse_float=finite, parse_int=integer, parse_constant=invalid, object_pairs_hook=pairs)
+
+
+def _compact_json_text(text: str) -> str:
+    """Compact validated JSON without rewriting number or string representations."""
+    characters, quoted, escaped = [], False, False
+    for char in text:
+        if quoted:
+            characters.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                quoted = False
+        elif char == '"':
+            characters.append(char)
+            quoted = True
+        elif char not in " \t\r\n":
+            characters.append(char)
+    return "".join(characters)
+
+
+def _set_nonblocking(stream):
+    if os.name != "nt" or sys.version_info >= (3, 12):
+        os.set_blocking(stream.fileno(), False)
+        return stream.read, stream.write
+    # os.set_blocking gained Windows pipe support in 3.12. Keep the adapter's
+    # Python 3.10+ contract using the same anonymous-pipe mode on older Windows.
+    import ctypes
+    import msvcrt
+    from ctypes import wintypes
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    set_state = kernel.SetNamedPipeHandleState
+    set_state.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD),
+                          ctypes.POINTER(wintypes.DWORD), ctypes.POINTER(wintypes.DWORD)]
+    set_state.restype = wintypes.BOOL
+    mode = wintypes.DWORD(1)  # PIPE_NOWAIT, byte mode
+    handle = msvcrt.get_osfhandle(stream.fileno())
+    if not set_state(handle, ctypes.byref(mode), None, None):
+        raise ctypes.WinError(ctypes.get_last_error())
+    kernel.ReadFile.argtypes = kernel.WriteFile.argtypes = [wintypes.HANDLE, ctypes.c_void_p,
+        wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), ctypes.c_void_p]
+    kernel.ReadFile.restype = kernel.WriteFile.restype = wintypes.BOOL
+
+    # Older Python CRT reads map ERROR_NO_DATA to EINVAL rather than EAGAIN.
+    # Interpret the actual nonblocking pipe result instead of hiding all EINVALs.
+    def read(size):
+        buffer, count = ctypes.create_string_buffer(size), wintypes.DWORD()
+        if kernel.ReadFile(handle, buffer, size, ctypes.byref(count), None):
+            return buffer.raw[:count.value]
+        error = ctypes.get_last_error()
+        if error == 232:  # ERROR_NO_DATA: pipe still open, no bytes ready
+            return None
+        if error == 109:  # ERROR_BROKEN_PIPE: EOF
+            return b""
+        raise ctypes.WinError(error)
+
+    def write(data):
+        raw, count = bytes(data), wintypes.DWORD()
+        buffer = ctypes.create_string_buffer(raw)
+        if kernel.WriteFile(handle, buffer, len(raw), ctypes.byref(count), None):
+            return count.value
+        error = ctypes.get_last_error()
+        if error in (109, 232):
+            raise BrokenPipeError("Bridge input pipe closed")
+        raise ctypes.WinError(error)
+
+    return read, write
+
+
+class NMResult:
+    """Detached, round-trippable record; construction/deserialization never runs N/M."""
+    def __init__(self, record: dict):
+        self._load_record(json.dumps(record, ensure_ascii=False, allow_nan=False, separators=(",", ":")))
+
+    def _load_record(self, text: str):
+        record = _strict_json(text, MAX_RESPONSE_BYTES, depth_limit=MAX_RESPONSE_DEPTH)
+        if (not isinstance(record, dict) or record.get("format") != FORMAT
+                or type(record.get("version")) is not int or record["version"] != VERSION
+                or type(record.get("success")) is not bool or record.get("locale") not in _COPY
+                or record.get("status") not in ("completed", "rejected")):
+            raise ValueError("Invalid bridge response")
+        if record["status"] == "completed":
+            if (not isinstance(record.get("request"), dict) or not isinstance(record.get("permissions"), dict)
+                    or not isinstance(record.get("result"), dict) or record["result"].get("success") is not record["success"]):
+                raise ValueError("Incomplete bridge response")
+        elif record["success"] or "result" in record or not isinstance(record.get("error"), dict):
+            raise ValueError("Invalid rejection")
+        self._record = record
+        # Python may expand valid JS numbers (1e-7 -> 1e-07). Preserve their wire
+        # representation so a bounded response remains bounded when saved/reloaded.
+        self._compact_json = _compact_json_text(text)
+
+    @classmethod
+    def from_json(cls, text: str) -> NMResult:
+        result = cls.__new__(cls)
+        result._load_record(text)
+        return result
+
+    def to_json(self, *, indent: int | None = None) -> str:
+        if indent is None:
+            return self._compact_json
+        text = json.dumps(self._record, ensure_ascii=False, allow_nan=False, indent=indent)
+        if len(text.encode("utf-8")) > MAX_RESPONSE_BYTES:
+            raise ValueError("Formatted record exceeds the JSON byte limit; use compact output")
+        return text
+
+    @property
+    def record(self) -> dict:
+        return copy.deepcopy(self._record)
+
+    @property
+    def request(self) -> dict | None:
+        return copy.deepcopy(self._record.get("request"))
+
+    @property
+    def result(self) -> dict | None:
+        return copy.deepcopy(self._record.get("result"))
+
+    @property
+    def success(self) -> bool:
+        return self._record["success"]
+
+    def __repr__(self) -> str:
+        return f"NMResult(status={self._record['status']!r}, success={self.success!r})"
+
+    def _repr_html_(self) -> str:
+        """Jupyter rich display: text is escaped, never evaluated or injected as HTML."""
+        record = self._record
+        labels = _COPY[record["locale"]]
+        def mapping(value):
+            return value if isinstance(value, dict) else {}
+
+        result = mapping(record.get("result"))
+        evidence = mapping(result.get("groupedMeasurements"))
+        rows = [(labels["field"], labels["value"])]
+        rows.append((labels["title"], labels["rejected"] if record["status"] == "rejected" else labels["status" if self.success else "failed"]))
+        error = mapping(record.get("error"))
+        if error:
+            rows.append((str(error.get("code", "")), str(error.get("message", ""))))
+        if result.get("error"):
+            rows.append((labels["failed"], result["error"]))
+        if evidence:
+            rows.extend([(labels["shots"], f"{evidence.get('usedShots')} / {evidence.get('requestedShots')}"),
+                         (labels["remaining"], evidence.get("unallocatedShots"))])
+            adaptive = mapping(evidence.get("adaptive"))
+            if adaptive:
+                rows.extend([(labels["pilot"], adaptive.get("pilotUsedShots")), (labels["held_out"], adaptive.get("estimationUsedShots"))])
+            costs = evidence.get("costs") if isinstance(evidence.get("costs"), list) else []
+            if costs:
+                cost = mapping(costs[-1])
+                rows.extend([(labels["cost" if self.success else "observed"], cost.get("value")),
+                             (labels["interval"], f"[{cost.get('lower')}, {cost.get('upper')}]"), (labels["se"], cost.get("standardError"))])
+            accuracy = mapping(evidence.get("targetAccuracy"))
+            if accuracy:
+                state = str(accuracy.get("status", "incomplete"))
+                rows.extend([(labels["precision"], f"{accuracy.get('absoluteError')}: {labels.get(state, state)}"),
+                             (labels["bound"], accuracy.get("absoluteErrorBound")), (labels["floor"], accuracy.get("numericResolutionFloor"))])
+                estimate = mapping(accuracy.get("requiredShotsEstimate"))
+                if estimate:
+                    estimated = estimate.get("shots") if estimate.get("status") == "estimated" else labels[
+                        "estimate_resolution" if estimate.get("status") == "numeric-resolution-limit" else "estimate_large"]
+                    if estimate.get("exceedsShotLimit") is True:
+                        estimated = f"{estimated} — {labels['above_limit']}"
+                    rows.extend([(labels["required_shots"], estimated), (labels["estimate_assumptions"], labels["estimate_note"])])
+        header, *body = rows
+        table = "<table><caption>" + html.escape(labels["title"]) + "</caption><thead><tr>"
+        table += "".join("<th scope=\"col\">" + html.escape(str(value)) + "</th>" for value in header)
+        table += "</tr></thead><tbody>"
+        table += "".join("<tr><th scope=\"row\">" + html.escape(str(key)) + "</th><td>" + html.escape(labels["unavailable"] if value is None else str(value)) + "</td></tr>" for key, value in body)
+        table += "</tbody></table><p>" + html.escape(labels["notice"]) + "</p>"
+        source = mapping(record.get("request")).get("source", "")
+        return table + "<details><summary>" + html.escape(labels["source"]) + "</summary><pre>" + html.escape(str(source)) + "</pre></details>"
+
+
+def _npm_adjacent_cli(module_path: Path) -> Path:
+    """Use the npm default only when the physical module has unambiguous origin.
+
+    A wheel may be installed with --target into a directory named ``python``.
+    Its local distribution identity/RECORD must take precedence over any sibling
+    npm-looking layout. Metadata elsewhere on sys.path does not own this module.
+    """
+    module_path = module_path.resolve(strict=True)
+    directory = module_path.parent
+    if module_path.name != "nm_bridge.py" or directory.name != "python":
+        raise ValueError("The standalone adapter requires explicit CLI selection")
+    package = directory.parent
+    marker = package / "package.json"
+    if marker.resolve(strict=True).parent != package:
+        raise ValueError("Ambiguous npm package marker")
+    with marker.open("rb") as stream:
+        manifest = _strict_json(stream.read(65537).decode("utf-8"), 65536, safe_integers=True)
+    if (not isinstance(manifest, dict) or manifest.get("name") != "@nm-lang/cli"
+            or not isinstance(manifest.get("bin"), dict) or manifest["bin"].get("nm") != "./bin/nm.mjs"):
+        raise ValueError("The module is not in the original N/M npm package")
+    markers = [entry for entry in directory.iterdir() if entry.name.endswith((".dist-info", ".egg-info"))]
+    if any(entry.is_symlink() for entry in markers):
+        raise ValueError("Ambiguous local Python distribution marker")
+    if any(entry.name.lower().replace("_", "-").replace(".", "-").startswith("nm-jupyter-adapter-") for entry in markers):
+        raise ValueError("Standalone adapter installation marker")
+    distributions = list(importlib.metadata.distributions(path=[str(directory)]))
+    if len(distributions) != len(markers):
+        raise ValueError("Unrecognized local Python distribution metadata")
+    for distribution in distributions:
+        names = distribution.metadata.get_all("Name", [])
+        name = names[0] if len(names) == 1 else None
+        files = distribution.files
+        if not isinstance(name, str) or not name or files is None:
+            raise ValueError("Incomplete local Python distribution metadata")
+        normalized = name.lower().replace("_", "-").replace(".", "-")
+        if normalized == "nm-jupyter-adapter" or any(
+                Path(distribution.locate_file(file)).resolve() == module_path for file in files):
+            raise ValueError("An installed Python distribution owns the bridge")
+    cli = (package / "bin/nm.mjs").resolve(strict=True)
+    if not cli.is_relative_to(package):
+        raise ValueError("The adjacent CLI resolves outside its npm package")
+    return cli
+
+
+class NMClient:
+    """Each call launches one CLI process, with independently chosen permissions.
+
+    command is a trusted argument sequence, never a shell string. The default uses
+    an absolute Node executable from PATH and the npm package's adjacent nm.mjs.
+    Empty/relative PATH entries and the working directory are never searched.
+    Standalone wheel users select an absolute trusted script with cli_path=.
+    That option and the existing trusted command= sequence are mutually exclusive.
+    """
+    def __init__(self, *, experimental: Sequence[str] = (), locale: str = "en", timeout: float = 30,
+                 command: Sequence[str] | None = None, cli_path: str | os.PathLike[str] | None = None):
+        if locale not in _COPY:
+            raise ValueError("locale must be en or tr")
+        self.locale = locale
+        if (type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0.1 <= timeout <= 60
+                or isinstance(experimental, (str, bytes)) or not isinstance(experimental, Sequence)
+                or any(not isinstance(name, str) or not name.isascii() or not name.isalpha() for name in experimental)
+                or len(set(experimental)) != len(experimental)):
+            raise NMBridgeError("NM-PY-001", "input", locale)
+        if cli_path is not None and command is not None:
+            raise NMBridgeError("NM-PY-001", "input", locale)
+        if command is None:
+            try:
+                cli = Path(cli_path) if cli_path is not None else _npm_adjacent_cli(Path(__file__))
+                if not cli.is_absolute():
+                    raise ValueError("CLI path must be absolute")
+                cli = cli.resolve(strict=True)
+                if not cli.is_file():
+                    raise ValueError("CLI path must be a file")
+            except (OSError, RuntimeError, TypeError, ValueError, UnicodeError, KeyError, IndexError):
+                raise NMBridgeError("NM-PY-012", "cli", locale) from None
+            command = (_resolve_node(locale), str(cli))
+        if (isinstance(command, (str, bytes)) or not isinstance(command, Sequence) or not command
+                or any(not isinstance(arg, str) or not arg or "\0" in arg for arg in command)):
+            raise NMBridgeError("NM-PY-001", "input", locale)
+        self.command, self.experimental, self.timeout = tuple(command), tuple(experimental), timeout
+
+    def check(self, source: str, *, context: Mapping | None = None) -> NMResult:
+        return self._invoke("check", source, context=context)
+
+    def run(self, source: str, *, context: Mapping | None = None) -> NMResult:
+        return self._invoke("run", source, context=context)
+
+    def train(self, source: str, *, options: Mapping | None = None, context: Mapping | None = None) -> NMResult:
+        return self._invoke("train", source, context=context, options=options)
+
+    def _invoke(self, operation, source, *, context, options=None):
+        if context is not None and not isinstance(context, Mapping) or options is not None and not isinstance(options, Mapping):
+            raise NMBridgeError("NM-PY-001", "input", self.locale)
+        request = {"format": FORMAT, "version": VERSION, "operation": operation, "source": source}
+        if context is None:
+            context = {"experimental": {name: True for name in self.experimental}}
+        request["context"] = dict(context)
+        if options is not None:
+            request["training"] = dict(options)
+        return self.execute(request)
+
+    def execute(self, request: Mapping) -> NMResult:
+        """Replay only request data. The client's permissions are never read from it."""
+        try:
+            if not isinstance(request, Mapping):
+                raise ValueError("Request must be a JSON object")
+            payload = json.dumps(request, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+            snapshot = _strict_json(payload, MAX_REQUEST_BYTES, safe_integers=True)
+            encoded = payload.encode("utf-8")
+        except (ValueError, TypeError, RecursionError, UnicodeError) as error:
+            raise NMBridgeError("NM-PY-001", "input", self.locale) from error
+        args = [*self.command, "bridge", "--locale", self.locale, "--timeout-ms", str(int(self.timeout * 1000))]
+        for name in self.experimental:
+            args.extend(("--allow-feature", name))
+        stdout, returncode = self._exchange(args, encoded)
+        try:
+            response = NMResult.from_json(stdout.decode("utf-8", errors="strict").removesuffix("\n"))
+            if returncode != (0 if response.success else 1):
+                raise ValueError("Exit/result mismatch")
+            if response.record["locale"] != self.locale:
+                raise ValueError("Locale mismatch")
+            if response.record["status"] == "completed" and (response.request != snapshot
+                    or response.record["permissions"].get("authorized") != {name: True for name in self.experimental}):
+                raise ValueError("Source/options/authority mismatch")
+            return response
+        except (ValueError, TypeError, RecursionError, UnicodeError) as error:
+            raise NMBridgeError("NM-PY-010", "transport", self.locale) from error
+
+    def _exchange(self, args, payload):
+        try:
+            process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                       shell=False, bufsize=0, creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+        except OSError as error:
+            raise NMBridgeError("NM-PY-010", "transport", self.locale) from error
+        output = bytearray()
+        # Reserve one of the two cleanup seconds for reaping the direct process.
+        # EOF is part of the deadline too: a custom launcher's child may inherit
+        # the pipes even after that launcher exits. No reader/writer threads or
+        # buffered stream locks may outlive this call.
+        deadline = time.monotonic() + self.timeout + 1
+        readers = {process.stdout: [MAX_RESPONSE_BYTES + 1, 0], process.stderr: [MAX_STDERR_BYTES, 0]}
+        position = 0
+        try:
+            _, write = _set_nonblocking(process.stdin)
+            read = {stream: _set_nonblocking(stream)[0] for stream in readers}
+            while readers or process.poll() is None:
+                if time.monotonic() >= deadline:
+                    raise NMBridgeError("NM-PY-008", "timeout", self.locale)
+                progressed = False
+                if not process.stdin.closed:
+                    try:
+                        written = write(memoryview(payload)[position:position + 65536])
+                        position += written or 0
+                        progressed = bool(written)
+                        if position == len(payload):
+                            process.stdin.close()
+                    except BrokenPipeError:
+                        process.stdin.close()
+                for stream, state in list(readers.items()):
+                    chunk = read[stream](65536)
+                    if chunk is None:
+                        continue
+                    progressed = True
+                    if not chunk:
+                        del readers[stream]
+                        stream.close()
+                        continue
+                    state[1] += len(chunk)
+                    if state[1] > state[0]:
+                        raise NMBridgeError("NM-PY-006", "output", self.locale)
+                    if stream is process.stdout:
+                        output.extend(chunk)
+                if not progressed:
+                    time.sleep(min(0.005, max(0, deadline - time.monotonic())))
+        except KeyboardInterrupt as error:
+            raise NMBridgeError("NM-PY-009", "cancel", self.locale) from error
+        except OSError as error:
+            raise NMBridgeError("NM-PY-010", "transport", self.locale) from error
+        finally:
+            if process.poll() is None:
+                try:
+                    process.kill()
+                except OSError:
+                    pass
+            try:
+                process.wait(timeout=1)
+            except subprocess.TimeoutExpired:
+                pass
+            for stream in (process.stdin, process.stdout, process.stderr):
+                try:
+                    stream.close()
+                except OSError:
+                    pass
+        return bytes(output), process.returncode

package/python/nm_jupyter/__init__.py

@@ -0,0 +1,20 @@
+"""Optional, explicitly invoked IPython cells over the stdlib N/M bridge.
+
+Importing this package neither imports IPython nor launches the CLI. The legacy
+``from nm_bridge import NMClient, NMResult`` remains supported.
+"""
+from nm_bridge import NMBridgeError, NMClient, NMResult
+
+__all__ = ["NMBridgeError", "NMClient", "NMResult"]
+
+
+def load_ipython_extension(ipython):
+    """Register %%nm only when IPython explicitly loads this extension."""
+    from .extension import load_ipython_extension as load
+    load(ipython)
+
+
+def unload_ipython_extension(ipython):
+    """Remove this extension's magic without changing other shell magics."""
+    from .extension import unload_ipython_extension as unload
+    unload(ipython)