Admit and persist identity
{"workflow":"workflows/release.nika"} to POST /v1/jobs; the server captures
its served workflow itself. A served name is the workflow’s path from the
project root, not from --workflows. An explicit local path such as
./release.nika instead asks a compatible local engine for a snapshot and
sends those captured bytes; a snapshot freezes inputs, so inputs is refused
on that form.
Remote run options accept idempotencyKey, access (the job’s access pin,
sent as JobByName.access beside a served name) and, where the server
advertises jobInputs, literal inputs. vars, model and maxCostUsd are
refused with NikaCompatibilityError (capability: 'runOptions') because
their request envelopes do not exist. A snapshot of a local file carries no
pin either: access beside one is refused (capability: 'snapshotAccess').
A fresh randomUUID() per retry defeats the contract: the key is what lets
the server return the original job instead of starting a second one. Keys
cover the whole --state-root and do not expire, so never reuse one for
another operation.
Spend on the server
The server bounds spend itself:nika serve --run-cost-ceiling <USD> caps
every job your code submits, 1 USD by default (none removes the cap).
A job whose cost floor exceeds it is admitted, then settles failed with
error.code NIKA-1709; run() does not throw. Bound a job through its
workflow (its model and max_tokens), and see Spend caps.
Observe and settle
machineBufferBytes, 16 MiB, is the bound of the server’s own job
store, so every result the server settles reaches run.result(). A client
configured with a smaller bound is refused with a NikaProtocolError that
names the size to set; the job keeps its result, and attachRun() with a
larger bound reads it again.
Recover after a process restart
lastEventId, and reuse it. Reattachment avoids resubmitting a workflow
merely because the Node process restarted. The engine’s settlement remains
available on result.settlement even when the cursor already consumed its
terminal event. Only a server job id is durable: a local run.id is a
throwaway id, and attachRun() refuses it.
Read status or cancel
202 with { accepted: true, status: 'cancellation_requested' }: the server accepted the request and the run is
still settling. Await run.result() for its actual status. A success or
failure that wins the race is preserved; an execution that has not settled
within the server’s 5-second grace ends interrupted, with no settlement. A
job cancelled before its execution started settles cancelled on the reply
itself (200), and a job that already ended answers accepted: false,
status: 'already_settled'. The API has no job-list route, so application
indexes remain application-owned.
Download what it produced
Once the job has settled,run.artifacts() lists the files its sealed journal
records, and run.readArtifact() or run.downloadArtifact() returns their
bytes, proven against the recorded size and SHA-256. A handle from
attachRun() has the same methods, so a recovered job’s files stay
reachable by its id:
SSE streaming
Preserve sequence continuity across observers.
Errors
Separate run failure from boundary failure.