@supernovae-st/nika 0.120.0 → 0.120.3

package/README.md

@@ -10,8 +10,9 @@
 <h1 align="center">@supernovae-st/nika</h1>
 
 <p align="center">
-  <strong>The TypeScript door to Nika: audit a workflow, run it, watch it, prove it.</strong><br>
-  Locally through the released engine, or against an authenticated <code>nika serve</code>.
+  <strong>Run AI workflows from TypeScript.</strong><br>
+  Audit a <code>.nika</code> file, run it, read the result, verify the receipt — locally
+  or against authenticated <code>nika serve</code>.
 </p>
 
 <p align="center">
@@ -29,22 +30,17 @@
   <a href="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/supernovae-st/nika-client"><img src="https://archive.softwareheritage.org/badge/origin/https://github.com/supernovae-st/nika-client/" alt="Archived by Software Heritage"></a>
 </p>
 
-## Thirty seconds, no API key
+## Run a workflow from your app
 
-One package installs the client, the `nika` command and the engine payload for
-your platform (macOS and Linux, arm64 and x64):
+Put repeatable AI work in a `.nika` file. From Node, run it and read the
+result. No server and no API key for the first run: `mock/echo` is a
+**local simulation** (output is prefixed `mock(echo) ·`, not a model answer).
 
 ```sh
-npm install @supernovae-st/nika@0.118.7
-./node_modules/.bin/nika --version
-```
-
-```
-nika 0.118.7 (f3a31a6ee)
+npm install @supernovae-st/nika
 ```
 
-Write `hello.nika`. The `mock/echo` model rehearses with no key and no
-network:
+Save as `hello.nika`:
 
 ```yaml
 nika: hello
@@ -59,7 +55,35 @@ outputs:
   greeting: ${{ tasks.greeting.output }}
 ```
 
-Audit it before anything runs:
+Save as `demo.mjs`:
+
+```js
+import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika';
+
+const run = await new Nika({ cwd: process.cwd() }).run('hello.nika', { maxCostUsd: 0 });
+const result = await run.result();
+if (!isNikaRunSucceeded(result)) {
+  console.error(result.status, result.error?.code, result.error?.message);
+  process.exitCode = 1;
+} else {
+  console.log(result.outputs);
+  // { greeting: "mock(echo) · Say hello from the Nika SDK." }
+}
+```
+
+```sh
+node demo.mjs
+```
+
+`run()` already admits: a red file throws `NikaOperationError` and never
+returns a handle. The `.nika` file is the contract; the SDK does not parse
+YAML. Pin the version you tested — see [Install](#install): the SDK and the
+standalone engine CLI release on independent clocks.
+
+`check()`, `run.events()`, and `traceVerify()` are the next steps. They stay
+taught and tested; they are not required to see the first result.
+
+### Next: audit without running (`check`)
 
 ```sh
 ./node_modules/.bin/nika check hello.nika
@@ -74,45 +98,31 @@ Audit it before anything runs:
  layers · valid ✔ · access ready ✔ · capacity fit ✔ · run ready ✔
 ```
 
-Now drive the same engine from TypeScript:
+The same report is `await nika.check('hello.nika', { nativeStrict: true })`.
+A red check never becomes a run.
 
-```ts
-import { Nika } from '@supernovae-st/nika';
-
-const nika = new Nika({
-  cwd: process.cwd(),
-  // bin: '/absolute/path/to/nika', // or set NIKA_BIN
-});
+### Next: watch the run (`run.events()`)
 
-const report = await nika.check('hello.nika', {
-  nativeStrict: true,
-});
-if (!report.clean) throw new Error('workflow did not pass nika check');
-
-const run = await nika.run('hello.nika', { maxCostUsd: 0 });
+```ts
 for await (const event of run.events()) {
-  // The same lifecycle words on both transports; the engine's own frame,
-  // in its protocol vocabulary, stays on event.raw.
   console.log([event.kind, event.task, event.status].filter(Boolean).join(' '));
 }
-
-const result = await run.result();
-console.log(result.status, result.outputs, result.receipt);
 ```
 
-Expected output: `run.started`, `task.scheduled greeting`,
-`task.started greeting`, `task.completed greeting`, `engine.event`, then
-`run.settled succeeded`, then the terminal `succeeded` line with the outputs
-and the receipt. The `engine.event` is the native journal's own
-`workflow_completed` frame: the SDK gives it no lifecycle name and no state,
-drops nothing, and shows it on `event.raw.kind`.
-
-That is six frames for one task; the same shape with 90 tasks was measured at
-273 (`3N + 3`). A session retains the most recent 4096 frames by default, so
-`run.events()` opened after `run.result()` replays them all, and is refused,
-never shortened, past that bound; see
+Expected native events for this one-task file: `run.started`,
+`task.scheduled greeting`, `task.started greeting`,
+`task.completed greeting`, `engine.event` (`workflow_completed` on
+`event.raw.kind`), then `run.settled succeeded`. Six `run.events()` frames,
+sealed or not (probed on 0.120.0). A session retains the most recent 4096
+frames by default; see
 [Observing a run after the fact](#observing-a-run-after-the-fact).
 
+### Next: verify a seal (`traceVerify`)
+
+`traceVerify` **verifies** an existing seal. It does not create one. A keyless
+machine still **succeeds**; the receipt is unsealed — see
+[Admission, execution, seal](#admission-execution-seal).
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/supernovae-st/nika-client/main/media/local-driver.gif" alt="The typed driver over the released binary: check the workflow, gate on the report, run it to the end under a cost ceiling, count the events" width="960">
 </p>
@@ -183,8 +193,11 @@ An engine without the capability rejects with `NikaCompatibilityError`
 (`capability: 'inputsLiteral'` or `'jobInputs'`) and nothing runs. The SDK
 never falls back to `--var`, and a resident that merely answers 202 has
 negotiated nothing: one from before the envelope accepts the field and ignores
-its values. The engine payload pinned by this package version advertises
-neither capability yet, so `inputs` is refused on it until the pin moves.
+its values.
+
+The **published 0.120.0** payload advertises `inputsLiteral` (`nika --sdk-identity`).
+Native `run({ inputs })` works on it. It does **not** advertise `jobInputs`;
+HTTP literal inputs stay a compatibility refusal until a resident that does.
 
 `vars` is deprecated. It remains the native `--var KEY=VALUE` operator channel,
 unchanged: the engine reads `@env:NAME` from its environment and coerces text
@@ -197,10 +210,9 @@ A `try { await run.result() } catch {}` alone therefore never catches a failed
 workflow: a CI job or an application must read `result.status` and treat
 anything but `succeeded` as its own failure, or a red run passes silently.
 
-On the development branch, `isNikaRunSucceeded` provides that TypeScript
-narrowing. It is **unreleased** and is not exported by the published
-`0.118.7` package; that package uses `result.status === 'succeeded'` directly.
-For CI built from this branch:
+`isNikaRunSucceeded` is exported by published **0.120.0**. Use it (or
+`result.status === 'succeeded'`) before treating a result as success.
+Paused, failed, cancelled, and interrupted all return false:
 
 ```ts
 import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika';
@@ -229,17 +241,40 @@ into a fabricated output map.
   secret and the cost floor. A red check never becomes a run.
 - **Sovereign by default.** The same file runs on local models (Ollama,
   llama.cpp, vLLM), on Mistral, Hugging Face, OpenAI, xAI, Anthropic and the
-  rest of the engine's catalog; `mock/echo` rehearses with no key and no
-  network.
-- **Traced after.** Every native run leaves a hash-chained journal and hands
-  back a receipt; `traceVerify()` asks the engine to verify it. The SDK never
-  re-implements the proof.
+  rest of the engine's catalog; `mock/echo` is a local simulation with no key
+  and no network.
+- **Traced after.** A native run writes a hash-chained journal and a receipt.
+  `traceVerify()` asks the engine to verify that evidence. A succeeded run can
+  still be unsealed. The SDK never re-implements the proof.
 - **One vocabulary, two transports.** `check`, `run`, `events`, `cancel`,
   `traceVerify` and `schedule` read the same against a local process and an
   authenticated `nika serve`; only the constructor changes. Run events carry
   the same lifecycle words on both (`run.started`, `run.waiting`,
   `run.settled`), with the engine's own frame kept on `event.raw`.
 
+## Admission, execution, seal
+
+Three different facts. Do not collapse them.
+
+| Fact | How you see it | What it is not |
+|---|---|---|
+| **Admission** | `check()` returns `clean: false` and findings. `run()` **throws** `NikaOperationError` (`NIKA-PARSE-005`, `NIKA-1708`, …) and yields no handle. | Not a successful execution. |
+| **Execution** | `run.result()` / `isNikaRunSucceeded(result)`. Admitted failure is **data** (`status: "failed"`). A human gate is `paused` (`run.waiting`), not success. | Not proof the journal is sealed. |
+| **Seal** | `result.receipt.sealed` and `traceVerify(receipt)`. Tamper-evident, not tamper-proof; not replayed unless you pass `--replay`; not anchored without a sidecar. | Not “the workflow was correct” and not “a human read the output”. |
+
+Probed on published 0.120.0 (2026-09-19): `run.events()` still yields the
+same six lifecycle frames with or without a signing key. With
+`~/.nika/keys/run-signing.*`, the hello fixture sealed and `traceVerify`
+returned `{ verified: true, verdict: "verified" }`. With an isolated `HOME`
+and no key files (keychain skipped: stderr not a TTY), the same file
+**succeeded**, `sealed: false`, and `traceVerify` returned
+`{ verified: false, verdict: "invalid", reason: "receipt_mismatch" }` while
+the engine still said the journal chain was OK and **UNSEALED**. In this
+keyless case that reason means no signed binding, not a failed workflow.
+`receipt_mismatch` is also the engine's word for a tampered or
+field-mismatched receipt — do not treat every occurrence as merely unsigned.
+The CLI verify line that counts journal events is not `run.events()`.
+
 ## One vocabulary
 
 `Nika` exposes `check`, `run`, `attachRun`, `traceVerify`, `listWorkflows`,
@@ -287,19 +322,34 @@ not parse YAML or reconstruct proof in TypeScript.
   Socratic risk matrix
 - [Migrating to 0.116](docs/migrating-to-0.116.md) · the intentional breaking
   migration to the smaller durable client surface
-- [docs.nika.sh](https://docs.nika.sh) · the language, the engine and the
-  other doors
+- [docs.nika.sh](https://docs.nika.sh) · language and engine
+- [SDK quickstart](https://docs.nika.sh/sdk/start/quickstart) · app walkthrough
+  (install **npm `@supernovae-st/nika`**, matching this README)
 
 ## Install
 
-Pin the version you tested, then verify the package the project actually
-resolved:
+```sh
+npm install @supernovae-st/nika
+```
+
+Every SDK package bundles its own matching engine: the `nika` binary under
+`node_modules/.bin` is the exact engine that package was qualified against.
+The standalone engine CLI (GitHub releases, brew, install script) releases on
+an independent clock, so its newest tag can be ahead of or behind the engine
+bundled in the latest npm package. The
+[npm registry](https://www.npmjs.com/package/@supernovae-st/nika?activeTab=versions)
+lists current published versions. Pin the version you tested, then verify the
+package the project actually resolved:
 
 ```sh
-npm install @supernovae-st/nika@0.118.7
 node -p "require('@supernovae-st/nika/package.json').version"
+./node_modules/.bin/nika --version
 ```
 
+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
 pin checks. It reports the installed dependency, not a moving registry tag.
 The native payloads `@supernovae-st/nika-<os>-<arch>` are optional
@@ -318,19 +368,66 @@ deprecated`. The repository keeps its name (`supernovae-st/nika-client`).
 
 ## Scaffold with the engine
 
-The lowest-friction creation door is the engine-owned scaffold:
+On the published 0.120.0 binary, `nika new` is **retired** (`unrecognized
+subcommand`). The creation door is `compile`. Exact skeleton name or `hello`;
+free-text intent stays incomplete and writes nothing:
 
 ```sh
 ./node_modules/.bin/nika init --project-file
-./node_modules/.bin/nika new 01-hello hello.nika
+./node_modules/.bin/nika compile hello hello.nika
+```
+
+No destination means preview only. `nika.yaml` is the project control plane
+(needed for `nika serve`). `hello.nika` is the executable contract passed to
+`check()` and `run()`. The engine's `hello` skeleton names its task `greet`
+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);
+}
 ```
 
-`nika.yaml` is the project control plane. `hello.nika` is executable
-workflow intent and is the file passed to `check()` and `run()`. The scaffold
-writes the engine's own annotated `01-hello` example (its task is named
-`greet` and its prompt asks for French); the contract this README relies on is
-the `outputs.greeting` key and the `mock/echo` model, which the hand-written
-file above satisfies too.
+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
 
@@ -340,7 +437,12 @@ Pass that receipt back unchanged:
 ```ts
 if (!result.receipt) throw new Error('run did not issue a receipt');
 const proof = await nika.traceVerify(result.receipt);
-if (!proof.verified) throw new Error(proof.output ?? 'trace verification failed');
+// proof.verified is the seal/binding, not the workflow outcome.
+if (isNikaRunSucceeded(result) && proof.verified) {
+  // run succeeded and the journal is sealed
+} else if (isNikaRunSucceeded(result) && !proof.verified) {
+  // succeeded, unsigned or otherwise unverified — read proof.reason
+}
 ```
 
 The SDK does not implement cryptography or inspect the trace itself. It asks the
@@ -388,9 +490,8 @@ settles on the terminal the resident records, `cancelled`, `succeeded`,
 `failed`, or `interrupted` once its grace expired. A job that already ended
 replays its result with `accepted: false` and `status: 'already_settled'`. The
 native transport signals its process the same way; the result is whatever the
-engine then wrote, `cancelled` when it settled the request (the released
-0.118.7 engine does), or `interrupted` when the process ended with no
-settlement frame.
+engine then wrote, `cancelled` when it settled the request, or `interrupted`
+when the process ended with no settlement frame.
 
 ## Connect to `nika serve`
 
@@ -646,8 +747,9 @@ A view opened late is seeded with every frame the session observed, or it is
 refused. It is never handed a shortened replay. How many frames a session
 retains is `eventBufferSize`, **4096 by default**.
 
-**The measured frame count: `3N + 3`, for one shape.** On the released 0.118.7
-engine, a clean run of N independent `mock/echo` `infer` tasks wrote
+**The measured frame count: `3N + 3`, for one sealed shape.** On the released
+0.118.7 engine (and still the native 0.120.0 hello fixture when sealed), a
+clean run of N independent `mock/echo` `infer` tasks wrote
 `workflow_started`, then `task_scheduled`, `task_started` and `task_completed`
 per task, then `workflow_completed` and `run_settled`. Two points were
 measured: 1 task is 6 frames, 90 tasks are 273. That is this fixture, not a
@@ -957,7 +1059,7 @@ The repository also carries 100 distinct use-case workflows and provider proof
 under `gauntlet/`.
 
 <!-- engine hero pinned to the release tag it demonstrates · re-pin on lockstep bumps -->
-![nika check audits the workflow, then runs and seals its trace](https://raw.githubusercontent.com/supernovae-st/nika/v0.118.7/media/nika-hero.gif)
+![nika check audits the workflow, then runs and seals its trace](https://raw.githubusercontent.com/supernovae-st/nika/v0.120.1/media/nika-hero.gif)
 
 ## Keeping it fresh
 

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