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 andnika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.
Usage and behavior
illustration
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).
Related concepts
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: f8c5df2127c7.
The Lab language identity is language:tool:emit; the registry view is ecosystem:tool/nika:emit. They refer to this contract without merging their graph identities.