@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/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.