Builtins catalog

The language stays verbs. Everything else is a tool, and the standard library ships builtins under the nika:* namespace, engine-native (no MCP round-trip, no subprocess), all invoked the same way:

read_config:
  invoke:
    tool: "nika:read"
    args: { path: "./config.yaml" }

The tables below name every builtin so you know what exists offline. For the argument contract of any one of them, ask your installed binary rather than a page that can drift:

nika catalog --tools          # every builtin, by category, with one-line contracts
nika catalog --tools --json   # the model-facing JSON Schemas (args · required)

Canonical source: nika-spec/stdlib/builtins-v0.1.md, the Apache-2.0 language spec. The set was curated by the Rams “less but better” sweep (ADR-086/087/088): one super-powerful builtin with mode args beats five single-purpose ones.

Overview

Builtins

tools · 6 categories

Extract modes

on nika:fetch

Namespace

nika:* · engine-native

Core (6)

The workflow-control family: speak, signal, guard, ask, finish, pause.

Builtin	What it does
`nika:log`	Emit a log entry (`debug`/`info`/`warn`/`error`) to the event stream: the human-readable diagnostic.
`nika:emit`	Emit a custom machine event (consumed by subscribers and the journal). `log` is for humans, `emit` is for machines.
`nika:assert`	Fail the task if a CEL `${{ }}` condition is false: the fail-fast guard (`when:` is the skip-guard).
`nika:prompt`	Interactive human confirm: blocks until answered; engines may use `default` in CI.
`nika:done`	Mark the current `agent:` loop complete and exit. Valid only inside an agent tool whitelist.
`nika:wait`	Temporal pause: relative `duration:` XOR absolute `until:` (ISO 8601), validated at parse time.

gate:
  with:
    count: ${{ tasks.fetch_data.output.count }}
  invoke:
    tool: "nika:assert"
    args:
      condition: "${{ with.count > 0 }}"
      message: "Expected non-empty result"

File (5)

Builtin	What it does
`nika:read`	Read a file. Returns string content.
`nika:write`	Write a file. Returns the path; binary upstream values are written as-is.
`nika:edit`	In-place find/replace. Returns the modified path.
`nika:glob`	Glob match. Returns an array of paths.
`nika:grep`	Recursive grep. Returns an array of `{ path, line, match }`.

Data (9)

jq is THE data language: map, filter, reshape, merge. The other eight cover what jq genuinely cannot do: diff, validate, delete-on-null merge, format conversion, generation, time, hashing, adjudication.

Builtin	What it does
`nika:jq`	Run a jq expression: the single transform-and-extraction language, same jq as `extract:` bindings.
`nika:json_diff`	JSON diff. Returns RFC 6902 JSON Patch (jq can’t diff).
`nika:validate`	Validate data against a JSON Schema: `format: json \| yaml`, returns `{ valid, errors }`.
`nika:json_merge_patch`	RFC 7396 merge patch: `null` deletes a key, the semantics jq’s `*` merge does not provide.
`nika:convert`	Universal format converter: `json` · `yaml` · `toml` · `csv`, `from:`/`to:` mode args. CSV emit takes `formula_guard: true` (opt-in) to neutralize spreadsheet formula-injection in untrusted data.
`nika:uuid`	Generate a UUID: `v7` default (timestamped/sortable, RFC 9562) or `v4`.
`nika:date`	Timestamp arithmetic: op-discriminated (`now`/`add`/`subtract`/`format`/`parse`/`diff`), timezone-aware, ISO 8601 out.
`nika:hash`	Content hashing: default blake3, or `sha256`/`sha512`; md5/sha1 are not supported.
`nika:decide`	The deterministic decision kernel (spec 11): evaluates a portable Decision Bundle (`bundle:`) against an EvidenceSnapshot (`evidence:`) and returns the full receipt — outcome, term-by-term contributions, intervals, conflicts with their witnesses, determination provenance. The model never decides: an `infer:` task collects the facts, this applies the rubric. Same evidence, same verdict, forever. Full contract: The decision bundle.

# recursive deep-merge of two task outputs — pure jq, no extra builtin
merged:
  with:
    base: ${{ tasks.base.output }}
    overlay: ${{ tasks.overlay.output }}
  invoke:
    tool: "nika:jq"
    args:
      input: ["${{ with.base }}", "${{ with.overlay }}"]
      expression: ".[0] * .[1]"

The decision bundle

One builtin in that table earns its own section. nika:decide is the only builtin whose semantics live outside the engine: the rubric is a portable JSON artifact you own and version, and the engine is a reference implementation of it, never its prison. Teaching shapes: nika try 14-decide-publish (offline, zero keys) and nika compile classify-and-route --json (incomplete until its questions are answered; a destination writes only when Ready).

The two args

Arg	Shape
`bundle:`	The Decision Bundle. Either the inline object, or a `./path.bundle.json` string. The path form is an ordinary `fs.read`: the file must sit inside `permits.fs.read`. A literal path outside it is a `NIKA-SEC-004` finding at `nika check`, before anything runs; a computed path is the run’s verdict. The inline form touches no filesystem at all, so a bundle in `const:` needs no `permits.fs`.
`evidence:`	The EvidenceSnapshot object: `t` plus an `evidence:` array of items. Required, and it must be an object.

Both args are required. A wrong arg shape is NIKA-BUILTIN-DECIDE-001, the arg plane every builtin shares. permits.tools must list nika:decide.

triage:
  invoke:
    tool: "nika:decide"
    args:
      bundle: "./decisions/refund.bundle.json"    # or the inline object
      evidence: "${{ tasks.collect.output }}"

The bundle, as the kernel reads it

A bundle is ONE JSON document with six mandatory regions. A missing region refuses before anything is scored.

Region	What the kernel reads
`manifest`	`id` · `version` · `owner` · `license`, all required non-empty strings. `digest` and `valid_until` are carried, not checked (see below).
`evidence_schema`	A non-empty map, one entry per evidence key. Per key: `type` (a spec 09 type expression, required) · `required` · `sources` (an allow-list) · `integrity` (the floor) · `identity: true`.
`transforms`	Named, bounded feature transforms: `clamp` · `linear` · `bucket`. Integer basis points only, `min ≤ max`, and the input is clamped into `min..max` before the kind’s arithmetic runs. That is what “total on its range” means: no input can fall outside.
`rules`	`dimensions.<name>.terms[]` and `thresholds[]`. This is the whole scoring program.
`governance`	`never_automatic: [outcome…]`, plus fields the kernel carries but does not read.
`fixtures`	The bundle’s own golden cases: `name` · `class` · `evidence`.

The three transform kinds, exactly:

Kind	Arithmetic
`clamp`	The clamped value itself.
`linear`	`clamped * scale_bp / 10000 + offset`, floor division. `scale_bp` defaults to `10000` (identity), `offset` to `0`.
`bucket`	`edges[n]` plus `values[n+1]`, edges sorted ascending. The first edge strictly above the value selects its value; past every edge, the last one. A log-shaped curve is an explicit table, honest and byte-equal across evaluators.

A rule term and a threshold:

{
  "rules": {
    "dimensions": {
      "refund_eligibility": {
        "terms": [
          { "evidence": "days_since_purchase", "transform": "within_window",
            "weight_bp": 6000, "monotonicity": "decreases" },
          { "evidence": "item_returned", "transform": "returned_step",
            "weight_bp": 4000, "monotonicity": "increases" }
        ]
      }
    },
    "thresholds": [
      { "dimension": "refund_eligibility", "recommend_gte_bp": 8000 }
    ]
  }
}

evidence must name a declared evidence_schema key, and that key must not be an identity: true key.
transform must name a declared transform.
weight_bp is an integer basis point: 8735 is 87.35%. One term contributes transform(value) * weight_bp / 10000, floor division.
monotonicity is increases · decreases · none (the default).
recommend_gte_bp is an integer basis point too, and its dimension must be a declared dimension.

The threshold ladder is read in order, and it reads intervals, never a point estimate: inf ≥ gate recommends (robust dominance) · sup < gate falls through to the next threshold · a straddle defers as incomparable with the available evidence · no threshold admitted defers. governance.never_automatic lists outcomes that may never ride out automatically. Every entry must be in the closed outcome enum (recommend · defer · human_required · opted_out · overridden), and it is applied last, over whatever outcome emerged: a bundle that lists recommend turns its own recommendations into human_required. Fixtures carry a class from a closed set: positive · negative · ambiguous · contradictory · adversarial. At least one contradictory fixture is mandatory: a bundle that cannot prove its Conflict handling is unpublishable.

What the kernel enforces

The bundle is validated in full before it scores anything, and both refusals are deterministic: same inputs, same refusal, never a partial receipt. NIKA-DECIDE-001 · the bundle breaks its own laws:

Fixed-point integrity. Every weight, threshold and transform bound is a real JSON integer. A float refuses, and so does 3.0, which is a float in both evaluators.
Closed rules. A term may only read a declared evidence_schema key, and only through a declared transform.
Identity counterfactual invariance. An identity: true key feeding a technical dimension refuses. The same case under a different author, tenure or tier yields the same technical decision, structurally.
A contradictory fixture is mandatory.
Declared monotonicity is property-checked, on the bundle’s own positive / negative / ambiguous fixtures: for every fixture pair that differs on exactly one monotone key, all else equal, that dimension’s score must move the declared way. It does not, and the bundle is refused at publication. The law is tested, not prose.
Shape laws: the six regions, the manifest strings, transform kinds in the closed set, min ≤ max, edges[n] with values[n+1] and edges sorted, fixture classes in the closed set.

NIKA-DECIDE-002 · the snapshot does not satisfy the schema:

an undeclared evidence key (the schema is the closed surface);
a value that does not fit the key’s declared type;
a source outside the key’s declared sources;
an integrity below the declared floor, on the lattice untrusted ⊑ observed ⊑ verified ⊑ authoritative.

Every item is judged, including a duplicate key, which is two claims. A missing required key is not an error: it lands in snapshot.missing and drives defer, because abstention is a safety property.

nika check does not evaluate the bundle. The bundle laws above are the kernel’s, and they fire when the task runs. A workflow carrying a bundle with no contradictory fixture, a float weight or a violated monotonicity audits clean and refuses at run time with NIKA-DECIDE-001. Prove a bundle by running it against its cases: see Testing · Proving a rule against cases.

What it does not enforce today

Stated plainly, so you do not buy a guarantee that is not there:

A fixture’s class is a label, not an asserted outcome. Nothing evaluates a positive fixture and checks that it recommends. Relabel a passing fixture negative and the bundle still publishes. The classes carry exactly two mechanical duties: at least one contradictory must exist, and the positive / negative / ambiguous set is the corpus the monotonicity check runs over. Everything else a class implies is yours to prove, one case file at a time.
manifest.digest is copied into the receipt verbatim, never recomputed and never verified against the bundle’s bytes.
manifest.valid_until is not read. Expiry is not enforced by the kernel.
governance.human_required_triggers, override and appeal are carried, not read. Only never_automatic changes an outcome today.
The snapshot’s observed_at, confidentiality and quality (freshness · completeness · independence_group) are carried, not scored. The ttl and the independence-group contribution cap are not applied by the kernel today.

The receipt

The success value is the whole receipt, and the explanation IS the formula:

{
  "decision_receipt_format": 1,
  "bundle": { "id": "refund-eligibility", "version": "1.0.0", "digest": null },
  "snapshot": { "t": "2026-09-02T09:00:00Z", "digests": ["d1", "d2"], "missing": [] },
  "dimensions": {
    "refund_eligibility": {
      "interval": { "lo": 10000, "hi": 10000 },
      "contributions": [
        { "evidence": "days_since_purchase", "known": true,
          "contribution": { "lo": 6000, "hi": 6000 },
          "weight_bp": 6000, "transform": "within_window" },
        { "evidence": "item_returned", "known": true,
          "contribution": { "lo": 4000, "hi": 4000 },
          "weight_bp": 4000, "transform": "returned_step" }
      ]
    }
  },
  "conflicts": [],
  "outcome": "recommend",
  "determination_provenance": [
    "dimension refund_eligibility dominates the threshold (inf 10000 >= 8000 bp) — robust, not point-estimated"
  ]
}

Field	What it carries
`outcome`	The closed enum: `recommend` · `defer` · `human_required` · `opted_out` · `overridden`. `defer` and `human_required` are successful evaluations, never errors.
`determination_provenance`	The ordered lines naming the commitments that decided between admissible outcomes: which threshold, which dominance test, which governance trigger. Data provenance says where the facts came from; this says what settled the verdict.
`dimensions.<name>.interval`	The dimension’s `lo` / `hi` in basis points. `lo == hi` means every term was known.
`dimensions.<name>.contributions[]`	Per term: `evidence` · `known` · `contribution` (`lo` / `hi`) · `weight_bp` · `transform`. A term whose value is missing or non-integer has `known: false` and contributes the transform’s whole interval, never an invented zero. Unknown is not False and not 0.
`conflicts[]`	One entry per key where two sources at `authoritative` integrity disagree: `key` · `class` · `required` · a `witness[]` of `source` · `value` · `digest`, both sides preserved. A conflict on a required key forces `human_required`.
`snapshot.digests`	The evidence digests, sorted: the receipt’s link back to the exact facts, so a decision can be published without publishing the evidence.
`snapshot.missing`	The required keys absent from the snapshot. Non-empty means `defer`.
`bundle`	`id` · `version` · `digest`, straight from the manifest.

A dimension is a vector component, never a universal scalar score. Declare change_risk and evidence_quality separately and route on each, rather than averaging them into one number nobody can appeal.

Where the lane goes

There is no lane field in the receipt: the routing decision is the outcome, and mapping an outcome to a queue is one nika:jq away.

route:
  with:
    receipt: ${{ tasks.decide.output }}
  invoke:
    tool: "nika:jq"
    args:
      input: ${{ with.receipt }}
      expression: 'if .outcome == "human_required" then "manual-review"
                   elif .outcome == "recommend" then "priority"
                   else "standard" end'

The semantics belong to the bundle. A stdlib-Python reference interpreter (conformance/decision_core.py in the spec) is the conformance oracle: for every bundle fixture, the engine’s receipt must be byte-equal canonical JSON against it. That proof, not a claim on this page, is what makes a bundle portable.

Network (2)

Builtin	What it does
`nika:fetch`	HTTP request + content extraction: extract modes (`article`, `markdown`, `links`, `feed`, `sitemap`, `selector`, `text`, `metadata`, `jq`) + `raw` passthrough — plus `form:` (urlencoded), `multipart:` (file parts ride the `permits.fs` READ boundary · ≤32 MiB) and `traverse:` (bounded same-origin crawl · `max_pages` ≤ 25 · robots honored · the effect certificate counts every page). Fetching a URL is calling a tool, not a verb — and so is crawling: no `nika:crawl`.
`nika:notify`	Send notifications: `channel:` enum (`webhook`/`slack`/`email`/`discord`/`sms`), one builtin not five.

Engines MUST ship SSRF defense on nika:fetch: private-network and cloud-metadata targets are rejected unless explicitly configured, and self-signed TLS is rejected by default.

Introspection (2)

Builtin	What it does
`nika:inspect`	Workflow introspection. Four `view:` modes: `cost` · `records` · `dag_info` · `threads`. Live cell seeded at run start (`available: true`). Teaching shape: `16-inspect-self`.
`nika:compose`	The agent loop’s self-check: pass a drafted workflow YAML, get the full `nika check` verdict back as JSON — never executed. Loop-only, like `nika:done` (valid only inside an `agent:` tools whitelist · grant after `nika:done`). Teaching shape: `15-compose-self-check`. Standalone `invoke:` is `NIKA-BUILTIN-COMPOSE-001`.

budget_check:
  invoke:
    tool: "nika:inspect"
    args: { view: cost }

Media (4)

Builtin	What it does
`nika:chart`	Deterministic chart rendering from rows + a semantic spec (`bar` · `line` · `area_band` · `scatter` · `heatmap`): a byte-identical SVG lands at `out:` (permit-gated write) and its sha256 rides the outputs as a trace-chain receipt. Pure compute + one write — no network, no clock, re-runs idempotent; optional Vega-Lite sibling via `compile_to:`. Full guide: Charts.
`nika:image_generate`	Provider-backed image generation and editing as an asset pipeline: renders land under a declared `output_dir:` (rides `permits.fs.write`), and `mode: edit` sources are read permit-gated (`permits.fs.read` — the mirror boundary); outputs and a provenance manifest carry paths + dimensions + sha256, and an edit records its `source_images` — image bytes never ride workflow outputs. Providers (v1.1 · local-first): `local` (any OpenAI-images-compatible self-hosted server — LocalAI · Ollama · sd.cpp · SGLang · vLLM-Omni · base URL via `NIKA_IMAGE_LOCAL_URL`) · `openai` (`gpt-image-2`) · `gemini` (`gemini-3.1-flash-image`) · `xai` (`grok-imagine-image`) · `mock` (offline, deterministic, zero keys). Full guide: Image generation — sovereign quickstart · editing · cookbook · honesty rules.
`nika:tts_generate`	Speech synthesis on the same asset-pipeline contract (full guide: Speech generation): ONE audio file lands under `output_dir:` (permit-gated), output + manifest carry path + sha256 + `duration_ms` (wav-exact, mp3 honestly null) — audio bytes never ride outputs. Providers (sovereign-first): `local` (any OpenAI-speech-compatible server — LocalAI · Kokoro-FastAPI · Speaches — via `NIKA_TTS_LOCAL_URL`) · `openai` (`gpt-4o-mini-tts`) · `elevenlabs` (`ELEVENLABS_API_KEY`) · `mock` (real deterministic WAV, offline). Teaching shape: `17-tts-self`.
`nika:image_fx`	Deterministic artistic effects on a PNG — dither (bayer · blue-noise · ign · floyd_steinberg · atkinson · jjn) · palette mapping (Oklab) · duotone · pixelate · halftone · grain · vignette · chromatic aberration · scanlines · glitch · ascii (png/text/ansi). Zero providers, zero network: byte-identical output forever for identical `(input, args)` — the artifact’s sha256 joins the trace chain, re-render IS the tamper check, and the full recipe (contract tag `image_fx/v1` · input sha256 · seed · ops) rides the PNG itself as a `nika` tEXt chunk. `input:` read + `out:` write both ride `permits.fs`. Full guide: Image effects — the receipts story · op table · cookbook.

hero:
  invoke:
    tool: "nika:image_generate"
    args:
      provider: mock              # offline dry-run · flip to local (sovereign) / gemini / openai / xai for real renders
      prompt: "OG hero — a monarch butterfly over a nebula"
      aspect_ratio: "16:9"
      output_dir: "./assets/og"

API keys are engine-configured, never workflow args: OPENAI_API_KEY / GEMINI_API_KEY / XAI_API_KEY (or the NIKA_-prefixed variants) and the local server’s NIKA_IMAGE_LOCAL_URL (+ optional NIKA_IMAGE_LOCAL_API_KEY) are read once at the engine’s composition root. The provider endpoints are engine-fixed constants — permits.net.http does not govern them (exactly like infer:); permits.tools and permits.fs do.

Design rules the set obeys

One super-powerful builtin, multi-mode args: fetch+extract, jq, convert, wait, date, inspect all follow the same pattern. No per-direction or per-shape builtin slots.
jq subsumes: anything that is a pure JSON transform is a jq expression, not a builtin. A builtin earns its slot only by doing what jq cannot.
Additive forever: new builtins may join in stdlib v0.x; existing arg shapes never break (a grammar change ships with its nika check --fix migration).

Full stdlib spec

Per-builtin args, error codes (NIKA-BUILTIN-*), trust classes, and what jq subsumed out of v0.1.

Verbs

How invoke: dispatches nika:* builtins vs MCP tools.

MCP catalog

External tools: the MCP server registry Nika knows by id.

Bindings

Templating that pipes output from one invoke: to the next.

YAML

Language fields

CLI & errors

Data catalogs

Workspace

Documentation system

Tool contracts

Builtins catalog

Overview

Builtins

Extract modes

Namespace

Core (6)

File (5)

Data (9)

The decision bundle

The two args

The bundle, as the kernel reads it

What the kernel enforces

What it does not enforce today

The receipt

Where the lane goes

Network (2)

Introspection (2)

Media (4)

Design rules the set obeys

See also

Full stdlib spec

Verbs

MCP catalog

Bindings

​Overview

Builtins

Extract modes

Namespace

​Core (6)

​File (5)

​Data (9)

​The decision bundle

​The two args

​The bundle, as the kernel reads it

​What the kernel enforces

​What it does not enforce today

​The receipt

​Where the lane goes

​Network (2)

​Introspection (2)

​Media (4)

​Design rules the set obeys

​See also

Full stdlib spec

Verbs

MCP catalog

Bindings

Overview

Core (6)

File (5)

Data (9)

The decision bundle

The two args

The bundle, as the kernel reads it

What the kernel enforces

What it does not enforce today

The receipt

Where the lane goes

Network (2)

Introspection (2)

Media (4)

Design rules the set obeys

See also