the spec · 06
Stdlib contract
The stdlib is the set of **providers** · **extract modes** · and **builtins** that ship with v0.1 conformant engines.
06 · Stdlib contract #
The stdlib is the set of providers · extract modes · and builtins that ship with v0.1 conformant engines. The stdlib is versioned independently from the core language · it may evolve while the 5 pillars remain frozen.
What is the stdlib? #
CORE LANGUAGE STDLIB───────────── ──────envelope providers (infer · agent)4 verbs (signatures only) extract modes (the nika:fetch tool)DAG semantics builtins (invoke)variable substitutionerror modelLocked forever at v1. Versioned · stdlib v0.x · evolves.A workflow that uses only the core language is portable across engines forever. Adding stdlib dependencies (e.g. specific provider names · specific builtins) constrains portability to engines that ship those stdlib elements.
Why split core vs stdlib? #
Three reasons ·
- Forward compat · we need to add providers (new LLMs ship every quarter), add builtins, add extract modes. Locking these in the core would mean breaking the language every few months. Splitting lets the core stay frozen.
- Optional surface · an engine may choose not to ship the full stdlib. A minimal engine may support only
mockprovider for testing. A specialized engine may ship only a subset of builtins. The conformance level reflects this (see 07-conformance.md). - Audience clarity · the core is the contract between workflow author and engine. The stdlib is the curated library of building blocks an engine ships.
Versioning #
The stdlib has independent versioning ·
stdlib/providers-v0.1.md, the 17 canonical providers for v0.1stdlib/extract-modes-v0.1.md, the <!-- canon:extract_modes -->9<!-- /canon --> canonical extract modes for v0.1stdlib/builtins-v0.1.md, the 28 canonical builtins for v0.1
When the stdlib evolves to v0.2 · those files become *-v0.2.md and new versions are published. The core language contract (nika: v1) is unchanged.
A workflow MAY declare a stdlib version dependency · though v0.1 does not require this. v0.2 may introduce an optional stdlib: field in the envelope.
Inclusion criteria #
For an element to enter the stdlib · it MUST satisfy ·
- Empirical demand · documented use in real workflows (canonical examples)
- Mature implementation · battle-tested in at least one engine · bug-stable
- Forward-compat safe · signature stable · no breaking semantic risk
- Sovereignty-aligned · prefers local-first OR multi-vendor (no single-cloud lock-in)
The reference engine provides these elements behind strict quality gates. Other engines may match this bar.
What's IN stdlib v0.1 #
Providers (17) #
ollama · lmstudio · llamacpp · localai · vllm (5 local) · mistral · anthropic · openai · openrouter · groq · deepseek · gemini · xai · huggingface · nvidia · moonshot (11 cloud) · mock (test)
Selected via a single model: <provider>/<name> field. Any other OpenAI-compatible local/remote server routes through the openai + base_url escape hatch (no new provider name). See stdlib/providers-v0.1.md.
Extract modes (9) #
markdown · article · jq · text · selector · metadata · links · feed · sitemap
See stdlib/extract-modes-v0.1.md.
Builtins (28) #
6 core (log · emit · assert · prompt · done · wait)
- 5 file (read · write · edit · glob · grep)
- 9 data (jq · json_diff · validate · json_merge_patch · convert · uuid · date · hash · decide · the decision kernel · spec 11 · 2026-07-15)
- 2 introspection (inspect · view-discriminated · 4 views cost/records/dag_info/threads · compose · agent-loop self-check)
- 2 network (fetch · notify)
- 4 media (image_generate · graduate #1 · 2026-07-05 · tts_generate · §Audio · sovereign-first · 2026-07-05 · image_fx · graduate #3 · deterministic artistic effects · 2026-07-09 · chart · graduate #4 · attested deterministic charts · 2026-07-09)
= 28 canonical builtins (Stdlib v0.1 · consolidated · was 42 ·
jqsubsumes 13 data builtins · validators merged intovalidate·task_status/orchestrate/locale_lookupcut ·sleep+wait_untilmerged into unifiednika:waitper ADR-087 ·cost+records+dag_info+threadsmerged into unifiednika:inspectper ADR-088 · ZERO capability loss ·decidejoined per spec 11 W-DEC · 2026-07-15) (+ the remaining media class · deferred to stdlib v0.x · NOT in the v0.1 count)
What's OUT of stdlib v0.1 #
Deliberately deferred to stdlib v0.x ·
- The remaining media builtins · pdf_extract · svg_render · chart · phash · thumbhash · provenance · etc. (heavy · high maintenance · niche audience —
image_generategraduated 2026-07-05, the rest waits) - Advanced agent presets · multi-agent coordination patterns · supervisor/worker · etc.
- Memory recall builtins · awaiting the engine's memory subsystem (the Connectome · stdlib v0.5+)
- Workflow include / import · single-file workflows in v0.1
When these mature · they enter stdlib v0.x. The core language doesn't need to change.
How a workflow references the stdlib #
Model selection #
model: anthropic/claude-sonnet-4-6 # <provider>/<name> · see stdlib/providers-v0.1.md# model: ollama/qwen3.5:4b # local · same shapeExtract mode #
invoke: tool: "nika:fetch" args: url: "https://example.com" mode: article # references stdlib/extract-modes-v0.1.mdBuiltin #
invoke: tool: "nika:read" # nika:* namespace = builtin args: path: "./config.yaml"How a workflow references non-stdlib tools #
For MCP tools (not in the stdlib · provided by external MCP servers) ·
invoke: tool: "mcp:postgres/query" # mcp:<server>/<tool> namespace (one colon · slash path) args: sql: "..."These are not stdlib · they depend on the engine's MCP server registry being configured.
Namespace ownership · `nika:` · `mcp:` (closed at v1) #
The namespace set is CLOSED at v1: nika: and mcp: are the only two
(02 §tool reference grammar ·
any other prefix is rejected at parse time) ·
- Namespace · Owner · Source of truth · Examples
- `nika:*` · **Spec-owned** · `stdlib/builtins-v0.1.md` (this directory's sibling) · `nika:read` · `nika:jq` · `nika:done`
- `mcp:<server>/*` · Engine + user · Engine's MCP server registry config · `mcp:postgres/query` · `mcp:browser/navigate`
The nika:* namespace is spec-owned. A custom engine MUST NOT add tools
to the nika:* namespace · it would violate portability (a workflow using a
vendor's nika:custom builtin would not run on a different engine).
Engine-specific tools route through `mcp:`: an engine that ships custom
capabilities exposes them as an MCP server it hosts (mcp:myengine/research).
That is exactly what the protocol is for · the tool is then declared in the
engine's MCP registry like any other (portability semantics intact · any
engine with that server configured runs the workflow) · and no third
namespace appears silently.
(An OpenAPI-style x-<vendor>: prefix was considered and is reserved as a
possible future additive minor: it does NOT exist in v0.1 · a parser that
accepts x-anything:tool today is non-conformant.)
Conformance levels #
See 07-conformance.md. In summary ·
- Level · Stdlib requirement
- Core · None · only parse + DAG + variable + error · no execution needed
- Runtime · Must execute the 4 verbs · provider/tool implementations engine's choice
- Stdlib v0.1 · Must ship the 17 providers + <!-- canon:extract_modes -->9<!-- /canon --> extract modes + 28 builtins
- Stdlib v0.1+media · RESERVED · enumerated when the media set publishes (stdlib v0.x · the 24 names are not yet normative)
A v0.1-compliant engine for a workflow author depends on which level they need.
Forward-compat #
The split between core and stdlib is locked at v1. The contents of the stdlib v0.x evolve.
Out of scope for v0.1 · explicit stdlib version pinning in the workflow envelope · per-task stdlib version overrides · stdlib element discovery API. See 08-out-of-scope.md.
🦋 Next · [07 · Conformance](./07-conformance.md)
nika-spec@6ac29351a · 06-stdlib-contract.md · sha256 018a0f775213c4bd… · the pack upstream