@supernovae-st/nika 0.71.0 → 0.118.7

package/docs/architecture.md

@@ -0,0 +1,85 @@
+# 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.
+- `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.
+- `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
+   `{ 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
+   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.
+
+## 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,87 @@
+# 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` | `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}/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
+  `vars`, `model`, and `maxCostUsd` until the request envelope owns them.
+- 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
+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.
+
+## 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
+
+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.
+
+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,147 @@
+# 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)` |
+
+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.
+
+`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 live iterator (default 256), so observe it concurrently or the
+prefix is gone. 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.yaml');
+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,156 @@
+# 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?
+- 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`?
+- 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.

package/openapi.json

@@ -0,0 +1 @@
+{"components":{"parameters":{"IdempotencyKey":{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":255,"minLength":1,"type":"string"}},"IfMatch":{"in":"header","name":"If-Match","required":false,"schema":{"maxLength":96,"type":"string"}},"IfNoneMatch":{"in":"header","name":"If-None-Match","required":false,"schema":{"const":"*","type":"string"}},"LastEventId":{"in":"header","name":"Last-Event-ID","required":false,"schema":{"pattern":"^(0|[1-9][0-9]*)$","type":"string"}}},"schemas":{"Error":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"ExecutionSnapshot":{"additionalProperties":false,"description":"Immutable byte-owned execution world — the body `nika check <file> --json --sdk-snapshot` prints (the engine is the one producer; a client never hashes). Unit bytes are canonical lowercase hexadecimal. `digest` and every unit `digest` are OPTIONAL caller-supplied integrity digests (canonical lowercase SHA-256 · a content assertion, never a signature): absent, the resident computes them and the receipt carries the result; present, they must match the bytes or the request is refused as `snapshot_tampered`. The decoded unit aggregate is limited to 16 MiB and the complete encoded request to 33 MiB. This object is the request body itself, not a path-bearing wrapper.","properties":{"digest":{"description":"Optional caller-supplied integrity digest of the world (never a signature)","pattern":"^[0-9a-f]{64}$","type":"string"},"format_version":{"const":1,"type":"integer"},"root":{"maxLength":4096,"minLength":1,"type":"string"},"units":{"items":{"additionalProperties":false,"properties":{"bytes_hex":{"pattern":"^(?:[0-9a-f]{2})*$","type":"string"},"digest":{"description":"Optional caller-supplied integrity digest of the unit (never a signature)","pattern":"^[0-9a-f]{64}$","type":"string"},"kind":{"description":"0 root (the admitted workflow) · 1 child (a transitively invoked workflow) · 2 skill (an Agent Skill document) · 3 import (an opaque import the caller supplied)","maximum":3,"minimum":0,"type":"integer"},"path":{"maxLength":4096,"minLength":1,"type":"string"}},"required":["path","kind","bytes_hex"],"type":"object"},"maxItems":256,"type":"array"}},"required":["format_version","root","units"],"type":"object"},"Health":{"additionalProperties":false,"properties":{"api_version":{"minLength":1,"type":"string"},"buildSha":{"minLength":1,"type":"string"},"build_sha":{"minLength":1,"type":"string"},"checkReportVersion":{"minimum":1,"type":"integer"},"engineVersion":{"minLength":1,"type":"string"},"engine_version":{"minLength":1,"type":"string"},"eventFormatVersion":{"minimum":1,"type":"integer"},"machineProtocolVersion":{"minimum":1,"type":"integer"},"service":{"const":"nika-serve","type":"string"},"snapshotFormatVersion":{"minimum":1,"type":"integer"},"specSha":{"minLength":1,"type":"string"},"spec_sha":{"minLength":1,"type":"string"},"status":{"const":"ok","type":"string"},"supportedCapabilities":{"items":{"type":"string"},"type":"array","uniqueItems":true},"traceFormatVersion":{"minimum":1,"type":"integer"}},"required":["status","service","engine_version","build_sha","spec_sha","api_version","engineVersion","buildSha","specSha","machineProtocolVersion","snapshotFormatVersion","checkReportVersion","eventFormatVersion","traceFormatVersion","supportedCapabilities"],"type":"object"},"Job":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"execution_id":{"type":"string"},"id":{"format":"uuid","type":"string"},"outputs":{"additionalProperties":true,"description":"Declared workflow outputs; present only after settlement when supplied by the execution adapter","type":"object"},"receipt":{"$ref":"#/components/schemas/JobReceipt"},"settlement":{"$ref":"#/components/schemas/RunSettlement"},"status":{"$ref":"#/components/schemas/JobStatus"},"trace_id":{"type":"string"}},"required":["id","status"],"type":"object"},"JobByName":{"additionalProperties":false,"description":"The by-name form (ADR-131): a workflow the served registry lists (GET /v1/workflows · project-root-relative, `.nika.yaml`). The resident captures its world exactly as a schedule does — the one owner of the snapshot and its digest domain. Idempotency binds to these request bytes.","properties":{"workflow":{"maxLength":4096,"minLength":1,"type":"string"}},"required":["workflow"],"type":"object"},"JobEvent":{"additionalProperties":false,"properties":{"code":{"type":"string"},"kind":{"type":["string","null"]},"message":{"type":"string"},"outputs":{"additionalProperties":true,"type":"object"},"receipt":{"$ref":"#/components/schemas/JobReceipt"},"sequence":{"minimum":1,"type":"integer"},"settlement":{"$ref":"#/components/schemas/RunSettlement"},"status":{"anyOf":[{"$ref":"#/components/schemas/JobStatus"},{"type":"null"}]}},"required":["sequence","kind","status"],"type":"object"},"JobOrigin":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"manual","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"arm_generation":{"pattern":"^[0-9a-f]{64}$","type":"string"},"decision":{"enum":["scheduled","catch_up"],"type":"string"},"fired_at":{"format":"date-time","type":"string"},"kind":{"const":"schedule","type":"string"},"schedule_id":{"description":"Origin-local identifier, bounded to 255 UTF-8 bytes by the server","maxLength":255,"minLength":1,"type":"string"},"schedule_origin":{"enum":["project","api"],"type":"string"},"schedule_revision":{"pattern":"^sha256:[0-9a-f]{64}$","type":"string"},"scheduled_for":{"format":"date-time","type":"string"},"slot_id":{"pattern":"^[0-9a-f]{64}$","type":"string"}},"required":["kind","schedule_origin","schedule_id","schedule_revision","slot_id","decision","scheduled_for","fired_at","arm_generation"],"type":"object"}]},"JobReceipt":{"additionalProperties":false,"description":"Terminal binding to the exact immutable admitted execution","properties":{"chain_head":{"minLength":1,"type":"string"},"execution_id":{"minLength":1,"type":"string"},"job_id":{"format":"uuid","type":"string"},"origin":{"$ref":"#/components/schemas/JobOrigin"},"snapshot_digest":{"pattern":"^[0-9a-f]{64}$","type":"string"},"trace_id":{"minLength":1,"type":"string"}},"required":["job_id","execution_id","trace_id","snapshot_digest"],"type":"object"},"JobStatus":{"description":"queued and running: the resident owns the execution. interrupted: execution ownership was lost and effect settlement is unknown — an EVIDENCE state (the journal is INCOMPLETE), never a run state (ADR-129). paused, succeeded, failed and cancelled: the run's own settlement, the words its terminal frame carries (ADR-128).","enum":["queued","running","interrupted","paused","succeeded","failed","cancelled"],"type":"string"},"JobStatusOnly":{"additionalProperties":false,"description":"Status only. Redacted diagnosis lives on GET /v1/jobs/{id} and SSE, never here.","properties":{"status":{"$ref":"#/components/schemas/JobStatus"}},"required":["status"],"type":"object"},"RunSettlement":{"additionalProperties":false,"description":"The run's settlement (ADR-128), built once by the runtime and projected whole: the state word every door speaks, why, the elapsed time on the kernel clock, the task tally, the spend with its qualifier, the failure named. Unknown cost is never zero: `total_cost_usd` is absent when nothing was metered. Present on the terminal event and durable job response of a job whose runtime settled; absent when the resident lost the execution (interrupted) or refused it before any task. Reattachment and idempotent admission replay project the same hash-bound terminal event, never a new settlement.","properties":{"cause":{"enum":["normal","human_gate","task_failed","output_contract","budget","operator","refused"],"type":"string"},"elapsed_ms":{"minimum":0,"type":"integer"},"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"task":{"description":"The task that failed · absent for a run-level cause","type":"string"}},"required":["code","message"],"type":"object"},"spend":{"additionalProperties":false,"properties":{"by_source":{"additionalProperties":{"type":"number"},"type":"object"},"priced_calls":{"minimum":0,"type":"integer"},"pricing_as_of":{"type":"string"},"qualifier":{"enum":["priced","partially_priced","unpriced","unmetered"],"type":"string"},"total_cost_usd":{"description":"Present only when at least one leaf metered real spend","minimum":0,"type":"number"},"unpriced_calls":{"minimum":0,"type":"integer"}},"required":["priced_calls","unpriced_calls","qualifier"],"type":"object"},"status":{"enum":["succeeded","failed","paused","cancelled"],"type":"string"},"tasks":{"additionalProperties":false,"properties":{"cancelled":{"minimum":0,"type":"integer"},"failed":{"minimum":0,"type":"integer"},"never_started":{"description":"Cancelled at the boundary without ever starting (counted in `cancelled` too)","minimum":0,"type":"integer"},"ok":{"description":"A recovered task IS a success (counted here too)","minimum":0,"type":"integer"},"recovered":{"minimum":0,"type":"integer"},"skipped":{"minimum":0,"type":"integer"},"total":{"minimum":0,"type":"integer"}},"required":["total","ok","failed","recovered","skipped","cancelled","never_started"],"type":"object"}},"required":["status","cause","spend"],"type":"object"},"ScheduleApply":{"additionalProperties":false,"properties":{"applied":{"const":true,"type":"boolean"},"changed":{"type":"boolean"},"status":{"$ref":"#/components/schemas/ScheduleStatus"}},"required":["applied","changed","status"],"type":"object"},"SchedulePut":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"afterSkip":{"enum":["next_slot","on_completion"],"type":"string"},"jitter":{"enum":["hash"],"type":"string"},"maxCostUsd":{"exclusiveMinimum":0,"type":"number"},"maxLatenessSeconds":{"minimum":0,"type":"integer"},"missed":{"enum":["catch-up","catch-up-once","skip"],"type":"string"},"overlap":{"enum":["skip","queue","replace"],"type":"string"},"pauseReason":{"maxLength":1024,"type":"string"},"pauseUntil":{"format":"date","type":"string"},"tolerance":{"type":"string"},"when":{"oneOf":[{"additionalProperties":false,"properties":{"at":{"format":"date-time","type":"string"},"kind":{"const":"once"}},"required":["kind","at"],"type":"object"},{"additionalProperties":false,"properties":{"expression":{"maxLength":4096,"type":"string"},"kind":{"const":"cadence"}},"required":["kind","expression"],"type":"object"}]},"workflow":{"maxLength":1024,"pattern":"^[^/].*\\.nika\\.yaml$","type":"string"}},"required":["workflow","when","maxCostUsd","missed"],"type":"object"},"ScheduleStatus":{"additionalProperties":true,"description":"Normalized definition, origin, distinct schedule revision, active/pause state, due verdict, bounded next slots with shift evidence, earliest wake hint, and last durable decision.","type":"object"},"SnapshotValidationAck":{"additionalProperties":false,"description":"Compact remote acknowledgement that the exact snapshot was revalidated. This is not the engine's public full check report; SDK callers retain the engine-owned report captured with the snapshot and return it only after this acknowledgement succeeds.","properties":{"root":{"minLength":1,"type":"string"},"snapshot_digest":{"pattern":"^[0-9a-f]{64}$","type":"string"},"status":{"const":"accepted","type":"string"},"units":{"minimum":1,"type":"integer"}},"required":["status","snapshot_digest","root","units"],"type":"object"},"TraceVerification":{"additionalProperties":false,"description":"Run-scoped typed verdict. Unavailable is an honest refusal: this server has no remote trace-journal authority and never scans or returns filesystem paths.","properties":{"reason":{"enum":["run_not_terminal","trace_journal_unavailable"],"type":"string"},"trace_id":{"minLength":1,"type":"string"},"verdict":{"enum":["unavailable"],"type":"string"}},"required":["verdict","reason"],"type":"object"},"WorkflowList":{"additionalProperties":false,"properties":{"workflows":{"items":{"minLength":1,"type":"string"},"type":"array"}},"required":["workflows"],"type":"object"},"WorkflowMetadata":{"additionalProperties":false,"properties":{"workflow":{"minLength":1,"type":"string"}},"required":["workflow"],"type":"object"}},"securitySchemes":{"bearerAuth":{"description":"Exactly one Authorization: Bearer value from the token file","scheme":"bearer","type":"http"}}},"info":{"description":"Authenticated loopback remote execution and declarative schedules. Artifacts, schedule list/delete/trigger/backfill, /v1/arm, and POST /v1/run are absent.","title":"nika serve","version":"0.118.7"},"openapi":"3.1.0","paths":{"/health":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}},"description":"Engine identity only"}},"security":[],"summary":"Public process liveness"}},"/v1/check":{"post":{"description":"Runs the same admission as POST /v1/jobs (ADR-131 · both forms) over the exact request body, and creates nothing.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JobByName"},{"$ref":"#/components/schemas/ExecutionSnapshot"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotValidationAck"}}},"description":"Compact snapshot validation acknowledgement, not the full engine check report"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"408":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Request deadline"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Encoded body or decoded snapshot resource limit"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Content-Type or Content-Encoding refused"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Malformed, unsupported, tampered, or semantically refused snapshot"}},"summary":"Judge a workflow without creating a job — by served name, or as immutable snapshot bytes"}},"/v1/jobs":{"post":{"description":"Two forms, one admission (ADR-131). `{\"workflow\": \"<name>\"}` names a workflow the served registry lists: the resident captures its world through ExecutionService, exactly as a schedule does. A snapshot body is the world `nika check <file> --json --sdk-snapshot` prints, decoded and readmitted through the same ExecutionService; its digests are optional caller-supplied integrity digests (a content assertion, never a signature). The server never interprets a caller filesystem path. Idempotency binds to the exact request bytes.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JobByName"},{"$ref":"#/components/schemas/ExecutionSnapshot"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Idempotent replay"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid idempotency key"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"408":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Request deadline"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Idempotency key already bound to another request"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Encoded body or decoded snapshot resource limit"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Content-Type or Content-Encoding refused"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Malformed, unsupported, tampered, or semantically refused snapshot"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Execution queue or durable store unavailable"},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Durable job capacity exhausted"}},"summary":"Admit a workflow as a durable job — by served name, or as immutable snapshot bytes"}},"/v1/jobs/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Job"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Job identity and status"}},"/v1/jobs/{id}/cancel":{"post":{"description":"A queued job cancels atomically before execution claims it. An active job receives the run-scoped cancellation signal and returns 202 until its execution owner settles: the result may be success, failure or cancellation; expired grace means interrupted, never an invented cancellation. A paused or final observation returns its existing result unchanged.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Cancelled before execution, or already ended observation"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Cancellation requested; execution has not yet settled"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Request cancellation or replay an ended observation"}},"/v1/jobs/{id}/events":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"$ref":"#/components/parameters/LastEventId"}],"responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string"},"x-nika-event-schema":{"$ref":"#/components/schemas/JobEvent"}}},"description":"text/event-stream; sends bounded retry guidance and cursor-neutral heartbeat comments; Last-Event-ID replays only persisted events after that sequence; terminal data adds declared outputs and receipt when available; failures add redacted {code,message}"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Job event SSE"}},"/v1/jobs/{id}/status":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusOnly"}}},"description":"Status"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Status only; diagnosis lives on GET /v1/jobs/{id} and SSE"}},"/v1/jobs/{id}/trace/verify":{"get":{"description":"Returns a typed honest refusal while no remote trace-journal authority exists. It never scans a trace directory or exposes a filesystem path.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceVerification"}}},"description":"Typed trace verdict"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Return the run-scoped trace verification verdict"}},"/v1/openapi.json":{"get":{"responses":{"200":{"description":"OpenAPI 3.1"},"401":{"description":"Bearer required"}},"summary":"This document"}},"/v1/schedules/{id}":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleStatus"}}},"description":"Fresh planned status","headers":{"ETag":{"schema":{"type":"string"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Read one declarative resident schedule"},"parameters":[{"in":"path","name":"id","required":true,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"put":{"description":"Create requires If-None-Match: *. Update requires the exact ETag in If-Match. Identical lost-response retries are unchanged and retain the revision.","parameters":[{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulePut"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleApply"}}},"description":"Applied or unchanged","headers":{"ETag":{"schema":{"type":"string"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Create or revision-conditionally update one resident schedule"}},"/v1/workflows":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowList"}}},"description":"Project-relative .nika.yaml names under the served registry (--workflows)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Contained workflow names"}},"/v1/workflows/{name}":{"get":{"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowMetadata"}}},"description":"Contained name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error envelope"}},"summary":"Workflow metadata without source bytes"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"http://127.0.0.1"}]}