@nika-open/nika runs .nika workflows from your application and proves
what they did. Your product owns the request, the interface and the business
state. The Nika engine owns parsing, admission, execution, policy, events,
receipts and traces, and the engine comes inside the npm package.
run() admits the workflow before it returns: a file the engine refuses
throws a typed NikaOperationError, and no handle is ever handed out.
result() is the one settlement: an admitted workflow that fails resolves as
status: 'failed' data, not a throw. The quickstart
runs this end to end in five minutes.
Two doors, one client
url for the local transport. Supply url and token for HTTP. On a
server, a served name such as workflows/release.nika (the workflow’s path
from the server’s project root) needs no local engine or file; an explicit
local path such as ./release.nika uses a compatible local engine to capture
an immutable snapshot first. How the SDK works compares
the two doors line by line.
An illustration of the two doors, with captured content. new Nika() starts the bundled engine as a child process, and new Nika({ url, token }) reaches nika serve with the same methods and other options. Two lines of demo.mts, the quick start in the package README, change between them: line 3, the constructor, takes url, token and allowInsecureHttp: true, which a plain http:// URL to a loopback host needs, and line 6, the run options, takes an idempotencyKey in place of maxCostUsd, which a server run refuses. The engine checks before anything runs: it refuses list-files.nika with NIKA-SEC-004, so no run exists, and runs hello.nika. The app reads six events from the local engine or two from the server, the run’s record is sealed, traceVerify(receipt) answers verified locally and sealed from the server, and one changed byte makes the verifier report BROKEN at line 5. An illustration: every code line, event, verdict, hash and version on screen was captured from @supernovae-st/nika 0.123.0, its bundled engine nika 0.123.0 (0bfde3765) and nika serve 0.123.0 in a mock/echo rehearsal; the cards, lanes, packets and pacing are drawn, and a real run takes milliseconds.
One lifecycle vocabulary
run() returns a handle only after admission; the handle is not a result.
Events are optional to render; run.result() is the run’s one ending,
including a pause at a human gate. Locally, a paused run resumes from the
command line; nika serve 0.124.3 has no route to answer the gate.
Configuration, compatibility, transport and protocol failures throw typed
errors.
Compatibility aliases from earlier releases
Compatibility aliases from earlier releases
nika.events(run), nika.cancel(run), nika.status(run) and run.done
remain as deprecated aliases. run.done is the same promise as
run.result(). New code should call the methods on the run handle:
run.events(), run.result(), run.cancel(), run.status().Documentation map
How it works
Start
Project
Local API
Runtime
Remote API
Operations
Reference
Authority boundary
- The SDK does not parse a second Nika language.
- It does not reconstruct traces or receipts in TypeScript.
- An observer
AbortSignaldoes not cancel a run; callrun.cancel(). - It does not infer success from an event kind.
- It exposes only the routes the released server answers.
Version and channel
Which published release these pages describe
Which published release these pages describe
nika.yaml from the working directory toward its ancestors. The file is optional when built-in defaults are enough. Its project-shape grammar is closed: nika · ceiling · arm · traces · registry. Direct runs and the cadence path (nika arm · nika serve) read the same file.