# The JSON line `--json` prints one line per input. The line holds the input, the decision's fields flattened next to it, the adapter calls made, and the result or the error when a body ran. It is the filter format. The log holds the same line, with the adapter's raw answers and the input's candidates next to it. `why` reads that. The SDK's `Decision` is the same object, plus `values` and `plan`. ## Shape by outcome | Field | run | confirm | ask | abstain | Holds | | :----------- | :-: | :-----: | :-: | :-----: | :------------------------------------------------------------- | | `input` | ● | ● | ● | ● | The sentence as decided | | `outcome` | ● | ● | ● | ● | `"run"`, `"confirm"`, `"ask"`, `"abstain"` | | `reflex` | ● | ● | ● | | The winner's local name | | `args` | ● | ● | ● | | Per argument, a typed value; partial for an ask. A pick read from words that spell it out carries `typed`, the value as it is typed | | `basis` | ○ | ○ | ○ | | Per value read from the input, what it stands on, by `by`: `ask`, its own question; `views`, two questions that agree; `view`, one of them and the `words` that hold it; either carries `anchored` where those words, asked alone, name the value; `words`, the words and a `yes`; `spelled`, words that spell it out and a `yes`, with `shape` where the value was held against the argument's examples: `whole`, `completed` by a case or a separator the examples share, or `open`; `only`, the one candidate of its kind and a `yes`; `text`, a text typed without quotes, with the `others` it could have been; `shared`, a value another part of the sentence states, `from` its words, and a `yes` | | `call` | ● | ● | | | The call on one line: `lights room="den" state="off"` | | `effect` | ● | ● | | | `"read"`, `"write"`, `"destructive"` | | `confidence` | ● | ● | ● | | The weakest judgment's probability | | `weakest` | ● | ● | ● | | `{ question, top, p }` | | `judgments` | ● | ● | ● | ● | Every choice read: `{ question, top, p }` | | `contenders` | ● | ● | ● | ● | The ranking: `{ reflex, route }` | | `runner_up` | ○ | ○ | ○ | | The second reflex, when there is one | | `prompt` | | ● | | | `{ own, reason, template }`: `evoke`'s line, why the call waits in one line, and the reflex's question | | `left` | ○ | ○ | ○ | | The words of the input that no value holds, each with what it does: `{ words, does, p }`, `does` one of `action`, `answers` with its `arg`, `result`, `nothing`, `more`; `cut` is `true` where the words follow a value and may be part of it, `again` where they say the call is wanted once more, `read` where a value of the call was read from them | | `whole` | ○ | ○ | ○ | | How far the call holds all the input says, where the call was read back against it | | `quotes` | ○ | ○ | ○ | | The texts in quotes that no value took, each with its marks, where the reflex takes a text in quotes | | `because` | | ● | | | Why it stopped, in order: `destructive`, `no_gate`, `under_floor`, `one_view`, `respelt`, `text_read`, `more`, `cut`, `quoted`, `text_left`, `whole`, `detail`, `named`, `pointed` | | `unconsumed` | ○ | ○ | ● | | Typed spans no argument took | | `missing` | | | ● | | Per missing argument: `arg`, `ask`, `because` (`unstated`, `out_of_range`, `not_offered`, `unsettled` or `unread`), `words` when the input holds words that answer the ask, `choices`; a pick's `choices.recent` lists the values recalled from this session's results, when any, and its `choices.readings` what the words that answer the ask read as, when they say a value aloud; `likely`, the listed word made ready for a yes, when there is one | | `trace` | ● | ● | ● | ● | One entry per adapter call, a round of questions each: `{ adapter, questions, ms }`. Empty when the answers came from the cache | | `result` | ○ | | | | `{ text, data? }` when the body ran | | `contained` | ○ | | | | Whenever the body ran, with `result` or `error`: whether this machine held it to its declaration, `{ "type": "full" }`, or `"partial"` or `"none"` with `why`, one sentence | | `error` | ○ | | | | The failure's message when it did not. The line is all that prints; the exit is 1 | | `frames` | ○ | | | | With `error`, the frames of the error a JavaScript body threw, from its first: `at body (throws.mts:1:1)` | | `cancelled` | ○ | | | | `true` when `Ctrl-C` ended the body; a step of a weave says it as `status` and `why` instead | A sentence read as several steps ([Weaving](../use/weaving.md)) prints one line per step, as each runs, the line of its decision with these fields more: `step` and `steps` first, the step's number and the count; `bound` after `trace`, where a value came from another step, `[{ arg, from, field, value }]`, `value` absent for a whole result, which stays on its source's line as `result.data`; `shared`, where the sentence said a word once for several steps and this one took it, `{ "": { "word", "via" } }`, `via` `fill` for a required argument and `rewrite` for an optional one written into the step's words; `beside`, where a day of the month was read beside the day of a step this one takes from, `{ "": }`; `from`, where a playbook wrote the step, `[{ playbook, step, slots }]`, outermost first; `when`, where the step runs only under a value an earlier step yields, `{ step, field, is }`; and `status` last, with `why` when the step stopped. A plan a playbook wrote prints the sentence's own line first: `step` 0, `steps` the count, the decision that picked the playbook, `playbook` and `slots`, and no `status`, so a filter counting lines per input sees one more. A request that is only what not to do prints one `abstain` line over the whole input, with no judgments and no contenders, and `because` `[{ "type": "nothing_to_do" }]`; a request refused before its plan was made prints the same line with the reason, `conditional` with its `text`. A plan stopped before any step ran prints every step's line at once, its `status` `refused`, `skipped`, `declined` or `unanswered`. A step run from a plan file carries `pinned` too, `{ "file", "id" }`: the file as shown, `~/month.plan.json`, and the SHA-256 of what was read, `h1:…`. `evoke try --json` prints the plan whole instead, on one line: `input`, `steps` with each step's decision, `binds`, `stages`, `verdict`, `exclusive`, `excluded`, `splits`, `count`, and `trace`, every adapter call the plan took. | Field | Holds | | :------- | :------------------------------------------------------------------------------------------------------ | | `status` | `"ran"`, `"failed"`, `"declined"`, `"refused"`, `"skipped"`, `"unanswered"` | | `why` | `{ "type": "earlier_step" }`, `{ "type": "nothing_to_take", "from" }` and `{ "type": "too_large", "from" }` with the source step, `found_nothing`, `{ "type": "not_chosen", "from", "value" }` for a step another value picked past, `no_reflex`, `cancelled`, `{ "type": "read_as", "reflex" }`, or `{ "type": "said", "message" }`: a prompt's own line, a failure, a question no one answered | In the plan `evoke try --json` prints, a step's `refs` count the steps they may name from 0; `step`, `after`, `stages` and `binds` count from 1. A step carries `shared` and `beside` as the line does, `typed` where the plan wrote its words anew, the words as typed, and `repair` where it was not one part decided on its own: `narrowed` or `spliced`, an item of its neighbour's task; `merged`, a part read with its neighbour; `split`, a part of a joint the classifier read as one thing; `corrected`, a part that says what not to do read with its step; `named`, a part that matched nothing alone, read as the reflex the whole sentence gives its words, its decision judging the reflex by that question, `weave.span__`, in place of `route`. `spliced` is also a part put in the words of the step before it: one that holds only values, or one that says the same for another value. So is each step written for one of the things that words like `both` point at. Its decision's `because` holds `pointed`, `{ "type": "pointed", "arg", "words" }`: the argument, and those words as typed. `first` and `verb` are two verbs before one thing: the first read without the second, and the second a step of its own that takes from it. `apart` is a step read for the one value its call holds, with its words as typed in `typed`. `again` is the step before it written again for another value its words name, with that value in place. Its decision judges the reflex by the question whether the request asks for that value as well, `weave.again_____`, in place of `route`. The answers are `also` where it does, `instead` where it means the value in place of the one read, `out` where it rules the value out, and `nothing` where the words say something else. A binding's `via` is `fill`, `rewrite` or `takes`, a whole result by the name its source returns, with no `kind`; the verdict's `because` names `no_source` and `several_sources` where such a result stops the plan. Each of `splits` carries `cut` where the plan cuts the sentence there; `count`, where the sentence could be cut, holds `one`, how surely it asks one thing, and `as_one` where it stands as one step for it. A plan carries `folded`, `[{ text, into, gave, picked }]`, the parts of the sentence folded into a step — a call typed again, or a step a playbook wrote — with the arguments the part gave and the word of it that picked the step among several; and `asides`, `[{ text, remark, does, by }]`, the parts that ask for nothing: a remark set aside, or words that may add a detail to a step, `does` the share of each answer, `{ aside, detail, asks }`, and `by` where the part was set aside by its words alone, `own` for your own action or `courtesy`. A plan a playbook wrote carries `from` on each of its steps and `when` on a step that may not run; its verdict's `because` holds `reviewed` per playbook, with the step, the sentence's `text` and its `prompt`, and names what refused it: `nested`, `too_deep`, `too_long`, `conditional`, `excluded`, or, for a branch, `no_field`, `bad_value`, `maybe_source` or `branch_into_plan`. A call by name, `evoke run --json`, prints the same line with nothing judged: `input` is empty, there is no `confidence`, `weakest`, `judgments` or `contenders`, `trace` is empty, and `result` or `error` says what the body did. A destructive call carries `prompt` and `because` like any confirm. Nothing was decided. ## The plan file `evoke try --save ` writes the plan whole as JSON, readable without a tool ([Files](files.md#a-plan-file)): `note`, fixed text; `plan`, `1`; `input`, the sentence as typed; `tags`, when any; `weave`, the plan as `try --json` prints it less `trace`; `evoke`, the version that wrote it; `adapter`, the lock's `{ name, id }`; `gate`, the adapter's floors, absent when it declares none; `set`, the plan digest; `reflexes`, per active reflex `item`, the hash of its wording, consent and settings, with `path` for a local one, or `ref`, `tag` and `h1` for a remote one, or nothing more for one handed to the SDK as code; `vocab`, each vocabulary's hash; `answers`, every classifier answer the plan took, `{ text, raw }` each, the whole sentence's own questions first. `run ` refuses the file when any of these differs here, with the line and the fix. ## Values ```json { "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 pick's `value` is what a recognizer read: the number, the seconds, the text; a date's reading, `{ "type": "offset", "days": 1 }`, `{ "type": "weekday", "weekday": "friday", "which": "next" }`, `{ "type": "day", "day": 14 }` or `{ "type": "calendar", "year": 2027, "month": 5, "day": 4 }`, resolved to a day only when the body runs; a time as `"17:30"`; an amount as `{ "amount": 1200, "currency": "EUR" }`; a code as its text. Its `span` is where it was read, in character offsets of the input. ## Examples A run, from `evoke try --json`: ```json {"input":"kill the lights in the den","outcome":"run","reflex":"lights","args":{"room":{"type":"word","word":"den"},"state":{"type":"option","key":"off"}},"call":"lights room=\"den\" state=\"off\"","effect":"write","basis":{"room":{"by":"views","ask":0.92,"reader":0.92},"state":{"by":"views","ask":0.94,"reader":0.94,"yes":0.95}},"left":[{"words":{"start":0,"end":15,"text":"kill the lights"},"does":"action","p":0.9}],"whole":0.9,"confidence":0.92,"weakest":{"question":"lights.room","top":"den","p":0.92},"judgments":[{"question":"route","top":"lights","p":0.95},{"question":"lights.room","top":"den","p":0.92},{"question":"lights.state","top":"off","p":0.94}],"runner_up":{"reflex":"timer","route":0.01},"contenders":[{"reflex":"lights","route":0.95},{"reflex":"timer","route":0.01},{"reflex":"volume","route":0.01}],"trace":[]} ``` An ask, from a filter with no terminal. The line stands for the prompt that could not be shown, exit 3: ```json {"input":"kill the lights","outcome":"ask","reflex":"lights","args":{"state":{"type":"option","key":"off"}},"basis":{"state":{"by":"views","ask":0.74,"reader":0.74,"yes":0.95}},"left":[{"words":{"start":0,"end":15,"text":"kill the lights"},"does":"action","p":0.9}],"unconsumed":[],"confidence":0.74,"weakest":{"question":"lights.state","top":"off","p":0.74},"judgments":[{"question":"route","top":"lights","p":0.95},{"question":"lights.state","top":"off","p":0.74}],"runner_up":{"reflex":"timer","route":0.01},"contenders":[{"reflex":"lights","route":0.95},{"reflex":"timer","route":0.01},{"reflex":"volume","route":0.01},{"reflex":"power","route":0.0}],"missing":[{"arg":"room","ask":"Which room?","because":{"type":"unstated"},"choices":{"type":"vocab","words":{"den":"The TV room downstairs; also 'the snug'.","office":"The upstairs study."}}}],"trace":[]} ``` ## Questions A question id is `route`, `fits.`, `.`, or `weave.`: a question `evoke` asks on its own account, beside a reflex's, and no reflex is named `weave`. A choice's keys are option keys, vocabulary words, `-` for a pick's candidates, `yes` and `no` for a flag, local names for the route, and the sentinels `none` and `unstated`. On an argument's question, `none` says the input states a value that is not among the choices. ## `evoke calibrate --json` One object, the report of [Calibrating](../use/calibrating.md): `adapter`; `records`, `reflexes`, `inputs`, `repeats`; `outcomes` with `run`, `confirm`, `ask`, `abstain`; `bins`, each `{ lo, hi, calls, right, interval, claimed, thin, over_confident }`, a bin with no call left out; `unknown`; `abstained` as `{ count, right, interval }`; `bars` with `read` and `write` where the effect has a complete call, each `{ bar, wrong, calls, per_thousand, at_most, near }` and `near` a list of `{ at, run, wrong }`, and `whole` where a call over its bar was read back against the input, `{ bar, calls, run, wrong, per_thousand, at_most, held_right }`; `questions`, each `{ kind, judgments, right, interval, claimed }` with `kind` one of `route`, `options`, `vocab`, `pick`, `flag`; `brier` with `brier`, `reliability`, `resolution`, `uncertainty`, absent without a call; `misses`, each `{ case, outcome, reflex?, confidence?, mismatch, wrong }`; under `--repeat`, `variance` with `flips`, `verdict_flips`, `spread` as `{ median, p90, max }`, `straddling`, `wrong_at_bar`, and `moved`, each `{ utterance, confidence?, route, winners, outcomes, wrong }`; and `log` with `adapter`, `decisions`, `ran`, `confirmed_ran`, `confirmed_stopped`, `asked`, `abstained`, `failed`, `skipped`, `stopped_by_confidence` as `[{ lo, hi, count }]`, `records` as `{ count, right, interval }`, and `unread`. An interval is `[low, high]`; a rate is per thousand. ## Rules of the wire Keys are `snake_case`. An absent optional is omitted, never `null`. A tagged value carries `type`. A decision carries `outcome`. Numbers are numbers: `0.85` and `0.850` are one value.