{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://nika.sh/spec/v1/project.schema.json",
  "title": "Nika project file · nika.yaml · v1",
  "description": "Structural contract for a project's `nika.yaml`: the project's name, its default spend ceiling, the team arming registry (`arm:`), the trace retention policy and the registry provenance floor. The grammar is closed — an unknown key anywhere is a named refusal — and every value form below is the one the parser accepts; the beat keys keep the French spellings the parser reads (`où` · `manqué` · `après_saut` · …) and each is described here in English.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "nika": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "The project's name — kebab-case opening with a letter (`my-project`). The retired schema tag (`v1`, `v2`, …) is refused: the version lives on the `$schema` line.",
      "not": {
        "pattern": "^v[0-9]+$"
      }
    },
    "ceiling": {
      "type": "number",
      "description": "The default `--max-cost-usd` for every run in this project (USD). A run may lower it, never raise it silently.",
      "exclusiveMinimum": 0
    },
    "arm": {
      "type": "array",
      "description": "The team arming registry: the beats the resident (`nika serve`) fires on their cadence. Validated by every door, fired by one.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "workflow",
          "cadence",
          "plafond",
          "manqué"
        ],
        "properties": {
          "workflow": {
            "type": "string",
            "pattern": "^(?!/)[^:\\\\\\u0000-\\u001f\\u007f]*[^/:\\\\\\u0000-\\u001f\\u007f]\\.nika(?![\\s\\S])",
            "description": "The workflow file, relative to the project root (`workflows/nightly.nika`)."
          },
          "cadence": {
            "type": "string",
            "description": "When the beat fires, its IANA zone first: five cron fields (`TZ=Europe/Paris 0 9 * * 1`), a French weekday and its time (`TZ=Europe/Paris lundi 9h07`), an anchored interval (`TZ=Europe/Paris every 2 weeks from 2026-10-05 09:00`), or `on-webhook`, the one form with no zone. The zone is required for every scheduled form; `nika check`, `nika arm` and `nika serve` refuse a cadence without it."
          },
          "où": {
            "type": "string",
            "enum": [
              "local",
              "cloud"
            ],
            "description": "Where the beat runs: `local` (this machine's resident) or `cloud` (a remote resident)."
          },
          "plafond": {
            "type": "number",
            "description": "Required, with no default: the beat's spend ceiling in USD for each fire (`--max-cost-usd`). Choosing for the operator would be choosing who pays.",
            "exclusiveMinimum": 0
          },
          "manqué": {
            "description": "Required, with no default: what a missed slot becomes when the firer comes back. `rattraper` fires the latest missed slot once; `{ rattraper: N }` fires up to the N latest missed slots, one run each, oldest first, so the activation shows the worst cost as « jusqu'à N × plafond »; `rattraper-une-fois` fires once, that run answering for every missed slot; `sauter` skips them. Each run receives the slot it fires for.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "rattraper",
                  "rattraper-une-fois",
                  "sauter"
                ]
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "rattraper"
                ],
                "properties": {
                  "rattraper": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "How many of the latest missed slots to fire, one run each, oldest first: a whole number from 1."
                  }
                }
              }
            ]
          },
          "chevauchement": {
            "type": "string",
            "enum": [
              "sauter",
              "file",
              "remplacer"
            ],
            "description": "What a new slot does while the previous fire still runs: `sauter` (skip it), `file` (queue it), `remplacer` (replace the running one)."
          },
          "après_saut": {
            "type": "string",
            "enum": [
              "prochain-créneau",
              "à-complétion"
            ],
            "description": "When the beat resumes after a skipped slot: at the next slot (`prochain-créneau`) or when the running fire completes (`à-complétion`)."
          },
          "actif": {
            "type": "boolean",
            "description": "Whether the beat is armed. A suspended beat (`false`) must say why in `raison`."
          },
          "raison": {
            "type": "string",
            "description": "Why the beat is suspended, verbatim. Required with `actif: false`."
          },
          "jusqu_au": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "description": "The date that bounds a suspension: an ISO calendar date (`2026-12-31`), nothing else. Required with `actif: false`."
          },
          "tolérance": {
            "type": "string",
            "pattern": "^[0-9]+/[0-9]+$",
            "description": "The (m,k)-firm skip tolerance (`3/4`). Accepted in the file, refused at apply and load until the (m,k) law exists."
          },
          "décalage": {
            "type": "string",
            "enum": [
              "hash"
            ],
            "description": "`hash`, the one value: a deterministic offset derived from the workflow path. Accepted in the file; both firers refuse it until the jitter law exists."
          },
          "par": {
            "type": "string",
            "description": "Who armed the beat, verbatim (a name, a handle) — the provenance line the ledger reads."
          },
          "inputs": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            },
            "description": "Per-beat inputs: the `--var KEY=VALUE` pairs every fire binds to the workflow's declared `inputs:` — one scalar per key, coerced by the declared type at admission (a typed array input takes its JSON text in quotes). A key the workflow does not declare refuses before the claim."
          }
        },
        "allOf": [
          {
            "if": {
              "required": [
                "actif"
              ],
              "properties": {
                "actif": {
                  "const": false
                }
              }
            },
            "then": {
              "required": [
                "raison",
                "jusqu_au"
              ]
            }
          },
          {
            "if": {
              "required": [
                "après_saut",
                "chevauchement"
              ]
            },
            "then": {
              "properties": {
                "chevauchement": {
                  "const": "sauter"
                }
              }
            }
          }
        ]
      }
    },
    "traces": {
      "type": "object",
      "additionalProperties": false,
      "description": "The trace retention policy for `.nika/traces/`.",
      "properties": {
        "keep": {
          "type": "string",
          "pattern": "^[0-9]+d$",
          "description": "The retention age cap (`30d`): a trace older than this exits even under the keep-N window. A paused trace is never collected."
        }
      },
      "required": [
        "keep"
      ]
    },
    "registry": {
      "type": "object",
      "additionalProperties": false,
      "description": "The registry provenance admission floor — a gate on what the project installs.",
      "properties": {
        "floor": {
          "type": "string",
          "enum": [
            "unprovenanced",
            "provenanced",
            "stage-clear",
            "verified"
          ],
          "description": "Refuse artifacts below this provenance tier: `unprovenanced` (digest-consistent) · `provenanced` (minisign-verified under the publisher's key) · `stage-clear` (a staged-window statement) · `verified` (a complete in-toto layout)."
        }
      },
      "required": [
        "floor"
      ]
    }
  },
  "anyOf": [
    {
      "maxProperties": 0
    },
    {
      "required": [
        "nika"
      ]
    }
  ]
}
