@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.
@@ -0,0 +1,486 @@
1
+ # Compile: from an intention to a checked workflow
2
+
3
+ `nika.compile(request)` asks the engine for a candidate workflow and runs
4
+ nothing. The outcome is data: `ready`, `incomplete` and `refused` all resolve,
5
+ and only transport, protocol, compatibility and engine-stamped failures throw.
6
+ A ready candidate is ordinary `.nika` source; you write it to a file and
7
+ `run(path)` admits it again, exactly like any other workflow.
8
+
9
+ ```text
10
+ compile(request) ──▶ outcome
11
+ ready ──────▶ write outcome.candidate ──▶ run(path) Check admits it again
12
+ incomplete ─▶ outcome.questions ──▶ nextCompileRequest(request, outcome, answers)
13
+ └──▶ compile(next request) ... (bounded: stop
14
+ when a round brings no new answer)
15
+ refused ────▶ outcome.diagnostics stop
16
+ ```
17
+
18
+ The SDK holds no compiler. Both doors print the engine's one machine document
19
+ (`nika-compile/src/wire.rs::outcome_document`); the SDK validates it, keeps the
20
+ engine's fields verbatim and adds only `ready`, the replay token of a kept
21
+ round (HTTP) and the CLI's own facts (local engine).
22
+
23
+ ## Start here: no model, no key
24
+
25
+ Without a provider, compile resolves the exact skeleton names
26
+ `nika compile --list` shows (`hello` and `classify-and-route` among them) and
27
+ edits the constants of an existing workflow; other free text comes back
28
+ `incomplete` with its questions.
29
+
30
+ ```ts
31
+ import { Nika } from '@nika-open/nika';
32
+
33
+ const nika = new Nika();
34
+ const candidate = await nika.compile({
35
+ intent: 'classify-and-route',
36
+ answers: { 'const.request': 'An outage affects support customers.' },
37
+ }, { timeoutMs: 15_000 });
38
+
39
+ // Every outcome is data: ready, incomplete and refused alike.
40
+ console.log(candidate.status, candidate.questions, candidate.diagnostics);
41
+ if (candidate.ready && candidate.candidate !== null) {
42
+ const edited = await nika.compile({
43
+ workflow: candidate.candidate,
44
+ change: { set_constant: { name: 'request', value: 'One customer is affected.' } },
45
+ });
46
+ console.log(edited.candidate);
47
+ }
48
+ ```
49
+
50
+ Measured on engine 0.123.0: the first call is `ready` at `compile_version` 1
51
+ with an `applied` diagnostic on `const.request`, and the edit is `ready` with
52
+ the new constant. An edit also accepts text, such as
53
+ `Set const.request to "One customer"`. A free intent such as
54
+ `'Every Monday at 9am summarize the support queue into ./digest.md'` comes
55
+ back `incomplete`, asking `model` (text), `trigger.timezone` (text),
56
+ `trigger.missed` and `trigger.overlap` (choices) and `trigger.ceiling`
57
+ (literal). The candidate is `.nika` source, never a run: write it to a file,
58
+ then `run(path)` admits it again like any other workflow.
59
+
60
+ **Watch a free intent become a ready candidate in two rounds, with no model call.**
61
+
62
+ <p align="center">
63
+ <picture>
64
+ <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-compile.png">
65
+ <img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/gifs/sdk-compile.gif" alt="node author.mts with the intent Every morning, summarize ./inbox/*.md into ./digest.md prints round 1 incomplete · 1 required, 4 optional question(s), the required question model, and every morning is a trigger, not a task; answer model = mock/echo; round 2 ready · provider calls: none; trigger schedule · daily · requires_binding; check clean · exit 0 · kept as digest.nika. Then the candidate's permits: read ./inbox/**, write ./digest.md, five nika: tools; then nika check plans it in 9 waves from glob_source to write_output" width="860">
66
+ </picture>
67
+ </p>
68
+ <p align="center"><sub>No provider is seated, so no model is called. Round 1 is <code>incomplete</code>: one required question, the runtime <code>model</code>, four optional ones, and <code>every morning</code> recorded as a trigger, not a task. Answering <code>model = mock/echo</code> through <code>nextCompileRequest()</code> makes round 2 <code>ready</code>; the schedule still <code>requires_binding</code>. The candidate asks to read <code>./inbox/**</code>, write <code>./digest.md</code> and call five <code>nika:</code> tools, and <code>nika check</code> plans it in 9 waves; nothing runs. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine.<br>▶ <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-compile.mp4?raw=true">MP4</a> · <a href="https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-compile.txt">transcript</a> · <a href="https://github.com/nika-open/nika-client/blob/main/scripts/media/scenes/sdk-compile/author.mts">the program</a></sub></p>
69
+
70
+ ## Two doors
71
+
72
+ | | `new Nika({ url, token })` | `new Nika()` (local engine) |
73
+ |---|---|---|
74
+ | Route | `POST /v1/compile` of `nika serve --bind` | `nika compile --json` |
75
+ | Deterministic compile | `compile` capability in `/health` | `compile` capability in `--sdk-identity` |
76
+ | Provider round | `cognition: 'explicitProvider'`; `/health` must advertise `compileNativeV2` | `authoringModel: 'provider/name'` |
77
+ | Who chooses the model | the server's operator (`nika serve --authoring-model`) | you, per request |
78
+ | Credentials | the server's environment | the local engine's environment |
79
+ | Answer round | the kept round's judged answer round by its `replay_token` (judge calls only) where `/health` lists `compileJudgedAnswerRound`, else a fresh round carrying the answers; or its zero-call replay | the engine replays the plan it recorded under `.nika/compile/` |
80
+ | The files the intent names | observed by the LOCAL engine in the client's `cwd` and sent as `observed_world` where `/health` lists `compileObservedWorld` (see below) | observed by the engine in its working directory |
81
+ | Who judges a candidate | the operator's decision model where `/health` lists `compileDecisionSeat` (`nika serve --decision-model`), else the authoring model | `decisionModel`, else the authoring model |
82
+
83
+ A door that lacks what a request needs refuses it with
84
+ `NikaCompatibilityError` before anything is posted or spawned, and the SDK
85
+ never compiles locally as a substitute for a server.
86
+
87
+ ## The files your intent names, over HTTP
88
+
89
+ A server never reads your files. So that its seat does not ask you for a
90
+ field name, a key or a shape it could have read, every generation-2 request
91
+ (a provider round, a judged answer round, a zero-call replay) asks the local
92
+ engine what it observes of the files the request states — `nika compile
93
+ --observe-only -- <intent>` (a text revision: its `original_intent` and its
94
+ change), run in the client's `cwd` — and sends that document unchanged as
95
+ `observed_world`. It holds what `nika compile` hands its own seat: a CSV's
96
+ header, a JSON file's keys and nested key paths, a column's short repeated
97
+ values (a status, a kind), counts of value kinds, the absent and
98
+ outside-the-project states — never a row. The server admits it only in that
99
+ shape, about paths the request states, at most 64 rows and 256 KiB
100
+ (`422 compile_observation_refused` otherwise); its seat, its grounding law
101
+ and its judge then read it.
102
+
103
+ | `observe` option | Behavior |
104
+ |---|---|
105
+ | absent (default) | sent when `/health` lists `compileObservedWorld`; nothing otherwise |
106
+ | `true` | required: a server without the capability is a `NikaCompatibilityError` (`capability: 'compileObservedWorld'`) before anything is posted |
107
+ | `false` | never observed, never sent |
108
+
109
+ Where `/health` also lists `compileTrialInputs` (a server that tries
110
+ candidates), the same request carries `trial_inputs`: the text of the files
111
+ the observation read (the engine offers them only when they are UTF-8 text
112
+ and at most 1 MiB in all). The server writes them into a scratch project of
113
+ its own and tries each final candidate there before it can be `ready`, in the
114
+ observed room `nika compile` and the Session use; the trial's report reaches
115
+ its judge and its repairs (`provenance.decision.rehearsal`). These bytes go
116
+ to the server that will run the workflow on the same files anyway; they are
117
+ never sent to a model nor echoed back. `observe: false` sends neither.
118
+
119
+ The observation is part of a kept round's input: its answer rounds observe
120
+ again, and a file that changed in between makes another input
121
+ (`409 compile_replay_input_changed`): author again. A local engine that cannot
122
+ print the document (one from before the flag) fails typed with
123
+ `capability: 'compileObservedWorld'` and nothing is posted; pass
124
+ `{ observe: false }` to compile without it. A local compile ignores the
125
+ option: the engine always observes its own working directory.
126
+
127
+ ## What is a provider call, and what is not
128
+
129
+ - Without an opt-in, compile is deterministic. It contacts no provider, even
130
+ when a key sits in the environment: an ambient key is never consent.
131
+ - HTTP `cognition: 'explicitProvider'` opts one fresh round into the server's
132
+ seated model. It may spend. Its `limits` may only narrow the operator's
133
+ bounds; above them the server answers `422 compile_limit`, never a clamp.
134
+ - A local `authoringModel` seats that model for this request. A local
135
+ `decisionModel` seats a bounded-decision capability for finite ambiguities;
136
+ its choices are recorded in `provenance.decision` and its cognition reads
137
+ `explicitDecision`.
138
+ - An outcome is `compile_version: 2` exactly when a provider call happened;
139
+ `provenance.authoring` is then the receipt (model, logical `calls`, token
140
+ counters, `backend.authority`). Token usage is not an invoice.
141
+ - A judged answer round (`explicitProvider` with a kept round's
142
+ `replay_token`) replays the kept plan with your answers and asks the seat
143
+ only to judge it: judge calls, `compile_version` 2, never a second authoring
144
+ call. It still may spend, on the judge.
145
+ - A zero-call replay (`deterministicOnly` with a `replay_token`) makes no call
146
+ and answers generation 1; it asks no verifier either. A local answer round
147
+ replays the recorded plan with no authoring call; a verifier that round asks
148
+ makes its own calls.
149
+ - Compile creates no run, job, approval, trace, schedule or permission. The
150
+ SDK reads no credential and sends none.
151
+
152
+ ## The request
153
+
154
+ ```ts
155
+ // HTTP: one provider round under the server's seat, narrowed by limits.
156
+ const first = await nika.compile({
157
+ intent: 'Every morning at 9, summarize ./inbox/*.md into ./digest.md',
158
+ cognition: 'explicitProvider',
159
+ limits: { max_calls: 6, deadline_ms: 120_000 },
160
+ });
161
+
162
+ // Local engine: the model you seat, its key read by the engine.
163
+ const local = await new Nika().compile({
164
+ intent: 'Every morning at 9, summarize ./inbox/*.md into ./digest.md',
165
+ authoringModel: 'mistral/mistral-small-latest',
166
+ limits: { max_calls: 6 },
167
+ });
168
+ ```
169
+
170
+ Fields that exist on the HTTP wire keep their wire spelling; fields that only
171
+ a local engine has are named after the flag they become.
172
+
173
+ | SDK field | HTTP body | Local engine argv |
174
+ |---|---|---|
175
+ | `intent` | `mode: "create"`, `intent` | the positional after `--` |
176
+ | `workflow` + `change` | `mode: "edit"`, `source`, `change: {text}` or `{set_constant}` | `--base <scratch file>` and `--change=<text>`; a `set_constant` becomes `Set const.NAME to JSON` |
177
+ | `original_intent` (edit) | `original_intent` | the positional beside `--base` |
178
+ | `workflow_id` (create) | `workflow_id` | refused: the `output` file name names the workflow |
179
+ | `answers` | `answers`, each a JSON value | `--answer=KEY=JSON`, once per key |
180
+ | `cognition` | `cognition` | refused |
181
+ | `limits.max_calls` | `limits.max_calls` | `--authoring-max-calls` |
182
+ | `limits.repairs` | `limits.repairs` | `--authoring-repairs` |
183
+ | `limits.max_tokens` | `limits.max_tokens` | `--authoring-max-tokens` |
184
+ | `limits.call_timeout_ms` | `limits.call_timeout_ms` | `--authoring-timeout`, whole seconds only |
185
+ | `limits.deadline_ms` | `limits.deadline_ms` | refused: no flag; bound the child with `timeoutMs` |
186
+ | `replay_token` | `replay_token`: with `explicitProvider` the judged answer round, with `deterministicOnly` the zero-call replay | refused |
187
+ | `authoringModel` | refused | `--authoring-model` |
188
+ | `decisionModel` (create) | refused | `--decision-model` |
189
+ | `fresh` (create) | refused | `--fresh` |
190
+ | `output` | refused | `--output` |
191
+
192
+ Over HTTP the request picks the wire generation:
193
+
194
+ | Request | Body | `/health` must advertise |
195
+ |---|---|---|
196
+ | no `cognition` | `compile_version: 1` | `compile` |
197
+ | `cognition: 'deterministicOnly'`, no token | `compile_version: 1` with that cognition | `compile` |
198
+ | `cognition: 'explicitProvider'` | `compile_version: 2`, a fresh round | `compileNativeV2` |
199
+ | `cognition: 'explicitProvider'` and `replay_token` | `compile_version: 2`, the kept round's judged answer round | `compileNativeV2` and `compileJudgedAnswerRound` |
200
+ | `cognition: 'deterministicOnly'` and `replay_token` | `compile_version: 2`, the kept round's zero-call replay | `compileNativeV2` |
201
+
202
+ The SDK refuses with `NikaConfigurationError`, before any request or process,
203
+ what the published wire refuses by shape: an unknown field; `intent` mixed
204
+ with `workflow`/`change`; a `replay_token` without a cognition or that is not
205
+ 64 lowercase hex digits; `limits` without a provider opt-in or beside
206
+ `deterministicOnly`; a limit that is not an integer within its published range
207
+ (`max_calls` and `max_tokens` 1–4294967295, `repairs` 0–4294967295, the two
208
+ durations from 1 ms); `original_intent` beside `set_constant`; a create-only
209
+ field on an edit. Over HTTP it also refuses `original_intent` on generation 1
210
+ and a generation-2 text change without `original_intent`. A field the chosen
211
+ door does not have is a `NikaCompatibilityError` with `capability:
212
+ 'compileOptions'`. Answers and constant values are strict JSON, judged without
213
+ running caller code; a key cannot be empty or contain `=`.
214
+
215
+ Not exposed: `--authoring-samples`, `--authoring-strategy`,
216
+ `--authoring-reasoning`, `--knowledge`, `--knowledge-exclude`,
217
+ `--knowledge-pack`, `--no-knowledge`, `--hot-policy`, `--force`,
218
+ `--private-authoring-capture` and `--list`. A local engine still reads
219
+ `NIKA_AUTHORING_REASONING` and `NIKA_KNOWLEDGE*` from its own environment.
220
+
221
+ ## The outcome
222
+
223
+ | Field | Meaning |
224
+ |---|---|
225
+ | `compile_version` | `2` when a provider call happened, else `1` |
226
+ | `status`, `ready` | the engine's completeness word; `ready` is exactly `status === 'ready'` |
227
+ | `candidate` | `.nika` source. Proposed only when ready; under `incomplete` a non-null candidate is a preview |
228
+ | `questions[]` | `key`, `label`, `type` (`text`, `literal` or `choice` with `options[]`), `why`, `mandatory`. A `choice` (engine 0.123, machine protocol 2) carries at least one option and is answered with one option's `key`; no other question carries options. `mandatory: false` belongs to a binding outside the program (a schedule's timezone, missed-run and overlap policies, ceiling) and never blocks ready |
229
+ | `diagnostics[]` | `kind`, `target`, `message`. Compiler targets include `semantic_verification`, `verify_held` and `verify_resume` |
230
+ | `requested_boundary` | the permits the candidate requests; never a grant |
231
+ | `requested_trigger` | the trigger the request names (`kind`, `status`, `cadence`, `cron`…), a requirement you bind through the schedule contract; absent on engines before the field |
232
+ | `check_preview` | the source-only Check report; never admission |
233
+ | `provenance` | `compiler_version`, `spec_pin`, `skeleton`, `cognition`, and when present `strategy`, `suggested_file`, `plan`, `decision`, `authoring` |
234
+ | `replay_token` | HTTP only: the `Nika-Compile-Replay` header of a provider round whose plan the server keeps |
235
+ | `judged_answer_round_available` | HTTP only, beside a kept round: whether the server that answered lists `compileJudgedAnswerRound` in `/health`. An SDK fact, read by `nextCompileRequest()` |
236
+ | `written`, `existing_destination` | local engine only, when the request named `output` |
237
+ | `plan_record_error`, `declined_record_error` | local engine only: it could not keep or remove a record under `.nika/compile/` |
238
+
239
+ Showing or hiding any of these is your application's choice; the SDK imposes
240
+ no display or masking.
241
+
242
+ ## Answer rounds
243
+
244
+ `nextCompileRequest(request, outcome, answers, options?)` builds the next
245
+ request: the same input with these answers merged over the previous ones. It
246
+ maps; it judges nothing.
247
+
248
+ - **HTTP, a kept round: the judged answer round.** When a provider round
249
+ answered a `replay_token` and its server serves the judged answer round
250
+ (`outcome.judged_answer_round_available`, from the `/health` capability
251
+ `compileJudgedAnswerRound`), the next request is that round's judged answer
252
+ round: the exact input, the merged answers, `cognition: 'explicitProvider'`,
253
+ the token and the previous `limits` (which may narrow it). The server
254
+ replays the kept plan with the answers and asks its seat only to judge the
255
+ replayed bytes: judge calls, `compile_version` 2, never a second authoring
256
+ call. A candidate the seat accepts is `ready`. One it does not accept is
257
+ held (`verify_held`, `incomplete`, no new token) and the server forgets the
258
+ token: any later request with it answers `409 compile_replay_unavailable`.
259
+ If the judged round answers new questions instead, the next request answers
260
+ them by the same token (or by a newer one the round answered).
261
+ - **HTTP, a kept round on a server that does not judge.** Where the server
262
+ does not list `compileJudgedAnswerRound`, the next request is a new fresh
263
+ round carrying the answers (no token): the one round there that can judge
264
+ them. It authors again and may spend. `{ cognition: 'deterministicOnly' }`
265
+ asks for the zero-call replay instead; `{ cognition: 'explicitProvider' }`
266
+ asks for the judged round whatever the server advertised, and the client
267
+ then refuses it before posting.
268
+ - **HTTP, a kept round: the zero-call replay.** Pass `{ cognition:
269
+ 'deterministicOnly' }` for the replay that makes no call: the exact input,
270
+ the token, no `limits`. It binds the answers into the kept plan but asks no
271
+ judge, so a model-authored candidate comes back `incomplete`, a preview with
272
+ its judgment pending (`provenance.decision.pending`); replaying again
273
+ returns the same document. From a replay, the next request stays a replay
274
+ unless you pass `{ cognition: 'explicitProvider' }`.
275
+ - **Either way,** the server compares the input byte for byte
276
+ (`409 compile_replay_input_changed` otherwise). Tokens live in that server
277
+ run only: a restart forgets them (`409 compile_replay_unavailable`), an
278
+ operator may limit their count and lifetime, and a lost first answer leaves
279
+ no token. Keep a token as you keep the request; do not log it.
280
+ - **HTTP, without a token.** A held candidate, a cold plan round or a round
281
+ that needed no call keeps no plan. The next request is a new fresh round
282
+ and may spend again. The `cognition` option is refused there: there is no
283
+ kept round to answer.
284
+ - **Local engine.** The next request repeats the intent with every answer as
285
+ `--answer`. When a round carries at least one answer, the engine replays
286
+ the plan it recorded for that intent under `.nika/compile/` in its working
287
+ directory, with no authoring call, and the seat's verifier may decide it in
288
+ that round; keep the same `cwd` between rounds. `fresh` is dropped. A round
289
+ with no answer reads the intent again and may spend.
290
+ - **A held outcome has no next round.** `nextCompileRequest()` refuses it with
291
+ `NikaConfigurationError`: its token is forgotten and asking again would
292
+ author anew. Stop there, or send a new request yourself.
293
+ - **`intent.clarification`.** Its answer replaces the whole request. A server
294
+ refuses it as an answer (`422 compile_new_intent_required` on a fresh or
295
+ judged round, `409 compile_replay_input_changed` on a replay): start a new
296
+ create request with the replacement intent. A local engine consumes it as an
297
+ `--answer` only beside a seat.
298
+
299
+ A loop must be bounded: stop on a held or refused outcome, when a round brings
300
+ no new answer, and after a few rounds.
301
+
302
+ ```ts
303
+ let request: NikaCompileRequest = { intent, cognition: 'explicitProvider', limits: { max_calls: 8 } };
304
+ let outcome = await nika.compile(request);
305
+ for (let round = 0; !outcome.ready && round < 4; round += 1) {
306
+ if (isNikaCompileHeld(outcome) || outcome.status === 'refused') break;
307
+ const answers = await askYourUser(outcome.questions); // your application's choice
308
+ if (Object.keys(answers).length === 0) break;
309
+ // After a provider round that kept its plan: its judged answer round where the
310
+ // server serves it, else a fresh round carrying the answers.
311
+ request = nextCompileRequest(request, outcome, answers);
312
+ outcome = await nika.compile(request);
313
+ }
314
+ ```
315
+
316
+ ### Servers without the judged answer round
317
+
318
+ The judged answer round needs a server that serves it, which `/health` says
319
+ with the capability `compileJudgedAnswerRound`. Engine 0.123.0 lists it beside
320
+ `compileNativeV2` on every native server, that is whenever the operator seats
321
+ a model with `nika serve --authoring-model` (measured with `mock/echo`: the
322
+ seated `/health` lists `compileNativeV2`, `compileJudgedAnswerRound`,
323
+ `compileObservedWorld` and `compileTrialInputs`, the unseated one none of
324
+ them). The SDK gates the round the way it gates generation 2: on a
325
+ server without the capability it refuses a judged answer round with
326
+ `NikaCompatibilityError` (`capability: 'compileJudgedAnswerRound'`) after
327
+ `/health` alone, before anything is posted, and the kept round stays
328
+ untouched. Beside every kept round it also sets
329
+ `outcome.judged_answer_round_available`, so `nextCompileRequest()` chooses a
330
+ round the server serves.
331
+
332
+ A server from before the round (the released 0.121.0 and 0.122.0) parsed
333
+ `explicitProvider` with a `replay_token` as `422 malformed_compile_request`,
334
+ before any slot or call; this package refuses those servers at their identity
335
+ anyway, since they speak machine protocol 1. The SDK still reports that
336
+ refusal to a judged answer round as the same `NikaCompatibilityError`,
337
+ defensively, for a server replaced since this client read its `/health` (once
338
+ per client).
339
+
340
+ ## Held candidates
341
+
342
+ When the verifier answers on a candidate's bytes and does not accept them, the
343
+ engine marks the outcome with an `applied` diagnostic targeting `verify_held`
344
+ and leaves it `incomplete`. `candidate` then holds a preview to show at most:
345
+ never run it or save it as an accepted result. `isNikaCompileHeld(outcome)`
346
+ reads the marker. A server keeps no replay token for it, and a held judged
347
+ answer round forgets the token it answered (a later request with it answers
348
+ `409 compile_replay_unavailable`), so asking again is a fresh round. A `verify_resume` marker means no admitted judgment was made: the
349
+ candidate is withdrawn and the round's record kept.
350
+
351
+ The SDK refuses with `NikaProtocolError` an outcome that calls itself `ready`
352
+ while carrying either marker, so a held or withdrawn candidate never reads as
353
+ ready.
354
+
355
+ ## Errors
356
+
357
+ | Error | When |
358
+ |---|---|
359
+ | `NikaConfigurationError` | the request or options break a shape law (above); nothing was sent or spawned |
360
+ | `NikaCompatibilityError` | the door lacks `compile`, `compileNativeV2`, `compileJudgedAnswerRound`, a required `compileObservedWorld` or a field (`compileOptions`); the local engine could not observe the request's files; or the answer carries a wire generation this request cannot receive |
361
+ | `NikaProtocolError` | the answer breaks the contract: malformed JSON, a ready outcome without candidate or with a held marker, generation 2 without its receipt, a replay token where none can be, a destination the request never named |
362
+ | `NikaTransportError` | aborted, timed out, the engine could not be spawned or was killed |
363
+ | `NikaOperationError` | the engine refused: `code` is its machine code, `status` the HTTP status or the local exit code |
364
+
365
+ `POST /v1/compile` refusals, as `NikaOperationError.code`:
366
+
367
+ | Status | Codes |
368
+ |---|---|
369
+ | 401 | `unauthorized` |
370
+ | 408 | `request_timeout` (intake, generation 1, replays) · `compile_deadline_exceeded` (a fresh round's absolute deadline passed; a call in flight may still be billed) |
371
+ | 409 | `compile_replay_unavailable` (an unknown, expired or forgotten token: a held judged round forgets its own) · `compile_replay_input_changed` · `compile_context_changed` (the server's pinned knowledge snapshot moved; nothing was sent) |
372
+ | 413 | `body_too_large` |
373
+ | 415 | `unsupported_media_type` · `unsupported_content_encoding` |
374
+ | 422 | `malformed_compile_request` · `compile_version_unsupported` · `compile_mode_unsupported` · `compile_cognition_unsupported` · `compile_limit` · `compile_new_intent_required` · `compile_observation_refused` · `compile_trial_inputs_refused` |
375
+ | 500 | `internal_error` · `compile_disclosure_refused` (the answer would carry a withheld credential) |
376
+ | 503 | `compile_busy` · `compile_replay_capacity` · `stopping` |
377
+
378
+ Local engine refusals arrive with exit 2 (`destination_name`,
379
+ `invalid_answer`, `authoring_authority`) or exit 3 (`read_base`, `knowledge`,
380
+ `authoring_config`, `compile_error`, `destination`). An engine that does not
381
+ know a flag answers with its usage error and no machine document; the SDK
382
+ reports it as `NikaProtocolError` quoting that error. The type
383
+ `NikaCompileRefusalCode` lists these words without closing the vocabulary.
384
+
385
+ ## Time and cancellation
386
+
387
+ `signal` and `timeoutMs` stop this request or child only. Over HTTP:
388
+
389
+ - a generation-1 request or a replay keeps the client's `requestTimeout`
390
+ unless `timeoutMs` is set;
391
+ - a provider round (fresh or judged) with `limits.deadline_ms` waits for that
392
+ deadline, the server's 5 s handoff and one `requestTimeout` more, so the
393
+ server's own `408 compile_deadline_exceeded` arrives before the client stops
394
+ waiting;
395
+ - a provider round without `timeoutMs` or `limits.deadline_ms` gets no SDK
396
+ deadline. The server sets none either unless its operator configured one
397
+ (`nika serve --authoring-deadline`): the round runs until it settles.
398
+
399
+ Stopping your wait stops neither the server's round nor its spend, and loses
400
+ its answer and replay token. The server sends its headers only when the round
401
+ settles, and Node's built-in `fetch` stops waiting for response headers after
402
+ 300 seconds. So a provider round with no deadline is posted through
403
+ `node:http`/`node:https`, which set no header or body deadline: only your
404
+ `signal` or the server ends the wait. A `fetch` you pass in the configuration
405
+ is used for every request, this one included, with its own timeouts: give it
406
+ a dispatcher that allows the round's length, or set `limits.deadline_ms`. A
407
+ local compile has no deadline unless you set one; a stopped child receives
408
+ SIGTERM, then SIGKILL after two seconds.
409
+
410
+ Responses are bounded: 8 MiB for a local compile and for an HTTP
411
+ generation-2 request, whose answer carries the round's plan, decision records
412
+ and receipt. An HTTP generation-1 answer keeps the smaller of
413
+ `machineBufferBytes` (16 MiB by default, so 8 MiB applies) and 8 MiB.
414
+
415
+ ## Files a local compile touches
416
+
417
+ - **Reads** the files a free intent names under the working directory, as a
418
+ bounded observation of their keys and short repeated values, never their
419
+ rows. An edit's base travels through a 0600 scratch file in a 0700 temporary
420
+ directory, removed on every path.
421
+ - **Writes** the plan record `.nika/compile/<intent sha256>.plan.json` and the
422
+ verdicts `.nika/compile/<intent sha256>.declined.json` (the directory ignores
423
+ itself for Git), and with `output` the ready candidate. Nothing that is not
424
+ ready is ever written to `output`.
425
+ - An HTTP compile writes nothing, anywhere. Its generation-2 requests spawn
426
+ the local engine with `compile --observe-only` (read-only, same bounds as
427
+ above) unless `observe: false`.
428
+
429
+ ## Engine versions
430
+
431
+ By the engine source at its release tags: 0.120.3 speaks generation 1 only,
432
+ without `requested_trigger` or `choice` questions, and its CLI has none of the
433
+ seat flags. 0.121.0 adds the seat flags, `requested_trigger`, `choice`
434
+ questions and Serve generation 2, without `limits.max_calls`, while still
435
+ announcing machine protocol 1. 0.122.0 adds `limits.max_calls` and
436
+ `--authoring-max-calls`. 0.123.0 announces machine protocol 2 and adds the
437
+ judged answer round with its capability, `nika compile --observe-only`,
438
+ `observed_world` with its `compileObservedWorld` capability, `trial_inputs`
439
+ with `compileTrialInputs`, and `nika serve --decision-model` with
440
+ `compileDecisionSeat`. 0.123.1 is a maintenance release: the same machine
441
+ protocol, and a default served document that differs from 0.123.0's only by
442
+ its version. 0.123.2 keeps machine protocol 2; its served document adds the
443
+ two artifact routes and declares answers 0.123.1 already sent, and its compile
444
+ door is unchanged. 0.124.0 keeps machine protocol 2 and the compile door of
445
+ 0.123.2: its compile code is unchanged, and its served document differs from
446
+ 0.123.2's only by its version and the artifacts route's description. 0.124.1
447
+ is a maintenance release of that line: the same machine protocol and compile
448
+ code, and a served document that differs from 0.124.0's only by its version.
449
+ 0.124.2 keeps both again, and its served document differs from 0.124.1's
450
+ only by its version: the service tier it adds is a field of the workflow
451
+ file, never of a request, and its health answer lists one more capability,
452
+ `accessServiceTier`. 0.124.3 keeps the machine protocol and the compile code
453
+ once more. Its served document adds one route,
454
+ `GET /v1/access-offers/{name}`, with the schemas of its answer, and its
455
+ health answer lists `accessSessionOffer`. 0.124.4 keeps both again, and its
456
+ default served document differs from 0.124.3's only by its version: the
457
+ standing cost policy it adds is a flag the operator gives at startup
458
+ (`nika serve --cost-policy`), never a field of a request. Only a server
459
+ started with that flag lists one more capability, `costStandingPolicyV1`,
460
+ and describes the `cost_admission` of a job's settlement in the document it
461
+ serves. 0.124.5, the engine this package version bundles, is the first
462
+ release published from `nika-open/nika` and keeps both once more: its
463
+ default served document differs from 0.124.4's only by its version, and its
464
+ health answer lists the same capabilities. This package refuses an engine
465
+ on protocol 1 at its identity. An engine without a flag answers with a usage
466
+ error; a server without a field answers `422 malformed_compile_request`.
467
+ Point `NIKA_BIN` (or `bin`) at the engine you mean to use.
468
+
469
+ The pinned `openapi.json` and `src/generated/openapi.d.ts` are the default
470
+ document of the released engine 0.124.5 resident, regenerated from the
471
+ released `nika serve`. The generation-2 types are written by hand from the
472
+ engine source at tag `v0.123.0`: `crates/nika-serve/src/server/compile/v2.rs`,
473
+ `author.rs` and `openapi-native.json` (the rounds, the judged answer round
474
+ included), `crates/nika-serve/src/server/model.rs` (its capabilities),
475
+ `crates/nika-compile/src/wire.rs` and `crates/nika-cli-host/src/compile.rs`
476
+ with `compile/render.rs`.
477
+
478
+ ## Example
479
+
480
+ [`examples/compile-then-run.ts`](https://github.com/nika-open/nika-client/blob/main/examples/compile-then-run.ts)
481
+ compiles an intention, answers its questions from a JSON file (over HTTP by
482
+ the judged answer round), writes the ready candidate and runs it through
483
+ `run()`, on either door. It reads the server URL and token or the engine
484
+ binary from the environment and embeds no key. On engine 0.123.0 without a
485
+ seat, `classify-and-route` asks `const.request`, the file answers it, the
486
+ next round is `ready`, and the run settles `succeeded`.