fanout

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# TEMPLATE · fanout · discover a collection → process every item in parallel → merge.5#6#   [discover]──▶[process ∥×N]───▶[survivors]──▶[merge]7#   nika:glob     for_each·infer    nika:jq        infer8#9# The "do this for EVERY one of them" job, where you do not know how many there10# are until the run starts. Discovery yields a collection, `for_each` fans it11# out under a real leash (bounded parallelism, per-item timeout, retries), one12# bad item cannot sink the batch, and the survivors merge into a single answer.13#14# Demonstrates ·15#   - `for_each:` over a RUNTIME collection · the fan width is discovered, never16#     written down17#   - the full leash · `max_parallel` + `timeout` + `retry` + `fail_fast: false`18#   - `on_error: recover: null` + a null-aware fan-in · a failed item becomes a19#     hole at its index, order is preserved, the batch survives20#21# Needs · nothing. Scaffolds and runs green in an empty directory — an empty22#   discovery skips the fan-out and the fan-in still returns a value.23#24# Run · nika run <file> --model mock/echo    # offline rehearsal25nika: v126workflow:27  id: fanout-template           # SLOT: kebab-case workflow id28  # SLOT: one honest sentence — `nika new` matches intents against these words29  description: "do the same step for each item · discover the collection · process in parallel · merge"30​31# SLOT: provider/model · local · zero key. Measured seat — `ollama/llama3.2:3b`.32# `--model mock/echo` needs no seat and is the path this file guarantees.33model: ollama/llama3.2:3b34​35run:36  # A `timeout:` is a deadline, and a deadline needs a clock. Declaring it says37  # out loud which one: `system` is the ambient wall clock (the honest default);38  # `virtual` drives a simulated clock for deterministic tests.39  clock: system40​41const:42  collection_source: "./items"      # SLOT: where the collection comes from43​44⛨permits:45  ⛨tools: ["nika:glob", "nika:jq", "nika:read"]46  ⛨fs:47    # TWO entries, and both earn their place. `nika:glob` is gated on the48    # DIRECTORY it walks, not on the files it returns — measured: with49    # `./items/*.md` here (the pattern) the run dies `NIKA-SEC-004 ·50    # ./items resolves outside the declared permits.fs.read boundary`,51    # because `*` never crosses `/` and so never matches `./items` itself.52    # And `nika:read` is gated on the FILES — a directory grant does not53    # cover its children (measured: dir-only here made every per-item read54    # die SEC-004, `recover: null` swallowed each, and the model was55    # handed nulls — a green run inventing content). A deeper pattern56    # (`./items/**/*.md`) walks deeper and needs `./items/**` for both.57    ⛨read: ["./items", "./items/*"]58​59tasks:60  discover:61    ◆invoke:                         # SLOT: glob / fetch sitemap / exec + jq split62      tool: "nika:glob"63      args: { pattern: "${{ const.collection_source }}/*.md" }64​65  # `discover` hands back PATH STRINGS — a prompt that interpolates the raw66  # item shows the model a FILENAME, never the file (measured: a green run67  # whose fluent « report » was invented from the names alone — check, mock68  # rehearsal and run all green around it). Reading the item is its own fan.69  # Delete this task — and fan `process` over `discover` — when your items70  # already ARE the content (an inline list · fetched records). Need each71  # content paired with its path? `resume-screener` shows the transpose.72  read:73    with:74      discover: ${{ tasks.discover.output }}75    for_each: ${{ with.discover }}76    max_parallel: 877    fail_fast: false78    on_error:79      recover: null                 # an unreadable item yields null · the batch lives80    ◆invoke:81      tool: "nika:read"82      args: { path: "${{ item }}" }83​84  process:85    with:86      read: ${{ tasks.read.output }}87    # The quiet-day guard: an EMPTY discovery skips the `read` fan, and a88    # skipped task hands NULL — which a bare for_each refuses (NIKA-VAR-006).89    # The ternary keeps the no-items day green end to end.90    for_each: "${{ with.read == null ? [] : with.read }}"91    max_parallel: 4                 # SLOT: the polite ceiling92    fail_fast: false93    timeout: "60s"                  # SLOT: per-iteration bound94    retry:95      max_attempts: 396      backoff_strategy: exponential97      jitter: true98    on_error:99      recover: null                 # a failed item yields null at its index · the batch lives100    ◇infer:                          # SLOT: the per-item job (any verb)101      max_tokens: 500               # SLOT: the per-ITEM ceiling · multiply by the fan width102      prompt: |103        Process this item · ${{ item }}104​105  survivors:106    with:107      process: ${{ tasks.process.output }}108    ◆invoke:                         # the null-aware fan-in · order preserved109      tool: "nika:jq"110      args:111        input: ${{ with.process }}112        # `. // []` · an EMPTY discovery skips the whole for_each (null113        # upstream) — the fan-in must survive its own quiet day.114        expression: "(. // []) | [ .[] | select(. != null) ]"115​116  merge:117    with:118      survivors: ${{ tasks.survivors.output }}119    ◇infer:120      max_tokens: 800               # SLOT: the fan-in ceiling121      # SLOT: the fan-in · the survivors array (failed items filtered). Keep122      # slot markers out of the block below — it is prompt TEXT, not YAML.123      prompt: |124        Merge these results into one report · ${{ with.survivors }}125​126outputs:127  report: ${{ tasks.merge.output }}128​