@nika-open/nika 0.0.0-stage → 0.124.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/errors.md ADDED
@@ -0,0 +1,154 @@
1
+ # Errors and troubleshooting
2
+
3
+ A workflow that runs and fails is **data**: `run.result()` resolves with
4
+ `status: 'failed'` and the engine's `error`. Everything else that can go wrong
5
+ is a typed error. Every error the package raises for an engine, transport,
6
+ configuration or compatibility problem extends `NikaError`. Misusing the API
7
+ itself (an empty workflow name, a negative event cursor, a receipt that is not
8
+ an object, a workflow name that escapes the served folder) throws a plain
9
+ `TypeError` or `RangeError` before any engine or network work starts.
10
+
11
+ ```text
12
+ NikaError
13
+ ├── NikaConfigurationError bad options or inputs; nothing was started or sent
14
+ ├── NikaEngineUnavailable no engine for this machine (see below)
15
+ ├── NikaTransportError spawn, network, timeout or abort
16
+ │ ├── NikaProtocolError output that breaks the machine contract
17
+ │ └── NikaObservationInterrupted this client lost its view of a run that may still run
18
+ ├── NikaCompatibilityError the engine or server lacks what the call needs
19
+ ├── NikaOperationError the engine or server refused, with its own code
20
+ ├── NikaEventBufferOverflowError one event view was refused; the run is unaffected
21
+ └── NikaRunOwnershipError a handle this client did not create
22
+ ```
23
+
24
+ ## A refused run
25
+
26
+ The engine refuses a workflow before admitting it for a red check, a cost
27
+ floor above `maxCostUsd`, a missing required input or a file it cannot read.
28
+ `run()` then rejects, before any `NikaRun` exists, with a
29
+ `NikaOperationError` carrying `operation: 'run'` and the engine's exit status
30
+ in `status`:
31
+
32
+ ```ts
33
+ try {
34
+ const run = await nika.run('./workflow.nika');
35
+ const result = await run.result(); // admitted: a failure here is result data
36
+ } catch (error) {
37
+ if (error instanceof NikaOperationError && error.operation === 'run') {
38
+ console.error(error.code); // for example 'NIKA-SEC-004'
39
+ for (const finding of error.findings ?? []) console.error(finding.message);
40
+ } else throw error;
41
+ }
42
+ ```
43
+
44
+ For a workflow whose `exec:` task runs `ls` under `permits: {}`, engine
45
+ 0.123.0 answers `NIKA-SEC-004` (exit status 2) with the finding
46
+ ``exec task under a boundary that forbids shells (task `list`) — fix: add "ls" to permits.exec``.
47
+
48
+ <p align="center">
49
+ <img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-check-refused.png" alt="list-files.nika runs ls -1 under permits: {}. node gate.mts list-files.nika prints check refused · exit 2, NIKA-SEC-004 and the finding exec task under a boundary that forbids shells (task list) — fix: add ls to permits.exec, then run not started · NIKA-SEC-004 · no run, no events, no trace" width="860">
50
+ </p>
51
+ <p align="center"><sub>That file from TypeScript: <code>check()</code> returns the refusal and its fix, and <code>run()</code> rejects with <code>NikaOperationError</code> before any run exists. Captured from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine; <a href="https://github.com/nika-open/nika-client/blob/main/scripts/media/scenes/sdk-admitted-executed-sealed/gate.mts"><code>gate.mts</code></a> is the program. The whole story, through the seal, is in the <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-admitted-executed-sealed.mp4?raw=true">recording</a>.</sub></p>
52
+
53
+ - `code` is the engine's own: the first check finding that names one
54
+ (`NIKA-SEC-004`, `NIKA-PARSE-005`, `NIKA-AUTH-006`…) or the refusal's code
55
+ (`NIKA-1709`, `NIKA-1708`). `machineCode` repeats it. When the engine named
56
+ none, as for an unreadable file, `code` is the package's `run_refused` and
57
+ `machineCode` is absent: the package never supplies an engine code.
58
+ - `findings` holds the engine's check findings untouched, as
59
+ `NikaCheckFinding` (`code?`, `message`, `severity`, `gate`, `kind`, `task`,
60
+ `docs_url`). A budget or launch refusal has none.
61
+ - Nothing was admitted, so nothing else exists: no run id, no events, no
62
+ trace, no receipt.
63
+
64
+ Output that proves neither an admission nor a refusal (a line that is not
65
+ machine output, a truncated or oversized report, an engine that exits without
66
+ a frame) rejects `run()` with `NikaProtocolError` instead.
67
+
68
+ ## A server's refusal
69
+
70
+ A refusal `nika serve` types as `{ error: { code, message } }` becomes a
71
+ `NikaOperationError` with the HTTP `status`, the server's `code`
72
+ (`unauthorized`, `job_not_found`, `idempotency_conflict`,
73
+ `malformed_snapshot`, `NIKA-1802` for an empty access pin, or another stamped
74
+ `NIKA-…` admission code), the same code on `machineCode`, and the refused
75
+ `operation`. Server messages are the engine's, without paths, and a reflected
76
+ bearer token is redacted before it reaches a message. A non-2xx answer
77
+ without that typed body stays a `NikaTransportError` whose body is redacted
78
+ entirely. Compile refusals are listed in [compile.md](compile.md#errors).
79
+
80
+ The artifact routes add their own codes, on `run.artifacts()`,
81
+ `run.downloadArtifact()` and `run.readArtifact()` (`operation` names the
82
+ method):
83
+
84
+ | HTTP | `code` | When |
85
+ |---|---|---|
86
+ | 401 | `unauthorized` | no bearer token, or a wrong one |
87
+ | 403 | `artifact_too_large` | a download over the server's `max_artifact_bytes` (256 MiB by default); the artifact stays listed |
88
+ | 404 | `job_not_found` | an unknown or foreign job id |
89
+ | 404 | `artifact_not_found` | no manifest entry by that name |
90
+ | 408 | `request_timeout` | the manifest took longer than the server's request deadline |
91
+ | 409 | `job_not_settled` | the job is queued, running or paused: `await run.result()` first |
92
+ | 409 | `artifact_journal_unavailable` | no journal binds the job: an interrupted job never sealed one |
93
+ | 409 | `artifact_journal_unverified` | the job's journal is not sealed and intact with its receipt's head: a server without a run key answers this for every job |
94
+ | 409 | `artifact_changed` | the bytes at the recorded place no longer match the record: changed, moved, removed or replaced since the run |
95
+ | 500 | `internal_error` | the server could not read the journal or the file |
96
+ | 503 | `store_busy` · `artifact_capacity` | the server's job state, or all four of its artifact slots, are busy: retry with backoff |
97
+
98
+ A download that the server refused on a retry fails its stream with that
99
+ error; one still cut short after its retries fails with a
100
+ `NikaTransportError`, and bytes that are not the recorded ones with a
101
+ `NikaProtocolError` (see [server.md](server.md#download-what-a-job-produced-artifacts)).
102
+
103
+ Two schedule refusals carry a name of the package's own in `code`, and keep
104
+ the server's word where it has one:
105
+
106
+ | HTTP | The server sends | `code` | Also on the error |
107
+ |---|---|---|---|
108
+ | 412 | `{ error: { code: 'schedule_precondition_failed', currentRevision, message } }`: a stale, missing or malformed revision | `schedule_conflict` | `machineCode: 'schedule_precondition_failed'`, `currentRevision` (the revision to retry from, or `null`) |
109
+ | 422 | `{ findings: [{ code, detail }] }`, no code of its own: a declaration the server refuses | `schedule_refused` | `findings`, each with the server's `code` (`schedule.cost`, `schedule.pause`…) |
110
+
111
+ So branch on `code` for these two, and read `machineCode` when you need the
112
+ server's own word.
113
+
114
+ ## Also good to know
115
+
116
+ - `NikaEventBufferOverflowError` is never about the run (see
117
+ [runs.md](runs.md#a-view-opened-late)).
118
+ - `NikaObservationInterrupted` carries `lastSequence`, the cursor to resume
119
+ from with `attachRun` (see [server.md](server.md#recovery-after-a-restart)).
120
+ - Local engine events stay open to new kinds; server events must match the
121
+ closed, redacted `JobEvent` shape of the pinned OpenAPI contract, and
122
+ unknown HTTP fields are rejected at that boundary.
123
+ - The package never turns an unpriced model into `$0`.
124
+
125
+ ## Troubleshooting
126
+
127
+ | You see | Why | What to do |
128
+ |---|---|---|
129
+ | `not verified: receipt_mismatch` after a successful run | the engine your app starts found no signing key it can read, so the record is unsealed (or the receipt was edited) | `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init`: on a Mac whose keychain holds a key from Nika 0.122 or older, it mints a new key as files, since Nika 0.123 and later can neither read nor copy that one; on Linux, `./node_modules/.bin/nika key align` from a terminal copies a key that `nika key init --force` stored in the Secret Service (see [receipts.md](receipts.md#signing-keys-where-the-engine-finds-them)) |
130
+ | `NikaEngineUnavailable` from `new Nika()` | no engine payload for this machine: Windows, musl Linux (Alpine), Node.js older than 22 (npm skips the payload with an `EBADENGINE` warning), or an install with `--omit=optional` | Node.js 22 or newer on macOS or glibc Linux with optional dependencies; or an absolute `bin`/`NIKA_BIN`; or a `nika serve` by URL |
131
+ | `NikaCompatibilityError` with `capability: 'engineIdentity'` | the engine or server speaks another machine protocol (0.122 and older speak 1) | upgrade the engine and every `nika serve` to 0.123 or later (the package bundles the engine of its own version), or point `NIKA_BIN` at such an engine; see [upgrading-to-0.123.md](upgrading-to-0.123.md) |
132
+ | `NikaCompatibilityError` naming another capability (`inputsLiteral`, `jobInputs`, `compile`, `compileNativeV2`…) | the engine or server does not advertise what the call needs | use an engine that does, or drop the option; nothing was started |
133
+ | `NikaCompatibilityError` with `capability: 'artifacts'` | the server does not list `artifacts` in `/health` (engines before 0.123.2 do not), or the run is a local one, whose files are where its workflow wrote them | connect to a server that serves artifacts; for a local run, read the files in the client's `cwd` |
134
+ | `NikaOperationError` with `code: 'artifact_journal_unverified'` | the server has no run key, so the journals of its jobs are unsealed | run `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init` as the server's user; the jobs that run after it serve their artifacts |
135
+ | `NikaOperationError` with `code: 'artifact_changed'` | the file the run saved was changed, moved or removed on the server since | restore it or run the job again: the server never serves other bytes |
136
+ | `NikaConfigurationError: Artifact … more than readArtifact() holds` | the artifact is larger than `maxBytes` (16 MiB by default) | raise `maxBytes`, or stream it with `run.downloadArtifact()` |
137
+ | `NikaCompatibilityError` with `capability: 'snapshotInputs'` or `'snapshotAccess'` | a local file (`./flow.nika`) run or checked through a server: its snapshot takes no `inputs` or `access` | name the workflow the server serves (`listWorkflows()`); nothing was captured or sent |
138
+ | `NikaConfigurationError` about `bin` or `NIKA_BIN` | a bare name or a relative path, which would make the OS search `PATH` | an absolute path |
139
+ | `nika serve` exits with `token file must be mode 0600` | the token file is readable by others | `chmod 600 .nika/serve.token` |
140
+ | `nika serve` exits with `token file must be 32–512 visible ASCII` | the token is not 32–512 visible ASCII bytes (too short, too long, or other characters) | mint it again: `(umask 077 && openssl rand -hex 24 > .nika/serve.token)` |
141
+ | `nika serve` exits with `nothing armed — this project has no nika.yaml` | the server needs a project file in its folder | a one-line `nika.yaml`: `nika: my-project` |
142
+ | `NikaProtocolError: … exceeded … bytes (machineBufferBytes): it is … bytes` | a frame or document is larger than `machineBufferBytes`: a bound you lowered, or a local result above the 16 MiB default | set `machineBufferBytes` to at least the size the message names; over a server, leaving it unset also works (the default holds any result a server settles), and `attachRun(jobId)` reads the job again (see [runs.md](runs.md#large-results-machinebufferbytes)) |
143
+ | `run()` rejects with `NikaOperationError` | the engine refused the workflow before it ran | `error.code` and `error.findings`; `./node_modules/.bin/nika check <file>` shows the same audit |
144
+ | `result.status` is `failed` with `error.code` `NIKA-1802` or `NIKA-1801` after `run({ access })` | the engine refused the access pin: unknown or retired (`NIKA-1802`), or not usable for the workflow's model (`NIKA-1801`); it never takes another path | use a pin the engine knows (`./node_modules/.bin/nika doctor` lists every path), or drop `access`; `check({ access })` on a local engine shows it in `verdicts.blockers` |
145
+ | `run()` rejects with `NIKA-SEC-009` or `NIKA-SEC-014` on a workflow that ran on engine 0.123 | engine 0.124 judges a child workflow through the task that calls it, and follows untrusted content through a file a builtin reads (`nika:read`, `nika:grep`…): a lethal trifecta or a confirm gate that does not stop an effect is refused through a child or a file as it is inline | `./node_modules/.bin/nika check <file>` names the tasks and the path; apply the fix its finding names, for example a blocking `nika:prompt` of the parent's own before the call (a gate inside the child does not clear its caller). A confirm gate in front of a call whose child acts must stop it on a "no": bind the answer on the call, `with: { go: "${{ tasks.ask.output }}" }` and `when: ${{ with.go == true }}` |
146
+ | `run({ vars })` rejects with `NikaOperationError` `unknown_input` or `input_type_mismatch` | the engine refused a `--var` pair; engine 0.124 names its code (0.123 named none, and the package said `run_refused`) | fix the pair the message names, or move to `inputs` |
147
+ | `result.status` is `failed` with `error.code` `NIKA-1804` or `NIKA-1805` on a harness seat (`codex`, `claude-code`) | the seat reported a failed turn: `NIKA-1804` when it offers a retry (a 429 or retry limit, a lost connection, a model it rejects), `NIKA-1805` when it does not (a quota, a full context, a bad request). Engine 0.123 settled such a turn `succeeded`, its error text as the output | read `result.error.message`, the seat's own words; a declared `retry:` retries `NIKA-1804`, and a model the seat does not serve needs another model. `NIKA-1803` names a sign-in the app lost: sign in again in that app |
148
+ | `check()` reports `verdicts.run_ready: false` with a `seat · …` blocker naming `NIKA-432` or `NIKA-465`, or a run on a harness seat fails with that code | the task sets what its seat cannot carry, and the run refuses it before anything is sent: on an `infer:` over ACP (`run.access.protocol: acp`), `temperature`, `max_tokens`, an enabled `thinking` budget or a `vision:` URL; from engine 0.124.1, any `vision:` on a seat's direct one-shot (`codex exec`, `claude -p`: no `protocol: acp`), whose command carries no image, where 0.124.0 ran the task without its images; on a seated `agent:`, a `tools:` list, and `images:` on an `agent:` no seat serves (`NIKA-465`) | the blocker names the way out: for `vision:` files, `run.access: { via: <seat>, protocol: acp }` on a seat whose ACP session reads images, else an API route; for the other fields, an API route, or drop the field |
149
+ | `run()` rejects with `NIKA-1709` naming `nika:image_generate` or `nika:tts_generate`, or a server job settles `failed` with that code and no `settlement` | from engine 0.124, under a cost cap (`maxCostUsd` on a local run or a schedule, a project `ceiling:`, a server's `--run-cost-ceiling`), a paid media call the engine's dated price table cannot price is refused before any request: OpenAI's default voice `gpt-4o-mini-tts`, `gpt-image-1.5`, `gpt-image-1-mini`, or an id the table does not list. So is a priced call whose floor exceeds the cap and, under a zero cap, an image billed from its usage (`gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`) or speech whose text only the run renders. A call whose provider, model or arguments only the run decides, or that an `agent:` makes, fails with `NIKA-1704` before its request instead | the refusal names every model the table prices: for speech `model: tts-1` or `tts-1-hd`, a priced ElevenLabs model, or the keyless `provider: system` voice; for images `gpt-image-2` or a 2.5 model; `local` or `mock` for a rehearsal; or raise the cap. Only a run with no cap makes a paid call the table cannot price, and its settlement counts it `unpriced` |
150
+ | `check()` reports, or `run()` rejects with, `NIKA-AUTH-006` or `NIKA-SEC-004` naming a `vision:` file, or `result.status` is `failed` with `NIKA-SEC-004`, `NIKA-BUILTIN-READ-001` or `NIKA-BUILTIN-READ-002` on an `infer:` task | from engine 0.124, an `infer:` `vision:` file is a read under `permits.fs.read`, judged on its resolved path before any provider call: `NIKA-AUTH-006` with no `permits:` block; `NIKA-SEC-004` outside the grant, or under a block that grants no read at all, a computed path included; `NIKA-BUILTIN-READ-001` when a granted path holds no file or renders empty, `NIKA-BUILTIN-READ-002` for any other read failure | add the path to `permits.fs.read` (`./node_modules/.bin/nika check --infer-permits <file>` prints the block for a literal path), or fix the path; a `source: url` image needs no grant |
151
+ | `result.status` is `failed` with `error.code` `NIKA-AGENT-007` | the `agent:` task declares `images: { save: }` and its seat delivered no image bytes (engine 0.124); a path the harness only reported is never opened | ask for an image in the prompt, or drop `save:` and read `.output.images` when none is expected |
152
+ | `result.status` is `interrupted` after `run.cancel()` on a server | the run was still inside a task when the server's fixed 5-second cancel grace expired | that is the server's ending, not a failed cancel; the result has no settlement (see [server.md](server.md#cancel-a-running-job-the-5-second-grace)) |
153
+ | `result.status` is `failed` and nothing threw | an admitted run failed: that is data | read `result.error` (`code`, `message`, `task`) and `result.settlement` |
154
+ | `result.status` is `paused` | a human gate holds the run: a `nika:prompt`, or a harness that asked for more than `permits:` grants (from engine 0.124, any command a Codex seat asks to run outside its sandbox) | it is neither success nor failure: show it as waiting; a local run's `workflow_paused` frame holds the question (see [runs.md](runs.md#read-the-result)) |
@@ -0,0 +1,41 @@
1
+ # Glossary
2
+
3
+ The words these pages use, defined once. The engine's own vocabulary is in the
4
+ [Nika documentation](https://docs.nika.sh) and the
5
+ [language specification](https://github.com/nika-open/nika-spec).
6
+
7
+ | Word | Meaning |
8
+ |---|---|
9
+ | **Workflow** | A `.nika` file: the model to use, what it may touch (`permits:`), its tasks and its outputs. On a server, a workflow is also addressed by its *served name*, a path relative to the server's `--workflows` folder. |
10
+ | **Check** | The engine's static audit of a workflow, before any model is called: plan, models, access, cost, permits. `nika check` prints it; `check()` returns it; every `run()` applies it first. |
11
+ | **Access pin** | The path the engine takes to a workflow's model: a class (`mock`, `api`…) or a harness seat (`codex`, `claude-code`…), set with `access` (`--access` on the CLI). A pin is a pin: one the engine cannot take is refused (`NIKA-1801`, `NIKA-1802`), never swapped for another path. |
12
+ | **Admission** | The engine accepting a workflow for a run. `run()` resolves on admission and rejects on a refusal; nothing runs without it. |
13
+ | **Run** | One admission of a workflow, and the `NikaRun` handle your code gets for it. |
14
+ | **Job** | A run held by `nika serve`. Its id (`run.id` over HTTP) is durable: store it to reattach after a restart. |
15
+ | **Execution** | The engine's own id for what actually ran (`execution_id`), carried by the receipt. |
16
+ | **Event** | One lifecycle step of a run, as `run.events()` yields it: `run.started`, `task.completed`, `run.settled`… The engine's exact frame rides on `event.raw`. |
17
+ | **Sequence** | The server's number for an event (`event.sequence`), the cursor you store and pass back as `lastEventId`. Local events have none. |
18
+ | **Settlement** | How a run ended, in the engine's words: `result.status` and `result.settlement` (cause, task tally, time, spend). |
19
+ | **Human gate** | A step that waits for a person. The run is `paused` (a `run.waiting` event): neither failed nor finished. |
20
+ | **Interrupted** | The engine lost an execution, so its ending is unknown. Not the same as `NikaObservationInterrupted`, which means this client lost its view of a run. |
21
+ | **Trace** | The tamper-evident, hash-chained record of a run that the engine writes (locally under `.nika/traces/`). |
22
+ | **Seal** | The engine's signature over a trace, written as its last line when the run ends, with a signing key. A trace without one is *unsealed*. |
23
+ | **Receipt** | The proof material a run hands your code (`result.receipt`). Pass it back unchanged to `traceVerify()`. |
24
+ | **Artifact** | A file a settled server job produced, as its sealed journal records it with its size and SHA-256: what a builtin saved (`nika:chart`, `nika:image_generate`…) or an image an agent sent. `run.artifacts()` lists them (the job's *manifest*, bound to its receipt), and `run.downloadArtifact()` streams one, its bytes proven against that record. A local run has no manifest. |
25
+ | **Signing key** | The engine's run-signing key pair (`nika key init`). The engine your app starts reads it from `~/.nika/keys/` or `NIKA_RUN_KEY_FILE`/`NIKA_RUN_PUB_FILE`, never from an OS keychain. |
26
+ | **Door** | One of the two ways the package reaches an engine: the bundled engine as a child process (`new Nika()`, transport `native-process`) or a `nika serve` over HTTP (`new Nika({ url, token })`, transport `http`). |
27
+ | **`nika serve` (the resident)** | The engine running as a long-lived server you operate. It holds jobs and schedules across restarts. |
28
+ | **Snapshot** | The exact bytes of a local workflow file, captured by a local engine and sent to a server when you pass a path such as `./flow.nika`. |
29
+ | **Idempotency key** | A key you own for one business operation. Over HTTP, the same key returns the same job, so a retry never runs twice. |
30
+ | **Schedule** | A cadence declared on a server (`schedule()`), changed only by its current *revision*. |
31
+ | **Inputs** | Literal JSON values for the workflow's declared `inputs:`, passed with `run(workflow, { inputs })`. |
32
+ | **Permits** | What a workflow may reach: files, network, commands, tools. Default-deny engine policy; nothing in this package grants more. |
33
+ | **`mock/echo`** | The engine's offline rehearsal model: it echoes the prompt back (prefixed `mock(echo) ·`), with no key and no network. |
34
+ | **Compile** | Asking the engine for a candidate workflow from an intention or an edit (`compile()`). It runs nothing. |
35
+ | **Round** | One compile request and its outcome. An `incomplete` outcome asks questions; `nextCompileRequest()` builds the next round with your answers. |
36
+ | **Seat** | The authoring model a server's operator configured (`nika serve --authoring-model`). Over HTTP, a request opts in to it with `cognition: 'explicitProvider'`. |
37
+ | **Kept plan** | The plan a server keeps from a provider round, named by its `replay_token`, so an answer round can replay it instead of authoring again. |
38
+ | **Compile generation** | The compile wire version: `compile_version` 2 exactly when a provider call happened, 1 otherwise. |
39
+ | **Capability** | A feature an engine or server advertises (`nika --sdk-identity`, `GET /health`): `inputsLiteral`, `jobInputs`, `compile`, `compileNativeV2`… The package checks it before it asks. |
40
+ | **Machine protocol** | The generation of the machine contract between this package and the engine (2 for 0.123 and 0.124). The package refuses an engine on another generation at its identity probe, before any job. |
41
+ | **Release train (lockstep)** | Each package version bundles the engine with the same number, the one it was tested with, and moves with it. |
@@ -0,0 +1,396 @@
1
+ # HTTP contract
2
+
3
+ `openapi.json` is the checked-in contract pin. The SDK authenticates every
4
+ route except public `GET /health`; bearer tokens are redacted from failures.
5
+ A non-2xx answer typed as `{ error: { code, message } }` becomes a
6
+ `NikaOperationError` carrying `status`, `code`, and the refused `operation`.
7
+ For a check by served name, a typed 404 or 422 instead returns
8
+ `{ clean: false, error }`; authentication and transport failures still throw.
9
+ Any other non-2xx body is discarded and reported as a redacted
10
+ `NikaTransportError`.
11
+
12
+ | HTTP route | SDK surface | Contract |
13
+ |---|---|---|
14
+ | `GET /health` | internal identity handshake | public liveness and protocol versions |
15
+ | `GET /v1/openapi.json` | generation only | authenticated OpenAPI 3.1 document |
16
+ | `GET /v1/workflows` | `listWorkflows()` | contained relative workflow names |
17
+ | `GET /v1/workflows/{name}` | `workflow(name)` | path-free metadata, never source bytes |
18
+ | `GET /v1/access-offers/{name}` | `accessOffer(workflow)` | capability-gated (`accessSessionOffer`, engine 0.124.3); what the sessions of the workflow's own declared ACP route offer now, read without a prompt; see [Ask what a route offers](server.md#ask-what-a-route-offers) |
19
+ | `POST /v1/compile` | `compile()` | capability-gated stateless source authoring; 200 ready/incomplete/refused, no job; generation 2 needs `compileNativeV2` |
20
+ | `POST /v1/check` | `check()` | validates a served name (with an optional `access` pin) or immutable snapshot bytes without a job |
21
+ | `POST /v1/jobs` | `run()` | admits a served name (with optional `access` and `inputs`) or exact snapshot bytes with an idempotency key |
22
+ | `GET /v1/jobs/{id}` | internal settlement | durable job identity, outputs, receipt, settlement, or redacted error |
23
+ | `GET /v1/jobs/{id}/status` | `run.status()` | current status only |
24
+ | `GET /v1/jobs/{id}/events` | `run.events()` / `attachRun()` | bounded, sequenced SSE with replay |
25
+ | `POST /v1/jobs/{id}/cancel` | `run.cancel()` | 200 a settled job or its terminal replay; 202 the request accepted on a running job, settled later by observation |
26
+ | `GET /v1/jobs/{id}/trace/verify` | `traceVerify(receipt)` | the server's engine-owned verdict on the journal it wrote for the job, in the CLI's lower-case words, and its `reason` (the seal tier beside a verdict that holds); see [Trace verification](#trace-verification) |
27
+ | `GET /v1/jobs/{id}/artifacts` | `run.artifacts()` | a settled job's artifact manifest, read from its sealed journal and bound to its receipt; see [Artifacts](#artifacts) |
28
+ | `GET /v1/jobs/{id}/artifacts/{name}` | `run.downloadArtifact()` / `run.readArtifact()` | one artifact's recorded bytes, with their size and SHA-256 in the headers, streamed past the request deadline |
29
+ | `GET/PUT /v1/schedules/{id}` | `scheduleStatus()` / `schedule()` | resident schedule projection and CAS mutation |
30
+
31
+ ## Connection rules
32
+
33
+ - HTTPS is required for every host except loopback. Plain HTTP is accepted
34
+ only for `localhost`, `127.0.0.0/8`, or `[::1]`, and only with an explicit
35
+ `allowInsecureHttp: true`; that opt-in never admits a routable host.
36
+ - URLs containing credentials, a query, or a fragment are rejected.
37
+ - Tokens must contain 32–512 visible ASCII bytes and are never sent to
38
+ `/health`.
39
+ - `GET /health` must name machine protocol 2, the generation of engines 0.123
40
+ and 0.124 and of the engine this package bundles. A resident on another
41
+ generation (0.122 and older speak 1) is refused with `NikaCompatibilityError`
42
+ (`capability: 'engineIdentity'`) before any other request. A local engine
43
+ that captures a snapshot or observes a compile must report the same
44
+ machine protocol, snapshot, check-report and event clocks as the resident.
45
+ - Each request has a bounded timeout, except a compile provider round
46
+ without `timeoutMs` or `limits.deadline_ms` (see [compile.md](compile.md))
47
+ and an artifact download (see [Artifacts](#artifacts)),
48
+ and each JSON body and SSE frame has a byte ceiling, `machineBufferBytes`:
49
+ 16 MiB by default, the bound of the resident's own job store, which
50
+ refuses rather than truncates a larger result. A body past it is refused
51
+ before it is read when its `Content-Length` says so, and the refusal names
52
+ the option and the exact size; an SSE frame past it is read to its end,
53
+ uncollected, so its refusal names its size too (see
54
+ [runs.md](runs.md#large-results-machinebufferbytes)).
55
+ - Remote `run()` and `check()` send `access` as `JobByName.access` or
56
+ `CheckByName.access`, the CLI's `--access` vocabulary, for a served name
57
+ only; a snapshot body takes no pin, so a local path with `access` is
58
+ refused (`NikaCompatibilityError`, `capability: 'snapshotAccess'`) before
59
+ any capture or request. Every machine-protocol-2 resident reads the field;
60
+ no capability gates it. The resident refuses an empty or blank pin at
61
+ admission (422 `NIKA-1802`); any other pin is admitted (202), and a pin the
62
+ execution cannot take settles the job `failed` with the engine's code. The
63
+ check door is source-only and evaluates no access plan: it refuses an empty
64
+ pin and acknowledges any other.
65
+ - Remote `check()` refuses `model` and `nativeStrict`; remote `run()` refuses
66
+ `model`, `maxCostUsd` and the deprecated `vars`. The server applies its own
67
+ per-run ceiling to manual jobs (`nika serve --run-cost-ceiling`, 1 USD by
68
+ default). From engine 0.124 a job whose paid image or speech call the
69
+ engine's price table cannot price is still admitted (202), then settles
70
+ `failed` with `NIKA-1709` before any task runs and with no `settlement`.
71
+ - Remote `run()` sends `inputs` as `JobByName.inputs` only for a served name
72
+ and only when `GET /health` advertises `jobInputs`. That capability, not a
73
+ 202, is the negotiation: a resident from before the envelope accepts the
74
+ extra field and ignores its values, so the SDK refuses it after `/health`
75
+ alone with `NikaCompatibilityError` (`capability: 'jobInputs'`). The
76
+ `inputs` envelope is engine-owned (nika#1642); `JobByName.inputs` is in the
77
+ pinned `openapi.json` since engine 0.123.
78
+ - A snapshot body takes no `inputs` overlay, an empty map included: `run()` of
79
+ a local path with `inputs` is refused before any capture or request.
80
+ - The serialized `inputs` map is bounded at 1 MiB by the SDK, the bound the
81
+ native channel reads. The resident's whole-request ceiling is its own and may
82
+ be lower.
83
+ - Caller-provided workflow catalog names must be contained slash-separated
84
+ paths. Absolute paths, backslashes, empty segments, `.` and `..` are
85
+ rejected before network I/O.
86
+
87
+ A contained `.nika` name uses the resident registry without a local
88
+ engine. Prefix a local file with `./` to capture and submit its snapshot.
89
+ A successful by-name check returns `clean: true` and the compact resident
90
+ acknowledgement; no local check report or exit code is fabricated.
91
+
92
+ ## Compile foundation
93
+
94
+ Serve must advertise `compile` in `/health`. This route was added in engine
95
+ commit `4334e58bddf539a6253f448eb05d562b6919f2b7`, after release 0.120.2, and
96
+ first published in release 0.120.3.
97
+ The bundled OpenAPI and generated types preserve that exact producer contract. The SDK then posts a v1 create
98
+ intent or inline edit source to `/v1/compile`, with bearer authentication and
99
+ JSON content type. A string change becomes `{text: change}`; a structured change
100
+ preserves `{set_constant: {name, value}}`. Literal answers retain their JSON
101
+ types. There is no path, destination, idempotency key or local fallback.
102
+
103
+ Every core outcome uses HTTP 200. `incomplete` and `refused` remain reviewable
104
+ data; non-200 error envelopes raise `NikaOperationError` with the HTTP status
105
+ and engine code. Bad versions, malformed outcomes, overflow, cancellation and
106
+ timeout fail typed. The response is bounded by the smaller of
107
+ `machineBufferBytes` and 8 MiB. Compile's timeout covers health negotiation,
108
+ response headers and the complete body.
109
+
110
+ The shared outcome contains candidate source, questions, diagnostics, requested
111
+ boundary, source-only Check preview and provenance. It carries no process exit
112
+ code or materialized destination. A candidate and its requested boundary grant
113
+ nothing: execution needs a separate caller decision and normal `run` admission.
114
+
115
+ ## Compile generation 2 (ahead of the pin)
116
+
117
+ A resident whose operator seated a native authoring model (`nika serve
118
+ --authoring-model`) advertises `compileNativeV2` and also speaks
119
+ `compile_version: 2`. The SDK sends generation 2 only for a request that names
120
+ `cognition: 'explicitProvider'` (one fresh round under that seat, or, with a
121
+ kept round's `replay_token`, that round's judged answer round) or a
122
+ `replay_token` with `cognition: 'deterministicOnly'` (a zero-call replay of a
123
+ round the server kept), and refuses all three after `/health` alone on a
124
+ resident without the capability. The body carries `mode`, `cognition`, the
125
+ input (`intent` and `workflow_id`, or `source`, `change` and
126
+ `original_intent`), `answers`, `limits` (`explicitProvider` only) and
127
+ `replay_token`.
128
+
129
+ The answer is `compile_version: 2` exactly when a provider call happened, with
130
+ its receipt in `provenance.authoring`; a replay and a round that needed no call
131
+ answer generation 1. A fresh round whose native plan the server keeps answers
132
+ the `Nika-Compile-Replay` header, surfaced as `outcome.replay_token` (64
133
+ lowercase hex digits, never quoted in an error); a header on any other answer
134
+ is a `NikaProtocolError`. Every 200 answer to a generation-2 request carries
135
+ `Cache-Control: no-store`; the SDK caches nothing either. A replay binds its
136
+ answers with zero calls but asks no verifier, so a model-authored candidate
137
+ stays `incomplete`. The judged answer round replays the kept plan with the
138
+ answers and asks the seat only to judge it (judge calls, generation 2, no
139
+ authoring call): `ready`, or held with its token forgotten (a later request
140
+ with it answers 409 `compile_replay_unavailable`). A server that serves it
141
+ lists `compileJudgedAnswerRound` in `/health` (engine 0.123.0 does whenever
142
+ its operator seats a model with `--authoring-model`); the SDK posts the round
143
+ only there, refuses it elsewhere after `/health` alone with a
144
+ `NikaCompatibilityError` (`compileJudgedAnswerRound`), and sets
145
+ `outcome.judged_answer_round_available` beside every kept round. An older
146
+ server's `422 malformed_compile_request` to the round maps to the same error,
147
+ as a defensive path.
148
+ The server sets no default deadline on a provider round: the client waits for
149
+ `limits.deadline_ms` plus the server's 5 s handoff and one `requestTimeout`,
150
+ or, without that limit, sets none unless `timeoutMs` is given. A
151
+ generation-2 answer is read up to 8 MiB. Refusals add 409 (`compile_replay_unavailable`, `compile_replay_input_changed`,
152
+ `compile_context_changed`), 408 `compile_deadline_exceeded`, 422
153
+ `compile_new_intent_required`, 500 `compile_disclosure_refused` and 503
154
+ `compile_replay_capacity` or `stopping`.
155
+
156
+ This contract is ahead of the pinned `openapi.json`, which describes the
157
+ default document of a resident from engine 0.123 on: the default document
158
+ never carries it, and a seated resident merges it into its live document. Its types
159
+ are written by hand from the engine source at tag `v0.123.0`
160
+ (`crates/nika-serve/src/server/compile/v2.rs`, `author.rs`,
161
+ `openapi-native.json`). This package speaks only to an engine on machine
162
+ protocol 2 (0.123 or later), which serves it when seated. See
163
+ [compile.md](compile.md).
164
+
165
+ ## Trace verification
166
+
167
+ `traceVerify(receipt)` over HTTP needs the receipt's `job_id` and asks
168
+ `GET /v1/jobs/{id}/trace/verify`. The answer (`TraceVerification`, closed)
169
+ carries the server's `verdict` and `reason`, both required by the pinned
170
+ contract, beside the CLI's own document (`exit`, `chain`, `seal`, `anchor`,
171
+ `replay`, `lines`) and never a filesystem path. The verdict is the CLI's
172
+ headline word for the journal the server wrote for the job: `ok`, `sealed`,
173
+ `anchored` and `replayed` hold; `incomplete` (no terminal frame, the writer's
174
+ liveness in `reason`), `tampered` (a buried seal) and `broken` (an edited
175
+ chain) do not; `unchained`, `empty`, `unreadable`, `refused`, `line-over-long`
176
+ and `unknown` are the CLI's refusal classes; `unavailable` means no journal
177
+ exists for the job (refused before its first event, queued, or a backend
178
+ keeping none). Beside a verdict that holds, `reason` is the seal tier:
179
+ `sealed` or `unsealed`.
180
+
181
+ The SDK sets `verified: true` only when the verdict holds (compared without
182
+ case) **and** the answer's `trace_id` equals the receipt's. The verdict
183
+ describes the job's journal, not the receipt: a receipt whose `trace_id` does
184
+ not match keeps the server's `sealed` and reads `verified: false`. Measured on
185
+ engine 0.123.0: a server with a signing key answers `sealed`/`sealed`, one
186
+ without answers `ok`/`unsealed`, and both read `verified: true` for the
187
+ matching receipt.
188
+
189
+ ## Artifacts
190
+
191
+ `run.artifacts()`, `run.downloadArtifact()` and `run.readArtifact()` need a
192
+ server whose `/health` lists `artifacts` (engine 0.123.2 added the routes;
193
+ 0.123.1 and older do not list them). Without it, and on the native transport,
194
+ they reject with `NikaCompatibilityError` (`capability: 'artifacts'`) before
195
+ any request.
196
+
197
+ **The manifest** (`ArtifactManifest`) is read like any JSON answer: bearer
198
+ token, `requestTimeout`, `machineBufferBytes`. The SDK checks each field the
199
+ contract names by type and lets any other key ride through, so a later
200
+ additive key is not a refusal: `receipt` (the closed `JobReceipt`, its
201
+ `job_id` the run's, with a `chain_head`), `verdict` (the journal tier,
202
+ `sealed` or `anchored`; any other word is refused), `max_artifact_bytes`,
203
+ `truncated` and `artifacts`. Each entry has a unique `name`, a `kind`, a
204
+ `size` that is a byte count, a `sha256` of 64 lowercase hexadecimal digits,
205
+ a `mime`, an optional `task` and an `event_id`; a `file` carries its `path`,
206
+ an `agent_image` none. Names are unique, digests need not be: from engine
207
+ 0.124 the file an `agent:` task saved with `images: { save: }` is listed as a
208
+ `file` beside the `agent_image` it was written from, both from one journal
209
+ event, with one size and digest. A `path` must be contained (relative,
210
+ `/`-separated, no empty, `.` or `..` segment, no backslash, no NUL). That
211
+ check is lexical and POSIX, the server's own: it does not make a path safe to join under a
212
+ local directory on every system (`C:x` is drive-relative on Windows, and two
213
+ paths that differ only by case collide on a case-insensitive disk). To write
214
+ an artifact locally, resolve the joined path, check that it stays under your
215
+ directory, and open it exclusively (`wx`). Any other shape is a
216
+ `NikaProtocolError` that quotes no value. The receipt must equal the job's own, compared key by key: the one
217
+ the handle settled with, or, when the handle has not seen the settlement, the
218
+ one `GET /v1/jobs/{id}` returns.
219
+
220
+ **A download** sends the name as one path segment, `encodeURIComponent(name)`
221
+ (its `/` become `%2F`, which the server decodes once and matches exactly),
222
+ with `Accept-Encoding: identity`. A name the manifest lists is held to its
223
+ entry: the 200 must carry `Content-Length` equal to `size`,
224
+ `Nika-Artifact-Sha256` equal to `sha256`, and no `Content-Encoding`. Any
225
+ other 200 is a `NikaProtocolError` before a byte is read. A name the complete
226
+ manifest does not list is still sent, so the server answers its own 404
227
+ `artifact_not_found`; a 200 for it is a protocol fault. Past a truncated
228
+ manifest's 1,024 entries a name is held to the response's two headers alone,
229
+ and `download.artifact` is absent.
230
+
231
+ The request goes through the client's unbounded fetch, as a provider compile
232
+ round does: no `requestTimeout` on its headers (the server hashes the whole
233
+ file against its record before it answers) or its body, which the server
234
+ streams outside its own request deadline, and no `machineBufferBytes`. Only
235
+ the caller's `signal`, or cancelling the stream, ends it. With an injected
236
+ `fetch`, that fetch's own timeouts apply.
237
+
238
+ The stream hashes every chunk as it arrives and never passes the recorded
239
+ size. It holds its last chunk back and closes only once exactly `size` bytes
240
+ hashed to `sha256`; bytes that are not the recorded ones fail it with a
241
+ `NikaProtocolError`. A body that ends before its `Content-Length`, or resets
242
+ before its end, is requested again, up to 3 more times, after 100, 200 and
243
+ 400 ms: the server has no range requests, so the whole artifact comes again,
244
+ its headers are held to the same size and digest, and its first bytes must
245
+ hash as the bytes already received. A retry the transport cannot deliver (no
246
+ connection, or one dropped before its headers) counts as one more incomplete
247
+ attempt. A refusal on a retry fails the stream with that `NikaOperationError`
248
+ (409 `artifact_changed` for a file that changed); a download still incomplete
249
+ after the last attempt fails with a `NikaTransportError`, and an abort with a
250
+ `NikaTransportError` naming the method. A body whose bytes all arrived but
251
+ whose end was lost is judged by its digest, without a retry.
252
+
253
+ `readArtifact()` reads the same stream into one `Uint8Array` and resolves
254
+ only once it closed. It refuses an artifact larger than `maxBytes` (16 MiB by
255
+ default) with `NikaConfigurationError`: before any download for a listed
256
+ one, from its `Content-Length` for one past a truncated manifest.
257
+
258
+ | Route | HTTP status · `error.code` |
259
+ |---|---|
260
+ | both | 401 `unauthorized` · 404 `job_not_found` · 409 `job_not_settled`, `artifact_journal_unavailable`, `artifact_journal_unverified` · 500 `internal_error` · 503 `store_busy`, `artifact_capacity` |
261
+ | the manifest only | 408 `request_timeout` |
262
+ | a download only | 403 `artifact_too_large` · 404 `artifact_not_found` · 409 `artifact_changed` |
263
+
264
+ Each is a `NikaOperationError` whose `operation` is the method called
265
+ (`artifacts`, `downloadArtifact` or `readArtifact`), with the server's code on
266
+ `code` and `machineCode` and the HTTP `status`. The SDK retries none of them:
267
+ a 503 says to retry with backoff. A server without a run key lists
268
+ `artifacts` but answers every request 409 `artifact_journal_unverified`,
269
+ since its journals are unsealed (see
270
+ [server.md](server.md#download-what-a-job-produced-artifacts)).
271
+
272
+ ## Settlement
273
+
274
+ The terminal `execution.settled` frame and the durable job nest the run's
275
+ `settlement` whole (engine 0.118, ADR-128): its `status` and `cause`, the
276
+ elapsed time, the task tally, the spend with its qualifier, and the failure
277
+ named with its task. The SDK types every known field, refuses a settlement
278
+ whose `status` contradicts the record carrying it, keeps fields it does not
279
+ know, and never derives a settlement from an exit code; a job the resident
280
+ lost (`interrupted`) carries none.
281
+
282
+ From engine 0.124.4 a server started with `nika serve --cost-policy` (health
283
+ capability `costStandingPolicyV1`) adds one field to the settlement of a job
284
+ that policy admitted, on the terminal frame and on the durable job:
285
+ `cost_admission`, the closed `nika/cost-admission@1` object that server's
286
+ own `GET /v1/openapi.json` describes (`authority: 'standing_policy'`, a
287
+ `price` of `unknown` or `host_declared`, the bounded `choice` with the rule
288
+ under `choice.standing`, and the `host` cap evidence). The pinned
289
+ `openapi.json` is the default document and does not declare it. The SDK
290
+ keeps the field as read, untyped, and validates none of it; beside the
291
+ settlement, as a key of the frame or of the job, it is still refused.
292
+
293
+ ## Frame time and journal evidence (engine 0.123)
294
+
295
+ Both resident projections are closed, and the SDK refuses any field it does
296
+ not know. Engine 0.123 adds two optional resident fields,
297
+ declared in the pinned `openapi.json`: a 0.123.0 resident writes `at` on
298
+ every frame, and `evidence` only when it reports a journal loss.
299
+
300
+ - `JobEvent.at` is when the resident admitted the event: an RFC 3339 timestamp
301
+ in UTC, outside the event's hash chain. It rides `event.raw.at` untouched.
302
+ Anything that is not such a timestamp is a `NikaProtocolError`. The durable
303
+ `Job` declares no `at`, so one there is still an unknown field.
304
+ - `evidence`, on the terminal frame and on the durable `Job`, reports that the
305
+ run's journal mirror stopped recording. It is exactly a `status` and a
306
+ `reason`. The one status is `mirror_lost`. The reason is `write_failed`
307
+ (opening, writing or syncing the journal failed) or `record_refused` (a
308
+ record could not be admitted within the writer's bounds): a coarse class,
309
+ never OS text and never a path. Any other shape or word is a
310
+ `NikaProtocolError`, as the engine itself refuses one, and its value is
311
+ never quoted in the error.
312
+
313
+ `evidence` is independent of the execution and is never a verdict: a run can
314
+ settle `succeeded` while its mirror is lost. It never changes `result.status`,
315
+ the settlement, or the receipt's identity checks. `run.result()` copies it to
316
+ `result.evidence` from the frame or record that settled the run, so a caller
317
+ who never iterates events still learns the trace may be incomplete before
318
+ trusting `traceVerify`. Its absence claims nothing: not that a journal exists,
319
+ only that no loss was reported. A native run never carries it.
320
+
321
+ ## Lifecycle vocabulary over the resident's frames
322
+
323
+ `run.events()` names the resident's closed `JobEvent` frames in the SDK's
324
+ lifecycle vocabulary and keeps each frame on `event.raw`:
325
+
326
+ | `JobEvent.kind` | `JobEvent.status` | `event.kind` |
327
+ |---|---|---|
328
+ | `execution.started` | any | `run.started` |
329
+ | `execution.settled` | `paused` | `run.waiting` |
330
+ | `execution.settled` | `succeeded` · `failed` · `cancelled` | `run.settled` |
331
+ | `execution.cancelled` | `cancelled` only | `run.settled` |
332
+ | `execution.refused` | `failed` only | `run.settled` |
333
+ | `execution.interrupted` · `interrupted` | `interrupted` | `run.interrupted` |
334
+ | anything else: a `null` or future kind; an end kind whose status is absent, `null`, future, `queued` or `running`; or a pair that contradicts itself (`execution.refused` carrying `succeeded` or `cancelled`, `execution.cancelled` carrying `succeeded` or `failed`, an end kind carrying `interrupted`) | | `engine.event` |
335
+
336
+ The pairs above are exhaustive and listed, never computed as a product of
337
+ kinds and words. An unnamed frame is still delivered with `event.raw` intact,
338
+ and `run.result()` still reads the state word the engine wrote on it. One
339
+ such frame is common: a job admitted with a non-empty `inputs` map opens its
340
+ stream with `execution.queued` (status `queued`, sequence 1), so it streams
341
+ three frames where a job without inputs streams two (engine 0.123.1).
342
+
343
+ The resident streams no per-task frame, so an HTTP run yields no `task.*`
344
+ event: the SDK never synthesizes one. `event.sequence` is the validated SSE
345
+ id, the cursor to persist. The engine's `interrupted` (execution ownership
346
+ was lost, settlement unknown) is data: a `run.interrupted` event and
347
+ `result.status`. It is unrelated to `NikaObservationInterrupted` below, which
348
+ is this client losing its view of a run that may still be running.
349
+
350
+ ## SSE recovery
351
+
352
+ The client checks that SSE ids are canonical positive integers and equal
353
+ `data.sequence`. An identical duplicate is ignored. A conflicting duplicate,
354
+ gap, or out-of-order frame is a protocol failure. After a reset the client
355
+ asks durable job state before reconnecting with `Last-Event-ID`; retry delays
356
+ and attempts are bounded.
357
+
358
+ A replacement Node process can call `attachRun(jobId, { lastEventId })`. The
359
+ SDK proves that the durable job exists before returning an owned run handle,
360
+ then sends the cursor as `Last-Event-ID`. Persist the job id and last event
361
+ sequence in the same application transaction that records each consumed event.
362
+ A cursor means “fully processed”, not merely “received”.
363
+
364
+ ## Idempotency and schedules
365
+
366
+ HTTP `run()` requires a caller-owned `idempotencyKey` of 1–255 bytes. Omitting
367
+ it throws `NikaConfigurationError` before network I/O or local snapshot capture.
368
+ Persist the key before admission and retry the exact request with the same key
369
+ if the response is lost or times out. The SDK never generates a hidden key or
370
+ retries admission automatically. Reusing a key with different request bytes
371
+ is an engine conflict, not a retry success: the `access` pin and the `inputs`
372
+ map are part of those bytes, so another pin under the same key answers 409
373
+ `idempotency_conflict`. A request without a pin keeps the exact bytes earlier
374
+ releases sent. Direct native runs still omit the key and reject it if
375
+ supplied.
376
+
377
+ The namespace is the whole durable job store under the server's configured
378
+ `state-root`, across workflows, clients, schedules, and server restarts. The
379
+ current engine has no time-based eviction: keys remain bound while that state
380
+ root exists and still count toward its configured job capacity. Use globally
381
+ unique, business-stable keys; do not recycle daily counters or workflow-local
382
+ names.
383
+
384
+ Schedules use compare-and-swap semantics. Create omits `revision`; update must
385
+ carry the exact previous `sha256:...` revision. The SDK never fabricates or
386
+ normalizes schedule facts.
387
+
388
+ A scheduled job's `receipt.origin` is closed: the firing's `kind`,
389
+ `schedule_origin`, `schedule_id`, `schedule_revision`, `slot_id`, `decision`,
390
+ `scheduled_for`, `fired_at` and `arm_generation`, and, from engine 0.123
391
+ (machine protocol 2), the silence a `catch-up-once` firing answers for:
392
+ `missed_first` (its first missed slot) and `missed_count` (how many slots it
393
+ holds), `scheduled_for` being its last. The SDK reads them as the resident
394
+ writes them: both or neither, on a `catch_up` decision only, at least one
395
+ slot, the first never after `scheduled_for`. Any other member or combination
396
+ is a `NikaProtocolError`.