Documentation
Everything hekla does, and where it stops.
heklang is the language you write and hekla is the runtime that serves it. These pages cover both: what each declaration means, what the runtime does with it, and what to reach for when something is wedged at three in the morning.
Start here
Introduction
What hekla is, what you write, and what the runtime does with it.
Getting started
Build a project from an empty directory, check it, test it, and call it over HTTP.
How it works
What happens between a request arriving and a read model answering, and which part of the runtime owns each step.
Editor setup
Highlighting from the tree-sitter grammar, format on save from hek fmt, and what each editor needs.
Writing a project
Project layout
How a directory becomes a program, which three directories are enforced, and why file order never matters.
Events
The declaration that defines a fact, how fields become tags, and what the runtime wraps around one.
Commands
The only declaration that appends, why a fold is a read declaration rather than a variable, and what the three outcomes mean.
Guards and refusals
A named proposition about the log, and a named reason for saying no.
Projectors
Entities, the four write statements, and why a projector has no failure channel.
Effects
The only declaration that reaches the world, and everything that makes doing so replayable.
Types and values
The complete type table, why equality is exact, and the one rule for what may be written where.
Containers and control flow
Lists, maps, iteration in a defined order, and why every heklang program terminates.
Functions, records and constants
The declarations that exist so a rule is written once, and the two places purity is enforced.
Tests
A test is a declaration, so the cases live beside the code and run with the same binary.
Personal data
A subject-scoped field, what the seal does to it, and how erasure becomes one key delete.
Operating it
Running a project
hekla serve, what it creates, what it refuses to start without, and every configuration option.
The HTTP API
Every route the runtime generates, the status each outcome maps to, and the exact response bodies.
Read models
Readiness, rebuilds, and what a read answers while a projector is catching up.
Effects in production
Lanes, the five states, the journal, and the four ways out of a wedge.
Keys and secrets
The master key that wraps every subject key, how to rotate it, and why a deployment credential is a different mechanism.
Change safety
hekla plan, replaying a deploy against its own journal, and the invariant sweep.
Deploying
What the artefact is, what to back up, what to watch, and the limits stated plainly.
Reference
hekla, the runtime
All ten subcommands, what each one needs, and what each one refuses.
hek, the language tool
The compiler's own CLI, for editors, pre-commit hooks and answering whether an edit changed anything.
Diagnostics
Every code the compiler can emit, what each one means, and what to do about it.
Standard library
Everything callable an author did not declare, and which declaration kinds may call each one.
Keywords and annotations
The closed sets. 32 hard keywords, 18 soft ones, and the six annotations.