Skip to main content
Builtins catalog / nika:emit

Core

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Emit a custom machine event (consumed by subscribers · journal).
Why this is not log with a different word (normative rationale · 2026-08-11). The separation was stated as “log = human diagnostic · emit = machine event” — a claim about the intended READER, and a reader is a property of the consumer, not of the write. That reasoning would not have survived the collapse sweep that merged sleep+wait_until and four introspection builtins. The load-bearing difference is the FAILURE MODE, and it is structural: nika:log has no failure codes at all — a log that cannot land never fails its task — while emit validates the event shape and refuses NIKA-BUILTIN-EMIT-001. Collapsing them forces one of two regressions: either every diagnostic becomes failable (73 files in the measured corpus rely on it not being), or machine events lose their shape gate. Two builtins, two contracts, one event stream — kept for what they promise on failure, not for who reads them.
event_type: matches ^[a-z][a-z0-9_.-]*$ · payload: any JSON value. Returns null. Delivery is engine-side (journal · subscribers) · best-effort once shape-valid. Throws · NIKA-BUILTIN-EMIT-001 (invalid event shape · validation_error).

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:emit. Specification revision: 5cd95cd25c0f.

Documentation

Guides, reference contracts and working examples.

Language spec

the nine-key envelope, Apache-2.0. The contract these docs explain.

Engine source

Rust, AGPL-3.0-or-later. Every commit public.

TypeScript SDK

Use one typed lifecycle locally or against authenticated nika serve HTTP.

Editor extension

The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema.

Homebrew tap

brew install supernovae-st/tap/nika for the latest tagged CLI release.

SuperNovae

The Paris studio crafting Nika. 🦋