@supernovae-st/nika 0.71.0 → 0.120.0

package/docs/architecture.md

@@ -0,0 +1,146 @@
+# SDK architecture
+
+The package has one public facade and two execution adapters:
+
+```text
+application
+    |
+    v
+Nika facade
+    |
+    v
+Transport interface  <--- lifecycle and authority seam
+    |                         |
+    v                         v
+NativeProcessTransport    HttpTransport
+    |                         |
+    v                         v
+local nika process         authenticated nika serve
+```
+
+## Modules and responsibilities
+
+- `src/index.ts` is the public Module. It validates caller-owned values, owns
+  run handles, and exposes one stable vocabulary.
+- `src/lib/transport.ts` is the Interface. It describes the operations both
+  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. 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 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.
+
+## Authority rules
+
+The SDK transports engine facts; it does not reproduce engine decisions.
+Parsing, admission, scheduling, cancellation settlement, receipts, trace
+verification, permits, and cost remain engine-owned.
+
+Some operations deliberately have one authority:
+
+- resident workflow discovery, durable status, and schedules require HTTP;
+- a direct native process refuses those operations with
+  `NikaCompatibilityError`;
+- remote execution by contained workflow name uses the resident registry;
+  explicit local paths need a compatible local engine to capture a snapshot;
+- when that capture is red the HTTP adapter returns the local engine's plain
+  `nika check --json` report, so `findings[]` stays canonical and no workflow
+  bytes are sent;
+- HTTP observation (attach, durable status, events, cancel, workflow catalog,
+  schedule status, trace verdicts) needs no local engine;
+- remote trace verification currently returns the engine's typed unavailable
+  verdict because the server has no path-free journal authority.
+
+## Lifecycle invariants
+
+1. `run()` resolves only after stable admission and returns an immutable
+   `NikaRun` handle: `id`, `events()`, `result()`, `status()`, `cancel()`, and
+   `done`, the compatibility alias of `result()`. 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()` 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
+
+If one Adapter is removed, the facade and lifecycle Seam remain coherent and
+the other Adapter still compiles. If the Transport Interface is removed,
+authority differences leak into every public method. If `run-session.ts` is
+removed, each consumer must reimplement buffering, ownership, cancellation,
+and settlement. Those boundaries therefore carry real architectural load.

package/docs/http-api.md

@@ -0,0 +1,160 @@
+# HTTP contract
+
+`openapi.json` is the checked-in contract pin. The SDK authenticates every
+route except public `GET /health`; bearer tokens are redacted from failures.
+A non-2xx answer typed as `{ error: { code, message } }` becomes a
+`NikaOperationError` carrying `status`, `code`, and the refused `operation`;
+For a check by served name, a typed 404 or 422 instead returns
+`{ clean: false, error }`; authentication and transport failures still throw.
+Any other non-2xx body is discarded and reported as a redacted
+`NikaTransportError`.
+
+| HTTP route | SDK surface | Contract |
+|---|---|---|
+| `GET /health` | internal identity handshake | public liveness and protocol versions |
+| `GET /v1/openapi.json` | generation only | authenticated OpenAPI 3.1 document |
+| `GET /v1/workflows` | `listWorkflows()` | contained relative workflow names |
+| `GET /v1/workflows/{name}` | `workflow(name)` | path-free metadata, never source bytes |
+| `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` | `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 |
+
+## Connection rules
+
+- HTTPS is required for every host except loopback. Plain HTTP is accepted
+  only for `localhost`, `127.0.0.0/8`, or `[::1]`, and only with an explicit
+  `allowInsecureHttp: true`; that opt-in never admits a routable host.
+- URLs containing credentials, a query, or a fragment are rejected.
+- Tokens must contain 32–512 visible ASCII bytes and are never sent to
+  `/health`.
+- 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
+  `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` 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.
+
+## Settlement
+
+The terminal `execution.settled` frame and the durable job nest the run's
+`settlement` whole (engine 0.118, ADR-128): its `status` and `cause`, the
+elapsed time, the task tally, the spend with its qualifier, and the failure
+named with its task. The SDK types every known field, refuses a settlement
+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
+`data.sequence`. An identical duplicate is ignored. A conflicting duplicate,
+gap, or out-of-order frame is a protocol failure. After a reset the client
+asks durable job state before reconnecting with `Last-Event-ID`; retry delays
+and attempts are bounded.
+
+A replacement Node process can call `attachRun(jobId, { lastEventId })`. The
+SDK proves that the durable job exists before returning an owned run handle,
+then sends the cursor as `Last-Event-ID`. Persist the job id and last event
+sequence in the same application transaction that records each consumed event.
+A cursor means “fully processed”, not merely “received”.
+
+## Idempotency and schedules
+
+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
+current engine has no time-based eviction: keys remain bound while that state
+root exists and still count toward its configured job capacity. Use globally
+unique, business-stable keys; do not recycle daily counters or workflow-local
+names.
+
+Schedules use compare-and-swap semantics. Create omits `revision`; update must
+carry the exact previous `sha256:...` revision. The SDK never fabricates or
+normalizes schedule facts.

package/docs/migrating-to-0.116.md

@@ -0,0 +1,162 @@
+# Migrating to 0.116
+
+Version 0.116 is an intentional breaking consolidation of the two published
+0.115 clients into one `Nika` facade. This is a 0.x minor release, but existing
+0.115 imports and method calls do not all remain source-compatible. Migrate in
+a branch and run the packed-package gauntlets before upgrading production.
+
+## Removed 0.115 surfaces
+
+- The `@supernovae-st/nika-client/local` export and `LocalNika` class are
+  removed. Use `new Nika({ bin, cwd })`; call `check()`, `run()`, `events()`,
+  and `traceVerify()` on that instance.
+- The root `nika.jobs` and `nika.workflows` namespaces are removed. Use the
+  facade methods shown below.
+- `Nika.fromEnv()`, `nika.health()`, `Nika.verifyWebhook()`, and the exported
+  webhook helper are removed. Construct the client explicitly; health is now
+  an internal compatibility preflight. Keep webhook verification in the
+  application boundary that owns its signing format.
+- Preview artifact, workflow-source/reload, and `runAndCollect` helpers are
+  removed instead of continuing as methods that always refuse.
+- Node 18 and 20 are no longer supported; the package now requires Node 22 or
+  newer.
+
+## Constructor migration
+
+The 0.115 root constructor was HTTP-only. In 0.116, no URL means the native
+process transport; supplying `url` and `token` selects HTTP. Remote `check()`
+and `run()` also need a local Nika binary (`bin`, `NIKA_BIN`, or the exact
+optional host payload package) because
+the SDK captures and validates immutable snapshot bytes before admission.
+The current by-name HTTP path also accepts contained workflow names without a
+local engine; prefix a local file with `./` to retain snapshot capture.
+
+```ts
+// 0.115
+const oldClient = new Nika({ url, token, timeout: 30_000 });
+
+// 0.116
+const nika = new Nika({
+  url,
+  token,
+  bin: process.env.NIKA_BIN,
+  requestTimeout: 30_000,
+  allowInsecureHttp: url.startsWith('http://127.0.0.1'),
+});
+```
+
+`timeout`, retries, polling, concurrency, logger, and per-run `signal` options
+from the old HTTP client are gone. Request and frame bounds are client
+invariants; observe or cancel a returned run through its owned lifecycle.
+
+## Method mapping
+
+| 0.115 | 0.116 |
+| --- | --- |
+| `local.check(file)` | `nika.check(file)` |
+| `local.run(file)` | `await nika.run(file)`, then `nika.events(run)` and `run.done` |
+| `local.runToEnd(file)` | `const run = await nika.run(file); await run.done` |
+| `local.traceVerify(path)` | No path-based replacement; retain the engine-issued receipt and call `nika.traceVerify(receipt)` |
+| `nika.jobs.submit(workflow)` | `nika.run(workflow)` |
+| `nika.jobs.status(id)` | retain the owned run; `nika.status(run)` |
+| `nika.jobs.stream(id)` | `attachRun(id)`, then `events(run)` |
+| `nika.jobs.cancel(id)` | `nika.cancel(run)` |
+| `nika.workflows.list()` | `nika.listWorkflows()` |
+| `nika.workflows.metadata(name)` | `nika.workflow(name)` |
+
+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`,
+`nika run --dry-run --json`, and `nika test`) until a future typed authority is
+explicitly admitted. This release does not silently emulate them.
+
+## The check report changed shape
+
+`check()` still returns `clean` and `exitCode`, but the object around them is
+no longer the 0.115 `LocalCheckReport` (eleven curated fields plus a `raw`
+escape hatch). It is the engine's own machine report, passed through: the
+former `raw` contents are now the top level, `reportVersion` is
+`report_version`, and `parseFatal` and `warnings` are gone. The engine emits
+its identity under both casings (`engineVersion` and `engine_version`,
+`buildSha` and `build_sha`, `specSha` and `spec_sha`, `checkReportVersion`
+and `report_version`); read either, do not diff them. In TypeScript only
+`report_version`, `clean`, and `exitCode` are typed; every other field,
+including `cost`, `findings`, and `hints`, is `unknown` behind an index
+signature, so strict callers narrow it themselves. Two problems that look like
+findings (a missing `permits:` block, a missing `max_tokens:`) are reported
+under `hints[]` (`{ kind, task, advice }`, no `code`), not `findings[]`, in
+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 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.
+
+## New resident discovery
+
+```ts
+const names = await nika.listWorkflows();
+const metadata = await nika.workflow(names[0]);
+```
+
+These methods require an HTTP client. A native-process client returns a typed
+`NikaCompatibilityError` with capability `workflowCatalog`.
+
+## Durable status
+
+```ts
+const run = await nika.run('flow.nika');
+console.log(await nika.status(run));
+console.log(await run.done);
+```
+
+`status(run)` is an observation, not terminal settlement. Keep `run.done` as
+the sole terminal promise. Native-process runs refuse `status()` because a
+short-lived process has no independent durable status authority.
+
+## Durable run recovery
+
+```ts
+const recovered = await nika.attachRun(saved.jobId, {
+  lastEventId: saved.lastEventSequence,
+});
+for await (const event of nika.events(recovered)) {
+  await saveApplicationCheckpoint(recovered.id, event.sequence);
+}
+console.log(await recovered.done);
+```
+
+`attachRun()` is HTTP-only. It proves the job exists, returns a normal owned
+run handle, and resumes the stream with `Last-Event-ID`. Save the job id and
+event cursor in application durable state before the original process exits.
+If more events arrive before the application subscribes than its configured
+buffer can retain, `events()` refuses with `NikaEventBufferOverflowError`
+instead of silently skipping a replay prefix.
+
+## Contract and release alignment
+
+Version 0.116 targets the engine train whose OpenAPI contract contains check,
+jobs, status, events, cancellation, typed trace verification, resident
+workflow discovery, and schedule CAS. Do not publish the SDK before the
+matching engine release and native payload assets exist.

package/docs/testing.md

@@ -0,0 +1,173 @@
+# Testing and release evidence
+
+The release judge is the packed package consumed from an isolated Node
+project, not a source import. Local development still starts with the fast
+gates:
+
+```sh
+npm ci
+npm test
+npm run build
+npm run check:coverage
+npm run check:release-evidence
+NIKA_BIN=/path/to/nika npm run gauntlet:check
+NIKA_BIN=/path/to/nika npm run gauntlet:run
+NIKA_BIN=/path/to/nika npm run gauntlet:projects
+NIKA_BIN=/path/to/nika npm run gauntlet:depth
+NIKA_BIN=/path/to/nika npm run gauntlet:hostile
+NIKA_BIN=/path/to/nika npm run gauntlet:recovery
+NIKA_BIN=/path/to/nika npm run gauntlet:one-door
+npm audit
+npm pack --dry-run
+```
+
+All engine-backed gauntlets use `NIKA_BIN` as the canonical explicit binary.
+`NIKA_GAUNTLET_BIN` remains a compatibility fallback for the corpus-only
+scripts. Evidence is invalid when the recorded engine identity does not match
+the intended release candidate. `npm run check:release-evidence` binds every
+current committed gauntlet result and packed tarball identity to the root
+package version. Historical ledgers are limited to an explicit allowlist and
+must remain labelled as non-gating evidence.
+
+CI adds a behavioral provenance replay. It downloads the Linux x64 asset for
+the exact root package version, verifies its GitHub attestation and published
+`SHA256SUMS` entry, then reruns all 100 deterministic workflows, the hostile suite, all five mini-SaaS projects, all five depth projects,
+the two-process recovery scenario, and five scenarios through six execution
+doors from a freshly packed SDK. The runner
+mints an ephemeral run-signing key. Its
+cancellation fixtures retain the in-process `nika:wait` cases and add an
+owned loopback rendezvous for controlled task-boundary cancellation. They
+need no shell command, platform sandbox, or sandbox waiver. Cancellation
+and sealed-trace claims are exercised against the public binary. The
+cancellation fixtures cancel an execution that is observably inside its 10 s
+`nika:wait` (the durable status reads `running`, no longer `queued`, and a
+further delay has passed) and record both the cancel reply and the terminal it
+leads to. On engine 0.118 the resident answers 202 `cancellation_requested`;
+its execution owner then records `execution.interrupted` with
+`status=interrupted` once the grace expires inside a task, or, when the request
+lands at a task boundary, `execution.cancelled` (the `cancel_job` writer) or
+`execution.settled` (the racing settlement writer) with `status=cancelled` and a
+settlement whose cause is `operator`. A cancel that lands before the execution
+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
+`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.
+It does not claim cryptographic proof of when the committed JSON file itself
+was originally written.
+
+## Test layers
+
+1. Unit tests cover configuration, local process framing, HTTP protocol
+   validation, SSE recovery, independent observer backpressure, scheduling,
+   receipts, and typed errors.
+2. The generated corpus holds 100 distinct use cases and 100 valid workflows.
+3. The deterministic runner executes every workflow with `mock/echo` and
+   seals trace evidence without paid-provider dependence.
+4. Project gauntlets install the tarball into fresh applications and exercise
+   realistic multi-step use cases.
+5. Hostile tests mutate transport frames, timing, status codes, identities,
+   revisions, and replay order.
+6. Public Personas use only the README, exported types, packed package, public
+   binary/help, loopback HTTP, and public documentation. They are synthetic
+   users, never substitutes for human usability evidence.
+
+The latest public-only first-contact wave and its convergent debt are recorded
+in [`gauntlet/personas/REPORT.md`](../gauntlet/personas/REPORT.md).
+
+## Socratic risk matrix
+
+Every release wave must ask and demonstrate an answer to these questions:
+
+- Can a first-time Node user succeed from the README without repository
+  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.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?
+- Does a stale schedule writer receive the current revision without mutating
+  durable state?
+- Do process and server restarts preserve the facts the API claims are
+  durable?
+- Can a replacement client reattach with its last committed SSE cursor without
+  replaying an application side effect?
+- Are auth failures, token rotation, malformed content types, compressed
+  bodies, oversized frames, invalid UTF-8, and timeouts typed and redacted?
+- Are receipt job, execution, and trace identities consistent across SSE,
+  durable state, and verification?
+- Is the run-signing private key still confined to engine custody, with only
+  public trust material entering application infrastructure?
+- Does every live OpenAPI route have a deliberate SDK treatment?
+- Does every documented example compile and run from the tarball?
+- Does the version agree across package metadata, lockfile, optional native
+  packages, OpenAPI identity, engine release, npm, and GitHub?
+- Can a claimed capability be deleted without a gate becoming red? If yes,
+  the capability is not yet wired.
+
+## Release evidence
+
+Record exact commands, versions, commit SHAs, platform, run counts, cost, and
+the path to machine-readable results. A green unit suite alone is never release
+evidence. A failed or skipped lane stays named; it is not rounded into a pass.
+
+The release ceremony is deliberately two-step. `release.yml` validates the
+tagged engine assets, starts the released Linux binary, proves the live
+OpenAPI/types pin, embeds the exact prepared commit and release version in all
+five package manifests before packing, and publishes four payloads plus the SDK
+through npm trusted publishing with GitHub OIDC and Sigstore provenance bound
+to the workflow identity. Every package registers organization `supernovae-st`,
+repository `nika-client`, workflow filename `release.yml`, and environment
+`npm-publish`, with direct `npm publish` enabled. The GitHub-hosted publish job
+uses Node 24, npm 11.19.1 and `id-token: write`; it receives no npm write token.
+`release-heal.yml` dispatches that same file on `main`; it does not publish or
+exchange an OIDC token itself. All five package manifests identify the SDK
+repository; native `SOURCE.json` still identifies the separate engine source.
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+An occupied version is accepted only after its exact
+prepared tarball integrity and fetched registry bytes match; errors other than
+an explicit registry 404 refuse publication. `release-finalize.yml` refuses to create the SDK tag and GitHub
+Release until all five exact versions are publicly observable on npm and every
+published manifest carries the same prepared commit and version.
+
+## One-door parity and process supervision
+
+`gauntlet:one-door` compares CLI, raw HTTP by name and snapshot, and packed SDK
+native, by-name and snapshot execution. It checks success, failure, recovery,
+paused observation and controlled cancellation. `NIKA_ONE_DOOR_REPORT` names
+its output file; CI retains it alongside the replay results. Development mode
+uses an offline installation of the freshly packed SDK with the explicit
+`NIKA_BIN`. Public npm parity requires `NIKA_PUBLIC_SDK_VERSION` and an outer
+artifact-provenance gate; runtime agreement alone is not an attestation.
+
+All harnesses own their child processes, impose finite deadlines and await
+cleanup before emitting green evidence. The corpus runs in a fresh project and
+HOME. Changed fixtures require new measured results: old committed ledgers
+remain historical observations until a successful exact-version replay replaces
+them. Never relabel an old binary or weaken the replay comparison.