# 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)
#   - `on_finally:` in its FULL mini form · `when:` + `timeout:` + verb
#     (03 showed the minimal form) · cleanup errors are logged, never
#     propagated · a task that never STARTED runs no cleanup at all
#
# 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: v1
workflow:
  id: 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"
    on_finally:
      # The FULL mini-task form: `when:` + `timeout:` + exactly one verb —
      # the closed shape (03 showed the minimal one). It runs once the
      # parent has STARTED, on every settle — and its errors are logged,
      # never propagated: a cleanup can never turn a green run red.
      - 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

the path · 12

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

run itnika try 12-failure-routing

12-failure-routing.nika.yaml

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#   - `on_finally:` in its FULL mini form · `when:` + `timeout:` + verb21#     (03 showed the minimal form) · cleanup errors are logged, never22#     propagated · a task that never STARTED runs no cleanup at all23#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: v130workflow:31  id: failure-routing3233⛨permits:34  ⛨exec: false35  ⛨tools: ["nika:assert", "nika:log", "nika:write"]36  ⛨fs:37    ⛨write: ["out/incident.md", "out/release-note.md"]3839inputs:40  drill:41    type: bool42    default: false43    required: true44    description: "true = rehearse the failure path · the deploy fails on purpose"4546tasks:47  deploy:48    # The assert stands in for the risky step so the drill stays offline49    # and deterministic — in a real file this is the release command. When50    # `--var drill=true` the condition is false and the task settles51    # `failure`, which is exactly what the two arms below route on.52    ◆invoke:53      tool: "nika:assert"54      args:55        condition: "${{ inputs.drill == false }}"56        message: "drill requested · the deploy step fails on purpose"57    on_finally:58      # The FULL mini-task form: `when:` + `timeout:` + exactly one verb —59      # the closed shape (03 showed the minimal one). It runs once the60      # parent has STARTED, on every settle — and its errors are logged,61      # never propagated: a cleanup can never turn a green run red.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: true95

nika-spec@6ac29351a · sha256 c8fd3d4b38d9c262…