[{"k":"h","depth":1,"text":"05 · Errors","id":"05--errors"},{"k":"quote","inline":[{"k":"text","text":"Nika has a "},{"k":"strong","text":"typed error model"},{"k":"text","text":". Every error has a code · a category ·\nand structured details. Tasks may declare retry policies and fallback\nrecovery. The workflow itself fails when an unrecovered terminal error\nreaches a task with no "},{"k":"code","text":"on_error:"},{"k":"text","text":" policy."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Error structure","id":"error-structure"},{"k":"p","inline":[{"k":"text","text":"Every error is a typed structure ·"}]},{"k":"code","lang":"json","text":"{\n  \"code\": \"NIKA-INFER-001\",\n  \"category\": \"provider_error\",\n  \"message\": \"Anthropic API returned 503 service unavailable\",\n  \"transient\": true,\n  \"details\": {\n    \"provider\": \"anthropic\",\n    \"model\": \"claude-3-5-sonnet\",\n    \"status_code\": 503,\n    \"retry_after_secs\": 30\n  },\n  \"task_id\": \"research\",\n  \"attempt\": 2\n}"},{"k":"h","depth":3,"text":"Fields","id":"fields"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`code` · yes · string · `NIKA-<NAMESPACE>-<NNN>` · stable identifier"}],[{"k":"text","text":"`category` · yes · enum · See category list below"}],[{"k":"text","text":"`message` · yes · string · Human-readable description"}],[{"k":"text","text":"`transient` · yes · boolean · True if retry might succeed (network · 503 · rate limit)"}],[{"k":"text","text":"`details` · no · object · Category-specific structured fields"}],[{"k":"text","text":"`task_id` · yes (runtime) · string · Which task this error occurred in"}],[{"k":"text","text":"`attempt` · yes (runtime) · integer · Which attempt failed (1-indexed)"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Error code namespaces","id":"error-code-namespaces"},{"k":"p","inline":[{"k":"text","text":"Error codes follow the format "},{"k":"code","text":"NIKA-<NAMESPACE>-<NNN>"},{"k":"text","text":" where namespace is 2-9 uppercase letters and NNN is a 3-digit zero-padded number. A code MAY add an "},{"k":"strong","text":"optional sub-namespace"},{"k":"text","text":" for self-documentation · "},{"k":"code","text":"NIKA-<NAMESPACE>-<SUB>-<NNN>"},{"k":"text","text":" (4-segment), used per-builtin ("},{"k":"code","text":"NIKA-BUILTIN-WAIT-001"},{"k":"text","text":" · each builtin owns its own 001-099) or per-field ("},{"k":"code","text":"NIKA-PARSE-WHEN-001"},{"k":"text","text":" · the "},{"k":"code","text":"when:"},{"k":"text","text":" field of a parse error). The canonical regex is "},{"k":"code","text":"^NIKA-[A-Z]{2,9}(-[A-Z][A-Z0-9_]{1,15})?-[0-9]{3}\u0024"},{"k":"text","text":" (also the "},{"k":"code","text":"retry.on_codes"},{"k":"text","text":" / "},{"k":"code","text":"on_error.on_codes"},{"k":"text","text":" validation pattern). The sub-namespace segment admits underscores so underscore-named builtins encode cleanly ("},{"k":"code","text":"NIKA-BUILTIN-JSON_MERGE_PATCH-001"},{"k":"text","text":")."}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Namespace · Scope · Reserved range"}],[{"k":"text","text":"`NIKA-PARSE` · YAML parse + envelope validation · 001-099"}],[{"k":"text","text":"`NIKA-DAG` · DAG topology · cycles · invalid deps · 001-099"}],[{"k":"text","text":"`NIKA-VAR` · Variable resolution failures · 001-099"}],[{"k":"text","text":"`NIKA-INFER` · `infer:` verb errors · 001-099"}],[{"k":"text","text":"`NIKA-EXEC` · `exec:` verb errors · 001-099"}],[{"k":"text","text":"`NIKA-INVOKE` · `invoke:` verb errors · 001-099"}],[{"k":"text","text":"`NIKA-AGENT` · `agent:` verb errors · 001-099"}],[{"k":"text","text":"`NIKA-PROVIDER` · Provider adapter errors · 001-099 per provider"}],[{"k":"text","text":"`NIKA-BUILTIN-<BUILTIN>` · Builtin tool errors · per-builtin sub-namespace (`NIKA-BUILTIN-WAIT-001` · `NIKA-BUILTIN-NOTIFY-001` · `NIKA-BUILTIN-INSPECT-001` · `NIKA-BUILTIN-IMAGE_GENERATE-001..007` + `NIKA-BUILTIN-IMAGE_FX-001..006` — the §Media builtins' planes, stdlib page normative · `NIKA-BUILTIN-FETCH-001` — `nika:fetch`'s network/extraction errors, whose instances carry `category: network_error` though the namespace is the uniform `NIKA-BUILTIN`) · 001-099 per builtin"}],[{"k":"text","text":"`NIKA-MCP` · MCP client errors · 001-099"}],[{"k":"text","text":"`NIKA-SEC` · Security policy violations (SSRF · blocklist) · 001-099"}],[{"k":"text","text":"`NIKA-TIMEOUT` · Task or step timeouts · 001-099"}],[{"k":"text","text":"`NIKA-TYPE` · Type core · contracts · lowering ([09-types.md](./09-types.md)) · 001-199 (001-099 static · 101+ runtime)"}],[{"k":"text","text":"`NIKA-CANCEL` · Task or workflow cancellation · 001-099"}],[{"k":"text","text":"`NIKA-IMPL` · Engine internal errors · 001-099"}],[{"k":"text","text":"`NIKA-YAML` · YAML profile refusals (anchors · aliases · merge keys · tags · caps · encoding — the R11 law set · [01 §YAML profile](./01-envelope.md#yaml-profile-normative) · pedagogical upgrades of the `NIKA-PARSE` floor) · 001-099"}],[{"k":"text","text":"`NIKA-COMP` · Composition (`invoke: workflow:` · [14-composition](./14-composition.md)) · 001-099"}],[{"k":"text","text":"`NIKA-DECIDE` · Decision bundles + evidence (`nika:decide` · [11-decision](./11-decision.md)) · 001-099"}],[{"k":"text","text":"`NIKA-PORT` · Gateway artifacts (deployment bundle · lowering · fidelity · [12-gateway](./12-gateway.md)) · 001-099"}],[{"k":"text","text":"`NIKA-POLICY` · `policy:` hard-rule violations ([10-authority](./10-authority.md)) · 001-099"}],[{"k":"text","text":"`NIKA-ASSERT` · `assert:` obligations ([15-proof](./15-proof.md)) · 001-099"}],[{"k":"text","text":"`NIKA-LOCK` · `nika.lock` pin violations ([15-proof](./15-proof.md)) · 001-099"}],[{"k":"text","text":"`NIKA-REG` · Registry client refusals (resolve · digest · advisory · [registry-v0.1](../registry/registry-v0.1.md) · allocated for the reference engine's `registry:` resolver — engine ADR-106) · 001-099"}]]},{"k":"p","inline":[{"k":"text","text":"This table allocates every namespace in use; the machine registry\n("},{"k":"link","text":"`canon/diagnostics/registry.yaml`","href":"../canon/diagnostics/registry.yaml"},{"k":"text","text":")\ncarries the per-code rows. A v0.1-compliant engine MUST use these namespaces for the canonical categories. New error codes MAY be added in minor bumps (additive · never repurposed)."}]},{"k":"h","depth":3,"text":"Concrete v0.1 codes · the normative floor","id":"concrete-v01-codes--the-normative-floor"},{"k":"p","inline":[{"k":"text","text":"The codes below are "},{"k":"strong","text":"allocated"},{"k":"text","text":": a conformant engine emits exactly these\ncodes for these failures (it MAY add more within a namespace's range · never\nrepurpose). This closes the « placeholder » gap: a second engine matches\nthese from this file alone."}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Code · Failure · Category · `transient`"}],[{"k":"text","text":"`NIKA-PARSE-001` · the YAML itself does not parse (syntax error) · `parse_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-002` · missing envelope field (`nika:` / `workflow:` / non-empty `tasks:`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-003` · `nika:` version marker is not exactly `v1` · `parse_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-004` · `workflow:` id violates `^[a-z][a-z0-9-]*\u0024` · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-005` · unknown field — strict mode rejects anything outside the closed v1 set · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-006` · task id violates `^[a-z][a-z0-9_]*\u0024` (snake_case · CEL-safe · no hyphens) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-007` · duplicate task id within the workflow · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-008` · task declares no verb — exactly one of `infer`/`exec`/`invoke`/`agent` required · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-009` · task declares multiple verbs — exactly one required · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-010` · `timeout:` violates the quoted Go-duration contract (positive · max 24h · descending units) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-011` · `retry:` block violates the spec shape (§retry below) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-012` · `on_error:` block violates the spec shape (fields mutually exclusive) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-013` · `with:`/`output:` binding uses a reserved name (`output` · `status` · `error` · `started_at` · `ended_at` · `duration_ms`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-014` · `secrets:` entry is not a store reference — inline literals forbidden ([01 §secrets](./01-envelope.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-017` · duplicate mapping key — no silent last-wins · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-018` · missing required field in a verb body (`infer.prompt` · `exec.command` · `invoke.tool`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-019` · generic structural validation — wrong YAML shape for a field · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-020` · `workflow:` is a scalar — the envelope became an object (`workflow:` then `id:`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-021` · top-level `description:` — it moved into `workflow.description` · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-022` · `tasks:` is a sequence — it became a map keyed by task id · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-023` · a task carries an `id:` field — the map key IS the identity · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-024` · a task carries `depends_on:` — dead since W2 (data → `with:` bindings · control → `after:` predicates · `check --fix` migrates) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-025` · `decode:` with `capture: structured` — that capture already IS an object (`{stdout, stderr, exit_code}`) · type the object with `returns:` instead · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-026` · a declared `entropy` × `clock` contradiction — `ambient × virtual` cannot be both live and reproducible ([01 §determinism](./01-envelope.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-027` · the other declared contradiction — an `entropy: none` or `seeded` run declaring `clock: system`: a reproducible run cannot read the wall clock ([01 §determinism](./01-envelope.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PARSE-028` · `entropy: none` while a structural randomness source is consumed (a live retry `jitter` · `nika:uuid`) — the claim and the run disagree ([01 §determinism](./01-envelope.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-COMP-001` · an `invoke: workflow:` target is not statically resolvable (templated · malformed · unpinned registry ref · [14 §form](./14-composition.md#the-form-normative)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-COMP-002` · the child workflow's effect boundary exceeds `Authority(parent) ∩ declared` ([14 laws 3/4](./14-composition.md#the-ten-laws-normative--g22--constitution-103)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-COMP-003` · the static call graph is not acyclic (self-launch · cycle · [14 law 7](./14-composition.md#the-ten-laws-normative--g22--constitution-103) · `NIKA-SEC-003` is the runtime backstop) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-COMP-004` · the typed call does not compose (args ⋢ inputs, or outputs ⋢ returns · [14 law 2](./14-composition.md#the-ten-laws-normative--g22--constitution-103)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-001` · cycle in the precedence graph G_p = E_d ∪ E_c (incl. self-dependency · via `with:`/`after:`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-002` · `with:`/`after:` references an undeclared task · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-004` · `on_error.recover` references a task downstream of the declaring task (await would deadlock) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-005` · `after:` predicate outside the closed set (`success` · `failure` · `skipped` · `terminal`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-006` · statically dead task — an incoming edge’s pass-set excludes every reachable producer state, or the `when:` gate is false under every reachable upstream combination ([03 §gate algebra](./03-dag.md#the-gate-algebra-v2-normative)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DAG-007` · status compared against a literal outside the vocabulary (`success` · `failure` · `skipped` · `cancelled`) — `==` never matches, `!=` always holds · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-001` · unknown type name (in `types:` · `returns:` · an `outputs:` type) — did-you-mean when close · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-002` · recursive type reference — the `types:` graph must be acyclic · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-003` · `returns:` and `schema:` on the same task — one contract, one spelling · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-004` · `returns:` type unreachable from the declared `decode:` (an object contract over `decode: text` · …) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-005` · a secret-carrying type in a lowered position (reserved with `secret<T>` · W4) · `security_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-006` · regex pattern outside the locked dialect (backreference · lookaround · named group · inline flags · lazy/possessive · `\\b` · `\\p` — [09 §the regex dialect](./09-types.md#the-regex-dialect-normative--locked)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-TYPE-101` · run-time contract violation — the decoded value does not fit `returns:` (`exec:`/`invoke:` lane · `infer:`/`agent:` stay `NIKA-INFER-002`-class) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DEFAULT-001` · a `default:` that does not conform to its own `type:` — the declaration would hand a caller a value its type forbids ([09 §types](./09-types.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-001` · unresolved reference (unknown namespace entry · undeclared `inputs`/`config`/`const`/`secrets`/`with` key) · `variable_error` · false"}],[{"k":"text","text":"`NIKA-VAR-002` · binding cardinality — a jq binding emitted zero or multiple values (evaluation-time · data-dependent) · `variable_error` · false"}],[{"k":"text","text":"`NIKA-VAR-003` · provably-invalid path into a declared `schema:` (static walk · [04](./04-variables.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-004` · jq runtime error while evaluating a binding · `variable_error` · false"}],[{"k":"text","text":"`NIKA-VAR-005` · static expression violation — outside the `cel-subset/0.1` grammar · chained relation · unknown function · statically-non-boolean `when:` root · jq compile error · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-006` · expression type error at evaluation — cross-type compare · non-boolean `when:` value · `for_each` over a non-array · `variable_error` · false"}],[{"k":"text","text":"`NIKA-VAR-007` · bytes value substituted into a string position · `variable_error` · false"}],[{"k":"text","text":"`NIKA-VAR-008` · unclosed `\u0024{{` opener · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-020` · bare `tasks.X` is the envelope, not a value — pick `.output` (closed projection set · 04 §namespaces) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-021` · a `tasks.*` reference outside the boundary (`with:` · `after:` · `on_error.recover` · `on_finally` parent-only · workflow `outputs:`) — hoist it into `with:` (`check --fix` applies it) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VAR-009` · typed `outputs` value did not match its declared `type:` at run end (the output half of the callable contract · [01 §engine MUST](./01-envelope.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VALUES-001` · the pre-flip envelope `vars:` block — dead since the E-split; classify each use into the authority its role commands ([04 §values](./04-variables.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VALUES-002` · the pre-flip envelope `env:` block — dead since the E-split; `config:` is workflow config, `exec.env` is one subprocess's OS environment ([04 §values](./04-variables.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-VALUES-003` · a value-namespace read outside the four-authority family (`\u0024{{ params.X }}` and friends) ([04 §values](./04-variables.md)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-INFER-001` · provider call failed (HTTP error · provider refusal) · `provider_error` · engine-assessed"}],[{"k":"text","text":"`NIKA-INFER-003` · the provider reported no token usage for a priced model — the ledger cannot bill the call honestly (fail-closed · the usage-absence gate, R3-F1) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-INFER-002` · structured output failed `schema:` validation (after any engine-internal retries) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-INFER-003` · the provider reported no token usage for a priced model — the ledger cannot bill the call honestly, so the call fails closed (the usage-absence gate · R3-F1) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-EXEC-001` · non-zero exit code (default capture modes · see [02 §exec](./02-verbs.md#exec--shell-command)) · `process_error` · false"}],[{"k":"text","text":"`NIKA-EXEC-002` · spawn failure (command not found · permission) · `process_error` · false"}],[{"k":"text","text":"`NIKA-INVOKE-001` · unknown tool (unresolvable `nika:`/`mcp:` id) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-INVOKE-002` · tool args failed the tool's schema · `validation_error` · false"}],[{"k":"text","text":"`NIKA-AGENT-001` · `max_turns` exhausted before completion · `budget_error` · false"}],[{"k":"text","text":"`NIKA-AGENT-002` · `max_tokens_total` exhausted before completion · `budget_error` · false"}],[{"k":"text","text":"`NIKA-AGENT-003` · a `skills:` path does not resolve (file missing/unreadable at compose time · [02 §Agent Skills](./02-verbs.md#agent-skills--skills)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-AGENT-004` · a `skills:` file is not a valid Agent Skill (no/unterminated/non-mapping frontmatter · missing/empty `name`/`description`) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-AGENT-005` · the provider reported no token usage for a priced model — every budget and ledger reads the turn as free, so the loop fails closed (the usage-absence gate · R3-F1) · `budget_error` · false"}],[{"k":"text","text":"`NIKA-MCP-001` · MCP server not configured / not reachable at call time · `tool_error` · engine-assessed"}],[{"k":"text","text":"`NIKA-MCP-002` · MCP tool call failed (transport · tool-side error) · `tool_error` · engine-assessed"}],[{"k":"text","text":"`NIKA-SEC-001` · `exec:` blocklist hit · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-002` · agent tool call outside the `tools:` whitelist · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-003` · run-recursion bound — nested-run depth exceeded OR self-launching workflow · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-004` · effect outside the declared `permits:` capability boundary (fs/net/exec/tool · [01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-005` · SSRF block — a `nika:fetch`/`nika:notify` URL resolves to a loopback/private/link-local/metadata target (the always-on engine floor · independent of `permits:`, with ONE carve-out: an exact loopback literal in `permits.net.http` declassifies the floor for that host only · [01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-006` · secret flow — a `secrets.<name>` value reaches an unsanctioned sink (an `exec:` argument · an `invoke:` payload · an `infer:`/`agent:` prompt) · the diagnostic carries the **taint path** + the exact `egress:` clause that would sanction it ([10 §secret flow](./10-authority.md#secret-flow-refusals-carry-their-codes-normative) · rules in [01 §egress](./01-envelope.md#egress--optional--sanctioned-destinations-declassification)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-007` · secret egress — a tainted value reaches the workflow boundary (`outputs:` · where a result leaves the run) · the diagnostic carries the taint path ([10 §secret flow](./10-authority.md#secret-flow-refusals-carry-their-codes-normative)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-008` · a `nika:fetch` whose RESOLVED URL path names a data-as-code class — matched case-insensitively on the final extension; the diagnostic names the class and both repairs ([10 §authority](./10-authority.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-009` · lethal trifecta complete — the declared boundary grants private read (`fs.read` non-empty) + untrusted ingress (a `nika:fetch` builtin invoked · an `mcp:*` tool invoked · an `agent:` whose whitelist admits ingress) + external egress (`net.http` non-empty · an escaping `fs.write` glob · `exec` enabled), the untrusted content **reaches** an egress-capable task's effect surface (a realized flow), and no blocking `invoke: nika:prompt` (no `default:`) dominates it · one finding per ungated tainted egress task, witness-named `source → sink` ([NEP-0002](../governance/nep-0002-lethal-trifecta-human-gate.md) v2.0 · the Rule of Two as a static check · SEC-008 stays allocated to the AUTH plane) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-010` · the approval-capability law is violated ([NEP-0013](../governance/nep-0013-approval-ticket.md) · the 6th invariant) — a rate-limited approval burst (`approval.rate_limited` · the N+1th distinct mint of a run, never a queue) · an approval whose resolved content hash differs from the shown hash (`approval.content_mismatch`) · a ticket replayed outside its run/step/hash scope (`approval.scope_mismatch`) · or the static heterogeneous-batch refusal (one prompt whose descendant closure unleashes two or more of `exec · write · net`) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-011` · preview-commit divergence — the commit digest recomputed at the sink over the exact bytes about to fire differs from the preview digest judged at resolution (one bit of rendered argv · a permuted context field · a mutated tool argument) · the step refuses fail-closed and the receipt carries `divergence: {preview, commit}` — judged = executed at the action scale ([NEP-0015](../governance/nep-0015-preview-commit.md) · F-P6) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-012` · unordered shared writes — two tasks incomparable in the DAG closure whose literal `nika:write`/`nika:edit` paths collide with no ordering edge (`after:` · `with:`) to serialize them, or a `for_each` fan writing one constant path · parallelism is safe exactly where the writes are provably disjoint (NEP-0014 law 1 · F-P15) · `security_error` · false"}],[{"k":"text","text":"`NIKA-SEC-013` · the endorsement mode law — a human gate (`invoke: nika:prompt`) declared under a `policy:` block that names no endorsement mode refuses fail-closed (`endorsement.undeclared_mode` · F-F5 · zero implicit escape), and `endorsement: solo` carried by a workflow with more than one gate refuses as the declaration lying (`endorsement.solo_count` · exactly one endorser) ([10 §policy](./10-authority.md) · NEP-0014 · F-P23) · `security_error` · false"}],[{"k":"text","text":"`NIKA-AUTH-006` · an absent `permits:` block — DeclaredPermits is empty, so every effect the body requires is refused before any token; the diagnostic carries the inferred block, ready to paste ([10 §authority](./10-authority.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-AUTH-007` · an interpolation reaches a permit BOUND (a host · glob · program · env name inside `permits:`) — a bound must be a literal, or the boundary is self-serve ([10 §authority](./10-authority.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-AUTH-008` · an untrusted value reaches a permitted verb's ARGUMENT and its canonical resolved form escapes the step's permit — the diagnostic carries the taint path ([10 §authority](./10-authority.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-AUTH-009` · an `env:` entry naming one of the engine's dangerous variables — an inert dead grant, flagged rather than silently passed ([01 §permits](./01-envelope.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-AUTH-010` · a `net.http` entry carrying a `*` anywhere but as the whole bare-`*` entry — hosts are exact names, and the bare `*` stays the explicit, visible escape ([01 §permits](./01-envelope.md)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-DECIDE-001` · the decision bundle is malformed or violates its own laws (float weight · undeclared evidence key in rules · identity key feeding a technical dimension · missing contradictory fixture · monotonicity violated by the bundle's own fixtures · [11 §nika:decide](./11-decision.md#nikadecide--the-deterministic-kernel-as-a-builtin)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DECIDE-002` · the evidence snapshot does not satisfy the bundle's evidence schema (type misfit · unauthorized source · integrity below the declared floor · undeclared key · [11 §evidence IR](./11-decision.md#evidence-ir-normative--g14)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PORT-001` · a gateway artifact (deployment bundle · capabilities report · lowering report · fidelity report · authority delta) is malformed or violates its laws (an unknown promoted · a `permissive_unsafe` row without refusal · the disclosure ⊆-chain violated · a child authority exceeding its parent · [12 §errors](./12-gateway.md#errors-the-nika-port-namespace--new-in-this-chapter)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-PORT-002` · policy lowering is `permissive_unsafe` — the backend would allow what the policy forbids · refused with the divergence witness ([12 §ExecutionBackend](./12-gateway.md#executionbackend--the-enforcement-contract-normative)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-POLICY-001` · a hard `policy:` rule is violated (`require.human_gate_before` · `forbid.exec_after` · `allow.providers` · `limits.max_tasks`) — the diagnostic names rule + task + witness · check-time, before any token ([10 §policy](./10-authority.md#the-policy-block--optional--named-workflow-law)) · `security_error` · false"}],[{"k":"text","text":"`NIKA-TIMEOUT-001` · task (or for_each iteration) exceeded `timeout:` · `timeout_error` · false"}],[{"k":"text","text":"`NIKA-CANCEL-001` · task cancelled (workflow failure gate · user cancellation) · `cancelled` · false"}],[{"k":"text","text":"`NIKA-ASSERT-001` · an `assert:` claims a level the evidence does not support (a `StaticProof` the IR cannot decide · a mis-leveled obligation · [15 §assert](./15-proof.md#assert--the-authors-obligations-normative)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-LOCK-001` · a dependency resolved that `nika.lock` does not pin, or a hand-edited lock digest does not match ([15 §lock](./15-proof.md#nikalock--the-single-lock-normative--f7)) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-BUILTIN-001` · builtin `invoke:` violates its statically-checkable arg contract (e.g. `nika:fetch` without `url:` · `nika:jq` arg shape) · `validation_error` · false"}],[{"k":"text","text":"`NIKA-BUILTIN-DONE-001` · `nika:done` invoked outside an `agent:` loop · `validation_error` · false"}],[{"k":"text","text":"`NIKA-DRIFT-001` · declared-but-unused — an `inputs:`/`config:`/`const:`/`secrets:` name or a `permits:` entry (exec program · tool glob · net host · fs path) that nothing in the body references · **advisory check hint — never fails the audit** (the report's `is_clean` ignores hints; dead declarations are smell, not failure) · the reverse direction (used-but-undeclared) is the hard `NIKA-VAR-001`/`NIKA-DAG-002`/`NIKA-SEC-004` surface, so **no `NIKA-DRIFT-002` exists** (an unemittable code would be dead weight — the no-duplication law is structural: hard codes name references, drift names declarations, never the same yaml site) · a dynamic consumer POISONS the used set (a shell-form exec hides its programs · an exec child hides the fs path sets · a dynamic URL/path hides the host/path set · an `agent:` whitelist dispatches dynamically — glob ⊆ glob is undecidable) and the category stays silent rather than risk a false positive · the fs read set DOES model the two decidable runtime gates (`nika:glob`'s literal walk root · a `nika:fetch` `multipart:` file part's literal path) · reference implementation nika#661 · `validation_error` · false"}]]},{"k":"p","inline":[{"k":"code","text":"NIKA-PARSE-015"},{"k":"text","text":" is "},{"k":"strong","text":"retired"},{"k":"text","text":" (never reuse): the typed-"},{"k":"code","text":"vars:"},{"k":"text","text":" 6-enum class\ndied with the E-split (R3b · LAW-GRAMMAR-0211) — the "},{"k":"code","text":"type:"},{"k":"text","text":" field of\n"},{"k":"code","text":"inputs:"},{"k":"text","text":"/"},{"k":"code","text":"outputs:"},{"k":"text","text":" declarations speaks the full TypeExpr of\n"},{"k":"link","text":"09-types","href":"./09-types.md"},{"k":"text","text":", so what PARSE-015 refused (the rich forms) is\nadmitted, and what stays outside the grammar refuses via "},{"k":"code","text":"NIKA-TYPE-001"},{"k":"text","text":".\nThe allocation hole is deliberate, per the additive-never-repurposed rule above."}]},{"k":"p","inline":[{"k":"code","text":"NIKA-PARSE-016"},{"k":"text","text":" is "},{"k":"strong","text":"retired"},{"k":"text","text":" (never reuse): the jq-binding-contains-template\nclass folded into "},{"k":"code","text":"NIKA-VAR-005"},{"k":"text","text":" at the deep-conformance registry remap: the\nallocation hole is deliberate, per the additive-never-repurposed rule above."}]},{"k":"p","inline":[{"k":"code","text":"NIKA-DAG-003"},{"k":"text","text":" is "},{"k":"strong","text":"retired"},{"k":"text","text":" (never reuse): « a "},{"k":"code","text":"tasks.X"},{"k":"text","text":" reference with no\ndeclared edge » became INEXPRESSIBLE in W2 « the flow » — the "},{"k":"code","text":"with:"},{"k":"text","text":" binding\nIS the edge (derived, never restated), and a reference outside the boundary\nis "},{"k":"code","text":"NIKA-VAR-021"},{"k":"text","text":". The allocation hole is deliberate."}]},{"k":"h","depth":3,"text":"Taxonomy ownership · the spec table is normative · engines derive","id":"taxonomy-ownership--the-spec-table-is-normative--engines-derive"},{"k":"p","inline":[{"k":"strong","text":"This table, not any engine's source code, owns the taxonomy."},{"k":"text","text":" A\nconformant engine (the Rust reference included) "},{"k":"em","text":"derives"},{"k":"text","text":" its error types\nfrom this section: every spec-relevant error it emits MUST carry a code\nmatching the canonical regex, in the namespace this table assigns to the\nfailure's scope, with the category semantics of §Categories. An engine MAY\nkeep richer internal error machinery (the reference engine's internal\ndiagnostics codes, subsystem-specific numbering, extra metadata). Internal\ncodes are "},{"k":"strong","text":"not"},{"k":"text","text":" spec surface and MUST NOT leak into workflow-visible\nerrors ("},{"k":"code","text":"tasks.X.error"},{"k":"text","text":" · run reports · conformance output) in place of the\ncanonical form. Two consequences ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"A second engine can be error-conformant from this file alone"},{"k":"text","text":": the\nconformance suite matches on "},{"k":"code","text":"code"},{"k":"text","text":" OR "},{"k":"code","text":"namespace"},{"k":"text","text":"+"},{"k":"code","text":"category"},{"k":"text","text":"\n("},{"k":"link","text":"07","href":"./07-conformance.md"},{"k":"text","text":") · nothing requires reading the reference\nimplementation."}],[{"k":"strong","text":"Drift direction is defined"},{"k":"text","text":" · if the reference engine and this table\ndisagree, the table wins and the engine fixes (same rule as the published\nJSON Schema · the prose is normative on conflict per "},{"k":"link","text":"07","href":"./07-conformance.md"},{"k":"text","text":")."}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Categories","id":"categories"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"category"},{"k":"text","text":" field is a closed enum at v1 ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Category · Meaning · `transient` default"}],[{"k":"text","text":"`parse_error` · Workflow YAML is malformed or invalid · false"}],[{"k":"text","text":"`validation_error` · Workflow violates a spec rule (cycle · unknown field · etc.) · false"}],[{"k":"text","text":"`variable_error` · Reference to undefined variable or invalid path · false"}],[{"k":"text","text":"`provider_error` · LLM provider returned an error · true (engine assesses)"}],[{"k":"text","text":"`network_error` · Network failure (DNS · TCP · TLS · timeout) · true"}],[{"k":"text","text":"`tool_error` · Builtin or MCP tool returned an error · depends"}],[{"k":"text","text":"`process_error` · `exec:` subprocess failure (non-zero exit · spawn) · false"}],[{"k":"text","text":"`budget_error` · an `agent:` loop budget exhausted (`max_turns` · `max_tokens_total`) · false"}],[{"k":"text","text":"`security_error` · SSRF · blocklist · capability denied · false"}],[{"k":"text","text":"`timeout_error` · Task or step exceeded its timeout · false"}],[{"k":"text","text":"`cancelled` · Workflow or task cancelled · false"}],[{"k":"text","text":"`internal_error` · Engine bug · unexpected state · false"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Retry policy","id":"retry-policy"},{"k":"p","inline":[{"k":"text","text":"A task MAY declare a "},{"k":"code","text":"retry:"},{"k":"text","text":" block. Retries apply to "},{"k":"strong","text":"transient"},{"k":"text","text":" errors only ("},{"k":"code","text":"error.transient == true"},{"k":"text","text":")."}]},{"k":"h","depth":3,"text":"Syntax","id":"syntax"},{"k":"code","lang":"yaml","text":"flaky_api:\n    invoke:\n      tool: \"nika:fetch\"\n      args:\n        url: \"https://flaky.example.com/data\"\n    retry:\n      max_attempts: 5              # default 1 (no retry)\n      backoff_ms: 1000             # initial backoff\n      backoff_strategy: exponential  # fixed | linear | exponential\n      backoff_max_ms: 30000        # cap on backoff (default 60000)\n      jitter: true                 # randomize backoff (default true · anti-thundering-herd)\n      on_codes:                    # optional · whitelist of codes to retry\n        - NIKA-BUILTIN-FETCH-001\n        - NIKA-PROVIDER-001"},{"k":"h","depth":3,"text":"Fields","id":"fields-1"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`max_attempts` · yes · integer ≥ 1 · Total attempts (including first try)"}],[{"k":"text","text":"`backoff_ms` · no · integer · Initial backoff · default 1000"}],[{"k":"text","text":"`backoff_strategy` · no · enum · `fixed` · `linear` · `exponential` (default `exponential`)"}],[{"k":"text","text":"`backoff_max_ms` · no · integer · Cap · default 60000 (1 min)"}],[{"k":"text","text":"`jitter` · no · boolean · Randomize the computed backoff to avoid thundering-herd · **default true** · engines SHOULD use a full-jitter / equal-jitter family (AWS « exponential backoff and jitter »)"}],[{"k":"text","text":"`on_codes` · no · array · If present · only retry on listed `NIKA-<NS>-<NNN>` codes · else retry all transient"}]]},{"k":"h","depth":3,"text":"Backoff strategies","id":"backoff-strategies"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"fixed"},{"k":"text","text":" · "},{"k":"code","text":"backoff_ms"},{"k":"text","text":" between every attempt"}],[{"k":"code","text":"linear"},{"k":"text","text":" · "},{"k":"code","text":"backoff_ms * attempt"},{"k":"text","text":" between attempts (1s · 2s · 3s · …)"}],[{"k":"code","text":"exponential"},{"k":"text","text":" · "},{"k":"code","text":"backoff_ms * 2^(attempt-1)"},{"k":"text","text":" between attempts (1s · 2s · 4s · 8s · …) · capped at "},{"k":"code","text":"backoff_max_ms"}]]},{"k":"p","inline":[{"k":"text","text":"With "},{"k":"code","text":"jitter: true"},{"k":"text","text":" (the default) the computed delay is randomized (full-jitter\nor equal-jitter family · per AWS « exponential backoff and jitter ») so many\ntasks retrying the same upstream do not synchronize into a thundering herd.\n"},{"k":"code","text":"on_codes"},{"k":"text","text":" lists canonical "},{"k":"code","text":"NIKA-<NS>-<NNN>"},{"k":"text","text":" codes (e.g. "},{"k":"code","text":"NIKA-BUILTIN-FETCH-001"},{"k":"text","text":"), not\nHTTP status numbers."}]},{"k":"h","depth":3,"text":"Conformance","id":"conformance"},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Honor "},{"k":"code","text":"max_attempts"},{"k":"text","text":" strictly"}],[{"k":"text","text":"Use the configured backoff between attempts"}],[{"k":"text","text":"Only retry transient errors ("},{"k":"code","text":"error.transient == true"},{"k":"text","text":") unless "},{"k":"code","text":"on_codes"},{"k":"text","text":" is configured"}],[{"k":"text","text":"Surface the LAST error if all retries fail"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Error recovery · `on_error:`","id":"error-recovery--on_error"},{"k":"p","inline":[{"k":"text","text":"A task MAY declare an "},{"k":"code","text":"on_error:"},{"k":"text","text":" block to recover from non-transient errors (or retried-and-still-failing transient errors)."}]},{"k":"h","depth":3,"text":"Syntax","id":"syntax-1"},{"k":"code","lang":"yaml","text":"api_call:\n    invoke:\n      tool: \"nika:fetch\"\n      args:\n        url: \"https://api.example.com/data\"\n    retry: { max_attempts: 3 }\n    on_error:\n      recover: \u0024{{ tasks.cached_data.output }}    # recovery output · a \u0024{{ }} ref OR a literal\n      # OR\n      # skip: true                          # skip · downstream sees status = skipped\n      # OR\n      # fail_workflow: true                 # explicit · same as no on_error"},{"k":"h","depth":3,"text":"Fields · exactly ONE action + an optional code filter","id":"fields--exactly-one-action--an-optional-code-filter"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Effect · Downstream sees"}],[{"k":"text","text":"`recover: <value>` · Use a recovery output: a `\u0024{{ }}` ref (e.g. another task's output) OR a literal · `status: success` · output = recover value"}],[{"k":"text","text":"`skip: true` · Skip this task on error · **the original error stays readable** at `tasks.X.error` (status is `skipped` · error populated · the one state where both coexist · enables downstream per-code routing) · `status: skipped` · `error` = the original typed error"}],[{"k":"text","text":"`fail_workflow: true` · Fail the whole workflow (default behavior) · n/a (workflow fails)"}],[{"k":"text","text":"`on_codes: [<NIKA-…>]` · **Optional filter** (combinable with exactly one action above) · the action applies ONLY when the final error's `code` is listed · an unlisted code falls through to the default (fail) · the catch-side mirror of `retry.on_codes` (same regex) · per the action"}]]},{"k":"p","inline":[{"k":"code","text":"recover:"},{"k":"text","text":" merges the former "},{"k":"code","text":"fallback:"},{"k":"text","text":" (ref) + "},{"k":"code","text":"value:"},{"k":"text","text":" (literal) into one field\n("},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":" resolves to values either way · 4 modes → 3 · one way)."}]},{"k":"code","lang":"yaml","text":"# Catch-side routing · recover ONLY on timeout · any other code still fails\nslow_fetch:\n    invoke: { tool: \"nika:fetch\", args: { url: \"https://slow.example.com\" } }\n    timeout: \"30s\"\n    on_error:\n      on_codes: [NIKA-TIMEOUT-001]\n      recover: { stale: true, items: [] }"},{"k":"h","depth":3,"text":"`recover:` reference resolution (normative)","id":"recover-reference-resolution-normative"},{"k":"p","inline":[{"k":"text","text":"A "},{"k":"code","text":"recover: \u0024{{ tasks.X.output }}"},{"k":"text","text":" reference is "},{"k":"strong","text":"NOT an execution-order\nedge"},{"k":"text","text":" — it is the "},{"k":"em","text":"recovery"},{"k":"text","text":" surface of the reference boundary\n("},{"k":"link","text":"04 §boundary","href":"./04-variables.md#the-reference-boundary--where-tasks-may-appear"},{"k":"text","text":" ·\nprojected as a "},{"k":"code","text":"recovery"},{"k":"text","text":" edge in "},{"k":"code","text":"graph_format: 2"},{"k":"text","text":", which never schedules).\nResolution happens at "},{"k":"strong","text":"recovery time"},{"k":"text","text":" ·"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"The failing task exhausts "},{"k":"code","text":"retry:"},{"k":"text","text":" · "},{"k":"code","text":"on_error.recover"},{"k":"text","text":" fires."}],[{"k":"text","text":"If the referenced task is already "},{"k":"strong","text":"terminal"},{"k":"text","text":", its value resolves\nimmediately."}],[{"k":"text","text":"If it is still "},{"k":"code","text":"pending"},{"k":"text","text":"/"},{"k":"code","text":"running"},{"k":"text","text":", the engine "},{"k":"strong","text":"awaits its terminal\nstate"},{"k":"text","text":" before resolving (deterministic · never a race · the DAG is\nfinite so the await always terminates)."}],[{"k":"text","text":"If it terminated without a usable value ("},{"k":"code","text":"failure"},{"k":"text","text":" · "},{"k":"code","text":"cancelled"},{"k":"text","text":" ·\n"},{"k":"code","text":"skipped"},{"k":"text","text":"), the reference is unresolved → "},{"k":"code","text":"NIKA-VAR-001"},{"k":"text","text":" → the recovery\nitself fails → the task fails as if "},{"k":"code","text":"on_error:"},{"k":"text","text":" were absent."}]]},{"k":"p","inline":[{"k":"strong","text":"Recovery × `output:` bindings (normative)"},{"k":"text","text":" · when "},{"k":"code","text":"recover:"},{"k":"text","text":" fires, the\nrecovery value "},{"k":"strong","text":"substitutes the raw output BEFORE binding extraction"},{"k":"text","text":":\nthe task's "},{"k":"code","text":"output:"},{"k":"text","text":" jq bindings evaluate over the recovered value exactly\nas they would over a verb response. Downstream consumers stay shape-stable\n("},{"k":"code","text":"tasks.X.title"},{"k":"text","text":" works whether the live call or the fallback produced the\ndata), which is why a recovery source SHOULD match the raw output's shape.\nA binding that fails over the recovered shape errors as usual\n("},{"k":"code","text":"NIKA-VAR-002"},{"k":"text","text":" / "},{"k":"code","text":"NIKA-VAR-004"},{"k":"text","text":") · the recovery does not mask it."}]},{"k":"p","inline":[{"k":"strong","text":"Parse-time acyclicity rule (`NIKA-DAG-004` · `validation_error`)"},{"k":"text","text":" · a\n"},{"k":"code","text":"recover:"},{"k":"text","text":" reference to a task that "},{"k":"strong","text":"transitively depends on the declaring\ntask"},{"k":"text","text":" (through G_p = E_d ∪ E_c) is rejected at parse time. At recovery time\nsuch a task could never reach a terminal state (it is waiting on the failing\ntask): the step-3 await would deadlock. The recovery surface is exempt from\n"},{"k":"em","text":"scheduling-edge creation"},{"k":"text","text":", not from "},{"k":"em","text":"acyclicity"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"Authors SHOULD keep recovery sources cheap and independent (the\nfetch-chain pattern · a local "},{"k":"code","text":"nika:read"},{"k":"text","text":" beside a live fetch)."}]},{"k":"h","depth":3,"text":"Examples","id":"examples"},{"k":"code","lang":"yaml","text":"# Use cached data on API failure\napi_call:\n    invoke: { tool: \"nika:fetch\", args: { url: \"https://api.example.com/data\" } }\n    on_error:\n      recover: \u0024{{ tasks.cached_data.output }}   # a \u0024{{ }} ref\n\n# Use a default on error\nget_count:\n    invoke:\n      tool: \"mcp:db/count_users\"\n    on_error:\n      recover: 0                                 # a literal\n\n# Skip on error · downstream may handle\noptional_step:\n    exec: { command: [\"./optional.sh\"] }\n    on_error:\n      skip: true\n\nnext:\n    after: { optional_step: success }       # strict gate · a skipped producer cancels this path\n    exec: { command: [\"...\"] }"},{"k":"hr"},{"k":"h","depth":2,"text":"Structured output validation","id":"structured-output-validation"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"infer:"},{"k":"text","text":" and "},{"k":"code","text":"agent:"},{"k":"text","text":" verbs may declare a JSON Schema for structured output. If the model returns invalid JSON or fails schema validation, an error of category "},{"k":"code","text":"validation_error"},{"k":"text","text":" is raised."}]},{"k":"p","inline":[{"k":"text","text":"The engine MAY auto-retry validation failures internally (transparent to the\nworkflow) before surfacing the error ("},{"k":"code","text":"NIKA-INFER-002"},{"k":"text","text":"). This behavior is\nengine-configurable: the SAME rule as "},{"k":"link","text":"02 §infer conformance","href":"./02-verbs.md#conformance"},{"k":"text","text":"\n(MAY · engine choice · the two sections state one contract)."}]},{"k":"code","lang":"yaml","text":"extract:\n    infer:\n      prompt: \"Extract entities from · \u0024{{ inputs.text }}\"\n      schema:\n        type: object\n        required: [entities]\n        properties:\n          entities:\n            type: array\n            items:\n              type: object\n              properties:\n                name: { type: string }\n                type: { type: string, enum: [person, place, organization] }\n    retry:\n      max_attempts: 3            # retry on transient errors\n    # validation failures may be retried internally · engine choice"},{"k":"hr"},{"k":"h","depth":2,"text":"Workflow-level error semantics","id":"workflow-level-error-semantics"},{"k":"p","inline":[{"k":"text","text":"If a task fails with no "},{"k":"code","text":"on_error:"},{"k":"text","text":" recovery · the "},{"k":"strong","text":"workflow's final state\nis `failure`"},{"k":"text","text":". What happens to the REST of the DAG is "},{"k":"strong","text":"gate-based · not a\nblanket kill"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"In-flight tasks drain"},{"k":"text","text":" · an engine MUST NOT abort an unrelated running\ntask because a sibling failed (industry default · GitHub Actions\nindependent jobs · Argo running nodes)."}],[{"k":"text","text":"A not-yet-started task is admitted per "},{"k":"strong","text":"GATE-v2"},{"k":"text","text":"\n("},{"k":"link","text":"03 §gate algebra","href":"./03-dag.md#the-gate-algebra-v2-normative"},{"k":"text","text":"): each of\nits edges checks the producer's settled state against that edge's\npass-set. A value edge from the failed task does not admit → the consumer\nis "},{"k":"code","text":"cancelled"},{"k":"text","text":", and the dead path propagates transitively."}],[{"k":"text","text":"A task whose edges DO admit on failure still runs · "},{"k":"code","text":"after: {x: failure}"},{"k":"text","text":"\n(the failure path) · "},{"k":"code","text":"after: {x: terminal}"},{"k":"text","text":" (the "},{"k":"strong","text":"always-pattern"},{"k":"text","text":": a\nfinal notify/report task runs even in a failing workflow) · a\n"},{"k":"code","text":".status"},{"k":"text","text":"/"},{"k":"code","text":".error"},{"k":"text","text":" observation binding."}],[{"k":"text","text":"The workflow's final state stays "},{"k":"code","text":"failure"},{"k":"text","text":" even when always-pattern tasks\nran afterward (any unrecovered task failure decides it)."}],[{"k":"strong","text":"User cancellation"},{"k":"text","text":" (Ctrl+C · API) IS a blanket kill · in-flight tasks\nare cancelled (their "},{"k":"code","text":"on_finally:"},{"k":"text","text":" still runs · "},{"k":"link","text":"03","href":"./03-dag.md#on_finally--optional--cleanup-hook--always-runs"},{"k":"text","text":")."}]]},{"k":"p","inline":[{"k":"text","text":"A workflow's final state is one of ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"State · Meaning"}],[{"k":"text","text":"`success` · All tasks reached terminal state · no unrecovered failures"}],[{"k":"text","text":"`failure` · At least one task failed with no recovery"}],[{"k":"text","text":"`cancelled` · The workflow was cancelled (Ctrl+C · API call · etc.)"}]]},{"k":"p","inline":[{"k":"text","text":"The engine MUST emit a typed completion event with this state."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Forward-compat","id":"forward-compat"},{"k":"p","inline":[{"k":"text","text":"The error structure (fields · categories · namespaces · retry shape · on_error shape) is locked at v1. Additional categories MAY be added in minor bumps (additive only · existing categories never repurposed). Additional retry strategies MAY be added."}]},{"k":"p","inline":[{"k":"text","text":"Out of scope for v0.1 · structured retry conditions (e.g. "},{"k":"code","text":"retry_when: \u0024{{ error.details.status_code == 503 }}"},{"k":"text","text":" · value-conditioned polling · see "},{"k":"link","text":"08 H19","href":"./08-out-of-scope.md#horizon-postures--the--did-you-think-of-x--table-2026-06-10"},{"k":"text","text":") · global on_error handlers (the always-pattern covers notification · §workflow-level semantics) · workflow-level circuit breakers. See "},{"k":"link","text":"08-out-of-scope.md","href":"./08-out-of-scope.md"},{"k":"text","text":"."}]},{"k":"hr"},{"k":"p","inline":[{"k":"text","text":"🦋 "},{"k":"em","text":"Next · [06 · Stdlib contract](./06-stdlib-contract.md)"}]}]

the spec · 05

Errors

Nika has a **typed error model**.

05 · Errors #

Nika has a typed error model. Every error has a code · a category · and structured details. Tasks may declare retry policies and fallback recovery. The workflow itself fails when an unrecovered terminal error reaches a task with no on_error: policy.

Error structure #

Every error is a typed structure ·

json

1{2  "code": "NIKA-INFER-001",3  "category": "provider_error",4  "message": "Anthropic API returned 503 service unavailable",5  "transient": true,6  "details": {7    "provider": "anthropic",8    "model": "claude-3-5-sonnet",9    "status_code": 503,10    "retry_after_secs": 3011  },12  "task_id": "research",13  "attempt": 214}

Fields #

Field · Required · Type · Notes
`code` · yes · string · `NIKA-<NAMESPACE>-<NNN>` · stable identifier
`category` · yes · enum · See category list below
`message` · yes · string · Human-readable description
`transient` · yes · boolean · True if retry might succeed (network · 503 · rate limit)
`details` · no · object · Category-specific structured fields
`task_id` · yes (runtime) · string · Which task this error occurred in
`attempt` · yes (runtime) · integer · Which attempt failed (1-indexed)

Error code namespaces #

Error codes follow the format NIKA-<NAMESPACE>-<NNN> where namespace is 2-9 uppercase letters and NNN is a 3-digit zero-padded number. A code MAY add an optional sub-namespace for self-documentation · NIKA-<NAMESPACE>-<SUB>-<NNN> (4-segment), used per-builtin (NIKA-BUILTIN-WAIT-001 · each builtin owns its own 001-099) or per-field (NIKA-PARSE-WHEN-001 · the when: field of a parse error). The canonical regex is ^NIKA-[A-Z]{2,9}(-[A-Z][A-Z0-9_]{1,15})?-[0-9]{3}$ (also the retry.on_codes / on_error.on_codes validation pattern). The sub-namespace segment admits underscores so underscore-named builtins encode cleanly (NIKA-BUILTIN-JSON_MERGE_PATCH-001).

Namespace · Scope · Reserved range
`NIKA-PARSE` · YAML parse + envelope validation · 001-099
`NIKA-DAG` · DAG topology · cycles · invalid deps · 001-099
`NIKA-VAR` · Variable resolution failures · 001-099
`NIKA-INFER` · `infer:` verb errors · 001-099
`NIKA-EXEC` · `exec:` verb errors · 001-099
`NIKA-INVOKE` · `invoke:` verb errors · 001-099
`NIKA-AGENT` · `agent:` verb errors · 001-099
`NIKA-PROVIDER` · Provider adapter errors · 001-099 per provider
`NIKA-BUILTIN-<BUILTIN>` · Builtin tool errors · per-builtin sub-namespace (`NIKA-BUILTIN-WAIT-001` · `NIKA-BUILTIN-NOTIFY-001` · `NIKA-BUILTIN-INSPECT-001` · `NIKA-BUILTIN-IMAGE_GENERATE-001..007` + `NIKA-BUILTIN-IMAGE_FX-001..006` — the §Media builtins' planes, stdlib page normative · `NIKA-BUILTIN-FETCH-001` — `nika:fetch`'s network/extraction errors, whose instances carry `category: network_error` though the namespace is the uniform `NIKA-BUILTIN`) · 001-099 per builtin
`NIKA-MCP` · MCP client errors · 001-099
`NIKA-SEC` · Security policy violations (SSRF · blocklist) · 001-099
`NIKA-TIMEOUT` · Task or step timeouts · 001-099
`NIKA-TYPE` · Type core · contracts · lowering ([09-types.md](./09-types.md)) · 001-199 (001-099 static · 101+ runtime)
`NIKA-CANCEL` · Task or workflow cancellation · 001-099
`NIKA-IMPL` · Engine internal errors · 001-099
`NIKA-YAML` · YAML profile refusals (anchors · aliases · merge keys · tags · caps · encoding — the R11 law set · [01 §YAML profile](./01-envelope.md#yaml-profile-normative) · pedagogical upgrades of the `NIKA-PARSE` floor) · 001-099
`NIKA-COMP` · Composition (`invoke: workflow:` · [14-composition](./14-composition.md)) · 001-099
`NIKA-DECIDE` · Decision bundles + evidence (`nika:decide` · [11-decision](./11-decision.md)) · 001-099
`NIKA-PORT` · Gateway artifacts (deployment bundle · lowering · fidelity · [12-gateway](./12-gateway.md)) · 001-099
`NIKA-POLICY` · `policy:` hard-rule violations ([10-authority](./10-authority.md)) · 001-099
`NIKA-ASSERT` · `assert:` obligations ([15-proof](./15-proof.md)) · 001-099
`NIKA-LOCK` · `nika.lock` pin violations ([15-proof](./15-proof.md)) · 001-099
`NIKA-REG` · Registry client refusals (resolve · digest · advisory · [registry-v0.1](../registry/registry-v0.1.md) · allocated for the reference engine's `registry:` resolver — engine ADR-106) · 001-099

This table allocates every namespace in use; the machine registry (`canon/diagnostics/registry.yaml`) carries the per-code rows. A v0.1-compliant engine MUST use these namespaces for the canonical categories. New error codes MAY be added in minor bumps (additive · never repurposed).

Concrete v0.1 codes · the normative floor #

The codes below are allocated: a conformant engine emits exactly these codes for these failures (it MAY add more within a namespace's range · never repurpose). This closes the « placeholder » gap: a second engine matches these from this file alone.

Code · Failure · Category · `transient`
`NIKA-PARSE-001` · the YAML itself does not parse (syntax error) · `parse_error` · false
`NIKA-PARSE-002` · missing envelope field (`nika:` / `workflow:` / non-empty `tasks:`) · `validation_error` · false
`NIKA-PARSE-003` · `nika:` version marker is not exactly `v1` · `parse_error` · false
`NIKA-PARSE-004` · `workflow:` id violates `^[a-z][a-z0-9-]*$` · `validation_error` · false
`NIKA-PARSE-005` · unknown field — strict mode rejects anything outside the closed v1 set · `validation_error` · false
`NIKA-PARSE-006` · task id violates `^[a-z][a-z0-9_]*$` (snake_case · CEL-safe · no hyphens) · `validation_error` · false
`NIKA-PARSE-007` · duplicate task id within the workflow · `validation_error` · false
`NIKA-PARSE-008` · task declares no verb — exactly one of `infer`/`exec`/`invoke`/`agent` required · `validation_error` · false
`NIKA-PARSE-009` · task declares multiple verbs — exactly one required · `validation_error` · false
`NIKA-PARSE-010` · `timeout:` violates the quoted Go-duration contract (positive · max 24h · descending units) · `validation_error` · false
`NIKA-PARSE-011` · `retry:` block violates the spec shape (§retry below) · `validation_error` · false
`NIKA-PARSE-012` · `on_error:` block violates the spec shape (fields mutually exclusive) · `validation_error` · false
`NIKA-PARSE-013` · `with:`/`output:` binding uses a reserved name (`output` · `status` · `error` · `started_at` · `ended_at` · `duration_ms`) · `validation_error` · false
`NIKA-PARSE-014` · `secrets:` entry is not a store reference — inline literals forbidden ([01 §secrets](./01-envelope.md)) · `validation_error` · false
`NIKA-PARSE-017` · duplicate mapping key — no silent last-wins · `validation_error` · false
`NIKA-PARSE-018` · missing required field in a verb body (`infer.prompt` · `exec.command` · `invoke.tool`) · `validation_error` · false
`NIKA-PARSE-019` · generic structural validation — wrong YAML shape for a field · `validation_error` · false
`NIKA-PARSE-020` · `workflow:` is a scalar — the envelope became an object (`workflow:` then `id:`) · `validation_error` · false
`NIKA-PARSE-021` · top-level `description:` — it moved into `workflow.description` · `validation_error` · false
`NIKA-PARSE-022` · `tasks:` is a sequence — it became a map keyed by task id · `validation_error` · false
`NIKA-PARSE-023` · a task carries an `id:` field — the map key IS the identity · `validation_error` · false
`NIKA-PARSE-024` · a task carries `depends_on:` — dead since W2 (data → `with:` bindings · control → `after:` predicates · `check --fix` migrates) · `validation_error` · false
`NIKA-PARSE-025` · `decode:` with `capture: structured` — that capture already IS an object (`{stdout, stderr, exit_code}`) · type the object with `returns:` instead · `validation_error` · false
`NIKA-PARSE-026` · a declared `entropy` × `clock` contradiction — `ambient × virtual` cannot be both live and reproducible ([01 §determinism](./01-envelope.md)) · `validation_error` · false
`NIKA-PARSE-027` · the other declared contradiction — an `entropy: none` or `seeded` run declaring `clock: system`: a reproducible run cannot read the wall clock ([01 §determinism](./01-envelope.md)) · `validation_error` · false
`NIKA-PARSE-028` · `entropy: none` while a structural randomness source is consumed (a live retry `jitter` · `nika:uuid`) — the claim and the run disagree ([01 §determinism](./01-envelope.md)) · `validation_error` · false
`NIKA-COMP-001` · an `invoke: workflow:` target is not statically resolvable (templated · malformed · unpinned registry ref · [14 §form](./14-composition.md#the-form-normative)) · `validation_error` · false
`NIKA-COMP-002` · the child workflow's effect boundary exceeds `Authority(parent) ∩ declared` ([14 laws 3/4](./14-composition.md#the-ten-laws-normative--g22--constitution-103)) · `security_error` · false
`NIKA-COMP-003` · the static call graph is not acyclic (self-launch · cycle · [14 law 7](./14-composition.md#the-ten-laws-normative--g22--constitution-103) · `NIKA-SEC-003` is the runtime backstop) · `validation_error` · false
`NIKA-COMP-004` · the typed call does not compose (args ⋢ inputs, or outputs ⋢ returns · [14 law 2](./14-composition.md#the-ten-laws-normative--g22--constitution-103)) · `validation_error` · false
`NIKA-DAG-001` · cycle in the precedence graph G_p = E_d ∪ E_c (incl. self-dependency · via `with:`/`after:`) · `validation_error` · false
`NIKA-DAG-002` · `with:`/`after:` references an undeclared task · `validation_error` · false
`NIKA-DAG-004` · `on_error.recover` references a task downstream of the declaring task (await would deadlock) · `validation_error` · false
`NIKA-DAG-005` · `after:` predicate outside the closed set (`success` · `failure` · `skipped` · `terminal`) · `validation_error` · false
`NIKA-DAG-006` · statically dead task — an incoming edge’s pass-set excludes every reachable producer state, or the `when:` gate is false under every reachable upstream combination ([03 §gate algebra](./03-dag.md#the-gate-algebra-v2-normative)) · `validation_error` · false
`NIKA-DAG-007` · status compared against a literal outside the vocabulary (`success` · `failure` · `skipped` · `cancelled`) — `==` never matches, `!=` always holds · `validation_error` · false
`NIKA-TYPE-001` · unknown type name (in `types:` · `returns:` · an `outputs:` type) — did-you-mean when close · `validation_error` · false
`NIKA-TYPE-002` · recursive type reference — the `types:` graph must be acyclic · `validation_error` · false
`NIKA-TYPE-003` · `returns:` and `schema:` on the same task — one contract, one spelling · `validation_error` · false
`NIKA-TYPE-004` · `returns:` type unreachable from the declared `decode:` (an object contract over `decode: text` · …) · `validation_error` · false
`NIKA-TYPE-005` · a secret-carrying type in a lowered position (reserved with `secret<T>` · W4) · `security_error` · false
`NIKA-TYPE-006` · regex pattern outside the locked dialect (backreference · lookaround · named group · inline flags · lazy/possessive · `\b` · `\p` — [09 §the regex dialect](./09-types.md#the-regex-dialect-normative--locked)) · `validation_error` · false
`NIKA-TYPE-101` · run-time contract violation — the decoded value does not fit `returns:` (`exec:`/`invoke:` lane · `infer:`/`agent:` stay `NIKA-INFER-002`-class) · `validation_error` · false
`NIKA-DEFAULT-001` · a `default:` that does not conform to its own `type:` — the declaration would hand a caller a value its type forbids ([09 §types](./09-types.md)) · `validation_error` · false
`NIKA-VAR-001` · unresolved reference (unknown namespace entry · undeclared `inputs`/`config`/`const`/`secrets`/`with` key) · `variable_error` · false
`NIKA-VAR-002` · binding cardinality — a jq binding emitted zero or multiple values (evaluation-time · data-dependent) · `variable_error` · false
`NIKA-VAR-003` · provably-invalid path into a declared `schema:` (static walk · [04](./04-variables.md)) · `validation_error` · false
`NIKA-VAR-004` · jq runtime error while evaluating a binding · `variable_error` · false
`NIKA-VAR-005` · static expression violation — outside the `cel-subset/0.1` grammar · chained relation · unknown function · statically-non-boolean `when:` root · jq compile error · `validation_error` · false
`NIKA-VAR-006` · expression type error at evaluation — cross-type compare · non-boolean `when:` value · `for_each` over a non-array · `variable_error` · false
`NIKA-VAR-007` · bytes value substituted into a string position · `variable_error` · false
`NIKA-VAR-008` · unclosed `${{` opener · `validation_error` · false
`NIKA-VAR-020` · bare `tasks.X` is the envelope, not a value — pick `.output` (closed projection set · 04 §namespaces) · `validation_error` · false
`NIKA-VAR-021` · a `tasks.*` reference outside the boundary (`with:` · `after:` · `on_error.recover` · `on_finally` parent-only · workflow `outputs:`) — hoist it into `with:` (`check --fix` applies it) · `validation_error` · false
`NIKA-VAR-009` · typed `outputs` value did not match its declared `type:` at run end (the output half of the callable contract · [01 §engine MUST](./01-envelope.md)) · `validation_error` · false
`NIKA-VALUES-001` · the pre-flip envelope `vars:` block — dead since the E-split; classify each use into the authority its role commands ([04 §values](./04-variables.md)) · `validation_error` · false
`NIKA-VALUES-002` · the pre-flip envelope `env:` block — dead since the E-split; `config:` is workflow config, `exec.env` is one subprocess's OS environment ([04 §values](./04-variables.md)) · `validation_error` · false
`NIKA-VALUES-003` · a value-namespace read outside the four-authority family (`${{ params.X }}` and friends) ([04 §values](./04-variables.md)) · `validation_error` · false
`NIKA-INFER-001` · provider call failed (HTTP error · provider refusal) · `provider_error` · engine-assessed
`NIKA-INFER-003` · the provider reported no token usage for a priced model — the ledger cannot bill the call honestly (fail-closed · the usage-absence gate, R3-F1) · `validation_error` · false
`NIKA-INFER-002` · structured output failed `schema:` validation (after any engine-internal retries) · `validation_error` · false
`NIKA-INFER-003` · the provider reported no token usage for a priced model — the ledger cannot bill the call honestly, so the call fails closed (the usage-absence gate · R3-F1) · `validation_error` · false
`NIKA-EXEC-001` · non-zero exit code (default capture modes · see [02 §exec](./02-verbs.md#exec--shell-command)) · `process_error` · false
`NIKA-EXEC-002` · spawn failure (command not found · permission) · `process_error` · false
`NIKA-INVOKE-001` · unknown tool (unresolvable `nika:`/`mcp:` id) · `validation_error` · false
`NIKA-INVOKE-002` · tool args failed the tool's schema · `validation_error` · false
`NIKA-AGENT-001` · `max_turns` exhausted before completion · `budget_error` · false
`NIKA-AGENT-002` · `max_tokens_total` exhausted before completion · `budget_error` · false
`NIKA-AGENT-003` · a `skills:` path does not resolve (file missing/unreadable at compose time · [02 §Agent Skills](./02-verbs.md#agent-skills--skills)) · `validation_error` · false
`NIKA-AGENT-004` · a `skills:` file is not a valid Agent Skill (no/unterminated/non-mapping frontmatter · missing/empty `name`/`description`) · `validation_error` · false
`NIKA-AGENT-005` · the provider reported no token usage for a priced model — every budget and ledger reads the turn as free, so the loop fails closed (the usage-absence gate · R3-F1) · `budget_error` · false
`NIKA-MCP-001` · MCP server not configured / not reachable at call time · `tool_error` · engine-assessed
`NIKA-MCP-002` · MCP tool call failed (transport · tool-side error) · `tool_error` · engine-assessed
`NIKA-SEC-001` · `exec:` blocklist hit · `security_error` · false
`NIKA-SEC-002` · agent tool call outside the `tools:` whitelist · `security_error` · false
`NIKA-SEC-003` · run-recursion bound — nested-run depth exceeded OR self-launching workflow · `security_error` · false
`NIKA-SEC-004` · effect outside the declared `permits:` capability boundary (fs/net/exec/tool · [01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary)) · `security_error` · false
`NIKA-SEC-005` · SSRF block — a `nika:fetch`/`nika:notify` URL resolves to a loopback/private/link-local/metadata target (the always-on engine floor · independent of `permits:`, with ONE carve-out: an exact loopback literal in `permits.net.http` declassifies the floor for that host only · [01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary)) · `security_error` · false
`NIKA-SEC-006` · secret flow — a `secrets.<name>` value reaches an unsanctioned sink (an `exec:` argument · an `invoke:` payload · an `infer:`/`agent:` prompt) · the diagnostic carries the **taint path** + the exact `egress:` clause that would sanction it ([10 §secret flow](./10-authority.md#secret-flow-refusals-carry-their-codes-normative) · rules in [01 §egress](./01-envelope.md#egress--optional--sanctioned-destinations-declassification)) · `security_error` · false
`NIKA-SEC-007` · secret egress — a tainted value reaches the workflow boundary (`outputs:` · where a result leaves the run) · the diagnostic carries the taint path ([10 §secret flow](./10-authority.md#secret-flow-refusals-carry-their-codes-normative)) · `security_error` · false
`NIKA-SEC-008` · a `nika:fetch` whose RESOLVED URL path names a data-as-code class — matched case-insensitively on the final extension; the diagnostic names the class and both repairs ([10 §authority](./10-authority.md)) · `security_error` · false
`NIKA-SEC-009` · lethal trifecta complete — the declared boundary grants private read (`fs.read` non-empty) + untrusted ingress (a `nika:fetch` builtin invoked · an `mcp:*` tool invoked · an `agent:` whose whitelist admits ingress) + external egress (`net.http` non-empty · an escaping `fs.write` glob · `exec` enabled), the untrusted content **reaches** an egress-capable task's effect surface (a realized flow), and no blocking `invoke: nika:prompt` (no `default:`) dominates it · one finding per ungated tainted egress task, witness-named `source → sink` ([NEP-0002](../governance/nep-0002-lethal-trifecta-human-gate.md) v2.0 · the Rule of Two as a static check · SEC-008 stays allocated to the AUTH plane) · `security_error` · false
`NIKA-SEC-010` · the approval-capability law is violated ([NEP-0013](../governance/nep-0013-approval-ticket.md) · the 6th invariant) — a rate-limited approval burst (`approval.rate_limited` · the N+1th distinct mint of a run, never a queue) · an approval whose resolved content hash differs from the shown hash (`approval.content_mismatch`) · a ticket replayed outside its run/step/hash scope (`approval.scope_mismatch`) · or the static heterogeneous-batch refusal (one prompt whose descendant closure unleashes two or more of `exec · write · net`) · `security_error` · false
`NIKA-SEC-011` · preview-commit divergence — the commit digest recomputed at the sink over the exact bytes about to fire differs from the preview digest judged at resolution (one bit of rendered argv · a permuted context field · a mutated tool argument) · the step refuses fail-closed and the receipt carries `divergence: {preview, commit}` — judged = executed at the action scale ([NEP-0015](../governance/nep-0015-preview-commit.md) · F-P6) · `security_error` · false
`NIKA-SEC-012` · unordered shared writes — two tasks incomparable in the DAG closure whose literal `nika:write`/`nika:edit` paths collide with no ordering edge (`after:` · `with:`) to serialize them, or a `for_each` fan writing one constant path · parallelism is safe exactly where the writes are provably disjoint (NEP-0014 law 1 · F-P15) · `security_error` · false
`NIKA-SEC-013` · the endorsement mode law — a human gate (`invoke: nika:prompt`) declared under a `policy:` block that names no endorsement mode refuses fail-closed (`endorsement.undeclared_mode` · F-F5 · zero implicit escape), and `endorsement: solo` carried by a workflow with more than one gate refuses as the declaration lying (`endorsement.solo_count` · exactly one endorser) ([10 §policy](./10-authority.md) · NEP-0014 · F-P23) · `security_error` · false
`NIKA-AUTH-006` · an absent `permits:` block — DeclaredPermits is empty, so every effect the body requires is refused before any token; the diagnostic carries the inferred block, ready to paste ([10 §authority](./10-authority.md)) · `security_error` · false
`NIKA-AUTH-007` · an interpolation reaches a permit BOUND (a host · glob · program · env name inside `permits:`) — a bound must be a literal, or the boundary is self-serve ([10 §authority](./10-authority.md)) · `security_error` · false
`NIKA-AUTH-008` · an untrusted value reaches a permitted verb's ARGUMENT and its canonical resolved form escapes the step's permit — the diagnostic carries the taint path ([10 §authority](./10-authority.md)) · `security_error` · false
`NIKA-AUTH-009` · an `env:` entry naming one of the engine's dangerous variables — an inert dead grant, flagged rather than silently passed ([01 §permits](./01-envelope.md)) · `security_error` · false
`NIKA-AUTH-010` · a `net.http` entry carrying a `*` anywhere but as the whole bare-`*` entry — hosts are exact names, and the bare `*` stays the explicit, visible escape ([01 §permits](./01-envelope.md)) · `security_error` · false
`NIKA-DECIDE-001` · the decision bundle is malformed or violates its own laws (float weight · undeclared evidence key in rules · identity key feeding a technical dimension · missing contradictory fixture · monotonicity violated by the bundle's own fixtures · [11 §nika:decide](./11-decision.md#nikadecide--the-deterministic-kernel-as-a-builtin)) · `validation_error` · false
`NIKA-DECIDE-002` · the evidence snapshot does not satisfy the bundle's evidence schema (type misfit · unauthorized source · integrity below the declared floor · undeclared key · [11 §evidence IR](./11-decision.md#evidence-ir-normative--g14)) · `validation_error` · false
`NIKA-PORT-001` · a gateway artifact (deployment bundle · capabilities report · lowering report · fidelity report · authority delta) is malformed or violates its laws (an unknown promoted · a `permissive_unsafe` row without refusal · the disclosure ⊆-chain violated · a child authority exceeding its parent · [12 §errors](./12-gateway.md#errors-the-nika-port-namespace--new-in-this-chapter)) · `validation_error` · false
`NIKA-PORT-002` · policy lowering is `permissive_unsafe` — the backend would allow what the policy forbids · refused with the divergence witness ([12 §ExecutionBackend](./12-gateway.md#executionbackend--the-enforcement-contract-normative)) · `security_error` · false
`NIKA-POLICY-001` · a hard `policy:` rule is violated (`require.human_gate_before` · `forbid.exec_after` · `allow.providers` · `limits.max_tasks`) — the diagnostic names rule + task + witness · check-time, before any token ([10 §policy](./10-authority.md#the-policy-block--optional--named-workflow-law)) · `security_error` · false
`NIKA-TIMEOUT-001` · task (or for_each iteration) exceeded `timeout:` · `timeout_error` · false
`NIKA-CANCEL-001` · task cancelled (workflow failure gate · user cancellation) · `cancelled` · false
`NIKA-ASSERT-001` · an `assert:` claims a level the evidence does not support (a `StaticProof` the IR cannot decide · a mis-leveled obligation · [15 §assert](./15-proof.md#assert--the-authors-obligations-normative)) · `validation_error` · false
`NIKA-LOCK-001` · a dependency resolved that `nika.lock` does not pin, or a hand-edited lock digest does not match ([15 §lock](./15-proof.md#nikalock--the-single-lock-normative--f7)) · `validation_error` · false
`NIKA-BUILTIN-001` · builtin `invoke:` violates its statically-checkable arg contract (e.g. `nika:fetch` without `url:` · `nika:jq` arg shape) · `validation_error` · false
`NIKA-BUILTIN-DONE-001` · `nika:done` invoked outside an `agent:` loop · `validation_error` · false
`NIKA-DRIFT-001` · declared-but-unused — an `inputs:`/`config:`/`const:`/`secrets:` name or a `permits:` entry (exec program · tool glob · net host · fs path) that nothing in the body references · **advisory check hint — never fails the audit** (the report's `is_clean` ignores hints; dead declarations are smell, not failure) · the reverse direction (used-but-undeclared) is the hard `NIKA-VAR-001`/`NIKA-DAG-002`/`NIKA-SEC-004` surface, so **no `NIKA-DRIFT-002` exists** (an unemittable code would be dead weight — the no-duplication law is structural: hard codes name references, drift names declarations, never the same yaml site) · a dynamic consumer POISONS the used set (a shell-form exec hides its programs · an exec child hides the fs path sets · a dynamic URL/path hides the host/path set · an `agent:` whitelist dispatches dynamically — glob ⊆ glob is undecidable) and the category stays silent rather than risk a false positive · the fs read set DOES model the two decidable runtime gates (`nika:glob`'s literal walk root · a `nika:fetch` `multipart:` file part's literal path) · reference implementation nika#661 · `validation_error` · false

NIKA-PARSE-015 is retired (never reuse): the typed-vars: 6-enum class died with the E-split (R3b · LAW-GRAMMAR-0211) — the type: field of inputs:/outputs: declarations speaks the full TypeExpr of 09-types, so what PARSE-015 refused (the rich forms) is admitted, and what stays outside the grammar refuses via NIKA-TYPE-001. The allocation hole is deliberate, per the additive-never-repurposed rule above.

NIKA-PARSE-016 is retired (never reuse): the jq-binding-contains-template class folded into NIKA-VAR-005 at the deep-conformance registry remap: the allocation hole is deliberate, per the additive-never-repurposed rule above.

NIKA-DAG-003 is retired (never reuse): « a tasks.X reference with no declared edge » became INEXPRESSIBLE in W2 « the flow » — the with: binding IS the edge (derived, never restated), and a reference outside the boundary is NIKA-VAR-021. The allocation hole is deliberate.

Taxonomy ownership · the spec table is normative · engines derive #

This table, not any engine's source code, owns the taxonomy. A conformant engine (the Rust reference included) derives its error types from this section: every spec-relevant error it emits MUST carry a code matching the canonical regex, in the namespace this table assigns to the failure's scope, with the category semantics of §Categories. An engine MAY keep richer internal error machinery (the reference engine's internal diagnostics codes, subsystem-specific numbering, extra metadata). Internal codes are not spec surface and MUST NOT leak into workflow-visible errors (tasks.X.error · run reports · conformance output) in place of the canonical form. Two consequences ·

A second engine can be error-conformant from this file alone: the conformance suite matches on code OR namespace+category (07) · nothing requires reading the reference implementation.
Drift direction is defined · if the reference engine and this table disagree, the table wins and the engine fixes (same rule as the published JSON Schema · the prose is normative on conflict per 07).

Categories #

The category field is a closed enum at v1 ·

Category · Meaning · `transient` default
`parse_error` · Workflow YAML is malformed or invalid · false
`validation_error` · Workflow violates a spec rule (cycle · unknown field · etc.) · false
`variable_error` · Reference to undefined variable or invalid path · false
`provider_error` · LLM provider returned an error · true (engine assesses)
`network_error` · Network failure (DNS · TCP · TLS · timeout) · true
`tool_error` · Builtin or MCP tool returned an error · depends
`process_error` · `exec:` subprocess failure (non-zero exit · spawn) · false
`budget_error` · an `agent:` loop budget exhausted (`max_turns` · `max_tokens_total`) · false
`security_error` · SSRF · blocklist · capability denied · false
`timeout_error` · Task or step exceeded its timeout · false
`cancelled` · Workflow or task cancelled · false
`internal_error` · Engine bug · unexpected state · false

Retry policy #

A task MAY declare a retry: block. Retries apply to transient errors only (error.transient == true).

Syntax #

yaml

1flaky_api:2    ◆invoke:3      tool: "nika:fetch"4      args:5        url: "https://flaky.example.com/data"6    retry:7      max_attempts: 5              # default 1 (no retry)8      backoff_ms: 1000             # initial backoff9      backoff_strategy: exponential  # fixed | linear | exponential10      backoff_max_ms: 30000        # cap on backoff (default 60000)11      jitter: true                 # randomize backoff (default true · anti-thundering-herd)12      on_codes:                    # optional · whitelist of codes to retry13        - NIKA-BUILTIN-FETCH-00114        - NIKA-PROVIDER-001

Fields #

Field · Required · Type · Notes
`max_attempts` · yes · integer ≥ 1 · Total attempts (including first try)
`backoff_ms` · no · integer · Initial backoff · default 1000
`backoff_strategy` · no · enum · `fixed` · `linear` · `exponential` (default `exponential`)
`backoff_max_ms` · no · integer · Cap · default 60000 (1 min)
`jitter` · no · boolean · Randomize the computed backoff to avoid thundering-herd · **default true** · engines SHOULD use a full-jitter / equal-jitter family (AWS « exponential backoff and jitter »)
`on_codes` · no · array · If present · only retry on listed `NIKA-<NS>-<NNN>` codes · else retry all transient

Backoff strategies #

fixed · backoff_ms between every attempt
linear · backoff_ms * attempt between attempts (1s · 2s · 3s · …)
exponential · backoff_ms * 2^(attempt-1) between attempts (1s · 2s · 4s · 8s · …) · capped at backoff_max_ms

With jitter: true (the default) the computed delay is randomized (full-jitter or equal-jitter family · per AWS « exponential backoff and jitter ») so many tasks retrying the same upstream do not synchronize into a thundering herd. on_codes lists canonical NIKA-<NS>-<NNN> codes (e.g. NIKA-BUILTIN-FETCH-001), not HTTP status numbers.

Conformance #

A v0.1-compliant engine MUST ·

Honor max_attempts strictly
Use the configured backoff between attempts
Only retry transient errors (error.transient == true) unless on_codes is configured
Surface the LAST error if all retries fail

Error recovery · `on_error:` #

A task MAY declare an on_error: block to recover from non-transient errors (or retried-and-still-failing transient errors).

Syntax #

yaml

1api_call:2    ◆invoke:3      tool: "nika:fetch"4      args:5        url: "https://api.example.com/data"6    retry: { max_attempts: 3 }7    on_error:8      recover: ${{ tasks.cached_data.output }}    # recovery output · a ${{ }} ref OR a literal9      # OR10      # skip: true                          # skip · downstream sees status = skipped11      # OR12      # fail_workflow: true                 # explicit · same as no on_error

Fields · exactly ONE action + an optional code filter #

Field · Effect · Downstream sees
`recover: <value>` · Use a recovery output: a `${{ }}` ref (e.g. another task's output) OR a literal · `status: success` · output = recover value
`skip: true` · Skip this task on error · **the original error stays readable** at `tasks.X.error` (status is `skipped` · error populated · the one state where both coexist · enables downstream per-code routing) · `status: skipped` · `error` = the original typed error
`fail_workflow: true` · Fail the whole workflow (default behavior) · n/a (workflow fails)
`on_codes: [<NIKA-…>]` · **Optional filter** (combinable with exactly one action above) · the action applies ONLY when the final error's `code` is listed · an unlisted code falls through to the default (fail) · the catch-side mirror of `retry.on_codes` (same regex) · per the action

recover: merges the former fallback: (ref) + value: (literal) into one field (${{ }} resolves to values either way · 4 modes → 3 · one way).

yaml

1# Catch-side routing · recover ONLY on timeout · any other code still fails2slow_fetch:3    ◆invoke: { tool: "nika:fetch", args: { url: "https://slow.example.com" } }4    timeout: "30s"5    on_error:6      on_codes: [NIKA-TIMEOUT-001]7      recover: { stale: true, items: [] }

`recover:` reference resolution (normative) #

A recover: ${{ tasks.X.output }} reference is NOT an execution-order edge — it is the recovery surface of the reference boundary (04 §boundary · projected as a recovery edge in graph_format: 2, which never schedules). Resolution happens at recovery time ·

The failing task exhausts retry: · on_error.recover fires.
If the referenced task is already terminal, its value resolves immediately.
If it is still pending/running, the engine awaits its terminal state before resolving (deterministic · never a race · the DAG is finite so the await always terminates).
If it terminated without a usable value (failure · cancelled · skipped), the reference is unresolved → NIKA-VAR-001 → the recovery itself fails → the task fails as if on_error: were absent.

Recovery × `output:` bindings (normative) · when recover: fires, the recovery value substitutes the raw output BEFORE binding extraction: the task's output: jq bindings evaluate over the recovered value exactly as they would over a verb response. Downstream consumers stay shape-stable (tasks.X.title works whether the live call or the fallback produced the data), which is why a recovery source SHOULD match the raw output's shape. A binding that fails over the recovered shape errors as usual (NIKA-VAR-002 / NIKA-VAR-004) · the recovery does not mask it.

Parse-time acyclicity rule (`NIKA-DAG-004` · `validation_error`) · a recover: reference to a task that transitively depends on the declaring task (through G_p = E_d ∪ E_c) is rejected at parse time. At recovery time such a task could never reach a terminal state (it is waiting on the failing task): the step-3 await would deadlock. The recovery surface is exempt from scheduling-edge creation, not from acyclicity.

Authors SHOULD keep recovery sources cheap and independent (the fetch-chain pattern · a local nika:read beside a live fetch).

Examples #

yaml

1# Use cached data on API failure2api_call:3    ◆invoke: { tool: "nika:fetch", args: { url: "https://api.example.com/data" } }4    on_error:5      recover: ${{ tasks.cached_data.output }}   # a ${{ }} ref67# Use a default on error8get_count:9    ◆invoke:10      tool: "mcp:db/count_users"11    on_error:12      recover: 0                                 # a literal1314# Skip on error · downstream may handle15optional_step:16    ▷exec: { command: ["./optional.sh"] }17    on_error:18      skip: true1920next:21    after: { optional_step: success }       # strict gate · a skipped producer cancels this path22    ▷exec: { command: ["..."] }

Structured output validation #

The infer: and agent: verbs may declare a JSON Schema for structured output. If the model returns invalid JSON or fails schema validation, an error of category validation_error is raised.

The engine MAY auto-retry validation failures internally (transparent to the workflow) before surfacing the error (NIKA-INFER-002). This behavior is engine-configurable: the SAME rule as 02 §infer conformance (MAY · engine choice · the two sections state one contract).

yaml

1extract:2    ◇infer:3      prompt: "Extract entities from · ${{ inputs.text }}"4      schema:5        type: object6        required: [entities]7        properties:8          entities:9            type: array10            items:11              type: object12              properties:13                name: { type: string }14                type: { type: string, enum: [person, place, organization] }15    retry:16      max_attempts: 3            # retry on transient errors17    # validation failures may be retried internally · engine choice

Workflow-level error semantics #

If a task fails with no on_error: recovery · the workflow's final state is `failure`. What happens to the REST of the DAG is gate-based · not a blanket kill ·

In-flight tasks drain · an engine MUST NOT abort an unrelated running task because a sibling failed (industry default · GitHub Actions independent jobs · Argo running nodes).
A not-yet-started task is admitted per GATE-v2 (03 §gate algebra): each of its edges checks the producer's settled state against that edge's pass-set. A value edge from the failed task does not admit → the consumer is cancelled, and the dead path propagates transitively.
A task whose edges DO admit on failure still runs · after: {x: failure} (the failure path) · after: {x: terminal} (the always-pattern: a final notify/report task runs even in a failing workflow) · a .status/.error observation binding.
The workflow's final state stays failure even when always-pattern tasks ran afterward (any unrecovered task failure decides it).
User cancellation (Ctrl+C · API) IS a blanket kill · in-flight tasks are cancelled (their on_finally: still runs · 03).

A workflow's final state is one of ·

State · Meaning
`success` · All tasks reached terminal state · no unrecovered failures
`failure` · At least one task failed with no recovery
`cancelled` · The workflow was cancelled (Ctrl+C · API call · etc.)

The engine MUST emit a typed completion event with this state.

Forward-compat #

The error structure (fields · categories · namespaces · retry shape · on_error shape) is locked at v1. Additional categories MAY be added in minor bumps (additive only · existing categories never repurposed). Additional retry strategies MAY be added.

Out of scope for v0.1 · structured retry conditions (e.g. retry_when: ${{ error.details.status_code == 503 }} · value-conditioned polling · see 08 H19) · global on_error handlers (the always-pattern covers notification · §workflow-level semantics) · workflow-level circuit breakers. See 08-out-of-scope.md.

🦋 Next · [06 · Stdlib contract](./06-stdlib-contract.md)

nika-spec@6ac29351a · 05-errors.md · sha256 fd4a32c60b7ac832… · the pack upstream