apiVersion: naftiko.dev/v1
kind: Capability
metadata:
  name: multi-nationality-cohort
  title: Build a Multi-Nationality User Cohort
  description: |
    Workflow capability that pulls balanced subsets of synthetic users across
    a set of nationalities (e.g. for localization, i18n, or address-parsing
    tests) and merges them into a single cohort.
  provider: randomuser
spec:
  inputs:
    nationalities:
      type: array
      items: { type: string, pattern: "^[a-z]{2}$" }
      default: [us, gb, fr, de, br, in]
    perNationality:
      type: integer
      default: 25
  steps:
    - name: fan-out
      kind: foreach
      over: "{{ inputs.nationalities }}"
      as: nat
      do:
        capability: randomuser-users
        operation: generateUsers
        params:
          results: "{{ inputs.perNationality }}"
          nat: "{{ nat }}"
          exc: login
        capture:
          batch: $.results
    - name: merge
      kind: reduce
      from: fan-out
      strategy: concat
      output: cohort
  guarantees:
    - Cohort size = len(nationalities) * perNationality.
    - Each user's `nat` matches the requested nationality bucket.