@nm-lang/cli 0.4.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 N/M 0.2.0 Preview command-line tools for running, formatting, linting, testing,
 exporting and managing local N/M workspaces.
 
-Package **0.4.0** targets the N/M **0.2.0** language contract.
+Package **0.5.0** targets the N/M **0.2.0** language contract.
 
 ## Install / Kurulum
 
@@ -21,12 +21,12 @@ npx --package=@nm-lang/cli nm --version
 ```
 
 An untagged install selects npm's `latest` channel. To pin this version,
-append `@0.4.0` to the package name. The N/M language remains
+append `@0.5.0` to the package name. The N/M language remains
 Preview independently of the npm channel. npm installs the matching Core dependency.
 No repository checkout or TypeScript build is needed to use a published package.
 
 Türkçe: Etiketsiz kurulum npm'in `latest` kanalını seçer.
-`@0.4.0` ile sürümü sabitleyebilirsiniz. N/M dili, npm kanalından bağımsız
+`@0.5.0` ile sürümü sabitleyebilirsiniz. N/M dili, npm kanalından bağımsız
 olarak Önizleme durumundadır. Core bağımlılığı otomatik kurulur; depoyu
 indirmeniz gerekmez.
 
@@ -58,10 +58,10 @@ simülasyondan gelir; gerçek kuantum donanımı kanıtı değildir.
 
 ### Selected tests and CI reports / Test seçimi ve CI raporları
 
-The `0.3.0` package adds test selection, watch mode and JSON, JUnit and SARIF
+The CLI provides test selection, watch mode and JSON, JUnit and SARIF
 reports for CI integrations.
 
-Türkçe: `0.3.0` paketi test seçimini, izleme modunu ve CI entegrasyonları için
+Türkçe: CLI test seçimini, izleme modunu ve CI entegrasyonları için
 JSON, JUnit ve SARIF raporlarını içerir.
 
 ```sh
@@ -130,11 +130,29 @@ Türkçe: Yeni CLI çağrılarında varsayılan dil profili açıktır. Eski dav
 - [Support / Destek](https://quantumsoftware.tech/en/#contact)
 
 
-## Hamiltonian 0.4.0 candidate / Hamiltonian 0.4.0 adayı
-
-This unpublished 0.4.0 candidate includes Hamiltonian evolution and shared-shot
-QWC expectations. Published npm 0.3.0 and earlier extension releases do not
-include these additions.
+## 0.5.0: Trainable evolution / Eğitilebilir evrim
+
+This package adds scalar-parameter evolution time and Hamiltonian coefficients,
+fixed gate topology at zero time/weight, and exact-statevector circuit/operator
+derivatives. The training host supports fixed or adaptive QWC allocation with
+one total shot budget, separate pilots/held-out confidence evidence, and optional
+final-cost precision targets. Required-shot estimates are informational; they do
+not spend extra shots, increase the 4096 limit or certify convergence. These
+features require the existing explicit Hamiltonian and grouping permissions.
+
+Türkçe: Parametreli evrim süresi/katsayıları, sıfırda korunan kapı yapısı ve kesin
+statevector devre/operatör türevleri eklenir. Eğitim host'u sabit/adaptif QWC,
+tek toplam ölçüm bütçesi, ayrı pilot/değerlendirme güven kanıtı ve isteğe bağlı
+son maliyet hassasiyetini destekler. Ölçüm tahmini bilgi amaçlıdır; ek ölçüm almaz,
+4096 sınırını artırmaz veya yakınsamayı belgelemez. Mevcut iki açık izin korunur.
+
+The N/M language contract remains 0.2.0; package and artifact versions are separate.
+N/M dil sözleşmesi 0.2.0 olarak kalır; paket ve dosya biçimi sürümleri ayrıdır.
+
+## Hamiltonian 0.4.0 / Hamiltonian 0.4.0
+
+Version 0.4.0 includes Hamiltonian evolution and shared-shot QWC expectations.
+Earlier releases do not include these additions.
 Both `hamiltonianEvolution` and `measurementGrouping` require explicit permission.
 Source printing and N/M IR v0.5 preserve original source, parser context, seed and
 shot plans. Imports rebuild with caller permissions; stored flags never grant them.
@@ -149,11 +167,14 @@ CLI: `--experimental-hamiltonian-evolution`, `--experimental-measurement-groupin
 The editor offers completion/hover, closed-default diagnostics and original
 source columns for generated gates in the recorded debugger.
 
-Türkçe: Bunlar yayımlanmamış yerel geliştirmelerdir; iki yeni izin varsayılan
-kapalıdır. Yazdırma/IR özgün kaynağı ve ortak ölçüm bütçesini korur; içe aktarım
+Türkçe: 0.4.0 bu geliştirmeleri içerir; iki yeni izin varsayılan kapalıdır.
+Yazdırma/IR özgün kaynağı ve ortak ölçüm bütçesini korur; içe aktarım
 kaydı çalıştırma yetkisi saymaz. CLI/MCP/LSP/Monaco/VS Code aynı izinleri taşır;
-tanılar ve ayarlar TR/EN destekler. TR/EN laboratuvarı sitede erişilebilirdir;
-yeni npm/eklenti paketinin yayını ayrı aşamadır.
+tanılar ve ayarlar TR/EN destekler. TR/EN laboratuvarı sitede erişilebilirdir.
+N/M dil sözleşmesi 0.2.0 ve ön izleme olgunluğu korunur.
+
+[Release notes](https://quantumsoftware.tech/en/docs/nm-language/releases) ·
+[Türkçe sürüm notları](https://quantumsoftware.tech/tr/docs/nm-language/releases)
 
 ## License / Lisans
 
@@ -164,3 +185,16 @@ separate permission. Your N/M programs and results remain yours. See
 
 Türkçe: Kullanım ücretsizdir; açık kaynak lisansı verilmez. Paket kodunu
 değiştirme ve yeniden dağıtma için ayrıca izin gerekir.
+
+## Python/Jupyter bridge / Python/Jupyter köprüsü
+
+Version 0.5.0 adds `nm bridge` for bounded JSON `check`, `run` and
+`train` requests through stdin. The `python/nm_bridge.py` stdlib adapter and
+`python/examples/training.ipynb` preserve source, explicit caller permissions,
+training options and complete measurement/confidence evidence. TR/EN output is
+supported; saved records never self-grant replay permissions. No separate PyPI
+release is provided. See `python/README.md` and the repository's
+`docs/NM_PYTHON_JUPYTER_BRIDGE_GUIDE.md`. The earlier npm 0.4.0 release does not include this bridge.
+Türkçe: 0.5.0, standart kütüphaneli yerel Python/Jupyter köprüsünü içerir;
+kayıtlar özgün kaynak, eğitim seçenekleri, bütçe ve güven kanıtını korur.
+Kayıt okumak çalıştırma izni vermez; ayrı bir PyPI paketi yayımlanmaz.

package/bin/bridge-host.mjs

@@ -0,0 +1,78 @@
+import { Worker } from "node:worker_threads";
+
+// Transport caps also cover stdin waiting, runtime loading and forced termination.
+export const nmBridgeTransportLimits = Object.freeze({ requestBytes: 262144, responseBytes: 4194304, defaultTimeoutMs: 30000, maxTimeoutMs: 60000 });
+const copy = {
+  en: { input: "Invalid bridge arguments, UTF-8 input, or request size.", timeout: "Bridge deadline exceeded. The Worker was terminated; no completed measurement or precision evidence is available.", execution: "Bridge Worker failed. No completed result is available.", cancel: "Bridge cancelled; no completed result is available." },
+  tr: { input: "Köprü bağımsız değişkenleri, UTF-8 girdisi veya istek boyutu geçersiz.", timeout: "Köprü süre sınırı aşıldı. Worker sonlandırıldı; tamamlanmış ölçüm veya hassasiyet kanıtı yoktur.", execution: "Köprü Worker hatası. Tamamlanmış sonuç yoktur.", cancel: "Köprü iptal edildi; tamamlanmış sonuç yoktur." },
+};
+function rejection(key, locale) {
+  return { exitCode: 1, stdout: [JSON.stringify({ format: "nm-python-bridge", version: 1, success: false, status: "rejected", locale,
+    error: { code: key === "timeout" ? "NM-PY-008" : key === "cancel" ? "NM-PY-009" : key === "execution" ? "NM-PY-007" : "NM-PY-001", message: copy[locale][key] } })], stderr: [] };
+}
+
+export async function runNMBridgeHost(args) {
+  const locale = args[args.indexOf("--locale") + 1] === "tr" ? "tr" : "en";
+  const forwarded = [], seen = new Set(), features = new Set();
+  let timeoutMs = nmBridgeTransportLimits.defaultTimeoutMs;
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (flag === "--allow-feature") {
+      const feature = args[++index];
+      if (!/^[A-Za-z]+$/u.test(feature ?? "") || features.has(feature)) return emit(rejection("input", locale));
+      features.add(feature); forwarded.push(flag, feature); continue;
+    }
+    if (seen.has(flag)) return emit(rejection("input", locale));
+    seen.add(flag);
+    if (flag === "--json") { forwarded.push(flag); continue; }
+    if (flag === "--locale" && ["en", "tr"].includes(args[index + 1])) { forwarded.push(flag, args[++index]); continue; }
+    if (flag === "--timeout-ms") {
+      const value = args[++index];
+      if (!/^\d+$/u.test(value ?? "") || Number(value) < 100 || Number(value) > nmBridgeTransportLimits.maxTimeoutMs) return emit(rejection("input", locale));
+      timeoutMs = Number(value); continue;
+    }
+    return emit(rejection("input", locale));
+  }
+  await new Promise(resolve => {
+    let worker, settled = false, size = 0;
+    const chunks = [];
+    const finish = async result => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      process.stdin.removeListener("data", onData); process.stdin.removeListener("end", onEnd); process.stdin.removeListener("error", onInputError);
+      process.removeListener("SIGINT", onCancel); process.removeListener("SIGTERM", onCancel);
+      chunks.length = 0; process.stdin.destroy();
+      if (worker) await worker.terminate();
+      emit(result); resolve();
+    };
+    const onCancel = () => void finish(rejection("cancel", locale));
+    const onInputError = () => void finish(rejection("input", locale));
+    const onData = chunk => {
+      size += chunk.length;
+      if (size > nmBridgeTransportLimits.requestBytes) return void finish(rejection("input", locale));
+      chunks.push(chunk);
+    };
+    const onEnd = () => {
+      let input;
+      try { input = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)); }
+      catch { return void finish(rejection("input", locale)); }
+      chunks.length = 0;
+      try {
+        worker = new Worker(new URL("./bridge-worker.mjs", import.meta.url), {
+          workerData: { args: forwarded, input }, resourceLimits: { maxOldGenerationSizeMb: 512, stackSizeMb: 8 },
+        });
+        worker.once("message", result => {
+          const valid = result && [0, 1].includes(result.exitCode) && result.stdout?.length === 1 && result.stderr?.length === 0
+            && typeof result.stdout[0] === "string" && Buffer.byteLength(result.stdout[0]) <= nmBridgeTransportLimits.responseBytes;
+          void finish(valid ? result : rejection("execution", locale));
+        });
+        worker.once("error", () => void finish(rejection("execution", locale)));
+        worker.once("exit", () => { if (!settled) void finish(rejection("execution", locale)); });
+      } catch { void finish(rejection("execution", locale)); }
+    };
+    const timer = setTimeout(() => void finish(rejection("timeout", locale)), timeoutMs);
+    process.once("SIGINT", onCancel); process.once("SIGTERM", onCancel);
+    process.stdin.on("data", onData); process.stdin.once("end", onEnd); process.stdin.once("error", onInputError);
+  });
+}
+function emit(result) { process.exitCode = result.exitCode; process.stdout.write(`${result.stdout.join("\n")}\n`); }

package/bin/bridge-worker.mjs

@@ -0,0 +1,27 @@
+import { parentPort, workerData } from "node:worker_threads";
+import Module from "node:module";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Same repository-source/installed-artifact selection as nm.mjs, inside the deadline.
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const sourceCLI = path.join(root, "lib/nm/cli.ts");
+let runtime;
+if (existsSync(sourceCLI) && process.env.NM_CLI_FORCE_PACKED !== "1") {
+  const original = Module._resolveFilename;
+  Module._resolveFilename = function (request, ...args) {
+    if (typeof request === "string" && request.startsWith("@/")) {
+      const absolute = path.join(root, request.slice(2));
+      request = existsSync(`${absolute}.ts`) ? `${absolute}.ts` : absolute;
+    }
+    return original.call(this, request, ...args);
+  };
+  const { createJiti } = await import("jiti");
+  runtime = createJiti(import.meta.url)(sourceCLI);
+} else runtime = await import("../dist/index.js");
+const result = runtime.runNMCLI(["bridge", ...workerData.args], {
+  readStdin: () => workerData.input,
+  readFile: () => { throw new Error("The JSON bridge does not read filesystem sources."); },
+});
+parentPort.postMessage(result);

package/bin/nm.mjs

@@ -25,7 +25,9 @@ const isPackedVersionCommand =
   process.env.NM_CLI_FORCE_PACKED === "1" &&
   (cliArgs[0] === "--version" || cliArgs[0] === "version");
 
-if (isPackedVersionCommand) {
+if (cliArgs[0] === "bridge") {
+  await (await import("./bridge-host.mjs")).runNMBridgeHost(cliArgs.slice(1));
+} else if (isPackedVersionCommand) {
   const { nmVersionManifest } = await import("../dist/version.js");
   process.stdout.write(
     cliArgs.includes("--json")