@supernovae-st/nika 0.120.2 → 0.120.3

package/README.md

@@ -346,8 +346,8 @@ node -p "require('@supernovae-st/nika/package.json').version"
 ./node_modules/.bin/nika --version
 ```
 
-This repository's source train is **0.120.2** (`package.json`), lockstep with
-public engine tag `v0.120.2` (`289a9adea`). A source train is not a published
+This repository's source train is **0.120.3** (`package.json`), lockstep with
+public engine tag `v0.120.3` (`578352a31`). A source train is not a published
 npm version until the release workflow publishes it.
 
 This package metadata subpath is exported for CommonJS, ESM build tools and CI
@@ -383,6 +383,52 @@ No destination means preview only. `nika.yaml` is the project control plane
 and asks for French; the hand-written file above is enough if it keeps
 `outputs.greeting` and `model: mock/echo`.
 
+## Compile a candidate without running it
+
+`compile()` requires an engine that advertises the `compile` capability. The
+released 0.120.3 engine supports native compilation and its Serve advertises
+HTTP compilation (the route landed in engine commit `4334e58b`, first published
+in v0.120.3); a 0.120.2 or older Serve predates that route and is refused
+without fallback. This SDK method first publishes with 0.120.3. This foundation resolves
+exact embedded skeleton names (including `hello`) and edits existing constants;
+unsupported intent remains `incomplete`.
+
+```ts
+const candidate = await nika.compile({
+  intent: 'classify-and-route',
+  answers: { 'const.request': 'An outage affects support customers.' },
+}, { timeoutMs: 15_000 });
+
+// The outcome is source and review data. Incomplete/refused are also outcomes.
+console.log(candidate.status, candidate.questions, candidate.diagnostics);
+if (candidate.ready && candidate.candidate !== null) {
+  const edited = await nika.compile({
+    workflow: candidate.candidate,
+    change: { set_constant: { name: 'request', value: 'One customer is affected.' } },
+  });
+  console.log(edited.candidate);
+}
+```
+
+Edits also accept a string such as `Set const.request to "One customer"`.
+Answers and structured values are strict JSON values, preserving numbers,
+booleans, null, strings, arrays and objects. The native adapter uses the engine's
+CLI; the HTTP adapter sends authenticated `POST /v1/compile`. An unavailable
+remote capability raises `NikaCompatibilityError` without local fallback.
+
+`candidate` is `.nika` source, distinct from the path accepted by `run()`.
+The caller reviews and materializes it before calling `run(path)`, which performs
+normal admission. `requested_boundary` and the source-only `check_preview` grant
+no execution authority. Compile creates no Run, job, approval or Proof, and the
+SDK writes no persistent candidate file. `signal`/`timeoutMs` stop only the
+compile request. The common outcome has no `exitCode` or `written` field.
+
+Compile accepts standard `AbortSignal`s, including `AbortSignal.any` composites.
+It rejects direct signal interface overrides and proxies before starting work.
+Composite sources must retain their standard interfaces: Node may read their
+public fields while inspecting or subscribing to a composite, so the SDK cannot
+validate a modified hidden source graph without invoking those fields.
+
 ## Verify a local trace
 
 Local terminal results carry an engine-issued receipt when tracing is enabled.

package/dist/bin/nika.js

@@ -150,29 +150,41 @@ function captureEngine(bin, args, options) {
       shell: false,
       stdio: ["ignore", "pipe", "pipe"]
     });
-    let stdout = "";
-    let stderr = "";
+    const stdout = [];
+    const stderr = [];
+    const bytes = { stdout: 0, stderr: 0 };
     let overflow = false;
     let spawnError;
+    let closed = false;
+    let killTimer;
+    const stop = () => {
+      child.kill("SIGTERM");
+      if (options.killGraceMs === void 0) return;
+      killTimer ??= setTimeout(() => {
+        if (!closed) child.kill("SIGKILL");
+      }, options.killGraceMs);
+      killTimer.unref();
+    };
     const append = (stream, chunk) => {
       if (overflow) return;
-      if (stream === "stdout") stdout += chunk;
-      else stderr += chunk;
-      if (Buffer.byteLength(stdout) > options.bufferBytes || Buffer.byteLength(stderr) > options.bufferBytes) {
+      bytes[stream] += chunk.byteLength;
+      if (bytes[stream] > options.bufferBytes) {
         overflow = true;
-        child.kill("SIGTERM");
+        stop();
+        return;
       }
+      (stream === "stdout" ? stdout : stderr).push(chunk);
     };
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
     child.stdout.on("data", (chunk) => append("stdout", chunk));
     child.stderr.on("data", (chunk) => append("stderr", chunk));
-    const abort = () => child.kill("SIGTERM");
+    const abort = () => stop();
     options.signal?.addEventListener("abort", abort, { once: true });
     child.once("error", (cause) => {
       spawnError = cause;
     });
-    child.once("close", (code) => {
+    child.once("close", (code, exitSignal) => {
+      closed = true;
+      if (killTimer) clearTimeout(killTimer);
       options.signal?.removeEventListener("abort", abort);
       if (options.signal?.aborted) {
         reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
@@ -188,7 +200,19 @@ function captureEngine(bin, args, options) {
           `${options.label} exceeded ${options.bufferBytes} bytes`
         ));
       } else {
-        resolve({ exitCode: code ?? 3, stdout, stderr });
+        let decoded;
+        try {
+          decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(stdout, bytes.stdout));
+        } catch {
+          reject(new NikaProtocolError(options.transport, `${options.label} stdout was not valid UTF-8`));
+          return;
+        }
+        resolve({
+          exitCode: code ?? 3,
+          stdout: decoded,
+          stderr: Buffer.concat(stderr, bytes.stderr).toString("utf8"),
+          exitSignal
+        });
       }
     });
   });
@@ -252,9 +276,9 @@ function incompatible(transport, message) {
 
 // src/lib/binary/verify.ts
 var IDENTITY_BUFFER_BYTES = 16 * 1024;
-async function verifyNikaEngine(engine) {
+async function verifyNikaEngine(engine, options = {}) {
   const expectedVersion = engine.packageRoot ? await verifyManagedPayload(engine) : void 0;
-  const identity = await probeIdentity(engine.bin);
+  const identity = await probeIdentity(engine.bin, options);
   if (expectedVersion !== void 0 && identity.engineVersion !== expectedVersion) {
     throw incompatible2(
       `Packaged engine version ${identity.engineVersion} does not match payload version ${expectedVersion}`
@@ -293,13 +317,15 @@ async function verifyManagedPayload(engine) {
   }
   return manifest.version;
 }
-async function probeIdentity(bin) {
+async function probeIdentity(bin, options) {
   const notAnEngine = `is ${bin} a nika engine? (run "${bin} --sdk-identity" by hand)`;
   const captured = await captureEngine(bin, ["--sdk-identity"], {
+    ...options,
     bufferBytes: IDENTITY_BUFFER_BYTES,
     transport: "native-process",
     label: "Engine identity probe"
   }).catch((cause) => {
+    if (options.signal?.aborted) throw cause;
     throw incompatible2(
       `Engine identity probe of ${bin} failed`,
       cause