# SPDX-License-Identifier: Apache-2.0
# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json
#
# 12 · Failure routing — the paths a run takes when it breaks.
#
# 03 drew control edges with `after:` and `success`/`skipped`. This lesson
# adds the arm nobody rehearses: a task that runs ONLY when its producer
# fails, and a cleanup hook in its full form. The file is a drill — flip
# one flag and watch the failure path fire, offline, deterministically.
#
# Demonstrates ·
#   - `after: { deploy: failure }` · the pass-set is strictly {failure} —
#     it admits neither `success` nor `cancelled` (the whatever-happens
#     word is `terminal`)
#   - a skipped arm is a VALUE · on the green run the failure arm settles
#     `cancelled`, which is dead-path elimination, not an error
#   - real WORK on the failure path · the sanctioned use — `retry:` covers
#     transient errors, `on_error: recover:` covers a fallback value, a
#     failure-edge task is for work (one-obvious-way/003 · /004)
#   - cleanup as a TASK on an `unwind` edge · `when:` + `timeout:` are the
#     ordinary task fields, not a second grammar · cleanup errors are logged,
#     never propagated · a producer that never STARTED unwinds nothing
#
# Run · nika run examples/12-failure-routing.nika.yaml
#   the drill · nika run examples/12-failure-routing.nika.yaml --var drill=true
#     — the deploy fails ON PURPOSE, the run exits red, and out/incident.md
#     is the artifact that proves the failure arm ran.

nika: failure-routing

permits:
  exec: false
  tools: ["nika:assert", "nika:log", "nika:write"]
  fs:
    write: ["out/incident.md", "out/release-note.md"]

inputs:
  drill:
    type: bool
    default: false
    required: true
    description: "true = rehearse the failure path · the deploy fails on purpose"

tasks:
  deploy:
    # The assert stands in for the risky step so the drill stays offline
    # and deterministic — in a real file this is the release command. When
    # `--var drill=true` the condition is false and the task settles
    # `failure`, which is exactly what the two arms below route on.
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ inputs.drill == false }}"
        message: "drill requested · the deploy step fails on purpose"
  release_lock:
    # Cleanup is a TASK on an `unwind` edge — `when:` and `timeout:` are the
    # ordinary task fields, not a second grammar. It runs once `deploy` has
    # STARTED, on every settle — and its errors are logged, never propagated:
    # a cleanup can never turn a green run red. An unwind task may read the
    # producer it unwinds (settled by definition) and nothing else.
    after: { deploy: unwind }
    when: ${{ tasks.deploy.status != "success" }}
    timeout: "10s"
    invoke:
      tool: "nika:log"
      args:
        level: warn
        message: "deploy settled ${{ tasks.deploy.status }} · lock released"

  publish:
    after: { deploy: success }
    invoke:
      tool: "nika:write"
      args:
        path: "out/release-note.md"
        content: "release went out · deploy green\n"
        create_dirs: true
        overwrite: true

  rollback:
    # Strictly the failure arm. On the green run this task settles
    # `cancelled` — its producer never entered the pass-set, so the path is
    # eliminated as a value, not reported as an error; the render says so
    # in one line: `⊘ rollback  gate: an edge did not admit`. On the drill
    # run it does real work: the incident record IS the reason this is a
    # task and not a `recover:`.
    after: { deploy: failure }
    invoke:
      tool: "nika:write"
      args:
        path: "out/incident.md"
        content: "deploy failed · rollback engaged · see the trace for the settle order\n"
        create_dirs: true
        overwrite: true

outputs:
  # The settle the two arms routed on. Measured on the green run:
  # `--output json` hands back {"deploy_status":"success"}.
  deploy_status: ${{ tasks.deploy.status }}

the path · 12

Failure routing — the paths a run takes when it breaks.

run itnika try 12-failure-routing

12-failure-routing.nika.yamlsource

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# 12 · Failure routing — the paths a run takes when it breaks.5#6# 03 drew control edges with `after:` and `success`/`skipped`. This lesson7# adds the arm nobody rehearses: a task that runs ONLY when its producer8# fails, and a cleanup hook in its full form. The file is a drill — flip9# one flag and watch the failure path fire, offline, deterministically.10#11# Demonstrates ·12#   - `after: { deploy: failure }` · the pass-set is strictly {failure} —13#     it admits neither `success` nor `cancelled` (the whatever-happens14#     word is `terminal`)15#   - a skipped arm is a VALUE · on the green run the failure arm settles16#     `cancelled`, which is dead-path elimination, not an error17#   - real WORK on the failure path · the sanctioned use — `retry:` covers18#     transient errors, `on_error: recover:` covers a fallback value, a19#     failure-edge task is for work (one-obvious-way/003 · /004)20#   - cleanup as a TASK on an `unwind` edge · `when:` + `timeout:` are the21#     ordinary task fields, not a second grammar · cleanup errors are logged,22#     never propagated · a producer that never STARTED unwinds nothing23#24# Run · nika run examples/12-failure-routing.nika.yaml25#   the drill · nika run examples/12-failure-routing.nika.yaml --var drill=true26#     — the deploy fails ON PURPOSE, the run exits red, and out/incident.md27#     is the artifact that proves the failure arm ran.2829nika: failure-routing3031⛨permits:32  ⛨exec: false33  ⛨tools: ["nika:assert", "nika:log", "nika:write"]34  ⛨fs:35    ⛨write: ["out/incident.md", "out/release-note.md"]3637inputs:38  drill:39    type: bool40    default: false41    required: true42    description: "true = rehearse the failure path · the deploy fails on purpose"4344tasks:45  deploy:46    # The assert stands in for the risky step so the drill stays offline47    # and deterministic — in a real file this is the release command. When48    # `--var drill=true` the condition is false and the task settles49    # `failure`, which is exactly what the two arms below route on.50    ◆invoke:51      tool: "nika:assert"52      args:53        condition: "${{ inputs.drill == false }}"54        message: "drill requested · the deploy step fails on purpose"55  release_lock:56    # Cleanup is a TASK on an `unwind` edge — `when:` and `timeout:` are the57    # ordinary task fields, not a second grammar. It runs once `deploy` has58    # STARTED, on every settle — and its errors are logged, never propagated:59    # a cleanup can never turn a green run red. An unwind task may read the60    # producer it unwinds (settled by definition) and nothing else.61    after: { deploy: unwind }62    when: ${{ tasks.deploy.status != "success" }}63    timeout: "10s"64    ◆invoke:65      tool: "nika:log"66      args:67        level: warn68        message: "deploy settled ${{ tasks.deploy.status }} · lock released"6970  publish:71    after: { deploy: success }72    ◆invoke:73      tool: "nika:write"74      args:75        path: "out/release-note.md"76        content: "release went out · deploy green\n"77        create_dirs: true78        overwrite: true7980  rollback:81    # Strictly the failure arm. On the green run this task settles82    # `cancelled` — its producer never entered the pass-set, so the path is83    # eliminated as a value, not reported as an error; the render says so84    # in one line: `⊘ rollback  gate: an edge did not admit`. On the drill85    # run it does real work: the incident record IS the reason this is a86    # task and not a `recover:`.87    after: { deploy: failure }88    ◆invoke:89      tool: "nika:write"90      args:91        path: "out/incident.md"92        content: "deploy failed · rollback engaged · see the trace for the settle order\n"93        create_dirs: true94        overwrite: true9596outputs:97  # The settle the two arms routed on. Measured on the green run:98  # `--output json` hands back {"deploy_status":"success"}.99  deploy_status: ${{ tasks.deploy.status }}100

nika-spec@2b3d6ac3e · sha256 8e19aed549838bd3…