The reflex format.

1.1Covered

• The manifest. Its keys, its text rules, what is wording and what is contract.
• The decision. The questions built from a manifest, the answers, the four outcomes.
• The gate. How a confidence is read, how an effect sets its bar, what always asks.
• The body. What a program receives, what it returns, how it is run.
• The files. A project, an overlay, a vocabulary, the lock, and how they merge.
• Distribution. Where a reflex comes from, how it is pinned, what a version means.
• The adapter and the wire. The contract an engine fits, and the JSON every decision prints.

1.2Not covered

How an engine produces a probability. What a body does with its arguments. How a host draws a prompt. An implementation MAY do each as it likes, as long as what this page states holds.

3.1Keys

3.2Text rules

Every string MUST be clean text: no control characters, except the line feed inside description, and no bidi controls. An implementation MUST refuse the rest, so a manifest can never repaint a terminal. Names of arguments, tags, config keys and vocabularies match [a-z][a-z0-9_]*. An argument name is never a JavaScript reserved word, so a body can destructure it. Option keys are one clean line each. none and unstated are reserved. Unknown keys are reported, never fatal.

3.3Wording and contract

A manifest is two things. A user MAY override the wording in an overlay. A user MUST NOT be able to change the contract: a contract key in an overlay makes the reflex inactive, never looser. Changing the contract is a version bump.

3.4Freezing

reflex = 1 is frozen. A key is never removed and never given a new meaning. A renamed key stays an alias. An unknown key is reported, never fatal, so the format is open to additions; the schema is strict, so an editor flags a typo first. The number bumps only when an old client must refuse a manifest. Every manifest ever tagged stays readable.

4.1The four sources

optional = true means an unstated argument is omitted and the body's own default applies. A required argument left unstated MUST be asked for. A flag is optional by nature and takes no optional. A shipped manifest MUST NOT assert a vocabulary argument in its records, because the words are the user's.

4.2Picks

A pick reads a piece of the input, word for word. Five recognizers exist, and they run in code. The classifier chooses among the candidates found. It never invents one. A pick with no candidate reads as unstated.

Quotes hide what they enclose, and a typed span hides the bare numbers inside it. range = [min, max] compares the value, in seconds for a duration, and is allowed on number and duration only. Out of range, the implementation asks, with the reason on the line.

4.3Renames

To rename an argument, an author declares its former names and keeps them declared forever: was = ["state"]. was is flat and cumulative. A retired name never returns as a live argument, and it never leaves the list. Every user's overlay and every call written with the old name follows the rename at merge time.

4.4Placeholders

confirm names required arguments only. A placeholder for an optional argument or a flag is an error. In an argv, a placeholder is a whole element, naming an options, vocab or pick argument. An element whose optional argument is unstated is dropped. A value that would start with - is refused. Flags and literal braces need a file body.

5.1Assertions

An argument a record does not name is not asserted. An example that asserts an option teaches it: "kill the lights" = { state = "off" } says this input is lights, and that kill means off.

5.2Identity

Records are keyed by the utterance as written, and the classifier reads that spelling. Two records are the same utterance under identity: NFC, lower-cased, whitespace collapsed and trimmed, and a trailing . ! ? or … dropped. Duplicates in one file MUST be refused. A user's line naming a shipped utterance replaces it, so the highest layer decides each utterance's table and value.

5.3Limits

Lint reports and never refuses. A manifest SHOULD keep its summary under 100 characters and its description under 1 000, list at most eight not_for entries, offer at most 24 options on one argument, hold at most 40 records per table, and keep every utterance under 200 characters. Text that addresses a model instead of describing an action is named.

6.1The questions

State is only the request: the sentence, and the questions built from installed manifests. Nothing else of the user's. A pick's candidates are found in code first, so the classifier chooses among spans that exist. An inactive reflex, one that lacks a word or a setting, is left out of every question.

6.2The answers

An implementation MUST validate every answer and fail closed. A choice is a distribution over the keys offered. An answer that names a value no argument offered, a key that is not a probability, or a question left unanswered, ends the decision with a fault, and nothing runs.

6.3The outcomes

A decision MUST refuse an input over 2 000 characters, and MUST stop at 30 seconds, shared between the classifier's answer and the body's run. A prompt waiting for a person never counts. When the deadline passes, the implementation stops and says so. It never guesses.

6.4Every judgment, shown

An implementation MUST be able to show every judgment of a decision without running it, and to explain the last decision from its log alone. In evoke that is try and why.

$ evoke try "kill the lights"
  lights 0.90 · none 0.06 · timer 0.02 · volume 0.02
  room   unstated 0.75 · den 0.20 · office 0.05
  state  off 0.58 · on 0.30 · dim 0.10 · unstated 0.02
  fits   lights 0.70 · timer 0.05 · volume 0.05
  ask room · weakest: state 0.58

The route, each argument with unstated as a choice, the fit per reflex, then the outcome and the weakest judgment. The room was not said, so the outcome is an ask.

7.1The bars

7.2Rules that hold

• A destructive reflex always confirms. No number and no flag skips its question. There is no --yes. Unattended use is a bar in a file the user owns and trusted.
• read never exceeds write. A user MAY move a bar for their own machine, under the adapter's table in evoke.toml, within that rule.
• The core never rescales. The adapter's numbers are its own calibration. An adapter that ships no bars never runs anything on its own: every decision confirms.
• Effect only tightens. A user's overlay may tighten an effect, never loosen it. The lock holds the effect the user consented to. Upstream may tighten it at any time; it loosens only through evoke update --accept.
• A complete call still stops. A typed span no argument consumed, or a runner-up over its bar, holds the outcome at confirm, with the reason on the line.

8.1What a file body receives and returns

A file body is a module ending in .mts or .mjs, inside the reflex directory, exporting a function by default. It is self-contained: web APIs and node: builtins are there, anything else is bundled into the file. It receives (args, { input, config, signal }): per argument, an option's key, a word's value or the word, a pick's value, or true for a flag; the sentence as typed; each config key as a string, secrets resolved for this run only; and a signal that is aborted at the deadline, on a decline, and on SIGTERM. It returns a string, or { text, data? }. Throwing is failure.

8.2The run

• The environment is scrubbed. PATH, HOME, TMPDIR, LANG and TERM, nothing else. Secrets reach a body through config, never the environment.
• The deadline is 30 seconds per decision, shared with the classifier's answer. Anything that must outlive the run detaches and returns at once.
• A body's own stdout goes to stderr, so a stray line never corrupts a result. The result is what the function returns.
• The process group is ended on timeout or decline: SIGTERM, a second's grace, then SIGKILL. A body's life is bounded by its caller's.
• An argv runs directly, never through a shell. The program is a name on PATH or an absolute path, never a path relative to wherever the tool runs.

9.1The overlay

overlays/<name>.toml is the user's wording for one reflex, in the manifest's own shape. It is merged over the shipped manifest by one rule: tables merge by key, and every value replaces whole. An overlay adds and replaces. It never deletes. Lists replace whole. The effective manifest is the shipped one with the overlay merged in.

description = "Turn the lights in one room on, off, or dim them."   # replaces whole
effect      = "destructive"                                        # may only tighten

[args.state]
ask = "On, off or dim?"                                             # new wording for an argument
options.dim = "Lower the brightness; the lights stay on."           # an existing key only

[examples]
"kill the lights" = { state = "off" }                              # sent to the classifier

[tests]
"turn on the kitchen lights" = { state = "on" }                    # a shipped example, held out now

An overlay MAY change wording: description, not_for, tags, confirm, each argument's ask, the meaning of its existing options, examples and tests. It MUST NOT change the contract: a contract key makes the reflex inactive, and names the line to remove. An overlay that fails to read makes its reflex inactive, never silently looser. A user's records MAY assert vocabulary arguments.

9.2The vocabulary

vocab/<name>.toml is a closed list of the user's words. Every argument that names the vocabulary shares it. A package MUST NOT ship or write one. A word is one clean line, trimmed, spaces allowed, unique under identity. none and unstated are reserved. The meaning is what the classifier reads. The value, when set, is what the program receives instead of the word, and the classifier never sees it.

den    = "The TV room downstairs; also 'the snug'."
office = { what = "The upstairs study.", value = "group-7" }

9.3The lock and the store

The lock records, for each remote reflex, the ref, the tag, the commit, the content hash h1 of the reflex directory, and the effect the user consented to. It records the adapter by name and id. Fetched code lives in a store keyed by h1, and an implementation MUST re-hash it against the lock at every start. A copy that does not match is a miss. Local reflexes are never locked.

9.4Trust

A project outside the home project MUST be trusted before an implementation decides in it. Trust binds to the content of the four owned paths: evoke.toml, evoke.lock, overlays/, vocab/. The implementation's own writes renew it. Any other change stops the next run until the project is trusted again. Adapter names resolve only against the tool's built-ins, never from a project directory, so a cloned repository cannot choose the classifier.

10.1Refs

10.2Fetching

A fetch is bare and shallow, read without a checkout, once per repository and tag. Symlinks and submodules MUST be refused. No code runs at install time. A repository with no version tag cannot be installed. A published tag never changes: the lock records the tag, the commit and the content hash, and a tag that moved MUST be refused. A fix is a new tag.

10.3Versions

One tag covers the whole repository. The next version is decided by the diff of the contract against the newest tag, and evoke check prints it:

A was violation is refused outright: a retired name returning, or a name dropped from the list. An update never prompts, never blocks and never rewrites a user's files. It reports what was rewritten and taken, what went stale, what was orphaned, and an effect loosened upstream, which the user keeps until they accept it.

10.4Installing

At install, an implementation MUST lint the manifest, and SHOULD route the examples already installed over the new set, naming every phrase the newcomer would steal, with its one-line fix. Lint and the theft test report. They never refuse.

11.1The contract

interface Adapter {
  // opaque; changes whenever answers could; compared, never parsed
  id: string
  // per-call ceilings; a plan over them is refused at load
  limits?: { options?: number; tokens?: number }
  // each number means P(correct)
  gate?: { route: number; fits?: number; read: number; write: number }
  // a recording's plan digest; another plan refuses it
  plan?: string
  answer(state: { request: string }, questions: Record<string, Question>, signal: AbortSignal): Promise<Raw>
}

type Question =
  // a choice: otherwise is the key meaning "none of these"
  | { type: "choice"; ask: string; options: Record<string, Text>; otherwise?: string }
  // a yes/no: answered as { yes: p }
  | { type: "yesno"; ask: string; yes: Text; no: Text }
type Text = string | { what: string; not_for?: string[]; examples?: string[] }
type Raw  = Record<string, Record<string, number>>   // per question, a number per key

• State is only { request }. An adapter sees the input and the questions, nothing else.
• A choice answer is a distribution over the keys offered, summing to 1. An omitted key reads as 0. A yes/no answers { yes: p }. The core validates every answer and fails closed. A missing question is a fault.
• otherwise marks the sentinel, none or unstated, in the structure, so an engine may abstain its own way.
• gate is the adapter's own calibration. The core never rescales. Without one, every decision confirms.
• answer is stateless and may be called with any subset of a plan's questions. An adapter that ignores its signal is raced against it anyway.
• id covers everything that could shift answers: model, version, prompt rendering, calibration. It is pinned in the lock. The endpoint is the adapter's own, built in with its id.

11.2The recording

A recording is an adapter over a file: the declaration, then the answers, keyed by utterance identity and question id. It answers offline, byte for byte. It is how the transcripts of the spec run without a key, and how an application's tests replay real answers.

id = "replay"

[gate]
route = 0.5
fits  = 0.3
read  = 0.6
write = 0.8

[answers."kill the lights in the den"]
route          = { lights = 0.91, timer = 0.02, volume = 0.01, none = 0.06 }
"fits.lights"  = { yes = 0.7 }
"fits.timer"   = { yes = 0.05 }
"lights.room"  = { den = 0.85, office = 0.05, unstated = 0.1 }
"lights.state" = { off = 0.88, on = 0.05, dim = 0.05, unstated = 0.02 }

A pick's candidates are keyed <start>-<end> by their character offsets in the input. The recording carries the adapter's declaration, so the gate in tests is the gate in production.

12.1Fields, by outcome

12.2Values and questions

{ "type": "option", "key": "off" }
{ "type": "word", "word": "office", "value": "group-7" }
{ "type": "pick", "span": { "start": 18, "end": 28, "text": "10 minutes" }, "value": { "type": "duration", "value": 600 } }
{ "type": "flag" }

A question id is route, fits.<reflex>, <reflex>.<argument>, or weave.<name>: a question the tool asks on its own account, beside a reflex's. A choice's keys are option keys, vocabulary words, <start>-<end> for a pick's candidates, yes and no for a flag, local names for the route, and the sentinels none and unstated.

13.1Reading

• A connective is a question. Where and, then, but, a comma, after or before could separate two things, the classifier is asked whether it does.
• Each part is decided as one input is. Routed, gated, its arguments read. A part that matches nothing is tried as another item of its neighbour's task first. Failing that, the whole request MUST be refused rather than half done.
• A part that begins with a negation is left out. not, don't, never, without: what was said not to do is no step.
• Order words order. then, after that, next; before you X, Y and Y after you X both read as X, then Y. Two writes never run side by side. Reads may.

13.2Binding

A body MAY declare what its result holds under [yields]. A later step that refers to it, it, them, that report, takes a field of the right kind into the argument it lacks. A required argument is filled with the value. An optional one is decided again with the value written into the words, under the same gate as any words. A reference several fields could satisfy MUST be asked, never guessed.

$ evoke "look up dana's address and email them"
  1  contact name="dana"  0.90
  2  mail · takes email from 1
dana <dana@example.com>
  2  mail to="dana@example.com"  0.88
drafted to dana@example.com

13.3Before anything runs

The plan is settled first. A step whose required argument no other step provides is asked for it up front. Then the plan is shown, numbered, one line per step. Each step then goes through the same gate as one input. A failure, a decline or a refusal ends the weave after its stage; the steps after it are skipped, and say so. The exit code is the worst step's. Under --json, one line per step carries step, steps, bound and status beside the decision's fields.

14.1Guaranteed

• State is only the request. The adapter sees the sentence and the questions built from installed manifests. Nothing else of the user's.
• A value is a closed choice or an exact span. Injected text can choose a call. It can never mint a value.
• The effect gate covers what it chooses. A destructive reflex always confirms, and there is no --yes.
• Prompts cannot be repainted. Control characters and bidi overrides are refused in every manifest, overlay and vocabulary string, and in every span. The tool's own line prints before the reflex's template.
• Wording is linted and conflict-tested at install. Effect only tightens. The contract cannot be overridden. Tags carry no meaning but --tag.
• Trust and the lock bind to content. A changed project stops. A tag that moved is refused. The store is re-hashed at every start.
• Fetching is narrow. A strict ref grammar, https and ssh only, no symlinks, no submodules, no checkout, no hook, no install-time script.
• Secrets are referenced, never stored. A project names a variable. The value reaches a body for the length of one run.

14.2Not guaranteed

Containment. A body runs with the user's rights under a scrubbed environment. The scrubbing prevents leaks. It does not contain malice. A read or write reflex over its bar runs without asking, and whatever it does with a span it is handed, an injected sentence can make it do. So its effect is the author's promise about exactly that. Read what you install. The manual's security page holds every claim, and how to try each without a key.

15.1What conformance means

• Schemas. JSON Schema for reflex.toml, an overlay, a vocabulary and evoke.toml, served at the addresses above. A conforming implementation reads every manifest they accept.
• Vectors. One directory per function of the core, one case per file: the input by name, and the exact expected output, on the wire above. A conforming implementation produces the same value for the same input, including the same fault.
• Transcripts. One directory per flow: the terminal, word for word, run offline on a recording. A conforming CLI prints the same lines and exits with the same codes.
• No key. The whole suite runs without a classifier. The recording answers, and the vectors pin what the answers become.

15.2Exit codes

Every line that needs something from a person ends with the literal command that gives it, and the set of those commands is closed.