Concepts
Seven words, three steps, and one idea that makes the rest follow.
The idea
The classifier evoke uses answers closed questions: which of these? is this stated? yes or no? It answers
with calibrated probabilities. Everything it knows about a
reflex comes from the reflex's own description, sent in the request. So the wording is the tuning, and one
line is documentation, tuning, test and customization at once:
"kill the lights" = { state = "off" }
A reflex is a package of such wording plus the program it describes. evoke fetches, versions and refines that
wording, and runs the program. The rules say how to write it so that it is read right.
The words
| Concept | Meaning |
|---|---|
| Reflex | A directory: reflex.toml and the file or program it names. Its identity is its location, owner/repo[/dir] at a git tag. |
| Manifest | reflex.toml: what the classifier reads and what the program receives. Its wording is yours to override. Its contract is not: argument names, option keys, sources, ranges, what it runs. |
| Project | A directory of files you own: evoke.toml, evoke.lock, overlays/, vocab/. Your home project lives in ~/.config/evoke/. An application has its own at its root. |
| Overlay | Your wording for one reflex, in one file, laid over the shipped manifest. It adds and replaces. It never deletes. |
| Vocabulary | Your word = "meaning" list, shared by every argument that names it. A package never ships or writes one. |
| Adapter | The classifier behind a decision, by name. jev and openjev both reach Jev, through TypeSafe AI's API or through OpenJEV. The core names no engine. |
| Runtime | What runs a program: Node for a .mts or .mjs file, nothing for an argv. Chosen from the manifest. Authors never see it. |
Two more words come up everywhere. A call is a reflex with its arguments filled in, on one line:
lights room="den" state="off". An effect is what running a reflex does to the world: read, write or
destructive. The effect decides how sure evoke must be before it runs without asking.
A tag is a word a manifest carries, so --tag can narrow a decision. A collection is a repository of
reflex directories. The Hub is where reflexes are found. For now, that is the first-party collection, evoke-build/reflexes.
The three steps
evoke "mute the office lights"
- Decide. Every active reflex's manifest becomes questions. Which reflex does the input ask for? For each argument, which value, or was it left unstated, or stated in words that are not among the choices? One request carries all the questions. The adapter answers each with a probability. Where an answer leaves a doubt, the reading checks itself with another question: it asks about a value a second way, whether a word of the input means the value it seems to, what the words no value holds do, and, before a call runs, whether the call holds all the input says. What it reads, it reads from your words; nothing is invented.
- Gate. Confidence is the weakest of those answers. Each effect has a bar. Against that bar, the outcome is settled: run, confirm, ask for a missing argument, or abstain. A destructive reflex always confirms. Code stays in control: the classifier proposes, the gate disposes.
- Run. The reflex's program runs with its arguments, a clean environment and a deadline. Its one line of text comes back.
What the classifier can and cannot do
It selects. An argument's value is one of five things: one of the author's options, one of your vocabulary words, a piece of what you typed, taken word for word, or, in a sentence of several steps, a field of an earlier step's result or that step's whole result, which the plan shows; or, when the words leave it out, a value an earlier result of this session holds, which you choose at the prompt. That piece can be a number, a duration, an email address, a URL, a quoted phrase, a date, a time, an amount or a code, and it is checked against its range. So a sentence can choose a call, but it can never invent a value. And what it chooses still passes the gate. That is the shape of every guarantee in Security.
Next: Typing a request.