@nm-lang/cli 0.5.0 → 0.7.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.5.0";
+    readonly packageVersion: "0.7.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.5.0",
+    packageVersion: "0.7.0",
     irVersion: "0.1",
     qasm3SidecarVersion: "0.3",
     learningPackageVersion: "0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nm-lang/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Command-line tools for formatting, linting, testing, workspace snapshots, execution, and exports for N/M quantum programs.",
   "repository": {
@@ -36,6 +36,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./project-create": {
+      "types": "./bin/project-create.d.mts",
+      "import": "./bin/project-create.mjs"
     }
   },
   "bin": {
@@ -49,7 +53,7 @@
     "NOTICE.txt"
   ],
   "dependencies": {
-    "@nm-lang/core": "0.5.0",
+    "@nm-lang/core": "0.7.0",
     "jiti": "^2.7.0"
   },
   "scripts": {

package/python/LICENSE.txt

@@ -0,0 +1,57 @@
+QuantumSoftware N/M npm Packages — Free Use License
+Version 1.0, 5 October 2026
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+
+1. Scope
+This license covers QuantumSoftware-owned code and assets in the official
+@nm-lang/core, @nm-lang/cli, @nm-lang/language-server and @nm-lang/mcp npm
+packages. It does not license the rest of the repository or the separately
+distributed VS Code extension. Third-party components remain subject to their
+respective licenses; their notices and permissions take precedence for those
+components.
+
+2. Free use
+You may download, install and use these official packages without charge for
+personal, educational and commercial purposes, import their APIs into your own
+programs, and make backup copies for your own use. QuantumSoftware authorizes
+distribution of its official packages through the nm-lang organization on the
+npm registry, including the registry's normal delivery and package-manager
+installation and caching mechanisms.
+
+3. Reserved rights
+This is not an open-source license. Except for the permissions above, rights
+to QuantumSoftware-owned code and assets are reserved. Modification,
+redistribution, sublicensing, sale or publication of that code or those assets
+requires separate permission from the rights holders, unless applicable law
+provides otherwise. Do not remove copyright or license notices. These
+restrictions do not override rights granted by any third-party license.
+
+4. Your programs
+This license imposes no restrictions on N/M programs you write, their source
+code, or simulation results produced using these packages. It does not
+transfer ownership of your work to QuantumSoftware. This clause does not grant
+additional redistribution rights to QuantumSoftware-owned runtime code bundled
+with your application; those rights are governed by sections 2 and 3.
+
+5. No warranty
+THE PACKAGES ARE PROVIDED "AS IS", WITHOUT WARRANTIES OF ANY KIND, TO THE
+EXTENT PERMITTED BY APPLICABLE LAW. TO THAT SAME EXTENT, THE RIGHTS HOLDERS
+ARE NOT LIABLE FOR DAMAGES ARISING FROM USE OF THE PACKAGES. RIGHTS THAT
+CANNOT BE EXCLUDED UNDER APPLICABLE LAW ARE NOT AFFECTED.
+
+6. Permission requests
+For additional permissions, contact the publisher through:
+https://quantumsoftware.tech/en/#contact
+
+Türkçe açıklama
+Resmî dört npm paketi kişisel, eğitim ve ticari amaçlarla ücretsiz kurulup
+kullanılabilir; API'leri kendi programlarınızdan çağırabilir ve kendi kullanımınız
+için yedek kopya alabilirsiniz. Bu bir açık kaynak lisansı değildir.
+QuantumSoftware'a ait kod ve varlıkları değiştirmek veya yeniden dağıtmak için
+ayrıca izin gerekir. Paketleri indirilebilir kılmak, kaynak kodu üzerinde açık
+kaynak hakları vermez. Üçüncü taraf lisanslarının ve yürürlükteki hukukun verdiği
+haklar korunur. Yazdığınız N/M programları ve ürettiğiniz sonuçların mülkiyeti
+size aittir. Uygulamanızla birlikte dağıtacağınız QuantumSoftware çalışma zamanı
+dosyaları için yukarıdaki izin ve kısıtlamalar geçerlidir. Yukarıdaki İngilizce
+metin lisansın koşullarını belirler.

package/python/NOTICE.txt

@@ -0,0 +1,11 @@
+QuantumSoftware N/M package notices
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+QuantumSoftware-owned code is licensed under LICENSE.txt.
+
+Runtime dependencies listed in package.json are installed separately by npm.
+Their own licenses and notices remain applicable. The QuantumSoftware license
+does not restrict the rights granted for those third-party components.
+
+jiti 2.x is a separately installed runtime dependency licensed under MIT.
+Its original LICENSE is included in the jiti package.

package/python/README.md

@@ -1,69 +1,174 @@
-# N/M Python/Jupyter bridge — CLI 0.5.0 / CLI köprüsü
+# N/M Python/Jupyter adapter / adaptörü
 
-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.
+This source tree adds a **local development wheel**, `nm-jupyter-adapter==0.0.0.dev0`,
+over the stdlib bridge included in `@nm-lang/cli`. This is not a PyPI release or
+an npm/VSIX version change. Install Node and a trusted N/M CLI separately; the
+wheel contains only the adapter, optional extension and usage/license metadata.
+Source-code rights remain reserved under the unchanged LICENSE.txt and NOTICE.txt.
+
+Bu kaynak ağacı, `@nm-lang/cli` içindeki standart kütüphane köprüsünü
+`nm-jupyter-adapter==0.0.0.dev0` **yerel geliştirme wheel'i** olarak kurmayı sağlar.
+PyPI yayını veya npm/VSIX sürüm değişikliği değildir. Node ve güvenilir N/M CLI
+ayrıca kurulur. Wheel yalnız adaptörü, isteğe bağlı uzantıyı ve kullanım/lisans
+metaverisini içerir. LICENSE.txt ve NOTICE.txt değişmeden korunur; kaynak hakları saklıdır.
+
+## Installation / Kurulum
+
+From the repository root, create disposable environments; nothing is installed
+into global Python. / Depo kökünde geçici ortamlar oluşturun; global Python'a
+kurulum yapılmaz.
+
+```powershell
+py -m venv .qa/python-adapter/tools
+.qa/python-adapter/tools/Scripts/python.exe -m pip install -r tests/python/requirements-adapter-build.txt
+.qa/python-adapter/tools/Scripts/python.exe -B scripts/build-nm-python-adapter.py
+py -m venv .qa/python-adapter/notebook
+.qa/python-adapter/notebook/Scripts/python.exe -m pip install --no-index --no-deps .qa/python-adapter/dist/nm_jupyter_adapter-0.0.0.dev0-py3-none-any.whl
+# Optional IPython/Jupyter; Python 3.11+ / İsteğe bağlı IPython/Jupyter; Python 3.11+
+.qa/python-adapter/notebook/Scripts/python.exe -m pip install -r tests/python/requirements-notebook.txt
+```
+
+On Unix, use `python3` and `bin/python` instead of `py` and `Scripts/python.exe`.
+The stdlib adapter and legacy imports support Python 3.10+. The pinned optional
+IPython 9.17.1 notebook environment requires Python 3.11+; installing the
+`notebook` extra on Python 3.10 does not install IPython. No global kernel is registered.
+Unix'te `python3` ve `bin/python` kullanın. Standart kütüphane adaptörü Python
+3.10+ destekler; sabitlenmiş IPython 9.17.1 notebook ortamı Python 3.11+ gerektirir.
+Python 3.10'da `notebook` ek bağımlılığı IPython kurmaz. Global kernel kaydı yapılmaz.
+
+## Explicit CLI selection / Açık CLI seçimi
+
+```python
+from pathlib import Path
+from nm_bridge import NMClient, NMResult  # Legacy import stays valid / Eski import korunur.
+
+# Select an existing trusted CLI script; replace this example absolute path.
+# Mevcut güvenilir CLI dosyanızı seçin; örnek mutlak yolu değiştirin.
+client = NMClient(cli_path=Path("C:/trusted/nm-cli/bin/nm.mjs"), locale="tr",
+                  experimental=("hamiltonianEvolution", "measurementGrouping"), timeout=30)
+record = client.train(source, options={"steps": 2, "targetAccuracy": {"absoluteError": 0.5}})
+record  # Escaped Jupyter table / Kaçışlanmış Jupyter tablosu
+restored = NMResult.from_json(record.to_json())  # Data only / Yalnız veri
+```
+
+Standalone wheel clients require `cli_path=` or the existing trusted `command=`
+argument sequence. `cli_path` must resolve to an existing absolute file and is
+mutually exclusive with `command`. No PATH/cwd search for the N/M CLI occurs.
+Inside the original npm `python/` layout, `NMClient()` still selects the adjacent
+`../bin/nm.mjs`; adding that `python/` directory to `sys.path` remains supported.
+`from nm_jupyter import NMClient, NMResult` exposes the same classes.
+The npm default verifies the physical module origin, the parent `package.json`
+identity (`@nm-lang/cli` and its `nm` entry), and local Python distribution
+metadata. Wheel/RECORD ownership or incomplete/ambiguous markers require explicit
+CLI selection even when the wheel target directory happens to be named `python`.
+
+Bağımsız wheel, açık `cli_path=` veya mevcut güvenilir `command=` dizisi gerektirir.
+`cli_path`, mevcut bir mutlak dosyaya çözülmelidir ve `command` ile birlikte
+verilemez. N/M CLI için PATH/çalışma dizini araması yapılmaz. npm paketinin özgün
+`python/` diziliminde `NMClient()` komşu `../bin/nm.mjs` dosyasını kullanmaya devam
+eder; bu dizini `sys.path` içine eklemek desteklenir. `nm_jupyter` aynı sınıfları dışa aktarır.
+npm varsayılanı gerçek modül konumunu, üst `package.json` kimliğini ve yerel Python
+dağıtım metaverisini doğrular. Wheel/RECORD sahipliği veya eksik/belirsiz işaretler,
+kurulum hedefinin adı `python` olsa bile açık CLI seçimi gerektirir.
 
 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.
+directory and resolves an absolute executable. 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. Missing/invalid CLI selection raises
+`NM-PY-012`. Explicit `command=` remains trusted caller input, unchanged and passed
+with `shell=False`; trust its executable and arguments yourself.
+
 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.
+kullanır. Boş/göreli girdiler ve çalışma dizinine çözülen yollar atlanır. Node
+bulunamazsa `NM-PY-011`, CLI seçimi eksik/geçersizse `NM-PY-012` verilir.
+Yalın program adı fallback'i yoktur. Açık `command=` değiştirilmeden `shell=False`
+ile kullanılır; program ve argümanların güvenilirliğini çağıran sağlar.
+
+## Optional explicit cells / İsteğe bağlı açık hücreler
 
 ```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
+%load_ext nm_jupyter
+```
+
+```text
+%%nm --client client --check
+module notebook_check;
+fn main(){let q=qreg[1];H(q[0]);return q;}
+```
+
+Use `--run` for simulation or `--train` for training; exactly one mode and an
+existing Python variable naming an explicitly configured `NMClient` are required
+on every cell. Names are direct identifier lookups, not Python expressions.
+Import/load/save/display never invokes a client. Execution occurs only when you
+explicitly run a cell or call the Python API. `%unload_ext nm_jupyter` removes the magic.
+
+Simülasyon için `--run`, eğitim için `--train` seçin. Her hücre tam bir mod ve
+açıkça yapılandırılmış bir `NMClient` Python değişkeni gerektirir. Adlar doğrudan
+aranır; Python ifadesi değildir. Import/uzantı yükleme/kaydetme/gösterim CLI çağırmaz.
+Yürütme yalnız hücreyi veya Python API'yi açıkça çalıştırınca olur.
+
+```text
+%%nm --client client --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9
+module notebook_training;
+@seed(27);
+@shots_budget(4096);
+param theta:Angle=0;
+fn main(){
+ let q=qreg[1];
+ observable Hamiltonian=theta*X(q[0])+0.25*theta*I;
+ evolve Hamiltonian for 0.4 steps 1 order 1 on q;
+ let energy=expect Y(q[0])+0.5*Z(q[0]);
+ return q;
+}
 ```
 
-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.
+The cell returns `NMResult`; in the next Python cell, use `record = _` to retain it.
+Options omitted from the magic remain absent, preserving source training defaults.
+Training flags are accepted only with `--train`. Steps: 1–100; learning rate:
+finite `(0,5]`; adaptive pilot shots: 2–32; absolute error: finite `(0,1000000]`.
+No shot override or feature grant is accepted in the magic. See the full guide
+for the enum choices. Nested SPSA/QNG tuning remains in `NMClient.train(options=...)`.
+
+Hücre `NMResult` döndürür; sonraki Python hücresinde `record = _` ile saklayın.
+Verilmeyen eğitim seçenekleri eklenmez; kaynağın varsayılanları korunur. Eğitim
+bayrakları yalnız `--train` ile geçerlidir. Adım 1–100, öğrenme oranı sonlu `(0,5]`,
+adaptif pilot ölçüm 2–32, mutlak hata sonlu `(0,1000000]` olur. Hücreye ölçüm sayısı
+override'ı veya özellik izni eklenmez. İç SPSA/QNG ayarları Python API'sinde kalır.
+
+## Limits and records / Sınırlar ve kayıtlar
+
+The bridge v1 limits remain: 32 KiB source, 256 KiB request, 4 MiB response,
+64 KiB stderr, request/result JSON depth 32/64, 14 qubits, 8 training parameters,
+100 steps, one inclusive shot budget up to 4096 and a 0.1–60 second deadline.
+Pipe I/O and EOF share the deadline; no I/O threads survive a call. Windows
+Python 3.10/3.11 retains the stdlib Win32 compatibility path. Cancellation kills
+the direct process and yields `NM-PY-009`; this is not a process-tree sandbox.
+
+Köprü v1 sınırları korunur: 32 KiB kaynak, 256 KiB istek, 4 MiB yanıt, 64 KiB stderr,
+32/64 JSON derinliği, 14 kübit, 8 parametre, 100 adım, pilotlar dahil en fazla
+4096 ölçüm ve 0.1–60 saniye süre. Giriş/çıkış ve EOF aynı süreye bağlıdır; I/O iş
+parçacığı kalmaz. Windows Python 3.10/3.11 desteği korunur. İptal doğrudan süreci
+sonlandırıp `NM-PY-009` verir; süreç ağacı sandbox'ı değildir.
+
+Saved JSON is data and grants no permission. Replay with
+`client.execute(restored.request)` needs independent caller permissions. Compact
+saving preserves wire number spellings; pretty output exceeding 4 MiB is rejected.
+Source snapshots are not checkpoints. Confidence and precision targets do not
+certify convergence, an optimum or hardware accuracy. Required-shot estimates
+are informational final-cost estimates, exclude pilots and never take extra shots.
+Source, options, shot accounting and confidence assumptions remain in the record;
+all user text in the rich table is HTML escaped.
+
+Kaydedilmiş JSON veridir; izin vermez. Yeniden yürütme bağımsız çağıran yetkisi
+gerektirir. Kompakt kayıt özgün sayı gösterimini korur; 4 MiB'ı aşan girintili çıktı
+reddedilir. Kaynak checkpoint, hassasiyet hedefi yakınsama/optimum/donanım belgesi
+değildir. Ölçüm tahmini bilgi amaçlıdır; pilotları içermez ve ek ölçüm almaz.
+Özgün kaynak, seçenekler ve ölçüm/güven varsayımları kayıtta kalır; tablo metni kaçışlanır.
+
+`examples/magic.ipynb` is an unexecuted TR/EN explicit-cell example. It is included
+with the npm source layout, not bundled into the minimal wheel. The existing
+`examples/training.ipynb` and legacy Python bridge API remain usable.
+
+Full guide / Tam rehber: `docs/NM_PYTHON_JUPYTER_ADAPTER_GUIDE.md`.
+Protocol and precision details / Protokol ve hassasiyet:
+`docs/NM_PYTHON_JUPYTER_BRIDGE_GUIDE.md`.

package/python/examples/magic.ipynb

@@ -0,0 +1,98 @@
+{
+ "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": [
+   "# Explicit N/M cells / Açık N/M hücreleri\n",
+   "Local development adapter; not a PyPI release. / Yerel geliştirme adaptörü; PyPI yayını değildir.\n",
+   "Install the local wheel and optional Python 3.11+ IPython/kernel requirements first. / Önce yerel wheel ve isteğe bağlı Python 3.11+ IPython/kernel gereksinimlerini kurun.\n",
+   "Select an existing trusted absolute CLI file by explicitly setting NM_ADAPTER_CLI_PATH before running this setup cell. The adapter does not discover it. / Setup hücresinden önce NM_ADAPTER_CLI_PATH ile güvenilir mutlak CLI dosyasını açıkça seçin.\n",
+   "Opening or saving this notebook does not execute it. Outputs are not pre-executed or saved. / Notebook'u açmak veya kaydetmek yürütme başlatmaz; önceden çalıştırılmış çıktı yoktur."
+  ]},
+  {"cell_type": "code", "id": "setup", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "import os\n",
+   "from pathlib import Path\n",
+   "from nm_bridge import NMClient, NMResult\n",
+   "cli_path = Path(os.environ['NM_ADAPTER_CLI_PATH'])  # Explicit trusted user/test selection / Açık güvenilir seçim\n",
+   "features = ('hamiltonianEvolution', 'measurementGrouping')\n",
+   "client_en = NMClient(cli_path=cli_path, locale='en', experimental=features)\n",
+   "client_tr = NMClient(cli_path=cli_path, locale='tr', experimental=features)\n",
+   "%load_ext nm_jupyter"
+  ]},
+  {"cell_type": "code", "id": "check-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --check\n",
+   "module magic_check;\n",
+   "fn main(){let q=qreg[1];H(q[0]);return q;}\n",
+   "// İı çğ üş 😀 <script>source is data</script> $literal {literal}"
+  ]},
+  {"cell_type": "code", "id": "retain-check-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["checked_en = _\n", "assert checked_en.success, checked_en.to_json()"]},
+  {"cell_type": "code", "id": "run-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --run\n",
+   "module magic_run;\n",
+   "@seed(17);\n",
+   "fn main(){let q=qreg[1];H(q[0]);let cost=expect Z(q[0]);return cost;}\n",
+   "// İı çğ üş 😀 <script>source is data</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-run-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["ran_en = _\n", "assert ran_en.success, ran_en.to_json()"]},
+  {"cell_type": "code", "id": "train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9\n",
+   "module magic_training;\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 steps 1 order 1 on q;\n",
+   " let energy=expect Y(q[0])+0.5*Z(q[0]);\n",
+   " return q;\n",
+   "}\n",
+   "// İı çğ üş 😀 <script>source is data</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["trained_en = _\n", "assert trained_en.success, trained_en.to_json()"]},
+  {"cell_type": "code", "id": "check-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --check\n",
+   "module magic_kontrol;\n",
+   "@dil(\"tr\");\n",
+   "fn main(){let q=qreg[1];H(q[0]);return q;}\n",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-check-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": ["checked_tr = _\n", "assert checked_tr.success, checked_tr.to_json()"]},
+  {"cell_type": "code", "id": "run-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --run\n",
+   "module magic_yurutme;\n",
+   "@dil(\"tr\");\n",
+   "@seed(17);\n",
+   "fn main(){let q=qreg[1];H(q[0]);let cost=expect Z(q[0]);return cost;}\n",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-run-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": ["ran_tr = _\n", "assert ran_tr.success, ran_tr.to_json()"]},
+  {"cell_type": "code", "id": "train-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9\n",
+   "module magic_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",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retained-records", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "trained_tr = _\n",
+   "assert trained_tr.success, trained_tr.to_json()\n",
+   "assert trained_tr.result == trained_en.result\n",
+   "restored = NMResult.from_json(trained_en.to_json())\n",
+   "assert restored.record == trained_en.record\n",
+   "denied = NMClient(cli_path=cli_path).execute(restored.request)\n",
+   "assert not denied.success and denied.record['error']['code'] == 'NM-PY-003'\n",
+   "# Replay needs a separate explicit API call with client permissions. / Yeniden yürütme ayrıca izinli API çağrısı gerektirir."
+  ]}
+ ]
+}

package/python/nm_bridge.py

@@ -1,12 +1,13 @@
 """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.
+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
@@ -32,6 +33,7 @@ _COPY = {
         "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",
@@ -54,6 +56,7 @@ _COPY = {
         "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",
@@ -325,15 +328,61 @@ class NMResult:
         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 adjacent CLI process, with independently chosen permissions.
+    """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):
+                 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
@@ -342,8 +391,19 @@ class NMClient:
                 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:
-            command = (_resolve_node(locale), str(Path(__file__).resolve().parents[1] / "bin" / "nm.mjs"))
+            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)

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)