[{"k":"h","depth":1,"text":"00 · Overview","id":"00--overview"},{"k":"quote","inline":[{"k":"text","text":"The one-page vision. Read this first."}]},{"k":"hr"},{"k":"h","depth":2,"text":"What Nika is","id":"what-nika-is"},{"k":"p","inline":[{"k":"text","text":"Nika is a "},{"k":"strong","text":"declarative YAML language for AI workflows"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"It describes the "},{"k":"strong","text":"what"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"which LLMs to call ("},{"k":"code","text":"infer:"},{"k":"text","text":")"}],[{"k":"text","text":"which commands to run ("},{"k":"code","text":"exec:"},{"k":"text","text":")"}],[{"k":"text","text":"which tools to call, including fetching a URL ("},{"k":"code","text":"invoke:"},{"k":"text","text":")"}],[{"k":"text","text":"which agentic loops to spawn ("},{"k":"code","text":"agent:"},{"k":"text","text":")"}]]},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"strong","text":"how"},{"k":"text","text":" lives in conformant engines."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Why a language?","id":"why-a-language"},{"k":"p","inline":[{"k":"text","text":"Every AI harness today reinvents the wheel · Python files · TypeScript\nclasses · skills crystallized into their own runtime. None of them are\n"},{"k":"strong","text":"portable"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"A portable language means ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"One YAML workflow · runs on any conformant engine"}],[{"k":"text","text":"Read · share · review · diff like any text"}],[{"k":"text","text":"The contract is the language · not the runtime"}]]},{"k":"p","inline":[{"k":"text","text":"Standards work · SQL · GraphQL · OpenAPI · Dockerfile · GitHub Actions YAML. Nika is that for AI workflows."}]},{"k":"hr"},{"k":"h","depth":2,"text":"The 5 pillars · immutable forever","id":"the-5-pillars--immutable-forever"},{"k":"code","lang":"text","text":"1.  ENVELOPE        nika: v1\n                    workflow:\n                      id: my-workflow-id\n\n2.  THE 4 VERBS     infer:  exec:  invoke:  agent:\n\n3.  DAG SHAPE       tasks · with (data edges) · after (control) · when · for_each\n\n4.  VARIABLES       \u0024{{ ... }} = CEL · ONE syntax · 6 namespaces\n                    inputs · config · const · secrets · with · tasks\n\n5.  ERROR MODEL     NIKA-<NS>-<NNN> codes · retry semantics · structured output"},{"k":"p","inline":[{"k":"text","text":"These 5 pillars are "},{"k":"strong","text":"locked forever"},{"k":"text","text":" at "},{"k":"code","text":"nika: v1"},{"k":"text","text":". Everything else (providers · builtins · extract modes · etc.) lives in the "},{"k":"strong","text":"stdlib"},{"k":"text","text":" and evolves independently. Minor language additions are "},{"k":"strong","text":"additive"},{"k":"text","text":" within "},{"k":"code","text":"v1"},{"k":"text","text":" (feature-detected · no minor version in the file)."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Pre-1.0 stability contract","id":"pre-10-stability-contract"},{"k":"quote","inline":[{"k":"strong","text":"`nika: v1` names the first stable family of the language. Its public\nstability begins at engine 1.0.0 — not before."}]},{"k":"p","inline":[{"k":"text","text":"Until the reference engine ships 1.0.0, the v1 grammar is "},{"k":"strong","text":"pre-stable"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"0.x releases may break the grammar."},{"k":"text","text":" Surface spellings — task shape ·\ndependency syntax · namespace names · field names — can be rewritten\ndeeply while the binary is "},{"k":"code","text":"0.x"},{"k":"text","text":". The 5 pillars above are locked as\n"},{"k":"strong","text":"concepts"},{"k":"text","text":"; their surface spellings are pre-stable like everything else\nuntil 1.0. What would actually be unclean is freezing ambiguities now and\nthen spending years building checkers, editors and migrations to\ncompensate for them."}],[{"k":"strong","text":"No syntax compatibility is promised before 1.0."},{"k":"text","text":" No aliases · no\ndeprecation cycles · no dual forms. When a form dies it leaves the parser\nentirely, in the same release that introduces its replacement."}],[{"k":"strong","text":"Every break lands as ONE atomic window"},{"k":"text","text":" · the spec changes first → the\nconformance oracle changes → engines re-vendor the pack → parser and\nruntime change → the whole example/template/conformance corpus migrates →\nLSP · MCP · editors · docs follow → the old form is gone. A release never\nships two worlds."}],[{"k":"strong","text":"Consumers pin exact spec commits"},{"k":"text","text":" ("},{"k":"code","text":"SPEC_PIN"},{"k":"text","text":") — never a moving branch.\nCross-repo coherence is judged by pinned re-proof, not by compatibility\nlayers."}],[{"k":"strong","text":"Machine contracts version independently"},{"k":"text","text":" of the language family ·\n"},{"k":"code","text":"graph_format"},{"k":"text","text":" · check "},{"k":"code","text":"report_version"},{"k":"text","text":" · run "},{"k":"code","text":"plan_version"},{"k":"text","text":" · trace ·\nlock · receipt formats each carry their own explicit integer and evolve\nby their own rules."}],[{"k":"strong","text":"The meta-principle"},{"k":"text","text":" · when tooling effort reveals a language defect,\nthe spec changes first and the tooling teaches second. A client-side\nworkaround is never permanent."}]]},{"k":"p","inline":[{"k":"text","text":"At engine 1.0.0 the grammar freezes · from then on "},{"k":"code","text":"v1"},{"k":"text","text":" changes are\nadditive and feature-detected, exactly as the pillars section states."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Hello world","id":"hello-world"},{"k":"code","lang":"yaml","text":"nika: v1\nworkflow:\n  id: hello\n\nmodel: ollama/qwen3.5:4b\ntasks:\n  greet:\n    infer:\n      prompt: \"Say hello in French\""},{"k":"hr"},{"k":"h","depth":2,"text":"A more representative example","id":"a-more-representative-example"},{"k":"code","lang":"yaml","text":"nika: v1\nworkflow:\n  id: scrape-and-summarize\n\nmodel: mistral/mistral-large\ntasks:\n  fetch_page:\n    invoke:\n      tool: \"nika:fetch\"        # fetching is a TOOL, not a verb (4-verb taxonomy)\n      args:\n        url: \"https://example.com/article\"\n        mode: article          # readability extraction\n\n  summarize:\n    with:\n      content: \u0024{{ tasks.fetch_page.output }}    # the binding IS the edge\n    infer:\n      prompt: \"Summarize in 3 bullets · \u0024{{ with.content }}\"\n\n  write_file:\n    with:\n      summary: \u0024{{ tasks.summarize.output }}\n    invoke:\n      tool: \"nika:write\"\n      args:\n        path: \"summary.md\"\n        content: \"\u0024{{ with.summary }}\"\n\noutputs:                              # what the workflow returns · symmetric to inputs:\n  summary: \u0024{{ tasks.summarize.output }}"},{"k":"p","inline":[{"k":"text","text":"3 tasks · 2 verbs ("},{"k":"code","text":"invoke:"},{"k":"text","text":" ×2 incl "},{"k":"code","text":"nika:fetch"},{"k":"text","text":" · "},{"k":"code","text":"infer:"},{"k":"text","text":") · variable substitution + an "},{"k":"code","text":"outputs:"},{"k":"text","text":" return contract. Note the graph is DERIVED: each "},{"k":"code","text":"with:"},{"k":"text","text":" binding that references "},{"k":"code","text":"\u0024{{ tasks.X.* }}"},{"k":"text","text":" IS a typed edge — data and its dependency are one declaration, no invisible edges ("},{"k":"link","text":"03","href":"./03-dag.md"},{"k":"text","text":"). The 4th verb, "},{"k":"code","text":"agent:"},{"k":"text","text":" (an agentic loop · may declare a "},{"k":"code","text":"schema:"},{"k":"text","text":"), is shown in "},{"k":"link","text":"examples/","href":"../examples/"},{"k":"text","text":"."}]},{"k":"hr"},{"k":"h","depth":2,"text":"How to read the rest","id":"how-to-read-the-rest"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Section · What it covers"}],[{"k":"text","text":"[01 envelope](./01-envelope.md) · The header · `nika: v1` · `workflow:` · typed `inputs` · `config` · `const` · `secrets`"}],[{"k":"text","text":"[02 verbs](./02-verbs.md) · The 4 verbs · signatures · semantics"}],[{"k":"text","text":"[03 DAG](./03-dag.md) · Tasks · `with:` data edges · `after:` control · `when` · `for_each` · the four graphs"}],[{"k":"text","text":"[04 variables](./04-variables.md) · `\u0024{{ inputs · config · const · secrets · with · tasks }}` · 6 namespaces"}],[{"k":"text","text":"[05 errors](./05-errors.md) · Error codes · retry · structured output schemas"}],[{"k":"text","text":"[06 stdlib contract](./06-stdlib-contract.md) · How the stdlib versions independently"}],[{"k":"text","text":"[07 conformance](./07-conformance.md) · What « v0.1-compliant » means"}],[{"k":"text","text":"[08 out of scope](./08-out-of-scope.md) · Explicit defer list (memory · macros · etc.)"}],[{"k":"text","text":"[09 types](./09-types.md) · The decidable type core · `types:` · `returns:` · `decode:` · the lattice · JSON-Schema lowering"}],[{"k":"text","text":"[10 authority](./10-authority.md) · The authority system · the effect vocabulary · `policy:` (named workflow law) · secret-flow codes · `certificate.effects`"}],[{"k":"text","text":"[11 decision](./11-decision.md) · The decision contract · portable Decision Bundle · Evidence IR (two lattices) · Belnap logic · fixed-point Decision IR · abstention · `nika:decide`"}],[{"k":"text","text":"[12 gateway](./12-gateway.md) · The gateway contracts · Deployment Bundle · ExecutionBackend (capabilities · lowering · readback) · AgentRuntimeAdapter (FidelityReport · AuthorityDelta) · the separation laws"}],[{"k":"text","text":"[13 outcomes](./13-outcomes.md) · The Outcome IR · TerminalClass × Cause × Payload · the normative transition table (one source: canon) · `trace_format: 2`"}],[{"k":"text","text":"[14 composition](./14-composition.md) · Workflow calling workflow · `invoke: workflow:` (tagged union) · the CallableContract · the ten composition laws · the trace forest"}],[{"k":"text","text":"[15 proof](./15-proof.md) · The proof layer · the semantic hash (H = H(domain ‖ version ‖ JCS(IR))) · `nika.lock` (pin by default) · `assert:` (StaticProof · TraceVerified · Unknown) · the one receipt"}],[{"k":"text","text":"[16 projections](./16-projections.md) · The oracle surface · one canonical projection (graph_format:2) served byte-identical across CLI · LSP · MCP · the LSP semantic document (`semantic_document_format: 1`) wraps it with spans + one-word `reason` · the additive arc (holes · actions · capabilities over the frozen IR)"}],[{"k":"text","text":"[17 trace](./17-trace.md) · The run journal · NDJSON frames chained by sha256 (`trace_format: 2` · the prologue manifest · the closed kind vocabulary) · the REQUIRED permit-decision witness (NEP-0007 · granted and refused alike) · the differential check ⇔ run equivalence law · graved from an observed run"}]]},{"k":"p","inline":[{"k":"strong","text":"Stdlib"},{"k":"text","text":" (versioned independently · not a spec section) · "},{"k":"link","text":"stdlib/","href":"../stdlib/"},{"k":"text","text":": "},{"k":"strong","text":"17 providers · <!-- canon:extract_modes -->9<!-- /canon --> extract modes · 28 builtins"},{"k":"text","text":" (6 core · 5 file · 8 data · 2 network · 2 introspection · 4 media)."}]},{"k":"hr"},{"k":"h","depth":2,"text":"What's NOT in v0.1 of the language","id":"whats-not-in-v01-of-the-language"},{"k":"p","inline":[{"k":"text","text":"The following are "},{"k":"strong","text":"deferred"},{"k":"text","text":" to stdlib v0.x or beyond ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Memory subsystem APIs (the engine's memory subsystem · the Connectome · separate stdlib version)"}],[{"k":"text","text":"Workflow include/import (single-file workflows only in v0.1)"}],[{"k":"text","text":"Macros / templates (no preprocessing layer)"}],[{"k":"text","text":"22 media builtins ("},{"k":"code","text":"pdf_extract"},{"k":"text","text":" · "},{"k":"code","text":"ocr"},{"k":"text","text":" · "},{"k":"code","text":"qr_validate"},{"k":"text","text":" · etc. · stdlib v0.x)"}],[{"k":"text","text":"Persistent jobs · scheduled execution (runtime concern · daemon at v0.3)"}],[{"k":"text","text":"Streaming output (deferred)"}],[{"k":"text","text":"Multi-workflow orchestration (deferred)"}]]},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"link","text":"`08-out-of-scope.md`","href":"./08-out-of-scope.md"},{"k":"text","text":" for the explicit list."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Frozen language envelope","id":"frozen-language-envelope"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"strong","text":"language"},{"k":"text","text":" envelope is frozen at "},{"k":"code","text":"nika: v1"},{"k":"text","text":" forever. "},{"k":"strong","text":"There is no `nika: v2` — ever."},{"k":"text","text":" The version marker names the one language family; deep grammar changes happen INSIDE "},{"k":"code","text":"v1"},{"k":"text","text":" while the reference engine is pre-1.0 (per the "},{"k":"link","text":"pre-1.0 stability contract","href":"#pre-10-stability-contract"},{"k":"text","text":" above), and after engine 1.0.0 changes are additive only (feature-detected · no minor version in the file). (This is the "},{"k":"strong","text":"language"},{"k":"text","text":" version, independent of any engine version: the reference engine ships its own semver toward a 1.0 release, which does not touch "},{"k":"code","text":"nika: v1"},{"k":"text","text":".)"}]},{"k":"p","inline":[{"k":"text","text":"In practice · we expect "},{"k":"code","text":"nika: v1"},{"k":"text","text":" to last 10+ years."}]},{"k":"hr"},{"k":"p","inline":[{"k":"text","text":"🦋 "},{"k":"em","text":"Less but better · Rams principle 10."}]}]

the spec · 00

Overview

The one-page vision.

00 · Overview #

The one-page vision. Read this first.

What Nika is #

Nika is a declarative YAML language for AI workflows.

It describes the what ·

which LLMs to call (infer:)
which commands to run (exec:)
which tools to call, including fetching a URL (invoke:)
which agentic loops to spawn (agent:)

The how lives in conformant engines.

Why a language? #

Every AI harness today reinvents the wheel · Python files · TypeScript classes · skills crystallized into their own runtime. None of them are portable.

A portable language means ·

One YAML workflow · runs on any conformant engine
Read · share · review · diff like any text
The contract is the language · not the runtime

Standards work · SQL · GraphQL · OpenAPI · Dockerfile · GitHub Actions YAML. Nika is that for AI workflows.

The 5 pillars · immutable forever #

text

11.  ENVELOPE        nika: v12                    workflow:3                      id: my-workflow-id452.  THE 4 VERBS     infer:  exec:  invoke:  agent:673.  DAG SHAPE       tasks · with (data edges) · after (control) · when · for_each894.  VARIABLES       ${{ ... }} = CEL · ONE syntax · 6 namespaces10                    inputs · config · const · secrets · with · tasks11125.  ERROR MODEL     NIKA-<NS>-<NNN> codes · retry semantics · structured output

These 5 pillars are locked forever at nika: v1. Everything else (providers · builtins · extract modes · etc.) lives in the stdlib and evolves independently. Minor language additions are additive within v1 (feature-detected · no minor version in the file).

Pre-1.0 stability contract #

`nika: v1` names the first stable family of the language. Its public stability begins at engine 1.0.0 — not before.

Until the reference engine ships 1.0.0, the v1 grammar is pre-stable ·

0.x releases may break the grammar. Surface spellings — task shape · dependency syntax · namespace names · field names — can be rewritten deeply while the binary is 0.x. The 5 pillars above are locked as concepts; their surface spellings are pre-stable like everything else until 1.0. What would actually be unclean is freezing ambiguities now and then spending years building checkers, editors and migrations to compensate for them.
No syntax compatibility is promised before 1.0. No aliases · no deprecation cycles · no dual forms. When a form dies it leaves the parser entirely, in the same release that introduces its replacement.
Every break lands as ONE atomic window · the spec changes first → the conformance oracle changes → engines re-vendor the pack → parser and runtime change → the whole example/template/conformance corpus migrates → LSP · MCP · editors · docs follow → the old form is gone. A release never ships two worlds.
Consumers pin exact spec commits (SPEC_PIN) — never a moving branch. Cross-repo coherence is judged by pinned re-proof, not by compatibility layers.
Machine contracts version independently of the language family · graph_format · check report_version · run plan_version · trace · lock · receipt formats each carry their own explicit integer and evolve by their own rules.
The meta-principle · when tooling effort reveals a language defect, the spec changes first and the tooling teaches second. A client-side workaround is never permanent.

At engine 1.0.0 the grammar freezes · from then on v1 changes are additive and feature-detected, exactly as the pillars section states.

Hello world #

yaml

1nika: v12workflow:3  id: hello45model: ollama/qwen3.5:4b6tasks:7  greet:8    ◇infer:9      prompt: "Say hello in French"

A more representative example #

yaml

1nika: v12workflow:3  id: scrape-and-summarize45model: mistral/mistral-large6tasks:7  fetch_page:8    ◆invoke:9      tool: "nika:fetch"        # fetching is a TOOL, not a verb (4-verb taxonomy)10      args:11        url: "https://example.com/article"12        mode: article          # readability extraction1314  summarize:15    with:16      content: ${{ tasks.fetch_page.output }}    # the binding IS the edge17    ◇infer:18      prompt: "Summarize in 3 bullets · ${{ with.content }}"1920  write_file:21    with:22      summary: ${{ tasks.summarize.output }}23    ◆invoke:24      tool: "nika:write"25      args:26        path: "summary.md"27        content: "${{ with.summary }}"2829outputs:                              # what the workflow returns · symmetric to inputs:30  summary: ${{ tasks.summarize.output }}

3 tasks · 2 verbs (invoke: ×2 incl nika:fetch · infer:) · variable substitution + an outputs: return contract. Note the graph is DERIVED: each with: binding that references ${{ tasks.X.* }} IS a typed edge — data and its dependency are one declaration, no invisible edges (03). The 4th verb, agent: (an agentic loop · may declare a schema:), is shown in examples/.

How to read the rest #

Section · What it covers
[01 envelope](./01-envelope.md) · The header · `nika: v1` · `workflow:` · typed `inputs` · `config` · `const` · `secrets`
[02 verbs](./02-verbs.md) · The 4 verbs · signatures · semantics
[03 DAG](./03-dag.md) · Tasks · `with:` data edges · `after:` control · `when` · `for_each` · the four graphs
[04 variables](./04-variables.md) · `${{ inputs · config · const · secrets · with · tasks }}` · 6 namespaces
[05 errors](./05-errors.md) · Error codes · retry · structured output schemas
[06 stdlib contract](./06-stdlib-contract.md) · How the stdlib versions independently
[07 conformance](./07-conformance.md) · What « v0.1-compliant » means
[08 out of scope](./08-out-of-scope.md) · Explicit defer list (memory · macros · etc.)
[09 types](./09-types.md) · The decidable type core · `types:` · `returns:` · `decode:` · the lattice · JSON-Schema lowering
[10 authority](./10-authority.md) · The authority system · the effect vocabulary · `policy:` (named workflow law) · secret-flow codes · `certificate.effects`
[11 decision](./11-decision.md) · The decision contract · portable Decision Bundle · Evidence IR (two lattices) · Belnap logic · fixed-point Decision IR · abstention · `nika:decide`
[12 gateway](./12-gateway.md) · The gateway contracts · Deployment Bundle · ExecutionBackend (capabilities · lowering · readback) · AgentRuntimeAdapter (FidelityReport · AuthorityDelta) · the separation laws
[13 outcomes](./13-outcomes.md) · The Outcome IR · TerminalClass × Cause × Payload · the normative transition table (one source: canon) · `trace_format: 2`
[14 composition](./14-composition.md) · Workflow calling workflow · `invoke: workflow:` (tagged union) · the CallableContract · the ten composition laws · the trace forest
[15 proof](./15-proof.md) · The proof layer · the semantic hash (H = H(domain ‖ version ‖ JCS(IR))) · `nika.lock` (pin by default) · `assert:` (StaticProof · TraceVerified · Unknown) · the one receipt
[16 projections](./16-projections.md) · The oracle surface · one canonical projection (graph_format:2) served byte-identical across CLI · LSP · MCP · the LSP semantic document (`semantic_document_format: 1`) wraps it with spans + one-word `reason` · the additive arc (holes · actions · capabilities over the frozen IR)
[17 trace](./17-trace.md) · The run journal · NDJSON frames chained by sha256 (`trace_format: 2` · the prologue manifest · the closed kind vocabulary) · the REQUIRED permit-decision witness (NEP-0007 · granted and refused alike) · the differential check ⇔ run equivalence law · graved from an observed run

Stdlib (versioned independently · not a spec section) · stdlib/: 17 providers · 9 extract modes · 28 builtins (6 core · 5 file · 8 data · 2 network · 2 introspection · 4 media).

What's NOT in v0.1 of the language #

The following are deferred to stdlib v0.x or beyond ·

Memory subsystem APIs (the engine's memory subsystem · the Connectome · separate stdlib version)
Workflow include/import (single-file workflows only in v0.1)
Macros / templates (no preprocessing layer)
22 media builtins (pdf_extract · ocr · qr_validate · etc. · stdlib v0.x)
Persistent jobs · scheduled execution (runtime concern · daemon at v0.3)
Streaming output (deferred)
Multi-workflow orchestration (deferred)

See `08-out-of-scope.md` for the explicit list.

Frozen language envelope #

The language envelope is frozen at nika: v1 forever. There is no `nika: v2` — ever. The version marker names the one language family; deep grammar changes happen INSIDE v1 while the reference engine is pre-1.0 (per the pre-1.0 stability contract above), and after engine 1.0.0 changes are additive only (feature-detected · no minor version in the file). (This is the language version, independent of any engine version: the reference engine ships its own semver toward a 1.0 release, which does not touch nika: v1.)

In practice · we expect nika: v1 to last 10+ years.

🦋 Less but better · Rams principle 10.

nika-spec@6ac29351a · 00-overview.md · sha256 7568e18ca1bc3031… · the pack upstream