SDK type index

Run lifecycle

interface NikaRun<Outputs extends Record<string, unknown> = Record<string, unknown>> {
  readonly id: NikaRunId
  readonly events: (options?: NikaEventsOptions) => AsyncIterable<NikaRunEvent<Outputs>>
  readonly result: () => Promise<NikaRunResult<Outputs>>
  readonly status: () => Promise<NikaRunStatus>      // resident-owned; native rejects (NikaCompatibilityError)
  readonly cancel: () => Promise<NikaCancelResult>   // idempotent; acceptance is not a result
  readonly done: Promise<NikaRunResult<Outputs>>     // compatibility alias of result()
}

The Outputs generic narrows result().outputs at compile time. It is a type-level convenience only — nothing runtime-validates model output against it. The workflow’s outputs: block exports named values; it does not validate them. Runtime shape enforcement comes from infer.schema (checked when the model answers) or an explicit validator task (nika:validate) — not from the export mapping, and never from a TypeScript generic. run.id differs by transport: on HTTP it is the resident’s durable job id (the identity to store); on the native transport it is an ephemeral correlation id of this SDK process — it appears in no journal, cannot be recovered after the process ends, and attachRun refuses it. Resume a native run through the engine’s own trace instead.

interface NikaRunResult<Outputs> {
  id: NikaRunId
  status: NikaRunStatus
  transport: 'native-process' | 'http'
  exitCode?: number
  outputs?: Outputs
  receipt?: NikaReceipt
  error?: NikaMachineError
  execution_id?: NikaExecutionId
  settlement?: NikaSettlement
  [key: string]: unknown
}

result() has one failure law: it rejects on transport, protocol or compatibility faults and on a broken observation (NikaObservationInterrupted, which carries the cursor) — none of which say the run failed; it may still be running. It resolves status: 'failed' for an admitted workflow failure (result data, with the engine’s error.code when named), and status: 'paused' when a human gate holds the run. Read isNikaRunSucceeded(result) before treating it as success.

Events

type NikaRunEventKind =
  | 'run.started' | 'task.scheduled' | 'task.started' | 'task.completed'
  | 'task.failed' | 'run.waiting' | 'run.settled' | 'run.interrupted'
  | 'run.sealed' | 'engine.event'

interface NikaRunEvent<Outputs> {
  readonly kind: NikaRunEventKind
  readonly transport: NikaTransportKind
  readonly status?: NikaRunStatus   // the engine's own state word, never renamed
  readonly sequence?: number        // HTTP only — persist for attachRun({ lastEventId })
  readonly task?: string            // the task a task.* frame named
  readonly error?: NikaMachineError
  readonly raw: NikaEvent<Outputs>  // the exact protocol frame the engine wrote
}

engine.event is the preservation door: every frame this SDK version does not know yet arrives there with its raw frame untouched — nothing is dropped, and no lifecycle meaning is invented for it. Keep a default branch in reducers; the set is additive. run.sealed is native-only.

Check and cancellation

NikaCheckResult is an open engine projection. A local check carries the findings report and process exitCode. A served-name HTTP check carries clean: true plus status, snapshot_digest, root and units, or clean: false with a typed refusal in error; it does not invent a local findings report or exit code. NikaCancelResult describes action acceptance: cancelled (settled on the reply), already_settled, or cancellation_requested — execution continues toward its own settlement in the last case. Use run.result() for the actual result, including success racing cancellation.

Proof

type NikaReceipt = Readonly<Record<string, unknown>>

interface NikaTraceVerifyResult {
  verified: boolean
  verdict?: 'verified' | 'invalid' | 'unavailable' | (string & {})
  reason?: string
  trace_id?: string
  exitCode?: number
  output?: string
  [key: string]: unknown
}

The native path answers verified or invalid; the resident answers unavailable while it has no trace-journal authority — a typed answer, not a 404.

Errors

NikaError
├── NikaConfigurationError
├── NikaTransportError
│   ├── NikaProtocolError
│   └── NikaObservationInterrupted
├── NikaCompatibilityError
├── NikaOperationError
├── NikaEventBufferOverflowError
└── NikaRunOwnershipError

NikaEngineUnavailable

NikaEngineUnavailable is exported separately by binary resolution. NikaObservationInterrupted means this client lost its observation of a run that may still be running — an evidence state, never a settlement. Schedule types are exported for the exact CAS-backed resident schedule contract; inspect the merged source declarations for their additive engine-owned fields.

Which published source this page describes

Merged source types

Review the source declarations at the pinned merged SDK commit.

Overview

Start

Project

Local API

Runtime

Remote API

Operations

Reference

SDK type index

Run lifecycle

Events

Check and cancellation

Proof

Errors

Merged source types

​Run lifecycle

​Events

​Check and cancellation

​Proof

​Errors

Merged source types

Run lifecycle

Events

Check and cancellation

Proof

Errors