@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.
- package/LICENSE +202 -0
- package/README.md +775 -5
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +87 -7
package/docs/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# @nika-open/nika documentation
|
|
2
|
+
|
|
3
|
+
These pages ship inside the npm package (`node_modules/@nika-open/nika/docs/`)
|
|
4
|
+
and describe the version you installed. Their links to files the package does
|
|
5
|
+
not ship (recordings, examples, scripts, the changelog) open the repository on
|
|
6
|
+
GitHub. Start with the
|
|
7
|
+
[README](../README.md): install, a first run, what happens underneath and the
|
|
8
|
+
two doors. Then read the page for what you are building.
|
|
9
|
+
|
|
10
|
+
## Build with it
|
|
11
|
+
|
|
12
|
+
| Page | What it covers |
|
|
13
|
+
|---|---|
|
|
14
|
+
| [runs.md](runs.md) | `check()`, results and statuses, literal `inputs`, access pins, `run.events()`, late views and their bounds, large results and `machineBufferBytes`, a server run's artifacts, cancellation, typed frames, the deprecated wrappers |
|
|
15
|
+
| [server.md](server.md) | `nika serve`: setup, idempotent runs, recovery with `attachRun`, the 5-second cancel grace, restarts, artifacts and their verified downloads, connection rules, schedules, the local/server differences |
|
|
16
|
+
| [receipts.md](receipts.md) | Traces, receipts and `traceVerify()` on both doors, what a verified receipt proves, signing keys and where each process reads them |
|
|
17
|
+
| [compile.md](compile.md) | `compile()`: from an intention or an edit to a checked candidate, answer rounds, provider rounds on a seated server |
|
|
18
|
+
| [errors.md](errors.md) | The error hierarchy, refused runs, server refusals and a troubleshooting table |
|
|
19
|
+
| [upgrading-to-0.123.md](upgrading-to-0.123.md) | Moving from 0.120.x, or from 0.123.x to 0.124: the machine-protocol rule and what changed in the data |
|
|
20
|
+
| [glossary.md](glossary.md) | Workflow, run, job, execution, trace, seal, receipt, door, seat, round… defined once |
|
|
21
|
+
|
|
22
|
+
## Contracts and internals
|
|
23
|
+
|
|
24
|
+
| Page | What it covers |
|
|
25
|
+
|---|---|
|
|
26
|
+
| [http-api.md](http-api.md) | Every `nika serve` route the package uses, SSE recovery, idempotency, schedule revisions, compile generation 2, artifacts |
|
|
27
|
+
| [architecture.md](architecture.md) | Modules, the two transports, lifecycle invariants and authority boundaries (for contributors) |
|
|
28
|
+
| [testing.md](testing.md) | Test layers, gauntlets and release evidence (for contributors) |
|
|
29
|
+
| [migrating-to-0.116.md](migrating-to-0.116.md) | History: the 0.115 to 0.116 consolidation into one `Nika` class |
|
|
30
|
+
|
|
31
|
+
## Watch it
|
|
32
|
+
|
|
33
|
+
Five terminal recordings of the published 0.124.0 package and the engine it
|
|
34
|
+
bundles, each run in a fresh project with `mock/echo` (no model key), and one
|
|
35
|
+
illustration. Each comes as a GIF, an MP4 you can pause, and a text
|
|
36
|
+
transcript. They live in the GitHub repository, not in the npm package.
|
|
37
|
+
[media/README.md](https://github.com/nika-open/nika-client/blob/main/media/README.md) says how they are made and checked, and
|
|
38
|
+
what the illustration draws.
|
|
39
|
+
|
|
40
|
+
| Watch | What it shows | Where it is explained |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| [The quick start](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-quickstart.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-quickstart.mp4?raw=true) · [transcript](https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-quickstart.txt) | The install, the signing key, `run()`, a typed result, a verified receipt | [README](../README.md#quick-start) |
|
|
43
|
+
| [Two doors](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-doors.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-doors.mp4?raw=true) (illustration) | One call through the package to the bundled engine or to `nika serve`: check, run, events, seal, verify | [README](../README.md#what-happens-underneath) |
|
|
44
|
+
| [Three facts](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-admitted-executed-sealed.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-admitted-executed-sealed.mp4?raw=true) · [transcript](https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-admitted-executed-sealed.txt) | A refused file that never runs, an unsealed run, a sealed one, one changed byte | [receipts.md](receipts.md#admitted-executed-sealed-three-different-facts) |
|
|
45
|
+
| [Events](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-events.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-events.mp4?raw=true) · [transcript](https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-events.txt) | `run.events()` for a four-task run, then `result()` | [runs.md](runs.md#watch-a-run-runevents) |
|
|
46
|
+
| [Compile](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-compile.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-compile.mp4?raw=true) · [transcript](https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-compile.txt) | A sentence to a ready candidate in two rounds, with no model call | [compile.md](compile.md#start-here-no-model-no-key) |
|
|
47
|
+
| [Your server](https://github.com/nika-open/nika-client/blob/main/media/gifs/sdk-remote.gif) · [MP4](https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-remote.mp4?raw=true) · [transcript](https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-remote.txt) | `nika serve` set up as the README says, one job, a retry, a wrong token | [server.md](server.md#set-it-up) |
|
|
48
|
+
|
|
49
|
+
## Runnable examples
|
|
50
|
+
|
|
51
|
+
[`examples/`](https://github.com/nika-open/nika-client/blob/main/examples/README.md) in the repository holds programs you can
|
|
52
|
+
run against the bundled engine or a local `nika serve`: the quick start, a
|
|
53
|
+
watched and cancelled run, a server job recovered across two processes,
|
|
54
|
+
compile then run, and a server job's artifacts listed and downloaded.
|
|
55
|
+
|
|
56
|
+
## Elsewhere
|
|
57
|
+
|
|
58
|
+
- The SDK guide on docs.nika.sh: [overview](https://docs.nika.sh/sdk/overview),
|
|
59
|
+
[quickstart](https://docs.nika.sh/sdk/start/quickstart),
|
|
60
|
+
[configuration](https://docs.nika.sh/sdk/reference/configuration),
|
|
61
|
+
[methods](https://docs.nika.sh/sdk/reference/methods),
|
|
62
|
+
[types](https://docs.nika.sh/sdk/reference/types),
|
|
63
|
+
[receipts](https://docs.nika.sh/sdk/runtime/receipts),
|
|
64
|
+
[remote jobs](https://docs.nika.sh/sdk/remote/jobs),
|
|
65
|
+
[OS schedulers](https://docs.nika.sh/sdk/operations/os-schedulers) and
|
|
66
|
+
[deployment topologies](https://docs.nika.sh/sdk/operations/deployment-topologies).
|
|
67
|
+
- [Known limits in 0.124](https://docs.nika.sh/changelog/known-limits).
|
|
68
|
+
- The [engine](https://github.com/nika-open/nika) and the
|
|
69
|
+
[language specification](https://github.com/nika-open/nika-spec).
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# SDK architecture
|
|
2
|
+
|
|
3
|
+
The package has one public facade and two execution adapters:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
application
|
|
7
|
+
|
|
|
8
|
+
v
|
|
9
|
+
Nika facade
|
|
10
|
+
|
|
|
11
|
+
v
|
|
12
|
+
Transport interface <--- lifecycle and authority seam
|
|
13
|
+
| |
|
|
14
|
+
v v
|
|
15
|
+
NativeProcessTransport HttpTransport
|
|
16
|
+
| |
|
|
17
|
+
v v
|
|
18
|
+
local nika process authenticated nika serve
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Modules and responsibilities
|
|
22
|
+
|
|
23
|
+
- `src/index.ts` is the public Module. It validates caller-owned values, owns
|
|
24
|
+
run handles, and exposes one stable vocabulary.
|
|
25
|
+
- `src/lib/transport.ts` is the Interface. It describes the operations both
|
|
26
|
+
Adapters must implement and makes unsupported authority explicit.
|
|
27
|
+
- `src/lib/native-process-transport.ts` is the local Adapter. It spawns the
|
|
28
|
+
selected engine without a shell and consumes newline-delimited machine
|
|
29
|
+
events. It reads the first machine frame before it returns a run, so
|
|
30
|
+
`run()` resolves on the engine's admission and rejects on its refusal.
|
|
31
|
+
- `src/lib/run-refusal.ts` reads the engine's one pre-run refusal object (its
|
|
32
|
+
check report carrying `clean: false`, or its `{ error }` envelope) and turns
|
|
33
|
+
it into the typed `NikaOperationError`. It judges nothing: a shape the
|
|
34
|
+
engine was not measured to write is a protocol fault, never a refusal.
|
|
35
|
+
- `src/lib/legacy-run-refusals.ts` is unreachable since 0.123 and scheduled
|
|
36
|
+
for removal. It recovers the three refusal dialects of engines up to
|
|
37
|
+
0.119.0, which predate the one `run --json` grammar; those engines speak
|
|
38
|
+
machine protocol 1, which the identity probe refuses before any run, so a
|
|
39
|
+
maintenance patch can delete it with its call sites (keeping the 0.123 wire
|
|
40
|
+
fixtures).
|
|
41
|
+
- `src/lib/http-transport.ts` is the remote Adapter. It verifies the remote
|
|
42
|
+
server identity once per client, resolves and verifies a local engine only
|
|
43
|
+
for caller-owned snapshot capture, then uses the authenticated HTTP
|
|
44
|
+
contract.
|
|
45
|
+
- `src/lib/run-session.ts` is the lifecycle Seam. It owns the eager event
|
|
46
|
+
pump, bounded independent observers, cancellation memoization, and the sole
|
|
47
|
+
terminal settlement. It builds the `NikaRun` handle as closures over itself,
|
|
48
|
+
so the Run owns `events()`, `result()`, `status()` and `cancel()`, and
|
|
49
|
+
passes `artifacts()`, `downloadArtifact()` and `readArtifact()` to its
|
|
50
|
+
transport.
|
|
51
|
+
- `src/lib/artifacts.ts` reads a server's artifact manifest and proves each
|
|
52
|
+
download: one verified stream that hashes every chunk, never passes the
|
|
53
|
+
recorded size, holds its last chunk until the digest matches, and requests
|
|
54
|
+
a body cut short again. It reads no journal and derives no artifact.
|
|
55
|
+
- `src/lib/run-events.ts` is the semantic Adapter: a pure projection of one
|
|
56
|
+
protocol frame onto the SDK's lifecycle vocabulary, with the frame kept by
|
|
57
|
+
identity on `raw`. It is applied at the edge of an observer view. There is
|
|
58
|
+
one history and one bounded queue per observer, and no second event bus.
|
|
59
|
+
- `openapi.json` and `src/generated/openapi.d.ts` pin the HTTP contract judged
|
|
60
|
+
by CI. `scripts/check-sdk-coverage.js` fails if a live runtime path is
|
|
61
|
+
missing or if the SDK names a path outside that contract.
|
|
62
|
+
|
|
63
|
+
## Authority rules
|
|
64
|
+
|
|
65
|
+
The SDK transports engine facts; it does not reproduce engine decisions.
|
|
66
|
+
Parsing, admission, scheduling, cancellation settlement, receipts, trace
|
|
67
|
+
verification, permits, and cost remain engine-owned.
|
|
68
|
+
|
|
69
|
+
Some operations deliberately have one authority:
|
|
70
|
+
|
|
71
|
+
- resident workflow discovery, durable status, and schedules require HTTP;
|
|
72
|
+
- a direct native process refuses those operations with
|
|
73
|
+
`NikaCompatibilityError`;
|
|
74
|
+
- remote execution by contained workflow name uses the resident registry;
|
|
75
|
+
explicit local paths need a compatible local engine to capture a snapshot;
|
|
76
|
+
- when that capture is red the HTTP adapter returns the local engine's plain
|
|
77
|
+
`nika check --json` report, so `findings[]` stays canonical and no workflow
|
|
78
|
+
bytes are sent;
|
|
79
|
+
- HTTP observation (attach, durable status, events, cancel, workflow catalog,
|
|
80
|
+
schedule status, trace verdicts) needs no local engine;
|
|
81
|
+
- remote trace verification returns the server's verdict on the journal it
|
|
82
|
+
wrote for the job (`ok`, `sealed`, `broken`…, in the CLI's words), and
|
|
83
|
+
`unavailable` only when no journal exists for it; the adapter adds only
|
|
84
|
+
`verified`, true when that verdict holds and names the receipt's trace;
|
|
85
|
+
- artifacts are the server's: its manifest, derived from the job's sealed
|
|
86
|
+
journal, is the only list, bound to the job's receipt, and each download is
|
|
87
|
+
proven against it. A native run refuses with `NikaCompatibilityError`
|
|
88
|
+
(`capability: 'artifacts'`); the SDK never lists a local file as one.
|
|
89
|
+
|
|
90
|
+
## Lifecycle invariants
|
|
91
|
+
|
|
92
|
+
1. `run()` resolves only after stable admission and returns an immutable
|
|
93
|
+
`NikaRun` handle: `id`, `events()`, `result()`, `status()`, `cancel()`,
|
|
94
|
+
the job's `artifacts()`, `downloadArtifact()` and `readArtifact()`, and
|
|
95
|
+
`done`, the compatibility alias of `result()`. Admission is not execution;
|
|
96
|
+
a succeeded `result()` is not a sealed receipt (`traceVerify` can return
|
|
97
|
+
`receipt_mismatch` on an UNSEALED journal). Its members are closures
|
|
98
|
+
over the run's one session, so an extracted method still works. The handle
|
|
99
|
+
owns the lifecycle and what the job produced, nothing else: checking,
|
|
100
|
+
proof, catalogs and authoring stay on the facade. A run handle never
|
|
101
|
+
means "maybe a run": a refusal
|
|
102
|
+
before admission rejects `run()` with `NikaOperationError` and no handle
|
|
103
|
+
exists. Over HTTP a red local snapshot refuses before any request is sent;
|
|
104
|
+
on the native transport the first machine frame decides. A run event is the
|
|
105
|
+
engine's admission evidence and is replayed as the first event; a refusal
|
|
106
|
+
object is the whole stream. The one spawn that executes the workflow is the
|
|
107
|
+
one that judges it: the SDK adds no preflight check and never spawns twice.
|
|
108
|
+
2. `run.result()` is the only terminal promise (`run.done` is the same one).
|
|
109
|
+
Workflow failure is result data; configuration, transport, protocol, and
|
|
110
|
+
compatibility failures throw. A `paused` result is a human gate: neither a
|
|
111
|
+
failure nor a completed execution.
|
|
112
|
+
3. A session's history retains at most `eventBufferSize` frames (default 4096,
|
|
113
|
+
never unbounded; each frame is bounded by `machineBufferBytes`). That
|
|
114
|
+
product bounds the retained history only, not the session or the process:
|
|
115
|
+
frames already handed to a consumer, other views and other runs are not
|
|
116
|
+
counted in it. Two different
|
|
117
|
+
bounds can be exceeded and they are never confused: a live view that falls
|
|
118
|
+
behind fails with `reason: 'live_backpressure'`, and a view opened after
|
|
119
|
+
more frames than it can be given is refused with
|
|
120
|
+
`reason: 'replay_truncated'` plus what was `observed` and `retained`.
|
|
121
|
+
Neither skips a frame, neither touches another view, and neither touches
|
|
122
|
+
the result: a run longer than the bound still settles normally. The
|
|
123
|
+
session is memory over what this process saw. It is not a control plane,
|
|
124
|
+
keeps nothing on disk, and reads no engine journal to extend a replay.
|
|
125
|
+
`run.events()` creates an independent bounded observer in the lifecycle
|
|
126
|
+
vocabulary. Aborting an observer never cancels the run. The vocabulary is a
|
|
127
|
+
stateless per-frame projection: it names a fact only for a (kind, status)
|
|
128
|
+
pair a producer defines, never defaults a state word, never deduplicates,
|
|
129
|
+
and never synthesizes a frame a transport did not emit. Every other frame
|
|
130
|
+
keeps flowing as `engine.event`, so transports differ in cardinality but
|
|
131
|
+
never in names, and `event.raw` is always the untouched protocol frame.
|
|
132
|
+
4. `run.cancel()` is idempotent per run: every call returns the one request.
|
|
133
|
+
5. `run.status()` reads the durable HTTP projection and refuses a native-only
|
|
134
|
+
run instead of guessing from local process state.
|
|
135
|
+
6. Schedule creation uses `If-None-Match: *`; updates require the exact opaque
|
|
136
|
+
revision in `If-Match`.
|
|
137
|
+
7. `attachRun()` is the one recovery door. It creates a fresh owned session
|
|
138
|
+
for an existing HTTP job; its initial sequence is caller-owned durable
|
|
139
|
+
checkpoint state, never inferred from in-memory SDK history. A native run
|
|
140
|
+
is process-bound: its `run.id` is an ephemeral correlation id, and the SDK
|
|
141
|
+
keeps no local job store, starts no hidden `nika serve`, and reads no
|
|
142
|
+
journal to fake durability.
|
|
143
|
+
8. Ownership has no registry. The facade maps each handle it created to its
|
|
144
|
+
session in a `WeakMap`. The deprecated `nika.events(run)`,
|
|
145
|
+
`nika.cancel(run)` and `nika.status(run)` wrappers resolve through it, so a
|
|
146
|
+
foreign, reconstructed, serialized, or other-client handle still throws
|
|
147
|
+
`NikaRunOwnershipError`. `nika.events(run)` keeps yielding the protocol
|
|
148
|
+
vocabulary unchanged. The wrappers shipped unchanged next to the Run-owned
|
|
149
|
+
lifecycle from 0.120.0, the first published version that carries it, and
|
|
150
|
+
are still here in 0.124.5; a later version that removes them says so in
|
|
151
|
+
its release notes.
|
|
152
|
+
9. An interrupted observation is a typed transport error carrying its cursor
|
|
153
|
+
(`NikaObservationInterrupted`), never an engine failure: the run may still
|
|
154
|
+
be running. The engine's own `interrupted` evidence state is data instead:
|
|
155
|
+
a `run.interrupted` event and `result.status === 'interrupted'`.
|
|
156
|
+
|
|
157
|
+
## Deletion test
|
|
158
|
+
|
|
159
|
+
If one Adapter is removed, the facade and lifecycle Seam remain coherent and
|
|
160
|
+
the other Adapter still compiles. If the Transport Interface is removed,
|
|
161
|
+
authority differences leak into every public method. If `run-session.ts` is
|
|
162
|
+
removed, each consumer must reimplement buffering, ownership, cancellation,
|
|
163
|
+
and settlement. Those boundaries therefore carry real architectural load.
|