@nm-lang/cli 0.3.0 → 0.5.0

package/dist/version.d.ts

@@ -29,7 +29,7 @@ export type NMLanguageReleaseChange = {
 };
 export declare const nmVersionManifest: {
     readonly languageVersion: "0.2.0";
-    readonly packageVersion: "0.3.0";
+    readonly packageVersion: "0.5.0";
     readonly irVersion: "0.1";
     readonly qasm3SidecarVersion: "0.3";
     readonly learningPackageVersion: "0.1";

package/dist/version.js

@@ -2,7 +2,7 @@ export const NM_LANGUAGE_PREVIEW_READINESS_FORMAT = "nm-language-preview-readine
 export const NM_LANGUAGE_PREVIEW_READINESS_VERSION = "0.1";
 export const nmVersionManifest = {
     languageVersion: "0.2.0",
-    packageVersion: "0.3.0",
+    packageVersion: "0.5.0",
     irVersion: "0.1",
     qasm3SidecarVersion: "0.3",
     learningPackageVersion: "0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nm-lang/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Command-line tools for formatting, linting, testing, workspace snapshots, execution, and exports for N/M quantum programs.",
   "repository": {
@@ -44,11 +44,12 @@
   "files": [
     "bin",
     "dist",
+    "python",
     "LICENSE.txt",
     "NOTICE.txt"
   ],
   "dependencies": {
-    "@nm-lang/core": "0.3.0",
+    "@nm-lang/core": "0.5.0",
     "jiti": "^2.7.0"
   },
   "scripts": {

package/python/README.md

@@ -0,0 +1,69 @@
+# N/M Python/Jupyter bridge — CLI 0.5.0 / CLI köprüsü
+
+Included in @nm-lang/cli 0.5.0; not a separate PyPI distribution.
+@nm-lang/cli 0.5.0 içinde bulunur; ayrı bir PyPI dağıtımı değildir.
+Python 3.10+ syntax; standard library only. Jupyter is installed separately.
+Add this directory to `sys.path`, then `from nm_bridge import NMClient, NMResult`.
+The default client runs the adjacent `../bin/nm.mjs` with Node directly.
+
+Default Node lookup accepts only absolute PATH directories outside the working
+directory and resolves an absolute executable path. Empty/relative entries and
+cwd aliases are skipped on every supported Python version. Missing Node raises
+`NM-PY-011`; no bare-name fallback is used. Explicit `command=` is trusted input
+and bypasses this lookup unchanged. Trust the selected executable and absolute
+PATH directories; records never grant permissions or execute themselves.
+Varsayılan Node araması yalnız çalışma dizini dışındaki mutlak PATH dizinlerini
+kullanır; boş/göreli girdiler ve çalışma dizinine çözülen yollar atlanır. Node
+bulunamazsa `NM-PY-011` verilir. Açık `command=` güvenilir girdidir ve değiştirilmez;
+seçilen programın güvenilirliği çağırana aittir. Kayıt okumak izin vermez veya çalıştırmaz.
+
+Pipe I/O and EOF waiting share the bounded deadline, including custom launchers
+whose descendants retain output handles. No I/O threads survive a call. Windows
+Python 3.10/3.11 uses a stdlib Win32 compatibility path; only the direct process
+is terminated, so this is not a process-tree sandbox.
+Giriş/çıkış ve EOF aynı süre sınırına bağlıdır; çağrı sonrası I/O iş parçacığı
+kalmaz. Özel başlatıcının alt süreci boruyu açık tutarsa eksik sonuç kabul edilmez.
+Windows Python 3.10/3.11 desteklenir; yalnız doğrudan başlatılan süreç sonlandırılır.
+
+```python
+client = NMClient(experimental=("hamiltonianEvolution", "measurementGrouping"), locale="tr")
+record = client.train(source, options={"steps": 2, "targetAccuracy": {"absoluteError": 0.5}})
+record  # Jupyter table / Jupyter tablosu
+data = record.to_json()  # Complete original source + options + result
+restored = NMResult.from_json(data)  # Data only; no execution or permission grant
+```
+
+Incoming JSON and compact saved records are limited to 4 MiB. Compact saving preserves
+wire number spellings; Python's float formatting cannot grow an accepted record past
+the limit. Pretty output may exceed the limit and is rejected.
+Gelen JSON ve kompakt kayıt sınırı 4 MiB'dır. Kompakt kayıt özgün sayı gösterimini
+korur; Python'ın sayı biçimlendirmesi geçerli kaydı sınırın üzerine büyütmez.
+Girintili çıktı sınırı aşarsa reddedilir.
+
+`source` is your N/M source text / kendi N/M kaynak metninizdir. `examples/training.ipynb`
+contains runnable TR/EN sources with one total 4096-shot budget, separate pilot
+measurements and target precision. Outputs are not pre-executed or saved.
+
+Feature permissions come from the client, never the record. Replay with
+`client.execute(restored.request)` requires independent explicit permissions.
+Source snapshots are not checkpoints. Precision targets do not certify convergence.
+`targetAccuracy.requiredShotsEstimate` estimates final-cost shots from current
+group proportions and confidence assumptions, excluding adaptive pilots. It is not
+a total training budget or a guarantee; estimates above 4096, unsafe integer counts
+and numeric resolution limits have explicit states. No extra shots are taken.
+Original source, training options, shot accounting and confidence assumptions are
+retained; output is escaped rather than treated as executable HTML.
+
+İzinler istemciden gelir; kaydı okumak izin vermez veya çalıştırmaz. Kaynak,
+eğitim seçenekleri, ölçüm bütçesi ve güven aralığı varsayımları korunur. Pilotlar
+bütçeye dahildir; hassasiyet hedefi yakınsama belgesi değildir. `locale="tr"` ve
+`locale="en"` desteklenir. Süre/boyut sınırları aşılırsa kısmi başarı üretilmez.
+`targetAccuracy.requiredShotsEstimate` son maliyet için gereken ölçümleri bilgi
+amaçlı tahmin eder; pilotlar dahil edilmez. Toplam eğitim bütçesi veya garanti değildir.
+4096 sınırı, güvenli tamsayı aralığı ve sayısal çözünürlük engelleri açıkça gösterilir;
+ek ölçüm yapılmaz.
+
+Full guide / Tam rehber:
+`docs/NM_PYTHON_JUPYTER_BRIDGE_GUIDE.md` in the repository. This preview is not a
+separately published PyPI distribution. It is covered by the adjacent npm package's
+LICENSE.txt and NOTICE.txt; source-code rights remain reserved.

package/python/examples/training.ipynb

@@ -0,0 +1,78 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+  "language_info": {"name": "python"}
+ },
+ "cells": [
+  {"cell_type": "markdown", "id": "scope", "metadata": {}, "source": [
+   "# N/M Python/Jupyter — CLI 0.5.0 / CLI bridge\n",
+   "Henüz yayımlanmadı. Önce bu dalın CLI'sini derleyin; Python 3.10+ ve Node gerekir. / Not published. Build the branch CLI first; Python 3.10+ and Node are required.\n",
+   "Her eğitim toplam 4096 ölçüm kullanır; pilotlar dahildir. Hedef hassasiyet yakınsama belgesi değildir. / Each training call uses 4096 total shots including pilots. Precision is not a convergence certificate.\n",
+   "Çıktılar önceden çalıştırılıp kaydedilmedi. / Outputs have not been pre-executed or saved."
+  ]},
+  {"cell_type": "code", "id": "setup", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "import os, sys\n",
+   "from pathlib import Path\n",
+   "# Explicit library location override / Açık kütüphane dizini seçimi\n",
+   "candidates = [Path(os.environ['NM_BRIDGE_PYTHON_PATH'])] if 'NM_BRIDGE_PYTHON_PATH' in os.environ else [Path.cwd(), Path.cwd().parent, Path.cwd() / 'packages/nm-cli/python']\n",
+   "adapter_dir = next((p.resolve() for p in candidates if (p / 'nm_bridge.py').is_file()), None)\n",
+   "assert adapter_dir is not None, 'Set NM_BRIDGE_PYTHON_PATH to the CLI python directory / CLI python dizinini belirtin'\n",
+   "sys.path.insert(0, str(adapter_dir))\n",
+   "from nm_bridge import NMClient, NMResult\n",
+   "features = ('hamiltonianEvolution', 'measurementGrouping')\n",
+   "options = {'steps': 2, 'learningRate': 0.17, 'optimizer': 'adam', 'objective': 'minimize', 'objectiveTarget': 'energy', 'gradientMethod': 'parameter-shift', 'measurementAllocation': {'method': 'adaptive', 'pilotShots': 8}, 'targetAccuracy': {'absoluteError': 1e-9}}"
+  ]},
+  {"cell_type": "markdown", "id": "turkish", "metadata": {}, "source": [
+   "## Türkçe\n",
+   "İzinleri çağıran açıkça seçer. Kaynak, seçenekler, grup tohumları ve güven aralıkları tam kayıtta korunur. / Caller permissions are explicit; source, options, group seeds and confidence bounds are retained."
+  ]},
+  {"cell_type": "code", "id": "train-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "source_tr = '''module notebook_egitimi;\n",
+   "@dil(\"tr\");\n",
+   "@seed(27);\n",
+   "@shots_budget(4096);\n",
+   "param theta:Angle=0;\n",
+   "fn main(){\n",
+   "  let q=qreg[1];\n",
+   "  observable Hamiltonian=theta*X(q[0])+0.25*theta*I;\n",
+   "  evolve Hamiltonian for 0.4 adımlar 1 order 1 on q;\n",
+   "  let energy=expect Y(q[0])+0.5*Z(q[0]);\n",
+   "  return q;\n",
+   "}\n",
+   "// Özgün kaynak: İı çğ üş 😀 <script>source is data</script>\n",
+   "'''\n",
+   "record_tr = NMClient(experimental=features, locale='tr').train(source_tr, options=options)\n",
+   "assert record_tr.success, record_tr.to_json()\n",
+   "assert record_tr.result['groupedMeasurements']['usedShots'] == 4096\n",
+   "assert record_tr.result['groupedMeasurements']['targetAccuracy']['status'] == 'not-met'\n",
+   "record_tr"
+  ]},
+  {"cell_type": "markdown", "id": "english", "metadata": {}, "source": [
+   "## English\n",
+   "The same options and one inclusive budget apply. Held-out estimates do not reuse pilots. No source string becomes executable HTML."
+  ]},
+  {"cell_type": "code", "id": "train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "source_en = source_tr.replace('@dil(\"tr\");\\n', '').replace('notebook_egitimi', 'notebook_training').replace('adımlar 1', 'steps 1')\n",
+   "client_en = NMClient(experimental=features, locale='en')\n",
+   "record_en = client_en.train(source_en, options=options)\n",
+   "assert record_en.success, record_en.to_json()\n",
+   "evidence = record_en.result['groupedMeasurements']\n",
+   "assert evidence['usedShots'] == evidence['adaptive']['pilotUsedShots'] + evidence['adaptive']['estimationUsedShots'] == 4096\n",
+   "assert evidence['targetAccuracy']['finalCost'] == evidence['costs'][-1]\n",
+   "record_en"
+  ]},
+  {"cell_type": "code", "id": "data-only-replay", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "restored = NMResult.from_json(record_en.to_json())\n",
+   "assert restored.record == record_en.record\n",
+   "assert restored.request['source'] == source_en\n",
+   "# Deserialization grants no permission / Kaydı okumak izin vermez.\n",
+   "denied = NMClient(locale='en').execute(restored.request)\n",
+   "assert not denied.success and denied.record['error']['code'] == 'NM-PY-003'\n",
+   "replayed = client_en.execute(restored.request)\n",
+   "assert replayed.result == record_en.result\n",
+   "print('Round-trip + independent replay permissions verified / Kayıt ve bağımsız yeniden yürütme izinleri doğrulandı')"
+  ]}
+ ]
+}

package/python/nm_bridge.py

@@ -0,0 +1,464 @@
+"""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 adjacent npm CLI must be built/installed. No network or shell is used here.
+"""
+from __future__ import annotations
+
+import copy
+import html
+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.",
+        "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.",
+        "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>"
+
+
+class NMClient:
+    """Each call launches one adjacent 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.
+    """
+    def __init__(self, *, experimental: Sequence[str] = (), locale: str = "en", timeout: float = 30,
+                 command: Sequence[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 command is None:
+            command = (_resolve_node(locale), str(Path(__file__).resolve().parents[1] / "bin" / "nm.mjs"))
+        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