@supernovae-st/nika 0.118.7 → 0.120.2

package/docs/architecture.md

@@ -26,14 +26,28 @@ local nika process         authenticated nika serve
   Adapters must implement and makes unsupported authority explicit.
 - `src/lib/native-process-transport.ts` is the local Adapter. It spawns the
   selected engine without a shell and consumes newline-delimited machine
-  events.
+  events. It reads the first machine frame before it returns a run, so
+  `run()` resolves on the engine's admission and rejects on its refusal.
+- `src/lib/run-refusal.ts` reads the engine's one pre-run refusal object (its
+  check report carrying `clean: false`, or its `{ error }` envelope) and turns
+  it into the typed `NikaOperationError`. It judges nothing: a shape the
+  engine was not measured to write is a protocol fault, never a refusal.
+- `src/lib/legacy-run-refusals.ts` is temporary. It recovers the three refusal
+  dialects of engines up to 0.119.0, which predate the one `run --json`
+  grammar, and is deleted with its call sites once no supported engine writes
+  them.
 - `src/lib/http-transport.ts` is the remote Adapter. It verifies the remote
   server identity once per client, resolves and verifies a local engine only
   for caller-owned snapshot capture, then uses the authenticated HTTP
   contract.
 - `src/lib/run-session.ts` is the lifecycle Seam. It owns the eager event
   pump, bounded independent observers, cancellation memoization, and the sole
-  terminal `run.done` settlement.
+  terminal settlement. It builds the `NikaRun` handle as closures over itself,
+  so the Run owns `events()`, `result()`, `status()` and `cancel()`.
+- `src/lib/run-events.ts` is the semantic Adapter: a pure projection of one
+  protocol frame onto the SDK's lifecycle vocabulary, with the frame kept by
+  identity on `raw`. It is applied at the edge of an observer view. There is
+  one history and one bounded queue per observer, and no second event bus.
 - `openapi.json` and `src/generated/openapi.d.ts` pin the HTTP contract judged
   by CI. `scripts/check-sdk-coverage.js` fails if a live runtime path is
   missing or if the SDK names a path outside that contract.
@@ -62,19 +76,68 @@ Some operations deliberately have one authority:
 ## Lifecycle invariants
 
 1. `run()` resolves only after stable admission and returns an immutable
-   `{ id, done }` handle.
-2. `run.done` is the only terminal promise. Workflow failure is result data;
-   configuration, transport, protocol, and compatibility failures throw.
-3. `events(run)` creates an independent bounded observer. Aborting an observer
-   never cancels the run.
-4. `cancel(run)` is idempotent per owned run handle.
-5. `status(run)` reads the durable HTTP projection and refuses a native-only
+   `NikaRun` handle: `id`, `events()`, `result()`, `status()`, `cancel()`, and
+   `done`, the compatibility alias of `result()`. Admission is not execution;
+   a succeeded `result()` is not a sealed receipt (`traceVerify` can return
+   `receipt_mismatch` on an UNSEALED journal). Its members are closures
+   over the run's one session, so an extracted method still works. The handle
+   owns the lifecycle and nothing else: checking, proof, catalogs and
+   authoring stay on the facade. A run handle never means "maybe a run": a refusal
+   before admission rejects `run()` with `NikaOperationError` and no handle
+   exists. Over HTTP a red local snapshot refuses before any request is sent;
+   on the native transport the first machine frame decides. A run event is the
+   engine's admission evidence and is replayed as the first event; a refusal
+   object is the whole stream. The one spawn that executes the workflow is the
+   one that judges it: the SDK adds no preflight check and never spawns twice.
+2. `run.result()` is the only terminal promise (`run.done` is the same one).
+   Workflow failure is result data; configuration, transport, protocol, and
+   compatibility failures throw. A `paused` result is a human gate: neither a
+   failure nor a completed execution.
+3. A session's history retains at most `eventBufferSize` frames (default 4096,
+   never unbounded; each frame is bounded by `machineBufferBytes`). That
+   product bounds the retained history only, not the session or the process:
+   frames already handed to a consumer, other views and other runs are not
+   counted in it. Two different
+   bounds can be exceeded and they are never confused: a live view that falls
+   behind fails with `reason: 'live_backpressure'`, and a view opened after
+   more frames than it can be given is refused with
+   `reason: 'replay_truncated'` plus what was `observed` and `retained`.
+   Neither skips a frame, neither touches another view, and neither touches
+   the result: a run longer than the bound still settles normally. The
+   session is memory over what this process saw. It is not a control plane,
+   keeps nothing on disk, and reads no engine journal to extend a replay.
+   `run.events()` creates an independent bounded observer in the lifecycle
+   vocabulary. Aborting an observer never cancels the run. The vocabulary is a
+   stateless per-frame projection: it names a fact only for a (kind, status)
+   pair a producer defines, never defaults a state word, never deduplicates,
+   and never synthesizes a frame a transport did not emit. Every other frame
+   keeps flowing as `engine.event`, so transports differ in cardinality but
+   never in names, and `event.raw` is always the untouched protocol frame.
+4. `run.cancel()` is idempotent per run: every call returns the one request.
+5. `run.status()` reads the durable HTTP projection and refuses a native-only
    run instead of guessing from local process state.
 6. Schedule creation uses `If-None-Match: *`; updates require the exact opaque
    revision in `If-Match`.
-7. `attachRun()` creates a fresh owned session for an existing HTTP job; its
-   initial sequence is caller-owned durable checkpoint state, never inferred
-   from in-memory SDK history.
+7. `attachRun()` is the one recovery door. It creates a fresh owned session
+   for an existing HTTP job; its initial sequence is caller-owned durable
+   checkpoint state, never inferred from in-memory SDK history. A native run
+   is process-bound: its `run.id` is an ephemeral correlation id, and the SDK
+   keeps no local job store, starts no hidden `nika serve`, and reads no
+   journal to fake durability.
+8. Ownership has no registry. The facade maps each handle it created to its
+   session in a `WeakMap`. The deprecated `nika.events(run)`,
+   `nika.cancel(run)` and `nika.status(run)` wrappers resolve through it, so a
+   foreign, reconstructed, serialized, or other-client handle still throws
+   `NikaRunOwnershipError`. `nika.events(run)` keeps yielding the protocol
+   vocabulary unchanged. The wrappers stay for one release train counted from
+   publication: they ship unchanged in the first published train that carries
+   the Run-owned lifecycle, the earliest train that may remove them is the one
+   after it, and the removal is the One SDK baseline owner's decision (#114),
+   announced in that train's release notes. No version or date is fixed.
+9. An interrupted observation is a typed transport error carrying its cursor
+   (`NikaObservationInterrupted`), never an engine failure: the run may still
+   be running. The engine's own `interrupted` evidence state is data instead:
+   a `run.interrupted` event and `result.status === 'interrupted'`.
 
 ## Deletion test
 

package/docs/http-api.md

@@ -18,9 +18,9 @@ Any other non-2xx body is discarded and reported as a redacted
 | `POST /v1/check` | `check()` | validates a served name or immutable snapshot bytes without a job |
 | `POST /v1/jobs` | `run()` | admits a served name or exact snapshot bytes with an idempotency key |
 | `GET /v1/jobs/{id}` | internal settlement | durable job identity, outputs, receipt, settlement, or redacted error |
-| `GET /v1/jobs/{id}/status` | `status(run)` | current status only |
-| `GET /v1/jobs/{id}/events` | `events(run)` / `attachRun()` | bounded, sequenced SSE with replay |
-| `POST /v1/jobs/{id}/cancel` | `cancel(run)` | 200 a settled job or its terminal replay; 202 the request accepted on a running job, settled later by observation |
+| `GET /v1/jobs/{id}/status` | `run.status()` | current status only |
+| `GET /v1/jobs/{id}/events` | `run.events()` / `attachRun()` | bounded, sequenced SSE with replay |
+| `POST /v1/jobs/{id}/cancel` | `run.cancel()` | 200 a settled job or its terminal replay; 202 the request accepted on a running job, settled later by observation |
 | `GET /v1/jobs/{id}/trace/verify` | `traceVerify(receipt)` | engine-owned typed trace verdict; `reason` only on a verdict that does not hold |
 | `GET/PUT /v1/schedules/{id}` | `scheduleStatus()` / `schedule()` | resident schedule projection and CAS mutation |
 
@@ -35,12 +35,25 @@ Any other non-2xx body is discarded and reported as a redacted
 - Each request has a bounded timeout and each JSON/SSE machine frame has a
   byte ceiling.
 - Remote `check()` refuses `model` and `nativeStrict`; remote `run()` refuses
-  `vars`, `model`, and `maxCostUsd` until the request envelope owns them.
+  `model`, `maxCostUsd` and the deprecated `vars` until a request envelope
+  owns them.
+- Remote `run()` sends `inputs` as `JobByName.inputs` only for a served name
+  and only when `GET /health` advertises `jobInputs`. That capability, not a
+  202, is the negotiation: a resident from before the envelope accepts the
+  extra field and ignores its values, so the SDK refuses it after `/health`
+  alone with `NikaCompatibilityError` (`capability: 'jobInputs'`). The
+  `inputs` envelope is engine-owned (nika#1642) and lands in the pinned
+  `openapi.json` when the engine pin reaches a release that serves it.
+- A snapshot body takes no `inputs` overlay, an empty map included: `run()` of
+  a local path with `inputs` is refused before any capture or request.
+- The serialized `inputs` map is bounded at 1 MiB by the SDK, the bound the
+  native channel reads. The resident's whole-request ceiling is its own and may
+  be lower.
 - Caller-provided workflow catalog names must be contained slash-separated
   paths. Absolute paths, backslashes, empty segments, `.` and `..` are
   rejected before network I/O.
 
-A contained `.nika.yaml` name uses the resident registry without a local
+A contained `.nika` name uses the resident registry without a local
 engine. Prefix a local file with `./` to capture and submit its snapshot.
 A successful by-name check returns `clean: true` and the compact resident
 acknowledgement; no local check report or exit code is fabricated.
@@ -55,6 +68,62 @@ whose `status` contradicts the record carrying it, keeps fields it does not
 know, and never derives a settlement from an exit code; a job the resident
 lost (`interrupted`) carries none.
 
+## Frame time and journal evidence (engine main)
+
+Both resident projections are closed, and the SDK refuses any field it does
+not know. Engine main adds two optional fields that are
+ahead of the pinned `openapi.json`: no released engine writes them yet, and a
+resident that predates them never sends them, so nothing changes against a
+released resident. They are read so that a resident built from engine main can
+be observed at all; the pin itself moves only with a release.
+
+- `JobEvent.at` is when the resident admitted the event: an RFC 3339 timestamp
+  in UTC, outside the event's hash chain. It rides `event.raw.at` untouched.
+  Anything that is not such a timestamp is a `NikaProtocolError`. The durable
+  `Job` declares no `at`, so one there is still an unknown field.
+- `evidence`, on the terminal frame and on the durable `Job`, reports that the
+  run's journal mirror stopped recording. It is exactly a `status` and a
+  `reason`. The one status is `mirror_lost`. The reason is `write_failed`
+  (opening, writing or syncing the journal failed) or `record_refused` (a
+  record could not be admitted within the writer's bounds): a coarse class,
+  never OS text and never a path. Any other shape or word is a
+  `NikaProtocolError`, as the engine itself refuses one, and its value is
+  never quoted in the error.
+
+`evidence` is independent of the execution and is never a verdict: a run can
+settle `succeeded` while its mirror is lost. It never changes `result.status`,
+the settlement, or the receipt's identity checks. `run.result()` copies it to
+`result.evidence` from the frame or record that settled the run, so a caller
+who never iterates events still learns the trace may be incomplete before
+trusting `traceVerify`. Its absence claims nothing: not that a journal exists,
+only that no loss was reported. A native run never carries it.
+
+## Lifecycle vocabulary over the resident's frames
+
+`run.events()` names the resident's closed `JobEvent` frames in the SDK's
+lifecycle vocabulary and keeps each frame on `event.raw`:
+
+| `JobEvent.kind` | `JobEvent.status` | `event.kind` |
+|---|---|---|
+| `execution.started` | any | `run.started` |
+| `execution.settled` | `paused` | `run.waiting` |
+| `execution.settled` | `succeeded` · `failed` · `cancelled` | `run.settled` |
+| `execution.cancelled` | `cancelled` only | `run.settled` |
+| `execution.refused` | `failed` only | `run.settled` |
+| `execution.interrupted` · `interrupted` | `interrupted` | `run.interrupted` |
+| anything else: a `null` or future kind; an end kind whose status is absent, `null`, future, `queued` or `running`; or a pair that contradicts itself (`execution.refused` carrying `succeeded` or `cancelled`, `execution.cancelled` carrying `succeeded` or `failed`, an end kind carrying `interrupted`) | | `engine.event` |
+
+The pairs above are exhaustive and listed, never computed as a product of
+kinds and words. An unnamed frame is still delivered with `event.raw` intact,
+and `run.result()` still reads the state word the engine wrote on it.
+
+The resident streams no per-task frame, so an HTTP run yields no `task.*`
+event: the SDK never synthesizes one. `event.sequence` is the validated SSE
+id, the cursor to persist. The engine's `interrupted` (execution ownership
+was lost, settlement unknown) is data: a `run.interrupted` event and
+`result.status`. It is unrelated to `NikaObservationInterrupted` below, which
+is this client losing its view of a run that may still be running.
+
 ## SSE recovery
 
 The client checks that SSE ids are canonical positive integers and equal
@@ -71,9 +140,13 @@ A cursor means “fully processed”, not merely “received”.
 
 ## Idempotency and schedules
 
-An omitted run idempotency key is generated once per admission. A caller key
-must be 1–255 bytes. Reusing a key with different snapshot bytes is an engine
-conflict, not a retry success.
+HTTP `run()` requires a caller-owned `idempotencyKey` of 1–255 bytes. Omitting
+it throws `NikaConfigurationError` before network I/O or local snapshot capture.
+Persist the key before admission and retry the exact request with the same key
+if the response is lost or times out. The SDK never generates a hidden key or
+retries admission automatically. Reusing a key with different request bytes
+is an engine conflict, not a retry success. Direct native runs still omit the
+key and reject it if supplied.
 
 The namespace is the whole durable job store under the server's configured
 `state-root`, across workflows, clients, schedules, and server restarts. The

package/docs/migrating-to-0.116.md

@@ -64,9 +64,20 @@ invariants; observe or cancel a returned run through its owned lifecycle.
 | `nika.workflows.list()` | `nika.listWorkflows()` |
 | `nika.workflows.metadata(name)` | `nika.workflow(name)` |
 
-The new run handle is intentionally only `{ id, done }`. Methods reject a
-look-alike object from another client, so persist the job id and reattach after
-a process restart instead of rebuilding a handle by hand.
+In 0.116 the run handle was only `{ id, done }`. The Run now owns its
+lifecycle: `run.events()`, `run.result()`, `run.status()` and `run.cancel()`,
+with `run.done` kept as the alias of `run.result()`. The `nika.events(run)`,
+`nika.cancel(run)` and `nika.status(run)` forms this guide shows still work
+unchanged as deprecated wrappers, and `nika.events(run)` still yields the
+protocol vocabulary; `run.events()` yields one lifecycle vocabulary on both
+transports with that frame on `event.raw`. The wrappers stay for one release
+train counted from the first published train that carries the new API, with
+no version or date fixed; "Migrating to the Run-owned lifecycle" in the
+README defines that window.
+
+The client-level methods reject a look-alike object and a run from another
+client, so persist the job id and reattach after a process restart instead of
+rebuilding a handle by hand.
 
 `LocalNika.version()`, `dryRunPlan()`, and `test()` have no One SDK method in
 0.116. Keep those CLI-facing probes in deployment/CI (`nika --version`,
@@ -92,8 +103,12 @@ both versions.
 
 `runToEnd()` returned `{ ok, exitCode, events[] }` with every event buffered.
 `run.done` returns the terminal result only; the events ride `events(run)`
-as a bounded live iterator (default 256), so observe it concurrently or the
-prefix is gone. The removed methods (`version()`, `dryRunPlan()`, path-based
+as a bounded iterator. In 0.116 a session retained 256 frames, below the 273 a
+measured clean native run of 90 `mock/echo` tasks writes, so such a run had to
+be observed concurrently or its prefix was gone. The default is now 4096 and a view opened
+after the result replays every retained frame; past the bound it is refused
+with `reason: 'replay_truncated'`, never shortened, and the result is
+unaffected. An explicit `eventBufferSize` keeps its cap. The removed methods (`version()`, `dryRunPlan()`, path-based
 `traceVerify()`) are absent, not stubbed: calling them throws a plain
 `TypeError: … is not a function`, and a trace that only exists as a file
 path in a later process has no SDK verification door in 0.116.
@@ -111,7 +126,7 @@ These methods require an HTTP client. A native-process client returns a typed
 ## Durable status
 
 ```ts
-const run = await nika.run('flow.nika.yaml');
+const run = await nika.run('flow.nika');
 console.log(await nika.status(run));
 console.log(await run.done);
 ```

package/docs/testing.md

@@ -52,7 +52,15 @@ starts is a 200 `cancelled` whose terminal is one of those two writer kinds,
 only with `status=cancelled`. The verifiers bind each cancel reply to the
 terminals it may lead to, demand the run status of that terminal, and refuse any
 other pairing. The parsed deterministic and packed-project results must match
-exactly except for the recovery job UUID. The hostile comparison excludes
+exactly except for the recovery job UUID and the depth `package_sha256`.
+That digest is provenance of the tarball this replay packed (README lives
+inside the npm pack): the verifier requires `depth-package.json` beside the
+ledger, hashes the artifact, checks filename/size/sha512 integrity, refuses
+a missing or substituted pack, then compares behavior without requiring the
+committed baseline digest (that digest is a labelled historical ledger
+identity, not a re-hash of this run). A documentation-only
+README change retargets the digest and must still reproduce every behavioral
+verdict. The hostile comparison excludes
 `generated_at` and per-scenario duration and canonicalizes only the two ratified
 writer kinds of a cancelled terminal after checking the exact pairing. This proves that the
 attested public release currently reproduces the committed behavioral claims.
@@ -86,12 +94,29 @@ Every release wave must ask and demonstrate an answer to these questions:
   knowledge?
 - Do ESM and CommonJS load from the packed tarball on every supported Node
   major?
+- Does a workflow the engine refuses reject native `run()` with the engine's
+  code and findings, on every refusal dialect a supported engine writes, with
+  no run handle, no second spawn and no preflight check? Does output that
+  proves neither admission nor refusal stay a protocol fault? The answer is
+  `test/native-run-admission.test.ts`. Its `wire-*` cases replay stdout and
+  stderr captured byte-for-byte from real engines
+  (`test/fixtures/run-wire/README.md` records which, and how); its
+  `SYNTHETIC` cases are invented hostile shapes. A replay proves the SDK
+  decodes those bytes, never that an engine still writes them: a new engine
+  release needs a new capture.
 - What happens if the server dies after admission but before the first SSE
   frame?
 - What happens if SSE reconnects after a duplicate, gap, conflicting replay,
   or terminal race?
 - Can one slow observer overflow without damaging another observer or
-  `run.done`?
+  `run.result()`?
+- Does one application read the same lifecycle words over the native process
+  and over HTTP, with `event.raw` still the protocol frame, and without a
+  per-task event the resident never streamed?
+- Does a frame whose state word is absent, null, future, or still running
+  stay an `engine.event` instead of being named settled?
+- Is a human gate (`paused`) kept apart from both failure and completion, and
+  the engine's `interrupted` evidence apart from a broken observation?
 - Can two clients race the same idempotency key with equal and unequal
   snapshots?
 - Does cancellation win or replay honestly when settlement races it?