@nika-open/nika 0.0.0-bootstrap.0 → 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,164 @@
1
+ # Migrating to 0.116
2
+
3
+ > This guide is history: it maps the 0.115 clients onto the one `Nika` class
4
+ > that 0.116 introduced. Moving from 0.120.x to the current 0.124.5 is
5
+ > [upgrading-to-0.123.md](upgrading-to-0.123.md).
6
+
7
+ Version 0.116 is an intentional breaking consolidation of the two published
8
+ 0.115 clients into one `Nika` facade. This is a 0.x minor release, but existing
9
+ 0.115 imports and method calls do not all remain source-compatible. Migrate in
10
+ a branch and run the packed-package gauntlets before upgrading production.
11
+
12
+ ## Removed 0.115 surfaces
13
+
14
+ - The `@supernovae-st/nika-client/local` export and `LocalNika` class are
15
+ removed. Use `new Nika({ bin, cwd })`; call `check()`, `run()`, `events()`,
16
+ and `traceVerify()` on that instance.
17
+ - The root `nika.jobs` and `nika.workflows` namespaces are removed. Use the
18
+ facade methods shown below.
19
+ - `Nika.fromEnv()`, `nika.health()`, `Nika.verifyWebhook()`, and the exported
20
+ webhook helper are removed. Construct the client explicitly; health is now
21
+ an internal compatibility preflight. Keep webhook verification in the
22
+ application boundary that owns its signing format.
23
+ - Preview artifact, workflow-source/reload, and `runAndCollect` helpers are
24
+ removed instead of continuing as methods that always refuse.
25
+ - Node 18 and 20 are no longer supported; the package now requires Node 22 or
26
+ newer.
27
+
28
+ ## Constructor migration
29
+
30
+ The 0.115 root constructor was HTTP-only. In 0.116, no URL means the native
31
+ process transport; supplying `url` and `token` selects HTTP. Remote `check()`
32
+ and `run()` also need a local Nika binary (`bin`, `NIKA_BIN`, or the exact
33
+ optional host payload package) because
34
+ the SDK captures and validates immutable snapshot bytes before admission.
35
+ The current by-name HTTP path also accepts contained workflow names without a
36
+ local engine; prefix a local file with `./` to retain snapshot capture.
37
+
38
+ ```ts
39
+ // 0.115
40
+ const oldClient = new Nika({ url, token, timeout: 30_000 });
41
+
42
+ // 0.116
43
+ const nika = new Nika({
44
+ url,
45
+ token,
46
+ bin: process.env.NIKA_BIN,
47
+ requestTimeout: 30_000,
48
+ allowInsecureHttp: url.startsWith('http://127.0.0.1'),
49
+ });
50
+ ```
51
+
52
+ `timeout`, retries, polling, concurrency, logger, and per-run `signal` options
53
+ from the old HTTP client are gone. Request and frame bounds are client
54
+ invariants; observe or cancel a returned run through its owned lifecycle.
55
+
56
+ ## Method mapping
57
+
58
+ | 0.115 | 0.116 |
59
+ | --- | --- |
60
+ | `local.check(file)` | `nika.check(file)` |
61
+ | `local.run(file)` | `await nika.run(file)`, then `nika.events(run)` and `run.done` |
62
+ | `local.runToEnd(file)` | `const run = await nika.run(file); await run.done` |
63
+ | `local.traceVerify(path)` | No path-based replacement; retain the engine-issued receipt and call `nika.traceVerify(receipt)` |
64
+ | `nika.jobs.submit(workflow)` | `nika.run(workflow)` |
65
+ | `nika.jobs.status(id)` | retain the owned run; `nika.status(run)` |
66
+ | `nika.jobs.stream(id)` | `attachRun(id)`, then `events(run)` |
67
+ | `nika.jobs.cancel(id)` | `nika.cancel(run)` |
68
+ | `nika.workflows.list()` | `nika.listWorkflows()` |
69
+ | `nika.workflows.metadata(name)` | `nika.workflow(name)` |
70
+
71
+ In 0.116 the run handle was only `{ id, done }`. The Run now owns its
72
+ lifecycle: `run.events()`, `run.result()`, `run.status()` and `run.cancel()`,
73
+ with `run.done` kept as the alias of `run.result()`. The `nika.events(run)`,
74
+ `nika.cancel(run)` and `nika.status(run)` forms this guide shows still work
75
+ unchanged as deprecated wrappers, and `nika.events(run)` still yields the
76
+ protocol vocabulary; `run.events()` yields one lifecycle vocabulary on both
77
+ transports with that frame on `event.raw`. The wrappers stay through the 0.123
78
+ maintenance line; "Migrating to the Run-owned lifecycle" in
79
+ [runs.md](runs.md#migrating-to-the-run-owned-lifecycle) describes them.
80
+
81
+ The client-level methods reject a look-alike object and a run from another
82
+ client, so persist the job id and reattach after a process restart instead of
83
+ rebuilding a handle by hand.
84
+
85
+ `LocalNika.version()`, `dryRunPlan()`, and `test()` have no One SDK method.
86
+ Keep those CLI-facing probes in deployment/CI (`nika --version`,
87
+ `nika run --dry-run --json`, and `nika test`); the SDK does not emulate them.
88
+
89
+ ## The check report changed shape
90
+
91
+ `check()` still returns `clean` and `exitCode`, but the object around them is
92
+ no longer the 0.115 `LocalCheckReport` (eleven curated fields plus a `raw`
93
+ escape hatch). It is the engine's own machine report, passed through: the
94
+ former `raw` contents are now the top level, `reportVersion` is
95
+ `report_version`, and `parseFatal` and `warnings` are gone. The engine emits
96
+ its identity under both casings (`engineVersion` and `engine_version`,
97
+ `buildSha` and `build_sha`, `specSha` and `spec_sha`, `checkReportVersion`
98
+ and `report_version`); read either, do not diff them. In TypeScript only
99
+ `report_version`, `clean`, and `exitCode` are typed; every other field,
100
+ including `cost`, `findings`, and `hints`, is `unknown` behind an index
101
+ signature, so strict callers narrow it themselves. Two problems that look like
102
+ findings (a missing `permits:` block, a missing `max_tokens:`) are reported
103
+ under `hints[]` (`{ kind, task, advice }`, no `code`), not `findings[]`, in
104
+ both versions.
105
+
106
+ `runToEnd()` returned `{ ok, exitCode, events[] }` with every event buffered.
107
+ `run.done` returns the terminal result only; the events ride `events(run)`
108
+ as a bounded iterator. In 0.116 a session retained 256 frames, below the 273 a
109
+ measured clean native run of 90 `mock/echo` tasks writes, so such a run had to
110
+ be observed concurrently or its prefix was gone. The default is now 4096 and a view opened
111
+ after the result replays every retained frame; past the bound it is refused
112
+ with `reason: 'replay_truncated'`, never shortened, and the result is
113
+ unaffected. An explicit `eventBufferSize` keeps its cap. The removed methods (`version()`, `dryRunPlan()`, path-based
114
+ `traceVerify()`) are absent, not stubbed: calling them throws a plain
115
+ `TypeError: … is not a function`, and a trace that only exists as a file
116
+ path in a later process has no SDK verification door in 0.116.
117
+
118
+ ## New resident discovery
119
+
120
+ ```ts
121
+ const names = await nika.listWorkflows();
122
+ const metadata = await nika.workflow(names[0]);
123
+ ```
124
+
125
+ These methods require an HTTP client. A native-process client returns a typed
126
+ `NikaCompatibilityError` with capability `workflowCatalog`.
127
+
128
+ ## Durable status
129
+
130
+ ```ts
131
+ const run = await nika.run('flow.nika');
132
+ console.log(await nika.status(run));
133
+ console.log(await run.done);
134
+ ```
135
+
136
+ `status(run)` is an observation, not terminal settlement. Keep `run.done` as
137
+ the sole terminal promise. Native-process runs refuse `status()` because a
138
+ short-lived process has no independent durable status authority.
139
+
140
+ ## Durable run recovery
141
+
142
+ ```ts
143
+ const recovered = await nika.attachRun(saved.jobId, {
144
+ lastEventId: saved.lastEventSequence,
145
+ });
146
+ for await (const event of nika.events(recovered)) {
147
+ await saveApplicationCheckpoint(recovered.id, event.sequence);
148
+ }
149
+ console.log(await recovered.done);
150
+ ```
151
+
152
+ `attachRun()` is HTTP-only. It proves the job exists, returns a normal owned
153
+ run handle, and resumes the stream with `Last-Event-ID`. Save the job id and
154
+ event cursor in application durable state before the original process exits.
155
+ If more events arrive before the application subscribes than its configured
156
+ buffer can retain, `events()` refuses with `NikaEventBufferOverflowError`
157
+ instead of silently skipping a replay prefix.
158
+
159
+ ## Contract and release alignment
160
+
161
+ Version 0.116 targets the engine train whose OpenAPI contract contains check,
162
+ jobs, status, events, cancellation, typed trace verification, resident
163
+ workflow discovery, and schedule CAS. Do not publish the SDK before the
164
+ matching engine release and native payload assets exist.
@@ -0,0 +1,156 @@
1
+ # Prove what ran: receipts, traces and signing keys
2
+
3
+ Every run leaves a *trace*: a tamper-evident, hash-chained record of what
4
+ happened, written by the engine (locally under `.nika/traces/` in its working
5
+ directory). With a signing key, the engine also *seals* the trace: it signs
6
+ the record when the run ends. The run hands your code a *receipt*, and
7
+ `traceVerify(receipt)` asks the engine to check the trace against it. The
8
+ package never reads a trace or does cryptography itself.
9
+
10
+ ## What `traceVerify()` answers
11
+
12
+ Measured on engine 0.123.0 with the quick-start file:
13
+
14
+ | Where the run happened | `traceVerify()` answers | What it means |
15
+ |---|---|---|
16
+ | Local engine, with a key it can read | `{ verified: true, verdict: 'verified' }` | the record is sealed and matches the receipt |
17
+ | Local engine, no key it can read | `{ verified: false, verdict: 'invalid', reason: 'receipt_mismatch' }` | the run still succeeded, but its record is unsealed |
18
+ | `nika serve` with a key it can read | `{ verified: true, verdict: 'sealed', reason: 'sealed' }` | the job's journal is sealed and names this receipt's trace |
19
+ | `nika serve` without one | `{ verified: true, verdict: 'ok', reason: 'unsealed' }` | the job's journal is intact but unsigned |
20
+
21
+ - **Locally**, `traceVerify` runs the engine's verifier on the trace the
22
+ receipt names (`nika trace verify`), then checks that the receipt matches
23
+ the engine's evidence for it (`nika trace evidence`): `verified: true`
24
+ means both held. `receipt_mismatch` is also the answer for a tampered or
25
+ edited receipt: do not read every one as "just unsigned".
26
+ - **Over HTTP**, `traceVerify` asks the server for its verdict on the journal
27
+ it wrote for the job (`GET /v1/jobs/{id}/trace/verify`). The verdict is the
28
+ CLI's word, in lower case: `ok` (intact, unsigned), `sealed`, `anchored` and
29
+ `replayed` hold; `incomplete`, `tampered` and `broken` do not; `unchained`,
30
+ `empty`, `unreadable`, `refused`, `line-over-long` and `unknown` are the
31
+ CLI's refusal classes; `unavailable` means the server has no journal for the
32
+ job (refused before its first event, still queued, or a backend that keeps
33
+ none). `reason` is always present: beside a verdict that holds it names the
34
+ seal tier (`sealed`, `unsealed`). The package sets `verified: true` only for
35
+ a verdict that holds **and** names this receipt's `trace_id`.
36
+
37
+ > [!WARNING]
38
+ > **Over HTTP, check `proof.verified` first.** `verdict` and `reason` are the
39
+ > server's words about the job's journal: they stay `sealed` even when the
40
+ > receipt you passed does not match that journal, and then `verified` is
41
+ > `false` (measured on 0.123.0 with a receipt whose `trace_id` was changed).
42
+ > Treat a job as sealed only when
43
+ > `proof.verified && ['sealed', 'anchored', 'replayed'].includes(proof.verdict ?? '')`;
44
+ > `verified: true` with `verdict: 'ok'` means intact but unsigned.
45
+
46
+ > [!IMPORTANT]
47
+ > A verified receipt proves that the run's record is intact and matches the
48
+ > receipt. It does not prove that the workflow was right, or that a person
49
+ > read its output. The record is tamper-evident, not tamper-proof.
50
+
51
+ ## Admitted, executed, sealed: three different facts
52
+
53
+ | Fact | How you see it | What it is not |
54
+ |---|---|---|
55
+ | **Admitted** | `run()` resolves with a `NikaRun`. A workflow the engine refuses makes `run()` throw `NikaOperationError` (`NIKA-SEC-004`, `NIKA-PARSE-005`, `NIKA-1708`…), and no run exists. `check()` shows the same verdict without running: `clean: false` and the findings. | Not a successful execution. |
56
+ | **Executed** | `run.result()` and `isNikaRunSucceeded(result)`. An admitted failure is data (`status: "failed"`). A human gate is `paused` (a `run.waiting` event), not success. | Not proof that the record is sealed. |
57
+ | **Sealed** | `result.receipt.sealed` and `traceVerify(receipt)`. Tamper-evident, not tamper-proof; not replayed unless you ask the CLI (`--replay`); not anchored without a sidecar. | Not "the workflow was correct", and not "a person read the output". |
58
+
59
+ Measured on engine 0.123.0 with the quick-start file: `run.events()` yields
60
+ the same six events with or without a signing key. With a key, the receipt
61
+ reads `sealed: true` and `traceVerify` returns
62
+ `{ verified: true, verdict: 'verified' }`. With an empty `HOME` and no key,
63
+ the same run **succeeds** with `sealed: false`, and `traceVerify` returns
64
+ `{ verified: false, verdict: 'invalid', reason: 'receipt_mismatch' }`, while
65
+ the engine's own `nika trace verify` still calls the journal chain OK and
66
+ unsealed. The event count that command prints counts journal entries; it is
67
+ not the number of `run.events()`.
68
+
69
+ **Watch the three facts from TypeScript, then one changed byte.**
70
+
71
+ <p align="center">
72
+ <picture>
73
+ <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-admitted-executed-sealed.png">
74
+ <img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/gifs/sdk-admitted-executed-sealed.gif" alt="node gate.mts on a workflow that runs ls under permits: {} prints check refused · exit 2 and NIKA-SEC-004, then run not started: no run, no events, no trace; a one-line permits fix checks clean and runs. node prove.mts with no signing key prints receipt sealed false · 5 events and not verified · invalid · receipt_mismatch; after NIKA_KEYCHAIN=off nika key init it prints sealed true · 6 events and verified. node tamper.mts changes one byte on line 4 of the trace, and node verify.mts prints not verified · invalid and engine BROKEN at line 5" width="860">
75
+ </picture>
76
+ </p>
77
+ <p align="center"><sub>Admitted: <code>check()</code> and <code>run()</code> refuse the file and no run exists. Executed, not sealed: with no key the run succeeds and the receipt reads <code>sealed false</code> over 5 journal entries. Sealed: after <code>NIKA_KEYCHAIN=off nika key init</code> the next run of the same file has 6, the last one <code>run_sealed</code>, and verifies. Then one changed byte, and the stored receipt fails: <code>BROKEN at line 5</code>. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine; the runs are <code>mock/echo</code> rehearsals.<br>▶ <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-admitted-executed-sealed.mp4?raw=true">MP4</a> · <a href="https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-admitted-executed-sealed.txt">transcript</a> · <a href="https://github.com/nika-open/nika-client/tree/main/scripts/media/scenes/sdk-admitted-executed-sealed">the programs it runs</a></sub></p>
78
+
79
+ ## What a receipt carries
80
+
81
+ Pass a receipt back unchanged, and store it with what it proves.
82
+
83
+ - **A local run's receipt** carries the proof fields (`trace_path`,
84
+ `chain_head`, `chain_len`, `sealed`) with `trace_id`, `execution_id`,
85
+ `snapshot_digest` and `receipt_format`.
86
+ - **A `nika serve` job's receipt** carries the job's identity (`job_id`,
87
+ `execution_id`, `trace_id`, `snapshot_digest`, `origin`) and the
88
+ `chain_head`. Store it with the job id. A scheduled job's `origin` names the
89
+ firing; see [server.md](server.md#schedules).
90
+
91
+ A run receipt is not the per-call access receipt. What a model call asked of
92
+ its route and what the route read back (`nika/access-selection@1`: model,
93
+ effort and, when the file declares one, the service tier) is a row of the
94
+ task's frame in the journal the seal covers, not a field of the run receipt.
95
+ On a local run, read it with `readNikaAccessSelection`
96
+ ([runs.md](runs.md#the-files-own-access-contract-runaccess)).
97
+
98
+ A trace can hold model outputs and file contents, so keep `.nika/` out of
99
+ git and treat traces as application data.
100
+
101
+ ## Signing keys: where the engine finds them
102
+
103
+ Run-signing keys belong to the engine. `nika key init` mints one,
104
+ `nika key trust` prints its public key and fingerprint to enroll on other
105
+ machines, `nika key rotate` retires it and mints a new one (records signed
106
+ with a retired key stay verifiable), and, on Linux, `nika key align` copies a
107
+ Secret Service key to the files the other processes read.
108
+
109
+ Which key a process signs with depends on the process and, for `nika` run
110
+ from a terminal, on the platform. Nika 0.123 and later:
111
+
112
+ | Process | Opens an OS keychain? | Signs with, in this order |
113
+ |---|---|---|
114
+ | `nika` run from a terminal, on macOS | no: Nika 0.123 and later never open the keychain on macOS, even from a terminal (`nika doctor` says `the keychain is not opened by this ad-hoc build`) | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
115
+ | `nika` run from a terminal, on Linux | yes: the desktop's Secret Service, when one answers | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, the Secret Service, then `~/.nika/keys/` |
116
+ | the engine your app starts (`new Nika()`) | never: it has no terminal | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
117
+ | `nika serve` | never | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
118
+
119
+ So the key your app's runs use must be a file, and `NIKA_KEYCHAIN=off` makes
120
+ one on every platform:
121
+
122
+ - **A new machine.** `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init`
123
+ writes the key to `~/.nika/keys/` (mode `0600`), where every process reads
124
+ it.
125
+ - **Without the variable, on Linux.** From a terminal, `nika key init`
126
+ refuses with `run-signing key material already exists`, even on a new
127
+ machine: off macOS the engine cannot see whether the keychain already holds
128
+ a run-key, so it never risks replacing one. On a desktop,
129
+ `nika key init --force` then stores the key in the Secret Service only,
130
+ where your app's engine and `nika serve` never look. To repair that, run
131
+ `./node_modules/.bin/nika key align` once from a terminal: it copies the
132
+ Secret Service key to `~/.nika/keys/`, retiring any other file key it
133
+ replaces, so the CLI, your app and `nika serve` sign with one key.
134
+ - **Without the variable, on macOS.** `nika key init` from a terminal writes
135
+ the files too, unless the keychain holds a run-key that Nika 0.122 or older
136
+ stored there. Then it refuses, and the repair it names, `nika key align`,
137
+ cannot succeed with Nika 0.123 and later, which can neither read nor copy
138
+ that key: it exits with `this process does not open the keychain`. The
139
+ variable skips the keychain check and mints a new key as files, a new
140
+ signing identity beside the old keychain key.
141
+ - **CI and servers.** Give the engine an explicit pair through
142
+ `NIKA_RUN_KEY_FILE` and `NIKA_RUN_PUB_FILE`; `nika key init` with those two
143
+ variables set writes the pair there.
144
+ - **Rotation.** `NIKA_KEYCHAIN=off nika key rotate` retires the file key to
145
+ `~/.nika/keys/retired.pub` and writes the next one as files. Without the
146
+ variable, on a Linux desktop terminal, the new key would go to the Secret
147
+ Service, and your app would keep signing with the old file key.
148
+ - **Check it.** `nika doctor` prints a `run-key` line for the process that
149
+ runs it. To see what the engine your app starts sees, take the terminal
150
+ away: `./node_modules/.bin/nika doctor 2>&1 | cat` names the key file it
151
+ signs with, or says `none · runs stay unsigned`.
152
+
153
+ `NIKA_KEYCHAIN=off` skips only the keychain; the file and explicit-pair paths
154
+ stay. Store receipts and public trust material in your app. Never copy a
155
+ private run key into SDK configuration, source control, workflow inputs or an
156
+ HTTP request.