Run lifecycle
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.
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
engine.event is the preservation door: every frame this SDK version does
not name 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 names a run_sealed frame if an
engine streams one; engine 0.124.3 writes the seal to the run’s record only,
so read result.receipt.sealed locally or traceVerify(...).verdict.
Check and cancellation
NikaCheckResult is an open engine projection. A local check carries the
findings report, process exitCode and verdicts, typed NikaCheckVerdicts
(valid · access_ready · capacity_fit · run_ready · blockers ·
network_tasks): under check({ access }) a pin the engine refuses keeps
clean: true with verdicts.access_ready: false and the refusal in
verdicts.blockers. access_ready judges the model routes only; from engine
0.124.1, network_tasks lists, sorted, the tasks whose own effects can still
reach the network (a fetch or webhook to a real host, an MCP tool, a paid
media call), which a mock/echo rehearsal does not stub. Each finding
(NikaCheckFinding) that names a part of the file carries span, a
NikaSourceSpan ({ start, end }): byte offsets into the workflow file,
start inclusive and end exclusive. From engine 0.124 a parse refusal
carries one too, and from 0.124.1 the offsets count a file’s byte-order mark,
as the file is saved. 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.
Compile
{ intent }, or the intent as a bare string) or an
edit ({ workflow, change }, the accepted source plus the change), never
both. incomplete and refused are data: the SDK throws only on transport,
protocol, compatibility and engine-stamped failures. Under incomplete, a
non-null candidate is a preview, never a result to run or save.
Artifacts
verdict is sealed or
anchored, names are unique, sizes are byte counts, digests are SHA-256 and
a file’s path is contained; any other key rides through. The path check
is lexical and POSIX, the server’s own, so it does not make a path safe to
join under a local directory on every system: to write an artifact under
yours, resolve the joined path, check that it stays inside, and open it
exclusively (wx). The download stream errors with NikaProtocolError for
bytes that are not the recorded ones, NikaOperationError for a server
refusal on a retry (artifact_changed), and NikaTransportError for a
download that stayed incomplete or was aborted.
Outputs and artifacts shows them in use.
Access pins
run({ access }) and check({ access }) take one
(Configuration).
Access contract and receipt
From 0.124.2. What a workflow file declares underrun.access and
run.reasoning, and what one model call did with it:
null means not applicable or not observed, never a copied value. A
configured value is what the route reported after the selection:
session_config when nothing was asked and the session stated its own,
confirmed_selection when a value was sent and read back,
accepted_request when the route took it without answering a configuration.
changed_mid_turn lists a model, an effort or a tier the route itself moved
during the turn. readNikaAccessRequirement and readNikaAccessSelection
return these from a task’s terminal frame
(Run events).
Access offer
From 0.124.3. WhataccessOffer() returns: the sessions of a served
workflow’s declared ACP route, read without a prompt
(Ask what a route offers):
NikaProtocolError. An observed row carries its
model.status and both listings. An unavailable row carries the code a run
would meet before its prompt.
Proof
verified, or invalid (reason: 'receipt_mismatch'
for an unsealed or edited record; no reason when the trace file cannot be
read). Over HTTP it is the CLI verifier’s tier in lower case: ok means intact
but unsigned (reason: 'unsealed'), and unavailable means the server holds
no journal for the job. The published 0.124.3 declarations list the same
words, with the CLI verifier’s refusal classes (unchained · empty ·
unreadable · refused · line-over-long · unknown), and over HTTP a
verdict that holds always carries its seal tier as reason (sealed or
unsealed). Receipts has the measured table.
Errors
NikaObservationInterrupted means this client lost its observation of a run
that may still be running: an evidence state, never a settlement. Schedule
types (NikaScheduleOptions, NikaScheduleStatus, NikaScheduleApplyResult)
are exported for the revision-checked server schedule contract; their
engine-owned fields are additive.
Which published source this page describes
Which published source this page describes
Published type declarations (v0.124.3)
Review the source of the published declarations.