@supernovae-st/nika 0.118.7 → 0.120.0

package/README.md

@@ -9,83 +9,45 @@
 
 <h1 align="center">@supernovae-st/nika</h1>
 
-<p align="center"><strong>One TypeScript surface for local Nika processes and authenticated Nika servers.</strong></p>
+<p align="center">
+  <strong>The TypeScript door to Nika: audit a workflow, run it, watch it, prove it.</strong><br>
+  Locally through the released engine, or against an authenticated <code>nika serve</code>.
+</p>
 
-`Nika` exposes one lifecycle vocabulary: `check`, `run`, `attachRun`, `status`, `events`,
-`cancel`, `traceVerify`, `listWorkflows`, `workflow`, `schedule`, and
-`scheduleStatus`.
-The engine remains authoritative for parsing, admission, execution, receipts,
-traces, permits, scheduling, and cost. The SDK transports those facts; it does
-not parse YAML or reconstruct proof in TypeScript.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@supernovae-st/nika"><img src="https://img.shields.io/npm/v/@supernovae-st/nika?label=npm" alt="npm version"></a>
+  <a href="https://github.com/supernovae-st/nika-client/actions/workflows/ci.yml"><img src="https://github.com/supernovae-st/nika-client/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="https://github.com/supernovae-st/nika/releases/latest"><img src="https://img.shields.io/github/v/release/supernovae-st/nika?label=engine" alt="Engine release"></a>
+  <a href="https://docs.nika.sh"><img src="https://img.shields.io/badge/docs-docs.nika.sh-8b8cf8.svg" alt="Documentation"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0"></a>
+</p>
 
-## Requirements
+<p align="center">
+  <a href="https://scorecard.dev/viewer/?uri=github.com/supernovae-st/nika-client"><img src="https://api.scorecard.dev/projects/github.com/supernovae-st/nika-client/badge" alt="OpenSSF Scorecard"></a>
+  <a href="https://www.npmjs.com/package/@supernovae-st/nika"><img src="https://img.shields.io/badge/npm-provenance-2ea44f.svg" alt="Published with provenance through GitHub Actions trusted publishing"></a>
+  <a href="https://www.npmjs.com/package/@supernovae-st/nika"><img src="https://img.shields.io/npm/dm/@supernovae-st/nika?label=downloads" alt="npm downloads"></a>
+  <a href="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/supernovae-st/nika-client"><img src="https://archive.softwareheritage.org/badge/origin/https://github.com/supernovae-st/nika-client/" alt="Archived by Software Heritage"></a>
+</p>
 
-- Node.js 22 or newer (the tested floor; an older major is unsupported, not
-  refused, and `npm install` does not warn about it)
-- for native execution or local snapshot capture, a compatible `nika` engine, resolved from `config.bin`, then `NIKA_BIN`
-  (absolute paths only), then the exact optional platform package; a bare
-  name or a relative path is refused because the operating system would
-  resolve it through `PATH` or the working directory, and a `nika` found on
-  `PATH` is deliberately never used
-- a `.nika.yaml` workflow
+## Thirty seconds, no API key
 
-## Documentation
-
-- [Architecture](docs/architecture.md) — Modules, Interface, Seam, Adapters,
-  lifecycle, and authority boundaries
-- [HTTP contract](docs/http-api.md) — every live route, recovery, security,
-  idempotency, and schedule CAS
-- [Testing and release evidence](docs/testing.md) — layered gauntlets and the
-  Socratic risk matrix
-- [Migrating to 0.116](docs/migrating-to-0.116.md) — intentional breaking
-  migration to the smaller durable client surface
-
-## Install
+One package installs the client, the `nika` command and the engine payload for
+your platform (macOS and Linux, arm64 and x64):
 
 ```sh
-npm view @supernovae-st/nika@0.118.7 version  # must report 0.118.7
 npm install @supernovae-st/nika@0.118.7
+./node_modules/.bin/nika --version
 ```
 
-If the registry reports any other version, the 0.118.7 release train is not
-complete. Earlier packages expose the retired `LocalNika`/HTTP split and do
-not implement the root facade documented below. The publication is complete
-only when the four matching native payload packages and this root client are
-all visible on npm.
-
-This package carries the product's name. Up to 0.115.0 it was published as
-`@supernovae-st/nika-client`; that name is deprecated on npm, stays installable
-for the versions it already holds, and receives no further releases. The
-native payloads were already `@supernovae-st/nika-<os>-<arch>`, and the
-repository keeps its name (`supernovae-st/nika-client`).
-
-Verify the package that the current project actually resolved:
-
-```sh
-node -p "require('@supernovae-st/nika/package.json').version"
 ```
-
-This package metadata subpath is exported for CommonJS, ESM build tools and CI
-pin checks. It reports the installed dependency, not a moving registry tag.
-
-## First local run
-
-The lowest-friction creation door is the engine-owned scaffold:
-
-```sh
-./node_modules/.bin/nika init --project-file
-./node_modules/.bin/nika new 01-hello hello.nika.yaml
+nika 0.118.7 (f3a31a6ee)
 ```
 
-`nika.yaml` is the project control plane. `hello.nika.yaml` is executable
-workflow intent and is the file passed to `check()` and `run()`. The scaffold
-writes the engine's own annotated `01-hello` example (its task is named
-`greet` and its prompt asks for French); the contract this README relies on is
-the `outputs.greeting` key and the `mock/echo` model, and the same file can be
-written by hand with this public envelope:
+Write `hello.nika`. The `mock/echo` model rehearses with no key and no
+network:
 
 ```yaml
-nika: sdk-hello
+nika: hello
 model: mock/echo
 permits: {}
 tasks:
@@ -97,7 +59,22 @@ outputs:
   greeting: ${{ tasks.greeting.output }}
 ```
 
-Then drive the installed engine:
+Audit it before anything runs:
+
+```sh
+./node_modules/.bin/nika check hello.nika
+```
+
+```
+ ✔ ORDER    no exec: sits downstream of a net-effecting task · unauthored content never reaches a shell
+ ✔ PERMITS  literal + const: args fit the boundary · computed paths + symlinks are the RUN's verdict
+ ✔ TRIFECTA no lethal trifecta over the declared permits: without a human gate
+ ✔ JOURNEY internal · 0 sources · 0 destinations · 1 model endpoint · no secret reaches an external destination
+ ✔ audited · 1 task · 1 wave · permits {} · est out ≤$0.0000 · 0 hints · risk low
+ layers · valid ✔ · access ready ✔ · capacity fit ✔ · run ready ✔
+```
+
+Now drive the same engine from TypeScript:
 
 ```ts
 import { Nika } from '@supernovae-st/nika';
@@ -107,41 +84,254 @@ const nika = new Nika({
   // bin: '/absolute/path/to/nika', // or set NIKA_BIN
 });
 
-const report = await nika.check('hello.nika.yaml', {
+const report = await nika.check('hello.nika', {
   nativeStrict: true,
 });
 if (!report.clean) throw new Error('workflow did not pass nika check');
 
-const run = await nika.run('hello.nika.yaml', { maxCostUsd: 0 });
-const watching = (async () => {
-  for await (const event of nika.events(run)) {
-    // Native progress frames carry no status; only the terminal frame does.
-    console.log(event.kind, event.status ?? '');
-  }
-})();
+const run = await nika.run('hello.nika', { maxCostUsd: 0 });
+for await (const event of run.events()) {
+  // The same lifecycle words on both transports; the engine's own frame,
+  // in its protocol vocabulary, stays on event.raw.
+  console.log([event.kind, event.task, event.status].filter(Boolean).join(' '));
+}
 
-const result = await run.done;
-await watching;
+const result = await run.result();
 console.log(result.status, result.outputs, result.receipt);
 ```
 
-Expected output: `workflow_started`, `task_scheduled`, `task_started`,
-`task_completed`, `workflow_completed`, then `run_settled succeeded`, then the
-terminal `succeeded` line with the outputs and the receipt.
+Expected output: `run.started`, `task.scheduled greeting`,
+`task.started greeting`, `task.completed greeting`, `engine.event`, then
+`run.settled succeeded`, then the terminal `succeeded` line with the outputs
+and the receipt. The `engine.event` is the native journal's own
+`workflow_completed` frame: the SDK gives it no lifecycle name and no state,
+drops nothing, and shows it on `event.raw.kind`.
+
+That is six frames for one task; the same shape with 90 tasks was measured at
+273 (`3N + 3`). A session retains the most recent 4096 frames by default, so
+`run.events()` opened after `run.result()` replays them all, and is refused,
+never shortened, past that bound; see
+[Observing a run after the fact](#observing-a-run-after-the-fact).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/supernovae-st/nika-client/main/media/local-driver.gif" alt="The typed driver over the released binary: check the workflow, gate on the report, run it to the end under a cost ceiling, count the events" width="960">
+</p>
+
+*Recorded by `scripts/media/render.sh` against this package and the released
+engine; every line on screen is the SDK's own output. The recorded driver
+predates the Run-owned lifecycle: it still calls `nika.events(run)`, a
+deprecated wrapper that keeps working through the
+[compatibility window](#migrating-to-the-run-owned-lifecycle), and the
+`run.done` alias, which is not deprecated.*
 
 Native checks and explicit local snapshot checks preserve the engine's
 `findings[]` and `exitCode`. A check by served name returns the resident's
 compact acknowledgement with `clean: true`, or its typed workflow refusal
 with `clean: false`; it does not invent local findings or an exit code.
 
-`run()` returns after stable admission. `run.done` is the sole terminal result.
+`run()` returns after stable admission, and the `NikaRun` it returns owns its
+lifecycle: `run.events()`, `run.result()`, `run.status()` and `run.cancel()`.
+`run.result()` is the sole terminal result (`run.done` is its compatibility
+alias, the same promise).
+A workflow the engine refuses before admission never yields a run: `run()`
+itself rejects with a `NikaOperationError` that names the engine's code and,
+for a red check, carries its `findings[]` (see [Errors](#errors)). The engine
+checks on every run, so no `check()` is needed first to be protected or taught.
+
+### Workflow inputs
+
+`inputs` binds the workflow's declared `inputs:` by name, and means the same
+thing on both transports:
+
+```ts
+const run = await nika.run('support-triage.nika', {
+  inputs: { ticketId: '42' },
+  // idempotencyKey: `triage-${ticket.id}`, // HTTP only
+});
+```
+
+Values are strict JSON and stay literal. `'42'` stays a string and `42` a
+number; `'@env:HOME'` and `'${{ tasks.x.output }}'` are text, never read from
+the environment or evaluated; nothing is coerced to the declared type. The
+engine owns the verdict and refuses before any run exists: an undeclared key
+(`unknown_input`), a value that does not fit its declared type
+(`input_type_mismatch`), a required input left out (`NIKA-1708`). Each rejects
+`run()` as a `NikaOperationError` with that code, native (`status: 3`) or HTTP
+(`status: 422`). Supplied values are recorded with `api-caller` provenance;
+declared defaults keep `file`.
+
+The SDK refuses, before it spawns or sends anything, a value JSON would
+silently lose: `undefined`, a function, a symbol, a bigint, `NaN` or
+`Infinity`, a cycle, a class instance (a `Date`, a `Map`), an object whose
+prototype only claims to be plain, an array hole, an accessor. That is a
+`NikaConfigurationError` naming the path (`inputs.ticket.tags[1] is
+undefined`), never the value. No caller code runs while the map is judged: a
+getter is never invoked, and a `Proxy` is refused before it is read, so none
+of its traps run. The serialized map is
+bounded at 1 MiB on both transports. Do not put a secret in `inputs`.
+
+The engine must advertise the channel, and the SDK checks before admission:
+
+- Native: `inputsLiteral` in `nika --sdk-identity`. The map rides the engine's
+  stdin (`nika run --inputs-json -`), so a value never appears in a process
+  listing.
+- HTTP: `jobInputs` in `GET /health`, for a workflow run by its served name.
+  An execution snapshot froze its inputs and takes no overlay, so an HTTP run
+  of a local path (`./flow.nika`) refuses `inputs`, an empty map included.
+
+An engine without the capability rejects with `NikaCompatibilityError`
+(`capability: 'inputsLiteral'` or `'jobInputs'`) and nothing runs. The SDK
+never falls back to `--var`, and a resident that merely answers 202 has
+negotiated nothing: one from before the envelope accepts the field and ignores
+its values. The engine payload pinned by this package version advertises
+neither capability yet, so `inputs` is refused on it until the pin moves.
+
+`vars` is deprecated. It remains the native `--var KEY=VALUE` operator channel,
+unchanged: the engine reads `@env:NAME` from its environment and coerces text
+to the declared type, so it cannot carry literal values and has no HTTP form.
+`inputs` and `vars` together reject `run()`; they are never merged.
 An admitted workflow failure is result data with `status: "failed"` and, when
 the engine named the failing task, `error: { code, message, task }`; transport,
 protocol, configuration, and compatibility failures throw typed SDK errors.
-A `try { await run.done } catch {}` alone therefore never catches a failed
+A `try { await run.result() } catch {}` alone therefore never catches a failed
 workflow: a CI job or an application must read `result.status` and treat
 anything but `succeeded` as its own failure, or a red run passes silently.
 
+On the development branch, `isNikaRunSucceeded` provides that TypeScript
+narrowing. It is **unreleased** and is not exported by the published
+`0.118.7` package; that package uses `result.status === 'succeeded'` directly.
+For CI built from this branch:
+
+```ts
+import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika';
+
+const run = await new Nika().run<{ answer: number }>('flow.nika');
+const result = await run.result();
+if (isNikaRunSucceeded(result)) {
+  console.log(result.outputs?.answer); // outputs stay typed and optional
+} else {
+  console.error(result.status, result.error?.code, result.error?.message);
+  process.exitCode = 1;
+}
+```
+
+A paused result is a human gate, not a successful completion and not a
+failure. It arrives as a `run.waiting` event, never as `run.settled`, and
+`result.status` keeps the engine's word, `paused`. Applications can render
+that state separately; a CI job awaiting completion must not pass it as
+success. The guard reads the engine's status and never turns absent outputs
+into a fabricated output map.
+
+## Why this door
+
+- **Audited before it runs.** `check()` returns the engine's verdict on the
+  order of effects, the permits, the lethal trifecta, the journey of every
+  secret and the cost floor. A red check never becomes a run.
+- **Sovereign by default.** The same file runs on local models (Ollama,
+  llama.cpp, vLLM), on Mistral, Hugging Face, OpenAI, xAI, Anthropic and the
+  rest of the engine's catalog; `mock/echo` rehearses with no key and no
+  network.
+- **Traced after.** Every native run leaves a hash-chained journal and hands
+  back a receipt; `traceVerify()` asks the engine to verify it. The SDK never
+  re-implements the proof.
+- **One vocabulary, two transports.** `check`, `run`, `events`, `cancel`,
+  `traceVerify` and `schedule` read the same against a local process and an
+  authenticated `nika serve`; only the constructor changes. Run events carry
+  the same lifecycle words on both (`run.started`, `run.waiting`,
+  `run.settled`), with the engine's own frame kept on `event.raw`.
+
+## One vocabulary
+
+`Nika` exposes `check`, `run`, `attachRun`, `traceVerify`, `listWorkflows`,
+`workflow`, `schedule`, and `scheduleStatus`. The `NikaRun` it returns owns the
+run's lifecycle:
+
+```
+NikaRun
+├── id
+├── events()   one lifecycle vocabulary · event.raw keeps the protocol frame
+├── result()   the one settlement · admitted failure is data, never a throw
+├── status()   durable over HTTP · a typed refusal on a native process
+└── cancel()   idempotent
+```
+
+`nika.events(run)`, `nika.cancel(run)` and `nika.status(run)` remain as
+deprecated wrappers for one release train, counted from the first published
+train that carries this API; see
+[Migrating to the Run-owned lifecycle](#migrating-to-the-run-owned-lifecycle).
+The handle owns observation, settlement, `status` and cancellation and nothing
+else: checking, proof, catalogs and authoring stay on `Nika`.
+
+The engine remains authoritative for parsing, admission, execution, receipts,
+traces, permits, scheduling, and cost. The SDK transports those facts; it does
+not parse YAML or reconstruct proof in TypeScript.
+
+## Requirements
+
+- Node.js 22 or newer (the tested floor; an older major is unsupported, not
+  refused, and `npm install` does not warn about it)
+- for native execution or local snapshot capture, a compatible `nika` engine, resolved from `config.bin`, then `NIKA_BIN`
+  (absolute paths only), then the exact optional platform package; a bare
+  name or a relative path is refused because the operating system would
+  resolve it through `PATH` or the working directory, and a `nika` found on
+  `PATH` is deliberately never used
+- a `.nika` workflow
+
+## Documentation
+
+- [Architecture](docs/architecture.md) · Modules, Interface, Seam, Adapters,
+  lifecycle, and authority boundaries
+- [HTTP contract](docs/http-api.md) · every live route, recovery, security,
+  idempotency, and schedule CAS
+- [Testing and release evidence](docs/testing.md) · layered gauntlets and the
+  Socratic risk matrix
+- [Migrating to 0.116](docs/migrating-to-0.116.md) · the intentional breaking
+  migration to the smaller durable client surface
+- [docs.nika.sh](https://docs.nika.sh) · the language, the engine and the
+  other doors
+
+## Install
+
+Pin the version you tested, then verify the package the project actually
+resolved:
+
+```sh
+npm install @supernovae-st/nika@0.118.7
+node -p "require('@supernovae-st/nika/package.json').version"
+```
+
+This package metadata subpath is exported for CommonJS, ESM build tools and CI
+pin checks. It reports the installed dependency, not a moving registry tag.
+The native payloads `@supernovae-st/nika-<os>-<arch>` are optional
+dependencies; npm installs the one that matches your platform.
+
+Earlier packages expose the retired `LocalNika`/HTTP split and do not
+implement the root facade documented here. This package carries the product's
+name: up to 0.115.0 it was published as `@supernovae-st/nika-client`. That
+name receives no further releases from this repository and stays installable
+for the versions it already holds. It is **not** marked deprecated on the npm
+registry: its published versions carry no `deprecated` field, so `npm install
+@supernovae-st/nika-client` still succeeds without a warning and installs the
+retired 0.115.0 API. The move to the new name says nothing about the
+registry; check it yourself with `npm view @supernovae-st/nika-client
+deprecated`. The repository keeps its name (`supernovae-st/nika-client`).
+
+## Scaffold with the engine
+
+The lowest-friction creation door is the engine-owned scaffold:
+
+```sh
+./node_modules/.bin/nika init --project-file
+./node_modules/.bin/nika new 01-hello hello.nika
+```
+
+`nika.yaml` is the project control plane. `hello.nika` is executable
+workflow intent and is the file passed to `check()` and `run()`. The scaffold
+writes the engine's own annotated `01-hello` example (its task is named
+`greet` and its prompt asks for French); the contract this README relies on is
+the `outputs.greeting` key and the `mock/echo` model, which the hand-written
+file above satisfies too.
+
 ## Verify a local trace
 
 Local terminal results carry an engine-issued receipt when tracing is enabled.
@@ -181,33 +371,36 @@ into SDK configuration, source control, workflow inputs, or an HTTP request.
 ## Cancel a run
 
 ```ts
-const run = await nika.run('slow.nika.yaml');
-const cancellation = await nika.cancel(run);
-const result = await run.done;
+const run = await nika.run('slow.nika');
+const cancellation = await run.cancel();
+const result = await run.result();
 
 console.log(cancellation.accepted, result.status);
 ```
 
-Cancellation is idempotent per `NikaRun`. An `AbortSignal` passed to `check`,
-`events`, or `traceVerify` only stops that request or observer; it never stands
-in for `cancel(run)`.
+Cancellation is idempotent per `NikaRun`: every `run.cancel()` returns the one
+request. An `AbortSignal` passed to `check`, `events`, or `traceVerify` only
+stops that request or observer; it never stands in for `run.cancel()`.
 
 Over HTTP a running job answers the request with 202: `cancellation` reads
-`{ accepted: true, status: 'cancellation_requested' }` and `run.done` settles
-on the terminal the resident records, `cancelled`, `succeeded`, `failed`, or
-`interrupted` once its grace expired. A job that already ended replays its
-result with `accepted: false` and `status: 'already_settled'`. The native
-transport signals its process the same way and settles `interrupted`.
+`{ accepted: true, status: 'cancellation_requested' }` and `run.result()`
+settles on the terminal the resident records, `cancelled`, `succeeded`,
+`failed`, or `interrupted` once its grace expired. A job that already ended
+replays its result with `accepted: false` and `status: 'already_settled'`. The
+native transport signals its process the same way; the result is whatever the
+engine then wrote, `cancelled` when it settled the request (the released
+0.118.7 engine does), or `interrupted` when the process ended with no
+settlement frame.
 
 ## Connect to `nika serve`
 
-A contained workflow name such as `hello.nika.yaml` or
-`daily/report.nika.yaml` is resolved by the resident registry. `check()` and
+A contained workflow name such as `hello.nika` or
+`daily/report.nika` is resolved by the resident registry. `check()` and
 `run()` send that name without a local engine or a local workflow file.
 Use `listWorkflows()` to discover the served names.
 
 To capture your local file instead, pass an explicit path such as
-`./hello.nika.yaml`. The compatible local engine captures an immutable
+`./hello.nika`. The compatible local engine captures an immutable
 snapshot, and the SDK sends its exact bytes and verifies the acknowledgement.
 Only this path needs `bin`, `NIKA_BIN`, or the exact optional native package.
 Observation and scheduling also use the server identity alone.
@@ -250,16 +443,27 @@ const nika = new Nika({
   // bin: '/absolute/path/to/nika',
 });
 
-const report = await nika.check('hello.nika.yaml');
-const run = await nika.run('hello.nika.yaml', {
-  idempotencyKey: 'hello-2026-08-30',
+const report = await nika.check('hello.nika');
+const run = await nika.run('hello.nika', {
+  idempotencyKey: 'hello-2026-08-30', // persist before admission; reuse on retry
 });
-for await (const event of nika.events(run)) {
+for await (const event of run.events()) {
   console.log(event.sequence, event.kind, event.status);
 }
-console.log(await run.done);
+console.log(await run.result());
 ```
 
+The application code after `new Nika(...)` is the same as the local one: the
+events read `run.started` then `run.settled`, in the same words. The resident
+streams no per-task frame today, so an HTTP run yields no `task.*` event; the
+SDK never invents one. `event.sequence` is the resident's replay cursor and
+exists only over HTTP.
+
+HTTP `run()` requires a caller-owned `idempotencyKey` before it sends a request.
+Persist a unique key for each business operation. If the response is lost or times
+out, retry the same request with that key; a new key can admit a second job.
+Direct native runs omit the key and reject one if supplied.
+
 If the Node process restarts after admission, recover the durable job without
 submitting the workflow again:
 
@@ -267,22 +471,30 @@ submitting the workflow again:
 const recovered = await nika.attachRun(saved.jobId, {
   lastEventId: saved.lastEventSequence,
 });
-for await (const event of nika.events(recovered)) {
+for await (const event of recovered.events()) {
   await saveApplicationCheckpoint(recovered.id, event.sequence);
 }
-console.log(await recovered.done);
+console.log(await recovered.result());
 ```
 
-Persist the job id and last committed sequence in application state. The
+`attachRun` is the one recovery door, and it returns a full `NikaRun`. A run
+handle is process-bound and is not serialized: persist the **job id** and the
+last committed `event.sequence` in application state. That id is durable only
+over HTTP, where `run.id` is the resident's job id. A native `run.id` is an
+ephemeral correlation id of the SDK process: it appears in no journal, cannot
+be recovered after the process ends, and `attachRun` refuses it. The
 idempotency namespace spans the server's entire `state-root` and currently has
 no TTL; use globally unique business keys and do not recycle them between
 workflows.
 
 When observation loses connectivity past its retry budget, the SDK performs
-one final durable read before giving up: a terminal record settles `run.done`
-from the workflow's truth, and a still-running record rejects with
-`NikaObservationInterrupted`, whose `lastSequence` feeds
-`attachRun(id, { lastEventId })` to resume.
+one final durable read before giving up: a terminal record settles
+`run.result()` from the workflow's truth, and a still-running record rejects
+with `NikaObservationInterrupted`, whose `lastSequence` feeds
+`attachRun(id, { lastEventId })` to resume. That error is about this client's
+view, not about the run, which may still be running. It is not the engine's
+own `interrupted` state: a resident that lost an execution says so with a
+`run.interrupted` event and `result.status === 'interrupted'`, as data.
 
 Plain HTTP is accepted only for a loopback host (`localhost`, `127.0.0.0/8`,
 `[::1]`), and only when `allowInsecureHttp: true` is explicit. Every other host
@@ -291,8 +503,10 @@ bearer token never leaves the machine in plaintext. A URL may not contain
 credentials, a query, or a fragment, and a 32–512 byte visible-ASCII token is
 mandatory.
 
-Remote snapshots currently do not have request envelopes for per-call `vars`
-or `model`; declare those facts in the workflow. There is no per-run spend
+A remote run by served name carries per-call `inputs` once the resident
+advertises `jobInputs` (see [Workflow inputs](#workflow-inputs)); a snapshot
+takes none. There is no request envelope for `model`, and none for the
+deprecated `vars`: declare a model in the workflow. There is no per-run spend
 bound over HTTP at all today: `maxCostUsd` is refused, the workflow language
 has no budget field, and the resident applies its own server-wide default
 ceiling. Bound a remote run by its model and `max_tokens` until the request
@@ -307,7 +521,7 @@ client refuses `schedule` and `scheduleStatus` because a short-lived process
 cannot honestly own durable schedule state.
 
 ```ts
-const applied = await nika.schedule('hello.nika.yaml', {
+const applied = await nika.schedule('hello.nika', {
   id: 'weekday-hello',
   when: { kind: 'cadence', expression: 'TZ=Europe/Paris 0 9 * * 1-5' },
   maxCostUsd: 0.01,
@@ -319,7 +533,7 @@ const applied = await nika.schedule('hello.nika.yaml', {
 const status = await nika.scheduleStatus('weekday-hello');
 console.log(applied.changed, status.next, status.lastDecision);
 
-await nika.schedule('hello.nika.yaml', {
+await nika.schedule('hello.nika', {
   id: 'weekday-hello',
   when: { kind: 'cadence', expression: 'TZ=Europe/Paris 0 9 * * 1-5' },
   maxCostUsd: 0.01,
@@ -354,18 +568,23 @@ it; a scheduled budget is always a real number.
 | Operation | Native process | HTTP |
 |---|---|---|
 | `check` | yes; `model` and `nativeStrict` allowed | yes; those two overrides refused |
-| `run` | yes; `vars`, `model`, `maxCostUsd` allowed | yes; `idempotencyKey` allowed |
-| `attachRun` | typed refusal | reattach to a durable job with an optional SSE cursor |
-| `status` | typed refusal; await `run.done` | durable status projection |
-| `events` | raw engine lifecycle frames | sequenced SSE frames with bounded replay |
-| `cancel` | signal-backed, idempotent | 200 settles the job; 202 accepts the request and `run.done` settles on the resident's terminal |
+| `run` | yes; `model`, `maxCostUsd` allowed | yes; `idempotencyKey` required; `model`, `maxCostUsd` refused |
+| `run` `inputs` | literal JSON over stdin; engine must advertise `inputsLiteral` | literal JSON by served name; resident must advertise `jobInputs`; a snapshot refuses them |
+| `run` `vars` (deprecated) | the `--var` operator channel, unchanged | typed refusal |
+| `attachRun` | typed refusal: a native run is process-bound | reattach to a durable job with an optional SSE cursor |
+| `run.status()` | typed refusal; await `run.result()` | durable status projection |
+| `run.events()` | lifecycle words over the engine's task and run frames | the same lifecycle words over sequenced SSE frames with bounded replay; no per-task frame |
+| `run.cancel()` | signal-backed, idempotent | 200 settles the job; 202 accepts the request and `run.result()` settles on the resident's terminal |
+| `run.id` | ephemeral correlation id; never durable | the resident's durable job id; the one to persist |
 | `traceVerify` | engine verification + signed receipt binding | typed verdict: `unavailable` until remote journal authority exists, then the CLI's tiers |
 | `schedule` / `scheduleStatus` | typed refusal | resident schedule authority |
 | `listWorkflows` / `workflow` | typed refusal | contained path-free workflow catalog |
 
-Event vocabulary is deliberately open. Native execution exposes detailed task
-lifecycle frames; HTTP exposes durable sequenced execution frames. Consumers
-must not assume identical cardinality across transports.
+The lifecycle vocabulary is one; the cardinality is not. Native execution
+exposes detailed task frames, HTTP exposes durable sequenced execution frames,
+and the SDK names only the facts a transport actually emitted. Consumers must
+not assume identical cardinality across transports. The protocol vocabulary
+under `event.raw` stays deliberately open.
 
 ## API
 
@@ -375,7 +594,9 @@ Shared options:
 
 - `cwd`: engine working directory and snapshot root
 - `bin`: explicit engine path
-- `eventBufferSize`: per-client observer ceiling, default 256
+- `eventBufferSize`: how many of a run's most recent frames a session retains
+  for a view opened after the fact, and the largest `bufferSize` a view may
+  ask for; default 4096. See [Observing a run after the fact](#observing-a-run-after-the-fact)
 - `machineBufferBytes`: machine frame/diagnostic ceiling, default 64 KiB
 
 Remote-only options:
@@ -390,21 +611,197 @@ Remote-only options:
 | Method | Result |
 |---|---|
 | `check(workflow, options?)` | `clean` plus the native check report or resident acknowledgement/refusal |
-| `run(workflow, options?)` | admitted `NikaRun` |
-| `attachRun(id, options?)` | reattached durable HTTP `NikaRun` |
-| `status(run)` | current durable HTTP status |
-| `events(run, options?)` | bounded `AsyncIterable<NikaEvent>` |
-| `cancel(run)` | `NikaCancelResult` |
+| `run(workflow, options?)` | admitted `NikaRun`; rejects without one when the engine refuses |
+| `attachRun(id, options?)` | reattached durable HTTP `NikaRun`: the one recovery door |
 | `traceVerify(receipt, options?)` | `NikaTraceVerifyResult` |
 | `schedule(workflow, options)` | durable apply acknowledgement |
 | `scheduleStatus(id)` | fresh engine schedule projection |
 | `listWorkflows()` | contained resident workflow names |
 | `workflow(name)` | path-free resident workflow metadata |
 
-### Typed events, outputs, and identities
+### `NikaRun`
+
+| Member | Result |
+|---|---|
+| `run.id` | `NikaRunId`: the durable job id over HTTP, an ephemeral correlation id natively |
+| `run.events(options?)` | bounded `AsyncIterable<NikaRunEvent>` in the lifecycle vocabulary |
+| `run.result()` | `Promise<NikaRunResult>`, settled once; an admitted failure resolves |
+| `run.status()` | current durable HTTP status; a typed refusal natively |
+| `run.cancel()` | `NikaCancelResult`; idempotent |
+| `run.done` | compatibility alias of `run.result()`: the same promise |
+
+Every member is bound to its run, so it can be extracted:
+`const { events, result } = run`. The handle is process-bound; it carries no
+`list`, `search`, proof, catalog or authoring door.
+
+### Observing a run after the fact
+
+```ts
+const run = await nika.run('wide.nika');
+const result = await run.result();          // first the result,
+for await (const event of run.events()) {}  // then every frame the session saw
+```
+
+A view opened late is seeded with every frame the session observed, or it is
+refused. It is never handed a shortened replay. How many frames a session
+retains is `eventBufferSize`, **4096 by default**.
+
+**The measured frame count: `3N + 3`, for one shape.** On the released 0.118.7
+engine, a clean run of N independent `mock/echo` `infer` tasks wrote
+`workflow_started`, then `task_scheduled`, `task_started` and `task_completed`
+per task, then `workflow_completed` and `run_settled`. Two points were
+measured: 1 task is 6 frames, 90 tasks are 273. That is this fixture, not a
+law of N-task workflows. Other shapes write more: a `nika:wait` task and a
+`nika:assert` task each showed one extra `permit_checked` frame, a failed task
+writes `task_failed`, and retries, agents and `for_each` were not measured.
+Count your own run rather than deriving it: `error.observed` below is the
+number. A `nika serve` job was measured at two frames, so the bound matters on
+a native process.
+
+| `eventBufferSize` | frames retained | in the measured shape only |
+|---|---|---|
+| 256, the default up to 0.118.7 | 256 | below the 273 frames of the 90-task run |
+| 4096, the default | 4096 | 15 times those 273 frames |
+
+**What the bound costs.** It is finite on purpose and is never `Infinity`.
+Every frame is bounded by `machineBufferBytes` (64 KiB), so the retained
+**history** holds at most `eventBufferSize × machineBufferBytes` of frame text:
+4096 × 64 KiB = 256 MiB per run at both defaults, where 256 frames gave
+16 MiB. That is arithmetic, not a measurement: the 273 measured frames total
+0.15 MiB (mean 571 bytes, largest 1501). It bounds the history only, not the
+session or the process: a frame already handed to your code lives as long as
+you keep it, and every open view and every concurrent run adds its own. Nothing
+here is a claim about heap or process memory. If that ceiling matters to you,
+set `eventBufferSize` yourself: an explicit value is kept exactly as given, so
+`eventBufferSize: 256` behaves as it always did.
+
+**Past the bound.** A run that writes more frames than the bound still runs and
+still succeeds: `run.result()` resolves as usual and is never affected. Only a
+view is refused, with `NikaEventBufferOverflowError`, and its `reason` says
+which of two different bounds was exceeded:
+
+| `error.reason` | What happened | What to do |
+|---|---|---|
+| `replay_truncated` | the view was opened after the run had produced more frames (`error.observed`) than it can be given (`error.limit`); `error.retained` is how many the session still holds | when `retained === observed` nothing is lost: open the view with `bufferSize >= observed`. Otherwise the earlier frames are gone from this process: set `eventBufferSize >= observed` for the next run, or observe it live |
+| `live_backpressure` | a view that was observing live fell more than `error.limit` frames behind the stream | read faster, or raise that view's `bufferSize`. Other views and the result are unaffected |
+
+```ts
+try {
+  for await (const event of run.events()) render(event);
+} catch (error) {
+  if (error instanceof NikaEventBufferOverflowError && error.reason === 'replay_truncated') {
+    // The run is fine. Its history is longer than this view can replay.
+    console.warn(`${error.observed} frames, ${error.retained} retained; run ${result.status}`);
+  } else throw error;
+}
+```
+
+Neither refusal skips a frame, and neither is about the run. `error.observed`
+is a count taken when the view was opened. The engine's journal stays the
+source of truth for a native trace (`receipt.trace_path`, `traceVerify`): a
+late `run.events()` is a convenience over what this process already saw, and
+the SDK reads no journal to extend it. Over HTTP the resident holds the job,
+so recover there with `attachRun(id, { lastEventId })`.
+
+### The lifecycle vocabulary
+
+`run.events()` yields `NikaRunEvent`: a lifecycle `kind` that is the same on
+both transports, plus the exact protocol frame on `raw`.
+
+| `event.kind` | Native frame (`event.raw.kind`) | HTTP frame (`event.raw.kind`) |
+|---|---|---|
+| `run.started` | `workflow_started` | `execution.started` |
+| `task.scheduled` · `task.started` · `task.completed` · `task.failed` | `task_scheduled` · `task_started` · `task_completed` · `task_failed` | none: the resident streams no per-task frame |
+| `run.waiting` | `run_settled` carrying `paused` | `execution.settled` carrying `paused` |
+| `run.settled` | `run_settled` carrying `succeeded` · `failed` · `cancelled` | `execution.settled` carrying `succeeded` · `failed` · `cancelled`; `execution.cancelled` carrying `cancelled` only; `execution.refused` carrying `failed` only |
+| `run.interrupted` | `workflow_interrupted` carrying `interrupted` | `execution.interrupted` · `interrupted` carrying `interrupted` |
+| `run.sealed` | `run_sealed` | none |
+| `engine.event` | every other frame (`workflow_completed`, `workflow_paused`, `permit_checked`, …) | every other frame, a `null` or future kind included |
+
+The SDK names a fact only when the engine wrote it. A frame that speaks of the
+run's state earns its name only for a (kind, status) pair a producer defines;
+the pairs are the ones listed above and nothing is computed from them. The
+engine's state word decides and is never defaulted, so an absent, null, future
+or still-running status stays an `engine.event`, and so does a terminal word
+on the wrong dedicated kind: `execution.refused` carrying `succeeded` or
+`cancelled`, or `execution.cancelled` carrying `succeeded` or `failed`,
+contradicts itself and is never called settled. `event.raw` still holds that
+frame, and `run.result()` still reads the state word the engine wrote. The
+projection keeps no state between frames, deduplicates nothing, and never
+synthesizes an event, so transports differ in cardinality but never in names.
+
+```ts
+for await (const event of run.events()) {
+  switch (event.kind) {
+    case 'run.started': break;
+    case 'task.completed': console.log('done:', event.task); break;
+    case 'task.failed': console.error(event.task, event.error?.code); break;
+    case 'run.waiting': console.log('a human gate holds the run'); break;
+    case 'run.settled': console.log('ended:', event.status); break;
+    case 'run.interrupted': console.warn('the engine lost this execution'); break;
+    default: break; // additive vocabulary: event.raw.kind names the frame
+  }
+}
+```
+
+`event.status` is always the engine's own word (a waiting run reads `paused`);
+`event.task` is the task a `task.*` frame named; `event.error` is the failure
+a `task.failed` frame or a `failed` settlement named, and no other state
+carries one; `event.sequence` is the resident's replay cursor and exists only
+over HTTP.
+An `engine.event` is given no lifecycle meaning: it carries its cursor and
+`raw`, never a `status`.
+
+`run.waiting` is not `run.settled`: a human gate holds a resumable run, which
+has neither failed nor completed. `run.interrupted` is the engine's report
+that it lost an execution, whose settlement is unknown; it is unrelated to
+the thrown `NikaObservationInterrupted`, which means this client lost its view
+of a run that may still be running.
+
+### Migrating to the Run-owned lifecycle
+
+The client-level lifecycle methods are deprecated and stay for one release
+train. They keep the ownership check: a run this client did not create still
+throws `NikaRunOwnershipError`, because there is no global run registry.
+
+**The compatibility window.** A release train is one published
+SDK-and-engine version, the meaning this repository already uses (see
+[Keeping it fresh](#keeping-it-fresh)). The window is counted from
+publication, never from a merge:
+
+1. It opens with the first train **published to npm** whose package carries
+   the Run-owned lifecycle. That train ships the wrappers, unchanged, next to
+   the new API.
+2. The earliest train that may remove them is the one **after** it. Removal
+   is not automatic: it is decided by the One SDK baseline owner
+   ([#114](https://github.com/supernovae-st/nika-client/issues/114)) and is
+   announced in the release notes of the train that performs it.
+3. No version and no date are fixed here. Until a train carrying this API is
+   published, nothing has started counting and the wrappers stay.
+
+| Deprecated | Use | What changes |
+|---|---|---|
+| `nika.events(run, options?)` | `run.events(options?)` | lifecycle `kind`; the protocol frame the wrapper yields is `event.raw` |
+| `nika.cancel(run)` | `run.cancel()` | nothing: the same memoized request |
+| `nika.status(run)` | `run.status()` | nothing |
+| `await run.done` | `await run.result()` | nothing: `done` stays as an alias of the same promise |
 
-`NikaEvent` is a discriminated union over the known lifecycle kinds of both
-transports. A native engine process emits `workflow_started`,
+`nika.events(run)` still yields the protocol vocabulary exactly as before, so
+existing consumers keep working unchanged while they migrate:
+
+```ts
+// before                                     // after
+for await (const e of nika.events(run)) {     for await (const e of run.events()) {
+  if (e.kind === 'workflow_started' ||          if (e.kind === 'run.started') start();
+      e.kind === 'execution.started') start();
+}                                             }
+```
+
+### Typed protocol events, outputs, and identities
+
+`NikaEvent` is the protocol frame under `event.raw` (and what the deprecated
+`nika.events(run)` yields): a discriminated union over the known protocol
+kinds of both transports. A native engine process emits `workflow_started`,
 `task_scheduled`, `task_started`, `task_completed`, `workflow_completed`,
 `workflow_failed`, `workflow_interrupted`, `run_settled`, and `run_sealed`. A
 `nika serve` job streams `execution.started`, `execution.settled`,
@@ -414,36 +811,36 @@ this SDK version does not know yet stay representable through the
 `NikaUnknownEvent` fallback, so the union is intentionally non-exhaustive and
 every variant keeps its future fields open.
 
-`run`, `attachRun`, and `events` accept one `Outputs` type argument. It types
-the terminal settlement — `run.done` and the `run_settled` /
-`execution.settled` / `workflow_completed` frames — without any runtime
-validation, and defaults to `Record<string, unknown>` so untyped callers see
-no change:
+`run` and `attachRun` accept one `Outputs` type argument. It types the
+terminal settlement — `run.result()` and, on the protocol frame, the
+`run_settled` / `execution.settled` / `workflow_completed` frames — without
+any runtime validation, and defaults to `Record<string, unknown>` so untyped
+callers see no change:
 
 ```ts
-const run = await nika.run<{ answer: number }>('flow.nika.yaml');
-const result = await run.done;          // result.outputs?: { answer: number }
+const run = await nika.run<{ answer: number }>('flow.nika');
+const result = await run.result();      // result.outputs?: { answer: number }
 
-for await (const event of nika.events(run)) {
-  if (isNikaRunSettledEvent(event)) {
+for await (const event of run.events()) {
+  if (isNikaRunSettledEvent(event.raw)) {
     // The settlement frame of either transport (`run_settled` natively,
     // `execution.settled` over HTTP): status, outputs, and receipt typed
     // together on the one frame that carries all three.
-    console.log(event.status, event.outputs?.answer, event.receipt);
+    console.log(event.raw.status, event.raw.outputs?.answer, event.raw.receipt);
   }
 }
 ```
 
-A run can also end without settling outputs — cancelled, refused, or
-interrupted. `isNikaTerminalEvent(event)` narrows those too: it reads the
-engine-reported `status` (`succeeded`, `failed`, `interrupted`, `cancelled`)
-rather than the kind, so it holds on either transport and on kinds this SDK
-version does not know yet:
+The protocol guards read `event.raw`. A run can also end without settling
+outputs — cancelled, refused, or interrupted. `isNikaTerminalEvent(event.raw)`
+narrows those too: it reads the engine-reported `status` (`succeeded`,
+`failed`, `interrupted`, `cancelled`) rather than the kind, so it holds on
+either transport and on kinds this SDK version does not know yet:
 
 ```ts
-for await (const event of nika.events(run)) {
-  if (isNikaTerminalEvent(event)) {
-    console.log('no further frames for this run:', event.status);
+for await (const event of run.events()) {
+  if (isNikaTerminalEvent(event.raw)) {
+    console.log('no further frames for this run:', event.raw.status);
   }
 }
 ```
@@ -479,6 +876,12 @@ NikaError
 └── NikaRunOwnershipError
 ```
 
+`NikaEventBufferOverflowError` is never about the run: `run.result()` is
+unaffected by it. Its `reason` tells a live view that fell behind
+(`live_backpressure`) from a view opened after more frames than it can replay
+(`replay_truncated`, with `observed` and `retained`); see
+[Observing a run after the fact](#observing-a-run-after-the-fact).
+
 Native engine event vocabulary stays open. HTTP events instead enforce the
 closed, redacted `JobEvent` projection advertised by the pinned OpenAPI contract;
 unknown HTTP fields are rejected at the trust boundary. The SDK never turns an
@@ -492,9 +895,37 @@ Server messages are engine-owned and path-free; a reflected bearer token is
 redacted before it reaches an error message. A non-2xx answer without that
 typed body stays a `NikaTransportError` whose body is redacted entirely.
 
-An engine refusal printed before a run starts — a `NIKA-…` code line such as a
-cost-floor refusal — settles `run.done` with a `NikaOperationError` carrying
-`operation: 'run'`, the engine's code, and its full refusal line.
+A native engine refuses a workflow before admitting it: a red check, a cost
+floor above `maxCostUsd`, a required input left unset, a file it cannot read.
+`run()` then rejects, before any `NikaRun` exists, with a `NikaOperationError`
+carrying `operation: 'run'` and the engine's exit status in `status`:
+
+```ts
+try {
+  const run = await nika.run('./workflow.nika');
+  const result = await run.result(); // admitted: a failure here is result data
+} catch (error) {
+  if (error instanceof NikaOperationError && error.operation === 'run') {
+    console.error(error.code); // 'NIKA-SEC-004'
+    for (const finding of error.findings ?? []) console.error(finding.message);
+  } else throw error;
+}
+```
+
+- `code` is the engine's own code: the first check finding that names one
+  (`NIKA-SEC-004`, `NIKA-PARSE-005`, `NIKA-AUTH-006`, …) or the refusal's code
+  (`NIKA-1709`, `NIKA-1708`). `machineCode` repeats it. When the engine named
+  none, as for an unreadable file, `code` is the SDK's `run_refused` and
+  `machineCode` is absent; the SDK never supplies an engine code.
+- `findings` holds the engine's check findings untouched, as
+  `NikaCheckFinding` (`code?`, `message`, `severity`, `gate`, `kind`, `task`,
+  `docs_url`). A budget or launch refusal has no findings.
+- Nothing was admitted, so nothing else exists: no run id, no events, no
+  trace, no receipt.
+
+Output that proves neither an admission nor a refusal (a line that is not
+machine output, a truncated or oversized report, an engine that exits without
+a frame) rejects `run()` with `NikaProtocolError` instead.
 
 ## Security boundaries
 
@@ -549,7 +980,7 @@ npm update @supernovae-st/nika
 ⚙️ nika ───────── engine, admission, execution, receipts and schedules
     │
     ▼
-🔌 nika-client ── this TypeScript door: native process or authenticated HTTP
+🔌 nika-client ── this door, published as @supernovae-st/nika: native process or authenticated HTTP
     │
     ▼
 🧩 Node.js applications