[{"k":"h","depth":1,"text":"07 · Conformance","id":"07--conformance"},{"k":"quote","inline":[{"k":"text","text":"An engine MAY claim « v0.1-compliant » if it passes the conformance\ntest suite at "},{"k":"link","text":"`../conformance/tests/`","href":"../conformance/"},{"k":"text","text":". This document\ndefines the conformance levels and what each requires."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Notation","id":"notation"},{"k":"p","inline":[{"k":"text","text":"The key words "},{"k":"strong","text":"MUST"},{"k":"text","text":", "},{"k":"strong","text":"MUST NOT"},{"k":"text","text":", "},{"k":"strong","text":"REQUIRED"},{"k":"text","text":", "},{"k":"strong","text":"SHALL"},{"k":"text","text":", "},{"k":"strong","text":"SHALL\nNOT"},{"k":"text","text":", "},{"k":"strong","text":"SHOULD"},{"k":"text","text":", "},{"k":"strong","text":"SHOULD NOT"},{"k":"text","text":", "},{"k":"strong","text":"MAY"},{"k":"text","text":", and "},{"k":"strong","text":"OPTIONAL"},{"k":"text","text":" in this\nspecification are to be interpreted as described in "},{"k":"link","text":"BCP 14","href":"https://www.rfc-editor.org/info/bcp14"},{"k":"text","text":"\n("},{"k":"link","text":"RFC 2119","href":"https://www.rfc-editor.org/rfc/rfc2119"},{"k":"text","text":" + "},{"k":"link","text":"RFC 8174","href":"https://www.rfc-editor.org/rfc/rfc8174"},{"k":"text","text":")\nwhen, and only when, they appear in all capitals."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Conformance levels","id":"conformance-levels"},{"k":"p","inline":[{"k":"text","text":"Three nested levels · increasing scope ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Level · What it covers · Use case"}],[{"k":"text","text":"**Core** · Parse + validate · DAG semantics · variable resolution · error structure · Linters · spec editors · static analyzers"}],[{"k":"text","text":"**Runtime** · Core + verb execution · Working engine (with own provider/tool impls)"}],[{"k":"text","text":"**Stdlib v0.1** · Runtime + the 17 providers + <!-- canon:extract_modes -->9<!-- /canon --> extract modes + 28 builtins · Full reference-impl-equivalent engine"}]]},{"k":"p","inline":[{"k":"text","text":"A higher level "},{"k":"strong","text":"includes"},{"k":"text","text":" the lower levels."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Level 1 · Core conformance","id":"level-1--core-conformance"},{"k":"p","inline":[{"k":"text","text":"An engine claims « Core v0.1-compliant » if it ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Parses"},{"k":"text","text":" any valid v0.1 workflow YAML correctly"},{"k":"text","text":"- Accepts a kebab-case `nika:` id (`^[a-z][a-z0-9-]*\u0024`) · rejects any other shape, `v1` included (`NIKA-PARSE-003`) — the key carries the file's NAME, and the version slot is gone forever and losslessly\n- Reads the document TYPE from `tasks:` (present ⇒ workflow · absent ⇒ project), never from the filename\n- Validates typed `inputs` (type + required) · validates `const` / `secrets` shape\n- Recognizes the 4 verbs (`infer` · `exec` · `invoke` · `agent`)\n- **Rejects** unknown fields with a clear error (`NIKA-PARSE-005` · strict) — at every level, not only the top (D-2026-08-11-N20)\n"}],[{"k":"strong","text":"Computes DAG topology"},{"k":"text","text":" correctly"},{"k":"text","text":"- Derives E_d from `with:` bindings (role per referenced field) and E_c from `after:` entries · G_p = E_d ∪ E_c ([03 §four graphs](./03-dag.md#the-four-graphs-normative))\n- Detects cycles in G_p · rejects with `NIKA-DAG-001`\n- Detects a `with:`/`after:` reference to an undeclared task · rejects with `NIKA-DAG-002`\n- Rejects an `after:` predicate outside the closed set · `NIKA-DAG-005`\n- Rejects `depends_on:` (dead form) · `NIKA-PARSE-024` · and a `tasks.*` reference outside the boundary · `NIKA-VAR-021`\n- Detects an `on_error.recover` reference to a task downstream of the declaring task · rejects with `NIKA-DAG-004` (the await would deadlock · [05](./05-errors.md#recover-reference-resolution-normative))\n- Computes topological waves for parallel execution\n"}],[{"k":"strong","text":"Resolves variable references"},{"k":"text","text":" correctly (static · reference-resolution · NOT runtime evaluation)"},{"k":"text","text":"- `\u0024{{ inputs.x }}` · `\u0024{{ const.x }}` resolve to declared envelope `inputs:` / `const:` entries\n- `\u0024{{ with.x }}` resolves to a declared task `with:` key\n- `\u0024{{ tasks.X.field }}` resolves to a declared upstream task + a valid field name\n- `\u0024{{ secrets.X }}` resolves to a declared `secrets:` entry\n- `when:` and `for_each:` expressions are valid **CEL** (the v0.1 subset · see 03-dag) and their references **resolve to known namespaces**: Core parses but does NOT *evaluate* them (no execution = no `tasks.X.status` to compare against · that is Runtime's job)\n- `extract:` bindings are valid **jq** expressions (the one data language · see 04-variables) · `\u0024{{ }}` never appears inside a binding\n- Reports undefined references with `NIKA-VAR-001` · static expression violations with `NIKA-VAR-005` (the deep-static layer · CEL subset parse · jq compile · `when:` boolean shape)\n"}],[{"k":"strong","text":"Produces typed errors"},{"k":"text","text":" matching the v0.1 spec"},{"k":"text","text":"- `code` follows `NIKA-<NAMESPACE>-<NNN>` format\n- `category` is one of the closed enum values\n- `transient` correctly set\n"}],[{"k":"strong","text":"Passes"},{"k":"text","text":" all tests in "},{"k":"code","text":"conformance/tests/core/"}]]},{"k":"p","inline":[{"k":"text","text":"A Core-compliant engine does NOT execute verbs and does NOT evaluate "},{"k":"code","text":"when:"},{"k":"text","text":" / "},{"k":"code","text":"for_each:"},{"k":"text","text":" over runtime state. It parses · validates · builds the DAG · resolves variable "},{"k":"em","text":"references"},{"k":"text","text":" (syntax + namespace validity) · produces typed errors. Runtime evaluation of conditions and iteration is Level 2."}]},{"k":"h","depth":3,"text":"`nika check` · the static pre-flight (the audit-before-it-runs surface)","id":"nika-check--the-static-pre-flight-the-audit-before-it-runs-surface"},{"k":"p","inline":[{"k":"text","text":"Because the language is "},{"k":"strong","text":"statically analyzable by construction"},{"k":"text","text":" (the DAG\nis acyclic, "},{"k":"code","text":"for_each"},{"k":"text","text":" is bounded, CEL is non-Turing, and effects are\ndeclared), a conformant engine can answer « what will this workflow do, cost,\nand touch? » with "},{"k":"strong","text":"zero API calls and zero tokens spent"},{"k":"text","text":". "},{"k":"code","text":"nika check"},{"k":"text","text":" is\nthe canonical CLI surface for that (Core conformance + the static\nguarantees below) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Guarantee · What it reports · zero execution · Backed by"}],[{"k":"text","text":"**Plan** · the wave topology · which tasks run in parallel · the critical path · DAG waves (Core §2)"}],[{"k":"text","text":"**Cost ceiling** · the worst-case spend · `Σ (max_tokens × provider price)` across `infer:`/`agent:` tasks · before one token is spent · the `nika:inspect view: cost` model, run statically"}],[{"k":"text","text":"**Energy ceiling** · the worst-case watt-hours over the same tasks, per scope class · the honesty law below · a sourced `Wh` per million OUTPUT tokens, catalog data"}],[{"k":"text","text":"**Secret leak** · every `secrets.X` that flows into an `exec` capture or a tool whose output is bound (the masking boundary · [04 §secrets](./04-variables.md)) · reference graph"}],[{"k":"text","text":"**Capability escape** · any effect outside a declared `permits:` block: a write outside `fs.write`, a fetch to an unlisted host, an `exec` under `exec: false`, an unlisted tool · `permits:` ([01](./01-envelope.md))"}],[{"k":"text","text":"**Provider parity** · (`--providers`) that the workflow uses zero provider-specific fields → the same `schema:` runs identically on all 17 providers (incl. the 5 local) · the closed verb-field set"}]]},{"k":"p","inline":[{"k":"text","text":"This is the property no other AI workflow runner gives: "},{"k":"strong","text":"GitHub Actions,\nTemporal, and LangGraph tell you nothing (and charge you nothing back)\nuntil you run."},{"k":"text","text":" A Nika workflow is auditable for cost, capabilities,\nsecrets, and portability "},{"k":"em","text":"as a static fact about the file"},{"k":"text","text":". "},{"k":"code","text":"nika check"},{"k":"text","text":" is\nan engine CLI surface (not a separate conformance level: it composes Core\nvalidation with the cost/secret/permits/parity reports); the guarantees it\nsurfaces ARE normative (they derive from Core conformance + the "},{"k":"code","text":"permits:"},{"k":"text","text":"\nand "},{"k":"code","text":"secrets:"},{"k":"text","text":" MUSTs), the CLI ergonomics around them are the engine's."}]},{"k":"h","depth":3,"text":"The spend-honesty law · *normative · cost and energy alike*","id":"the-spend-honesty-law--normative--cost-and-energy-alike"},{"k":"p","inline":[{"k":"text","text":"The two spend readings are one doctrine in two units. Money is the\nvolatile one — it rots with every price change and means nothing on a\nlocal provider; watt-hours are the durable one. Both speak "},{"k":"strong","text":"the same\nfour words"},{"k":"text","text":", and neither may print a number that hides what it could\nnot bound ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Word · What it claims"}],[{"k":"text","text":"**floor** (`≥`) · the provable minimum · the real figure can only be higher"}],[{"k":"text","text":"**ceiling** (`≤`) · the provable worst case · a task's declared cap × a sourced rate, summed over the bounded tasks"}],[{"k":"text","text":"**UNBOUNDED** · a task with no provable limit, **named** one by one, carrying the why (`no max_tokens declared` · the author can fix it)"}],[{"k":"text","text":"**unpriced** · the task will spend, and no sourced rate exists for its model"}]]},{"k":"p","inline":[{"k":"text","text":"The law (MUST) ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Name the bounded part, name every unbounded task, and never print\na total that hides either."},{"k":"text","text":" A surface that cannot honor this prints\nnothing rather than a wrong number. The two rungs MUST read ONE\nclassification of the tasks — the same task has the same shape on\nboth — and an unbounded task is named "},{"k":"strong","text":"once"},{"k":"text","text":", not once per rung:\nthe second rung counts it and points at the first. Two adjacent\nreadings that describe one task differently teach the reader to\ndistrust both."}],[{"k":"strong","text":"Unknown stays unknown."},{"k":"text","text":" A figure the engine cannot source renders\n"},{"k":"code","text":"unpriced"},{"k":"text","text":", never zero. A local model is "},{"k":"code","text":"unpriced"},{"k":"text","text":" — the operator's\nwatts — never « free ». Absence of a rate is not a rate of zero, and\n"},{"k":"code","text":"0"},{"k":"text","text":" is the one rendering a reader takes as a promise."}],[{"k":"strong","text":"A proven zero is not an unknown."},{"k":"text","text":" A task whose "},{"k":"code","text":"for_each"},{"k":"text","text":"\niterates a literal EMPTY collection provably never runs: it is\ncounted "},{"k":"strong","text":"never-run"},{"k":"text","text":" and gets no row. A ceiling over a task that\ncannot execute would be invented, and two adjacent rungs would\ndescribe the same task differently. "},{"k":"em","text":"(Measured residual, 2026-08-13 ·\n`nika 0.108.0` — the ENERGY rung honours this; the COST rung still\nprints such a task at `\u00240.0000`, so the two rungs do disagree about\nit today. The `never-run` class exists on the energy arm only. The\nlaw is the target for both.)"}],[{"k":"strong","text":"Watt-hours sum inside a scope class and never across one."},{"k":"text","text":" An\nenergy fact declares what it covers — "},{"k":"code","text":"gpu"},{"k":"text","text":" (accelerator only) ·\n"},{"k":"code","text":"device"},{"k":"text","text":" (whole host) · "},{"k":"code","text":"fleet"},{"k":"text","text":" (host + idle + datacenter overhead)\n— and the same model differs by roughly 2× between the ends of that\nladder. A mixed workflow reports one subtotal per class: not a\nrefusal, and never a sum that describes nothing."}],[{"k":"strong","text":"A figure carries its origin and its date, or it does not enter."},{"k":"text","text":"\nEvery energy rate is stated per million OUTPUT tokens (decode\ndominates measured inference; a per-total figure would dilute the\nnumber with nearly-free prefill), and rides a closed provenance —\n"},{"k":"code","text":"measured-local"},{"k":"text","text":" · "},{"k":"code","text":"independent-measured"},{"k":"text","text":" · "},{"k":"code","text":"vendor-claim"},{"k":"text","text":" ·\n"},{"k":"code","text":"independent-estimate"},{"k":"text","text":" — with the month it was measured. Modelling\nmay enter, wearing its label; it may never enter as a silent\ndefault. Figures rot with hardware generations: a dateless or\nsourceless one is refused rather than believed."}]]},{"k":"p","inline":[{"k":"text","text":"The rate table itself is engine data, not language surface — as is any\nbudget that "},{"k":"em","text":"enforces"},{"k":"text","text":" a ceiling (§Observability in\n"},{"k":"link","text":"08","href":"./08-out-of-scope.md"},{"k":"text","text":" defers those). What is normative here is the\nreading: what a spend claim is allowed to say."}]},{"k":"h","depth":3,"text":"Editor tooling · the canonical JSON Schema","id":"editor-tooling--the-canonical-json-schema"},{"k":"p","inline":[{"k":"text","text":"The spec ships a canonical "},{"k":"strong","text":"JSON Schema"},{"k":"text","text":" at\n"},{"k":"link","text":"`schemas/workflow.schema.json`","href":"../schemas/"},{"k":"text","text":" describing the envelope +\ntask shape + verb argument structures. It is the machine-readable companion to\nthis prose spec (kept in sync · the prose is normative on conflict)."}]},{"k":"p","inline":[{"k":"text","text":"Editors (VS Code · Zed · JetBrains · Neovim) pick it up via the standard\n"},{"k":"code","text":"yaml.schemas"},{"k":"text","text":" association (or a "},{"k":"code","text":"# yaml-language-server: \u0024schema=…"},{"k":"text","text":" modeline)\nto give "},{"k":"strong","text":"autocomplete + inline validation"},{"k":"text","text":" as you type, the same DX as\nGitHub Actions and Docker Compose. A working modeline today:"}]},{"k":"code","lang":"yaml","text":"# yaml-language-server: \u0024schema=https://raw.githubusercontent.com/supernovae-st/nika-spec/main/schemas/workflow.schema.json\nnika: my-workflow"},{"k":"h","depth":4,"text":"The address MUST become versioned and immutable (normative · D-2026-08-11-N24)","id":"the-address-must-become-versioned-and-immutable-normative--d-2026-08-11-n24"},{"k":"p","inline":[{"k":"text","text":"⚠️ "},{"k":"strong","text":"The modeline above points at a moving branch, and that is a defect with\ntwo independent causes."}]},{"k":"p","inline":[{"k":"em","text":"The first is ours."},{"k":"text","text":" Since "},{"k":"link","text":"§unknown key","href":"#an-unknown-key-is-an-error-at-every-level-normative--d-2026-08-11-n20"},{"k":"text","text":"\nan unknown key is an error, so this schema's "},{"k":"code","text":"additionalProperties: false"},{"k":"text","text":" is\nno longer a lint preference — it is the accepted surface of the language. Served\nfrom "},{"k":"code","text":"main"},{"k":"text","text":", that surface moves under every editor in the world "},{"k":"strong","text":"while no file\nhas changed"},{"k":"text","text":". A workflow that validated on Monday shows red on Tuesday because\na schema it never named was edited. This is precisely the drift the strict rule\nexists to prevent, arriving through the back door."}]},{"k":"p","inline":[{"k":"em","text":"The second is the host's."},{"k":"text","text":" "},{"k":"code","text":"raw.githubusercontent.com"},{"k":"text","text":" fronts a cache that\nserves stale bytes: a schema can be correct at the commit and wrong at the\nreader for an unspecified window. "},{"k":"strong","text":"Immutable upstream is not immutable at the\npoint of use"},{"k":"text","text":" — measured in this workspace, 2026-08-07."}]},{"k":"p","inline":[{"k":"strong","text":"The shape."},{"k":"text","text":" One address per minor, frozen forever ·"}]},{"k":"code","lang":"yaml","text":"# yaml-language-server: \u0024schema=https://nika.sh/schema/v0.1/workflow.schema.json\nnika: my-workflow"},{"k":"p","inline":[{"k":"text","text":"This is what JSON Schema, OpenAPI, Kubernetes and CWL all do, and it composes\nwith the "},{"k":"code","text":"nika:"},{"k":"text","text":" mark the envelope already carries. A file written in 2027\nstill reads in 2030 against "},{"k":"strong","text":"its own"},{"k":"text","text":" schema. Until the address ships, the\nmodeline above is the pragmatic form and this paragraph is the standing debt —\nstated, not hidden."}]},{"k":"p","inline":[{"k":"text","text":"This is also what makes a Nika file\npleasant (and trap-free) for an AI to author: the schema constrains the shape\nbefore the engine ever runs. CEL expressions and jq expressions inside string\nfields are validated by the engine (Core level), not the JSON Schema."}]},{"k":"p","inline":[{"k":"strong","text":"Use case"},{"k":"text","text":" · linters · spec editors · LSP server intelligence · static analyzers."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Level 2 · Runtime conformance","id":"level-2--runtime-conformance"},{"k":"p","inline":[{"k":"text","text":"An engine claims « Runtime v0.1-compliant » if it satisfies Core conformance PLUS ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Executes the 4 verbs"},{"k":"text","text":" with correct semantics"},{"k":"text","text":"- `infer:` calls a configured provider · returns response\n- `exec:` runs the command in a shell · honors timeout + security\n- `invoke:` resolves and calls the tool · returns response\n- `agent:` runs the multi-turn loop · honors max_turns + tools whitelist\n"}],[{"k":"strong","text":"Honors task fields"},{"k":"text","text":" correctly"},{"k":"text","text":"- GATE-v2 admission · every incoming edge's producer settles inside that edge's pass-set, else `cancelled` (dead-path · [03 §gate algebra](./03-dag.md#the-gate-algebra-v2-normative))\n- `when` skips when false (POST-gate · local namespaces)\n- `timeout` (Go-duration string · `\"30s\"` · `\"5m\"` etc.) hard-kills on timeout\n- `retry` strategy honored on transient errors\n- `on_error` recovery honored on terminal errors\n- `with` scope injected into task body\n- `output` binding via jq\n"}],[{"k":"strong","text":"Implements security policies"},{"k":"text","text":"- `exec:` blocklist (engine SHOULD ship a sane default · MAY allow override)\n- `fetch:` SSRF defense for private IP ranges\n- `invoke:` capability checks (engine's choice of capability model)\n"}],[{"k":"strong","text":"Emits workflow events"},{"k":"text","text":"- `task.started` · `task.completed` · `task.failed` · `task.skipped`\n- `workflow.started` · `workflow.completed` · `workflow.failed`\n- Event payload includes `task_id` · timestamp · status · duration\n"}],[{"k":"strong","text":"Passes"},{"k":"text","text":" all tests in "},{"k":"code","text":"conformance/tests/runtime/"}]]},{"k":"p","inline":[{"k":"text","text":"Runtime-compliant engines may bring "},{"k":"strong","text":"their own"},{"k":"text","text":" provider implementations · tool implementations · MCP server registries. They are not required to ship the canonical stdlib."}]},{"k":"p","inline":[{"k":"strong","text":"Use case"},{"k":"text","text":" · custom engines for specialized environments (embedded · WASM · custom LLM gateway · etc.)."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Level 3 · Stdlib v0.1 conformance","id":"level-3--stdlib-v01-conformance"},{"k":"p","inline":[{"k":"text","text":"An engine claims « Stdlib v0.1-compliant » if it satisfies Runtime conformance PLUS ·"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Ships all 17 canonical providers"},{"k":"text","text":" (per "},{"k":"link","text":"stdlib/providers-v0.1.md","href":"../stdlib/providers-v0.1.md"},{"k":"text","text":")"}],[{"k":"strong","text":"Ships all 9 canonical extract modes"},{"k":"text","text":" (per "},{"k":"link","text":"stdlib/extract-modes-v0.1.md","href":"../stdlib/extract-modes-v0.1.md"},{"k":"text","text":")"}],[{"k":"strong","text":"Ships at least all 28 canonical builtins"},{"k":"text","text":" (core 6 + file 5 + data 9 + network 2 + introspection 2 + media 4 · the remaining deferred media builtins are optional · the byte-determinism clauses of "},{"k":"code","text":"nika:image_fx"},{"k":"text","text":" and "},{"k":"code","text":"nika:chart"},{"k":"text","text":" are part of the bar — an engine that cannot honor them is not conformant, no waiver)"}],[{"k":"strong","text":"Passes"},{"k":"text","text":" all tests in "},{"k":"code","text":"conformance/tests/stdlib/"}]]},{"k":"p","inline":[{"k":"text","text":"A Stdlib-compliant engine is functionally equivalent to the reference implementation for any workflow that uses only the canonical stdlib elements."}]},{"k":"p","inline":[{"k":"strong","text":"Use case"},{"k":"text","text":" · the default level for production engines."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Suite status · v0.1 (honest)","id":"suite-status--v01-honest"},{"k":"p","inline":[{"k":"text","text":"What is populated TODAY vs what lands with the reference engine ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Layer · Status · What it proves"}],[{"k":"text","text":"**Core fixtures** (`tests/core/`) · ✅ populated · runner-executable · parse + validate + DAG + variables + errors · the full Level-1 static contract"}],[{"k":"text","text":"**Deep-static fixtures** (`tests/deep/`) · ✅ populated · runner-executable · the expression layer the schema cannot see · the normative CEL EBNF parsed for real · jq compile · duration grammar · schema-meta · `when:` shape · binding purity"}],[{"k":"text","text":"**Stdlib static surface** (`tests/stdlib/`) · ✅ populated · runner-executable · the stdlib **names + shapes** layer · provider prefixes · the closed `nika:*` builtin set · extract modes · checkable with zero execution (lists derive from [`canon.yaml`](../canon.yaml))"}],[{"k":"text","text":"**Examples as conformance inputs** (`examples/`) · ✅ executed by the runner `all` gate · every shipped example MUST validate at the full static level"}],[{"k":"text","text":"**Runtime behavioral fixtures** (`tests/runtime/`) · ✅ **measured by command** (2026-07-30) · verb execution · task statuses/outputs · events · the trace chain — driven through the PUBLIC doors (`nika run --json` · `nika trace verify`) by [`scripts/runtime-differential.py`](../scripts/runtime-differential.py) · every fixture agrees with the released engine"}],[{"k":"text","text":"**Stdlib behavioral fixtures** (`tests/stdlib/behavioral/`) · 🌗 **no-network half measured** (2026-07-30) · builtin *behavior* through the run door — `nika:jq` executes for real (typed result) · the `nika:write`→`nika:read` pair roundtrips under a declared `permits.fs` · `nika:convert` converts (from:/to: required) — same differential, same sweep as the runtime tier. The network half (fetch under HTTP mocks · provider behavior beyond `mock/echo`) stays post-announce"}]]},{"k":"p","inline":[{"k":"text","text":"(The provider prefix list is a "},{"k":"strong","text":"registry, not grammar"},{"k":"text","text":" — the freeze\nholds the form, the membership grows additively under the registration\npolicy in "},{"k":"link","text":"providers-v0.1.md §Registration\npolicy","href":"../stdlib/providers-v0.1.md"},{"k":"text","text":" · no NEP for a membership row, a\nNEP for any change to the form.)"}]},{"k":"p","inline":[{"k":"text","text":"Run the static gate yourself · "},{"k":"code","text":"python conformance/runner.py all"},{"k":"text","text":": the\nrunner output is the live count (counts in prose drift · the suite is the\nsource). Run the behavioral tier yourself ·\n"},{"k":"code","text":"NIKA_BIN=<engine> python3 scripts/runtime-differential.py"},{"k":"text","text":" — same law,\nthe differential's summary is the live count. A « Core v0.1-compliant »\nclaim is FULLY testable today; « Runtime » claims are testable on both\nhalves (static fixtures + the behavioral differential) · « Stdlib v0.1 »\non its static half, its behavioral half when those fixtures publish."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Conformance test structure","id":"conformance-test-structure"},{"k":"code","lang":"text","text":"conformance/\n├── tests/\n│   ├── core/                  # Level-1 fixtures · parse · validate · DAG · variables · errors\n│   ├── deep/                  # deep-static layer · CEL subset parse · jq compile ·\n│   │                          # durations · schema-meta · when shape · binding purity\n│   ├── lints/                 # advisory-lint fixtures\n│   ├── runtime/               # verb execution · task fields · events (behavioral half)\n│   │   ├── trace/            #   the journal, judged by the walk (a verdict)\n│   │   ├── receipt/          #   the receipt, judged by its reading (what projects)\n│   │   ├── registry/         #   a cache record × an operator floor, judged by admission\n│   │   ├── energy/           #   a workflow, judged by the energy reading it must report\n│   │   └── resume/           #   a journal × a compat declaration, judged by the version crossing\n│   └── stdlib/                # provider/extract/builtin canonical surface\n│\n├── runner.py                  # the static oracle · `all` is the CI gate\n├── *_core.py                  # per-domain reference evaluators (type · decision ·\n│                              # gateway · outcome · composition · yaml-profile ·\n│                              # proof · projection) + their `*_selftest.py` sweeps\n├── yaml-profile/              # R11 profile fixtures (valid/ + invalid/)\n├── type-corpus/               # the generated type corpus (gen-type-corpus.py)\n├── values/                    # the three-authority family (C2 · R3a · valid/ + invalid/)\n├── types/                     # io-declaration predicate vocabulary (C2 · R3b · valid/ + invalid/)\n├── gates/                     # the after: predicate vocabulary (C2 · R5 · valid/ + invalid/)\n└── runner-protocol.md         # how to run the suite against any engine"},{"k":"p","inline":[{"k":"strong","text":"The directory is the source"},{"k":"text","text":" — this sketch is a map, not the inventory\n("},{"k":"code","text":"python3 conformance/runner.py all"},{"k":"text","text":" prints the live fixture counts).\nEach fixture is a pair · "},{"k":"code","text":"input.yaml"},{"k":"text","text":" (the workflow to feed) + "},{"k":"code","text":"expected.json"},{"k":"text","text":" (the expected output or error structure)."}]},{"k":"p","inline":[{"k":"text","text":"For tests that require executing against real LLMs / networks · the suite uses the "},{"k":"code","text":"mock"},{"k":"text","text":" provider and HTTP mocks to keep tests deterministic."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Runner protocol","id":"runner-protocol"},{"k":"p","inline":[{"k":"text","text":"A conformance runner ·"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Reads each "},{"k":"code","text":"input.yaml"}],[{"k":"text","text":"Pipes it to the engine being tested ("},{"k":"code","text":"engine run --input -"},{"k":"text","text":")"}],[{"k":"text","text":"Captures the engine's output (stdout JSON · structured)"}],[{"k":"text","text":"Compares against "},{"k":"code","text":"expected.json"}],[{"k":"text","text":"Reports pass/fail per test · final summary"}]]},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"code","text":"conformance/runner-protocol.md"},{"k":"text","text":" for the exact JSON wire format."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Claiming conformance","id":"claiming-conformance"},{"k":"p","inline":[{"k":"text","text":"The public claim string is "},{"k":"strong","text":"« Nika v1 Conformant — <Level> (spec <commit>) »"},{"k":"text","text":"\n· Level ∈ "},{"k":"code","text":"Core"},{"k":"text","text":" · "},{"k":"code","text":"Runtime"},{"k":"text","text":" · "},{"k":"code","text":"Stdlib v0.1"},{"k":"text","text":" · the spec commit is the pin\nthe suite ran against. One form everywhere — badges · READMEs · listings ·\nrelease notes. (In normative sentences, « v0.1-compliant » names the level\n"},{"k":"em","text":"bar"},{"k":"text","text":" an engine satisfies; the string above is the one public "},{"k":"em","text":"claim"},{"k":"text","text":".)"}]},{"k":"p","inline":[{"k":"text","text":"To make the claim · an engine ·"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"MUST pass the conformance suite at the claimed level"}],[{"k":"text","text":"MUST name the level and the spec commit in the claim (the format above)"}],[{"k":"text","text":"MAY open a PR on "},{"k":"link","text":"supernovae-st/nika-spec","href":"https://github.com/supernovae-st/nika-spec"},{"k":"text","text":" to be listed in "},{"k":"code","text":"CONFORMANT_IMPLEMENTATIONS.md"}]]},{"k":"p","inline":[{"k":"text","text":"The claim is earned by passing the suite, never by declaration\n("},{"k":"link","text":"NEP-0000 §Relationship to conformance","href":"../governance/nep-0000-the-nep-process.md"},{"k":"text","text":").\nThe reference implementation "},{"k":"link","text":"supernovae-st/nika","href":"https://github.com/supernovae-st/nika"},{"k":"text","text":" targets Stdlib v0.1 conformance."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Versioning","id":"versioning"},{"k":"p","inline":[{"k":"text","text":"A conformance claim is "},{"k":"strong","text":"specific to a spec version"},{"k":"text","text":". As the stdlib evolves to v0.2 · engines re-claim conformance against the new suite. The Core conformance level is stable forever within v1 of the language."}]},{"k":"h","depth":3,"text":"An unknown key is an error, at every level (normative · D-2026-08-11-N20)","id":"an-unknown-key-is-an-error-at-every-level-normative--d-2026-08-11-n20"},{"k":"p","inline":[{"k":"text","text":"An engine MUST refuse a key it does not know ("},{"k":"code","text":"NIKA-PARSE-005"},{"k":"text","text":"). It MUST NOT\naccept-and-warn. "},{"k":"strong","text":"This clause used to leave the choice to the engine, and a\nchoice here is not a detail: it is the whole growth model."},{"k":"text","text":" Two conformant\nengines were entitled to disagree on every future key — one refusing a file\nthe other ran — which is the definition of a language that has not decided\nwhat it is."}]},{"k":"p","inline":[{"k":"strong","text":"Why refusal is the safe direction, and acceptance is not."},{"k":"text","text":" The instinct\nruns the other way: accept-and-warn looks forward-compatible, since a file\nwritten for a later minor would still run on an older engine. It is the wrong\ninstinct here, because "},{"k":"strong","text":"a key in this language can REMOVE authority."},{"k":"text","text":" A\nfuture rule that forbids something would be silently dropped by an older\nengine, and the file would run with "},{"k":"strong","text":"more"},{"k":"text","text":" authority than its author\ngranted — failing open, in the one language whose premise is that an absent\ngrant means zero. Refusal fails closed: the file does not run at all, and the\nauthor learns why."}]},{"k":"p","inline":[{"k":"strong","text":"What it buys, and it is not small."},{"k":"text","text":" Every key this spec reserves for a later\nminor lands "},{"k":"strong","text":"additively and for free"},{"k":"text","text":" under refusal: no valid file uses one\ntoday, so admitting it later breaks nothing. Adding to a closed space is always\ncompatible; the closure is what makes the growth safe. It also\ncatches the misspelling — "},{"k":"code","text":"permit:"},{"k":"text","text":" written for "},{"k":"code","text":"permits:"},{"k":"text","text":" — which today is\naccepted in silence and yields "},{"k":"em","text":"zero authority"},{"k":"text","text":" without saying so, the most\nexpensive typo the language can carry."}]},{"k":"p","inline":[{"k":"strong","text":"Precedent, and it is not ours."},{"k":"text","text":" CWL treats an unrecognised field as "},{"k":"em","text":"a\nfatal error"},{"k":"text","text":"; the field its readers may ignore is the advisory one, not the\nstructural one. A serious specification refuses."}]},{"k":"p","inline":[{"k":"text","text":"⚠️ "},{"k":"strong","text":"A corollary that is not optional."},{"k":"text","text":" Under strict refusal, the published\nJSON Schema ("},{"k":"code","text":"additionalProperties: false"},{"k":"text","text":") can no longer be served from a\nmoving branch: it needs a "},{"k":"strong","text":"versioned, immutable address"},{"k":"text","text":" (one per minor).\nOtherwise the editors of the world watch the accepted surface move under them\nwhile no file has changed — the drift the refusal exists to prevent, arriving\nby the back door."}]},{"k":"hr"},{"k":"p","inline":[{"k":"text","text":"🦋 "},{"k":"em","text":"Next · [08 · Out of scope](./08-out-of-scope.md)"}]}]

the spec · 07

Conformance

An engine MAY claim « v0.1-compliant » if it passes the conformance test suite at [`../conformance/tests/`](../conformance/).

07 · Conformance #

An engine MAY claim « v0.1-compliant » if it passes the conformance test suite at `../conformance/tests/`. This document defines the conformance levels and what each requires.

Notation #

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL in this specification are to be interpreted as described in BCP 14 (RFC 2119 + RFC 8174) when, and only when, they appear in all capitals.

Conformance levels #

Three nested levels · increasing scope ·

Level · What it covers · Use case
**Core** · Parse + validate · DAG semantics · variable resolution · error structure · Linters · spec editors · static analyzers
**Runtime** · Core + verb execution · Working engine (with own provider/tool impls)
**Stdlib v0.1** · Runtime + the 17 providers + 9 extract modes + 28 builtins · Full reference-impl-equivalent engine

A higher level includes the lower levels.

Level 1 · Core conformance #

An engine claims « Core v0.1-compliant » if it ·

Parses any valid v0.1 workflow YAML correctly- Accepts a kebab-case `nika:` id (`^[a-z][a-z0-9-]*$`) · rejects any other shape, `v1` included (`NIKA-PARSE-003`) — the key carries the file's NAME, and the version slot is gone forever and losslessly - Reads the document TYPE from `tasks:` (present ⇒ workflow · absent ⇒ project), never from the filename - Validates typed `inputs` (type + required) · validates `const` / `secrets` shape - Recognizes the 4 verbs (`infer` · `exec` · `invoke` · `agent`) - **Rejects** unknown fields with a clear error (`NIKA-PARSE-005` · strict) — at every level, not only the top (D-2026-08-11-N20)
Computes DAG topology correctly- Derives E_d from `with:` bindings (role per referenced field) and E_c from `after:` entries · G_p = E_d ∪ E_c ([03 §four graphs](./03-dag.md#the-four-graphs-normative)) - Detects cycles in G_p · rejects with `NIKA-DAG-001` - Detects a `with:`/`after:` reference to an undeclared task · rejects with `NIKA-DAG-002` - Rejects an `after:` predicate outside the closed set · `NIKA-DAG-005` - Rejects `depends_on:` (dead form) · `NIKA-PARSE-024` · and a `tasks.*` reference outside the boundary · `NIKA-VAR-021` - Detects an `on_error.recover` reference to a task downstream of the declaring task · rejects with `NIKA-DAG-004` (the await would deadlock · [05](./05-errors.md#recover-reference-resolution-normative)) - Computes topological waves for parallel execution
Resolves variable references correctly (static · reference-resolution · NOT runtime evaluation)- `${{ inputs.x }}` · `${{ const.x }}` resolve to declared envelope `inputs:` / `const:` entries - `${{ with.x }}` resolves to a declared task `with:` key - `${{ tasks.X.field }}` resolves to a declared upstream task + a valid field name - `${{ secrets.X }}` resolves to a declared `secrets:` entry - `when:` and `for_each:` expressions are valid **CEL** (the v0.1 subset · see 03-dag) and their references **resolve to known namespaces**: Core parses but does NOT *evaluate* them (no execution = no `tasks.X.status` to compare against · that is Runtime's job) - `extract:` bindings are valid **jq** expressions (the one data language · see 04-variables) · `${{ }}` never appears inside a binding - Reports undefined references with `NIKA-VAR-001` · static expression violations with `NIKA-VAR-005` (the deep-static layer · CEL subset parse · jq compile · `when:` boolean shape)
Produces typed errors matching the v0.1 spec- `code` follows `NIKA-<NAMESPACE>-<NNN>` format - `category` is one of the closed enum values - `transient` correctly set
Passes all tests in conformance/tests/core/

A Core-compliant engine does NOT execute verbs and does NOT evaluate when: / for_each: over runtime state. It parses · validates · builds the DAG · resolves variable references (syntax + namespace validity) · produces typed errors. Runtime evaluation of conditions and iteration is Level 2.

`nika check` · the static pre-flight (the audit-before-it-runs surface) #

Because the language is statically analyzable by construction (the DAG is acyclic, for_each is bounded, CEL is non-Turing, and effects are declared), a conformant engine can answer « what will this workflow do, cost, and touch? » with zero API calls and zero tokens spent. nika check is the canonical CLI surface for that (Core conformance + the static guarantees below) ·

Guarantee · What it reports · zero execution · Backed by
**Plan** · the wave topology · which tasks run in parallel · the critical path · DAG waves (Core §2)
**Cost ceiling** · the worst-case spend · `Σ (max_tokens × provider price)` across `infer:`/`agent:` tasks · before one token is spent · the `nika:inspect view: cost` model, run statically
**Energy ceiling** · the worst-case watt-hours over the same tasks, per scope class · the honesty law below · a sourced `Wh` per million OUTPUT tokens, catalog data
**Secret leak** · every `secrets.X` that flows into an `exec` capture or a tool whose output is bound (the masking boundary · [04 §secrets](./04-variables.md)) · reference graph
**Capability escape** · any effect outside a declared `permits:` block: a write outside `fs.write`, a fetch to an unlisted host, an `exec` under `exec: false`, an unlisted tool · `permits:` ([01](./01-envelope.md))
**Provider parity** · (`--providers`) that the workflow uses zero provider-specific fields → the same `schema:` runs identically on all 17 providers (incl. the 5 local) · the closed verb-field set

This is the property no other AI workflow runner gives: GitHub Actions, Temporal, and LangGraph tell you nothing (and charge you nothing back) until you run. A Nika workflow is auditable for cost, capabilities, secrets, and portability as a static fact about the file. nika check is an engine CLI surface (not a separate conformance level: it composes Core validation with the cost/secret/permits/parity reports); the guarantees it surfaces ARE normative (they derive from Core conformance + the permits: and secrets: MUSTs), the CLI ergonomics around them are the engine's.

The spend-honesty law · normative · cost and energy alike #

The two spend readings are one doctrine in two units. Money is the volatile one — it rots with every price change and means nothing on a local provider; watt-hours are the durable one. Both speak the same four words, and neither may print a number that hides what it could not bound ·

Word · What it claims
**floor** (`≥`) · the provable minimum · the real figure can only be higher
**ceiling** (`≤`) · the provable worst case · a task's declared cap × a sourced rate, summed over the bounded tasks
**UNBOUNDED** · a task with no provable limit, **named** one by one, carrying the why (`no max_tokens declared` · the author can fix it)
**unpriced** · the task will spend, and no sourced rate exists for its model

The law (MUST) ·

Name the bounded part, name every unbounded task, and never print a total that hides either. A surface that cannot honor this prints nothing rather than a wrong number. The two rungs MUST read ONE classification of the tasks — the same task has the same shape on both — and an unbounded task is named once, not once per rung: the second rung counts it and points at the first. Two adjacent readings that describe one task differently teach the reader to distrust both.
Unknown stays unknown. A figure the engine cannot source renders unpriced, never zero. A local model is unpriced — the operator's watts — never « free ». Absence of a rate is not a rate of zero, and 0 is the one rendering a reader takes as a promise.
A proven zero is not an unknown. A task whose for_each iterates a literal EMPTY collection provably never runs: it is counted never-run and gets no row. A ceiling over a task that cannot execute would be invented, and two adjacent rungs would describe the same task differently. (Measured residual, 2026-08-13 · `nika 0.108.0` — the ENERGY rung honours this; the COST rung still prints such a task at `$0.0000`, so the two rungs do disagree about it today. The `never-run` class exists on the energy arm only. The law is the target for both.)
Watt-hours sum inside a scope class and never across one. An energy fact declares what it covers — gpu (accelerator only) · device (whole host) · fleet (host + idle + datacenter overhead) — and the same model differs by roughly 2× between the ends of that ladder. A mixed workflow reports one subtotal per class: not a refusal, and never a sum that describes nothing.
A figure carries its origin and its date, or it does not enter. Every energy rate is stated per million OUTPUT tokens (decode dominates measured inference; a per-total figure would dilute the number with nearly-free prefill), and rides a closed provenance — measured-local · independent-measured · vendor-claim · independent-estimate — with the month it was measured. Modelling may enter, wearing its label; it may never enter as a silent default. Figures rot with hardware generations: a dateless or sourceless one is refused rather than believed.

The rate table itself is engine data, not language surface — as is any budget that enforces a ceiling (§Observability in 08 defers those). What is normative here is the reading: what a spend claim is allowed to say.

Editor tooling · the canonical JSON Schema #

The spec ships a canonical JSON Schema at `schemas/workflow.schema.json` describing the envelope + task shape + verb argument structures. It is the machine-readable companion to this prose spec (kept in sync · the prose is normative on conflict).

Editors (VS Code · Zed · JetBrains · Neovim) pick it up via the standard yaml.schemas association (or a # yaml-language-server: $schema=… modeline) to give autocomplete + inline validation as you type, the same DX as GitHub Actions and Docker Compose. A working modeline today:

yaml

1# yaml-language-server: $schema=https://raw.githubusercontent.com/supernovae-st/nika-spec/main/schemas/workflow.schema.json2nika: my-workflow

The address MUST become versioned and immutable (normative · D-2026-08-11-N24) #

⚠️ The modeline above points at a moving branch, and that is a defect with two independent causes.

The first is ours. Since §unknown key an unknown key is an error, so this schema's additionalProperties: false is no longer a lint preference — it is the accepted surface of the language. Served from main, that surface moves under every editor in the world while no file has changed. A workflow that validated on Monday shows red on Tuesday because a schema it never named was edited. This is precisely the drift the strict rule exists to prevent, arriving through the back door.

The second is the host's. raw.githubusercontent.com fronts a cache that serves stale bytes: a schema can be correct at the commit and wrong at the reader for an unspecified window. Immutable upstream is not immutable at the point of use — measured in this workspace, 2026-08-07.

The shape. One address per minor, frozen forever ·

yaml

1# yaml-language-server: $schema=https://nika.sh/schema/v0.1/workflow.schema.json2nika: my-workflow

This is what JSON Schema, OpenAPI, Kubernetes and CWL all do, and it composes with the nika: mark the envelope already carries. A file written in 2027 still reads in 2030 against its own schema. Until the address ships, the modeline above is the pragmatic form and this paragraph is the standing debt — stated, not hidden.

This is also what makes a Nika file pleasant (and trap-free) for an AI to author: the schema constrains the shape before the engine ever runs. CEL expressions and jq expressions inside string fields are validated by the engine (Core level), not the JSON Schema.

Use case · linters · spec editors · LSP server intelligence · static analyzers.

Level 2 · Runtime conformance #

An engine claims « Runtime v0.1-compliant » if it satisfies Core conformance PLUS ·

Executes the 4 verbs with correct semantics- `infer:` calls a configured provider · returns response - `exec:` runs the command in a shell · honors timeout + security - `invoke:` resolves and calls the tool · returns response - `agent:` runs the multi-turn loop · honors max_turns + tools whitelist
Honors task fields correctly- GATE-v2 admission · every incoming edge's producer settles inside that edge's pass-set, else `cancelled` (dead-path · [03 §gate algebra](./03-dag.md#the-gate-algebra-v2-normative)) - `when` skips when false (POST-gate · local namespaces) - `timeout` (Go-duration string · `"30s"` · `"5m"` etc.) hard-kills on timeout - `retry` strategy honored on transient errors - `on_error` recovery honored on terminal errors - `with` scope injected into task body - `output` binding via jq
Implements security policies- `exec:` blocklist (engine SHOULD ship a sane default · MAY allow override) - `fetch:` SSRF defense for private IP ranges - `invoke:` capability checks (engine's choice of capability model)
Emits workflow events- `task.started` · `task.completed` · `task.failed` · `task.skipped` - `workflow.started` · `workflow.completed` · `workflow.failed` - Event payload includes `task_id` · timestamp · status · duration
Passes all tests in conformance/tests/runtime/

Runtime-compliant engines may bring their own provider implementations · tool implementations · MCP server registries. They are not required to ship the canonical stdlib.

Use case · custom engines for specialized environments (embedded · WASM · custom LLM gateway · etc.).

Level 3 · Stdlib v0.1 conformance #

An engine claims « Stdlib v0.1-compliant » if it satisfies Runtime conformance PLUS ·

Ships all 17 canonical providers (per stdlib/providers-v0.1.md)
Ships all 9 canonical extract modes (per stdlib/extract-modes-v0.1.md)
Ships at least all 28 canonical builtins (core 6 + file 5 + data 9 + network 2 + introspection 2 + media 4 · the remaining deferred media builtins are optional · the byte-determinism clauses of nika:image_fx and nika:chart are part of the bar — an engine that cannot honor them is not conformant, no waiver)
Passes all tests in conformance/tests/stdlib/

A Stdlib-compliant engine is functionally equivalent to the reference implementation for any workflow that uses only the canonical stdlib elements.

Use case · the default level for production engines.

Suite status · v0.1 (honest) #

What is populated TODAY vs what lands with the reference engine ·

Layer · Status · What it proves
**Core fixtures** (`tests/core/`) · ✅ populated · runner-executable · parse + validate + DAG + variables + errors · the full Level-1 static contract
**Deep-static fixtures** (`tests/deep/`) · ✅ populated · runner-executable · the expression layer the schema cannot see · the normative CEL EBNF parsed for real · jq compile · duration grammar · schema-meta · `when:` shape · binding purity
**Stdlib static surface** (`tests/stdlib/`) · ✅ populated · runner-executable · the stdlib **names + shapes** layer · provider prefixes · the closed `nika:*` builtin set · extract modes · checkable with zero execution (lists derive from [`canon.yaml`](../canon.yaml))
**Examples as conformance inputs** (`examples/`) · ✅ executed by the runner `all` gate · every shipped example MUST validate at the full static level
**Runtime behavioral fixtures** (`tests/runtime/`) · ✅ **measured by command** (2026-07-30) · verb execution · task statuses/outputs · events · the trace chain — driven through the PUBLIC doors (`nika run --json` · `nika trace verify`) by [`scripts/runtime-differential.py`](../scripts/runtime-differential.py) · every fixture agrees with the released engine
**Stdlib behavioral fixtures** (`tests/stdlib/behavioral/`) · 🌗 **no-network half measured** (2026-07-30) · builtin *behavior* through the run door — `nika:jq` executes for real (typed result) · the `nika:write`→`nika:read` pair roundtrips under a declared `permits.fs` · `nika:convert` converts (from:/to: required) — same differential, same sweep as the runtime tier. The network half (fetch under HTTP mocks · provider behavior beyond `mock/echo`) stays post-announce

(The provider prefix list is a registry, not grammar — the freeze holds the form, the membership grows additively under the registration policy in providers-v0.1.md §Registration policy · no NEP for a membership row, a NEP for any change to the form.)

Run the static gate yourself · python conformance/runner.py all: the runner output is the live count (counts in prose drift · the suite is the source). Run the behavioral tier yourself · NIKA_BIN=<engine> python3 scripts/runtime-differential.py — same law, the differential's summary is the live count. A « Core v0.1-compliant » claim is FULLY testable today; « Runtime » claims are testable on both halves (static fixtures + the behavioral differential) · « Stdlib v0.1 » on its static half, its behavioral half when those fixtures publish.

Conformance test structure #

text

1conformance/2├── tests/3│   ├── core/                  # Level-1 fixtures · parse · validate · DAG · variables · errors4│   ├── deep/                  # deep-static layer · CEL subset parse · jq compile ·5│   │                          # durations · schema-meta · when shape · binding purity6│   ├── lints/                 # advisory-lint fixtures7│   ├── runtime/               # verb execution · task fields · events (behavioral half)8│   │   ├── trace/            #   the journal, judged by the walk (a verdict)9│   │   ├── receipt/          #   the receipt, judged by its reading (what projects)10│   │   ├── registry/         #   a cache record × an operator floor, judged by admission11│   │   ├── energy/           #   a workflow, judged by the energy reading it must report12│   │   └── resume/           #   a journal × a compat declaration, judged by the version crossing13│   └── stdlib/                # provider/extract/builtin canonical surface14│15├── runner.py                  # the static oracle · `all` is the CI gate16├── *_core.py                  # per-domain reference evaluators (type · decision ·17│                              # gateway · outcome · composition · yaml-profile ·18│                              # proof · projection) + their `*_selftest.py` sweeps19├── yaml-profile/              # R11 profile fixtures (valid/ + invalid/)20├── type-corpus/               # the generated type corpus (gen-type-corpus.py)21├── values/                    # the three-authority family (C2 · R3a · valid/ + invalid/)22├── types/                     # io-declaration predicate vocabulary (C2 · R3b · valid/ + invalid/)23├── gates/                     # the after: predicate vocabulary (C2 · R5 · valid/ + invalid/)24└── runner-protocol.md         # how to run the suite against any engine

The directory is the source — this sketch is a map, not the inventory (python3 conformance/runner.py all prints the live fixture counts). Each fixture is a pair · input.yaml (the workflow to feed) + expected.json (the expected output or error structure).

For tests that require executing against real LLMs / networks · the suite uses the mock provider and HTTP mocks to keep tests deterministic.

Runner protocol #

A conformance runner ·

Reads each input.yaml
Pipes it to the engine being tested (engine run --input -)
Captures the engine's output (stdout JSON · structured)
Compares against expected.json
Reports pass/fail per test · final summary

See conformance/runner-protocol.md for the exact JSON wire format.

Claiming conformance #

The public claim string is « Nika v1 Conformant — <Level> (spec <commit>) » · Level ∈ Core · Runtime · Stdlib v0.1 · the spec commit is the pin the suite ran against. One form everywhere — badges · READMEs · listings · release notes. (In normative sentences, « v0.1-compliant » names the level bar an engine satisfies; the string above is the one public claim.)

To make the claim · an engine ·

MUST pass the conformance suite at the claimed level
MUST name the level and the spec commit in the claim (the format above)
MAY open a PR on supernovae-st/nika-spec to be listed in CONFORMANT_IMPLEMENTATIONS.md

The claim is earned by passing the suite, never by declaration (NEP-0000 §Relationship to conformance). The reference implementation supernovae-st/nika targets Stdlib v0.1 conformance.

Versioning #

A conformance claim is specific to a spec version. As the stdlib evolves to v0.2 · engines re-claim conformance against the new suite. The Core conformance level is stable forever within v1 of the language.

An unknown key is an error, at every level (normative · D-2026-08-11-N20) #

An engine MUST refuse a key it does not know (NIKA-PARSE-005). It MUST NOT accept-and-warn. This clause used to leave the choice to the engine, and a choice here is not a detail: it is the whole growth model. Two conformant engines were entitled to disagree on every future key — one refusing a file the other ran — which is the definition of a language that has not decided what it is.

Why refusal is the safe direction, and acceptance is not. The instinct runs the other way: accept-and-warn looks forward-compatible, since a file written for a later minor would still run on an older engine. It is the wrong instinct here, because a key in this language can REMOVE authority. A future rule that forbids something would be silently dropped by an older engine, and the file would run with more authority than its author granted — failing open, in the one language whose premise is that an absent grant means zero. Refusal fails closed: the file does not run at all, and the author learns why.

What it buys, and it is not small. Every key this spec reserves for a later minor lands additively and for free under refusal: no valid file uses one today, so admitting it later breaks nothing. Adding to a closed space is always compatible; the closure is what makes the growth safe. It also catches the misspelling — permit: written for permits: — which today is accepted in silence and yields zero authority without saying so, the most expensive typo the language can carry.

Precedent, and it is not ours. CWL treats an unrecognised field as a fatal error; the field its readers may ignore is the advisory one, not the structural one. A serious specification refuses.

⚠️ A corollary that is not optional. Under strict refusal, the published JSON Schema (additionalProperties: false) can no longer be served from a moving branch: it needs a versioned, immutable address (one per minor). Otherwise the editors of the world watch the accepted surface move under them while no file has changed — the drift the refusal exists to prevent, arriving by the back door.

🦋 Next · [08 · Out of scope](./08-out-of-scope.md)

nika-spec@2b3d6ac3e · 07-conformance.md · sha256 16604aec244e4ff6… · the pack upstream