[{"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: my-workflow-id        ← the mark AND the name\n                    9 keys · nika · model · inputs · const · secrets\n                              permits · run · tasks · outputs\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 · 5 namespaces\n                    inputs · 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 v1. 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 version marker in the file at all)."}]},{"k":"hr"},{"k":"h","depth":2,"text":"Pre-1.0 stability contract","id":"pre-10-stability-contract"},{"k":"quote","inline":[{"k":"strong","text":"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: 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: 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 · the 9 keys · `nika:` (the mark AND the name) · typed `inputs` · `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 · const · secrets · with · tasks }}` · 5 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 · `returns:` (the type expression, INLINE) · `decode:` · the lattice · JSON-Schema lowering"}],[{"k":"text","text":"[10 authority](./10-authority.md) · The authority system · the effect vocabulary · the unconditional order law (`NIKA-SEC-015`) · 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:3) 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":"h","depth":2,"text":"What supervises a run — *and what does not*","id":"what-supervises-a-run--and-what-does-not"},{"k":"p","inline":[{"k":"text","text":"Nika is a "},{"k":"strong","text":"local process"},{"k":"text","text":", and this is a claim about its limits, not a\nfeature list."}]},{"k":"p","inline":[{"k":"text","text":"Restate states the constraint that applies here better than a\nself-assessment would: "},{"k":"em","text":"\"A library cannot supervise itself. It dies\ntogether with the process… the component that guarantees a process runs\nto completion has to see the whole process — it cannot live inside the\nthing whose lifetime it is guaranteeing.\""},{"k":"text","text":" That reasoning reaches Nika.\n"},{"k":"code","text":"nika run"},{"k":"text","text":" is not a supervised workflow service; it is a program on your\nmachine, and "},{"k":"strong","text":"the supervisor of a local CLI is whatever started it"},{"k":"text","text":" —\nyour shell, your CI job, your systemd unit."}]},{"k":"p","inline":[{"k":"text","text":"What Nika does guarantee is narrower and worth stating exactly. Every\neffect is recorded in a hash-chained trace as it happens, so a killed\nrun leaves an "},{"k":"strong","text":"auditable prefix"},{"k":"text","text":" rather than an unknown state, and\n"},{"k":"code","text":"nika run --resume <trace>"},{"k":"text","text":" continues from it."}]},{"k":"p","inline":[{"k":"text","text":"Resumption is keyed by "},{"k":"strong","text":"task identity"},{"k":"text","text":", never by position. A task is\nskipped only when its identity matches a journaled success — and that\nidentity covers the task's content, so "},{"k":"strong","text":"an edited task or a changed\ninput always re-runs"},{"k":"text","text":". Nothing in the journal is addressed by index, by\nordinal, or by rank within a wave; a reader that indexes a trace\npositionally is non-conforming. The consequence is worth stating\npositively: replaying a trace against a file that has since been edited\ncannot silently re-associate a record with a task that is no longer the\none that produced it. The edit is visible, and the work is redone."}]},{"k":"p","inline":[{"k":"text","text":"What Nika does "},{"k":"strong","text":"not"},{"k":"text","text":" claim: that a run survives its own process being\nkilled without a supervisor restarting it, that a crashed machine\nresumes on reboot by itself, or that any daemon is watching. Durable\nexecution against those failures is a different architecture with a\ndifferent operational cost, and v1 does not pretend to it."}]},{"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":"strong","text":"v1"},{"k":"text","text":" forever. "},{"k":"strong","text":"There is no `nika: v2` — ever."},{"k":"text","text":" Because that was true, the version slot carried no bits, and the envelope nuke gave it away: "},{"k":"code","text":"nika:"},{"k":"text","text":" now holds the file's NAME. "},{"k":"strong","text":"Nothing was lost."},{"k":"text","text":" v1 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 version marker in the file at all). (This is the "},{"k":"strong","text":"language"},{"k":"text","text":" family, independent of any engine version: the reference engine ships its own semver toward a 1.0 release, which does not touch v1.)"}]},{"k":"p","inline":[{"k":"text","text":"In practice · we expect v1 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: my-workflow-id        ← the mark AND the name2                    9 keys · nika · model · inputs · const · secrets3                              permits · run · tasks · outputs452.  THE 4 VERBS     infer:  exec:  invoke:  agent:673.  DAG SHAPE       tasks · with (data edges) · after (control) · when · for_each894.  VARIABLES       ${{ ... }} = CEL · ONE syntax · 5 namespaces10                    inputs · const · secrets · with · tasks11125.  ERROR MODEL     NIKA-<NS>-<NNN> codes · retry semantics · structured output

These 5 pillars are locked forever at 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 version marker in the file at all).

Pre-1.0 stability contract #

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: hello23model: ollama/qwen3.5:4b4tasks:5  greet:6    ◇infer:7      prompt: "Say hello in French"

A more representative example #

yaml

1nika: scrape-and-summarize23model: mistral/mistral-large4tasks:5  fetch_page:6    ◆invoke:7      tool: "nika:fetch"        # fetching is a TOOL, not a verb (4-verb taxonomy)8      args:9        url: "https://example.com/article"10        mode: article          # readability extraction1112  summarize:13    with:14      content: ${{ tasks.fetch_page.output }}    # the binding IS the edge15    ◇infer:16      prompt: "Summarize in 3 bullets · ${{ with.content }}"1718  write_file:19    with:20      summary: ${{ tasks.summarize.output }}21    ◆invoke:22      tool: "nika:write"23      args:24        path: "summary.md"25        content: "${{ with.summary }}"2627outputs:                              # what the workflow returns · symmetric to inputs:28  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 · the 9 keys · `nika:` (the mark AND the name) · typed `inputs` · `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 · const · secrets · with · tasks }}` · 5 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 · `returns:` (the type expression, INLINE) · `decode:` · the lattice · JSON-Schema lowering
[10 authority](./10-authority.md) · The authority system · the effect vocabulary · the unconditional order law (`NIKA-SEC-015`) · 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:3) 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.

What supervises a run — and what does not #

Nika is a local process, and this is a claim about its limits, not a feature list.

Restate states the constraint that applies here better than a self-assessment would: "A library cannot supervise itself. It dies together with the process… the component that guarantees a process runs to completion has to see the whole process — it cannot live inside the thing whose lifetime it is guaranteeing." That reasoning reaches Nika. nika run is not a supervised workflow service; it is a program on your machine, and the supervisor of a local CLI is whatever started it — your shell, your CI job, your systemd unit.

What Nika does guarantee is narrower and worth stating exactly. Every effect is recorded in a hash-chained trace as it happens, so a killed run leaves an auditable prefix rather than an unknown state, and nika run --resume <trace> continues from it.

Resumption is keyed by task identity, never by position. A task is skipped only when its identity matches a journaled success — and that identity covers the task's content, so an edited task or a changed input always re-runs. Nothing in the journal is addressed by index, by ordinal, or by rank within a wave; a reader that indexes a trace positionally is non-conforming. The consequence is worth stating positively: replaying a trace against a file that has since been edited cannot silently re-associate a record with a task that is no longer the one that produced it. The edit is visible, and the work is redone.

What Nika does not claim: that a run survives its own process being killed without a supervisor restarting it, that a crashed machine resumes on reboot by itself, or that any daemon is watching. Durable execution against those failures is a different architecture with a different operational cost, and v1 does not pretend to it.

Frozen language envelope #

The language envelope is frozen at v1 forever. There is no `nika: v2` — ever. Because that was true, the version slot carried no bits, and the envelope nuke gave it away: nika: now holds the file's NAME. Nothing was lost. v1 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 version marker in the file at all). (This is the language family, independent of any engine version: the reference engine ships its own semver toward a 1.0 release, which does not touch v1.)

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

🦋 Less but better · Rams principle 10.

nika-spec@2b3d6ac3e · 00-overview.md · sha256 d4ef55ec1d1e65cb… · the pack upstream