{
 "$schema": "https://nika.sh/schema/errors-catalog.json",
 "version": 3,
 "description": "Nika error catalog · generated from nika-spec canon.yaml (spec/05-errors.md is the prose home · the registry is the v0.1 normative floor · engines may add codes within a namespace · never repurpose). Code format ^NIKA-[A-Z]{2,9}(-[A-Z][A-Z0-9_]{1,15})?-[0-9]{3}$.",
 "spec": "https://github.com/supernovae-st/nika-spec/blob/main/spec/05-errors.md",
 "namespaces": {
  "NIKA-AGENT": {
   "scope": "agent: verb errors",
   "range": "001-099"
  },
  "NIKA-BUILTIN": {
   "scope": "Builtin tool errors · per-builtin sub-namespace",
   "range": "001-099"
  },
  "NIKA-CANCEL": {
   "scope": "Task or workflow cancellation",
   "range": "001-099"
  },
  "NIKA-DAG": {
   "scope": "DAG topology · cycles · invalid deps",
   "range": "001-099"
  },
  "NIKA-EXEC": {
   "scope": "exec: verb errors",
   "range": "001-099"
  },
  "NIKA-IMPL": {
   "scope": "Engine internal errors",
   "range": "001-099"
  },
  "NIKA-INFER": {
   "scope": "infer: verb errors",
   "range": "001-099"
  },
  "NIKA-INVOKE": {
   "scope": "invoke: verb errors",
   "range": "001-099"
  },
  "NIKA-MCP": {
   "scope": "MCP client errors",
   "range": "001-099"
  },
  "NIKA-PARSE": {
   "scope": "YAML parse + envelope validation",
   "range": "001-099"
  },
  "NIKA-PROVIDER": {
   "scope": "Provider adapter errors",
   "range": "001-099"
  },
  "NIKA-SEC": {
   "scope": "Security policy violations (SSRF · blocklist)",
   "range": "001-099"
  },
  "NIKA-TIMEOUT": {
   "scope": "Task or step timeouts",
   "range": "001-099"
  },
  "NIKA-VAR": {
   "scope": "Variable resolution failures",
   "range": "001-099"
  }
 },
 "categories": [
  "parse_error",
  "validation_error",
  "variable_error",
  "provider_error",
  "network_error",
  "tool_error",
  "process_error",
  "budget_error",
  "security_error",
  "timeout_error",
  "cancelled",
  "internal_error"
 ],
 "codes": [
  {
   "code": "NIKA-PARSE-001",
   "category": "parse_error",
   "transient": "false",
   "failure": "the YAML itself does not parse (syntax error)"
  },
  {
   "code": "NIKA-PARSE-002",
   "category": "validation_error",
   "transient": "false",
   "failure": "missing envelope field (nika: / workflow: / non-empty tasks:)"
  },
  {
   "code": "NIKA-PARSE-003",
   "category": "parse_error",
   "transient": "false",
   "failure": "nika: version marker is not exactly v1"
  },
  {
   "code": "NIKA-PARSE-004",
   "category": "validation_error",
   "transient": "false",
   "failure": "workflow: id violates ^[a-z][a-z0-9-]*$"
  },
  {
   "code": "NIKA-PARSE-005",
   "category": "validation_error",
   "transient": "false",
   "failure": "unknown field — strict mode rejects anything outside the closed v1 set"
  },
  {
   "code": "NIKA-PARSE-006",
   "category": "validation_error",
   "transient": "false",
   "failure": "task id violates ^[a-z][a-z0-9_]*$ (snake_case · CEL-safe · no hyphens)"
  },
  {
   "code": "NIKA-PARSE-007",
   "category": "validation_error",
   "transient": "false",
   "failure": "duplicate task id within the workflow"
  },
  {
   "code": "NIKA-PARSE-008",
   "category": "validation_error",
   "transient": "false",
   "failure": "task declares no verb — exactly one of infer/exec/invoke/agent required"
  },
  {
   "code": "NIKA-PARSE-009",
   "category": "validation_error",
   "transient": "false",
   "failure": "task declares multiple verbs — exactly one required"
  },
  {
   "code": "NIKA-PARSE-010",
   "category": "validation_error",
   "transient": "false",
   "failure": "timeout: violates the quoted Go-duration contract (positive · max 24h · descending units)"
  },
  {
   "code": "NIKA-PARSE-011",
   "category": "validation_error",
   "transient": "false",
   "failure": "retry: block violates the spec shape"
  },
  {
   "code": "NIKA-PARSE-012",
   "category": "validation_error",
   "transient": "false",
   "failure": "on_error: block violates the spec shape (fields mutually exclusive)"
  },
  {
   "code": "NIKA-PARSE-013",
   "category": "validation_error",
   "transient": "false",
   "failure": "with:/output: binding uses a reserved name (output · status · error · started_at · ended_at · duration_ms)"
  },
  {
   "code": "NIKA-PARSE-014",
   "category": "validation_error",
   "transient": "false",
   "failure": "secrets: entry is not a store reference — inline literals forbidden"
  },
  {
   "code": "NIKA-PARSE-015",
   "category": "validation_error",
   "transient": "false",
   "failure": "typed vars: declaration malformed (type in string/number/integer/boolean/array/object)"
  },
  {
   "code": "NIKA-PARSE-017",
   "category": "validation_error",
   "transient": "false",
   "failure": "duplicate mapping key — no silent last-wins"
  },
  {
   "code": "NIKA-PARSE-018",
   "category": "validation_error",
   "transient": "false",
   "failure": "missing required field in a verb body (infer.prompt · exec.command · invoke.tool)"
  },
  {
   "code": "NIKA-PARSE-019",
   "category": "validation_error",
   "transient": "false",
   "failure": "generic structural validation — wrong YAML shape for a field"
  },
  {
   "code": "NIKA-DAG-001",
   "category": "validation_error",
   "transient": "false",
   "failure": "cycle in depends_on (incl. self-dependency)"
  },
  {
   "code": "NIKA-DAG-002",
   "category": "validation_error",
   "transient": "false",
   "failure": "depends_on references an undeclared task"
  },
  {
   "code": "NIKA-DAG-003",
   "category": "validation_error",
   "transient": "false",
   "failure": "a tasks.X reference with no declared edge"
  },
  {
   "code": "NIKA-DAG-004",
   "category": "validation_error",
   "transient": "false",
   "failure": "on_error.recover references a task downstream of the declaring task (await would deadlock)"
  },
  {
   "code": "NIKA-VAR-001",
   "category": "variable_error",
   "transient": "false",
   "failure": "unresolved reference (unknown namespace entry · undeclared env/vars key)"
  },
  {
   "code": "NIKA-VAR-002",
   "category": "variable_error",
   "transient": "false",
   "failure": "binding cardinality — a jq binding emitted zero or multiple values"
  },
  {
   "code": "NIKA-VAR-003",
   "category": "validation_error",
   "transient": "false",
   "failure": "provably-invalid path into a declared schema (static walk)"
  },
  {
   "code": "NIKA-VAR-004",
   "category": "variable_error",
   "transient": "false",
   "failure": "jq runtime error while evaluating a binding"
  },
  {
   "code": "NIKA-VAR-005",
   "category": "validation_error",
   "transient": "false",
   "failure": "static expression violation — outside cel-subset/0.1 · chained relation · unknown function · non-boolean when: root · jq compile error"
  },
  {
   "code": "NIKA-VAR-006",
   "category": "variable_error",
   "transient": "false",
   "failure": "expression type error at evaluation — cross-type compare · non-boolean when: value · for_each over a non-array"
  },
  {
   "code": "NIKA-VAR-007",
   "category": "variable_error",
   "transient": "false",
   "failure": "bytes value substituted into a string position"
  },
  {
   "code": "NIKA-VAR-008",
   "category": "validation_error",
   "transient": "false",
   "failure": "unclosed ${{ opener"
  },
  {
   "code": "NIKA-VAR-009",
   "category": "validation_error",
   "transient": "false",
   "failure": "typed outputs value did not match its declared type: at run end (the output half of the callable contract)"
  },
  {
   "code": "NIKA-INFER-001",
   "category": "provider_error",
   "transient": "engine-assessed",
   "failure": "provider call failed (HTTP error · provider refusal)"
  },
  {
   "code": "NIKA-INFER-002",
   "category": "validation_error",
   "transient": "false",
   "failure": "structured output failed schema validation (after any engine-internal retries)"
  },
  {
   "code": "NIKA-EXEC-001",
   "category": "process_error",
   "transient": "false",
   "failure": "non-zero exit code (default capture modes)"
  },
  {
   "code": "NIKA-EXEC-002",
   "category": "process_error",
   "transient": "false",
   "failure": "spawn failure (command not found · permission)"
  },
  {
   "code": "NIKA-INVOKE-001",
   "category": "validation_error",
   "transient": "false",
   "failure": "unknown tool (unresolvable nika:/mcp: id)"
  },
  {
   "code": "NIKA-INVOKE-002",
   "category": "validation_error",
   "transient": "false",
   "failure": "tool args failed the tool's schema"
  },
  {
   "code": "NIKA-AGENT-001",
   "category": "budget_error",
   "transient": "false",
   "failure": "max_turns exhausted before completion"
  },
  {
   "code": "NIKA-AGENT-002",
   "category": "budget_error",
   "transient": "false",
   "failure": "max_tokens_total exhausted before completion"
  },
  {
   "code": "NIKA-MCP-001",
   "category": "tool_error",
   "transient": "engine-assessed",
   "failure": "MCP server not configured / not reachable at call time"
  },
  {
   "code": "NIKA-MCP-002",
   "category": "tool_error",
   "transient": "engine-assessed",
   "failure": "MCP tool call failed (transport · tool-side error)"
  },
  {
   "code": "NIKA-SEC-001",
   "category": "security_error",
   "transient": "false",
   "failure": "exec: blocklist hit"
  },
  {
   "code": "NIKA-SEC-002",
   "category": "security_error",
   "transient": "false",
   "failure": "agent tool call outside the tools: whitelist"
  },
  {
   "code": "NIKA-SEC-003",
   "category": "security_error",
   "transient": "false",
   "failure": "run-recursion bound — nested-run depth exceeded OR self-launching workflow"
  },
  {
   "code": "NIKA-SEC-004",
   "category": "security_error",
   "transient": "false",
   "failure": "effect outside the declared permits: capability boundary (fs/net/exec/tool)"
  },
  {
   "code": "NIKA-SEC-005",
   "category": "security_error",
   "transient": "false",
   "failure": "SSRF block — a nika:fetch/nika:notify URL resolves to a loopback/private/link-local/metadata target (always-on engine floor · independent of permits:)"
  },
  {
   "code": "NIKA-TIMEOUT-001",
   "category": "timeout_error",
   "transient": "false",
   "failure": "task (or for_each iteration) exceeded timeout:"
  },
  {
   "code": "NIKA-CANCEL-001",
   "category": "cancelled",
   "transient": "false",
   "failure": "task cancelled (workflow failure gate · user cancellation)"
  },
  {
   "code": "NIKA-BUILTIN-001",
   "category": "validation_error",
   "transient": "false",
   "failure": "builtin invoke violates its statically-checkable arg contract (e.g. nika:fetch without url: · nika:jq arg shape)"
  },
  {
   "code": "NIKA-BUILTIN-DONE-001",
   "category": "validation_error",
   "transient": "false",
   "failure": "nika:done invoked outside an agent: loop"
  }
 ]
}